# 系统基础模型

<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)