# 数据库管理

<cite>
**本文引用的文件**
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/init_db.py](file://backend/init_db.py)
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py)
- [backend/create_plan_tables.py](file://backend/create_plan_tables.py)
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向数据库管理员与后端开发，系统讲解本项目的数据库初始化、表结构创建、数据迁移与版本管理、备份与恢复策略、性能优化、监控与连接池配置、事务管理最佳实践以及安全与审计配置。项目采用 SQLAlchemy 异步 ORM 与 Alembic 迁移工具，结合 PostgreSQL 数据库，提供从开发到生产的完整数据库生命周期管理方案。

## 项目结构
数据库相关能力主要分布在以下模块：
- 配置与连接：应用配置与数据库连接池参数、异步引擎与会话工厂
- 模型定义：统一的 ORM 基类与完整的业务模型（科室、员工、指标、考核、工资、用户、计划、模板、菜单等）
- 初始化脚本：数据库表创建、基础数据与模板数据初始化
- 迁移工具：Alembic 版本化迁移、离线/在线迁移执行
- 辅助脚本：菜单表创建、计划表创建、指标模板初始化、字段迁移

```mermaid
graph TB
subgraph "配置与连接"
CFG["配置模块<br/>settings.DATABASE_URL 等"]
ENG["异步引擎与会话工厂"]
end
subgraph "模型层"
MODELS["ORM 模型定义<br/>Department/Staff/Indicator 等"]
end
subgraph "初始化与脚本"
INIT_DB["初始化脚本<br/>创建表与基础数据"]
INIT_TPL["模板初始化脚本"]
MIGRATE["字段迁移脚本"]
CREATE_MENU["菜单表创建脚本"]
CREATE_PLAN["计划表创建脚本"]
end
subgraph "迁移工具"
ALEMBIC_INI["Alembic 配置"]
ALEMBIC_ENV["Alembic 环境配置"]
V001["版本 001 初始表"]
V002["版本 002 模板与字段"]
end
CFG --> ENG
ENG --> MODELS
MODELS --> INIT_DB
MODELS --> INIT_TPL
MODELS --> MIGRATE
MODELS --> CREATE_MENU
MODELS --> CREATE_PLAN
ALEMBIC_INI --> ALEMBIC_ENV
ALEMBIC_ENV --> V001
ALEMBIC_ENV --> V002
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/alembic.ini](file://backend/alembic.ini#L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)

## 核心组件
- 数据库连接与会话
  - 异步引擎与会话工厂：通过配置模块提供的数据库 URL 创建异步引擎，并生成异步会话工厂；提供依赖注入式会话获取函数，自动提交、回滚与关闭
  - 连接池参数：在配置模块中定义连接池大小与溢出参数，确保高并发下的稳定性
- 模型与索引
  - 统一的 DeclarativeBase 基类，所有业务模型继承该基类
  - 多表建立复合索引与约束，覆盖常用查询条件与外键关系
- Alembic 迁移
  - 离线/在线迁移：支持离线模式与异步在线模式，适配不同部署场景
  - 版本化迁移：初始版本创建核心表，后续版本扩展模板与字段
- 初始化与脚本
  - 表创建与基础数据：批量创建表并插入示例数据
  - 模板与指标：按模板文档初始化指标与模板关联
  - 字段迁移：向现有表动态添加新字段，兼容历史版本

章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L65)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L11-L371)
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L9-L42)

## 架构总览
数据库层围绕“配置 → 引擎/会话 → 模型 → 迁移/脚本”的主干展开，形成清晰的职责边界与可演进的版本化管理。

```mermaid
graph TB
CFG["配置模块<br/>DATABASE_URL/DATABASE_POOL_SIZE 等"]
ENGINE["异步引擎"]
SESSION["异步会话工厂"]
BASE["ORM 基类 Base"]
MODELS["业务模型集合"]
ALEMBIC["Alembic 迁移"]
SCRIPTS["初始化与维护脚本"]
CFG --> ENGINE
ENGINE --> SESSION
SESSION --> MODELS
BASE --> MODELS
ALEMBIC --> MODELS
SCRIPTS --> MODELS
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
- [backend/init_db.py](file://backend/init_db.py#L11-L18)

## 详细组件分析

### 数据库初始化与表结构创建
- 初始化流程
  - 使用异步引擎在连接上下文中一次性创建所有表
  - 插入基础数据（科室、员工、指标、管理员），避免重复初始化
- 表结构要点
  - 主键自增、唯一约束、外键关系明确
  - 常用查询列建立索引，如科室类型、员工状态、考核周期、模板类型等
  - 约束保证数据完整性，如指标权重正数约束

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant INIT as "初始化脚本"
participant ENGINE as "异步引擎"
participant MODELS as "ORM 模型"
participant DB as "数据库"
CLI->>INIT : 调用初始化入口
INIT->>ENGINE : 获取连接
INIT->>MODELS : create_all()
MODELS->>DB : 创建表与索引
INIT->>DB : 插入基础数据
DB-->>INIT : 返回结果
INIT-->>CLI : 输出完成信息
```

图表来源
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L13)

章节来源
- [backend/init_db.py](file://backend/init_db.py#L11-L79)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L13)
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)

### Alembic 数据库迁移工具
- 配置与环境
  - Alembic 配置文件指定脚本位置、日志级别与数据库 URL
  - 环境配置加载应用配置与模型元数据，支持离线与在线迁移
- 版本管理
  - 初始版本：创建核心业务表与索引
  - 模板版本：新增指标模板表与关联表，向指标表添加多字段
- 回滚与增量更新
  - 每个版本提供升级与降级逻辑，确保可逆演进
  - 新增字段采用条件判断，避免重复迁移失败

```mermaid
flowchart TD
START(["开始"]) --> CHECK_CFG["读取 Alembic 配置"]
CHECK_CFG --> LOAD_META["加载模型元数据"]
LOAD_META --> MODE{"迁移模式？"}
MODE --> |离线| OFFLINE["离线迁移<br/>直接写入 SQL"]
MODE --> |在线| ONLINE["在线迁移<br/>异步连接执行"]
OFFLINE --> RUN_MIGR["执行迁移"]
ONLINE --> RUN_MIGR
RUN_MIGR --> DONE(["结束"])
```

图表来源
- [backend/alembic.ini](file://backend/alembic.ini#L3-L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L65)

章节来源
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)

### 数据模型与索引设计
- 模型关系
  - 部门与员工一对多、员工与考核/工资一对一多关联
  - 考核记录与明细、指标与模板的多对多通过中间表实现
- 索引策略
  - 针对高频过滤与连接字段建立复合索引，提升查询性能
  - 外键字段与状态字段建立索引，加速筛选与排序
- 约束与校验
  - 指标权重正数约束，保证业务合理性
  - 唯一约束用于编码与用户名等关键字段

```mermaid
erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "被考核"
STAFF ||--o{ SALARY_RECORDS : "产生工资"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被评估"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATORS ||--o{ TEMPLATE_INDICATORS : "关联"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L78-L80)
- [backend/app/models/models.py](file://backend/app/models/models.py#L108-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L170-L173)
- [backend/app/models/models.py](file://backend/app/models/models.py#L195-L197)
- [backend/app/models/models.py](file://backend/app/models/models.py#L301-L304)
- [backend/app/models/models.py](file://backend/app/models/models.py#L330-L332)

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)

### 模板与指标初始化策略
- 模板初始化
  - 依据文档模板创建通用、手术、医技、行政、后勤五类模板
  - 模板与指标通过中间表建立关联，支持分类与权重配置
- 指标初始化
  - 按平衡计分卡维度与科室类型拆分指标集合
  - 支持字段扩展（目标值、单位、计算方法、扣分标准、数据来源、适用科室类型、一票否决等）

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant INIT as "模板初始化脚本"
participant DB as "数据库"
participant MODELS as "ORM 模型"
CLI->>INIT : 调用初始化入口
INIT->>DB : 查询是否存在指标
DB-->>INIT : 返回空/存在
alt 不存在
INIT->>MODELS : 创建指标
INIT->>MODELS : 创建模板
INIT->>MODELS : 关联模板与指标
INIT->>DB : 提交事务
else 已存在
INIT-->>CLI : 跳过初始化
end
INIT-->>CLI : 输出完成信息
```

图表来源
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L11-L371)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L189-L272)

章节来源
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L11-L371)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L189-L272)

### 字段迁移与增量更新
- 字段迁移脚本
  - 向指标表动态添加平衡计分卡维度、目标单位、考核方法、扣分标准、数据来源、适用科室类型、一票否决等字段
  - 采用条件判断避免重复添加导致迁移失败
- 与 Alembic 的配合
  - Alembic 版本 002 同样实现字段添加逻辑，两者可互补使用

```mermaid
flowchart TD
START(["开始"]) --> CONNECT["连接数据库"]
CONNECT --> ADD_COL["逐个添加字段"]
ADD_COL --> CHECK{"字段是否存在？"}
CHECK --> |是| SKIP["跳过该字段"]
CHECK --> |否| DO_ADD["执行添加"]
SKIP --> NEXT["下一个字段"]
DO_ADD --> NEXT
NEXT --> DONE(["结束"])
```

图表来源
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L9-L42)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L65-L91)

章节来源
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L9-L42)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L65-L91)

### 连接池与事务管理
- 连接池配置
  - 在配置模块中设置连接池大小与溢出参数，满足高并发请求
- 事务管理
  - 会话工厂在依赖注入中自动提交或回滚异常，finally 关闭会话，确保资源释放
- 并发与一致性
  - 异步引擎与会话配合，避免阻塞；外键与索引设计减少锁竞争

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)

## 依赖关系分析
- 组件耦合
  - 模型层依赖配置模块提供的数据库 URL，迁移工具依赖模型元数据
  - 初始化脚本与模板脚本依赖模型与会话工厂
- 外部依赖
  - Alembic 依赖 SQLAlchemy 异步引擎
  - 运行时依赖 PostgreSQL 数据库

```mermaid
graph LR
CONFIG["配置模块"] --> ENGINE["异步引擎"]
ENGINE --> SESSION["异步会话"]
SESSION --> MODELS["ORM 模型"]
MODELS --> INIT["初始化脚本"]
MODELS --> SCRIPTS["模板/迁移脚本"]
ALEMBIC_INI["Alembic 配置"] --> ALEMBIC_ENV["Alembic 环境"]
ALEMBIC_ENV --> MODELS
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/alembic.ini](file://backend/alembic.ini#L3-L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/alembic.ini](file://backend/alembic.ini#L3-L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)

## 性能考虑
- 索引设计
  - 为常用过滤字段（如科室类型、员工状态、考核周期、模板类型、用户名等）建立复合索引
  - 对外键字段与排序字段建立索引，减少全表扫描
- 查询优化
  - 使用关系查询时注意惰性加载与联结策略，避免 N+1 查询
  - 对大表进行分页查询，限制返回字段
- 连接池优化
  - 合理设置连接池大小与溢出参数，避免连接争用
  - 在高并发场景下启用异步 I/O，减少阻塞
- 数据建模
  - 将 JSON 字段用于灵活配置（如模板维度权重、适用科室类型），但需谨慎查询与索引策略

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L143-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
- [backend/app/models/models.py](file://backend/app/models/models.py#L258-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L306-L311)
- [backend/app/models/models.py](file://backend/app/models/models.py#L334-L338)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)

## 故障排查指南
- 迁移失败
  - 检查 Alembic 配置文件中的数据库 URL 是否正确
  - 确认模型元数据已正确加载，版本文件命名与依赖关系无误
  - 在线迁移需确保异步连接可用，必要时切换为离线迁移验证
- 字段迁移冲突
  - 使用条件判断避免重复添加字段；若 Alembic 与脚本同时执行，建议统一由 Alembic 管理
- 初始化数据重复
  - 初始化脚本中包含存在性检查，避免重复插入；如出现异常，清理缓存或重新执行
- 连接池耗尽
  - 检查连接池参数与并发请求量，适当增大池大小或优化查询
- 权限问题
  - 确保数据库用户具备创建表、索引与修改表结构的权限

章节来源
- [backend/alembic.ini](file://backend/alembic.ini#L7)
- [backend/alembic/env.py](file://backend/alembic/env.py#L42-L53)
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L9-L42)
- [backend/init_db.py](file://backend/init_db.py#L20-L26)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)

## 结论
本项目通过配置驱动的异步数据库连接、完善的模型与索引设计、版本化的 Alembic 迁移与多类初始化脚本，构建了可演进、可维护、高性能的数据库管理方案。遵循本文的迁移策略、性能优化与安全配置建议，可在生产环境中稳定运行并持续演进。

## 附录

### 数据库备份与恢复流程
- 备份
  - 使用数据库自带工具进行逻辑或物理备份，定期归档
  - 在迁移前执行备份，确保可回滚
- 恢复
  - 从最近备份点恢复，结合 Alembic 迁移补全到最新版本
  - 验证关键表与索引完整性，执行回归测试

### 数据迁移策略
- 渐进式迁移
  - 先迁移结构（表、索引、约束），再迁移数据（基础数据、模板、指标）
- 回滚策略
  - 使用 Alembic 降级到上一版本，配合备份快速恢复
- 兼容性
  - 新增字段采用条件判断，避免破坏现有数据

### 监控指标与连接池配置
- 监控指标
  - 连接池利用率、活跃连接数、等待队列长度、慢查询数量
- 连接池配置
  - 根据并发峰值与响应时间调整池大小与超时参数

### 事务管理最佳实践
- 会话生命周期
  - 依赖注入中自动提交或回滚，finally 关闭会话
- 事务粒度
  - 将原子性要求高的操作放在同一事务中，避免长事务

### 安全配置与审计
- 安全配置
  - 最小权限原则，仅授予所需 DDL/DML 权限
  - 使用强口令与 TLS 加密传输
- 审计日志
  - 记录关键 DDL 操作与重要 DML 变更，便于追溯与合规