draft

docs/design/002-heepay-customer-file-upload.md

@@ -0,0 +1,135 @@
+# 002 - 汇元商户文件上传 API
+
+**接口名称：** `customer.file.upload`
+**更新时间：** 2025-11-28
+**状态：** 已实现
+
+---
+
+## 调用地址
+
+| 环境 | 地址 |
+|------|------|
+| 生产 | `https://openapi.heepay.com/v1/customer/gateway` |
+| 沙箱 | `http://openapi.heepaydev.com/v1/customer/gateway` |
+
+与入网接口共用同一进件网关（`channels.heepay.merchant_url`）。
+
+---
+
+## 接口说明
+
+上传图片/视频/文件，返回 `file_id`，供入网接口（001）中所有 `*_img` 字段使用。**必须先上传文件获取 `file_id`，再调用入网接口。**
+
+---
+
+## 请求业务参数（biz_content）
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `file_content` | 文件内容 | 是 | ByteData | 文件二进制内容（Base64 编码后传入） |
+| `file_sign` | 文件内容签名 | 是 | String | 文件内容的 MD5 值，用于校验文件完整性 |
+| `file_media_type` | 文件类型 | 是 | String | 参照【文件类型编码】列表（待补充） |
+
+---
+
+## 响应业务参数
+
+| 字段 | 名称 | 必填 | 类型 | 说明 |
+|------|------|------|------|------|
+| `file_id` | 文件 ID | 否 | String | 上传成功后返回，传入入网接口的 `*_img` 字段 |
+
+---
+
+## 支持的文件格式
+
+| 类型 | 格式 |
+|------|------|
+| 图片 | `png` / `bmp` / `gif` / `jpg` / `jpeg` |
+| 视频 | `mp4` / `flv` / `avi` / `rm` / `rmvb` / `wav` |
+| 文件 | `zip` / `rar` / `pdf` |
+
+---
+
+## 业务错误码
+
+| 错误码 | 说明 | 处理建议 |
+|--------|------|---------|
+| `invalid_parameter_file_type_not_correct` | 文件类型不正确 | 检查格式是否在支持列表内 |
+| `invalid_parameter_file_size_too_big` | 文件过大 | 压缩后重新上传 |
+| `invalid_parameter_file_sign_can_not_null` | 文件签名不能为空 | 传入 `file_sign`（MD5） |
+| `invalid_parameter_file_sign_err` | 文件签名异常 | 确认文件是否损坏，重新计算 MD5 |
+| `invalid_parameter_file_has_err` | file 有误，疑似被修改 | 检查文件完整性 |
+| `invalid_parameter_file_need_ext` | 文件名需带扩展名 | 上传时文件名需包含扩展名 |
+| `unknown_exception` | 系统未知问题 | 参考返回描述 |
+| `unknown_error_gateway` | 网关系统不可用 | 稍后重试 |
+| `invalid_auth` | 授权权限不足 | 检查签名/权限 |
+| `missing_parameter` | 缺少参数 | 补充必填参数 |
+| `invalid_parameter` | 无效参数 | 检查参数格式 |
+| `invalid_request` | 无效请求 | 参考返回详细信息 |
+| `biz_failure` | 业务错误 | 参照具体错误提示 |
+| `service_not_exists` | 服务不存在 | 确认服务是否开通 |
+| `service_time_out` | 系统繁忙 | 稍后重试 |
+| `channel_error` | 通道系统异常 | 用相同参数重新调用 |
+
+---
+
+## 实现要点
+
+1. **`file_content` 编码方式**：ByteData 类型，实现时需将文件二进制内容 Base64 编码后放入 `biz_content` JSON 字符串中
+2. **`file_sign` 计算**：对原始文件二进制内容计算 MD5，得到 32 位小写十六进制字符串
+3. **文件名带扩展名**：请求中需要携带文件名（含扩展名），具体字段名待联调确认
+4. **调用顺序**：文件上传 → 获取 `file_id` → 入网申请（001），`file_id` 需持久化存储备用
+5. **复用性**：同一文件可上传一次，`file_id` 在多个字段中复用（如法人正反面同一人时）
+
+---
+
+## 文件类型编码（file_media_type）
+
+| 文件名称 | 类型值 |
+|---------|--------|
+| 营业执照 | `01` |
+| 开户许可证/开户证明照 | `02` |
+| 门头照 | `03` |
+| 店内场景照 | `04` |
+| 收银台照 | `05` |
+| 法人身份证正面照 | `06` |
+| 法人身份证反面照 | `07` |
+| 联系人身份证正面照 | `08` |
+| 联系人身份证反面照 | `09` |
+| 公司大楼照 | `10` |
+| 公司前台照 | `11` |
+| 结算银行卡正面照 | `12` |
+| 结算银行卡反面照 | `13` |
+| 结算人手持银行卡正面照 | `14` |
+| 经营者身份证正面照 | `15` |
+| 经营者身份证反面照 | `16` |
+| 经营者手持身份证正面照 | `17` |
+| 经营者手持银行卡正面照 | `18` |
+| 其它图片1 | `19` |
+| 其它图片2 | `20` |
+| 开户意愿视频 | `50` |
+| 分账协议 | `52` |
+
+> 对照入网接口（001）字段与文件类型的映射关系：
+>
+> | 入网字段 | file_media_type |
+> |---------|----------------|
+> | `subject_info.cert_img`（营业执照） | `01` |
+> | `settlement_info.open_account_img`（开户许可证） | `02` |
+> | `scene_info.shop_brand_img`（门头照/公司大楼照） | `03` 或 `10` |
+> | `scene_info.customer_service_img`（收银台照/公司前台照） | `05` 或 `11` |
+> | `scene_info.work_env_img`（店内场景照） | `04` |
+> | `identity_info.cert_front_img`（法人证件正面） | `06` |
+> | `identity_info.cert_back_img`（法人证件反面） | `07` |
+> | `contact_info.cert_front_img`（联系人证件正面） | `08` |
+> | `contact_info.cert_back_img`（联系人证件反面） | `09` |
+> | `addition_info.open_merch_video`（开户意愿视频） | `50` |
+> | `addition_info.sharing_protocol_img`（分账协议） | `52` |
+
+---
+
+## 待补充
+
+- [ ] 文件大小限制（图片/视频各自上限）
+- [ ] 文件名字段名称确认（`file_name`？）