docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
475
docs/_templates/API设计-模板.md
vendored
Normal file
475
docs/_templates/API设计-模板.md
vendored
Normal file
@@ -0,0 +1,475 @@
|
||||
# [模块名称] - API设计
|
||||
|
||||
> **基础路径：** `/api/v1/模块名`
|
||||
> **端点数量：** X个
|
||||
> **认证要求：** JWT Token
|
||||
> **最后更新：** YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## 📋 API概览
|
||||
|
||||
| 端点 | 方法 | 说明 | 认证 |
|
||||
|------|------|------|------|
|
||||
| `/api/v1/xxx/resources` | GET | 获取资源列表 | ✅ |
|
||||
| `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ✅ |
|
||||
| `/api/v1/xxx/resources` | POST | 创建资源 | ✅ |
|
||||
| `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ✅ |
|
||||
| `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 📚 API详细设计
|
||||
|
||||
### 1. 获取资源列表
|
||||
|
||||
**端点：** `GET /api/v1/xxx/resources`
|
||||
|
||||
**用途：** 获取当前用户的资源列表（分页）
|
||||
|
||||
**请求参数：**
|
||||
|
||||
**Query参数：**
|
||||
```typescript
|
||||
{
|
||||
page?: number; // 页码，默认1
|
||||
pageSize?: number; // 每页数量，默认10，最大100
|
||||
status?: string; // 筛选：状态（active/inactive）
|
||||
keyword?: string; // 搜索关键词
|
||||
sortBy?: string; // 排序字段（createdAt/updatedAt）
|
||||
sortOrder?: 'asc' | 'desc'; // 排序方向，默认desc
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例：**
|
||||
```bash
|
||||
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**成功响应：** `200 OK`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"userId": 123,
|
||||
"fieldName": "示例",
|
||||
"description": "描述",
|
||||
"status": "active",
|
||||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||||
"updatedAt": "2025-11-06T10:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 10,
|
||||
"total": 100,
|
||||
"totalPages": 10
|
||||
}
|
||||
},
|
||||
"message": "获取成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
// 401 Unauthorized
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "未授权，请先登录"
|
||||
}
|
||||
}
|
||||
|
||||
// 400 Bad Request
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "INVALID_PARAMS",
|
||||
"message": "参数错误",
|
||||
"details": [
|
||||
{ "field": "pageSize", "message": "最大不能超过100" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取资源详情
|
||||
|
||||
**端点：** `GET /api/v1/xxx/resources/:id`
|
||||
|
||||
**用途：** 获取指定资源的详细信息
|
||||
|
||||
**路径参数：**
|
||||
- `id` (必填): 资源ID
|
||||
|
||||
**请求示例：**
|
||||
```bash
|
||||
GET /api/v1/xxx/resources/123
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**成功响应：** `200 OK`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 123,
|
||||
"userId": 456,
|
||||
"fieldName": "示例",
|
||||
"description": "详细描述",
|
||||
"status": "active",
|
||||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||||
"updatedAt": "2025-11-06T10:00:00.000Z",
|
||||
// 额外的关联数据
|
||||
"user": {
|
||||
"id": 456,
|
||||
"name": "用户名"
|
||||
}
|
||||
},
|
||||
"message": "获取成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
// 404 Not Found
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "资源不存在"
|
||||
}
|
||||
}
|
||||
|
||||
// 403 Forbidden
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "无权访问此资源"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 创建资源
|
||||
|
||||
**端点：** `POST /api/v1/xxx/resources`
|
||||
|
||||
**用途：** 创建新资源
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"fieldName": "资源名称", // 必填，长度2-200
|
||||
"description": "描述", // 可选，最大5000字
|
||||
"status": "active" // 可选，默认active
|
||||
}
|
||||
```
|
||||
|
||||
**验证规则：**
|
||||
- `fieldName`: 必填，2-200字符，不能包含特殊字符
|
||||
- `description`: 可选，最大5000字符
|
||||
- `status`: 可选，有效值：active, inactive
|
||||
|
||||
**请求示例：**
|
||||
```bash
|
||||
POST /api/v1/xxx/resources
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"fieldName": "新资源",
|
||||
"description": "这是一个新资源"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应：** `201 Created`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 124,
|
||||
"userId": 456,
|
||||
"fieldName": "新资源",
|
||||
"description": "这是一个新资源",
|
||||
"status": "active",
|
||||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||||
"updatedAt": "2025-11-06T10:00:00.000Z"
|
||||
},
|
||||
"message": "创建成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
// 422 Unprocessable Entity
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "参数验证失败",
|
||||
"details": [
|
||||
{ "field": "fieldName", "message": "字段名称不能为空" },
|
||||
{ "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
// 409 Conflict
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "ALREADY_EXISTS",
|
||||
"message": "该资源已存在"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新资源
|
||||
|
||||
**端点：** `PUT /api/v1/xxx/resources/:id`
|
||||
|
||||
**用途：** 更新指定资源（完整更新）
|
||||
|
||||
**路径参数：**
|
||||
- `id` (必填): 资源ID
|
||||
|
||||
**请求体：**
|
||||
```json
|
||||
{
|
||||
"fieldName": "更新后的名称",
|
||||
"description": "更新后的描述",
|
||||
"status": "inactive"
|
||||
}
|
||||
```
|
||||
|
||||
**请求示例：**
|
||||
```bash
|
||||
PUT /api/v1/xxx/resources/123
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"fieldName": "更新后的名称",
|
||||
"description": "更新后的描述"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应：** `200 OK`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 123,
|
||||
"fieldName": "更新后的名称",
|
||||
"description": "更新后的描述",
|
||||
"updatedAt": "2025-11-06T11:00:00.000Z"
|
||||
},
|
||||
"message": "更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
// 404 Not Found
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "资源不存在"
|
||||
}
|
||||
}
|
||||
|
||||
// 403 Forbidden
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "无权修改此资源"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除资源
|
||||
|
||||
**端点：** `DELETE /api/v1/xxx/resources/:id`
|
||||
|
||||
**用途：** 删除指定资源（软删除）
|
||||
|
||||
**路径参数：**
|
||||
- `id` (必填): 资源ID
|
||||
|
||||
**请求示例：**
|
||||
```bash
|
||||
DELETE /api/v1/xxx/resources/123
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**成功响应：** `200 OK`
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": null,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应：**
|
||||
```json
|
||||
// 404 Not Found
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "NOT_FOUND",
|
||||
"message": "资源不存在"
|
||||
}
|
||||
}
|
||||
|
||||
// 403 Forbidden
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "无权删除此资源"
|
||||
}
|
||||
}
|
||||
|
||||
// 409 Conflict
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "CANNOT_DELETE",
|
||||
"message": "该资源有关联数据，无法删除"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 认证与权限
|
||||
|
||||
### 认证方式
|
||||
所有API都需要JWT Token认证：
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 权限检查
|
||||
- 用户只能访问自己的资源
|
||||
- ADMIN角色可以访问所有资源
|
||||
|
||||
---
|
||||
|
||||
## 📊 错误码汇总
|
||||
|
||||
| 错误码 | HTTP状态 | 说明 |
|
||||
|--------|---------|------|
|
||||
| UNAUTHORIZED | 401 | 未授权 |
|
||||
| FORBIDDEN | 403 | 无权限 |
|
||||
| NOT_FOUND | 404 | 资源不存在 |
|
||||
| VALIDATION_ERROR | 422 | 参数验证失败 |
|
||||
| ALREADY_EXISTS | 409 | 资源已存在 |
|
||||
| INTERNAL_ERROR | 500 | 服务器错误 |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 使用示例
|
||||
|
||||
### JavaScript/TypeScript
|
||||
```typescript
|
||||
// 获取资源列表
|
||||
const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
},
|
||||
});
|
||||
const data = await response.json();
|
||||
|
||||
// 创建资源
|
||||
const response = await fetch('/api/v1/xxx/resources', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
fieldName: '新资源',
|
||||
description: '描述',
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
### cURL
|
||||
```bash
|
||||
# 获取列表
|
||||
curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
|
||||
# 创建资源
|
||||
curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"fieldName":"新资源","description":"描述"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
**性能优化：**
|
||||
- 列表接口必须支持分页，默认pageSize=10，最大100
|
||||
- 避免返回过多关联数据，按需加载
|
||||
- 大量数据导出使用异步任务
|
||||
|
||||
**安全性：**
|
||||
- 所有接口必须验证JWT Token
|
||||
- 必须检查资源归属（用户只能操作自己的资源）
|
||||
- 敏感字段不要返回（如密码）
|
||||
|
||||
**向后兼容：**
|
||||
- API变更使用版本号（/api/v2）
|
||||
- 不要删除已有字段，只能标记为deprecated
|
||||
- 新增字段必须有默认值
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
**规范：**
|
||||
- [API设计规范](../../04-开发规范/02-API设计规范.md)
|
||||
- [API路由总览](../../04-开发规范/04-API路由总览.md)
|
||||
|
||||
**数据库：**
|
||||
- [本模块数据库设计](./01-数据库设计.md)
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** YYYY-MM-DD
|
||||
**维护人：** 技术架构师
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
79
docs/_templates/README.md
vendored
Normal file
79
docs/_templates/README.md
vendored
Normal file
@@ -0,0 +1,79 @@
|
||||
# 文档模板
|
||||
|
||||
> **目录说明：** 本目录包含各类文档的标准模板
|
||||
> **使用方法：** 创建新文档时，复制对应模板，填充内容
|
||||
|
||||
---
|
||||
|
||||
## 📋 模板清单
|
||||
|
||||
| 模板 | 说明 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| **[AI对接] 快速上下文-模板.md** | 快速上下文文档模板 | 创建新模块/能力时 |
|
||||
| **模块README-模板.md** | 模块README模板 | 创建新业务模块时 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用说明
|
||||
|
||||
### 1. 创建新业务模块
|
||||
|
||||
**步骤：**
|
||||
1. 复制 `模块README-模板.md` 到新模块目录
|
||||
2. 重命名为 `README.md`
|
||||
3. 填充所有 `[占位符]` 内容
|
||||
4. 删除不需要的章节
|
||||
|
||||
### 2. 创建快速上下文文档
|
||||
|
||||
**步骤：**
|
||||
1. 复制 `[AI对接] 快速上下文-模板.md` 到对应目录
|
||||
2. 重命名为 `[AI对接] [模块代号]快速上下文.md`
|
||||
3. 填充所有内容
|
||||
4. 确保Token消耗在目标范围内
|
||||
|
||||
---
|
||||
|
||||
## 📏 模板规范
|
||||
|
||||
### 快速上下文文档规范
|
||||
|
||||
**L0级别（总体）：**
|
||||
- Token消耗：~800
|
||||
- 阅读时间：2分钟
|
||||
- 内容：项目全貌、快速跳转
|
||||
|
||||
**L1级别（层级）：**
|
||||
- Token消耗：~1500
|
||||
- 阅读时间：3分钟
|
||||
- 内容：层级概览、模块清单
|
||||
|
||||
**L2级别（模块）：**
|
||||
- Token消耗：~2000
|
||||
- 阅读时间：5分钟
|
||||
- 内容：模块详情、开发指南
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [文档体系重构方案](../00-系统总体设计/02-文档体系重构方案.md)
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** 2025-11-06
|
||||
**维护人：** 技术架构师
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
180
docs/_templates/[AI对接] 快速上下文-模板.md
vendored
Normal file
180
docs/_templates/[AI对接] 快速上下文-模板.md
vendored
Normal file
@@ -0,0 +1,180 @@
|
||||
# [AI对接] [模块名]快速上下文
|
||||
|
||||
> **阅读时间：** [2-5]分钟
|
||||
> **Token消耗：** ~[800-2000] tokens
|
||||
> **前置阅读：** `00-系统总体设计/[AI对接] 快速上下文.md`（如果是L2级别）
|
||||
|
||||
---
|
||||
|
||||
## 📋 模块定位
|
||||
|
||||
[一句话描述模块核心功能和价值]
|
||||
|
||||
**商业价值：** ⭐⭐⭐⭐⭐ [评级]
|
||||
**开发状态：** [✅已完成 / ⏳开发中 / ⏳规划中]
|
||||
**依赖能力：** [列出依赖的通用能力]
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心功能
|
||||
|
||||
[列出3-6个核心功能，用1-2句话描述每个功能]
|
||||
|
||||
1. ✅ **功能1** - 简要描述
|
||||
2. ✅ **功能2** - 简要描述
|
||||
3. ⏳ **功能3** - 简要描述
|
||||
|
||||
**本周重点：** [当前开发重点]
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 技术架构一览
|
||||
|
||||
### 前端（React）
|
||||
```
|
||||
src/pages/[ModuleName]/
|
||||
├── [SubModule1]/
|
||||
├── [SubModule2]/
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 后端（Node.js）
|
||||
```
|
||||
backend/src/modules/[module_code]/
|
||||
├── controllers/
|
||||
├── services/
|
||||
└── routes/
|
||||
```
|
||||
|
||||
### 数据库（[module]_schema）
|
||||
```sql
|
||||
CREATE SCHEMA [module]_schema;
|
||||
- [table1] # 表1说明
|
||||
- [table2] # 表2说明
|
||||
- ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 核心业务流程
|
||||
|
||||
[用简洁的流程图或步骤描述最核心的业务流程]
|
||||
|
||||
```
|
||||
1. 用户操作
|
||||
↓
|
||||
2. 前端处理
|
||||
↓
|
||||
3. 后端处理
|
||||
↓
|
||||
4. 数据存储
|
||||
↓
|
||||
5. 返回结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 已有设计文档
|
||||
|
||||
### PRD文档
|
||||
- `00-项目概述/01-产品需求文档(PRD).md` - [简要说明]
|
||||
|
||||
### 技术设计
|
||||
- `01-设计文档/02-数据库设计.md` - [简要说明]
|
||||
- `01-设计文档/03-API设计.md` - [简要说明]
|
||||
|
||||
### UI原型
|
||||
- `01-设计文档/07-UI设计/[原型文件].html`
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖的通用能力
|
||||
|
||||
### [能力1]（[状态]）
|
||||
```typescript
|
||||
// 接口示例或关键说明
|
||||
```
|
||||
|
||||
### [能力2]（[状态]）
|
||||
```typescript
|
||||
// 接口示例或关键说明
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 API端点清单
|
||||
|
||||
### [功能模块1]
|
||||
```
|
||||
POST /api/v1/[module]/[resource]
|
||||
GET /api/v1/[module]/[resource]
|
||||
...
|
||||
```
|
||||
|
||||
### [功能模块2]
|
||||
```
|
||||
POST /api/v1/[module]/[resource2]
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📅 开发计划
|
||||
|
||||
### Week 1
|
||||
- Day 1-2：[任务]
|
||||
- Day 3-4：[任务]
|
||||
- Day 5：[任务]
|
||||
|
||||
### Week 2
|
||||
- Day 1-2：[任务]
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 关键技术难点
|
||||
|
||||
1. **难点1** - [说明和解决方案]
|
||||
2. **难点2** - [说明和解决方案]
|
||||
|
||||
---
|
||||
|
||||
## ✅ 快速开发检查清单
|
||||
|
||||
**开始开发前确认：**
|
||||
- [ ] [依赖能力1]是否已实现？
|
||||
- [ ] 数据库Schema是否已创建？
|
||||
- [ ] Prisma Schema是否已更新？
|
||||
- [ ] API路由是否已注册？
|
||||
|
||||
**常见问题：**
|
||||
- Q: [问题]？
|
||||
- A: [答案]
|
||||
|
||||
---
|
||||
|
||||
## 📖 更多详细信息
|
||||
|
||||
**需要完整PRD：** → `00-项目概述/01-产品需求文档(PRD).md`
|
||||
**需要数据库详情：** → `01-设计文档/02-数据库设计.md`
|
||||
**需要API详情：** → `01-设计文档/03-API设计.md`
|
||||
**需要UI设计：** → `01-设计文档/07-UI设计/`
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** [日期]
|
||||
**维护人：** [维护人]
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
220
docs/_templates/数据库设计-模板.md
vendored
Normal file
220
docs/_templates/数据库设计-模板.md
vendored
Normal file
@@ -0,0 +1,220 @@
|
||||
# [模块名称] - 数据库设计
|
||||
|
||||
> **Schema：** `xxx_schema`
|
||||
> **表数量：** X个
|
||||
> **依赖：** platform_schema.users（如有）
|
||||
> **最后更新：** YYYY-MM-DD
|
||||
|
||||
---
|
||||
|
||||
## 📋 Schema说明
|
||||
|
||||
**Schema创建：**
|
||||
```sql
|
||||
CREATE SCHEMA IF NOT EXISTS xxx_schema;
|
||||
```
|
||||
|
||||
**职责范围：**
|
||||
- 功能1相关数据
|
||||
- 功能2相关数据
|
||||
- ...
|
||||
|
||||
**依赖关系：**
|
||||
- 依赖 `platform_schema.users`（用户信息）
|
||||
- 依赖 `platform_schema.xxx`（如有）
|
||||
|
||||
---
|
||||
|
||||
## 📊 ER图（可选）
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ users (外部) │
|
||||
└────────┬────────┘
|
||||
│ 1:N
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 主表 │
|
||||
└────────┬────────┘
|
||||
│ 1:N
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ 子表 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 表结构设计
|
||||
|
||||
### 1. xxx_table_name（表描述）
|
||||
|
||||
**用途：** 简要说明表的用途
|
||||
|
||||
**字段说明：**
|
||||
|
||||
```sql
|
||||
CREATE TABLE xxx_schema.xxx_table_name (
|
||||
-- 主键
|
||||
id SERIAL PRIMARY KEY,
|
||||
|
||||
-- 外键
|
||||
user_id INTEGER REFERENCES platform_schema.users(id) ON DELETE CASCADE,
|
||||
|
||||
-- 业务字段
|
||||
field_name VARCHAR(200) NOT NULL,
|
||||
description TEXT,
|
||||
status VARCHAR(20) DEFAULT 'active',
|
||||
|
||||
-- 时间戳（必须）
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW(),
|
||||
|
||||
-- 索引
|
||||
INDEX idx_xxx_user_id (user_id),
|
||||
INDEX idx_xxx_status (status)
|
||||
);
|
||||
```
|
||||
|
||||
**字段详解：**
|
||||
|
||||
| 字段名 | 类型 | 约束 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | SERIAL | PK | 主键 |
|
||||
| user_id | INTEGER | FK, NOT NULL | 用户ID |
|
||||
| field_name | VARCHAR(200) | NOT NULL | 字段说明 |
|
||||
| description | TEXT | - | 详细描述 |
|
||||
| status | VARCHAR(20) | DEFAULT 'active' | 状态：active/inactive/deleted |
|
||||
| created_at | TIMESTAMP | NOT NULL | 创建时间 |
|
||||
| updated_at | TIMESTAMP | NOT NULL | 更新时间 |
|
||||
|
||||
**业务规则：**
|
||||
- 每个用户最多创建X个记录
|
||||
- status字段的有效值：active, inactive, deleted
|
||||
- 软删除：不物理删除，只修改status为deleted
|
||||
|
||||
---
|
||||
|
||||
### 2. xxx_table_name_2（第二个表）
|
||||
|
||||
（重复上面的结构）
|
||||
|
||||
---
|
||||
|
||||
## 🔍 索引设计
|
||||
|
||||
### 单列索引
|
||||
```sql
|
||||
-- 用户ID索引（外键必须加索引）
|
||||
CREATE INDEX idx_xxx_user_id ON xxx_schema.xxx_table_name(user_id);
|
||||
|
||||
-- 状态索引（常用筛选字段）
|
||||
CREATE INDEX idx_xxx_status ON xxx_schema.xxx_table_name(status);
|
||||
|
||||
-- 创建时间索引（常用排序字段）
|
||||
CREATE INDEX idx_xxx_created_at ON xxx_schema.xxx_table_name(created_at DESC);
|
||||
```
|
||||
|
||||
### 复合索引
|
||||
```sql
|
||||
-- 用户+状态组合查询
|
||||
CREATE INDEX idx_xxx_user_status ON xxx_schema.xxx_table_name(user_id, status);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 外键约束
|
||||
|
||||
### 依赖关系
|
||||
```sql
|
||||
-- 依赖用户表
|
||||
ALTER TABLE xxx_schema.xxx_table_name
|
||||
ADD CONSTRAINT fk_xxx_users
|
||||
FOREIGN KEY (user_id) REFERENCES platform_schema.users(id)
|
||||
ON DELETE CASCADE; -- 用户删除时级联删除
|
||||
|
||||
-- 模块内关联
|
||||
ALTER TABLE xxx_schema.child_table
|
||||
ADD CONSTRAINT fk_child_parent
|
||||
FOREIGN KEY (parent_id) REFERENCES xxx_schema.parent_table(id)
|
||||
ON DELETE CASCADE;
|
||||
```
|
||||
|
||||
### 外键策略
|
||||
- ✅ **ON DELETE CASCADE**：用户删除时，自动删除所有关联数据
|
||||
- ⚠️ **跨Schema外键**：只能引用 platform_schema，不能引用其他业务模块
|
||||
|
||||
---
|
||||
|
||||
## 📈 数据迁移（可选）
|
||||
|
||||
### 初始化数据
|
||||
```sql
|
||||
-- 如果需要初始化数据
|
||||
INSERT INTO xxx_schema.xxx_table_name (field_name, status) VALUES
|
||||
('示例1', 'active'),
|
||||
('示例2', 'active');
|
||||
```
|
||||
|
||||
### 迁移脚本
|
||||
```sql
|
||||
-- 如果需要从旧表迁移数据
|
||||
-- migrations/xxx_migration.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 数据量预估
|
||||
|
||||
| 表名 | 预估记录数 | 增长速度 |
|
||||
|------|-----------|---------|
|
||||
| xxx_table_name | 10万/年 | 中等 |
|
||||
| xxx_table_name_2 | 100万/年 | 高 |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
**性能优化：**
|
||||
- 大表必须添加分页查询
|
||||
- 热点字段必须添加索引
|
||||
- 定期清理软删除的数据
|
||||
|
||||
**安全性：**
|
||||
- 敏感字段需要加密存储
|
||||
- 所有外键必须有 ON DELETE 策略
|
||||
- 避免N+1查询问题
|
||||
|
||||
**维护性：**
|
||||
- 表结构变更需要写迁移脚本
|
||||
- 重要变更需要备份数据
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
**规范：**
|
||||
- [数据库设计规范](../../04-开发规范/01-数据库设计规范.md)
|
||||
- [数据库全局视图](../../04-开发规范/03-数据库全局视图.md)
|
||||
|
||||
**API设计：**
|
||||
- [本模块API设计](./02-API设计.md)
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** YYYY-MM-DD
|
||||
**维护人：** 技术架构师
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
87
docs/_templates/模块README-模板.md
vendored
Normal file
87
docs/_templates/模块README-模板.md
vendored
Normal file
@@ -0,0 +1,87 @@
|
||||
# [模块代号] - [模块名称]
|
||||
|
||||
> **模块代号：** [代号] ([英文全称])
|
||||
> **开发状态：** [✅已完成 / ⏳开发中 / ⏳规划中]
|
||||
> **商业价值：** ⭐⭐⭐⭐⭐ [评级]
|
||||
> **独立性：** ⭐⭐⭐⭐⭐ [评级]
|
||||
> **优先级：** [P0/P1/P2]
|
||||
|
||||
---
|
||||
|
||||
## 📋 模块概述
|
||||
|
||||
[2-3句话描述模块核心功能和价值]
|
||||
|
||||
**核心价值：** [核心差异化点]
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心功能
|
||||
|
||||
### [已完成功能 / 计划功能]
|
||||
1. [✅/⏳] **功能1** - 简要描述
|
||||
2. [✅/⏳] **功能2** - 简要描述
|
||||
3. [✅/⏳] **功能3** - 简要描述
|
||||
|
||||
**[本周/下一步]重点：** [当前重点]
|
||||
|
||||
---
|
||||
|
||||
## 📂 文档结构
|
||||
|
||||
```
|
||||
[模块代号]-[模块名称]/
|
||||
├── [AI对接] [代号]快速上下文.md # [状态]
|
||||
├── 00-项目概述/
|
||||
│ ├── 01-产品需求文档(PRD).md # [状态]
|
||||
│ └── README.md
|
||||
├── 01-设计文档/
|
||||
│ ├── 01-技术架构设计.md # [状态]
|
||||
│ ├── 02-数据库设计.md # [状态]
|
||||
│ ├── 03-API设计.md # [状态]
|
||||
│ └── README.md
|
||||
├── 02-业务规则/
|
||||
├── 03-开发计划/
|
||||
├── 04-测试文档/
|
||||
└── README.md # ✅ 当前文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖的通用能力
|
||||
|
||||
- **[能力1]** - [用途]
|
||||
- **[能力2]** - [用途]
|
||||
|
||||
---
|
||||
|
||||
## 🎯 商业模式
|
||||
|
||||
**目标客户：** [目标客户群]
|
||||
**售卖方式：** [独立产品 / 组合售卖 / 平台功能]
|
||||
**定价策略：** [定价方式]
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ [技术难点 / 核心特色]
|
||||
|
||||
[如果有特别的技术难点或核心特色，在这里说明]
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** [日期]
|
||||
**维护人：** 技术架构师
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user