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:
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions

View 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
**维护人:** 技术架构师