# 04-开发规范

> **目标：** 统一团队开发规范，提高代码质量和协作效率  
> **适用范围：** 平台层 + 能力层 + 业务模块层  
> **强制等级：** ⭐⭐⭐⭐⭐ 必须遵守

---

## 📋 规范文档列表

### 1. 数据库设计规范 ⭐⭐⭐⭐⭐
**文件：** `01-数据库设计规范.md` ⏳ 待创建（从 `01-设计文档/数据库设计文档.md` 提取）

**核心内容：**
- Schema隔离策略（platform_schema、asl_schema等）
- 表命名规范（小写+下划线）
- 字段命名规范
- 索引设计规范
- 外键约束规范
- 通用字段（created_at、updated_at等）

**快速参考：** [数据库全局视图](./03-数据库全局视图.md) ⭐ 已创建

---

### 2. API设计规范 ⭐⭐⭐⭐⭐
**文件：** `02-API设计规范.md` ⏳ 待创建（从 `01-设计文档/API设计规范.md` 提取）

**核心内容：**
- RESTful API设计原则
- URL命名规范（`/api/v1/模块/资源`）
- HTTP方法使用规范
- 请求/响应格式规范
- 错误码设计
- 认证和权限

**快速参考：** [API路由总览](./04-API路由总览.md) ⭐ 已创建

---

### 3. 数据库全局视图 ⭐⭐⭐⭐⭐ ✅ 新增
**文件：** `03-数据库全局视图.md`

**用途：** 提供所有Schema和表的快速索引

**核心内容：**
- Schema划分策略（8个Schema）
- 所有表的总览和跳转链接
- 跨Schema依赖关系
- 数据量预估

**使用场景：**
- 查看全局数据架构
- 快速定位某个表属于哪个Schema
- 了解跨模块数据关系

---

### 4. API路由总览 ⭐⭐⭐⭐⭐ ✅ 新增
**文件：** `04-API路由总览.md`

**用途：** 提供所有API端点的快速索引

**核心内容：**
- 路由命名规范
- 所有模块的API端点总览
- 路由冲突检查
- 端点统计（~85个）

**使用场景：**
- 查看全局API架构
- 避免路由冲突
- 快速查找某个功能的API端点

---

### 5. 代码规范 ⭐⭐⭐⭐
**文件：** `05-代码规范.md` → 重命名自 `代码规范.md`（已存在，818行）

**核心内容：**
- TypeScript编码规范
- React组件规范
- 文件和目录命名
- 代码注释规范
- 错误处理规范
- 日志记录规范

**已有内容，包含：**
- ESLint配置
- Prettier配置
- 详细的编码规范

---

### 6. Git提交规范 ⭐⭐⭐⭐⭐ ✅ 已完成
**文件：** `06-Git提交规范.md`

**核心内容：**
- 远程仓库配置（Gitee）
- Commit Message格式规范
- 分支管理策略
- 中文编码问题解决方案 ⭐ 重要
- Git历史重写与维护
- PR/MR规范和代码审查流程
- 常见问题与最佳实践

**包含实用工具：**
- `fix-git-commit-messages.ps1` 脚本使用说明
- Git 别名配置
- 中文乱码修复完整流程

**快速参考：**
```
<type>(<scope>): <subject>

feat: 新功能  fix: Bug修复  docs: 文档
style: 格式   refactor: 重构  perf: 优化
test: 测试    chore: 构建    ci: CI/CD
```

---

### 7. 测试规范 ⭐⭐⭐
**文件：** `07-测试规范.md` ⏳ 待创建

**核心内容：**
- 单元测试规范
- 集成测试规范
- E2E测试规范
- 测试覆盖率要求

**测试覆盖率要求：**
- 核心业务逻辑：≥80%
- 工具函数：≥90%
- API Controller：≥70%

---

### 12. 安全开发规范 ⭐⭐⭐⭐⭐ ✅ 新增
**文件：** `12-安全开发规范.md`

**核心内容：**
- API 访问控制（防 IDOR 水平越权）
- 数据库查询安全（防 SQL 注入）
- LLM 调用 PII 脱敏规范
- 认证与授权规范
- 敏感信息管理（防泄露）
- 前端安全规范
- 日志与错误处理安全
- 部署与网络安全
- Code Review 安全检查清单

**使用场景：**
- 新增 API 接口时，检查访问控制是否正确
- Code Review 时，对照安全检查清单逐项检查
- 处理用户数据时，确认脱敏和加密要求

---

## 🎯 规范优先级

### P0 - 必须遵守
- ✅ 数据库设计规范
- ✅ API设计规范
- ✅ Git提交规范（Commit Message）
- ✅ **安全开发规范** ⭐ 新增

### P1 - 强烈建议
- ✅ 代码规范（TypeScript/React）
- ✅ 错误处理规范
- ✅ 日志记录规范

### P2 - 建议遵守
- ⚪ 测试规范
- ⚪ 文档注释规范
- ⚪ 性能优化规范

---

## 🔍 快速查找

**我要设计数据库表：** → `01-数据库设计规范.md`  
**我要设计API接口：** → `02-API设计规范.md`  
**我要查看全局数据架构：** → `03-数据库全局视图.md` ✅  
**我要查看全局API路由：** → `04-API路由总览.md` ✅  
**我要编写代码：** → `05-代码规范.md` ✅  
**我要提交代码：** → `06-Git提交规范.md` ✅  
**我要解决中文乱码：** → `06-Git提交规范.md` (第4节) ✅  
**我要配置远程仓库：** → `06-Git提交规范.md` (第1节) ✅  
**我要编写测试：** → `07-测试规范.md`  
**我要确保代码安全：** → `12-安全开发规范.md` ✅  
**我要做 Code Review：** → `12-安全开发规范.md` (第9节 检查清单) ✅

---

## ⚠️ 违反规范的后果

### 数据库设计不规范
- ❌ Schema混乱，模块耦合
- ❌ 无法实现模块独立部署
- ❌ 数据迁移困难

### API设计不规范
- ❌ 前后端对接困难
- ❌ API文档混乱
- ❌ 版本升级困难

### 代码不规范
- ❌ 代码可读性差
- ❌ 维护成本高
- ❌ Bug率上升

---

## 📝 规范更新流程

1. 提出规范变更需求（Issue或PR）
2. 团队讨论和评审
3. 更新规范文档
4. 通知全员
5. 逐步迁移旧代码

---

## 🔗 相关工具

**代码检查：**
- ESLint（JavaScript/TypeScript）
- Prettier（代码格式化）
- Stylelint（CSS）

**提交检查：**
- Husky（Git Hooks）
- Commitlint（Commit Message检查）

**数据库：**
- Prisma（ORM + Migration）
- pgAdmin（数据库管理）

---

**最后更新：** 2025-11-06  
**维护人：** 技术架构师