toolbox/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Tradewind Toolbox 是一个基于 Laravel 12 的内部工具管理平台，提供 Vue 3 单页应用前端和 RESTful API 后端。主要功能模块包括：

• 环境管理 - .env 文件的保存、应用、备份、恢复
• JIRA 集成 - 周报生成、工时日志查询
• 消息同步 - 跨系统消息队列同步和对比
• 消息分发 - 消息路由配置管理
• 日志分析 - 阿里云 SLS 日志查询 + AI 分析
• Git 监控 - Release 分支检查、冲突检测
• Jenkins 监控 - 构建状态监控和钉钉通知

常用命令

# 开发环境（同时启动后端、队列、日志、前端）
composer dev

# 运行测试
composer test

# PHP 代码格式化
./vendor/bin/pint

# 数据库迁移
php artisan migrate

# 清除缓存
php artisan optimize:clear

# 前端构建
npm run build

核心架构

服务层 (app/Services/)

业务逻辑集中在 Services 目录，所有服务在 AppServiceProvider 中注册为单例：

服务	职责
ConfigService	数据库键值配置存储
JiraService	JIRA REST API 集成
SlsService	阿里云 SLS 日志查询
AiService	AI 提供商管理（支持 OpenAI 兼容接口）
LogAnalysisService	日志分析编排（SLS → AI → 代码分析）
CodeAnalysisService	代码级分析（调用 Gemini/Claude CLI）
GitMonitorService	Git 仓库监控
JenkinsMonitorService	Jenkins 构建监控
DingTalkService	钉钉 Webhook 通知
EnvService	.env 文件管理
ScheduledTaskService	定时任务动态控制

外部客户端 (app/Clients/)

封装外部服务调用：AiClient、SlsClient、JenkinsClient、AgentClient、MonoClient

定时任务 (routes/console.php)

所有定时任务可在管理后台动态启用/禁用，状态存储在 configs 表：

• git-monitor:check - 每 10 分钟检查 release 分支
• git-monitor:cache - 每天 02:00 刷新 release 缓存
• log-analysis:run - 每天 02:00 执行日志+代码分析
• jenkins:monitor - 每分钟检查 Jenkins 构建

队列任务 (app/Jobs/)

LogAnalysisJob - 后台执行日志分析：获取日志 → 按 app 分组 → AI 分析 → 代码分析 → 保存报告 → 推送通知

路由结构

• Web 路由 (routes/web.php) - 所有页面通过 AdminController@index 渲染 Vue SPA
• API 路由 (routes/api.php) - RESTful API，按模块分组（env、jira、log-analysis、admin 等）
• 中间件 - AdminIpMiddleware IP 白名单、OperationLogMiddleware 操作审计

技术栈

• 后端: PHP 8.2+, Laravel 12, PHPUnit 11
• 前端: Vue 3, Vite 7, Tailwind CSS 4, CodeMirror 6
• 数据库: SQLite (默认) / MySQL
• 队列: Database 驱动
• 外部集成: JIRA、阿里云 SLS、OpenAI 兼容 API、钉钉、Jenkins