liuhuayong 7e90ae7e14 fix: add actual files (remove submodule refs)

2026-06-13 13:48:51 +08:00

6.8 KiB

Raw Permalink Blame History

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`

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`

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/` 部署

./build-images.sh            # 构建镜像
sudo ./deploy.sh             # 生产部署
sudo ./deploy.sh --stop | --restart

生产配置：/opt/admin-xy/.env

`dev-assistant/`

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

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

6.8 KiB Raw Permalink Blame History Unescape Escape

CLAUDE.md

通用工作偏好

先判断目标项目

高频命令

admin-xy/server

admin-xy/web

admin-xy/ 部署

dev-assistant/

log-analyzer/