| | |
|---|
| | | # 编码规范 |
|---|
| | | # 编码规范 |
|---|
| | | |
|---|
| | | 创建人员：Codex |
|---|
| | | 文件职责：定义通用编码注意事项、编码流程、验收方式、问题修复原则，适用于管理体系下的多个项目。 |
|---|
| | | 管理规范/模板：../../管理系统说明.md；../../全局规范.md；开发环境创建指南.md；开发审计规范.md；非临时文件应能追溯到事项、需求、方案、验收结果。 |
|---|
| | | 引用文件：../../管理系统说明.md；../../全局规范.md；开发环境创建指南.md；开发审计规范.md；编码方案范本.md；AI管理体系建议.md；旧项目开发规范已去项目化抽象。 |
|---|
| | | 记录方式：全局编码规范文档；编码流程、方案要求、测试验收或问题修复口径变化时更新。 |
|---|
| | | |
|---|
| | | 统一依赖：本规范必须同时遵守 `../../全局规范.md` 和 `../project-doc/项目规范.md`；项目本地编码规范可补充流程，但不得违反全局规范、全局项目规范和本体系硬约束。 |
|---|
| | | |
|---|
| | | ## 1. 目标 |
|---|
| | | |
|---|
| | |
|---|
| | | 1. 代码放在 `dev/<target>-dev/`。 |
|---|
| | | 2. 测试放在 `dev/<target>-dev/test/`。 |
|---|
| | | 3. 目标相关代码文档、测试说明和重型编码方案附件放在 `dev-doc/<target>-doc/`。 |
|---|
| | | 4. 开发事项总纲、计划、执行日志、审计报告和问题记录统一放在 `dev-doc/` 根级账本，不在目标目录复制第二套。 |
|---|
| | | 4. 开发事项总纲、计划、执行日志和问题记录默认放在 `dev-doc/` 根级账本，不在目标目录复制第二套。 |
|---|
| | | 5. 审计报告入口按目标体系分账：需求开发、项目工具开发等独立开发事项写 `dev-doc/开发审计报告.md`；实验开发写 `exp-doc/实验审计报告.md`；案例分析开发写 `ana-doc/案例审计报告.md`。 |
|---|
| | | |
|---|
| | | 常见映射： |
|---|
| | | |
|---|
| | | 1. 产品 / 需求开发：`dev/pro-dev/`、`dev/pro-dev/test/`、`dev-doc/pro-doc/`。 |
|---|
| | | 1. 需求 / 需求开发：`dev/pro-dev/`、`dev/pro-dev/test/`、`dev-doc/pro-doc/`。 |
|---|
| | | 2. 实验开发：`dev/exp-dev/`、`dev/exp-dev/test/`、`dev-doc/exp-doc/`。 |
|---|
| | | 3. 案例分析开发：`dev/ana-dev/`、`dev/ana-dev/test/`、`dev-doc/ana-doc/`。 |
|---|
| | | |
|---|
| | |
|---|
| | | 编码前按以下顺序执行： |
|---|
| | | |
|---|
| | | 1. 确认事项编号、任务目标、责任模块。 |
|---|
| | | 2. 阅读相关需求文档、产品方案、架构文档、模块说明文档、核心流程文档、流程图、接口文档；没有的上游文档要说明“不适用”。 |
|---|
| | | 2. 阅读相关需求文档、需求方案、架构文档、模块说明文档、核心流程文档、流程图、接口文档；没有的上游文档要说明“不适用”。 |
|---|
| | | 3. 判断本次是需求问题、代码问题、数据问题，还是流程问题。 |
|---|
| | | 4. 明确改动范围，列出会被影响的模块和产物。 |
|---|
| | | 5. 如属于多模块或长流程改动，先写代码编写方案。 |
|---|
| | | 6. 明确验收方式，包括最小样本、边界样本、失败样本、全量样本。 |
|---|
| | | 7. 再开始编码。 |
|---|
| | | |
|---|
| | | 如果本次是产品体系交付到开发的事项，还必须先读项目本地 `pro-doc/产品规范.md`、`pro-doc/需求规范.md`，以及需求文档引用的产品方案、架构文档、模块说明文档、核心流程文档。若这些上游产品文档缺失或互相冲突，应按产品/需求问题退回，不得靠代码补口径。 |
|---|
| | | 如果本次是需求体系交付到开发的事项，还必须先读项目本地 `pro-doc/需求规范.md`、`pro-doc/需求规范.md`，以及需求文档引用的需求方案、架构文档、模块说明文档、核心流程文档。若这些上游需求文档缺失或互相冲突，应按需求问题退回，不得靠代码补口径。 |
|---|
| | | |
|---|
| | | 如果本次是实验开发、案例分析开发或项目工具开发，也必须读取对应目标体系规范和事项账本；开发规范只约束怎么写代码，不替代目标体系的业务流程。 |
|---|
| | | |
|---|
| | |
|---|
| | | |
|---|
| | | 这类任务通常不需要先写需求文档，也不需要写代码编写方案。 |
|---|
| | | |
|---|
| | | 产品体系正式交付到开发的事项，默认不适用“无需求文档的轻量实现”。如果产品侧只给了口头要求或草案，应先回到产品/需求流程形成可审计需求，再进入开发。 |
|---|
| | | 这类任务完成后通常不强制审核员审核，但必须自测并留下运行方式、输出位置和自测结果。如果代码开始影响核心流程、正式产物、长期接口或被其他事项复用，应升级到有需求文档的轻量实现或重型实现。 |
|---|
| | | |
|---|
| | | 需求体系正式交付到开发的事项，默认不适用“无需求文档的轻量实现”。如果需求侧只给了口头要求或草案，应先回到需求流程形成可审计需求，再进入开发。 |
|---|
| | | |
|---|
| | | 执行流程： |
|---|
| | | |
|---|
| | |
|---|
| | | 4. 写完后先做基础自测，例如语法、导入、最小样本、关键输出。 |
|---|
| | | 5. 自检：逐条对比需求文档和代码实现，确认是否有字段缺失、口径偏差、流程绕过、产物不一致。 |
|---|
| | | 6. 修掉自检发现的问题。 |
|---|
| | | 7. 输出验收结论，说明跑了什么测试、结果是什么、还有什么限制。 |
|---|
| | | 7. 交给审核员做轻量代码审核，重点检查需求-代码一致性、自测结果、关键输出、是否越权写正式产物、是否存在明显数据或流程风险。 |
|---|
| | | 8. 审核通过后输出验收结论，说明跑了什么测试、结果是什么、还有什么限制。 |
|---|
| | | |
|---|
| | | 最低交付： |
|---|
| | | |
|---|
| | |
|---|
| | | 2. 对应需求文档。 |
|---|
| | | 3. 自测命令和结果。 |
|---|
| | | 4. 需求-代码自检结论。 |
|---|
| | | 5. 未解决问题或限制。 |
|---|
| | | 5. 审核员轻量审核结论。 |
|---|
| | | 6. 未解决问题或限制。 |
|---|
| | | |
|---|
| | | ### 5.3 有需求文档的重型实现 |
|---|
| | | |
|---|
