proposal: Windup 前端用户模块的产品口径 #157

背景

后端的认证模块已经在 PR #75 落地，实现说明见 #146。它提供八个端点：注册、密码登录、发送验证码、验证码免密登录、刷新令牌、登出、当前用户、修改密码。access token 有效期 15 分钟，refresh token 7 天，验证码 6 位、5 分钟有效、发送冷却 60 秒。敏感接口限流 10 次每分钟每 IP，全局 60 次每分钟每 IP。

有两条规则决定了前端的形态。第一，鉴权中间件的白名单只放行 /auth/* 与文档、健康检查，其余接口一律要求有效的 access token；第二，资源归属从令牌推导，ProjectCreate 不再接受 user_id。也就是说，这个产品的任何一次数据读写都以登录为前提。

前端目前完全没有登录这回事。所有页面直接调接口，没有会话、没有守卫、没有账号入口。PR #142 已经把项目创建入口改成按登录态禁用，但没有任何模块提供登录态。PR #147 提供了一份未接线的会话层实现。

本提案要定的不是「是否需要登录」，那已由后端确定，而是登录这件事在前端呈现成什么样。

需要确定的口径

一、未登录访问者能看到什么

后端的白名单是接口层面的，页面层面的边界由前端决定。三种取法：

1. 全站要求登录，未登录访问任何路径都跳转到登录面板。
2. 首页匿名可见，其余页面要求登录。
3. 首页与快速开始的介绍部分匿名可见，直到用户触发第一次生成才要求登录。

倾向第二种。首页不调用任何接口，把登录墙放在第一屏会让访问者在了解产品之前就被拦住；而 /quick-start 会触发生成任务，第三种取法要在流程中途插入登录，正在填写的内容需要跨登录保存，代价明显高于收益。

二、登录方式与摩擦

后端提供密码登录与验证码免密登录两条路径，且密码登录当前也强制要求邮箱验证码，该设定的合理性正在 #156 讨论。

前端要定的是：两条路径同时呈现，还是以其中一条为主。倾向以验证码免密登录为默认，密码登录作为次要入口。理由是在当前后端设定下，密码登录并不比免密登录更快，却多要求用户记住一个密码。若 #156 的结论是密码登录取消验证码，则默认路径改为密码登录。

三、账号能力边界

本轮账号中心提供：查看邮箱与昵称、修改密码、登出。

不提供修改昵称，因为后端没有对应端点，缺口已记在 #155；不提供修改邮箱、头像、注销账号，这些字段与流程都不在数据模型里。

四、接口缺位期间的界面表现

找回密码的接口尚不存在，缺口记在 #154。在它补齐之前，登录面板保留「忘记密码」的位置并明确说明该功能尚未开放，不做静默隐藏，也不做点击无反应的死链。

同理，昵称在账号中心以只读形式展示，标注暂不可修改。

拆分的实现 issue

提案通过后拆为四条，按顺序推进：

1. 前端认证会话层。用户实体与接口契约、会话三态、令牌持有与静默续期、登出、多标签页同步。不含界面。
2. 登录与注册界面。账号面板、两条登录路径、注册、发码冷却、错误呈现、登录后回跳。
3. 登录态守卫与未登录引导。受保护路由、未登录落点、会话过期处理、顶栏账号态与登出入口。
4. 账号中心。查看资料、修改密码、登出。

第二条必须先于第三条，因为守卫的跳转目标是登录面板。

PR #147 已经提供了第一条所需的实现。它的去留取决于代码评审结果：可用则直接推动合入，需要修改则在该 PR 内提出，若不适合继续则关闭并在新实现中复用其代码，PR 正文注明来源。

明确排除

本提案不涉及后端改动。第三方登录、多因素认证、组织与团队、权限分级、账号注销均不在范围内。项目列表接口仍在查询参数里传 user_id 这一处历史遗留，归入第一条 issue 一并清理。

需要的决策

• 采用哪一种未登录访问口径。
• 登录面板默认呈现哪条路径。
• 是否同意本轮账号中心只做查看、改密码与登出。

关联

• feat: 实现用户认证模块——注册/登录/JWT/验证码/限流 #146 后端认证模块的实现说明
• fix: access token 过期时鉴权中间件返回 500 而非业务码 401 #153 access token 过期时返回 500
• feat: 补齐找回密码接口 #154 找回密码接口缺口
• feat: 补齐昵称修改接口 #155 昵称修改接口缺口
• discuss: 密码登录是否必须附带邮箱验证码 #156 密码登录是否必须附带邮箱验证码
• feat: 统一前端路由、导航与真实依赖装配（Refs #70） #103 前端路由与依赖装配，认证之外的装配仍归该 issue
• feat(auth): add auth session module with user entity and session management #147 未接线的前端会话层实现