rakullapp_core（Flutter）

目标平台：Web + 桌面 + Android · 直连 user_manager / immersive_study_server / collection_server
rakullapp_core 是系统的视图层。完成初始引导后，MainScreen（lib/app/）直接进入学习主面板（lib/immersive_study/screens/）。学习功能用 user_manager 的 /api/auth/* 登录拿到共享 HS256 JWT，并以 Authorization: Bearer <jwt> 附加到每个请求。

​
直连三个服务

客户端只直连三个面向客户端的服务，绝不直接访问内部的 agent_server / data_server：
关注点服务--dart-define默认
鉴权 / 管理 / 用量user_managerUSER_MANAGER_API_BASEhttp://localhost:8010
全部学习 /api/*（控制器）immersive_study_serverSTUDY_API_BASEhttp://localhost:8012
收藏 /v1/collections/*collection_serverCOLLECTION_API_BASEhttp://localhost:8013
flutter run -d chrome \
  --dart-define=USER_MANAGER_API_BASE=http://localhost:8010 \
  --dart-define=STUDY_API_BASE=http://localhost:8012 \
  --dart-define=COLLECTION_API_BASE=http://localhost:8013

​
目录结构（按服务组件划分）

lib/ 按后端服务组件组织：每个顶层目录对应客户端直连的一个服务，外加 shared/（跨领域基础设施）与 app/（导航外壳）。新同学可以在一个目录里找到某个功能的全部代码（API 客户端 / 模型 / 页面 / 组件 / 状态），无需在 api/、models/、screens/、widgets/ 之间来回跳转。
模块对应服务端口职责
lib/user_manager/user_manager:8010鉴权（Supabase OAuth + 本地）、管理后台、注册、用量
lib/immersive_study/immersive_study_server:8012全部学习 /api/*：文章、阅读器、句子、任务、反馈
lib/collection/collection_server:8013收藏与条目
lib/shared/（跨领域）-HTTP 内核、JWT 存储、配置、i18n、黑白主题、通用组件
lib/app/（导航外壳）-引导、欢迎页与组合各功能的主面板
模块依赖方向：shared/ 不依赖任何功能模块；功能模块只依赖 shared/；app/ 在顶层组合各功能（其中 immersive_study 与 collection 互有少量耦合——阅读时收藏 / 从收藏打开文章）。 导入约定：跨目录用 package:rakullapp_core/<模块>/...，同目录用相对导入。完整模块指南见仓库内 rakullapp_core/ARCHITECTURE.md。

​
多语言（i18n）

界面文案集中在 lib/shared/i18n/，与业务代码解耦：
  • AppStrings（app_strings.dart）是所有可翻译文案的抽象契约；每种语言提供一份实现（strings_en.dart / strings_zh.dart / strings_zh_hant.dart / strings_ja.dart），由编译器保证每种语言都实现了全部 key。
  • AppLocale（app_locale.dart）是语言注册表：code + nativeName + toLocale()。简体与繁体共用 zh 语言码，靠 script（Hant）或地区（TW/HK/MO）区分。
  • LocaleController + LocaleScope 持有当前语言并用 SharedPreferences 持久化；首次启动按「已保存 → 设备语言 → 英文」回退。
  • 语言切换器（language_switcher.dart）固定在每个 Web 页面右上角，列出 AppLocale.supported，点击即时切换。
当前支持：English · 简体中文 · 繁體中文 · 日本語（仅界面文案；正文翻译 / 语法讲解仍由后端按既有语言生成）。
新增一种语言：在 AppLocale 加一项、实现一份 AppStrings、在 AppLocalizations 注册即可——切换器、supportedLocales 与持久化都会自动生效。

​
阅读器的模块

阅读器里点一个句子会打开一个模块化底部面板：Source（原文）/ Translation（翻译）/ Grammar（语法讲解）/ Vocal（朗读）/ Collection（收藏）/ ChatBot（占位）。Owner 与 root 还能在文章上做编辑、重解析、切换可见性、删除等操作。

​
黑白主题（要求 7）

应用使用单色 ColorScheme（lib/shared/theme/app_colors.dart + main.dart）：以黑白为主色，配中性灰阶（grey50..grey900），没有任何品牌色/亮色；状态只用图标 + 灰阶表达。app_colors_test.dart 会断言整套调色板保持灰阶（R=G=B）。

​
SSE 在 Web 上的行为

SSE 增量进度依赖流式 HTTP 响应，在移动端/桌面端可逐条更新；在 Web（BrowserClient）上，最终事件会在请求完成时一次性送达。

​
测试

flutter pub get
dart fix --apply      # 可选：自动修 const/风格 lint
flutter analyze
flutter test
测试使用 http 的 MockClient（不依赖真实后端）：URL/鉴权头拼装、SSE 行解析、JWT 角色解析、模型解码，以及一个文章列表 widget 测试。