功能：账号与登录
字数
1577 字
阅读时间
7 分钟
功能简介
账号与登录功能负责在微信小程序中建立、刷新和吊销 MindGuard 用户的安全会话，支持与校园身份绑定、风控验证与跨模块鉴权。该功能与“账号与资料管理”“隐私中心”“我的”Tab 紧密联动，是所有需要用户身份的业务流程的前置条件。
支持的登录方式
1. 微信一键登录
- 入口：登录页面主按钮、全局登录失效弹窗。
- 流程：
wx.login→ 云函数authLogin根据 code 获取 openid/unionid → 查询/创建users记录 → 下发session_token与session_id。 - 成功条件：用户状态为
active/inactive；更新users.last_login_at。 - 失败处理：
E_USER_RESTRICTED：用户被封禁，提示联系辅导员/客服。E_WX_AUTH_DENIED：用户拒绝授权，记录埋点login_result（status=cancelled）。- 网络异常：允许重试，最多 3 次后提示稍后再试。
2. 绑定学号 + 密码（登录后补充身份）
- 触发条件：
users.campus_affiliation缺失或student_binding.status!='verified'。 - 接口：
/api/auth/bind-student（POST），参数student_id、password、consent_scope。 - 验证：调用校内认证网关，成功后写入
users.student_binding（{student_id, verified_at, department}）。 - 风控：失败三次需短信或图形验证码辅助验证；支持“忘记密码”指引到学校自助系统。
- 解除绑定：账号设置页可发起解绑，需再次验证微信密码或短信。
3. 其他补充登录能力（规划）
- 守护人/辅导员以邀请链接进入时，可通过同流程完成微信登录，但需额外确认角色（
users.role）。 - 后续支持企业微信/教职工单点登录，可在
authLogin中拓展凭据解析。
会话策略
- 凭据形式：
- 前端持久化
session_token（headerX-Session-Token）与session_id（用于埋点）。 - 云开发侧依赖 TCB 登录态
_openid作为最终鉴权依据，所有数据库写操作校验_openid。
- 前端持久化
- 有效期：
session_token有效期 7 天，refresh_token有效期 30 天；存储于sessions集合。- 若 5 天内未活跃，
ensureLoggedIn触发静默刷新（调用/api/auth/refresh）。
- 刷新机制：
- 请求返回
401且refresh_token有效时自动调用刷新接口，成功后重放原请求。 - 刷新失败时清除本地凭据并跳转登录页。
- 请求返回
- 登出策略：
- 用户在账号设置点击“退出登录”时调用
/api/auth/logout，服务端将sessions.status置为revoked并清空 refresh token。 - 在设备风险检测、封禁时，后端可批量失效所有活跃会话。
- 用户在账号设置点击“退出登录”时调用
业务流程
- 用户触发登录页或全局鉴权失败弹窗。
- 提交微信登录授权，后端创建/刷新用户记录与
sessions。 - 前端存储 token，触发
getCurrentUser拉取资料，更新“我的”Tab 欢迎卡与隐私中心入口。 - 若需要，展示学号绑定弹窗并完成校内身份补全。
- 后续每次请求前调用
ensureLoggedIn校验 token 有效性，失效时自动刷新或跳转登录页。 - 用户主动退出或账号被封禁时，吊销
sessions并清除本地缓存。
数据交互
- 集合：
users：写入last_login_at、status、student_binding；引用参见《集合-用户.users.md》。sessions：记录session_token、refresh_token、user_id、device_fingerprint等字段，详见新增《集合-登录会话.sessions.md》。
- 接口/服务：
- 云函数
authLogin：校验 code、生成凭据。 - REST
/api/auth/refresh：刷新 session。 - REST
/api/auth/logout：注销。 - REST
/api/auth/bind-student：绑定学号。 services/auth.js：提供getCurrentUser、ensureLoggedIn封装，统一错误处理与重定向。
- 云函数
- 埋点：
pv_login、act_login_wechat、act_login_bind_student、login_result。详见《埋点与数据分析.md》对应更新。
错误码与提示
| 错误码 | 触发场景 | 前端反馈 | 说明 |
|---|---|---|---|
E_AUTH_EXPIRED | session 过期 | 弹出“登录失效，请重新登录” | 调用 refresh 失败 |
E_USER_RESTRICTED | 用户状态 restricted/suspended | 展示封禁说明与申诉渠道 | 不允许继续登录 |
E_CAPTCHA_INVALID | 验证码错误 | 输入框标红 + 错误文本 | 记录失败次数，触发冷却 |
E_STUDENT_BIND_FAIL | 学号认证失败 | 提示校内账号或密码错误 | 累计失败后要求验证码 |
E_DEVICE_RISK | 风控标记 | 要求人工验证/联系客服 | sessions 标记 requires_review |
安全与合规
- 与《色彩系统》“错误提示”策略一致，避免大面积危险色造成二次打击。
- 所有 token 使用 HTTPS 传输，存储在
wx.setStorageSync前加密（可使用 AES 加密后存储）。 sessions集合配置 TTL 索引自动清理过期记录，减少泄露风险。- 登录协议勾选状态同步写入
users.consent_version，与隐私中心一致。 - 支持未成年人监护提醒：若
users.guardian_ids为空且年龄 <18，登录成功后提示补充监护人。
测试与验收联动
- 对应《测试用例.md》新增
LOGIN-*用例，覆盖成功登录、验证码失败、封禁、token 过期重登、学号绑定。 - 回归时需验证登录后“我的”Tab、任务列表等模块可正常读取数据。
- 与上线流程联动：上线前必须完成正式域名、微信开放平台配置，并在体验版自测表中记录登录结果。
埋点与数据联动
- 登录漏斗：
pv_login→act_login_wechat→login_result(status=success)→act_login_bind_student。 - 失败样本分析：
login_result(status=failed)携带error_code，可在数据后台按失败类型统计。 - 会话续期监控：
login_result(status=success, context=refresh)用于衡量 refresh 成功率。
变更记录
- 2024-04-07：新增账号与登录功能文档，定义会话策略、接口联动、测试与埋点要求。
贡献者
Cai Hongyu