Files
shanxia2.0/docs/superpowers/specs/2026-08-18-reimburse-apply-batch-import-design.md
T
2026-08-19 09:14:37 +08:00

298 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 报销申请批量导入(Excel 下拉模板)— 设计文档
> **日期**: 2026-08-18
> **状态**: 已实现(待联调验收)
> **仓库**: shanxia2.0(`backend/` + `web-admin/`)
> **入口页**: `http://localhost:3006/#/bx/reimburse/apply`
> **界面模式**: P01 标准列表扩展(工具栏 + 导入弹窗);参考 Fresh Mint 工具栏按钮规则
> **实现路径**: 方案 A — 后端生成模板 + 后端导入
## 背景与问题
报销申请页已支持新增 / 编辑 / 删除。用户希望增加**批量导入**,并特别要求:
1. **费用项目**、**申请人**在 Excel 中为下拉框(非自由文本)。
2. 可**下载模板**,模板内**内置下拉数据**,并带**填写说明与示例行**,便于理解。
现状难点:
- 费用项目在页面是树形选择;Excel 只能做扁平下拉。
- 申请人选项接口 label 仅为昵称,易重名。
- 一单多明细;导入行模型需显式分组。
- 仓库内 CRM「下载模板」仅有表头,**无** DataValidation 下拉;本需求需新增能力。
## 已确认决策
| # | 决策 | 说明 |
|---|------|------|
| D1 | **实现路径 A** | 后端 `openpyxl` 动态生成模板(隐藏选项表 + DataValidation);后端解析导入;前端只做下载/上传与结果展示 |
| D2 | **行模型 B** | Excel **一行 = 一条明细**;相同「分组号」合成一张报销单 |
| D3 | **单头一致性** | 同组每一行都须填写申请人 / 报销日期 / 标题(标题可空),且**必须完全一致**;不一致则**整组失败** |
| D4 | **空分组号** | 允许为空;空则该行**单独成一张单** |
| D5 | **仅草稿** | 导入成功写入「待提交」草稿;不自动提交审批 |
| D6 | **标题可空** | 同组标题都空 → 按现有规则自动生成;若填写则同组必须相同 |
| D7 | **费用项范围** | 下拉含当前租户全部**启用**节点(含一级父节点),与页面 `check-strictly` 一致 |
| D8 | **部分成功** | 合法分组写入;失败组/行返回错误清单;不因单组失败回滚整文件 |
| D9 | **不做发票/附件** | v1 不导入关联发票与附件;用户可事后编辑草稿补票 |
| D10 | **模板含说明+示例** | 「填写说明」工作表 + 数据表内示例行(导入时跳过) |
---
## 一、目标与范围
### 目标
在报销申请列表提供「下载模板」「批量导入」,使用户能通过带下拉的 Excel 批量创建多张(含多明细)草稿报销单。
### 范围内
- 后端:导入模板生成、导入解析/分组/校验/写库、结果结构
- Web:`#/bx/reimburse/apply` 工具栏按钮 + 导入结果弹窗
- 费用项目全路径下拉、申请人唯一展示名下拉
- 与现有 `create_with_details` / `resolve_applicant` 对齐
### 范围外(v1)
- 发票、附件导入
- 导入后自动提交审批
- 按单号更新已有单据(仅新建)
- Excel 级联下拉(`INDIRECT`)
- 前端本地解析后循环调用单条创建 API
- `bx-mobile` / 小程序导入
---
## 二、Excel 模板形态
### 2.1 工作表
| 工作表 | 可见性 | 用途 |
|--------|--------|------|
| `报销导入` | 可见 | 用户填写;含表头、示例行、数据验证下拉 |
| `填写说明` | 可见 | 规则说明、列说明、常见错误 |
| `_选项_费用项目` | 隐藏 | A 列:下拉展示文案;B 列:id(内部) |
| `_选项_申请人` | 隐藏 | A 列:下拉展示文案;B 列:userId(内部) |
生成时按**当前登录用户**与租户实时查询选项,不使用静态 xlsx 文件。
### 2.2 `报销导入` 列定义
| 列名 | 必填 | 说明 |
|------|------|------|
| 分组号 | 否 | 相同非空值合成一张单;空 = 该行单独成单 |
| 申请人 | 是 | 下拉;展示 `昵称(工号)`(见 2.4) |
| 报销日期 | 是 | `YYYY-MM-DD`;同组必须一致 |
| 报销标题 | 否 | 同组都空则自动生成;填写则同组必须相同 |
| 费用项目 | 是 | 下拉;全路径,分隔符 ` / ` |
| 金额(元) | 是 | 数值且 > 0 |
| 报销事由 | 是 | 对应明细 `remark` |
| 发生时间 | 否 | `YYYY-MM-DD`;对应明细 `occur_date` |
### 2.3 下拉实现(openpyxl)
- 使用 `DataValidation(type="list")`,`formula1` 引用隐藏表列区域(如 `=_选项_费用项目!$A$2:$A$N`)。
- **禁止**把选项拼进公式字符串(255 字符限制)。
- `showErrorMessage=True`,提示「请从下拉列表选择」。
- 下拉仅为 UX;导入以服务端当前库精确匹配为准。
### 2.4 展示文案与匹配键
**费用项目**
- 展示:祖先全路径,分隔符为 ` / `(半角斜杠两侧各一空格),例如 `差旅费 / 市内交通`;一级节点仅本级名称。
- 仅 `status=启用` 的节点进入选项表。
- 若规范化后全路径冲突:在文案末尾追加 `(编码:xxx)` 或短 id 后缀保证唯一;导入匹配同一套规则。
- 匹配:导入单元格文本 trim 后与选项 A 列精确相等 → 得到 id;失败则该行错误。
**申请人**
- 展示:`{nickName}({userNo})`;`userNo` 为空时用稳定后缀(如用户 id 后 6 位)保证唯一。
- 有 `bx:reimburseApply:changeApplicant` 或 `super_admin`:选项 = 本租户全部有效用户。
- 无权限:选项仅当前用户;导入仍走 `ReimburseService.resolve_applicant`(无权限强制本人)。
- 匹配:精确匹配展示文案 → userId。
### 2.5 填写说明与示例(D10)
**`填写说明` 工作表**(要点,实现时可微调文案):
1. 请使用本系统「下载模板」获取最新文件;费用项/人员变更后请重新下载。
2. 推荐 Excel 或 WPS **桌面版**;在线表格可能丢失下拉。
3. **一行一条费用明细**;相同「分组号」合成一张报销单。
4. 分组号可空:空则该行单独成单。
5. 同一分组内:申请人、报销日期、报销标题必须每行都填且完全一致(标题可都留空以自动生成)。
6. 费用项目、申请人请用下拉选择,勿手改名称。
7. 灰色**示例行仅供参考,导入时自动跳过**,请从示例下方空行开始填写。
8. 导入结果为「待提交」草稿;发票请导入后在系统内关联。
9. 请勿修改或删除隐藏的 `_选项_*` 工作表。
**`报销导入` 示例行**(建议 2~3 行,浅灰底 +「示例」标识,导入跳过):
| 分组号 | 申请人 | 报销日期 | 报销标题 | 费用项目 | 金额 | 报销事由 | 发生时间 |
|--------|--------|----------|----------|----------|------|----------|----------|
| G1 | (当前用户展示名) | (今日) | | (选项表第一项路径) | 50.00 | 【示例】地铁通勤,请删除本行 | |
| G1 | (同上) | (同上) | | (选项表第二项或同第一项) | 300.00 | 【示例】住宿,请删除本行 | (昨日) |
| | (同上) | (同上) | | (任选项) | 20.00 | 【示例】空分组号单独成单 | |
示例行识别规则(按优先级):
1. 首列或隐藏标记列含 `__EXAMPLE__` / 约定标记;或
2. 「报销事由」以 `【示例】` 开头;或
3. 生成时写入的固定行号范围(模板内注释说明)。
推荐采用 **事由前缀 `【示例】` + 行底色**,解析简单、用户可见。
---
## 三、导入校验与写库
### 3.1 流程
```
上传 xlsx
→ 读「报销导入」表,校验表头
→ 跳过空行、示例行
→ 按分组号分桶(空分组号 → 每行独立桶)
→ 对每个分组:
校验单头一致(申请人/日期/标题)
解析申请人、费用项、金额、事由、发生时间
任一行失败 → 整组失败,不写库
全部通过 → create_with_details(draft)
→ 汇总 success / errors 返回
```
### 3.2 分组单头规则(D3 / D6)
对分组内所有数据行:
- `申请人`、`报销日期` 字符串 trim 后必须完全一致。
- `报销标题`:要么全部为空(自动生成),要么全部非空且文本完全一致;**不允许**组内「有的空有的不空」。
- 不一致 → 整组错误,例如:`同组申请人不一致` / `同组报销标题不能部分为空`。
### 3.3 字段校验
| 字段 | 规则 |
|------|------|
| 申请人 | 选项匹配成功;再 `resolve_applicant` |
| 报销日期 | 可解析为日期;建议规范为 `YYYY-MM-DD` |
| 费用项目 | 选项匹配且仍为启用 |
| 金额 | 数值且 > 0 |
| 报销事由 | 非空 trim |
| 发生时间 | 空或合法日期 |
### 3.4 写库
- 复用 `ReimburseService.create_with_details`(及 API 层 `_build_details_data` 同类逻辑)。
- 状态:待提交草稿(与页面「保存草稿」一致)。
- 不调用 submit;不写 `invoice_ids` / `invoice_links`。
- `create_by` = 当前操作人;`applicant_*` = 解析后的申请人。
- **部分成功(D8)**:成功组 commit(或按组 flush+commit 策略保证已成功组不因后续失败回滚);失败组仅进 `errors`。
- 建议上限:单次最多 **500** 行有效数据(可常量配置);超出返回 400 提示拆分。
### 3.5 错误与结果结构
整文件无法解析(非 xlsx、缺必要表头)→ HTTP 400。
可解析时业务成功响应(示意):
```json
{
"successGroups": 2,
"successRows": 3,
"failGroups": 1,
"failRows": 2,
"created": [
{ "groupNo": "G1", "applyId": "...", "applyCode": "..." }
],
"errors": [
{ "groupNo": "G2", "rows": [5, 6], "message": "同组申请人不一致" },
{ "groupNo": "", "rows": [8], "message": "费用项目「xxx」不存在或已停用" }
]
}
```
`rows` 为 Excel 行号(含表头时从 1 计,与用户所见一致;实现时在说明中写明)。
---
## 四、API 与前端
### 4.1 后端 API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/reimburses/import-template` | 下载模板(StreamingResponse xlsx) |
| POST | `/api/reimburses/import` | `multipart` 文件字段(如 `file`) |
- 认证:与报销申请其它接口相同(`get_bx_current_user`)。
- 菜单权限:与报销申请列表入口一致;不新开「导入」权限码(若产品后续要单独控权可再加)。
- 改申请人:不新增权限码,沿用 `bx:reimburseApply:changeApplicant`。
落点建议:
- 路由:`backend/app/api/bx/reimburse.py`
- 服务:`backend/app/services/bx/reimburse_import.py`(或同目录等价命名)
- Excel 工具:可抽 `backend/app/utils/excel_data_validation.py`(隐藏表 + list 验证),供后续其它导入复用
### 4.2 前端
页面:`web-admin/src/views/bx/reimburse/apply/index.vue`
工具栏(「新增报销申请」之后,**中性描边** `btn-ghost`):
1. **下载模板**
2. **批量导入**
导入弹窗:
- 选择 `.xlsx` / `.xls`
- 文案提示:请先下载最新模板;示例行自动跳过;结果为待提交草稿
- 上传后展示成功组数/行数、失败清单(分组号、行号、原因)
- 关闭后刷新列表
API 封装:`web-admin/src/api/bx`(或现有 `reimburseApi`)增加 `downloadImportTemplate`、`importExcel`。
**不做**:用 `ArtExcelImport` 前端解析后循环 `create`。
UI 约束:无遮罩模糊;按钮带图标;符合 Fresh Mint「仅首主按钮用主色」。
---
## 五、风险与验收
### 5.1 风险对策
| 风险 | 对策 |
|------|------|
| 下拉被绕过 | 服务端精确匹配当前库 |
| 昵称重名 | `昵称(工号)` 唯一展示 |
| 费用项同名 | 全路径;冲突加后缀 |
| 旧模板 | 说明要求重新下载;导入以当前主数据为准 |
| 无权限改申请人 | `resolve_applicant` 强制本人 |
| 示例入库 | `【示例】` 前缀跳过 |
| WPS/在线表丢失验证 | 说明推荐桌面版;服务端仍校验 |
### 5.2 验收标准
1. 可下载模板:含填写说明、灰色示例行、费用项与申请人下拉。
2. 示例行不入库。
3. 相同分组号且单头一致 → 一张多明细草稿。
4. 空分组号 → 每行一张单。
5. 同组单头不一致或主数据无法匹配 → 该组失败,其它组合法写入。
6. 无改申请人权限时,入库申请人仍为操作人本人。
7. 状态为待提交;不关联发票、不自动提交。
8. 工具栏按钮样式符合 Fresh Mint。
---
## 六、实现落点预览
| 层 | 路径 |
|----|------|
| API | `backend/app/api/bx/reimburse.py` |
| Service | `backend/app/services/bx/reimburse_import.py` |
| Excel 工具 | `backend/app/utils/`(DataValidation 辅助) |
| 前端页 | `web-admin/src/views/bx/reimburse/apply/index.vue` |
| 前端 API | `web-admin/src/api/bx`(reimburse 相关) |
下一步:经用户确认本 spec 后,使用 writing-plans 产出实现计划(`docs/superpowers/plans/`)。