xst
5e4e978cd5
- 原型评估_滇中好运物流云_20260917/：物流云原型评估产物（含核对表与字段对比表） - requirements/小象开票收款方创建需求.md + prototypes/小象开票原型.html：小象开票建司机/车辆/收款信息需求 - requirements.txt：Execute 战区依赖调整（移除 pytest/allure-pytest/requests，改用 pytest-html，Appium 默认注释） - .claude/launch.json：新增物流公司管理原型预览服务（wuliu-proto:8138） - .agents/skills：agent 技能定义
16 KiB
16 KiB
小象开票 —— 收款方创建需求文档（创建司机 / 创建车辆 / 新增收款信息）
版本: 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（风格与"物流公司管理"原型一致，数据为演示数据） UI 参考: 三十六匠发票"司机上传 / 车辆上传"页面截图（表头筛选行 + 批量上传按钮样式） 菜单位置: 小象开票（顶级菜单）下新增：创建司机、创建车辆、新增收款信息
1. 背景与目标
小象开票（联合开票）业务要求承运方（司机、车辆）及其收款账户先在 xxyb 平台完成建档，才能开票。当前建档在小象平台侧手工操作，与运八系统脱节。本次在小象开票菜单下新增三个功能，直接调用 xxyb 开放接口完成建档：
- 创建司机：录入司机信息 → 调用
createDriver在 xxyb 平台创建司机档案； - 创建车辆：录入车辆信息 → 调用
createVehicle创建车辆档案； - 新增收款信息：录入收款人账户 → 调用
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. 验收要点（概要）
- 三个接口的 Header（token/cid）由平台配置注入，前端无感知；请求体字段与接口文档一致（逐字段核对）。
- 必填校验生效：司机（手机号/姓名/身份证）、车辆（车牌/颜色/车型/车长/能源类型/行驶证正反/有效期）、收款信息（类型/姓名/身份证/银行卡号；个人时手机号必填）。
- 有效期选择"长期"时提交值为字符串"长期"；日期字段格式 yyyy-MM-dd。
- 提交成功落库
data.id并以"待审核"入列表；失败展示msg且表单保留。 - 收款人类型=企业时手机号非必填、个人时必填（联动）。
- 车牌颜色/车型/能源类型/准驾车型/收款人类型取值与 Code.html 枚举一致。
- 列表筛选（表头筛选行）与分页正常；审核状态展示正确。
- 权限：非授权角色只读；跨机构数据不可见。
10. 原型对照
| 原型页面 | 说明 |
|---|---|
| 创建司机（列表 + 新增弹窗） | 对标三十六匠"司机上传"截图：表头筛选行 + 批量上传按钮 |
| 创建车辆（列表 + 新增弹窗） | 对标"车辆上传"截图：车辆分类/车牌颜色/能源类型列 |
| 新增收款信息（列表 + 新增弹窗） | 新增设计，列表含收款人类型 |
| 侧边栏 | 小象开票菜单下新增三个菜单项（NEW 标识） |