运单资料文件包下载 需求文档
版本 v1.0（定稿） · 运八平台端 · 2026-09-08
项 | 内容 |
功能名称 | 运单资料文件包下载（新增菜单） |
所属端 | 运八平台端（Web 管理后台） |
版本 | v1.0（定稿） |
编写日期 | 2026-09-08 |
确认记录 | 2026-09-08 需求方确认，13 项待确认事项全部采纳本文档建议方案（见第八章） |
需求来源 | 运营口头需求（2026-09-08），本文档为整理稿 |
关联术语 | 以 knowledge_base/01_standards/terminology.md 为准 |
原型 | resources/prototypes/anhuibaba_file_package.html（静态演示：任务列表 / 上传弹窗 / 文件包结构预览 / 失败清单） |
运营人员在线下归档、审计、对账等场景中，需要按批次收集运单资料：运单合同、电子回单，以及司机证件照片、车辆证件照片。目前只能逐单进入运单详情手工下载整理，效率低且易遗漏。
目标：提供一个“上传运单清单 → 系统自动生成资料文件包 → 任务完成后下载”的批量导出能力，按“司机+身份证+车辆”自动归批，资料按运单分目录组织、按规则命名，一次下载即可获得全部资料。
本期范围：仅做资料导出打包；不新增数据采集，合同、电子回单、司机证件、车辆证件均读取运八平台现有数据。
术语 | 定义 |
批次 | 上传清单中，运单在系统内的 司机姓名 + 司机身份证号 + 车牌号 三要素完全一致的一组运单。 |
文件包（批次包） | 一个批次生成的目录，内含该批次全部运单的运单包。 |
运单包 | 批次包下按运单维度建立的子目录，内含该运单的合同、电子回单及（仅最小序号运单）司机、车辆证件照片。 |
最小序号运单 | 同一批次内，上传清单中“序号”最小的运单。该运单的运单包额外包含司机证件照片、车辆证件照片。 |
运营人员 系统
│ ① 下载模板，填写运单清单并上传 │
│ ────────────────────────────────────→ │ ② 校验模板与数据（见 4.2.2）
│ │ ③ 创建打包任务（待处理 → 处理中）
│ ④ 任务列表查看处理进度 │ ④ 按批次分组 → 逐运单下载关联文件 → 组装文件包
│ ←──────────────────────────────────── │ ⑤ 任务完成（已完成 / 已完成·部分失败 / 失败）
│ ⑥ 点击“下载”获取文件包 zip │
│ ←──────────────────────────────────── │ ⑦ 返回 zip，记录下载审计日志
核心规则：司机+身份证+车辆算一批运单，生成一个文件包；文件包内按运单建运单包；批次内最小序号的运单包额外含司机及车辆证件照片，其余运单包只含合同与电子回单。
• 运八平台端新增独立菜单，菜单名称 “运单文件包”，挂在运单管理相关模块下。
• 页面结构：上方“上传任务”入口（模板下载 + 上传按钮），下方“任务列表”。
• 可见角色：运营人员；菜单需权限控制——文件包含身份证等敏感证件照片。
列名 | 类型 | 必填 | 说明 |
序号 | 整数 | 是 | 正整数，全文件内唯一；决定批次内“最小序号运单”的判定 |
货源单号 | 文本 | 是 | 系统内货源单号 |
运单号 | 文本 | 是 | 系统内运单号 |
• 文件格式：.xlsx；页面提供模板下载。
• 限制：单文件行数上限 2000 行；文件大小上限 10MB。
级别 | 规则 | 处理方式 |
文件级 | 非 xlsx 格式 / 列名缺失或不符 / 文件损坏 | 上传即拒绝，提示具体原因，不创建任务 |
文件级 | 行数、大小超上限 | 上传即拒绝 |
数据级 | 序号非正整数或重复 | 该行计入失败清单 |
数据级 | 货源单号 / 运单号为空 | 该行计入失败清单 |
数据级 | 运单号在系统中不存在 | 该行计入失败清单 |
数据级 | 文件中货源单号与该运单实际所属货源不一致 | 该行计入失败清单 |
数据级 | 同一运单号在文件中重复出现 | 重复行计入失败清单 |
数据级 | 运单缺少司机或车辆信息，无法归批 | 该行计入失败清单（原因：无法归批） |
处理原则：文件级错误整体拒绝；数据级错误剔除失败行后继续处理有效行，任务状态记为“已完成·部分失败”。
待处理 → 处理中 → 已完成 （全部有效行成功）
→ 已完成·部分失败 （部分行失败，可下载失败清单）
→ 失败 （系统级错误导致整体未生成文件包）
字段 | 说明 |
任务编号 | 系统生成 |
源文件名 | 上传的清单文件名 |
上传人 / 上传时间 | — |
任务状态 | 待处理 / 处理中 / 已完成 / 已完成·部分失败 / 失败 |
总行数 / 成功数 / 失败数 | 处理进度与结果统计 |
完成时间 | — |
操作 | 下载文件包（任务成功后显示）、下载失败清单（存在失败行时显示，xlsx，含序号/货源单号/运单号/失败原因） |
按有效行运单在系统内的 司机姓名 + 司机身份证号 + 车牌号 三要素归组，三要素完全一致归为一批，每批生成一个文件包。同一司机换车、同一车辆换司机都会拆分为不同批次。
运单资料_【任务编号】.zip ← 任务下载总包
├─ 【司机姓名】-【身份证号】-【车牌号】/ ← 批次文件包①
│ ├─ 1-YD20260901001-HY202609001-含司机及车辆证件/ ← 批次内最小序号运单包
│ │ ├─ 合同/（该运单全部合同文件）
│ │ ├─ 电子回单/（该运单全部支付记录对应回单）
│ │ ├─ 司机证件/（身份证、驾驶证、从业资格证等照片）
│ │ └─ 车辆证件/（行驶证、道路运输证等照片）
│ └─ 3-YD20260901003-HY202609001/ ← 批次内其余运单包
│ ├─ 合同/
│ └─ 电子回单/
└─ 【司机姓名】-【身份证号】-【车牌号】/ ← 批次文件包②
└─ 2-YD20260901002-HY202609002-含司机及车辆证件/ ← 单运单批次，仍含证件
• 任务下载总包命名：运单资料_【任务编号】.zip。
• 批次文件包命名：【司机姓名】-【身份证号】-【车牌号】。
• 运单包命名（需求明确）：最小序号运单 【序号】-【运单号】-【货源单号】-含司机及车辆证件；其余运单 【序号】-【运单号】-【货源单号】。
• 运单包内按 合同 / 电子回单 / 司机证件 / 车辆证件 建子目录；文件保留系统原文件名，重名时自动追加 (1)、(2)。
内容 | 最小序号运单 | 其余运单 | 数据来源 |
运单相关合同 | √ | √ | 运单关联的合同附件（以运单详情-合同附件为准，含承运合同；不含委托合同/框架合同） |
电子回单 | √ | √ | 运单全部支付记录对应的银行电子回单 |
司机证件照片 | √ | × | 该运单司机档案：身份证（人像面/国徽面）、驾驶证、从业资格证等 |
车辆证件照片 | √ | × | 该运单车辆档案：行驶证、道路运输证、车辆照片等 |
证件照片以批次内最小序号运单挂载的司机、车辆档案为准（同批次三要素一致，证件相同，故只随最小序号运单导出一份）。
• 某运单无合同或无电子回单：不阻断任务，对应子目录不生成，原因记入失败清单（如“无电子回单：运单无支付记录”）。
• 批次内最小序号运单因故剔除（校验失败/文件缺失）：重新计算批次内最小序号，证件照片改挂到新的最小序号运单。
• 单个文件下载失败自动重试 3 次，仍失败则记入失败清单，不阻断其余文件。
• 任务完成后，任务列表该行显示“下载”按钮，下载内容为任务总包 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 天，过期自动清理 |
敏感数据 | 司机身份证号、证件照片属敏感个人信息：菜单需权限控制、下载记审计日志；批次包命名含完整身份证号，包内数据仅限授权人员获取 |
幂等 | 同一任务重复点击下载不重复生成文件包 |
原 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. 任务失败、部分失败、重复下载、保留期过期等边界行为符合第五、六章定义。