# **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 或在技术会议上发起讨论。