01-guest.md 4.5 KB

用户使用场景 · 游客(Guest / 未登录)

来源:AGENTS.md(统一认证、公开路径)、API_REFERENCE.md(/api/auth/*、/api/articles/* 部分公开、/api/media/upload 公开)、黑盒方案 T-01~T-05。 关联用例:test-cases/guest.md(TC-G-01~TC-G-05)。


场景 G-1:首次打开小程序,看到引流首页

用户故事:作为还没注册的访客,我想一打开就能看到产品价值并找到登录入口,以便我决定是否注册。

  • 角色:游客(无 token)
  • 前置条件:清除本地登录态;小程序启动,wechat.test-mode 可开。
  • 主流程
    1. 冷启动进入 splash / home 引流页。
    2. 页面不自动进入任何业务页(家庭/任务/能量等)。
    3. 明显展示「微信一键登录 / 手机号登录 / 邀请加入」入口。
  • 异常/边界:弱网或微信授权失败时不白屏,提供「稍后」「手机号登录」兜底。
  • 关联需求/设计:JwtInterceptor 拦截 /api/**(仅 8 个公开路径除外);游客不应看到业务数据。
  • 关联用例:TC-G-01

场景 G-2:微信一键登录(默认成为家长)

用户故事:作为新用户,我想用微信一键登录免去注册麻烦,以便快速进入家庭管理。

  • 角色:游客
  • 前置条件:微信授权可用(测试模式走模拟 openid)。
  • 主流程
    1. 点击「微信一键登录」→ 授权昵称/头像。
    2. 调用 POST /api/auth/wechat-login → 返回 Result 含 token + 用户信息。
    3. 角色默认 parent,跳转家长首页。
    4. 若该微信首次登录,自动创建 User + family_members(memberType=login)。
  • 异常/边界:同一微信重复登录应返回已有账号(不重复建号);授权拒绝则停留在登录页。
  • 关联需求/设计:AuthController /api/auth/* 公开;openid 关联 User,决定 memberType。
  • 关联用例:TC-G-02

场景 G-3:手机号 + 验证码登录

用户故事:作为不想用微信的用户,我想用手机号登录,以便也能使用全部功能。

  • 角色:游客
  • 前置条件:有效手机号(如 13800000001)。
  • 主流程
    1. 点击「手机号登录」→ POST /api/auth/send-code 获取验证码。
    2. 输入验证码 → POST /api/auth/phone-login。
    3. 验证码正确 → 登录成功并下发 token;错误 → 提示失败且不产生会话。
  • 异常/边界:验证码错误/过期、频繁发送限流;错误验证码绝不签发 token。
  • 关联用例:TC-G-03

场景 G-4:凭邀请注册并加入指定家庭

用户故事:作为被家人邀请的用户,我想通过邀请码/二维码直接加入家庭,以便立即成为成员。

  • 角色:游客(持有家庭邀请令牌)
  • 前置条件:家长已在 POST /api/family/invite/generate 生成邀请码/二维码(含令牌与落地页)。
  • 主流程
    1. 扫码或点开落地页 → 进入注册/登录。
    2. 走 POST /api/auth/register-with-invite(携带邀请令牌)。
    3. 登录成功后自动归属到对应家庭,家庭成员列表出现该用户。
  • 异常/边界:令牌失效/过期 → 提示「邀请已失效」;已登录用户用他人邀请 → 按业务规则处理(加入或被拒)。
  • 关联需求/设计:FamilyInviteController /api/family/invite/*;二维码含令牌+落地页(cfclub 特性)。
  • 关联用例:TC-G-04

场景 G-5:未登录访问业务页被拦截;浏览商城/文章可被放行

用户故事:作为游客,我想随便看看商品和内容,但访问我的家庭/任务时必须先登录,以便数据安全。

  • 角色:游客(无 token)
  • 前置条件:已知某业务页路由(如 /pages/family/index、/pages/tasks/index)。
  • 主流程
    1. 直接请求带业务路由的页面(无 Authorization)。
    2. JwtInterceptor 返回 401 → 前端跳转登录页;登录后回跳原页。
    3. 打开商城主页 POST /api/product/list、文章列表 POST /api/articles/list → 可见内容(公开路径)。
    4. 点击商品详情/文章详情需登录项 → 被拦截提示登录。
  • 异常/边界:仅 8 个公开路径免鉴权;其余 /api/** 一律拦截;登录态过期后接口统一 401。
  • 关联需求/设计:JWT 认证;Authorization Header;8 个公开路径白名单。
  • 关联用例:TC-G-05