357 lines
14 KiB
Markdown
357 lines
14 KiB
Markdown
> **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` 中拦截。
|