提交文件

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,452 @@
+# 系统基础模型
+
+<cite>
+**本文引用的文件**
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [docs/详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件聚焦系统基础模型，围绕以下核心实体展开：用户（User）、菜单（Menu）、指标模板（IndicatorTemplate）、模板指标（TemplateIndicator）。文档将深入解释这些模型的设计理念、实现细节与相互关系，涵盖用户认证与授权、菜单权限管理、指标模板系统、模板与指标的关联关系、用户角色管理、菜单层级结构、模板类型分类、模板指标权重与排序机制、用户与员工的关联关系、菜单父子层级、模板激活状态管理等主题。同时提供系统配置示例、权限控制机制与模板管理最佳实践。
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 2.0 异步 ORM 的分层架构：
+- models 层：定义数据库模型与枚举类型
+- schemas 层：定义 Pydantic 数据模式（输入/输出）
+- api 层：定义路由与权限依赖
+- services 层：封装业务逻辑
+- core 层：安全、配置、数据库连接等基础设施
+- main：应用入口与中间件注册
+
+```mermaid
+graph TB
+subgraph "应用层"
+API_AUTH["API: /api/v1/auth"]
+API_MENUS["API: /api/v1/menus"]
+API_TEMPLATES["API: /api/v1/templates"]
+end
+subgraph "服务层"
+S_AUTH["Security 模块"]
+S_MENU["MenuService"]
+S_TEMPLATE["TemplateService"]
+end
+subgraph "模型层"
+M_USER["User"]
+M_MENU["Menu"]
+M_INDICATOR["Indicator"]
+M_TEMPLATE["IndicatorTemplate"]
+M_TINDICATOR["TemplateIndicator"]
+end
+API_AUTH --> S_AUTH
+API_MENUS --> S_MENU
+API_TEMPLATES --> S_TEMPLATE
+S_AUTH --> M_USER
+S_MENU --> M_MENU
+S_TEMPLATE --> M_TEMPLATE
+S_TEMPLATE --> M_TINDICATOR
+S_TEMPLATE --> M_INDICATOR
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L438)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+
+## 核心组件
+本节对 User、Menu、IndicatorTemplate、TemplateIndicator 四个核心模型进行系统性解析，包括字段含义、约束、关系与索引策略。
+
+- User（系统用户）
+  - 关键点：用户名唯一、密码哈希存储、关联员工（可选）、角色（字符串）、启用状态、最后登录时间
+  - 关系：与 Staff 为一对一（外键关联）
+  - 权限：通过角色字段区分 admin/manager/staff；安全中间件提供获取当前用户、激活用户、管理员/经理权限校验
+- Menu（系统菜单）
+  - 关键点：父子自引用（parent_id → menus.id）、菜单类型（菜单/按钮）、排序、可见性、启用状态
+  - 关系：自关联 parent/children；支持树形结构查询
+  - 权限：菜单权限标识（permission）用于前端路由鉴权
+- IndicatorTemplate（指标模板）
+  - 关键点：模板类型（TemplateType）、维度权重（JSON 字符串）、考核周期、启用状态
+  - 关系：一对多到 TemplateIndicator
+- TemplateIndicator（模板指标）
+  - 关键点：与 Indicator 多对一、分类（category）、目标值/单位、权重、评分方法/参数、排序、备注
+  - 关系：与 Indicator 一对一（反向为多对一）
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L582-L639)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
+
+## 架构总览
+系统采用前后端分离，后端提供 REST API，前端通过权限标识与菜单树渲染导航。认证采用 JWT，菜单树仅返回可见且启用项，模板管理支持按类型与启用状态筛选。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant API as "API 路由"
+participant SEC as "安全模块"
+participant SVC as "服务层"
+participant DB as "数据库"
+FE->>API : 登录请求
+API->>SEC : 校验用户名/密码
+SEC->>DB : 查询用户
+DB-->>SEC : 用户记录
+SEC-->>API : 生成访问令牌
+API-->>FE : 返回令牌
+FE->>API : 获取菜单树
+API->>SEC : 获取当前激活用户
+SEC-->>API : 当前用户
+API->>SVC : 查询菜单树
+SVC->>DB : 查询根菜单可见且启用
+DB-->>SVC : 菜单集合
+SVC-->>API : 菜单树
+API-->>FE : 返回菜单树
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L29)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
+
+## 详细组件分析
+
+### 用户与认证授权
+- 认证流程
+  - 登录：OAuth2Password 请求表单，校验密码哈希，检查用户启用状态，签发访问令牌
+  - 注册：检查用户名唯一性，生成密码哈希，创建用户记录
+  - 当前用户：从 JWT 提取用户 ID，查询用户并校验启用状态
+  - 权限：管理员（admin）与经理（manager）具备更高操作权限
+- 角色与权限
+  - User.role 控制资源访问范围
+  - 路由层通过依赖注入校验当前用户角色与状态
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant AuthAPI as "Auth API"
+participant Security as "Security"
+participant DB as "数据库"
+Client->>AuthAPI : POST /api/v1/auth/login
+AuthAPI->>DB : 查询用户
+DB-->>AuthAPI : 用户(含密码哈希)
+AuthAPI->>Security : 验证密码
+Security-->>AuthAPI : 校验结果
+AuthAPI->>Security : 生成访问令牌
+AuthAPI-->>Client : {access_token, token_type}
+Client->>AuthAPI : GET /api/v1/auth/me
+AuthAPI->>Security : 获取当前激活用户
+Security->>DB : 查询用户
+DB-->>Security : 用户
+Security-->>AuthAPI : 当前用户
+AuthAPI-->>Client : 用户信息
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L91)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+
+### 菜单与权限管理
+- 菜单模型
+  - 支持菜单/按钮两类，父子自引用，排序与可见性控制
+  - 菜单树查询：仅返回顶层、可见且启用的菜单，并递归加载子节点
+- 权限控制
+  - 菜单权限标识（permission）用于前端路由鉴权
+  - 菜单管理 API 通过角色依赖限制创建/更新/删除操作
+- 初始化
+  - 支持初始化默认菜单，避免重复初始化
+
+```mermaid
+flowchart TD
+Start(["获取菜单树"]) --> BuildQuery["构建查询: 顶层菜单<br/>可见且启用"]
+BuildQuery --> LoadChildren["加载子节点关系"]
+LoadChildren --> OrderBy["按排序与ID排序"]
+OrderBy --> ToDict["_menu_to_dict 递归转字典"]
+ToDict --> End(["返回菜单树"])
+```
+
+图表来源
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L101-L109)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+
+### 指标模板系统
+- 模板类型
+  - 通用模板、手术临床、非手术有病房、非手术无病房、医技、护理、行政、后勤
+- 维度权重
+  - 模板可配置 BSC 四维度权重（JSON 字符串），用于汇总计算
+- 考核周期
+  - 支持月度/年度等周期配置
+- 列表与详情
+  - 支持按类型与启用状态筛选，返回模板指标数量
+  - 详情包含模板基本信息与完整指标列表（含指标名称、编码、类型、维度、权重、排序等）
+
+```mermaid
+classDiagram
+class IndicatorTemplate {
+template_name
+template_code
+template_type
+dimension_weights
+assessment_cycle
+is_active
+indicators[]
+}
+class TemplateIndicator {
+indicator_id
+category
+target_value
+target_unit
+weight
+scoring_method
+scoring_params
+sort_order
+remark
+indicator
+}
+class Indicator {
+name
+code
+indicator_type
+bs_dimension
+weight
+max_score
+}
+IndicatorTemplate "1" --> "many" TemplateIndicator : "包含"
+TemplateIndicator "many" --> "1" Indicator : "关联"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
+
+### 模板与指标的关联关系
+- 关联表 TemplateIndicator
+  - 唯一约束：同一模板下指标唯一
+  - 排序字段 sort_order 决定展示顺序
+  - 支持批量添加，自动补齐排序
+- 权重与排序机制
+  - 模板层与指标层均支持权重配置
+  - 汇总时需遵循维度权重与指标权重的乘积规则（由上层业务逻辑决定）
+- 激活状态管理
+  - 模板与指标均可启用/停用，影响使用范围与计算
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L438)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L207)
+
+### 用户与员工的关联关系
+- User 与 Staff
+  - User.staff_id 外键关联 Staff.id，表示系统用户与员工的绑定关系
+  - 便于登录后获取员工信息与权限边界
+- 员工状态与部门
+  - Staff.status 与 Department.parent_id/level 等字段共同构成组织与人员管理基础
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+### 菜单层级结构
+- 自引用关系
+  - Menu.parent_id → Menu.id，支持任意层级
+  - 服务层通过 selectinload 预加载 children，避免 N+1 查询
+- 树形渲染
+  - 顶层查询（parent_id IS NULL），按 sort_order 与 id 排序
+  - 递归转换为字典树，供前端渲染
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+
+### 模板类型分类逻辑
+- TemplateType 枚举覆盖全院主要科室类型，便于按类型匹配模板
+- 服务层提供类型标签映射，便于前端展示
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L385)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L270-L283)
+
+### 权重与排序机制
+- 指标层权重
+  - Indicator.weight 与 TemplateIndicator.weight 双层权重
+  - 数据库层对指标权重设置正数约束
+- 排序
+  - TemplateIndicator.sort_order 决定模板内指标顺序
+  - 批量添加时可按传入顺序补齐排序
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L124-L146)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L421-L427)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L256-L267)
+
+### 激活状态管理
+- 模板与菜单均提供 is_active 字段
+- 菜单树查询默认仅返回启用项
+- 模板列表支持按 is_active 过滤
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L398-L398)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L360-L360)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L21)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
+
+## 依赖分析
+- 模型依赖
+  - User ←→ Staff（一对一外键）
+  - Menu ←→ Menu（自引用）
+  - IndicatorTemplate → TemplateIndicator → Indicator（多对一）
+- 服务依赖
+  - MenuService 依赖 Menu 模型
+  - TemplateService 依赖 IndicatorTemplate、TemplateIndicator、Indicator 模型
+- API 依赖
+  - auth 路由依赖 Security 与 User 模型
+  - menus 路由依赖 MenuService 与 Menu 模型
+  - templates 路由依赖 TemplateService 与模板相关 Schema
+
+```mermaid
+graph LR
+A["User"] <- --> B["Staff"]
+C["Menu"] --自引用 --> C
+D["IndicatorTemplate"] --> E["TemplateIndicator"]
+E --> F["Indicator"]
+G["MenuService"] --> C
+H["TemplateService"] --> D
+H --> E
+H --> F
+I["Auth API"] --> G
+J["Menus API"] --> G
+K["Templates API"] --> H
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L438)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+
+## 性能考虑
+- 查询优化
+  - 使用 selectinload 预加载关系，减少 N+1 查询
+  - 菜单树查询限定顶层、可见与启用条件
+- 索引策略
+  - 模型层为常用过滤字段建立索引（如模板类型、菜单可见性、指标权重约束）
+- 分页与排序
+  - 模板列表支持分页与排序，避免一次性加载过多数据
+- 缓存与并发
+  - 配置层提供数据库连接池参数，建议在生产环境按负载调优
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L368-L372)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L143-L146)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+## 故障排查指南
+- 登录失败
+  - 检查用户名是否存在、密码是否正确、用户是否启用
+  - 查看安全模块的凭据验证与令牌生成流程
+- 菜单不可见
+  - 确认菜单 is_visible 与 is_active 状态
+  - 检查菜单树查询是否仅返回可见启用项
+- 模板操作失败
+  - 检查模板编码唯一性、模板与指标是否存在、唯一约束冲突
+  - 确认排序字段是否正确传递
+- 权限不足
+  - 确认当前用户角色（admin/manager/staff）
+  - 检查路由依赖是否正确应用
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L86-L98)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L136-L140)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L167-L182)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
+
+## 结论
+本系统基础模型围绕 User、Menu、IndicatorTemplate、TemplateIndicator 构建，通过清晰的枚举与约束、合理的索引与查询策略、严格的权限控制与安全中间件，实现了用户认证授权、菜单权限管理、指标模板体系与模板-指标关联的完整闭环。模板类型覆盖全院主要科室，权重与排序机制满足多维度汇总需求，激活状态管理确保系统灵活性。配合服务层与 API 层的职责分离，系统具备良好的扩展性与可维护性。
+
+## 附录
+
+### 系统配置示例
+- JWT 配置
+  - SECRET_KEY、ALGORITHM、ACCESS_TOKEN_EXPIRE_MINUTES
+- 数据库连接
+  - DATABASE_URL、DATABASE_POOL_SIZE、DATABASE_MAX_OVERFLOW
+- 跨域与分页
+  - CORS_ORIGINS、DEFAULT_PAGE_SIZE、MAX_PAGE_SIZE
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+
+### 权限控制机制
+- 当前用户获取与校验
+  - 从 JWT 解析用户 ID，查询用户并校验启用状态
+- 角色权限
+  - 管理员（admin）：最高权限
+  - 经理（manager）：部分管理操作
+  - 普通员工（staff）：受限操作
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L109)
+
+### 模板管理最佳实践
+- 模板类型选择
+  - 根据科室类型选择对应模板，避免跨类型混用
+- 维度权重设计
+  - 明确财务/客户/内部流程/学习与成长的权重范围与合计
+- 指标权重与排序
+  - 指标层权重与模板层权重协同，排序字段保持连续与稳定
+- 激活状态
+  - 新建模板先启用少量指标进行测试，逐步放开
+
+章节来源
+- [docs/详细设计.md](file://docs/详细设计.md#L69-L95)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L63-L74)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L270-L283)