180 lines
6.8 KiB
Markdown
180 lines
6.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件是 Claude Code 在该仓库中的根级路由指南。保持简短、稳定，只记录"Claude 无法从代码本身轻易推断"的事实、硬约束和工具路由。可重复执行的流程、检查清单、深度参考资料放入 `.claude/skills/` 或 `.claude/commands/`。
|
||
|
||
---
|
||
|
||
## 通用工作偏好
|
||
|
||
> 适用于本项目所有会话，与用户级 `~/.claude/CLAUDE.md` 中的个人偏好保持一致。
|
||
|
||
**语言**：默认中文回复；英文术语、命令、代码标识符保留英文。注释、文档、commit 优先遵循项目规范。
|
||
|
||
**工作方式**：
|
||
- 对多文件、非显然或有风险的改动，先用 2-3 句话说明思路
|
||
- 对架构/接口/依赖决策，给出 2-3 个方案、权衡和推荐理由
|
||
- 对关键歧义先提问；低风险细节可先明确假设再推进
|
||
- 优先复用现有代码模式；只有现有模式不足时再引入新抽象
|
||
- 复杂、可拆分、上下文污染高的任务，优先使用合适的 subagent
|
||
|
||
**代码与文档**：注释解释意图、前提、边界和异常语义，不复述代码表面行为。公共 API 用结构化注释（summary / params / returns / throws）。
|
||
|
||
**验证习惯**：改动完成后运行最小但足以证明正确性的验证集。不用空方法、TODO 占位或跳过关键校验来冒充完成。
|
||
|
||
---
|
||
|
||
## 先判断目标项目
|
||
|
||
这是一个 monorepo，子项目彼此独立：
|
||
|
||
| 子项目 | 技术栈 | 端口 |
|
||
|--------|--------|------|
|
||
| `admin-xy/server` | Spring Boot 3 + Java 21 + Flyway + H2(dev)/MySQL(prod) | 9010 |
|
||
| `admin-xy/web` | React 18 + Vite + TypeScript + Radix + Tailwind | 9001 |
|
||
| `dev-assistant/bridge` | Node.js + TypeScript，AI 代理桥接服务（REST + WebSocket） | 9020 |
|
||
| `dev-assistant/web-sdk` | TypeScript SDK，嵌入式 AI 助手前端组件 | — |
|
||
| `log-analyzer/` | Vite + React + TS，解析 `.claude/logs/` 下的 hook trace JSONL | — |
|
||
| `.claude/` | Claude Code 资产目录（skills / commands / hooks / rules / scripts / logs） | — |
|
||
|
||
工作前先选定目标项目，安装、构建、测试、发布均在对应子项目内分别执行。
|
||
|
||
---
|
||
|
||
## 高频命令
|
||
|
||
### `admin-xy/server`
|
||
|
||
```bash
|
||
mvn spring-boot:run # 默认 dev profile（H2，端口 9010）
|
||
mvn -DskipTests clean package
|
||
mvn test
|
||
mvn test -Dtest=AuthServiceTest
|
||
mvn test -Dtest=AuthServiceTest#shouldLoginWithValidCredentials
|
||
```
|
||
|
||
- 入口：`com.adminxy.AdminXyApplication`
|
||
- 生产 profile：`prod`（MySQL，全部敏感配置来自环境变量）
|
||
|
||
### `admin-xy/web`
|
||
|
||
```bash
|
||
npm install && npm run dev # Vite dev server 端口 9001，/api 反代到 http://localhost:9010
|
||
npm run build && npm run preview
|
||
```
|
||
|
||
- 路径别名：`@` → `src`
|
||
- UI：Radix + Tailwind，组件在 `src/components/ui`
|
||
|
||
### `admin-xy/` 部署
|
||
|
||
```bash
|
||
./build-images.sh # 构建镜像
|
||
sudo ./deploy.sh # 生产部署
|
||
sudo ./deploy.sh --stop | --restart
|
||
```
|
||
|
||
- 生产配置：`/opt/admin-xy/.env`
|
||
|
||
### `dev-assistant/`
|
||
|
||
```bash
|
||
cd dev-assistant && npm install
|
||
npm run dev # bridge 服务启动，端口 9020
|
||
npm run build # tsc 构建
|
||
npm test # vitest 单元测试
|
||
```
|
||
|
||
- bridge 提供 `/api/models`、WebSocket `/ws` 等接口
|
||
- 需要 AI 提供方的 API Key（配置在 `.env` 或环境变量中，严禁硬编码）
|
||
|
||
### `log-analyzer/`
|
||
|
||
```bash
|
||
npm install && npm run dev # 自定义 Vite 插件读取 .claude/logs/
|
||
```
|
||
|
||
---
|
||
|
||
## 关键架构事实
|
||
|
||
### `admin-xy` 后端
|
||
|
||
- **分层**：`Controller → Service → Repository → Entity → DTO`，按领域（auth/user/role/menu）分包
|
||
- **统一响应**：`ApiResponse<T>`；分页：`PageResult<T>`
|
||
- **认证**：JWT 无状态；`JwtAuthenticationFilter` 从 `Authorization: Bearer <token>` 读取
|
||
- **授权**：`@EnableMethodSecurity` + `@PreAuthorize` + `permission/` 自定义校验
|
||
- **迁移**：Flyway 管理，`ddl-auto=validate`
|
||
|
||
### `admin-xy` 前端
|
||
|
||
- **路由**：react-router-dom v6，含 `guards.tsx` 鉴权守卫
|
||
- **状态**：Zustand，跨页面可变状态禁用 Context
|
||
- **表单**：Zod schema → `@hookform/resolvers/zod` → react-hook-form
|
||
- **API**：axios 实例在 `src/lib/` 统一处理 JWT 注入、401 拦截
|
||
|
||
### `.claude/` 约束
|
||
|
||
- `hooks/trace.mjs` 必须把日志写到脚本自身路径下的 `../logs`，不能依赖 `cwd`
|
||
- 任何新 hook 若需写文件，同样以脚本自身路径定位输出目录
|
||
- `.claude/logs/` 已纳入 git 追踪，用于 `log-analyzer` 复现会话
|
||
- `settings.json` 使用 `$CLAUDE_PROJECT_DIR` 环境变量引用 hook 脚本路径（Claude Code 运行时自动注入），避免硬编码绝对路径
|
||
|
||
---
|
||
|
||
## 硬约束
|
||
|
||
- 不要在仓库根执行"统一构建/统一测试"替代子项目命令（除非任务明确跨多个项目）
|
||
- 禁止修改已发布的 Flyway `V*.sql`；新增迁移必须递增版本号
|
||
- 生产敏感配置必须来自环境变量或 `/opt/admin-xy/.env`，严禁硬编码
|
||
- `JWT_SECRET` 必须至少 32 字节
|
||
- 前端禁止 `console.log`；使用现有 logger 或 sonner
|
||
- 后端 `9010`、前端 `9001`、bridge `9020`；改端口须同步更新 `vite.config.ts`、`docker-compose.yml`、`application.yml`
|
||
- 默认远程仓库：Gitee `https://gitee.com/xiangyuetech-d/claude-ecc.git`
|
||
- Git 提交格式：`feat|fix|refactor|docs|test|chore|perf|ci: <desc>`，不追加自动归因尾行
|
||
|
||
---
|
||
|
||
## 本地 Skills / Commands 路由
|
||
|
||
项目本地 skill/command 与通用能力冲突时，优先使用仓库内定义。详细编码、安全、测试规则以 `.claude/rules/` 下各 `.md` 为准；本文件只保留路由和高信号约束。
|
||
|
||
### 研究与规划
|
||
|
||
- `/plan`：先分析风险并输出实施计划
|
||
- `/search-first`：先研究现有方案
|
||
- `/docs` / `/documentation-lookup`：查最新框架文档
|
||
- `/deep-research`：多源研究、引用汇总
|
||
- `/blueprint`：多阶段、需长期拆解的复杂任务
|
||
|
||
### `admin-xy/server` 后端
|
||
|
||
- `/springboot-patterns`、`/java-coding-standards`、`/jpa-patterns`
|
||
- `/database-migrations`、`/springboot-security`、`/security-review`
|
||
- `/springboot-tdd`、`/springboot-verification`
|
||
|
||
### `admin-xy/web` 与 `log-analyzer` 前端
|
||
|
||
- `/frontend-patterns`、`/coding-standards`、`/docs`
|
||
- `/e2e` / `/e2e-testing`（Playwright）
|
||
|
||
### 质量与发布
|
||
|
||
- `/verify` / `/verification-loop`：统一验证当前改动
|
||
- `/quality-gate`、`/code-review`、`/ai-regression-testing`
|
||
- `/publish-admin-xy`：admin-xy 上线发布流程
|
||
- `/deployment-patterns`、`/docker-patterns`
|
||
|
||
### 仓库维护
|
||
|
||
- `/codebase-onboarding`、`/context-budget`
|
||
- `/security-scan`：扫描 `.claude/` 配置风险
|
||
- `/rules-distill`：把重复经验沉淀回规则文件
|
||
|
||
---
|
||
|
||
## 维护原则
|
||
|
||
- 本文件控制在 200 行以内；超出后优先拆到子级 `CLAUDE.md` 或 skill/command
|
||
- 只保留"Claude 不能从代码轻易推断"的事实
|
||
- 如果 `admin-xy/` 和 `dev-assistant/` 的规则继续分化，在各自目录新增子级 `CLAUDE.md`
|