# 基础数据字段

<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 的唯一性
  - 枚举：统一使用模型中定义的枚举类型，避免拼写差异
  - 索引：在高频查询列上保持索引，定期评估查询计划
  - 校验：前端与后端双重校验，确保数据质量