xykj-plus/claude-ecc/README.md

# claude-ecc

一个面向 `admin-xy` 生态的 monorepo，当前包含 3 个相对独立的子项目：

- `admin-xy/`：企业管理系统，前后端分离，支持 Docker Compose 生产部署
- `log-analyzer/`：本地日志会话分析工具，用于查看 `.claude/logs/` 下的 trace JSONL
- `dev-assistant/`：面向 `admin-xy` 的页面开发助手，当前仓库内已包含 bridge 服务与默认配置

这个仓库没有统一的根级构建入口。每个子项目都需要在自己的目录中安装依赖、启动和构建。

## 项目总览

| 子项目 | 作用 | 技术栈 | 默认端口 |
| --- | --- | --- | --- |
| `admin-xy/server` | 企业管理系统后端 | Spring Boot 3, Java 21, Spring Security, JPA, Flyway | `9010` |
| `admin-xy/web` | 企业管理系统前端 | React 18, Vite, TypeScript, Zustand, Zod, Radix UI, Tailwind CSS | `9001` |
| `log-analyzer` | Trace 日志分析与可视化 | React 18, Vite, TypeScript, Recharts | `5177` |
| `dev-assistant/bridge` | 页面开发助手桥接服务 | Node.js, TypeScript, Hono, WebSocket, Claude Agent SDK | `9020` |

## 目录结构

```text
.
├── admin-xy/
│   ├── server/          # Spring Boot 后端
│   ├── web/             # React + Vite 前端
│   ├── build-images.sh  # 构建前后端 Docker 镜像
│   └── deploy.sh        # 生产部署脚本
├── log-analyzer/        # 读取 .claude/logs 的本地分析工具
├── dev-assistant/
│   ├── bridge/          # Node bridge 服务
│   └── config/          # 默认模型与桥接配置
└── .claude/logs/        # trace-*.jsonl 会话日志
```

## 环境要求

建议本地准备以下环境：

- Java `21`
- Maven `3.9+`
- Node.js `>=24`
- npm `10+`
- Docker 与 Docker Compose

## 快速开始

### 1. 启动 admin-xy 后端

```bash
cd admin-xy/server
mvn spring-boot:run
```

默认使用 `dev` profile，监听 `http://localhost:9010`，本地开发数据库为 H2 内存库，表结构由 Flyway 迁移管理。

### 2. 启动 admin-xy 前端

```bash
cd admin-xy/web
npm install
npm run dev
```

前端默认监听 `http://localhost:9001`，并把 `/api` 代理到 `http://localhost:9010`。

### 3. 启动 log-analyzer

```bash
cd log-analyzer
npm install
npm run dev
```

`log-analyzer` 会通过 Vite 自定义插件直接读取仓库根目录的 `.claude/logs/`，适合本地排查会话、trace 和 hook 执行记录。

### 4. 启动 dev-assistant bridge

```bash
cd dev-assistant
npm install
npm run bridge:dev
```

bridge 默认监听 `http://localhost:9020`，并允许来自 `http://localhost:9001` 的浏览器请求。默认配置文件位于 `dev-assistant/config/dev-assistant.yaml`。

## admin-xy

`admin-xy` 是仓库里的主业务项目，分为后端 `server/` 与前端 `web/` 两部分。

### 后端

- 入口类：`com.adminxy.AdminXyApplication`
- 技术栈：Spring Boot 3.3、Java 21、Spring Security、Spring Data JPA、Flyway、JWT
- 开发环境：默认 `dev` profile，使用 H2
- 生产环境：`prod` profile，使用 MySQL

常用命令：

```bash
cd admin-xy/server

# 本地运行
mvn spring-boot:run

# 全量测试
mvn test

# 打包（跳过测试）
mvn -DskipTests clean package
```

### 前端

- 技术栈：React 18、Vite、TypeScript、Zustand、react-hook-form、Zod、Radix UI、Tailwind CSS
- 路径别名：`@` -> `src`
- 前端开发端口：`9001`

常用命令：

```bash
cd admin-xy/web

npm install
npm run dev
npm run build
npm run preview
```

### 生产部署

`admin-xy` 的生产部署统一通过脚本完成，不建议手动拆分成单独的 Docker 命令。

```bash
cd admin-xy

# 构建镜像
./build-images.sh
./build-images.sh --no-cache

# 生产部署
sudo ./deploy.sh

# 重启已有服务
sudo ./deploy.sh --restart

# 停止并移除容器
sudo ./deploy.sh --stop
```

部署脚本会：

1. 初始化 `/opt/admin-xy`
2. 校验 `/opt/admin-xy/.env`
3. 同步 `docker-compose.yml`
4. 构建镜像
5. 执行 `docker compose up -d`

生产环境关键变量：

- `SPRING_DATASOURCE_ADMIN_URL`
- `SPRING_DATASOURCE_ADMIN_USERNAME`
- `SPRING_DATASOURCE_ADMIN_PASSWORD`
- `JWT_SECRET`

## log-analyzer

`log-analyzer` 是一个纯前端工具，但它在开发模式下通过 Vite 插件内置了本地文件读取接口，用来直接分析 trace 日志。

当前插件会暴露这些本地接口：

- `/api/folders`
- `/api/sessions`
- `/api/sessions/:sid`

日志来源目录是仓库根下的 `.claude/logs/`，常见文件名格式为：

```text
.claude/logs/trace-<session-id>.jsonl
```

常用命令：

```bash
cd log-analyzer

npm install
npm run dev
npm run build
```

适用场景：

- 查看某次 Codex / Claude 会话的 trace
- 排查 hook 事件时间线
- 分析本地开发流程中的会话数据

## dev-assistant

`dev-assistant` 用于给 `admin-xy` 提供页面开发辅助能力。当前仓库中已明确包含：

- `bridge/`：Node bridge 服务，负责协议适配、WebSocket 会话和配置加载
- `config/`：默认路由、模型目录、日志源和桥接参数

常用命令：

```bash
cd dev-assistant

npm install
npm run bridge:dev
npm run bridge:build
npm run bridge:test
```

默认桥接配置来自 `dev-assistant/config/dev-assistant.yaml`，其中定义了：

- 默认模型路由
- GLM / MiniMax 模型目录
- 工作目录写入限制
- 日志源路径
- bridge 端口与 WebSocket 路径

## 开发约定

### Git 提交

本仓库使用 Conventional Commits 风格：

```text
feat: ...
fix: ...
refactor: ...
docs: ...
test: ...
chore: ...
perf: ...
ci: ...
```

### 运行方式

- 不要在仓库根目录执行统一的 `npm install`
- 每个子项目在自己的目录中单独安装依赖
- `admin-xy`、`log-analyzer`、`dev-assistant` 彼此相对独立

### 日志与排查

- trace 日志统一存放在 `.claude/logs/`
- `log-analyzer` 默认读取该目录
- `admin-xy` 生产部署通过 `deploy.sh` 管理

## 常见任务

| 我想做什么 | 进入目录 | 命令 |
| --- | --- | --- |
| 启动 admin-xy 后端 | `admin-xy/server` | `mvn spring-boot:run` |
| 启动 admin-xy 前端 | `admin-xy/web` | `npm run dev` |
| 构建 admin-xy 前端 | `admin-xy/web` | `npm run build` |
| 运行 admin-xy 后端测试 | `admin-xy/server` | `mvn test` |
| 发布 admin-xy | `admin-xy` | `sudo ./deploy.sh` |
| 启动 log-analyzer | `log-analyzer` | `npm run dev` |
| 构建 log-analyzer | `log-analyzer` | `npm run build` |
| 启动 dev-assistant bridge | `dev-assistant` | `npm run bridge:dev` |

## 说明

这份 README 以当前仓库里的实际目录与配置为准。如果某个子模块后续发生调整，建议同步更新这里的目录结构、启动命令和端口说明。