开发流程规范

1. 总原则

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

2. 功能状态

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

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

3. 开发前流程

确认上一已发布语义化版本及标签提交，执行 npm run schema:baseline 和 npm run schema:verify。
MySQL 已启用时只能从 APP_ENV=development、a_share_analysis_dev 和本机回环地址导出完整 Schema；MySQL 未启用时只保存 not_applicable 清单，不创建空 SQL。
将 database/schema-baselines/<上一发布版本>/ 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，governance:start 才会继续。
分配功能编号和英文短名称。
建立 docs/features/<编号>-<短名称>/。
编写 prd.md，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
PRD 审核通过后，将产品需求转换为可测试的工程需求。
比较可选方案，记录设计与关键决策。
更新 API、事件和数据结构契约。
编写测试计划和实施计划。
明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
确保 Git 工作区基线可识别，执行：

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

governance:start 会只读复核上一发布版本 Schema 基线；缺失、失效或版本不一致时立即阻断，不会代为生成。
运行 GitNexus 查询、上下文和影响分析，将结果写入 gitnexus/impact-plan.md。
高风险或关键路径变化必须先向用户说明影响，再进入开发。

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

4. 开发过程

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

5. 开发后流程

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

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

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

6. 完成定义

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

需求和设计已确认。
实施计划与实际变化一致。
代码符合开发规范并包含必要中文注释。
测试和构建有最新成功证据。
视觉变化有同视口对比证据。
GitNexus 开发前后报告和差异说明齐全。
代码 Review 结论为 passed，Critical 和 Important 问题已关闭。
开发规范符合性 Review 结论为 passed。
发布说明和回退方法可执行。
中文提交已关联功能编号。
当前分支和本次新建标签已推送到 origin，功能档案保存远程核对结果。
配置契约变化已同步开发/生产模板和适用的 Compose、systemd、Nginx及部署文档。
下一版本开发前所需的上一发布版本 Schema 基线已验证、独立提交并推送 Gitea。

7. 数据库 Schema 基线

基线目录固定为 database/schema-baselines/vX.Y.Z/，版本是被备份的已发布版本。
真实基线由 schema.sql、manifest.yaml、checksum.sha256 组成；范围包括表、索引、外键、视图、触发器、存储过程、函数和 Event Scheduler 事件，不含数据。
MySQL 未启用时目录只能包含 manifest.yaml，状态为 not_applicable、原因为 mysql_disabled。
schema:baseline 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。
修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。
首次启用 MySQL 的版本必须通过迁移建立开发库，并在 MySQL 5.7 开发环境生成第一份真实 Schema 基线。

8. 提交流程

提交格式：

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

示例：

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 代替精确推送。推送失败时不得宣称任务完成；应记录不含凭据的错误摘要，排查后重试同一精确命令。

9. 发布与回退

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

7.0 KiB Raw Blame History Unescape Escape