mach-cms-frontend/前端Agent工作纪律.md

CDD 纪律

• 你只修改前端代码，禁止修改后端仓库任何文件
• 如果你发现 openapi.yaml 与实际后端返回不符，停止开发，上报问题，等 YAML 更新后再重新生成 API 代码
• 每次后端接口变更后，必须执行 npm run api:generate 重新生成类型
• 禁止为了"让代码跑通"而修改生成的 src/generated/api/ 目录下的任何文件

---

附录：Git 开发规范（必须遵守）

远程仓库已配置完成，每次 commit 后立即 push。

分支策略

• 直接在 main 分支上开发，不创建 feature 分支
• 每次 commit 后立即 git push origin main

Commit 格式（Conventional Commits）

type(scope): subject

Type: feat fix refactor test docs chore style

Scope（前端）: page component store api router type asset config contract

示例:

feat(page): implement article list with pagination
feat(component): add ArticleCard and Pagination
fix(api): handle 401 auto-refresh token correctly
chore(api-gen): regenerate types from openapi.yaml v0.2
style(component): fix indentation in AdminLayout

少量多次标准（核心）

• 单 commit 单意图：一个 commit 只做一件事
• 文件数 ≤ 10，行数 ≤ 200
• 每次 commit 前必须 npm run build 通过（无 TS 错误）
• commit 后 30 秒内必须 push
• 提交信息用英文，祈使句，首字母小写，≤ 50 字符

与 CDD 结合的提交顺序

1. 契约变更：feat(contract): xxx（由架构 Owner 发起）
2. 后端实现：feat(api): implement xxx endpoint（Agent1 执行）
3. 前端生成：chore(api-gen): regenerate from openapi.yaml
4. 前端对接：feat(page): xxx

禁止行为

• git commit -m "update" / git commit -m "fix bug"
• 一次性提交 20+ 个无关文件
• 提交有 TypeScript 类型错误的代码
• 本地 commit 后数小时不 push
• 绕过 openapi.yaml 直接手写 API 类型

标准流程

git pull --rebase origin main    # 提交前同步
git add -p                       # 交互式添加（推荐）
git diff --cached                # 自我审查
git commit -m "type(scope): subject"
git push origin main             # 立即推送