# 摊位资料审核：App 前端对接说明（2026-10-16）

本说明供商家 App 前端对接摊位资料审核。摊位资料属于摊位，不属于某个登录账号；摊主账号（`userType=4`）可填写、提交和查看本摊位申请。夜市主账号（`userType=3`）只能通过进度接口查看旗下摊位状态。普通商家资料页不因此改变。本次只交付后端与两个 PC 的代码及 App 对接文档，App 页面代码需由 App 前端实现。

## 页面字段

顶部照片使用已有的摊位现场照片 `stallImageUrls`。摊位名称、地址、所属夜市由 `GET /stall/qualification` 返回，页面只展示，不作为保存参数提交。所有摊位使用同一套字段和必填规则，不区分个人或公司经营。

| 页面项目 | 请求字段 | 提交时要求 | 限制 |
|---|---|---|---|
| 负责人姓名 | `responsibleName` | 必填 | 最多 100 字符 |
| 手机号码 | `contactPhone` | 必填 | 最多 32 字符 |
| 身份证／护照号码 | `identityNumber` | 必填 | 最多 64 字符 |
| 身份证／护照图片 | `identityImageUrls` | 至少 1 张 | 图片数组 |
| 摊位现场照片 | `stallImageUrls` | 至少 1 张 | 图片数组 |
| 银行账户户名 | `bankAccountName` | 必填 | 最多 100 字符 |
| 银行名称 | `bankName` | 必填 | 最多 100 字符；见下方银行列表 |
| 银行账号 | `bankAccountNo` | 必填 | 最多 64 字符 |
| 银行账户证明 | `bankProofImageUrls` | 至少 1 张 | 图片数组 |
| 电子邮箱 | `email` | 选填 | 最多 255 字符；填写时须为有效邮箱 |
| 摊位介绍 | `stallIntroduction` | 选填 | 最多 1000 字符 |
| 营业登记证明 | `businessRegistrationImageUrls` | 选填 | 图片数组 |
| 董监事资料查询截图 | `directorScreenshotImageUrls` | 选填 | 图片数组 |
| 食品业者登录字号 | `foodRegistrationNumber` | 选填 | 最多 64 字符 |
| 食品业者登录证明 | `foodRegistrationImageUrls` | 选填 | 图片数组 |
| 实质受益人声明（UBO） | `uboDeclarationImageUrls` | 选填 | 图片数组 |

每组图片最多 5 张，每张最多 5 MB，仅支持 JPEG/PNG。草稿允许缺必填项；提交时 App 应先提示缺失项，服务端仍会再次校验。选填文本可传空字符串，选填图片可传空数组。银行四项只作为审核材料快照保存，不会自动修改实际收款银行卡或支付设置。

## 接口与数据流

摊位资料接口沿用商家 App 的 `token` 请求头；成功响应为 `{ "code": 200, "msg": "...", "data": ... }`。`storeId` 从登录账号的摊位绑定推导，保存时不要传 `storeId`、状态、审核人、摊位名称或地址。

1. `GET /stall/qualification`：进入页面及保存、提交后刷新资料。读取 `data.version` 作为下一次保存或提交请求的版本；首次没有申请时为 `0`。`data.currentApplication` 是当前申请，`data.approvedApplication` 是当前有效的已通过申请，二者可能不是同一版本。还返回 `storeId`、`stallName`、`stallAddress`、`nightMarketId` 和 `history`。`history` 是摘要，查看某条完整材料再调用详情接口。
2. `GET /infouser/user/bankList`：银行名称下拉数据来自 `data` 数组，选项显示 `dictLabel`，保存 `dictLabel` 到 `bankName`，与商家 PC 一致。
3. `POST /utils/Upload`：使用 `multipart/form-data`，文件字段名 `file`。成功后把响应的 `data`（例如 `/profile/upload/2026/10/16/photo.png`）放入对应图片数组；保存路径字符串，不传图片二进制或完整外部 URL。上传中禁止保存、提交。公共路径可按后端域名加返回路径预览。
4. `POST /stall/qualification/draft`：JSON body 保存草稿。即使资料不完整也可保存；填写了邮箱或上传了图片时仍须符合格式和文件规则。
5. `POST /stall/qualification/submit`：与草稿使用相同 JSON body，服务端校验必填资料并提交审核。成功后使用返回的 `data.version` 和 `data.currentApplication` 更新页面。
6. `GET /stall/qualification/applications/{id}`：点击 `history` 中的某条记录时，读取该版本完整资料与图片；只能查看本人摊位。历史申请只读。
7. `GET /stall/qualification/market`：如夜市主 App 要展示旗下摊位进度，可使用此接口；只返回进度摘要，不返回负责人、证件及图片。

保存或提交请求示例（图片路径和填写内容仅为格式示例）：

```json
{
  "version": 0,
  "responsibleName": "负责人姓名",
  "contactPhone": "09xxxxxxxx",
  "identityNumber": "证件号码",
  "email": "",
  "stallIntroduction": "",
  "bankAccountName": "账户户名",
  "bankName": "银行名称",
  "bankAccountNo": "银行账号",
  "identityImageUrls": ["/profile/upload/2026/10/16/id.png"],
  "stallImageUrls": ["/profile/upload/2026/10/16/stall.png"],
  "bankProofImageUrls": ["/profile/upload/2026/10/16/bank.png"],
  "businessRegistrationImageUrls": [],
  "directorScreenshotImageUrls": [],
  "foodRegistrationNumber": "",
  "foodRegistrationImageUrls": [],
  "uboDeclarationImageUrls": []
}
```

## 状态与操作

| `currentApplication.status` | 页面显示 | 可操作行为 |
|---|---|---|
| `null`（无申请） | 未提交 | 填写、保存草稿、提交 |
| `0` | 草稿 | 编辑、保存草稿、提交 |
| `1` | 待审核 | 展示已提交资料，不允许修改或重复提交 |
| `2` | 已通过 | 展示审核结果；再次修改时会创建新申请版本，旧有效版本在新申请通过前继续有效 |
| `3` | 已驳回 | 展示 `rejectReason`；修改后保存或重新提交会创建新申请版本 |

不要仅凭当前申请状态判断是否已有有效资质：应看 `approvedApplication` 是否存在。审核通过也不会自动设置摊位营业状态。遇到版本冲突时重新调用 `GET /stall/qualification`，让用户确认最新资料后再操作，不能自动覆盖。旧待审核申请如果缺少新增的银行资料，平台不能直接审核通过，需要驳回后由摊主补齐重提。

## 图片历史兼容与上线前提

新上传统一使用 `/utils/Upload`。历史资料可能包含旧私有引用（如 `storeId/UUID.jpg`），这种引用用 `GET /stall/qualification/files/{storeId}/{fileName}` 携带 `token` 读取并显示；不要把它拼成公开图片 URL。图片链接可能包含证件材料，不要把完整申请、图片路径或请求体写入普通日志。

后端读取新字段前，须先由开发者手动执行 `updatesql/sql.md` 末尾的 **2026-10-16 摊位资料审核补充字段（034）** SQL。本轮未执行数据库迁移或真实 App 联调；App 前端完成后应验证新建、草稿回显、提交、待审核只读、驳回重提、历史图片和银行下拉。