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

output/versions/安徽运八需求/v4/normalized_inputs/requirement.md

@@ -0,0 +1,164 @@
+# 安徽运八需求
+
+> 文档角色：需求文档
+> 原始来源：`source_docs\requirements_raw\安徽运八需求.docx`
+
+安徽运八需求
+一、需求概述
+根据国家税务总局及交通运输部对网络货运平台合规的监管要求，平台需将税源地为安徽运八的运单相关数据分阶段上报至省级网络货运信息监测系统（安徽运八），其他税源地不走此逻辑。上报分为三个阶段：装货完成上报、打款完成上报、开票完成上报，以及ETC发票上传。本功能模块旨在实现上报流程的自动化管理，并提供异常监控与向平台发起申诉的能力。
+二、功能说明
+2.1 上报运单看板
+· 功能描述
+上报运单看板是系统的首页，集中展示所有上报阶段运单的汇总状态，支持按条件筛选、查看详情和发起申诉。
+· 查询条件
+运单号/托运单号/货源单号：模糊搜索
+上报阶段：全部 / 第一次上报 / 第二次上报 / 第三次上报
+核验状态：全部 / 异常 / 通过
+申诉状态：全部 / 未申诉 / 申诉中 / 申诉通过 / 申诉驳回
+操作按钮：查询、重置、导出
+· 列表字段
+货源单号、运单号、托运单号、车牌号、司机姓名、
+托运方名称、上报阶段、核验状态、申诉状态、异常项、
+货物名称、合同金额、最新核验时间、操作（申诉/进度/详情）
+2.2 第一次上报（装货完成）
+功能描述
+第一次上报在运单装货完成后自动触发（仅上传货源税源地为安徽运八的运单，其他税源地无需上传），上报数据包含运单信息、托运方信息、收货方信息、司机信息、车辆信息、货物信息、保险信息等。
+特殊说明
+• 上报完成后，若安徽运八平台核验通过，系统会自动调用“修改第一次上报部分字段”接口，更新装货后可能发生变化的字段（如实际里程），无需人工干预。
+• 若上报失败，系统需要自动重试（最多3次），若仍失败则通过系统站内信或者其他方式通知运营人员。
+• 第一次上传是后续两次上传的基础，若失败会导致后续上报无法进行，需重点关注。
+上报状态规则
+| 状态 | 说明 | 操作按钮 | 标签颜色 |
+| 上传中 | 数据正在上报中 | 无 | 蓝色 |
+| 已上传 | 上报成功 | 无 | 绿色 |
+| 上传失败 | 上报超时 | 手动上传 | 红色 |
+| 异常 | 数据校验不通过 | 详情查看异常原因 | 橙色 |
+列表字段
+货源单号、运单号、托运单号、车牌号、司机姓名、托运方名称、业务类型、货物名称、装货地址、卸货地址、运输里程、合同编号、上报状态、操作（详情）
+详情弹窗字段分组
+详情弹窗按以下子对象分组展示：
+建单信息（必选，13字段）：上游企业委托运输单号、本运单单号、托运人建单时间、网络货运经营者名称、统一社会信用代码、道路运输经营许可证编号、业务类型代码、运输组货方式代码、司机接单时间、司机起运时间、承运合同编号、委托合同编号（可选）、运输里程（可选）
+托运人信息（必选，7字段）：托运人名称、托运人统一社会信用代码、框架合同编号（可选）、装货地点、装货经度、装货纬度、装货地行政区划代码
+收货方信息（必选，5字段）：收货方名称、收货方统一社会信用代码/身份证号、收货地点、收货经度、收货纬度
+司机信息（必选，13字段）：司机姓名、身份证号、驾驶证号、驾驶证发证机关、从业资格证号、从业资格证有效期起、从业资格证有效期至、税务登记证号、手机号、驾驶证有效期起、驾驶证有效期至、准驾车型、省份代码
+接单车辆信息（必选，19字段）：车牌号、车牌颜色编码、号牌种类、车辆识别代号VIN)、车主姓名/单位名称、车主证件号、使用性质、车辆类型、能源类型、注册日期、发证日期、发证机关、核定载质量吨)、总质量吨)、道路运输证号、挂车牌照号（可选）、行驶证档案编号（可选）、道路运输证有效期起（可选）、道路运输证有效期至（可选）
+货物信息（必选，可多条，4字段）：货物名称、货物类型代码、货物量、计量单位
+保险信息（可选，2字段）：保险单号、保险公司名称
+异常信息：核验状态、异常原因、异常时间、处理状态
+2.3 第二次上报（打款完成）
+功能描述
+第二次上报在运费支付完成后系统自动触发，上报数据包含运抵信息、货主资金流水、承运人资金流水、承运合同信息、委托合同信息、车辆轨迹信息等。
+特殊说明
+• 第二次上传核验项最多，是最容易出现异常的环节，需要重点关注。
+• 若资金流水单号重复，会导致上报失败，系统会自动检查并提示。
+• 车辆轨迹点位数量不足或偏差过大，会导致"车辆轨迹合规"核验异常，可通过"补传轨迹"功能补充轨迹数据。
+• 若上报失败，系统会自动重试（最多3次），若仍失败则告警通知运营人员。
+列表字段
+货源单号、运单号、托运单号、车牌号、司机姓名、托运方名称、承运运费、总金额、付款方式、付款时间、收款人、收款账号、收款账号类型、核验状态、异常项、上报状态、操作（上报/详情）
+收款账号类型说明
+• 个人账户：司机个人银行卡账号，标签为蓝色
+• 对公账户：企业银行账号，标签为绿色
+详情弹窗字段分组
+（1）运单信息（必选）：同第一次上报
+（2）托运方信息（必选）：同第一次上报
+（3）收货方信息（必选）：同第一次上报
+（4）资金流水信息（必选）：支付金额、支付方式、支付时间、付款方名称、收款方名称、收款人、收款账号、收款账号类型、流水号、支付状态
+（5）车辆轨迹信息（必选，可多条，2~2000个点）：定位类型、定位时间、定位地点、经度、纬度、轨迹类型
+（6）异常信息：核验状态、异常原因、异常时间、处理状态
+核验内容（监管平台自动核验，异常时可发起申诉）
+| 核验项 | 说明 |
+| 运单重复核验 | 检查同一运单是否重复上报 |
+| 车辆资质核验 | 检查车辆道路运输证是否在有效期内 |
+| 司机资质核验 | 检查司机从业资格证是否在有效期内 |
+| 集中支付核验 | 检查资金流水是否通过网货平台集中支付 |
+| 资金流水核验 | 检查资金流水单号是否重复、金额是否匹配 |
+| 合同核验 | 检查运输合同和委托合同是否有效 |
+| 车辆轨迹合规核验 | 检查车辆轨迹是否真实、与运单路线是否匹配 |
+2.4 第三次上报（开票完成）
+功能描述
+第三次上报在发票开具完成后触发，上报数据包含运单信息（托运单号数组）、发票信息、油气发票信息等。
+特殊说明
+• 第三次上传需要在运单完成第二次上传后方可进行。
+• 若增值税发票验证失败，会导致上报失败，需检查发票信息是否正确。
+• 若上报失败，系统会自动重试（最多3次），若仍失败则告警通知运营人员。
+列表字段
+货源单号、运单号、托运单号、车牌号、司机姓名、托运方名称、发票号码、发票金额、开票日期、核验状态、异常原因、上报状态、操作（详情）
+详情弹窗字段分组
+（1）运单信息（必选）：同第一次上报
+（2）发票信息（必选，17字段）：托运单号数组、发票号码、发票代码号、发票金额价税合计)、开票日期、销售方名称、销售方纳税人识别号、销售方地址、销售方电话、销售方开户行、销售方银行账户、受票方名称、受票方纳税人识别号、受票方地址、受票方电话、受票方开户行、受票方银行卡号
+（3）油气发票信息（可选，可多条）：油气托运单号、油气发票文件
+（4）异常信息：核验状态、异常原因、异常时间、处理状态
+2.5 ETC发票上传
+功能描述
+ETC发票上传用于上报车辆通行高速公路的ETC发票信息，作为税务抵扣凭证。
+特殊说明
+• ETC发票上传需要在税务抵扣完成后进行，否则会导致上报失败。
+• 若ETC发票验证失败，会导致上报失败，需检查发票信息是否正确。
+• 若上报失败，系统会自动重试（最多3次），若仍失败则告警通知运营人员。
+列表字段
+货源单号、运单号、托运单号、车牌号、司机姓名、托运方名称、ETC发票号码、发票金额、税率、上传状态、操作（详情）
+详情弹窗字段分组
+（1）运单信息：运单号、货源单号、托运单号、车牌号、司机姓名、托运方名称、收货方名称
+（2）ETC发票信息（每张发票18字段）：ETC发票号码、ETC发票代码、开票时间、发票金额、税率、税额、价税合计、销售方名称、销售方税号、受票方名称、受票方税号、入口收费站、出口收费站、交易时间、交易金额、交易匹配时间、交易流水号、ETC发票文件
+（3）异常信息：核验状态、异常原因、异常时间、处理状态
+2.6 异常申诉功能
+运单完成第二次上传后，安徽省管理平台自动进行 7 大类核验（车辆资质、司机资质、资金流水、合同、轨迹等）。如核验结果为异常时，运营人员可通过申诉机制向平台说明情况并申请重新核验。
+本模块补全“异常查询 → 发起申诉 → 跟踪监管平台反馈 → 合规判断”的完整闭环。
+当上报数据被核验为异常时，运营人员可发起申诉，向安徽监管平台说明情况并申请重新核验。申诉记录管理页面展示所有申诉记录及省平台反馈结果。
+列表字段
+运单号、托运单号、车牌号、司机姓名、托运方名称、上报阶段、核验状态、异常项、申诉状态、申诉时间、申诉人、省平台反馈结果、监管平台反馈时间、操作（详情/重新申诉）
+详情弹窗字段分组
+（1）申诉信息：申诉单号、上报阶段、异常项、申诉原因、申诉状态、申诉时间、申诉人、申诉附件
+（2）运单信息：运单号、托运单号、车牌号、司机姓名、托运方名称
+（3）异常信息：核验状态、异常原因、异常时间
+（4）省平台反馈信息：反馈结果、反馈时间、反馈意见
+（5）处理记录：操作人、操作时间、操作类型、操作内容（时间线展示）
+申诉复核说明
+（注：申诉由安徽监管平台复核，非我方审核）
+（复核不通过时，可补充材料后重新发起申诉）
+异常代码一览表
+2.7 上报日志
+功能描述
+上报日志记录所有上报接口的调用记录，用于问题排查和审计。
+查询条件
+• 运单号/托运单号/货源单号：模糊搜索
+• 上报阶段：全部 / 第一次上报 / 第二次上报 / 第三次上报 / ETC上传
+• 上报结果：全部 / 成功 / 失败
+• 开始时间 ~ 结束时间：时间范围筛选
+列表字段
+序号、货源单号、运单号、托运单号、上报阶段、上报结果、接口URL、HTTP状态码、响应时间、上报时间、操作（弹窗详情查看完整请求/响应报文）
+三. 数据字段说明
+3.1 第一次上报字段（装货完成）
+核心子对象及必选字段：
+• waybillInfo（建单信息）：originalDocumentNumber、shippingNoteNumber、documentCreateTime、carrier、unifiedSocialCreditIdentifier、permitNumber、businessTypeCode、goodsArrangementTypeCode、orderReceivingTime、departureTime、commercialContractNumber、contractNumber、mileage
+• consignorInfo（托运人信息）：consignor、consignorId、frameContractNumber、placeOfLoading、loadingLongitude、loadingLatitude、loadingCountrySubdivisionCode
+• consigneeInfo（收货方信息）：consignee、consigneeId、goodsReceiptPlace、unLoadingLongitude、unLoadingLatitude
+• driverInfo（司机信息）：driverName、drivingIdNumber、drivingLicense、issuingOrganizations、qualificationCertificate、qualificationCertificateFrom、qualificationCertificateTo、taxRegistrationCertificate、telephone、validPeriodFrom、validPeriodTo、vehicleClass、provinceCode
+• carInfo（接单车辆信息）：vehicleNumber、vehiclePlateColorCode、LicensePlateTypeCode、vin、owner、ownerId、useCharacter、vehicleType、vehicleEnergyType、registerDate、issueDate、issuingOrganizations、vehicleTonnage、grossMass、roadTransportCertificateNumber、trailerVehiclePlateNumber、vehicleLicenseNumbe、roadTransportSocialCreditFrom、roadTransportSocialCreditTo
+• goodsInfos（货物信息，可多条）：descriptionOfGoods、cargoTypeClassificationCode、quantity、unit
+• insuranceInformation（保险信息，可选）：policyNumber、insuranceCompany
+3.2 第二次上报字段（打款完成）
+新增字段说明：
+• 收款人（自定义扩展字段）：对应资金流水中的收款方名称recipient)
+• 收款账号（自定义扩展字段）：对应资金流水中的收款账号receiptAccount)
+• 收款账号类型（自定义扩展字段）：个人账户 / 对公账户，为我方自定义列
+3.3 第三次上报字段（开票完成）
+核心字段：
+• 发票号码（invoiceNo）：增值税发票号码
+• 发票代码（invoiceCode）：增值税发票代码
+• 发票金额（invoiceAmount）：价税合计（保留2位小数）
+（注：第三次上传的invoice无税率字段，税率仅出现在ETC发票上传中）
+• 销售方名称（sellerName）：开票方企业名称
+• 受票方名称（buyerName）：托运人/货主企业名称
+3.4 ETC发票字段
+核心字段：
+• ETC发票号码（etcInvoiceNo）：高速公路通行费电子发票号码
+• 入口收费站（entryStation）：通行入口
+• 出口收费站（exitStation）：通行出口
+• 税额（taxAmount）：可抵扣税额（税率3%）
+详细数据接口字段请查阅上报接口：
+https://www.showdoc.com.cn/2210641821476236/9919735893682511
+密码：szjj@2023
+原型文件路径：
+"E:\WeChat\xwechat_files\wxid_2n9ko0aq1th822_44c3\msg\file\2026-07\anhuibaba_index.html"
+接口文档路径："E:\Downloads\网货企业端接口文档（最新）.pdf"

output/versions/安徽运八需求/v4/normalized_inputs/requirement_restructured.md

@@ -0,0 +1,506 @@
+# 安徽运八需求（以API文档为准重构）
+
+> **重构原则**: API接口文档(网货企业端接口文档 V1.0.2) 为权威数据源，HTML原型为UI参考，原始需求文档为业务背景补充。
+> **重构时间**: 2026-07-13
+> **原始需求**: `source_docs/requirements_raw/安徽运八需求.docx`
+> **API文档**: `E:\Downloads\网货企业端接口文档（最新）.pdf` V1.0.2 (2023-04)
+> **原型**: `anhuibaba_index.html`
+
+---
+
+## 一、系统边界
+
+本需求涉及两套系统的对接：
+
+| 系统 | 职责 | 本文档覆盖 |
+|:---|:---|:---|
+| **运八平台（我方）** | 自动触发三阶段上报、ETC上传；查询核验结果；发起/跟踪申诉；查看上报日志 | 全量 |
+| **安徽省级网络货运监测系统（省平台）** | 接收上报数据；执行核验；受理申诉并反馈 | 仅接口交互 |
+
+API文档覆盖的是**运八平台→省平台**的查询和申诉接口。上报触发逻辑（装货完成/打款完成/开票完成自动触发）属于运八平台内部业务逻辑，API文档中未定义上报提交接口。
+
+---
+
+## 二、API接口清单（权威来源：接口文档 V1.0.2）
+
+### 2.1 通用规范
+
+| 项目 | 规范 |
+|:---|:---|
+| 基地址 | `http://*******/api/` |
+| 协议 | HTTP POST |
+| 请求格式 | JSON（除上传文件接口外） |
+| 响应格式 | `{"code":200, "message":"操作成功", "data":{}}` |
+| 认证 | JWT Token，调用 `/sys/login` 获取，除登录接口外均需在请求头携带 |
+| 时间格式 | `yyyy-MM-dd HH:mm:ss` |
+| 成功码 | `code=200` |
+| 失败码 | `code=500` |
+
+### 2.2 接口一览（共9个）
+
+| # | 接口 | URL | 说明 |
+|:---:|:---|:---|:---|
+| 1 | 获取token | `POST /sys/login` | JWT认证，参数: loginName, loginPassword |
+| 2 | 上传申诉附件 | `POST /appeal/uploadFile` | 文件上传，参数: file (File) |
+| 3 | 提交申诉运单 | `POST /appeal/insert` | 发起申诉，参数: freightSheetNumber, complaintNumber, attachmentUrl, content, verificationAbnormalItems |
+| 4 | 查询异常运单信息 | `POST /verificationSummary/page` | 分页查询，支持多维度筛选 |
+| 5 | 查询申诉进度 | `POST /appeal/page` | 分页查询申诉记录及审核结果 |
+| 6 | 查询运单核验详情 | `POST /verificationSummary/verificationDetail` | 单运单全部核验项明细 |
+| 7 | 查询发票是否合规 | `POST /verificationSummary/cargoOwnerInvoiceInfo` | 判断托运人发票系统核验是否合规 |
+| 8 | 运单里程核验查询 | `POST /verificationSummary/mileageVerificationInfo` | 批量查询运单里程核验状态 |
+| 9 | 运单里程申诉 | `POST /mileageAppeal/insert` | 对里程核验结果发起申诉 |
+
+### 2.3 接口详细定义
+
+#### 接口1: 获取token
+```
+POST /sys/login
+请求: { "loginName": "xxx", "loginPassword": "xxx" }
+响应: { "code": 200, "data": { "token": "...", "expireTime": 1681219619843, "loginName": "ceshi", "name": "测试" } }
+```
+
+#### 接口2: 上传申诉附件
+```
+POST /appeal/uploadFile
+请求: multipart/form-data, 字段 file (File)
+```
+
+#### 接口3: 提交申诉运单
+```
+POST /appeal/insert
+请求:
+  freightSheetNumber    String  运单号           必填
+  complaintNumber       String  申诉编号          必填
+  attachmentUrl         String  申诉附件URL       必填
+  content               String  申诉内容          必填
+  verificationAbnormalItems String 核验异常项ID   必填  (逗号分隔，如"120,160")
+```
+
+#### 接口4: 查询异常运单信息
+```
+POST /verificationSummary/page
+请求:
+  pageIndex              int     页码            必填
+  pageSize               int     每页条数         必填
+  freightSheetNumber     String  运单号           可选
+  verificationAbnormalItems String 异常项ID       可选 (多个逗号拼接)
+  driverName             String  驾驶员姓名       可选
+  driverIdCard           String  驾驶员身份证号   可选
+  vehicleNumber          String  车牌号           可选
+  appealStateId          int     申诉状态ID       可选
+  verifyStateId          int     核验状态ID       可选
+  beginTime ~ endTime            运单创建时间范围  可选
+  beginFirstVerifyTime ~ endFirstVerifyTime  首次核验时间范围  可选
+  beginLastVerifyTime ~ endLastVerifyTime    最新核验时间范围  可选
+  beginInsertTime ~ endInsertTime            插入时间范围      可选
+
+响应:
+  pageRecords[]:
+    freightSheetNumber       String  运单号
+    appealStateId            int     申诉状态ID
+    appealStateName          String  申诉状态名称
+    verificationAbnormalItem String  核验异常项
+    createTime               date    运单创建时间
+    lastVerifyTime           date    最新核验时间
+    firstVerifyTime          date    首次核验时间
+    vehicleNumber            String  车牌号
+    driverName               String  驾驶员姓名
+    driverIdCard             String  驾驶员身份证号
+    verifyStateId            int     核验状态ID
+    verifyStateName          String  核验状态名称
+    abnormalDetails[]:
+      id        int     异常项ID
+      name      String  异常项名称
+      message   String  异常原因
+      time      date    异常时间
+      state     int     异常项处理状态 (100=未申诉, 110=申诉中)
+```
+
+#### 接口5: 查询申诉进度
+```
+POST /appeal/page
+请求:
+  pageIndex          int     页码              必填
+  pageSize           int     每页条数           必填
+  freightSheetNumber String  运单号             可选
+  abnormalTypeId     String  核验异常项ID        可选
+  auditStateId       String  审核状态ID         可选
+  beginTime ~ endTime        申诉时间范围        可选
+  auditBeginTime ~ auditEndTime 审核时间范围     可选
+  complaintNumber    String  申诉编号           可选
+
+响应:
+  pageRecords[]:
+    complaintNumber          String  申诉编号
+    freightSheetNumber       String  运单号
+    content                  String  申诉内容
+    complainantName          String  申诉人
+    auditStateId             int     审核状态ID
+    auditStateName           String  审核状态名称
+    auditorName              String  审核人
+    auditRemark              String  审核备注
+    auditTime                date    审核时间
+    verificationAbnormalItem String  运单异常项
+    cancelPerson             String  取消人
+    cancelReason             String  取消原因
+    cancelTime               date    取消时间
+    revokeUserName           String  撤回人
+    revokeTime               date    撤回时间
+    createTime               date    创建时间
+    appealAbnormalList[]:
+      verificationTypeId     int     异常项ID
+      verificationTypeName   String  异常项名称
+```
+
+#### 接口6: 查询运单核验详情
+```
+POST /verificationSummary/verificationDetail
+请求:
+  freightSheetNumber  String  运单号  必填
+  beginInsertTime     String  插入时间-开始  可选
+  endInsertTime       String  插入时间-结束  可选
+
+响应:
+  pageRecords[].details[]:
+    verificationCode      int     核验项编码
+    verificationName      String  核验项名称
+    verificationState     String  核验状态
+    verificationStateId   int     核验状态ID
+    verificationTime      date    核验时间
+    message               String  核验信息
+```
+
+#### 接口7: 查询发票是否合规
+```
+POST /verificationSummary/cargoOwnerInvoiceInfo
+请求: { "freightSheetNumber": "55141359" }
+响应: { "isSystemVerification": true }  // true=系统核验合规, false=人工判定合规
+```
+
+#### 接口8: 运单里程核验查询
+```
+POST /verificationSummary/mileageVerificationInfo
+请求: { "freightSheetNumberList": ["22222222", "111111"] }
+响应: [
+  { "verificationStateId": 110, "freightSheetNumber": "22222222", "mileage": 350.263 },
+  { "verificationStateId": null, "freightSheetNumber": "4658151", "mileage": null }
+]
+// 注: 运单未上报里程时 verificationStateId 和 mileage 为 null
+```
+
+#### 接口9: 运单里程申诉
+```
+POST /mileageAppeal/insert
+请求:
+  freightSheetNumber  String  运单号    必填
+  content             String  申诉内容  必填
+  complaintNumber     String  申诉编号  必填
+  mileage             String  里程数    必填
+```
+
+---
+
+## 三、数据字典（权威来源：接口文档 §4.1~§4.5）
+
+### 3.1 异常项ID对照表（§4.1）— 共17项
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 委托合同 | 托运人与承运人签订的委托运输合同核验 |
+| 120 | 承运合同 | 承运人以自身名义签订的运输合同核验 |
+| 130 | 实时定位 | 车辆实时定位数据核验 |
+| 140 | 运单时间逻辑 | 运单各时间节点的逻辑合理性核验（如装货时间<卸货时间） |
+| 150 | 车辆资质 | 车辆道路运输经营许可证有效性核验 |
+| 160 | 道路运输证 | 车辆道路运输证有效期核验 |
+| 170 | 驾驶证 | 驾驶员驾驶证有效性核验 |
+| 180 | 从业资格证 | 驾驶员从业资格证有效期核验 |
+| 190 | 车辆重复 | 同一车辆在同一时段是否存在多运单 |
+| 200 | 司机重复 | 同一司机在同一时段是否存在多运单 |
+| 210 | 车辆轨迹 | GPS轨迹真实性、与运单路线匹配度核验 |
+| 220 | 运费收款 | 运单是否在运费收款方名下 |
+| 230 | 公司统一收款 | 是否通过公司账户统一收款 |
+| 240 | 集中支付 | 是否通过网络货运平台集中支付 |
+| 250 | 资金流水 | 资金流水单号唯一性、金额匹配核验 |
+| 260 | 发票信息 | 托运人发票信息核验（第三次上报相关） |
+| 270 | 非通行车辆可开票 | 非通行车辆是否允许开具通行费发票 |
+
+### 3.2 运单核验状态（§4.2）
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 未核验 | 运单尚未被省平台核验 |
+| 110 | 核验通过 | 全部核验项通过 |
+| 120 | 全部异常 | 存在核验不通过的异常项 |
+
+### 3.3 运单部分核验状态（§4.3）
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 未核验 | 尚未核验 |
+| 110 | 部分核验 | 部分核验项已通过，仍有待核验项 |
+| 120 | 全部核验 | 全部核验项已出结果 |
+
+### 3.4 运单申诉状态（§4.4）— 权威枚举
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| **100** | **未申诉** | 尚未发起申诉 |
+| **110** | **审核通过** | 省平台审核通过 |
+| **120** | **审核不通过** | 省平台审核驳回 |
+| **130** | **已取消** | 申诉已取消（原始需求未提及此状态） |
+
+> **与原始需求的差异**: 
+> - 原始需求: 未申诉 / 申诉中 / 申诉通过 / 申诉驳回
+> - API文档: 未申诉(100) / 审核通过(110) / 审核不通过(120) / 已取消(130)
+> - **API文档为权威来源**。原始需求的"申诉中"在API中对应"未申诉(100)"状态下的一个进行中标记（接口4响应中 abnormalDetails[].state=110 表示申诉中）。
+> - 原型中的"待省平台反馈"和"反馈处理中"为UI层面的展示状态，非后端枚举值。
+
+### 3.5 附件状态（§4.5）
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 未处理 | 申诉附件尚未被省平台处理 |
+| 110 | 处理通过 | 附件核验通过 |
+| 120 | 处理异常 | 附件核验异常 |
+
+---
+
+## 四、功能模块（综合API文档+原型+原始需求）
+
+### 4.1 上报运单看板
+
+**入口**: 侧边栏 → 上报运单看板
+
+**统计卡片**（原型定义）:
+- 异常运单数、待申诉数、申诉中数、已处理数
+
+**查询条件**（综合原型+接口4请求参数）:
+
+| 筛选项 | 类型 | 可选值 |
+|:---|:---|:---|
+| 运单号/托运单号/货源单号 | 文本输入 | 模糊搜索 |
+| 上报阶段 | 下拉 | 全部 / 第一次上报 / 第二次上报 / 第三次上报 |
+| 核验状态 | 下拉 | 全部 / 异常 / 通过 |
+| 申诉状态 | 下拉 | 全部 / 未申诉(100) / 审核通过(110) / 审核不通过(120) / 已取消(130) |
+
+**列表字段**（原型为准，15列含勾选）:
+货源单号 / 运单号 / 托运单号 / 车牌号 / 司机姓名 / 上报阶段 / 托运方名称 / 核验状态 / 申诉状态 / 异常项 / 货物名称 / 合同金额 / 最新核验时间 / 操作
+
+**操作按钮**:
+- 异常运单: [申诉] [详情]
+- 申诉中运单: [进度] [详情]
+- 正常运单: [详情]
+
+**标签颜色**（原型CSS定义）:
+- 蓝色 `.tag-blue`: 上传中、申诉中
+- 绿色 `.tag-green`: 已上传、通过、已完成、申诉通过、对公账户
+- 红色 `.tag-red`: 上传失败、异常、申诉驳回
+- 橙色 `.tag-orange`: 异常项标签、待上报
+- 灰色 `.tag-gray`: 未申诉
+- 紫色 `.tag-purple`: (预留)
+
+### 4.2 第一次上报（装货完成）
+
+**触发条件**: 运单装货完成 AND 货源税源地=安徽
+
+**上报数据子对象**（以接口文档字段定义为准）:
+
+| 子对象 | 必选/可选 | 核心字段 |
+|:---|:---|:---|
+| waybillInfo（建单信息） | 必选 | originalDocumentNumber, shippingNoteNumber, documentCreateTime, carrier, unifiedSocialCreditIdentifier, permitNumber, businessTypeCode, goodsArrangementTypeCode, orderReceivingTime, departureTime, commercialContractNumber, contractNumber(可选), mileage(可选) |
+| consignorInfo（托运人信息） | 必选 | consignor, consignorId, frameContractNumber(可选), placeOfLoading, loadingLongitude, loadingLatitude, loadingCountrySubdivisionCode |
+| consigneeInfo（收货方信息） | 必选 | consignee, consigneeId, goodsReceiptPlace, unLoadingLongitude, unLoadingLatitude |
+| driverInfo（司机信息） | 必选 | driverName, drivingIdNumber, drivingLicense, issuingOrganizations, qualificationCertificate, qualificationCertificateFrom, qualificationCertificateTo, taxRegistrationCertificate, telephone, validPeriodFrom, validPeriodTo, vehicleClass, provinceCode |
+| carInfo（车辆信息） | 必选 | vehicleNumber, vehiclePlateColorCode, LicensePlateTypeCode, vin, owner, ownerId, useCharacter, vehicleType, vehicleEnergyType, registerDate, issueDate, issuingOrganizations, vehicleTonnage, grossMass, roadTransportCertificateNumber, trailerVehiclePlateNumber(可选), vehicleLicenseNumbe(可选), roadTransportSocialCreditFrom(可选), roadTransportSocialCreditTo(可选) |
+| goodsInfos（货物信息） | 必选，可多条 | descriptionOfGoods, cargoTypeClassificationCode, quantity, unit |
+| insuranceInformation（保险信息） | 可选 | policyNumber, insuranceCompany |
+
+**业务规则**:
+- 仅安徽税源地(省份代码=34，非28)运单触发
+- 上报成功后自动调用"修改第一次上报部分字段"接口更新变化字段
+- 失败自动重试最多3次，全部失败后站内信通知运营
+- 第一次上报是后续上报的前置条件（后端校验）
+
+**列表页**（原型为准，14列+勾选）:
+货源单号 / 运单号 / 托运单号 / 车牌号 / 司机姓名 / 托运方名称 / 业务类型 / 货物名称 / 装货地址 / 卸货地址 / 运输里程 / 合同编号 / 上报状态 / 操作
+
+**上报状态**（内部系统状态，非API枚举）:
+- 上传中（蓝色）
+- 已上传（绿色）
+- 上传失败（红色）— 显示"手动上传"按钮
+- 异常（橙色）
+
+### 4.3 第二次上报（打款完成）
+
+**触发条件**: 财务打款完成 AND 第一次上报已完成
+
+**核验项**: 省平台自动核验，共17项（见§3.1）。每项独立产生核验结果，核验异常项可通过申诉机制逐项申诉。
+
+**上报数据子对象**:
+| 子对象 | 必选/可选 | 核心字段 |
+|:---|:---|:---|
+| waybillInfo | 必选 | （同第一次上报） |
+| consignorInfo | 必选 | （同第一次上报） |
+| consigneeInfo | 必选 | （同第一次上报） |
+| 资金流水信息 | 必选 | 支付金额、支付方式、支付时间、付款方名称、收款方名称、收款人、收款账号、收款账号类型、流水号、支付状态 |
+| 车辆轨迹信息 | 必选，2~2000点 | 定位类型、定位时间、定位地点、经度、纬度、轨迹类型 |
+
+**列表页**（原型为准，17列+勾选）:
+货源单号 / 运单号 / 托运单号 / 车牌号 / 司机姓名 / 托运方名称 / 承运运费 / 总金额 / 付款方式 / 付款时间 / 收款人 / 收款账号 / 收款账号类型 / 核验状态 / 异常项 / 上报状态 / 操作
+
+**收款账号类型标签**: 个人账户=蓝色, 对公账户=绿色
+
+### 4.4 第三次上报（开票完成）
+
+**触发条件**: 发票开具完成 AND 第二次上报已完成
+
+**前置条件**: 第二次上报必须完成（后端校验）
+
+**API关联接口**: 
+- `POST /verificationSummary/cargoOwnerInvoiceInfo` — 查询托运人发票系统核验是否合规
+- 响应: `isSystemVerification`: true=系统核验合规, false=人工判定合规
+
+**列表页**（原型为准，15列+勾选）:
+货源单号 / 运单号 / 托运单号 / 发票号码 / 发票金额 / 税率 / 销售方名称 / 受票方名称 / 开票日期 / 油气票张数 / 核验状态 / 异常原因 / 上报状态 / 操作
+
+### 4.5 ETC发票上传
+
+**触发条件**: 税务抵扣完成
+
+**列表页**（原型为准，10列+勾选）:
+货源单号 / 运单号 / 托运单号 / ETC发票号 / 交易金额 / 入口收费站 / 出口收费站 / 交易时间 / 上传状态 / 操作
+
+**详情弹窗字段**（原型为准）:
+- 运单信息: 运单号、货源单号、托运单号、车牌号、司机姓名、托运方名称、收货方名称
+- ETC发票信息: ETC发票号码、ETC发票代码、交易金额、税率(3%)、发票金额(不含税)、税额、入口收费站、出口收费站、交易时间、发票状态
+
+### 4.6 异常申诉功能
+
+**关联API接口**: 
+- `POST /appeal/uploadFile` — 上传申诉附件
+- `POST /appeal/insert` — 提交申诉
+- `POST /appeal/page` — 查询申诉进度
+- `POST /mileageAppeal/insert` — 里程申诉（独立接口）
+
+**申诉流程**（闭环）:
+```
+异常运单查询(接口4) → 发起申诉(接口3) → 省平台复核 → 
+查询申诉进度(接口5) → 审核通过(110) | 审核不通过(120) → 
+重新申诉(接口3) | 取消(130)
+```
+
+**申诉状态流转**（以API §4.4为准）:
+```
+未申诉(100) → 审核通过(110) [终态]
+未申诉(100) → 审核不通过(120) → 重新申诉 → 未申诉(100) [新申诉单]
+未申诉(100) → 已取消(130) [终态]
+```
+
+**列表页**（原型为准，14列+勾选）:
+运单号 / 托运单号 / 车牌号 / 司机姓名 / 托运方名称 / 上报阶段 / 核验状态 / 异常项 / 申诉状态 / 申诉时间 / 申诉人 / 省平台反馈结果 / 省平台反馈时间 / 操作
+
+**详情弹窗分组**（原型为准）:
+- 申诉信息: 申诉单号、上报阶段、异常项、申诉原因、申诉状态、申诉时间、申诉人、申诉附件
+- 运单信息: 运单号、托运单号、车牌号、司机姓名、托运方名称
+- 异常信息: 核验状态、异常原因、异常时间
+- 省平台反馈信息: 反馈状态、反馈时间、反馈结果、反馈意见
+- 处理记录（时间线）: 操作人、操作时间、操作类型、操作内容
+
+### 4.7 上报日志
+
+**查询条件**（原型为准）:
+- 运单号/托运单号/货源单号: 模糊搜索
+- 上报阶段: 全部 / 第一次上报 / 第二次上报 / 第三次上报 / ETC上传
+- 上报结果: 全部 / 成功 / 失败
+- 时间范围: 开始时间 ~ 结束时间
+
+**列表字段**（原型为准，11列）:
+序号 / 货源单号 / 运单号 / 托运单号 / 上报阶段 / 上报结果 / 接口URL / HTTP状态码 / 响应时间 / 上报时间 / 操作
+
+**日志详情弹窗**: 展示完整请求报文（URL/Method/Headers/Body）和响应报文（StatusCode/Headers/Body），JSON格式化展示，支持一键复制。
+
+---
+
+## 五、状态枚举汇总（以API文档为权威）
+
+### 5.1 申诉状态（API §4.4 权威）
+
+| Code | 名称 | 原始需求对应 | 说明 |
+|:---:|:---|:---|:---|
+| 100 | 未申诉 | 未申诉 + 申诉中 | 含已提交但省平台尚未审核的情况 |
+| 110 | 审核通过 | 申诉通过 | 终态 |
+| 120 | 审核不通过 | 申诉驳回 | 可重新申诉 |
+| 130 | 已取消 | （无） | API独有，原始需求未提及 |
+
+### 5.2 核验状态（API §4.2 权威）
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 未核验 | 运单尚未核验 |
+| 110 | 核验通过 | 全部17项核验通过 |
+| 120 | 全部异常 | 存在核验异常项 |
+
+### 5.3 异常项处理状态（API §4.1 子字段）
+
+| Code | 名称 | 说明 |
+|:---:|:---|:---|
+| 100 | 未申诉 | 该异常项尚未发起申诉 |
+| 110 | 申诉中 | 该异常项已提交申诉，待审核 |
+
+### 5.4 上报状态（内部系统状态，非API枚举）
+
+| 状态 | 标签颜色 | 说明 |
+|:---|:---|:---|
+| 上传中 | 蓝色 | 数据正在上报中 |
+| 已上传 | 绿色 | 上报成功 |
+| 上传失败 | 红色 | 上报超时或错误，显示"手动上传"按钮 |
+| 异常 | 橙色 | 数据校验不通过 |
+
+---
+
+## 六、与原始需求的关键差异
+
+| # | 项目 | 原始需求 | API文档（权威） | 影响 |
+|:---:|:---|:---|:---|:---|
+| 1 | 核验项数量 | 7类 | **17项** (§4.1) | 测试覆盖需从14条扩展到34条 |
+| 2 | 申诉状态 | 未申诉/申诉中/通过/驳回 | **未申诉(100)/审核通过(110)/审核不通过(120)/已取消(130)** | 申诉状态枚举全部更新 |
+| 3 | 申诉"进行中" | 独立状态"申诉中" | 归属于"未申诉(100)"，由abnormalDetails[].state=110标识 | 状态机变更 |
+| 4 | 已取消状态 | 无 | **130=已取消** | 新增状态，需补充测试 |
+| 5 | 里程申诉 | 无 | **独立接口** `/mileageAppeal/insert` | 新增功能模块 |
+| 6 | 发票合规查询 | 无 | **独立接口** `/verificationSummary/cargoOwnerInvoiceInfo` | 新增功能点 |
+| 7 | 核验状态 | 通过/异常（二元） | 未核验(100)/通过(110)/全部异常(120) | 新增"未核验"初始状态 |
+| 8 | 附件状态 | 无 | 未处理(100)/处理通过(110)/处理异常(120) | 新增枚举 |
+
+---
+
+## 七、上报接口文档参考
+
+原始需求中提到的上报接口文档（上报数据字段定义）:
+- URL: `https://www.showdoc.com.cn/2210641821476236/9919735893682511`
+- 密码: `szjj@2023`
+
+> ⚠️ 此文档定义了上报请求的字段结构（第一次上报7个子对象、第二次上报资金流水+轨迹、第三次上报发票信息），因受密码保护未直接读取。上报字段定义建议以此文档为准。
+
+---
+
+## 八、待确认项（累计14项）
+
+### 阻塞级（影响测试覆盖）
+1. **核验项分组映射**: API 17项核验如何映射到UI展示的异常项？是否所有17项均可独立申诉？
+2. **上报接口字段定义**: showdoc文档中的字段是否与API文档§4一致？
+
+### 重要级
+3. 申诉状态"已取消(130)"的触发条件和权限
+4. 原型中"待省平台反馈"和"反馈处理中"两个UI状态如何对应API的"未申诉(100)"
+5. 第三次上报列表字段以原型(15列)还是原始需求(13列)为准
+6. 里程申诉与通用申诉的关系——是否合并入口还是独立入口
+7. 发票合规查询（接口7）的调用时机——第三次上报前校验还是独立查询
+
+### 参考级
+8. 自动重试间隔时间（当前参考值5s/15s/30s）
+9. ETC税额四舍五入规则（0.01×3%=0.0003→?）
+10. 申诉超时告警阈值（当前参考值7个工作日）
+11. 原始需求与API文档省份代码一致性
+12. 原型第二次上报详情弹窗缺失车辆轨迹——是原型bug还是设计如此
+13. 原型详情弹窗字段分组与接口字段定义的完整映射
+14. ETC上传触发条件"税务抵扣完成"由哪个系统事件触发