Files

2026-04-30 18:40:55 +08:00

9.0 KiB

Raw Blame History

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

Fonrey 登录管理技术方案

版本: 4.0
项目: Fonrey 房产经纪管理系统
技术栈: Django 4.x + HTMX + Alpine.js + PostgreSQL 16 + Redis + Celery
关联 PRD: PRD/登录管理/用户登录管理模块PRD.md（v2.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-04-30

一、文档定位与边界

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

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

本文件不展开数据表字段与索引。数据结构以 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 设计原则

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

五、端点清单（对齐 PRD）

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	登出销毁会话

六、关键流程约束

6.1 Tenant 识别

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

6.2 密码登录

请求体（示例）：

{
  "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 正式）