# 模块文档索引

本目录收录项目核心业务模块的开发文档。

这些文档的目标不是替代源码，而是帮助开发者快速理解：

- 每个模块负责什么
- 模块的入口文件在哪里
- 模块之间如何协作
- 主要数据和调用链怎么流动
- 改某个功能时应该先看哪些文件

## 推荐阅读方式

如果你是第一次进入模块层，建议按下面顺序阅读：

1. `auth`
2. `extractor`
3. `validation`
4. `cleaner`
5. `update`
6. `settings`

这个顺序基本对应项目的主要业务路径和依赖关系。

## 模块关系图

```mermaid
graph TD
    Auth[auth]
    Extractor[extractor]
    Validation[validation]
    Cleaner[cleaner]
    Update[update]
    Settings[settings]

    Auth --> Extractor
    Auth --> Cleaner
    Auth --> Settings
    Auth --> Update
    Extractor --> Validation
    Validation --> Cleaner
```

可以把它理解成：

- `auth`
  提供用户上下文，是多个模块的前置条件
- `extractor`
  负责输入和提取，是共享订单号的来源之一
- `validation`
  把共享数据和数据库数据转成 Cleaner 可消费结果
- `cleaner`
  消费校验结果并执行 ERP 清理
- `update`
  根据当前用户上下文给出更新能力和状态
- `settings`
  提供 ERP 凭据等配置能力

## 模块目录一览

| 模块       | 文档            | 核心职责                                                  |
| ---------- | --------------- | --------------------------------------------------------- |
| Auth       | `auth.md`       | 登录、silent login、管理员代切用户、用户上下文同步        |
| Extractor  | `extractor.md`  | 订单号输入、提取执行、日志与共享订单号同步                |
| Validation | `validation.md` | 共享 Production IDs、校验查询、结果富化、Cleaner 数据准备 |
| Cleaner    | `cleaner.md`    | 物料校验展示、删除计划保存、ERP 清理执行、报告展示        |
| Update     | `update.md`     | 更新目录、状态广播、下载、安装、用户/管理员更新视图       |
| Settings   | `settings.md`   | ERP 凭据加载与保存、当前用户配置管理                      |

## 模块入口地图

```mermaid
graph LR
    Renderer[Renderer Pages / Hooks]
    Preload[Preload APIs]
    IPC[IPC Handlers]
    Services[Main Services]
    Modules[业务模块文档]

    Renderer --> Preload
    Preload --> IPC
    IPC --> Services
    Modules --> Renderer
    Modules --> IPC
    Modules --> Services
```

阅读模块文档时，建议同时关注三层入口：

- renderer 入口
  页面、组件、hooks
- IPC 入口
  handler
- main service 入口
  application service / domain service

## 按任务选择阅读路径

如果你是按任务来看文档，可以参考下面这张图：

```mermaid
flowchart TD
    Task[当前任务]
    Login[登录 / 用户切换]
    Extract[订单提取]
    Validate[物料校验]
    Clean[ERP 清理]
    UpdateTask[应用更新]
    Config[配置修改]

    Task --> Login
    Task --> Extract
    Task --> Validate
    Task --> Clean
    Task --> UpdateTask
    Task --> Config

    Login --> AuthDoc[auth.md]
    Extract --> ExtractorDoc[extractor.md]
    Validate --> ValidationDoc[validation.md]
    Clean --> CleanerDoc[cleaner.md]
    UpdateTask --> UpdateDoc[update.md]
    Config --> SettingsDoc[settings.md]
```

## 和 architecture 文档的关系

`modules/` 和 `architecture/` 的关系如下：

```mermaid
graph LR
    Architecture[architecture/]
    Modules[modules/]
    Guides[guides/]

    Architecture --> Modules
    Modules --> Guides
```

理解方式可以是：

- 先看 `architecture/`
  建立系统整体认知
- 再看 `modules/`
  深入理解业务模块
- 最后看 `guides/`
  落到具体开发动作

## 后续扩展建议

如果后续业务边界继续演进，可以在这里继续增加模块文档，例如：

- `report.md`
- `materials.md`
- `config.md`
- `logger.md`

新增模块文档时，建议同步更新这份索引页，让 `modules/README.md` 持续保持为模块层总入口。