283 lines
8.1 KiB
Markdown
283 lines
8.1 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 登录管理技术方案
|
||
|
||
**版本**: 3.1
|
||
**项目**: Fonrey 房产经纪管理系统
|
||
**技术栈**: Django 4.x + HTMX + Alpine.js + PostgreSQL 16 + Redis + Celery
|
||
**关联 PRD**: `PRD/登录管理/用户登录管理模块PRD.md`
|
||
**关联数据模型**: `DATA_MODEL/DATA_MODEL_LOGIN.md`（本方案不重复 DDL）
|
||
**关联契约规范**: `TECH_STACK/API_CONTRACT.md`（全局 API 契约权威）
|
||
**最后更新**: 2026-04-27
|
||
|
||
---
|
||
|
||
## 一、文档定位与边界
|
||
|
||
本文件仅定义登录模块的：
|
||
|
||
1. 模块边界与服务职责
|
||
2. API 端点设计（页面 / HTMX / JSON）
|
||
3. 登录安全策略（验证码、锁定、会话、找回）
|
||
4. 缓存与异步任务策略
|
||
5. 错误码与测试映射
|
||
|
||
> 不在本文件展开表字段、索引、DDL。数据结构以 `DATA_MODEL_LOGIN.md` 为唯一权威。
|
||
|
||
---
|
||
|
||
## 二、范围定义（以 P0 为准）
|
||
|
||
### 2.1 P0 必须覆盖
|
||
|
||
- Tenant ID 校验（Public Schema）
|
||
- 用户名 + 密码登录（Tenant Schema）
|
||
- 验证码挑战与一次性 pass token
|
||
- 连续失败锁定与解锁机制
|
||
- 找回用户名 / 重置密码
|
||
- 首次登录强制改密
|
||
- 安全登出与会话销毁
|
||
|
||
### 2.2 预留（非本期强制）
|
||
|
||
- MFA（OTP / 短信）
|
||
- 企业 SSO（OAuth2 / SAML）
|
||
- 设备指纹与风险评分
|
||
|
||
---
|
||
|
||
## 三、模块架构边界
|
||
|
||
## 3.1 模块职责（`apps/account`）
|
||
|
||
- 登录认证入口与 Session 建立
|
||
- 密码策略、锁定策略、登录防刷策略执行
|
||
- 找回流程与一次性重置令牌管理
|
||
- 登录/登出/失败审计事件写入
|
||
|
||
## 3.2 多租户分层职责
|
||
|
||
| 层级 | Schema | 职责 |
|
||
|---|---|---|
|
||
| Tenant ID 校验 | Public | 校验租户标识、域名映射、租户状态 |
|
||
| 登录认证 | Tenant | 账号鉴权、失败计数、会话建立 |
|
||
| 密码找回 | Tenant | 身份确认、令牌签发与核销 |
|
||
|
||
## 3.3 外部依赖
|
||
|
||
| 依赖模块 | 用途 |
|
||
|---|---|
|
||
| `apps/org` | 员工状态联动（离职/冻结禁止登录） |
|
||
| `core/encryption.py` | 手机号等敏感信息加密与脱敏 |
|
||
| `core/cache.py` | 验证码票据、失败计数、频控缓存 |
|
||
| `Celery` | 找回消息异步发送、安全日报任务 |
|
||
|
||
---
|
||
|
||
## 四、API 设计原则
|
||
|
||
1. 登录链路固定三段：Tenant 校验 → 验证码 → 账号认证。
|
||
2. 最小暴露原则：账号不存在与密码错误统一返回。
|
||
3. 认证状态以数据库为准，Redis 仅做加速与频控。
|
||
4. 安全相关写操作后立即失效缓存，不依赖 TTL。
|
||
5. HTMX 返回片段，JSON 返回结构化错误体。
|
||
|
||
---
|
||
|
||
## 五、端点清单（核心）
|
||
|
||
## 5.1 页面路由（SSR）
|
||
|
||
| 路径 | 方法 | 鉴权 | 说明 |
|
||
|---|---|---|---|
|
||
| `/account/tenant/verify/` | GET | 否 | 首次租户识别页 |
|
||
| `/account/login/` | GET | 否 | 登录页 |
|
||
| `/account/change-password/` | GET | 是 | 首登强制改密页 |
|
||
| `/account/recover-username/` | GET | 否 | 找回用户名页 |
|
||
| `/account/recover-password/` | GET | 否 | 找回密码页 |
|
||
|
||
## 5.2 HTMX 片段端点
|
||
|
||
| 路径 | 方法 | 用途 | 返回 |
|
||
|---|---|---|---|
|
||
| `/account/fragments/login-form/` | GET | 登录表单局刷 | HTML 片段 |
|
||
| `/account/fragments/captcha/` | GET | 验证码区块刷新 | HTML 片段 |
|
||
| `/account/fragments/recover-step/` | GET | 找回步骤局刷 | HTML 片段 |
|
||
|
||
## 5.3 JSON API（P0）
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/account/tenant/verify/` | POST | 校验 tenant_id 与可用性 |
|
||
| `/api/account/captcha/generate/` | POST | 生成验证码 challenge |
|
||
| `/api/account/captcha/verify/` | POST | 校验 challenge 并签发 pass token |
|
||
| `/api/account/login/` | POST | 登录并建立 session |
|
||
| `/api/account/logout/` | POST | 登出并销毁 session |
|
||
| `/api/account/password/change/` | POST | 登录态改密 |
|
||
| `/api/account/username/recover/` | POST | 找回用户名 |
|
||
| `/api/account/password/recover/request/` | POST | 申请重置密码令牌 |
|
||
| `/api/account/password/recover/reset/` | POST | 使用令牌重置密码 |
|
||
|
||
---
|
||
|
||
## 六、关键 API 规范（请求/响应）
|
||
|
||
## 6.1 登录
|
||
|
||
`POST /api/account/login/`
|
||
|
||
```json
|
||
{
|
||
"tenant_id": "fonrey-sh",
|
||
"username": "agent_001",
|
||
"password": "******",
|
||
"captcha_pass_token": "token"
|
||
}
|
||
```
|
||
|
||
成功 `200`：
|
||
|
||
```json
|
||
{
|
||
"message": "登录成功",
|
||
"redirect_url": "/home/"
|
||
}
|
||
```
|
||
|
||
失败码：`ACCOUNT_LOGIN_INVALID_CREDENTIAL` / `ACCOUNT_LOCKED` / `ACCOUNT_CAPTCHA_INVALID`
|
||
|
||
## 6.2 申请重置密码
|
||
|
||
`POST /api/account/password/recover/request/`
|
||
|
||
```json
|
||
{
|
||
"tenant_id": "fonrey-sh",
|
||
"username": "agent_001",
|
||
"contact": "138****0000"
|
||
}
|
||
```
|
||
|
||
规则：
|
||
- 频率限制（建议 5 次/小时）
|
||
- 统一返回文案，避免枚举账号存在性
|
||
|
||
---
|
||
|
||
## 七、HTMX 交互约定
|
||
|
||
## 7.1 Header 约定
|
||
|
||
- 请求头：`HX-Request: true`
|
||
- 成功触发：`HX-Trigger: {"toast":{"level":"success","message":"操作成功"}}`
|
||
- 失败触发：`HX-Trigger: {"toast":{"level":"error","message":"操作失败"}}`
|
||
- 登录成功：`HX-Redirect: /home/`
|
||
|
||
## 7.2 模板分片命名
|
||
|
||
- `templates/account/fragments/login_form.html`
|
||
- `templates/account/fragments/captcha_panel.html`
|
||
- `templates/account/fragments/recover_step.html`
|
||
|
||
---
|
||
|
||
## 八、权限与数据范围
|
||
|
||
## 8.1 访问控制
|
||
|
||
- 匿名可访问：租户校验、登录、找回相关端点
|
||
- 登录后访问：改密、登出
|
||
- 首登未改密用户仅允许访问改密页面
|
||
|
||
## 8.2 审计字段要求
|
||
|
||
登录与找回相关操作至少记录：
|
||
- tenant_schema
|
||
- username（或脱敏标识）
|
||
- ip / user_agent
|
||
- result_code
|
||
- created_at
|
||
|
||
---
|
||
|
||
## 九、异步任务与缓存策略
|
||
|
||
## 9.1 Celery 任务
|
||
|
||
| 任务 | 触发时机 | 说明 |
|
||
|---|---|---|
|
||
| `account_send_recover_message_task` | 找回请求成功后 | 异步发送邮件/短信 |
|
||
| `account_security_digest_task` | 定时任务 | 汇总锁定、失败、异常登录统计 |
|
||
|
||
## 9.2 Redis Key 规范
|
||
|
||
| Key | TTL | 说明 |
|
||
|---|---|---|
|
||
| `{schema}:account:captcha:{challenge_id}` | 180s | 验证码挑战态 |
|
||
| `{schema}:account:captcha:pass:{token}` | 180s | 验证通过一次性票据 |
|
||
| `{schema}:account:login_fail:{username}` | 1800s | 登录失败计数 |
|
||
| `{schema}:account:recover:rate:{username}` | 3600s | 找回频控 |
|
||
|
||
---
|
||
|
||
## 十、性能与可靠性约束
|
||
|
||
- 登录链路接口目标：`p95 < 300ms`（不含外部消息发送）
|
||
- 找回请求接口目标：`p95 < 400ms`（消息发送异步化）
|
||
- 缓存故障时系统应降级到 DB 校验，但保留频控硬兜底
|
||
- 验证码组件不可用时，应返回明确错误并禁止跳过登录防护
|
||
|
||
---
|
||
|
||
## 十一、安全与合规
|
||
|
||
1. 密码仅允许 Django 安全哈希（PBKDF2 / Argon2）。
|
||
2. 连续失败 N 次锁定（建议 5 次，30 分钟）。
|
||
3. 重置令牌一次性使用，过期失效，不可复用。
|
||
4. 登出必须销毁会话，旧页面刷新需重定向登录。
|
||
5. 敏感字段仅脱敏返回，禁止明文日志输出。
|
||
|
||
---
|
||
|
||
## 十二、错误码建议
|
||
|
||
| code | HTTP | 场景 |
|
||
|---|---|---|
|
||
| `ACCOUNT_TENANT_INVALID` | 400 | tenant 无效或停用 |
|
||
| `ACCOUNT_CAPTCHA_INVALID` | 400 | 验证码失败/过期 |
|
||
| `ACCOUNT_LOGIN_INVALID_CREDENTIAL` | 401 | 账号或密码错误 |
|
||
| `ACCOUNT_LOCKED` | 423 | 账号锁定中 |
|
||
| `ACCOUNT_PASSWORD_WEAK` | 400 | 新密码不满足复杂度 |
|
||
| `ACCOUNT_RESET_TOKEN_INVALID` | 400 | 重置令牌无效/已使用 |
|
||
|
||
---
|
||
|
||
## 十三、测试映射（P0）
|
||
|
||
| 场景 | 最低覆盖 |
|
||
|---|---|
|
||
| Tenant 校验 | 有效/无效/停用租户 |
|
||
| 登录链路 | 验证码通过、失败锁定、解锁后登录 |
|
||
| 找回流程 | 频控、令牌一次性、过期处理 |
|
||
| 首登改密 | 未改密不可进入业务页 |
|
||
| 登出 | 会话销毁、回退重定向 |
|
||
|
||
测试文件：`tests/integration/account/test_us_account.py`
|
||
|
||
---
|
||
|
||
## 十四、落地顺序建议
|
||
|
||
1. 先实现 tenant 校验 + 登录主链路
|
||
2. 再接验证码 + 失败锁定
|
||
3. 再实现找回用户名/密码
|
||
4. 最后补安全摘要任务与审计报表
|
||
|
||
---
|
||
|
||
## 十五、文档同步规则
|
||
|
||
- 登录数据结构调整：同步 `DATA_MODEL_LOGIN.md`
|
||
- 安全策略或门禁调整：同步 `权限管理系统技术方案.md`
|
||
- API 变更：同步本文件与登录 PRD 验收条目
|