AIclinicalresearch/docs/_templates/数据库设计-模板.md

# [模块名称] - 数据库设计

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