> **For AI assistants**: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.

# Fonrey 登录管理技术方案

**版本**: 4.1  
**项目**: Fonrey 房产经纪管理系统  
**技术栈**: Django 4.x + HTMX + Alpine.js + PostgreSQL 16 + Redis + Celery  
**关联 PRD**: `PRD/登录管理/用户登录管理模块PRD.md`（v3.0）  
**关联数据模型**: `DATA_MODEL/DATA_MODEL_LOGIN.md`（本方案不重复 DDL）  
**关联契约规范**: `TECH_STACK/API_CONTRACT.md`（全局 API 契约权威）  
**关联测试规范**: `TECH_STACK/测试规范.md`、`TEST_CASES/TEST_CASES_LOGIN_MODULE.md`  
**最后更新**: 2026-05-02

---

## 变更历史

| 日期         | 变更人      | 变更内容                                                                                                                                                                                                                                                                                                            |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-04-30 | Atlas    | 补充"变更历史"章节（文档治理）                                                                                                                                                                                                                                                                                                |
| 2026-05-02 | Sisyphus | 按 `ADR-20260502-003` 承接从 PRD v3.0 迁出的实现细节：①§5.3 新增 Tenant Verify 请求/响应 JSON Schema；②§5.3 新增预留 Wechat 端点 `GET /api/auth/wechat/qrcode/` 与 `POST /api/auth/wechat/callback/`（仅占位，MVP 不开放）；③新增 §十三 Electron 客户端约定（Tenant Code 存储/Session/登录页加载/多标签页/登出/窗口关闭/强制更新）；④§六 关键流程约束补全密码错误锁定阈值、滑块容差、找回密码错误次数等数值口径，统一以本文件为准 |

## 一、文档定位与边界

本文件定义登录模块的实现口径：

1. 模块范围与职责边界
2. API 端点（页面 / HTMX / JSON）
3. 安全策略（滑块验证、登录锁定、短信 OTP、会话）
4. Redis/Celery 运行策略
5. 错误码与测试映射

> 本文件不展开数据表字段与索引。数据结构以 `DATA_MODEL_LOGIN.md` 为唯一权威。

---

## 二、范围定义（以 PRD v2.0 为准）

### 2.1 P0 必须覆盖

- Tenant Code 识别（首次启动 + 切换公司）
- 密码登录（手机号/密码 + 滑块）
- 首次登录强制修改密码
- 找回密码（纯短信三步流程）
- 手机验证码登录（MVP 正式功能）
- 登录失败锁定 / 自动解锁 / 管理员解锁
- 安全登出与会话失效

### 2.2 非目标 / 预留

- 微信扫码登录（仅保留禁用入口与接口占位，不开放功能）
- 企业 SSO（OAuth2 / SAML）
- 风险评分/设备指纹

### 2.3 已废弃（不得实现）

- 找回用户名流程（Story 4 已废弃）

---

## 三、模块架构边界

### 3.1 模块职责（`apps/account`）

- 租户识别与租户上下文建立前置校验
- 登录鉴权、会话签发、登出销毁
- 首登改密门禁（`is_initial_password`）
- 短信 OTP 发送/校验（找回密码 + 验证码登录）
- 登录与安全审计事件写入

### 3.2 多租户分层职责

| 层级 | Schema | 职责 |
|---|---|---|
| Tenant Code 校验 | Public | 校验 `tenant_code`、租户状态、品牌信息返回 |
| 登录认证 | Tenant | 账号鉴权、失败计数、锁定状态、会话签发 |
| 短信 OTP | Tenant | OTP 记录、场景区分、过期与尝试次数控制 |

### 3.3 外部依赖

| 依赖模块 | 用途 |
|---|---|
| `apps/org` | 员工状态联动（离职/停用不可登录） |
| `core/encryption.py` | 手机号加密/哈希能力 |
| `core/cache.py` | 滑块票据、频控、锁定计数、重置 token |
| `Celery` | 短信发送异步化（可选，建议） |

---

## 四、API 设计原则

1. 登录安全链路：**Tenant 校验 → 滑块验证 → 登录提交**。  
2. 防枚举：账号不存在/停用等敏感状态采用统一外显文案。  
3. 账号锁定是账号维度策略，不区分密码登录或验证码登录。  
4. Redis 仅作运行态与频控，最终状态以数据库持久化字段为准。  
5. 所有登录相关接口遵循 `TECH_STACK/API_CONTRACT.md` 的统一错误响应格式。

---

## 五、端点清单

### 5.1 页面路由（SSR）

| 路径                               | 方法  | 鉴权  | 说明                  |
| -------------------------------- | --- | --- | ------------------- |
| `/auth/tenant/identify/`         | GET | 否   | Tenant 识别页          |
| `/auth/login/`                   | GET | 否   | 登录页（密码登录/验证码登录 Tab） |
| `/auth/password/forgot/`         | GET | 否   | 找回密码三步页             |
| `/auth/password/change-initial/` | GET | 是   | 首次登录强制改密页           |

> 说明：`/auth/wechat/*` 仅预留，不在 MVP 开放。

### 5.2 HTMX 片段端点

| 路径                             | 方法  | 用途          | 返回      |
| ------------------------------ | --- | ----------- | ------- |
| `/auth/fragments/captcha/`     | GET | 刷新滑块区块      | HTML 片段 |
| `/auth/fragments/login-form/`  | GET | 登录 Tab 内容局刷 | HTML 片段 |
| `/auth/fragments/forgot-step/` | GET | 找回密码步骤局刷    | HTML 片段 |

### 5.3 JSON API（MVP）

| 端点 | 方法 | 说明 |
|---|---|---|
| `/api/auth/tenant/verify/` | POST | Tenant Code 校验（公开接口） |
| `/api/auth/captcha/` | GET | 获取滑块拼图验证码（返回背景图 Base64 + 碎片图 Base64 + 验证 Token） |
| `/api/auth/captcha/verify/` | POST | 校验滑块并签发 `captcha_pass_token` |
| `/api/auth/login/` | POST | 密码登录 |
| `/api/auth/login/phone/` | POST | 手机验证码登录 |
| `/api/auth/recover/password/request/` | POST | 找回密码步骤一：发 OTP |
| `/api/auth/recover/password/verify/` | POST | 找回密码步骤二：校验 OTP，颁发 `sms_reset_token` |
| `/api/auth/recover/password/reset/` | POST | 找回密码步骤三：提交新密码 |
| `/api/auth/password/change-initial/` | POST | 首次登录强制改密提交 |
| `/api/auth/logout/` | POST | 登出销毁会话 |

#### 5.3.1 Tenant Verify 请求/响应 Schema

请求体：

```json
{ "tenant_code": "202500010001" }
```

成功响应（HTTP 200）：

```json
{
  "valid": true,
  "tenant_name": "XX房产经纪有限公司",
  "tenant_logo_url": "https://cdn.fonrey.com/tenants/xxx/logo.png",
  "login_url": "https://xxx.fonrey.com/auth/login/"
}
```

失败响应（HTTP 200，业务态失败）：

```json
{
  "valid": false,
  "error_code": "AUTH_TENANT_NOT_FOUND",
  "message": "识别码无效"
}
```

限流超限响应（HTTP 429）遵循 `API_CONTRACT.md` 统一错误格式，`code = AUTH_TENANT_RATE_LIMITED`。

### 5.4 预留端点（MVP 不开放）

| 端点 | 方法 | 状态 | 说明 |
|---|---|---|---|
| `/api/auth/wechat/qrcode/` | GET | 仅占位 | 微信扫码登录二维码获取（v2 实现） |
| `/api/auth/wechat/callback/` | POST | 仅占位 | 微信扫码回调换取系统 Token（v2 实现） |

> MVP 内 URLConf 中**不注册**这两个路由，登录页 UI 入口以禁用态展示；v2 启用时再按本表落地路由与视图。

---

## 六、关键流程约束

### 6.1 Tenant 识别

- `tenant_code` 固定 12 位数字，前后空格自动 trim
- 成功返回：租户名称、Logo URL、登录地址
- 失败返回：`valid=false` + 统一错误信息
- 接口公开但必须限流：单 IP 每分钟 ≤ 10 次

### 6.2 密码登录

请求体（示例）：

```json
{
  "phone": "13800138000",
  "password": "***",
  "captcha_pass_token": "token"
}
```

关键规则：
- 滑块通过后方可提交登录
- 密码连续错误 ≥ 5 次，锁定 30 分钟
- `is_initial_password = true` 时强制跳转改密页
- 错误文案统一，不泄露账号存在性细节

### 6.3 找回密码（纯短信三步）

#### 步骤一：发送 OTP
- `scene = password_reset`
- OTP 有效期：10 分钟
- 同手机号频控：5 次/小时
- 手机号不存在/停用：统一提示“如该手机号已注册，验证码将在 1 分钟内发送”

#### 步骤二：校验 OTP
- 正确且未过期：签发 `sms_reset_token`（15 分钟，一次性）
- 错误：累计尝试，≥5 次作废该 OTP
- 过期：提示重新获取

#### 步骤三：重置密码
- 必须携带有效 `sms_reset_token`
- 成功后：`is_initial_password = false`
- 该用户所有会话立即失效，跳回登录页

### 6.4 手机验证码登录（MVP 正式）

请求体（示例）：

```json
{
  "phone": "13800138000",
  "sms_code": "123456"
}
```

关键规则：
- 获取登录验证码前必须先通过滑块
- `scene = login`
- OTP 有效期：5 分钟
- 同手机号频控：10 次/小时（与 `password_reset` 独立计数）
- OTP 错误 ≥5 次作废
- 账号 `locked` 或 `disabled` 时，验证码登录同样拒绝

---

## 七、Redis Key 规范（对齐 PRD）

| Key | TTL | 说明 |
|---|---|---|
| `captcha_token:{uuid}` | 3 分钟 | 滑块验证会话 |
| `captcha_pass:{uuid}` | 3 分钟 | 一次性通过凭证 |
| `login_fail:{tenant_id}:{username}` | 30 分钟 | 登录失败计数 |
| `sms_limit:password_reset:{phone}` | 1 小时 | 找回密码 OTP 发送频控（≤5次） |
| `sms_limit:login:{phone}` | 1 小时 | 登录 OTP 发送频控（≤10次） |
| `sms_reset_token:{token}` | 15 分钟 | 找回密码步骤三凭证 |
| `tenant_verify_ip:{ip}` | 1 分钟 | Tenant 校验接口 IP 限流（≤10次） |

---

## 八、安全与合规

1. 密码仅允许 Django 安全哈希（PBKDF2/Argon2）。
2. OTP 明文不得入库，仅存哈希。
3. 敏感字段日志脱敏（手机号、token、验证码）。
4. 会话过期或登出后，受保护页面必须重定向登录。
5. HTTPS 强制，不允许明文传输降级。

---

## 九、错误码建议（登录模块）

| code | HTTP | 中文含义 |
|---|---|---|
| `AUTH_TENANT_NOT_FOUND` | 400 | 租户识别码无效 |
| `AUTH_TENANT_RATE_LIMITED` | 429 | Tenant 校验请求过于频繁 |
| `AUTH_CAPTCHA_INVALID` | 400 | 滑块验证失败 |
| `AUTH_INVALID_CREDENTIAL` | 401 | 手机号或密码错误 |
| `AUTH_ACCOUNT_LOCKED` | 423 | 账号已锁定 |
| `AUTH_ACCOUNT_DISABLED` | 403 | 账号已停用 |
| `AUTH_SMS_OTP_INVALID` | 400 | 短信验证码错误 |
| `AUTH_SMS_OTP_EXPIRED` | 400 | 短信验证码过期 |
| `AUTH_SMS_OTP_RATE_LIMITED` | 429 | OTP 发送超限 |
| `AUTH_SMS_RESET_TOKEN_INVALID` | 400 | 重置凭证无效或过期 |
| `AUTH_PASSWORD_WEAK` | 400 | 新密码不满足强度规则 |

---

## 十、测试映射（与全局编号对齐）

- 测试编号规范：`TEST_CASES/TEST_CASE_ID_SPEC.md`
- 注册表：`TEST_CASES/TEST_CASE_REGISTRY.md`
- 登录模块用例：`TEST_CASES/TEST_CASES_LOGIN_MODULE.md`

建议最小执行集：
- Tenant 识别：`TC-FON-000001` ~ `000010`
- 密码登录与锁定：`TC-FON-000011` ~ `000028`
- 首登改密：`TC-FON-000029` ~ `000033`
- 找回密码：`TC-FON-000034` ~ `000044`
- 验证码登录：`TC-FON-000045` ~ `000048`

---

## 十一、落地顺序建议

1. Tenant 识别 + 密码登录主链路
2. 滑块与失败锁定
3. 首登改密门禁
4. 找回密码三步（短信）
5. 手机验证码登录（scene=login）
6. 报表与监控补齐

---

## 十二、文档同步规则

- PRD 登录模块变更：同步本文件
- 数据结构调整：同步 `DATA_MODEL_LOGIN.md`
- 测试用例新增/变更：同步 `TEST_CASES/TEST_CASE_REGISTRY.md` 与登录用例文档
- API 契约调整：同步 `TECH_STACK/API_CONTRACT.md`

---

## 十三、Electron 客户端约定（实现口径）

> 承接自原 PRD §5.7（按 `ADR-20260502-003` 迁入本文件）。本节为 Electron 渲染层与主进程在登录链路上的实现规约，开发时必须严格遵循。

### 13.1 存储与会话

| 约定项 | 实现规格 |
|---|---|
| Tenant Code 存储 | `electron-store` 或 `app.getPath('userData')` 下的配置文件，**必须 AES 加密**，禁止明文落盘 |
| Session Token 存储 | 内存（主进程 `global` 变量）+ Chromium 管理的 `session` Cookie（`HttpOnly` + `Secure` + `SameSite=Strict`），**禁止写入磁盘明文文件** |
| 多标签页 | 同一 `BrowserWindow` 内，所有页面共享同一 `session.defaultSession`，复用同一 Session Cookie |
| 窗口关闭 | Session 保留（不自动登出）；下次启动客户端时，若 Cookie 未过期且 `/api/auth/whoami/` 校验通过，直接进入系统 |

### 13.2 登录页加载流程

1. 主进程读取本地缓存的 `tenant_code`：
   - 不存在 → `BrowserWindow.loadURL('app://tenant-identify')`（本地静态页或专用 Tenant 识别 URL）
   - 存在 → 调用 `POST /api/auth/tenant/verify/` 复核（防止租户被禁用 / 改名）
     - 成功 → 构建 `https://{tenant_slug}.fonrey.com/auth/login/`，通过 `BrowserWindow.loadURL()` 加载
     - 失败 → 清除本地 `tenant_code` 缓存 → 跳回 Tenant 识别页
2. 切换公司：用户在登录页点击「切换公司」 → 主进程清缓存 → 关闭当前 `BrowserWindow` → 重新走步骤 1。

### 13.3 登出与强制更新

| 场景 | 客户端动作 |
|---|---|
| 用户登出 | 调用 `POST /api/auth/logout/` → 清除 Chromium Session Cookie（`session.defaultSession.clearStorageData({ storages: ['cookies'] })`）→ 跳转登录页 |
| 服务端 Session 过期（401） | 渲染层捕获 401 → 主进程清 Cookie → 跳转登录页并提示"登录已过期，请重新登录" |
| 客户端版本低于 `min_required_version` | 加载登录页前先展示"请更新客户端"模态，阻断登录流程；联动 `平台管理后台技术方案.md` 客户端发布章节 |

### 13.4 安全约束（与 AGENTS.md §5 对齐）

- 渲染进程必须 `nodeIntegration: false`、`contextIsolation: true`、`sandbox: true`；
- 渲染层禁止内嵌业务逻辑或本地数据库（壳应用原则）；
- 主进程与渲染层之间通过 `contextBridge` 暴露的最小白名单 IPC 接口通信；
- 仅允许加载 `https://*.fonrey.com` 与 `app://` 协议，其他 URL 在 `will-navigate` 中拦截。