chore: 入库 9 月积压成果（滇中好运原型评估、小象开票需求与原型、工具配置）

- 原型评估_滇中好运物流云_20260917/：物流云原型评估产物（含核对表与字段对比表） - requirements/小象开票收款方创建需求.md + prototypes/小象开票原型.html：小象开票建司机/车辆/收款信息需求 - requirements.txt：Execute 战区依赖调整（移除 pytest/allure-pytest/requests，改用 pytest-html，Appium 默认注释） - .claude/launch.json：新增物流公司管理原型预览服务（wuliu-proto:8138） - .agents/skills：agent 技能定义
2026-09-29 10:03:43 +08:00
parent 8c61209dd4
commit 5e4e978cd5
14 changed files with 2463 additions and 9 deletions
@@ -0,0 +1,272 @@
+# 小象开票 —— 收款方创建需求文档（创建司机 / 创建车辆 / 新增收款信息）
+
+> **版本**: v1.0（初稿）
+> **编写日期**: 2026-09-28
+> **状态**: 待评审
+> **接口文档（权威来源）**:
+> - 创建司机：https://v4.xxyb.cn/markdown/link/proxy/DriverCreate.html
+> - 创建车辆：https://v4.xxyb.cn/markdown/link/proxy/VehicleCreate.html
+> - 新增收款信息：https://v4.xxyb.cn/markdown/link/proxy/PayeeCreate.html
+> - 公共枚举：https://v4.xxyb.cn/markdown/link/base/Code.html
+> **交互原型**: [prototypes/小象开票原型.html](prototypes/小象开票原型.html)（风格与"物流公司管理"原型一致，数据为演示数据）
+> **UI 参考**: 三十六匠发票"司机上传 / 车辆上传"页面截图（表头筛选行 + 批量上传按钮样式）
+> **菜单位置**: 小象开票（顶级菜单）下新增：创建司机、创建车辆、新增收款信息
+
+---
+
+## 1. 背景与目标
+
+小象开票（联合开票）业务要求承运方（司机、车辆）及其收款账户先在 xxyb 平台完成建档，才能开票。当前建档在小象平台侧手工操作，与运八系统脱节。本次在小象开票菜单下新增三个功能，直接调用 xxyb 开放接口完成建档：
+
+1. **创建司机**：录入司机信息 → 调用 `createDriver` 在 xxyb 平台创建司机档案；
+2. **创建车辆**：录入车辆信息 → 调用 `createVehicle` 创建车辆档案；
+3. **新增收款信息**：录入收款人账户 → 调用 `createPayee` 创建收款信息。
+
+建档结果（第三方返回 ID、审核状态）在列表中可见、可追溯。
+
+### 1.1 设计原则
+
+- 三个功能均为**记录/建档性质**：调用成功即在本系统留存记录并展示第三方审核状态，**不阻断**运单、开票等任何既有流程（是否允许开票由小象平台侧控制）。
+- 接口文档为字段权威来源，本文档字段表与其一致；页面展示字段为全量字段的子集（必填 + 高频选填），其余字段按接口文档保留扩展。
+
+---
+
+## 2. 名词
+
+| 名词 | 说明 |
+|:---|:---|
+| xxyb 平台 | 联合开票合作方（小象），接口基地址 `https://www.xxyb.cn/union/api/link/` |
+| 税源地 | 开票主体（如云南运八数据科技有限公司），建档时随单传入 |
+| 审核状态 | xxyb 平台对建档资料的审核结果：待审核 / 审核通过 / 审核不通过（AuditStatusEnum） |
+| 长期 | 证件有效期无固定截止日期时，有效期字段填写字符串"长期" |
+
+---
+
+## 3. 角色与权限
+
+| 角色 | 权限 |
+|:---|:---|
+| 开票运营人员 | 三个页面的新增、查看、批量上传 |
+| 其他角色 | 列表只读（按需授权） |
+
+- 数据按机构隔离（沿用平台多机构规则）；操作记行为日志。
+- **Header 鉴权**：`token`（应用令牌）、`cid`（合作ID），由平台配置统一注入，前端不接触。
+
+---
+
+## 4. 功能清单
+
+| 编号 | 功能 | 说明 | 优先级 |
+|:---|:---|:---|:---:|
+| FR-01 | 创建司机 | 司机列表 + 新增司机弹窗，提交调用 `createDriver` | P0 |
+| FR-02 | 创建车辆 | 车辆列表 + 新增车辆弹窗，提交调用 `createVehicle` | P0 |
+| FR-03 | 新增收款信息 | 收款信息列表 + 新增弹窗，提交调用 `createPayee` | P0 |
+| FR-04 | 审核状态展示 | 列表展示 xxyb 审核状态与审核时间 | P0 |
+| FR-05 | 批量上传 | 司机身份证批量上传、车牌号批量上传（参照三十六匠页面；范围见 Q1） | P2 |
+
+---
+
+## 5. 接口规范（权威来源：xxyb 接口文档）
+
+### 5.0 公共
+
+- 请求方式：POST（JSON）；Header：`token`（应用令牌，必填）、`cid`（合作ID，必填）。
+- 返回结构：`{ code, msg, data, requestId }`；`code=200` 成功；成功后 `data.id` 为第三方建档 ID，需落库保存。
+- 图片/附件类字段均为 **URL**：文件先上传平台文件服务（OBS）取得 URL 后再随接口提交。
+
+### 5.1 创建司机 `POST /union/api/link/createDriver`
+
+| 字段 | 类型 | 层级 | 说明 | 必填 |
+|:---|:---|:---:|:---|:---:|
+| driverPhone | String | 1 | 司机手机号 | 是 |
+| driverRealAuthDomain | ApiDriverRealAuthDomain | 1 | 司机基础信息 | 是 |
+| driverAuthDomain | ApiDriverAuthDomain | 1 | 司机认证信息 | 否 |
+
+**ApiDriverRealAuthDomain 司机实名认证信息**：
+
+| 字段 | 类型 | 说明 | 必填 |
+|:---|:---|:---|:---:|
+| driverName | String | 司机姓名 | 是 |
+| driverIdCard | String | 身份证 | 是 |
+| driverIdCardAddress | String | 身份证地址 | 否 |
+| idCardFrontImg | String | 身份证人像面图片 | 否 |
+| idCardBackImg | String | 身份证国徽面图片 | 否 |
+
+**ApiDriverAuthDomain 司机认证信息（全部选填）**：
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| driverLicense | String | 驾驶证 |
+| driverLicenseFrontImg / BackImg | String | 驾驶证正/反面图片 |
+| driverLicenseIssuingAuthority | String | 驾驶证发证机关 |
+| driverLicenseExpireStartTime / EndTime | String | 驾驶证有效期起/止（长期填"长期"） |
+| professionalQualificationCertificate | String | 从业资格证 |
+| professionalQualificationCertificateImg | String | 从业资格证图片 |
+| professionalQualificationCertificateExpireStartTime / EndTime | String | 从业资格证有效期起/止 |
+| approvedDrivingType | ApprovedDrivingTypeEnum | 准驾车型（A1/A2/A1A2/B2/C1 等组合值，见 Code.html） |
+
+返回：`data.id` = 司机ID。
+
+### 5.2 创建车辆 `POST /union/api/link/createVehicle`
+
+| 字段 | 类型 | 层级 | 说明 | 必填 |
+|:---|:---|:---:|:---|:---:|
+| vehicleBasicDomain | ApiVehicleBasicDomain | 1 | 车辆基础信息 | 是 |
+| vehicleAuthDomain | ApiVehicleAuthDomain | 1 | 车辆认证信息 | 否 |
+
+**ApiVehicleBasicDomain 车辆基础信息**：
+
+| 字段 | 类型 | 说明 | 必填 |
+|:---|:---|:---|:---:|
+| licensePlateNumber | String | 车辆牌号 | 是 |
+| licensePlateColor | ColorEnum | 车牌颜色（BLUE 蓝 / YELLOW 黄 / GREEN 绿） | 是 |
+
+**ApiVehicleAuthDomain 车辆认证信息**（必填：vehicleType、vehicleLength、vehicleEnergyType、vehicleLicenseFrontImg、vehicleLicenseBackImg、vehicleLicenseExpireTime；其余选填）：
+
+| 字段 | 类型 | 说明 |
+|:---|:---|:---|
+| vehicleType | VehicleTypeEnum | 车型（重型半挂牵引车/重型自卸货车/轻型厢式货车等，见 Code.html） |
+| vehicleLength | BigDecimal | 车长 |
+| vehicleEnergyType | VehicleEnergyTypeEnum | 能源类型（A汽油/B柴油/C电/E天然气/O混合动力/Y无/Z其他等） |
+| vehicleIdentificationNumber | String | 车辆识别代码 |
+| vehicleLicense | String | 行驶证 |
+| vehicleLicenseFrontImg / BackImg / ClipImg | String | 行驶证正面/反面/副页图片 |
+| vehicleLicenseRegisterTime / ExpireTime | String | 行驶证注册日期/有效期 |
+| vehicleLicenseIssuingAuthority / IssuingTime | String | 行驶证发证机关/发证日期 |
+| roadTransportLicense + Img + AnnualInspectionImg + ExpireTime | String | 道路运输证系列 |
+| roadTransportBusinessLicense | String | 道路运输经营许可证 |
+| trailerLicenseNumber + Img + BackImg | String | 挂车牌照/副本照片 |
+| groupPhotoImg | String | 人车合照 |
+| totalMass / approvedLoad / curbWeight | BigDecimal | 总质量/核定载质量/整备质量 |
+| overallDimensions / useNature | String | 外廓尺寸/使用性质 |
+| creditCode | String | 统一社会信用代码/身份证号 |
+| vehicleOwner / vehicleOwnerExpireTime | String | 车辆所有人/有效期 |
+| affiliationAgreement | List&lt;String&gt; | 挂靠协议（多附件 URL） |
+
+返回：`data.id` = 车辆ID。
+
+### 5.3 新增收款信息 `POST /union/api/link/createPayee`
+
+| 字段 | 类型 | 层级 | 说明 | 必填 |
+|:---|:---|:---:|:---|:---:|
+| payeeBasicDomain | ApiPayeeBasicDomain | 1 | 收款信息 | 是 |
+
+**ApiPayeeBasicDomain 收款人基础信息**：
+
+| 字段 | 类型 | 说明 | 必填 | 备注 |
+|:---|:---|:---|:---:|:---|
+| payeeName | String | 收款人姓名 | 是 | |
+| payeeIdCard | String | 收款人身份证 | 是 | |
+| payeeBankCard | String | 收款银行卡号 | 是 | |
+| payeeBankCardImg | String | 收款银行卡图片 | 否 | |
+| payeeBankName | String | 收款银行 | 否 | |
+| payeePhone | String | 收款手机号 | 条件 | accountType 为 PERSONAL 时必填 |
+| accountType | AccountTypeEnum | 收款人类型 | 是 | PERSONAL 个人 / ENTERPRISE 企业 |
+
+返回：`data.id` = 收款人ID。
+
+---
+
+## 6. 业务规则
+
+### BR-01 必填与格式校验（前端 + 后端双重）
+
+- 手机号 11 位；身份证 18 位国标格式；银行卡号按 Luhn 校验 + 位数 15-19 位。
+- 收款人类型 = 个人时，`payeePhone` 必填（接口条件必填，前端联动校验）。
+- 车牌号格式校验（省份简称+字母+5/6位，含挂车"挂"字尾）；车辆长度数值 ≥ 0。
+
+### BR-02 证件有效期"长期"口径
+
+- 有效期截止类字段（驾驶证/资格证/行驶证/道路运输证/车辆所有人有效期）支持选择"长期"，提交时填写字符串 `长期`；起止格式 `yyyy-MM-dd`。
+
+### BR-03 附件
+
+- 页面上传证件图片 → 平台文件服务（OBS）→ 取 URL 随接口提交；单图 ≤ 10MB，jpg/jpeg/png/pdf（挂靠协议支持多文件）。
+- 上传失败时阻断提交并提示。
+
+### BR-04 提交与结果落库
+
+- 提交成功：保存 `data.id`（第三方ID）+ 提交内容 + 税源地 + 审核状态=待审核；提示"创建成功"。
+- 提交失败：展示接口 `msg`；表单不清空。
+- **重复创建**：同一身份证号（司机）/同一车牌号（车辆）在"待审核或审核通过"状态下重复创建时，前端提示确认；后端是否阻断以 xxyb 平台校验为准（见 Q4）。
+
+### BR-05 审核状态同步
+
+- 列表展示审核状态（待审核/审核通过/审核不通过）与审核时间，来源于 xxyb 平台。
+- 同步方式见待确认 Q2（回调 / 定时轮询），状态变化仅做展示更新，不影响本系统流程。
+
+### BR-06 批量上传
+
+- 参照三十六匠页面提供"批量上传 / 司机身份证批量上传 / 车牌号批量上传"入口（Excel 模板导入，逐条调接口）；范围见 Q1。
+
+---
+
+## 7. 页面详述
+
+### 7.1 创建司机（小象开票 → 创建司机）
+
+- **按钮**：查询、新增司机、批量上传、司机身份证批量上传（后两者见 Q1）。
+- **表头筛选行**（参照截图样式，无标签、placeholder 直书）：请选择税源地 ▼ / 请选择审核状态 ▼ / 审核时间起-止 / 请输入司机 / 请输入身份证号。
+- **列表列**：选择框、税源地、审核状态（待审核-橙 / 审核通过-绿 / 审核不通过-红）、审核时间、司机姓名、身份证号、身份证有效期（驾驶证有效期止）、手机号、操作（查看、重新上传——仅审核不通过时显示）。
+- **新增司机弹窗**（字段名对应 5.1）：
+  - 基础信息：司机手机号*、司机姓名*、身份证号*、身份证地址、身份证人像面图片、身份证国徽面图片；
+  - 认证信息（选填，默认折叠）：驾驶证号、驾驶证正/反面图片、发证机关、驾驶证有效期起/止（支持"长期"）、从业资格证、资格证图片、资格证有效期起/止、准驾车型（下拉）。
+- 提交成功后列表新增一行：审核状态"待审核"，第三方ID落库。
+
+### 7.2 创建车辆（小象开票 → 创建车辆）
+
+- **按钮**：查询、新增车辆、批量上传、车牌号批量上传。
+- **表头筛选行**：请选择税源地 ▼ / 请选择审核状态 ▼ / 审核时间起-止 / 请输入车牌 / 请输入车辆所有人 / 请选择车辆分类 ▼ / 请选择车牌颜色 ▼ / 请选择能源类型 ▼。
+- **列表列**：税源地、审核状态、审核时间、车牌号、车辆所有人、车辆分类（=vehicleType）、车牌颜色、车辆能源类型、操作（查看、重新上传）。
+- **新增车辆弹窗**：
+  - 基础信息：车牌号*、车牌颜色*（蓝/黄/绿）；
+  - 认证信息：车型*（下拉，VehicleTypeEnum）、车长*（米）、能源类型*（下拉）、车辆识别代码、行驶证正面图片*、行驶证反面图片*、行驶证有效期*（支持"长期"）、道路运输证、道路运输经营许可证、车辆所有人；
+  - 其余字段（挂车、质量参数、外廓尺寸、挂靠协议等）按接口文档保留输入（弹窗"更多信息"折叠区），原型中省略展示。
+
+### 7.3 新增收款信息（小象开票 → 新增收款信息）
+
+- **按钮**：查询、新增收款信息、导出。
+- **表头筛选行**：请输入收款人姓名 / 请输入身份证号 / 请选择收款人类型 ▼。
+- **列表列**：收款人姓名、身份证号、收款银行卡号、收款银行、收款手机号、收款人类型（个人/企业）、第三方ID、创建时间、操作（查看）。
+- **新增收款信息弹窗**：收款人类型*（个人/企业，切换联动）、收款人姓名*、身份证号*、收款银行卡号*、银行卡图片、收款银行、收款手机号（**个人必填**联动校验）。
+
+---
+
+## 8. 待确认问题
+
+| 编号 | 问题 | 倾向方案 |
+|:---:|:---|:---|
+| Q1 | 批量上传是否本期实现（Excel 模板 + 逐条调接口）？ | 建议本期先做单笔，批量二期 |
+| Q2 | 审核状态如何同步：xxyb 回调（Callback）还是我方定时轮询？ | 待与平台确认接口 |
+| Q3 | 审核不通过后的"重新上传"是调编辑接口重新提交还是新建一条？接口文档未见编辑接口 | 待平台确认；倾向新建一条并作废旧记录 |
+| Q4 | 重复创建（同身份证/同车牌）xxyb 侧是否幂等/报错？ | 以平台校验为准，我方先做提示 |
+| Q5 | 菜单项命名：创建司机 / 创建车辆 / 新增收款信息（与接口同名）还是 司机管理 / 车辆管理 / 收款信息？ | 待产品确认 |
+| Q6 | 税源地字段接口未见入参——是否随 `cid` 隐含？列表中税源地列取值来源？ | 待与平台确认 |
+
+> ⚠️ 待确认 Q6 补充：接口文档的请求参数中**没有税源地字段**，但参照页面（三十六匠）列表均有"税源地"列。需确认税源地是否由 `cid`（合作ID）隐含绑定，或需要额外参数。
+
+> ⚠️ 待确认 Q7：**企业收款人（accountType=ENTERPRISE）的 payeeIdCard 字段填什么？** 接口字段名为"收款人身份证"，企业场景下应填法定代表人身份证还是统一社会信用代码？原型当前按"企业填统一社会信用代码、个人填身份证"处理。
+
+---
+
+## 9. 验收要点（概要）
+
+1. 三个接口的 Header（token/cid）由平台配置注入，前端无感知；请求体字段与接口文档一致（逐字段核对）。
+2. 必填校验生效：司机（手机号/姓名/身份证）、车辆（车牌/颜色/车型/车长/能源类型/行驶证正反/有效期）、收款信息（类型/姓名/身份证/银行卡号；个人时手机号必填）。
+3. 有效期选择"长期"时提交值为字符串"长期"；日期字段格式 yyyy-MM-dd。
+4. 提交成功落库 `data.id` 并以"待审核"入列表；失败展示 `msg` 且表单保留。
+5. 收款人类型=企业时手机号非必填、个人时必填（联动）。
+6. 车牌颜色/车型/能源类型/准驾车型/收款人类型取值与 Code.html 枚举一致。
+7. 列表筛选（表头筛选行）与分页正常；审核状态展示正确。
+8. 权限：非授权角色只读；跨机构数据不可见。
+
+---
+
+## 10. 原型对照
+
+| 原型页面 | 说明 |
+|:---|:---|
+| 创建司机（列表 + 新增弹窗） | 对标三十六匠"司机上传"截图：表头筛选行 + 批量上传按钮 |
+| 创建车辆（列表 + 新增弹窗） | 对标"车辆上传"截图：车辆分类/车牌颜色/能源类型列 |
+| 新增收款信息（列表 + 新增弹窗） | 新增设计，列表含收款人类型 |
+| 侧边栏 | 小象开票菜单下新增三个菜单项（NEW 标识） |