Yb-QaAutomationHub/requirements/小象开票收款方创建需求.md

# 小象开票 —— 收款方创建需求文档（创建司机 / 创建车辆 / 新增收款信息）

> **版本**: 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<String> | 挂靠协议（多附件 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 标识） |