# Renderer 职责与开发路径 ## 阅读顺序 `main.ts` 注册 Vue、Pinia、路由与 i18n。`App.vue` 协调应用初始化及清理。`app/AppShell.vue` 只组合标题栏、导航与独立滚动区域;`app/useAppearance.ts` 将配置状态应用到 DOM 和 i18n。 `app/info.ts` 缓存一次 app.info 查询,并合并并发请求。主进程返回注册窗口的真实 role;路由守卫据此限定次级窗口可显示的页面。它改善界面行为,最终授权仍在主进程 procedure。 `pages` 是页面布局;`features/<功能>` 包含功能 composable 与面板;`features/preferences/store.ts` 拥有跨窗口共享配置和订阅,不操作 DOM。`i18n/locales` 是字典,`i18n/index.ts` 只初始化。 ## 添加功能 1. 在主进程模块定义一次 tRPC procedure,声明角色、输入和输出。共享模型才放 contracts。 2. 在 renderer/features/<功能>/use<功能>.ts 直接调用唯一客户端 lib/trpc.ts,管理状态和资源。 3. 在同目录的组件展示功能,在 pages 中组合;路由使用懒加载。 4. 可跨页面复用的状态才进入 Pinia;不要为一次页面操作建立全局 store。 不增加重复描述每条 API 的 renderer service、repository 或 dispatch 层。客户端类型由主进程 AppRouter 的 type-only 导入推导。可测试的功能 composable 接收可选客户端参数,无需新增第二套接口。 ## 生命周期规则 - useTask 管理忙碌状态、操作反馈与作用域 AbortSignal;读取请求传入 signal。离开作用域后忽略反馈,功能自己的异步状态提交也必须检查 isActive。 - 各功能独立拥有任务状态,避免整页互相禁用。成功前不自动重试有副作用的操作。 - 配置和更新通过 useSnapshotStream 管理订阅、快照与会话。先等订阅启动,再读取快照;事件优先于较旧响应。断开后显式重连,先清理旧会话。不要再分别实现同样的初始化竞争处理。 - 文件对话框返回后立即追踪授权,离开页面或读取失败时释放;目录刷新使用代次和 token 检查,避免旧请求覆盖新结果。 - 保存文件在确认前固定 token 和内容,并在确认后再次检查页面及选中项。凭证输入提交后立即清空,退出时也清空。 - 卸载无法撤销已经交给主进程的写入,因此只忽略迟到的 UI 结果。传输取消不是业务事务回滚。 ## 滚动与样式 UI 组件中没有 tRPC 或业务状态。UiScrollArea 封装可聚焦、具名的原生滚动区域;不管理滚动业务。聊天或虚拟列表若确实需要额外能力,应在自己的功能模块实现。 设计和滚动条取舍见 [DESIGN.md](../DESIGN.md)。使用 token 而不是硬编码新的主题颜色。功能样式采用 scoped;只有布局及共享状态样式放应用全局 CSS。 首次读取与操作忙碌是不同的状态。笔记、草稿和凭据由各自 composable 的 ready 表示已确认数据;读取失败时提供显式重试,草稿未读取成功前禁止保存,避免把未加载的空值写回磁盘。UiButton 的 busy/busyLabel 只负责禁用与呈现执行反馈,翻译和任务仍由功能模块提供。 UiPanel 使用 aria-labelledby 关联自己的标题。默认功能面板不展示持久化实现标记;设置使用最大 640px 的单列布局。更新状态使用语言字典,长内容、键盘焦点和标题栏之外的滚动区域通过真实 Electron 测试验证。 ## ai-friend 滚动条评估依据 检查了原项目的 src/renderer/src/directives/scrollbar/index.ts、composables/useScrollbar.ts、assets/style/\_scrollbar.scss、components/ScrollBox.vue 及 App.vue。主题滑块、透明轨道和独立区域可迁移。当前 directive 默认每个容器持续 requestAnimationFrame 调用 update,并计算嵌套层级及祖先 overflow;轨道使用 1000 起的层级。composable 的 globalDs 未赋值,多实例共享 rafId,也增加了清理复杂度。以上是代码层面的评估,没有把它当作经过 CPU 基准测试的性能结论。 聊天 ScrollBox 的跟随底部与 MutationObserver 是场景行为。本模板没有聊天业务,所以不默认迁移。当前 UiScrollArea 使用原生滚动;如果未来需要虚拟列表或定制轨道,再针对实际需求评估。 ## 超时与重连 IPC 默认 query 15 秒、mutation 120 秒、订阅启动 15 秒;订阅建立后没有空闲超时。可用调用选项 context.timeoutMs 指定等待时长,0 明确表示无限等待。原生对话框、菜单、更新下载及安装使用无限等待,避免把用户思考时间或下载时间误判为失败。 超时会释放客户端监听并发送 request.cancel;业务可能已经完成,因此 mutation 的超时提示明确要求核实后再操作,通信层不会自动重试。请求取消仍校验窗口来源与 owner。主进程任务需要自行响应 procedure signal,取消不是事务回滚。 配置同步失败可使用应用通知中的重试;更新同步失败可使用更新面板的重试。它们只重新订阅并读取状态,不重复之前的写入、下载或安装。文件监听的恢复仍由重新选择目录操作完成,未建立自动恢复全部业务的机制。