01 — SA 登录与账号
来源：
kangaroo_prototype/src/apps/pocketbuy_sa/api/auth.ts+store/sessionStore.ts
涉及页面：Login PRD
共 3 个接口：① SA 登录 ② 当前 SA 档案查询 ③ 重置 SA 密码
业务上下文
- SA App 是 SA 工作工具，每天频繁登录使用
- SA 账号由后台运营创建（不开放自注册），初始密码由运营当面 / 微信告知
- 登录通过返回 token + SA 档案 + 授权 merchant / POS 列表（这些是后续办单流程的前置数据）
- token 长期有效（业界 30 天默认即可）
- 密码重置：SA 可在 Settings 内直接重置（不验旧密码 / 不发 OTP）；忘记密码场景由运营兜底（重置接口由后台运营调用）
1. SA 登录
业务描述：SA 用手机号 + 密码登录，成功返回 token + SA 档案 + 授权列表（merchant / POS）。
触发场景：Login 页点击 Login 按钮。
入参
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | string | ✓ | 10 位 NG 本地号（不含 +234 前缀；前端已剥离） |
| password | string | ✓ | 明文密码（HTTPS 传输；后端按存储策略哈希比对） |
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| auth_token | string | 登录 token；长期有效；前端持久化到本地 |
| sa_id | string | SA 工号（稳定 ID；如 SA-000128） |
| sa_name | string | SA 显示名 |
| bound_merchants | array<Merchant> | 授权可办单的商户列表（用于 Applications 筛选 / Achievement 拆分） |
| bound_pos_locations | array<PosLocation> | 授权 POS 列表（用于办单时扫码 / 校验现场办单） |
Merchant 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| merchant_id | string | 商户 ID（业务实体） |
| merchant_name | string | 商户全名 |
| short_label | string? | 短标签（如 Ikeja，UI 紧凑场景用） |
PosLocation 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| pos_id | string | POS ID（同时是 QR 扫码内容） |
| pos_name | string | POS 显示名（如 Ikeja Branch） |
| pos_address | string | POS 地址 |
| merchant_id | string | 所属商户 ID |
| merchant_name | string | 所属商户名（冗余冗余便于 UI 直接展示，不强制 join） |
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| AUTH_INVALID_CREDENTIALS | 手机号或密码错误 | inline 错误 Phone or password is incorrect（不区分用户名/密码错防枚举） |
| AUTH_ACCOUNT_DISABLED | 账户被运营禁用 | inline 错误 Your account is disabled. Contact your supervisor. |
| AUTH_LOCKED（二期） | 短时间错误次数过多锁定 | inline 错误 Too many attempts. Contact your supervisor. |
注：
- 多设备登录：同账号在多台手机登录互不踢出（SA 可能用工作机 + 个人机），各设备各自持有独立 token；token 失效互不影响
2. 当前 SA 档案查询
业务描述：用现有 token 拉取当前登录 SA 的档案 + 授权列表，用于 App 启动时重建会话上下文 / token 即将过期时刷新档案。
触发场景：
- App 启动且本地有 token（rehydrate session）
- 长会话续期（如 token 仍有效但 SA 档案可能已被运营更新）
入参
无业务字段（仅鉴权 token，通过头部传递；架构师定）
出参
与「SA 登录」出参结构一致 — auth_token 字段可省略或重新下发（视 token 续期策略）。
| 字段 | 类型 | 说明 |
|---|---|---|
| sa_id / sa_name | 同上 | |
| bound_merchants | array<Merchant> | 同上 |
| bound_pos_locations | array<PosLocation> | 同上 |
| auth_token | string? | 可选；若续签策略要求重发则带回 |
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| AUTH_TOKEN_INVALID | token 失效（过期 / 撤销） | 清本地 session + 跳 /login |
| AUTH_ACCOUNT_DISABLED | 账户已被禁用 | 同上 |
注：
- 授权列表同步策略：本接口同时承担「授权列表实时同步」职责 — SA 端在 每次开启新办单（点 New Application）前 调用本接口刷新
bound_merchants/bound_pos_locations，确保运营新增 / 撤销 POS 后能即时感知；不依赖后端 push
3. 重置 SA 密码
业务描述：登录态 SA 在 Settings 子页直接重置密码 —— 不验证旧密码 / 不发 OTP。MVP 账号体系简单，验证强度由运营兜底（如发现异常重置，运营后台可禁用账号）；前端做”两次输入新密码一致 + 长度 ≥6”基础体验防错。
触发场景：Settings 页 “Reset Password” 入口点击 → 弹层输入新密码 + 确认 → Submit。
入参
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| new_password | string | ✓ | 新密码明文（HTTPS 传输；后端按存储策略哈希）；长度 ≥6 |
出参
| 字段 | 类型 | 说明 |
|---|---|---|
| ok | boolean | true 表示重置成功；token 不重发（保持当前会话） |
关键异常
| 异常码 | 含义 | 前端处理 |
|---|---|---|
| AUTH_TOKEN_INVALID | token 失效 | 清本地 session + 跳 /login |
| RESET_PASSWORD_WEAK | 新密码不满足后端策略（如纯数字 / 短于 6） | inline 错误 |
| AUTH_ACCOUNT_DISABLED | 账户已禁用 | 跳 /login |
注：
- 接口仅 SA 本人登录态下调用；运营后台兜底重置由独立后台接口处理（不在本清单）
- 安全增强建议（二期）：加旧密码验证 / OTP 二次确认 / 操作审计落日志
- 重置成功后无需重新登录（保持当前 token 有效）；下次登录用新密码