Yb-QaAutomationHub/output/analysis/运单资料文件包下载需求_分析.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 风险对应测试点不得静默省略。