269 lines
6.6 KiB
Markdown
269 lines
6.6 KiB
Markdown
# 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 以当前仓库里的实际目录与配置为准。如果某个子模块后续发生调整，建议同步更新这里的目录结构、启动命令和端口说明。
|