foodie-server/specs/034-stall-qualification/app-frontend-adjustment.md

摊位资料审核：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 要展示旗下摊位进度，可使用此接口；只返回进度摘要，不返回负责人、证件及图片。

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

{
  "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 前端完成后应验证新建、草稿回显、提交、待审核只读、驳回重提、历史图片和银行下拉。