chore: establish local platform baseline

docs/web-authentication-session.md

@@ -0,0 +1,56 @@
+# Web登录会话与失效恢复说明
+
+## 1. 登录边界
+
+Web端使用OIDC授权码加PKCE完成登录，OIDC提供方只证明外部身份。浏览器取得短期访问令牌后调用`GET /api/v1/me`，由云端根据`issuer + subject`解析当前有效的平台账号、客户组织、家庭成员关系、运营角色和能力。业务工作台只在OIDC用户与云端账号映射同时有效时挂载，不依据浏览器保存的角色或客户组织自行放行。
+
+OIDC客户端把当前用户状态保存在`sessionStorage`，关闭当前浏览器会话后不继续复用；启用自动静默续期，并在访问令牌到期前60秒发起续期。业务接口只通过`Authorization: Bearer`发送访问令牌，页面和业务状态不持久化令牌正文。
+
+## 2. 首次登录和回调
+
+1. 用户点击“登录研发环境”，浏览器跳转OIDC提供方；
+2. OIDC提供方完成账号验证和PKCE交换后返回`/auth/callback`；
+3. Web客户端只处理一次回调，并从OIDC事务状态恢复登录前的站内相对地址；无合法返回地址时回到`/`，同时拒绝协议相对地址、跨源地址和回调页自身，避免重复交换授权码和开放重定向；
+4. 客户端调用`/api/v1/me`取得服务端权限事实；
+5. 只有两层状态均成功时才展示家庭业务和当前账号允许的运营工作台。
+
+回调失败、网络错误或云端账号映射失败时停留在身份区，不挂载业务工作台。若OIDC用户仍有效，页面允许重新读取云端账号；用户也可以重新发起认证。
+
+## 3. 业务接口返回401
+
+所有带令牌的API请求统一处理HTTP 401。任何家庭或运营接口返回401时，API客户端触发页面级`platform:authentication-required`事件，而不是只在当前子页面显示局部错误。认证状态管理器对并发401执行合并处理：
+
+1. 清除`sessionStorage`中的旧OIDC用户和访问令牌；
+2. 立即清除云端账号状态，使全部家庭与运营工作台卸载；
+3. React组件卸载时取消仍在执行的业务请求和SSE读取；
+4. 身份区明确显示“登录状态已经失效，请重新登录”；
+5. 用户点击“重新登录”后重新执行OIDC与`/api/v1/me`双重校验，成功后重新挂载业务区。
+
+401表示身份凭据已经失效；权限不足必须由服务端返回403，页面不得把403升级为全局退出。网络超时、503和普通业务冲突也只在对应页面提供恢复，不清除有效登录状态。
+
+## 4. 令牌到期和静默续期失败
+
+OIDC客户端发现已保存用户过期、收到访问令牌到期事件或静默续期失败时，同样删除本地旧用户并进入重新登录状态。不能继续保留顶部“已登录”账号卡片，也不能让已挂载工作台使用旧令牌反复请求。手工退出使用OIDC标准退出跳转，并在用户卸载事件后清空本地状态。
+
+## 5. 工作台导航与恢复
+
+家庭业务使用根地址；运营工作台分别使用`?workspace=config`、`billing`、`alerts`和`diagnostics`。点击工作台入口通过`history.pushState`写入浏览器历史，前进/后退通过`popstate`恢复页面；刷新或直接打开合法地址时，在OIDC身份和云端账号加载完成后恢复目标工作台。
+
+URL只表达界面位置，不授予运营权限。客户端必须等待云端账号解析完成后检查`platform_role`：没有运营权限的账号即使直接输入运营地址，也回到家庭业务并使用`replaceState`清除无权访问或未知的`workspace`值。会话短暂失效时保留合法工作台位置，重新登录并重新取得同等权限后回到原工作台；如果新账号权限不同，则安全回退家庭业务。
+
+页面切换不会把表单正文、密钥引用、访问令牌或客户组织编号写入URL。快速自动检查应按接近人工操作的节奏切换，避免把瞬时超过用户级读取突发值的脚本行为误判为导航故障；真实检查仍要求所有请求不出现429。
+
+## 6. 轻量验证
+
+`test/e2e/visual-authentication-recovery.mjs`使用真实本地OIDC登录，在家庭数据刷新时只注入一次401，验证：
+
+- 身份区显示会话失效和重新登录入口；
+- 家庭工作台立即卸载；
+- 本地OIDC用户条目清零；
+- 未完成业务请求因组件卸载而取消；
+- 重新登录可利用仍有效的OIDC服务端会话恢复账号与业务工作台；
+- 除预期401和请求取消外，不出现失败请求、控制台错误或页面横向溢出。
+
+该检查不修改业务数据，不替代生产OIDC会话时长、MFA、跨设备退出、管理员强制失效和真实反向代理Cookie/安全头验收。
+
+`test/e2e/visual-workspace-navigation.mjs`另验证运行配置和费用额度选择写入URL、刷新恢复、浏览器后退/前进、未知值回退家庭业务，以及直接打开告警工作台地址。`test/e2e/visual-ops-sensitive-access-request.mjs`从未登录的联调诊断深链发起真实OIDC认证，验证回调后仍停留在目标工作台，再执行无提交的申请表单门禁检查。检查要求零429、零控制台错误、零非预期失败请求和零横向溢出。