tyt-api-nest/docs/auth.md

认证模块说明（src/auth）

1. 目标

• 提供系统管理员创建、院内账号密码登录、B 端小程序手机号登录、C 端小程序手机号登录、/me 身份查询。
• 使用 JWT 做认证，院内账号与家属小程序账号走两套守卫。

2. 核心接口

• POST /auth/system-admin：创建系统管理员（需引导密钥）
• POST /auth/login：院内账号密码登录，后台与小程序均可复用
• POST /auth/login/confirm：院内账号密码多账号确认登录
• POST /auth/miniapp/b/phone-login：B 端小程序手机号登录
• POST /auth/miniapp/b/phone-login/confirm：B 端同手机号多账号确认登录
• POST /auth/miniapp/c/phone-login：C 端小程序手机号登录
• GET /auth/me：返回当前院内登录用户上下文

3. 院内账号密码登录流程

1. 前端提交 phone + password，role 与 hospitalId 都可以选传。
2. 若仅匹配到 1 个院内账号，后端直接返回 JWT。
3. 若匹配到多个院内账号，后端返回 loginTicket + accounts 候选列表。
4. 前端带 loginTicket + userId 调用确认接口获取最终 JWT。

4. 微信小程序登录流程

B 端

1. 前端调用 wx.login 获取 loginCode。
2. 前端调用手机号授权获取 phoneCode。
3. 调用 POST /auth/miniapp/b/phone-login。
4. 若手机号仅命中 1 个院内账号，后端直接返回 JWT。
5. 若命中多个院内账号，后端返回 loginTicket + accounts。
6. 前端带 loginTicket + userId 调用确认接口拿最终 JWT。

C 端

1. 前端同样传 loginCode + phoneCode。
2. 后端先校验该手机号是否已存在于 Patient.phone。
3. 校验通过后创建或绑定 FamilyMiniAppAccount，并返回 C 端 JWT。

5. 鉴权流程

院内账号

1. AccessTokenGuard 从 Authorization 读取 Bearer Token。
2. 校验 JWT 签名、id、iat 等关键载荷字段。
3. 根据 id 回库读取 User 当前角色与组织归属。
4. 校验 iat >= user.tokenValidAfter，保证旧 token 失效。

家属小程序账号

1. FamilyAccessTokenGuard 从 Authorization 读取 Bearer Token。
2. 校验 C 端 token 的 id + type=FAMILY_MINIAPP。
3. 根据 id 回库读取 FamilyMiniAppAccount。
4. 将家属账号上下文注入 request.familyActor。

6. 环境变量

• AUTH_TOKEN_SECRET
• SYSTEM_ADMIN_BOOTSTRAP_KEY
• WECHAT_MINIAPP_APPID
• WECHAT_MINIAPP_SECRET

7. 关键规则

• 后台 Web 与 B 端小程序都可以复用 POST /auth/login 做账号密码登录。
• 密码登录命中多个院内账号时，不再强制前端手填 hospitalId，改为后端返回候选账号供选择。
• B 端小程序登录复用 User 表，继续使用 openId。
• B 端账号未绑定 openId 时，首次小程序登录自动绑定。
• 同一个 openId 可绑定多个院内账号，支持同一微信号切换多角色/多院区账号。
• 若目标院内账号已绑定其他微信号，仍需先在用户管理中清空该账号的 openId 再重新绑定。
• C 端家属账号独立存放在 FamilyMiniAppAccount。
• C 端手机号必须先存在于患者档案，否则拒绝登录。
• serviceUid 仅预留字段，本次不提供绑定接口。