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. 新员工入职：请优先阅读 03 - Coding & Frameworks 目录下的相关语言与框架规范，确保首个提交符合团队红线。
2. 架构设计与选型：在引入新技术或进行微服务拆分前，请先查阅并编写 01 - Knowledge & Prompts 目录下的 ADR 文档。
3. 日常疑难杂症：善用 01 目录中沉淀的 AI Prompts 资产，加速代码生成与排障过程。

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