Yb-QaAutomationHub/output/versions/运单资料文件包下载需求/v1/运单资料文件包下载需求_分析.md

# 运单资料文件包下载需求 结构化分析

> 生成时间: 2026-09-08
> 需求文档: requirements/运单资料文件包下载需求.md（v1.0 定稿）
> 原始载体: requirements/运单资料文件包下载需求.docx（同版本 Word 载体，内容一致，见 decisions/运单资料文件包下载需求_确认结论.md）
> 原型: resources/prototypes/anhuibaba_file_package.html（任务列表 / 上传弹窗 / 文件包结构预览 / 失败清单）
> 项目画像: knowledge_base/00_project/project_profile.md
> 确认状态: 需求方已于 2026-09-08 确认全部 13 项待确认事项（需求文档第八章），本文档无遗留待确认项

## 1. 需求背景

运营人员在线下归档、审计、对账场景中需要按批次收集运单资料：运单合同、电子回单，以及司机证件照片、车辆证件照片。目前只能逐单进入运单详情手工下载整理，效率低且易遗漏。

## 2. 目标

提供"上传运单清单 → 系统自动生成资料文件包 → 任务完成后下载"的批量导出能力。核心规则：**司机姓名+身份证号+车牌号三要素完全一致的运单归为一批，生成一个文件包**；文件包内按运单建运单包；批次内**最小序号**运单包额外含司机及车辆证件照片。

**本期范围**：仅做资料导出打包；不新增数据采集，合同、电子回单、司机证件、车辆证件均读取运八平台现有数据。

## 3. 用户角色

| 角色 | 职责 |
| :--- | :--- |
| 运营人员 | 唯一可见角色：下载模板、上传清单、查看任务进度、下载文件包/失败清单 |
| 系统后台 | 异步打包任务：校验、归批、逐运单下载关联文件、组装 zip、清理过期包 |
| 平台管理员 | 权限分配（菜单仅授权运营人员） |

## 4. 功能模块

### 4.1 菜单入口（运八平台端）
运单管理相关模块下新增独立菜单"运单文件包"。页面结构：上方"上传任务"入口（模板下载 + 上传按钮），下方"任务列表"。菜单需权限控制——文件包含身份证等敏感证件照片。

### 4.2 文件上传
- 模板列：序号（正整数，全文件唯一）/ 货源单号 / 运单号，格式 .xlsx，提供模板下载。
- 限制：单文件 ≤2000 行，≤10MB。
- 文件级校验（整体拒绝，不创建任务）：非 xlsx、列名缺失或不符、文件损坏、行数/大小超限。
- 数据级校验（该行计入失败清单）：序号非正整数或重复、货源单号/运单号为空、运单号不存在、货源单号与运单实际所属货源不一致、运单号文件内重复、运单缺司机或车辆信息无法归批。
- 处理原则：文件级错误整体拒绝；数据级错误剔除失败行后继续处理有效行。

### 4.3 任务
- 状态机：待处理 → 处理中 → 已完成（全部有效行成功）/ 已完成·部分失败（部分行失败）/ 失败（系统级错误整体未生成文件包）。
- 任务列表字段：任务编号、源文件名、上传人、上传时间、任务状态、总行数/成功数/失败数、完成时间、操作（下载文件包——任务成功后显示；下载失败清单——存在失败行时显示，xlsx，含序号/货源单号/运单号/失败原因）。

### 4.4 文件包生成
- 批次划分：按有效行运单在**系统内**的司机姓名+身份证号+车牌号归组。同一司机换车、同一车辆换司机拆分为不同批次。
- 目录结构（三层）：任务总包 `运单资料_【任务编号】.zip` → 批次包 `【司机姓名】-【身份证号】-【车牌号】` → 运单包 `【序号】-【运单号】-【货源单号】`（最小序号运单追加 `-含司机及车辆证件` 后缀）。
- 运单包子目录：合同 / 电子回单 / 司机证件 / 车辆证件；文件保留系统原文件名，重名自动追加 (1)、(2)。
- 内容矩阵：合同+电子回单 → 全部运单；司机证件+车辆证件 → 仅批次内最小序号运单（证件以最小序号运单挂载的司机、车辆档案为准）。
- 合同口径：以运单详情-合同附件为准（含承运合同），不含委托合同/框架合同。
- 电子回单口径：运单全部支付记录对应的银行电子回单。
- 文件缺失：不阻断任务，对应子目录不生成，原因记入失败清单；最小序号运单被剔除时重算最小序号并改挂证件；单个文件下载失败自动重试 3 次，仍失败记入失败清单。

### 4.5 下载
任务完成后任务列表显示"下载"按钮，下载任务总包 zip；支持重复下载，不重复生成（幂等）；下载记录审计日志（操作人、时间、任务编号）；按批次文件包单独下载本期不做。

## 5. 核心规则

### 5.1 归批与证件挂载
- 三要素 = 系统内司机姓名+身份证号+车牌号，完全一致归一批（非按上传行顺序、非按货源单号）。
- 最小序号 = 上传清单中该批次内序号最小的运单；序号全文件唯一。
- 单运单批次的运单包仍含司机及车辆证件。
- 失败行剔除后，证件挂载到批次内剩余运单中序号最小者。

### 5.2 校验与失败处理
- 文件级 → 整体拒绝；数据级 → 行级剔除继续。
- 无电子回单（如运单被关闭、无支付记录）：不阻断，子目录不生成，原因记失败清单。

### 5.3 异步与性能
- 打包为后台异步任务，上传后无需等待；任务列表可见进度（成功/失败条数）。
- 1000 单规模任务 30 分钟内完成。
- 多任务并发：后台排队处理，并发上限 1~2，防磁盘/带宽压力。

### 5.4 存储与幂等
- 文件包默认保留 7 天，过期自动清理，不可下载，需重新上传生成。
- 同一任务重复点击下载不重复生成文件包。
- 同一文件重复上传：允许，各自生成独立任务，不合并去重。

### 5.5 敏感数据合规
- 司机身份证号、证件照片属敏感个人信息：菜单需权限控制、下载记审计日志。
- 批次包命名含完整身份证号（确认决议 #3）；zip 不加密，依赖权限+审计（确认决议 #12）。

## 6. 状态流转

```
任务：待处理 → 处理中 → 已完成 | 已完成·部分失败 | 失败
失败/完成后可删除任务重新上传（系统异常场景）
文件包：已生成 →（7天）→ 过期清理 → 不可下载
```

## 7. 异常与边界场景（需求第六章汇总）

1. 模板格式/列名错误 → 上传即拒绝
2. 序号重复、非正整数 → 行级失败清单
3. 运单号不存在 / 货源单号不匹配 → 行级失败清单
4. 运单被关闭、未产生支付记录无电子回单 → 不阻断，记失败清单
5. 运单缺司机或车辆信息无法归批 → 行级失败清单
6. 批次内最小序号运单被剔除 → 证件改挂重算后的最小序号运单
7. 同一文件重复上传 → 允许，独立任务
8. 多任务并发 → 排队，并发上限 1~2
9. 文件包超保留期 → 不可下载，重新上传
10. 任务处理中系统异常 → 任务置"失败"，支持删除重传

## 8. 歧义标注与待确认项

> ✅ **无遗留待确认项**：原 v0.1 草稿 13 项待确认事项已于 2026-09-08 经需求方全部确认并采纳文档建议方案（需求文档第八章确认决议记录）：

| # | 事项 | 确认结论 |
|:---:|:---|:---|
| 1 | 菜单名称与挂载位置 | "运单文件包"，挂运单管理模块下 |
| 2 | 可见角色/权限 | 运营人员 |
| 3 | 批次文件包命名 | 司机姓名-身份证号-车牌号（含完整身份证号） |
| 4 | 运单包内子目录 | 合同/电子回单/司机证件/车辆证件 |
| 5 | "运单相关合同"范围 | 以运单详情-合同附件为准（含承运合同），不含委托合同/框架合同 |
| 6 | 货源单号与系统不一致时 | 该行失败 |
| 7 | 数据级校验失败行处理 | 剔除后继续，任务记"已完成·部分失败" |
| 8 | 失败行剔除后证件挂载 | 挂到批次内剩余运单的最小序号运单 |
| 9 | 行数/大小上限 | 2000 行 / 10MB |
| 10 | 文件包保留期 | 7 天 |
| 11 | 按批次包单独下载 | 本期不做 |
| 12 | zip 是否加密 | 不加密（依赖权限+审计） |
| 13 | 序号唯一性范围 | 全文件唯一 |

## 9. 需求条目清单（追溯链骨干，供测试点/用例/覆盖率审计引用）

| 需求条目 | 内容摘要 | 来源章节 | 优先级基准 |
| :--- | :--- | :--- | :---: |
| REQ-001 | 新增"运单文件包"菜单挂运单管理模块下，页面为上传入口+任务列表结构 | 4.1 | P0 |
| REQ-002 | 菜单权限控制：仅运营人员可见可操作（敏感数据） | 4.1/七 | P0 |
| REQ-003 | 模板下载：xlsx 模板，列=序号/货源单号/运单号 | 4.2.1 | P1 |
| REQ-004 | 上传限制：xlsx、≤2000 行、≤10MB | 4.2.1 | P1 |
| REQ-005 | 文件级校验整体拒绝：非 xlsx/列名缺失或不符/损坏/超限，不创建任务并提示具体原因 | 4.2.2 | P0 |
| REQ-006 | 数据级校验行级失败：序号非法/重复、单号为空、运单号不存在、货源不匹配、运单号文件内重复、无法归批 | 4.2.2 | P0 |
| REQ-007 | 数据级处理原则：剔除失败行继续有效行，任务记"已完成·部分失败" | 4.2.2 | P0 |
| REQ-008 | 任务状态机：待处理→处理中→已完成/已完成·部分失败/失败 | 4.3.1 | P0 |
| REQ-009 | 任务列表字段完整：任务编号/源文件名/上传人/上传时间/状态/总·成功·失败数/完成时间/操作 | 4.3.2 | P1 |
| REQ-010 | 批次划分：系统内司机姓名+身份证号+车牌号三要素归批，换车/换司机拆批 | 4.4.1 | P0 |
| REQ-011 | 三层目录结构与命名：总包/批次包/运单包命名规则，最小序号运单包带"-含司机及车辆证件"后缀 | 4.4.2 | P0 |
| REQ-012 | 运单包内容矩阵：合同+回单全员，司机证件+车辆证件仅最小序号运单；单运单批次仍含证件 | 4.4.3 | P0 |
| REQ-013 | 数据来源口径：合同=运单详情-合同附件（含承运不含委托/框架）；回单=全部支付记录银行电子回单；证件=司机/车辆档案 | 4.4.3 | P1 |
| REQ-014 | 子目录组织与重名处理：合同/电子回单/司机证件/车辆证件子目录，原文件名保留，重名追加(1)(2) | 4.4.2 | P1 |
| REQ-015 | 文件缺失处理：无合同/回单不阻断记失败清单；最小序号剔除重算改挂；单文件下载失败重试 3 次 | 4.4.4 | P0 |
| REQ-016 | 下载：任务完成后可下载总包 zip；重复下载不重复生成（幂等） | 4.5/七 | P0 |
| REQ-017 | 下载审计日志：操作人、时间、任务编号 | 4.5/七 | P0 |
| REQ-018 | 失败清单下载：存在失败行时显示，xlsx 含序号/货源单号/运单号/失败原因 | 4.3.2 | P1 |
| REQ-019 | 异步处理：后台打包，上传后无需等待，列表可见进度 | 七 | P1 |
| REQ-020 | 性能：1000 单规模任务 30 分钟内完成 | 七 | P1 |
| REQ-021 | 保留期：7 天过期自动清理，不可下载需重新上传 | 七/六#9 | P1 |
| REQ-022 | 并发控制：多任务排队，并发上限 1~2 | 六#8 | P1 |
| REQ-023 | 重复上传：同一文件重复上传允许，独立任务不合并 | 六#7 | P2 |
| REQ-024 | 系统异常：任务处理中异常置"失败"，支持删除后重新上传 | 六#10 | P1 |
| REQ-025 | 按批次文件包单独下载：本期不做（负向范围确认） | 4.5/八#11 | P3 |
| REQ-026 | zip 不加密，依赖权限控制+审计日志保障敏感数据（确认决议 #12） | 八#12 | P2 |

## 10. 项目差异化约束

- 所属端：运八平台端（Web 管理后台，Vue.js + Element UI SPA），非 C 端。
- 测试环境：管理端 https://ybxcx.ynyun8.com:8000/admin；超级管理员账号 super_admin（项目画像 §1）。
- 文件存储依赖华为云 OBS（项目画像 §6.1）——打包任务需从 OBS 拉取合同/回单/证件原件，OBS 不可用是打包失败的主要外部依赖风险。
- 敏感个人信息（身份证号、证件照片）导出场景：权限隔离 + 审计日志为合规必测项；批次包命名含完整身份证号放大泄露面。
- Excel 大文件处理：本项目既有 Excel 导出惯例默认 20000 条（项目画像 §8.3），本需求上传方向限 2000 行/10MB，测试需覆盖边界（2000/2001 行、10MB 临界）。
- 异步任务与并发：项目画像必测异常场景含"重复提交(幂等)、并发提交、超时重试、依赖服务不可用"——对应本需求重复下载幂等、并发任务排队、OBS 依赖失败重试 3 次。
- 与 requirements/安徽运八需求.md 为并行模块（相似度 0.105，见 decisions/运单资料文件包下载需求_确认结论.md），不共享数据口径，无冲突防御需求；历史缺陷防御重点关注文件打包下载类通用缺陷（见 knowledge_base/02_history/historical_defects.md）。
- 风险矩阵基线（output/analysis/运单资料文件包下载需求_风险评估.md）：P0=0，P1=1（RISK-AVAILABILITY：并发/重试/幂等），P2=4（资损/合规/数据/兼容性）；P1 风险对应测试点不得静默省略。