本文档面向接下来参与 Luotopia 共同开发的贡献者，欢迎大家直接选择自己心怡的模块直接开始开发！
Caution
开发前请一定、务必阅读 README 的开发规约部分。由于开发规约追加更新频繁，请时常查阅以免遗漏。
后端
cd D:\Github\Luotopia\Luotopia\Luotopia-server
# 日常开发：Docker 只启动依赖服务，本机运行迁移和 API；该命令会复用已有 Postgres 数据卷
docker compose -f docker-compose.dev.yml up -d && go run ./cmd/migrate && go run ./cmd/server完整容器化联调或更新服务镜像：
cd D:\Github\Luotopia\Luotopia\Luotopia-server
docker compose -f docker-compose.dev.yml --profile app up -d --build# 1) 停止服务但保留 Postgres 数据卷
cd /home/projects/Luotopia/Luotopia-server
docker compose -f docker-compose.dev.yml --profile app down --remove-orphans
# 2) 拉取并使用开发态运行（2个 Docker 依赖 + 本机 Go 服务）
cd /home/projects/Luotopia
git pull
cd Luotopia-server
docker compose -f docker-compose.dev.yml up -d postgres redis && go run ./cmd/migrate && go run ./cmd/server
# 3) 拉取并使用打包部署态运行（重建服务镜像，保留数据库数据）
cd /home/projects/Luotopia
git pull
cd Luotopia-server
docker compose -f docker-compose.dev.yml --profile app up -d --build --force-recreate更新服务时不要执行 docker compose -f docker-compose.dev.yml down -v、docker volume rm 或 docker system prune --volumes。Postgres 用户数据保存在 Compose 命名卷 luotopia-postgres-data 中，up -d --build 会重建应用镜像并保留该数据卷。
开发时请遵循现有项目结构：页面型功能放在 lib/features/pages/，可复用组件型能力放在 lib/features/components/，跨模块通用实体、仓储接口和值对象放在 lib/shared/，主题、路由、本地化、时间等基础设施放在 lib/core/。
就校园页子应用页面来说，其代码应放在 lib/features/pages/campus/sub_apps/ 下。sub_apps/ 的每个一级代码目录必须与某个实际子应用一一对应，辅助代码应放在所属子应用。具体规则见 校园页子应用架构指南。
Flutter 客户端页面路由必须按业务归属建模，而不是按入口来源建模。校园页子应用应挂在 /campus/...，设置页只挂真正的设置项，共享账户和认证流程统一挂在 /account/...。例如校园子页面需要武大认证时，应打开 /account/whu，不要跳到 /settings/... 下的登录页。
功能页面不要直接依赖 go_router，也不要直接调用 context.push 或 context.go。普通二级流程使用 AppNavigatorX.openSecondary，弹出式全屏流程使用 AppNavigatorX.openModal，主分支切换才使用 AppNavigatorX.goPrimary。返回页面或关闭 dialog、sheet、webview 时可以使用 Navigator.of(context).pop/maybePop。
新增路由时应先在 AppRoutePaths 中定义常量，再在 app_router.dart 中挂到对应业务域。除非已明确做兼容迁移方案，否则不要为同一个页面保留新旧两套路由。
涉及武汉大学教务系统的能力请使用 whu_auth模块提供的接口，无需自行实现令牌获取、持久化等功能，可以参考 校园页教务认证开发指南
whu_auth 模块使用时如有力所不能及之处请提 issue 我们更新解决之。
新增或迁移 WebView 页面时请使用 Webview 统一创建器（ app_web_view_page.dart 中的 AppWebViewPage ）。
统一创建器负责： WebViewController 的创建或复制加载层、错误层、返回、刷新逻辑。
属于业务页面负责：认证检查、CAS Cookie 准备、Header 规则、导航拦截、 JS Bridge。通过 AppWebViewPage 提供的回调接入。
详细接入方式见 WebView 页面调用规范。
本仓库中的 UI 开发请使用 shadcn_flutter 组件库或与之风格相同的自建组件，以使全局风格统一。
自建组件请从页面中独立出来以便复用。
待开发模块分客户端功能和服务端协同功能，前者可以直接在本仓库开发完了，后者需要一并认领Luotopia-Server仓库里的对应issue一并开发完成之。
待开发模块目录：
复杂度：低
目的是用符合交互逻辑的简洁直观 UI 使用户能便捷了解/查询/决策全校全校区空闲教室相关信息。
模块需求：
- 支持按日期、校区、教学楼、节次查询空闲教室。
- 展示教室名称、容量、楼栋、可用节次等信息。
- 支持加载、空结果、授权失败、接口异常、解析失败状态。
- 缺省查询条件尽量保持轻量。
- 支持直接把选定的空间教室的自习工作直接加入日程。
要求设计交互逻辑合理简洁。
复杂度：低
此功能依赖于全校课表功能的开发。
模块需求：
- 基于用户当前空闲时间、本地课程表和全校课表数据生成可蹭课程候选。
- 支持按当前时间、校区/地点距离、课程热度、教师、课程类型筛选。
- 候选结果能查看课程详情，并可加入本地日程。
- 有推荐时将结果推送至校园页主页
复杂度：中
要求与 lib.whu 建立稳定的交互方式，使用户可以在应用页面里完成图书馆相关操作。
模块需求：
- 接入图书馆馆藏查询系统。
- 展示当前借阅、到期时间、续借状态、馆藏位置。
- 支持续借、借阅历史、到期提醒。
- 到期提醒应接入系统通知模块，而不是只在校园页展示静态提示。
复杂度：低
模块需求：
- 支持查询可预约空间、日期、时间段和座位。
- 支持创建预约、取消预约、查看我的预约。
- 预约成功后可选择写入本地事项，并可设置提醒。
- 使用合理的 UI 和交互逻辑设计。
复杂度：低
模块需求：
- 支持查询场馆、项目、日期、时段和可预约状态。
- 支持预约、取消预约、查看我的预约。
- 预约记录可同步为本地日程事项。
- 使用合理的 UI 和交互逻辑设计。
复杂度：低
直接放俩 webview 在那儿就行。注意用正确的用户令牌权限传入方式。
复杂度：低
成绩页可扩展为更完整的绩点/综测分析模块。
目前的问题主要是 UI 交互逻辑不太合理，并且功能也太少，允许并鼓励开发者重新设计一套 view 。 注意调研武大实际总绩点与综测计算规则。
模块需求：
- 支持总成绩、绩点、学分统计、挂科/重修标识、课程类别筛选。
- 支持历年成绩趋势和学期对比。
- 支持导出或复制成绩摘要，但不要默认上传到服务端。
- 与课程给分模块关联时，只传递必要课程标识，不上传用户个人成绩。
以下功能需要 Luotopia 账号或服务端接口协同。当前 Luotopia 登录注册已有客户端页面和本地 token 缓存，但 LuotopiaAuthRepository.baseUrl 仍是 http://10.0.2.2:8080，生产环境配置和服务端能力需要继续完善。
复杂度：〇
模块需求：
- 将服务端地址从硬编码本地模拟器地址改为可配置的环境配置。
- 明确开发、测试、生产环境的 API baseUrl 管理方式。
- 统一处理 token 过期、刷新、退出登录、服务端错误码。
- 为需要登录的模块提供统一的授权请求封装。
验收标准：
- token 失效后用户能重新登录，业务页不会无限失败。
- 论坛、课程评价、学习资料共享等模块可复用同一认证能力。
复杂度：中
全校课表更新频率低，爬取逻辑复杂，适合放在服务端。 客户端每次打开全校课表应用时比对当前本地缓存，落后时从服务器更新新表，在本地持久化保存。
客户端重点在于性能优化，以及向用户公开丰富且合理的查询、筛选参数。 相关功能参考“https://jwgl.whu.edu.cn/design/viewFunc_cxDesignFuncPageIndex.html?gnmkdm=N214599&layout=default”
复杂度：高 ——讨论后开发
复杂度：低
校园页顶部天气卡目前使用 mock 数据。要求服务端接入天气接口，客户端按需请求服务器显示实时天气。
模块需求：
- 服务端代理天气接口，避免客户端暴露第三方天气 API Key。
- 客户端展示实时天气、体感温度、最高/最低温、空气质量、逐小时预报。
- 默认位置为武汉大学，可扩展用户当前位置。
- 天气功能对所有用户开放，未登录状态也应通过公开统一拉取获取天气。
- 支持缓存最近一次成功数据，接口失败时展示缓存时间和重试入口；首次无缓存时可显示 mock 数据，并在更新时间位置明确标注待更新。
复杂度：低
设置页顶部头图应作为服务端驱动内容，不受用户本地壁纸配置控制。当前设置页头图复用了应用内壁纸能力，后续应改为从 Luotopia Server 获取当前头图信息，客户端及时更新并缓存显示。
模块需求：
- 服务端提供当前设置页头图信息，包括图片地址、更新时间、来源说明等必要元数据。
- 客户端从 Luotopia Server 拉取头图，不在客户端暴露第三方图片 API Key 或服务端内部来源。
- 客户端缓存最近一次成功图片，接口失败时继续展示缓存图片，并能记录或展示缓存更新时间。
- 首次无缓存且请求失败时展示明确降级背景，不影响设置页账号与功能入口使用。
- 设置页头图与用户自定义壁纸中心解耦，避免用户修改主页/列表壁纸时影响设置页品牌视觉。
验收标准：
- 设置页头图能从服务端获取并显示。
- 服务端更新头图后，客户端能在合理时机刷新本地缓存。
- 离线或接口失败时能显示最近一次成功缓存。
- 无缓存失败态不遮挡设置页主要内容。
复杂度：高
校园页已有“课程给分”入口，课程详情页也有静态给分展示，但没有真实数据和服务端接口。
模块需求：
- 按课程维度展示给分统计：总评、平时、期末、成绩分布、样本数。
- 支持按教师、学期、课程性质筛选。
- 支持用户匿名提交自己的给分数据。
- 服务端聚合数据，客户端只展示聚合结果，避免暴露个人成绩。
- 与本地课程事项、全校课表结果建立课程标识映射。
验收标准：
- 从校园页或课程详情页进入都能看到同一课程的真实给分统计。
- 样本数不足时明确提示，不显示误导性统计。
- 登录用户提交后能看到状态反馈，重复提交策略明确。
复杂度：高
校园页已有“课程评价”入口，课程详情页有静态评价卡片。需要接入真实课程评价社区功能。
模块需求：
- 展示课程评分、评价列表、评价标签、教师维度信息。
- 登录用户可匿名发布评价、编辑或删除自己的评价。
- 支持点赞、举报、排序和分页。
- 服务端需要审核/风控能力，客户端展示待审核、已隐藏等状态。
- 兼容原 whu.sb 的数据迁移或导入策略，如果服务端提供历史数据。
验收标准：
- 课程详情页不再展示静态 mock 评价。
- 用户能查看真实评价并提交新评价。
- 被举报或审核中的内容有明确展示规则。
复杂度：中
需与 Openwhu 等友社组织讨论后确认接入方式。
校园页已有“学习资料共享”入口，当前无页面和服务端接口。
模块需求：
- 按课程、教师、学期、资料类型检索资料。
- 支持上传资料、下载资料、收藏资料。
- 上传需要 Luotopia 登录，并记录审核状态。
- 资料需支持基础元数据：标题、课程、教师、描述、文件类型、大小、上传者匿名信息。
- 服务端负责文件存储、访问控制、审核和滥用处理。
验收标准：
- 用户能按课程搜索并下载资料。
- 登录用户能上传资料并看到审核状态。
- 无资料、上传失败、文件过大、无权限等状态都有明确提示。
复杂度：中
项目已有 features/components/wallpaper/、Bing 每日图获取缓存能力和 AppWallpaperBackground，但还没有完整的壁纸配置中心。后续应把壁纸能力正式做成用户可控制的应用背景系统。
模块需求：
- 支持用户选择“不设壁纸”、本地图片、Bing 每日图作为壁纸来源；缺省值为“不设壁纸”。
- 本地图片和 Bing 图片地位等同，用户选哪个就使用哪个，不要默认强行显示在线壁纸。
- 支持主页表格页配置背景图像，并保证表格、事项块、文字在浅色/深色图片上仍可读。
- 支持任务列表页按分列表分别配置壁纸，至少覆盖“我的一天”“全部事项”“任务”“日程”“备忘”这些现有列表。
- 复用并扩展现有
components/wallpaper能力，不要另起一套壁纸下载、缓存和展示系统。 - 支持图片缓存、图片读取失败、在线来源失败、无壁纸等状态的明确降级。
验收标准：
- 用户可以在设置或列表设置入口选择壁纸来源。
- 不设壁纸时，主页和列表页保持原有清爽背景，不请求不必要的在线壁纸。
- 本地图片和 Bing 图片都能作为主页背景使用。
- 列表页不同分列表可以显示不同壁纸配置。
- 壁纸加载失败时页面仍可正常使用，不出现空白或遮挡主要内容。
复杂度：〇
事项编辑器已经支持保存提醒选项，详情页也能展示提醒字段，但应用还没有真正调度系统通知。
模块需求：
- 为任务、日程、备忘建立通知调度服务。
- 根据
ReminderOption计算通知触发时间，支持准时、提前 5 分钟、提前 15 分钟、提前 1 小时、提前 1 天。 - 创建、编辑、删除事项时同步创建、更新、取消通知。
- 应用启动时校准未来通知，避免本地数据和系统通知状态不一致。
- Android 端处理通知权限申请、通知渠道、点击通知打开事项详情。
验收标准：
- 创建带提醒的事项后，系统能在正确时间发出通知。
- 修改事项时间或提醒策略后，旧通知不会继续触发。
- 删除事项后，对应通知被取消。
复杂度：〇
事项编辑器已有重复规则选择，RepeatSettingsPage 仍提示“复杂重复规则后续继续扩展”。当前重复规则还没有完整的事项实例展开、完成态处理和日历展示闭环。
模块需求：
- 明确重复事项的数据模型：保存原始事项和重复规则，按视图范围展开实例。
- 支持每天、工作日、每周、每月、每年这些现有
RepeatRule。 - 主页、列表页、AI 查询、详情页都能识别重复实例。
- 支持单次完成、恢复完成、删除整组重复事项的最小闭环。
- 后续复杂规则可扩展自定义间隔、结束日期、指定星期等，但第一阶段不要引入过度复杂模型。
验收标准：
- 创建每周重复事项后，主页切换到后续周能看到对应实例。
- 列表页“我的一天”能显示当天重复实例。
- 完成当天实例不应错误地完成所有未来实例，除非明确选择整组操作。
复杂度：〇
AI 页已支持 OpenAI-compatible 接口、流式回复、事项草稿生成和会话列表，但 AI 会话虽然写入了 SharedPreferences，启动阶段还没有把 ai.sessions 和 ai.activeSessionId 恢复到 aiChatBootstrapSessionStoreProvider。
模块需求：
- 在启动加载阶段读取 AI 会话列表和当前会话 ID。
- 会话列表支持删除会话、重命名会话、清空历史。
- 当前会话被删除时自动选择最近会话，没有会话时创建空会话。
- AI 返回解析失败时保留用户输入和错误信息，方便重试。
- 不把 API Key、系统提示词或隐私数据写进聊天消息明文以外的调试输出。
验收标准：
- 重启应用后能看到历史 AI 会话。
- 删除当前会话不会导致 AI 页空指针或无法发送。
- 未配置 AI 时继续显示设置引导，不阻塞其它页面。
复杂度：〇
设置首页 Lorem Ipsum部分将是友情链接的地方
复杂度：〇
项目已有部分 Android 小组件布局、刷新 worker 和同步服务。要求在现有能力基础上改善、新增 Android 桌面小组件，并为 iOS、macOS、Windows、Linux 等其它系统补齐各自平台可行的桌面小组件或等价入口。
模块需求：
- Android 侧继续完善现有小组件：点击事项进入事项详情，点击新增进入事项编辑页。
- Android 侧新增更多尺寸和形态的小组件，如今日事项、课程方格、周课程、快速创建、倒计时/即将开始事项等。
- 根据设置同步语言、主题和刷新频率，支持深色模式与系统动态色的合理适配。
- 支持课程方格、日程列表、快速创建等不同小组件的数据边界，当本地事项为空、数据过期或同步关闭时展示明确状态。
- 调研并实现其它系统桌面小组件或等价能力：
- iOS / iPadOS：WidgetKit 小组件，优先支持今日事项、课程表、快速查看。
- macOS：优先复用 WidgetKit 或提供菜单栏/通知中心入口。
- Windows：调研 Windows Widgets、托盘/开始菜单磁贴等可行入口，无法原生支持时给出替代方案。
- Linux：调研桌面环境差异，优先提供托盘、通知或可嵌入面板的轻量入口。
- 各平台实现应共享同一份事项快照语义，避免每个平台各自重新定义数据结构。
验收标准：
- Android 小组件能稳定显示当前事项数据，应用内增删改事项后能及时刷新。
- 新增 Android 小组件至少覆盖一个现有小组件没有覆盖的使用场景。
- 至少完成一个非 Android 平台的小组件或等价桌面入口原型，并在文档中说明该平台限制。
- 小组件入口跳转到正确页面，无法深链的系统需要给出明确降级行为。