lujiuyin/suixinkan_uikit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 增加门店身份注销流程

Browse Source
This commit is contained in:
lujiuyin
2026-08-31 09:43:14 +08:00
parent 396597a160
commit e529bb5942
35 changed files with 6062 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/账号注销后端接口需求-简洁版.md
+43
View File
@@ -0,0 +1,43 @@
# 账号注销后端接口需求（简洁版）
> **本方案已被替代：** 2026-08-28 确认改用旧接口实现当前门店身份注销，不再实施主账号注销。参见 [门店身份注销接入说明](门店身份注销接入说明.md)。下文仅为历史记录。
当前 iOS 已有注销页面和本地 Mock 流程，需要后端提供真实能力。以下路径为建议，可复用已有等价接口。
## 1. 需要的接口
统一前缀：`/api/app/account-deletion`
| 接口 | 入参 | 需要返回 |
| --- | --- | --- |
| `GET /precheck` 注销核验 | 无，以 Token 识别主账号 | 钱包、作品与相册、项目、云盘资产；脱敏手机号；注销影响说明；是否可注销及阻断原因；核验标识和有效期 |
| `POST /send-sms-code` 发送验证码 | 无，发送至主账号绑定手机号 | 验证码会话标识、有效秒数、重发间隔；不返回验证码 |
| `POST /submit` 提交申请 | 核验标识、验证码会话及验证码、资产确认项、说明版本、幂等请求 ID | 申请 ID、状态、提交时间、计划注销时间 |
| `GET /status` 查询状态 | 无，以有效身份凭证识别主账号 | 当前状态、申请信息、能否取消、服务端时间 |
| `POST /cancel` 取消申请 | 申请 ID，使用恢复专用凭证 | 取消结果、新登录临时 Token、当前可选景区/门店身份 |
沿用现有 `token` 请求头和 `code/msg/data` 响应结构，成功码为 `100000`。错误需区分：注销条件不满足、核验过期、验证码错误/过期/限流、已有申请、超过取消期限、凭证失效。
## 2. 现有登录与鉴权需要配合
- 修改 `POST /api/app/v9/login`：身份验证通过后，正常账号按原流程登录；冷静期账号返回注销信息及**短时恢复专用 Token**，等待用户确认；已到期或已注销账号禁止登录。
- 恢复专用 Token 只能查询状态和取消绑定申请，不能访问业务接口。用户点击“恢复账号并登录”才调用取消接口，重新登录本身不能自动取消注销。
- `/api/app/v9/set-user`、刷新凭证及统一鉴权必须检查主账号状态，防止旧 Token、旧版本或其他设备绕过限制。取消成功后签发新凭证，不恢复旧 Token。
## 3. 必须保证的业务规则
1. **注销范围：** 手机号登录对应的主账号及其关联身份，由后端从凭证识别；不接受客户端指定任意手机号或用户 ID，不删除景区、门店实体或他人的共享资产。
2. **提交校验：** 后端再次检查验证码、资产确认及未完成业务；重复提交不能生成多个申请或延长冷静期。
3. **七天冷静期：** 截止时间由后端返回和判断，截止前可取消，恰好到期即不可取消；取消与到期任务必须互斥。
4. **会话限制：** 提交成功立即禁止该主账号全部设备的业务访问；客户端清理登录态。提交超时不能直接视为失败，应重新验证身份后查询结果。
5. **到期处理：** 后端自动执行，不依赖 App 在线；冷静期内不做不可逆删除，处理失败可重试，实际处理完成后才标记已注销。
建议状态：`none` 无申请、`pending` 冷静期、`canceled` 已取消、`processing` 到期处理中、`completed` 已完成。
## 4. 请后端与产品确认
- 余额、冻结款、提现中、未完成订单、线下未补缴款和负责人身份是否阻断注销，如何处理。
- 个人资产、共享资产、客户已购内容和交易记录分别删除、保留还是移交；注销后同手机号能否重新注册。
- 最终接口字段和错误码、短信频控、七天是否按 168 小时计算，以及测试账号、到期测试方式和可联调时间。
> 当前 Mock 的固定验证码和“放弃资产”文案仅用于演示，不能直接作为真实业务规则。
docs/账号注销后端接口需求.md
+431
View File
@@ -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 文案不能直接作为最终业务承诺，应随实际后端处理规则调整。
docs/门店身份注销接入说明.md
+160
View File
@@ -0,0 +1,160 @@
# 门店身份注销接入说明
更新时间：2026-08-28。当前分支 `dev_9_7`，未提交或推送。
**最新实测：15:27:24的申请已于15:55:36因重新登录自动撤销（9 / CANCELLED_BY_LOGIN）。最新交互改为申请成功立即退出登录、下次登录取得身份凭证后核验；普通启动和普通页面返回前台不主动查询。本轮不重新申请、不等待终态。**
## 范围
采用用户提供的《260821-App 门店用户账号注销.md》中的旧接口，不需要新增手机号主账号接口。仅注销当前 `store_user` 对应的 `ss_store_user.id`；同手机号其他身份不受影响，不支持景区身份注销。移除了原手机号级 Mock、固定验证码和本地七天完成判定。
统一前缀：`/api/yf-handset-app/account-deregister`。
| 请求 | 请求体 |
| --- | --- |
| GET `/eligibility`、GET `/status` | 无 |
| POST `/waivers/wallet`、POST `/waivers/points` | `{"accepted":true}` |
| POST `/send-sms`、POST `/cancel` | 无业务字段 |
| POST `/apply` | `sms_code`、`reason` |
请求层冻结当前门店用户 ID 和 Token，请求前后核对身份；使用 `session.userId`，不是门店实体 ID。注销请求与响应正文不写入调试日志。完整脱敏数据见[旧接口返回数据说明](门店身份注销旧接口返回数据说明.md)，操作经过见[接口实测](门店身份注销接口实测.md)。
## 已实现
- 设置页仅门店身份显示注销入口；页面采用“确认资产 → 手机验证”两步流程，以身份卡、资产卡、须知卡和底部主按钮明确注销范围。
- 注销页、只读条件页和状态页均使用下拉刷新，删除右上角刷新入口；操作过程统一使用全局通用 Loading，不保留页面内的小转圈。“其他身份不受影响”等提示不再区分其他身份类别。
- 查询资产、业务风险等待时间和全部阻断项；现金与积分合并为一个入口和一次弹窗确认，分别列明两项自愿放弃说明，零资产也不省略。底层顺序调用两个旧接口，逐次核对身份、余额及财务归属；部分成功保留真实标记，不自动重发修改请求。
- 条件满足后进入真实短信验证和申请确认。验证码为用户输入，收件手机号由后端决定。`/apply` 明确成功后立即复用已有退出通知清理会话并返回登录页，不再等一次状态查询，也不自动重新登录；响应丢失则保留核验保护，不能冒充成功或自动重发。
- 区分风险等待期 `eligible_at` 与冷静期 `cooling_until`；按服务端原文展示时间，不猜测时区。
- 严格识别实测状态：无记录、`0` 待确认草稿、`1` 冷静期、`9` 已撤销。字段缺失、状态矛盾和未知枚举都不默认放行。
- 普通冷启动使用已有会话直接进入首页；登录流程取得门店身份凭证后才核验状态，期间保留登录页面背景并显示全局 Loading，不显示“正在查询注销状态”的独立页面。正常结果直接进入业务页，冷静期、未知状态或失败才展示结果页。登录中的多身份选择仍属于此核验入口；已登录时切换身份不额外主动查询。完整草稿不影响第二次资产确认或正常使用。若核验发现冷静期，仍以独立卡片显示截止时间并提供下拉刷新、只读条件、主动撤销和退出入口。
- 用户确认撤销后先重查同一申请，POST 成功后再次 GET 核实。确认已撤销才恢复业务；响应丢失不自动重发，旧身份或旧限制版本的响应不能放行当前会话。旧 null/草稿不能作为撤销成功依据。
- 提交前按环境与门店用户 ID 保存意图，不保存 Token、手机号、验证码或资产。明确业务拒绝或新撤销记录可清除；重新申请前的旧撤销记录不能清除新意图。UserDefaults 不是后端幂等或断电事务保障。
- 冷静期 `eligibility` 虽然返回两项确认 false，也禁止再次确认；已撤销可重新准备申请，但必须按最新条件重新确认资产。
- 网络层将 `150015` 作为当前门店凭证的业务限制，不当作全局登录失效。核验期间暂停推送绑定和业务通知跳转；核验通过后恢复。
- 用15:29实测的150015与状态JSON补充集成回归，覆盖 `ProfileAPI.userInfo → APIClient → 身份限制通知 → RootCoordinator → 冷静期页面`；确认原Token和身份保留、业务暂停、无登录或撤销请求。通知转发在测试中使用独立NotificationCenter，不等同于真实SceneDelegate端到端操作。
- 普通页面从后台返回不主动查询，不替换导航栈。仅当前已显示的受限/核验页返回前台时刷新，并废弃后台前的旧查询；不会重新发送短信、申请或撤销。业务接口明确返回当前 Token 的 `150015` 时仍立即限制业务并核验。
- 普通登录、选择及切换身份不再无条件弹出注销提示；自动撤销规则保留在注销提交确认和申请状态页。登录后的服务端状态核验保持不变。身份列表为空时不进入首页，但“全部身份注销后后端究竟返回什么”尚未实测。
## 真实接口和页面验证
2026-08-28 在测试环境、配对 iPhone 11 上分次授权验证：
1. 两项零资产确认成功，第一次确认产生草稿0；第二次确认后允许申请。
2. 真机发送短信并收到验证码，14:23:40 提交测试申请，GET 确认冷静期1。
3. 14:24:04 主动撤销成功，14:24:05 两个 GET 均确认已撤销9。未留下待注销申请，未最终删除身份。
4. 安装新增状态处理后，14:39 重新打开 App，原身份直接恢复首页，没有重新登录；再次进入设置中的注销入口成功。读取详情页的镜像操作随后超时，因此未把撤销后详情页的完整展示记为通过。
短信和申请 POST 的原始响应体未保存，只有界面和后续 GET 的成功证据；不能将 GET 结构冒充 POST 响应。撤销响应体已保存脱敏样例。上述14:24立即撤销流程已结束。
随后用户明确要求在已登录的 iPhone Air 模拟器操作，并确认保留新申请至到期复核：15:27:24提交一次，界面自动进入冷静期限制页。15:28 GET `/status` 和 `/eligibility` 均确认冷静期1；15:29 GET `/userinfo` 返回真实150015，前后状态查询仍为1。截至15:50未撤销或重新登录；15:56再次只读复核时，服务端已返回15:55:36因重新登录自动撤销（9 / CANCELLED_BY_LOGIN）。该申请不再等待到期。模拟器仅用于用户指定的人工操作，不用于替代单元测试的真机要求。
## 自动化验证
- iPhone 11（`00008030-001E48E21139802E`），未使用模拟器。
- 冷静期/撤销首轮：61 项注销测试全部通过（API 8、进入核验21、响应8、流程24）。随后补充一项取消前后旧 null/草稿的防御测试，纳入最后全量回归。
- 冷静期页面真机 Mock 渲染截图已导出并检查，文案、截止时间和撤销入口完整可见。
- 测试中的短信、资产确认、申请与撤销只使用 Mock；宿主 App 仍可能产生既有后台请求，不能称整台设备离线。
- 前台恢复改动之前的全量：781项中771通过、10项失败（15条失败记录，2条 unexpected）；与原始基线逐项对比，失败用例集合完全一致，无新增失败。注销相关62项全部通过（API 8、进入核验22、响应8、流程24）。全量不是全部通过。
- 前台路由版全量：791项中781通过、10项失败（15条失败记录，2条 unexpected），失败用例集合与基线完全一致；注销相关72项全部通过。
- UI改版前全量（15:45）：792项中782通过、10项失败，无跳过项；失败用例集合仍与基线完全一致，无新增失败。注销相关73项全部通过（API 8、进入核验23、响应8、根路由10、流程24），均在iPhone 11运行；日志与xcresult摘要已交叉核对。
结果文件：
- 本轮61项：`/private/tmp/suixinkan-deregister-cooling-20260828.xcresult`
- 本轮冷静期截图：`/private/tmp/suixinkan-deregister-cooling-20260828-attachments/DB6A885A-C10C-49E0-A5F4-D3EB5D0AA3B1.png`
- 前台恢复改动之前的全量：`/private/tmp/suixinkan-deregister-cooling-full-20260828.xcresult`
- 前台恢复测试尝试（手机锁定，未执行，中断）：`/private/tmp/suixinkan-deregister-foreground-20260828.xcresult`
- 当前最终构建（成功，仅编译）：`/private/tmp/suixinkan-deregister-final-build-20260828.xcresult`
- 路由修正后32项回归：`/private/tmp/suixinkan-deregister-foreground-r2-20260828.xcresult`
- 前台路由版全量：`/private/tmp/suixinkan-deregister-foreground-final-20260828.xcresult`
- 当前最终全量：`/private/tmp/suixinkan-deregister-real-contract-20260828.xcresult`
- 原始基线：`/private/tmp/suixinkan-account-deletion-baseline-20260827-r2.xcresult`
## 尚未完成，不能视为完整上线验收
1. 旧文档没有给出终审“阻断”“正式完成”的数字枚举和完整响应；当前只能保守展示待核验页，不能伪造终态或自动清理账号。
2. 重新登录/选择身份自动撤销发生在哪个接口、受限 Token 能否切换其他身份、最终注销后鉴权及所有身份注销后的登录响应，尚未实测。
3. 真实150015接口响应已采样，客户端限制通知到核验页已用真实数据Mock验证；实际SceneDelegate端到端操作和真实多端验证仍缺。最新流程不再主动轮询其他设备的申请变化，依赖登录核验、用户进入注销功能查询或业务接口明确限制。
4. 新撤销按钮交互使用 Mock 验证与截图检查；真实撤销通过受控 API 完成，没有再次创建申请来验证新按钮。完整终态页面验收仍未完成。
5. 非零资产、确认过期、错误验证码、重复申请/撤销及完成后的错误响应还缺真实样例。
不要求后端新增接口；补充现有 Controller/Resource/DTO 源码或脱敏响应即可继续。严禁通过本机时间、`remaining_seconds: 0`、`can_apply` 或仍存在 `cooling_until` 推断已注销。
## 此前完整目标核对（15:50历史记录）
下表保留当时的验证范围。本轮最新结果见文末UI改版小节，不继续等待已撤销申请的终态。
| 要求 | 当前证据 | 结论 |
| --- | --- | --- |
| 仅当前门店身份，保留同手机号其他身份 | 请求冻结 `session.userId`/Token，8项请求层测试；无批量接口 | 已实现，路由回归已通过 |
| 展示所有条件、分别确认资产及快照失效 | 真实两项零资产确认与条件响应；模型/流程测试 | 已验证零资产正常流程，未真实操作非零资产 |
| 实际短信、申请确认、7天冷静期 | 真机收到短信，申请后 GET 返回1及7天截止时间 | 已验证，未捕获两个 POST 的原始响应体 |
| 主动撤销并恢复使用 | 真实 cancel 返回9，随后 GET 复核，冷启动恢复首页；撤销逻辑测试 | 主动接口已验证，新弹窗及前台路由Mock测试已通过 |
| 不将150015当作手机号登录失效 | 原请求Token隔离测试、推送暂停测试、真实userinfo响应；真实JSON重放至冷静期UI | 接口及客户端Mock集成已验证，实际SceneDelegate端到端操作待验证 |
| 冷启动、前台、多端及过期响应 | 冷启动已真机检查；RootTests 10项和状态回退测试1项 | 已通过iPhone真机Mock测试；不代替真实多端验证 |
| 冷静期到期复核、阻断、正式完成页面及清理 | 旧文档描述规则，但无终态枚举/响应 | 未完成，需要现有接口样例或源码 |
| 登录/选择同一身份自动撤销、全部身份注销后登录 | 旧文档规则、登录提示和空身份列表Mock测试 | 后端真实行为未验证 |
| 所有相关测试、全量回归及最终页面验收 | 当前73项注销相关测试通过；全量792项中10项基线失败 | 当前代码回归已执行；完整终态及真实多端验收未完成 |
| 不改变其他业务配置，不切分支、提交或推送 | 当前 `dev_9_7`；配置/依赖差异检查为空 | 保持约定 |
若后续扩展终态，仍需：`/status` 在“终审阻断”和“正式完成”时的脱敏完整响应或对应资源模型源码，以及终态 Token 查询和撤销规则。此前获准保留的测试申请已经自动撤销，本轮不重新申请。不得跳过7天冷静期、修改数据库或制造订单/资产变化来取得样例。
### 15:50完成度复核：仍未满足完整目标
直接核对当前状态模型和AccessViewModel：只映射草稿0、冷静期1和已撤销9，未知终态仍进入待核验页；尚无终审阻断、正式完成页面及清理依据。因此73项相关测试通过不能证明完整注销终态已经接入。
15:48与15:50的真实GET都返回同一冷静期申请，`completed_at`和`cancel_time`仍为null。期间只结束并重启iPhone Air的App进程，未清空数据或重新登录；重启后原Token仍能查询同一申请。窗口工具停留在另一模拟器窗口且菜单操作失败，未取得iPhone Air冷启动页面，故不将该项UI验证记为通过。
已查本机、原文档、公开文档入口、现有权限可见代码站及项目列表；仍无终态源码或响应。该缺口在提交后、真实响应集成回归后及本次复核中持续存在。当前需要服务端到期产生新状态，或取得现有后端源码才能推进终态接入；暂停重复测试与状态轮询。没有创建定时任务或自动监控，后续复核需恢复本任务。
## 本轮UI改版（2026-08-28）
- 两步页面沿用App蓝白色、16pt边距和白色圆角卡片；底部固定唯一主按钮，验证码与获取按钮同行；输入完整后才允许提交。
- 资产确认类阻断集中在资产卡，其他条件完整展示为待处理事项；订单等条件未满足时不能开始合并确认。
- 新增confirmAssetsAndContinue(snapshot:api:)，跳过已确认项；任何一项失败或资产变化均停留在条件页，核对后由用户主动重试。
- 状态页用图标、标题、身份和截止时间分层展示。未知和失败状态只提供简短说明与重试，不伪造注销完成；删除草稿等调试文案。
- 本轮不扩展终态，不改变登录和状态核验架构，不操作真实短信、确认、申请或撤销。上文15:27—15:50记录为历史过程，当前以15:56已撤销结果为准。
- 最终真机回归：90项注销相关测试全部通过，其中本轮新增17项（13项合并确认、4项UIKit交互/布局）；全量809项中799通过、10项失败、0跳过。失败用例集合与改版前基线完全一致，没有新增失败；全量不宣称全部通过。
- 已检查真机Mock截图：375pt资产页、非零资产及业务阻断、手机验证、冷静期、查询失败、未知状态；验证码与原因输入时，输入框可滚动至可见区域，底部按钮位于键盘上方。截图只包含测试窗口，未合成系统独立键盘窗口。所有短信及注销修改请求均为Mock，未再次操作真实注销。
- 现有键盘库的局部兼容处理已验证：只禁用本页两个输入框的重复位移，保持导航栏位置稳定；验证码和原因均可滚动至键盘上方，不改变其他页面的键盘设置。最终回归包含该处理。
本轮验证文件：
- 全量结果：`/private/tmp/suixinkan-deregister-redesign-r5-20260828.xcresult`
- 结构化摘要：`/private/tmp/suixinkan-deregister-redesign-r5-summary.json`
- 截图目录：`/private/tmp/suixinkan-deregister-redesign-r5-images/`
- 中间一次构建成功但因iPhone锁屏未能启动测试；解锁后使用同一构建完成上述真机回归，没有改用模拟器。
## 登录入口提示修复（2026-08-28）
- 移除登录、选择门店身份和切换门店身份时无条件出现的注销提示，删除无用的提示组件。
- 保留手机号/密码/协议校验和加载期间的防重复操作；不改变登录后的注销状态核验。自动撤销规则继续在注销提交确认和申请状态页说明。
- 登录页面支持注入现有AuthAPI用于Mock回归，不改登录协议、不访问真实登录接口，也不写入测试登录会话。
- iPhone 11回归：登录12项、账号切换2项、注销90项全部通过。全量812项中802通过、10项失败、0跳过；失败集合与修复前一致，没有新增失败。
- 结果：`/private/tmp/suixinkan-login-prompt-fix-20260828.xcresult`；摘要：`/private/tmp/suixinkan-login-prompt-fix-20260828-summary.json`。
## 申请成功退出与查询时机简化（2026-08-28）
- 提交前仍核对状态和资产；`/apply` 明确成功即发送现有退出通知，复用推送解绑、会话清理及返回登录页流程。不再追加成功后的 GET，也不先显示申请状态页。
- 仅填验证码、点击提交或打开最终确认弹窗都不会自动申请。最终弹窗新增“提交成功后将退出登录”；连点和成功后重复回调均不能重复申请或重复退出。
- 验证码等明确业务拒绝不退出；申请响应丢失保留提交意图并进入核验保护，不自动重发。已接受的提交意图仍按环境、门店身份保存，供下次登录核实。
- 普通启动和普通页面返回前台不主动查询注销状态；登录得到身份 Token 后核验。旧 `/status` 需要身份凭证，不能在未登录时只凭手机号查询；旧后端登录/选择该身份可能已自动撤销申请，因此此时可能返回已撤销。
- 保留业务 `150015` 限制和受限页面的刷新；不能因为简化正常启动就忽略服务端明确限制。进入注销功能时仍需查询条件与状态。
- 本轮只使用 Mock 验证提交和退出回调，不操作真实短信、资产确认、申请、撤销或登录。
- iPhone 11 真机全量回归：817项中807通过、10项失败、0跳过；失败用例集合与原始基线及上一轮完全一致，无新增失败。注销相关94项全部通过，包含本轮新增的登录核验时机、成功一次退出、失败不退出和最终确认弹窗测试；普通启动/前台不查询的路由断言同步更新。
- 结果：`/private/tmp/suixinkan-deregister-logout-20260828.xcresult`；摘要：`/private/tmp/suixinkan-deregister-logout-20260828-summary.json`。退出通过注入回调验证，没有为验收再次提交真实注销；现有退出通知到会话清理沿用原实现。
## 下拉刷新与统一 Loading（2026-08-28）
- 删除注销流程右上角刷新按钮，资产/验证页、只读条件页和申请状态页均支持下拉刷新；只执行查询，不自动确认资产、发短信、申请或撤销。
- 去掉注销页“景区”相关固定文案，统一描述其他身份不受影响。真实身份名称和服务端待处理事项仍如实展示，不改业务身份或接口字段。
- 初次查询、下拉刷新、确认资产、发送短信、提交申请及撤销操作统一复用 `GlobalLoadingManager` 的全屏遮罩与动画。下拉只作为触发手势，隐藏其系统转圈，避免叠加两套 Loading。
- 登录核验不再先创建查询根页面：保留当前登录页面背景，核验成功直接进入首页；异常结果才创建状态页，复用已查询的结果，不追加重复 GET。
- 保留请求前后的身份校验、限制信号优先级和后台旧响应作废。退出/切换会话会结束本次核验持有的 Loading，迟到响应不能关闭新请求的 Loading 或替换新账号页面。
- 测试使用独立会话、Mock 网络和测试窗口；本轮不发出真实短信、资产确认、申请、撤销或登录请求。
- 最终 iPhone 11 全量回归：821项中811通过、10项既有失败、0跳过，失败集合与上一轮完全一致。98项注销相关测试全部通过，覆盖下拉刷新、失败后结束加载、输入保留、登录期间不换根、重复核验及旧响应隔离。
- 已检查真机 Mock 截图：资产页和冷静期页右上角无刷新按钮；提交中显示现有白色圆角动画卡片与全屏灰色遮罩，没有页面内转圈。登录不换根通过独立窗口路由测试验证，未再次操作真实账号登录。
- 首次增量构建存在旧初始化签名缓存，清理构建产物后解决；连续 UI 回归需要等待测试窗口显示稳定后再模拟登录，修正仅在测试夹具中，业务代码没有新增延时，也没有放宽断言。
- 结果：`/private/tmp/suixinkan-deregister-loading-r3-20260828.xcresult`；摘要：`/private/tmp/suixinkan-deregister-loading-r3-20260828-summary.json`；截图：`/private/tmp/suixinkan-deregister-loading-r3-20260828-images/`。
docs/门店身份注销接口实测.md
+342
View File
@@ -0,0 +1,342 @@
# 门店身份注销接口实测
实测时间：2026-08-28 11:39；追加 13:45–13:46 零资产确认（服务端响应时间）。
环境：`https://api-test.zhifly.cn`。首次 11:39 使用用户明确授权的 iPhone 当前 `store_user` 登录 Token，仅执行 `GET /eligibility` 与 `GET /status`，当时未调用修改接口。后续额外授权的两项零资产确认见第 5 节。请求头与当前 Debug App 一致：`token`、`X-APP-VERSION: 1.3.1`、`X-OS-TYPE: iOS`、JSON Accept/Content-Type。
以下为真实响应；仅 `store_user_id`、`finance_identity_id` 统一替换为数值 `0` 脱敏，不能把该值用作有效身份。没有保存 Token。
## 1. 注销条件
`GET /api/yf-handset-app/account-deregister/eligibility`
HTTP 200，业务码 `100000`：
```json
{
"code": 100000,
"msg": "success",
"data": {
"can_apply": false,
"store_user_id": 0,
"finance_identity_id": 0,
"wallet_balance_fen": 0,
"wallet_balance": "0.00",
"points_balance": 0,
"wallet_waived": false,
"points_waived": false,
"unfulfilled_count": 37,
"fulfillment_in_progress_count": 0,
"risk_end_at": "2026-08-27 15:47:32",
"eligible_at": "2026-09-03 15:47:32",
"risk_window_hours": 168,
"blockers": [
{
"code": "ORDER_UNFULFILLED",
"message": "账户仍有未履约订单或带单",
"action": "complete_orders"
},
{
"code": "RISK_WINDOW_NOT_EXPIRED",
"message": "最后一笔业务的风险结束时间尚未超过7天",
"action": "wait_risk_window"
},
{
"code": "WALLET_WAIVER_MISSING",
"message": "请先确认放弃现金余额",
"action": "confirm_wallet_waiver"
},
{
"code": "POINTS_WAIVER_MISSING",
"message": "请先确认放弃积分",
"action": "confirm_points_waiver"
}
],
"deregister": null
},
"time": "2026-08-28 11:39:51"
}
```
本次观测到的类型：
| 字段 | JSON 类型 / 含义 |
| --- | --- |
| `can_apply` | 布尔值，服务端是否允许申请 |
| `store_user_id`、`finance_identity_id` | 整数 |
| `wallet_balance_fen` | 整数，现金余额（分） |
| `wallet_balance` | 字符串，金额展示值；本次为 `"0.00"` |
| `points_balance` | 整数，积分余额 |
| `wallet_waived`、`points_waived` | 独立布尔值，是否已确认放弃 |
| `unfulfilled_count`、`fulfillment_in_progress_count` | 整数 |
| `risk_end_at`、`eligible_at` | 时间字符串，格式 `yyyy-MM-dd HH:mm:ss`；时区及无历史业务时的空值形式尚未确认 |
| `risk_window_hours` | 整数，本次为 `168` |
| `blockers` | 对象数组，每项有字符串 `code`、`message`、`action` |
| `deregister` | 本次为 `null`，尚未观测非空结构 |
本次余额与积分均为零，服务端仍返回两项放弃确认缺失。客户端不能因为资产为零就省略确认。当前还有 37 项未履约订单或带单，且风险等待期未结束，不能提交注销。`eligible_at` 是业务风险期截止时间，不是提交申请后的冷静期截止时间；达到该时间也不代表其他条件自动满足。
## 2. 注销状态
`GET /api/yf-handset-app/account-deregister/status`
HTTP 200，业务码 `100000`：
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": null
},
"time": "2026-08-28 11:39:51"
}
```
当前查询没有返回注销申请。不能据此推断非空申请的字段名称、状态枚举或是否可撤销。
## 3. 首次只读探测后尚缺的信息（后续进展见第 5、6 节）
- 草稿、冷静期、阻断、撤销、完成时 `data.deregister` 的非空结构、状态字段和值。
- `cooling_until`、`remaining_seconds` 的实际位置及类型。
- 无历史业务时风险时间的空值形式、时间字符串所用时区。
- 重新登录或选择身份自动撤销的具体接口时机，以及受限 Token 是否允许切换其他身份。
这些情况需要现有后端响应样例/源码，或在获得明确授权的专用测试身份上验证。本次授权仅限只读查询，不为采样创建、撤销注销申请或确认资产放弃。
## 4. 后续零资产确认授权（2026-08-28 13:42）
用户随后明确允许：在测试环境重新核实现金余额与积分均为 0 后，分别调用两项资产放弃确认接口，并查询是否产生草稿。此授权不包含发送短信、提交或撤销注销申请，也不允许非零资产确认。
已确认 iPhone 11 连接，并读取本 App 的当前会话：没有登录 Token，保存的账号类型为 `photog`，不是旧注销接口要求的 `store_user`。因此此次没有发出任何接口请求或资产确认，设备偏好未修改，本地临时偏好副本已删除。需在测试版 App 登录门店身份后继续；不要为采样登录已有未完成注销申请的身份，以免触发自动撤销。
## 5. 已完成两项真实零资产确认（2026-08-28 13:45–13:46）
用户重新登录后，核实当前为有效 `store_user`。每项确认前均重新查询：身份与设备会话一致、现金余额（分和展示金额）与积分均为 0；只访问测试环境，禁止重定向，不自动重试修改请求。仅执行了已授权的 `POST /waivers/wallet`、`POST /waivers/points` 各一次，没有发送短信、提交或撤销注销申请。
本次身份初始没有未履约/交付处理中记录，`risk_end_at`、`eligible_at` 均为 JSON `null`，阻断仅为两项确认缺失。与第 1 节较早查询的身份情况不同，不能沿用之前的 37 项未履约记录。
| 阶段 | `wallet_waived` | `points_waived` | `can_apply` | `deregister` |
| --- | --- | --- | --- | --- |
| 确认前 | false | false | false | null |
| 现金确认后 | true | false | false | `status: 0` 草稿 |
| 积分确认后 | true | true | true | 同一未提交草稿 |
两个确认请求均 HTTP 200、`code: 100000`，`data` 返回 `asset_type`（分别为 `"wallet"`、`"points"`）、`wallet_balance_fen: 0`、`wallet_balance: "0.00"`、`points_balance: 0` 及两项确认时间。现金确认后 `wallet_waived_at: "2026-08-28 13:45:57"`、`points_waived_at: null`；积分确认后后者变为 `"2026-08-28 13:46:42"`。
两个 GET 中的 `data.deregister` 都返回以下结构；仅 `id` 脱敏为 0，实际是正整数：
```json
{
"id": 0,
"status": 0,
"status_label": "待确认",
"reason": "",
"apply_time": null,
"cooling_until": null,
"remaining_seconds": 0,
"cancel_time": null,
"blocked_code": "",
"blocked_reason": "",
"completed_at": null
}
```
**确认结论：第一次资产确认即产生非空草稿；`status` 为数字，0 对应“待确认”。非空记录不等于已提交，不能一律限制普通业务或后续资产确认。两项确认后即使仍有草稿，`can_apply` 也会变为 true。** `remaining_seconds: 0` 在草稿中存在，不能单独据此认定冷静期已结束或注销已完成。
已据此修正客户端草稿判断、继续确认/验证和启动核验，并补充 Mock 测试。只将完整且无提交、撤销、阻断或完成字段冲突的 `status: 0` 识别为草稿；未知状态仍不推断。所有本地会话临时副本已删除，未写回设备偏好，未保存 Token。
仍缺：冷静期、撤销、阻断、完成的实际状态值及对应时间数据；确认过期响应；登录/切换自动撤销的具体时机。继续真实验证需要另行授权短信、提交与撤销操作，当前授权不包含这些操作。
## 6. 短信、申请与立即撤销（2026-08-28 14:16–14:24）
用户另外授权在切换后的专用测试身份上发送短信、提交申请，获取状态后立即撤销。真机页面核实：现金/积分为0、两项确认已完成、无未履约及风险等待阻断。通过 iPhone 镜像发送短信，用户提供验证码后提交；未将验证码写入源码或文档。短信和申请的原始 POST 响应体没有保存，不能把后续 GET 当作 POST 原文。
- 申请原因：`API test; cancel immediately`。
- 申请时间：`2026-08-28 14:23:40`。
- 查询确认：`status: 1`、`status_label: "冷静期中"`，冷静期截止 `2026-09-04 14:23:40`。
- 核对当前身份、同一申请及原因后只调用一次 `/cancel`，不自动重试。
- 撤销成功时间：`2026-08-28 14:24:04`，返回 `status: 9`、`status_label: "已撤销"`。
- `14:24:05` 再次 GET `/status` 与 `/eligibility` 确认已撤销；未留下待注销申请，未执行最终注销。
- 本地临时会话副本已删除，未编辑设备偏好，未在文档中保存 Token、手机号或真实身份 ID。
### 冷静期状态
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": {
"id": 0,
"status": 1,
"status_label": "冷静期中",
"reason": "API test; cancel immediately",
"apply_time": "2026-08-28 14:23:40",
"cooling_until": "2026-09-04 14:23:40",
"remaining_seconds": 604776,
"cancel_time": null,
"blocked_code": "",
"blocked_reason": "",
"completed_at": null
}
},
"time": "2026-08-28 14:24:03"
}
```
### 撤销响应
```json
{
"code": 100000,
"msg": "注销申请已撤销",
"data": {
"deregister": {
"id": 0,
"status": 9,
"status_label": "已撤销",
"reason": "API test; cancel immediately",
"apply_time": "2026-08-28 14:23:40",
"cooling_until": "2026-09-04 14:23:40",
"remaining_seconds": 0,
"cancel_time": "2026-08-28 14:24:04",
"blocked_code": "CANCELLED_BY_USER",
"blocked_reason": "用户主动撤销注销",
"completed_at": null
}
},
"time": "2026-08-28 14:24:04"
}
```
### 撤销后的条件
```json
{
"code": 100000,
"msg": "success",
"data": {
"can_apply": false,
"store_user_id": 0,
"finance_identity_id": 0,
"wallet_balance_fen": 0,
"wallet_balance": "0.00",
"points_balance": 0,
"wallet_waived": false,
"points_waived": false,
"unfulfilled_count": 0,
"fulfillment_in_progress_count": 0,
"risk_end_at": null,
"eligible_at": null,
"risk_window_hours": 168,
"blockers": [
{
"code": "WALLET_WAIVER_MISSING",
"message": "请先确认放弃现金余额",
"action": "confirm_wallet_waiver"
},
{
"code": "POINTS_WAIVER_MISSING",
"message": "请先确认放弃积分",
"action": "confirm_points_waiver"
}
],
"deregister": {
"id": 0,
"status": 9,
"status_label": "已撤销",
"reason": "API test; cancel immediately",
"apply_time": "2026-08-28 14:23:40",
"cooling_until": "2026-09-04 14:23:40",
"remaining_seconds": 0,
"cancel_time": "2026-08-28 14:24:04",
"blocked_code": "CANCELLED_BY_USER",
"blocked_reason": "用户主动撤销注销",
"completed_at": null
}
},
"time": "2026-08-28 14:24:05"
}
```
冷静期 GET `/eligibility` 已返回两项确认 false 和缺少确认的两个阻断，撤销后也是如此；冷静期不能因此重新确认资产。撤销记录保留旧冷静期时间；remaining_seconds 为0不等于注销完成。正式完成与终审阻断的状态值、自动撤销和所有身份注销后的登录响应仍未验证。此次授权操作已结束，不继续发送短信或创建申请。
## 2026-08-28：补查终态契约及新申请准备
用户随后允许继续申请注销，以尝试获取缺失的终态响应。本节是新的调查记录，不代表已经创建新的申请。
| 查找范围 | 结果 |
| --- | --- |
| 本机 iOS、Android 参考工程及桌面相关文件 | 未找到旧注销后端的 Controller、Resource、状态枚举或 migration 源码 |
| 测试 API 的 `/docs`、`/api/documentation`、`/openapi.json`、`/swagger.json` | HTTP 200，但业务体均为路由不存在，不能当作可用接口文档 |
| Gitea 匿名仓库搜索 | 没有返回匹配仓库；不代表私有仓库不存在 |
| Chrome 中已有登录的 Gitea 会话 | 可访问当前用户的仓库列表；代码搜索 `StoreUserDeregister`、`deregister` 均未匹配，未取得注销后端源码 |
| 已打开的飞书原始文档 | 页面显示最近修改为8月21日；相关规则与本地文档一致，未给出终态数字枚举、完整 JSON 或完成后的鉴权响应 |
| 真机当前 App 会话 | 无有效门店登录态，因此没有发起认证查询、短信、资产确认、申请或撤销 |
当前仍需先在真机登录一个允许最终注销的专用测试门店身份，再读取该身份的条件。若保留申请等待正式完成，需经过服务端7天冷静期；不能修改本机时间来替代服务端等待，也不能为制造终审阻断而擅自修改订单、资产或数据库。按旧文档，重新登录或选中申请中的同一身份会自动撤销申请，等待期间应避免这种操作。
“终审阻断”需要到期复核发现条件变化，单纯提交并等待不能保证得到该状态。此次只读查找未新增任何终态实测结论。
## 2026-08-28 15:23：按用户要求改在模拟器准备新申请
- 用户明确要求操作其已登录的 iPhone Air 模拟器。本次是人工界面操作，不是模拟器单元测试；不改变此前真机测试结论。
- 页面当前身份为北大科技园，显示现金0元、积分0；初始只有两项资产确认阻断，上次申请已撤销。
- 用户授权分别确认两项零资产并发送验证码。继续操作时，现金已显示确认完成，因此没有重复提交现金确认；随后单独确认零积分。
- 页面显示两项资产均已确认、当前条件满足；仍为未提交草稿。
- 15:23通过页面发送一次注销验证码，界面提示已发送至当前身份绑定手机号。未保存短信 POST 原始响应，不能把界面提示当作完整接口 JSON。
- 停留在验证码输入页，等待用户提供本次验证码；此时尚未提交新申请，也未进入新的冷静期。
## 2026-08-28 15:27—15:29：新申请已提交并保留
- 用户提供本次验证码，并在最终弹窗前明确确认：只注销北大科技园身份，保留申请至服务端7天后复核，正式完成不可恢复，不像上次立即撤销。
- 15:27:24在模拟器点击一次“确认提交申请”。原因为 `Test account deregistration`；验证码不写入文档或代码。
- 页面进入冷静期核验页，显示截止时间 `2026-09-04 15:27:24`（服务端时间）。
- 15:28:27只读 GET `/status`、`/eligibility` 均确认 `deregister.status: 1`，`cancel_time`、`completed_at` 均为 null。
- 15:29:22以同一现有 Token GET `/api/yf-handset-app/userinfo`，返回 HTTP 200、业务码150015、`data.status: "cooling"`、相同冷静期截止时间；响应没有 `time` 字段。前后 GET `/status` 均成功且仍是同一冷静期记录。
- 未重复发送短信、未重复申请、未执行撤销、登录或身份选择。未保留 Token 副本或修改模拟器偏好设置。
**此时申请仍待注销，与14:24已撤销的旧申请不同；后续已于15:55:36因重新登录自动撤销，见文末15:56记录。** 终审阻断/正式完成未发生；不能把冷静期截止当作已经注销。查询样例已加入[旧接口返回数据说明](门店身份注销旧接口返回数据说明.md)。短信和申请 POST 原始响应体仍未捕获，不能用 GET 代替。
本轮脱敏证据：
- `/private/tmp/suixinkan-contract-discovery-20260828/152826-simulator-status-redacted.json`
- `/private/tmp/suixinkan-contract-discovery-20260828/152826-simulator-eligibility-redacted.json`
- `/private/tmp/suixinkan-contract-discovery-20260828/152921-simulator-userinfo-cooling-redacted.json`
- `/private/tmp/suixinkan-contract-discovery-20260828/152921-simulator-status-before-auth-redacted.json`
- `/private/tmp/suixinkan-contract-discovery-20260828/152921-simulator-status-after-auth-redacted.json`
## 2026-08-28 15:45：真实响应回归与源码补查
- 将本轮150015及对应status响应整理为Swift测试夹具；逐字段对比采样JSON，仅注销记录ID替换为测试值301。
- 在iPhone 11上完成全量792项测试：782通过、10项既有失败，无跳过；失败用例集合与原始基线一致。注销相关73项全部通过，包括真实userinfo限制响应经API、通知和路由进入冷静期页面的新增Mock集成测试。
- 本轮仅更新测试与文档，未操作模拟器中的真实申请；未变更工程配置、版本号或依赖。
- 补查已保存项目列表，未发现相关后端工程；Android工程现有Git主机的HTTP网页根返回空响应，未取得源码。未猜测后端仓库路径、修改服务器或扩展访问权限。
- 结果：`/private/tmp/suixinkan-deregister-real-contract-20260828.xcresult`。终态样例仍缺，不能将测试通过作为正式注销完成的证据。
## 2026-08-28 15:48—15:50：最终只读复核与冷启动尝试
- 15:48:04查询仍为申请时间15:27:24的冷静期1。
- 仅终止并重启iPhone Air中的App进程；未卸载、清空数据、登录或选择身份。工具未能切换至正确模拟器窗口，故冷启动UI没有验证完成。
- 15:50:51用原会话再次GET `/status`、`/eligibility`，均返回同一申请的冷静期1，截止时间不变，`remaining_seconds: 603392`，撤销时间与完成时间均为null。
- 证据：`/private/tmp/suixinkan-contract-discovery-20260828/155050-simulator-status-redacted.json`及同前缀的`eligibility-redacted.json`。
- 未产生新的终态依据，不继续重复轮询或制造业务变化；待服务端到期状态或已有源码可用后再推进。
## 2026-08-28 15:56：重新登录自动撤销
用户告知已进入后，只读查询发现15:27:24申请已于15:55:36自动撤销。两次GET均返回status9、CANCELLED_BY_LOGIN、用户重新登录自动撤销的说明，completed_at仍为null。没有调用cancel或重新申请；未采集触发撤销的具体登录请求，因此不能断言具体接口时机。
证据：/private/tmp/suixinkan-contract-discovery-20260828/155633-simulator-status-redacted.json及同前缀eligibility文件。此前待注销记录的截止时间已失效，不再等待该申请于9月4日完成。用户随后要求UI简化，本轮仅使用Mock测试，不再操作真实注销。
## 2026-08-28 17:01：验证资产确认接口的false参数
用户单独授权尝试现金、积分接口传`accepted: false`。使用iPhone 11当前已登录门店身份和测试环境，先只读确认两项标记均为true、金额均为0、状态为未提交草稿0，再分别调用一次两个确认接口。
- 现金：17:01:14返回HTTP 200、业务码100099、`msg: 请明确确认自愿放弃对应资产`、`data: []`。
- 积分：17:01:32返回同样结果。
- 每次调用后重新GET查询：`wallet_waived`和`points_waived`仍为true，草稿仍为0，金额未变化，没有进入冷静期。
- 结论：当前接口不接受false作为撤回确认；本轮没有调用true、短信、申请、撤销或登录接口。未重试POST。
完整返回及前后状态见[旧接口返回数据说明4.4节](门店身份注销旧接口返回数据说明.md)。脱敏证据目录：`/private/tmp/suixinkan-waiver-false-20260828/`。
docs/门店身份注销旧接口返回数据说明.md
+477
View File
@@ -0,0 +1,477 @@
# 门店身份注销旧接口返回数据说明
整理日期：2026-08-28。依据旧接口文档及当天测试环境的真实响应。
**注销范围：当前 `store_user` 对应的门店用户身份，不是手机号主账号，不影响同手机号的其他身份。**
示例中的 `store_user_id`、`finance_identity_id` 和注销记录 `id` 均脱敏为 `0`，实际为正整数；脱敏值不能用于请求或业务判断。本文不包含 Token、手机号或姓名。
## 1. 请求信息与实测范围
- 测试环境：`https://api-test.zhifly.cn`
- 统一路径前缀：`/api/yf-handset-app/account-deregister`
- 请求头：`token: <当前身份Token>`、`X-APP-VERSION: 1.3.1`、`X-OS-TYPE: iOS`、JSON Accept/Content-Type。
| 方法 | 路径后缀 | 用途 | 真实响应覆盖情况 |
| --- | --- | --- | --- |
| GET | `/eligibility` | 查询注销条件 | 已实测：阻断、两项确认、允许申请、冷静期、撤销后 |
| GET | `/status` | 查询注销记录 | 已实测：无记录、待确认草稿、冷静期、已撤销 |
| POST | `/waivers/wallet` | 确认放弃现金 | 已实测：零余额确认成功 |
| POST | `/waivers/points` | 确认放弃积分 | 已实测：零积分确认成功 |
| POST | `/send-sms` | 发送注销验证码 | 真机发送并收到短信；未保存原始响应体 |
| POST | `/apply` | 提交注销申请 | 真机提交后 GET 确认冷静期；未保存 POST 原始响应体 |
| POST | `/cancel` | 撤销注销申请 | 已实测：撤销成功，并 GET 复核 |
已按用户分次授权执行两项零资产确认，以及一次“短信 → 提交 → 查询 → 立即撤销”。申请时间为 14:23:40，14:24:04 撤销成功，14:24:05 查询确认已撤销；未保留待注销申请，未执行最终注销。正文不记录验证码。
**此前申请状态（15:56复核）：15:27:24创建的申请已于15:55:36因重新登录自动撤销（9 / CANCELLED_BY_LOGIN）。没有保留这次待注销申请，旧截止时间不再代表有效冷静期。**
17:01补充实测：当前真机身份查询为未提交草稿0，两项资产已确认，尚未进入冷静期。按用户授权分别尝试`accepted: false`，两条接口均拒绝，确认标记没有重置，见4.4节。
## 2. 公共响应与业务码
| 字段 | 已观测 JSON 类型 | 含义 |
| --- | --- | --- |
| `code` | number（整数） | 业务码，成功为 `100000` |
| `msg` | string | 响应说明，成功可为 `"success"` 或 `"注销申请已撤销"`，不能固定匹配文案 |
| `data` | object；未登录时为 array | 具体业务数据 |
| `time` | string | 成功样例中的服务端时间，格式 `yyyy-MM-dd HH:mm:ss`；时区待确认 |
**HTTP 200 不等于业务成功，必须检查 `code`。**
| 业务码 | 含义 | 验证情况 |
| --- | --- | --- |
| `100000` | 请求成功 | 两个 GET、两个资产确认及撤销响应均观察到 |
| `100090` | 未登录 | 不带 Token 查询两个 GET 时实测 |
| `100099` | 本次表示未明确同意放弃资产 | 两项确认接口传`accepted: false`时实测，见4.4 |
| `150015` | 冷静期身份访问普通业务接口受限 | 15:29使用申请中的身份 GET `/api/yf-handset-app/userinfo` 实测，见5.7 |
两个 GET 的未登录响应均为 HTTP 200，正文如下，没有 `time` 字段：
```json
{"code":100090,"msg":"未登录","data":[]}
```
## 3. 注销条件：GET `/eligibility`
### 3.1 存在阻断时的真实响应
HTTP 200，以下为服务端 `2026-08-28 11:39:51` 的响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"can_apply": false,
"store_user_id": 0,
"finance_identity_id": 0,
"wallet_balance_fen": 0,
"wallet_balance": "0.00",
"points_balance": 0,
"wallet_waived": false,
"points_waived": false,
"unfulfilled_count": 37,
"fulfillment_in_progress_count": 0,
"risk_end_at": "2026-08-27 15:47:32",
"eligible_at": "2026-09-03 15:47:32",
"risk_window_hours": 168,
"blockers": [
{
"code": "ORDER_UNFULFILLED",
"message": "账户仍有未履约订单或带单",
"action": "complete_orders"
},
{
"code": "RISK_WINDOW_NOT_EXPIRED",
"message": "最后一笔业务的风险结束时间尚未超过7天",
"action": "wait_risk_window"
},
{
"code": "WALLET_WAIVER_MISSING",
"message": "请先确认放弃现金余额",
"action": "confirm_wallet_waiver"
},
{
"code": "POINTS_WAIVER_MISSING",
"message": "请先确认放弃积分",
"action": "confirm_points_waiver"
}
],
"deregister": null
},
"time": "2026-08-28 11:39:51"
}
```
### 3.2 `data` 字段说明
| 字段 | 已观测 JSON 类型 | 数据信息 |
| --- | --- | --- |
| `can_apply` | boolean | 服务端是否允许提交申请 |
| `store_user_id` | number（整数） | 门店用户身份 ID，不是门店实体 ID |
| `finance_identity_id` | number（整数） | 财务身份 ID |
| `wallet_balance_fen` | number（整数） | 现金余额，单位分，适合金额计算 |
| `wallet_balance` | string | 现金金额展示值，如 `"0.00"`，不是 JSON 数字 |
| `points_balance` | number（整数） | 积分余额 |
| `wallet_waived` | boolean | 当前现金余额快照是否已确认放弃 |
| `points_waived` | boolean | 当前积分余额快照是否已确认放弃 |
| `unfulfilled_count` | number（整数） | 未履约记录数量；本次分别观察到 37 和 0 |
| `fulfillment_in_progress_count` | number（整数） | 处理中记录数量，本次为 0；具体统计范围待后端确认 |
| `risk_end_at` | string / null | 最后业务风险结束时间 |
| `eligible_at` | string / null | 业务风险等待截止时间，**不是注销冷静期截止** |
| `risk_window_hours` | number（整数） | 业务风险等待时长，本次为 168 小时 |
| `blockers` | array<object> | 全部阻断项；无阻断时为 `[]` |
| `deregister` | object / null | 注销记录；草稿结构见第 5 节 |
时间字符串本次采用 `yyyy-MM-dd HH:mm:ss`。另一个测试身份的两个风险时间均为 null，不能把 null 转成当前时间或自行追加 168 小时等待。
### 3.3 `blockers[]` 字段与取值
每项包含三个字符串：`code` 为业务标识，`message` 为展示提示，`action` 为建议动作。应展示全部阻断项。
| 已实测 `code` | 含义 | 已实测 `action` |
| --- | --- | --- |
| `ORDER_UNFULFILLED` | 存在未履约订单或带单 | `complete_orders` |
| `RISK_WINDOW_NOT_EXPIRED` | 风险等待期未结束 | `wait_risk_window` |
| `WALLET_WAIVER_MISSING` | 未确认放弃现金 | `confirm_wallet_waiver` |
| `POINTS_WAIVER_MISSING` | 未确认放弃积分 | `confirm_points_waiver` |
旧文档另列出以下代码，但未实测其完整对象和 `action`：
| 仅文档列出的代码 | 文档含义 |
| --- | --- |
| `SHARED_FINANCE_IDENTITY` | 与其他启用身份共用财务账本，需人工处理 |
| `NEGATIVE_ASSET` | 负余额或负积分 |
| `FINANCE_IN_FLIGHT` | 财务流程尚未收口 |
| `FULFILLMENT_IN_PROGRESS` | 退款、分账或交付任务处理中 |
| `WAIVER_STALE` | 确认后余额变化，需重新确认 |
### 3.4 另一个身份的连续数据变化
以下身份现金、积分均为 0，未履约及处理中数量为 0，两个风险时间均为 null。它与 3.1 中有 37 项未履约记录的身份不同。
| 阶段 | `wallet_waived` | `points_waived` | `can_apply` | 阻断 | `deregister` |
| --- | --- | --- | --- | --- | --- |
| 确认前 | false | false | false | 缺两项确认 | null |
| 现金确认后 | true | false | false | 仅缺积分确认 | `status: 0` 草稿 |
| 积分确认后 | true | true | true | `[]` | 仍为 `status: 0` 草稿 |
| 申请后的冷静期 | false | false | false | 缺两项确认 | `status: 1` 冷静期中 |
| 主动撤销后 | false | false | false | 缺两项确认 | `status: 9` 已撤销 |
**第一次资产确认就会产生非空草稿。两项确认后可以申请，但尚未提交申请，也未进入冷静期。**
冷静期中两项确认已变回 false，不应按阻断建议再次确认资产。撤销后重新申请需重新核验条件和确认资产；尚未真实测试再次申请。
## 4. 两项资产确认接口
现金和积分分别请求，均使用以下 JSON 请求体：
```json
{"accepted":true}
```
### 4.1 POST `/waivers/wallet`
HTTP 200，现金确认成功的真实响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"asset_type": "wallet",
"wallet_balance_fen": 0,
"wallet_balance": "0.00",
"points_balance": 0,
"wallet_waived_at": "2026-08-28 13:45:57",
"points_waived_at": null
},
"time": "2026-08-28 13:45:57"
}
```
### 4.2 POST `/waivers/points`
HTTP 200，积分确认成功的真实响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"asset_type": "points",
"wallet_balance_fen": 0,
"wallet_balance": "0.00",
"points_balance": 0,
"wallet_waived_at": "2026-08-28 13:45:57",
"points_waived_at": "2026-08-28 13:46:42"
},
"time": "2026-08-28 13:46:42"
}
```
### 4.3 确认响应字段
| 字段 | 已观测 JSON 类型 | 含义 |
| --- | --- | --- |
| `asset_type` | string | 本次确认的资产：`wallet` 或 `points` |
| `wallet_balance_fen` | number（整数） | 当前现金余额，分 |
| `wallet_balance` | string | 当前现金金额展示值 |
| `points_balance` | number（整数） | 当前积分余额 |
| `wallet_waived_at` | string（本次均非空） | 现金确认时间；其他场景是否可为 null 尚未实测 |
| `points_waived_at` | string / null | 积分确认时间；现金确认后仍为 null，积分确认后为时间字符串 |
零余额、零积分也需分别确认。确认成功后重新查询条件和状态，以最新标记为准。旧文档规定确认绑定余额快照；确认本身不等于提交注销或立即清零资产。
### 4.4 `accepted: false` 不支持撤回确认（真实测试）
2026-08-28 17:01，使用iPhone 11当前已登录门店身份，在测试环境分别发送一次：
```json
{"accepted":false}
```
前置状态：`status: 0`未提交草稿，`wallet_waived: true`、`points_waived: true`，现金与积分均为0；`apply_time`、`cooling_until`、`completed_at`均为null。
| 接口 | 服务端响应时间 | HTTP状态 | 业务码 | 结果 |
| --- | --- | --- | --- | --- |
| POST `/waivers/wallet` | 2026-08-28 17:01:14 | 200 | 100099 | 拒绝false，确认标记未变化 |
| POST `/waivers/points` | 2026-08-28 17:01:32 | 200 | 100099 | 拒绝false，确认标记未变化 |
现金接口完整响应如下；积分接口除`time`为`2026-08-28 17:01:32`外，其余字段相同：
```json
{
"code": 100099,
"msg": "请明确确认自愿放弃对应资产",
"data": [],
"time": "2026-08-28 17:01:14"
}
```
每次POST后均再次查询`/status`和`/eligibility`：两项确认仍为true，草稿仍为0，金额未变化，`can_apply`仍为true。**当前接口不能通过传false把已确认状态重置为未确认。** 本轮没有发送true、短信、申请或撤销请求，也没有重新登录。`/cancel`能否取消未提交草稿仍未验证，不能由本次结果推断。
脱敏证据：`/private/tmp/suixinkan-waiver-false-20260828/device-wallet-response.json`、`device-points-response.json`及同目录各自的`before/after-status`、`before/after-eligibility`文件。Token未输出或保存；读取真机会话时的临时副本已删除。
## 5. 注销状态：GET `/status`
### 5.1 无记录
HTTP 200，真实响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": null
},
"time": "2026-08-28 11:39:51"
}
```
### 5.2 已确认资产、尚未提交的草稿
HTTP 200，真实响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": {
"id": 0,
"status": 0,
"status_label": "待确认",
"reason": "",
"apply_time": null,
"cooling_until": null,
"remaining_seconds": 0,
"cancel_time": null,
"blocked_code": "",
"blocked_reason": "",
"completed_at": null
}
},
"time": "2026-08-28 13:46:42"
}
```
### 5.3 `data.deregister` 字段
| 字段 | 本次实际类型/值 | 含义与待确认事项 |
| --- | --- | --- |
| `id` | number（正整数，示例脱敏为 0） | 注销记录 ID，不是门店用户 ID |
| `status` | number（整数），`0` / `1` / `9` | 分别为待确认、冷静期中、已撤销；其他值未知 |
| `status_label` | string | 服务端状态文案，如 `"冷静期中"`、`"已撤销"` |
| `reason` | string | 草稿为空；提交后保留用户输入的原因 |
| `apply_time` | string / null | 申请时间，本次 `2026-08-28 14:23:40` |
| `cooling_until` | string / null | 冷静期截止，本次 `2026-09-04 14:23:40`；撤销后仍保留 |
| `remaining_seconds` | number（整数） | 查询时剩余秒数；草稿、已撤销都为 0，不能据此认定已完成 |
| `cancel_time` | string / null | 撤销时间，本次 `2026-08-28 14:24:04` |
| `blocked_code` | string | 草稿/冷静期为空；主动撤销为 `CANCELLED_BY_USER` |
| `blocked_reason` | string | 草稿/冷静期为空；主动撤销为 `用户主动撤销注销` |
| `completed_at` | null | 完成时间；非空类型和格式未实测 |
同一草稿结构也出现在 `eligibility` 的 `data.deregister` 内。两个 GET 的 `cooling_until`、`remaining_seconds` 位于该记录对象中；不能据此推断 `/apply` 响应的嵌套结构。
### 5.4 冷静期的真实响应
GET `/status`，HTTP 200。该结果确认申请已受理，但不是 `/apply` 的原始响应体。
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": {
"id": 0,
"status": 1,
"status_label": "冷静期中",
"reason": "API test; cancel immediately",
"apply_time": "2026-08-28 14:23:40",
"cooling_until": "2026-09-04 14:23:40",
"remaining_seconds": 604776,
"cancel_time": null,
"blocked_code": "",
"blocked_reason": "",
"completed_at": null
}
},
"time": "2026-08-28 14:24:03"
}
```
### 5.5 主动撤销的真实响应
POST `/cancel`，HTTP 200，无业务请求字段。撤销后再次 GET `/status` 返回相同记录，`msg: "success"`、`time: "2026-08-28 14:24:05"`。
```json
{
"code": 100000,
"msg": "注销申请已撤销",
"data": {
"deregister": {
"id": 0,
"status": 9,
"status_label": "已撤销",
"reason": "API test; cancel immediately",
"apply_time": "2026-08-28 14:23:40",
"cooling_until": "2026-09-04 14:23:40",
"remaining_seconds": 0,
"cancel_time": "2026-08-28 14:24:04",
"blocked_code": "CANCELLED_BY_USER",
"blocked_reason": "用户主动撤销注销",
"completed_at": null
}
},
"time": "2026-08-28 14:24:04"
}
```
`status: 9` 表示已撤销；保留旧 `apply_time`、`cooling_until` 不代表仍在冷静期。这里的 `CANCELLED_BY_USER` 是撤销原因，不是终审阻断状态。两个 GET 均确认两项资产确认标记变为 false；冷静期时已经是 false，不能断言由撤销动作单独导致。
### 5.6 新申请保留在冷静期的真实响应
用户最终确认后，于模拟器点击一次提交；以下为后续 GET `/status` 的真实响应（HTTP 200），不是 POST `/apply` 的响应体：
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": {
"id": 0,
"status": 1,
"status_label": "冷静期中",
"reason": "Test account deregistration",
"apply_time": "2026-08-28 15:27:24",
"cooling_until": "2026-09-04 15:27:24",
"remaining_seconds": 604736,
"cancel_time": null,
"blocked_code": "",
"blocked_reason": "",
"completed_at": null
}
},
"time": "2026-08-28 15:28:27"
}
```
同时 GET `/eligibility` 返回现金0、积分0、两项确认 false，以及缺少资产确认的两个阻断；其 `deregister` 仍为上述冷静期记录。不能因此重新确认资产或重复申请。
### 5.7 冷静期普通业务限制的真实响应
15:29以同一身份的现有 Token 只读请求 GET `/api/yf-handset-app/userinfo`，HTTP 200：
```json
{
"code": 150015,
"msg": "账号处于注销冷静期，请先撤销注销后再继续使用",
"data": {
"status": "cooling",
"cooling_until": "2026-09-04 15:27:24",
"remaining_seconds": 604681
}
}
```
该响应没有 `time`，且 `data.status` 是字符串 `"cooling"`；与 `/status` 中 `data.deregister.status` 的数字1不是同一层级或类型，不能共用数字状态 DTO。
请求前后 GET `/status` 均成功且保持同一冷静期申请，`cancel_time`、`completed_at` 均为 null。这证明本次普通信息查询受限，但当前 Token 仍可查询注销状态；不代表正式完成后的鉴权规则已验证，也不能外推为全部普通业务接口已逐一验证。
上述150015和随后status响应已整理为测试夹具（仅记录ID替换为301），并在iPhone 11重放验证业务API、限制通知、状态查询和冷静期页面之间的衔接。此项为Mock集成验证，不是再次请求真实账号或重新申请。
### 5.8 重新登录自动撤销的真实响应
用户重新进入后，15:56只读GET确认之前的申请已撤销，HTTP 200：
```json
{
"code": 100000,
"msg": "success",
"data": {
"deregister": {
"id": 0,
"status": 9,
"status_label": "已撤销",
"reason": "Test account deregistration",
"apply_time": "2026-08-28 15:27:24",
"cooling_until": "2026-09-04 15:27:24",
"remaining_seconds": 0,
"cancel_time": "2026-08-28 15:55:36",
"blocked_code": "CANCELLED_BY_LOGIN",
"blocked_reason": "用户重新登录，自动撤销注销",
"completed_at": null
}
},
"time": "2026-08-28 15:56:34"
}
```
CANCELLED_BY_LOGIN与主动撤销的CANCELLED_BY_USER不同，但同为已撤销9。本次未捕获触发撤销的登录请求，不能确定是哪个登录或身份选择接口触发。并未完成正式注销。
## 6. 尚缺的响应与验证
| 接口 | 旧文档已知信息 | 尚缺信息 |
| --- | --- | --- |
| POST `/send-sms` | 已通过真机发送并收到短信 | 原始成功/失败响应、频率限制及业务码 |
| POST `/apply` | 请求字段 `sms_code`、`reason`；提交后查到冷静期1 | POST 完整响应层级、验证码错误及重复申请响应 |
| POST `/cancel` | 成功体及撤销后9状态已实测 | 失败、重复撤销和终态撤销响应 |
尚未获得阻断、正式完成的 `/status` 响应，不能猜测数字枚举。时间字符串的时区仍待确认，`completed_at` 非空类型和格式仍未实测。
已获得登录自动撤销后的真实状态9和CANCELLED_BY_LOGIN原因，但具体触发接口仍未捕获。到期复核、正式完成后的鉴权响应及全部身份注销后的登录响应仍未验证。此前两次申请现均已撤销。
## 7. 接入注意
1. 按当前门店用户身份隔离状态，不能按手机号共用状态。
2. 展示全部阻断项，不能只使用 `can_apply` 或 HTTP 状态码判断流程。
3. 完整的未提交草稿不应阻止第二项资产确认或手机号验证，非空记录不等于已提交。
4. `eligible_at` 是提交前的业务风险等待截止；`cooling_until` 是提交后的冷静期截止，两者不能混用。
5. `remaining_seconds: 0`、本机时间到期、`can_apply: true` 都不能单独作为注销完成依据。
6. 未知状态、字段缺失或请求失败不能默认解释为“没有申请”。
7. 已撤销9仍含 `cooling_until`，且 `blocked_code` 非空；不能误显示为仍在冷静期或终审阻断。
历史探测过程见 [接口实测记录](门店身份注销接口实测.md)，客户端进度见 [接入说明](门店身份注销接入说明.md)。