xykj-plus/claude-ecc/CLAUDE.md

# 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`