QaAutomationHub/output/analysis/安徽运八需求_分析.md

# 安徽运八需求 结构化分析

> 生成时间: 2026-07-13（最后更新: 2026-07-14，根据14项确认决议）
> 需求文档: source_docs/requirements_raw/安徽运八需求.docx
> 重构需求: output/normalized_inputs/安徽运八需求/requirement_restructured.md（以API文档V1.0.2为查询+申诉权威数据源，以Showdoc文档为上报接口字段定义权威数据源）
> Showdoc上报接口文档: output/prototype/showdoc文档.md（5个上报接口 + FAQ）
> 项目画像: knowledge_base/00_project/project_profile.md

## 1. 需求背景

根据国家税务总局及交通运输部对网络货运平台合规的监管要求，平台需将税源地为安徽运八的运单相关数据分阶段上报至省级网络货运信息监测系统（安徽运八），其他税源地不走此逻辑。

## 2. 目标

实现上报流程的自动化管理，并提供异常监控与向平台发起申诉的能力。上报分为三个阶段：装货完成上报、打款完成上报、开票完成上报，以及ETC发票上传。

## 3. 用户角色

| 角色 | 职责 |
| :--- | :--- |
| 平台运营人员 | 查看看板、发起申诉、监控上报状态 |
| 系统自动 | 自动触发三阶段上报和ETC上传 |
| 财务人员 | 打款操作（触发第二次上报） |
| 安徽监管平台 | 接收上报数据、执行核验、反馈结果 |

## 4. 功能模块

### 4.1 上报运单看板
集中展示所有上报阶段运单的汇总状态，支持按条件筛选（运单号/托运单号/货源单号模糊搜索、上报阶段、核验状态、申诉状态）、查看详情和发起申诉。

### 4.2 委托合同上传（前置步骤）
运单第一次上报前，需先将委托合同（框架）通过 `/api/dataUpload/mandateContractFrame`（Showdoc定义）上传至省平台。委托合同（框架）和委托合同二选一上报。合同文件可暂不传，后续通过修改接口补充。

### 4.3 第一次上报（装货完成）
运单装货完成后自动触发，仅上传货源税源地为安徽运八的运单。上报数据包含运单信息、托运方信息、收货方信息、司机信息、车辆信息、货物信息、保险信息等。核验通过后自动调用"修改第一次上报部分字段"接口。

### 4.4 第二次上报（打款完成）
运费支付完成后自动触发，上报数据包含资金流水信息、车辆轨迹信息等。监管平台进行核验。⚠️ 根据网货企业端接口文档 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.5 第三次上报（开票完成）
发票开具完成后触发，上报数据包含运单信息、发票信息、油气发票信息等。

### 4.6 ETC发票上传
ETC发票税务抵扣成功后，由运营人员在运八系统**手动确认抵扣完成**，确认后系统触发ETC发票上传（非自动触发）。上传信息包含车牌号、车牌颜色、ETC发票号、不含税金额(invoiceAmount)、税率3%、税额、价税合计(totalPriceAndTax)、入口/出口收费站、交易时间等。

### 4.7 异常申诉功能
补全"异常查询 → 发起申诉 → 跟踪监管平台反馈 → 合规判断"的完整闭环。

### 4.8 上报日志
记录所有上报接口的调用记录（请求/响应报文、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 | **已取消** | （无） | （无） | **否·省平台只读** | 省平台侧操作取消申诉，我方系统不提供"取消申诉"功能，仅查询展示此状态 |

> **已取消(130)专项说明**: 
> - 状态130=已取消的触发在省平台侧（省平台管理员取消），非我方可操作。
> - 我方系统**不提供"取消申诉"按钮或接口**，不测试我方主动取消申诉的用例。
> - 申诉状态流转（我方视角）：未申诉(100) → 审核通过(110) [终态]；未申诉(100) → 审核不通过(120) → 重新申诉 → 未申诉(100)。
> - 看板筛选下拉值以API §4.4为准（未申诉/审核通过/审核不通过/已取消），其中130仅作筛选展示。

### 5.7 申诉单项约束（API §3.3）

- 接口 `POST /appeal/insert` 的 `verificationAbnormalItems` 参数说明为**"只支持单个异常项目申诉"**
- 每次申诉仅针对**一个**核验异常项
- 同一运单有多个异常项时，需分别发起多次申诉（每项一个申诉单）
- 申诉流程必须包含**异常项单选步骤**，不允许批量勾选后一次提交
- 传入多个异常项ID（如 `"120,160"`）时，接口应拒绝并返回错误提示

## 6. 数据字段（以Showdoc为权威字段定义）

> **授权来源**: Showdoc文档（`output/prototype/showdoc文档.md`）定义上报接口字段结构。关键精度要求：上报接口时间格式为 `yyyyMMddHHmmss`（14位），第二次上报金额保留3位小数（如整数以.000填充），ETC invoiceAmount为不含税金额。

### 6.1 第一次上报核心字段（Showdoc: firstUpload）
- waybillInfo（建单信息）: 13字段必选（含mileage可选）
- consignorInfo（托运人信息）: 7字段必选
- consigneeInfo（收货方信息）: 6字段必选（含unLoadingNationSubdivisionCode）
- driverInfo（司机信息）: 15字段必选（含registerDate、anchoredUrl）
- carInfo（接单车辆信息）: 20字段必选（含anchoredUrl）
- goodsInfos（货物信息）: 4字段/条必选（quantity=Double）
- insuranceInformation（保险信息）: 2字段可选

### 6.2 第二次上报核心字段（Showdoc: secondUpload）
- arrivalInfo（运抵信息）: 6字段必选（含startTicketFileUrl、arrivalTicketFileUrl）
- ownerStatements（货主流水）: 13字段必选（monetaryAmount=Double·3位小数）
- carrierStatements（承运人流水）: 14字段必选（含oilCardAmount·replaceAgreementFiles）
- carrierContractInfo（承运合同）: 18字段必选（含contractUrl·金额3位小数）
- ownerContractInfo（委托合同）: 18字段可选（委托合同与框架合同二选一）
- trackList（车辆轨迹）: 6字段/点必选（2~2000个点）

### 6.3 第三次上报核心字段（Showdoc: thirdUpload）
- invoice（货主发票）: 17字段必选（含invoiceUrl文件）
- oilGasInvoices（油气发票）: 选填，可多条

### 6.4 ETC发票核心字段（Showdoc: etcInvoiceUpload）
- etcInvoices（ETC发票）: **17字段/张**（invoiceAmount=不含税金额·保留2位小数·税率3%）

## 7. 状态流转

### 7.1 上报状态
上传中(蓝色) → 已上传(绿色) / 上传失败(红色) / 异常(橙色)

### 7.2 申诉状态（我方流转）
未申诉 → 申诉中 → 申诉通过 / 申诉驳回 → 重新申诉

> 已取消(130)由省平台侧操作，不纳入我方流转。

## 8. 歧义标注与待确认项（14项已全部确认 ✅）

> **更新 2026-07-14**: 以下14项全部通过用户确认决议。方框标记为确认结果。

### 8.1 核验项定义差异 ✅
> ✅ 确认: 以API文档§4.1 17项为准。17项核验全部展示，每项可独立申诉。测试点覆盖34条（17项×通过+异常）。

### 8.2 申诉状态枚举三版本不一致 ✅
> ✅ 确认: 以API §4.4为准。130=已取消为省平台侧操作，我方只读不提供取消申诉功能。原型UI状态映射已确认。

### 8.3 第三次上报列表字段差异 ✅
> ✅ 确认: 以原型15列为准。

### 8.4 看板申诉状态下拉值差异 ✅
> ✅ 确认: 以API §4.4为准（未申诉/审核通过/审核不通过/已取消），其中130为省平台只读状态。

### 8.5 原型详情弹窗字段数量差异 ✅
> ✅ 确认: 以接口Showdoc定义为准。

### 8.6 原型缺失车辆轨迹信息 ✅
> ✅ 确认: 为原原型Bug。增强版原型已包含轨迹表格。

### 8.7 技术细节已全部确认 ✅
> ✅ 待确认7: 自动重试间隔5s/15s/30s可用。
> ✅ 待确认8: ETC税率统一3%，税额按3%计算。
> ✅ 待确认9: 申诉超时告警阈值7个工作日可用。
> ✅ 待确认10: 安徽=34与云南=28逻辑隔离，无冲突。
> ✅ 待确认11: **Showdoc文档已读取**，字段定义以Showdoc为权威（金额3位小数，时间yyyyMMddHHmmss格式，ETC invoiceAmount=不含税金额，委托合同上传mandateContractFrame为前置步骤）。
> ✅ 待确认12: 里程申诉接口 /mileageAppeal/insert 为独立接口，纳入本期范围。
> ✅ 待确认13: ETC发票不含税金额(invoiceAmount)需在测试用例中体现。
> ✅ **新增**: ETC触发条件确认 — 税务抵扣成功后由运营人员人工确认，非自动触发。

## 9. 项目差异化约束

- 省份代码: 安徽=34（非云南=28）
- 该需求为新增模块，与现有云南上报逻辑隔离
- 测试环境管理端: https://ybxcx.ynyun8.com:8000/admin
- 支付方式: arpa_2（云企付二期）