提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/部署运维/备份恢复.md
+++ b/.qoder/repowiki/zh/content/部署运维/备份恢复.md
@@ -0,0 +1,303 @@
+# 备份恢复
+
+<cite>
+**本文引用的文件**
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/init_db.py](file://backend/init_db.py)
+- [backend/alembic/env.py](file://backend/alembic/env.py)
+- [backend/alembic.ini](file://backend/alembic.ini)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/.env.example](file://backend/.env.example)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/app/main.py](file://backend/app/main.py)
+- [docs/database.md](file://docs/database.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向“医院绩效系统”的数据库备份与恢复，结合现有代码库中的数据库配置、迁移机制与模型定义，提供覆盖全量备份、增量/差异备份思路、自动化脚本编写、调度与存储管理、数据恢复与灾难恢复流程、业务连续性保障、备份验证与完整性检查、恢复测试方法，以及多环境（开发/测试/生产）数据同步与安全（加密传输、异地容灾）建议。由于当前仓库未包含数据库备份脚本与运维配置，本指南在不虚构实现的前提下，给出可落地的策略与流程。
+
+## 项目结构
+系统采用 FastAPI + SQLAlchemy 异步 ORM + Alembic 迁移的后端架构，数据库连接与配置集中在核心模块，模型定义位于 models，迁移配置位于 alembic。整体结构清晰，便于扩展备份与恢复能力。
+
+```mermaid
+graph TB
+subgraph "后端"
+CFG["配置模块<br/>backend/app/core/config.py"]
+DB["数据库连接模块<br/>backend/app/core/database.py"]
+MODELS["数据模型<br/>backend/app/models/models.py"]
+ALEMBIC_ENV["迁移环境<br/>backend/alembic/env.py"]
+ALEMBIC_INI["迁移配置<br/>backend/alembic.ini"]
+INIT_DB["初始化脚本<br/>backend/init_db.py"]
+MAIN["应用入口<br/>backend/app/main.py"]
+end
+CFG --> DB
+DB --> MODELS
+ALEMBIC_ENV --> MODELS
+ALEMBIC_INI --> ALEMBIC_ENV
+INIT_DB --> DB
+INIT_DB --> MODELS
+MAIN --> CFG
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+- [backend/init_db.py](file://backend/init_db.py#L1-L83)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+- [backend/init_db.py](file://backend/init_db.py#L1-L83)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+
+## 核心组件
+- 配置模块：集中管理数据库连接串、池大小、调试开关等，是备份与恢复策略的配置依据。
+- 数据库连接模块：提供异步引擎与会话工厂，确保备份/恢复过程中的事务一致性。
+- 模型定义：明确表结构、索引与约束，为备份范围与恢复顺序提供依据。
+- 迁移环境与配置：Alembic 提供结构变更的版本化管理，备份策略需考虑结构与数据的协同。
+- 初始化脚本：演示了建表与初始数据插入流程，可作为恢复后验证的基础。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+- [backend/init_db.py](file://backend/init_db.py#L11-L18)
+
+## 架构总览
+系统数据库连接通过异步引擎与会话工厂实现，模型层定义了完整的业务表结构。Alembic 提供结构迁移能力；初始化脚本用于快速搭建测试环境。备份与恢复应围绕这些组件展开，确保结构与数据的一致性。
+
+```mermaid
+sequenceDiagram
+participant App as "应用入口<br/>app/main.py"
+participant Cfg as "配置模块<br/>app/core/config.py"
+participant Db as "数据库连接<br/>app/core/database.py"
+participant Alembic as "迁移环境<br/>alembic/env.py"
+participant Models as "数据模型<br/>models/models.py"
+App->>Cfg : 读取配置
+Cfg-->>App : 返回数据库URL/池参数
+App->>Db : 创建异步引擎与会话工厂
+Db->>Models : 使用Base元数据
+App->>Alembic : 执行迁移(结构)
+Alembic->>Models : 读取metadata
+App->>Db : 初始化/写入数据
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
+
+## 详细组件分析
+
+### 数据库连接与备份影响面
+- 异步引擎与会话工厂：备份应在数据库空闲时段执行，避免长事务阻塞；恢复后需重启应用以重新建立连接。
+- 事务语义：备份期间的写入可能被截断，需结合 WAL/逻辑复制实现近零停机。
+
+```mermaid
+flowchart TD
+Start(["开始备份"]) --> CheckConn["检查数据库连接与可用性"]
+CheckConn --> TxnCheck{"是否存在长事务?"}
+TxnCheck --> |是| WaitIdle["等待事务结束或选择快照级别"]
+TxnCheck --> |否| ChooseMethod["选择备份方法<br/>物理/逻辑/快照"]
+WaitIdle --> ChooseMethod
+ChooseMethod --> ExecBackup["执行备份"]
+ExecBackup --> Verify["校验备份完整性"]
+Verify --> End(["结束"])
+```
+
+图表来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+
+### 模型与索引对备份的影响
+- 索引与约束：备份需保证索引与约束在恢复后一致，避免后续查询异常。
+- 关系与级联：恢复后需验证外键关系与级联行为。
+
+```mermaid
+erDiagram
+DEPARTMENTS ||--o{ STAFF : "1:N"
+STAFF ||--o{ ASSESSMENTS : "1:N"
+INDICATORS ||--o{ ASSESSMENT_DETAILS : "1:N"
+ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
+STAFF ||--o{ SALARY_RECORDS : "1:N"
+USERS ||--o{ ASSESSMENTS : "1:N(assessor)"
+USERS ||--o{ ASSESSMENTS : "1:N(reviewer)"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L202)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L260)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L311)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L338)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L202)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L260)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L311)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L338)
+
+### Alembic 迁移与备份的关系
+- 结构变更：迁移文件记录了数据库结构演进，备份时需同时备份迁移历史与当前结构，确保恢复后能正确升级。
+- 版本控制：备份应包含 Alembic 配置与版本目录，以便在新环境中按版本回放。
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者"
+participant Alembic as "Alembic"
+participant Repo as "版本库"
+participant Prod as "生产数据库"
+Dev->>Alembic : 生成迁移文件
+Alembic->>Repo : 提交迁移文件
+Dev->>Prod : 执行迁移(结构变更)
+Prod-->>Dev : 升级完成
+```
+
+图表来源
+- [docs/database.md](file://docs/database.md#L272-L285)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)
+
+章节来源
+- [docs/database.md](file://docs/database.md#L272-L285)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)
+
+### 初始化脚本与恢复验证
+- 初始化脚本展示了建表与插入初始数据的流程，可用于恢复后的基础数据验证。
+
+章节来源
+- [backend/init_db.py](file://backend/init_db.py#L11-L18)
+- [backend/init_db.py](file://backend/init_db.py#L19-L79)
+
+## 依赖关系分析
+- 配置模块驱动数据库连接模块，后者依赖模型基类；迁移环境读取配置与模型元数据；应用入口加载配置与路由。
+- 备份策略需考虑这些依赖链路的连通性与一致性。
+
+```mermaid
+graph LR
+CFG["config.py"] --> DB["database.py"]
+DB --> MODELS["models.py"]
+ALEMBIC_ENV["alembic/env.py"] --> MODELS
+ALEMBIC_INI["alembic.ini"] --> ALEMBIC_ENV
+MAIN["app/main.py"] --> CFG
+INIT_DB["init_db.py"] --> DB
+INIT_DB --> MODELS
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L4-L25)
+- [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/alembic.ini](file://backend/alembic.ini#L7-L7)
+- [backend/app/main.py](file://backend/app/main.py#L10-L12)
+- [backend/init_db.py](file://backend/init_db.py#L6-L8)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L4-L25)
+- [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/alembic.ini](file://backend/alembic.ini#L7-L7)
+- [backend/app/main.py](file://backend/app/main.py#L10-L12)
+- [backend/init_db.py](file://backend/init_db.py#L6-L8)
+
+## 性能考量
+- 备份窗口：选择业务低峰时段，避免与长事务冲突。
+- 连接池：备份期间可临时降低最大连接数，减少资源竞争。
+- 并发策略：逻辑备份支持并发，但需注意锁与一致性；物理备份需确保一致性快照。
+- 恢复速度：索引重建与约束检查是恢复耗时的关键环节，建议在专用实例上进行恢复演练。
+
+## 故障排查指南
+- 连接失败：检查数据库 URL、凭据与网络连通性；确认配置模块的环境变量加载。
+- 迁移异常：核对 Alembic 配置与版本目录；确保模型元数据与迁移目标一致。
+- 恢复不完整：核对备份集是否包含结构与数据；确认恢复顺序与外键约束满足条件。
+- 权限问题：确保备份/恢复账户具备必要权限；遵循最小权限原则。
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L3-L10)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L32)
+- [backend/alembic/env.py](file://backend/alembic/env.py#L56-L65)
+
+## 结论
+本指南基于现有代码库的数据库配置、模型与迁移机制，提出了备份与恢复的整体策略与流程。建议在现有基础上补充自动化脚本、调度任务与存储管理规范，并定期开展恢复测试与演练，以确保业务连续性与灾难恢复的有效性。
+
+## 附录
+
+### 备份策略与配置方法
+- 全量备份
+  - 逻辑备份：适用于 PostgreSQL，支持跨平台与增量点定位；建议开启压缩与并行度。
+  - 物理备份：适用于需要零停机的场景，需使用一致性快照或只读副本。
+- 增量/差异备份
+  - 增量：基于 WAL 的增量备份，适合频繁写入场景；需配合 PITR（Point-in-Time Recovery）。
+  - 差异：每日差异备份+周期性全量，降低恢复时间；需严格管理差异链。
+- 自动化脚本
+  - 使用定时任务触发备份；脚本需包含连接参数、输出路径、压缩与校验步骤。
+  - 对于 PostgreSQL，可参考官方工具与扩展（如逻辑复制、物理快照）。
+- 备份调度
+  - 低峰时段执行；设置重试与告警；记录备份元数据（版本、时间戳、校验和）。
+- 存储管理
+  - 多层存储：本地热存储、近线归档、远端冷存储；分级保留策略。
+  - 去重与压缩：降低存储成本；注意解压性能对恢复时间的影响。
+
+### 数据恢复流程
+- 准备阶段：确认目标环境与依赖（数据库版本、驱动、连接参数）。
+- 结构恢复：优先恢复迁移历史与结构，确保模型与索引一致。
+- 数据恢复：按备份集顺序恢复数据；校验主键/唯一性与外键关系。
+- 应用启动：重启应用，执行必要的迁移升级；运行初始化脚本进行基础数据验证。
+
+### 灾难恢复计划与业务连续性
+- RTO/RPO：根据业务需求设定恢复目标；优先保证结构与关键数据的恢复。
+- 多活/异地：部署多活实例或异地副本；定期进行切换演练。
+- 降级策略：在极端情况下，优先恢复核心模块（如认证、基础数据），再逐步恢复其他模块。
+
+### 备份数据验证、完整性检查与恢复测试
+- 校验清单：备份集完整性、结构一致性、关键数据抽样比对。
+- 完整性检查：导入到隔离环境进行一致性校验（索引、约束、外键）。
+- 恢复测试：定期在非生产环境进行恢复演练，评估恢复时间与数据可用性。
+
+### 多环境部署的备份策略
+- 开发/测试：使用独立数据库或容器化实例；定期从生产拉取受限数据进行备份与恢复测试。
+- 生产：采用企业级备份解决方案；结合逻辑复制或物理快照实现近零停机。
+
+### 备份存储安全、加密传输与异地容灾
+- 加密：备份文件与传输通道均需加密；密钥管理遵循最小权限与轮换策略。
+- 传输：使用安全协议（如 SFTP/HTTPS）；对敏感数据进行脱敏处理。
+- 异地容灾：在不同地理区域保留备份副本；定期进行异地恢复演练。
--- a/.qoder/repowiki/zh/content/部署运维/安全合规.md
+++ b/.qoder/repowiki/zh/content/部署运维/安全合规.md
@@ -0,0 +1,308 @@
+# 安全合规
+
+<cite>
+**本文引用的文件**
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/.env.example](file://backend/.env.example)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
+- [backend/test_api.py](file://backend/test_api.py)
+- [test_frontend_connection.py](file://test_frontend_connection.py)
+- [docs/backend.md](file://docs/backend.md)
+- [docs/database.md](file://docs/database.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与安全特性](#性能与安全特性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向“医院绩效考核管理系统”的安全与合规落地，聚焦以下方面：
+- 身份认证与授权：JWT 令牌管理、密码加密存储、会话安全与权限控制
+- 网络安全：HTTPS、CORS 策略与前端访问控制
+- 数据安全：敏感数据保护、传输安全与访问控制
+- 审计与风控：日志记录、违规检测与事件响应
+- 漏洞治理：扫描工具使用、补丁管理与合规检查
+- 权限治理：用户权限管理、角色分配与最小权限原则
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 异步 ORM，按功能分层组织：
+- 核心配置与安全：core/config.py、core/security.py、core/logging_config.py
+- API 层：api/v1/*（如 auth.py）
+- 数据模型与枚举：models/models.py
+- 数据契约：schemas/schemas.py
+- 应用入口与中间件：main.py
+- 示例环境变量：.env.example
+- 文档与数据库设计：docs/backend.md、docs/database.md
+- 前端连接测试脚本：test_frontend_connection.py、backend/test_api.py
+
+```mermaid
+graph TB
+subgraph "后端"
+CFG["配置<br/>core/config.py"]
+SEC["安全模块<br/>core/security.py"]
+LOG["日志配置<br/>core/logging_config.py"]
+MAIN["应用入口<br/>app/main.py"]
+AUTH["认证路由<br/>api/v1/auth.py"]
+MODELS["数据模型<br/>models/models.py"]
+SCHEMAS["数据契约<br/>schemas/schemas.py"]
+end
+CFG --> SEC
+CFG --> MAIN
+SEC --> AUTH
+MAIN --> AUTH
+AUTH --> MODELS
+MODELS --> SCHEMAS
+LOG --> MAIN
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [docs/backend.md](file://docs/backend.md#L391-L436)
+- [docs/database.md](file://docs/database.md#L1-L95)
+
+## 核心组件
+- 配置中心：集中管理应用名、版本、调试、API 前缀、数据库连接、JWT 密钥与算法、CORS 白名单、分页参数等
+- 安全模块：OAuth2 密码流、JWT 编解码、bcrypt 密码哈希、当前用户解析、活跃用户校验、管理员/经理权限校验
+- 认证路由：登录、注册、当前用户信息查询
+- 日志模块：按日轮转的多处理器日志，区分应用日志与错误日志
+- 数据模型：用户表含用户名、密码哈希、角色、启用状态等字段
+- 数据契约：用户登录、注册、令牌、用户响应等 Pydantic 模型
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
+
+## 架构总览
+系统通过 FastAPI 提供 REST 接口，CORS 中间件允许指定来源访问；认证采用 OAuth2 密码流配合 JWT；密码以 bcrypt 存储；日志统一输出到控制台与文件。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant API as "FastAPI 应用"
+participant AUTH as "认证路由"
+participant SEC as "安全模块"
+participant DB as "数据库"
+FE->>API : "OPTIONS/POST /api/v1/auth/login"
+API->>AUTH : "路由分发"
+AUTH->>SEC : "验证用户名/密码"
+SEC->>DB : "查询用户并比对哈希"
+DB-->>SEC : "用户对象"
+SEC-->>AUTH : "生成JWT"
+AUTH-->>FE : "返回access_token"
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L41-L48)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+## 详细组件分析
+
+### 身份认证与授权机制
+- OAuth2 密码流：通过 OAuth2PasswordBearer 获取令牌 URL，实现标准授权流程
+- JWT 令牌：包含过期时间与主体标识，使用 HS256 算法签名
+- 密码存储：bcrypt 哈希，不可逆存储
+- 当前用户解析：从 JWT 解析 sub 字段，查询用户并校验是否启用
+- 角色权限：提供管理员与经理级权限校验，未授权请求返回 403
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> Parse["解析JWT载荷"]
+Parse --> Valid{"载荷有效？"}
+Valid -- 否 --> Err["抛出401凭据无效"]
+Valid -- 是 --> LoadUser["根据ID查询用户"]
+LoadUser --> Found{"找到用户？"}
+Found -- 否 --> Err
+Found -- 是 --> Active{"用户启用？"}
+Active -- 否 --> Disabled["抛出400用户禁用"]
+Active -- 是 --> Role{"角色校验"}
+Role --> End(["结束"])
+```
+
+图表来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L20-L110)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+### JWT 令牌管理
+- 令牌签发：携带 exp 与 sub，使用 SECRET_KEY 和 ALGORITHM
+- 令牌过期：默认 8 小时
+- 令牌使用：Bearer 方式在 Authorization 头传递
+- 令牌刷新：当前实现未内置刷新逻辑，建议生产环境引入刷新令牌与黑名单
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L43)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/.env.example](file://backend/.env.example#L6-L8)
+
+### 密码加密存储
+- bcrypt 哈希：注册与登录均基于 bcrypt 校验
+- 密码长度与复杂度：契约层限制最小长度，建议结合业务策略增加复杂度要求
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L327)
+
+### 会话安全管理
+- 会话依赖：当前实现基于 JWT，无服务端会话存储
+- 令牌撤销：未实现黑名单机制，建议引入 Redis/JWT 黑名单或缩短令牌有效期
+- 传输安全：建议强制 HTTPS，避免明文传输
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L52)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+
+### 网络安全配置
+- CORS：允许指定来源、凭证、方法与头
+- 健康检查：提供 /health 接口便于探活
+- 异常处理：全局捕获 HTTP 与验证异常并记录日志
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L41-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L30)
+- [docs/backend.md](file://docs/backend.md#L372-L389)
+
+### 数据安全保护
+- 数据模型：用户表包含密码哈希、角色、启用状态等字段
+- 数据契约：用户登录、注册、令牌、用户响应等模型定义
+- 建议：对敏感字段进行脱敏展示；数据库连接使用 SSL；对日志中敏感字段进行脱敏
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
+
+### 审计日志、违规检测与事件响应
+- 日志：控制台 INFO 级别输出，文件 DEBUG 级别轮转，错误单独 ERROR 文件
+- 建议：接入集中化日志系统（如 ELK/Sentry），设置告警阈值；对登录失败、权限拒绝、敏感操作进行标记与告警
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+
+### 漏洞扫描与补丁管理
+- 建议：定期运行依赖扫描（pip-audit、safety、npm audit 等），修复高危与严重漏洞
+- 版本管理：固定依赖版本，启用自动安全更新与 PR 审查
+- 生产部署：仅在受信网络与 HTTPS 下暴露 API
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L83-L92)
+
+### 合规性检查清单
+- 配置项：密钥、算法、CORS 白名单、分页上限、调试开关
+- 数据保护：密码哈希、传输加密、日志脱敏
+- 权限治理：角色枚举、权限校验、最小权限
+- 运维：健康检查、异常处理、日志轮转
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+
+### 用户权限管理与角色分配
+- 角色字段：用户表 role 字段
+- 权限校验：管理员与经理级权限校验函数
+- 最小权限：建议在路由与服务层进一步细化资源级权限
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L252-L252)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
+
+## 依赖关系分析
+```mermaid
+graph LR
+CFG["core/config.py"] --> SEC["core/security.py"]
+CFG --> MAIN["app/main.py"]
+SEC --> AUTH["api/v1/auth.py"]
+AUTH --> MODELS["models/models.py"]
+MODELS --> SCHEMAS["schemas/schemas.py"]
+MAIN --> LOG["core/logging_config.py"]
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+## 性能与安全特性
+- 异步数据库：使用异步 SQLAlchemy，提升并发性能
+- JWT 无状态：减少服务端会话开销
+- CORS 精准白名单：降低跨域攻击面
+- 日志分级：区分开发与生产日志级别，避免敏感信息泄露
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L391-L436)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
+- [backend/app/main.py](file://backend/app/main.py#L41-L48)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L65)
+
+## 故障排查指南
+- 登录失败：检查用户名/密码是否匹配，确认用户启用状态
+- CORS 问题：确认前端 Origin 是否在 CORS_ORIGINS 列表
+- 令牌无效：确认 SECRET_KEY 一致、算法匹配、未过期
+- 日志定位：查看应用日志与错误日志文件，定位异常堆栈
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L25-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L46-L52)
+- [backend/app/main.py](file://backend/app/main.py#L58-L77)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L21)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)
+- [backend/test_api.py](file://backend/test_api.py#L5-L32)
+
+## 结论
+本系统在认证与授权、日志与异常处理方面具备良好基础，建议在生产环境中补充 HTTPS、令牌黑名单、最小权限细化、集中化日志与告警、漏洞扫描与补丁管理等措施，以满足更严格的合规与安全要求。
+
+## 附录
+- 数据库 ER 设计参考：用户与科室、员工、考核、指标、工资、计划、菜单、模板等实体关系
+- 配置示例：环境变量示例文件，包含数据库、JWT 密钥与调试开关
+
+章节来源
+- [docs/database.md](file://docs/database.md#L1-L95)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
--- a/.qoder/repowiki/zh/content/部署运维/数据库管理.md
+++ b/.qoder/repowiki/zh/content/部署运维/数据库管理.md
@@ -0,0 +1,437 @@
+# 数据库管理
+
+<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 变更，便于追溯与合规
--- a/.qoder/repowiki/zh/content/部署运维/环境部署.md
+++ b/.qoder/repowiki/zh/content/部署运维/环境部署.md
@@ -0,0 +1,352 @@
+# 环境部署
+
+<cite>
+**本文引用的文件**
+- [backend/.env.example](file://backend/.env.example)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/init_db.py](file://backend/init_db.py)
+- [backend/alembic.ini](file://backend/alembic.ini)
+- [frontend/package.json](file://frontend/package.json)
+- [frontend/vite.config.js](file://frontend/vite.config.js)
+- [docs/backend.md](file://docs/backend.md)
+- [docs/frontend.md](file://docs/frontend.md)
+- [docs/database.md](file://docs/database.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能注意事项](#性能注意事项)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向开发与运维团队，提供“医院绩效系统”的完整环境部署方案，覆盖开发与生产环境的搭建步骤、Python 3.10+ 与 Node.js 环境准备、PostgreSQL 数据库安装、后端 FastAPI 与前端 Vue 依赖安装、环境变量配置、虚拟环境与依赖隔离、版本兼容性检查，以及 Docker 容器化与传统部署方案的对比说明。
+
+## 项目结构
+系统采用前后端分离架构：
+- 后端：Python + FastAPI + SQLAlchemy 2.x + Alembic + PostgreSQL
+- 前端：Vue 3 + Vite + Element Plus + Axios
+- 配置与文档：Pydantic Settings 管理后端配置；Vite 代理将前端请求转发至后端；Alembic 管理数据库迁移
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_PKG["frontend/package.json"]
+FE_VITE["frontend/vite.config.js"]
+end
+subgraph "后端"
+BE_REQ["backend/requirements.txt"]
+BE_CFG["backend/app/core/config.py"]
+BE_MAIN["backend/app/main.py"]
+BE_ENV_EXAMPLE["backend/.env.example"]
+BE_ALEMBIC["backend/alembic.ini"]
+end
+FE_PKG --> FE_VITE
+BE_REQ --> BE_CFG
+BE_CFG --> BE_MAIN
+BE_ENV_EXAMPLE --> BE_CFG
+BE_ALEMBIC --> BE_CFG
+```
+
+图表来源
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L1-L475)
+- [docs/frontend.md](file://docs/frontend.md#L1-L416)
+- [docs/database.md](file://docs/database.md#L1-L286)
+
+## 核心组件
+- 后端配置与运行
+  - 配置来源：Pydantic Settings 从 .env 读取环境变量，支持调试模式、数据库连接、JWT 密钥、CORS、分页等参数
+  - 应用入口：FastAPI 应用创建、CORS 中间件注册、路由挂载、健康检查与异常处理
+- 数据库与迁移
+  - 数据库：PostgreSQL（异步驱动 asyncpg），默认 URL 与池大小、溢出配置
+  - 迁移：Alembic 管理数据库版本，支持升级/降级/历史查看
+- 前端开发与构建
+  - 依赖：Vue 3、Vue Router、Pinia、Element Plus、Axios、ECharts、Day.js、Vite、Sass
+  - 代理：Vite 将 /api 前缀代理到后端 8000 端口，解决跨域
+- 初始化脚本
+  - 数据库初始化：创建表并插入测试数据（若表为空）
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/main.py](file://backend/app/main.py#L15-L92)
+- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+## 架构总览
+系统采用前后端分离部署：
+- 前端通过 Vite 开发服务器运行，开发时通过代理将 /api 请求转发到后端
+- 后端使用 Uvicorn 运行，暴露 REST API，Swagger UI 与 ReDoc 文档位于 /api/v1/docs 与 /api/v1/redoc
+- 数据库使用 PostgreSQL，Alembic 管理迁移
+
+```mermaid
+graph TB
+Browser["浏览器/客户端"] --> FE_DEV["前端开发服务器<br/>Vite (5173)"]
+FE_DEV --> API_PROXY["Vite 代理 /api -> 后端 8000"]
+subgraph "后端"
+UVICORN["Uvicorn 服务器<br/>FastAPI 应用 (8000)"]
+CORS["CORS 中间件"]
+ROUTER["API 路由 /api/v1/*"]
+LOGGING["日志与异常处理"]
+end
+UVICORN --> CORS
+UVICORN --> ROUTER
+UVICORN --> LOGGING
+ROUTER --> DB["PostgreSQL 数据库"]
+ROUTER --> ALEMBIC["Alembic 迁移"]
+```
+
+图表来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+
+## 详细组件分析
+
+### 后端环境准备与依赖安装
+- Python 3.10+
+  - 建议使用虚拟环境隔离依赖，确保与系统 Python 解耦
+- 安装后端依赖
+  - 使用 requirements.txt 安装 FastAPI、SQLAlchemy、Alembic、Pydantic、JWT、密码哈希、异步数据库驱动等
+- 环境变量
+  - 复制 .env.example 为 .env，按需修改数据库连接、JWT 密钥、调试模式等
+- 数据库初始化
+  - 可选：执行数据库初始化脚本创建表与测试数据
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> PyVer["检查 Python 3.10+"]
+PyVer --> Venv["创建并激活虚拟环境"]
+Venv --> PipReq["pip install -r backend/requirements.txt"]
+PipReq --> EnvCfg["复制 .env.example 为 .env 并配置参数"]
+EnvCfg --> DBInit{"是否需要初始化数据库?"}
+DBInit --> |是| RunInit["执行数据库初始化脚本"]
+DBInit --> |否| SkipInit["跳过初始化"]
+RunInit --> Done(["完成"])
+SkipInit --> Done
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+### 前端环境准备与依赖安装
+- Node.js 与包管理器
+  - 安装 Node.js，使用 npm 安装依赖
+- 安装前端依赖
+  - 依据 package.json 的 dependencies 与 devDependencies 安装
+- 开发与构建
+  - 开发：npm run dev
+  - 构建：npm run build
+  - 预览：npm run preview
+
+```mermaid
+flowchart TD
+StartFE(["开始"]) --> NodeCheck["检查 Node.js 版本"]
+NodeCheck --> NpmInstall["npm install"]
+NpmInstall --> DevRun["npm run dev (5173)"]
+DevRun --> ProxyCfg["Vite 代理 /api -> 后端 8000"]
+NpmInstall --> Build["npm run build (dist)"]
+Build --> Preview["npm run preview"]
+ProxyCfg --> DoneFE(["完成"])
+Preview --> DoneFE
+```
+
+图表来源
+- [frontend/package.json](file://frontend/package.json#L6-L10)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+
+章节来源
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
+
+### 数据库安装与迁移
+- PostgreSQL 安装
+  - 安装 PostgreSQL，创建数据库与用户
+- 连接配置
+  - 在 .env 或配置文件中设置 DATABASE_URL，确保与 alembic.ini 中的 SQLAlchemy URL 一致或按需调整
+- 迁移与升级
+  - 使用 Alembic 生成、升级、降级与查看迁移历史
+
+```mermaid
+flowchart TD
+DBStart(["开始"]) --> InstallPG["安装 PostgreSQL 并创建数据库"]
+InstallPG --> CfgURL["配置 DATABASE_URL (.env 或配置)"]
+CfgURL --> AlembicInit["初始化 Alembic (如未初始化)"]
+AlembicInit --> Gen["生成迁移 alembic revision --autogenerate"]
+Gen --> Upgrade["升级到最新 alembic upgrade head"]
+Upgrade --> DoneDB(["完成"])
+```
+
+图表来源
+- [backend/.env.example](file://backend/.env.example#L4-L4)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+- [docs/database.md](file://docs/database.md#L274-L285)
+
+章节来源
+- [docs/database.md](file://docs/database.md#L274-L285)
+- [backend/.env.example](file://backend/.env.example#L4-L4)
+- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
+
+### 环境变量配置说明
+- 必填项
+  - 数据库连接：DATABASE_URL（示例值来自 .env.example）
+  - JWT 密钥：SECRET_KEY（生产环境建议至少 32 字符且随机）
+  - 调试模式：DEBUG（开发环境开启，生产关闭）
+- 可选项
+  - CORS 允许源：CORS_ORIGINS（前端开发端口 3000/5173）
+  - API 前缀：API_PREFIX（默认 /api/v1）
+  - 数据库连接池：DATABASE_POOL_SIZE、DATABASE_MAX_OVERFLOW
+  - 分页参数：DEFAULT_PAGE_SIZE、MAX_PAGE_SIZE
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
+
+### 虚拟环境创建、依赖隔离与版本兼容性检查
+- 虚拟环境
+  - 使用 venv 或 conda 创建独立 Python 环境，避免全局污染
+- 依赖隔离
+  - 后端使用 requirements.txt；前端使用 package.json；分别在各自目录安装
+- 版本兼容性
+  - 后端：FastAPI >= 0.115、SQLAlchemy >= 2.0.36、Alembic >= 1.14、Pydantic >= 2.10、asyncpg >= 0.30、uvicorn >= 0.32
+  - 前端：Vue 3.4+、Vite 5.0+、Element Plus 2.5+、Axios 1.6+
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [docs/backend.md](file://docs/backend.md#L3-L15)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+- [docs/frontend.md](file://docs/frontend.md#L3-L16)
+
+### Docker 容器化部署与传统部署对比
+- 传统部署（本机直装）
+  - 优点：部署简单、资源占用低、便于调试
+  - 缺点：环境差异大、依赖冲突风险高
+- 容器化部署（Docker）
+  - 优点：环境一致、可移植性强、易于扩展与回滚
+  - 缺点：学习成本、镜像体积与网络配置
+- 建议
+  - 生产环境优先采用容器化；开发环境可按需选择
+
+[本节为概念性说明，不直接分析具体文件，故无章节来源]
+
+## 依赖关系分析
+后端与前端的关键依赖关系如下：
+
+```mermaid
+graph LR
+subgraph "后端依赖"
+FASTAPI["FastAPI"]
+SQLA["SQLAlchemy 2.x"]
+ALEMBIC["Alembic"]
+PYDANTIC["Pydantic / Pydantic Settings"]
+ASYNC["asyncpg / aiosqlite"]
+UVICORN["Uvicorn"]
+end
+subgraph "前端依赖"
+VUE["Vue 3"]
+ROUTER["Vue Router"]
+PINIA["Pinia"]
+AXIOS["Axios"]
+ELEM["Element Plus"]
+ECHARTS["ECharts"]
+DAYJS["Day.js"]
+VITE["Vite"]
+SASS["Sass"]
+end
+VITE --> AXIOS
+AXIOS --> BACKEND["后端 API (/api/v1)"]
+BACKEND --> SQLA
+SQLA --> ALEMBIC
+BACKEND --> ASYNC
+BACKEND --> UVICORN
+BACKEND --> PYDANTIC
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+
+## 性能注意事项
+- 数据库连接池
+  - 合理设置连接池大小与溢出数量，避免高并发下的连接争用
+- 异步 I/O
+  - 使用异步数据库驱动与异步 ORM，提升 I/O 密集场景性能
+- 前端静态资源
+  - 生产构建后启用缓存与压缩，减少带宽与加载时间
+- 日志与监控
+  - 生产环境开启结构化日志，结合外部监控系统追踪性能瓶颈
+
+[本节提供一般性指导，不直接分析具体文件，故无章节来源]
+
+## 故障排查指南
+- 前端跨域问题
+  - 确认 Vite 代理配置指向后端 8000 端口，代理前缀 /api 与后端 API 前缀一致
+- 后端无法连接数据库
+  - 检查 DATABASE_URL、数据库服务状态、网络连通性与凭据
+- JWT 令牌无效
+  - 确认 SECRET_KEY 设置正确且前后端一致，注意生产环境必须足够复杂
+- Alembic 迁移失败
+  - 检查迁移脚本与数据库版本一致性，必要时执行降级再升级
+- 健康检查
+  - 访问后端 /health 端点确认服务可用
+
+章节来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L18)
+- [backend/app/main.py](file://backend/app/main.py#L54-L56)
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L396-L416)
+
+## 结论
+通过本指南，您可以在开发与生产环境中快速搭建“医院绩效系统”。建议：
+- 使用虚拟环境隔离后端依赖，使用包管理器安装前端依赖
+- 正确配置 .env 与配置模块，确保数据库、JWT、CORS 等关键参数生效
+- 使用 Alembic 管理数据库迁移，生产环境优先容器化部署
+- 遵循版本兼容性要求，关注性能与可观测性
+
+[本节为总结性内容，不直接分析具体文件，故无章节来源]
+
+## 附录
+- 快速命令参考
+  - 后端安装与运行：pip install -r backend/requirements.txt；uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+  - 前端安装与运行：npm install；npm run dev；npm run build；npm run preview
+  - 数据库迁移：alembic revision --autogenerate -m "..."；alembic upgrade head；alembic downgrade -1；alembic history
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [docs/frontend.md](file://docs/frontend.md#L380-L416)
+- [docs/database.md](file://docs/database.md#L274-L285)
--- a/.qoder/repowiki/zh/content/部署运维/系统监控.md
+++ b/.qoder/repowiki/zh/content/部署运维/系统监控.md
@@ -0,0 +1,351 @@
+# 系统监控
+
+<cite>
+**本文引用的文件**   
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/.env.example](file://backend/.env.example)
+- [test_frontend_connection.py](file://test_frontend_connection.py)
+- [ALL_ISSUES_FIXED.md](file://ALL_ISSUES_FIXED.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向“系统监控与日志管理”，围绕应用日志配置、错误日志收集、性能日志分析、日志轮转策略、日志级别与格式标准化，以及系统资源与应用性能监控（API响应时间、数据库查询性能、并发处理能力）、告警机制与通知渠道、监控仪表板搭建与可视化展示进行系统化说明。结合仓库现有代码，给出可落地的实践建议与最佳实践。
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 2.0 异步架构，日志配置集中于核心模块，主程序负责异常处理与健康检查，统计服务与 API 提供了性能与报表相关的能力入口。前端通过健康检查脚本与测试报告验证系统连通性。
+
+```mermaid
+graph TB
+subgraph "后端"
+MAIN["app/main.py"]
+CFG["app/core/config.py"]
+LOG["app/core/logging_config.py"]
+DB["app/core/database.py"]
+STATS_API["app/api/v1/stats.py"]
+STATS_SVC["app/services/stats_service.py"]
+MODELS["app/models/models.py"]
+end
+subgraph "外部"
+REQ["requirements.txt"]
+ENV[".env.example"]
+TEST["test_frontend_connection.py"]
+end
+MAIN --> LOG
+MAIN --> CFG
+MAIN --> STATS_API
+STATS_API --> STATS_SVC
+STATS_SVC --> DB
+DB --> MODELS
+REQ --> MAIN
+ENV --> CFG
+TEST --> MAIN
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)
+
+## 核心组件
+- 日志配置模块：定义日志目录、格式、级别与处理器（控制台、应用日志文件、错误日志文件），并提供子日志器获取方法。
+- 主应用：注册异常处理器、CORS 中间件、路由；提供健康检查端点；统一记录 HTTP、校验与全局异常。
+- 配置模块：集中管理应用名称、版本、调试开关、数据库连接池大小、JWT、跨域、分页等配置。
+- 数据库模块：创建异步引擎与会话工厂，支持调试模式下的 SQL 输出。
+- 统计 API 与服务：提供 BSC 维度、部门统计、趋势、排名、完成度等统计接口与服务实现，便于性能与业务指标分析。
+- 模型层：定义科室、员工、指标、考核、明细、工资、计划、菜单、模板等实体与索引，支撑统计分析与查询性能。
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+
+## 架构总览
+下图展示了日志、异常处理、数据库访问与统计分析之间的交互关系，体现监控与日志在系统中的位置与职责边界。
+
+```mermaid
+graph TB
+CLIENT["客户端/前端"] --> API["FastAPI 应用"]
+API --> EXC["异常处理器<br/>HTTP/校验/全局异常"]
+API --> LOG["日志记录器"]
+API --> ROUTER["路由注册"]
+ROUTER --> STATS_API["统计 API 层"]
+STATS_API --> STATS_SVC["统计服务层"]
+STATS_SVC --> DB["异步数据库引擎/会话"]
+DB --> MODELS["ORM 模型"]
+LOG --> HANDLER_APP["应用日志文件处理器"]
+LOG --> HANDLER_ERR["错误日志文件处理器"]
+LOG --> HANDLER_CONSOLE["控制台处理器"]
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L54-L76)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L33-L59)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L202)
+
+## 详细组件分析
+
+### 日志配置与轮转策略
+- 日志目录与文件命名：自动创建 logs 目录，按日期生成应用日志与错误日志文件，避免多进程写冲突。
+- 日志格式：统一包含时间戳、记录器名称、级别与消息体，便于检索与聚合。
+- 处理器与级别：
+  - 控制台处理器：INFO 级别及以上输出至 stdout。
+  - 应用日志文件处理器：DEBUG 级别，10MB 分割，保留 7 份备份。
+  - 错误日志文件处理器：ERROR 级别，独立文件，10MB 分割，保留 7 份备份。
+- 子日志器：通过 get_logger(name) 获取子记录器，便于模块化日志隔离与追踪。
+
+```mermaid
+flowchart TD
+Start(["应用启动"]) --> InitLogger["初始化日志记录器<br/>设置级别与格式"]
+InitLogger --> AddConsole["添加控制台处理器<br/>级别: INFO"]
+InitLogger --> AddAppFile["添加应用日志文件处理器<br/>级别: DEBUG<br/>大小: 10MB<br/>备份数: 7"]
+InitLogger --> AddErrFile["添加错误日志文件处理器<br/>级别: ERROR<br/>大小: 10MB<br/>备份数: 7"]
+AddConsole --> Ready["日志系统就绪"]
+AddAppFile --> Ready
+AddErrFile --> Ready
+```
+
+图表来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L26-L59)
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+### 异常处理与错误日志收集
+- HTTP 异常：记录请求方法、URL、状态码与详情，便于定位接口错误。
+- 请求校验异常：记录校验错误上下文，辅助前端参数修正。
+- 全局异常：记录异常堆栈，便于定位未捕获异常。
+- 健康检查：提供 /health 端点，便于运维快速判断服务可用性。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant A as "FastAPI 应用"
+participant L as "日志记录器"
+C->>A : 发起请求
+A->>A : 路由匹配与业务处理
+alt HTTP 异常
+A->>L : 记录警告日志
+A-->>C : 返回 HTTP 错误
+else 校验异常
+A->>L : 记录错误日志
+A-->>C : 返回校验错误
+else 其他异常
+A->>L : 记录错误日志(含堆栈)
+A-->>C : 返回服务器错误
+end
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L58-L76)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+
+### 性能日志与统计分析入口
+- 统计 API：提供 BSC 维度、部门统计、趋势、排名、完成度等接口，作为性能与业务分析的数据源。
+- 统计服务：封装复杂查询与聚合逻辑，支持按年月、科室等维度过滤与排序。
+- 数据模型：定义考核、明细、指标、部门、员工等实体，配合索引提升查询效率。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant API as "统计 API"
+participant SVC as "统计服务"
+participant DB as "数据库引擎/会话"
+participant M as "ORM 模型"
+FE->>API : GET /stats/...
+API->>SVC : 调用统计方法(传入过滤条件)
+SVC->>DB : 执行异步查询(聚合/分组/排序)
+DB->>M : 映射为模型对象
+SVC-->>API : 返回聚合结果
+API-->>FE : 返回 JSON 响应
+```
+
+图表来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L202)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+
+### 数据库连接与查询性能
+- 异步引擎：基于 SQLAlchemy 2.0 的异步引擎，支持 echo 开关用于调试期 SQL 输出。
+- 会话工厂：配置过载与池大小，结合业务并发需求调整。
+- 索引与约束：模型层定义了多处索引与约束，有助于统计查询的性能与数据完整性。
+
+```mermaid
+classDiagram
+class DatabaseConfig {
+DATABASE_URL
+DATABASE_POOL_SIZE
+DATABASE_MAX_OVERFLOW
+DEBUG
+}
+class Engine {
+create_async_engine(url, echo)
+}
+class SessionMaker {
+async_session_maker()
+}
+class Base {
+<<declarative_base>>
+}
+DatabaseConfig --> Engine : "提供连接参数"
+Engine --> SessionMaker : "创建会话工厂"
+SessionMaker --> Base : "会话绑定模型"
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+
+### 健康检查与前端连通性
+- 健康检查：/health 返回服务状态与版本，便于容器编排与负载均衡探活。
+- 前端连通性测试：脚本对后端健康端点与前端端口进行探测，辅助快速定位网络或服务问题。
+
+```mermaid
+sequenceDiagram
+participant T as "测试脚本"
+participant BE as "后端 /health"
+participant FE as "前端"
+T->>BE : GET /health
+BE-->>T : 200 健康状态
+T->>FE : GET 前端首页
+FE-->>T : 200 页面
+T-->>T : 输出连通性结论
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L54-L56)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L15-L35)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)
+
+## 依赖关系分析
+- 运行时依赖：FastAPI、Uvicorn、SQLAlchemy 2.x、asyncpg/aiosqlite、Alembic、Pydantic、Pydantic-Settings、Passlib、python-dotenv、HTTPX、PyTest 等。
+- 环境变量：数据库 URL、JWT 密钥、调试开关等通过 .env.example 提供示例。
+
+```mermaid
+graph LR
+FASTAPI["FastAPI"] --> UVICORN["Uvicorn"]
+FASTAPI --> SQLA["SQLAlchemy 2.x"]
+SQLA --> ASYNC["异步引擎/会话"]
+SQLA --> MODELS["ORM 模型"]
+ALEMBIC["Alembic"] --> DB["数据库迁移"]
+PYDANTIC["Pydantic/Settings"] --> CONFIG["应用配置"]
+PASSLIB["Passlib"] --> AUTH["认证/加密"]
+DOTENV["python-dotenv"] --> CONFIG
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L46)
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+
+## 性能考虑
+- 日志轮转：当前配置为 10MB 分割、7 份备份，建议结合磁盘容量与日志量评估，必要时降低单文件大小或增加备份数。
+- 日志级别：生产环境建议将控制台级别提升至 WARNING 或 ERROR，减少 INFO 级噪声；仅在调试阶段开启 DEBUG。
+- 数据库连接池：根据并发与数据库承载能力调整池大小与最大溢出数，避免连接争用。
+- 查询优化：利用模型层索引（如考核状态、周期、部门等）与分页，避免一次性加载大量数据。
+- API 响应时间：可通过中间件或装饰器埋点统计请求耗时，结合日志与指标系统进行趋势分析。
+
+## 故障排查指南
+- 健康检查失败：确认后端服务已启动且监听端口正确，查看日志文件定位异常。
+- 前端无法访问：使用测试脚本检查前端端口可达性，核对 CORS 配置。
+- 统计接口返回空数据：当前部分统计接口返回模拟数据或需填充真实数据，参考测试报告中的接口调用示例。
+- 数据库连接问题：核对 .env 中 DATABASE_URL 与数据库服务状态，确认驱动（asyncpg/aiosqlite）安装正确。
+
+章节来源
+- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)
+- [ALL_ISSUES_FIXED.md](file://ALL_ISSUES_FIXED.md#L94-L169)
+- [backend/.env.example](file://backend/.env.example#L3-L10)
+
+## 结论
+本项目已具备完善的日志配置与异常处理基础，统计 API 与服务提供了性能与业务分析的入口。建议在生产环境中进一步完善日志级别与轮转策略、引入数据库慢查询与连接池监控、扩展告警与通知机制，并基于统计接口搭建可视化仪表板，实现持续可观测与趋势分析。
+
+## 附录
+
+### 日志级别与格式标准化建议
+- 级别划分：DEBUG/INFO/WARNING/ERROR/CRITICAL，生产环境默认 WARNING，调试时临时提升。
+- 格式字段：时间戳、记录器名称、线程/协程 ID、级别、模块路径、行号、消息体、异常堆栈（如有）。
+- 文件命名：按日期切分，错误日志独立文件，便于检索与归档。
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L24)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L33-L59)
+
+### 告警机制与通知渠道
+- 告警维度：HTTP 错误率、异常频次、数据库连接池耗尽、慢查询阈值、队列积压、磁盘/内存/CPU 阈值。
+- 阈值设置：结合历史峰值与 SLA 设定，建议采用滚动窗口与自适应阈值。
+- 通知渠道：邮件、企业微信/钉钉机器人、IM 通道，区分严重与一般告警等级。
+
+[本节为概念性内容，无需文件来源]
+
+### 监控仪表板与可视化
+- 数据源：统计 API（BSC 维度、部门统计、趋势、排名、完成度）与系统指标（CPU/内存/磁盘/网络）。
+- 可视化组件：折线图（趋势）、柱状图（排名）、仪表盘（关键指标）、热力图（部门得分分布）。
+- 实现建议：前端图表库 + 后端定时抓取/推送，或接入 Prometheus/Grafana（扩展）。
+
+[本节为概念性内容，无需文件来源]
--- a/.qoder/repowiki/zh/content/部署运维/部署运维.md
+++ b/.qoder/repowiki/zh/content/部署运维/部署运维.md
@@ -0,0 +1,337 @@
+# 部署运维
+
+<cite>
+**本文引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/.env.example](file://backend/.env.example)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/init_db.py](file://backend/init_db.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [docs/backend.md](file://docs/backend.md)
+- [docs/database.md](file://docs/database.md)
+- [frontend/package.json](file://frontend/package.json)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向医院绩效系统的生产部署与运维，覆盖以下主题：
+- 生产环境部署流程与环境变量配置
+- Docker 容器化部署与 Nginx 反向代理、SSL 证书管理
+- 数据库备份策略、日志管理与性能监控
+- 负载均衡、高可用架构与灾难恢复计划
+- 运维脚本、自动化部署与版本升级流程
+- 安全加固、漏洞扫描与合规性检查
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 2.0 异步架构，前端为 Vue 3 + Vite。系统通过 .env 管理运行时配置，支持 Alembic 数据库迁移。
+
+```mermaid
+graph TB
+subgraph "后端"
+A["app/main.py<br/>应用入口与路由注册"]
+B["app/core/config.py<br/>配置管理"]
+C["app/core/database.py<br/>异步数据库引擎"]
+D["app/core/logging_config.py<br/>日志配置"]
+E["app/api/v1/__init__.py<br/>路由聚合"]
+F["init_db.py<br/>初始化与测试数据"]
+end
+subgraph "前端"
+G["frontend/package.json<br/>构建与依赖"]
+end
+A --> E
+A --> B
+A --> D
+E --> C
+F --> C
+G --> A
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/init_db.py](file://backend/init_db.py#L1-L83)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [docs/backend.md](file://docs/backend.md#L1-L475)
+
+## 核心组件
+- 应用入口与路由：创建 FastAPI 实例、注册 CORS、健康检查、全局异常处理，并挂载 v1 路由前缀。
+- 配置管理：集中管理应用名称、版本、调试模式、API 前缀、数据库连接、JWT 密钥算法与过期时间、CORS 源、分页参数等。
+- 数据库层：异步 SQLAlchemy 引擎与会话工厂，提供依赖注入式数据库会话。
+- 日志模块：按日轮转的多处理器日志记录，区分应用日志与错误日志。
+- 初始化脚本：自动建表与插入测试数据，避免重复初始化。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+## 架构总览
+系统采用前后端分离架构，后端提供 REST API，前端通过 Axios 访问后端接口；数据库为 PostgreSQL，使用异步驱动。
+
+```mermaid
+graph TB
+FE["前端应用<br/>Vue 3 + Vite"] --> API["后端API<br/>FastAPI"]
+API --> DB["数据库<br/>PostgreSQL"]
+API --> LOG["日志系统<br/>按日轮转"]
+API --> CFG["配置中心<br/>.env + pydantic-settings"]
+```
+
+图表来源
+- [docs/backend.md](file://docs/backend.md#L3-L15)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L37)
+
+## 详细组件分析
+
+### 配置管理（Settings）
+- 环境变量文件：.env.example 提供数据库 URL、JWT 密钥、调试开关等示例。
+- 运行时配置：Settings 使用 pydantic-settings 从 .env 加载，支持缓存单例。
+- 关键项：
+  - 应用名称与版本、调试模式、API 前缀
+  - 数据库连接串、连接池大小与溢出
+  - JWT 密钥、算法与过期时间
+  - CORS 源列表
+  - 分页默认与最大页大小
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+
+### 数据库层（异步引擎与会话）
+- 异步引擎：基于配置的 DATABASE_URL 创建 asyncpg 引擎，DEBUG 控制 echo。
+- 会话工厂：异步会话构造与生命周期管理，提供依赖注入。
+- 依赖函数：get_db 提供事务语义（提交/回滚/关闭），确保异常安全。
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+
+### 日志模块（RotatingFileHandler）
+- 日志目录：位于 backend/logs，按日期命名文件。
+- 处理器：
+  - 控制台 INFO 级别输出
+  - 文件 DEBUG 级别轮转（10MB，保留7份）
+  - 错误 ERROR 级别单独文件轮转
+- 获取子日志器：统一命名空间，便于模块化追踪。
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)
+
+### 应用入口与路由（FastAPI）
+- 应用实例：设置标题、版本、OpenAPI 文档路径前缀。
+- CORS 中间件：允许指定源、凭证、方法与头。
+- 路由注册：聚合 v1 子路由，统一前缀。
+- 健康检查：/health 返回状态与版本。
+- 异常处理：HTTP、请求校验、全局异常统一记录与抛出。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+
+### 初始化脚本（建表与测试数据）
+- 自动建表：创建所有模型对应的数据表。
+- 测试数据：若 departments 表为空则批量插入默认数据。
+- 管理员账户：创建 admin 用户并设置密码哈希。
+
+章节来源
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+### 前端构建与依赖
+- 构建脚本：dev/build/preview。
+- 依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js。
+- 与后端交互：通过 Axios 访问后端 API（具体接口见 API 文档）。
+
+章节来源
+- [frontend/package.json](file://frontend/package.json#L6-L26)
+- [docs/backend.md](file://docs/backend.md#L470-L475)
+
+## 依赖关系分析
+后端模块之间的依赖关系如下：
+
+```mermaid
+graph LR
+main_py["app/main.py"] --> api_v1_init["app/api/v1/__init__.py"]
+main_py --> cfg_py["app/core/config.py"]
+main_py --> log_cfg_py["app/core/logging_config.py"]
+api_v1_init --> db_py["app/core/database.py"]
+init_db_py["init_db.py"] --> db_py
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L10-L51)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L27-L65)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/init_db.py](file://backend/init_db.py#L14-L15)
+
+## 性能考虑
+- 数据库连接池：通过配置 DATABASE_POOL_SIZE 与 DATABASE_MAX_OVERFLOW 控制并发与溢出。
+- 异步 I/O：使用 SQLAlchemy 2.0 异步引擎与 asyncpg，减少阻塞。
+- 日志级别：生产建议提升控制台级别至 INFO，避免过多 DEBUG 输出。
+- 分页限制：MAX_PAGE_SIZE 限制单页最大条数，防止资源滥用。
+- 健康检查：/health 用于探活，结合负载均衡实现快速摘除不健康实例。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/main.py](file://backend/app/main.py#L53-L56)
+
+## 故障排查指南
+- 健康检查失败：确认 /health 返回 healthy 与版本号。
+- 数据库连接异常：检查 DATABASE_URL、网络连通性与 PostgreSQL 服务状态。
+- 日志定位：查看 backend/logs 下按日期命名的日志文件，优先关注 ERROR 日志。
+- CORS 问题：确认前端地址在 CORS_ORIGINS 列表中。
+- 初始化未生效：确认 init_db.py 执行顺序与数据库权限。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L53-L77)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
+- [backend/init_db.py](file://backend/init_db.py#L20-L25)
+
+## 结论
+本指南提供了从配置、部署到运维监控的完整实践路径。建议在生产环境中严格管理 .env，启用 HTTPS 与 TLS，完善数据库备份与日志归档，并结合负载均衡与健康检查实现高可用。
+
+## 附录
+
+### A. 生产环境部署流程
+- 准备阶段
+  - 准备 PostgreSQL 实例，创建数据库与用户。
+  - 生成并妥善保管 SECRET_KEY（至少 32 字符）。
+- 配置
+  - 复制 .env.example 为 .env，填写 DATABASE_URL、SECRET_KEY、DEBUG=false。
+  - 设置 CORS_ORIGINS 为前端域名或 IP。
+- 启动
+  - 安装依赖：pip install -r backend/requirements.txt
+  - 初始化数据库：python backend/init_db.py
+  - 启动服务：uvicorn app.main:app --host 0.0.0.0 --port 8000
+- 验证
+  - 访问 /health 检查服务状态
+  - 访问 /api/v1/docs 或 /api/v1/redoc 查看接口文档
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/init_db.py](file://backend/init_db.py#L81-L83)
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+
+### B. 环境变量清单
+- DATABASE_URL：数据库连接串（PostgreSQL）
+- SECRET_KEY：JWT 密钥
+- DEBUG：调试模式开关
+- CORS_ORIGINS：允许跨域的源列表
+- API_PREFIX：API 前缀（如 /api/v1）
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L3-L10)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
+
+### C. Docker 容器化部署（步骤说明）
+- 构建镜像
+  - 基于 Python 3.11+ 镜像
+  - 复制 requirements.txt 并安装依赖
+  - 复制后端代码与 .env
+  - 暴露端口 8000
+- 运行容器
+  - 挂载日志目录 backend/logs 至宿主机
+  - 指定环境变量（DATABASE_URL、SECRET_KEY、DEBUG、CORS_ORIGINS、API_PREFIX）
+  - 通过健康检查 /health 配置探针
+- 注意
+  - 将 .env 放置于受控位置，避免泄露
+  - 使用只读卷挂载代码，仅挂载日志目录为可写
+
+[本节为概念性说明，不直接分析具体文件，故无“章节来源”]
+
+### D. Nginx 反向代理与 SSL 证书
+- 反代配置要点
+  - 将 /api/* 反代至后端服务（如 http://backend:8000）
+  - 静态资源指向前端 dist 目录（如 /dist）
+  - 启用 gzip/ssl，开启 HSTS
+- SSL 证书
+  - 使用 Let’s Encrypt 或企业 CA
+  - 自动续期脚本与监控告警
+- 健康检查
+  - upstream 中配置 /health 探针，失败自动摘除
+
+[本节为概念性说明，不直接分析具体文件，故无“章节来源”]
+
+### E. 数据库备份策略
+- 全量备份：每周日凌晨执行 pg_dump -U <user> -h <host> <db> > backup.sql
+- 增量/归档：开启 WAL 归档，配合 PITR
+- 存储备份：加密存储于对象存储或磁带库，保留 4-8 周
+- 验证恢复：每季度执行恢复演练
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### F. 日志管理与性能监控
+- 日志
+  - 后端：backend/logs 按日轮转，保留 7 天
+  - 前端：浏览器控制台与网络面板排查
+- 监控
+  - 指标：CPU/内存/连接数/慢查询/错误率
+  - 告警：阈值触发与收敛策略
+  - 链路追踪：结合 OpenTelemetry 或 APM
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### G. 负载均衡、高可用与灾难恢复
+- 高可用
+  - 多实例部署（至少 2 个后端实例）
+  - PostgreSQL 主从复制或托管服务
+  - 健康检查与自动摘除
+- 灾难恢复
+  - RTO/RPO 目标明确
+  - 快速恢复流程与角色分工
+  - 定期演练与文档更新
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### H. 运维脚本、自动化部署与版本升级
+- 自动化
+  - CI/CD：拉取代码 → 单元测试 → 构建镜像 → 发布
+  - 蓝绿/滚动发布：灰度流量切换
+- 升级流程
+  - 数据库迁移：alembic upgrade head
+  - 前后端版本对齐：锁定依赖版本
+  - 回滚预案：镜像标签回滚与数据库 downgrade
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L438-L452)
+
+### I. 安全加固、漏洞扫描与合规
+- 安全加固
+  - 禁用 DEBUG，最小权限原则
+  - 强密码与密钥轮换，HTTPS 强传输
+  - 输入校验与 SQL 注入防护（ORM 已内置）
+- 漏洞扫描
+  - 依赖扫描：pip-audit/安全扫描工具
+  - 漏洞修复与补丁管理
+- 合规
+  - 数据最小化与访问审计
+  - 签名与完整性校验（如需要）
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]