Yb-QaAutomationHub/requirements/运单资料文件包下载需求.md

运单资料文件包下载需求

文档角色：正式维护版需求 原始来源：requirements\运单资料文件包下载需求.md 标准化来源：output\normalized_inputs\运单资料文件包下载需求\requirement.md 输入类型：md

维护信息

• 当前维护文件：requirements\运单资料文件包下载需求.md
• 最近维护说明：暂无

技术方案来源

• 未关联技术方案

正式维护内容

运单资料文件包下载 需求文档

项	内容
功能名称	运单资料文件包下载（新增菜单）
所属端	运八平台端（Web 管理后台）
版本	v1.0（定稿）
编写日期	2026-09-08
确认记录	2026-09-08 需求方确认，13 项待确认事项全部采纳本文档建议方案（见第八章）
原型	resources/prototypes/anhuibaba_file_package.html（静态演示：任务列表 / 上传弹窗 / 文件包结构预览 / 失败清单）
需求来源	运营口头需求（2026-09-08），本文档为整理稿
关联术语	以 knowledge_base/01_standards/terminology.md 为准

---

一、需求背景与目标

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

目标：提供一个"上传运单清单 → 系统自动生成资料文件包 → 任务完成后下载"的批量导出能力，按"司机+身份证+车辆"自动归批，资料按运单分目录组织、按规则命名，一次下载即可获得全部资料。

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

---

二、名词定义

术语	定义
批次	上传清单中，运单在系统内的 司机姓名 + 司机身份证号 + 车牌号 三要素完全一致的一组运单。
文件包（批次包）	一个批次生成的目录，内含该批次全部运单的运单包。
运单包	批次包下按运单维度建立的子目录，内含该运单的合同、电子回单及（仅最小序号运单）司机、车辆证件照片。
最小序号运单	同一批次内，上传清单中"序号"最小的运单。该运单的运单包额外包含司机证件照片、车辆证件照片。

---

三、整体流程

运营人员                                系统
  │ ① 下载模板，填写运单清单并上传          │
  │ ────────────────────────────────────→ │ ② 校验模板与数据（见 4.2.2）
  │                                       │ ③ 创建打包任务（待处理 → 处理中）
  │ ④ 任务列表查看处理进度                 │ ④ 按批次分组 → 逐运单下载关联文件 → 组装文件包
  │ ←──────────────────────────────────── │ ⑤ 任务完成（已完成 / 已完成·部分失败 / 失败）
  │ ⑥ 点击"下载"获取文件包 zip             │
  │ ←──────────────────────────────────── │ ⑦ 返回 zip，记录下载审计日志

核心规则：司机+身份证+车辆算一批运单，生成一个文件包；文件包内按运单建运单包；批次内最小序号的运单包额外含司机及车辆证件照片，其余运单包只含合同与电子回单。

---

四、功能需求

4.1 菜单入口

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

4.2 文件上传

4.2.1 上传模板

列名	类型	必填	说明
序号	整数	是	正整数，全文件内唯一；决定批次内"最小序号运单"的判定
货源单号	文本	是	系统内货源单号
运单号	文本	是	系统内运单号

• 文件格式：.xlsx；页面提供模板下载。
• 限制：单文件行数上限 2000 行；文件大小上限 10MB。

4.2.2 校验规则

级别	规则	处理方式
文件级	非 xlsx 格式 / 列名缺失或不符 / 文件损坏	上传即拒绝，提示具体原因，不创建任务
文件级	行数、大小超上限	上传即拒绝
数据级	序号非正整数或重复	该行计入失败清单
数据级	货源单号 / 运单号为空	该行计入失败清单
数据级	运单号在系统中不存在	该行计入失败清单
数据级	文件中货源单号与该运单实际所属货源不一致	该行计入失败清单
数据级	同一运单号在文件中重复出现	重复行计入失败清单
数据级	运单缺少司机或车辆信息，无法归批	该行计入失败清单（原因：无法归批）

处理原则：文件级错误整体拒绝；数据级错误剔除失败行后继续处理有效行，任务状态记为"已完成·部分失败"。

4.3 任务

4.3.1 任务状态

待处理 → 处理中 → 已完成          （全部有效行成功）
              → 已完成·部分失败    （部分行失败，可下载失败清单）
              → 失败              （系统级错误导致整体未生成文件包）

4.3.2 任务列表

字段	说明
任务编号	系统生成
源文件名	上传的清单文件名
上传人 / 上传时间	—
任务状态	待处理 / 处理中 / 已完成 / 已完成·部分失败 / 失败
总行数 / 成功数 / 失败数	处理进度与结果统计
完成时间	—
操作	下载文件包（任务成功后显示）、下载失败清单（存在失败行时显示，xlsx，含序号/货源单号/运单号/失败原因）

4.4 文件包生成规则

4.4.1 批次划分

按有效行运单在系统内的 司机姓名 + 司机身份证号 + 车牌号 三要素归组，三要素完全一致归为一批，每批生成一个文件包。同一司机换车、同一车辆换司机都会拆分为不同批次。

4.4.2 目录结构与命名

运单资料_【任务编号】.zip                            ← 任务下载总包
├─ 【司机姓名】-【身份证号】-【车牌号】/              ← 批次文件包①
│   ├─ 1-YD20260901001-HY202609001-含司机及车辆证件/   ← 批次内最小序号运单包
│   │   ├─ 合同/（该运单全部合同文件）
│   │   ├─ 电子回单/（该运单全部支付记录对应回单）
│   │   ├─ 司机证件/（身份证、驾驶证、从业资格证等照片）
│   │   └─ 车辆证件/（行驶证、道路运输证等照片）
│   └─ 3-YD20260901003-HY202609001/                   ← 批次内其余运单包
│       ├─ 合同/
│       └─ 电子回单/
└─ 【司机姓名】-【身份证号】-【车牌号】/              ← 批次文件包②
    └─ 2-YD20260901002-HY202609002-含司机及车辆证件/   ← 单运单批次，仍含证件

• 任务下载总包命名：运单资料_【任务编号】.zip。
• 批次文件包命名：【司机姓名】-【身份证号】-【车牌号】。
• 运单包命名（需求明确）：
  • 最小序号运单：【序号】-【运单号】-【货源单号】-含司机及车辆证件
  • 其余运单：【序号】-【运单号】-【货源单号】
• 运单包内按 合同 / 电子回单 / 司机证件 / 车辆证件 建子目录；文件保留系统原文件名，重名时自动追加 (1)、(2)。

4.4.3 各运单包内容

内容	最小序号运单	其余运单	数据来源
运单相关合同	✅	✅	运单关联的合同附件（以运单详情-合同附件为准，含承运合同；不含委托合同/框架合同）
电子回单	✅	✅	运单全部支付记录对应的银行电子回单
司机证件照片	✅	❌	该运单司机档案：身份证（人像面/国徽面）、驾驶证、从业资格证等
车辆证件照片	✅	❌	该运单车辆档案：行驶证、道路运输证、车辆照片等

证件照片以批次内最小序号运单挂载的司机、车辆档案为准（同批次三要素一致，证件相同，故只随最小序号运单导出一份）。

4.4.4 文件缺失处理

• 某运单无合同或无电子回单：不阻断任务，对应子目录不生成，原因记入失败清单（如"无电子回单：运单无支付记录"）。
• 批次内最小序号运单因故剔除（校验失败/文件缺失）：重新计算批次内最小序号，证件照片改挂到新的最小序号运单。
• 单个文件下载失败自动重试 3 次，仍失败则记入失败清单，不阻断其余文件。

4.5 下载

• 任务完成后，任务列表该行显示"下载"按钮，下载内容为任务总包 zip（含全部批次文件包）。
• 支持重复下载，不重复生成。
• 下载行为记录审计日志（操作人、时间、任务编号）——文件包含身份证等敏感个人信息。
• 按批次文件包单独下载：本期不做。

---

五、上传示例与生成结果

上传清单：

序号	货源单号	运单号	司机（系统内）	车牌（系统内）
1	HY202609001	YD20260901001	张三	皖A12345
2	HY202609002	YD20260901002	李四	皖B67890
3	HY202609001	YD20260901003	张三	皖A12345

生成结果：

• 批次① = 序号 1、3（张三+同一身份证+皖A12345）→ 文件包"张三-340102199001011234-皖A12345"，内含运单包 1-…-含司机及车辆证件（合同+回单+张三证件+皖A12345 证件）和 3-…（仅合同+回单）。
• 批次② = 序号 2（李四）→ 文件包"李四-340102199001015678-皖B67890"，运单包 2-…-含司机及车辆证件（单运单批次，仍含司机及车辆证件）。

---

六、异常与边界场景汇总

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

---

七、非功能需求

项	要求
异步处理	打包为后台异步任务，任务列表可见进度（成功/失败条数）；上传后无需等待
性能	1000 单规模任务 30 分钟内完成
保留期	生成的文件包默认保留 7 天，过期自动清理
敏感数据	司机身份证号、证件照片属敏感个人信息：菜单需权限控制、下载记审计日志；批次包命名含完整身份证号，包内数据仅限授权人员获取
幂等	同一任务重复点击下载不重复生成文件包

---

八、确认决议记录（2026-09-08）

原 v0.1 草稿 13 项待确认事项，经需求方确认全部采纳文档建议方案，逐项记录如下：

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

---

九、验收要点

1. 上传合法清单后任务创建成功，完成后可下载 zip；zip 内批次划分与目录命名符合 4.4 规则。
2. 同一批次内仅最小序号运单包含司机、车辆证件照片，其余运单仅含合同与电子回单。
3. 单运单批次的运单包仍包含司机及车辆证件照片。
4. 各类非法数据按 4.2.2 处理，失败清单内容准确可下载。
5. 任务失败、部分失败、重复下载、保留期过期等边界行为符合第五、六章定义。