BIPMaterialManager/docs/developer/architecture/file-map.md

文件地图

本文档提供一个“高频核心文件地图”，帮助开发者快速定位项目里最值得先看的文件，而不是在目录树里盲找。

1. 快速定位图

graph TD
    Root[项目入口]
    Main[src/main/index.ts]
    Preload[src/preload/index.ts]
    Renderer[src/renderer/src/App.tsx]
    Pages[src/renderer/src/pages]
    IPC[src/main/ipc]
    Services[src/main/services]

    Root --> Main
    Root --> Preload
    Root --> Renderer
    Renderer --> Pages
    Main --> IPC
    Main --> Services

2. 最先阅读的文件

如果你刚进入仓库，建议优先看这些文件：

文件	作用
src/main/index.ts	主进程启动入口
src/main/bootstrap/runtime.ts	运行时初始化与 IPC 注册
src/main/ipc/index.ts	所有 IPC handler 注册中心
src/preload/index.ts	preload 入口
src/preload/api/index.ts	renderer 可用 API 聚合入口
src/renderer/src/App.tsx	React 应用入口
src/renderer/src/components/app/AuthenticatedAppShell.tsx	已认证态主壳层

3. Main 进程文件地图

3.1 启动与窗口

graph TD
    Index[index.ts]
    Runtime[bootstrap/runtime.ts]
    Guards[bootstrap/process-guards.ts]
    Window[bootstrap/main-window.ts]

    Index --> Runtime
    Index --> Guards
    Index --> Window

关键文件：

• src/main/index.ts
• src/main/bootstrap/runtime.ts
• src/main/bootstrap/process-guards.ts
• src/main/bootstrap/main-window.ts

3.2 IPC 注册层

graph TD
    IPCIndex[ipc/index.ts]
    Auth[auth-handler.ts]
    Cleaner[cleaner-handler.ts]
    Extractor[extractor-handler.ts]
    Validation[validation-handler.ts]
    Update[update-handler.ts]
    Settings[settings-handler.ts]
    Report[report-handler.ts]

    IPCIndex --> Auth
    IPCIndex --> Cleaner
    IPCIndex --> Extractor
    IPCIndex --> Validation
    IPCIndex --> Update
    IPCIndex --> Settings
    IPCIndex --> Report

建议优先关注：

• src/main/ipc/index.ts
• src/main/ipc/auth-handler.ts
• src/main/ipc/cleaner-handler.ts
• src/main/ipc/extractor-handler.ts
• src/main/ipc/validation-handler.ts
• src/main/ipc/update-handler.ts

3.3 核心服务层

graph TD
    Services[services/]
    Auth[auth/]
    Cleaner[cleaner/]
    Validation[validation/]
    Update[update/]
    Config[config/]
    ERP[erp/]
    Report[report/]

    Services --> Auth
    Services --> Cleaner
    Services --> Validation
    Services --> Update
    Services --> Config
    Services --> ERP
    Services --> Report

高频核心文件：

• src/main/services/auth/auth-application-service.ts
• src/main/services/cleaner/cleaner-application-service.ts
• src/main/services/validation/validation-application-service.ts
• src/main/services/validation/shared-production-ids-store.ts
• src/main/services/update/update-service.ts
• src/main/services/update/update-catalog-service.ts
• src/main/services/config/config-manager.ts

4. Preload 文件地图

preload 现在已经按领域组织。

graph TD
    Preload[index.ts]
    API[api/index.ts]
    IPC[lib/ipc.ts]
    Auth[api/auth.ts]
    Cleaner[api/cleaner.ts]
    Extractor[api/extractor.ts]
    Validation[api/validation.ts]
    Materials[api/materials.ts]
    Process[api/process.ts]
    Resolver[api/resolver.ts]

    Preload --> API
    API --> Auth
    API --> Cleaner
    API --> Extractor
    API --> Validation
    API --> Materials
    API --> Process
    API --> Resolver
    API --> IPC

关键文件：

• src/preload/index.ts
• src/preload/index.d.ts
• src/preload/api/index.ts
• src/preload/lib/ipc.ts

5. Renderer 文件地图

5.1 应用壳层

关键文件：

• src/renderer/src/App.tsx
• src/renderer/src/hooks/useAppBootstrap.ts
• src/renderer/src/components/app/AuthenticatedAppShell.tsx
• src/renderer/src/components/app/UnauthenticatedApp.tsx

graph TD
    App[App.tsx]
    Bootstrap[useAppBootstrap.ts]
    Authenticated[AuthenticatedAppShell.tsx]
    Unauthenticated[UnauthenticatedApp.tsx]

    App --> Bootstrap
    App --> Authenticated
    App --> Unauthenticated

5.2 页面入口

关键页面：

• src/renderer/src/pages/ExtractorPage.tsx
• src/renderer/src/pages/CleanerPage.tsx
• src/renderer/src/pages/SettingsPage.tsx

5.3 Cleaner 相关

graph TD
    Page[CleanerPage.tsx]
    Hook[useCleaner.ts]
    Sidebar[CleanerSidebar.tsx]
    Toolbar[CleanerToolbar.tsx]
    Table[CleanerResultsTable.tsx]
    Bar[CleanerExecutionBar.tsx]
    Helpers[hooks/cleaner/helpers.ts]
    API[hooks/cleaner/api.ts]

    Page --> Hook
    Page --> Sidebar
    Page --> Toolbar
    Page --> Table
    Page --> Bar
    Hook --> Helpers
    Hook --> API

关键文件：

• src/renderer/src/pages/CleanerPage.tsx
• src/renderer/src/hooks/useCleaner.ts
• src/renderer/src/hooks/cleaner/api.ts
• src/renderer/src/hooks/cleaner/helpers.ts

5.4 Extractor 相关

关键文件：

• src/renderer/src/pages/ExtractorPage.tsx
• src/renderer/src/hooks/useExtractor.ts
• src/renderer/src/hooks/useSharedProductionIds.ts
• src/renderer/src/hooks/usePersistentTextState.ts
• src/renderer/src/components/OrderNumberInput.tsx

5.5 更新相关

关键文件：

• src/renderer/src/components/UpdateDialog.tsx
• src/renderer/src/hooks/useUpdateDialogState.ts
• src/renderer/src/hooks/useAppBootstrap.ts

6. 测试文件地图

graph TD
    Tests[tests/]
    Unit[unit/]
    Integration[integration/]
    E2E[e2e/]
    Manual[manual/]

    Tests --> Unit
    Tests --> Integration
    Tests --> E2E
    Tests --> Manual

和当前重构关系较强的测试包括：

• tests/unit/preload-surface.test.ts
• tests/unit/auth-handler.test.ts
• tests/unit/cleaner-handler.test.ts
• tests/unit/bootstrap-runtime.test.ts
• tests/unit/update-catalog-service.test.ts
• tests/unit/use-shared-production-ids.test.ts
• tests/unit/use-update-dialog-state.test.ts

7. 阅读建议

不同任务建议优先看不同文件：

flowchart TD
    Task[开发任务]
    Startup[启动问题]
    Cleaner[Cleaner 功能]
    Extractor[Extractor 功能]
    Update[更新功能]
    Auth[认证功能]

    Task --> Startup
    Task --> Cleaner
    Task --> Extractor
    Task --> Update
    Task --> Auth

    Startup --> A[src/main/index.ts / bootstrap]
    Cleaner --> B[CleanerPage / useCleaner / cleaner-handler / cleaner service]
    Extractor --> C[ExtractorPage / useExtractor / extractor-handler]
    Update --> D[UpdateDialog / useAppBootstrap / update service]
    Auth --> E[useAppBootstrap / auth-handler / auth service]