# 数据库状态字段审查

## 审查范围

- 容器：`x-financial-main`
- 数据库：当前运行时 PostgreSQL
- 字段范围：所有 `status`、`stage`、`approval`、`state` 相关列
- 审查方式：只读查询 `information_schema` 与各表状态值分布

## 总体结论

- 当前数据库没有 `status_code`、`state_code`、`stage_code` 这类数字状态码字段。
- 所有匹配到的状态字段类型都是 `character varying`。
- 非业务运行态表，例如 agent 运行、工具调用、预算池、风险观察，主要使用英文机器码。
- 报销主表 `expense_claims` 是当前最需要修复的表：`status` 使用英文码，`approval_stage` 同时混入英文码和中文节点名。

## 报销主表现状

`expense_claims` 当前共 498 条。

按单据类型拆分：

- 申请类单据：2 条，阶段为 `审批完成`、`直属领导审批`。
- 普通报销单：1 条，阶段为 `待提交`。
- 半年模拟报销单：495 条，主要问题都集中在这里。

`expense_claims.status` 当前值：

- `paid`：212
- `approved`：98
- `pending_payment`：67
- `finance_review`：43
- `submitted`：41
- `returned`：17
- `rejected`：13
- `draft`：7

`expense_claims.approval_stage` 当前值：

- `payment`：279
- `completed`：97
- `finance_review`：43
- `manager_review`：40
- `supplement`：17
- `rejected`：13
- `draft`：6
- `审批完成`：1
- `待提交`：1
- `直属领导审批`：1

## 问题判断

现在不是单纯中文显示问题，而是字段职责混乱：

- `status` 被当作流程机器状态使用。
- `approval_stage` 既被当作流程节点，也被历史模拟数据写成英文状态码。
- 单据中心和审批权限逻辑依赖 `submitted + 中文审批阶段`。
- 旧模拟数据中的 `finance_review/manager_review/payment/completed` 会导致审核、归档、报销单分类偏差。

## 建议契约

短期先采用当前代码最接近的契约：

- `status`：稳定机器码，继续使用英文枚举。
- `approval_stage`：当前流程节点，统一使用中文节点名。
- 前端和接口展示层：只展示中文标签，不直接暴露机器码。

中期如要数字状态码，需要单独迁移：

- 增加 `status_code`、`approval_stage_code` 或独立状态字典表。
- 保留现有字符串字段作为兼容层，避免一次性改动所有查询、权限、看板和智能体逻辑。
- 完成迁移后再逐步让业务代码改读数字码。

## 报销主表修复映射

建议先只修 `expense_claims` 的模拟数据和历史异常阶段：

- `status=finance_review` → `status=submitted`，`approval_stage=财务审批`
- `approval_stage=manager_review` → `直属领导审批`
- `approval_stage=budget_review` → `预算管理者审批`
- `approval_stage=finance_review` → `财务审批`
- `status=pending_payment` → `approval_stage=待付款`
- `status=paid` → `approval_stage=已付款`
- `status=approved` 且为报销单 → `approval_stage=归档入账`
- `status=approved` 且为申请单 → `approval_stage=审批完成`
- `status=returned` → `approval_stage=待补充`
- `status=rejected` → `approval_stage=已驳回`
- `status=draft` → `approval_stage=待提交`

## 后续动作

- 已完成：只读审查数据库状态字段。
- 已完成：模拟数据修复脚本支持 dry-run 和中文阶段归一化。
- 已完成：新增报销状态注册表，统一状态码、标签、阶段别名与历史值归一化。
- 已完成：新增只读审计脚本 `audit_expense_claim_statuses.py`，用于修复前后核对状态一致性。
- 已验证：当前 498 张单据中 495 张模拟报销单需要归一化，集中在 `payment`、`completed`、`finance_review`、`manager_review` 等历史阶段值。
- 待确认：执行模拟数据修复脚本 `--apply --refresh-profiles`。
- 待确认：执行 mock 附件脚本 `--apply`。
- 待开发：如确认要数字状态码，新增状态字典/状态码迁移方案。