4.5 KiB
4.5 KiB
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 的全自动化流水线与卡点策略。
📖 如何使用本指南？
1. 👨💻 开发者日常使用 (AI Native 驱动)
本规范库不仅是给人看的，更是给 AI 助手（如 Cursor, GitHub Copilot）看的。我们通过 01 - Knowledge & Prompts/AI Prompts/ 目录下的指令文件来驱动 AI 自动生成符合团队红线的代码和文档。
标准开发工作流：
- 全局约束：在开启新的 AI 对话时，始终优先引入
@01 - Knowledge & Prompts/AI Prompts/P0_全局开发与架构决策指令.md，让 AI 具备架构决策意识和 Git 提交习惯。 - 按需调用指令：根据你当前所处的开发阶段，将对应的
P1到P7指令文件作为 System Prompt 发送给 AI。- 例如：需要写业务代码时，输入：“请根据
@P4_生成核心业务代码.md的要求，帮我实现用户登录模块。”
- 例如：需要写业务代码时，输入：“请根据
- 动态绑定规范：AI 会根据指令中的
@语法，自动去读取02到05目录下的具体规范（如 API 规范、Python 规范），确保生成的代码 100% 符合团队红线。 - 架构决策 (ADR)：当 AI 发现技术分歧并向你提问时，做出选择，AI 会自动在
01 - Knowledge & Prompts/Architecture Decision Records/下生成 ADR 文档。
2. 🏢 新员工入职与人工查阅
- 快速上手：请优先阅读
03 - Coding & Frameworks目录下的相关语言与框架规范，确保首个提交符合团队红线。 - 架构设计与选型：在引入新技术或进行微服务拆分前，请先查阅
02 - Design Standard/2.4 项目文档与架构决策规范.md，并编写 ADR 文档。
维护说明：本文档及子目录规范由系统架构组与核心开发团队共同维护。若有规范调整建议，请提交 PR 或在技术会议上发起讨论。