移动端代码结构

应用与界面

• lib/main.dart 负责平台启动和应用主题，并保留已有公开入口。
• lib/home_page.dart 负责主页面组合、用户提示、弹窗和页面生命周期。
• home_view.dart 连接组件参数与页面操作；home_library_actions.dart 保留仓库弹窗和加载后的页面效果。
• LoginView 展示登录表单，控制器和登录操作由调用方提供。
• LibraryDrawer 展示本地与远端仓库，使用参数和回调连接仓库操作。
• NoteToolbar 展示紧凑工具栏，通过回调传递模式切换和笔记操作。
• NoteContent 展示编辑或预览内容，复用标签拥有的编辑与滚动控制器。

状态归属与依赖

标签会话

• TabSessionController 拥有标签列表、活动标签、主标签、导航历史及编辑资源。
• note_tab.dart 定义单个标签；note_tab_session.dart 保留会话格式和草稿恢复规则。
• note_tabs.dart 保留标签栏和关闭确认，并重新导出原有模型和恢复接口。
• 会话写入延迟为 300 毫秒；写入在入队时捕获仓库与快照，串行执行。
• 关闭页面前先捕获会话快照，再释放编辑资源；未完成的写入不再通知页面。
• 页面负责关闭确认、导航定位、提示，以及差异视图的切换。

仓库与账号

• RepositoryController 拥有账号会话、本地与远端仓库、当前仓库、文件列表、最近打开、收藏和修改时间。
• 仓库控制器调用已有存储与同步服务，保留会话字段、磁盘格式和远端协议。
• 仓库切换依次等待相关同步、保存旧仓库笔记、保存旧标签会话、加载目标仓库并安装恢复状态。
• 页面接着恢复文件选择器状态、刷新同步状态和差异、启动可选收藏与历史刷新。
• 加载结果校验仓库、账号及生命周期；旧请求不更新新的仓库或账号。

同步协调

• SyncCoordinator 拥有同步状态、准备阶段信号、当前写入仓库信号、自动同步定时器和设置写入队列。
• 页面将前后台状态传给协调器；协调器依赖仓库和标签控制器，不依赖 State、BuildContext 或界面组件。
• 收藏同步、历史时间加载和删除标签后的导航效果通过明确回调连接现有模块。
• 异步工作释放等待信号，即使同步失败也不会阻塞后续仓库切换。
• 页面关闭时先停止同步调度、移除监听，再捕获标签快照和释放编辑资源；已开始的磁盘操作可以完成，但不再刷新界面。

新增功能与维护

MP3 播放服务

• mp3_library.dart 定义目录、曲目、参数和播放边界规则，使用独立 HTTP 客户端连接固定 MP3 服务，不复用笔记同步的认证或路径限制。
• mp3_controller.dart 拥有应用级播放器、媒体会话、目录配置和加载状态；首次打开页面时按需初始化，页面退出不释放服务。
• mp3_audio_handler.dart 中的 Mp3AudioHandler 将耳机、通知栏和锁屏命令转给同一个控制器，使用 just_audio 播放和 audio_session 处理音频中断。
• 按秒跳转在控制器中按需加载相邻曲目时长，逐首传递剩余偏移；中间曲目不播放，最终定位后按原状态恢复，版本标记和暂停意图防止旧跳转覆盖新操作。
• mp3_player_page.dart 负责紧凑布局、参数弹窗及操作结果；mp3_transcript.dart 集中管理正文选择与手势，曲目切换时重置资源。页面不直接持有原生播放资源。
  • 正文通过已有指针监听识别单指横滑，先纵向移动、长按或多指即取消；距离阈值提示使用不拦截触摸的覆盖层，松手后复用目录切曲规则并保留播放状态。原生滚动、选区手柄及复制菜单继续由 Flutter 管理。
• 配置保存在应用文档目录的 mp3-player.json，按目录保存曲目路径、进度与参数；捕获快照后串行临时文件写入和重命名，每 5 秒保存进度。
• 音频加载串行执行，目录、曲目与正文请求使用版本标记；过期结果不能更新当前页面或启动旧曲目，加载期间的暂停取消待启动播放。
• Android 配置媒体前台服务和媒体按键接收，Activity 继承 AudioServiceActivity；iOS 启用后台音频。HTTP 网络例外限定为 MP3 域名。
• 新增原生依赖后须完全重启应用；后台与蓝牙行为需 Android/iOS 真机验收，单元测试不代替平台验证。

录音转写

• voice_transcription.dart 负责系统安全存储中的凭据、豆包 2.0 标准版 HTTP 调用及本机任务记录，不依赖笔记同步认证。
• 任务位于应用文档目录的 voice-transcriptions/，按仓库目录、仓库 ID、附件路径和 SHA-256 摘要生成键；写入先捕获快照，再串行使用临时文件与重命名持久化。
• 请求编号在上传前落盘；响应不明确时保留原编号，查询与重新提交分离，重新提交只由显式操作触发。
• voice_transcription_dialog.dart 拥有当前弹窗的任务、编辑草稿和前台轮询，关闭时保存结果并释放 HTTP 客户端；voice_transcription_settings.dart 负责配置交互。
• voice_transcription_actions.dart 连接已有语音条与主页面，在插入前重新验证标签、仓库、录音摘要及唯一链接，再复用编辑历史与标签会话保存。
• voice_transcription_batch.dart 复用单文件任务，按正文顺序处理当前笔记的录音；主页面通过现有忙碌状态锁定编辑与同步，弹窗显示进度，停止后保留原任务，确认后以一次编辑历史操作插入全部有效结果。
• 录音暂停使用原生录音器的 pause/resume 并暂停计时；附件以录音开始的本机时间命名，冲突后追加数字，最终选定路径在复制前写入恢复记录。
• voice_transcription_test.dart 使用本地 HTTP 服务验证鉴权、任务恢复及超时；voice_transcription_ui_test.dart 验证设置、前后台轮询、结果编辑和横竖屏布局。

维护约定

• 界面组件不读取主页面私有状态；通过参数获取状态，通过回调发起操作。
• 新增标签操作放入标签控制器；仓库与账号数据操作放入仓库控制器；同步调度放入同步协调器。
• 弹窗、提示、焦点和界面导航留在页面及界面组件；现有 part 文件逐步调用控制器，不再增加重复的业务状态。
• 拆分时保留控件尺寸、提示文字、焦点、滚动位置和原有业务时序。
• 按完整职责提取模块，不按某次功能增量创建零散文件。
• 新增或修改代码后运行 flutter analyze 和 flutter test。
• 当前 Windows Gradle 环境存在已确认的 loopback 连接错误；环境未变化时不重复打包。

验证

• 现有布局、标签、导航、草稿恢复、差异和同步测试覆盖功能行为。
• tab_session_controller_test.dart 覆盖延迟写入、失败恢复、仓库快照隔离和资源释放。
• repository_coordination_test.dart 覆盖同步等待与准备阶段、旧草稿保存顺序、旧同步结果与账号列表隔离，以及释放后的异步结果。
• 差异界面和差异算法保持现状，后续按独立职责整理。
• mp3_player_test.dart 覆盖目录解析、播放边界、配置恢复、选中行、加载竞争、维护接口、音频中断、正文手势和横竖屏页面。
• mp3_entry_test.dart 验证未登录、没有笔记库时仍能使用菜单入口。
• mp3_transcript_test.dart 验证播放控制模式下的多指长按、取消条件、复制菜单，以及关闭控制后恢复单指选字；正文仅拦截原生单指触摸，继续复用 Flutter 选区手柄与工具栏。
• mp3_seek_test.dart 验证跨曲前进/回退、连续跨曲、列表边界、时长异常，以及加载期间暂停和新操作的竞争。