提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/数据库设计/数据字典/基础数据字段.md
+++ b/.qoder/repowiki/zh/content/数据库设计/数据字典/基础数据字段.md
@@ -0,0 +1,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 的唯一性
+  - 枚举：统一使用模型中定义的枚举类型，避免拼写差异
+  - 索引：在高频查询列上保持索引，定期评估查询计划
+  - 校验：前端与后端双重校验，确保数据质量