Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Blame History

系统基础模型

**本文引用的文件** - [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)

简介

本文件聚焦系统基础模型，围绕以下核心实体展开：用户（User）、菜单（Menu）、指标模板（IndicatorTemplate）、模板指标（TemplateIndicator）。文档将深入解释这些模型的设计理念、实现细节与相互关系，涵盖用户认证与授权、菜单权限管理、指标模板系统、模板与指标的关联关系、用户角色管理、菜单层级结构、模板类型分类、模板指标权重与排序机制、用户与员工的关联关系、菜单父子层级、模板激活状态管理等主题。同时提供系统配置示例、权限控制机制与模板管理最佳实践。

项目结构

后端采用 FastAPI + SQLAlchemy 2.0 异步 ORM 的分层架构：

models 层：定义数据库模型与枚举类型
schemas 层：定义 Pydantic 数据模式（输入/输出）
api 层：定义路由与权限依赖
services 层：封装业务逻辑
core 层：安全、配置、数据库连接等基础设施
main：应用入口与中间件注册

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

图表来源

章节来源

核心组件

本节对 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 一对一（反向为多对一）

章节来源

架构总览

系统采用前后端分离，后端提供 REST API，前端通过权限标识与菜单树渲染导航。认证采用 JWT，菜单树仅返回可见且启用项，模板管理支持按类型与启用状态筛选。

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 : 返回菜单树

图表来源

详细组件分析

用户与认证授权

认证流程
- 登录：OAuth2Password 请求表单，校验密码哈希，检查用户启用状态，签发访问令牌
- 注册：检查用户名唯一性，生成密码哈希，创建用户记录
- 当前用户：从 JWT 提取用户 ID，查询用户并校验启用状态
- 权限：管理员（admin）与经理（manager）具备更高操作权限
角色与权限
- User.role 控制资源访问范围
- 路由层通过依赖注入校验当前用户角色与状态

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 : 用户信息

图表来源

章节来源

菜单与权限管理

菜单模型
- 支持菜单/按钮两类，父子自引用，排序与可见性控制
- 菜单树查询：仅返回顶层、可见且启用的菜单，并递归加载子节点
权限控制
- 菜单权限标识（permission）用于前端路由鉴权
- 菜单管理 API 通过角色依赖限制创建/更新/删除操作
初始化
- 支持初始化默认菜单，避免重复初始化

flowchart TD
Start(["获取菜单树"]) --> BuildQuery["构建查询: 顶层菜单<br/>可见且启用"]
BuildQuery --> LoadChildren["加载子节点关系"]
LoadChildren --> OrderBy["按排序与ID排序"]
OrderBy --> ToDict["_menu_to_dict 递归转字典"]
ToDict --> End(["返回菜单树"])

图表来源

章节来源

指标模板系统

模板类型
- 通用模板、手术临床、非手术有病房、非手术无病房、医技、护理、行政、后勤
维度权重
- 模板可配置 BSC 四维度权重（JSON 字符串），用于汇总计算
考核周期
- 支持月度/年度等周期配置
列表与详情
- 支持按类型与启用状态筛选，返回模板指标数量
- 详情包含模板基本信息与完整指标列表（含指标名称、编码、类型、维度、权重、排序等）

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 : "关联"

图表来源

章节来源

模板与指标的关联关系

关联表 TemplateIndicator
- 唯一约束：同一模板下指标唯一
- 排序字段 sort_order 决定展示顺序
- 支持批量添加，自动补齐排序
权重与排序机制
- 模板层与指标层均支持权重配置
- 汇总时需遵循维度权重与指标权重的乘积规则（由上层业务逻辑决定）
激活状态管理
- 模板与指标均可启用/停用，影响使用范围与计算

章节来源

用户与员工的关联关系

User 与 Staff
- User.staff_id 外键关联 Staff.id，表示系统用户与员工的绑定关系
- 便于登录后获取员工信息与权限边界
员工状态与部门
- Staff.status 与 Department.parent_id/level 等字段共同构成组织与人员管理基础

章节来源

菜单层级结构

自引用关系
- Menu.parent_id → Menu.id，支持任意层级
- 服务层通过 selectinload 预加载 children，避免 N+1 查询
树形渲染
- 顶层查询（parent_id IS NULL），按 sort_order 与 id 排序
- 递归转换为字典树，供前端渲染

章节来源

模板类型分类逻辑

TemplateType 枚举覆盖全院主要科室类型，便于按类型匹配模板
服务层提供类型标签映射，便于前端展示

章节来源

权重与排序机制

指标层权重
- Indicator.weight 与 TemplateIndicator.weight 双层权重
- 数据库层对指标权重设置正数约束
排序
- TemplateIndicator.sort_order 决定模板内指标顺序
- 批量添加时可按传入顺序补齐排序

章节来源

激活状态管理

模板与菜单均提供 is_active 字段
菜单树查询默认仅返回启用项
模板列表支持按 is_active 过滤

章节来源

依赖分析

模型依赖
- User ←→ Staff（一对一外键）
- Menu ←→ Menu（自引用）
- IndicatorTemplate → TemplateIndicator → Indicator（多对一）
服务依赖
- MenuService 依赖 Menu 模型
- TemplateService 依赖 IndicatorTemplate、TemplateIndicator、Indicator 模型
API 依赖
- auth 路由依赖 Security 与 User 模型
- menus 路由依赖 MenuService 与 Menu 模型
- templates 路由依赖 TemplateService 与模板相关 Schema

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

图表来源

性能考虑

查询优化
- 使用 selectinload 预加载关系，减少 N+1 查询
- 菜单树查询限定顶层、可见与启用条件
索引策略
- 模型层为常用过滤字段建立索引（如模板类型、菜单可见性、指标权重约束）
分页与排序
- 模板列表支持分页与排序，避免一次性加载过多数据
缓存与并发
- 配置层提供数据库连接池参数，建议在生产环境按负载调优

章节来源

故障排查指南

登录失败
- 检查用户名是否存在、密码是否正确、用户是否启用
- 查看安全模块的凭据验证与令牌生成流程
菜单不可见
- 确认菜单 is_visible 与 is_active 状态
- 检查菜单树查询是否仅返回可见启用项
模板操作失败
- 检查模板编码唯一性、模板与指标是否存在、唯一约束冲突
- 确认排序字段是否正确传递
权限不足
- 确认当前用户角色（admin/manager/staff）
- 检查路由依赖是否正确应用

章节来源

结论

本系统基础模型围绕 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

权限控制机制

当前用户获取与校验
- 从 JWT 解析用户 ID，查询用户并校验启用状态
角色权限
- 管理员（admin）：最高权限
- 经理（manager）：部分管理操作
- 普通员工（staff）：受限操作

章节来源

backend/app/core/security.py

模板管理最佳实践

模板类型选择
- 根据科室类型选择对应模板，避免跨类型混用
维度权重设计
- 明确财务/客户/内部流程/学习与成长的权重范围与合计
指标权重与排序
- 指标层权重与模板层权重协同，排序字段保持连续与稳定
激活状态
- 新建模板先启用少量指标进行测试，逐步放开

章节来源

18 KiB Raw Blame History Unescape Escape

系统基础模型

目录

简介

项目结构

核心组件

架构总览

详细组件分析

用户与认证授权

菜单与权限管理

指标模板系统

模板与指标的关联关系

用户与员工的关联关系

菜单层级结构

模板类型分类逻辑

权重与排序机制

激活状态管理

依赖分析

性能考虑

故障排查指南

结论

附录

系统配置示例

权限控制机制

模板管理最佳实践

18 KiB

Raw Blame History