BIPMaterialManager/docs/developer/guides/renderer-development.md

Renderer 开发指南

本文档说明在当前项目里开发 React 渲染层时，推荐的组织方式和常见改动路径。

1. Renderer 结构

graph TD
    App[App.tsx]
    Pages[pages/]
    Components[components/]
    Hooks[hooks/]
    Stores[stores/]
    Lib[lib/]

    App --> Pages
    Pages --> Components
    Pages --> Hooks
    Hooks --> Stores
    Hooks --> Lib

2. 开发原则

当前 renderer 层推荐遵循这些边界：

• 页面组件优先作为组装层
• 复杂流程优先下沉到 hook
• 纯逻辑优先抽到 helper / lib
• 非首屏重型弹窗优先考虑懒加载
• bridge 调用优先放在 hook，不直接散落在组件树中

3. 页面开发路径

flowchart TD
    Feature[新增或修改页面功能]
    Page[页面容器]
    Hook[页面 Hook]
    Components[子组件]
    Helpers[helper / lib]
    Preload[window.electron facade]

    Feature --> Page
    Page --> Hook
    Page --> Components
    Hook --> Helpers
    Hook --> Preload

4. 当前页面入口

主要页面：

• ExtractorPage.tsx
• CleanerPage.tsx
• SettingsPage.tsx

主壳层：

• App.tsx
• AuthenticatedAppShell.tsx
• UnauthenticatedApp.tsx

5. Hook 组织建议

推荐把 hook 分成几类：

• 页面启动/编排 hook 例如 useAppBootstrap
• 业务流程 hook 例如 useCleaner、useExtractor
• 辅助状态 hook 例如 usePersistentTextState、useSharedProductionIds

graph LR
    Page[Page]
    Bootstrap[Bootstrap Hook]
    Domain[Domain Hook]
    Helper[Helper Hook]

    Page --> Bootstrap
    Page --> Domain
    Domain --> Helper

6. 当前推荐风格

结合近期重构，当前 renderer 更推荐：

• App.tsx 保持薄入口
• CleanerPage 保持页面布局和弹窗编排
• 重型局部区域拆成子组件
• 异步状态收敛到 hook

7. 状态更新建议

flowchart LR
    Input[用户输入]
    Local[局部 state]
    Derived[派生状态]
    Async[异步请求]
    UI[UI 更新]

    Input --> Local
    Local --> Derived
    Local --> Async
    Derived --> UI
    Async --> UI

建议：

• 能派生的状态尽量派生，不额外存储
• 输入态不要直接挂太多高频副作用
• 非紧急 UI 更新可考虑 startTransition

8. 弹窗开发建议

当前项目弹窗较多，建议遵循：

• 非首屏关键弹窗优先懒加载
• 弹窗状态尽量放在页面或页面 hook 中统一管理
• 弹窗本身专注展示和内部交互

9. 典型改动路径

改 Cleaner 页面

• CleanerPage.tsx
• components/cleaner/*
• useCleaner.ts
• hooks/cleaner/*

改 Extractor 页面

• ExtractorPage.tsx
• useExtractor.ts
• useSharedProductionIds.ts

改更新弹窗

• UpdateDialog.tsx
• useUpdateDialogState.ts
• useAppBootstrap.ts

10. 测试建议

当前 renderer 测试更适合先从：

• 状态 helper
• hook 决策逻辑
• 与 preload 调用边界有关的轻量测试

开始补，而不是一上来就做全量 UI 集成测试。

11. 常见反模式

• 页面组件同时承载过多副作用
• 在组件中直接散布大量 window.electron.xxx
• 一个 hook 同时管理初始化、交互、请求、持久化和对话框
• 非首屏重型组件全部静态导入