feat: 安徽运八需求全流水线输出同步 + 知识库/agents/资源文件更新

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

@@ -1,106 +1,189 @@
-# 安徽运八需求 分析报告
+# 安徽运八需求 结构化分析
 
-> 生成时间: 2026-07-13
-> 文档角色: 需求分析
-> 原始来源: `source_docs/requirements_raw/安徽运八需求.docx`
+> 生成时间: 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. 需求概述
+## 1. 需求背景
 
-根据国家税务总局及交通运输部对网络货运平台合规的监管要求，平台需将运单相关数据分阶段上报至省级网络货运信息监测系统（安徽运八）。上报分为三个阶段：装货完成上报、打款完成上报、开票完成上报，以及ETC发票上传。
+根据国家税务总局及交通运输部对网络货运平台合规的监管要求，平台需将税源地为安徽运八的运单相关数据分阶段上报至省级网络货运信息监测系统（安徽运八），其他税源地不走此逻辑。
 
-### 核心目标
-- 实现上报流程的自动化管理（自动触发 + 重试 + 通知）
-- 提供异常监控与核验结果展示
-- 提供向监管平台发起申诉的完整闭环能力
-- ETC发票上传作为税务抵扣凭证
+## 2. 目标
 
-### 涉及角色
-- 运营人员：看板监控、手动上传、发起申诉
-- 系统：自动触发上报、自动重试、自动更新字段
-- 监管平台（安徽运八）：核验上报数据、返回核验结果
-- 司机/财务：触发装货完成/打款完成/开票完成（间接触发上报）
+实现上报流程的自动化管理，并提供异常监控与向平台发起申诉的能力。上报分为三个阶段：装货完成上报、打款完成上报、开票完成上报，以及ETC发票上传。
 
-## 2. 功能模块分析
+## 3. 用户角色
 
-| 模块 | 功能 | 触发方式 | 依赖 | 关键风险 |
-| :--- | :--- | :--- | :--- | :--- |
-| 上报运单看板 | 汇总展示、筛选查询、导出 | 手动访问 | 无 | 数据量大时性能 |
-| 第一次上报 | 装货完成后上报基础运单数据 | 自动触发 | 运单装货完成 | 失败阻断后续上报 |
-| 第二次上报 | 打款完成后上报资金流水+轨迹 | 自动触发 | 第一次上报通过 | 7类核验，异常最多 |
-| 第三次上报 | 开票完成后上报发票数据 | 自动触发 | 第二次上报通过 | 发票验证失败 |
-| ETC发票上传 | 税务抵扣后上传ETC发票 | 手动触发 | 税务抵扣完成 | 税额计算精度 |
-| 异常申诉 | 核验异常→申诉→监管复核→结果 | 手动触发 | 核验异常 | 申诉闭环完整性 |
-| 上报日志 | 接口调用记录、请求/响应查看 | 手动访问 | 无 | 日志完整性 |
+| 角色 | 职责 |
+| :--- | :--- |
+| 平台运营人员 | 查看看板、发起申诉、监控上报状态 |
+| 系统自动 | 自动触发三阶段上报和ETC上传 |
+| 财务人员 | 打款操作（触发第二次上报） |
+| 安徽监管平台 | 接收上报数据、执行核验、反馈结果 |
 
-## 3. 关键业务规则
+## 4. 功能模块
 
-### 3.1 上报阶段依赖链
-```
-装货完成 → 第一次上报 → 核验通过 → 自动更新字段
-    ↓
-打款完成 → 第二次上报 → 7类核验（车辆资质/司机资质/资金流水/集中支付/合同/轨迹合规/运单重复）
-    ↓
-开票完成 → 第三次上报 → 发票验证
-    ↓
-税务抵扣 → ETC发票上传
-```
+### 4.1 上报运单看板
+集中展示所有上报阶段运单的汇总状态，支持按条件筛选（运单号/托运单号/货源单号模糊搜索、上报阶段、核验状态、申诉状态）、查看详情和发起申诉。
 
-### 3.2 重试策略
-- 所有上报阶段：失败后自动重试，最多3次
-- 3次全部失败：通知运营人员（站内信/其他方式）
-- 重试期间幂等保护：不产生重复上报
+### 4.2 委托合同上传（前置步骤）
+运单第一次上报前，需先将委托合同（框架）通过 `/api/dataUpload/mandateContractFrame`（Showdoc定义）上传至省平台。委托合同（框架）和委托合同二选一上报。合同文件可暂不传，后续通过修改接口补充。
 
-### 3.3 状态机
-```
-上传中(蓝) ──成功→ 已上传(绿)
-上传中(蓝) ──超时→ 上传失败(红) → 手动上传 → 上传中
-上传中(蓝) ──校验失败→ 异常(橙) → 查看详情
-```
+### 4.3 第一次上报（装货完成）
+运单装货完成后自动触发，仅上传货源税源地为安徽运八的运单。上报数据包含运单信息、托运方信息、收货方信息、司机信息、车辆信息、货物信息、保险信息等。核验通过后自动调用"修改第一次上报部分字段"接口。
 
-### 3.4 申诉状态机
-```
-未申诉 → 申诉中 → 申诉通过(绿) / 申诉驳回 → 重新申诉 → 申诉中
-```
+### 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. 数据量预估
+### 4.5 第三次上报（开票完成）
+发票开具完成后触发，上报数据包含运单信息、发票信息、油气发票信息等。
 
-| 对象 | 预估量级 | 说明 |
-| :--- | :--- | :--- |
-| 日上报运单数 | 1000-5000 | 根据平台运单量 |
-| 每运单轨迹点数 | 2-2000 | 取决于运输距离 |
-| 申诉并发量 | < 100/天 | 异常率较低 |
-| 日志保留期 | 建议≥90天 | 审计和排查需要 |
+### 4.6 ETC发票上传
+ETC发票税务抵扣成功后，由运营人员在运八系统**手动确认抵扣完成**，确认后系统触发ETC发票上传（非自动触发）。上传信息包含车牌号、车牌颜色、ETC发票号、不含税金额(invoiceAmount)、税率3%、税额、价税合计(totalPriceAndTax)、入口/出口收费站、交易时间等。
 
-## 5. 歧义标注
+### 4.7 异常申诉功能
+补全"异常查询 → 发起申诉 → 跟踪监管平台反馈 → 合规判断"的完整闭环。
 
-> ⚠️ 待确认：重试间隔时间未在需求中明确，建议确认（如30s/60s/120s递增）
-> 影响范围: 所有上报阶段的重试行为
-> 建议确认方向: 与产品和安徽运八平台确认合理的重试间隔
+### 4.8 上报日志
+记录所有上报接口的调用记录（请求/响应报文、HTTP状态码、响应时间），用于问题排查和审计。
 
-> ⚠️ 待确认：站内信通知的具体内容模板未定义
-> 影响范围: 运营人员通知体验
-> 建议确认方向: 确认通知应包含哪些字段（运单号/失败原因/重试次数/建议操作）
+## 5. 核心规则
 
-> ⚠️ 待确认：上报数据中"省份代码"字段默认值（当前项目属云南省=28，但本需求为安徽=34？）
-> 影响范围: 第一次上报司机信息省份代码
-> 建议确认方向: 确认安徽运八上报的省份代码应使用哪个值
+### 5.1 税源地过滤
+- 仅税源地为安徽运八的运单触发上报
+- 其他税源地（如云南=28）不触发任何上报
 
-> ⚠️ 待确认：导出Excel的数据量上限未定义
-> 影响范围: 看板导出功能
-> 建议确认方向: 确认是否需要限制单次导出条数（如最多10000条）
+### 5.2 上报阶段依赖链
+- 第一次上报是后续两次上报的基础
+- 第二次上报依赖第一次上报完成
+- 第三次上报依赖第二次上报完成
+- 后端必须做前置状态校验（非仅前端控制）
 
-## 6. 与项目画像的差异化分析
+### 5.3 自动重试机制
+- 各阶段上报失败后自动重试（最多3次）
+- 3次全部失败后告警通知运营人员
+- 重试期间禁止手动触发上传
 
-| 维度 | 项目画像（云南省） | 安徽运八需求 | 差异 |
-| :--- | :--- | :--- | :--- |
-| 上报省份 | 云南省(reportProvince=28) | 安徽省 | 省份代码需切换 |
-| 支付方式 | arpa_2 + 网商银行(浦发/快钱/光大) | 同平台支付体系 | 资金流水需关联现有支付渠道 |
-| 目标角色 | 运营/货主/车队长/司机/财务 | 主要面向运营人员 | 权限模型可复用 |
-| 测试环境 | ybxcx.ynyun8.com:8000 | 同环境 | 测试环境可复用 |
+### 5.4 核验规则
+- 第二次上报包含**17项独立核验**（API文档§4.1定义），比需求的7类更为细化
+- 核验异常可通过申诉机制向监管平台说明情况
+- 每项核验有独立的核验结果（verificationCode/verificationName/verificationState）和申诉入口
+- 申诉由安徽监管平台复核
 
-## 7. 风险总结
+> **核验项扩展说明（来源：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项×通过+异常）。
 
-| 风险ID | 类别 | 等级 | 说明 |
-| :--- | :--- | :---: | :--- |
-| RISK-FINANCIAL | 资损 | P1 | 资金流水金额不匹配、流水号重复可能导致财务数据错误 |
-| RISK-AVAILABILITY | 可用性 | P2 | 上报接口超时或不可用影响业务流程，需重试+告警兜底 |
+### 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（云企付二期）