CLAUDE-template.md 4.42 KB

Edit Raw Blame History



CLAUDE.md — ERP项目 Claude Code 主指令文件


本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。


🎯 项目概述


项目名称: 【人工填写：公司 + 项目名，例如"XX 公司 ERP 管理系统"】

项目简述: 【人工填写：一句话描述项目目标，例如"面向中小制造企业的全流程 ERP，涵盖采购/库存/生产/销售/财务"】

目标用户: 【人工填写：谁会用，例如"企业内部管理人员（采购员、仓管员、生产主管、销售员、财务人员、管理层）"】

部署方式: 【人工填写：私有化部署 / 云部署 / Docker 容器化 等】


📐 编码行为约束


你必须做的 ✅


严格遵循 docs/04-技术规范.md——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 等项目专属技术规约全部在此

严格遵循 docs/04-技术规范.md § 1.2 分层结构 / § 2.1 目录约定——文件放对位置

每个后端接口 必须先在 docs/05-API接口契约.md 定义，再编码实现

每个功能可追溯到 req_id <模块代码>-<子模块代码>-<功能名>——commit tag + 代码注释（如 // USR-USR-LOGIN: 用户登录）+ plan/spec 文件名均用此 tag

遇到跨模块改动（动到非当前模块的代码）——允许改，但必须在《模块完成报告》记录原因 / 影响评估（留痕）


你禁止做的 🚫


主会话直接 mysql -e 跑业务 DDL（只读查询 / 临时本地调试除外）——业务 schema 必须走 sql/migrations/V_n__*.sql，详见下方 Schema 演化规约


Schema 演化规约（Flyway migration）


文件命名：sql/migrations/V<n>__<snake_case_desc>.sql，例：V5__add_user_email_unique_index.sql


版本号分配：建文件前 ls sql/migrations/V*.sql 查当前最大 n，新文件 n_max + 1


Apply 方式：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 build.gradle 声明 flyway-core + flyway-mysql 依赖）。scripts/setup-test-db.mjs 只负责清空库，不做 apply

已合并的 migration 永不修改：发现错了写一个补救 migration（如 V7__fix_V5_index_name.sql），旧 V_n.sql


临时调试 DDL：临时在本地试字段/索引可手动 mysql -e，但不写 migration；下次 setup-test-db.mjs 会 drop+create 清掉

A4 生成的 V1：V1__initial_schema.sql 是 A 阶段由 db-init 从 docs/03-数据库设计文档.md（A3 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由 B 阶段每个 REQ 按需写入，同时反向同步更新 docs/03 对应表小节以保持 SSoT 一致


🌱 演示数据（demo seed）


人工验收/演示三步走：node scripts/setup-test-db.mjs（DROP+CREATE 空库）→ 起后端（Spring Boot 启动时 Flyway 建 schema）→ node scripts/seed-demo-data.mjs（注入演示种子）

种子来源：sql/seed/*.sql 由 B 阶段每个后端模块完成后自动生成、随 git 提交；演示数据用确定性显式主键，区间 1000–9999


数据不持久：库会被各测试闸门 DROP+CREATE 随时重建——种子不保证存活，只保证随时可复现；重建后按上述时序重新注入即可

幂等账本：账本表 _demo_seed_history 由 seed-demo-data.mjs 自建自管，重复执行自动跳过已应用文件


🗂️ Git 提交规范

每次提交必须遵循以下格式：
<type>(<scope>): <subject>


scope: 模块名，如 user / inventory / order


subject: 简短描述；业务类（feat / fix / test）必须带 req_id（<模块代码>-<子模块代码>-<功能名>，如 USR-USR-LOGIN）后缀


type 含义：


type
看到它意味着


feat

新能力上线——用户多了一个功能、接口、页面或业务规则


fix

修 bug——原来行为错了，这次改对


refactor

重构——外部行为不变，只改代码结构 / 命名 / 抽象


docs

文档改动——只动 Markdown / 代码注释，不动实现


style

格式调整——空白 / 缩进 / import 顺序，逻辑 0 变化


test

只动测试代码——补用例 / 修 fixture，不碰实现


chore

流程维护——构建 / 依赖 / 工具 / 证据档案 / 里程碑元数据等非业务动作