校园页教务认证开发指南
接入 whu_auth、查询型与交互型校园应用
面向开发校园页次级应用的贡献者：如何接入武汉大学统一身份认证（CAS）与教务系统授权。
基本结构
项目采用轻量 MVVM + feature-first 结构。
- 校园页应用：
lib/features/pages/campus/ - 武大认证：
lib/features/whu_auth/ - 可复用能力（如课程导入）：放在对应子应用内（课程导入已迁至
sub_apps/timetable/course_import/）
依赖方向：页面与 ViewModel 负责交互与状态；domain 负责模型与规则；data 负责请求、解析与外部服务对接。
教务认证复用方式
新应用不需要自己处理 CAS Cookie，也不应复制 WebView 登录、Cookie 读取、重定向和会话维护逻辑。这些由 whu_auth 封装。
需要理解三点：
- 用户在「武大账户」页通过内嵌 WebView 登录统一身份认证。
- 登录成功后，应用保存统一身份认证 Cookie，并可换取教务系统会话。
- 校园应用在请求教务接口前，通过认证网关获取已授权的教务会话，使用完必须关闭。
页面层先判断是否已认证。未认证时展示登录引导（指向武大账户页）；已认证后再请求教务。data 层服务只接收已授权会话并请求接口，不直接依赖页面上下文。
查询型应用
只从云端单向获取信息，必要时持久化到本地；不向云端提交会改变远端状态的业务写操作。成绩、课程表属于此类。
- 成绩：宫格进入成绩页 → 检查武大认证 → 获取教务会话 → 成绩服务请求接口 → 解析为页面模型。
- 课程表：同样获取会话并请求个人课表，再转换为本地课表与课程事项，供主页、列表等复用；不改变教务远端数据。
开发重点是把云端数据稳定转为本应用模型：
- 校园页只负责入口和跳转
- 页面负责未登录、加载中、错误、空数据、成功展示
- data service 负责访问教务接口并解析原始返回
- 仅本页使用的模型可留在子应用内；跨模块复用则放入
shared - 页面不直接拼复杂请求，也不直接解析教务原始返回
空闲教室、全校课表、学习资料列表等只要不提交远端业务变更，优先按查询型设计。
交互型应用
会与云端发生双向业务交互（预约、续借、取消、确认、支付等）。自习预约、运动场馆、E 卡付款码等应按交互型设计。图书借阅（sub_apps/library）已落地，可按交互型补齐续借等远端状态变更。
除展示结果外，还要把远端状态变化当作核心业务：
- 页面清楚展示当前远端状态，以及操作后果
- 预约、取消、续借、支付等提交前应有确认或清晰操作语义
- data service 将「查询状态」与「提交动作」分成清晰方法
- 提交完成后重新拉取远端状态，避免只依赖本地乐观状态
- 失败时保留可理解原因，允许重试或回到安全状态
- 防重复提交：按钮禁用、加载态
- 未确认远端成功时，不要把本地状态永久写成成功
ViewModel 至少区分：初始加载、可操作、提交中、提交成功后刷新、提交失败、认证失效。
新校园应用开发顺序
- 确认是否需要武大统一身份认证或教务授权
- 在校园宫格增加入口，并注册路由
- 设计最小 domain model
- 需要教务时新增独立 data service
- 页面或 ViewModel 经认证网关获取会话，再调用 data service
- 处理未登录、加载中、空数据、错误、成功
- 需跨模块时再写入
shared
不要把认证、请求、解析和业务转换全部堆在页面里。
错误处理
至少覆盖：
- 尚未登录统一身份认证
- CAS Cookie 过期，教务授权失败
- 教务接口非成功状态
- 返回登录页、异常页或非预期格式
- 字段变化导致解析失败
错误信息面向用户：未登录引导登录；授权失败提示重新登录或重试；接口失败说明请求失败；解析失败说明返回格式异常。不要静默吞错，不要在日志或界面暴露 Cookie 等敏感信息。
协作约定
新增前检查 whu_auth、现有子应用 data、课程导入等是否可复用。认证与教务会话必须复用现有封装。
完整闭环：入口、路由、页面、数据服务、模型与错误状态一起完成。仅占位时可写「功能开发中」；接入真实服务后应补齐状态与数据边界。
提交前自查：是否遵守 MVVM，是否复用认证网关，是否关闭教务会话，是否泄露敏感信息，是否将业务与令牌认证充分解耦。