开发流程规范

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、MySQL 5.7.x、utf8mb4_general_ci 和固定开发主机白名单（回环地址或 112.192.20.11）导出 Schema；配置优先读取被 Git 忽略的 deploy/env/development/api.env.local，不存在时才读取无秘密模板。空开发库保存 format v3 的 captured_empty 清单，不创建空 SQL；MySQL 未启用时只保存 not_applicable 清单。
将 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/impact-plan.md 骨架。
功能开发和缺陷修复都必须运行 GitNexus query、context 和 upstream impact，将直接/间接消费者、执行流、风险与工具限制写入 gitnexus/impact-plan.md。
必须逐项判断 HTTP/OpenAPI、Web API 与 adapter、消息契约、数据库迁移与 Schema、Redis、API、Scheduler、Worker、配置部署、测试和文档是否需要同步修改。
HIGH 或 CRITICAL 风险及关键路径变化必须先向用户说明影响并取得确认，再进入开发；partial 或工具不可用不能解释为无影响，必须用静态引用和 Git diff 交叉验证。

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

4. 开发过程

使用短期功能分支；当前仓库基线建立阶段经用户明确确认后可直接在 main 工作。
每个可观察行为先写失败测试，再实现最小代码并重构。
需求或设计发生变化时，先更新功能档案并记录原因，再改代码。
代码持续检查安全边界与性能目标；出现新的攻击面、容量假设或依赖时，先回写设计和测试计划。
只有真实重复已经出现且职责稳定时才抽取工具、组件或共享库，禁止按预期未来需求提前抽象。
每个阶段保存必要截图和测试结果，禁止只在聊天中保留决定。
发现缺陷时先记录复现步骤和失败测试，禁止无证据猜测式修复。

5. 开发后流程

完成类型检查、单元测试、契约测试、构建和页面流程测试。
对界面变化保存参考图、实现图和同视口对比结果。
查看 Git diff，确认没有计划外文件和密钥。
执行 GitNexus 变更检测；若 MCP 工具不可用，记录限制并至少保存 Git diff 与重新索引结果。
填写 gitnexus/after.md、detected-changes.md 和 comparison.md。
填写独立 development-summary.md，明确原始需求、范围变化、实际完成、修复缺陷、未完成项、关键提交和验证证据；不得合并到发布说明。
执行代码 Review，将安全与残余风险、性能与资源影响、GitNexus 同步修改、问题严重程度、修复提交和复审结论写入 review/code-review.md。
逐条执行开发规范符合性 Review，检查前后端架构、抽象依据、依赖评估和开发总结，将结果写入 review/standards-review.md。
任一 Review 为 changes_required 时，返回开发阶段；修复后重跑相关测试、GitNexus开发后分析和 Review。
两项 Review 均为 passed 且全部证据文件齐全后，运行：

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

完成门禁通过后，更新发布说明、回退说明、变更记录和版本号。
使用中文 Conventional Commit 提交。
提交后立即将当前分支推送到项目专用 Gitea origin；如果本次创建了标签，再精确推送该标签。
比较本地与远程分支 SHA，并将提交、推送目标和结果写入功能档案。推送失败时保留本地提交，任务状态保持未完成。
提交后执行 npx gitnexus status；若状态过期，再运行 npx gitnexus analyze。

6. 完成定义

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

需求和设计已确认。
实施计划与实际变化一致。
代码符合开发规范并包含必要中文注释。
测试和构建有最新成功证据。
视觉变化有同视口对比证据。
GitNexus 开发前后报告和差异说明齐全。
开发总结明确记录原始需求、范围变化、完成需求、修复缺陷、延期项、提交和验证证据。
安全策略、性能目标、验证证据和残余风险完整；不适用项有原因及边界。
GitNexus 已评估其他功能和模块的影响，同步修改清单与实际变更一致。
前端 Axios/API 分域和后端业务模块内按需分层符合开发规范。
代码 Review 结论为 passed，Critical 和 Important 问题已关闭。
开发规范符合性 Review 结论为 passed。
发布说明和回退方法可执行。
中文提交已关联功能编号。
当前分支和本次新建标签已推送到 origin，功能档案保存远程核对结果。
配置契约变化已同步开发/生产模板、systemd、Nginx 和源码部署文档。
pnpm verify:release 源码发布门禁通过；外部基础设施不可达时按前置条件失败，不得由项目脚本启动替代服务。
下一版本开发前所需的上一发布版本 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；启用但无对象时目录也只包含 manifest.yaml，状态为 format v3 的 captured_empty 并记录零对象计数。
schema:baseline 不接受 env 路径、环境类型或数据库名参数；配置路径固定在开发环境，生产配置和生产数据库不属于该命令的权限范围。
修正已发布基线必须新增治理记录说明原因，禁止静默覆盖或重写历史目录。
首次启用 MySQL 的版本必须在 MySQL 5.7 开发环境生成第一份真实或 captured_empty Schema 基线；format v1/v2 历史清单保持只读兼容，禁止因工具升级重写。

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。
发布产物必须对应确定提交，不从浮动分支临时构建。
应用通过把 /opt/a-share-analysis/current 原子切回上一完整不可变发布目录并重启 systemd 服务回退。
数据库采用可兼容迁移和前向修复，破坏性回滚需先备份和演练。
规则、提示词和消息契约发布后不得原地覆盖，只能新增版本。

9.4 KiB Raw Permalink Blame History Unescape Escape