cps-develop-docs/README.md

CPS 研发团队规范与文档导航 (Developer Playbook)

欢迎来到 CPS 研发团队规范文档库！本文档是整个团队在架构设计、编码实施、项目协同以及代码审查等环节的唯一基准指南。

🗂️ 核心目录导航

📂 01 - Knowledge & Prompts (知识库与架构沉淀)

沉淀团队宏观架构决策与 AI 提效资产，强调“为什么这么做”而非单纯的“怎么做”。

• 📝 Architecture Decision Records (ADR)：记录重大技术选型对比与架构演进背景。
• 🤖 AI Prompts：存放标准代码生成、Code Review 及排障的 AI 提示词模板。

📂 02 - Architecture & Design (系统与架构设计规范)

脱离具体编程语言与框架的通用系统设计、接口契约与数据规约。

• 🏗️ 2.1 系统架构设计原则：定义单体/微服务边界、分层架构模式（DDD/MVC/BFF）及依赖解耦底线。
• 🔌 2.2 API 接口设计规范：规定 RESTful 协议标准、统一的请求头、响应结构及分页/错误码策略。
• 💾 2.3 数据库与存储设计规范：明确表结构与字段命名、慢查询规避红线及 Redis 缓存防雪崩/穿透规范。

📂 03 - Coding & Frameworks (编码基础与框架实施规范)

针对具体编程语言和 Web 框架的强制性编码约束与最佳实践。

• 💻 Python 编码与开发规范：定义 Python 现代工具链 (uv, Ruff)、类型注解标准及核心设计范式。
• ⚙️ 框架开发实施规范 (Django/DRF)：规定 Model/Serializer 性能红线、Fat Service 分层原则及数据隔离策略。
• 🏢 GTCO_AI 项目特有业务实施规范：针对 GTCO_AI 业务项目的私有红线、专属鉴权绑定与联调脚本约束。

📂 04 - Quality & Review (质量保证与代码审查)

保障代码合入主干前的高质量与安全性，防范线上故障回归。

• 🧪 4.1 自动化测试规范：明确 3A 原则、Mock 边界及单元/集成/E2E 接口测试的执行策略。
• 🧐 4.2 代码审查 (Code Review) 规范：梳理 CR 触发门禁、架构/逻辑审查 Checklist 及团队沟通礼仪。
• 🛡️ 4.3 安全编码规范：防御 SQL 注入/XSS/CSRF 三大 Web 漏洞，制定敏感数据脱敏与存储红线。

📂 05 - Collaboration & Delivery (协作与交付规范)

定义代码从本地开发到生产环境的标准化流转轨道与持续集成策略。

• 🌿 5.1 版本控制与代码提交规范：确立常驻三分支模型 (main/test/dev)、Angular 提交规范及 SemVer 版本号管理。
• 🚀 5.2 CI/CD 与环境部署规范：定义多环境隔离标准及基于 Jenkinsfile 的全自动化流水线与卡点策略。

📂 ref (历史参考资料，仅供借鉴)

ref/ 目录用于存放历史规范、外部参考文档或迁移期材料，仅用于对照和借鉴。

• ❌ 不作为当前项目执行标准：开发、评审与交付不以 ref/ 下文档作为判定依据。
• ✅ 以正式规范为准：实际执行统一遵循 01 到 05 目录中的正式规范文档。

📖 如何使用本指南？

1. 👨‍💻 开发者日常使用 (AI Native 驱动)

本规范库不仅是给人看的，更是给 AI 助手（如 Cursor, GitHub Copilot）看的。我们通过 01 - Knowledge & Prompts/AI Prompts/ 目录下的指令文件来驱动 AI 自动生成符合团队红线的代码和文档。

标准开发工作流：

1. 全局约束：在开启新的 AI 对话时，始终优先引入 @01 - Knowledge & Prompts/AI Prompts/P0_全局开发与架构决策指令.md，让 AI 具备架构决策意识和 Git 提交习惯。
2. 按需调用指令：根据你当前所处的开发阶段，将对应的 P1 到 P8 指令文件作为 System Prompt 发送给 AI。
   • 例如：需要写新业务代码时，输入：“请根据 @P4_生成核心业务代码.md 的要求，帮我实现用户登录模块。”
   • 例如：需要重构老代码时，输入：“请根据 @P8_执行遗留代码重构.md 的要求，帮我把这段代码重构一下。”
3. 动态绑定规范：AI 会根据指令中的 @ 语法，自动去读取 02 到 05 目录下的具体规范（如 API 规范、Python 规范），确保生成的代码 100% 符合团队红线。
4. 架构决策 (ADR)：当 AI 发现技术分歧并向你提问时，做出选择，AI 会自动在 01 - Knowledge & Prompts/Architecture Decision Records/ 下生成 ADR 文档。

1.1 🤖 仅使用 .github 的 Copilot 自定义配置（推荐）

如果你希望不再手动“添加上下文”，而是让 Copilot 自动加载团队规则，请统一使用仓库根目录下的 .github/ 自定义资产。

目录约定：

.github/
   copilot-instructions.md
   instructions/
      *.instructions.md
   prompts/
      *.prompt.md

三类文件职责：

1. copilot-instructions.md：全局常驻规则（例如中文输出、决策点询问、ADR 先行、提交规范）。
2. instructions/*.instructions.md：按文件匹配自动注入的规范（通过 applyTo 控制作用范围）。
3. prompts/*.prompt.md：按阶段显式调用的任务模板（如蓝图、设计、编码、测试、审查、部署、重构）。

Prompt Frontmatter 关键要求：

1. 使用 agent: 字段，不再使用已弃用的 mode: 字段。
2. 必须提供 description:，并写入清晰关键词，便于 Copilot 发现与匹配。

示例：

---
agent: agent
description: "用于生成核心业务代码；关键词：Fat Service、OpenAPI、统一响应"
---

落地步骤：

1. 在 .github/copilot-instructions.md 写入 P0 全局纪律。
2. 在 .github/prompts/ 放置 P1-P8 阶段模板。
3. 在 .github/instructions/ 放置规范文件，并配置精确 applyTo（避免使用过宽模式导致上下文噪音）。
4. 在 Copilot Chat 中直接调用对应 Prompt，日常无需再手动追加全局上下文。

排错清单（无效时优先检查）：

1. frontmatter 是否使用 --- 成对包裹。
2. Prompt 是否使用了 agent: 而不是 mode:。
3. description 是否包含可检索关键词。
4. applyTo 是否匹配了当前编辑文件路径。
5. 文件是否位于仓库根目录 .github/ 下（而非其他目录）。

2. 🏢 新员工入职与人工查阅

1. 快速上手：请优先阅读 03 - Coding & Frameworks 目录下的相关语言与框架规范，确保首个提交符合团队红线。
2. 架构设计与选型：在引入新技术或进行微服务拆分前，请先查阅 02 - Design Standard/2.4 项目文档与架构决策规范.md，并编写 ADR 文档。
3. 参考资料边界：ref/ 目录仅供历史对照，不参与规范门禁与日常执行。

---

维护说明：本文档及子目录规范由系统架构组与核心开发团队共同维护。若有规范调整建议，请提交 PR 或在技术会议上发起讨论。