2026-03-24 16:13:32 +08:00
|
|
|
|
# **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 的全自动化流水线与卡点策略。
|
|
|
|
|
|
|
2026-04-01 11:16:19 +08:00
|
|
|
|
### **📂 ref (历史参考资料，仅供借鉴)**
|
|
|
|
|
|
|
|
|
|
|
|
`ref/` 目录用于存放历史规范、外部参考文档或迁移期材料，**仅用于对照和借鉴**。
|
|
|
|
|
|
|
|
|
|
|
|
* ❌ **不作为当前项目执行标准**：开发、评审与交付不以 `ref/` 下文档作为判定依据。
|
|
|
|
|
|
* ✅ **以正式规范为准**：实际执行统一遵循 `01` 到 `05` 目录中的正式规范文档。
|
|
|
|
|
|
|
2026-03-24 16:13:32 +08:00
|
|
|
|
## **📖 如何使用本指南？**
|
|
|
|
|
|
|
2026-03-30 12:04:26 +08:00
|
|
|
|
### **1. 👨💻 开发者日常使用 (AI Native 驱动)**
|
|
|
|
|
|
|
|
|
|
|
|
本规范库不仅是给人看的，更是**给 AI 助手（如 Cursor, GitHub Copilot）看的**。我们通过 `01 - Knowledge & Prompts/AI Prompts/` 目录下的指令文件来驱动 AI 自动生成符合团队红线的代码和文档。
|
|
|
|
|
|
|
|
|
|
|
|
**标准开发工作流：**
|
|
|
|
|
|
1. **全局约束**：在开启新的 AI 对话时，始终优先引入 `@01 - Knowledge & Prompts/AI Prompts/P0_全局开发与架构决策指令.md`，让 AI 具备架构决策意识和 Git 提交习惯。
|
2026-03-30 12:12:16 +08:00
|
|
|
|
2. **按需调用指令**：根据你当前所处的开发阶段，将对应的 `P1` 到 `P8` 指令文件作为 System Prompt 发送给 AI。
|
|
|
|
|
|
* *例如：需要写新业务代码时，输入：“请根据 `@P4_生成核心业务代码.md` 的要求，帮我实现用户登录模块。”*
|
|
|
|
|
|
* *例如：需要重构老代码时，输入：“请根据 `@P8_执行遗留代码重构.md` 的要求，帮我把这段代码重构一下。”*
|
2026-03-30 12:04:26 +08:00
|
|
|
|
3. **动态绑定规范**：AI 会根据指令中的 `@` 语法，自动去读取 `02` 到 `05` 目录下的具体规范（如 API 规范、Python 规范），确保生成的代码 100% 符合团队红线。
|
|
|
|
|
|
4. **架构决策 (ADR)**：当 AI 发现技术分歧并向你提问时，做出选择，AI 会自动在 `01 - Knowledge & Prompts/Architecture Decision Records/` 下生成 ADR 文档。
|
|
|
|
|
|
|
|
|
|
|
|
### **2. 🏢 新员工入职与人工查阅**
|
|
|
|
|
|
|
|
|
|
|
|
1. **快速上手**：请优先阅读 `03 - Coding & Frameworks` 目录下的相关语言与框架规范，确保首个提交符合团队红线。
|
|
|
|
|
|
2. **架构设计与选型**：在引入新技术或进行微服务拆分前，请先查阅 `02 - Design Standard/2.4 项目文档与架构决策规范.md`，并编写 ADR 文档。
|
2026-04-01 11:16:19 +08:00
|
|
|
|
3. **参考资料边界**：`ref/` 目录仅供历史对照，不参与规范门禁与日常执行。
|
2026-03-30 12:04:26 +08:00
|
|
|
|
|
|
|
|
|
|
---
|
2026-03-24 16:13:32 +08:00
|
|
|
|
|
|
|
|
|
|
**维护说明**：本文档及子目录规范由系统架构组与核心开发团队共同维护。若有规范调整建议，请提交 PR 或在技术会议上发起讨论。
|
