99 lines
3.6 KiB
Markdown
99 lines
3.6 KiB
Markdown
# 开发流程规范
|
|
|
|
## 1. 总原则
|
|
|
|
每个步骤必须留痕、可以直接阅读、可以比较、可以关联到 Git 提交并有明确回退方法。功能开发以功能编号为主键，禁止先写代码、后补需求和设计。
|
|
|
|
## 2. 功能状态
|
|
|
|
```text
|
|
proposed → designing → approved → developing → verifying → released
|
|
↘ blocked
|
|
released → superseded
|
|
```
|
|
|
|
状态只能在证据齐全时前进。`released` 必须对应 Git 提交和版本；被替代的设计保留原文并标记 `superseded`，不得删除历史原因。
|
|
|
|
## 3. 开发前流程
|
|
|
|
1. 分配功能编号和英文短名称。
|
|
2. 建立 `docs/features/<编号>-<短名称>/`。
|
|
3. 填写需求、范围、非目标和验收标准。
|
|
4. 比较可选方案，记录设计与关键决策。
|
|
5. 更新 API、事件和数据结构契约。
|
|
6. 编写测试计划和实施计划。
|
|
7. 确保 Git 工作区基线可识别，执行：
|
|
|
|
```bash
|
|
npm run governance:start -- FEAT-MO-001 market-overview
|
|
```
|
|
|
|
8. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
|
|
9. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
|
|
|
|
开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。
|
|
|
|
## 4. 开发过程
|
|
|
|
- 使用短期功能分支；当前仓库基线建立阶段经用户明确确认后可直接在 `main` 工作。
|
|
- 每个可观察行为先写失败测试，再实现最小代码并重构。
|
|
- 需求或设计发生变化时，先更新功能档案并记录原因，再改代码。
|
|
- 每个阶段保存必要截图和测试结果，禁止只在聊天中保留决定。
|
|
- 发现缺陷时先记录复现步骤和失败测试，禁止无证据猜测式修复。
|
|
|
|
## 5. 开发后流程
|
|
|
|
1. 完成类型检查、单元测试、契约测试、构建和页面流程测试。
|
|
2. 对界面变化保存参考图、实现图和同视口对比结果。
|
|
3. 查看 Git diff，确认没有计划外文件和密钥。
|
|
4. 执行 GitNexus 变更检测；若 MCP 工具不可用，记录限制并至少保存 Git diff 与重新索引结果。
|
|
5. 再次运行：
|
|
|
|
```bash
|
|
npm run governance:finish -- FEAT-MO-001 market-overview
|
|
```
|
|
|
|
6. 填写 `gitnexus/after.md`、`detected-changes.md` 和 `comparison.md`。
|
|
7. 更新发布说明、回退说明、变更记录和版本号。
|
|
8. 使用中文 Conventional Commit提交。
|
|
9. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。
|
|
|
|
## 6. 完成定义
|
|
|
|
下列任一项缺失，功能不得标记完成：
|
|
|
|
- 需求和设计已确认。
|
|
- 实施计划与实际变化一致。
|
|
- 代码符合开发规范并包含必要中文注释。
|
|
- 测试和构建有最新成功证据。
|
|
- 视觉变化有同视口对比证据。
|
|
- GitNexus 开发前后报告和差异说明齐全。
|
|
- 发布说明和回退方法可执行。
|
|
- 中文提交已关联功能编号。
|
|
|
|
## 7. 提交流程
|
|
|
|
提交格式：
|
|
|
|
```text
|
|
<类型>(<功能编号>): <中文摘要>
|
|
```
|
|
|
|
示例：
|
|
|
|
```text
|
|
feat(FEAT-MO-001): 新增市场概览结论区
|
|
fix(FEAT-MO-001): 修正成交额同比计算口径
|
|
docs(GOV-001): 建立工程治理与追溯规范
|
|
```
|
|
|
|
一次提交应表达一个完整意图，但不为了追求小提交把同一功能切成无法独立理解的碎片。
|
|
|
|
## 8. 发布与回退
|
|
|
|
- 使用语义化版本和带注释 Git Tag。
|
|
- 发布产物必须对应确定提交，不从浮动分支临时构建。
|
|
- 应用优先通过部署上一不可变镜像回退。
|
|
- 数据库采用可兼容迁移和前向修复，破坏性回滚需先备份和演练。
|
|
- 规则、提示词和消息契约发布后不得原地覆盖，只能新增版本。
|