chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交文件

Browse Source
This commit is contained in:
chenqi
2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

599
.qoder/repowiki/zh/content/数据库设计/数据字典/基础数据字段.md Normal file
View File

@@ -0,0 +1,599 @@
# 基础数据字段
<cite>
**本文引用的文件**
- [models.py](file://backend/app/models/models.py)
- [finance.py](file://backend/app/models/finance.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [database.md](file://docs/database.md)
- [departments.py](file://backend/app/api/v1/departments.py)
- [staff.py](file://backend/app/api/v1/staff.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件聚焦于基础数据字段的详细数据字典，覆盖以下核心表：
- 科室信息表（Department）
- 员工信息表（Staff）
- 用户表（User）
同时补充与基础数据强相关的财务记录表（DepartmentFinance）字段说明，以及与字段相关的枚举类型、索引设计、约束与业务规则。文档提供字段定义、类型与长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、字段间关联关系与外键约束、索引设计与性能考虑，并给出实际使用示例与最佳实践建议。
## 项目结构
本项目采用前后端分离架构，后端基于 FastAPI + SQLAlchemy ORM，数据库迁移使用 Alembic。基础数据模型集中在 models 模块，API 路由位于 app/api/v1 下，数据字典与 ER 图见 docs/database.md。
```mermaid
graph TB
subgraph "后端"
A["models.py<br/>数据模型"]
B["finance.py<br/>财务模型"]
C["schemas.py<br/>Pydantic模式"]
D["alembic 迁移<br/>001_initial.py / 002_template.py"]
E["API 路由<br/>departments.py / staff.py"]
end
subgraph "文档"
F["docs/database.md<br/>ER图与字段说明"]
end
A --> D
B --> D
C --> E
E --> A
F --> A
```
图表来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L149)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
- [departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
章节来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L149)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
- [database.md](file://docs/database.md#L97-L232)
- [departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
## 核心组件
- 科室信息表（Department）
- 员工信息表（Staff）
- 用户表（User）
- 科室财务记录表（DepartmentFinance）
章节来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [models.py](file://backend/app/models/models.py#L244-L261)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
## 架构总览
基础数据字段与业务流程的关系如下：
- Department 与 Staff 为 1:N 关系（部门-员工）
- Staff 与 User 为 N:1 关系（员工-用户）
- DepartmentFinance 与 Department 为 1:N 关系（科室-财务记录）
```mermaid
erDiagram
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
boolean is_active
text description
datetime created_at
datetime updated_at
}
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
decimal base_salary
decimal performance_ratio
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
USERS {
int id PK
string username UK
string password_hash
int staff_id FK
string role
boolean is_active
datetime last_login
datetime created_at
datetime updated_at
}
DEPARTMENT_FINANCES {
int id PK
int department_id FK
int period_year
int period_month
enum finance_type
string category
decimal amount
string source
text remark
datetime created_at
datetime updated_at
}
DEPARTMENTS ||--o{ STAFF : "1:N"
STAFF ||--o{ USERS : "N:1"
DEPARTMENTS ||--o{ DEPARTMENT_FINANCES : "1:N"
```
图表来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [models.py](file://backend/app/models/models.py#L244-L261)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
## 详细组件分析
### 科室信息表（Department）
- 表名：departments
- 主键：id（自增整数）
- 唯一键：code（唯一）
- 外键：parent_id 引用 departments.id（自关联，表示上级科室）
- 索引：idx_dept_type、idx_dept_parent
- 枚举：dept_type（来自 DeptType）
字段定义与规则
- id
- 类型：整数（主键）
- 约束：自增、非空
- 默认值：无
- 业务含义：科室唯一标识
- 取值范围：正整数
- 注释：主键
- 关联关系：parent_id 自关联指向自身
- 索引：PK
- name
- 类型：字符串（最大长度 100）
- 约束：非空
- 默认值：无
- 业务含义：科室名称
- 取值范围：长度不超过 100
- 注释：科室名称
- code
- 类型：字符串（最大长度 20）
- 约束：唯一、非空
- 默认值：无
- 业务含义：科室编码（全局唯一）
- 取值范围：长度不超过 20
- 注释：科室编码
- 索引：UK
- dept_type
- 类型：枚举（DeptType）
- 约束：非空
- 默认值：无
- 业务含义：科室类型
- 取值范围：clinical_surgical、clinical_nonsurgical_ward、clinical_nonsurgical_noward、medical_tech、medical_auxiliary、nursing、admin、finance、logistics
- 注释：科室类型
- 索引：idx_dept_type
- parent_id
- 类型：整数
- 约束：可空，外键引用 departments.id
- 默认值：空
- 业务含义：上级科室 ID（自关联）
- 取值范围：对应存在的 id 或空
- 注释：上级科室
- 索引：idx_dept_parent
- level
- 类型：整数
- 约束：默认 1
- 默认值：1
- 业务含义：层级（1-5）
- 取值范围：1-5
- 注释：层级
- sort_order
- 类型：整数
- 约束：默认 0
- 默认值：0
- 业务含义：排序
- 注释：排序
- is_active
- 类型：布尔
- 约束：默认 true
- 默认值：true
- 业务含义：是否启用
- 注释：是否启用
- description
- 类型：文本
- 约束：可空
- 默认值：空
- 业务含义：描述
- 注释：描述
- created_at / updated_at
- 类型：日期时间
- 约束：默认当前时间；更新时自动更新
- 默认值：无
- 业务含义：创建/更新时间
- 注释：创建时间、更新时间
业务规则与最佳实践
- 编码唯一性：code 必须全局唯一，新增前需校验重复
- 层级与排序：level 与 sort_order 用于树形展示与排序
- 自关联：parent_id 支持多级组织架构，查询时注意避免环路
- 索引：dept_type 与 parent_id 建议在过滤与树形查询中使用
章节来源
- [models.py](file://backend/app/models/models.py#L62-L86)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
- [database.md](file://docs/database.md#L99-L116)
### 员工信息表（Staff）
- 表名：staff
- 主键：id（自增整数）
- 唯一键：employee_id（唯一）
- 外键：department_id 引用 departments.id
- 索引：idx_staff_dept、idx_staff_status
- 枚举：status（来自 StaffStatus）
字段定义与规则
- id
- 类型：整数（主键）
- 约束：自增、非空
- 默认值：无
- 业务含义：员工唯一标识
- 注释：主键
- employee_id
- 类型：字符串（最大长度 20）
- 约束：唯一、非空
- 默认值：无
- 业务含义：工号（唯一）
- 取值范围：长度不超过 20
- 注释：工号
- 索引：UK
- name
- 类型：字符串（最大长度 50）
- 约束：非空
- 默认值：无
- 业务含义：姓名
- 取值范围：长度不超过 50
- 注释：姓名
- department_id
- 类型：整数
- 约束：非空，外键引用 departments.id
- 默认值：无
- 业务含义：所属科室
- 注释：所属科室
- 索引：idx_staff_dept
- position
- 类型：字符串（最大长度 50）
- 约束：非空
- 默认值：无
- 业务含义：职位
- 取值范围：长度不超过 50
- 注释：职位
- title
- 类型：字符串（最大长度 50）
- 约束：可空
- 默认值：空
- 业务含义：职称
- 注释：职称
- phone
- 类型：字符串（最大长度 20）
- 约束：可空
- 默认值：空
- 业务含义：联系电话
- 注释：联系电话
- email
- 类型：字符串（最大长度 100）
- 约束：可空
- 默认值：空
- 业务含义：邮箱
- 注释：邮箱
- base_salary
- 类型：数值（精度 10，小数 2）
- 约束：默认 0
- 默认值：0
- 业务含义：基本工资
- 取值范围：≥0
- 注释：基本工资
- performance_ratio
- 类型：数值（精度 5，小数 2）
- 约束：默认 1.0
- 默认值：1.0
- 业务含义：绩效系数（0-5）
- 取值范围：0-5
- 注释：绩效系数
- status
- 类型：枚举（StaffStatus）
- 约束：默认 active
- 默认值：active
- 业务含义：员工状态
- 取值范围：active、leave、resigned、retired
- 注释：状态
- 索引：idx_staff_status
- hire_date
- 类型：日期时间
- 约束：可空
- 默认值：空
- 业务含义：入职日期
- 注释：入职日期
- created_at / updated_at
- 类型：日期时间
- 约束：默认当前时间；更新时自动更新
- 默认值：无
- 业务含义：创建/更新时间
- 注释：创建时间、更新时间
业务规则与最佳实践
- 工号唯一性：employee_id 必须唯一，新增前需校验重复
- 状态枚举：仅允许枚举值，避免脏数据
- 薪资与系数：base_salary 与 performance_ratio 用于后续绩效工资计算
- 索引：department_id 与 status 用于筛选与分页
章节来源
- [models.py](file://backend/app/models/models.py#L88-L114)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
- [database.md](file://docs/database.md#L117-L136)
### 用户表（User）
- 表名：users
- 主键：id（自增整数）
- 唯一键：username（唯一）
- 外键：staff_id 引用 staff.id
- 索引：idx_user_username
字段定义与规则
- id
- 类型：整数（主键）
- 约束：自增、非空
- 默认值：无
- 业务含义：用户唯一标识
- 注释：主键
- username
- 类型：字符串（最大长度 50）
- 约束：唯一、非空
- 默认值：无
- 业务含义：用户名
- 取值范围：长度不超过 50
- 注释：用户名
- 索引：UK
- password_hash
- 类型：字符串（最大长度 255）
- 约束：非空
- 默认值：无
- 业务含义：密码哈希
- 注释：密码哈希
- staff_id
- 类型：整数
- 约束：可空，外键引用 staff.id
- 默认值：空
- 业务含义：关联员工
- 注释：关联员工
- role
- 类型：字符串（最大长度 20）
- 约束：默认 staff
- 默认值：staff
- 业务含义：角色
- 取值范围：admin、manager、staff
- 注释：角色
- is_active
- 类型：布尔
- 约束：默认 true
- 默认值：true
- 业务含义：是否启用
- 注释：是否启用
- last_login
- 类型：日期时间
- 约束：可空
- 默认值：空
- 业务含义：最后登录时间
- 注释：最后登录
- created_at / updated_at
- 类型：日期时间
- 约束：默认当前时间；更新时自动更新
- 默认值：无
- 业务含义：创建/更新时间
- 注释：创建时间、更新时间
业务规则与最佳实践
- 用户名唯一性：username 必须唯一
- 角色枚举：仅允许 admin、manager、staff
- 关联员工：staff_id 可空，表示未绑定员工的系统用户
- 登录追踪：last_login 用于审计与安全策略
章节来源
- [models.py](file://backend/app/models/models.py#L244-L261)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L156-L172)
- [schemas.py](file://backend/app/schemas/schemas.py#L314-L345)
- [database.md](file://docs/database.md#L218-L232)
### 科室财务记录表（DepartmentFinance）
- 表名：department_finances
- 主键：id（自增整数）
- 外键：department_id 引用 departments.id
- 索引：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category
- 枚举：finance_type（来自 FinanceType）
- 约束：amount ≥ 0
字段定义与规则
- id
- 类型：整数（主键）
- 约束：自增、非空
- 默认值：无
- 业务含义：财务记录唯一标识
- 注释：主键
- department_id
- 类型：整数
- 约束：非空，外键引用 departments.id
- 默认值：无
- 业务含义：所属科室
- 注释：科室ID
- 索引：idx_finance_dept
- period_year / period_month
- 类型：整数
- 约束：非空
- 默认值：无
- 业务含义：年度/月份
- 注释：年度、月份
- 索引：idx_finance_period
- finance_type
- 类型：枚举（FinanceType）
- 约束：非空
- 默认值：无
- 业务含义：财务类型（收入/支出）
- 取值范围：revenue、expense
- 注释：财务类型
- 索引：idx_finance_type
- category
- 类型：字符串（最大长度 50）
- 约束：非空
- 默认值：无
- 业务含义：类别（如检查费、床位费等）
- 取值范围：长度不超过 50
- 注释：类别
- 索引：idx_finance_category
- amount
- 类型：数值（精度 12，小数 2）
- 约束：默认 0，且 ≥ 0
- 默认值：0
- 业务含义：金额
- 取值范围：≥0
- 注释：金额
- 约束：check(amount >= 0)
- source
- 类型：字符串（最大长度 100）
- 约束：可空
- 默认值：空
- 业务含义：数据来源
- 注释：数据来源
- remark
- 类型：文本
- 约束：可空
- 默认值：空
- 业务含义：备注
- 注释：备注
- created_at / updated_at
- 类型：日期时间
- 约束：默认当前时间；更新时自动更新
- 默认值：无
- 业务含义：创建/更新时间
- 注释：创建时间、更新时间
业务规则与最佳实践
- 金额非负：通过约束保证 amount ≥ 0
- 类别与类型：category 与 finance_type 组合用于财务归类与统计
- 周期聚合：period_year 与 period_month 用于月度/年度汇总
章节来源
- [finance.py](file://backend/app/models/finance.py#L45-L74)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
## 依赖分析
- Department 与 Staff 的关系：1:N（部门-员工），通过 department_id 外键关联
- Staff 与 User 的关系：N:1（员工-用户），通过 staff_id 外键关联
- Department 与 DepartmentFinance 的关系：1:N（科室-财务记录），通过 department_id 外键关联
```mermaid
graph LR
DEPT["Department"] --> |FK| STAFF["Staff"]
STAFF --> |FK| USER["User"]
DEPT --> |FK| FIN["DepartmentFinance"]
```
图表来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [models.py](file://backend/app/models/models.py#L244-L261)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
章节来源
- [models.py](file://backend/app/models/models.py#L62-L114)
- [models.py](file://backend/app/models/models.py#L244-L261)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
## 性能考量
- 索引设计
- Department：idx_dept_type、idx_dept_parent，适合按类型过滤与树形查询
- Staff：idx_staff_dept、idx_staff_status，适合按科室与状态筛选
- Assessments：idx_assessment_staff、idx_assessment_period、idx_assessment_status，适合按员工、周期与状态查询
- SalaryRecords：idx_salary_staff、idx_salary_period，适合按员工与周期查询
- Users：idx_user_username，适合按用户名登录
- DepartmentFinance：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category，适合财务统计与聚合
- 约束与校验
- Staff.performance_ratio 与 Indicator.weight 使用 Pydantic 校验（ge/le），数据库层使用 CheckConstraint（如 DepartmentFinance.amount ≥ 0）
- 查询建议
- 分页与过滤：优先使用带索引的列进行 where 条件与 order by
- 树形查询：Department.parent_id + level 用于层级展示
- 聚合统计：DepartmentFinance 按 period_year/month + category + type 聚合
章节来源
- [models.py](file://backend/app/models/models.py#L82-L86)
- [models.py](file://backend/app/models/models.py#L111-L114)
- [models.py](file://backend/app/models/models.py#L174-L178)
- [models.py](file://backend/app/models/models.py#L227-L230)
- [models.py](file://backend/app/models/models.py#L258-L260)
- [finance.py](file://backend/app/models/finance.py#L68-L74)
- [schemas.py](file://backend/app/schemas/schemas.py#L117-L136)
- [schemas.py](file://backend/app/schemas/schemas.py#L158-L176)
## 故障排查指南
- 新增科室失败（编码重复）
- 现象：创建接口返回错误，提示编码已存在
- 排查：检查 departments.code 是否唯一；确认是否已有相同编码
- 处理：修改编码或删除冲突记录
- 新增员工失败（工号重复）
- 现象：创建接口返回错误，提示工号已存在
- 排查：检查 staff.employee_id 是否唯一
- 处理：修改工号或删除冲突记录
- 删除科室失败（存在子科室）
- 现象：删除接口返回错误，提示无法删除
- 排查：确认该科室是否存在子科室（parent_id 指向该 id）
- 处理：先删除子科室或调整组织架构
- 薪资/财务金额异常
- 现象：DepartmentFinance.amount 出现负值
- 排查：检查数据来源与业务逻辑；确认约束是否生效
- 处理：修正数据或调整业务流程
章节来源
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [departments.py](file://backend/app/api/v1/departments.py#L104-L106)
- [finance.py](file://backend/app/models/finance.py#L73-L74)
## 结论
本文档对基础数据字段进行了系统梳理，明确了字段类型、长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、外键关系与索引设计，并提供了性能考量与故障排查建议。遵循这些字段规范与最佳实践，有助于确保数据一致性、查询性能与业务稳定性。
## 附录
- 字段使用示例（示意）
- 新增科室：提供 name、code、dept_type、parent_id、level、sort_order、is_active、description
- 新增员工：提供 employee_id、name、department_id、position、title、phone、email、base_salary、performance_ratio、status、hire_date
- 新增用户：提供 username、password_hash、staff_id、role、is_active、last_login
- 新增财务记录：提供 department_id、finance_type、category、amount、period_year、period_month、source、remark
- 最佳实践
- 唯一性：严格维护 code 与 employee_id 的唯一性
- 枚举：统一使用模型中定义的枚举类型，避免拼写差异
- 索引：在高频查询列上保持索引，定期评估查询计划
- 校验：前端与后端双重校验，确保数据质量

473
.qoder/repowiki/zh/content/数据库设计/数据字典/指标模板字段.md Normal file
View File

@@ -0,0 +1,473 @@
# 指标模板字段
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [templates.py](file://backend/app/api/v1/templates.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [init_templates.py](file://backend/app/scripts/init_templates.py)
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [template.js](file://frontend/src/api/template.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
## 简介
本文件聚焦于指标模板相关字段的数据字典，覆盖以下核心实体与关系：
- 指标模板表（IndicatorTemplate）
- 模板指标关联表（TemplateIndicator）
- 模板类型枚举（TemplateType）
- 指标与模板的多对多关联关系
- 维度权重配置与指标分类管理
- 模板版本管理与继承关系设计
- 激活状态与使用范围约束
本文件同时提供字段定义、约束说明、数据流向与前后端交互示例，帮助开发者与运维人员快速理解与使用模板系统。
## 项目结构
模板系统由后端模型与服务、API路由、前端页面与接口组成，形成“模型-服务-接口-视图”的完整链路。
```mermaid
graph TB
subgraph "后端"
M["models.py<br/>数据模型"]
S["template_service.py<br/>服务层"]
A["templates.py<br/>API路由"]
SC["schemas.py<br/>Pydantic模式"]
ALEMBIC["002_template.py<br/>迁移脚本"]
end
subgraph "前端"
V["Templates.vue<br/>模板管理页面"]
API["template.js<br/>模板API封装"]
end
V --> API
API --> A
A --> S
S --> M
M --> ALEMBIC
SC --> A
```
图表来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [template.js](file://frontend/src/api/template.js#L1-L62)
章节来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [template.js](file://frontend/src/api/template.js#L1-L62)
## 核心组件
- 指标模板表（IndicatorTemplate）
- 字段：id、template_name、template_code、template_type、description、dimension_weights、assessment_cycle、is_active、created_at、updated_at
- 关系：与模板指标关联表一对多
- 约束：唯一索引（template_code）、索引（template_type、is_active）
- 模板指标关联表（TemplateIndicator）
- 字段：id、template_id、indicator_id、category、target_value、target_unit、weight、scoring_method、scoring_params、sort_order、remark、created_at、updated_at
- 关系：与模板表、指标表多对一
- 约束：唯一索引（template_id, indicator_id）、索引（template_id、indicator_id）
- 模板类型枚举（TemplateType）
- 类型：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics
- 指标表（Indicator）
- 字段：id、name、code、indicator_type、bs_dimension、weight、max_score、target_value、target_unit、calculation_method、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto、is_active、created_at、updated_at
- 约束：CheckConstraint(weight > 0)
章节来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [models.py](file://backend/app/models/models.py#L117-L147)
- [models.py](file://backend/app/models/models.py#L375-L385)
## 架构总览
模板系统采用“模板-指标”多对多关系，通过模板指标关联表实现灵活配置。模板类型决定适用科室范围，维度权重用于汇总计算，指标分类用于二级归类，权重与评分方法用于最终得分计算。
```mermaid
erDiagram
INDICATOR_TEMPLATE {
int id PK
string template_name
string template_code UK
string template_type
text description
text dimension_weights
string assessment_cycle
boolean is_active
datetime created_at
datetime updated_at
}
TEMPLATE_INDICATOR {
int id PK
int template_id FK
int indicator_id FK
string category
numeric target_value
string target_unit
numeric weight
string scoring_method
text scoring_params
int sort_order
text remark
datetime created_at
datetime updated_at
}
INDICATOR {
int id PK
string name
string code UK
string indicator_type
string bs_dimension
numeric weight
numeric max_score
numeric target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
text applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
INDICATOR_TEMPLATE ||--o{ TEMPLATE_INDICATOR : "包含"
INDICATOR ||--o{ TEMPLATE_INDICATOR : "被包含"
```
图表来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [models.py](file://backend/app/models/models.py#L117-L147)
## 详细组件分析
### 指标模板表（IndicatorTemplate）字段字典
- id
- 类型：整数
- 主键：是
- 描述：模板主键
- 约束：自增
- 章节来源
- [models.py](file://backend/app/models/models.py#L391-L391)
- template_name
- 类型：字符串（最大长度200）
- 描述：模板名称
- 章节来源
- [models.py](file://backend/app/models/models.py#L392-L392)
- [schemas.py](file://backend/app/schemas/schemas.py#L699-L700)
- template_code
- 类型：字符串（最大长度50）
- 描述：模板编码（唯一）
- 约束：唯一索引
- 章节来源
- [models.py](file://backend/app/models/models.py#L393-L393)
- [002_template.py](file://backend/alembic/versions/002_template.py#L27-L36)
- [schemas.py](file://backend/app/schemas/schemas.py#L700-L701)
- template_type
- 类型：枚举（TemplateType）
- 描述：模板类型
- 取值：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics
- 章节来源
- [models.py](file://backend/app/models/models.py#L394-L394)
- [schemas.py](file://backend/app/schemas/schemas.py#L702-L702)
- [002_template.py](file://backend/alembic/versions/002_template.py#L28-L28)
- description
- 类型：文本
- 描述：模板描述
- 章节来源
- [models.py](file://backend/app/models/models.py#L395-L395)
- [schemas.py](file://backend/app/schemas/schemas.py#L703-L703)
- dimension_weights
- 类型：文本（JSON）
- 描述：维度权重配置（财务、客户、内部流程、学习与成长）
- 示例：{"financial": 35, "customer": 30, "internal_process": 25, "learning_growth": 10}
- 章节来源
- [models.py](file://backend/app/models/models.py#L396-L396)
- [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)
- assessment_cycle
- 类型：字符串（最大长度20）
- 描述：考核周期（monthly/quarterly/annual）
- 默认值：monthly
- 章节来源
- [models.py](file://backend/app/models/models.py#L397-L397)
- [schemas.py](file://backend/app/schemas/schemas.py#L705-L705)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L89-L89)
- is_active
- 类型：布尔
- 描述：是否启用
- 默认值：true
- 章节来源
- [models.py](file://backend/app/models/models.py#L398-L398)
- [schemas.py](file://backend/app/schemas/schemas.py#L728-L728)
- [002_template.py](file://backend/alembic/versions/002_template.py#L32-L32)
- created_at/updated_at
- 类型：日期时间
- 描述：创建与更新时间
- 章节来源
- [models.py](file://backend/app/models/models.py#L399-L400)
- [models.py](file://backend/app/models/models.py#L400-L400)
- 关系与索引
- 关系：与模板指标关联表一对多
- 索引：template_type、is_active
- 章节来源
- [models.py](file://backend/app/models/models.py#L402-L408)
- [002_template.py](file://backend/alembic/versions/002_template.py#L38-L39)
### 模板指标关联表（TemplateIndicator）字段字典
- id
- 类型：整数
- 主键：是
- 描述：模板指标关联主键
- 章节来源
- [models.py](file://backend/app/models/models.py#L415-L415)
- template_id
- 类型：整数
- 外键：指向 indicator_templates.id
- 描述：模板ID
- 章节来源
- [models.py](file://backend/app/models/models.py#L416-L416)
- [002_template.py](file://backend/alembic/versions/002_template.py#L45-L57)
- indicator_id
- 类型：整数
- 外键：指向 indicators.id
- 描述：指标ID
- 章节来源
- [models.py](file://backend/app/models/models.py#L417-L417)
- [002_template.py](file://backend/alembic/versions/002_template.py#L46-L57)
- category
- 类型：字符串（最大长度100）
- 描述：指标分类（二级指标分类）
- 示例：收支管理、患者满意度、质量与安全
- 章节来源
- [models.py](file://backend/app/models/models.py#L418-L418)
- [schemas.py](file://backend/app/schemas/schemas.py#L657-L657)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)
- target_value/target_unit
- 类型：数值/字符串
- 描述：目标值与单位
- 章节来源
- [models.py](file://backend/app/models/models.py#L419-L420)
- [schemas.py](file://backend/app/schemas/schemas.py#L658-L659)
- weight
- 类型：数值（默认1.0）
- 描述：在模板内的权重
- 章节来源
- [models.py](file://backend/app/models/models.py#L421-L421)
- [schemas.py](file://backend/app/schemas/schemas.py#L660-L660)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L91-L107)
- scoring_method/scoring_params
- 类型：字符串/文本
- 描述：评分方法与参数（JSON）
- 方法：range、target、deduction、bonus、veto
- 章节来源
- [models.py](file://backend/app/models/models.py#L422-L423)
- [schemas.py](file://backend/app/schemas/schemas.py#L661-L662)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L211-L217)
- sort_order
- 类型：整数
- 描述：排序
- 默认值：0
- 章节来源
- [models.py](file://backend/app/models/models.py#L424-L424)
- [template_service.py](file://backend/app/services/template_service.py#L191-L202)
- remark
- 类型：文本
- 描述：备注
- 章节来源
- [models.py](file://backend/app/models/models.py#L425-L425)
- created_at/updated_at
- 类型：日期时间
- 描述：创建与更新时间
- 章节来源
- [models.py](file://backend/app/models/models.py#L426-L427)
- 关系与索引
- 关系：与模板表、指标表多对一
- 索引：template_id、indicator_id、(template_id, indicator_id)唯一
- 章节来源
- [models.py](file://backend/app/models/models.py#L429-L437)
- [002_template.py](file://backend/alembic/versions/002_template.py#L61-L63)
### 模板类型枚举（TemplateType）
- 取值与含义
- general：通用模板
- surgical：手术临床科室
- nonsurgical_ward：非手术有病房科室
- nonsurgical_noward：非手术无病房科室
- medical_tech：医技科室
- nursing：护理单元
- admin：行政科室
- logistics：后勤科室
- 使用场景
- 用于区分模板适用科室类型，配合指标的适用科室类型字段实现过滤
- 章节来源
- [models.py](file://backend/app/models/models.py#L375-L385)
- [schemas.py](file://backend/app/schemas/schemas.py#L642-L652)
### 指标分类管理与维度权重配置
- 指标分类（category）
- 作用：对模板内的指标进行二级分类，便于统计与展示
- 示例：收支管理、患者满意度、质量与安全、内部服务效率等
- 章节来源
- [models.py](file://backend/app/models/models.py#L418-L418)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)
- 维度权重（dimension_weights）
- 结构：JSON对象，键为维度标识，值为百分比
- 维度：financial、customer、internal_process、learning_growth
- 用途：用于模板层面的维度汇总与权重分配
- 章节来源
- [models.py](file://backend/app/models/models.py#L396-L396)
- [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)
- 指标维度（bs_dimension）
- 作用：指标所属的平衡计分卡维度，与模板维度权重协同使用
- 章节来源
- [models.py](file://backend/app/models/models.py#L125-L125)
- [init_templates.py](file://backend/init_indicator_templates.py#L28-L38)
### 模板与指标的多对多关联与权重分配机制
- 关联关系
- 通过 TemplateIndicator 实现模板与指标的多对多绑定
- 每个模板内的指标可独立设置权重、目标值、评分方法等
- 权重分配
- 模板维度权重：用于模板层面的维度汇总
- 指标权重：用于模板内指标的加权计算
- 章节来源
- [models.py](file://backend/app/models/models.py#L411-L431)
- [template_service.py](file://backend/app/services/template_service.py#L110-L124)
### 模板版本管理与继承关系
- 版本字段
- 当前模型未内置版本字段；如需版本管理，可在模板表中扩展 version 字段
- 继承关系
- 可通过模板类型与指标适用科室类型实现“继承”效果：通用模板可作为特定模板的父模板，再叠加差异字段
- 章节来源
- [models.py](file://backend/app/models/models.py#L391-L400)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
### 激活状态与使用范围约束
- 激活状态（is_active）
- 控制模板是否可用
- 前端通过开关切换，后端接口支持批量更新
- 使用范围
- 模板类型（template_type）限定适用科室类型
- 指标的适用科室类型（applicable_dept_types）进一步限制
- 章节来源
- [models.py](file://backend/app/models/models.py#L398-L398)
- [models.py](file://backend/app/models/models.py#L134-L134)
- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
## 依赖分析
模板系统的关键依赖关系如下：
```mermaid
graph LR
ENUM["TemplateType 枚举"] --> IT["IndicatorTemplate 模型"]
IT --> TI["TemplateIndicator 模型"]
IND["Indicator 模型"] --> TI
SVC["TemplateService 服务"] --> IT
SVC --> TI
API["templates.py 路由"] --> SVC
SCHEMA["schemas.py 模式"] --> API
FRONT["Templates.vue 页面"] --> API
API --> FRONT
```
图表来源
- [models.py](file://backend/app/models/models.py#L375-L385)
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
章节来源
- [models.py](file://backend/app/models/models.py#L375-L385)
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
## 性能考虑
- 查询优化
- 模板列表按 template_type 与 is_active 进行过滤，建议保持索引有效
- 模板详情加载时使用 selectinload 预加载关联指标，避免 N+1 查询
- 写入优化
- 批量添加模板指标时，服务层会自动设置排序，减少重复计算
- 前端渲染
- 前端对维度权重进行 JSON 解析与可视化展示，注意空值处理与错误捕获
## 故障排查指南
- 模板编码冲突
- 现象：创建模板时报错“模板编码已存在”
- 排查：检查唯一索引约束与迁移脚本
- 章节来源
- [templates.py](file://backend/app/api/v1/templates.py#L136-L139)
- [002_template.py](file://backend/alembic/versions/002_template.py#L36-L36)
- 指标重复添加
- 现象：添加模板指标返回失败
- 排查：检查唯一索引（template_id, indicator_id）
- 章节来源
- [template_service.py](file://backend/app/services/template_service.py#L174-L182)
- [002_template.py](file://backend/alembic/versions/002_template.py#L63-L63)
- 维度权重解析失败
- 现象：前端维度权重显示异常
- 排查：确认 JSON 格式正确，服务端/前端均做容错处理
- 章节来源
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L310-L317)
- 指标权重校验
- 现象：指标权重小于等于0导致异常
- 排查：数据库层有 CheckConstraint，前端也应限制输入范围
- 章节来源
- [models.py](file://backend/app/models/models.py#L145-L145)
- [schemas.py](file://backend/app/schemas/schemas.py#L158-L158)
## 结论
指标模板系统通过清晰的模型设计与严格的约束，实现了模板类型、维度权重、指标分类与权重分配的灵活配置。模板与指标的多对多关系通过关联表实现解耦，支持按科室类型与适用范围进行精细化管理。建议后续在模板表中增加版本字段以完善版本管理能力，并在前端增强对 JSON 参数的校验与提示，提升系统的稳定性与易用性。

596
.qoder/repowiki/zh/content/数据库设计/数据字典/数据字典.md Normal file
View File

@@ -0,0 +1,596 @@
# 数据字典
<cite>
**本文档引用的文件**
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/models/finance.py](file://backend/app/models/finance.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
- [docs/database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本数据字典面向医院绩效管理系统，系统围绕“科室—员工—考核—工资—财务”主线构建，涵盖指标管理、计划管理、模板管理、财务核算等模块。本文档从字段层面梳理每个实体的数据定义（业务含义、数据类型、长度/精度限制、取值范围、默认值），明确枚举类型及其使用场景，阐述字段与业务实体的对应关系，给出数据流转过程，并提供维护更新规范与查询使用指南。
## 项目结构
系统采用前后端分离架构，后端基于FastAPI + SQLAlchemy，采用分层设计（API → Service → Model），前端Vue3 + Vite。数据库采用SQLite（开发环境），通过Alembic进行版本化迁移。
```mermaid
graph TB
FE["前端界面<br/>Vue3 + Vite"] --> API["后端API<br/>FastAPI"]
API --> SVC["服务层<br/>各模块Service"]
SVC --> MODELS["模型层<br/>SQLAlchemy ORM"]
MODELS --> DB["数据库<br/>SQLite"]
```
图表来源
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
章节来源
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
## 核心组件
- 数据模型层：定义实体、字段、约束、索引、枚举类型
- 模式层（Pydantic）：定义API输入输出结构、字段校验规则
- API层：定义REST接口、参数、返回结构
- 服务层：封装业务逻辑、事务处理、数据聚合
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 架构概览
系统围绕“绩效考核—工资核算—财务分析”的主流程展开，指标与模板驱动考核，考核结果驱动工资生成，财务模块提供收支与结余分析。
```mermaid
graph TB
subgraph "基础数据"
DEPT["科室表<br/>departments"]
STAFF["员工表<br/>staff"]
USERS["用户表<br/>users"]
end
subgraph "指标与计划"
IND["指标表<br/>indicators"]
TPL["模板表<br/>indicator_templates"]
TIND["模板指标关联<br/>template_indicators"]
PLAN["绩效计划表<br/>performance_plans"]
REL["计划指标关联<br/>plan_kpi_relations"]
end
subgraph "考核与工资"
ASSESS["考核记录表<br/>assessments"]
DETAIL["考核明细表<br/>assessment_details"]
SAL["工资记录表<br/>salary_records"]
end
subgraph "财务"
FIN["科室财务记录<br/>department_finances"]
end
DEPT <-- "1:N" --> STAFF
STAFF <-- "N:1" --> DEPT
STAFF <-- "N:1" --> USERS
IND <-- "N:1" --> DETAIL
ASSESS <-- "1:N" --> DETAIL
DETAIL <-- "N:1" --> IND
PLAN <-- "1:N" --> REL
REL <-- "N:1" --> IND
STAFF <-- "N:1" --> ASSESS
STAFF <-- "N:1" --> SAL
DEPT <-- "N:1" --> FIN
```
图表来源
- [docs/database.md](file://docs/database.md#L1-L286)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
## 详细组件分析
### 1) 基础数据实体
#### 1.1 科室表 departments
- 字段定义
- id: 整型, 主键, 自增
- name: 字符串, 长度100, 非空, 说明: 科室名称
- code: 字符串, 长度20, 唯一, 非空, 说明: 科室编码
- dept_type: 枚举, 非空, 说明: 科室类型
- parent_id: 整型, 外键, 说明: 上级科室
- level: 整型, 默认1, 说明: 层级
- sort_order: 整型, 默认0, 说明: 排序
- is_active: 布尔, 默认true, 说明: 是否启用
- description: 文本, 说明: 描述
- created_at/updated_at: 时间戳, 说明: 创建/更新时间
- 约束与索引
- 唯一键: code
- 索引: idx_dept_type, idx_dept_parent
- 业务含义
- 支持多级组织架构，支持停用/启用；用于员工归属、计划/模板适用范围等
- 默认值与取值范围
- level: 1-5
- sort_order: 任意整数
- is_active: true/false
- 使用场景
- 员工入职时绑定科室；计划/模板按科室类型筛选适用范围
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
- [docs/database.md](file://docs/database.md#L99-L116)
#### 1.2 员工表 staff
- 字段定义
- id: 整型, 主键, 自增
- employee_id: 字符串, 长度20, 唯一, 非空, 说明: 工号
- name: 字符串, 长度50, 非空, 说明: 姓名
- department_id: 整型, 外键, 非空, 说明: 所属科室
- position: 字符串, 长度50, 非空, 说明: 职位
- title: 字符串, 长度50, 说明: 职称
- phone/email: 字符串, 长度20/100, 说明: 联系方式
- base_salary: 数值, 精度(10,2), 默认0, 说明: 基本工资
- performance_ratio: 数值, 精度(5,2), 默认1.0, 说明: 绩效系数
- status: 枚举, 默认active, 说明: 员工状态
- hire_date: 时间戳, 说明: 入职日期
- created_at/updated_at: 时间戳
- 约束与索引
- 唯一键: employee_id
- 索引: idx_staff_dept, idx_staff_status
- 业务含义
- 基于基本工资与绩效系数计算绩效奖金；参与考核与工资生成
- 默认值与取值范围
- base_salary ≥ 0
- 0 ≤ performance_ratio ≤ 5
- 使用场景
- 薪资计算、部门统计、计划责任人
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L107-L150)
- [docs/database.md](file://docs/database.md#L117-L137)
#### 1.3 用户表 users
- 字段定义
- id: 整型, 主键, 自增
- username: 字符串, 长度50, 唯一, 非空, 说明: 用户名
- password_hash: 字符串, 长度255, 非空, 说明: 密码哈希
- staff_id: 整型, 外键, 说明: 关联员工
- role: 字符串, 长度20, 默认staff, 说明: 角色
- is_active: 布尔, 默认true, 说明: 是否启用
- last_login: 时间戳, 说明: 最后登录
- created_at/updated_at: 时间戳
- 约束与索引
- 唯一键: username
- 索引: idx_user_username
- 业务含义
- 系统访问控制与权限管理的基础
章节来源
- [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-L345)
### 2) 指标与模板
#### 2.1 指标表 indicators
- 字段定义
- id: 整型, 主键, 自增
- name/code: 字符串, 长度100/20, 唯一, 非空, 说明: 指标名称/编码
- indicator_type: 枚举, 非空, 说明: 指标类型
- bs_dimension: 枚举, 非空, 说明: 平衡计分卡维度
- weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
- max_score: 数值, 精度(5,2), 默认100, 说明: 最高分值
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
- calculation_method/assessment_method/deduction_standard/data_source: 文本, 说明: 计算/考核/扣分/数据来源
- applicable_dept_types: 文本(JSON数组), 说明: 适用科室类型
- is_veto: 布尔, 默认false, 说明: 是否一票否决
- is_active: 布尔, 默认true, 说明: 是否启用
- created_at/updated_at: 时间戳
- 约束与索引
- 约束: weight > 0
- 索引: idx_indicator_type
- 业务含义
- 考核的最小颗粒，决定评分与权重；支持JSON存储适用范围
- 默认值与取值范围
- weight > 0
- max_score ≥ 0
- 使用场景
- 考核打分、计划目标设定、模板匹配
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L153-L193)
- [docs/database.md](file://docs/database.md#L138-L158)
#### 2.2 指标模板表 indicator_templates
- 字段定义
- id: 整型, 主键, 自增
- template_name/code: 字符串, 长度200/50, 唯一, 非空
- template_type: 枚举, 非空, 说明: 模板类型
- description: 文本, 说明: 模板描述
- dimension_weights: 文本(JSON), 说明: 维度权重
- assessment_cycle: 字符串, 长度20, 默认monthly, 说明: 考核周期
- is_active: 布尔, 默认true
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_template_type, idx_template_active
- 业务含义
- 为不同科室类型提供标准化指标集合，支持批量导入
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L409)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L732)
#### 2.3 模板指标关联表 template_indicators
- 字段定义
- id: 整型, 主键, 自增
- template_id/indicator_id: 整型, 外键, 非空, 说明: 模板与指标
- category: 字符串, 长度100, 说明: 指标分类(二级指标)
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
- weight: 数值, 精度(5,2), 默认1.0
- scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
- sort_order: 整型, 默认0, 说明: 排序
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_ti_template, idx_ti_indicator, idx_ti_unique(模板+指标唯一)
- 业务含义
- 将指标纳入模板，支持排序与评分参数配置
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
### 3) 考核与工资
#### 3.1 考核记录表 assessments
- 字段定义
- id: 整型, 主键, 自增
- staff_id: 整型, 外键, 非空, 说明: 被考核员工
- period_year/period_month: 整型, 非空, 说明: 考核年度/月份
- period_type: 字符串, 长度20, 默认monthly, 说明: 周期类型
- total_score/weighted_score: 数值, 精度(5,2), 默认0, 说明: 总分/加权得分
- status: 枚举, 默认draft, 说明: 状态
- assessor_id/reviewer_id: 整型, 外键, 说明: 考核人/审核人
- submit_time/review_time: 时间戳, 说明: 提交/审核时间
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_assessment_staff, idx_assessment_period, idx_assessment_status
- 业务含义
- 记录一次完整的考核流程，支持草稿、提交、审核、确认、驳回
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L220-L271)
- [docs/database.md](file://docs/database.md#L159-L180)
#### 3.2 考核明细表 assessment_details
- 字段定义
- id: 整型, 主键, 自增
- assessment_id/indicator_id: 整型, 外键, 非空
- actual_value: 数值, 精度(10,2), 说明: 实际值
- score: 数值, 精度(5,2), 默认0, 说明: 得分
- evidence: 文本, 说明: 佐证材料
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_detail_assessment, idx_detail_indicator
- 业务含义
- 记录每个指标的得分与实际值，支撑总分与加权得分计算
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L196-L219)
- [docs/database.md](file://docs/database.md#L181-L196)
#### 3.3 工资记录表 salary_records
- 字段定义
- id: 整型, 主键, 自增
- staff_id: 整型, 外键, 非空
- period_year/period_month: 整型, 非空
- base_salary/performance_score/performance_bonus/deduction/allowance: 数值, 精度(10,2)/(5,2), 默认0, 说明: 基本工资/绩效得分/绩效奖金/扣款/补贴
- total_salary: 数值, 精度(10,2), 默认0, 说明: 应发工资
- status: 字符串, 长度20, 默认pending, 说明: 状态
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_salary_staff, idx_salary_period
- 业务含义
- 基于考核结果生成工资，支持确认与批量确认
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L312)
- [docs/database.md](file://docs/database.md#L197-L217)
### 4) 绩效计划
#### 4.1 绩效计划表 performance_plans
- 字段定义
- id: 整型, 主键, 自增
- plan_name/code: 字符串, 长度200/50, 唯一, 非空
- plan_level: 枚举, 非空, 说明: 计划层级(hospital/department/individual)
- plan_year/plan_month: 整型/可选, 说明: 年度/月份
- plan_type: 字符串, 长度20, 默认annual, 说明: 计划类型(annual/monthly)
- department_id/staff_id: 整型/可选, 外键, 说明: 所属科室/责任人
- parent_plan_id: 整型, 外键, 说明: 上级计划
- description/strategic_goals/key_initiatives: 文本, 说明: 描述/战略目标/关键举措
- status: 枚举, 默认draft, 说明: 状态
- submitter_id/approver_id: 整型, 外键, 说明: 提交人/审批人
- submit_time/approve_time: 时间戳, 说明: 提交/审批时间
- approve_remark: 文本, 说明: 审批意见
- version: 整型, 默认1, 说明: 版本号
- is_active: 布尔, 默认true, 说明: 是否启用
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_plan_level, idx_plan_year, idx_plan_department, idx_plan_status
- 业务含义
- 支持医院/科室/个人三级计划，支持父子计划与审批流程
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L312)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
#### 4.2 计划指标关联表 plan_kpi_relations
- 字段定义
- id: 整型, 主键, 自增
- plan_id/indicator_id: 整型, 外键, 非空
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
- weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
- scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 索引: idx_relation_plan, idx_relation_indicator, idx_relation_unique(计划+指标唯一)
- 业务含义
- 将指标纳入具体计划，支持目标与权重配置
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L339)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L481-L518)
### 5) 财务核算
#### 5.1 科室财务记录表 department_finances
- 字段定义
- id: 整型, 主键, 自增
- department_id: 整型, 外键, 非空
- period_year/period_month: 整型, 非空
- finance_type: 枚举, 非空, 说明: 收入/支出
- category: 字符串, 长度50, 非空, 说明: 类别
- amount: 数值, 精度(12,2), 默认0, 说明: 金额
- source: 字符串, 长度100, 说明: 数据来源
- remark: 文本, 说明: 备注
- created_at/updated_at: 时间戳
- 约束与索引
- 约束: amount ≥ 0
- 索引: idx_finance_dept, idx_finance_period, idx_finance_type, idx_finance_category
- 业务含义
- 记录各科室的收支明细，支持按类别统计与结余计算
章节来源
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L75)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L407-L452)
### 6) 枚举类型与取值范围
- 科室类型 DeptType
- 取值: clinical_surgical, clinical_nonsurgical_ward, clinical_nonsurgical_noward, medical_tech, medical_auxiliary, nursing, admin, finance, logistics
- 用途: 控制模板与计划适用范围
- 员工状态 StaffStatus
- 取值: active, leave, resigned, retired
- 考核状态 AssessmentStatus
- 取值: draft, submitted, reviewed, finalized, rejected
- 指标类型 IndicatorType
- 取值: quality, quantity, efficiency, service, cost
- 计划层级 PlanLevel
- 取值: hospital, department, individual
- 计划状态 PlanStatus
- 取值: draft, pending, approved, rejected, active, completed, cancelled
- 菜单类型 MenuType
- 取值: menu, button
- 模板类型 TemplateType
- 取值: general, surgical, nonsurgical_ward, nonsurgical_noward, medical_tech, nursing, admin, logistics
- 财务类型 FinanceType
- 取值: revenue, expense
- 收入类别 RevenueCategory
- 取值: examination, lab_test, radiology, bed, nursing, treatment, surgery, injection, oxygen, other
- 支出类别 ExpenseCategory
- 取值: material, personnel, maintenance, utility, other
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L43)
- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
- [backend/app/models/models.py](file://backend/app/models/models.py#L341-L345)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L385)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L16-L43)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L12-L45)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L463-L479)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L584-L588)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L642-L652)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L378-L405)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L378-L405)
### 7) 数据流转说明
#### 7.1 考核到工资的流程
```mermaid
sequenceDiagram
participant API as "API"
participant Svc as "SalaryService"
participant DB as "数据库"
API->>Svc : "根据考核生成工资"
Svc->>DB : "查询已确认的考核记录"
DB-->>Svc : "返回考核与明细"
Svc->>Svc : "计算绩效得分/奖金"
Svc->>DB : "写入工资记录"
DB-->>Svc : "返回记录ID"
Svc-->>API : "生成成功"
```
图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L194-L206)
#### 7.2 财务收支统计流程
```mermaid
flowchart TD
Start(["开始"]) --> Fetch["查询科室收支记录"]
Fetch --> Group["按类别分组统计"]
Group --> Sum["计算合计"]
Sum --> Balance["结余 = 收入合计 - 支出合计"]
Balance --> End(["结束"])
```
图表来源
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L21-L155)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L75)
## 依赖分析
```mermaid
graph LR
STAFF["staff"] --> DEPT["departments"]
STAFF --> USERS["users"]
ASSESS["assessments"] --> STAFF
ASSESS --> DETAIL["assessment_details"]
DETAIL --> IND["indicators"]
SAL["salary_records"] --> STAFF
PLAN["performance_plans"] --> DEPT
PLAN --> STAFF
PLAN --> REL["plan_kpi_relations"]
REL --> IND
TPL["indicator_templates"] --> TIND["template_indicators"]
TIND --> IND
FIN["department_finances"] --> DEPT
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
## 性能考虑
- 索引策略
- 对常用过滤字段建立索引（如科室类型、状态、周期、部门）
- 对外键字段建立索引，减少连接开销
- 查询优化
- 使用selectinload预加载关联对象，避免N+1查询
- 分页查询配合COUNT子查询，避免全表扫描
- 数据类型选择
- 数值使用Decimal保证精度；字符串使用VARCHAR并设置合理上限
- 缓存建议
- 对静态枚举与模板列表可做内存缓存，降低数据库压力
## 故障排除指南
- 常见错误与定位
- “指标/模板/科室编码已存在”：检查唯一约束冲突
- “无法删除，存在子记录”：先清理子项再删除
- “无法生成/确认工资”：检查考核状态与重复生成
- “无效的类别”：确认财务类别枚举值
- 排查步骤
- 查看API返回状态码与错误信息
- 检查数据库约束与索引是否生效
- 核对枚举值是否在允许范围内
- 使用服务层日志定位业务流程异常点
章节来源
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L82)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L103-L107)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L104-L110)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L170-L175)
## 结论
本数据字典系统性梳理了医院绩效管理系统的数据结构与业务规则，明确了字段定义、枚举取值、默认值与约束、索引策略与使用场景，并给出了数据流转与维护规范。建议在后续迭代中持续完善字段注释、扩展审计字段、引入字段变更追踪机制，确保数据治理的可追溯性与一致性。
## 附录
### A. 字段与业务实体对应关系
- 科室 → 员工：一对多
- 员工 → 考核：一对多
- 考核 → 明细：一对多
- 明细 → 指标：多对一
- 员工 → 工资：一对多
- 计划 → 指标：多对多（通过plan_kpi_relations）
- 模板 → 指标：多对多（通过template_indicators）
- 科室 → 财务：一对多
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
### B. 数据字典维护与更新规范
- 新增字段
- 在模型层定义字段与约束，补充Pydantic模式
- 在API层增加参数校验与默认值
- 在服务层处理字段映射与业务逻辑
- 更新数据库迁移脚本并升级数据库
- 修改字段
- 评估兼容性与影响范围
- 通过迁移脚本安全变更，保留历史数据
- 更新API与模式校验规则
- 删除字段
- 确认无业务依赖后，通过迁移脚本删除
- 清理相关API与服务逻辑
### C. 数据字典查询与使用指南
- 基础查询
- 通过API参数过滤（如科室类型、状态、周期）
- 使用分页参数控制返回数量
- 高级查询
- 结合多个条件组合查询
- 使用树形结构查询科室层级
- 数据导出
- 指标与模板支持批量导入/导出
- 财务模块支持按类别统计与汇总
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L51)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L56)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L75)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L116-L155)

469
.qoder/repowiki/zh/content/数据库设计/数据字典/枚举类型定义.md Normal file
View File

@@ -0,0 +1,469 @@
# 枚举类型定义
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [templates.py](file://backend/app/api/v1/templates.py)
- [init_templates.py](file://backend/app/scripts/init_templates.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档提供了医院绩效管理系统中所有枚举类型的完整数据字典。系统采用平衡计分卡（BSC）理论框架，通过标准化的枚举类型确保业务逻辑的一致性和可维护性。
该系统涵盖了从基础科室管理到复杂绩效考核的完整业务流程，所有关键业务状态和分类都通过精心设计的枚举类型来实现。
## 项目结构
系统采用分层架构设计，枚举类型分布在多个层次中：
```mermaid
graph TB
subgraph "数据模型层"
A[models.py<br/>数据库模型枚举]
end
subgraph "API层"
B[templates.py<br/>模板管理API]
C[departments.py<br/>科室管理API]
D[menus.py<br/>菜单管理API]
end
subgraph "服务层"
E[template_service.py<br/>模板服务]
F[department_service.py<br/>科室服务]
G[menu_service.py<br/>菜单服务]
end
subgraph "脚本层"
H[init_templates.py<br/>模板初始化]
end
A --> B
A --> C
A --> D
B --> E
C --> F
D --> G
H --> A
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L16-L438)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
## 核心组件
系统定义了以下主要枚举类型：
### 科室类型 (DeptType)
用于标识医院各类科室的标准化分类体系。
### 平衡计分卡维度 (BSCDimension)
基于财务、客户、内部流程、学习成长四个维度的绩效评估框架。
### 员工状态 (StaffStatus)
员工在组织中的生命周期状态管理。
### 考核状态 (AssessmentStatus)
绩效考核流程中的状态流转控制。
### 指标类型 (IndicatorType)
不同类型绩效指标的分类标准。
### 计划状态 (PlanStatus)
绩效计划执行过程中的状态管理。
### 菜单类型 (MenuType)
系统菜单结构的类型区分。
### 模板类型 (TemplateType)
绩效指标模板的分类体系。
**章节来源**
- [models.py](file://backend/app/models/models.py#L16-L438)
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
## 架构概览
系统采用统一的枚举类型管理策略，确保跨层一致性：
```mermaid
classDiagram
class DeptType {
+CLINICAL_SURGICAL
+CLINICAL_NONSURGICAL_WARD
+CLINICAL_NONSURGICAL_NOWARD
+MEDICAL_TECH
+MEDICAL_AUXILIARY
+NURSING
+ADMIN
+FINANCE
+LOGISTICS
}
class BSCDimension {
+FINANCIAL
+CUSTOMER
+INTERNAL_PROCESS
+LEARNING_GROWTH
}
class StaffStatus {
+ACTIVE
+LEAVE
+RESIGNED
+RETIRED
}
class AssessmentStatus {
+DRAFT
+SUBMITTED
+REVIEWED
+FINALIZED
+REJECTED
}
class IndicatorType {
+QUALITY
+QUANTITY
+EFFICIENCY
+SERVICE
+COST
}
class PlanStatus {
+DRAFT
+PENDING
+APPROVED
+REJECTED
+ACTIVE
+COMPLETED
+CANCELLED
}
class MenuType {
+MENU
+BUTTON
}
class TemplateType {
+GENERAL
+SURGICAL
+NON_SURGICAL_WARD
+NON_SURGICAL_NOWARD
+MEDICAL_TECH
+NURSING
+ADMIN
+LOGISTICS
}
DeptType --> BSCDimension : "影响"
IndicatorType --> BSCDimension : "映射"
TemplateType --> DeptType : "适用"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L16-L438)
## 详细组件分析
### 科室类型 (DeptType) 数据字典
| 枚举值 | 业务含义 | 适用科室 | 使用场景 | 约束条件 |
|--------|----------|----------|----------|----------|
| clinical_surgical | 手术临床科室 | 外科、骨科、胸外科等 | 手术量、手术质量评估 | DRG/ RBRVS 计费 |
| clinical_nonsurgical_ward | 非手术有病房科室 | 内科、儿科、神经科等 | 住院患者管理、病床使用率 | 床位周转率评估 |
| clinical_nonsurgical_noward | 非手术无病房科室 | 急诊科、观察室等 | 急诊处理能力、观察患者管理 | 急诊周转时间 |
| medical_tech | 医技科室 | 检验科、放射科、超声科等 | 检查报告质量、服务效率 | 报告准确率、及时性 |
| medical_auxiliary | 医辅科室 | 病理科、药剂科等 | 辅助诊断支持、药品管理 | 质量控制标准 |
| nursing | 护理单元 | 各病区护理单元 | 护理质量、患者满意度 | 护理技术操作规范 |
| admin | 行政科室 | 院办、党办、财务科等 | 管理效能、服务支持 | 内部客户满意度 |
| finance | 财务科室 | 财务科 | 财务核算、成本控制 | 会计准则遵循 |
| logistics | 后勤保障科室 | 总务科、设备科等 | 后勤保障、设备维护 | 设备完好率 |
**使用场景示例**：
- 指标模板选择：不同科室类型适用不同的指标模板
- 数据筛选：按科室类型过滤统计数据
- 权限控制：特定功能对特定科室类型开放
**章节来源**
- [models.py](file://backend/app/models/models.py#L16-L26)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
### 平衡计分卡维度 (BSCDimension) 数据字典
| 维度值 | 业务含义 | 权重范围 | 关键指标示例 | 适用场景 |
|--------|----------|----------|--------------|----------|
| financial | 财务维度 | 30%-40% | 收支结余率、成本控制、资产效率 | 财务绩效评估 |
| customer | 顾客维度 | 25%-35% | 患者满意度、服务可及性、投诉管理 | 服务质量评估 |
| internal_process | 内部流程维度 | 20%-30% | 医疗质量、医疗安全、院感控制 | 运营效率评估 |
| learning_growth | 学习成长维度 | 5%-15% | 科研教学、人才培养、业务学习 | 能力发展评估 |
**权重配置原则**：
- 通用模板：财务40%，客户30%，内部流程25%，学习成长5%
- 手术科室：财务35%，客户20%，内部流程30%，学习成长15%
- 医技科室：财务20%，客户30%，内部流程40%，学习成长10%
**章节来源**
- [models.py](file://backend/app/models/models.py#L29-L34)
- [templates.py](file://backend/app/api/v1/templates.py#L63-L74)
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L186)
### 员工状态 (StaffStatus) 数据字典
| 状态值 | 业务含义 | 系统行为 | 统计影响 | 权限控制 |
|--------|----------|----------|----------|----------|
| active | 在职 | 可参与考核、享受绩效 | 计入在岗人员统计 | 完整权限 |
| leave | 休假 | 不参与考核、暂停绩效 | 不计入在岗统计 | 有限权限 |
| resigned | 离职 | 不参与考核、结算薪酬 | 不再统计 | 无权限 |
| retired | 退休 | 不参与考核、结算薪酬 | 不再统计 | 无权限 |
**状态流转图**：
```mermaid
stateDiagram-v2
[*] --> active
active --> leave : 请假/调休
leave --> active : 返回工作
active --> resigned : 离职办理
active --> retired : 退休办理
resigned --> [*]
retired --> [*]
```
**章节来源**
- [models.py](file://backend/app/models/models.py#L37-L42)
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L28)
### 考核状态 (AssessmentStatus) 数据字典
| 状态值 | 业务含义 | 系统权限 | 数据处理 | 流程控制 |
|--------|----------|----------|----------|----------|
| draft | 草稿 | 创建/编辑 | 临时保存 | 初始状态 |
| submitted | 已提交 | 审核查看 | 待审核状态 | 提交流程 |
| reviewed | 已审核 | 确认审批 | 审核中 | 审核流程 |
| finalized | 已确认 | 工资核算 | 生效状态 | 结束状态 |
| rejected | 已驳回 | 重新编辑 | 退回修改 | 异常流程 |
**状态流转流程**：
```mermaid
sequenceDiagram
participant U as 用户
participant S as 系统
participant A as 审核人
participant P as 系统
U->>S : 创建/编辑考核
S->>S : 状态=draft
U->>S : 提交考核
S->>S : 状态=submitted
A->>S : 审核通过
S->>S : 状态=reviewed
A->>S : 确认生效
S->>S : 状态=finalized
S->>P : 生成工资记录
```
**章节来源**
- [models.py](file://backend/app/models/models.py#L45-L51)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
### 指标类型 (IndicatorType) 数据字典
| 类型值 | 业务含义 | 计算方法 | 评估标准 | 示例指标 |
|--------|----------|----------|----------|----------|
| quality | 质量指标 | 定性/定量评估 | 百分比/分数制 | 甲级病历率、满意度 |
| quantity | 数量指标 | 绝对数值统计 | 完成率/达标率 | 手术台次、门诊量 |
| efficiency | 效率指标 | 比较/比率分析 | 时间/成本效率 | 住院日、周转率 |
| service | 服务指标 | 客户满意度 | 星级/评分制 | 服务态度、及时性 |
| cost | 成本指标 | 成本效益分析 | 成本控制效果 | 材料消耗、成本率 |
**评估方法分类**：
- 区间法：设定目标区间，按比例扣分
- 目标参照法：与目标值对比，超耗扣分
- 加分法：超额完成给予奖励分
- 扣分法：违规事件直接扣分
- 一票否决：重大事故直接无效
**章节来源**
- [models.py](file://backend/app/models/models.py#L54-L60)
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
### 计划状态 (PlanStatus) 数据字典
| 状态值 | 业务含义 | 审批流程 | 统计作用 | 系统控制 |
|--------|----------|----------|----------|----------|
| draft | 草稿 | 无需审批 | 临时保存 | 创建/修改 |
| pending | 待审批 | 上级审批 | 待执行 | 提交申请 |
| approved | 已批准 | 审批通过 | 执行准备 | 正式生效 |
| rejected | 已驳回 | 审批拒绝 | 修改调整 | 退回修改 |
| active | 执行中 | 开始执行 | 实际执行 | 进行中 |
| completed | 已完成 | 执行结束 | 归档统计 | 结束状态 |
| cancelled | 已取消 | 主动取消 | 终止执行 | 异常终止 |
**计划层级**：
- hospital：医院级计划，全局性目标
- department：科室级计划，部门目标
- individual：个人级计划，员工目标
**章节来源**
- [models.py](file://backend/app/models/models.py#L233-L241)
- [schemas.py](file://backend/app/schemas/schemas.py#L463-L478)
### 菜单类型 (MenuType) 数据字典
| 类型值 | 业务含义 | 界面表现 | 权限控制 | 使用场景 |
|--------|----------|----------|----------|----------|
| menu | 菜单 | 可展开的导航项 | 路由访问权限 | 主要功能入口 |
| button | 按钮 | 可点击的操作按钮 | 功能操作权限 | 具体业务操作 |
**菜单结构**：
- 一级菜单：工作台、科室管理、员工管理等
- 二级菜单：具体的业务功能页面
- 按钮权限：新增、编辑、删除、查看等操作
**章节来源**
- [models.py](file://backend/app/models/models.py#L341-L344)
- [schemas.py](file://backend/app/schemas/schemas.py#L584-L587)
### 模板类型 (TemplateType) 数据字典
| 类型值 | 业务含义 | 适用范围 | 权重配置 | 特殊要求 |
|--------|----------|----------|----------|----------|
| general | 通用模板 | 全院各科室 | 4维均衡 | 基础通用指标 |
| surgical | 手术临床科室 | 外科、妇科、眼科等 | 财务35% | DRG/RBRVS导向 |
| nonsurgical_ward | 非手术有病房科室 | 内科、儿科等 | 4维均衡 | 住院管理重点 |
| nonsurgical_noward | 非手术无病房科室 | 急诊、观察室等 | 4维均衡 | 急诊效率评估 |
| medical_tech | 医技科室 | 检验、放射、超声等 | 内部流程40% | 质量效率双核心 |
| nursing | 护理单元 | 各病区护理单元 | 顾客30% | 护理质量优先 |
| admin | 行政科室 | 院办、党办、财务等 | 顾客40% | 服务支持导向 |
| logistics | 后勤科室 | 总务、设备、基建等 | 内部流程40% | 保障效率优先 |
**模板特点**：
- **通用模板**：平衡四维度，适合大多数科室
- **手术模板**：强调财务效率，体现技术价值
- **医技模板**：注重质量与效率并重
- **行政模板**：突出服务支持能力
- **后勤模板**：重视保障及时性
**章节来源**
- [models.py](file://backend/app/models/models.py#L375-L384)
- [schemas.py](file://backend/app/schemas/schemas.py#L642-L651)
- [templates.py](file://backend/app/api/v1/templates.py#L45-L60)
## 依赖分析
### 数据库迁移依赖
系统通过 Alembic 迁移管理枚举类型的数据库存储：
```mermaid
flowchart TD
A[初始版本] --> B[添加指标维度字段]
B --> C[模板类型定义]
C --> D[枚举类型持久化]
E[DeptType] --> F[departments表]
G[BSCDimension] --> H[indicators表]
I[AssessmentStatus] --> J[assessments表]
K[TemplateType] --> L[indicator_templates表]
F --> M[SQL约束]
H --> M
J --> M
L --> M
```
**图表来源**
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L173)
- [002_template.py](file://backend/alembic/versions/002_template.py#L65-L95)
### 业务流程依赖
```mermaid
graph LR
subgraph "业务流程"
A[科室类型] --> B[指标模板]
B --> C[绩效考核]
C --> D[工资核算]
end
subgraph "状态管理"
E[员工状态] --> F[考核状态]
F --> G[计划状态]
end
subgraph "系统集成"
H[菜单类型] --> I[权限控制]
I --> J[界面展示]
end
B --> F
C --> G
D --> G
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
**章节来源**
- [002_template.py](file://backend/alembic/versions/002_template.py#L65-L95)
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
## 性能考虑
### 枚举类型性能优化
1. **数据库索引优化**
- 科室类型：departments.dept_type
- 员工状态：staff.status
- 考核状态：assessments.status
- 指标类型：indicators.indicator_type
2. **查询性能**
- 使用枚举值进行精确匹配优于字符串模糊查询
- 合理利用数据库索引提高查询效率
- 避免在 WHERE 子句中进行枚举值转换
3. **内存使用**
- 枚举类型占用固定内存空间
- 避免频繁创建新的枚举实例
- 使用枚举缓存机制减少重复创建
## 故障排除指南
### 常见问题及解决方案
**问题1：枚举值不一致**
- 症状：数据库中存储的枚举值与代码定义不匹配
- 解决方案：检查 Alembic 迁移文件，确保数据库字段类型正确
**问题2：状态流转异常**
- 症状：考核状态无法正常转换
- 解决方案：验证状态转换规则，检查业务逻辑实现
**问题3：模板应用错误**
- 症状：指标模板不适用于特定科室类型
- 解决方案：检查 applicable_dept_types 字段配置
**问题4：权限控制失效**
- 症状：菜单权限不生效
- 解决方案：验证 MenuType 和权限标识配置
**章节来源**
- [models.py](file://backend/app/models/models.py#L16-L438)
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
## 结论
本系统通过标准化的枚举类型设计，实现了以下目标：
1. **业务一致性**：统一的枚举定义确保各模块间业务逻辑的一致性
2. **可维护性**：集中化的枚举管理便于后续扩展和维护
3. **可扩展性**：清晰的枚举层次结构支持业务需求变化
4. **数据完整性**：数据库层面的约束保证数据质量
建议在后续开发中：
- 定期审查和更新枚举定义
- 建立枚举变更的审批流程
- 完善枚举值的业务文档
- 加强枚举类型的单元测试

414
.qoder/repowiki/zh/content/数据库设计/数据字典/系统菜单字段.md Normal file
View File

@@ -0,0 +1,414 @@
# 系统菜单字段
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [menus.py](file://backend/app/api/v1/menus.py)
- [menu_service.py](file://backend/app/services/menu_service.py)
- [menu.js](file://frontend/src/api/menu.js)
- [Menus.vue](file://frontend/src/views/system/Menus.vue)
- [Layout.vue](file://frontend/src/views/Layout.vue)
- [index.js](file://frontend/src/router/index.js)
- [security.py](file://backend/app/core/security.py)
- [create_menu_tables.py](file://backend/create_menu_tables.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档提供了医院绩效系统中系统菜单相关字段的详细数据字典。涵盖了系统菜单表(Menu)、菜单类型枚举(MenuType)等字段定义，详细说明了菜单层级结构、权限控制、路由配置等相关字段。文档包含了菜单树形结构的父子关系和排序机制，提供了菜单权限验证和动态加载的字段设计说明，以及菜单可见性和激活状态的字段约束。同时说明了菜单与功能权限的关联关系。
## 项目结构
系统采用前后端分离架构，菜单管理功能分布在以下层次：
```mermaid
graph TB
subgraph "前端层"
FE_API[菜单API调用]
FE_VIEW[菜单管理界面]
FE_ROUTER[前端路由]
end
subgraph "后端层"
API[菜单API路由]
SERVICE[菜单业务逻辑]
MODEL[菜单数据模型]
SCHEMA[数据验证模式]
end
subgraph "数据库层"
DB[(MySQL数据库)]
end
FE_API --> API
FE_VIEW --> FE_API
FE_ROUTER --> FE_VIEW
API --> SERVICE
SERVICE --> MODEL
MODEL --> DB
SCHEMA --> API
```
**图表来源**
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [models.py](file://backend/app/models/models.py#L347-L373)
**章节来源**
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [models.py](file://backend/app/models/models.py#L347-L373)
## 核心组件
### 菜单数据模型
系统菜单采用自引用的树形结构设计，支持无限层级的菜单组织。每个菜单项包含完整的元数据信息，用于前端渲染和权限控制。
### 菜单类型枚举
系统支持两种菜单类型：
- **菜单(Menu)**: 用于页面导航的主要菜单项
- **按钮(Button)**: 用于页面内功能按钮的权限控制
### 菜单字段定义
| 字段名 | 数据类型 | 是否可空 | 默认值 | 描述 |
|--------|----------|----------|--------|------|
| id | Integer | 否 | 自增 | 菜单唯一标识符 |
| parent_id | Integer | 是 | NULL | 父菜单ID，自引用外键 |
| menu_type | Enum | 否 | menu | 菜单类型(MENU/BUTTON) |
| menu_name | String(100) | 否 | - | 菜单显示名称 |
| menu_icon | String(50) | 是 | NULL | Element Plus图标名称 |
| path | String(200) | 否 | - | Vue Router路由路径 |
| component | String(200) | 是 | NULL | 页面组件路径 |
| permission | String(100) | 是 | NULL | 权限标识符 |
| sort_order | Integer | 否 | 0 | 排序权重 |
| is_visible | Boolean | 否 | TRUE | 是否在菜单中显示 |
| is_active | Boolean | 否 | TRUE | 菜单是否启用 |
| created_at | DateTime | 否 | 当前时间 | 创建时间戳 |
| updated_at | DateTime | 否 | 当前时间 | 更新时间戳 |
**章节来源**
- [models.py](file://backend/app/models/models.py#L347-L373)
- [schemas.py](file://backend/app/schemas/schemas.py#L590-L638)
## 架构概览
系统菜单架构采用经典的三层架构模式，实现了完整的菜单生命周期管理：
```mermaid
sequenceDiagram
participant Client as 前端客户端
participant API as 菜单API
participant Service as 菜单服务
participant Model as 数据模型
participant DB as 数据库
Client->>API : GET /menus/tree?visible_only=true
API->>Service : get_tree(visible_only)
Service->>Model : 查询菜单树
Model->>DB : SQL查询
DB-->>Model : 菜单数据
Model-->>Service : 菜单对象
Service->>Service : 转换为字典结构
Service-->>API : 菜单树数据
API-->>Client : JSON响应
Note over Client,DB : 菜单树形结构加载流程
```
**图表来源**
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
**章节来源**
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
## 详细组件分析
### 菜单树形结构设计
系统采用自引用关系实现菜单树形结构，支持无限层级嵌套：
```mermaid
classDiagram
class Menu {
+Integer id
+Integer parent_id
+MenuType menu_type
+String menu_name
+String menu_icon
+String path
+String component
+String permission
+Integer sort_order
+Boolean is_visible
+Boolean is_active
+DateTime created_at
+DateTime updated_at
+children : Menu[]
+parent : Menu
}
class MenuType {
<<enumeration>>
MENU
BUTTON
}
Menu --> Menu : "parent_id -> id"
Menu --> Menu : "children"
Menu --> MenuType : "uses"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L347-L373)
- [models.py](file://backend/app/models/models.py#L341-L345)
### 菜单权限控制机制
系统实现了多层次的权限控制体系：
```mermaid
flowchart TD
Start([用户请求菜单]) --> CheckAuth["检查用户认证"]
CheckAuth --> AuthOK{"认证通过?"}
AuthOK --> |否| Deny["拒绝访问"]
AuthOK --> |是| LoadTree["加载菜单树"]
LoadTree --> FilterVisible["过滤可见菜单"]
FilterVisible --> FilterActive["过滤启用菜单"]
FilterActive --> SortOrder["按排序字段排序"]
SortOrder --> BuildTree["构建菜单树"]
BuildTree --> ReturnMenu["返回菜单数据"]
Deny --> End([结束])
ReturnMenu --> End
style Start fill:#e1f5fe
style End fill:#ffebee
style Deny fill:#ffebee
```
**图表来源**
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
- [security.py](file://backend/app/core/security.py#L85-L91)
### 菜单排序机制
系统支持多维度排序控制：
1. **主排序**: `sort_order` 字段，数值越小优先级越高
2. **次排序**: `id` 字段，确保相同排序值的稳定性
3. **层级排序**: 顶级菜单优先于子菜单
**章节来源**
- [menu_service.py](file://backend/app/services/menu_service.py#L24-L24)
- [menu_service.py](file://backend/app/services/menu_service.py#L49-L49)
### 菜单可见性控制
系统通过两个独立字段控制菜单的显示状态：
| 控制字段 | 类型 | 默认值 | 作用域 | 影响范围 |
|----------|------|--------|--------|----------|
| is_visible | Boolean | TRUE | 菜单树渲染 | 前端菜单树显示 |
| is_active | Boolean | TRUE | 功能启用 | 菜单功能可用性 |
**章节来源**
- [menu_service.py](file://backend/app/services/menu_service.py#L20-L21)
- [schemas.py](file://backend/app/schemas/schemas.py#L600-L601)
### 菜单与功能权限关联
系统通过 `permission` 字段实现菜单与功能权限的关联：
```mermaid
erDiagram
MENUS {
int id PK
int parent_id FK
enum menu_type
string menu_name
string menu_icon
string path
string component
string permission
int sort_order
boolean is_visible
boolean is_active
datetime created_at
datetime updated_at
}
USERS {
int id PK
string username UK
string password_hash
string role
boolean is_active
datetime last_login
datetime created_at
datetime updated_at
}
USER_PERMISSIONS {
int user_id FK
string permission
boolean granted
datetime granted_at
}
MENUS ||--o{ MENUS : "parent_id -> id"
USERS ||--o{ USER_PERMISSIONS : "has"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L347-L373)
- [security.py](file://backend/app/core/security.py#L94-L109)
**章节来源**
- [models.py](file://backend/app/models/models.py#L358-L358)
- [schemas.py](file://backend/app/schemas/schemas.py#L598-L598)
### 前端菜单管理界面
前端提供了完整的菜单管理功能：
```mermaid
sequenceDiagram
participant Admin as 管理员
participant View as 菜单管理界面
participant API as 菜单API
participant Service as 菜单服务
participant DB as 数据库
Admin->>View : 打开菜单管理页面
View->>API : 加载菜单列表
API->>Service : get_list()
Service->>DB : 查询菜单
DB-->>Service : 菜单数据
Service-->>API : 菜单列表
API-->>View : 返回数据
View-->>Admin : 显示菜单表格
Admin->>View : 新建菜单
View->>API : create_menu()
API->>Service : create()
Service->>DB : 插入菜单
DB-->>Service : 成功
Service-->>API : 菜单对象
API-->>View : 返回结果
View-->>Admin : 显示成功消息
```
**图表来源**
- [Menus.vue](file://frontend/src/views/system/Menus.vue#L144-L152)
- [menu.js](file://frontend/src/api/menu.js#L18-L21)
**章节来源**
- [Menus.vue](file://frontend/src/views/system/Menus.vue#L1-L265)
- [menu.js](file://frontend/src/api/menu.js#L1-L37)
## 依赖分析
系统菜单功能涉及多个组件间的复杂依赖关系：
```mermaid
graph TB
subgraph "数据层"
MenuModel[Menu模型]
MenuType[MenuType枚举]
end
subgraph "业务层"
MenuService[MenuService]
Security[安全模块]
end
subgraph "接口层"
MenuAPI[菜单API]
Schema[数据模式]
end
subgraph "表现层"
Frontend[前端界面]
Router[Vue Router]
end
MenuAPI --> MenuService
MenuService --> MenuModel
MenuService --> Security
MenuAPI --> Schema
Frontend --> MenuAPI
Router --> Frontend
MenuModel --> MenuType
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L341-L345)
- [models.py](file://backend/app/models/models.py#L347-L373)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
**章节来源**
- [models.py](file://backend/app/models/models.py#L341-L345)
- [models.py](file://backend/app/models/models.py#L347-L373)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
## 性能考虑
### 数据库索引优化
系统为菜单表建立了多个关键索引以提升查询性能：
| 索引名称 | 字段组合 | 用途 | 性能影响 |
|----------|----------|------|----------|
| idx_menu_parent | parent_id | 父子关系查询 | 快速定位子菜单 |
| idx_menu_type | menu_type | 类型过滤查询 | 快速筛选菜单类型 |
| idx_menu_visible | is_visible | 可见性过滤 | 快速筛选显示菜单 |
### 查询优化策略
1. **延迟加载**: 使用 `selectinload` 优化N+1查询问题
2. **条件过滤**: 在服务层统一处理查询条件
3. **排序优化**: 利用复合索引支持排序查询
### 前端性能优化
1. **菜单树缓存**: 避免重复加载相同的菜单树
2. **懒加载**: 路由组件按需加载
3. **虚拟滚动**: 大数据量时使用虚拟滚动
## 故障排除指南
### 常见问题及解决方案
| 问题类型 | 症状 | 可能原因 | 解决方案 |
|----------|------|----------|----------|
| 菜单不显示 | 菜单树为空 | is_visible=false 或 is_active=false | 检查菜单状态字段 |
| 菜单排序异常 | 菜单顺序错误 | sort_order字段冲突 | 重新设置排序值 |
| 子菜单无法删除 | 删除报错 | 存在子菜单依赖 | 先删除子菜单再删除父菜单 |
| 权限控制失效 | 无权限访问 | permission字段缺失 | 添加正确的权限标识符 |
### 调试工具
1. **数据库查询**: 使用SQL查询验证菜单状态
2. **API测试**: 使用Postman测试菜单接口
3. **浏览器调试**: 检查前端控制台错误
**章节来源**
- [menu_service.py](file://backend/app/services/menu_service.py#L86-L98)
- [security.py](file://backend/app/core/security.py#L94-L109)
## 结论
系统菜单字段设计体现了良好的软件工程实践，通过清晰的数据模型、完善的权限控制和高效的查询机制，实现了灵活的菜单管理功能。自引用的树形结构设计支持复杂的菜单层级，而权限标识符则为细粒度的权限控制提供了基础。
系统的关键优势包括：
- **灵活性**: 支持无限层级的菜单结构
- **可扩展性**: 易于添加新的菜单类型和字段
- **安全性**: 多层次的权限控制机制
- **易用性**: 完整的前端管理界面
未来可以考虑的改进方向：
- 增加菜单访问日志功能
- 实现菜单模板化管理
- 添加菜单权限继承机制
- 优化大数据量场景下的性能表现

454
.qoder/repowiki/zh/content/数据库设计/数据字典/绩效计划字段.md Normal file
View File

@@ -0,0 +1,454 @@
# 绩效计划字段
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [create_plan_tables.py](file://backend/create_plan_tables.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文件为医院绩效系统中绩效计划相关字段的详细数据字典，涵盖以下核心实体：
- 绩效计划表（PerformancePlan）
- 计划层级（PlanLevel）
- 计划状态（PlanStatus）
- 计划指标关联表（PlanKpiRelation）
文档详细说明了计划层级结构、计划审批流程、指标权重分配等相关字段，并包含计划执行跟踪和状态管理的字段约束。同时提供计划与指标关联关系的数据字典说明，以及计划版本管理和变更追踪的字段设计。
## 项目结构
该系统采用典型的三层架构设计：
- API层：处理HTTP请求和响应
- 服务层：实现业务逻辑和工作流控制
- 数据模型层：定义数据库表结构和关系
```mermaid
graph TB
subgraph "API层"
API[performance_plans.py]
end
subgraph "服务层"
Service[performance_plan_service.py]
end
subgraph "模型层"
Models[models.py]
Schemas[schemas.py]
end
subgraph "数据库"
DB[(SQLite/PostgreSQL)]
end
API --> Service
Service --> Models
Models --> DB
Schemas --> API
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [models.py](file://backend/app/models/models.py#L270-L339)
## 核心组件
### 绩效计划表（PerformancePlan）
绩效计划表是整个绩效管理体系的核心实体，用于存储各级别（医院级、科室级、个人级）的绩效计划信息。
#### 基础字段定义
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | Integer | 主键, 自增 | 计划唯一标识符 |
| plan_name | String(200) | 非空 | 计划名称 |
| plan_code | String(50) | 唯一, 非空 | 计划编码，全局唯一 |
| plan_level | Enum | 非空 | 计划层级：hospital/department/individual |
| plan_year | Integer | 非空 | 计划年度（2000-2100） |
| plan_month | Integer | 可空 | 计划月份（1-12），仅月度计划使用 |
| plan_type | String(20) | 默认 annual | 计划类型：annual/monthly |
| department_id | Integer | 外键 | 所属科室ID |
| staff_id | Integer | 外键 | 责任人ID |
| parent_plan_id | Integer | 外键 | 上级计划ID，支持层级结构 |
| description | Text | 可空 | 计划描述 |
| strategic_goals | Text | 可空 | 战略目标 |
| key_initiatives | Text | 可空 | 关键举措 |
| status | Enum | 默认 draft | 计划状态：draft/pending/approved/rejected/active/completed/cancelled |
| submitter_id | Integer | 外键 | 提交人ID |
| submit_time | DateTime | 可空 | 提交时间 |
| approver_id | Integer | 外键 | 审批人ID |
| approve_time | DateTime | 可空 | 审批时间 |
| approve_remark | Text | 可空 | 审批意见 |
| version | Integer | 默认 1 | 版本号，用于版本管理 |
| is_active | Boolean | 默认 TRUE | 是否启用 |
| created_at | DateTime | 默认当前时间 | 创建时间 |
| updated_at | DateTime | 默认当前时间 | 更新时间 |
#### 索引设计
- idx_plan_level：按计划层级查询优化
- idx_plan_year：按年度查询优化
- idx_plan_department：按科室查询优化
- idx_plan_status：按状态查询优化
### 计划层级（PlanLevel）
计划层级枚举定义了绩效计划的组织层次结构：
```mermaid
classDiagram
class PlanLevel {
+hospital : "医院级"
+department : "科室级"
+individual : "个人级"
}
class PerformancePlan {
+plan_level : PlanLevel
+parent_plan_id : int
+child_plans : PerformancePlan[]
}
PerformancePlan --> PlanLevel : "使用"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L263-L268)
- [models.py](file://backend/app/models/models.py#L277-L304)
### 计划状态（PlanStatus）
计划状态枚举定义了完整的审批和执行生命周期：
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 待审批 : "提交"
待审批 --> 已批准 : "审批通过"
待审批 --> 已驳回 : "审批驳回"
已批准 --> 执行中 : "激活"
已批准 --> 已取消 : "取消"
执行中 --> 已完成 : "完成"
执行中 --> 已取消 : "取消"
已完成 --> [*]
已取消 --> [*]
已驳回 --> [*]
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L233-L242)
### 计划指标关联表（PlanKpiRelation）
计划指标关联表建立了计划与具体考核指标之间的多对多关系，支持每个指标在不同计划中的差异化配置。
#### 关联字段定义
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | Integer | 主键, 自增 | 关联关系唯一标识符 |
| plan_id | Integer | 外键, 非空 | 关联的计划ID |
| indicator_id | Integer | 外键, 非空 | 关联的指标ID |
| target_value | Decimal(10,2) | 可空 | 目标值 |
| target_unit | String(50) | 可空 | 目标值单位 |
| weight | Decimal(5,2) | 默认 1.0 | 权重（0-100） |
| scoring_method | String(50) | 可空 | 评分方法 |
| scoring_params | Text | 可空 | 评分参数（JSON格式） |
| remark | Text | 可空 | 备注 |
| created_at | DateTime | 默认当前时间 | 创建时间 |
| updated_at | DateTime | 默认当前时间 | 更新时间 |
#### 关联关系
- 一对多：一个计划可以关联多个指标
- 一对多：一个指标可以出现在多个计划中
- 唯一约束：同一计划下的指标必须唯一
**章节来源**
- [models.py](file://backend/app/models/models.py#L314-L339)
- [schemas.py](file://backend/app/schemas/schemas.py#L481-L517)
## 架构概览
系统采用RESTful API设计，支持完整的CRUD操作和业务流程控制：
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API层"
participant Service as "服务层"
participant Model as "模型层"
participant DB as "数据库"
Client->>API : GET /plans/{plan_id}
API->>Service : get_by_id(plan_id)
Service->>Model : 查询PerformancePlan
Model->>DB : SQL查询
DB-->>Model : 返回结果
Model-->>Service : PerformancePlan对象
Service-->>API : 格式化响应
API-->>Client : JSON数据
Note over Client,DB : 审批流程示例
Client->>API : POST /plans/{plan_id}/approve
API->>Service : approve(approver_id, approved, remark)
Service->>Model : 更新状态和审批信息
Model->>DB : 更新操作
DB-->>Model : 确认更新
Model-->>Service : 更新结果
Service-->>API : 审批结果
API-->>Client : 审批状态
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L144-L182)
## 详细组件分析
### 计划层级结构
系统支持三级层级结构，通过parent_plan_id字段实现自关联：
```mermaid
graph TD
HospitalPlan["医院级计划<br/>parent_plan_id: NULL"]
DeptPlan1["科室级计划<br/>parent_plan_id: 医院级计划ID"]
DeptPlan2["科室级计划<br/>parent_plan_id: 医院级计划ID"]
IndividualPlan1["个人级计划<br/>parent_plan_id: 科室级计划ID"]
IndividualPlan2["个人级计划<br/>parent_plan_id: 科室级计划ID"]
HospitalPlan --> DeptPlan1
HospitalPlan --> DeptPlan2
DeptPlan1 --> IndividualPlan1
DeptPlan1 --> IndividualPlan2
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L283-L301)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L319-L341)
### 计划审批流程
审批流程严格遵循状态机设计，确保业务合规性：
```mermaid
flowchart TD
Start([开始]) --> Draft["草稿状态<br/>DRAFT"]
Draft --> Submit["提交申请<br/>SUBMIT"]
Submit --> Pending["待审批<br/>PENDING"]
Pending --> Approve{"审批决定"}
Approve --> |通过| Approved["已批准<br/>APPROVED"]
Approve --> |驳回| Rejected["已驳回<br/>REJECTED"]
Approved --> Activate["激活计划<br/>ACTIVE"]
Activate --> Completed["完成<br/>COMPLETED"]
Rejected --> End([结束])
Completed --> End
Active --> End
```
**图表来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
### 指标权重分配
指标权重分配支持动态配置，每个计划可以为相同指标设置不同的权重：
#### 权重约束
- 权重范围：0-100
- 总权重：同一计划内所有指标权重之和通常为100%
- 动态调整：支持运行时修改权重分配
#### 评分参数
支持JSON格式的评分参数，如：
```json
{
"threshold": 90,
"bonus": 1.2,
"penalty": 0.8
}
```
**章节来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L486-L488)
- [models.py](file://backend/app/models/models.py#L323-L325)
### 计划执行跟踪
系统提供完整的过程跟踪机制：
#### 时间戳管理
- created_at：记录创建时间
- updated_at：自动更新时间戳
- submit_time：提交时间
- approve_time：审批时间
#### 版本管理
- version字段：支持版本追踪
- is_active：控制计划启用状态
- 支持历史版本对比
**章节来源**
- [models.py](file://backend/app/models/models.py#L288-L296)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L120-L128)
### 计划与指标关联关系
关联关系通过PlanKpiRelation表实现，支持灵活的配置：
```mermaid
erDiagram
PERFORMANCE_PLANS {
int id PK
string plan_name
int plan_year
enum plan_level
int department_id FK
int staff_id FK
}
PLAN_KPI_RELATIONS {
int id PK
int plan_id FK
int indicator_id FK
decimal weight
decimal target_value
string target_unit
}
INDICATORS {
int id PK
string name
string code
enum indicator_type
decimal weight
}
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "包含"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被包含"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L270-L339)
## 依赖关系分析
系统采用清晰的分层依赖关系：
```mermaid
graph LR
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
Alembic[Alembic迁移]
end
subgraph "内部模块"
API[API层]
Service[服务层]
Models[模型层]
Schemas[模式层]
end
FastAPI --> API
SQLAlchemy --> Models
Alembic --> Models
API --> Service
Service --> Models
Service --> Schemas
Models --> Schemas
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L18)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L13)
### 数据库迁移
系统使用Alembic进行数据库版本管理，支持增量升级和降级：
#### 迁移版本
- 001_initial：初始版本，创建基础表结构
- 002_template：添加指标模板相关表
#### 迁移特性
- 自动检测模型变化
- 支持安全的数据库演进
- 提供回滚能力
**章节来源**
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
## 性能考虑
### 查询优化
1. **索引策略**
- 多列组合索引用于常用查询条件
- 唯一索引确保数据完整性
- 选择性索引提升查询性能
2. **查询优化**
- 使用selectinload避免N+1查询问题
- 分页查询支持大数据集
- 条件查询减少数据传输
### 缓存策略
- 配置适当的缓存层
- 对静态配置数据进行缓存
- 利用数据库连接池
## 故障排除指南
### 常见问题
1. **计划状态异常**
- 检查状态转换规则
- 验证审批权限
- 确认时间戳完整性
2. **指标关联问题**
- 验证唯一性约束
- 检查权重分配合理性
- 确认评分参数格式
3. **数据库连接问题**
- 检查连接池配置
- 验证迁移版本一致性
- 监控数据库性能
### 调试建议
1. **日志记录**
- 启用详细的API日志
- 记录关键业务操作
- 监控错误堆栈
2. **测试策略**
- 单元测试覆盖核心逻辑
- 集成测试验证流程
- 性能测试评估瓶颈
**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)
## 结论
本数据字典详细描述了医院绩效系统中绩效计划相关的核心字段和业务逻辑。系统采用清晰的分层架构，支持完整的计划生命周期管理，包括：
- 多层级的组织结构支持
- 完整的审批流程控制
- 灵活的指标权重配置
- 详细的执行跟踪机制
- 强大的版本管理功能
通过合理的数据库设计和API接口，系统能够有效支撑医院的绩效管理体系，为不同层级的组织提供个性化的绩效管理解决方案。

364
.qoder/repowiki/zh/content/数据库设计/数据字典/考核相关字段.md Normal file
View File

@@ -0,0 +1,364 @@
# 考核相关字段
<cite>
**本文引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [assessment.js](file://frontend/src/api/assessment.js)
- [stats.py](file://backend/app/api/v1/stats.py)
- [database.md](file://docs/数据库设计.md)
- [详细设计文档.md](file://docs/详细设计文档.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件聚焦于“考核相关字段”的数据字典与业务规则，覆盖以下对象：
- 考核记录表（Assessment）
- 考核明细表（AssessmentDetail）
- 考核状态枚举（AssessmentStatus）
- 考核周期、状态流转、评分计算、完整性校验与一致性保障机制
- 考核结果计算与统计分析相关字段说明
目标是帮助开发者与业务人员快速理解字段含义、取值范围、约束条件、状态转换与计算逻辑，并提供排障建议与最佳实践。
## 项目结构
后端采用分层架构：API 控制器 → 服务层 → ORM 模型；前端通过 API 与后端交互，展示与操作考核流程。
```mermaid
graph TB
FE["前端视图<br/>Assessments.vue / AssessmentDetail.vue"] --> API["FastAPI 路由<br/>assessments.py"]
API --> SVC["服务层<br/>assessment_service.py"]
SVC --> DB["SQLAlchemy 模型<br/>models.py"]
DB --> SQL["数据库表<br/>assessments / assessment_details"]
API --> STATS["统计接口<br/>stats.py"]
```
图表来源
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L149-L202)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
章节来源
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L149-L202)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
## 核心组件
- Assessment（考核记录表）
- 关键字段：period_year、period_month、period_type、total_score、weighted_score、status、assessor_id、reviewer_id、submit_time、review_time、remark
- 业务规则：按月度周期生成记录；总分与加权得分由明细计算；状态驱动流程推进
- AssessmentDetail（考核明细表）
- 关键字段：assessment_id、indicator_id、actual_value、score、evidence、remark
- 业务规则：每个指标一条明细；得分与佐证材料可编辑（草稿态）
- AssessmentStatus（考核状态枚举）
- 草稿（draft）、已提交（submitted）、已审核（reviewed）、已确认（finalized）、已驳回（rejected）
章节来源
- [models.py](file://backend/app/models/models.py#L149-L202)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
## 架构总览
考核流程由前端触发，经 API 路由进入服务层，持久化到数据库模型，最终支持统计分析。
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API 路由"
participant SVC as "服务层"
participant DB as "模型/数据库"
FE->>API : "提交/审核/确认"
API->>SVC : "调用对应方法"
SVC->>DB : "读取/更新 Assessment/Details"
DB-->>SVC : "返回实体"
SVC-->>API : "返回处理结果"
API-->>FE : "返回响应"
```
图表来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L227-L255)
## 详细组件分析
### Assessment（考核记录表）数据字典
- 字段定义与约束
- id：主键，自增整数
- staff_id：外键指向员工，必填
- period_year：整数，必填，年份范围约束见后端校验
- period_month：整数，必填，1-12
- period_type：字符串，默认 monthly
- total_score：数值，总分，创建时由明细得分求和
- weighted_score：数值，加权得分，按指标权重加权求和
- status：状态枚举，默认 draft
- assessor_id：外键，考核人
- reviewer_id：外键，审核人
- submit_time：提交时间
- review_time：审核时间
- remark：备注
- created_at/updated_at：时间戳
- 业务规则
- 考核周期：以年/月为单位，period_type 默认 monthly
- 总分与加权得分：由明细聚合计算
- 状态流转：草稿 → 已提交 → 已审核 → 已确认；或草稿 → 已驳回
- 时间字段：提交/审核时写入对应时间
- 约束与索引
- 索引：staff_id、period_year+period_month、status
- 约束：状态枚举值限定
章节来源
- [models.py](file://backend/app/models/models.py#L149-L178)
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L257)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [database.md](file://docs/数据库设计.md#L159-L177)
### AssessmentDetail（考核明细表）数据字典
- 字段定义与约束
- id：主键，自增整数
- assessment_id：外键，必填
- indicator_id：外键，必填
- actual_value：实际值，可选
- score：数值，得分，创建默认 0
- evidence：佐证材料，可选
- remark：备注
- created_at/updated_at：时间戳
- 业务规则
- 每个指标一条明细
- 草稿态允许编辑得分与佐证材料
- 服务层在创建/更新时重新计算总分与加权得分
- 约束与索引
- 索引：assessment_id、indicator_id
章节来源
- [models.py](file://backend/app/models/models.py#L181-L202)
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
### AssessmentStatus（考核状态枚举）数据字典
- 枚举值
- draft：草稿
- submitted：已提交
- reviewed：已审核
- finalized：已确认
- rejected：已驳回
- 状态转换规则
- 草稿 → 已提交（提交）
- 已提交 → 已审核 或 已驳回（审核）
- 已审核 → 已确认（确认）
- 草稿/已驳回 → 可更新（更新时仅允许草稿或已驳回）
章节来源
- [models.py](file://backend/app/models/models.py#L45-L52)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
### 考核周期与状态流转
- 考核周期
- 默认周期类型为 monthly
- 不同指标模板可配置周期（如年度、季度），但记录层面以年/月为单位
- 状态流转
- 提交：将状态从草稿改为已提交并记录提交时间
- 审核：将状态从已提交改为已审核或已驳回，并记录审核时间
- 确认：将状态从已审核改为已确认
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核驳回"
已审核 --> 已确认 : "确认"
已确认 --> [*]
已驳回 --> 草稿 : "重新编辑"
```
图表来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
### 评分计算与字段约束
- 总分计算
- 总分 = 明细得分之和
- 加权得分计算
- 加权得分 = Σ(明细得分 × 指标权重)
- 权重来自指标表（指标权重 > 0）
- 字段约束
- 指标权重必须大于 0（数据库 CheckConstraint）
- 年度/月份范围在 Pydantic 层面有限制
- 得分字段有最小值 0 的约束
```mermaid
flowchart TD
Start(["创建/更新考核"]) --> LoadDetails["加载明细与指标"]
LoadDetails --> SumScore["总分 = Σ 明细.score"]
LoadDetails --> WeightCalc["加权得分 = Σ 明细.score × 指标.weight"]
SumScore --> SaveAssessment["保存 Assessment"]
WeightCalc --> SaveAssessment
SaveAssessment --> End(["完成"])
```
图表来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [models.py](file://backend/app/models/models.py#L149-L178)
章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [models.py](file://backend/app/models/models.py#L149-L178)
### 完整性检查与一致性保障
- 前端约束
- 草稿态允许编辑得分与佐证材料，得分上限为指标最大分值
- 状态按钮随状态变化显示
- 后端约束
- 状态流转严格限制（仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认）
- 批量创建时按年/月/员工去重，避免重复记录
- 指标权重 > 0 的数据库约束
- 统计一致性
- 统计接口基于当前周期与部门维度聚合，确保跨部门/跨周期对比一致
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
- [models.py](file://backend/app/models/models.py#L144-L146)
### 考核结果计算与统计分析
- 计算字段
- total_score：总分
- weighted_score：加权得分
- 统计接口
- 科室绩效统计、周期统计、趋势分析、排名等
- 前端展示平均分、总人数、奖金汇总等
章节来源
- [stats.py](file://backend/app/api/v1/stats.py#L36-L242)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L31-L74)
## 依赖关系分析
- 模型层
- Assessment ←→ AssessmentDetail（一对多）
- Assessment ←→ Staff（多对一）
- AssessmentDetail ←→ Indicator（多对一）
- 服务层
- 服务层负责状态流转、计算与批量创建
- API 层
- 提供 CRUD、提交、审核、确认、批量创建等接口
- 前端
- 视图根据状态动态渲染按钮与输入框
```mermaid
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
}
class Staff
class Indicator
Assessment "1" o-- "*" AssessmentDetail : "明细"
Assessment "many" --> "1" Staff : "员工"
AssessmentDetail "many" --> "1" Indicator : "指标"
```
图表来源
- [models.py](file://backend/app/models/models.py#L149-L202)
章节来源
- [models.py](file://backend/app/models/models.py#L149-L202)
## 性能考量
- 查询性能
- 为 staff_id、period_year+period_month、status 建立索引，有利于筛选与排序
- 写入性能
- 批量创建时按部门与周期预检，避免重复记录
- 计算性能
- 总分与加权得分在服务层一次性计算，减少多次往返
- 建议
- 对高频查询增加复合索引
- 对大表进行分区或归档策略（如历史周期）
章节来源
- [models.py](file://backend/app/models/models.py#L174-L178)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
## 故障排查指南
- 常见问题
- 状态不可变更：仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认
- 无法提交/审核/确认：检查当前状态是否符合预期
- 批量创建重复：系统按 staff_id+period_year+period_month 去重
- 指标权重异常：数据库约束要求权重 > 0
- 前端定位
- 查看状态标签与按钮可用性
- 校验得分上限与佐证材料输入
- 后端定位
- 检查服务层状态判断与时间字段写入
- 核对明细聚合逻辑与指标权重
章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)
## 结论
本数据字典明确了考核记录与明细的核心字段、状态流转、评分计算与约束条件，并结合前后端实现展示了完整的业务闭环。遵循上述规则可确保数据一致性与流程可控性，同时为后续扩展（如维度得分、模板周期等）提供清晰边界。
## 附录
- API 路由与前端交互
- 列表/详情/创建/更新/提交/审核/确认/批量创建
- 前端通过 assessment.js 发起请求，Assessments.vue 与 AssessmentDetail.vue 控制 UI 行为
章节来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)