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

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

Schema： xxx_schema
表数量： X个
依赖： platform_schema.users（如有）
最后更新： YYYY-MM-DD

---

📋 Schema说明

Schema创建：

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（表描述）

用途： 简要说明表的用途

字段说明：

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（第二个表）

（重复上面的结构）

---

🔍 索引设计

单列索引

-- 用户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);

复合索引

-- 用户+状态组合查询
CREATE INDEX idx_xxx_user_status ON xxx_schema.xxx_table_name(user_id, status);

---

🔗 外键约束

依赖关系

-- 依赖用户表
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，不能引用其他业务模块

---

📈 数据迁移（可选）

初始化数据

-- 如果需要初始化数据
INSERT INTO xxx_schema.xxx_table_name (field_name, status) VALUES
  ('示例1', 'active'),
  ('示例2', 'active');

迁移脚本

-- 如果需要从旧表迁移数据
-- migrations/xxx_migration.sql

---

📊 数据量预估

表名	预估记录数	增长速度
xxx_table_name	10万/年	中等
xxx_table_name_2	100万/年	高

---

⚠️ 注意事项

性能优化：

• 大表必须添加分页查询
• 热点字段必须添加索引
• 定期清理软删除的数据

安全性：

• 敏感字段需要加密存储
• 所有外键必须有 ON DELETE 策略
• 避免N+1查询问题

维护性：

• 表结构变更需要写迁移脚本
• 重要变更需要备份数据

---

🔗 相关文档

规范：

• 数据库设计规范
• 数据库全局视图

API设计：

• 本模块API设计

---

最后更新： YYYY-MM-DD
维护人： 技术架构师