xst
11 KiB
安徽运八需求 结构化分析
生成时间: 2026-07-13 需求文档: source_docs/requirements_raw/安徽运八需求.docx 重构需求: output/normalized_inputs/安徽运八需求/requirement_restructured.md（以API文档V1.0.2为权威数据源） 项目画像: knowledge_base/00_project/project_profile.md
1. 需求背景
根据国家税务总局及交通运输部对网络货运平台合规的监管要求，平台需将税源地为安徽运八的运单相关数据分阶段上报至省级网络货运信息监测系统（安徽运八），其他税源地不走此逻辑。
2. 目标
实现上报流程的自动化管理，并提供异常监控与向平台发起申诉的能力。上报分为三个阶段：装货完成上报、打款完成上报、开票完成上报，以及ETC发票上传。
3. 用户角色
| 角色 | 职责 |
|---|---|
| 平台运营人员 | 查看看板、发起申诉、监控上报状态 |
| 系统自动 | 自动触发三阶段上报和ETC上传 |
| 财务人员 | 打款操作（触发第二次上报） |
| 安徽监管平台 | 接收上报数据、执行核验、反馈结果 |
4. 功能模块
4.1 上报运单看板
集中展示所有上报阶段运单的汇总状态，支持按条件筛选（运单号/托运单号/货源单号模糊搜索、上报阶段、核验状态、申诉状态）、查看详情和发起申诉。
4.2 第一次上报（装货完成）
运单装货完成后自动触发，仅上传货源税源地为安徽运八的运单。上报数据包含运单信息、托运方信息、收货方信息、司机信息、车辆信息、货物信息、保险信息等。核验通过后自动调用"修改第一次上报部分字段"接口。
4.3 第二次上报（打款完成）
运费支付完成后自动触发，上报数据包含资金流水信息、车辆轨迹信息等。监管平台进行核验。⚠️ 根据网货企业端接口文档 V1.0.2 §4.1，核验项从需求描述的7类扩展为API定义的17项独立核验项：100=委托合同、120=承运合同、130=实时定位、140=运单时间逻辑、150=车辆资质、160=道路运输证、170=驾驶证、180=从业资格证、190=车辆重复、200=司机重复、210=车辆轨迹、220=运费收款、230=公司统一收款、240=集中支付、250=资金流水、260=发票信息、270=非通行车辆可开票。每项有独立的核验结果和申诉入口。
4.4 第三次上报（开票完成）
发票开具完成后触发，上报数据包含运单信息、发票信息、油气发票信息等。
4.5 ETC发票上传
用于上报车辆通行高速公路的ETC发票信息，作为税务抵扣凭证。需在税务抵扣完成后进行。
4.6 异常申诉功能
补全"异常查询 → 发起申诉 → 跟踪监管平台反馈 → 合规判断"的完整闭环。
4.7 上报日志
记录所有上报接口的调用记录（请求/响应报文、HTTP状态码、响应时间），用于问题排查和审计。
5. 核心规则
5.1 税源地过滤
- 仅税源地为安徽运八的运单触发上报
- 其他税源地（如云南=28）不触发任何上报
5.2 上报阶段依赖链
- 第一次上报是后续两次上报的基础
- 第二次上报依赖第一次上报完成
- 第三次上报依赖第二次上报完成
- 后端必须做前置状态校验（非仅前端控制）
5.3 自动重试机制
- 各阶段上报失败后自动重试（最多3次）
- 3次全部失败后告警通知运营人员
- 重试期间禁止手动触发上传
5.4 核验规则
- 第二次上报包含17项独立核验（API文档§4.1定义），比需求的7类更为细化
- 核验异常可通过申诉机制向监管平台说明情况
- 每项核验有独立的核验结果（verificationCode/verificationName/verificationState）和申诉入口
- 申诉由安徽监管平台复核
核验项扩展说明（来源：API §4.1）: 原始需求仅描述7大类核验（运单重复/车辆资质/司机资质/集中支付/资金流水/合同/轨迹合规），但API文档§4.1定义了完整的17项独立核验项（100=委托合同, 120=承运合同, 130=实时定位, 140=运单时间逻辑, 150=车辆资质, 160=道路运输证, 170=驾驶证, 180=从业资格证, 190=车辆重复, 200=司机重复, 210=车辆轨迹, 220=运费收款, 230=公司统一收款, 240=集中支付, 250=资金流水, 260=发票信息, 270=非通行车辆可开票）。每项有独立的核验结果和申诉入口，测试覆盖需从14条（7类×通过+异常）扩展到34条（17项×通过+异常）。
5.5 API接口清单（来自网货企业端接口文档 V1.0.2）
| 接口 | URL | 方法 | 说明 |
|---|---|---|---|
| 获取token | /sys/login | POST | JWT认证 |
| 上传申诉附件 | /appeal/uploadFile | POST | 文件上传 |
| 提交申诉运单 | /appeal/insert | POST | 发起申诉 |
| 查询异常运单信息 | /verificationSummary/page | POST | 分页查询，含abnormalDetails（17项核验明细） |
| 查询申诉进度 | /appeal/page | POST | 分页查询，含审核状态/审核人/取消/撤回 |
| 查询运单核验详情 | /verificationSummary/verificationDetail | POST | 单运单核验明细列表 |
| 查询发票合规 | /verificationSummary/cargoOwnerInvoiceInfo | POST | 判断托运人发票是否系统核验合规（需求未提及！） |
| 运单里程核验查询 | /verificationSummary/mileageVerificationInfo | POST | 批量查询运单里程核验状态 |
| 运单里程申诉 | /mileageAppeal/insert | POST | 提交里程申诉（需求未提及的新功能！） |
5.6 申诉状态枚举（以API §4.4为权威）
| Code | API名称(§4.4权威) | 原始需求对应 | 原型对应 | 说明 |
|---|---|---|---|---|
| 100 | 未申诉 | 未申诉 + 申诉中 | 未申诉 + 待省平台反馈 + 反馈处理中 | 含已提交但省平台尚未审核的情况（申诉"进行中"通过 abnormalDetails[].state=110 标识） |
| 110 | 审核通过 | 申诉通过 | 申诉通过 | 终态 |
| 120 | 审核不通过 | 申诉驳回 | 申诉驳回 | 可重新申诉 |
| 130 | 已取消 | （无） | （无） | API独有，原始需求未提及此状态 |
以API文档§4.4为权威数据源，所有开发实现和测试验证均以此枚举为准。
⚠️ 待确认:
- 原型中"待省平台反馈"和"反馈处理中"为UI层面的展示状态，非后端枚举值，需确认UI状态与API枚举的映射关系。
- API有"已取消"状态(130)但需求和原型均未体现——需确认是否支持申诉取消及触发权限。
- 看板筛选下拉值以API §4.4为准（未申诉/审核通过/审核不通过/已取消）。
5.7 申诉单项约束（API §3.3）
- 接口
POST /appeal/insert的verificationAbnormalItems参数说明为**"只支持单个异常项目申诉"** - 每次申诉仅针对一个核验异常项
- 同一运单有多个异常项时，需分别发起多次申诉（每项一个申诉单）
- 申诉流程必须包含异常项单选步骤，不允许批量勾选后一次提交
- 传入多个异常项ID（如
"120,160"）时，接口应拒绝并返回错误提示
6. 数据字段
6.1 第一次上报核心字段
- waybillInfo（建单信息）: 13字段（必选）
- consignorInfo（托运人信息）: 7字段（必选）
- consigneeInfo（收货方信息）: 5字段（必选）
- driverInfo（司机信息）: 13字段（必选）
- carInfo（接单车辆信息）: 19字段（必选）
- goodsInfos（货物信息）: 4字段/条（必选，可多条）
- insuranceInformation（保险信息）: 2字段（可选）
6.2 第二次上报新增字段
- 资金流水信息: 10字段（必选）
- 车辆轨迹信息: 6字段/点（必选，2~2000个点）
6.3 第三次上报核心字段
- 发票信息: 17字段（必选）
- 油气发票信息（可选，可多条）
6.4 ETC发票核心字段
- ETC发票信息: 18字段/张
7. 状态流转
7.1 上报状态
上传中(蓝色) → 已上传(绿色) / 上传失败(红色) / 异常(橙色)
7.2 申诉状态
未申诉 → 申诉中 → 申诉通过 / 申诉驳回 → 重新申诉
8. 歧义标注与待确认项
8.1 核验项定义差异（P0 阻断）
⚠️ 待确认1: 需求文档将核验项描述为7大类，但API文档§4.1定义了17项独立核验项。测试点已按API文档17项逐项覆盖（TP-C-006
TP-C-019 保留原7类 + TP-C-026TP-C-049 补充12项），需与产品和开发确认最终核验粒度。
8.2 申诉状态枚举三版本不一致（P1）
⚠️ 待确认2: 申诉状态在需求（未申诉/申诉中/申诉通过/申诉驳回）、原型（未申诉/待省平台反馈/反馈处理中/申诉通过/申诉驳回）、API（未申诉100/审核通过110/审核不通过120/已取消130）三处不一致，需确认最终版本。详见 §5.6 对照表。
8.3 第三次上报列表字段差异（P1）
⚠️ 待确认3: 原型列表比需求多4个字段（税率、销售方名称、受票方名称、油气票张数），共15列（含checkbox），需确认最终字段列表。
8.4 看板申诉状态下拉值差异（P1）
⚠️ 待确认4: 原型看板申诉状态下拉值为"未申诉/待省平台反馈/反馈处理中/申诉通过/申诉驳回"，与需求"未申诉/申诉中/申诉通过/申诉驳回"不一致，需确认最终版本。
8.5 原型详情弹窗字段数量差异（P1）
⚠️ 待确认5: 原型详情弹窗各分组字段数量与需求/接口文档不一致（原型大幅简化），需确认以哪个为准。
8.6 原型缺失车辆轨迹信息（P1）
⚠️ 待确认6: 原型第二次上报详情弹窗中车辆轨迹信息缺失——是原型bug还是实际不展示？
8.7 技术细节待确认
⚠️ 待确认7: 自动重试的具体间隔时间（需求中未明确），当前假设为5s/15s/30s，需与技术方案确认。 ⚠️ 待确认8: ETC税额边界值（0.01元→税额=0.00）的四舍五入规则需与财务确认。 ⚠️ 待确认9: 申诉超时告警阈值（需求中未明确），当前假设为7个工作日，需与产品确认。 ⚠️ 待确认10: 安徽运八与现有云南运八上报逻辑是否存在字段/接口冲突，需人工确认。 ⚠️ 待确认11: 上报接口文档密码保护（szjj@2023），字段定义以接口文档为准，需确认需求与接口文档一致性。 ⚠️ 待确认12: 里程申诉接口 /mileageAppeal/insert 为需求未提及的新功能，需确认是否纳入本期范围。 ⚠️ 待确认13: ETC发票详情含"不含税金额"字段是否需要在测试用例中体现。
9. 项目差异化约束
- 省份代码: 安徽=34（非云南=28）
- 该需求为新增模块，与现有云南上报逻辑隔离
- 测试环境管理端: https://ybxcx.ynyun8.com:8000/admin
- 支付方式: arpa_2（云企付二期）