feat: 增加门店身份注销流程
This commit is contained in:
@@ -0,0 +1,431 @@
|
||||
# 账号注销后端接口需求
|
||||
|
||||
> **2026-08-28 已被新范围替代:** 本次迭代改为使用旧 `account-deregister` 接口,仅注销当前 `store_user` 身份,不实施本文的主账号注销、新接口或恢复专用 Token 方案。当前接入情况见 [门店身份注销接入说明](门店身份注销接入说明.md)。下文保留为历史讨论记录。
|
||||
|
||||
更新日期:2026-08-27
|
||||
适用端:随心瞰商家版 iOS;后端账号状态应同时约束 Android、旧版本客户端及其他登录入口。
|
||||
文档性质:**接口需求建议稿,以下新增路径和字段尚未与后端确认,不代表线上已有接口。**
|
||||
|
||||
## 1. 需要后端提供什么
|
||||
|
||||
需要 **5 个注销接口、现有登录与鉴权流程改造,以及服务端到期处理任务**。
|
||||
|
||||
| 类型 | 建议接口 / 能力 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| 新增 | `GET /api/app/account-deletion/precheck` | 返回真实资产、注销影响说明及阻断原因 |
|
||||
| 新增 | `POST /api/app/account-deletion/send-sms-code` | 向主账号绑定手机号发送注销专用验证码 |
|
||||
| 新增 | `POST /api/app/account-deletion/submit` | 校验验证码和用户确认,提交注销申请 |
|
||||
| 新增 | `GET /api/app/account-deletion/status` | 查询当前账号的服务端注销状态及截止时间 |
|
||||
| 新增 | `POST /api/app/account-deletion/cancel` | 冷静期内由用户明确确认后取消注销 |
|
||||
| 修改 | `POST /api/app/v9/login` | 身份验证通过后区分正常登录、待注销恢复和不可恢复状态 |
|
||||
| 修改 | `POST /api/app/v9/set-user` 与统一鉴权 | 禁止待注销或已注销账号取得、使用业务 Token |
|
||||
| 服务端任务 | 到期注销、失败重试、会话失效 | 不依赖客户端在线或再次打开 App |
|
||||
|
||||
如果已有等价能力,可以复用后端现有路径,但需覆盖本文的数据和行为要求,不必重复建设。
|
||||
|
||||
### 当前客户端状态
|
||||
|
||||
- 已有设置入口、资产核验页、短信验证页、成功页、密码登录时的恢复确认和冷启动检查。
|
||||
- 当前为 `AccountDeletionMockService`:资产是固定示例,验证码固定为 `123456`,注销记录保存在本机 `UserDefaults`。
|
||||
- **目前不会发送真实短信,也不会注销后端账号或删除后端数据。**
|
||||
- 接入真实接口后,服务端状态为唯一依据;本机时间、手机号输入值及本地记录不能作为注销结果或操作权限的依据。
|
||||
|
||||
## 2. 账号范围与统一约定
|
||||
|
||||
### 2.1 注销对象
|
||||
|
||||
当前功能意图是注销**手机号登录对应的主账号及其关联业务身份**,不是仅退出当前登录,也不是只停用当前选中的景区或门店身份。
|
||||
|
||||
- 后端根据 Token 解析稳定的主账号 ID,并据此聚合所有关联景区、门店身份的数据。
|
||||
- 请求不接受客户端指定待注销的 `user_id`、`username`、`phone`、`scenic_id` 或 `store_id`;短信收件人也由后端确定。
|
||||
- 当前业务身份资料里的手机号可能与主账号绑定手机号不同,不能直接用业务身份手机号发送注销短信。
|
||||
- “解除景区、门店账号”指解除该用户的关联身份;**不应删除景区、门店实体,也不能误删其他用户、门店或客户共同拥有的数据**。
|
||||
- 若存在管理员、负责人或共享资产,需明确移交、保留或阻断策略,不能因为客户端勾选“放弃资产”就直接删除。
|
||||
|
||||
### 2.2 请求和响应
|
||||
|
||||
沿用当前 App 网络层约定:
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
token: <当前请求所需的凭证>
|
||||
X-APP-VERSION: <客户端版本>
|
||||
X-OS-TYPE: <客户端现有平台标识>
|
||||
```
|
||||
|
||||
当前工程使用 `token` 请求头,**不是** `Authorization: Bearer ...`。恢复专用凭证也建议放在同一请求头,由服务端识别凭证类型和权限。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
- 成功业务码沿用 `100000`;新增失败码由后端统一分配,见第 6 节。
|
||||
- JSON 字段使用 `snake_case`;布尔值使用 `true/false`,空列表使用 `[]`。
|
||||
- ID 建议统一返回字符串,客户端不依赖数据库自增 ID 或 UUID 的内部格式。
|
||||
- 时间统一使用带时区的 ISO 8601 字符串,例如 `2026-08-27T08:00:00Z`;客户端负责本地化显示。
|
||||
- 时间相关响应返回 `server_time`;冷静期截止、验证码到期和取消资格全部由服务端判断。
|
||||
|
||||
### 2.3 状态及七天冷静期
|
||||
|
||||
建议在真实服务中区分“不可再取消”和“数据已处理完成”,避免定时任务尚未完成就展示为永久删除成功。
|
||||
|
||||
| `state` | 含义 | 允许恢复 | 允许进入业务 |
|
||||
| --- | --- | --- | --- |
|
||||
| `none` | 没有注销申请 | 不适用 | 是 |
|
||||
| `pending` | 在冷静期内,待用户取消或到期 | 是,且服务端当前时间必须早于截止时间 | 否 |
|
||||
| `canceled` | 最近一次申请已取消 | 不适用;可以重新申请 | 是,需重新取得有效业务 Token |
|
||||
| `processing` | 已到截止时间,正在执行最终处理 | 否 | 否 |
|
||||
| `completed` | 服务端已完成约定的注销处理 | 否 | 否 |
|
||||
|
||||
流转:`none/canceled → pending → processing → completed`;仅 `pending` 且未到期时允许转为 `canceled`。
|
||||
|
||||
- 建议默认冷静期为提交成功后 `7 × 24` 小时,后端返回准确的 `scheduled_deletion_at`,客户端不自行推算。
|
||||
- 恰好到达截止时刻即不可取消;即使定时任务尚未运行,接口也必须立即按不可恢复处理。
|
||||
- 任务失败保持不可恢复状态,记录原因并重试,不能重新开放登录或重置冷静期。
|
||||
- 当前 Mock 没有 `processing` 状态;接入真实后端时客户端需同步扩展。
|
||||
|
||||
## 3. 五个接口的详细需求
|
||||
|
||||
### 3.1 注销前置核验
|
||||
|
||||
```http
|
||||
GET /api/app/account-deletion/precheck
|
||||
```
|
||||
|
||||
使用有效业务 Token,无查询参数。返回整个主账号范围内的资产快照、当前绑定手机号的脱敏值、注销后果,以及是否允许提交。
|
||||
|
||||
成功响应示例(资产数值仅为示例):
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"precheck_id": "precheck_example_001",
|
||||
"expires_at": "2026-08-27T08:10:00Z",
|
||||
"server_time": "2026-08-27T08:00:00Z",
|
||||
"masked_phone": "138****0000",
|
||||
"can_submit": true,
|
||||
"blocking_reasons": [],
|
||||
"assets": [
|
||||
{"kind": "wallet", "title": "钱包余额", "value": "0.00", "unit": "CNY", "value_text": "¥0.00"},
|
||||
{"kind": "works", "title": "作品与相册", "value": "36", "unit": "item", "value_text": "36个"},
|
||||
{"kind": "projects", "title": "项目", "value": "4", "unit": "item", "value_text": "4个"},
|
||||
{"kind": "cloud_files", "title": "云盘文件", "value": "8589934592", "unit": "byte", "value_text": "8 GB"}
|
||||
],
|
||||
"consequences": [
|
||||
"本人关联的景区与门店身份将解除",
|
||||
"个人作品和云盘文件将按已确认的规则处理",
|
||||
"提交后7天内再次登录并确认恢复,可取消注销"
|
||||
],
|
||||
"acknowledgement_version": "account-deletion-v1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 要求 |
|
||||
| --- | --- |
|
||||
| `precheck_id` / `expires_at` | 后端生成的核验快照标识及有效期,绑定当前主账号,用于确认用户看到的资产和后果 |
|
||||
| `masked_phone` | 主账号实际绑定手机号的脱敏值;不返回短信验证码 |
|
||||
| `can_submit` | 是否满足注销条件;客户端据此禁止或允许继续 |
|
||||
| `blocking_reasons` | 不可提交时返回 `[{"reason_code":"WALLET_NOT_SETTLED","message":"请先处理钱包余额或结算中的款项"}]`,可有多项 |
|
||||
| `assets` | 当前页面需要 `wallet`、`works`、`projects`、`cloud_files` 四类;零资产也返回对应项 |
|
||||
| `value` / `unit` / `value_text` | 原始值统一为字符串;金额为元且保留两位小数,计数、字节为整数字符串;`value_text` 供页面直接展示 |
|
||||
| `consequences` | 由后端按最终业务规则返回,不能宣称会删除实际需要保留的数据 |
|
||||
| `acknowledgement_version` | 本次注销说明版本,随提交保存确认记录 |
|
||||
|
||||
要求:
|
||||
|
||||
- 核验不得触发删除、资金扣除、身份解绑或短信发送。
|
||||
- 作品、相册、项目及云盘文件的统计口径和去重方式由后端明确,不能把共享资产全部算成该用户可删除的资产。
|
||||
- 余额、冻结款、提现中、未完成订单、未补缴收款等是否阻断,由产品和后端确认。**在规则确认前,建议未结清资金类问题阻断注销,不直接照搬 Mock 的“放弃余额”。**
|
||||
- 提交时必须再次校验条件。资产或影响范围发生需要重新确认的变化时,返回“请重新核验”,不得默默沿用旧快照。
|
||||
|
||||
### 3.2 发送注销短信验证码
|
||||
|
||||
```http
|
||||
POST /api/app/account-deletion/send-sms-code
|
||||
```
|
||||
|
||||
使用有效业务 Token,请求体为 `{}`。只发送给当前主账号绑定手机号,不接受任意手机号参数。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"verification_id": "verification_example_001",
|
||||
"masked_phone": "138****0000",
|
||||
"expires_in": 300,
|
||||
"retry_after": 60,
|
||||
"server_time": "2026-08-27T08:01:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `verification_id` 是验证码会话标识,绑定主账号、当时的绑定手机号及“账号注销”用途,提交时一并携带。
|
||||
- `expires_in`、`retry_after` 单位为秒;示例为 5 分钟有效、60 秒后可重发,实际值由后端配置并返回。
|
||||
- 使用 6 位数字验证码;不在响应、日志或埋点中返回明文验证码。
|
||||
- 设置账号、手机号、IP 等维度的频率限制及错误次数限制;重发后旧验证码失效。
|
||||
- 与登录、提现、实名认证等验证码用途隔离。可复用短信基础设施,不可混用验证码。
|
||||
- 主账号换绑手机号后,旧手机号对应的验证码会话及核验快照失效,要求重新开始。
|
||||
- 缺少绑定手机号、发送失败或触发限流时返回明确错误;前端不能在失败时显示“已发送”。
|
||||
|
||||
### 3.3 提交注销申请
|
||||
|
||||
```http
|
||||
POST /api/app/account-deletion/submit
|
||||
```
|
||||
|
||||
使用有效业务 Token。请求示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"client_request_id": "709277cb-2085-49c1-b80f-042476c7c36b",
|
||||
"precheck_id": "precheck_example_001",
|
||||
"verification_id": "verification_example_001",
|
||||
"sms_code": "482951",
|
||||
"acknowledged_asset_kinds": ["wallet", "works", "projects", "cloud_files"],
|
||||
"acknowledgement_version": "account-deletion-v1"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `client_request_id` | 是 | 客户端为本次提交生成的 UUID 字符串;网络重试沿用同一个值 |
|
||||
| `precheck_id` | 是 | 当前主账号的有效核验快照,不接受其他账号的快照 |
|
||||
| `verification_id` / `sms_code` | 是 | 验证码会话及用户输入的真实短信码;示例不是固定验证码 |
|
||||
| `acknowledged_asset_kinds` | 是 | 用户已确认的资产类别,须与快照中要求确认的集合一致 |
|
||||
| `acknowledgement_version` | 是 | 用户确认的注销说明版本 |
|
||||
|
||||
成功响应示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"state": "pending",
|
||||
"can_cancel": true,
|
||||
"server_time": "2026-08-27T08:02:00Z",
|
||||
"request": {
|
||||
"id": "deletion_example_001",
|
||||
"client_request_id": "709277cb-2085-49c1-b80f-042476c7c36b",
|
||||
"status": "pending",
|
||||
"submitted_at": "2026-08-27T08:02:00Z",
|
||||
"scheduled_deletion_at": "2026-09-03T08:02:00Z",
|
||||
"canceled_at": null,
|
||||
"completed_at": null,
|
||||
"acknowledged_asset_kinds": ["wallet", "works", "projects", "cloud_files"],
|
||||
"acknowledgement_version": "account-deletion-v1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
处理要求:
|
||||
|
||||
1. 服务端重新校验身份、验证码、快照、确认版本以及资金和未完成业务条件。
|
||||
2. 原子保存申请及用户确认记录、消耗验证码,并使该主账号所有设备上的业务 Token、旧登录临时 Token 和刷新凭证失去业务访问权限。
|
||||
3. 冷静期内保留可恢复的身份及数据,不提前执行不可逆删除;状态必须限制新建订单、上传、提现等业务操作。
|
||||
4. 同一主账号同一时刻最多有一条有效申请。已成功的同一 `client_request_id` 重试应返回原申请,不因验证码已消费而重复报错;同一幂等键不能承载不同请求内容。
|
||||
5. 账号已有待处理申请时,不创建第二条,也不延长原截止时间;返回原状态或可识别的“已有申请”错误,客户端转查询状态。
|
||||
6. 成功页使用服务端返回的截止时间。客户端收到成功响应后应立即清理业务登录态;即使用户尚未点击成功页“退出”,后端也已禁止业务访问。
|
||||
|
||||
**响应丢失的处理:** 提交可能已成功且原 Token 已失效。此时客户端重新完成身份验证,通过登录接口取得恢复专用凭证,再查 `status`;不得把网络超时直接当成提交失败,也不得为了查询结果自动取消注销。
|
||||
|
||||
### 3.4 查询注销状态
|
||||
|
||||
```http
|
||||
GET /api/app/account-deletion/status
|
||||
```
|
||||
|
||||
- 无查询参数,以凭证定位主账号。
|
||||
- 接受有效业务 Token、正常登录临时 Token,或第 4 节定义的恢复专用 Token;不能提供匿名按手机号查询。
|
||||
- 原业务 Token 已被注销操作撤销时,不重新赋予其查询权限,应先重新验证身份取得恢复专用 Token。
|
||||
- 用于启动检查、回到前台、多设备状态校准,以及提交/取消请求超时后的结果确认。
|
||||
|
||||
响应 `data` 与提交接口一致,包含 `state`、`can_cancel`、`server_time`、`request`。无申请时:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"state": "none",
|
||||
"can_cancel": false,
|
||||
"server_time": "2026-08-27T08:00:00Z",
|
||||
"request": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `canceled` 返回最近取消的申请和 `canceled_at`;`completed` 返回实际完成时间 `completed_at`。
|
||||
- `can_cancel` 由后端计算,只能在状态为 `pending` 且未到截止时刻时为 `true`。
|
||||
- 查询不得取消注销或延长冷静期。到期任务尚未完成时返回 `processing`,不能仅凭时间到了就返回 `completed`。
|
||||
- 状态查询失败时,不应默认账号正常;客户端提示重试或重新登录,业务接口仍由后端鉴权保护。
|
||||
|
||||
### 3.5 取消注销申请
|
||||
|
||||
```http
|
||||
POST /api/app/account-deletion/cancel
|
||||
token: <恢复专用 Token>
|
||||
```
|
||||
|
||||
只有重新验证身份且用户点击“恢复账号并登录”后调用:
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "deletion_example_001"
|
||||
}
|
||||
```
|
||||
|
||||
成功响应示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"request_id": "deletion_example_001",
|
||||
"state": "canceled",
|
||||
"canceled_at": "2026-08-28T01:00:00Z",
|
||||
"server_time": "2026-08-28T01:00:00Z",
|
||||
"login": {
|
||||
"token": "new-account-selection-token",
|
||||
"scenic_users": [],
|
||||
"store_users": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `login` 结构复用现有 v9 登录响应;示例数组省略业务内容,实际需返回恢复后当前可选的景区、门店身份。
|
||||
- 返回的 `login.token` 为新生成的正常账号选择临时 Token;客户端继续走原有单账号自动选择、多账号选择及 `/v9/set-user` 流程,不复用注销前的旧凭证。
|
||||
- `request_id` 必须与凭证绑定的主账号和注销申请一致,不能取消别人的申请或该账号下一次新申请。
|
||||
- 与到期任务通过事务或等效并发控制互斥;按服务端时间决定取消是否成功,不能出现既恢复又删除的结果。
|
||||
- 对同一已取消申请的重试,不重复改变状态或产生副作用。若凭证仍有效,可返回原取消结果和有效登录上下文;若凭证已撤销或过期,重新登录确认状态,不要求用户再次取消。
|
||||
- 到期、`processing`、`completed` 均拒绝恢复,返回可识别错误;不得重新启用旧 Token。
|
||||
|
||||
## 4. 登录、会话与多端配合
|
||||
|
||||
### 4.1 调整现有 `/api/app/v9/login`
|
||||
|
||||
保留现有手机号密码登录参数。必须先完成密码/验证码等身份验证,再返回该主账号的注销状态,避免泄露任意手机号是否注册或注销。
|
||||
|
||||
| 状态 | 登录接口行为 |
|
||||
| --- | --- |
|
||||
| `none` / `canceled` | 沿用当前 `token`、`scenic_users`、`store_users`;可附带最新注销状态 |
|
||||
| 未到期的 `pending` | 不签发正常账号选择或业务 Token;返回申请信息和恢复专用 Token,等待用户决定 |
|
||||
| `processing` / `completed` | 返回明确的不可登录、不可恢复业务错误,不签发可登录凭证 |
|
||||
|
||||
待注销登录建议使用成功 Envelope 承载“验证身份成功但尚未登录”的结果:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 100000,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"token": "",
|
||||
"scenic_users": [],
|
||||
"store_users": [],
|
||||
"account_deletion": {
|
||||
"state": "pending",
|
||||
"request_id": "deletion_example_001",
|
||||
"submitted_at": "2026-08-27T08:02:00Z",
|
||||
"scheduled_deletion_at": "2026-09-03T08:02:00Z",
|
||||
"server_time": "2026-08-28T01:00:00Z",
|
||||
"can_cancel": true
|
||||
},
|
||||
"recovery_token": "opaque-recovery-token",
|
||||
"recovery_token_expires_at": "2026-08-28T01:10:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
恢复专用 Token 要求:
|
||||
|
||||
- 短时有效,并绑定主账号、当前注销申请和允许的操作;示例有效期为 10 分钟,实际由后端配置。
|
||||
- **仅可查询注销状态和取消该申请**,不能调用 `/v9/set-user`、订单、钱包、文件下载等业务接口,也不能兑换或刷新成业务 Token。
|
||||
- 不能通过改请求参数变成其他用户的凭证;不记录到普通日志、埋点或 URL。
|
||||
- 用户选择“暂不登录”只结束本次登录,不调用取消接口;重新登录或查询本身不得自动恢复账号。
|
||||
- 取消完成后撤销该申请的恢复操作权限;新登录凭证按取消接口约定返回。
|
||||
|
||||
### 4.2 修改 `/api/app/v9/set-user` 和统一鉴权
|
||||
|
||||
- 无论客户端是否接入新功能,待注销及不可恢复账号都不能通过旧临时 Token、刷新 Token、账号切换或其他登录入口继续使用业务。
|
||||
- 校验“凭证属于谁、凭证可做什么、账号当前是什么状态”,不能只检查签名或过期时间。
|
||||
- 提交注销需要覆盖同一主账号的全部设备和全部关联业务身份,不仅让提交申请的 iPhone 退出。
|
||||
- Android 当前有 `/v9/login` 的密码和短信两种登录方式;所有方式执行相同的状态检查。iOS 短信登录入口目前仍待接入,不能因此遗漏后端约束。
|
||||
- 冷静期取消后签发新凭证,不恢复旧凭证的有效性;业务身份列表以取消时的最新数据为准。
|
||||
|
||||
### 4.3 与客户端接入的关系
|
||||
|
||||
当前本地 `loginState`、`cancelDeletion` 是同步方法,接入网络后需改为异步;不能只替换 Mock 类名。
|
||||
|
||||
客户端还需扩展登录返回模型、恢复专用 Token 上下文、`processing` 状态、短信倒计时、阻断原因和核验快照处理。当前 Mock 使用登录输入框中的手机号取消注销,真实接口必须改用受验证的主账号/申请上下文,不能继续依赖可编辑输入值。
|
||||
|
||||
当前 Mock 申请 ID 使用 Swift `UUID`,资产枚举原始值包含 `cloudFiles`;本文建议接口使用字符串 ID 和 `cloud_files`。客户端需通过网络 DTO 显式映射,不能把本地 Mock 模型直接序列化后当作请求契约。
|
||||
|
||||
## 5. 服务端必须负责的后台处理
|
||||
|
||||
- 提交成功后持久保存申请,App 卸载、退出或长期离线都不影响到期处理。
|
||||
- 冷静期内不执行不可逆清理;到期后先禁止恢复,再按最终确认的规则解除身份、处理个人资产和第三方关联。
|
||||
- 共享资产、资金账务、交易记录、客户已购买内容等分别制定处理方案;需要保留的记录与可删除的个人数据应区分,保留范围及周期由相关负责人确认。
|
||||
- 处理任务可重复执行且有重试机制;只有约定的必需处理步骤完成后才标记 `completed`,部分失败不能假报成功。
|
||||
- 保留可审计的申请、确认说明版本、时间、取消记录、处理进度及失败原因;审计中不保留明文验证码或 Token。
|
||||
- 到期删除与取消操作必须有统一的并发保护;业务鉴权和后台任务读取一致的主账号状态。
|
||||
- 需要测试环境的可控时间或缩短冷静期能力,以便验证到期边界及失败重试;不得在生产开放客户端任意修改截止时间的接口。
|
||||
|
||||
## 6. 错误返回要求
|
||||
|
||||
沿用整数 `code` 和可直接展示的中文 `msg`。以下名称是**待后端分配业务码的语义清单**,不是现有错误码。
|
||||
|
||||
| 错误语义 | 典型场景 | 客户端处理 |
|
||||
| --- | --- | --- |
|
||||
| `ACCOUNT_IDENTITY_REQUIRED` | 主账号没有可用于验证的绑定手机号 | 提示先处理账号信息 |
|
||||
| `DELETION_BLOCKED` | 资金未结清、订单未完成、负责人未移交等 | 展示阻断原因,禁止提交 |
|
||||
| `PRECHECK_EXPIRED` / `PRECHECK_CHANGED` | 快照过期、资产或说明版本发生变化 | 重新核验并要求再次确认 |
|
||||
| `ACKNOWLEDGEMENT_REQUIRED` | 缺少必需资产确认或确认版本不匹配 | 返回资产核验页 |
|
||||
| `SMS_SEND_FAILED` / `SMS_RATE_LIMITED` | 短信发送失败或限流 | 提示重试;限流返回重试秒数 |
|
||||
| `SMS_CODE_INVALID` / `SMS_CODE_EXPIRED` / `SMS_ATTEMPTS_EXCEEDED` | 验证码错误、过期、尝试超限 | 提示重输或重新发送 |
|
||||
| `DELETION_ALREADY_PENDING` | 已有有效申请 | 查询原申请,不重复创建 |
|
||||
| `NO_PENDING_DELETION` | 申请不存在或并非当前可取消申请 | 查询最新状态 |
|
||||
| `DELETION_NOT_CANCELABLE` | 已到截止时间或正在最终处理 | 不再提供恢复入口 |
|
||||
| `ACCOUNT_DELETION_COMPLETED` | 已完成注销 | 禁止登录和恢复 |
|
||||
| `RECOVERY_TOKEN_INVALID` / `RECOVERY_TOKEN_EXPIRED` | 恢复凭证失效 | 重新验证身份,不自动取消 |
|
||||
| `IDEMPOTENCY_CONFLICT` | 同一幂等键用于不同请求内容 | 停止自动重试,提示重新操作 |
|
||||
|
||||
错误响应继续采用现有 Envelope。后端如需在 `data` 中返回 `blocking_reasons`、`retry_after` 等结构化详情,需同时给出字段契约;当前 iOS `APIClient` 对失败响应只暴露 `code/msg`,接入时需要补充详情解析。
|
||||
|
||||
**与现有全局登录失效处理区分:** 当前 iOS 会将 HTTP `401/403` 及业务码 `180024`、`100091`、`100090`、`100060` 视为登录失效。资产阻断、验证码错误、快照过期等业务问题不要复用这些码,避免误触发全局退出。真实凭证失效仍沿用项目鉴权规则。
|
||||
|
||||
## 7. 联调验收清单
|
||||
|
||||
1. 主账号关联多个景区、门店时,核验范围完整;切换业务身份不会变成另一个注销对象;不能查询、提交或取消其他主账号的申请。
|
||||
2. 无手机号、无资产、存在余额/冻结款/未完成业务时,分别返回约定的正常或阻断结果。
|
||||
3. 正确验证码可提交;错误、过期、重发前旧码、其他用途码、其他账号验证码都不可提交。
|
||||
4. 资产确认不完整、核验过期、资产发生变化、说明版本不一致时,后端拒绝并要求重新确认。
|
||||
5. 成功申请返回准确截止时间;重复请求不产生新申请、不重置冷静期;请求超时后可重新验证身份并查到真实结果。
|
||||
6. 提交成功后所有设备及旧版本业务访问受限;旧 Token、账号选择、短信登录等不能绕过注销状态。
|
||||
7. 冷静期登录只显示恢复确认;点“暂不登录”保持待注销,点“恢复账号并登录”后取消并取得新的账号选择凭证。
|
||||
8. 恢复专用 Token 只能查询状态和取消绑定申请;不能访问业务或取消其他申请。
|
||||
9. 截止前可取消、恰好截止不可取消;取消与到期任务并发时只产生一个一致结果。
|
||||
10. 未运行 App 也会按期处理;任务部分失败会重试,处理期间保持不可恢复,未完成时不返回 `completed`。
|
||||
11. 已取消账号可再次发起新申请;旧申请和旧恢复凭证不能影响新申请。
|
||||
12. 完成注销后不能登录或恢复;共享数据、客户内容和需保留记录按确认的方案处理,没有越权删除。
|
||||
|
||||
## 8. 请后端与产品确认并回传
|
||||
|
||||
- **账号及数据边界:** 主账号映射、关联身份范围;作品与相册/项目的统计口径;共享资产和已售内容的处理方式。
|
||||
- **准入规则:** 余额是否允许放弃;冻结资金、提现中、未完成订单、线下未补缴款及负责人身份是否阻断,如何解除阻断。
|
||||
- **时限和最终处理:** 七天是否按 168 小时计算;到期处理内容、记录保留范围与周期;注销后同手机号能否重新注册,且不得恢复旧账号数据。
|
||||
- **接口契约:** 最终路径、字段类型、完整正常/异常响应、业务码、短信频控、恢复凭证权限及有效期。
|
||||
- **联调交付:** 测试环境地址、测试账号及各状态样例、到期和失败重试验证方式、预计可联调时间。
|
||||
|
||||
上述规则确认前,客户端中的“永久删除”“放弃资产”等 Mock 文案不能直接作为最终业务承诺,应随实际后端处理规则调整。
|
||||
Reference in New Issue
Block a user