# 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 监控** - 构建状态监控和钉钉通知

## 常用命令

```bash
# 开发环境（同时启动后端、队列、日志、前端）
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