# 开发流程规范

## 1. 总原则

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

## 2. 功能状态

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

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

## 3. 开发前流程

1. 确认上一已发布语义化版本及标签提交，执行 `npm run schema:baseline` 和 `npm run schema:verify`。
2. 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` 清单。
3. 将 `database/schema-baselines/<上一发布版本>/` 作为独立中文提交推送 Gitea，核对本地和远程 SHA；既有版本目录禁止覆盖。只有 Git 已跟踪、工作区无改动、当前分支已推送且远程发布标签提交一致时，`governance:start` 才会继续。
4. 分配功能编号和英文短名称。
5. 建立 `docs/features/<编号>-<短名称>/`。
6. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。
7. PRD 审核通过后，将产品需求转换为可测试的工程需求。
8. 比较可选方案，记录设计与关键决策。
9. 在设计中完成安全策略与评估、性能目标与评估；不适用项必须写明原因和边界。
10. 更新 API、事件和数据结构契约，并评估新增依赖的替代、安全、许可证、体积或运行成本及退出方案。
11. 编写测试计划和实施计划，明确安全验证、性能验证和风险相称的测试强度。
12. 明确功能需要的环境变量、功能开关和部署影响；同步更新开发/生产模板，禁止只修改本机真实 env。
13. 确保 Git 工作区基线可识别，执行：

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

14. `governance:start` 会只读复核上一发布版本 Schema 基线；缺失、失效或版本不一致时立即阻断，不会代为生成，并为后续功能建立 `gitnexus/impact-plan.md` 骨架。
15. 功能开发和缺陷修复都必须运行 GitNexus query、context 和 upstream impact，将直接/间接消费者、执行流、风险与工具限制写入 `gitnexus/impact-plan.md`。
16. 必须逐项判断 HTTP/OpenAPI、Web API 与 adapter、消息契约、数据库迁移与 Schema、Redis、API、Scheduler、Worker、配置部署、测试和文档是否需要同步修改。
17. HIGH 或 CRITICAL 风险及关键路径变化必须先向用户说明影响并取得确认，再进入开发；`partial` 或工具不可用不能解释为无影响，必须用静态引用和 Git diff 交叉验证。

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

## 4. 开发过程

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

## 5. 开发后流程

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

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

11. 完成门禁通过后，更新发布说明、回退说明、变更记录和版本号。
12. 使用中文 Conventional Commit 提交。
13. 提交后立即将当前分支推送到项目专用 Gitea `origin`；如果本次创建了标签，再精确推送该标签。
14. 比较本地与远程分支 SHA，并将提交、推送目标和结果写入功能档案。推送失败时保留本地提交，任务状态保持未完成。
15. 提交后执行 `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. 提交流程

提交格式：

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

示例：

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

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

提交后推送当前分支：

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

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

```bash
git push origin <本次标签名>
```

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

## 9. 发布与回退

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