a-share-analysis/docs/governance/development-workflow.md

开发流程规范

1. 总原则

每个步骤必须留痕、可以直接阅读、可以比较、可以关联到 Git 提交并有明确回退方法。功能开发以功能编号为主键，禁止先写代码、后补需求和设计。

2. 功能状态

proposed → prd_review → designing → approved → developing → verifying → reviewing → released
                                      ↘ blocked
released → superseded

状态只能在证据齐全时前进。released 必须对应 Git 提交和版本；被替代的设计保留原文并标记 superseded，不得删除历史原因。

3. 开发前流程

1. 分配功能编号和英文短名称。
2. 建立 docs/features/<编号>-<短名称>/。
3. 编写 prd.md，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
4. PRD 审核通过后，将产品需求转换为可测试的工程需求。
5. 比较可选方案，记录设计与关键决策。
6. 更新 API、事件和数据结构契约。
7. 编写测试计划和实施计划。
8. 确保 Git 工作区基线可识别，执行：

npm run governance:start -- FEAT-MO-001 market-overview

9. 运行 GitNexus 查询、上下文和影响分析，将结果写入 gitnexus/impact-plan.md。
10. 高风险或关键路径变化必须先向用户说明影响，再进入开发。

开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。

4. 开发过程

• 使用短期功能分支；当前仓库基线建立阶段经用户明确确认后可直接在 main 工作。
• 每个可观察行为先写失败测试，再实现最小代码并重构。
• 需求或设计发生变化时，先更新功能档案并记录原因，再改代码。
• 每个阶段保存必要截图和测试结果，禁止只在聊天中保留决定。
• 发现缺陷时先记录复现步骤和失败测试，禁止无证据猜测式修复。

5. 开发后流程

1. 完成类型检查、单元测试、契约测试、构建和页面流程测试。
2. 对界面变化保存参考图、实现图和同视口对比结果。
3. 查看 Git diff，确认没有计划外文件和密钥。
4. 执行 GitNexus 变更检测；若 MCP 工具不可用，记录限制并至少保存 Git diff 与重新索引结果。
5. 再次运行：

npm run governance:finish -- FEAT-MO-001 market-overview

6. 填写 gitnexus/after.md、detected-changes.md 和 comparison.md。
7. 执行代码 Review，将问题、严重程度、修复提交和复审结论写入 review/code-review.md。
8. 逐条执行开发规范符合性 Review，将结果写入 review/standards-review.md。
9. 任一 Review 为 changes_required 时，返回开发阶段；修复后重跑相关测试、GitNexus开发后分析和 Review。
10. 两项 Review 均为 passed 后，更新发布说明、回退说明、变更记录和版本号。
11. 使用中文 Conventional Commit 提交。
12. 提交后立即将当前分支推送到项目专用 Gitea origin；如果本次创建了标签，再精确推送该标签。
13. 比较本地与远程分支 SHA，并将提交、推送目标和结果写入功能档案。推送失败时保留本地提交，任务状态保持未完成。
14. 提交后执行 npx gitnexus status；若状态过期，再运行 npx gitnexus analyze。

6. 完成定义

下列任一项缺失，功能不得标记完成：

• 需求和设计已确认。
• 实施计划与实际变化一致。
• 代码符合开发规范并包含必要中文注释。
• 测试和构建有最新成功证据。
• 视觉变化有同视口对比证据。
• GitNexus 开发前后报告和差异说明齐全。
• 代码 Review 结论为 passed，Critical 和 Important 问题已关闭。
• 开发规范符合性 Review 结论为 passed。
• 发布说明和回退方法可执行。
• 中文提交已关联功能编号。
• 当前分支和本次新建标签已推送到 origin，功能档案保存远程核对结果。

7. 提交流程

提交格式：

<类型>(<功能编号>): <中文摘要>

示例：

feat(FEAT-MO-001): 新增市场概览结论区
fix(FEAT-MO-001): 修正成交额同比计算口径
docs(GOV-001): 建立工程治理与追溯规范

一次提交应表达一个完整意图，但不为了追求小提交把同一功能切成无法独立理解的碎片。

提交后推送当前分支：

git push origin "$(git branch --show-current)"

如果本次创建了标签，只推送该标签：

git push origin <本次标签名>

禁止使用 --force、--force-with-lease 或 --tags 代替精确推送。推送失败时不得宣称任务完成；应记录不含凭据的错误摘要，排查后重试同一精确命令。

8. 发布与回退

• 使用语义化版本和带注释 Git Tag。
• 发布产物必须对应确定提交，不从浮动分支临时构建。
• 应用优先通过部署上一不可变镜像回退。
• 数据库采用可兼容迁移和前向修复，破坏性回滚需先备份和演练。
• 规则、提示词和消息契约发布后不得原地覆盖，只能新增版本。