# 4.1 账号登录

> **本文件是【账号登录 LGN】模块需求的编辑入口。**
> 主文件 [`../Continental-Retail-APP-PRD.md`](../Continental-Retail-APP-PRD.md) 第 4.1 节已于 2026-08 从本文件回灌（V1.1），此后的需求变更仍改本文件、再回灌。
> **两者不一致时以本文件为准。** 目录约定见 [`README.md`](./README.md)。

| 项 | 值 |
| --- | --- |
| 模块码 | LGN |
| V1.0 章节 | 4.1 |
| 描述粒度 | 14 维完整模板 |
| 需求依据 | 业务需求 + 设计稿 |
| 现状承载系统 | O2O 接单宝后台（用户主数据） |
| 需求条数 | 10（待确认 7，完成度 30%） |
| 配图 | 1 张（设计稿 1） |

模块概要

---

一套账号切换多家门店，账号统一管理、员工权限配置。

![设计稿-登录页](../app-design-images/登录.png)

**页面内容** —— App 登录页目标形态：深色轮胎背景 + 橙色徽标，中部为手机号 / 验证码登录区与「密码登录」「我要注册」两个次级入口，下方是第三方登录（微信、支付宝）与协议勾选行。

**关键交互** —— ①输入手机号 → 点「获取验证码」，60 秒内不可重复获取（[REQ-LGN-001](#412-业务规则)）；②点「密码登录」→ 切换为用户名 + 密码模式；③点「我要注册」→ 进入注册流程（表单与审核流程未定 `TODO(REQ-LGN-004)`）；④点微信 / 支付宝 → 第三方授权，首次需绑定已有手机号账号（`TODO(REQ-LGN-003)` 是否纳入本期）；⑤点《用户协议》/《隐私政策》→ 查看全文；⑥勾选协议后「登录」方可提交。

**可用角色** —— 店长 ✅、技工 ✅，登录环节两个角色完全一致；差异从登录成功后的角色化导航开始（见[导航收敛与角色化配置](./02-HOM-APP首页与导航.md#425-导航收敛与角色化配置)）。第三方登录与注册两项对两个角色均为 ❓ `TODO(REQ-LGN-003)` / `TODO(REQ-LGN-004)`。

**需求关联** —— [REQ-LGN-001](#412-业务规则) 验证码登录、[REQ-LGN-002](#412-业务规则) 密码登录、[REQ-LGN-003](#412-业务规则) 第三方登录、[REQ-LGN-004](#412-业务规则) 注册与审核、[REQ-LGN-005](#412-业务规则) 协议展示与留痕

> **本图与验收标准的两处对不上，需设计补稿**（不新增需求，属设计稿状态缺失）：
>
> 1. 稿中协议勾选框为**未勾选**态，而「登录」按钮画的是完整橙色实心（非置灰）。[验收标准第 1 条](#416-验收标准)要求未勾选时按钮为禁用态 —— **设计稿未画禁用态**。
> 2. 稿中**未见「忘记密码」入口**，而 [REQ-LGN-006](#412-业务规则) 规定忘记密码经手机号验证码重置。该入口可能在「密码登录」模式下才出现，但**密码登录态的稿未提供**，本图无法确认。

## 4.1.1 需求描述

**业务目标** —— 用一套账号替代 6 套小程序各自的登录，消除重复登录；同时建立可审核、可回收的账号管控机制，解决[痛点 2.2](../Continental-Retail-APP-PRD.md#22-账号权限管控)

**目标角色** —— 店长、技工

**入口** —— APP 冷启动且无有效会话；会话失效后的任意页面被动跳转

**前置条件** —— 账号已在 O2O 接单宝后台存在并通过审核；设备可访问网络

**页面内容**：

- 品牌背景 + Continental Logo
- 手机号输入框
- 验证码输入框 + 「获取验证码」
- 「登录」主按钮
- 「密码登录」次按钮（切换到用户名 + 密码模式）
- 「我要注册」文字入口
- 第三方登录区（微信、支付宝）
- 底部协议勾选「已阅读并同意《用户协议》与《隐私政策》」

**主流程**：

1. 输入手机号
2. 获取验证码
3. 输入验证码
4. 勾选协议
5. 点击登录
6. 后端校验通过下发 access / refresh token
7. 拉取该账号的门店列表与角色
8. 单门店直接进入首页；多门店弹出门店选择
9. 进入 APP 首页

**异常流程**：

- 手机号未注册 → 提示并引导「我要注册」
- 验证码错误 → 提示剩余可试次数
- 验证码超时 → 提示重新获取
- 未勾选协议 → 登录按钮不可用
- 账号被停用 → 提示联系门店管理员
- 账号无任何门店归属 → 阻断登录并提示
- 网络异常 → 保留已输入内容并允许重试

**业务规则** —— 见 [4.1.2](#412-业务规则)

**权限规则** —— 登录本身不区分角色；登录成功后由后端下发角色（店长 / 技工）与该角色的可见 tab 集合、功能权限，见[导航收敛与角色化配置](./02-HOM-APP首页与导航.md#425-导航收敛与角色化配置)与[附录 B](../Continental-Retail-APP-PRD.md#附录-b-权限矩阵)

**访问链路** —— App → App Backend → O2O 后台（用户主数据校验）；App Backend → 短信网关（验证码下发）；App Backend → 马上下单（门店列表）

**逻辑数据来源** —— 用户主数据：**O2O 接单宝后台**（手机号、用户名、密码、角色）；门店列表：马上下单；协议内容：APP 后台管理 Web

**回写目标** —— 登录日志、设备信息写入 App Backend；协议同意记录（版本号 + 时间戳）写入 App Backend

**状态变化** —— 无会话 → 已登录（持有 access/refresh token）→ 已选定门店上下文

**验收标准** —— 见 [4.1.6](#416-验收标准)

## 4.1.2 业务规则

**REQ-LGN-001 手机号验证码登录** —— 手机号为 11 位中国大陆号码；验证码 6 位数字，有效期 5 分钟；同一手机号 60 秒内只能获取一次；单日获取上限 `TODO(REQ-LGN-001)`

**REQ-LGN-002 用户名密码登录** —— 用户名与密码沿用 O2O 注册时设置的凭据；密码在传输与存储全程不可逆

**REQ-LGN-003 第三方登录** —— 支持微信、支付宝授权登录。首次授权需绑定已有手机号账号后方可进入；未绑定账号不允许直接创建新账号。

> ⚠️ 该需求仅见于设计稿 —— `TODO(REQ-LGN-003)` 需确认是否纳入本期

**REQ-LGN-004 注册与审核** —— 设计稿含「我要注册」入口。注册后账号处于「待审核」状态，需门店店长或后台管理员审核通过方可登录，以解决[痛点 2.2](../Continental-Retail-APP-PRD.md#22-账号权限管控) 的「随意注册」问题。

> ⚠️ 注册表单字段、审核人、审核时效均未定义 —— `TODO(REQ-LGN-004)`

**REQ-LGN-005 协议展示与留痕** —— 用户协议、隐私政策内容由后台管理 Web 维护，经法务审核；用户点击可查看全文；同意时记录协议版本号与同意时间；协议版本更新后需重新征得同意

**REQ-LGN-006 密码策略** —— 密码长度、复杂度、有效期、历史密码不可复用条数 —— `TODO(REQ-LGN-006)`。忘记密码通过手机号验证码重置

**REQ-LGN-007 登录失败锁定** —— 连续登录失败达到阈值后锁定账号一段时间。阈值与锁定时长 —— `TODO(REQ-LGN-007)`

**REQ-LGN-008 登出** —— 用户主动登出时清理本地会话、门店上下文、缓存的业务数据与 WebView Cookie，见《App 门店上下文与会话管理文档》

**REQ-LGN-009 会话与 Token** —— access token 短期有效，refresh token 轮换续期；refresh 失效后跳转登录页。轮换策略见《后端安全与认证文档》。具体有效期 —— `TODO(REQ-LGN-009)`

**REQ-LGN-010 门店上下文** —— 登录后必须确定唯一「当前门店」；切换门店时级联失效所有门店相关缓存与在途请求，见《App 门店上下文与会话管理文档》

## 4.1.3 店长

1. 店长通过自己注册的手机号登录页面；
2. 店长通过注册的用户名、密码登录页面；
3. 店长点击「用户协议」，可以查看用户协议的具体内容；
4. 店长点击「隐私协议」，可以查看隐私协议的具体内容。

## 4.1.4 技工

1. 技工通过自己注册的手机号登录页面；
2. 技工通过自己的用户名、密码登录页面；
3. 技工点击「用户协议」，可以查看用户协议的具体内容；
4. 技工点击「隐私协议」，可以查看隐私协议的具体内容。

> 登录环节店长与技工无差异；差异从登录成功后的角色化导航开始，见[导航收敛与角色化配置](./02-HOM-APP首页与导航.md#425-导航收敛与角色化配置)。

## 4.1.5 业务数据列表

用户信息当前存放在 O2O 接单宝后台，用户的登录验证数据一致性以 O2O 接单宝后台的数据为用户主数据。

| # | 字段 | 字段名 | 数据来源 | 说明 |
| --- | --- | --- | --- | --- |
| 1 | 手机号 | PhoneNum | O2O 后台 | 用户注册手机号 |
| 2 | 用户名 | Username | O2O 后台 | 用户在 O2O 注册时的用户名 |
| 3 | 密码 | Password | O2O 后台 | 用户名设置的密码 |
| 4 | 用户协议 | UserProtocol | APP 后台管理 Web | 由法务审核后的协议条例 |
| 5 | 隐私政策 | PrivateProtocol | APP 后台管理 Web | 由法务审核后的隐私政策 |
| 6 | 验证码 | ValidateCode | 第三方短信网关 | 后台调用短信网关发送至用户手机 |
| 7 | 角色 | RoleCode | O2O 后台 / APP 后台 | 店长 / 技工，决定导航与权限 —— 权威来源待确认 `TODO(REQ-LGN-011)` |
| 8 | 门店列表 | StoreList | 马上下单 | 该账号可访问的门店集合 |
| 9 | 协议同意记录 | ProtocolConsent | APP Backend | 协议版本号 + 同意时间戳 |

账号登录业务数据

## 4.1.6 验收标准

1. 未勾选协议时登录按钮为禁用态，无法提交；
2. 单门店账号登录后直接进入首页，不出现门店选择步骤；
3. 多门店账号登录后必须完成门店选择才能进入首页；
4. 主动登出后，重新启动 APP 不会恢复到已登录状态，且 WebView 中原会话不可复用；
5. refresh token 失效后，任意业务页面的接口调用都会被统一拦截并跳转登录页，不出现半登录态；
6. 切换门店后，首页及各业务页展示的数据全部属于新门店，无旧门店数据残留。

---

## 附：本模块归拢信息

> 以下内容从主文件的其它章节归拢而来，便于本模块独立评审。**回灌主文件时不处理本分界线以下的部分**——主文件的附录仍是全局视图。

### 附-1 业务数据字典（主文件附录 A.1）

| # | 数据集 | 来源 | 安全 | 备注 |
| --- | --- | --- | --- | --- |
| 1 | 第三方验证码 | App Backend | HTTPS | 短信调用第三方短信网关 |
| 2 | 登录成功结果集 | App Backend | HTTPS | 账号密码登录与验证码登录共用 |
| 3 | 用户协议与隐私政策完整内容 | App Backend | HTTPS | 注册/登录前须确认（[REQ-NFR-020](../Continental-Retail-APP-PRD.md#84-安全与合规)） |

登录模块数据集（摘自主文件[附录 A.1](../Continental-Retail-APP-PRD.md#a1-登录)）。字段级清单见上方 [4.1.5](#415-业务数据列表)。

> 主文件[附录 A.9 个人中心](../Continental-Retail-APP-PRD.md#a9-个人中心)第 5 条隐含一条与本模块相关、尚未成文的规则：**多设备可同时登录，单设备登出不影响其它设备**。这与[账号权限管控痛点](../Continental-Retail-APP-PRD.md#22-账号权限管控)中「账号共用」的治理诉求存在张力 —— 是否需要单设备登录限制，在 `TODO(REQ-LGN-009)` 一并确认。

### 附-2 权限矩阵（主文件附录 B 本模块分行）

**图例**：✅ 完整权限 · 🔸 受限 · ⚙️ 需店长/后台显式授权 · ✗ 无权限 · ❓ 待确认

| 功能 | 店长 | 技工 | 备注 / 待确认 |
| --- | --- | --- | --- |
| 手机验证码 / 账号密码登录 | ✅ | ✅ | |
| 第三方登录（微信/支付宝） | ❓ | ❓ | 仅见于设计稿 `TODO(REQ-LGN-003)` |
| 注册 | ❓ | ❓ | 需审核 `TODO(REQ-LGN-004)` |

登录模块权限矩阵（摘自主文件[附录 B](../Continental-Retail-APP-PRD.md#附录-b-权限矩阵)）

适用的全局权限实施规则：接口层强制（REQ-ACC-004）；⚙️ 类由店长或后台经[人员管理「可用系统」](./09-STM-门店管理.md#49-门店管理)授予（REQ-ACC-005）；**🔸 与 ❓ 项在待确认关闭前，一律按更严格的一侧实现**（REQ-ACC-006）；权限变更后用户下次进入 App 即生效（REQ-ACC-007）。

### 附-3 待确认项（主文件 10.2.1）

| 编号 | 待确认内容 | 建议决策方 |
| --- | --- | --- |
| REQ-LGN-001 | 验证码单日获取上限 | 安全 / 后端 |
| REQ-LGN-003 | 微信/支付宝第三方登录是否纳入本期（仅见于设计稿） | 产品 |
| REQ-LGN-004 | 注册表单字段、审核人、审核时效（设计稿有「我要注册」） | 产品 / 运营 |
| REQ-LGN-006 | 密码长度、复杂度、有效期、历史密码不可复用条数 | 安全 |
| REQ-LGN-007 | 登录失败锁定阈值与锁定时长 | 安全 |
| REQ-LGN-009 | access / refresh token 有效期 | 安全 / 后端 |
| REQ-LGN-011 | 角色（RoleCode）的权威来源是 O2O 后台还是 APP 后台 | 架构 |

登录模块待确认项（摘自主文件 [10.2.1](../Continental-Retail-APP-PRD.md#1021-登录lgn)，7 条）

### 附-4 配图清单（主文件附录 C 4.1 节）

| 序 | 说明 | 文件 |
| --- | --- | --- |
| 1 | 设计稿-登录页（验证码 / 密码 / 第三方三种登录方式 + 注册入口 + 协议勾选） | `../app-design-images/登录.png` |

登录模块配图清单，1 张（设计稿 1）。说明较主文件[附录 C](../Continental-Retail-APP-PRD.md#附录-c-图表清单)已按实际截图内容补充，主文件附录 C 回灌时应一并更新。

### 附-5 本次拆分新增发现

本模块**未新增编号需求**。逐图核看发现的两处缺口均为**设计稿状态缺失**，已就地记在图下：登录按钮的禁用态未画、密码登录模式与「忘记密码」入口无设计稿。两者都已被现有的[验收标准第 1 条](#416-验收标准)与 [REQ-LGN-006](#412-业务规则) 覆盖，补稿即可，无需新增需求编号。
