1.8.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -8,6 +8,7 @@ out
 
 # AI Agent
 .claude
+.agents
 
 # Environment
 .env
@@ -15,6 +16,8 @@ out
 # Test outputs
 coverage/
 downloads/
+release-output/
+build/bin/
 *.xlsx
 *.parsed.json
 
@@ -41,4 +44,4 @@ logs
 nul
 
 # TypeScript incremental compilation cache
-*.tsbuildinfo
+*.tsbuildinfo

BROWSER_DEPLOYMENT.md

@@ -1,176 +0,0 @@
-# Playwright 浏览器部署指南
-
-## 概述
-
-本文档为开发人员提供 ERPAuto 应用程序中 Playwright Chromium 浏览器的部署指南。文档说明如何将浏览器文件从开发机复制到目标用户机器，确保应用程序能够正常运行浏览器自动化任务。
-
-**重要提示**：部署前请先阅读 [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) 了解版本信息。
-
-## 目标路径
-
-浏览器文件必须部署在以下路径：
-
-```
-%APPDATA%\erpauto\ms-playwright\chromium-1208\
-```
-
-完整展开路径示例（Windows）：
-
-```
-C:\Users\<用户名>\AppData\Roaming\erpauto\ms-playwright\chromium-1208\
-```
-
-## 目录结构
-
-部署完成后，目标目录结构应如下所示：
-
-```
-%APPDATA%\erpauto\ms-playwright\
-└── chromium-1208/
-    └── chrome-win/
-        ├── chrome.exe              # 浏览器可执行文件
-        ├── chrome_dll.dll
-        ├── resources/
-        ├── locales/
-        └── ...                     # 其他浏览器文件
-```
-
-**关键文件**：`chrome-win/chrome.exe` 必须存在，否则浏览器无法启动。
-
-## 部署步骤
-
-### 步骤 1：在开发机上准备
-
-1. 确保开发机已安装正确版本的 Playwright：
-
-   ```bash
-   npm install playwright@1.58.2
-   ```
-
-2. 下载 Chromium 浏览器：
-
-   ```bash
-   npx playwright install chromium
-   ```
-
-3. 定位开发机上的浏览器缓存目录：
-
-   ```
-   C:\Users\<开发机用户名>\AppData\Local\ms-playwright\chromium-1208
-   ```
-
-### 步骤 2：复制文件
-
-1. **复制整个浏览器目录**
-   - 将开发机上的 `chromium-1208` 目录完整复制
-   - 不要只复制部分文件，确保所有子目录和文件都包含在内
-
-2. **粘贴到目标路径**
-   - 在目标机器上创建目录：`%APPDATA%\erpauto\ms-playwright\`
-   - 将 `chromium-1208` 目录粘贴到该路径下
-
-3. **验证文件完整性**
-   - 确认目标路径存在：`%APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win\chrome.exe`
-   - 检查文件大小约为 280MB
-
-### 步骤 3：配置环境变量（可选）
-
-如需确保应用程序使用正确的浏览器路径，可设置以下环境变量：
-
-```batch
-set PLAYWRIGHT_BROWSERS_PATH=%APPDATA%\erpauto\ms-playwright
-```
-
-或在应用程序代码中设置：
-
-```javascript
-process.env.PLAYWRIGHT_BROWSERS_PATH = path.join(app.getPath('userData'), 'ms-playwright')
-```
-
-## 验证步骤
-
-部署完成后，执行以下验证步骤：
-
-### 验证 1：检查目录结构
-
-在目标机器上运行：
-
-```batch
-dir %APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win\chrome.exe
-```
-
-应显示文件存在。
-
-### 验证 2：启动浏览器测试
-
-运行 ERPAuto 应用程序，执行以下操作：
-
-1. 登录应用程序
-2. 进入「数据提取」页面
-3. 输入一个有效订单号
-4. 点击「开始提取」
-5. 观察浏览器是否正常启动并执行任务
-
-### 验证 3：检查日志
-
-查看应用程序日志，确认没有浏览器相关的错误信息：
-
-- 无 "browser not found" 错误
-- 无 "chromium revision not found" 错误
-- 无 "PLAYWRIGHT_BROWSERS_PATH" 相关警告
-
-## 故障排查
-
-### 问题 1：浏览器无法启动
-
-**症状**：应用程序报错，提示找不到浏览器或启动失败。
-
-**解决方案**：
-
-1. 确认修订号匹配（必须是 1208）
-2. 检查 `chrome-win/chrome.exe` 文件是否存在
-3. 验证 `PLAYWRIGHT_BROWSERS_PATH` 环境变量设置正确
-4. 确认目标机器具有相同的 Playwright 版本（1.58.2）
-
-### 问题 2：版本不匹配错误
-
-**症状**：应用程序启动时报出版本冲突错误。
-
-**解决方案**：
-
-1. 检查 `package.json` 中的 Playwright 版本是否为 1.58.2
-2. 确认复制的 Chromium 修订号为 1208
-3. 参考 [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) 核对所有版本信息
-
-### 问题 3：权限不足
-
-**症状**：无法写入或读取浏览器目录。
-
-**解决方案**：
-
-1. 确保目标目录具有适当的读写权限
-2. 以管理员身份运行应用程序进行测试
-3. 检查防病毒软件是否阻止了浏览器执行
-
-### 问题 4：路径错误
-
-**症状**：应用程序在错误的位置查找浏览器文件。
-
-**解决方案**：
-
-1. 确认 `%APPDATA%` 环境变量指向正确的用户目录
-2. 检查应用程序是否正确解析了 `userData` 路径
-3. 在代码中硬编码浏览器路径进行调试
-
-## 注意事项
-
-- **仅部署 Chromium**：ERPAuto 只需要 Chromium 浏览器，不需要 Firefox 或 WebKit
-- **版本一致性**：开发机和目标机器的 Playwright 版本必须一致
-- **修订号匹配**：Chromium 修订号（1208）必须完全匹配，否则可能出现兼容性问题
-- **文件完整性**：复制时确保所有文件完整，损坏的浏览器文件会导致启动失败
-- **网络隔离环境**：目标机器如果无法访问互联网，必须提前部署浏览器文件，因为无法自动下载
-
-## 参考文档
-
-- [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) - 版本信息和目录结构详情
-- [README.md](./README.md) - 项目总体说明

BROWSER_VERSIONS.md

@@ -1,96 +0,0 @@
-# Playwright 浏览器版本信息
-
-本文档记录 ERPAuto 项目使用的 Playwright 浏览器版本和部署信息。
-
-## 版本信息
-
-| 组件            | 版本号       |
-| --------------- | ------------ |
-| Playwright      | 1.58.2       |
-| Chromium        | 145.0.7632.6 |
-| Chromium 修订号 | 1208         |
-
-## 浏览器目录结构
-
-Playwright 将浏览器文件缓存在以下位置：
-
-### Windows 开发环境
-
-```
-C:\Users\<用户名>\AppData\Local\ms-playwright\
-└── chromium-1208/
-    └── chrome-win/
-        ├── chrome.exe
-        └── ...
-```
-
-### 目标部署环境
-
-```
-%APPDATA%\erpauto\ms-playwright\
-└── chromium-1208/
-    └── chrome-win/
-        ├── chrome.exe
-        └── ...
-```
-
-## 部署指南
-
-### 开发环境准备
-
-1. 安装 Playwright 1.58.2
-
-   ```bash
-   npm install playwright@1.58.2
-   ```
-
-2. 下载 Chromium 浏览器
-   ```bash
-   npx playwright install chromium
-   ```
-
-### 浏览器文件复制步骤
-
-1. **定位源目录**
-   - 开发机上找到 Playwright 浏览器缓存目录
-   - 默认路径：`C:\Users\<用户名>\AppData\Local\ms-playwright\chromium-1208`
-
-2. **复制浏览器文件**
-   - 将整个 `chromium-1208` 目录复制到部署目标
-   - 目标路径：`%APPDATA%\erpauto\ms-playwright\chromium-1208`
-
-3. **验证目录结构**
-   - 确认目标路径包含 `chrome-win/chrome.exe`
-   - 确保所有子文件完整复制
-
-### 环境变量配置
-
-如需要自定义浏览器路径，可设置环境变量：
-
-```bash
-# Windows
-set PLAYWRIGHT_BROWSERS_PATH=%APPDATA%\erpauto\ms-playwright
-```
-
-## 注意事项
-
-- 仅包含 Chromium 浏览器（Firefox 和 WebKit 不需要）
-- 浏览器文件体积约为 280MB
-- 部署时确保目标机器具有相同的 Playwright 版本（1.58.2）
-- 修订号必须匹配（1208），否则可能出现兼容性问题
-
-## 故障排查
-
-### 浏览器无法启动
-
-1. 检查修订号是否匹配（1208）
-2. 确认 `chrome-win/chrome.exe` 文件存在
-3. 验证 PLAYWRIGHT_BROWSERS_PATH 环境变量设置
-
-### 版本不匹配错误
-
-确保以下版本一致：
-
-- package.json 中的 Playwright 版本
-- 下载的 Chromium 修订号
-- browsers.json 中定义版本号

CLAUDE.md

@@ -1,141 +1,165 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+本文件用于给 AI 编程代理提供本项目的最小必要指导。  
+目标不是替代 `README` 或 `docs/`，而是帮助代理快速理解项目结构、工作方式和关键约束。
 
-## Development Commands
+## 项目概览
 
-### Running the Application
+ERPAuto 是一个基于 Electron 的桌面应用，用于自动化处理 ERP 系统中的数据提取、清理、校验和配置管理。
+
+技术栈：
+
+- Electron 39
+- React 19
+- TypeScript 5.9
+- electron-vite / Vite 7
+- Playwright 1.58
+- Vitest
+
+## 常用命令
+
+开发与构建：
 
 ```bash
-npm run dev              # Start development server with hot reload
+npm run dev
-npm run build            # Full build with type checking
+npm run build
-npm run build:win        # Build Windows executable
+npm run build:win
 ```
 
-### Code Quality
+质量检查：
 
 ```bash
-npm run lint             # ESLint check
+npm run typecheck
-npm run format           # Prettier format
+npm run typecheck:node
-npm run typecheck        # TypeScript check (both main and renderer)
+npm run typecheck:web
-npm run typecheck:node   # TypeScript check for main process only
+npm run lint
-npm run typecheck:web    # TypeScript check for renderer only
+npm run format
 ```
 
-### Testing
+测试：
 
 ```bash
-npm run test             # Run unit tests (Vitest)
+npm run test
-npm run test:coverage    # Run tests with coverage report
+npm run test:coverage
-npm run test:e2e         # Run E2E tests (Playwright)
+npm run test:e2e
-npm run test:e2e:ui      # Run E2E tests with UI
-npm run test:e2e:report  # Show E2E test report
 ```
 
-## Architecture Overview
+发布：
 
-ERPAuto is an **Electron desktop application** for automating ERP system data processing. The application follows the classic Electron architecture with three distinct processes:
+```bash
+npm run release:publish -- --channel stable
+npm run release:publish -- --channel preview
+```
 
-### Process Structure
+详细发布流程见：
+[docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
 
-1. **Main Process** (`src/main/`)
+## 代码结构
-   - Node.js environment managing application lifecycle
-   - Entry point: `src/main/index.ts`
-   - Registers all IPC handlers via `registerIpcHandlers()`
-   - Loads configuration from `config.yaml` via ConfigManager at startup
 
-2. **Preload Script** (`src/preload/`)
+### 主进程
-   - Security bridge between main and renderer processes
-   - Exposes type-safe APIs via `contextBridge` as `window.electron` and `window.api`
-   - Central API surface organized by domain (auth, extractor, cleaner, database, etc.)
 
-3. **Renderer Process** (`src/renderer/`)
+- 路径：`src/main/`
-   - React 19 + TypeScript UI
+- 入口：`src/main/index.ts`
-   - Uses exposed preload APIs for all main process communication
+- 职责：
-   - Authentication-based routing with role-based access control
+  - 应用生命周期管理
+  - 配置加载
+  - IPC 注册
+  - 更新服务初始化
 
-### Service Architecture
+### 预加载层
 
-The main process is organized around domain-specific services in `src/main/services/`:
+- 路径：`src/preload/`
+- 职责：
+  - 暴露 `window.electron` API
+  - 作为 renderer 和 main 之间的安全桥
 
-- **ERP Services** (`services/erp/`): Browser automation using Playwright
+### 渲染进程
-  - `ExtractorService` - Downloads material plan data
-  - `CleanerService` - Deletes specified materials with dry-run support
-  - `ErpAuthService` - Handles ERP authentication
-  - `OrderResolverService` - Validates and resolves order numbers
-  - `locators.ts` - ERP element selectors
 
-- **Database Services** (`services/database/`): Dual database support
+- 路径：`src/renderer/`
-  - `MySqlService` / `mysql.ts` - MySQL operations
+- 技术：React + TypeScript
-  - `SqlServerService` / `sql-server.ts` - SQL Server operations
+- 特点：
-  - DAO pattern: `discrete-material-plan-dao.ts`, `materials-to-be-deleted-dao.ts`
+  - 通过 preload 暴露的 API 调用主进程
+  - 以登录状态和角色控制主要功能入口
 
-- **User Services** (`services/user/`): Authentication and session management
+### 服务层
-  - `BipUsersDao` - User data access
-  - `SessionManager` - Active session tracking
 
-- **Other Services**:
+主进程服务集中在 `src/main/services/`，按领域拆分：
-  - `config/` - Configuration management
-  - `excel/` - Excel file parsing
 
-### IPC Handler Pattern
+- `erp/`：ERP 浏览器自动化
+- `database/`：MySQL / SQL Server
+- `user/`：登录、会话、用户切换
+- `config/`：YAML 配置管理
+- `update/`：便携版更新
+- `excel/`：Excel 处理
 
-All IPC communication follows a consistent pattern:
+## 关键事实
 
-- Handlers are in `src/main/ipc/`, organized by domain (8 modules)
+### 配置系统
-- Each handler module exports a `register*Handlers()` function
-- All handlers are registered in `src/main/ipc/index.ts`
-- Channel naming follows `domain:action` convention (e.g., `extractor:run`, `auth:login`)
 
-### Authentication Flow
+- 使用 YAML 配置
+- 模板文件：`config.template.yaml`
+- 开发环境通常使用项目根目录下的 `config.yaml`
+- 生产环境会将配置放到用户目录
 
-The application implements a multi-stage authentication system:
+### IPC 组织方式
 
-1. **Silent Login**: On startup, attempts automatic login using computer name
+- 所有 IPC handler 在 `src/main/ipc/`
-2. **Fallback**: Shows login dialog if silent login fails
+- 每个领域一个 handler 模块
-3. **Admin User Selection**: Admin users can switch to other user accounts
+- 统一在 `src/main/ipc/index.ts` 注册
-4. **Session Management**: Persistent sessions with role-based permissions (Admin/User/Guest)
+- channel 命名遵循 `domain:action`
 
-Admin users see logout buttons and can access user switching. Non-admin users have restricted access based on the user who initiated their session.
+### 认证与角色
 
-### Type System
+当前主要角色是：
 
-- Separate TypeScript configs: `tsconfig.node.json` (main/preload) and `tsconfig.web.json` (renderer)
+- `Admin`
-- Types are co-located with features: `src/main/types/` contains domain-specific type definitions
+- `User`
-- The preload script exposes a typed API surface that's available in renderer
+- `Guest`
 
-### Path Aliases
+登录流程支持：
 
-- `@renderer` → `src/renderer/src` (renderer process)
+- 静默登录
-- `@main` → `src/main` (main process, tests only)
+- 普通登录
-- `@services` → `src/main/services` (main process, tests only)
+- 管理员切换用户
-- `@types` → `src/main/types` (main process, tests only)
 
-## Configuration Management
+### 便携版自动更新
 
-The application uses a YAML-based configuration system (`config.yaml`) managed by `ConfigManager`:
+项目已实现 Windows 便携版更新，关键点：
 
-- **Development**: `config.yaml` in project root (easy to edit and version control)
+- 更新检查基于登录用户角色
-- **Production**: `config.yaml` in user data directory (AppData on Windows)
+- 支持 `stable` / `preview` 双通道
+- `User` 只看 `stable`
+- `Admin` 同时看 `stable` 和 `preview`
+- 使用原生 `portable-updater.exe` 完成替换，不依赖 PowerShell
 
-Key configurations in `config.yaml`:
+相关文档：
 
-- **ERP Settings**: URL (fixed infrastructure)
+- [docs/portable-auto-update-architecture.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/portable-auto-update-architecture.md)
-- **Database**: MySQL and SQL Server connection configs (dual support)
+- [docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
-- **Paths**: Data directory and output file settings
-- **Extraction**: Batch size, verbosity, persistence options
-- **Validation**: Data source, batch size, match mode
-- **Order Resolution**: Database table and field names for order number lookup
 
-Note: ERP credentials (username/password) are stored in the database (`dbo_BIPUsers` table) per user, managed via the Settings UI.
+## 代理工作约束
 
-## Key Technologies
+1. 优先修改现有文件，不要随意新建同类文件。
+2. 变更前先理解对应模块的现有模式，尽量保持风格一致。
+3. renderer 不要直接访问 Node/Electron 能力，统一走 preload。
+4. 配置、IPC、类型定义通常需要同步更新，避免只改一层。
+5. 涉及发布、更新、构建链路时，优先复用现有脚本，不要重复实现。
+6. 涉及浏览器部署或更新流程时，先看 `docs/` 里的专题文档。
 
-- **Electron 39** - Desktop framework
+## 代理优先查看的文档
-- **React 19** - UI framework
+
-- **TypeScript 5.9** - Type safety
+- [README.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/README.md)
-- **Playwright 1.58** - Browser automation for ERP interaction
+- [docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
-- **electron-vite + Vite 7** - Build tooling
+- [docs/portable-auto-update-architecture.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/portable-auto-update-architecture.md)
-- **Zod** - Runtime validation
+- [docs/browser/PLAYWRIGHT_DEPLOYMENT.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/browser/PLAYWRIGHT_DEPLOYMENT.md)
-- **Vitest** - Unit tests
+
-- **Playwright Test** - E2E tests
+## 不放在这里的内容
+
+以下内容不应继续堆在本文件中：
+
+- 详细用户使用说明
+- 大段业务流程说明
+- 重复的架构长文
+- 版本发布记录
+
+这些内容应继续放在 `README` 或 `docs/` 下的专题文档中。

PLAYWRIGHT_DEPLOYMENT.md

@@ -1,101 +0,0 @@
-# Playwright 部署说明
-
-## 浏览器路径问题修复
-
-### 问题描述
-
-应用启动时提示"浏览器文件未找到"，但浏览器文件已经放置在正确路径下。
-
-**原因**：Playwright 1.48+ 改变了浏览器目录命名规则：
-
-- **旧格式**：`chromium-win32/chrome.exe`
-- **新格式**：`chromium-1208/chrome-win64/chrome.exe`（revision 号可能不同）
-
-### 解决方案
-
-代码已更新为自动检测新旧两种格式，并显示当前目录内容以便调试。
-
-## 快速部署
-
-### 方法 1：使用 Playwright CLI（推荐）
-
-```bash
-# 在应用目录运行
-npx playwright install chromium
-```
-
-浏览器会自动下载并安装到正确位置：
-
-- **用户数据目录**：`%APPDATA%\erpauto\ms-playwright\`
-- **完整路径**：`C:\Users\pengq\AppData\Roaming\erpauto\ms-playwright\chromium-<revision>\chrome-win64\chrome.exe`
-
-### 方法 2：手动复制
-
-如果你已经有 Playwright 浏览器文件，可以复制到应用的用户数据目录：
-
-1. 找到现有浏览器文件（通常在 `%USERPROFILE%\AppData\Local\ms-playwright`）
-2. 复制到 `%APPDATA%\erpauto\ms-playwright\`
-3. 确保目录结构正确：
-   ```
-   ms-playwright/
-   ├── chromium-1208/
-   │   ├── chrome-win64/
-   │   │   └── chrome.exe
-   │   └── INSTALLATION_COMPLETE
-   └── chromium_headless_shell-1208/
-       └── ...
-   ```
-
-### 方法 3：使用 PLAYWRIGHT_BROWSERS_PATH 环境变量
-
-将浏览器文件放在共享位置，然后设置环境变量：
-
-```bash
-# 系统环境变量
-setx PLAYWRIGHT_BROWSERS_PATH "D:\shared\playwright-browsers"
-```
-
-或在应用启动脚本中设置。
-
-## 验证安装
-
-运行应用后，检查是否还有错误提示。如果没有浏览器错误，说明安装成功。
-
-你也可以在应用日志中查找：
-
-- `Found Chromium revision: chromium-1208` - 表示成功找到浏览器
-- `Playwright browser not found` - 表示未找到，会显示可用目录列表
-
-## 常见问题
-
-### Q: 显示"浏览器文件未找到"但文件确实在那里
-
-检查目录结构是否正确：
-
-```powershell
-# 查看当前目录内容
-Get-ChildItem $env:APPDATA\erpauto\ms-playwright
-
-# 检查 chrome.exe 是否存在
-Test-Path "$env:APPDATA\erpauto\ms-playwright\chromium-*/chrome-win64/chrome.exe"
-```
-
-### Q: 不同用户使用同一个浏览器文件
-
-使用环境变量 `PLAYWRIGHT_BROWSERS_PATH` 指向共享目录。
-
-### Q: 离线部署
-
-1. 在有网络的机器上运行 `npx playwright install chromium`
-2. 复制整个 `ms-playwright` 目录
-3. 在目标机器上设置 `PLAYWRIGHT_BROWSERS_PATH` 指向该目录
-
-## 下次构建
-
-只需运行：
-
-```bash
-npm run build:win
-```
-
-所有配置已保存，Playwright 模块和浏览器路径检查会自动处理。

README.md

@@ -76,16 +76,12 @@ npm run dev
 ### 构建应用
 
 ```bash
-# Windows
+# Windows 安装版 + 便携版
 npm run build:win
-
-# macOS
-npm run build:mac
-
-# Linux
-npm run build:linux
 ```
 
+当前项目的正式构建与发布链路仅维护 Windows 目标。
+
 ## 使用指南
 
 ### 数据提取

build/PortableUpdater.cs

@@ -0,0 +1,247 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Text;
+using System.Threading;
+
+internal static class PortableUpdater
+{
+    private static string _logPath = string.Empty;
+
+    private static int Main(string[] args)
+    {
+        try
+        {
+            var options = ParseArgs(args);
+
+            var targetExe = Require(options, "--targetExe");
+            var downloadedExe = Require(options, "--downloadedExe");
+            var parentPid = int.Parse(Require(options, "--parentPid"));
+            _logPath = Require(options, "--logPath");
+            var argsBase64 = options.ContainsKey("--argsBase64") ? options["--argsBase64"] : string.Empty;
+
+            WriteLog("Portable updater started");
+            WriteLog("Target exe: " + targetExe);
+            WriteLog("Downloaded exe: " + downloadedExe);
+            WriteLog("Parent pid: " + parentPid);
+
+            var appArgs = DecodeArgs(argsBase64);
+
+            WaitForProcessExit(parentPid, 120);
+            WaitForFileAvailable(targetExe, 120);
+
+            var backupExe = targetExe + ".bak";
+            if (File.Exists(backupExe))
+            {
+                WriteLog("Removing stale backup: " + backupExe);
+                File.Delete(backupExe);
+            }
+
+            WriteLog("Backing up current executable");
+            File.Move(targetExe, backupExe);
+
+            try
+            {
+                WriteLog("Replacing executable");
+                File.Move(downloadedExe, targetExe);
+            }
+            catch (Exception replaceError)
+            {
+                WriteLog("Replace failed: " + replaceError.Message);
+                if (File.Exists(backupExe) && !File.Exists(targetExe))
+                {
+                    File.Move(backupExe, targetExe);
+                }
+                throw;
+            }
+
+            var startInfo = new ProcessStartInfo
+            {
+                FileName = targetExe,
+                UseShellExecute = false,
+                WorkingDirectory = Path.GetDirectoryName(targetExe) ?? Environment.CurrentDirectory,
+                Arguments = BuildArgumentString(appArgs)
+            };
+
+            WriteLog("Launching updated executable");
+            Process.Start(startInfo);
+
+            if (File.Exists(backupExe))
+            {
+                WriteLog("Removing backup file");
+                File.Delete(backupExe);
+            }
+
+            WriteLog("Portable update completed successfully");
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            WriteLog("Portable update failed: " + ex);
+            return 1;
+        }
+    }
+
+    private static Dictionary<string, string> ParseArgs(string[] args)
+    {
+        var result = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var key = args[i];
+            if (!key.StartsWith("--", StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            var value = i + 1 < args.Length ? args[i + 1] : string.Empty;
+            if (value.StartsWith("--", StringComparison.Ordinal))
+            {
+                result[key] = string.Empty;
+                continue;
+            }
+
+            result[key] = value;
+            i++;
+        }
+
+        return result;
+    }
+
+    private static string Require(Dictionary<string, string> options, string key)
+    {
+        if (!options.ContainsKey(key) || string.IsNullOrWhiteSpace(options[key]))
+        {
+            throw new InvalidOperationException("Missing required argument: " + key);
+        }
+
+        return options[key];
+    }
+
+    private static string[] DecodeArgs(string argsBase64)
+    {
+        if (string.IsNullOrWhiteSpace(argsBase64))
+        {
+            return Array.Empty<string>();
+        }
+
+        var raw = Encoding.UTF8.GetString(Convert.FromBase64String(argsBase64));
+        return raw.Split(new[] { '\0' }, StringSplitOptions.RemoveEmptyEntries);
+    }
+
+    private static void WaitForProcessExit(int pid, int timeoutSeconds)
+    {
+        var deadline = DateTime.UtcNow.AddSeconds(timeoutSeconds);
+
+        while (DateTime.UtcNow < deadline)
+        {
+            try
+            {
+                using (var process = Process.GetProcessById(pid))
+                {
+                    if (process.HasExited)
+                    {
+                        WriteLog("Parent process exited");
+                        return;
+                    }
+                }
+            }
+            catch (ArgumentException)
+            {
+                WriteLog("Parent process already exited");
+                return;
+            }
+
+            Thread.Sleep(500);
+        }
+
+        throw new TimeoutException("Timed out waiting for process exit: " + pid);
+    }
+
+    private static void WaitForFileAvailable(string filePath, int timeoutSeconds)
+    {
+        var deadline = DateTime.UtcNow.AddSeconds(timeoutSeconds);
+
+        while (DateTime.UtcNow < deadline)
+        {
+            try
+            {
+                using (File.Open(filePath, FileMode.Open, FileAccess.ReadWrite, FileShare.None))
+                {
+                    WriteLog("Target executable is no longer locked");
+                    return;
+                }
+            }
+            catch (IOException)
+            {
+                Thread.Sleep(500);
+            }
+            catch (UnauthorizedAccessException)
+            {
+                Thread.Sleep(500);
+            }
+        }
+
+        throw new TimeoutException("Timed out waiting for target executable to become writable: " + filePath);
+    }
+
+    private static void WriteLog(string message)
+    {
+        if (string.IsNullOrWhiteSpace(_logPath))
+        {
+            return;
+        }
+
+        try
+        {
+            var directory = Path.GetDirectoryName(_logPath);
+            if (!string.IsNullOrWhiteSpace(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            File.AppendAllText(
+                _logPath,
+                DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss.fff") + " " + message + Environment.NewLine,
+                Encoding.UTF8
+            );
+        }
+        catch
+        {
+            // Best effort logging only.
+        }
+    }
+
+    private static string BuildArgumentString(IEnumerable<string> args)
+    {
+        var builder = new StringBuilder();
+
+        foreach (var arg in args)
+        {
+            if (builder.Length > 0)
+            {
+                builder.Append(' ');
+            }
+
+            builder.Append(QuoteArgument(arg));
+        }
+
+        return builder.ToString();
+    }
+
+    private static string QuoteArgument(string arg)
+    {
+        if (string.IsNullOrEmpty(arg))
+        {
+            return "\"\"";
+        }
+
+        if (arg.IndexOfAny(new[] { ' ', '\t', '"' }) < 0)
+        {
+            return arg;
+        }
+
+        return "\"" + arg.Replace("\\", "\\\\").Replace("\"", "\\\"") + "\"";
+    }
+}

config.template.yaml

@@ -70,3 +70,16 @@ rustfs:
   secretKey: '<YOUR_SECRET_KEY>' # 密钥
   bucket: 'erpauto' # 存储桶名称
   region: 'us-east-1' # 区域（S3 兼容，默认即可）
+
+# 便携版自动更新配置
+update:
+  enabled: false
+  allowDevMode: false
+  endpoint: 'http://192.168.110.114:9000'
+  accessKey: '<YOUR_ACCESS_KEY>'
+  secretKey: '<YOUR_SECRET_KEY>'
+  bucket: 'erpauto'
+  region: 'us-east-1'
+  basePrefix: 'updates/win-portable'
+  checkIntervalMinutes: 30
+  maxAdminHistoryPerChannel: 10

docs/browser/BROWSER_VERSIONS.md

@@ -0,0 +1,139 @@
+# Playwright 浏览器版本信息
+
+本文档记录 ERPAuto 当前使用的 Playwright 版本，以及代码中采用的浏览器目录约定。
+
+## 当前版本
+
+根据 [package.json](/d:/FileLib/Projects/CodeMigration/ERPAuto/package.json)，项目当前依赖为：
+
+| 组件               | 当前版本  |
+| ------------------ | --------- |
+| `playwright`       | `^1.58.2` |
+| `playwright-core`  | `^1.58.2` |
+| `@playwright/test` | `^1.58.2` |
+
+## 当前代码中的目录约定
+
+根据 [src/main/index.ts](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/index.ts)，应用启动时会把：
+
+```text
+PLAYWRIGHT_BROWSERS_PATH = %APPDATA%\erpauto\ms-playwright
+```
+
+随后按以下顺序检查 Chromium：
+
+1. 优先检查：
+
+```text
+%APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win64\chrome.exe
+```
+
+2. 兼容旧结构：
+
+```text
+%APPDATA%\erpauto\ms-playwright\chromium-win32\chrome.exe
+```
+
+3. 如果仍然找不到，则继续扫描任意 `chromium-*` 目录，并尝试：
+
+```text
+%APPDATA%\erpauto\ms-playwright\chromium-<revision>\chrome-win64\chrome.exe
+```
+
+这意味着：
+
+- `chromium-1208` 是当前代码优先查找的默认 revision
+- 但应用并不只接受 `1208`
+- 当前主目录结构是 `chrome-win64`
+
+## 推荐目录结构
+
+### Windows 开发环境
+
+```text
+C:\Users\<用户名>\AppData\Local\ms-playwright\
+└── chromium-1208/
+    └── chrome-win64/
+        ├── chrome.exe
+        └── ...
+```
+
+### 目标部署环境
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+└── chromium-1208/
+    └── chrome-win64/
+        ├── chrome.exe
+        └── ...
+```
+
+如果不是 `1208`，只要目录名满足 `chromium-*` 且内部存在 `chrome-win64\chrome.exe`，当前代码也能识别。
+
+## 使用建议
+
+### 开发环境准备
+
+1. 安装项目依赖：
+
+```bash
+npm install
+```
+
+2. 下载 Chromium 浏览器：
+
+```bash
+npx playwright install chromium
+```
+
+### 复制浏览器文件
+
+1. 在开发机上找到 Playwright 浏览器缓存目录：
+
+```text
+C:\Users\<用户名>\AppData\Local\ms-playwright\
+```
+
+2. 复制完整的 `chromium-*` 目录到目标路径：
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+```
+
+3. 确保内部存在：
+
+```text
+chrome-win64\chrome.exe
+```
+
+## 注意事项
+
+- ERPAuto 当前只依赖 Chromium，不需要 Firefox 和 WebKit
+- 浏览器文件体积较大，建议按整个 revision 目录复制
+- 当前代码会优先尝试 `chromium-1208`
+- 但从实现角度看，“revision 严格等于 1208”不是唯一成功条件
+- 真正关键的是目录结构与可执行文件路径满足当前查找规则
+
+## 故障排查
+
+### 浏览器无法启动
+
+优先检查：
+
+1. `%APPDATA%\erpauto\ms-playwright\` 是否存在
+2. 是否存在 `chromium-1208\chrome-win64\chrome.exe`
+3. 是否存在其他 `chromium-*` 目录，且包含 `chrome-win64\chrome.exe`
+4. 是否误用了过时的 `chrome-win\chrome.exe` 路径
+
+### 版本不匹配或路径不匹配
+
+建议同时确认：
+
+- `package.json` 中的 Playwright 版本
+- 目标机器上实际部署的 Chromium 目录
+- 当前目录结构是否为 `chrome-win64\chrome.exe`
+- 应用启动时是否能在 `%APPDATA%\erpauto\ms-playwright\` 下扫描到有效 revision
+
+## 相关文档
+
+- [PLAYWRIGHT_DEPLOYMENT.md](./PLAYWRIGHT_DEPLOYMENT.md)

docs/browser/PLAYWRIGHT_DEPLOYMENT.md

@@ -0,0 +1,179 @@
+# Playwright 部署说明
+
+本文档聚焦“如何让 ERPAuto 在目标机器上拥有可用的 Playwright Chromium 浏览器”，适合作为实际部署操作说明。
+
+如果你想看版本信息，请同时参考：
+
+- [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md)
+
+## 背景
+
+ERPAuto 启动时会把 `PLAYWRIGHT_BROWSERS_PATH` 设置到：
+
+```text
+%APPDATA%\erpauto\ms-playwright
+```
+
+随后在该目录下查找 Chromium 浏览器文件。当前代码支持：
+
+- `chromium-1208\chrome-win64\chrome.exe`
+- `chromium-win32\chrome.exe`
+- 任意 `chromium-*` 目录下的 `chrome-win64\chrome.exe`
+
+因此，部署的本质就是把一个完整可用的 Chromium revision 目录放到这个位置。
+
+当前查找顺序是：
+
+1. 先查 `%APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win64\chrome.exe`
+2. 再查 `%APPDATA%\erpauto\ms-playwright\chromium-win32\chrome.exe`
+3. 最后扫描任意 `chromium-*` 目录下的 `chrome-win64\chrome.exe`
+
+所以从部署角度看，真正重要的不是目录名一定等于 `1208`，而是目录结构满足当前实现的查找规则。
+
+## 推荐部署方式
+
+### 方式 1：使用 Playwright CLI
+
+如果目标机器能联网，最简单的方式是在项目目录执行：
+
+```bash
+npx playwright install chromium
+```
+
+执行后，需要把下载得到的 `chromium-*` 目录放到：
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+```
+
+说明：
+
+- Playwright 默认下载目录通常是 `%LOCALAPPDATA%\ms-playwright\`
+- ERPAuto 运行时查找的是 `%APPDATA%\erpauto\ms-playwright\`
+- 所以“下载成功”不等于“应用一定能找到”，最终还是要确保文件落在 ERPAuto 使用的目录下
+
+### 方式 2：手动复制
+
+这是离线环境或最稳定的部署方式。
+
+1. 在一台已完成 `npx playwright install chromium` 的机器上找到：
+
+```text
+C:\Users\<用户名>\AppData\Local\ms-playwright\
+```
+
+2. 复制完整的 `chromium-*` 目录，例如：
+
+```text
+chromium-1208
+```
+
+3. 将该目录复制到目标机器：
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+```
+
+4. 确认内部存在：
+
+```text
+chrome-win64\chrome.exe
+```
+
+## 推荐目录示例
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+└── chromium-1208/
+    └── chrome-win64/
+        ├── chrome.exe
+        ├── chrome.dll
+        ├── locales/
+        ├── resources/
+        └── ...
+```
+
+如果你使用的是旧结构，也可兼容：
+
+```text
+%APPDATA%\erpauto\ms-playwright\
+└── chromium-win32/
+    └── chrome.exe
+```
+
+## 验证方式
+
+### 验证 1：检查文件
+
+执行：
+
+```powershell
+Get-ChildItem $env:APPDATA\erpauto\ms-playwright
+```
+
+如果使用默认 revision，再执行：
+
+```powershell
+Test-Path "$env:APPDATA\erpauto\ms-playwright\chromium-1208\chrome-win64\chrome.exe"
+```
+
+如果你部署的是其他 revision，请按实际目录替换。
+
+### 验证 2：启动应用
+
+启动 ERPAuto，观察是否仍弹出“浏览器文件未找到”错误框。
+
+如果没有弹窗，通常说明启动时的浏览器路径检查已经通过。
+
+### 验证 3：执行真实业务
+
+进入依赖 Playwright 的功能页面，执行一次真实流程，确认浏览器可以正常启动。
+
+## 常见问题
+
+### 问题 1：文件明明存在，但应用还是报找不到
+
+常见原因：
+
+1. 文件放在 `%LOCALAPPDATA%\ms-playwright\`，而不是 `%APPDATA%\erpauto\ms-playwright\`
+2. 目录结构是旧文档里的 `chrome-win\chrome.exe`
+3. revision 目录名不符合 `chromium-*`
+4. 缺少 `chrome-win64\chrome.exe`
+
+### 问题 2：想多个用户共用同一份浏览器文件
+
+当前代码在应用启动时会直接把 `PLAYWRIGHT_BROWSERS_PATH` 设为：
+
+```text
+%APPDATA%\erpauto\ms-playwright
+```
+
+所以默认行为是“每个用户使用自己的用户目录”。  
+如果要改成共享目录，需要同时改代码，而不是只改系统环境变量。
+
+### 问题 3：构建时是否会自动打包 Chromium
+
+不会。
+
+当前 [package.json](/d:/FileLib/Projects/CodeMigration/ERPAuto/package.json) 的 `build:win` 明确设置了：
+
+```text
+PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+```
+
+也就是说：
+
+- 构建过程不会自动下载浏览器
+- 打包产物也不自带 Chromium
+- 浏览器仍需要单独部署到目标机器
+
+## 结论
+
+当前最稳妥的部署方式是：
+
+1. 在联网机器下载 Chromium
+2. 复制完整 `chromium-*` 目录
+3. 放到 `%APPDATA%\erpauto\ms-playwright\`
+4. 确保内部有 `chrome-win64\chrome.exe`
+
+只要满足这几个条件，ERPAuto 当前实现就能正确识别并使用浏览器。

docs/build-and-release-guide.md

@@ -0,0 +1,199 @@
+# 构建与发布流程
+
+本文档说明 ERPAuto Windows 便携版的当前构建与发布方式，包括推荐的一键发布命令、分步命令，以及发布产物在对象存储中的结构。
+
+## 概览
+
+当前发布链路分为 3 个阶段：
+
+1. 构建 Windows 包
+2. 生成本地发布物料和索引
+3. 上传到对象存储并校验远端索引
+
+现在已经提供一键总控脚本：
+
+```bash
+npm run release:publish -- --channel stable
+```
+
+或：
+
+```bash
+npm run release:publish -- --channel preview
+```
+
+## 发布前准备
+
+发布前需要确认：
+
+1. [package.json](/d:/FileLib/Projects/CodeMigration/ERPAuto/package.json) 和 [package-lock.json](/d:/FileLib/Projects/CodeMigration/ERPAuto/package-lock.json) 的版本号已经改到目标版本
+2. [config.yaml](/d:/FileLib/Projects/CodeMigration/ERPAuto/config.yaml) 中 `update` 配置正确，且对象存储可访问
+3. 对应版本的 changelog 已存在于 `docs/releases/`
+
+changelog 自动查找规则如下：
+
+1. 优先查找 `docs/releases/<version>-rebuild.md`
+2. 如果不存在，再查找 `docs/releases/<version>.md`
+
+例如当前版本是 `1.3.6`，脚本会按顺序尝试：
+
+```text
+docs/releases/1.3.6-rebuild.md
+docs/releases/1.3.6.md
+```
+
+## 推荐流程：一键发布
+
+### 发布 Stable
+
+```bash
+npm run release:publish -- --channel stable
+```
+
+### 发布 Preview
+
+```bash
+npm run release:publish -- --channel preview
+```
+
+这个命令会自动完成：
+
+1. 读取当前 `package.json` 版本号
+2. 校验 `package.json` / `package-lock.json` 版本一致
+3. 校验 changelog 文件存在
+4. 设置 `APP_CHANNEL`
+5. 执行 `build:win`
+6. 执行 `release:prepare`
+7. 执行 `release:upload --verify`
+8. 输出本次发布摘要
+
+## 分步流程
+
+如果需要调试，也可以手工分步执行。
+
+### 1. 构建
+
+Stable：
+
+```bash
+$env:APP_CHANNEL="stable"
+npm run build:win
+```
+
+Preview：
+
+```bash
+$env:APP_CHANNEL="preview"
+npm run build:win
+```
+
+### 2. 生成发布物料
+
+```bash
+npm run release:prepare -- --channel stable --changelog docs/releases/1.3.6.md
+```
+
+或：
+
+```bash
+npm run release:prepare -- --channel preview --changelog docs/releases/1.3.6.md
+```
+
+这一步会生成：
+
+- `release-output/updates/win-portable/<channel>/artifacts/...`
+- `release-output/updates/win-portable/<channel>/changelogs/...`
+- `release-output/updates/win-portable/<channel>/index.json`
+
+### 3. 上传并校验
+
+```bash
+npm run release:upload -- --channel stable --verify
+```
+
+或：
+
+```bash
+npm run release:upload -- --channel preview --verify
+```
+
+## 上传策略
+
+当前上传脚本默认采用“增量上传”：
+
+- 上传当前版本对应的 `artifact`
+- 上传当前版本对应的 `changelog`
+- 上传最新的 `index.json`
+
+也就是说，它不会再把旧版本的 exe 和旧 changelog 全部重复上传。
+
+如果确实需要整条通道做一次全量同步，可以显式使用：
+
+```bash
+npm run release:upload -- --channel stable --full-sync
+```
+
+## 对象存储目录结构
+
+发布到对象存储后的目录结构如下：
+
+```text
+updates/win-portable/
+├── stable/
+│   ├── artifacts/
+│   │   └── erpauto-<version>-stable-portable.exe
+│   ├── changelogs/
+│   │   └── <version>.md
+│   └── index.json
+└── preview/
+    ├── artifacts/
+    │   └── erpauto-<version>-preview-portable.exe
+    ├── changelogs/
+    │   └── <version>.md
+    └── index.json
+```
+
+## 相关脚本
+
+- [publish-release.js](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/publish-release.js)
+  一键总控脚本，负责串起 build、prepare、upload。
+- [prepare-release.js](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/prepare-release.js)
+  负责整理本地发布物料和生成 `index.json`。
+- [upload-release.js](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/upload-release.js)
+  负责上传当前版本物料和 `index.json`，并可回读远端索引。
+- [compile-updater.js](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/compile-updater.js)
+  负责构建原生 `portable-updater.exe`。
+
+## 常见问题
+
+### 1. 缺少 `--channel`
+
+会直接失败，因为发布必须显式指定 `stable` 或 `preview`。
+
+### 2. 找不到 changelog
+
+说明 `docs/releases/` 下没有当前版本对应的 Markdown 文件。  
+先补 changelog，再执行发布。
+
+### 3. 版本不是当前通道最新
+
+总控脚本在 `prepare` 后会检查本地生成的 `index.json`。  
+如果当前版本不是该通道索引的第一项，脚本会停止，避免把旧版本误当成当前发布版本。
+
+### 4. 只想调试某一步
+
+可以直接使用分步命令：
+
+- `npm run build:win`
+- `npm run release:prepare -- ...`
+- `npm run release:upload -- ...`
+
+## 建议
+
+日常发布优先使用：
+
+```bash
+npm run release:publish -- --channel <stable|preview>
+```
+
+只有在排查问题或需要特殊处理时，再退回分步命令。

docs/developer/README.md

@@ -0,0 +1,137 @@
+# Developer Docs
+
+这组文档面向项目开发者，目标是帮助团队快速理解项目结构、运行时分层、核心业务模块和常见开发路径。
+
+它不是一次性说明，而是一套会持续维护的开发文档入口。
+
+## 文档目标
+
+- 帮助新开发者快速建立项目地图
+- 帮助现有开发者定位功能入口、关键文件和调用链
+- 为重构、排障、扩展功能提供统一参考
+- 逐步沉淀重要设计决策，而不是只留在提交记录和口头沟通中
+
+## 推荐阅读顺序
+
+如果你是第一次接触这个项目，建议按下面顺序阅读：
+
+1. 项目总览
+2. 运行时架构
+3. 核心模块文档
+4. 开发与调试指南
+
+## 开发者文档总导航
+
+```mermaid
+graph TD
+    Developer[docs/developer]
+    Architecture[architecture/]
+    Modules[modules/]
+    Guides[guides/]
+
+    Overview[系统地图]
+    Runtime[运行时分层]
+    DataFlow[数据流与关键文件]
+    Business[业务模块]
+    TaskGuides[开发任务指南]
+
+    Developer --> Architecture
+    Developer --> Modules
+    Developer --> Guides
+
+    Architecture --> Overview
+    Architecture --> Runtime
+    Architecture --> DataFlow
+    Modules --> Business
+    Guides --> TaskGuides
+```
+
+也可以把这三层理解成：
+
+```mermaid
+flowchart LR
+    A[architecture]
+    B[modules]
+    C[guides]
+
+    A -->|先理解系统| B
+    B -->|再理解业务边界| C
+    C -->|最后落到开发动作| Done[开始修改与维护]
+```
+
+## 计划中的目录结构
+
+```text
+docs/developer/
+  README.md
+  architecture/
+    README.md
+    overview.md
+    runtime-architecture.md
+    data-flow.md
+    file-map.md
+    decision-log.md
+  modules/
+    README.md
+    extractor.md
+    cleaner.md
+    validation.md
+    auth.md
+    update.md
+    settings.md
+  guides/
+    README.md
+    local-development.md
+    debugging.md
+    ipc-development.md
+    renderer-development.md
+    release-process.md
+```
+
+## 内容组织原则
+
+这套文档会按“读者任务”来组织，而不是简单照抄源码目录。
+
+文档主要分为三类：
+
+- `architecture/`
+  说明系统整体结构、运行时分层、关键数据流和核心设计决策。
+- `modules/`
+  说明每个业务模块的职责、入口文件、调用链、状态流和常见改动点。
+- `guides/`
+  说明开发者在实际工作中最常见的任务，例如本地启动、调试、扩展 IPC、修改前端页面、发布版本等。
+
+## 维护约定
+
+为了保证这套文档长期可用，后续维护建议遵循这些约定：
+
+- 新增核心模块时，同步补一篇对应的模块文档
+- 发生重要重构时，更新相关架构文档和决策记录
+- 文档优先解释“职责、边界、调用关系”，而不是堆砌实现细节
+- 文档应当多用、善用 `mermaid` 做图形化表达
+- 遇到结构、分层、调用链、时序、流程时，优先考虑先画图再解释
+- 图负责帮助读者快速建立整体认知，文字负责解释细节和边界
+- 文档尽量附上关键文件路径，并保持图和正文一一对应
+- 文档中的路径、模块名、调用链描述应与当前代码保持一致
+
+## 当前状态
+
+当前 `developer` 文档目录刚刚建立，后续会优先补齐这些内容：
+
+- 项目总览
+- 运行时架构
+- `extractor` 模块
+- `cleaner` 模块
+- `validation` 模块
+- `update` 模块
+
+## 相关文档
+
+当前仓库里已经有一些与架构、重构和流程相关的文档，后续会逐步整理并决定是否纳入这套开发者文档体系：
+
+- `docs/validation-handler-refactor-overview.md`
+- `docs/use-cleaner-refactor-overview.md`
+- `docs/plans/2026-03-21-electron-best-practices-optimization-plan.md`
+- `docs/plans/2026-03-21-vercel-react-best-practices-optimization-plan.md`
+
+后续这份 README 会作为整个 `docs/developer/` 的总索引持续维护。

docs/developer/architecture/README.md

@@ -0,0 +1,107 @@
+# 架构文档索引
+
+本目录收录项目的架构层文档，主要用于帮助开发者建立系统级认知。
+
+如果 `modules/` 关注“某个业务模块怎么工作”，`guides/` 关注“具体开发时怎么做”，那么 `architecture/` 关注的是：
+
+- 项目整体长什么样
+- 运行时是怎么分层的
+- 关键数据流怎么走
+- 核心文件分布在哪里
+- 过去为什么做出某些架构决策
+
+## 推荐阅读顺序
+
+建议按下面顺序阅读：
+
+1. `overview.md`
+2. `runtime-architecture.md`
+3. `data-flow.md`
+4. `file-map.md`
+5. `decision-log.md`
+
+这个顺序基本对应：
+
+- 先建立地图
+- 再理解运行时分层
+- 再看核心数据如何流动
+- 再定位关键文件
+- 最后理解历史决策
+
+## 架构层导航图
+
+```mermaid
+graph TD
+    Architecture[architecture/]
+    Overview[overview.md]
+    Runtime[runtime-architecture.md]
+    DataFlow[data-flow.md]
+    FileMap[file-map.md]
+    Decisions[decision-log.md]
+
+    Architecture --> Overview
+    Architecture --> Runtime
+    Architecture --> DataFlow
+    Architecture --> FileMap
+    Architecture --> Decisions
+```
+
+## 文档职责一览
+
+| 文档 | 主要回答的问题 |
+| --- | --- |
+| `overview.md` | 这个项目整体是什么、做什么、核心目录和主链路是什么 |
+| `runtime-architecture.md` | `main / preload / renderer` 如何协作 |
+| `data-flow.md` | 核心业务数据如何在各层之间流动 |
+| `file-map.md` | 关键文件在哪里、应该先看哪些入口 |
+| `decision-log.md` | 最近几轮重要重构和架构决策是什么 |
+
+## 按问题选择阅读路径
+
+```mermaid
+flowchart TD
+    Question[当前问题]
+    Whole[我想先理解整个项目]
+    RuntimeQ[我想知道进程分层和调用边界]
+    FlowQ[我想知道数据怎么流]
+    FileQ[我想快速定位该看哪些文件]
+    HistoryQ[我想知道为什么现在是这个结构]
+
+    Question --> Whole
+    Question --> RuntimeQ
+    Question --> FlowQ
+    Question --> FileQ
+    Question --> HistoryQ
+
+    Whole --> OverviewDoc[overview.md]
+    RuntimeQ --> RuntimeDoc[runtime-architecture.md]
+    FlowQ --> FlowDoc[data-flow.md]
+    FileQ --> FileDoc[file-map.md]
+    HistoryQ --> DecisionDoc[decision-log.md]
+```
+
+## 与其他目录的关系
+
+```mermaid
+graph LR
+    Architecture[architecture/]
+    Modules[modules/]
+    Guides[guides/]
+
+    Architecture --> Modules
+    Modules --> Guides
+```
+
+理解方式：
+
+- 先通过 `architecture/` 建立系统级认知
+- 再进入 `modules/` 深入业务模块
+- 最后通过 `guides/` 落到开发动作
+
+## 使用建议
+
+- 如果准备改动较大的功能，先看架构层文档再下手
+- 如果遇到“代码都看到了，但不知道该从哪里改”，优先看 `file-map.md`
+- 如果遇到“现在为什么这样设计”，优先看 `decision-log.md`
+
+后续如果新增新的架构层文档，也建议同步更新这份索引页。

docs/developer/architecture/data-flow.md

@@ -0,0 +1,273 @@
+# 数据流
+
+本文档聚焦项目中的核心数据流，帮助开发者理解关键业务数据如何在 `renderer`、`preload`、`main` 和外部系统之间流动。
+
+## 1. 数据流总览
+
+项目中的数据大致分成五类：
+
+- 用户输入数据
+- 页面状态数据
+- IPC 请求与响应数据
+- 主进程领域数据
+- 外部系统数据
+
+整体关系如下：
+
+```mermaid
+graph TD
+    User[用户输入]
+    Renderer[Renderer State]
+    Preload[Preload API]
+    IPC[IPC Handlers]
+    Services[Main Services]
+    External[DB / ERP / Files / Update Source]
+
+    User --> Renderer
+    Renderer --> Preload
+    Preload --> IPC
+    IPC --> Services
+    Services --> External
+    External --> Services
+    Services --> IPC
+    IPC --> Preload
+    Preload --> Renderer
+```
+
+## 2. 提取到清理的主数据流
+
+项目里最核心的一条数据流是：
+
+1. 用户输入订单号
+2. Extractor 执行提取
+3. 共享 Production IDs
+4. Cleaner 基于共享数据做校验
+5. 保存删除计划
+6. 执行 ERP 清理
+7. 生成报告与导出
+
+```mermaid
+flowchart LR
+    Input[订单号输入]
+    Extractor[Extractor 提取]
+    SharedIds[共享 Production IDs]
+    Validation[物料校验]
+    Plan[删除计划]
+    Cleaner[ERP 清理执行]
+    Report[报告 / 导出]
+
+    Input --> Extractor
+    Input --> SharedIds
+    Extractor --> SharedIds
+    SharedIds --> Validation
+    Validation --> Plan
+    Plan --> Cleaner
+    Cleaner --> Report
+```
+
+## 3. Renderer 内部数据流
+
+在 renderer 中，数据通常按下面路径流动：
+
+```mermaid
+flowchart LR
+    UI[页面 / 组件]
+    Hook[Hook]
+    Store[Store / Local State]
+    Bridge[window.electron facade]
+
+    UI --> Hook
+    Hook --> Store
+    Hook --> Bridge
+    Bridge --> Hook
+    Hook --> UI
+```
+
+具体表现为：
+
+- 页面组件负责接收用户输入和渲染状态
+- hook 负责请求编排、局部状态和副作用管理
+- store 负责消息提示、日志或跨组件状态
+- preload facade 负责把 bridge 调用标准化
+
+## 4. Authentication 数据流
+
+认证流程是应用启动时最先发生的一条数据流。
+
+```mermaid
+sequenceDiagram
+    participant App as App / useAppBootstrap
+    participant Preload as preload.auth
+    participant Handler as auth-handler
+    participant AppSvc as auth-application-service
+    participant Session as session-manager
+
+    App->>Preload: getComputerName()
+    App->>Preload: silentLogin()
+    Preload->>Handler: invoke auth channel
+    Handler->>AppSvc: silentLogin()
+    AppSvc->>Session: resolve session / user
+    Session-->>AppSvc: user info
+    AppSvc-->>Handler: login result
+    Handler-->>Preload: IpcResult
+    Preload-->>App: auth state
+```
+
+这条链路最终驱动：
+
+- `UnauthenticatedApp`
+- `AuthenticatedAppShell`
+- 管理员代切用户流程
+
+## 5. Extractor 数据流
+
+Extractor 模块的数据流重点在“订单号输入”和“提取执行结果”。
+
+```mermaid
+sequenceDiagram
+    participant Page as ExtractorPage
+    participant Persist as usePersistentTextState
+    participant Shared as useSharedProductionIds
+    participant Hook as useExtractor
+    participant Preload as preload.extractor / validation
+    participant Main as extractor-handler + services
+
+    Page->>Persist: 保存订单号输入
+    Page->>Shared: debounce 同步共享 Production IDs
+    Page->>Hook: startExtraction(orderNumbers)
+    Hook->>Preload: setSharedProductionIds()
+    Hook->>Preload: runExtractor()
+    Preload->>Main: invoke
+    Main-->>Preload: extraction result
+    Preload-->>Hook: result
+    Hook-->>Page: progress / logs / complete
+```
+
+这里当前有两类数据：
+
+- 持久化输入数据
+  通过 `sessionStorage`
+- 跨模块共享数据
+  通过 `validation` 模块中的 shared production IDs
+
+## 6. Validation / Cleaner 数据流
+
+Cleaner 页面的数据流相对更复杂，包含筛选、校验、选择、保存和执行几个阶段。
+
+```mermaid
+flowchart TD
+    ValidationInput[校验模式 / 共享订单号]
+    Validate[请求校验]
+    Results[validationResults]
+    Filter[filteredResults]
+    Selection[selectedItems]
+    Plan[保存删除计划]
+    Execute[执行 ERP 清理]
+    Progress[progress]
+    Report[执行报告]
+
+    ValidationInput --> Validate
+    Validate --> Results
+    Results --> Filter
+    Results --> Selection
+    Filter --> Selection
+    Selection --> Plan
+    Plan --> Execute
+    Execute --> Progress
+    Execute --> Report
+```
+
+这一块当前的关键状态都集中在：
+
+- `useCleaner`
+- `src/renderer/src/hooks/cleaner/api.ts`
+- `src/renderer/src/hooks/cleaner/helpers.ts`
+
+## 7. Update 数据流
+
+更新模块的数据流分成两部分：
+
+- 被动状态流
+  main 进程通过事件推送状态变化
+- 主动拉取流
+  renderer 在打开对话框或刷新时拉取 catalog / status / changelog
+
+```mermaid
+sequenceDiagram
+    participant Hook as useAppBootstrap
+    participant Dialog as useUpdateDialogState
+    participant Preload as preload.update
+    participant Main as update-handler / update services
+
+    Main->>Preload: onStatusChanged
+    Preload->>Hook: update status event
+    Hook->>Preload: getStatus()
+    Hook->>Preload: getCatalog()
+    Dialog->>Preload: getChangelog(release)
+    Preload->>Main: invoke
+    Main-->>Preload: status / catalog / changelog
+    Preload-->>Hook: normalized result
+    Preload-->>Dialog: changelog content
+```
+
+## 8. 事件推送型数据流
+
+项目中有一部分状态不是通过“请求一次拿一次”获取，而是主进程主动推送。
+
+当前主要推送通道包括：
+
+- cleaner progress
+- extractor progress
+- extractor log
+- update status changed
+
+```mermaid
+flowchart LR
+    MainService[Main Service]
+    EventChannel[IPC Event Channel]
+    PreloadListener[Preload Listener]
+    RendererHook[Renderer Hook]
+    UI[UI]
+
+    MainService --> EventChannel
+    EventChannel --> PreloadListener
+    PreloadListener --> RendererHook
+    RendererHook --> UI
+```
+
+## 9. 配置与持久化数据流
+
+项目中的持久化既包含主进程配置，也包含 renderer 局部偏好。
+
+```mermaid
+graph TD
+    UI[Renderer UI]
+    Hook[Hook / Helper]
+    Session[sessionStorage]
+    ConfigIPC[config API]
+    ConfigSvc[ConfigManager]
+    ConfigFile[config.yaml]
+
+    UI --> Hook
+    Hook --> Session
+    Hook --> ConfigIPC
+    ConfigIPC --> ConfigSvc
+    ConfigSvc --> ConfigFile
+```
+
+当前典型例子：
+
+- `cleaner_dryRun`
+- `cleaner_headless`
+- `cleaner_validationMode`
+- `extractor_orderNumbers`
+
+## 10. 开发建议
+
+在处理数据流时，建议优先遵守这些原则：
+
+- 页面输入态不要直接驱动高频 bridge 副作用
+- 共享数据流要明确谁负责写入、谁负责消费
+- preload 只做 facade，不在 bridge 层堆业务分支
+- handler 只做转发和错误包装
+- 复杂状态流尽量配套时序图或单测

docs/developer/architecture/decision-log.md

@@ -0,0 +1,326 @@
+# 设计决策记录
+
+本文档记录项目中值得被长期记住的关键架构决策。它不追求覆盖所有历史细节，而是保留那些会影响后续开发判断的决定。
+
+## 1. 记录原则
+
+这里主要记录三类决策：
+
+- 影响整体结构的重构决策
+- 影响跨层边界的接口决策
+- 影响后续维护方式的工程化决策
+
+```mermaid
+flowchart LR
+    Problem[问题]
+    Decision[决策]
+    Impact[影响]
+    FollowUp[后续维护]
+
+    Problem --> Decision --> Impact --> FollowUp
+```
+
+## 2. 决策一览
+
+```mermaid
+timeline
+    title 近期关键架构决策
+    2026-03-21 : 主进程 bootstrap 拆分
+               : IPC handler 薄壳化
+               : preload 按 domain 重组
+               : update 模块职责拆分
+               : React App 入口收敛
+               : Cleaner 页面拆分
+               : UpdateDialog 状态收敛
+               : renderer 重型弹窗按需加载
+```
+
+## 3. 主进程入口拆分
+
+### 背景
+
+此前主进程入口承载了过多职责，启动、窗口、运行时检查、IPC 注册和进程守卫都集中在单文件中。
+
+### 决策
+
+将主进程启动相关逻辑拆分到：
+
+- `bootstrap/main-window.ts`
+- `bootstrap/runtime.ts`
+- `bootstrap/process-guards.ts`
+
+### 结果
+
+```mermaid
+graph LR
+    Before[单一 index.ts]
+    After[index.ts + bootstrap/*]
+
+    Before --> After
+```
+
+### 影响
+
+- `index.ts` 更容易读
+- 启动链路更容易定位问题
+- 后续添加启动逻辑不必继续堆到一个入口文件里
+
+## 4. IPC handler 薄壳化
+
+### 背景
+
+部分 handler 曾经承担大量业务编排逻辑，尤其是认证、校验和清理流程。
+
+### 决策
+
+把核心编排下沉到 application service，handler 保持为薄壳。
+
+当前典型结构：
+
+```mermaid
+graph TD
+    Handler[IPC Handler]
+    AppService[Application Service]
+    Domain[Domain Service]
+
+    Handler --> AppService --> Domain
+```
+
+### 影响
+
+- handler 更容易测试
+- 业务逻辑更容易复用
+- 主进程边界更清晰
+
+## 5. Validation 模块拆分
+
+### 背景
+
+`validation-handler` 曾同时承担 IPC、共享状态、数据库分支、SQL 拼接和数据富化。
+
+### 决策
+
+将职责拆分到独立模块：
+
+- `shared-production-ids-store.ts`
+- `validation-database.ts`
+- `production-input-service.ts`
+- `validation-application-service.ts`
+
+### 结果
+
+```mermaid
+graph TD
+    Handler[validation-handler]
+    Store[shared-production-ids-store]
+    DB[validation-database]
+    Input[production-input-service]
+    AppSvc[validation-application-service]
+
+    Handler --> Store
+    Handler --> AppSvc
+    AppSvc --> DB
+    AppSvc --> Input
+```
+
+### 影响
+
+- 共享订单号状态不再埋在 handler 中
+- 数据库与输入识别边界更清晰
+- 后续校验链路文档化和测试化更容易
+
+## 6. Preload 按领域重组
+
+### 背景
+
+preload 曾接近一个“大接口总表”，内部职责不够清晰。
+
+### 决策
+
+将 preload 改为按 domain 组织：
+
+- `api/auth.ts`
+- `api/cleaner.ts`
+- `api/extractor.ts`
+- `api/validation.ts`
+- `api/materials.ts`
+- `api/process.ts`
+- `api/logger.ts`
+
+### 结果
+
+```mermaid
+graph LR
+    Before[单体 preload]
+    After[domain preload APIs]
+
+    Before --> After
+```
+
+### 影响
+
+- renderer 使用的 bridge 更有语义
+- preload 更适合继续维护
+- 类型边界更稳定
+
+## 7. Update 模块拆分
+
+### 背景
+
+更新服务长期承担目录拉取、状态广播、下载、安装和版本决策等多类职责。
+
+### 决策
+
+将 update 模块拆成多个协作者：
+
+- `update-service.ts`
+- `update-catalog-service.ts`
+- `update-installer.ts`
+- `update-storage-client.ts`
+- `update-status-publisher.ts`
+- `update-support.ts`
+
+### 结果
+
+```mermaid
+graph TD
+    UpdateService[UpdateService]
+    Catalog[UpdateCatalogService]
+    Installer[UpdateInstaller]
+    Storage[UpdateStorageClient]
+    Publisher[UpdateStatusPublisher]
+
+    UpdateService --> Catalog
+    UpdateService --> Installer
+    UpdateService --> Storage
+    UpdateService --> Publisher
+```
+
+### 影响
+
+- 更新职责边界更清晰
+- 测试粒度更细
+- 维护内部更新逻辑的成本下降
+
+## 8. React 入口收敛
+
+### 背景
+
+`App.tsx` 曾同时承担认证启动、更新状态刷新、导航、未认证态和已认证态 UI。
+
+### 决策
+
+拆出：
+
+- `useAppBootstrap.ts`
+- `AuthenticatedAppShell.tsx`
+- `UnauthenticatedApp.tsx`
+
+### 影响
+
+- 入口组件回归组装层
+- 认证与更新状态更容易追踪
+- 后续页面和对话框拆分更容易
+
+## 9. Cleaner 页面拆分
+
+### 背景
+
+`CleanerPage` 曾是典型的大页面，包含筛选区、工具栏、表格、执行区和多个弹窗。
+
+### 决策
+
+拆分出：
+
+- `CleanerSidebar.tsx`
+- `CleanerToolbar.tsx`
+- `CleanerResultsTable.tsx`
+- `CleanerExecutionBar.tsx`
+
+### 结果
+
+```mermaid
+graph TD
+    CleanerPage[CleanerPage]
+    Sidebar[Sidebar]
+    Toolbar[Toolbar]
+    Table[ResultsTable]
+    Bar[ExecutionBar]
+
+    CleanerPage --> Sidebar
+    CleanerPage --> Toolbar
+    CleanerPage --> Table
+    CleanerPage --> Bar
+```
+
+### 影响
+
+- 页面阅读成本下降
+- UI 结构更清楚
+- 后续继续拆 `useCleaner` 更安全
+
+## 10. UpdateDialog 状态收敛
+
+### 背景
+
+更新弹窗里选中版本和 changelog 请求状态容易产生旧请求覆盖新状态的问题。
+
+### 决策
+
+新增：
+
+- `useUpdateDialogState.ts`
+
+并把 changelog 请求保护和选中版本逻辑集中到 hook 中。
+
+### 影响
+
+- 异步状态更稳定
+- 版本切换逻辑更容易测试
+
+## 11. Renderer 重型弹窗按需加载
+
+### 背景
+
+多个重型弹窗并不是首屏关键路径，但此前会参与静态导入。
+
+### 决策
+
+对这些组件使用 `React.lazy + Suspense`：
+
+- `UpdateDialog`
+- `MaterialTypeManagementDialog`
+- `ExecutionReportDialog`
+- `ReportViewerDialog`
+
+### 结果
+
+```mermaid
+graph LR
+    Static[静态导入]
+    Lazy[按需加载]
+
+    Static --> Lazy
+```
+
+### 影响
+
+- renderer 初始负担下降
+- 常用主流程更轻
+
+## 12. 后续记录方式
+
+后续新增重大决策时，建议按这个格式补充：
+
+1. 背景
+2. 决策
+3. 结果图
+4. 影响
+5. 相关文件
+
+建议记录的场景包括：
+
+- 新增跨层通信机制
+- 重构核心模块边界
+- 修改更新、认证、校验、清理主链路
+- 引入新的状态管理或测试策略

docs/developer/architecture/file-map.md

@@ -0,0 +1,288 @@
+# 文件地图
+
+本文档提供一个“高频核心文件地图”，帮助开发者快速定位项目里最值得先看的文件，而不是在目录树里盲找。
+
+## 1. 快速定位图
+
+```mermaid
+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 启动与窗口
+
+```mermaid
+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 注册层
+
+```mermaid
+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 核心服务层
+
+```mermaid
+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 现在已经按领域组织。
+
+```mermaid
+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`
+
+```mermaid
+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 相关
+
+```mermaid
+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. 测试文件地图
+
+```mermaid
+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. 阅读建议
+
+不同任务建议优先看不同文件：
+
+```mermaid
+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]
+```

docs/developer/architecture/overview.md

@@ -0,0 +1,273 @@
+# 项目总览
+
+本文档用于帮助开发者快速建立对项目的整体认知，包括系统目标、核心能力、目录结构和主要运行路径。
+
+## 1. 项目定位
+
+`ERPAuto` 是一个基于 Electron + React + TypeScript 构建的内部桌面工具，主要用于辅助 ERP 相关的数据提取、校验、清理、配置和更新管理。
+
+当前项目的核心业务能力主要包括：
+
+- 批量提取 ERP 数据并导入本地数据库
+- 基于数据库和共享订单号进行物料校验
+- 执行 ERP 物料清理与结果导出
+- 用户认证、管理员代切用户
+- 桌面端应用更新
+- 本地配置、日志、报告与文件处理
+
+项目可以先粗略理解成下面这张图：
+
+```mermaid
+mindmap
+  root((ERPAuto))
+    数据提取
+      订单号输入
+      批量导出
+      导入数据库
+    物料校验与清理
+      共享 Production IDs
+      校验结果
+      删除计划
+      ERP 执行
+      执行报告
+    用户与权限
+      silent login
+      管理员代切用户
+    系统能力
+      配置
+      日志
+      更新
+      报告
+```
+
+## 2. 技术栈概览
+
+- 桌面容器：Electron
+- 前端渲染：React 19
+- 构建工具：electron-vite / Vite
+- 语言：TypeScript
+- 样式：Tailwind CSS
+- 测试：Vitest / Playwright
+- 数据库：MySQL / SQL Server
+- 自动化：Playwright
+
+## 3. 顶层结构
+
+项目核心代码主要分布在这几个目录：
+
+- `src/main/`
+  Electron 主进程，负责窗口、IPC、服务编排、配置、日志、更新、ERP 相关主流程。
+- `src/preload/`
+  preload bridge，向 renderer 暴露按领域组织的安全 API facade。
+- `src/renderer/src/`
+  React 渲染层，负责页面、组件、hooks、状态管理和交互流程。
+- `tests/`
+  单元测试、集成测试、e2e 和手工测试。
+- `docs/`
+  项目说明、执行计划、架构文档和后续维护文档。
+
+也可以从目录责任关系上理解：
+
+```mermaid
+graph TD
+    Root[项目根目录]
+    Main[src/main]
+    Preload[src/preload]
+    Renderer[src/renderer/src]
+    Tests[tests]
+    Docs[docs]
+
+    Root --> Main
+    Root --> Preload
+    Root --> Renderer
+    Root --> Tests
+    Root --> Docs
+
+    Main --> MainDesc[主进程与服务执行]
+    Preload --> PreloadDesc[桥接 API 与 IPC 封装]
+    Renderer --> RendererDesc[页面 组件 Hooks 状态]
+    Tests --> TestsDesc[单测 集成 E2E]
+    Docs --> DocsDesc[说明 计划 开发文档]
+```
+
+## 4. 运行时分层
+
+项目运行时可简单理解为三层：
+
+```mermaid
+graph LR
+    Renderer[Renderer / React]
+    Preload[Preload API Facade]
+    Main[Main Process Services]
+
+    Renderer --> Preload
+    Preload --> Main
+```
+
+职责划分如下：
+
+- `renderer`
+  负责页面展示、用户交互、状态管理和流程触发。
+- `preload`
+  负责把 IPC 能力整理成前端可用的 API facade。
+- `main`
+  负责真正的业务执行、数据库访问、ERP 自动化、文件和更新处理。
+
+从用户操作到系统执行的主路径如下：
+
+```mermaid
+flowchart LR
+    User[用户操作]
+    Page[React 页面]
+    Hook[页面 Hook]
+    Preload[Preload API]
+    Handler[IPC Handler]
+    Service[Main Service]
+    External[数据库 / ERP / 文件 / 更新源]
+
+    User --> Page
+    Page --> Hook
+    Hook --> Preload
+    Preload --> Handler
+    Handler --> Service
+    Service --> External
+```
+
+## 5. 当前核心页面
+
+当前渲染层主要有三个业务页面：
+
+- `ExtractorPage`
+  负责订单号输入、批量提取和提取日志展示。
+- `CleanerPage`
+  负责物料校验、负责人分配、删除计划保存、ERP 清理执行与结果查看。
+- `SettingsPage`
+  负责系统设置与配置维护。
+
+应用入口在：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/components/app/AuthenticatedAppShell.tsx`
+- `src/renderer/src/components/app/UnauthenticatedApp.tsx`
+
+页面级结构可以简化为：
+
+```mermaid
+graph TD
+    App[App.tsx]
+    Unauth[UnauthenticatedApp]
+    Shell[AuthenticatedAppShell]
+    Extractor[ExtractorPage]
+    Cleaner[CleanerPage]
+    Settings[SettingsPage]
+
+    App --> Unauth
+    App --> Shell
+    Shell --> Extractor
+    Shell --> Cleaner
+    Shell --> Settings
+```
+
+## 6. 当前主进程结构
+
+主进程侧目前已经按职责拆成几类目录：
+
+- `bootstrap/`
+  应用启动、窗口创建、进程守卫、运行时初始化。
+- `ipc/`
+  IPC handler 注册与调用入口。
+- `services/`
+  具体业务服务实现，按领域组织。
+- `types/`
+  主进程与 preload/renderer 共享的类型定义。
+
+`services/` 当前主要领域包括：
+
+- `auth`
+- `cleaner`
+- `config`
+- `database`
+- `erp`
+- `excel`
+- `logger`
+- `report`
+- `rustfs`
+- `update`
+- `user`
+- `validation`
+
+主进程结构关系如下：
+
+```mermaid
+graph TD
+    MainIndex[index.ts]
+    Bootstrap[bootstrap/]
+    IPC[ipc/]
+    Services[services/]
+    Types[types/]
+
+    MainIndex --> Bootstrap
+    MainIndex --> IPC
+    IPC --> Services
+    Services --> Types
+    IPC --> Types
+```
+
+## 7. 关键业务链路
+
+项目最重要的几条业务链路可以概括为：
+
+```mermaid
+graph TD
+    A[登录与认证]
+    B[订单号提取]
+    C[共享 Production IDs]
+    D[物料校验]
+    E[删除计划保存]
+    F[ERP 清理执行]
+    G[报告与导出]
+    H[应用更新]
+
+    A --> B
+    B --> C
+    C --> D
+    D --> E
+    E --> F
+    F --> G
+    A --> H
+```
+
+## 8. 目录阅读建议
+
+如果你是第一次进入代码库，建议按下面顺序读：
+
+1. `src/main/index.ts`
+2. `src/main/bootstrap/`
+3. `src/preload/index.ts`
+4. `src/renderer/src/App.tsx`
+5. `src/renderer/src/pages/`
+6. 对应业务模块的 `src/main/ipc/` 和 `src/main/services/`
+
+阅读路径也可以理解成：
+
+```mermaid
+flowchart TD
+    A[src/main/index.ts]
+    B[src/main/bootstrap]
+    C[src/preload/index.ts]
+    D[src/renderer/src/App.tsx]
+    E[src/renderer/src/pages]
+    F[src/main/ipc]
+    G[src/main/services]
+
+    A --> B --> C --> D --> E --> F --> G
+```
+
+## 9. 相关文档
+
+继续阅读建议：
+
+- `runtime-architecture.md`
+  了解 `main / preload / renderer` 的分层与调用关系。
+- 后续 `modules/` 目录中的模块文档
+  深入理解各业务模块。

docs/developer/architecture/runtime-architecture.md

@@ -0,0 +1,381 @@
+# 运行时架构
+
+本文档说明项目在运行时的主要分层、进程边界和核心调用路径，帮助开发者理解请求是如何从 React 页面一路进入主进程服务的。
+
+## 1. 运行时结构
+
+项目运行时由三部分组成：
+
+- Electron `main` 进程
+- Electron `preload`
+- Electron `renderer` 渲染进程
+
+它们之间的关系如下：
+
+```mermaid
+graph LR
+    Renderer[Renderer\nReact Pages / Hooks / Components]
+    Preload[Preload\nDomain APIs + IPC Wrapper]
+    IPC[IPC Handlers]
+    Services[Main Services]
+    External[DB / ERP / Files / Update Source]
+
+    Renderer --> Preload
+    Preload --> IPC
+    IPC --> Services
+    Services --> External
+```
+
+如果从 Electron 的进程边界来理解，可以进一步看成：
+
+```mermaid
+flowchart LR
+    subgraph RendererProcess[Renderer Process]
+        UI[Pages / Components]
+        Hooks[Hooks / Stores]
+    end
+
+    subgraph PreloadLayer[Preload Layer]
+        Facade[Domain APIs]
+        IPCClient[ipc wrapper]
+    end
+
+    subgraph MainProcess[Main Process]
+        Bootstrap[Bootstrap]
+        Handlers[IPC Handlers]
+        DomainServices[Domain Services]
+    end
+
+    UI --> Hooks
+    Hooks --> Facade
+    Facade --> IPCClient
+    IPCClient --> Handlers
+    Handlers --> DomainServices
+    Bootstrap --> Handlers
+```
+
+## 2. Main 进程
+
+主进程是应用的执行中心，负责：
+
+- 应用启动和窗口创建
+- 进程守卫和异常处理
+- IPC 注册
+- 配置、日志、数据库、文件、更新等系统能力
+- ERP 自动化与业务流程执行
+
+关键入口文件：
+
+- `src/main/index.ts`
+- `src/main/bootstrap/main-window.ts`
+- `src/main/bootstrap/runtime.ts`
+- `src/main/bootstrap/process-guards.ts`
+
+### 2.1 Bootstrap 层
+
+`bootstrap/` 负责把主进程入口收敛成薄启动文件。
+
+当前主要模块：
+
+- `main-window.ts`
+  创建 `BrowserWindow`，配置窗口行为与生命周期。
+- `runtime.ts`
+  负责运行时初始化、服务初始化和 IPC 注册。
+- `process-guards.ts`
+  负责全局异常、未处理拒绝和进程级兜底。
+
+bootstrap 层内部关系如下：
+
+```mermaid
+graph TD
+    Index[index.ts]
+    Guards[process-guards.ts]
+    Runtime[runtime.ts]
+    Window[main-window.ts]
+    AppReady[app.whenReady]
+
+    Index --> Guards
+    Index --> AppReady
+    AppReady --> Runtime
+    AppReady --> Window
+```
+
+### 2.2 IPC 层
+
+`src/main/ipc/` 中的 handler 负责注册 IPC 通道，并把请求转发到应用服务或领域服务。
+
+当前主要 handler 包括：
+
+- `auth-handler.ts`
+- `cleaner-handler.ts`
+- `extractor-handler.ts`
+- `validation-handler.ts`
+- `update-handler.ts`
+- `settings-handler.ts`
+- `report-handler.ts`
+
+当前设计目标是：handler 尽量保持“薄壳”，只做参数接收、错误包装和 service 转发。
+
+这层的目标结构是：
+
+```mermaid
+graph LR
+    Request[IPC Request]
+    Handler[Handler]
+    AppService[Application Service]
+    DomainService[Domain Service / Repository]
+    Response[IpcResult Response]
+
+    Request --> Handler
+    Handler --> AppService
+    AppService --> DomainService
+    DomainService --> AppService
+    AppService --> Handler
+    Handler --> Response
+```
+
+### 2.3 Services 层
+
+`src/main/services/` 是主进程的核心实现层。
+
+主要领域：
+
+- `auth/`
+  用户登录、silent login、用户切换。
+- `cleaner/`
+  ERP 清理执行编排。
+- `update/`
+  更新目录拉取、状态广播、下载和安装。
+- `validation/`
+  物料校验、共享订单号、数据库查询封装。
+- `config/`
+  配置加载与保存。
+- `logger/`
+  日志服务。
+- `report/`
+  报告查询与下载。
+
+当前主进程服务从领域上大致可视化为：
+
+```mermaid
+graph TD
+    Services[services/]
+    Auth[auth]
+    Validation[validation]
+    Cleaner[cleaner]
+    Update[update]
+    Config[config]
+    ERP[erp]
+    Report[report]
+    Logger[logger]
+
+    Services --> Auth
+    Services --> Validation
+    Services --> Cleaner
+    Services --> Update
+    Services --> Config
+    Services --> ERP
+    Services --> Report
+    Services --> Logger
+```
+
+## 3. Preload 层
+
+preload 是 renderer 与 main 之间的桥接层，负责把 IPC 能力封装成按领域组织的 API。
+
+关键入口文件：
+
+- `src/preload/index.ts`
+- `src/preload/index.d.ts`
+
+当前 preload 内部结构：
+
+- `src/preload/api/`
+  按领域拆分的 API facade
+- `src/preload/lib/ipc.ts`
+  统一的 IPC 调用封装
+
+当前已经拆分出的 API 模块包括：
+
+- `auth.ts`
+- `cleaner.ts`
+- `database.ts`
+- `extractor.ts`
+- `file.ts`
+- `logger.ts`
+- `materials.ts`
+- `process.ts`
+- `resolver.ts`
+- `validation.ts`
+
+preload 组织方式如下：
+
+```mermaid
+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]
+    UpdateLike[api/process.ts / logger.ts / file.ts]
+
+    Preload --> API
+    API --> Auth
+    API --> Cleaner
+    API --> Extractor
+    API --> Validation
+    API --> UpdateLike
+    API --> IPC
+```
+
+preload 的职责不是承载业务，而是：
+
+- 隐藏 IPC 细节
+- 为 renderer 提供稳定的调用接口
+- 维持类型边界
+
+## 4. Renderer 层
+
+renderer 是 React 应用本体，负责页面展示、交互和前端状态管理。
+
+关键入口文件：
+
+- `src/renderer/src/main.tsx`
+- `src/renderer/src/App.tsx`
+
+当前主要目录：
+
+- `pages/`
+  页面级容器，例如 `ExtractorPage`、`CleanerPage`、`SettingsPage`
+- `components/`
+  通用 UI、业务组件、对话框
+- `hooks/`
+  页面逻辑、状态收敛、bridge 调用编排
+- `stores/`
+  状态存储与消息提示
+- `lib/`
+  前端侧辅助工具和持久化 helper
+
+renderer 层当前结构可以简化为：
+
+```mermaid
+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
+```
+
+## 5. 一次典型调用链
+
+以 Cleaner 校验流程为例，一次从页面到主进程的调用链大致如下：
+
+```mermaid
+sequenceDiagram
+    participant UI as CleanerPage / useCleaner
+    participant Preload as preload.validation
+    participant IPC as validation-handler
+    participant AppSvc as validation-application-service
+    participant DB as database / repository
+
+    UI->>Preload: validate(request)
+    Preload->>IPC: ipcRenderer.invoke(...)
+    IPC->>AppSvc: service.validate(...)
+    AppSvc->>DB: query / enrich / aggregate
+    DB-->>AppSvc: validation results
+    AppSvc-->>IPC: payload
+    IPC-->>Preload: IpcResult
+    Preload-->>UI: normalized response
+```
+
+## 6. 页面与模块关系
+
+当前主要页面与主进程模块的对应关系大致如下：
+
+- `ExtractorPage`
+  对应 `extractor`、`validation`
+- `CleanerPage`
+  对应 `validation`、`cleaner`、`materials`、`report`
+- `SettingsPage`
+  对应 `settings`、`config`
+- `UpdateDialog`
+  对应 `update`
+
+```mermaid
+graph LR
+    ExtractorPage --> ExtractorSvc[extractor / validation]
+    CleanerPage --> CleanerSvc[validation / cleaner / report]
+    SettingsPage --> SettingsSvc[settings / config]
+    UpdateDialog --> UpdateSvc[update]
+```
+
+## 7. 事件与状态流
+
+项目里常见的状态流主要有三类：
+
+- 页面内局部状态
+  例如表单输入、当前选中项、弹窗开关。
+- preload bridge 调用结果
+  例如查询结果、校验结果、更新目录。
+- 主进程主动推送事件
+  例如 cleaner 执行进度、update 状态变化。
+
+当前典型事件订阅点包括：
+
+- `window.electron.cleaner.onProgress(...)`
+- `window.electron.update.onStatusChanged(...)`
+- `window.electron.extractor.onProgress(...)`
+- `window.electron.extractor.onLog(...)`
+
+事件流可以概括成：
+
+```mermaid
+sequenceDiagram
+    participant Main as Main Service
+    participant IPC as IPC / Preload
+    participant Hook as Renderer Hook
+    participant UI as React UI
+
+    Main->>IPC: push progress/status
+    IPC->>Hook: onProgress / onStatusChanged
+    Hook->>UI: update state
+    UI->>UI: rerender
+```
+
+## 8. 当前架构特点
+
+当前项目运行时架构有几个比较明显的特点：
+
+- 主进程侧已经完成一轮职责收敛，bootstrap、handler、service 边界更清晰
+- preload 已从大文件重组为按领域组织的 facade
+- renderer 正在从“大页面 + 大 hook”逐步收敛为更小的页面边界
+- 更新模块、validation 模块、Cleaner 页面都已经完成阶段性重构
+
+## 9. 开发建议
+
+在这个运行时架构下，建议按下面原则进行开发：
+
+- 新业务优先落在 main service，而不是直接堆到 handler
+- renderer 不直接感知 IPC channel，统一走 preload facade
+- 页面容器尽量只负责组装，复杂流程下沉到 hook
+- 共享类型优先放在稳定的 `types/` 目录
+- 重要状态流尽量画出调用链或补单测
+
+## 10. 后续阅读
+
+如果你已经理解了运行时分层，下一步建议继续读：
+
+- 后续的 `modules/cleaner.md`
+- 后续的 `modules/extractor.md`
+- 后续的 `modules/validation.md`
+- 后续的 `modules/update.md`

docs/developer/guides/README.md

@@ -0,0 +1,114 @@
+# 开发指南索引
+
+本目录收录“开发者实际做事时会用到的指南文档”。
+
+如果 `architecture/` 负责解释系统是什么，`modules/` 负责解释模块怎么工作，那么 `guides/` 负责回答：
+
+- 本地怎么启动
+- 出问题怎么调试
+- 怎么新增或修改 IPC
+- 怎么开发 renderer
+- 怎么构建和发布
+
+## 阅读建议
+
+如果你是第一次参与这个项目的开发，推荐按下面顺序阅读：
+
+1. `local-development.md`
+2. `debugging.md`
+3. `renderer-development.md`
+4. `ipc-development.md`
+5. `release-process.md`
+
+## 指南地图
+
+```mermaid
+graph TD
+    Guides[guides/]
+    Local[local-development]
+    Debug[debugging]
+    Renderer[renderer-development]
+    IPC[ipc-development]
+    Release[release-process]
+
+    Guides --> Local
+    Guides --> Debug
+    Guides --> Renderer
+    Guides --> IPC
+    Guides --> Release
+```
+
+## 按任务查阅
+
+你可以按当前任务来选文档：
+
+```mermaid
+flowchart TD
+    Task[当前任务]
+    Start[启动项目]
+    Fix[排查问题]
+    UI[修改前端]
+    Bridge[修改 IPC]
+    Ship[构建 / 发布]
+
+    Task --> Start
+    Task --> Fix
+    Task --> UI
+    Task --> Bridge
+    Task --> Ship
+
+    Start --> LocalDoc[local-development.md]
+    Fix --> DebugDoc[debugging.md]
+    UI --> RendererDoc[renderer-development.md]
+    Bridge --> IPCDoc[ipc-development.md]
+    Ship --> ReleaseDoc[release-process.md]
+```
+
+## 当前文档一览
+
+| 文档 | 主要内容 |
+| --- | --- |
+| `local-development.md` | 环境准备、启动、构建、常用命令、本地验证 |
+| `debugging.md` | 分层调试思路、调试入口、主链路定位方法 |
+| `renderer-development.md` | React 渲染层开发方式、页面/hook/组件边界 |
+| `ipc-development.md` | 新增或修改 IPC 能力的推荐实现路径 |
+| `release-process.md` | 构建、发布、更新产物与上传流程 |
+
+## 与其他文档目录的关系
+
+```mermaid
+graph LR
+    Architecture[architecture/]
+    Modules[modules/]
+    Guides[guides/]
+
+    Architecture --> Modules
+    Modules --> Guides
+```
+
+理解方式：
+
+- 先看 `architecture/`
+  建立系统级认知
+- 再看 `modules/`
+  理解业务边界
+- 最后看 `guides/`
+  落到具体开发动作
+
+## 使用建议
+
+- 改代码前，先看对应模块文档，再看对应 guide
+- 如果是跨层改动，优先先看 `ipc-development.md`
+- 如果是页面交互问题，优先结合 `renderer-development.md` 与模块文档一起看
+- 如果是运行时问题，优先从 `debugging.md` 开始
+
+## 后续可继续补充的指南
+
+随着文档继续完善，后续可以考虑新增：
+
+- `testing.md`
+- `database-development.md`
+- `erp-automation.md`
+- `config-management.md`
+
+后续新增指南时，建议同步更新这份索引页，让它持续作为 `guides/` 的入口文档。

docs/developer/guides/debugging.md

@@ -0,0 +1,189 @@
+# 调试指南
+
+本文档说明项目里最常见的调试入口、日志观察方式和问题定位路径。
+
+## 1. 调试总览
+
+```mermaid
+flowchart TD
+    Problem[出现问题]
+    Area{问题在哪一层}
+    Renderer[Renderer]
+    Preload[Preload / IPC]
+    Main[Main / Services]
+    External[ERP / DB / Update]
+
+    Problem --> Area
+    Area --> Renderer
+    Area --> Preload
+    Area --> Main
+    Area --> External
+```
+
+## 2. 常见调试入口
+
+项目里当前有几个现成的调试入口：
+
+```bash
+npm run debug:erp-login
+npm run debug:config-path
+npm run test:rustfs
+```
+
+对应文件：
+
+- `src/main/tools/erp-login-debug.ts`
+- `src/main/tools/config-path-debug.ts`
+- `src/main/tools/rustfs-test.ts`
+
+## 3. 调试分层思路
+
+### 3.1 Renderer 问题
+
+适合从这里开始：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/pages/*`
+- `src/renderer/src/hooks/*`
+
+常见现象：
+
+- 页面不更新
+- 弹窗打不开
+- 表单状态异常
+- 请求重复触发
+
+### 3.2 Preload / IPC 问题
+
+```mermaid
+graph LR
+    Renderer --> Preload
+    Preload --> Handler
+    Handler --> Service
+```
+
+定位顺序建议：
+
+1. renderer 是否正确调用 `window.electron.xxx`
+2. preload facade 是否暴露了正确接口
+3. handler 是否已注册
+4. service 是否返回了预期结构
+
+### 3.3 Main 进程问题
+
+适合从这里开始：
+
+- `src/main/index.ts`
+- `src/main/bootstrap/*`
+- `src/main/ipc/*`
+- `src/main/services/*`
+
+常见现象：
+
+- 启动失败
+- 数据库连接失败
+- ERP 登录失败
+- 更新检查失败
+
+## 4. Cleaner 调试路径
+
+```mermaid
+flowchart TD
+    CleanerIssue[Cleaner 问题]
+    UI[CleanerPage / useCleaner]
+    Validation[validation-handler / service]
+    Handler[cleaner-handler]
+    AppSvc[cleaner-application-service]
+    ERP[erp/cleaner.ts]
+    Report[report / rustfs]
+
+    CleanerIssue --> UI
+    UI --> Validation
+    Validation --> Handler
+    Handler --> AppSvc
+    AppSvc --> ERP
+    ERP --> Report
+```
+
+## 5. Extractor 调试路径
+
+```mermaid
+flowchart TD
+    ExtractorIssue[Extractor 问题]
+    Input[ExtractorPage / OrderNumberInput]
+    Hook[useExtractor]
+    Shared[useSharedProductionIds]
+    Handler[extractor-handler]
+    Service[erp/extractor.ts]
+
+    ExtractorIssue --> Input
+    Input --> Hook
+    Input --> Shared
+    Hook --> Handler
+    Handler --> Service
+```
+
+## 6. Update 调试路径
+
+```mermaid
+flowchart TD
+    UpdateIssue[Update 问题]
+    Hook[useAppBootstrap]
+    Dialog[UpdateDialog / useUpdateDialogState]
+    Handler[update-handler]
+    Service[UpdateService]
+    Catalog[UpdateCatalogService]
+    Installer[UpdateInstaller]
+    Storage[UpdateStorageClient]
+
+    UpdateIssue --> Hook
+    UpdateIssue --> Dialog
+    Hook --> Handler
+    Dialog --> Handler
+    Handler --> Service
+    Service --> Catalog
+    Service --> Installer
+    Service --> Storage
+```
+
+## 7. 认证调试路径
+
+```mermaid
+sequenceDiagram
+    participant App as useAppBootstrap
+    participant Auth as auth-handler
+    participant AppSvc as auth-application-service
+    participant Session as session-manager
+
+    App->>Auth: silentLogin / login / switchUser
+    Auth->>AppSvc: application service
+    AppSvc->>Session: user resolution
+    Session-->>AppSvc: session result
+    AppSvc-->>Auth: response
+    Auth-->>App: auth state
+```
+
+## 8. 日志观察建议
+
+调试时优先关注：
+
+- renderer 控制台输出
+- main 进程日志
+- 关键 application service 的 logger 输出
+- audit log（如果问题涉及登录、清理等操作记录）
+
+## 9. 定位建议
+
+出现问题时，建议优先回答这几个问题：
+
+1. 问题发生在哪一层
+2. 是状态流问题还是外部依赖问题
+3. 是请求没发出、没到 handler，还是 service 失败
+4. 是同步返回问题，还是事件推送问题
+
+## 10. 调试原则
+
+- 先缩小层级，再深入代码
+- 先看入口与边界，再看实现细节
+- 能复现就尽量用最小路径复现
+- 复杂主链路优先画调用链再改代码

docs/developer/guides/ipc-development.md

@@ -0,0 +1,159 @@
+# IPC 开发指南
+
+本文档说明在项目中新增或修改一个 IPC 能力时，推荐的实现路径和注意事项。
+
+## 1. IPC 开发原则
+
+当前项目的 IPC 目标结构是：
+
+```mermaid
+graph LR
+    Renderer[Renderer]
+    Preload[Preload Facade]
+    Handler[IPC Handler]
+    AppService[Application Service]
+    Domain[Domain Service / DAO]
+
+    Renderer --> Preload --> Handler --> AppService --> Domain
+```
+
+原则：
+
+- renderer 不直接感知 IPC channel 细节
+- preload 负责 facade 化
+- handler 保持薄壳
+- 业务逻辑尽量放到 application service 或 domain service
+
+## 2. 新增一个 IPC 能力的推荐步骤
+
+```mermaid
+flowchart TD
+    Need[需要新增能力]
+    Types[定义类型]
+    Service[实现 service]
+    Handler[注册 handler]
+    Preload[暴露 preload API]
+    Renderer[接入 renderer]
+    Test[补测试]
+
+    Need --> Types --> Service --> Handler --> Preload --> Renderer --> Test
+```
+
+## 3. 第一步：定义类型
+
+优先在稳定类型层定义：
+
+- request 类型
+- response 类型
+- preload 暴露面类型
+
+常见位置：
+
+- `src/main/types/`
+- `src/preload/index.d.ts`
+
+## 4. 第二步：实现 service
+
+如果能力有实际业务逻辑，优先先写 service。
+
+不要直接把逻辑堆到 handler 里。
+
+示意结构：
+
+```mermaid
+graph TD
+    Request[Request]
+    Handler[Handler]
+    Service[Application Service]
+    Repo[Repository / DAO]
+    Response[Response]
+
+    Request --> Handler
+    Handler --> Service
+    Service --> Repo
+    Repo --> Service
+    Service --> Handler
+    Handler --> Response
+```
+
+## 5. 第三步：注册 handler
+
+常见位置：
+
+- `src/main/ipc/<module>-handler.ts`
+- `src/main/ipc/index.ts`
+
+handler 里建议只做：
+
+- 接收参数
+- 转发给 service
+- 用统一错误包装返回 `IpcResult`
+
+## 6. 第四步：接到 preload
+
+常见位置：
+
+- `src/preload/api/<module>.ts`
+- `src/preload/api/index.ts`
+- `src/preload/index.d.ts`
+
+preload 的职责是把主进程能力变成 renderer 可调用的 facade，而不是承载业务判断。
+
+## 7. 第五步：接到 renderer
+
+renderer 侧通常有两种接法：
+
+- 直接在页面 hook 中调用
+- 先落一层 hook / helper，再被页面使用
+
+建议优先把复杂调用路径集中到 hook。
+
+## 8. 典型示例路径
+
+以一个校验相关能力为例：
+
+```mermaid
+sequenceDiagram
+    participant UI as useCleaner / useValidation
+    participant Preload as preload.validation
+    participant Handler as validation-handler
+    participant AppSvc as validation-application-service
+
+    UI->>Preload: validate(request)
+    Preload->>Handler: invoke
+    Handler->>AppSvc: validate(...)
+    AppSvc-->>Handler: response
+    Handler-->>Preload: IpcResult
+    Preload-->>UI: normalized result
+```
+
+## 9. 修改 IPC 时优先检查的文件
+
+- `src/main/ipc/index.ts`
+- `src/main/ipc/<module>-handler.ts`
+- `src/main/services/<module>/...`
+- `src/preload/api/<module>.ts`
+- `src/preload/api/index.ts`
+- `src/preload/index.d.ts`
+- renderer 对应 hook / page
+
+## 10. 测试建议
+
+如果是新增 IPC 能力，建议至少补：
+
+- handler 单测
+- application service 单测
+- preload surface 或 renderer 状态测试（视复杂度而定）
+
+## 11. 常见反模式
+
+- 直接在页面里拼 IPC channel
+- handler 里写完整业务流程
+- preload 里堆业务分支
+- 改了主进程返回结构但不更新 renderer 类型
+
+## 12. 实践建议
+
+- 优先复用现有领域模块
+- 先想边界，再写调用
+- 先让主进程能力清晰，再接 renderer

docs/developer/guides/local-development.md

@@ -0,0 +1,193 @@
+# 本地开发指南
+
+本文档说明如何在本地启动、检查、构建和验证项目。
+
+## 1. 开发环境概览
+
+```mermaid
+flowchart LR
+    Clone[拉取代码]
+    Install[安装依赖]
+    Config[准备配置]
+    Dev[启动开发环境]
+    Verify[类型检查 / lint / 测试]
+
+    Clone --> Install --> Config --> Dev --> Verify
+```
+
+## 2. 基础要求
+
+- Node.js >= 18
+- npm >= 9
+- 本地可访问 ERP 系统
+- 可访问 MySQL 或 SQL Server
+
+## 3. 安装依赖
+
+```bash
+npm install
+```
+
+## 4. 准备配置
+
+项目使用 `config.yaml` 作为主配置文件。
+
+```mermaid
+graph TD
+    Config[config.yaml]
+    ERP[ERP URL]
+    DB[数据库配置]
+    Update[更新配置]
+    Paths[路径配置]
+
+    Config --> ERP
+    Config --> DB
+    Config --> Update
+    Config --> Paths
+```
+
+至少要确认这些配置可用：
+
+- ERP URL
+- 当前使用的数据库类型
+- 数据库连接信息
+
+说明：
+
+- ERP 用户名和密码不是放在 `config.yaml`
+- 这部分在应用设置页中按用户存储
+
+## 5. 启动开发环境
+
+```bash
+npm run dev
+```
+
+开发启动链路如下：
+
+```mermaid
+sequenceDiagram
+    participant Dev as npm run dev
+    participant Vite as electron-vite
+    participant Main as main process
+    participant Preload as preload build
+    participant Renderer as renderer dev server
+
+    Dev->>Vite: electron-vite dev
+    Vite->>Main: build main
+    Vite->>Preload: build preload
+    Vite->>Renderer: start renderer dev server
+    Vite->>Main: launch electron
+```
+
+## 6. 常用开发命令
+
+```bash
+# 启动开发环境
+npm run dev
+
+# 类型检查
+npm run typecheck
+
+# 代码格式化
+npm run format
+
+# lint
+npm run lint
+
+# 单测
+npm run test:run
+
+# E2E
+npm run test:e2e
+```
+
+## 7. 构建命令
+
+当前正式维护的是 Windows 构建链路。
+
+```bash
+# 常规构建
+npm run build
+
+# Windows 安装版
+npm run build:win
+
+# 仅生成 unpack 目录
+npm run build:unpack
+```
+
+构建路径如下：
+
+```mermaid
+flowchart TD
+    Build[build]
+    Typecheck[typecheck]
+    ElectronVite[electron-vite build]
+    Updater[build:updater]
+    Builder[electron-builder]
+
+    Build --> Typecheck
+    Build --> ElectronVite
+    Build --> Updater
+    Build --> Builder
+```
+
+## 8. 日常验证建议
+
+修改代码后，建议至少跑：
+
+```bash
+npm run typecheck
+npx eslint <changed files>
+```
+
+如果改到关键主链路，再补：
+
+```bash
+npx vitest run <related tests>
+```
+
+## 9. 常见本地问题
+
+### 9.1 `npm run dev` 无法启动
+
+优先检查：
+
+- `config.yaml` 是否存在
+- 数据库配置是否正确
+- 当前终端里是否残留异常环境变量
+
+### 9.2 类型检查失败
+
+```mermaid
+flowchart TD
+    TypeError[类型错误]
+    Main{node 还是 web}
+    Node[node tsconfig]
+    Web[web tsconfig]
+    Fix[修正类型引用边界]
+
+    TypeError --> Main
+    Main --> Node
+    Main --> Web
+    Node --> Fix
+    Web --> Fix
+```
+
+### 9.3 ERP 登录相关问题
+
+优先检查：
+
+- 设置页中的 ERP 账号密码
+- ERP URL
+- 网络可达性
+- 是否可用调试脚本复现
+
+## 10. 相关文件
+
+- `package.json`
+- `config.yaml`
+- `src/main/index.ts`
+- `src/main/bootstrap/runtime.ts`
+- `electron-builder.yml`

docs/developer/guides/release-process.md

@@ -0,0 +1,138 @@
+# 发布流程指南
+
+本文档说明当前项目的构建、发布和上传链路。
+
+当前正式维护的是 Windows 发布流程。
+
+## 1. 发布链路总览
+
+```mermaid
+flowchart TD
+    Prepare[release:prepare]
+    Build[build / build:win]
+    Updater[build:updater]
+    Publish[release:publish]
+    Upload[release:upload]
+
+    Prepare --> Build
+    Build --> Updater
+    Updater --> Publish
+    Publish --> Upload
+```
+
+## 2. 当前相关命令
+
+```bash
+npm run release:prepare
+npm run build:win
+npm run release:publish
+npm run release:upload
+```
+
+以及构建相关命令：
+
+```bash
+npm run build
+npm run build:updater
+npm run build:unpack
+```
+
+## 3. 相关脚本
+
+当前发布链路涉及这些脚本：
+
+- `scripts/prepare-release.js`
+- `scripts/publish-release.js`
+- `scripts/upload-release.js`
+- `scripts/compile-updater.js`
+
+## 4. 构建阶段
+
+```mermaid
+flowchart LR
+    Prebuild[prebuild]
+    Typecheck[typecheck]
+    Vite[electron-vite build]
+    Updater[compile-updater]
+    Builder[electron-builder --win]
+
+    Prebuild --> Typecheck --> Vite --> Updater --> Builder
+```
+
+这一阶段大致会完成：
+
+- 清理旧产物
+- 类型检查
+- 构建 main / preload / renderer
+- 构建更新相关产物
+- 生成 Windows 安装包
+
+## 5. 发布前建议检查
+
+发布前建议确认：
+
+- `npm run typecheck` 通过
+- 关键测试通过
+- `config.yaml` / 发布配置没有误改
+- 更新目录与版本号符合预期
+- release 文案、构建产物和上传目标一致
+
+## 6. 更新链路关系
+
+发布流程和 update 模块关系很强：
+
+```mermaid
+graph LR
+    Release[发布脚本]
+    Artifact[构建产物]
+    Storage[对象存储 / 发布目录]
+    Update[UpdateService]
+    Client[客户端 UpdateDialog]
+
+    Release --> Artifact
+    Artifact --> Storage
+    Storage --> Update
+    Update --> Client
+```
+
+也就是说，发布流程最终会直接影响：
+
+- `UpdateCatalogService`
+- `UpdateDialog`
+- 客户端是否能正确检测与安装更新
+
+## 7. 常见问题
+
+### 7.1 构建失败
+
+优先检查：
+
+- `npm run typecheck`
+- 更新编译脚本是否正常
+- Windows 构建配置是否被误改
+
+### 7.2 发布后客户端看不到更新
+
+优先检查：
+
+- 发布目录是否正确上传
+- 版本号与 channel 是否正确
+- update catalog 是否包含该版本
+- 客户端 `UpdateService` 是否成功拉取目录
+
+### 7.3 上传成功但安装失败
+
+优先检查：
+
+- `UpdateInstaller` 的下载与校验逻辑
+- 产物哈希是否正确
+- 客户端本地下载路径与安装流程
+
+## 8. 相关文件
+
+- `package.json`
+- `electron-builder.yml`
+- `scripts/prepare-release.js`
+- `scripts/publish-release.js`
+- `scripts/upload-release.js`
+- `src/main/services/update/*`

docs/developer/guides/renderer-development.md

@@ -0,0 +1,164 @@
+# Renderer 开发指南
+
+本文档说明在当前项目里开发 React 渲染层时，推荐的组织方式和常见改动路径。
+
+## 1. Renderer 结构
+
+```mermaid
+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. 页面开发路径
+
+```mermaid
+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`
+
+```mermaid
+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. 状态更新建议
+
+```mermaid
+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 同时管理初始化、交互、请求、持久化和对话框
+- 非首屏重型组件全部静态导入

docs/developer/modules/README.md

@@ -0,0 +1,159 @@
+# 模块文档索引
+
+本目录收录项目核心业务模块的开发文档。
+
+这些文档的目标不是替代源码，而是帮助开发者快速理解：
+
+- 每个模块负责什么
+- 模块的入口文件在哪里
+- 模块之间如何协作
+- 主要数据和调用链怎么流动
+- 改某个功能时应该先看哪些文件
+
+## 推荐阅读方式
+
+如果你是第一次进入模块层，建议按下面顺序阅读：
+
+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` 持续保持为模块层总入口。

docs/developer/modules/auth.md

@@ -0,0 +1,119 @@
+# Auth 模块
+
+`Auth` 模块负责桌面端用户认证、silent login、管理员代切用户，以及把用户上下文同步给更新等后续模块。
+
+## 1. 模块职责
+
+- 获取机器名
+- 执行 silent login
+- 用户名密码登录
+- 管理员查看用户列表并切换用户
+- 登出并清理会话
+- 同步当前用户类型到更新模块
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    App[useAppBootstrap]
+    Preload[preload.auth]
+    Handler[auth-handler]
+    AppSvc[auth-application-service]
+    Session[session-manager]
+    Update[update-service]
+
+    App --> Preload
+    Preload --> Handler
+    Handler --> AppSvc
+    AppSvc --> Session
+    AppSvc --> Update
+```
+
+## 3. 关键入口文件
+
+- `src/renderer/src/hooks/useAppBootstrap.ts`
+- `src/renderer/src/components/app/UnauthenticatedApp.tsx`
+- `src/main/ipc/auth-handler.ts`
+- `src/main/services/auth/auth-application-service.ts`
+- `src/main/services/user/session-manager.ts`
+
+## 4. 认证主流程
+
+```mermaid
+sequenceDiagram
+    participant App as useAppBootstrap
+    participant Preload as preload.auth
+    participant Handler as auth-handler
+    participant AppSvc as auth-application-service
+    participant Session as session-manager
+
+    App->>Preload: getComputerName()
+    App->>Preload: silentLogin()
+    Preload->>Handler: invoke
+    Handler->>AppSvc: silentLogin()
+    AppSvc->>Session: loginByComputerName()
+    Session-->>AppSvc: userInfo
+    AppSvc-->>Handler: login result
+    Handler-->>Preload: IpcResult
+    Preload-->>App: auth state
+```
+
+## 5. 管理员分支
+
+如果 silent login 或显式登录得到的是管理员账号，认证流程不会直接结束，而是进入“代切用户”分支。
+
+```mermaid
+flowchart TD
+    Login[登录成功]
+    Admin{是否 Admin}
+    Select[getAllUsers]
+    Switch[switchUser]
+    Authenticated[进入已认证态]
+
+    Login --> Admin
+    Admin -- 否 --> Authenticated
+    Admin -- 是 --> Select
+    Select --> Switch
+    Switch --> Authenticated
+```
+
+## 6. 与更新模块的关系
+
+Auth 模块和 Update 模块之间有明确联动：
+
+```mermaid
+graph LR
+    Auth[AuthApplicationService]
+    UserType[UserType]
+    Update[UpdateService]
+
+    Auth --> UserType
+    UserType --> Update
+```
+
+在以下时机会同步用户上下文：
+
+- silent login 成功
+- 显式登录成功
+- 用户切换成功
+- logout
+
+## 7. 最近的结构优化
+
+Auth 相关逻辑最近做过两项关键收敛：
+
+- 把编排逻辑从 `auth-handler` 下沉到 `auth-application-service`
+- 在 `silentLogin()` 中加入并发去重，避免重复 silent login 触发连接风暴
+
+## 8. 常见改动点
+
+- 改前端启动认证：`useAppBootstrap.ts`
+- 改登录与切换流程：`auth-application-service.ts`
+- 改会话层：`session-manager.ts`
+- 改 IPC 契约：`auth-handler.ts`
+
+## 9. 修改建议
+
+- 页面不要直接堆认证细节，优先继续收敛到 bootstrap hook
+- 用户上下文变化时，记得考虑 update 状态是否需要同步
+- silent login 流程不要破坏当前的防重入保护

docs/developer/modules/cleaner.md

@@ -0,0 +1,197 @@
+# Cleaner 模块
+
+`Cleaner` 模块负责物料校验结果的展示、筛选、负责人分配、删除计划保存，以及最终 ERP 清理执行与报告展示。
+
+## 1. 模块职责
+
+- 展示校验后的物料列表
+- 负责人筛选与内联编辑
+- 勾选待处理物料
+- 保存删除计划到数据库
+- 执行 ERP 清理
+- 展示执行进度和执行报告
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    Page[CleanerPage]
+    Hook[useCleaner]
+    Sidebar[CleanerSidebar]
+    Toolbar[CleanerToolbar]
+    Table[CleanerResultsTable]
+    Bar[CleanerExecutionBar]
+    Helpers[hooks/cleaner/helpers.ts]
+    API[hooks/cleaner/api.ts]
+    Preload[preload.cleaner / validation / materials]
+    Handler[cleaner-handler / validation-handler]
+    MainSvc[cleaner-application-service]
+
+    Page --> Hook
+    Page --> Sidebar
+    Page --> Toolbar
+    Page --> Table
+    Page --> Bar
+    Hook --> Helpers
+    Hook --> API
+    API --> Preload
+    Preload --> Handler
+    Handler --> MainSvc
+```
+
+## 3. 关键入口文件
+
+- `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`
+- `src/renderer/src/components/cleaner/CleanerSidebar.tsx`
+- `src/renderer/src/components/cleaner/CleanerToolbar.tsx`
+- `src/renderer/src/components/cleaner/CleanerResultsTable.tsx`
+- `src/renderer/src/components/cleaner/CleanerExecutionBar.tsx`
+- `src/main/ipc/cleaner-handler.ts`
+- `src/main/services/cleaner/cleaner-application-service.ts`
+
+## 4. 页面主流程
+
+```mermaid
+flowchart TD
+    Load[页面初始化]
+    Validate[获取并校验物料]
+    Results[validationResults]
+    Filter[筛选与隐藏]
+    Select[勾选与负责人编辑]
+    Plan[保存删除计划]
+    Execute[执行 ERP 清理]
+    Report[执行报告 / 查看报告]
+
+    Load --> Validate
+    Validate --> Results
+    Results --> Filter
+    Results --> Select
+    Select --> Plan
+    Plan --> Execute
+    Execute --> Report
+```
+
+## 5. 前端状态组织
+
+当前 `useCleaner` 管理的主要状态包括：
+
+- 页面初始化与权限
+- 校验结果与筛选结果
+- 勾选状态与隐藏状态
+- 负责人编辑状态
+- 执行设置
+- 进度状态
+- 报告弹窗状态
+- 确认弹窗状态
+
+可以理解成：
+
+```mermaid
+mindmap
+  root((useCleaner))
+    权限与初始化
+      isAdmin
+      currentUsername
+      managers
+    校验结果
+      validationResults
+      filteredResults
+      selectedItems
+      hiddenItems
+    执行状态
+      isRunning
+      isExecuting
+      progress
+      reportData
+    设置
+      dryRun
+      headless
+      processConcurrency
+    交互
+      editingCell
+      confirmDialog
+      dialogs
+```
+
+## 6. 主进程执行链路
+
+Cleaner 真正执行 ERP 清理时，主进程调用链大致如下：
+
+```mermaid
+sequenceDiagram
+    participant UI as useCleaner
+    participant Preload as preload.cleaner
+    participant Handler as cleaner-handler
+    participant AppSvc as cleaner-application-service
+    participant ERP as CleanerService / ErpAuthService
+    participant Report as report / rustfs
+
+    UI->>Preload: runCleaner(input)
+    Preload->>Handler: invoke
+    Handler->>AppSvc: runCleaner(...)
+    AppSvc->>ERP: 登录并执行清理
+    ERP-->>AppSvc: cleaner result
+    AppSvc->>Report: 生成并上传报告
+    AppSvc-->>Handler: result
+    Handler-->>Preload: IpcResult
+    Preload-->>UI: 执行结果
+```
+
+## 7. 模块边界
+
+Cleaner 依赖多个模块：
+
+```mermaid
+graph LR
+    Cleaner[Cleaner]
+    Validation[Validation]
+    Materials[Materials / MaterialType]
+    Report[Report]
+    Config[Config]
+    ERP[ERP Services]
+
+    Cleaner --> Validation
+    Cleaner --> Materials
+    Cleaner --> Report
+    Cleaner --> Config
+    Cleaner --> ERP
+```
+
+其中：
+
+- `validation`
+  提供校验结果和 Cleaner 可消费数据
+- `materials`
+  提供负责人和删除计划相关能力
+- `report`
+  提供报告查看与生成
+- `config`
+  提供执行配置
+
+## 8. 最近的结构优化
+
+这一块近期做过两轮收敛：
+
+- `CleanerPage` 拆成 `Sidebar / Toolbar / ResultsTable / ExecutionBar`
+- `useCleaner` 内部 API / helpers 已经第一轮抽离
+
+同时页面中的重型弹窗也已经改成按需加载。
+
+## 9. 常见改动点
+
+- 改筛选或展示：`CleanerPage.tsx` 与 `components/cleaner/*`
+- 改前端执行逻辑：`useCleaner.ts`
+- 改校验请求与导出：`hooks/cleaner/api.ts`
+- 改纯逻辑：`hooks/cleaner/helpers.ts`
+- 改主进程执行：`cleaner-application-service.ts`
+- 改 ERP 清理细节：`src/main/services/erp/cleaner.ts`
+
+## 10. 修改建议
+
+- 优先保持页面组件继续做“组装层”
+- 如果新增复杂交互，优先下沉到 hook 或 helper
+- 执行链路的真实业务逻辑放在主进程 service
+- 报告、导出、上传等后处理不要塞回 UI 层

docs/developer/modules/extractor.md

@@ -0,0 +1,133 @@
+# Extractor 模块
+
+`Extractor` 模块负责接收订单号输入、触发提取流程、同步共享订单号，并把提取结果导入后续链路可消费的数据形态。
+
+## 1. 模块职责
+
+- 接收和持久化订单号输入
+- 将订单号同步为共享 `Production IDs`
+- 触发批量提取流程
+- 展示提取进度和日志
+- 为 `Cleaner` 等后续模块提供共享订单号基础
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    Page[ExtractorPage]
+    Input[OrderNumberInput]
+    Persist[usePersistentTextState]
+    Shared[useSharedProductionIds]
+    Hook[useExtractor]
+    Preload[preload.extractor / validation]
+    Handler[extractor-handler]
+    Service[ERP Extractor Service]
+
+    Page --> Input
+    Page --> Persist
+    Page --> Shared
+    Page --> Hook
+    Hook --> Preload
+    Preload --> Handler
+    Handler --> Service
+```
+
+## 3. 关键入口文件
+
+- `src/renderer/src/pages/ExtractorPage.tsx`
+- `src/renderer/src/hooks/useExtractor.ts`
+- `src/renderer/src/hooks/usePersistentTextState.ts`
+- `src/renderer/src/hooks/useSharedProductionIds.ts`
+- `src/renderer/src/components/OrderNumberInput.tsx`
+- `src/main/ipc/extractor-handler.ts`
+- `src/main/services/erp/extractor.ts`
+
+## 4. 主要流程
+
+```mermaid
+sequenceDiagram
+    participant UI as ExtractorPage
+    participant Persist as usePersistentTextState
+    participant Shared as useSharedProductionIds
+    participant Hook as useExtractor
+    participant Preload as preload.extractor
+    participant Main as extractor-handler / extractor service
+
+    UI->>Persist: 保存输入
+    UI->>Shared: debounce 同步共享 IDs
+    UI->>Hook: startExtraction(orderNumbers)
+    Hook->>Preload: setSharedProductionIds()
+    Hook->>Preload: runExtractor()
+    Preload->>Main: invoke
+    Main-->>Preload: 提取结果
+    Preload-->>Hook: success / error / progress
+    Hook-->>UI: 更新日志与状态
+```
+
+## 5. 关键状态
+
+当前前端侧最重要的状态包括：
+
+- `orderNumbers`
+  用户输入的订单号文本
+- `isRunning`
+  是否正在提取
+- `progress`
+  当前提取进度
+- `logs`
+  提取过程日志
+- `error`
+  当前错误
+- `isComplete`
+  提取是否结束
+
+## 6. 与其他模块的关系
+
+Extractor 与其他模块的关系如下：
+
+```mermaid
+graph LR
+    Extractor[Extractor]
+    SharedIds[shared Production IDs]
+    Validation[Validation]
+    Cleaner[Cleaner]
+
+    Extractor --> SharedIds
+    SharedIds --> Validation
+    Validation --> Cleaner
+```
+
+它最重要的跨模块输出不是页面本身，而是：
+
+- 共享 `Production IDs`
+- 导入数据库的数据
+
+## 7. 最近的结构优化
+
+最近这一块做过两类收敛：
+
+- 把订单号持久化抽到 `usePersistentTextState`
+- 把共享订单号同步抽到 `useSharedProductionIds`
+
+这样页面不再自己同时处理：
+
+- 输入状态
+- `sessionStorage`
+- bridge 副作用
+
+## 8. 常见改动点
+
+如果你要改 Extractor，通常会落在这些位置：
+
+- 改输入与格式统计：`OrderNumberInput.tsx`
+- 改页面交互：`ExtractorPage.tsx`
+- 改前端提取编排：`useExtractor.ts`
+- 改共享订单号同步：`useSharedProductionIds.ts`
+- 改主进程执行：`extractor-handler.ts` / `erp/extractor.ts`
+
+## 9. 修改建议
+
+- 输入变化不要直接叠加更多高频副作用
+- 共享订单号写入尽量维持单一入口
+- 提取日志和进度流优先保持事件推送式结构
+- 如果新增提取后处理，优先放在主进程 service，而不是塞回页面

docs/developer/modules/settings.md

@@ -0,0 +1,103 @@
+# Settings 模块
+
+`Settings` 模块当前主要负责 ERP 登录凭据的查看、编辑和保存，并通过当前用户上下文对配置进行按用户管理。
+
+## 1. 模块职责
+
+- 加载当前用户的 ERP 配置
+- 编辑 ERP 用户名和密码
+- 保存配置到后端持久化存储
+- 提示保存结果
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    Page[SettingsPage]
+    Preload[preload.settings]
+    Handler[settings-handler]
+    Config[Config / User ERP Config Service]
+    Storage[数据库中的用户配置]
+
+    Page --> Preload
+    Preload --> Handler
+    Handler --> Config
+    Config --> Storage
+```
+
+## 3. 关键入口文件
+
+- `src/renderer/src/pages/SettingsPage.tsx`
+- `src/main/ipc/settings-handler.ts`
+- `src/main/services/config/config-manager.ts`
+- `src/main/services/user/user-erp-config-service.ts`
+
+## 4. 主流程
+
+```mermaid
+sequenceDiagram
+    participant Page as SettingsPage
+    participant Preload as preload.settings
+    participant Handler as settings-handler
+    participant Service as config / user-erp-config-service
+
+    Page->>Preload: getSettings()
+    Preload->>Handler: invoke
+    Handler->>Service: load current user config
+    Service-->>Handler: settings payload
+    Handler-->>Preload: IpcResult
+    Preload-->>Page: ERP credentials
+
+    Page->>Preload: saveSettings(payload)
+    Preload->>Handler: invoke
+    Handler->>Service: persist config
+    Service-->>Handler: save result
+    Handler-->>Preload: IpcResult
+    Preload-->>Page: success / error
+```
+
+## 5. 页面状态
+
+当前设置页非常轻量，主要状态包括：
+
+- `credentials`
+- `isModified`
+- `isLoading`
+
+```mermaid
+flowchart LR
+    Load[加载配置]
+    Edit[编辑账号密码]
+    Dirty[isModified = true]
+    Save[保存配置]
+    Success[提示成功]
+
+    Load --> Edit
+    Edit --> Dirty
+    Dirty --> Save
+    Save --> Success
+```
+
+## 6. 与其他模块的关系
+
+Settings 模块与这些模块关系较强：
+
+- `auth`
+  当前用户决定读取和保存哪份 ERP 配置
+- `cleaner`
+  Cleaner 执行时会读取 ERP 账号密码
+- `extractor`
+  提取链路也依赖 ERP 登录能力
+
+## 7. 常见改动点
+
+- 改页面交互：`SettingsPage.tsx`
+- 改 IPC 契约：`settings-handler.ts`
+- 改配置存储逻辑：`user-erp-config-service.ts`
+- 改全局配置：`config-manager.ts`
+
+## 8. 修改建议
+
+- 保持“页面只编辑当前用户配置”的边界清晰
+- 不要把 ERP 凭据保存逻辑重新分散到多个模块
+- 如果后续扩展更多设置项，建议引入更清晰的分组和局部表单结构

docs/developer/modules/update.md

@@ -0,0 +1,153 @@
+# Update 模块
+
+`Update` 模块负责应用版本目录拉取、状态广播、更新包下载、安装器启动，以及为不同用户类型生成不同的更新视图。
+
+## 1. 模块职责
+
+- 检查更新是否可用
+- 拉取更新目录
+- 为 `User` / `Admin` 生成不同的更新决策
+- 下载更新包并校验
+- 启动安装流程
+- 广播更新状态给 renderer
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    Hook[useAppBootstrap]
+    Dialog[UpdateDialog / useUpdateDialogState]
+    Preload[preload.update]
+    Handler[update-handler]
+    Service[UpdateService]
+    Catalog[UpdateCatalogService]
+    Installer[UpdateInstaller]
+    Storage[UpdateStorageClient]
+    Publisher[UpdateStatusPublisher]
+
+    Hook --> Preload
+    Dialog --> Preload
+    Preload --> Handler
+    Handler --> Service
+    Service --> Catalog
+    Service --> Installer
+    Service --> Storage
+    Service --> Publisher
+```
+
+## 3. 关键入口文件
+
+- `src/renderer/src/hooks/useAppBootstrap.ts`
+- `src/renderer/src/components/UpdateDialog.tsx`
+- `src/renderer/src/hooks/useUpdateDialogState.ts`
+- `src/main/ipc/update-handler.ts`
+- `src/main/services/update/update-service.ts`
+- `src/main/services/update/update-catalog-service.ts`
+- `src/main/services/update/update-installer.ts`
+- `src/main/services/update/update-storage-client.ts`
+- `src/main/services/update/update-status-publisher.ts`
+
+## 4. 更新数据流
+
+```mermaid
+sequenceDiagram
+    participant Hook as useAppBootstrap
+    participant Dialog as useUpdateDialogState
+    participant Preload as preload.update
+    participant Handler as update-handler
+    participant Service as UpdateService
+    participant Catalog as UpdateCatalogService
+
+    Hook->>Preload: getStatus()
+    Hook->>Preload: getCatalog()
+    Dialog->>Preload: getChangelog(release)
+    Preload->>Handler: invoke
+    Handler->>Service: getStatus / getCatalog / getChangelog
+    Service->>Catalog: resolve dialog catalog
+    Catalog-->>Service: release decisions
+    Service-->>Handler: update data
+    Handler-->>Preload: IpcResult
+    Preload-->>Hook: status / catalog
+    Preload-->>Dialog: changelog
+```
+
+## 5. 状态模型
+
+更新模块当前最核心的是 `UpdateStatus`：
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> checking
+    checking --> available
+    checking --> downloaded
+    checking --> error
+    available --> downloading
+    downloading --> downloaded
+    downloading --> error
+    downloaded --> installing
+    installing --> [*]
+```
+
+同时 `UpdateDialogCatalog` 会根据用户角色形成不同视图：
+
+- `user`
+- `admin`
+- `disabled`
+
+## 6. 用户与管理员差异
+
+```mermaid
+flowchart TD
+    Context[当前用户类型]
+    User[User]
+    Admin[Admin]
+    UserCatalog[推荐稳定版]
+    AdminCatalog[Stable + Preview 目录]
+
+    Context --> User
+    Context --> Admin
+    User --> UserCatalog
+    Admin --> AdminCatalog
+```
+
+普通用户主要消费：
+
+- 推荐版本
+- 已下载版本
+- 安装动作
+
+管理员主要消费：
+
+- 完整版本目录
+- Stable / Preview 版本切换
+- 手动下载并安装
+
+## 7. 最近的结构优化
+
+Update 模块已经做过多轮职责拆分：
+
+- 版本目录决策拆到 `update-catalog-service`
+- 下载与安装拆到 `update-installer`
+- 状态广播拆到 `update-status-publisher`
+- 对象存储访问拆到 `update-storage-client`
+
+同时前端侧：
+
+- `useUpdateDialogState` 收敛了选中版本和 changelog 状态
+- `UpdateDialog` 已改成按需加载
+
+## 8. 常见改动点
+
+- 改 renderer 状态流：`useAppBootstrap.ts` / `useUpdateDialogState.ts`
+- 改弹窗展示：`UpdateDialog.tsx`
+- 改更新检查与轮询：`update-service.ts`
+- 改版本决策：`update-catalog-service.ts`
+- 改安装流程：`update-installer.ts`
+
+## 9. 修改建议
+
+- 更新决策逻辑优先放在 main service，不要回流到 renderer
+- changelog、catalog、status 要保持边界清晰
+- 用户类型变化时要考虑 status/catalog 的复位逻辑
+- 如果新增发布通道，优先扩展 catalog service

docs/developer/modules/validation.md

@@ -0,0 +1,147 @@
+# Validation 模块
+
+`Validation` 模块负责共享订单号管理、输入识别、数据库校验查询、物料结果富化，以及为 Cleaner 提供可消费的数据。
+
+## 1. 模块职责
+
+- 存储与读取共享 `Production IDs`
+- 将输入转换为可校验的 source numbers
+- 查询数据库中的物料记录
+- 结合类型关键词和已标记物料生成校验结果
+- 为 Cleaner 提供订单号与物料代码
+
+## 2. 模块结构
+
+```mermaid
+graph TD
+    Handler[validation-handler]
+    AppSvc[validation-application-service]
+    Store[shared-production-ids-store]
+    Input[production-input-service]
+    DB[validation-database]
+    DAO[DAO / database services]
+
+    Handler --> Store
+    Handler --> AppSvc
+    AppSvc --> Input
+    AppSvc --> DB
+    DB --> DAO
+```
+
+## 3. 关键入口文件
+
+- `src/main/ipc/validation-handler.ts`
+- `src/main/services/validation/validation-application-service.ts`
+- `src/main/services/validation/shared-production-ids-store.ts`
+- `src/main/services/validation/production-input-service.ts`
+- `src/main/services/validation/validation-database.ts`
+- `src/renderer/src/hooks/useValidation.ts`
+
+## 4. 主流程
+
+```mermaid
+sequenceDiagram
+    participant UI as Renderer / useValidation / useCleaner
+    participant Handler as validation-handler
+    participant Store as shared-production-ids-store
+    participant AppSvc as validation-application-service
+    participant Input as production-input-service
+    participant DB as validation-database
+
+    UI->>Handler: set/get shared Production IDs
+    Handler->>Store: read/write sender scoped IDs
+
+    UI->>Handler: validate(request)
+    Handler->>AppSvc: validate(...)
+    AppSvc->>Input: resolve source numbers
+    AppSvc->>DB: query material records
+    DB-->>AppSvc: rows
+    AppSvc-->>Handler: validation results + stats
+    Handler-->>UI: response
+```
+
+## 5. 共享 Production IDs
+
+共享订单号是 Validation 模块最重要的跨页面状态之一。
+
+```mermaid
+graph LR
+    Extractor[Extractor]
+    Store[shared-production-ids-store]
+    Validation[Validation]
+    Cleaner[Cleaner]
+
+    Extractor --> Store
+    Store --> Validation
+    Validation --> Cleaner
+```
+
+这个状态当前按 `senderId` 维度存储，主要被：
+
+- `Extractor`
+  写入
+- `Validation`
+  读取和解析
+- `Cleaner`
+  间接消费
+
+## 6. 结果生成逻辑
+
+校验结果不仅是数据库原始数据，还会叠加：
+
+- 已标记删除状态
+- 负责人关键词匹配
+- 用户权限作用域
+
+```mermaid
+flowchart TD
+    DBRows[数据库物料记录]
+    Marked[已标记物料]
+    Keywords[类型关键词]
+    Scope[用户作用域]
+    Result[ValidationResult]
+
+    DBRows --> Result
+    Marked --> Result
+    Keywords --> Result
+    Scope --> Result
+```
+
+## 7. 模块输出
+
+Validation 主要对外输出两类数据：
+
+- `ValidationResponse`
+  提供给校验页和 Cleaner 页
+- `CleanerData`
+  提供给 Cleaner 执行前的数据准备
+
+## 8. 最近的结构优化
+
+这一块已经从早期的大 `validation-handler` 中拆分出来：
+
+- `shared-production-ids-store`
+- `validation-database`
+- `production-input-service`
+- `validation-application-service`
+
+这样之后：
+
+- handler 只做 IPC 壳
+- 共享状态有独立归属
+- 数据库方言差异有独立封装
+
+## 9. 常见改动点
+
+- 改共享订单号逻辑：`shared-production-ids-store.ts`
+- 改输入识别：`production-input-service.ts`
+- 改数据库差异：`validation-database.ts`
+- 改校验结果富化：`validation-application-service.ts`
+- 改 renderer 侧调用：`useValidation.ts`
+
+## 10. 修改建议
+
+- 不要再把共享状态放回 handler
+- 数据库分支优先收敛在 `validation-database`
+- 校验结果组装逻辑尽量集中在 application service
+- 跨模块共享数据要保持单向来源清晰

docs/plans/2026-03-21-electron-best-practices-optimization-plan.md

@@ -0,0 +1,377 @@
+# Electron 最佳实践优化计划
+
+本文档基于 `$electron-best-practices` 对当前项目的审查结果整理而成，目标不是一次性重构整个 Electron 应用，而是按照“低风险、可验证、逐步收敛”的方式，分阶段提升主进程、preload、IPC、更新模块和工程配置的可维护性。
+
+## 1. 计划背景
+
+当前项目已经具备了较好的 Electron 基础结构：
+
+- 主进程、preload、renderer 三层已分离
+- Renderer 通过 `contextBridge` 暴露能力
+- IPC 统一采用 `invoke/handle` 模式
+- 大部分主进程能力已经模块化到 `ipc/` 与 `services/`
+
+但从长期维护角度看，项目仍存在几个明显问题：
+
+- `src/main/index.ts` 入口文件承担职责过多
+- 部分 IPC handler 仍然是“厚编排层”
+- `src/preload/index.ts` 更像“接口总表”，不是按领域划分的 facade
+- 更新链路实现较重，边界尚不清晰
+- 打包配置存在模板残留，容易误导维护者
+- Electron 边界层测试尚未系统化
+
+## 2. 优化目标
+
+本轮优化聚焦以下目标：
+
+- 让主进程入口只负责启动顺序，不承载业务细节
+- 让 IPC handler 回归“薄壳”，把编排逻辑下沉到应用服务层
+- 让 preload API 按业务领域组织，而不是按主进程实现镜像
+- 收敛更新模块的职责边界，降低后续维护复杂度
+- 清理打包与发布配置中的模板残留
+- 为 Electron 边界补足更稳定的测试支撑
+
+## 3. 优化范围
+
+本计划优先处理 Electron 工程化与可维护性问题，不把安全性作为唯一优先目标，但会顺带处理那些同时影响可维护性的边界设计问题。
+
+本次计划重点覆盖：
+
+- 主进程启动与应用初始化
+- IPC handler 与 application service 分层
+- preload API 结构
+- 更新模块
+- 打包配置
+- Electron 边界层测试
+
+暂不作为本轮首要目标：
+
+- 大规模 UI 重构
+- 业务流程重写
+- ERP 自动化细节重构
+
+## 4. 当前问题总览
+
+```mermaid
+graph TD
+    MainIndex[src/main/index.ts]
+    IPC[IPC Handlers]
+    Preload[src/preload/index.ts]
+    Update[update-service.ts]
+    Builder[electron-builder.yml]
+    Tests[tests/unit]
+
+    MainIndex -->|启动逻辑过重| Maintainability[维护成本上升]
+    IPC -->|编排过厚| Maintainability
+    Preload -->|API 面过大| Maintainability
+    Update -->|职责边界不清| Maintainability
+    Builder -->|模板残留| Maintainability
+    Tests -->|边界覆盖不足| Maintainability
+```
+
+## 5. 分阶段执行计划
+
+### Phase 1: 收敛主进程入口
+
+目标：
+
+- 让 `src/main/index.ts` 只表达启动顺序
+- 把运行时检查、窗口创建、异常守卫、模块初始化拆到独立函数或模块
+
+建议涉及文件：
+
+- `src/main/index.ts`
+- `src/main/bootstrap/` 下新增或调整模块
+
+建议拆分方向：
+
+- `bootstrapApp()`
+- `createMainWindow()`
+- `setupProcessGuards()`
+- `verifyPlaywrightRuntime()`
+- `initializeAppServices()`
+
+预期收益：
+
+- 降低入口文件修改风险
+- 提高启动问题排查效率
+- 为多窗口、多实例策略预留更清晰的扩展点
+
+风险等级：
+
+- 低到中
+
+验证方式：
+
+- 应用冷启动成功
+- 窗口创建与关闭流程正常
+- 异常日志、更新初始化、IPC 注册行为不回归
+
+### Phase 2: 让 IPC Handler 回归薄壳
+
+目标：
+
+- 把 `cleaner-handler`、`auth-handler` 这类厚编排层下沉到应用服务
+- 明确 handler、application service、infrastructure service 的职责边界
+
+建议涉及文件：
+
+- `src/main/ipc/cleaner-handler.ts`
+- `src/main/ipc/auth-handler.ts`
+- `src/main/ipc/update-handler.ts`
+- `src/main/services/`
+
+建议拆分方向：
+
+- `CleanerApplicationService`
+- `AuthApplicationService`
+- `UpdateApplicationService`
+
+handler 只负责：
+
+- 接收请求
+- 调用 service
+- 映射返回结构
+- 统一错误包装
+
+预期收益：
+
+- 提升主进程业务编排的可测试性
+- 降低 handler 文件复杂度
+- 让业务流程更容易被复用和替换
+
+风险等级：
+
+- 中
+
+验证方式：
+
+- 关键 IPC 流程回归测试
+- 原有 renderer 调用协议保持不变
+- 清理、登录、更新等主流程手动验收通过
+
+### Phase 3: 重组 Preload API
+
+目标：
+
+- 把 `src/preload/index.ts` 从“大总表”改造成“按领域组织的 facade”
+- 稳定 renderer 对 Electron 能力的访问边界
+
+建议涉及文件：
+
+- `src/preload/index.ts`
+- `src/preload/index.d.ts`
+- `src/main/types/`
+
+建议拆分方向：
+
+- `authApi`
+- `cleanerApi`
+- `updateApi`
+- `reportApi`
+- `fileApi`
+
+建议原则：
+
+- renderer 只拿到业务语义接口
+- preload 不原样映射主进程实现细节
+- 类型定义集中管理，避免 renderer 和 main 双边漂移
+
+预期收益：
+
+- 降低渲染层对 IPC 细节的耦合
+- 提高 preload 的可读性和可扩展性
+- 为后续做 runtime schema 校验打基础
+
+风险等级：
+
+- 中
+
+验证方式：
+
+- `npm run typecheck`
+- preload surface 测试通过
+- 主要页面功能回归正常
+
+### Phase 4: 收敛更新模块边界
+
+目标：
+
+- 把更新服务中的下载、状态管理、安装协调、日志处理边界进一步明确
+- 降低自定义更新链路的维护成本
+
+建议涉及文件：
+
+- `src/main/services/update/update-service.ts`
+- `src/main/ipc/update-handler.ts`
+- `src/main/types/`
+
+建议拆分方向：
+
+- `UpdateStateMachine`
+- `UpdateDownloadService`
+- `UpdateInstallCoordinator`
+- `UpdateEventBridge`
+
+预期收益：
+
+- 更新问题更容易定位
+- 状态流转更容易测试
+- 后续切换更新策略时影响面更小
+
+风险等级：
+
+- 中到高
+
+验证方式：
+
+- 更新检查、下载、安装提示链路验证
+- 状态事件顺序测试
+- 失败重试与异常日志验证
+
+### Phase 5: 清理打包与发布配置
+
+目标：
+
+- 让构建配置更贴近当前项目实际维护范围
+- 清理无效、模板化或误导性的配置项
+
+建议涉及文件：
+
+- `electron-builder.yml`
+- `package.json`
+- `scripts/` 下发布相关脚本
+- `docs/releases/` 与构建说明文档
+
+重点检查项：
+
+- 实际支持的平台范围
+- 发布目标与渠道
+- 无关权限说明
+- Windows 优先配置是否清晰
+
+预期收益：
+
+- 降低发版配置理解成本
+- 减少“看似支持、实际无人维护”的伪能力
+- 让发布文档与配置保持一致
+
+风险等级：
+
+- 低
+
+验证方式：
+
+- 本地构建通过
+- 发布脚本执行链路无回归
+- 文档与配置一致性核对完成
+
+### Phase 6: 补强 Electron 边界层测试
+
+目标：
+
+- 让最容易劣化的 Electron 边界层拥有稳定回归保护
+
+建议涉及文件：
+
+- `tests/unit/preload-surface.test.ts`
+- `tests/unit/ipc-index.test.ts`
+- 新增 `tests/unit/update-service.*`
+- 新增 `tests/unit/cleaner-handler.*`
+- 新增 `tests/unit/auth-handler.*`
+
+优先补测内容：
+
+- 主进程启动编排
+- preload surface 稳定性
+- IPC 返回包装与错误路径
+- update service 状态迁移
+- handler 与 service 交互边界
+
+预期收益：
+
+- 降低后续拆分时的回归风险
+- 提升主进程重构信心
+- 让 Electron 工程层而非仅业务工具层获得测试保护
+
+风险等级：
+
+- 低
+
+验证方式：
+
+- 单元测试通过
+- 关键流程 smoke test 通过
+
+## 6. 推荐执行顺序
+
+```mermaid
+graph LR
+    A[Phase 1 主进程入口收敛]
+    B[Phase 2 IPC Handler 薄壳化]
+    C[Phase 3 Preload API 重组]
+    D[Phase 4 更新模块收敛]
+    E[Phase 5 构建配置清理]
+    F[Phase 6 Electron 边界测试补强]
+
+    A --> B
+    B --> C
+    C --> D
+    D --> E
+    B --> F
+    C --> F
+    D --> F
+```
+
+建议优先顺序：
+
+1. 先做主进程入口收敛
+2. 再做 IPC handler 薄壳化
+3. 然后重组 preload API
+4. 再处理更新模块
+5. 清理打包配置
+6. 在每一阶段同步补强测试
+
+说明：
+
+- `Phase 1` 与 `Phase 2` 性价比最高
+- `Phase 3` 适合在 handler 边界稳定后推进
+- `Phase 4` 风险相对更高，应放在前面边界清晰后再处理
+- `Phase 6` 不应完全放到最后，建议伴随每阶段一起推进
+
+## 7. 每阶段完成标准
+
+每一阶段建议采用统一完成标准：
+
+- 相关模块职责边界变清晰
+- 对外接口保持兼容或完成显式迁移
+- `npm run lint` 通过
+- `npm run typecheck` 通过
+- 相关单元测试通过
+- 关键手工路径验证完成
+- 对应文档同步更新
+
+## 8. 本计划与现有重构工作的衔接
+
+当前已经完成的两轮重构：
+
+- `validation-handler` 第一阶段拆分
+- `useCleaner` 第一阶段拆分
+
+它们为本计划提供了两个基础：
+
+- 团队已经验证“先拆超大文件，再保持对外行为不变”的策略可行
+- 后续继续拆 `cleaner-handler`、`preload`、`App` 时，可以沿用相同方法论
+
+因此，Electron 向优化建议优先从主进程和边界层继续推进，而不是立刻进入更深的 UI 重构。
+
+## 9. 后续建议
+
+建议后续执行方式如下：
+
+1. 先按本计划完成 `Phase 1`
+2. 每完成一个阶段，单独补一份重构说明文档
+3. 每个阶段单独提交，避免一次性大改
+4. 每阶段结束后重新运行 `lint`、`typecheck` 和对应测试
+
+如果后续决定正式执行，本计划可作为 Electron 工程化重构的主索引文档持续维护。

docs/plans/2026-03-21-vercel-react-best-practices-optimization-plan.md

@@ -0,0 +1,495 @@
+# React 最佳实践优化计划
+
+本文档基于 `$vercel-react-best-practices` 对当前项目 React 渲染层的审查结果整理而成，目标不是立刻重写页面，而是按“先收敛数据流，再拆重型组件，最后做体验与性能微调”的顺序，逐步降低渲染层维护成本。
+
+## 1. 审查背景
+
+当前项目的 React 层已经具备一些不错的基础：
+
+- 页面与 Electron 主进程通过 preload facade 通信
+- 关键业务已经逐步抽到 hook 和 service
+- `Cleaner` 相关逻辑已经做过第一轮拆分
+- 更新、认证、日志、校验等流程已有一定模块意识
+
+但从 `$vercel-react-best-practices` 的角度看，当前主要问题仍集中在：
+
+- 页面容器组件承担过多状态与副作用
+- 大 hook 同时管理初始化、交互状态、远程请求、持久化
+- effect 数量偏多，且存在“启动时拉很多东西、认证后再拉一遍”的流程
+- 重型 UI 区块还没有进一步拆成可稳定复用的小边界
+- 某些异步请求与 UI 更新仍可进一步并行化、延后 await 或降低重渲染范围
+
+## 2. Skill 视角下的主要问题
+
+### 2.1 高优先级: `App.tsx` 仍是重型入口容器
+
+涉及文件：
+
+- `src/renderer/src/App.tsx`
+
+问题表现：
+
+- 认证初始化、更新订阅、页面导航、顶部壳层、登录/选人/更新弹窗都集中在一个组件里
+- `initializeAuth()` 同时负责获取机器名、silent login、admin 用户分流、错误兜底
+- `useEffect` 和回调之间仍有较强耦合，后续继续扩展容易变成新的“前端编排中心”
+
+与 skill 对应：
+
+- `rerender-split-combined-hooks`
+- `rerender-move-effect-to-event`
+- `advanced-init-once`
+
+建议方向：
+
+- 抽出 `useAppBootstrap`
+- 抽出 `useUpdateController`
+- 把顶部壳层拆成 `AppShell`
+- 把未认证态与已认证态拆成两条渲染分支组件
+
+### 2.2 高优先级: `CleanerPage` + `useCleaner` 仍然是“大页面 + 大 hook”模式
+
+涉及文件：
+
+- `src/renderer/src/pages/CleanerPage.tsx`
+- `src/renderer/src/hooks/useCleaner.ts`
+
+问题表现：
+
+- `CleanerPage` 同时渲染左侧筛选区、顶部工具栏、结果表格、底部执行区和多个弹窗
+- `useCleaner` 同时承担权限初始化、sessionStorage 同步、配置加载、进度订阅、校验请求、导出、执行删除、内联编辑、确认弹窗状态
+- hook 返回面非常大，页面对 hook 的内部结构有明显耦合
+
+与 skill 对应：
+
+- `rerender-split-combined-hooks`
+- `rerender-derived-state-no-effect`
+- `rerender-no-inline-components`
+- `rendering-content-visibility`
+
+建议方向：
+
+- `useCleanerPageState`
+- `useCleanerExecution`
+- `useCleanerSelection`
+- `CleanerSidebar`
+- `CleanerToolbar`
+- `CleanerResultsTable`
+- `CleanerExecutionBar`
+
+### 2.3 中优先级: `ExtractorPage` 里存在“输入变化即触发跨模块副作用”的同步路径
+
+涉及文件：
+
+- `src/renderer/src/pages/ExtractorPage.tsx`
+
+问题表现：
+
+- `orderNumbers` 每次变化都会写 `sessionStorage`
+- 同时每次变化都会调用 `window.electron.validation.setSharedProductionIds()` 或 `clearSharedProductionIds()`
+- 这条路径把“输入态”和“共享业务态”绑得很紧，后续如果输入组件更复杂，容易造成高频桥接调用
+
+与 skill 对应：
+
+- `rerender-move-effect-to-event`
+- `client-localstorage-schema`
+- `js-cache-storage`
+
+建议方向：
+
+- 只在“格式化完成 / 用户提交 / debounce 稳定后”同步共享订单号
+- 把 sessionStorage 读写抽到专门 persistence helper
+- 为共享 Production ID 增加单独同步入口，而不是输入 effect 隐式触发
+
+### 2.4 中优先级: 更新对话框的异步拉取和状态切换还可以再收敛
+
+涉及文件：
+
+- `src/renderer/src/components/UpdateDialog.tsx`
+- `src/renderer/src/App.tsx`
+
+问题表现：
+
+- `App` 负责状态订阅和 catalog/status 刷新
+- `UpdateDialog` 内部再负责根据选中版本拉 changelog
+- 当前实现是可工作的，但状态来源分散，后续容易出现 “catalog 变了 / changelog 还在旧请求中” 的边界问题
+
+与 skill 对应：
+
+- `async-defer-await`
+- `async-parallel`
+- `rerender-dependencies`
+- `rendering-usetransition-loading`
+
+建议方向：
+
+- 建立 `useUpdateDialogState`
+- catalog/status/changelog 分层管理
+- 选版本后的 changelog 拉取用请求标识或最新值保护
+- 对切换版本时的 UI 更新引入 `startTransition`
+
+### 2.5 中优先级: 页面级异步初始化还缺少统一“启动编排 hook”
+
+涉及文件：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/hooks/useCleaner.ts`
+- `src/renderer/src/pages/ExtractorPage.tsx`
+
+问题表现：
+
+- 认证初始化、Cleaner 初始化、配置加载、进度订阅分别散在多个组件和 hook 的 `useEffect` 中
+- 目前逻辑可读，但入口分散，出现启动问题时需要在多个位置来回追
+
+与 skill 对应：
+
+- `advanced-init-once`
+- `async-parallel`
+- `rerender-split-combined-hooks`
+
+建议方向：
+
+- `useAppBootstrap`
+- `useCleanerBootstrap`
+- 把“初始加载”“事件订阅”“持久化恢复”拆成更小的 effect 组
+
+### 2.6 中优先级: 组件树里还有一些可延迟加载的重型弹窗
+
+涉及文件：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/pages/CleanerPage.tsx`
+- `src/renderer/src/components/UpdateDialog.tsx`
+- `src/renderer/src/components/ReportViewerDialog.tsx`
+- `src/renderer/src/components/ExecutionReportDialog.tsx`
+- `src/renderer/src/components/MaterialTypeManagementDialog.tsx`
+
+问题表现：
+
+- 多个重型弹窗在页面初始渲染时就参与静态导入
+- 像 `ReportViewerDialog`、Markdown 渲染、报告浏览、类型管理这类功能明显不是首屏关键路径
+
+与 skill 对应：
+
+- `bundle-dynamic-imports`
+- `bundle-conditional`
+- `bundle-defer-third-party`
+
+建议方向：
+
+- 对非首屏弹窗引入 `React.lazy`
+- 在用户点击前后再加载重型内容
+- 优先收敛 `ReportViewerDialog` 与 `UpdateDialog`
+
+## 3. 当前问题总览
+
+```mermaid
+graph TD
+    App[App.tsx]
+    CleanerPage[CleanerPage.tsx]
+    UseCleaner[useCleaner.ts]
+    ExtractorPage[ExtractorPage.tsx]
+    UpdateDialog[UpdateDialog.tsx]
+    Dialogs[Heavy Dialogs]
+
+    App -->|认证 更新 导航混合| Maintainability[维护成本上升]
+    CleanerPage -->|页面职责过大| Maintainability
+    UseCleaner -->|状态 请求 持久化混合| Maintainability
+    ExtractorPage -->|输入驱动副作用| Maintainability
+    UpdateDialog -->|异步状态来源分散| Maintainability
+    Dialogs -->|非首屏静态导入| Bundle[首屏与包体压力]
+```
+
+## 4. 优化目标
+
+本轮 React 向优化聚焦以下目标：
+
+- 让页面容器组件回归“组装层”
+- 让 hook 边界按职责拆清，不再兼做状态、初始化、请求和交互编排
+- 让跨模块副作用从输入/渲染 effect 中收敛到更稳定的事件或 bootstrap 层
+- 让重型弹窗按需加载，减少首屏包体负担
+- 让异步加载流程更并行、更可追踪、更容易测试
+
+## 5. 分阶段执行计划
+
+### Phase 1: 收敛应用入口与认证启动流
+
+目标：
+
+- 把 `App.tsx` 从“大容器”拆成更清晰的组装层
+- 明确认证、更新、壳层 UI 的职责边界
+
+建议涉及文件：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/hooks/useAuth.ts`
+- `src/renderer/src/hooks/useLogger.ts`
+- 新增 `src/renderer/src/hooks/useAppBootstrap.ts`
+- 新增 `src/renderer/src/components/app/`
+
+建议拆分方向：
+
+- `useAppBootstrap()`
+- `AuthenticatedApp`
+- `UnauthenticatedApp`
+- `AppShell`
+- `UpdateEntryButton`
+
+预期收益：
+
+- 减少 `App.tsx` 的状态面
+- 降低启动 effect 的复杂度
+- 让认证与更新逻辑更容易测试
+
+风险等级：
+
+- 中
+
+验证方式：
+
+- silent login / 登录 / 管理员选人流程回归正常
+- 更新状态订阅正常
+- `npm run typecheck` 与相关测试通过
+
+### Phase 2: 拆分 `CleanerPage` 与 `useCleaner`
+
+目标：
+
+- 进一步拆解 Cleaner 的页面结构和 hook 职责
+- 降低单个 hook / 页面承载的状态数量
+
+建议涉及文件：
+
+- `src/renderer/src/pages/CleanerPage.tsx`
+- `src/renderer/src/hooks/useCleaner.ts`
+- `src/renderer/src/hooks/cleaner/`
+- 新增 `src/renderer/src/components/cleaner/`
+
+建议拆分方向：
+
+- `useCleanerBootstrap`
+- `useCleanerSelection`
+- `useCleanerExecution`
+- `CleanerSidebar`
+- `CleanerToolbar`
+- `CleanerResultsTable`
+- `CleanerExecutionFooter`
+
+预期收益：
+
+- 降低重渲染范围
+- 提高 Cleaner 页面可读性
+- 为表格和执行区单独补测试创造条件
+
+风险等级：
+
+- 中到高
+
+验证方式：
+
+- 校验、筛选、勾选、编辑负责人、执行删除、导出流程手工验证
+- `cleaner` 相关单测通过
+
+### Phase 3: 收敛 Extractor 与共享 Production ID 同步
+
+目标：
+
+- 把输入态和共享业务态解耦
+- 降低输入变化带来的高频副作用
+
+建议涉及文件：
+
+- `src/renderer/src/pages/ExtractorPage.tsx`
+- `src/renderer/src/hooks/useExtractor.ts`
+- 新增 `src/renderer/src/hooks/useSharedProductionIds.ts`
+- 新增 `src/renderer/src/lib/session-storage/`
+
+建议拆分方向：
+
+- 仅在提交或 debounce 后同步共享 ID
+- 抽出 `usePersistentTextState`
+- 把 sessionStorage 与 Electron bridge 副作用集中管理
+
+预期收益：
+
+- 提高输入响应稳定性
+- 降低桥接调用频率
+- 更符合“interaction in event handlers, not passive effects”的原则
+
+风险等级：
+
+- 低到中
+
+验证方式：
+
+- 提取页输入、重置、共享订单号联动正常
+- Cleaner 过滤模式仍能读取共享订单号
+
+### Phase 4: 收敛更新弹窗与异步加载路径
+
+目标：
+
+- 把 `UpdateDialog` 的异步状态切换和版本详情拉取独立出来
+- 降低 `App` 与弹窗之间的状态耦合
+
+建议涉及文件：
+
+- `src/renderer/src/components/UpdateDialog.tsx`
+- `src/renderer/src/App.tsx`
+- 新增 `src/renderer/src/hooks/useUpdateDialogState.ts`
+
+建议拆分方向：
+
+- `useUpdateCatalog`
+- `useReleaseChangelog`
+- 版本切换时用 `startTransition`
+- changelog 拉取加最新请求保护
+
+预期收益：
+
+- 更新弹窗行为更稳定
+- 降低状态竞争和旧请求覆盖新状态的风险
+- 提升大型 Markdown 内容切换时的交互流畅度
+
+风险等级：
+
+- 中
+
+验证方式：
+
+- User/Admin 更新流程验证
+- 版本切换与 changelog 展示正常
+
+### Phase 5: 做弹窗与重型模块按需加载
+
+目标：
+
+- 把非首屏关键弹窗改成按需加载
+- 降低 renderer 初始包体
+
+建议涉及文件：
+
+- `src/renderer/src/App.tsx`
+- `src/renderer/src/pages/CleanerPage.tsx`
+- `src/renderer/src/components/ReportViewerDialog.tsx`
+- `src/renderer/src/components/MaterialTypeManagementDialog.tsx`
+- `src/renderer/src/components/ExecutionReportDialog.tsx`
+- `src/renderer/src/components/UpdateDialog.tsx`
+
+建议拆分方向：
+
+- `React.lazy`
+- 懒加载弹窗容器
+- 打开前预加载关键模块
+
+预期收益：
+
+- 降低首屏 JS 负担
+- 让常用流程优先加载
+
+风险等级：
+
+- 低
+
+验证方式：
+
+- 首屏功能正常
+- 弹窗首次打开正常
+- 打包后 smoke test 正常
+
+### Phase 6: 补强 React 渲染层测试
+
+目标：
+
+- 给这轮 React 收敛提供稳定回归保护
+
+建议涉及文件：
+
+- 新增 `App` 相关组件测试
+- 新增 `CleanerPage` / `useCleaner` 相关测试
+- 新增 `UpdateDialog` 状态流测试
+- 新增 `ExtractorPage` 共享订单号同步测试
+
+优先补测内容：
+
+- 认证启动分支
+- 更新弹窗状态切换
+- Cleaner 筛选与执行状态切换
+- Extractor 输入与共享 ID 同步
+
+预期收益：
+
+- 降低后续 UI/状态重构风险
+- 提高页面容器层的修改信心
+
+风险等级：
+
+- 低
+
+验证方式：
+
+- 单元测试 / 组件测试通过
+- 关键页面 smoke test 正常
+
+## 6. 推荐执行顺序
+
+```mermaid
+graph LR
+    A[Phase 1 App 入口与认证收敛]
+    B[Phase 2 Cleaner 页面与 Hook 拆分]
+    C[Phase 3 Extractor 同步路径收敛]
+    D[Phase 4 UpdateDialog 异步状态收敛]
+    E[Phase 5 弹窗按需加载]
+    F[Phase 6 React 层测试补强]
+
+    A --> B
+    A --> D
+    B --> F
+    C --> F
+    D --> F
+    E --> F
+```
+
+建议优先顺序：
+
+1. 先做 `App` 入口与认证启动流收敛
+2. 再做 `CleanerPage + useCleaner`
+3. 然后收敛 `ExtractorPage` 的共享 ID 同步
+4. 再处理 `UpdateDialog`
+5. 最后做弹窗按需加载
+6. 测试补强贯穿整个过程
+
+## 7. 每阶段完成标准
+
+每一阶段建议采用统一完成标准：
+
+- 页面或 hook 的职责边界明显变清晰
+- 对外行为保持兼容
+- `npm run typecheck` 通过
+- 相关单元测试 / 组件测试通过
+- 关键页面功能手工验证通过
+- 对应说明文档同步更新
+
+## 8. 与现有重构工作的衔接
+
+当前已经完成的工作为这轮 React 优化提供了基础：
+
+- `validation-handler` 已拆成更清晰的主进程结构
+- `useCleaner` 已做过第一轮内部 helpers/api 抽离
+- Electron 侧 preload、update、handler、bootstrap 已经收敛
+
+这意味着 React 侧现在可以更放心地继续拆：
+
+- 页面入口不会再同时背负太多主进程耦合
+- 更新弹窗可以直接依托已收敛的 update service / preload facade
+- Cleaner 页面可以聚焦 UI 与状态，不必再同时处理主进程边界混乱问题
+
+## 9. 后续建议
+
+建议执行方式如下：
+
+1. 先从 `Phase 1` 开始，优先收敛 `App.tsx`
+2. 每完成一个阶段，单独提交
+3. 对 `Cleaner` 和 `UpdateDialog` 每完成一轮都补测试
+4. 在大页面拆分后，再做 bundle 与懒加载优化
+
+如果后续决定正式执行，本计划可作为 React 渲染层重构的主索引文档持续维护。

docs/plans/2026-03-26-report-analysis-dialog-refactor-analysis.md

@@ -0,0 +1,212 @@
+# ReportAnalysisDialog 组件重构分析
+
+## 📊 当前状态分析
+
+### 基本指标
+
+- **总行数**: 948 行
+- **函数/声明**: 9 个
+- **React Hooks**: 20 个使用
+- **职责数量**: 5+ 个主要职责
+
+### 组件职责分析
+
+#### 1. 数据获取与解析 (~150 行)
+
+- `loadAndAnalyzeReports` - 数据加载逻辑
+- `extractReportValues` - 报告内容解析
+- `parseDurationToSeconds` - 时间解析
+
+#### 2. 数据聚合与转换 (~200 行)
+
+- `chartData` useMemo - 按日期聚合
+- `comparisonData` useMemo - 按用户聚合
+- `comparisonChartData` useMemo - 图表数据格式化
+- `allUsers` useMemo - 用户列表提取
+
+#### 3. 状态管理 (~100 行)
+
+- 6 个 useState hooks
+- 5 个 useCallback handlers
+- 复杂的状态交互逻辑
+
+#### 4. UI 控制与交互 (~200 行)
+
+- 指标选择按钮
+- 视图模式切换
+- 用户筛选器
+- 加载/错误状态显示
+
+#### 5. 图表渲染 (~300 行)
+
+- Recharts 图表配置
+- 两个不同的视图模式
+- 自定义 Tooltip 组件
+- 图表样式和布局
+
+## 🎯 重构目标
+
+### 主要问题
+
+1. **单一文件过大**: 难以维护和理解
+2. **职责混乱**: 数据获取、处理、UI 混在一起
+3. **复用性差**: 逻辑和 UI 紧耦合
+4. **测试困难**: 难以单独测试各个部分
+
+### 重构原则
+
+1. **单一职责**: 每个模块只负责一件事
+2. **可复用性**: 提取通用逻辑到 hooks
+3. **可测试性**: 分离逻辑和 UI
+4. **可维护性**: 清晰的文件结构
+
+## 📦 建议的文件结构
+
+```
+src/renderer/src/components/report-analysis/
+├── index.tsx                          # 主组件入口 (~150 行)
+├── hooks/
+│   ├── useReportData.ts              # 数据获取和解析 (~100 行)
+│   ├── useChartData.ts               # 数据聚合和转换 (~150 行)
+│   └── useReportFilters.ts           # 筛选状态管理 (~80 行)
+├── components/
+│   ├── ReportChart.tsx               # 图表组件 (~200 行)
+│   ├── MetricSelector.tsx            # 指标选择器 (~80 行)
+│   ├── ViewModeToggle.tsx            # 视图模式切换 (~50 行)
+│   ├── UserFilter.tsx                # 用户筛选器 (~100 行)
+│   ├── CustomTooltip.tsx             # 自定义 tooltip (~100 行)
+│   ├── ComparisonTooltip.tsx         # 对比 tooltip (~80 行)
+│   └── LoadingState.tsx              # 加载状态组件 (~60 行)
+├── utils/
+│   ├── parser.ts                     # 报告解析工具 (~100 行)
+│   ├── aggregators.ts                # 数据聚合函数 (~120 行)
+│   └── formatters.ts                 # 格式化工具 (~60 行)
+└── types.ts                          # 类型定义 (~80 行)
+```
+
+## 🔧 重构方案
+
+### 方案 A: 完全重构 (推荐)
+
+**优点**: 最大程度的解耦和可维护性
+**缺点**: 需要更多时间，可能引入新问题
+**时间估计**: 2-3 小时
+
+### 方案 B: 渐进式重构
+
+**优点**: 风险较低，可以逐步验证
+**缺点**: 过渡期代码可能不够优雅
+**时间估计**: 1-2 小时
+
+### 方案 C: 最小化重构
+
+**优点**: 改动最小，风险最低
+**缺点**: 解决根本问题有限
+**时间估计**: 30-45 分钟
+
+## 📝 详细重构步骤
+
+### Phase 1: 提取类型和工具函数 (低风险)
+
+1. 创建 `types.ts` - 集中管理所有类型定义
+2. 创建 `utils/parser.ts` - 提取报告解析逻辑
+3. 创建 `utils/aggregators.ts` - 提取数据聚合逻辑
+
+### Phase 2: 提取自定义 Hooks (中风险)
+
+1. 创建 `hooks/useReportData.ts` - 数据获取和解析
+2. 创建 `hooks/useChartData.ts` - 数据聚合和转换
+3. 创建 `hooks/useReportFilters.ts` - 筛选状态管理
+
+### Phase 3: 提取 UI 组件 (中风险)
+
+1. 创建 `components/MetricSelector.tsx`
+2. 创建 `components/ViewModeToggle.tsx`
+3. 创建 `components/UserFilter.tsx`
+4. 创建 `components/ReportChart.tsx`
+
+### Phase 4: 重构主组件 (高风险)
+
+1. 简化 `index.tsx` 只保留组合逻辑
+2. 添加错误边界
+3. 优化加载状态
+
+## 🎯 重构后的预期效果
+
+### 代码行数分布
+
+- 主组件: ~150 行 (减少 84%)
+- 每个 hook: ~80-150 行
+- 每个 UI 组件: ~50-200 行
+- 工具函数: ~60-120 行
+
+### 可维护性提升
+
+- ✅ 单个文件更小，更易理解
+- ✅ 职责清晰，修改影响范围小
+- ✅ 更容易进行单元测试
+- ✅ 可以独立优化各个部分
+
+### 性能影响
+
+- ➡️ 性能基本不变或略有提升
+- ➡️ 代码分割优化可能略微改善首次加载
+- ➡️ 更好的 memoization 机会
+
+## 🚨 风险评估
+
+### 高风险区域
+
+- 图表配置逻辑（Recharts 配置复杂）
+- 数据转换和聚合（业务逻辑密集）
+- 状态同步（多个状态之间的交互）
+
+### 缓解措施
+
+- 保持现有测试通过
+- 逐步重构，每步验证
+- 添加 TypeScript 严格检查
+- 保留原有功能注释
+
+## 📋 验证清单
+
+重构完成后需要验证：
+
+- [ ] 所有现有功能正常工作
+- [ ] 单元测试通过
+- [ ] E2E 测试通过
+- [ ] 类型检查无错误
+- [ ] 性能无明显下降
+- [ ] 代码风格符合规范
+
+## 🤔 建议的实施顺序
+
+### 推荐方案: 渐进式重构 (方案 B)
+
+**第1步**: 提取类型和工具函数 (15分钟)
+
+- 创建类型定义文件
+- 提取解析工具函数
+- 验证编译和测试
+
+**第2步**: 提取自定义 Hooks (30分钟)
+
+- 提取数据获取逻辑
+- 提取数据聚合逻辑
+- 提取筛选状态管理
+- 验证功能正常
+
+**第3步**: 提取 UI 组件 (30分钟)
+
+- 提取控制面板组件
+- 提取图表组件
+- 提取状态显示组件
+- 验证交互正常
+
+**第4步**: 简化主组件 (15分钟)
+
+- 重构为组合式组件
+- 清理代码和注释
+- 最终验证
+
+**总计**: 约 90 分钟，分4个阶段，每个阶段都可以独立验证

docs/portable-auto-update-architecture.md

@@ -0,0 +1,274 @@
+# ERPAuto 便携版自动更新说明
+
+## 概览
+
+当前实现的是一套面向 Windows 便携版的自定义更新系统，核心特点如下：
+
+- 基于 S3 兼容对象存储分发更新包
+- 按登录用户角色决定更新通道和行为
+- `User` 只跟随 `Stable`
+- `Admin` 同时可见 `Stable` 和 `Preview`
+- 更新包可后台下载，但安装必须由用户触发
+- 安装阶段使用独立的原生 `portable-updater.exe` 完成 exe 替换
+
+## 核心组件
+
+- 主进程更新服务
+  路径：[`src/main/services/update/update-service.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-service.ts)
+- 更新规则工具
+  路径：[`src/main/services/update/update-utils.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-utils.ts)
+- 更新 IPC
+  路径：[`src/main/ipc/update-handler.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/ipc/update-handler.ts)
+- 前端更新弹窗
+  路径：[`src/renderer/src/components/UpdateDialog.tsx`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/components/UpdateDialog.tsx)
+- 前端更新入口
+  路径：[`src/renderer/src/App.tsx`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/App.tsx)
+- 原生更新器
+  路径：[`build/PortableUpdater.cs`](/d:/FileLib/Projects/CodeMigration/ERPAuto/build/PortableUpdater.cs)
+- 更新器编译脚本
+  路径：[`scripts/compile-updater.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/compile-updater.js)
+- 发布准备脚本
+  路径：[`scripts/prepare-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/prepare-release.js)
+- 发布上传脚本
+  路径：[`scripts/upload-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/upload-release.js)
+
+## 角色策略
+
+### `User`
+
+- 只读取 `stable/index.json`
+- 目标版本永远是最新 `Stable`
+- 如果当前客户端是 `Preview`，即使本地版本号更高，也会被视为“需要更新回稳定版”
+- 后台会自动下载推荐的 `Stable`
+- 用户点击后执行安装
+
+### `Admin`
+
+- 同时读取 `stable/index.json` 和 `preview/index.json`
+- 不自动下载
+- 只展示可选版本和更新说明
+- 由管理员手动选择版本并触发下载、安装
+
+## 当前安装包身份
+
+构建时会注入 `__APP_CHANNEL__`，用于标识当前客户端自身是 `stable` 还是 `preview`。
+
+这个值的作用非常关键：
+
+- 决定 `User` 是否需要从 `Preview` 洗回 `Stable`
+- 决定 `Admin` 当前处于哪条版本线
+- 决定更新弹窗中当前通道的展示
+
+相关声明：
+
+- [`src/shared/app-env.d.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/shared/app-env.d.ts)
+- [`src/renderer/src/env.d.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/renderer/src/env.d.ts)
+
+## 远端目录结构
+
+更新目录按通道分开：
+
+```text
+updates/win-portable/stable/index.json
+updates/win-portable/stable/artifacts/erpauto-<version>-stable-portable.exe
+updates/win-portable/stable/changelogs/<version>.md
+
+updates/win-portable/preview/index.json
+updates/win-portable/preview/artifacts/erpauto-<version>-preview-portable.exe
+updates/win-portable/preview/changelogs/<version>.md
+```
+
+`index.json` 的每个条目至少包含：
+
+- `version`
+- `channel`
+- `artifactKey`
+- `sha256`
+- `size`
+- `publishedAt`
+- `changelogKey`
+- `notesSummary`
+
+## 总体架构图
+
+```mermaid
+flowchart LR
+  A[Electron Renderer] -->|IPC| B[Update Handler]
+  B --> C[Update Service]
+  C --> D[S3-Compatible Object Storage]
+  C --> E[Local Cache<br/>pending-update]
+  C --> F[portable-updater.exe]
+  F --> G[Replace Old EXE]
+  G --> H[Launch New EXE]
+```
+
+## 登录后的更新时序
+
+```mermaid
+sequenceDiagram
+  participant U as User/Admin
+  participant R as Renderer
+  participant A as Auth Handler
+  participant S as Update Service
+  participant O as Object Storage
+
+  U->>R: 登录 / 无感登录
+  R->>A: auth.login / auth.silentLogin
+  A->>S: setUserContext(userType)
+  S->>O: 读取 stable/index.json
+  alt Admin
+    S->>O: 读取 preview/index.json
+  end
+  S->>S: 计算推荐版本与状态
+  alt User 且需要更新
+    S->>O: 下载最新 Stable
+    S->>S: 校验 sha256
+    S-->>R: UPDATE_STATUS_CHANGED(downloaded)
+  else Admin
+    S-->>R: UPDATE_STATUS_CHANGED(available)
+  end
+```
+
+## `User` 更新决策图
+
+```mermaid
+flowchart TD
+  A[当前用户是 User] --> B[读取 stable 最新版本]
+  B --> C{当前通道是 preview?}
+  C -- 是 --> D[强制推荐回 Stable]
+  C -- 否 --> E{当前版本 != 最新 Stable?}
+  E -- 是 --> F[推荐最新 Stable]
+  E -- 否 --> G[不提示更新]
+  D --> H[后台自动下载]
+  F --> H
+  H --> I[校验 sha256]
+  I --> J[导航栏显示 立即更新]
+```
+
+## `Admin` 更新决策图
+
+```mermaid
+flowchart TD
+  A[当前用户是 Admin] --> B[读取 stable 目录]
+  A --> C[读取 preview 目录]
+  B --> D[合并目录]
+  C --> D
+  D --> E{是否存在更高版本?}
+  E -- 是 --> F[推荐更高版本]
+  E -- 否 --> G{是否存在跨通道可切换版本?}
+  G -- 是 --> H[推荐跨通道版本]
+  G -- 否 --> I[不展示更新]
+  F --> J[打开弹窗后手动下载]
+  H --> J
+```
+
+## 安装阶段时序
+
+```mermaid
+sequenceDiagram
+  participant R as Renderer
+  participant S as Update Service
+  participant P as portable-updater.exe
+  participant X as Current Portable EXE
+  participant N as New Downloaded EXE
+
+  R->>S: installDownloaded()
+  S->>P: 启动 portable-updater.exe
+  S->>X: app.quit()
+  P->>X: 等待旧进程退出
+  P->>X: 等待文件解锁
+  P->>X: 备份为 .bak
+  P->>N: 移动到目标路径
+  P->>X: 启动新版本
+  P->>X: 删除 .bak
+```
+
+## 本地目录与日志
+
+### 下载缓存
+
+```text
+%APPDATA%\erpauto\pending-update\
+```
+
+### 更新器运行文件与日志
+
+```text
+%APPDATA%\erpauto\updates\
+  portable-updater.exe
+  portable-update.log
+  portable-launch.log
+```
+
+## 发布流程
+
+### 1. 构建
+
+```powershell
+$env:APP_CHANNEL="stable"
+npm run build:win
+```
+
+### 2. 准备发布目录
+
+```powershell
+node scripts/prepare-release.js --channel stable --changelog docs/releases/1.3.2-rebuild.md
+```
+
+### 3. 上传到对象存储
+
+```powershell
+npm run release:upload -- --channel stable --verify
+```
+
+## 发布流程图
+
+```mermaid
+flowchart TD
+  A[build:win] --> B[生成 dist/erpauto-portable.exe]
+  B --> C[prepare-release]
+  C --> D[复制 artifact]
+  C --> E[复制 changelog]
+  C --> F[生成 index.json]
+  F --> G[release-upload]
+  G --> H[上传到对象存储]
+  H --> I[verify 远端 index.json]
+```
+
+## 版本排序规则
+
+为了避免“后发布低版本覆盖高版本”的问题，当前排序规则是：
+
+- 优先按版本号降序
+- 同版本再按 `publishedAt` 降序
+
+这条规则同时存在于：
+
+- [`src/main/services/update/update-utils.ts`](/d:/FileLib/Projects/CodeMigration/ERPAuto/src/main/services/update/update-utils.ts)
+- [`scripts/prepare-release.js`](/d:/FileLib/Projects/CodeMigration/ERPAuto/scripts/prepare-release.js)
+
+## 失败保护
+
+当前实现包含这些基本保护：
+
+- 缺失 `preview/index.json` 时，按空列表处理，不中断整体更新检查
+- 更新包下载完成后必须校验 `sha256`
+- `portable-updater.exe` 会等待旧进程退出和目标文件解锁
+- 替换前先备份旧 exe 为 `.bak`
+- 替换失败时尝试回滚
+
+## 当前已验证通过的能力
+
+- `1.3.1 -> 1.3.2` 的 `Stable` 发布链路已打通
+- 新分支实现能够成功构建 Windows 便携版
+- 原生 `portable-updater.exe` 能成功编译并被打包带入资源目录
+- 本地发布目录生成正常
+- 上传脚本可将更新包和索引发布到对象存储
+- 客户端真实升级流程已验证通过
+
+## 后续可继续优化的点
+
+- 将 `UpdateService` 进一步拆分，降低文件复杂度
+- 将日志策略区分成“正式日志”和“诊断日志”
+- 增加更多针对下载与安装阶段的单测
+- 将完整构建发布链路整理为一键化脚本

docs/releases/1.3.1-rebuild.md

@@ -0,0 +1,11 @@
+# 1.3.1 Rebuild
+
+## Highlights
+
+- Rebuilt the portable auto-update flow on a clean branch.
+- Added role-aware update catalog handling for `Stable` and `Preview`.
+- Added native `portable-updater.exe` handoff for portable upgrades.
+
+## Notes
+
+- This release is intended for rebuild validation on the new implementation branch.

docs/releases/1.3.2-rebuild.md

@@ -0,0 +1,11 @@
+# 1.3.2 Rebuild
+
+## Highlights
+
+- Published the clean-branch portable auto-update implementation.
+- Added role-aware update checks, changelog loading, and update dialog UI.
+- Added native `portable-updater.exe` build and packaging flow.
+
+## Notes
+
+- This release is intended to validate `1.3.1 -> 1.3.2` upgrade flow on the rebuilt implementation.

docs/releases/1.4.0.md

@@ -0,0 +1,44 @@
+# 1.4.0
+
+## 亮点
+
+- 新增 Windows 便携版自动更新能力，支持 `stable` / `preview` 双通道发布。
+- 更新策略与登录用户角色联动：
+  - `User` 只接收稳定版更新
+  - `Admin` 可查看并切换稳定版与预览版
+- 更新包下载完成后，可在应用内查看更新说明并执行自动替换升级。
+
+## 自动更新
+
+- 新增便携版更新服务，支持：
+  - 登录后自动检查更新
+  - 后台下载更新包
+  - 展示更新状态与更新日志
+  - 退出后自动替换旧版本并重启
+- 更新器采用原生 `portable-updater.exe`，不再依赖 PowerShell 脚本。
+- 支持预览版与稳定版分通道发布，并兼容普通用户从 `preview` 回退到 `stable` 的场景。
+
+## 界面与交互
+
+- 顶部导航新增更新入口。
+- 新增更新对话框，可展示 changelog 并执行安装。
+- 报告查看器增强了 Markdown 渲染体验，支持 GitHub 风格样式与代码高亮。
+
+## 发布与维护
+
+- 新增一键发布命令：
+
+```bash
+npm run release:publish -- --channel stable
+npm run release:publish -- --channel preview
+```
+
+- 发布脚本会自动串联构建、整理发布物料、上传和远端索引校验。
+- 上传逻辑已优化为默认增量上传，只上传当前版本的 artifact、changelog 和 `index.json`。
+- 补充了构建发布文档和自动更新架构文档，方便后续维护。
+
+## 文档整理
+
+- 浏览器部署文档已迁移并整理到 `docs/browser/`。
+- 新增构建与发布流程说明文档。
+- 精简了 `CLAUDE.md`，让 AI 代理指导文档更聚焦、更易维护。

docs/releases/1.4.1.md

@@ -0,0 +1,11 @@
+# 1.4.1
+
+## 改进
+
+- 报告查看器的报告选择器升级为可搜索下拉框。
+- 报表较多时，可以通过输入关键字快速筛选目标报告，减少滚动查找成本。
+
+## 体验优化
+
+- 优化了报告选择交互，选择流程更适合长列表场景。
+- 同步合并 `dev` 分支中已完成的报告查看器可用性改进。

docs/releases/1.4.2.md

@@ -0,0 +1,11 @@
+# 1.4.2
+
+## 架构优化
+
+- 重构主进程启动流程和 IPC 编排层，按领域拆分 preload API。
+- 解耦更新服务职责，对话框改为懒加载以优化性能。
+
+## 质量改进
+
+- 修复类型检查问题，加固启动流程和认证健壮性。
+- 新增核心模块测试覆盖，完善开发者文档。

docs/releases/1.5.0.md

@@ -0,0 +1,13 @@
+# 1.5.0
+
+## 核心功能
+
+- 新增 Playwright 浏览器自动下载，首次启动自动从 S3 获取。
+- 实时显示下载进度（百分比、速度、剩余时间）。
+- 支持取消下载，网络异常自动重试。
+- 下载完成后自动进入登录界面，无需重启应用。
+
+## 体验优化
+
+- 修复下载完成后卡在"认证中"的问题。
+- 修复速度和剩余时间显示为"计算中"的问题。

docs/releases/1.5.1.md

@@ -0,0 +1,7 @@
+# 1.5.1
+
+## 体验优化
+
+- User 用户登录后立即进入应用，更新检查和下载在后台运行。
+- 下载完成后自动显示更新提示，整个过程对用户透明。
+- 优化登录流程体验，消除更新下载导致的阻塞时间。

docs/releases/1.6.0.md

@@ -0,0 +1,14 @@
+# 1.6.0
+
+## 核心功能
+
+- 新增管理员报表分析功能，支持多维度数据统计和可视化。
+- 提供按日期聚合和用户对比两种视图模式。
+- 支持处理订单数、删除物料数、错误数量等 7 种指标分析。
+- 提供每订单平均耗时等效率指标，帮助识别性能瓶颈。
+
+## 体验优化
+
+- 对比视图下自动限制指标单选，避免图表信息过载。
+- 切换视图模式时智能保留已选指标，提升交互流畅度。
+- 优化时间解析逻辑，准确提取执行耗时数据。

docs/releases/1.6.1.md

@@ -0,0 +1,42 @@
+# 1.6.1
+
+## 核心改进
+
+- **重大重构**：将报告分析组件从 948 行单体组件重构为模块化架构，拆分为 11 个专注的模块文件。
+- **代码质量提升**：主组件代码量减少 79%（948 → 200 行），显著提升可维护性和可读性。
+- **架构优化**：分离数据获取、状态管理和 UI 渲染逻辑，遵循单一职责原则。
+
+## 体验优化
+
+- **修复 tooltip 显示问题**：解决执行时间在提示框中重复显示的问题，现在只显示一次格式化后的时间值。
+- **统一时间格式**：所有时间数值统一保留 1 位小数，提升数据显示的一致性和专业度。
+- **优化界面布局**：精简 tooltip 底部信息，避免冗余内容干扰用户视线。
+
+## 性能优化
+
+- **组件渲染优化**：将 tooltip 组件移出父组件并使用 React.memo，减少不必要的重新渲染。
+- **正则表达式优化**：预编译正则表达式模式，避免在循环中重复创建，提升数据处理效率。
+- **状态更新优化**：使用函数式 setState 更新，避免闭包陷阱和过期的状态读取。
+- **回调函数优化**：使用 useCallback 稳定回调函数引用，减少子组件的不必要更新。
+
+## 开发体验
+
+- **模块化设计**：将复杂组件拆分为可复用的 hooks 和 UI 组件，便于单独测试和维护。
+- **类型安全**：完整的 TypeScript 类型定义，提升开发时的类型检查和 IDE 支持。
+- **代码组织**：清晰的文件结构（types、hooks、components、utils），便于团队协作和代码导航。
+- **向后兼容**：保持原有 API 接口不变，现有使用方式无需修改。
+
+## 技术细节
+
+- 应用 Vercel React 最佳实践，包括：
+  - 避免内联组件定义（rerender-no-inline-components）
+  - 提升正则表达式创建位置（js-hoist-regexp）
+  - 使用函数式状态更新（rerender-functional-setState）
+  - 最小化回调依赖项（rerender-dependencies）
+- 新增自定义 hooks：useReportData、useChartData、useReportFilters
+- 新增 UI 组件：MetricSelector、ViewModeToggle、UserFilter、ReportChart
+- 新增工具函数：数据解析器和聚合器
+
+## 破坏性变更
+
+无破坏性变更，所有现有功能保持完全兼容。

docs/releases/1.6.2.md

@@ -0,0 +1,6 @@
+# 1.6.2
+
+## 系统优化
+
+- 简化用户角色体系，移除未使用的 Guest 角色。
+- 优化类型安全性，加强用户认证流程健壮性。

docs/releases/1.7.0.md

@@ -0,0 +1,18 @@
+# 1.7.0
+
+## 核心功能
+
+- 新增提取操作历史记录功能，每次执行提取后自动保存订单号和总排号。
+- 支持查看历史批次详情，包含操作时间、订单数、记录数、成功/失败统计。
+- 批次记录可展开查看，显示总排号与订单号的对应关系。
+
+## 界面与交互
+
+- 提取页面新增"操作历史"按钮，点击打开历史记录对话框。
+- 管理员可查看所有用户的历史记录，普通用户仅查看自己的记录。
+- 支持删除历史批次，管理员可删除任意批次，普通用户仅可删除自己的记录。
+
+## 数据存储
+
+- 新增数据库表 `ExtractorOperationHistory`，支持 SQL Server 和 MySQL。
+- 需执行数据库脚本创建表结构（详见项目文档）。

docs/releases/1.7.1.md

@@ -0,0 +1,6 @@
+# 1.7.1
+
+## 问题修复
+
+- 修复 MySQL 数据库下操作历史查询报错问题。
+- 优化历史记录数据结构，支持按订单统计记录数量。

docs/releases/1.7.2.md

@@ -0,0 +1,6 @@
+# 1.7.2
+
+## 问题修复
+
+- 修复操作历史时间显示错误（时区转换导致时间快8小时）。
+- 操作历史支持一键复制总排号和订单号。

docs/releases/1.8.0.md

@@ -0,0 +1,12 @@
+# 1.8.0
+
+## 权限控制
+
+- 操作历史删除按钮仅对管理员可见，普通用户无法删除历史记录。
+- 修复用户状态传递问题，确保权限判断正确生效。
+
+## 界面与交互
+
+- 管理员可使用多选标签（Chip）按用户筛选操作历史。
+- 支持同时选择多个用户查看记录，点击标签即可切换选中状态。
+- 添加"清空筛选"按钮，一键恢复显示所有用户记录。

docs/releases/README.md

@@ -0,0 +1,106 @@
+# 发布文档规范
+
+## 文档定位
+
+发布文档面向**最终用户**，不是技术开发日志。内容应该简洁、清晰、有价值。
+
+## 内容风格
+
+### ✅ 推荐写法
+
+- **用户视角**：描述功能带来的价值，而非技术实现
+- **简洁明了**：每条更新 1-2 句话，避免冗长
+- **分类清晰**：按功能模块或改进类型分组
+
+**示例**：
+
+```markdown
+## 核心功能
+
+- 新增 Playwright 浏览器自动下载，首次启动自动从 S3 获取。
+- 实时显示下载进度（百分比、速度、剩余时间）。
+```
+
+### ❌ 避免写法
+
+- 技术细节（文件路径、代码实现、架构设计）
+- 开发过程描述（"重构了"、"优化了算法"）
+- 过长的段落（超过 2 行）
+
+## 文档结构
+
+### 标准格式
+
+```markdown
+# {版本号}
+
+## {分类 1}
+
+- {更新点 1}
+- {更新点 2}
+
+## {分类 2}
+
+- {更新点 1}
+- {更新点 2}
+```
+
+### 常见分类
+
+- `核心功能` - 新功能、重大特性
+- `改进` / `体验优化` - 现有功能优化
+- `问题修复` - Bug 修复
+- `界面与交互` - UI/UX 改进
+
+## 篇幅要求
+
+- **小版本**（x.x.1）：5-10 行
+- **中版本**（x.x.0）：10-20 行
+- **大版本**（x.0.0）：20-40 行
+
+## 示例参考
+
+### 简洁版（1.4.2）
+
+```markdown
+# 1.4.2
+
+## 架构优化
+
+- 重构主进程启动流程和 IPC 编排层，按领域拆分 preload API。
+- 解耦更新服务职责，对话框改为懒加载以优化性能。
+
+## 质量改进
+
+- 修复类型检查问题，加固启动流程和认证健壮性。
+- 新增核心模块测试覆盖，完善开发者文档。
+```
+
+### 详细版（1.4.0）
+
+```markdown
+# 1.4.0
+
+## 亮点
+
+- 新增 Windows 便携版自动更新能力，支持 `stable` / `preview` 双通道发布。
+- 更新策略与登录用户角色联动。
+
+## 自动更新
+
+- 新增便携版更新服务，支持登录后自动检查更新。
+- 更新器采用原生 `portable-updater.exe`，不再依赖 PowerShell 脚本。
+```
+
+## 发布流程
+
+1. 创建版本文件：`docs/releases/{version}.md`
+2. 参考现有文档风格编写
+3. 提交 git：`git add docs/releases/{version}.md`
+4. 提交信息：`docs: add release notes for version {version}`
+
+## 维护说明
+
+- 发布文档一旦创建，**不再修改**（除非有重大错误）
+- 技术细节放入 `docs/` 下的专题文档
+- Changelog 由发布脚本自动生成，不手动维护

docs/use-cleaner-refactor-overview.md

@@ -0,0 +1,246 @@
+# useCleaner 重构说明
+
+本文档记录 `src/renderer/src/hooks/useCleaner.ts` 的第一阶段重构工作。目标不是一次性把整个 Cleaner 页面完全组件化，而是优先拆出共享类型、纯函数和 IPC 编排逻辑，让 `useCleaner` 从“大而全逻辑容器”逐步收敛为“组合层”。
+
+## 1. 重构背景
+
+重构前，`useCleaner.ts` 同时负责：
+
+- 页面初始化
+- 权限判断
+- sessionStorage 持久化
+- 校验请求
+- 结果筛选
+- 勾选状态处理
+- 删除计划构建
+- 保存物料变更
+- Cleaner 执行编排
+- 导出编排
+- 弹窗确认
+- 报告状态维护
+
+这导致它虽然名义上是一个 hook，但实际上已经接近一个“前端页面服务总线”。
+
+## 2. 重构目标
+
+本次重构目标是：
+
+- 提取共享类型，消除重复定义
+- 提取纯函数，隔离无副作用逻辑
+- 提取 IPC / 异步编排，隔离对 `window.electron` 的直接调用
+- 保持 `useCleaner()` 返回值和 `CleanerPage.tsx` 使用方式不变
+
+## 3. 重构后结构
+
+```mermaid
+graph TD
+    Page[CleanerPage.tsx]
+    Hook[useCleaner.ts]
+
+    subgraph CleanerHookModules[Cleaner Hook Modules]
+        Types[hooks/cleaner/types.ts]
+        Helpers[hooks/cleaner/helpers.ts]
+        Api[hooks/cleaner/api.ts]
+    end
+
+    subgraph ExternalDeps[External Dependencies]
+        Electron[window.electron]
+        Store[useAppStore / Toast]
+        Dialog[ConfirmDialog]
+    end
+
+    Page --> Hook
+    Hook --> Types
+    Hook --> Helpers
+    Hook --> Api
+    Hook --> Store
+    Hook --> Dialog
+    Api --> Electron
+```
+
+## 4. 本次拆分内容
+
+### 4.1 共享类型
+
+新增：
+
+- `src/renderer/src/hooks/cleaner/types.ts`
+
+统一收敛了以下类型：
+
+- `ValidationRequest`
+- `ValidationResult`
+- `ValidationStats`
+- `ValidationResponsePayload`
+- `CleanerProgress`
+- `CleanerReportData`
+- `CleanerInitializationResult`
+- `CleanerConfigResult`
+
+这一步解决了原来多个文件重复定义同类类型的问题，比如：
+
+- `useCleaner.ts`
+- `useValidation.ts`
+- `ExecutionReportDialog.tsx`
+
+### 4.2 纯函数与数据构造
+
+新增：
+
+- `src/renderer/src/hooks/cleaner/helpers.ts`
+
+提取出的纯函数包括：
+
+- `getStoredBoolean()`
+- `getStoredValidationMode()`
+- `filterValidationResults()`
+- `buildDeletionPlan()`
+- `buildExportItems()`
+
+这些逻辑之前都散落在 `useCleaner.ts` 的 `useMemo` 或事件处理函数里，现在可以单独测试。
+
+### 4.3 IPC 与异步编排
+
+新增：
+
+- `src/renderer/src/hooks/cleaner/api.ts`
+
+提取出的异步编排包括：
+
+- `initializeCleanerPage()`
+- `loadCleanerConfig()`
+- `runValidationRequest()`
+- `saveDeletionPlan()`
+- `reloadManagers()`
+- `runCleanerExecution()`
+- `exportCleanerResults()`
+
+这样做之后，`useCleaner.ts` 不再需要在每个 handler 里直接拼接 `window.electron.xxx` 调用细节。
+
+## 5. useCleaner 的角色变化
+
+```mermaid
+flowchart LR
+    subgraph Before[重构前]
+        A[useCleaner.ts]
+        A --> A1[本地状态]
+        A --> A2[筛选逻辑]
+        A --> A3[删除计划构建]
+        A --> A4[执行清理请求]
+        A --> A5[导出请求]
+        A --> A6[初始化请求]
+        A --> A7[共享类型定义]
+    end
+
+    subgraph After[重构后]
+        B[useCleaner.ts]
+        B --> B1[组合状态]
+        B --> B2[调用 helpers]
+        B --> B3[调用 api]
+
+        C[helpers.ts]
+        D[api.ts]
+        E[types.ts]
+
+        B --> C
+        B --> D
+        B --> E
+    end
+```
+
+重构后，`useCleaner.ts` 更接近“组合层”：
+
+- 管理 React state
+- 串联用户交互流程
+- 调用 helpers 和 api
+- 将最终能力暴露给页面
+
+## 6. 受影响的文件
+
+### 6.1 主体修改
+
+- `src/renderer/src/hooks/useCleaner.ts`
+- `src/renderer/src/hooks/useValidation.ts`
+- `src/renderer/src/components/ExecutionReportDialog.tsx`
+
+### 6.2 新增模块
+
+- `src/renderer/src/hooks/cleaner/types.ts`
+- `src/renderer/src/hooks/cleaner/helpers.ts`
+- `src/renderer/src/hooks/cleaner/api.ts`
+
+### 6.3 新增测试
+
+- `tests/unit/cleaner-helpers.test.ts`
+
+## 7. 具体收益
+
+### 7.1 类型一致性提升
+
+之前 `ValidationResult`、`CleanerProgress` 在多个文件重复定义，修改字段时容易遗漏。  
+现在统一从 `hooks/cleaner/types.ts` 引用，降低了类型漂移风险。
+
+### 7.2 可测试性提升
+
+原先删除计划构建、筛选和导出映射逻辑只能通过 hook 间接覆盖。  
+现在这些逻辑已经被抽成纯函数，可以直接做单测。
+
+### 7.3 Hook 复杂度下降
+
+虽然 `useCleaner.ts` 还没有变成一个很小的文件，但其中的“细节密度”已经明显下降：
+
+- 数据变换逻辑外提
+- API 编排逻辑外提
+- 重复类型移除
+
+### 7.4 为下一步组件拆分做准备
+
+后续如果要拆 `CleanerPage.tsx`：
+
+- 左侧筛选区
+- 表格工具栏
+- 底部执行区
+
+这些组件就可以直接消费已经整理好的 hook 能力，而不是继续把逻辑往页面里塞。
+
+## 8. 验证方式
+
+本次重构后执行了以下验证：
+
+- `npm run typecheck:node`
+- `tests/unit/cleaner-helpers.test.ts`
+- `tests/unit/cleaner.test.ts`
+
+## 9. 新增测试覆盖点
+
+`tests/unit/cleaner-helpers.test.ts` 覆盖了：
+
+- 非管理员筛选逻辑
+- 删除计划构建逻辑
+- 导出数据构建逻辑
+
+## 10. 仍然保留在 useCleaner 中的内容
+
+为了控制改动风险，这次没有继续下沉以下能力：
+
+- `ConfirmDialog` 的 Promise 封装
+- 编辑状态 `editingCell / editValue`
+- `isRunning / isExecuting / isReportDialogOpen` 等 UI 状态
+- 页面层直接依赖的完整返回对象
+
+这些能力仍然保留在 `useCleaner.ts`，因为它们和当前页面交互绑定较深。
+
+## 11. 下一步建议
+
+基于目前的结构，建议下一阶段继续做：
+
+1. 拆 `CleanerPage.tsx` 为“左侧筛选区”和“右侧结果与执行区”两个子组件。
+2. 将 `showConfirmDialog()` 封装为独立 hook，例如 `useConfirmDialogController()`。
+3. 将 inline edit 相关逻辑提取到更专门的 manager-assignment controller。
+4. 视情况把 Cleaner 相关状态进一步收敛到专门 store 或 domain hook 中。
+
+## 12. 总结
+
+这次 `useCleaner` 重构的核心价值，不是“让文件立刻变得很小”，而是先把最容易复用、最适合测试、最不应继续堆在 hook 里的部分拆出来。
+
+它为接下来的页面组件拆分提供了一个更稳的基础，也让 Cleaner 模块开始从“页面驱动逻辑”向“模块化前端能力”转变。

docs/validation-handler-refactor-overview.md

@@ -0,0 +1,217 @@
+# validation-handler 重构说明
+
+本文档记录 `src/main/ipc/validation-handler.ts` 的第一阶段重构工作，目标是把“超大 IPC Handler”拆回到更清晰的职责边界中，同时保持对外 IPC 协议和业务行为不变。
+
+## 1. 重构背景
+
+重构前，`validation-handler.ts` 同时承担了以下职责：
+
+- IPC 通道注册
+- 跨页面共享 `Production ID` 状态
+- 数据库连接创建与释放
+- MySQL / SQL Server 方言分支
+- 输入识别与订单号解析
+- 物料校验结果组装
+- Cleaner 执行前数据准备
+- 物料查询与富化
+
+这种结构的主要问题是：
+
+- 文件过大，理解成本高
+- 数据库和业务规则直接堆叠在 IPC 层
+- 复用困难，后续其他模块无法直接复用这些逻辑
+- 单元测试难以细粒度编写
+
+## 2. 重构目标
+
+本次重构聚焦在“职责下沉、行为不变”：
+
+- 保留原有 IPC channel 和返回结构
+- 将共享状态、数据库工厂、输入解析、验证业务流程拆出
+- 让 `validation-handler.ts` 回归为薄 IPC 壳层
+- 为后续继续拆 `cleaner-handler`、前端校验流程提供复用基础
+
+## 3. 重构后结构
+
+```mermaid
+graph TD
+    Renderer[Renderer / Preload]
+    Handler[validation-handler.ts]
+
+    subgraph ValidationServices[Validation Services]
+        Store[shared-production-ids-store.ts]
+        DbFactory[validation-database.ts]
+        InputSvc[production-input-service.ts]
+        AppSvc[validation-application-service.ts]
+    end
+
+    subgraph ExistingServices[Existing Services]
+        MaterialsDAO[MaterialsToBeDeletedDAO]
+        PlanDAO[DiscreteMaterialPlanDAO]
+        Session[SessionManager]
+    end
+
+    Renderer --> Handler
+    Handler --> Session
+    Handler --> Store
+    Handler --> AppSvc
+    Handler --> MaterialsDAO
+
+    AppSvc --> Store
+    AppSvc --> DbFactory
+    AppSvc --> InputSvc
+    AppSvc --> MaterialsDAO
+    AppSvc --> PlanDAO
+```
+
+## 4. 新增与调整的文件
+
+### 4.1 IPC 薄壳
+
+- `src/main/ipc/validation-handler.ts`
+
+职责收敛为：
+
+- 注册 IPC handler
+- 从 `SessionManager` 读取当前用户
+- 调用应用服务
+- 对简单 DAO 操作做最轻量转发
+
+### 4.2 共享状态模块
+
+- `src/main/services/validation/shared-production-ids-store.ts`
+
+职责：
+
+- 管理按 `senderId` 隔离的共享 `Production IDs`
+- 提供 `set/get/clear`
+
+价值：
+
+- 将原本散落在 handler 文件顶部的状态提升为独立服务
+- 后续如果要迁移到更持久的 session store，只需替换这一层
+
+### 4.3 数据库创建与表名适配
+
+- `src/main/services/validation/validation-database.ts`
+
+职责：
+
+- 创建用于 validation 相关流程的数据库服务
+- 提供 `getValidationTableName()` 做表名方言转换
+
+价值：
+
+- 收敛 MySQL / SQL Server 的连接逻辑
+- 避免 IPC 文件里反复出现数据库构造代码
+
+### 4.4 输入解析服务
+
+- `src/main/services/validation/production-input-service.ts`
+
+职责：
+
+- 读取 Production ID 文件
+- 识别输入是 `production_id`、`order_number` 还是 `unknown`
+- 从输入解析出订单号列表
+
+价值：
+
+- 把“输入解析规则”变成可复用、可测试的纯业务模块
+
+### 4.5 应用服务
+
+- `src/main/services/validation/validation-application-service.ts`
+
+职责：
+
+- 校验流程编排
+- Cleaner 数据准备
+- 物料按负责人查询 / 全量查询的富化逻辑
+- 统一管理数据库生命周期
+
+价值：
+
+- 形成明确的 application service 层
+- 让后续业务扩展不再从 IPC 文件开刀
+
+## 5. 重构前后职责对比
+
+```mermaid
+flowchart LR
+    subgraph Before[重构前]
+        A1[validation-handler.ts]
+        A1 --> A2[IPC 注册]
+        A1 --> A3[共享状态]
+        A1 --> A4[数据库连接]
+        A1 --> A5[输入解析]
+        A1 --> A6[校验编排]
+        A1 --> A7[物料富化]
+        A1 --> A8[Cleaner 数据准备]
+    end
+
+    subgraph After[重构后]
+        B1[validation-handler.ts]
+        B2[shared-production-ids-store.ts]
+        B3[validation-database.ts]
+        B4[production-input-service.ts]
+        B5[validation-application-service.ts]
+
+        B1 --> B5
+        B1 --> B2
+        B5 --> B3
+        B5 --> B4
+    end
+```
+
+## 6. 本次保留不变的部分
+
+为了控制风险，这次没有修改以下内容：
+
+- IPC channel 名称
+- Preload / Renderer 调用方式
+- 物料匹配规则
+- Cleaner 数据准备规则
+- DAO 层的既有 SQL 结构
+
+也就是说，这次更像是一次“结构性搬迁”，不是业务规则改造。
+
+## 7. 验证方式
+
+本次重构完成后，做了以下验证：
+
+- `npm run typecheck:node`
+- `tests/unit/shared-production-ids-store.test.ts`
+- `tests/unit/production-input-service.test.ts`
+- 既有 `tests/unit/ipc-index.test.ts`
+
+## 8. 新增测试
+
+新增测试文件：
+
+- `tests/unit/shared-production-ids-store.test.ts`
+- `tests/unit/production-input-service.test.ts`
+
+覆盖内容：
+
+- sender 隔离存储
+- 去重行为
+- 清空逻辑
+- 输入类型识别
+
+## 9. 收益总结
+
+这次重构带来的直接收益：
+
+- `validation-handler.ts` 不再承担过多业务职责
+- validation 相关逻辑形成了可复用服务层
+- 输入解析与共享状态有了独立测试入口
+- 后续继续拆 `cleaner-handler` 时，可以直接复用订单号解析和 cleaner 数据准备逻辑
+
+## 10. 后续建议
+
+建议在这个基础上继续推进：
+
+1. 将 `validation-application-service.ts` 中的 SQL Server / MySQL 分支继续下沉到 repository 或 dialect adapter。
+2. 逐步给 `getCleanerData()`、`getMaterialsByManager()` 这类编排逻辑补更多单测。
+3. 把和 validation 强耦合的 renderer 逻辑改成显式依赖 application contract，而不是隐式依赖 payload shape。

electron-builder.yml

@@ -2,6 +2,9 @@ appId: com.electron.app
 productName: erpauto
 directories:
   buildResources: build
+extraResources:
+  - from: build/bin/portable-updater.exe
+    to: portable-updater.exe
 files:
   - '!**/.vscode/*'
   - '!src/*'
@@ -35,26 +38,4 @@ nsis:
   shortcutName: ${productName}
   uninstallDisplayName: ${productName}
   createDesktopShortcut: always
-mac:
-  entitlementsInherit: build/entitlements.mac.plist
-  extendInfo:
-    - NSCameraUsageDescription: Application requests access to the device's camera.
-    - NSMicrophoneUsageDescription: Application requests access to the device's microphone.
-    - NSDocumentsFolderUsageDescription: Application requests access to the user's Documents folder.
-    - NSDownloadsFolderUsageDescription: Application requests access to the user's Downloads folder.
-  notarize: false
-dmg:
-  artifactName: ${name}-${version}.${ext}
-linux:
-  target:
-    - AppImage
-    - snap
-    - deb
-  maintainer: electronjs.org
-  category: Utility
-appImage:
-  artifactName: ${name}-${version}.${ext}
 npmRebuild: false
-publish:
-  provider: generic
-  url: https://example.com/auto-updates

electron.vite.config.ts

@@ -18,14 +18,24 @@ const getGitHash = (): string => {
 const require = createRequire(import.meta.url)
 const version = require('./package.json').version
 const gitHash = getGitHash()
+const appChannel = process.env.APP_CHANNEL === 'preview' ? 'preview' : 'stable'
 
 export default defineConfig({
-  main: {},
+  main: {
-  preload: {},
+    define: {
+      __APP_CHANNEL__: JSON.stringify(appChannel)
+    }
+  },
+  preload: {
+    define: {
+      __APP_CHANNEL__: JSON.stringify(appChannel)
+    }
+  },
   renderer: {
     define: {
       __APP_VERSION__: JSON.stringify(version),
-      __GIT_HASH__: JSON.stringify(gitHash)
+      __GIT_HASH__: JSON.stringify(gitHash),
+      __APP_CHANNEL__: JSON.stringify(appChannel)
     },
     resolve: {
       alias: {

eslint.config.mjs

@@ -6,7 +6,18 @@ import eslintPluginReactHooks from 'eslint-plugin-react-hooks'
 import eslintPluginReactRefresh from 'eslint-plugin-react-refresh'
 
 export default defineConfig(
-  { ignores: ['**/node_modules', '**/dist', '**/out'] },
+  {
+    ignores: [
+      '**/node_modules',
+      '**/dist',
+      '**/out',
+      '.agents/**',
+      '.claude/**',
+      'scripts/**',
+      'src/main/tools/**',
+      'tests/manual/**'
+    ]
+  },
   tseslint.configs.recommended,
   eslintPluginReact.configs.flat.recommended,
   eslintPluginReact.configs.flat['jsx-runtime'],
@@ -18,15 +29,24 @@ export default defineConfig(
     }
   },
   {
-    files: ['**/*.{ts,tsx}'],
+    files: ['**/*.{js,ts,tsx}'],
     plugins: {
       'react-hooks': eslintPluginReactHooks,
       'react-refresh': eslintPluginReactRefresh
     },
     rules: {
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
       ...eslintPluginReactHooks.configs.recommended.rules,
+      'react-hooks/set-state-in-effect': 'off',
       ...eslintPluginReactRefresh.configs.vite.rules
     }
   },
+  {
+    files: ['tests/**/*.{ts,tsx}'],
+    rules: {
+      '@typescript-eslint/no-unused-vars': 'off'
+    }
+  },
   eslintConfigPrettier
 )

package.json

@@ -1,6 +1,6 @@
 {
   "name": "erpauto",
-  "version": "1.3.1",
+  "version": "1.8.0",
   "description": "An Electron application with React and TypeScript",
   "main": "./out/main/index.js",
   "author": "example.com",
@@ -15,10 +15,12 @@
     "dev": "chcp 65001 && electron-vite dev",
     "build": "chcp 65001 && npm run typecheck && electron-vite build",
     "postinstall": "electron-builder install-app-deps",
-    "build:unpack": "chcp 65001 && set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 && npm run build && electron-builder --dir",
+    "build:updater": "node scripts/compile-updater.js",
-    "build:win": "chcp 65001 && set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 && npm run prebuild && npm run build && electron-builder --win",
+    "build:unpack": "chcp 65001 && set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 && npm run build:updater && npm run build && electron-builder --dir",
-    "build:mac": "chcp 65001 && npm run prebuild && electron-vite build && electron-builder --mac",
+    "build:win": "chcp 65001 && set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 && npm run prebuild && npm run build && npm run build:updater && electron-builder --win",
-    "build:linux": "chcp 65001 && npm run prebuild && electron-vite build && electron-builder --linux",
+    "release:prepare": "node scripts/prepare-release.js",
+    "release:publish": "node scripts/publish-release.js",
+    "release:upload": "node scripts/upload-release.js",
     "prebuild": "node -e \"const fs=require('fs');['dist','out'].forEach(d=>{try{fs.rmSync(d,{recursive:true})}catch(e){}})\"",
     "test": "vitest",
     "test:run": "vitest run",
@@ -34,11 +36,13 @@
     "@aws-sdk/client-s3": "^3.929.0",
     "@electron-toolkit/preload": "^3.0.2",
     "@electron-toolkit/utils": "^4.0.0",
+    "@headlessui/react": "^2.2.9",
     "@tailwindcss/vite": "^4.2.1",
     "@types/js-yaml": "^4.0.9",
     "chromium-bidi": "^15.0.0",
     "date-fns": "^4.1.0",
     "exceljs": "^4.4.0",
+    "github-markdown-css": "^5.9.0",
     "js-yaml": "^4.1.1",
     "lucide-react": "^0.575.0",
     "mssql": "^12.2.0",
@@ -47,7 +51,11 @@
     "playwright-core": "^1.58.2",
     "react-focus-lock": "^2.13.7",
     "react-markdown": "^10.1.0",
+    "recharts": "^3.8.0",
     "reflect-metadata": "^0.2.2",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-highlight": "^7.0.2",
+    "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "typeorm": "^0.3.28",
     "uuid": "^13.0.0",

scripts/compile-updater.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+const rootDir = process.cwd()
+const sourcePath = path.join(rootDir, 'build', 'PortableUpdater.cs')
+const outputDir = path.join(rootDir, 'build', 'bin')
+const outputPath = path.join(outputDir, 'portable-updater.exe')
+
+function findCompiler() {
+  const candidates = [
+    'C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\csc.exe',
+    'C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\csc.exe'
+  ]
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null
+}
+
+function main() {
+  if (process.platform !== 'win32') {
+    console.log('Skipping updater compilation on non-Windows platform.')
+    return
+  }
+
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`Updater source not found: ${sourcePath}`)
+  }
+
+  const compiler = findCompiler()
+  if (!compiler) {
+    throw new Error('Unable to find csc.exe for compiling portable-updater.exe')
+  }
+
+  fs.mkdirSync(outputDir, { recursive: true })
+
+  const compileArgs = ['/nologo', '/target:exe', '/optimize+', `/out:${outputPath}`, sourcePath]
+
+  const result = spawnSync(compiler, compileArgs, {
+    cwd: rootDir,
+    stdio: 'inherit'
+  })
+
+  if (result.status !== 0) {
+    throw new Error(`csc.exe failed with exit code ${result.status}`)
+  }
+
+  console.log(`Portable updater compiled successfully: ${outputPath}`)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`compile-updater failed: ${error.message}`)
+  process.exit(1)
+}

scripts/prepare-release.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+
+function printUsage() {
+  console.log(`
+Usage:
+  node scripts/prepare-release.js --channel <stable|preview> --changelog <file> [options]
+
+Options:
+  --channel <stable|preview>      Release channel. Required.
+  --changelog <file>              Markdown changelog file. Required.
+  --artifact <file>               Portable exe path. Default: dist/erpauto-portable.exe
+  --version <x.y.z>               Release version. Default: package.json version
+  --summary <text>                Optional short summary for notesSummary
+  --published-at <ISO date>       Optional publish time. Default: current time
+  --base-prefix <prefix>          Default: updates/win-portable
+  --output <dir>                  Default: release-output
+  --existing-index <file>         Existing index.json to merge with
+`)
+}
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith('--')) continue
+    const key = token.slice(2)
+    const value = argv[i + 1]
+    if (!value || value.startsWith('--')) {
+      args[key] = true
+      continue
+    }
+    args[key] = value
+    i += 1
+  }
+  return args
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true })
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256')
+    const stream = fs.createReadStream(filePath)
+    stream.on('data', (chunk) => hash.update(chunk))
+    stream.on('error', reject)
+    stream.on('end', () => resolve(hash.digest('hex')))
+  })
+}
+
+function loadExistingIndex(existingIndexPath, outputIndexPath) {
+  const candidate = existingIndexPath || (fs.existsSync(outputIndexPath) ? outputIndexPath : null)
+  if (!candidate) {
+    return { releases: [] }
+  }
+
+  const parsed = readJson(candidate)
+  if (!parsed || !Array.isArray(parsed.releases)) {
+    throw new Error(`Invalid index file: ${candidate}`)
+  }
+
+  return parsed
+}
+
+function sortReleases(releases) {
+  return [...releases].sort((left, right) => {
+    const leftParts = String(left.version)
+      .split('.')
+      .map((part) => Number.parseInt(part, 10) || 0)
+    const rightParts = String(right.version)
+      .split('.')
+      .map((part) => Number.parseInt(part, 10) || 0)
+
+    const length = Math.max(leftParts.length, rightParts.length)
+    for (let i = 0; i < length; i += 1) {
+      const l = leftParts[i] || 0
+      const r = rightParts[i] || 0
+      if (r !== l) {
+        return r - l
+      }
+    }
+
+    const leftTime = new Date(left.publishedAt).getTime()
+    const rightTime = new Date(right.publishedAt).getTime()
+    if (rightTime !== leftTime) {
+      return rightTime - leftTime
+    }
+
+    return 0
+  })
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.help || args.h) {
+    printUsage()
+    process.exit(0)
+  }
+
+  const packageJson = readJson(path.resolve(process.cwd(), 'package.json'))
+  const version = args.version || packageJson.version
+  const channel = args.channel
+  const changelogPath = args.changelog
+  const artifactPath = path.resolve(process.cwd(), args.artifact || 'dist/erpauto-portable.exe')
+  const basePrefix = args['base-prefix'] || 'updates/win-portable'
+  const outputRoot = path.resolve(process.cwd(), args.output || 'release-output')
+  const publishedAt = args['published-at'] || new Date().toISOString()
+  const summary = args.summary
+
+  assert(channel === 'stable' || channel === 'preview', 'Missing or invalid --channel')
+  assert(changelogPath, 'Missing --changelog')
+  assert(fs.existsSync(artifactPath), `Artifact not found: ${artifactPath}`)
+
+  const resolvedChangelogPath = path.resolve(process.cwd(), changelogPath)
+  assert(fs.existsSync(resolvedChangelogPath), `Changelog not found: ${resolvedChangelogPath}`)
+
+  const artifactStat = fs.statSync(artifactPath)
+  const sha256 = await sha256File(artifactPath)
+  const fileName = `erpauto-${version}-${channel}-portable.exe`
+  const changelogFileName = `${version}.md`
+
+  const channelDir = path.join(outputRoot, basePrefix, channel)
+  const artifactsDir = path.join(channelDir, 'artifacts')
+  const changelogDir = path.join(channelDir, 'changelogs')
+  const outputIndexPath = path.join(channelDir, 'index.json')
+
+  ensureDir(artifactsDir)
+  ensureDir(changelogDir)
+
+  const targetArtifactPath = path.join(artifactsDir, fileName)
+  const targetChangelogPath = path.join(changelogDir, changelogFileName)
+
+  fs.copyFileSync(artifactPath, targetArtifactPath)
+  fs.copyFileSync(resolvedChangelogPath, targetChangelogPath)
+
+  const releaseEntry = {
+    version,
+    channel,
+    artifactKey: `${basePrefix}/${channel}/artifacts/${fileName}`,
+    sha256,
+    size: artifactStat.size,
+    publishedAt,
+    changelogKey: `${basePrefix}/${channel}/changelogs/${changelogFileName}`,
+    ...(summary ? { notesSummary: summary } : {})
+  }
+
+  const existingIndex = loadExistingIndex(
+    args['existing-index'] ? path.resolve(process.cwd(), args['existing-index']) : null,
+    outputIndexPath
+  )
+
+  const mergedReleases = sortReleases([
+    releaseEntry,
+    ...existingIndex.releases.filter(
+      (item) => !(item.version === version && item.channel === channel)
+    )
+  ])
+
+  fs.writeFileSync(
+    outputIndexPath,
+    `${JSON.stringify({ releases: mergedReleases }, null, 2)}\n`,
+    'utf-8'
+  )
+
+  console.log('Release package prepared successfully.')
+  console.log(`Channel:        ${channel}`)
+  console.log(`Version:        ${version}`)
+  console.log(`Artifact:       ${targetArtifactPath}`)
+  console.log(`Changelog:      ${targetChangelogPath}`)
+  console.log(`Index:          ${outputIndexPath}`)
+  console.log(`SHA256:         ${sha256}`)
+}
+
+main().catch((error) => {
+  console.error(`prepare-release failed: ${error.message}`)
+  process.exit(1)
+})

scripts/publish-release.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+const { spawnSync } = require('child_process')
+
+function usage() {
+  console.log(`
+Usage:
+  node scripts/publish-release.js --channel <stable|preview> [options]
+
+Options:
+  --channel <stable|preview>  Release channel. Required.
+  --changelog <file>          Optional changelog file. Default: auto-resolve from version
+  --config <file>             Config file path. Default: config.yaml
+  --help                      Show this help message
+`)
+}
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith('--')) continue
+    const key = token.slice(2)
+    const value = argv[i + 1]
+    if (!value || value.startsWith('--')) {
+      args[key] = true
+      continue
+    }
+    args[key] = value
+    i += 1
+  }
+  return args
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+}
+
+function readYaml(filePath) {
+  return yaml.load(fs.readFileSync(filePath, 'utf-8'))
+}
+
+function resolveChangelogPath(version, explicitPath) {
+  if (explicitPath) {
+    return path.resolve(process.cwd(), explicitPath)
+  }
+
+  const rebuildPath = path.resolve(process.cwd(), 'docs', 'releases', `${version}-rebuild.md`)
+  if (fs.existsSync(rebuildPath)) {
+    return rebuildPath
+  }
+
+  return path.resolve(process.cwd(), 'docs', 'releases', `${version}.md`)
+}
+
+function validateUpdateConfig(configPath) {
+  assert(fs.existsSync(configPath), `Config file not found: ${configPath}`)
+
+  const parsed = readYaml(configPath)
+  const update = parsed && parsed.update
+
+  assert(update, 'Missing update config in config file')
+  assert(update.enabled, 'update.enabled is false')
+  assert(update.endpoint, 'update.endpoint is required')
+  assert(update.accessKey, 'update.accessKey is required')
+  assert(update.secretKey, 'update.secretKey is required')
+  assert(update.bucket, 'update.bucket is required')
+  assert(update.basePrefix, 'update.basePrefix is required')
+
+  return update
+}
+
+function hasConflictMarker(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8')
+  return content.includes('<<<<<<<') || content.includes('=======') || content.includes('>>>>>>>')
+}
+
+function validateVersionFiles(version) {
+  const packageJsonPath = path.resolve(process.cwd(), 'package.json')
+  const packageLockPath = path.resolve(process.cwd(), 'package-lock.json')
+
+  assert(fs.existsSync(packageLockPath), `package-lock.json not found: ${packageLockPath}`)
+  assert(!hasConflictMarker(packageJsonPath), 'package.json contains merge conflict markers')
+  assert(!hasConflictMarker(packageLockPath), 'package-lock.json contains merge conflict markers')
+
+  const packageLock = readJson(packageLockPath)
+  assert(packageLock.version === version, 'package-lock.json version does not match package.json')
+
+  const rootPackage = packageLock.packages && packageLock.packages['']
+  if (rootPackage && rootPackage.version) {
+    assert(
+      rootPackage.version === version,
+      'package-lock root package version does not match package.json'
+    )
+  }
+}
+
+function runStep(name, command, args, envOverrides = {}) {
+  console.log('')
+  console.log(`==> ${name}`)
+  console.log(`$ ${command} ${args.join(' ')}`)
+
+  let result
+  if (process.platform === 'win32') {
+    const shellCommand = [command, ...args]
+      .map((arg) => (/\s|"/.test(arg) ? `"${String(arg).replace(/"/g, '\\"')}"` : arg))
+      .join(' ')
+
+    result = spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', shellCommand], {
+      cwd: process.cwd(),
+      env: { ...process.env, ...envOverrides },
+      stdio: 'inherit'
+    })
+  } else {
+    result = spawnSync(command, args, {
+      cwd: process.cwd(),
+      env: { ...process.env, ...envOverrides },
+      stdio: 'inherit'
+    })
+  }
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`${name} failed with exit code ${result.status}`)
+  }
+}
+
+function readPreparedIndex(channel, basePrefix) {
+  const indexPath = path.resolve(
+    process.cwd(),
+    'release-output',
+    ...basePrefix.split('/'),
+    channel,
+    'index.json'
+  )
+
+  assert(fs.existsSync(indexPath), `Prepared index not found: ${indexPath}`)
+  const parsed = readJson(indexPath)
+  assert(parsed && Array.isArray(parsed.releases), `Invalid prepared index: ${indexPath}`)
+  return { indexPath, parsed }
+}
+
+function summarizeRelease(version, channel, releaseEntry, indexPath) {
+  console.log('')
+  console.log('Release published successfully.')
+  console.log(`Version:        ${version}`)
+  console.log(`Channel:        ${channel}`)
+  console.log(`Artifact:       ${releaseEntry.artifactKey}`)
+  console.log(`SHA256:         ${releaseEntry.sha256}`)
+  console.log(`Changelog:      ${releaseEntry.changelogKey}`)
+  console.log(`Prepared Index: ${indexPath}`)
+  console.log(`Published At:   ${releaseEntry.publishedAt}`)
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.help || args.h) {
+    usage()
+    process.exit(0)
+  }
+
+  const channel = args.channel
+  assert(channel === 'stable' || channel === 'preview', 'Missing or invalid --channel')
+
+  const packageJsonPath = path.resolve(process.cwd(), 'package.json')
+  assert(fs.existsSync(packageJsonPath), `package.json not found: ${packageJsonPath}`)
+  const packageJson = readJson(packageJsonPath)
+  const version = packageJson.version
+  assert(version, 'package.json version is required')
+
+  const configPath = path.resolve(process.cwd(), args.config || 'config.yaml')
+  const updateConfig = validateUpdateConfig(configPath)
+  validateVersionFiles(version)
+
+  const changelogPath = resolveChangelogPath(version, args.changelog)
+  assert(fs.existsSync(changelogPath), `Changelog not found: ${changelogPath}`)
+
+  runStep('Build Windows package', 'npm', ['run', 'build:win'], {
+    APP_CHANNEL: channel
+  })
+
+  runStep('Prepare release package', 'npm', [
+    'run',
+    'release:prepare',
+    '--',
+    '--channel',
+    channel,
+    '--changelog',
+    changelogPath
+  ])
+
+  const { indexPath, parsed } = readPreparedIndex(channel, updateConfig.basePrefix)
+  const latestRelease = parsed.releases[0]
+  assert(latestRelease, 'Prepared index does not contain any release entry')
+  assert(
+    latestRelease.version === version && latestRelease.channel === channel,
+    `Prepared index latest entry mismatch: expected ${version}/${channel}, got ${latestRelease.version}/${latestRelease.channel}`
+  )
+
+  runStep('Upload release package', 'npm', [
+    'run',
+    'release:upload',
+    '--',
+    '--channel',
+    channel,
+    '--verify'
+  ])
+
+  summarizeRelease(version, channel, latestRelease, indexPath)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`publish-release failed: ${error.message}`)
+  process.exit(1)
+}

scripts/upload-release.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+const { GetObjectCommand, PutObjectCommand, S3Client } = require('@aws-sdk/client-s3')
+
+function usage() {
+  console.log(`
+Usage:
+  node scripts/upload-release.js --channel <stable|preview> [options]
+
+Options:
+  --channel <stable|preview>  Release channel. Required.
+  --source <dir>              Local release root. Default: release-output
+  --config <file>             Config file path. Default: config.yaml
+  --version <x.y.z>           Release version. Default: package.json version
+  --full-sync                 Upload the whole channel directory instead of current release only
+  --verify                    Read back remote index.json after upload
+`)
+}
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith('--')) continue
+    const key = token.slice(2)
+    const value = argv[i + 1]
+    if (!value || value.startsWith('--')) {
+      args[key] = true
+      continue
+    }
+    args[key] = value
+    i += 1
+  }
+  return args
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+}
+
+function loadConfig(configPath) {
+  const raw = fs.readFileSync(configPath, 'utf-8')
+  const parsed = yaml.load(raw)
+  const update = parsed && parsed.update
+
+  assert(update, 'Missing update config in config.yaml')
+  assert(update.enabled, 'update.enabled is false')
+  assert(update.endpoint, 'update.endpoint is required')
+  assert(update.accessKey, 'update.accessKey is required')
+  assert(update.secretKey, 'update.secretKey is required')
+  assert(update.bucket, 'update.bucket is required')
+
+  return update
+}
+
+function getContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  if (ext === '.json') return 'application/json; charset=utf-8'
+  if (ext === '.md') return 'text/markdown; charset=utf-8'
+  if (ext === '.exe') return 'application/vnd.microsoft.portable-executable'
+  return 'application/octet-stream'
+}
+
+async function readRemoteText(client, bucket, key) {
+  const response = await client.send(
+    new GetObjectCommand({
+      Bucket: bucket,
+      Key: key
+    })
+  )
+
+  const chunks = []
+  for await (const chunk of response.Body) {
+    chunks.push(Buffer.from(chunk))
+  }
+  return Buffer.concat(chunks).toString('utf-8')
+}
+
+function buildFileDescriptor(sourceRoot, absolutePath) {
+  return {
+    absolutePath,
+    relativeKey: path.relative(sourceRoot, absolutePath).replace(/\\/g, '/')
+  }
+}
+
+function collectUploadFiles(sourceRoot, channelRoot, channel, version, fullSync, basePrefix) {
+  const indexPath = path.join(channelRoot, 'index.json')
+  assert(fs.existsSync(indexPath), `Index not found: ${indexPath}`)
+
+  if (fullSync) {
+    const results = []
+    const entries = fs.readdirSync(channelRoot, { withFileTypes: true })
+
+    function walk(dirPath) {
+      const dirEntries = fs.readdirSync(dirPath, { withFileTypes: true })
+      for (const entry of dirEntries) {
+        const fullPath = path.join(dirPath, entry.name)
+        if (entry.isDirectory()) {
+          walk(fullPath)
+        } else {
+          results.push(buildFileDescriptor(sourceRoot, fullPath))
+        }
+      }
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(channelRoot, entry.name)
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      } else {
+        results.push(buildFileDescriptor(sourceRoot, fullPath))
+      }
+    }
+
+    return { files: results, indexKey: `${basePrefix}/${channel}/index.json` }
+  }
+
+  const parsedIndex = readJson(indexPath)
+  assert(parsedIndex && Array.isArray(parsedIndex.releases), `Invalid index file: ${indexPath}`)
+
+  const releaseEntry = parsedIndex.releases.find(
+    (release) => release.version === version && release.channel === channel
+  )
+  assert(releaseEntry, `Release entry not found in index for ${channel}/${version}`)
+
+  const artifactPath = path.resolve(sourceRoot, releaseEntry.artifactKey)
+  const changelogPath = path.resolve(sourceRoot, releaseEntry.changelogKey)
+
+  assert(fs.existsSync(artifactPath), `Artifact not found: ${artifactPath}`)
+  assert(fs.existsSync(changelogPath), `Changelog not found: ${changelogPath}`)
+
+  return {
+    files: [
+      buildFileDescriptor(sourceRoot, artifactPath),
+      buildFileDescriptor(sourceRoot, changelogPath),
+      buildFileDescriptor(sourceRoot, indexPath)
+    ],
+    indexKey: `${basePrefix}/${channel}/index.json`
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help || args.h) {
+    usage()
+    process.exit(0)
+  }
+
+  const channel = args.channel
+  assert(channel === 'stable' || channel === 'preview', 'Missing or invalid --channel')
+
+  const sourceRoot = path.resolve(process.cwd(), args.source || 'release-output')
+  const configPath = path.resolve(process.cwd(), args.config || 'config.yaml')
+  const updateConfig = loadConfig(configPath)
+  const packageJson = readJson(path.resolve(process.cwd(), 'package.json'))
+  const version = args.version || packageJson.version
+  assert(version, 'Missing release version')
+
+  const channelRoot = path.join(sourceRoot, updateConfig.basePrefix, channel)
+  assert(fs.existsSync(channelRoot), `Upload root not found: ${channelRoot}`)
+
+  const client = new S3Client({
+    region: updateConfig.region || 'us-east-1',
+    endpoint: updateConfig.endpoint,
+    credentials: {
+      accessKeyId: updateConfig.accessKey,
+      secretAccessKey: updateConfig.secretKey
+    },
+    forcePathStyle: true
+  })
+
+  const { files, indexKey } = collectUploadFiles(
+    sourceRoot,
+    channelRoot,
+    channel,
+    version,
+    Boolean(args['full-sync']),
+    updateConfig.basePrefix
+  )
+  assert(files.length > 0, `No files found under ${channelRoot}`)
+
+  for (const file of files) {
+    const body = fs.readFileSync(file.absolutePath)
+
+    await client.send(
+      new PutObjectCommand({
+        Bucket: updateConfig.bucket,
+        Key: file.relativeKey,
+        Body: body,
+        ContentType: getContentType(file.absolutePath)
+      })
+    )
+
+    console.log(`Uploaded: ${file.relativeKey}`)
+  }
+
+  if (args.verify) {
+    const remoteIndex = await readRemoteText(client, updateConfig.bucket, indexKey)
+    console.log('')
+    console.log(`Verified remote index: ${indexKey}`)
+    console.log(remoteIndex)
+  }
+}
+
+main().catch((error) => {
+  console.error(`upload-release failed: ${error.message}`)
+  process.exit(1)
+})

skills-lock.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "skills": {
+    "electron-best-practices": {
+      "source": "jwynia/agent-skills",
+      "sourceType": "github",
+      "computedHash": "744549070132b3bc0602fd7121d42278ba74694b9d0943358093bde3543cbe97"
+    },
+    "vercel-react-best-practices": {
+      "source": "vercel-labs/agent-skills",
+      "sourceType": "github",
+      "computedHash": "e218e50fe7057a4db91390e579c7db5aafac2394c31a3d8e5fa9444c8fa00726"
+    }
+  }
+}

src/main/bootstrap/main-window.ts

@@ -0,0 +1,59 @@
+import { BrowserWindow, app, shell } from 'electron'
+import { join } from 'path'
+import icon from '../../../resources/icon.png?asset'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function isDevelopment(): boolean {
+  return Boolean(process.env['ELECTRON_RENDERER_URL']) || process.env.NODE_ENV === 'development'
+}
+
+export function createMainWindow(): BrowserWindow {
+  const mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 670,
+    show: false,
+    autoHideMenuBar: true,
+    ...(process.platform === 'linux' ? { icon } : {}),
+    webPreferences: {
+      preload: join(__dirname, '../preload/index.js'),
+      contextIsolation: true,
+      sandbox: true,
+      nodeIntegration: false
+    }
+  })
+
+  mainWindow.on('ready-to-show', () => {
+    mainWindow.show()
+  })
+
+  mainWindow.webContents.setWindowOpenHandler((details) => {
+    shell.openExternal(details.url)
+    return { action: 'deny' }
+  })
+
+  if (isDevelopment() && process.env['ELECTRON_RENDERER_URL']) {
+    mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])
+  } else {
+    mainWindow.loadFile(join(__dirname, '../renderer/index.html'))
+  }
+
+  return mainWindow
+}
+
+export function registerMainWindowLifecycle(): void {
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createMainWindow()
+    }
+  })
+
+  app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') {
+      app.quit()
+    }
+  })
+}

src/main/bootstrap/process-guards.ts

@@ -0,0 +1,40 @@
+import { app } from 'electron'
+import logger from '../services/logger/index'
+import { logAudit } from '../services/logger/audit-logger'
+
+export function setupProcessGuards(): void {
+  process.on('uncaughtException', async (err) => {
+    logger.error('Uncaught exception', { error: err })
+    await logAudit('SYSTEM_CRASH', 'system', {
+      username: 'system',
+      computerName: process.env.COMPUTERNAME || 'unknown',
+      resource: 'main-process',
+      status: 'failure',
+      metadata: { error: err.message, stack: err.stack }
+    })
+    console.error('Uncaught exception:', err)
+    setTimeout(() => process.exit(1), 1000)
+  })
+
+  process.on('unhandledRejection', async (reason) => {
+    logger.error('Unhandled Rejection', { reason: String(reason) })
+    await logAudit('SYSTEM_ERROR', 'system', {
+      username: 'system',
+      computerName: process.env.COMPUTERNAME || 'unknown',
+      resource: 'main-process',
+      status: 'failure',
+      metadata: { reason: String(reason) }
+    })
+    console.error('Unhandled Rejection:', reason)
+  })
+
+  app.on('render-process-gone', (_, webContents, details) => {
+    logger.error('Render process gone', { details, webContentsId: webContents.id })
+    console.error('Render process gone:', details)
+  })
+
+  app.on('child-process-gone', (_, details) => {
+    logger.error('Child process gone', { details })
+    console.error('Child process gone:', details)
+  })
+}

src/main/bootstrap/runtime.ts

@@ -0,0 +1,92 @@
+import { app } from 'electron'
+import fs from 'fs'
+import { join } from 'path'
+import { ConfigManager } from '../services/config/config-manager'
+import { UpdateService } from '../services/update/update-service'
+
+export function configurePlaywrightBrowsersPath(): string {
+  const browsersPath = join(app.getPath('userData'), 'ms-playwright')
+  process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath
+  return browsersPath
+}
+
+export function setupElectronRuntime(): void {
+  app.setAppUserModelId('com.electron')
+
+  app.on('browser-window-created', (_, window) => {
+    window.webContents.on('before-input-event', (event, input) => {
+      const isReloadShortcut = (input.control || input.meta) && input.key.toLowerCase() === 'r'
+      const isToggleDevTools = input.key === 'F12'
+
+      if (!app.isPackaged && isToggleDevTools && input.type === 'keyDown') {
+        window.webContents.toggleDevTools()
+        event.preventDefault()
+        return
+      }
+
+      if (app.isPackaged && isReloadShortcut) {
+        event.preventDefault()
+      }
+    })
+  })
+}
+
+/**
+ * Check if Playwright browsers are installed
+ * @returns true if browsers exist, false otherwise
+ */
+export function ensurePlaywrightRuntime(browsersPath: string): boolean {
+  try {
+    fs.mkdirSync(browsersPath, { recursive: true })
+  } catch (error) {
+    console.error('Failed to create browsers directory:', error)
+  }
+
+  const newChromiumPath = join(browsersPath, 'chromium-1208', 'chrome-win64', 'chrome.exe')
+  const oldChromiumPath = join(browsersPath, 'chromium-win32', 'chrome.exe')
+  const chromiumPath = fs.existsSync(newChromiumPath) ? newChromiumPath : oldChromiumPath
+
+  if (fs.existsSync(chromiumPath)) {
+    return true
+  }
+
+  let foundRevision = false
+  try {
+    const entries = fs.readdirSync(browsersPath)
+    for (const entry of entries) {
+      if (entry.startsWith('chromium-') && !entry.includes('headless')) {
+        const revisionPath = join(browsersPath, entry, 'chrome-win64', 'chrome.exe')
+        if (fs.existsSync(revisionPath)) {
+          console.log('Found Chromium revision:', entry)
+          foundRevision = true
+          break
+        }
+      }
+    }
+  } catch {
+    // Ignore browser directory probing failures and fall through to the warning dialog.
+  }
+
+  if (foundRevision) {
+    return true
+  }
+
+  console.warn(
+    'Playwright browser not found. Available:',
+    fs.existsSync(browsersPath) ? fs.readdirSync(browsersPath) : 'none'
+  )
+  return false
+}
+
+export async function initializeMainProcessServices(): Promise<void> {
+  try {
+    const configManager = ConfigManager.getInstance()
+    await configManager.initialize()
+    UpdateService.getInstance().initialize()
+  } catch (error) {
+    console.error('Failed to initialize ConfigManager:', error)
+  }
+
+  const { registerIpcHandlers } = await import('../ipc')
+  registerIpcHandlers()
+}

src/main/index.ts

@@ -1,189 +1,23 @@
-import { app, shell, BrowserWindow, ipcMain, dialog } from 'electron'
+import { app, ipcMain } from 'electron'
-import { join } from 'path'
+import { createMainWindow, registerMainWindowLifecycle } from './bootstrap/main-window'
-import { electronApp, optimizer, is } from '@electron-toolkit/utils'
+import {
-import icon from '../../resources/icon.png?asset'
+  configurePlaywrightBrowsersPath,
-import { registerIpcHandlers } from './ipc'
+  ensurePlaywrightRuntime,
-import { ConfigManager } from './services/config/config-manager'
+  initializeMainProcessServices,
-import logger from './services/logger/index'
+  setupElectronRuntime
-import { logAudit } from './services/logger/audit-logger'
+} from './bootstrap/runtime'
-import { fileURLToPath } from 'url'
+import { setupProcessGuards } from './bootstrap/process-guards'
-import { dirname } from 'path'
-import fs from 'fs'
 
-// Set Playwright browsers path BEFORE any playwright import
-process.env.PLAYWRIGHT_BROWSERS_PATH = join(app.getPath('userData'), 'ms-playwright')
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-function createWindow(): void {
-  // Create the browser window.
-  const mainWindow = new BrowserWindow({
-    width: 1200,
-    height: 670,
-    show: false,
-    autoHideMenuBar: true,
-    ...(process.platform === 'linux' ? { icon } : {}),
-    webPreferences: {
-      preload: join(__dirname, '../preload/index.js'),
-      sandbox: true
-    }
-  })
-
-  mainWindow.on('ready-to-show', () => {
-    mainWindow.show()
-  })
-
-  mainWindow.webContents.setWindowOpenHandler((details) => {
-    shell.openExternal(details.url)
-    return { action: 'deny' }
-  })
-
-  // HMR for renderer base on electron-vite cli.
-  // Load the remote URL for development or the local html file for production.
-  if (is.dev && process.env['ELECTRON_RENDERER_URL']) {
-    mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])
-  } else {
-    mainWindow.loadFile(join(__dirname, '../renderer/index.html'))
-  }
-}
-
-// This method will be called when Electron has finished
-// initialization and is ready to create browser windows.
-// Some APIs can only be used after this event occurs.
 app.whenReady().then(async () => {
-  // Validate Playwright browser path
+  setupProcessGuards()
-  const browsersPath = process.env.PLAYWRIGHT_BROWSERS_PATH!
+  registerMainWindowLifecycle()
+  const playwrightBrowsersPath = configurePlaywrightBrowsersPath()
+  const browsersExist = ensurePlaywrightRuntime(playwrightBrowsersPath)
+  console.log('Playwright browsers exist:', browsersExist)
+  await initializeMainProcessServices()
+  setupElectronRuntime()
 
-  // Create directory if it doesn't exist
-  try {
-    fs.mkdirSync(browsersPath, { recursive: true })
-  } catch (error) {
-    console.error('Failed to create browsers directory:', error)
-  }
-
-  // Check if chromium browser exists (supports both old and new Playwright directory structures)
-  // New format (v1.48+): chromium-1208/chrome-win64/chrome.exe
-  // Old format: chromium-win32/chrome.exe
-  const newChromiumPath = join(browsersPath, 'chromium-1208', 'chrome-win64', 'chrome.exe')
-  const oldChromiumPath = join(browsersPath, 'chromium-win32', 'chrome.exe')
-  const chromiumPath = fs.existsSync(newChromiumPath) ? newChromiumPath : oldChromiumPath
-
-  if (!fs.existsSync(chromiumPath)) {
-    // Try to find any chromium revision
-    let foundRevision = false
-    try {
-      const entries = fs.readdirSync(browsersPath)
-      for (const entry of entries) {
-        if (entry.startsWith('chromium-') && !entry.includes('headless')) {
-          const revisionPath = join(browsersPath, entry, 'chrome-win64', 'chrome.exe')
-          if (fs.existsSync(revisionPath)) {
-            console.log('Found Chromium revision:', entry)
-            foundRevision = true
-            break
-          }
-        }
-      }
-    } catch (e) {
-      // Ignore
-    }
-
-    if (!foundRevision) {
-      dialog.showErrorBox(
-        '浏览器文件未找到',
-        `Playwright 浏览器文件不存在。\n\n` +
-          `期望路径：${newChromiumPath}\n` +
-          `或：${oldChromiumPath}\n\n` +
-          `当前目录内容：${fs.existsSync(browsersPath) ? fs.readdirSync(browsersPath).join(', ') : '目录不存在'}\n\n` +
-          `请运行以下命令安装浏览器：\n` +
-          `npx playwright install chromium`
-      )
-      console.warn(
-        'Playwright browser not found. Available:',
-        fs.existsSync(browsersPath) ? fs.readdirSync(browsersPath) : 'none'
-      )
-    }
-  }
-
-  // Initialize ConfigManager BEFORE registering IPC handlers
-  // This ensures config is loaded before any service tries to use it
-  try {
-    const configManager = ConfigManager.getInstance()
-    await configManager.initialize()
-  } catch (error) {
-    console.error('Failed to initialize ConfigManager:', error)
-    // Continue anyway - default config will be created
-  }
-
-  // Set app user model id for windows
-  electronApp.setAppUserModelId('com.electron')
-
-  // Default open or close DevTools by F12 in development
-  // and ignore CommandOrControl + R in production.
-  // see https://github.com/alex8088/electron-toolkit/tree/master/packages/utils
-  app.on('browser-window-created', (_, window) => {
-    optimizer.watchWindowShortcuts(window)
-  })
-
-  // Register IPC handlers (after ConfigManager is initialized)
-  registerIpcHandlers()
-
-  // IPC test
   ipcMain.on('ping', () => console.log('pong'))
 
-  createWindow()
+  createMainWindow()
-
-  app.on('activate', function () {
-    // On macOS it's common to re-create a window in the app when the
-    // dock icon is clicked and there are no other windows open.
-    if (BrowserWindow.getAllWindows().length === 0) createWindow()
-  })
 })
-
-// Quit when all windows are closed, except on macOS. There, it's common
-// for applications and their menu bar to stay active until the user quits
-// explicitly with Cmd + Q.
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-// Global exception handlers to prevent crashes without logging
-process.on('uncaughtException', async (err) => {
-  logger.error('Uncaught exception', { error: err })
-  await logAudit('SYSTEM_CRASH', 'system', {
-    username: 'system',
-    computerName: process.env.COMPUTERNAME || 'unknown',
-    resource: 'main-process',
-    status: 'failure',
-    metadata: { error: err.message, stack: err.stack }
-  })
-  console.error('Uncaught exception:', err)
-  setTimeout(() => process.exit(1), 1000)
-})
-
-process.on('unhandledRejection', async (reason, promise) => {
-  logger.error('Unhandled Rejection', { reason: String(reason) })
-  await logAudit('SYSTEM_ERROR', 'system', {
-    username: 'system',
-    computerName: process.env.COMPUTERNAME || 'unknown',
-    resource: 'main-process',
-    status: 'failure',
-    metadata: { reason: String(reason) }
-  })
-  console.error('Unhandled Rejection:', reason)
-})
-
-app.on('render-process-gone', (_, webContents, details) => {
-  logger.error('Render process gone', { details, webContentsId: webContents.id })
-  console.error('Render process gone:', details)
-})
-
-app.on('child-process-gone', (_, details) => {
-  logger.error('Child process gone', { details })
-  console.error('Child process gone:', details)
-})
-
-// In this file you can include the rest of your app's specific main process
-// code. You can also put them in separate files and require them here.

src/main/ipc/auth-handler.ts

@@ -11,252 +11,68 @@
  */
 
 import { ipcMain } from 'electron'
-import { SessionManager } from '../services/user/session-manager'
-import { createLogger } from '../services/logger'
-import { logAudit } from '../services/logger/audit-logger'
 import type { UserInfo } from '../types/user.types'
+import type {
+  CurrentUserResponse,
+  LoginRequest,
+  LoginResponse,
+  SilentLoginResponse,
+  UserSelectionResponse
+} from '../types/auth-ipc.types'
 import { IPC_CHANNELS } from '../../shared/ipc-channels'
-import { ValidationError } from '../types/errors'
 import { withErrorHandling, type IpcResult } from './index'
-
+import { AuthApplicationService } from '../services/auth/auth-application-service'
-const log = createLogger('AuthHandler')
-
-/**
- * Login request
- */
-export interface LoginRequest {
-  username: string
-  password: string
-}
-
-/**
- * Login response
- */
-export interface LoginResponse {
-  success: boolean
-  userInfo?: UserInfo
-  error?: string
-}
-
-/**
- * Silent login response
- */
-export interface SilentLoginResponse {
-  success: boolean
-  userInfo?: UserInfo
-  requiresUserSelection?: boolean // True if admin needs to select a user
-  error?: string
-}
-
-/**
- * User selection response
- */
-export interface UserSelectionResponse {
-  success: boolean
-  userInfo?: UserInfo
-  error?: string
-}
-
-/**
- * Current user response
- */
-export interface CurrentUserResponse {
-  isAuthenticated: boolean
-  userInfo?: UserInfo
-}
 
 /**
  * Register IPC handlers for user authentication
  */
 export function registerAuthHandlers(): void {
-  const sessionManager = SessionManager.getInstance()
+  const authService = new AuthApplicationService()
 
-  /**
-   * Get computer name
-   */
   ipcMain.handle(IPC_CHANNELS.AUTH_GET_COMPUTER_NAME, async (): Promise<IpcResult<string>> => {
-    return withErrorHandling(async () => {
+    return withErrorHandling(async () => authService.getComputerName(), 'auth:getComputerName')
-      const os = await import('os')
-      return os.hostname()
-    }, 'auth:getComputerName')
   })
 
-  /**
-   * Silent login by computer name
-   */
   ipcMain.handle(
     IPC_CHANNELS.AUTH_SILENT_LOGIN,
     async (): Promise<IpcResult<SilentLoginResponse>> => {
-      return withErrorHandling(async () => {
+      return withErrorHandling(async () => authService.silentLogin(), 'auth:silentLogin')
-        log.info('Attempting silent login')
-        const success = await sessionManager.loginByComputerName()
-        const userInfo = sessionManager.getUserInfo()
-
-        if (success && userInfo) {
-          // Check if admin needs user selection
-          const requiresUserSelection = userInfo.userType === 'Admin'
-
-          log.info('Silent login successful', {
-            username: userInfo.username,
-            userType: userInfo.userType,
-            requiresUserSelection
-          })
-
-          // Audit log: LOGIN success (non-blocking)
-          const os = await import('os')
-          logAudit('LOGIN', String(userInfo.id), {
-            username: userInfo.username,
-            computerName: os.hostname(),
-            resource: 'ERP_SYSTEM',
-            status: 'success',
-            metadata: { loginType: 'silent', userType: userInfo.userType }
-          }).catch((err) => log.warn('Failed to write audit log', { err }))
-
-          return {
-            success: true,
-            userInfo,
-            requiresUserSelection
-          }
-        }
-
-        throw new ValidationError('无感登录失败：未找到匹配用户', 'VAL_INVALID_INPUT')
-      }, 'auth:silentLogin')
     }
   )
 
-  /**
-   * Login with username and password
-   */
   ipcMain.handle(
     IPC_CHANNELS.AUTH_LOGIN,
     async (_event, request: LoginRequest): Promise<IpcResult<LoginResponse>> => {
-      return withErrorHandling(async () => {
+      return withErrorHandling(
-        const { username, password } = request
+        async () => authService.login(request.username, request.password),
-
+        'auth:login'
-        if (!username || !password) {
+      )
-          log.warn('Login attempt with missing credentials')
-          throw new ValidationError('请输入用户名和密码', 'VAL_MISSING_REQUIRED')
-        }
-
-        log.info('Login attempt', { username })
-        const success = await sessionManager.login(username, password)
-        const userInfo = sessionManager.getUserInfo()
-
-        if (success && userInfo) {
-          log.info('Login successful', { username, userType: userInfo.userType })
-
-          // Audit log: LOGIN success (non-blocking)
-          const os = await import('os')
-          logAudit('LOGIN', String(userInfo.id), {
-            username: userInfo.username,
-            computerName: os.hostname(),
-            resource: 'ERP_SYSTEM',
-            status: 'success',
-            metadata: { loginType: 'credentials', userType: userInfo.userType }
-          }).catch((err) => log.warn('Failed to write audit log', { err }))
-
-          return {
-            success: true,
-            userInfo
-          }
-        }
-
-        // Audit log: LOGIN failure (non-blocking)
-        const os = await import('os')
-        logAudit('LOGIN', '0', {
-          username,
-          computerName: os.hostname(),
-          resource: 'ERP_SYSTEM',
-          status: 'failure',
-          metadata: { loginType: 'credentials', reason: 'invalid_credentials' }
-        }).catch((err) => log.warn('Failed to write audit log', { err }))
-
-        log.warn('Login failed - invalid credentials', { username })
-        throw new ValidationError('用户名或密码错误', 'VAL_INVALID_INPUT')
-      }, 'auth:login')
     }
   )
 
-  /**
-   * Logout
-   */
   ipcMain.handle(IPC_CHANNELS.AUTH_LOGOUT, async (): Promise<IpcResult<void>> => {
-    return withErrorHandling(async () => {
+    return withErrorHandling(async () => authService.logout(), 'auth:logout')
-      const userInfo = sessionManager.getUserInfo()
-      log.info('User logout', { username: userInfo?.username })
-
-      // Audit log: LOGOUT (non-blocking)
-      if (userInfo) {
-        const os = await import('os')
-        logAudit('LOGOUT', String(userInfo.id), {
-          username: userInfo.username,
-          computerName: os.hostname(),
-          resource: 'ERP_SYSTEM',
-          status: 'success',
-          metadata: { userType: userInfo.userType }
-        }).catch((err) => log.warn('Failed to write audit log', { err }))
-      }
-
-      sessionManager.logout()
-    }, 'auth:logout')
   })
 
-  /**
-   * Get current user
-   */
   ipcMain.handle(
     IPC_CHANNELS.AUTH_GET_CURRENT_USER,
     async (): Promise<IpcResult<CurrentUserResponse>> => {
-      return withErrorHandling(async () => {
+      return withErrorHandling(async () => authService.getCurrentUser(), 'auth:getCurrentUser')
-        const isAuthenticated = sessionManager.isAuthenticated()
-        const userInfo = sessionManager.getUserInfo()
-        return {
-          isAuthenticated,
-          userInfo: userInfo ?? undefined
-        }
-      }, 'auth:getCurrentUser')
     }
   )
 
-  /**
-   * Get all users (for admin user selection)
-   */
   ipcMain.handle(IPC_CHANNELS.AUTH_GET_ALL_USERS, async (): Promise<IpcResult<UserInfo[]>> => {
-    return withErrorHandling(async () => {
+    return withErrorHandling(async () => authService.getAllUsers(), 'auth:getAllUsers')
-      log.debug('Fetching all users for admin selection')
-      return await sessionManager.getAllUsers()
-    }, 'auth:getAllUsers')
   })
 
-  /**
-   * Switch user (admin only)
-   */
   ipcMain.handle(
     IPC_CHANNELS.AUTH_SWITCH_USER,
     async (_event, userInfo: UserInfo): Promise<IpcResult<UserSelectionResponse>> => {
-      return withErrorHandling(async () => {
+      return withErrorHandling(async () => authService.switchUser(userInfo), 'auth:switchUser')
-        log.info('User switch attempt', { targetUser: userInfo.username })
-        const success = sessionManager.switchUser(userInfo)
-
-        if (success) {
-          const newUser = sessionManager.getUserInfo()
-          log.info('User switch successful', { newUsername: newUser?.username })
-          return {
-            success: true,
-            userInfo: newUser ?? undefined
-          }
-        }
-
-        log.warn('User switch failed')
-        throw new ValidationError('用户切换失败', 'VAL_INVALID_INPUT')
-      }, 'auth:switchUser')
     }
   )
 
-  /**
-   * Check if current user is admin
-   */
   ipcMain.handle(IPC_CHANNELS.AUTH_IS_ADMIN, async (): Promise<IpcResult<boolean>> => {
-    return withErrorHandling(async () => sessionManager.isAdmin(), 'auth:isAdmin')
+    return withErrorHandling(async () => authService.isAdmin(), 'auth:isAdmin')
   })
 }

src/main/ipc/cleaner-handler.ts

@@ -1,368 +1,34 @@
-import { ipcMain, type WebContents } from 'electron'
+import { ipcMain } from 'electron'
-import { ErpAuthService } from '../services/erp/erp-auth'
-import { CleanerService } from '../services/erp/cleaner'
-import { OrderNumberResolver } from '../services/erp/order-resolver'
-import { MySqlService } from '../services/database/mysql'
-import { SqlServerService } from '../services/database/sql-server'
-import { ConfigManager } from '../services/config/config-manager'
-import { ResultExporter } from '../services/excel/result-exporter'
-import { CleanerReportGenerator } from '../services/report/cleaner-report-generator'
-import { RustfsService } from '../services/rustfs'
-import { SessionManager } from '../services/user/session-manager'
-import { createLogger } from '../services/logger'
-import { logAudit } from '../services/logger/audit-logger'
 import { withErrorHandling, type IpcResult } from './index'
-import { ErpConnectionError, ValidationError, DatabaseQueryError } from '../types/errors'
 import type {
   CleanerInput,
   CleanerResult,
-  CleanerProgress,
   ExportResultItem,
   ExportResultResponse
 } from '../types/cleaner.types'
-import { UserErpConfigService } from '../services/user/user-erp-config-service'
 import { IPC_CHANNELS } from '../../shared/ipc-channels'
-
+import { CleanerApplicationService } from '../services/cleaner/cleaner-application-service'
-const log = createLogger('CleanerHandler')
-
-function sendProgress(
-  sender: WebContents,
-  message: string,
-  progress: number,
-  extra?: Partial<CleanerProgress>
-): void {
-  try {
-    const progressData: CleanerProgress = {
-      message,
-      progress,
-      currentOrderIndex: extra?.currentOrderIndex ?? 0,
-      totalOrders: extra?.totalOrders ?? 0,
-      currentMaterialIndex: extra?.currentMaterialIndex ?? 0,
-      totalMaterialsInOrder: extra?.totalMaterialsInOrder ?? 0,
-      currentOrderNumber: extra?.currentOrderNumber,
-      phase: extra?.phase ?? 'processing'
-    }
-    sender.send(IPC_CHANNELS.CLEANER_PROGRESS, progressData)
-  } catch (error) {
-    log.warn('Failed to send progress event', { error })
-  }
-}
-
-async function getDatabaseService(): Promise<MySqlService | SqlServerService> {
-  const configManager = ConfigManager.getInstance()
-  const config = configManager.getConfig()
-  const dbType = configManager.getDatabaseType()
-
-  if (dbType === 'sqlserver') {
-    const dbConfig = config.database.sqlserver
-    const sqlServerService = new SqlServerService({
-      server: dbConfig.server,
-      port: dbConfig.port,
-      user: dbConfig.username,
-      password: dbConfig.password,
-      database: dbConfig.database,
-      options: {
-        encrypt: false,
-        trustServerCertificate: dbConfig.trustServerCertificate
-      }
-    })
-    await sqlServerService.connect()
-    return sqlServerService
-  } else {
-    const dbConfig = config.database.mysql
-    const mysqlService = new MySqlService({
-      host: dbConfig.host,
-      port: dbConfig.port,
-      user: dbConfig.username,
-      password: dbConfig.password,
-      database: dbConfig.database
-    })
-    await mysqlService.connect()
-    return mysqlService
-  }
-}
-
-/**
- * Get ERP configuration for current user
- * URL is from config.yaml (fixed infrastructure)
- * Username and password are from user's database config
- */
-async function getErpConfig(): Promise<{
-  url: string
-  username: string
-  password: string
-}> {
-  // Get ERP URL from config.yaml (fixed for all users)
-  const configManager = ConfigManager.getInstance()
-  const globalConfig = configManager.getConfig()
-  const erpUrl = globalConfig.erp.url
-
-  // Get username and password from user's database config
-  const erpConfigService = UserErpConfigService.getInstance()
-  const userConfig = await erpConfigService.getCurrentUserErpConfig()
-
-  if (!userConfig || !userConfig.username || !userConfig.password) {
-    throw new ValidationError(
-      'ERP 配置不完整。请在设置中配置 ERP 用户名和密码',
-      'VAL_MISSING_REQUIRED'
-    )
-  }
-
-  return {
-    url: erpUrl,
-    username: userConfig.username,
-    password: userConfig.password
-  }
-}
 
 export function registerCleanerHandlers(): void {
+  const cleanerService = new CleanerApplicationService()
+
   ipcMain.handle(
     IPC_CHANNELS.CLEANER_RUN,
     async (event, input: CleanerInput): Promise<IpcResult<CleanerResult>> => {
-      const sender = event.sender
+      return withErrorHandling(
-      const startTime = Date.now()
+        async () => cleanerService.runCleaner(event.sender, input),
-
+        'cleaner:run'
-      return withErrorHandling(async () => {
+      )
-        let authService: ErpAuthService | null = null
-        let dbService: MySqlService | SqlServerService | null = null
-
-        try {
-          // Get ERP configuration from database for current user
-          log.info('Fetching ERP configuration from database...')
-          const erpConfig = await getErpConfig()
-
-          log.info('ERP config retrieved', {
-            url: erpConfig.url ? 'configured' : 'EMPTY',
-            username: erpConfig.username ? 'configured' : 'EMPTY'
-          })
-
-          const configManager = ConfigManager.getInstance()
-          const dbType = configManager.getDatabaseType()
-          log.info(
-            `Connecting to ${dbType === 'sqlserver' ? 'SQL Server' : 'MySQL'} for order resolution...`
-          )
-
-          try {
-            dbService = await getDatabaseService()
-          } catch (error) {
-            throw new DatabaseQueryError(
-              '数据库连接失败',
-              'DB_CONNECTION_FAILED',
-              error instanceof Error ? error : undefined
-            )
-          }
-
-          const resolver = new OrderNumberResolver(dbService)
-          const mappings = await resolver.resolve(input.orderNumbers)
-
-          const validOrderNumbers = resolver.getValidOrderNumbers(mappings)
-          const warnings = resolver.getWarnings(mappings)
-
-          if (warnings.length > 0) {
-            log.warn('Resolution warnings', { warnings })
-          }
-
-          if (validOrderNumbers.length === 0) {
-            throw new ValidationError(
-              '没有有效的生产订单号可处理。请检查输入的格式或数据库连接。',
-              'VAL_INVALID_INPUT'
-            )
-          }
-
-          log.info('Resolved order numbers', { count: validOrderNumbers.length })
-
-          authService = new ErpAuthService({
-            url: erpConfig.url,
-            username: erpConfig.username,
-            password: erpConfig.password,
-            headless: input.headless ?? true
-          })
-
-          log.info('Logging in to ERP...')
-          try {
-            await authService.login()
-          } catch (error) {
-            throw new ErpConnectionError(
-              'ERP 登录失败',
-              'ERP_LOGIN_FAILED',
-              error instanceof Error ? error : undefined
-            )
-          }
-          log.info('Login successful')
-
-          // Send login complete progress
-          const totalOrders = validOrderNumbers.length
-          const loginProgress = (1 / (1 + totalOrders)) * 100
-          sendProgress(sender, 'ERP 登录成功', loginProgress, {
-            phase: 'login',
-            currentOrderIndex: 0,
-            totalOrders,
-            currentMaterialIndex: 0,
-            totalMaterialsInOrder: 0
-          })
-
-          const cleaner = new CleanerService(authService)
-
-          const modifiedInput: CleanerInput = {
-            ...input,
-            orderNumbers: validOrderNumbers,
-            onProgress: (message, progress, extra) => {
-              sendProgress(sender, message, progress ?? 0, extra)
-            }
-          }
-
-          log.info('Starting cleaning', {
-            orderCount: validOrderNumbers.length,
-            queryBatchSize: input.queryBatchSize ?? 100,
-            processConcurrency: input.processConcurrency ?? 1
-          })
-          const result = await cleaner.clean(modifiedInput)
-
-          if (warnings.length > 0) {
-            result.errors = [...warnings, ...result.errors]
-          }
-
-          // Send completion progress
-          sendProgress(sender, '清理完成', 100, {
-            phase: 'complete',
-            currentOrderIndex: totalOrders,
-            totalOrders,
-            currentMaterialIndex: 0,
-            totalMaterialsInOrder: 0
-          })
-
-          log.info('Cleaning completed', {
-            processedCount: result.ordersProcessed,
-            errorCount: result.errors.length
-          })
-
-          // Audit log: CLEAN (non-blocking)
-          const os = await import('os')
-          const currentUser = SessionManager.getInstance().getUserInfo()
-          if (currentUser) {
-            const status: 'success' | 'failure' | 'partial' =
-              result.errors.length > 0 && result.materialsDeleted > 0
-                ? 'partial'
-                : result.errors.length > 0
-                  ? 'failure'
-                  : 'success'
-            logAudit('CLEAN', String(currentUser.id), {
-              username: currentUser.username,
-              computerName: os.hostname(),
-              resource: 'MATERIAL_PLAN',
-              status,
-              metadata: {
-                orderCount: validOrderNumbers.length,
-                dryRun: input.dryRun ?? false,
-                queryBatchSize: input.queryBatchSize ?? 100,
-                processConcurrency: input.processConcurrency ?? 1,
-                materialsDeleted: result.materialsDeleted,
-                materialsSkipped: result.materialsSkipped,
-                errorCount: result.errors.length
-              }
-            }).catch((err) => log.warn('Failed to write audit log', { err }))
-          }
-
-          // Generate report and upload to RustFS (silent, user unaware)
-          try {
-            const endTime = Date.now()
-            const currentUser = SessionManager.getInstance().getUserInfo()
-            const username = currentUser?.username ?? 'unknown'
-
-            const reportGenerator = new CleanerReportGenerator()
-            const reportPath = await reportGenerator.generateReport(result, {
-              dryRun: input.dryRun ?? false,
-              username,
-              startTime,
-              endTime
-            })
-            log.info('Report generated', { path: reportPath })
-
-            // Upload to RustFS if enabled
-            const configManager = ConfigManager.getInstance()
-            const config = configManager.getConfig()
-
-            if (config.rustfs?.enabled && config.rustfs.endpoint) {
-              try {
-                const rustfs = new RustfsService({ config: config.rustfs })
-                const reportFileName = reportPath.split(/[\\/]/).pop() || 'report.md'
-                const storageKey = rustfs.generateReportKey(reportFileName, username)
-
-                log.info('Uploading report to RustFS', {
-                  localPath: reportPath,
-                  storageKey
-                })
-
-                const uploadResult = await rustfs.uploadFile(
-                  reportPath,
-                  storageKey,
-                  'text/markdown; charset=utf-8'
-                )
-
-                if (uploadResult.success) {
-                  log.info('Report uploaded to RustFS successfully', {
-                    key: storageKey,
-                    etag: uploadResult.etag
-                  })
-                } else {
-                  log.warn('Failed to upload report to RustFS', {
-                    error: uploadResult.error,
-                    key: storageKey
-                  })
-                }
-              } catch (rustfsError) {
-                log.error('RustFS upload failed', {
-                  error: rustfsError instanceof Error ? rustfsError.message : String(rustfsError)
-                })
-              }
-            } else {
-              log.debug('RustFS is not enabled, skipping upload')
-            }
-          } catch (reportError) {
-            log.warn('Failed to generate report', {
-              error: reportError instanceof Error ? reportError.message : String(reportError)
-            })
-          }
-
-          return result
-        } finally {
-          if (authService) {
-            try {
-              await authService.close()
-              log.debug('Browser closed')
-            } catch (closeError) {
-              log.warn('Error closing browser', {
-                error: closeError instanceof Error ? closeError.message : String(closeError)
-              })
-            }
-          }
-
-          if (dbService) {
-            try {
-              await dbService.disconnect()
-              log.debug('Database disconnected')
-            } catch (closeError) {
-              log.warn('Error disconnecting database', {
-                error: closeError instanceof Error ? closeError.message : String(closeError)
-              })
-            }
-          }
-        }
-      }, 'cleaner:run')
     }
   )
 
   ipcMain.handle(
     IPC_CHANNELS.CLEANER_EXPORT_RESULTS,
     async (_event, items: ExportResultItem[]): Promise<IpcResult<ExportResultResponse>> => {
-      return withErrorHandling(async () => {
+      return withErrorHandling(
-        log.info('Exporting validation results', { count: items.length })
+        async () => cleanerService.exportResults(items),
-        if (!items || items.length === 0) {
+        'cleaner:exportResults'
-          throw new ValidationError('没有数据可导出', 'VAL_INVALID_INPUT')
+      )
-        }
-        const exporter = new ResultExporter()
-        return await exporter.exportValidationResults(items)
-      }, 'cleaner:exportResults')
     }
   )
 }

src/main/ipc/extractor-handler.ts

@@ -3,6 +3,7 @@ import { ErpAuthService } from '../services/erp/erp-auth'
 import { ExtractorService } from '../services/erp/extractor'
 import { OrderNumberResolver } from '../services/erp/order-resolver'
 import { create, type IDatabaseService } from '../services/database'
+import { ExtractorOperationHistoryDAO } from '../services/database/extractor-operation-history-dao'
 import { createLogger } from '../services/logger'
 import { logAudit } from '../services/logger/audit-logger'
 import { SessionManager } from '../services/user/session-manager'
@@ -12,6 +13,7 @@ import type { ExtractorInput, ExtractorResult, ExtractionProgress } from '../typ
 import { UserErpConfigService } from '../services/user/user-erp-config-service'
 import { ConfigManager } from '../services/config/config-manager'
 import { IPC_CHANNELS } from '../../shared/ipc-channels'
+import { randomUUID } from 'crypto'
 
 const log = createLogger('ExtractorHandler')
 
@@ -141,6 +143,29 @@ export function registerExtractorHandlers(): void {
 
           log.info('Resolved order numbers', { count: validOrderNumbers.length })
 
+          // Initialize operation history recording
+          const currentUser = SessionManager.getInstance().getUserInfo()
+          const historyDao = new ExtractorOperationHistoryDAO()
+          const batchId = randomUUID()
+
+          // Save order records to history (preserve productionId -> orderNumber mapping)
+          if (currentUser) {
+            const orderRecords = mappings.map((m) => ({
+              productionId: m.productionId || null,
+              orderNumber: m.orderNumber || m.input
+            }))
+            await historyDao.insertBatchRecords(
+              batchId,
+              currentUser.id,
+              currentUser.username,
+              orderRecords
+            )
+            log.info('Operation history batch created', {
+              batchId,
+              recordCount: orderRecords.length
+            })
+          }
+
           // Log deduplication summary
           sendLog(sender, 'info', dedupReport.summary)
 
@@ -223,11 +248,29 @@ export function registerExtractorHandlers(): void {
             })
           }
 
+          // Update operation history batch status
+          if (currentUser) {
+            const status: 'success' | 'failed' | 'partial' =
+              result.errors.length > 0 && result.recordCount > 0
+                ? 'partial'
+                : result.errors.length > 0
+                  ? 'failed'
+                  : 'success'
+
+            // Write per-order record counts
+            for (const { orderNumber, recordCount } of result.orderRecordCounts) {
+              await historyDao.updateRecordStatus(batchId, orderNumber, status, undefined, recordCount)
+            }
+
+            // Update batch status without recordCount (per-order counts are set individually)
+            await historyDao.updateBatchStatus(batchId, status)
+            log.info('Operation history batch status updated', { batchId, status })
+          }
+
           // Audit log: EXTRACT (non-blocking)
           const os = await import('os')
-          const currentUser = SessionManager.getInstance().getUserInfo()
           if (currentUser) {
-            const status: 'success' | 'failure' | 'partial' =
+            const auditStatus: 'success' | 'failure' | 'partial' =
               result.errors.length > 0 && result.recordCount > 0
                 ? 'partial'
                 : result.errors.length > 0
@@ -237,7 +280,7 @@ export function registerExtractorHandlers(): void {
               username: currentUser.username,
               computerName: os.hostname(),
               resource: 'MATERIAL_PLAN',
-              status,
+              status: auditStatus,
               metadata: {
                 orderCount: validOrderNumbers.length,
                 recordCount: result.recordCount,

src/main/ipc/index.ts

@@ -15,20 +15,21 @@ import { registerMaterialTypeHandlers } from './material-type-handler'
 import { registerUserErpConfigHandlers } from './user-erp-config-handler'
 import { registerLoggerHandlers } from './logger-handler'
 import { registerReportHandlers } from './report-handler'
+import { registerUpdateHandlers } from './update-handler'
+import { registerPlaywrightBrowserHandlers } from './playwright-browser'
+import { registerOperationHistoryHandlers } from './operation-history-handler'
 import { createLogger, logError } from '../services/logger'
 import { serializeError, sanitizeError } from '../services/logger/error-utils'
 import { getErrorMessage, getErrorCode, isBaseError } from '../types/errors'
+import type { IpcResult } from '../types/ipc.types'
+
+export type { IpcResult } from '../types/ipc.types'
 
 const log = createLogger('IPC')
 
-/**
+function getErrorCauseMessage(error: { cause?: unknown }): string | undefined {
- * Standard result type for all IPC handlers
+  const { cause } = error
- */
+  return cause instanceof Error ? cause.message : undefined
-export interface IpcResult<T = unknown> {
-  success: boolean
-  data?: T
-  error?: string
-  code?: string
 }
 
 export function ok<T>(data: T): IpcResult<T> {
@@ -69,7 +70,7 @@ export function withErrorHandling<T>(
       if (isBaseError(error)) {
         logError(log, `[${context}] ${error.name}`, error, {
           code,
-          cause: (error as any).cause?.message,
+          cause: getErrorCauseMessage(error),
           handler: context
         })
       } else {
@@ -105,5 +106,8 @@ export function registerIpcHandlers(): void {
   registerUserErpConfigHandlers()
   registerLoggerHandlers()
   registerReportHandlers()
+  registerUpdateHandlers()
+  registerPlaywrightBrowserHandlers()
+  registerOperationHistoryHandlers()
   log.info('All IPC handlers registered')
 }

src/main/ipc/operation-history-handler.ts

@@ -0,0 +1,124 @@
+/**
+ * IPC Handler for Extractor Operation History
+ *
+ * Handles IPC requests for operation history management:
+ * - Get batch list (filtered by user for non-admin users)
+ * - Get batch details
+ * - Delete batches
+ */
+
+import { ipcMain } from 'electron'
+import { ExtractorOperationHistoryDAO } from '../services/database/extractor-operation-history-dao'
+import { SessionManager } from '../services/user/session-manager'
+import { withErrorHandling, type IpcResult } from './index'
+import { IPC_CHANNELS } from '../../shared/ipc-channels'
+import { createLogger } from '../services/logger'
+import type {
+  BatchStats,
+  OperationHistoryRecord,
+  GetBatchesOptions
+} from '../types/operation-history.types'
+
+const log = createLogger('OperationHistoryHandler')
+
+/**
+ * Register IPC handlers for operation history
+ */
+export function registerOperationHistoryHandlers(): void {
+  const dao = new ExtractorOperationHistoryDAO()
+
+  /**
+   * Get batches list
+   * Admin users get all batches, regular users get only their own
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.OPERATION_HISTORY_GET_BATCHES,
+    async (event, options?: GetBatchesOptions): Promise<IpcResult<BatchStats[]>> => {
+      return withErrorHandling(async () => {
+        const currentUser = SessionManager.getInstance().getUserInfo()
+
+        if (!currentUser) {
+          throw new Error('用户未登录')
+        }
+
+        // Admin gets all batches, User gets only their own
+        const userId = currentUser.userType === 'Admin' ? undefined : currentUser.id
+
+        log.info('Getting operation history batches', {
+          userId: currentUser.id,
+          userType: currentUser.userType,
+          filtered: userId !== undefined
+        })
+
+        const batches = await dao.getBatches(userId, options)
+        return batches
+      }, 'operationHistory:getBatches')
+    }
+  )
+
+  /**
+   * Get batch details
+   * Users can only view their own batch details, admins can view all
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.OPERATION_HISTORY_GET_BATCH_DETAILS,
+    async (event, batchId: string): Promise<IpcResult<OperationHistoryRecord[]>> => {
+      return withErrorHandling(async () => {
+        const currentUser = SessionManager.getInstance().getUserInfo()
+
+        if (!currentUser) {
+          throw new Error('用户未登录')
+        }
+
+        log.info('Getting batch details', { batchId, userId: currentUser.id })
+
+        const details = await dao.getBatchDetails(batchId)
+
+        // For non-admin users, verify they own this batch
+        if (currentUser.userType !== 'Admin' && details.length > 0) {
+          const batchOwnerId = details[0].userId
+          if (batchOwnerId !== currentUser.id) {
+            throw new Error('没有权限查看此批次详情')
+          }
+        }
+
+        return details
+      }, 'operationHistory:getBatchDetails')
+    }
+  )
+
+  /**
+   * Delete a batch
+   * Users can only delete their own batches, admins can delete any
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.OPERATION_HISTORY_DELETE_BATCH,
+    async (event, batchId: string): Promise<IpcResult<{ deleted: boolean }>> => {
+      return withErrorHandling(async () => {
+        const currentUser = SessionManager.getInstance().getUserInfo()
+
+        if (!currentUser) {
+          throw new Error('用户未登录')
+        }
+
+        const isAdmin = currentUser.userType === 'Admin'
+
+        log.info('Deleting batch', {
+          batchId,
+          userId: currentUser.id,
+          isAdmin
+        })
+
+        const result = await dao.deleteBatch(batchId, currentUser.id, isAdmin)
+
+        if (!result.success) {
+          throw new Error(result.error || '删除批次失败')
+        }
+
+        return { deleted: true }
+      }, 'operationHistory:deleteBatch')
+    }
+  )
+
+  log.info('Operation history IPC handlers registered')
+}

src/main/ipc/playwright-browser.ts

@@ -0,0 +1,110 @@
+/**
+ * Playwright Browser IPC Handlers
+ * Handles browser download requests from renderer process
+ */
+
+import { app, ipcMain, IpcMainInvokeEvent } from 'electron'
+import { join } from 'path'
+import { IPC_CHANNELS } from '../../shared/ipc-channels'
+import { withErrorHandling, type IpcResult } from './index'
+import { DownloadService } from '../services/playwright-browser'
+import { ConfigManager } from '../services/config/config-manager'
+import { S3Client } from '@aws-sdk/client-s3'
+import type { DownloadProgress } from '../services/playwright-browser'
+
+/**
+ * Create S3 client from config
+ */
+function createS3Client(): S3Client {
+  const config = ConfigManager.getInstance().getConfig().update
+  if (!config) {
+    throw new Error('Update config is not available')
+  }
+
+  return new S3Client({
+    region: config.region,
+    endpoint: config.endpoint,
+    credentials: {
+      accessKeyId: config.accessKey,
+      secretAccessKey: config.secretKey
+    },
+    forcePathStyle: true
+  })
+}
+
+/**
+ * Check if Playwright browsers are installed
+ */
+async function checkBrowsersExist(): Promise<boolean> {
+  const fs = await import('fs')
+  const browsersPath = join(app.getPath('userData'), 'ms-playwright')
+  const newChromiumPath = join(browsersPath, 'chromium-1208', 'chrome-win64', 'chrome.exe')
+  const oldChromiumPath = join(browsersPath, 'chromium-win32', 'chrome.exe')
+  const chromiumPath = fs.default.existsSync(newChromiumPath) ? newChromiumPath : oldChromiumPath
+
+  if (fs.default.existsSync(chromiumPath)) {
+    return true
+  }
+
+  let foundRevision = false
+  try {
+    const entries = fs.default.readdirSync(browsersPath)
+    for (const entry of entries) {
+      if (entry.startsWith('chromium-') && !entry.includes('headless')) {
+        const revisionPath = join(browsersPath, entry, 'chrome-win64', 'chrome.exe')
+        if (fs.default.existsSync(revisionPath)) {
+          foundRevision = true
+          break
+        }
+      }
+    }
+  } catch {
+    // Ignore browser directory probing failures
+  }
+
+  return foundRevision
+}
+
+/**
+ * Track active download for cancellation
+ */
+let activeDownload: { service: DownloadService; cancelled: boolean } | null = null
+
+export function registerPlaywrightBrowserHandlers(): void {
+  ipcMain.handle(IPC_CHANNELS.PLAYWRIGHT_BROWSER_CHECK, async (): Promise<IpcResult<boolean>> => {
+    return withErrorHandling(async () => {
+      return checkBrowsersExist()
+    }, 'playwright-browser:check')
+  })
+
+  ipcMain.handle(
+    IPC_CHANNELS.PLAYWRIGHT_BROWSER_DOWNLOAD,
+    async (event: IpcMainInvokeEvent): Promise<IpcResult<void>> => {
+      return withErrorHandling(async () => {
+        const s3Client = createS3Client()
+        const service = new DownloadService({ s3Client })
+
+        activeDownload = { service, cancelled: false }
+
+        await service.downloadAll((progress: DownloadProgress) => {
+          if (activeDownload?.cancelled) {
+            throw new Error('Download cancelled by user')
+          }
+
+          event.sender.send(IPC_CHANNELS.PLAYWRIGHT_BROWSER_PROGRESS, progress)
+        })
+
+        activeDownload = null
+      }, 'playwright-browser:download')
+    }
+  )
+
+  ipcMain.handle(IPC_CHANNELS.PLAYWRIGHT_BROWSER_CANCEL, async (): Promise<IpcResult<void>> => {
+    return withErrorHandling(async () => {
+      if (activeDownload) {
+        activeDownload.cancelled = true
+        activeDownload = null
+      }
+    }, 'playwright-browser:cancel')
+  })
+}

src/main/ipc/report-handler.ts

@@ -27,72 +27,69 @@ function getRustfsService(): RustfsService | null {
 }
 
 export function registerReportHandlers(): void {
-  ipcMain.handle(
+  ipcMain.handle(IPC_CHANNELS.REPORT_LIST_ALL, async (): Promise<IpcResult<ReportMetadata[]>> => {
-    IPC_CHANNELS.REPORT_LIST_ALL,
+    return withErrorHandling(async () => {
-    async (): Promise<IpcResult<ReportMetadata[]>> => {
+      const rustfs = getRustfsService()
-      return withErrorHandling(async () => {
+      if (!rustfs) {
-        const rustfs = getRustfsService()
+        throw new Error('RustFS is not configured or enabled')
-        if (!rustfs) {
+      }
-          throw new Error('RustFS is not configured or enabled')
-        }
 
-        const configManager = ConfigManager.getInstance()
+      const configManager = ConfigManager.getInstance()
-        const config = configManager.getConfig()
+      const config = configManager.getConfig()
 
-        // Create a direct S3Client since RustfsService doesn't expose listObjects natively easily
+      // Create a direct S3Client since RustfsService doesn't expose listObjects natively easily
-        const client = new S3Client({
+      const client = new S3Client({
-          region: config.rustfs?.region || 'us-east-1',
+        region: config.rustfs?.region || 'us-east-1',
-          endpoint: config.rustfs?.endpoint || '',
+        endpoint: config.rustfs?.endpoint || '',
-          credentials: {
+        credentials: {
-            accessKeyId: config.rustfs?.accessKey || '',
+          accessKeyId: config.rustfs?.accessKey || '',
-            secretAccessKey: config.rustfs?.secretKey || ''
+          secretAccessKey: config.rustfs?.secretKey || ''
-          },
+        },
-          forcePathStyle: true
+        forcePathStyle: true
-        })
+      })
 
-        log.info('Fetching all reports from RustFS')
+      log.info('Fetching all reports from RustFS')
-        const input = {
+      const input = {
-          Bucket: config.rustfs?.bucket || '',
+        Bucket: config.rustfs?.bucket || '',
-          Prefix: 'reports/cleaner/'
+        Prefix: 'reports/cleaner/'
-        }
+      }
 
-        const command = new ListObjectsV2Command(input)
+      const command = new ListObjectsV2Command(input)
-        const response = await client.send(command)
+      const response = await client.send(command)
 
-        const reports: ReportMetadata[] = []
+      const reports: ReportMetadata[] = []
 
-        if (response.Contents) {
+      if (response.Contents) {
-          for (const item of response.Contents) {
+        for (const item of response.Contents) {
-            if (item.Key && item.Key.endsWith('.md')) {
+          if (item.Key && item.Key.endsWith('.md')) {
-              // reports/cleaner/{username}/{filename}
+            // reports/cleaner/{username}/{filename}
-              const parts = item.Key.split('/')
+            const parts = item.Key.split('/')
-              if (parts.length >= 4) {
+            if (parts.length >= 4) {
-                const username = parts[2]
+              const username = parts[2]
-                const filename = parts.slice(3).join('/')
+              const filename = parts.slice(3).join('/')
-                reports.push({
+              reports.push({
-                  key: item.Key,
+                key: item.Key,
-                  filename,
+                filename,
-                  username,
+                username,
-                  lastModified: item.LastModified,
+                lastModified: item.LastModified,
-                  size: item.Size
+                size: item.Size
-                })
+              })
-              }
             }
           }
         }
+      }
 
-        // Sort by lastModified descending
+      // Sort by lastModified descending
-        reports.sort((a, b) => {
+      reports.sort((a, b) => {
-          if (a.lastModified && b.lastModified) {
+        if (a.lastModified && b.lastModified) {
-            return b.lastModified.getTime() - a.lastModified.getTime()
+          return b.lastModified.getTime() - a.lastModified.getTime()
-          }
+        }
-          return 0
+        return 0
-        })
+      })
 
-        return reports
+      return reports
-      }, 'report:listAll')
+    }, 'report:listAll')
-    }
+  })
-  )
 
   ipcMain.handle(
     IPC_CHANNELS.REPORT_LIST_BY_USER,

src/main/ipc/resolver-handler.ts

@@ -10,38 +10,12 @@ import { ipcMain } from 'electron'
 import { create, type IDatabaseService } from '../services/database'
 import { OrderNumberResolver } from '../services/erp/order-resolver'
 import { createLogger } from '../services/logger'
-import type { OrderMapping, ResolutionStats } from '../services/erp/order-resolver'
+import type { ResolverInput, ResolverResponse } from '../types/resolver-ipc.types'
 import { IPC_CHANNELS } from '../../shared/ipc-channels'
 import { withErrorHandling, type IpcResult } from './index'
 
 const log = createLogger('ResolverHandler')
 
-/**
- * Resolver input from renderer
- */
-export interface ResolverInput {
-  /** List of order numbers/productionIDs to resolve */
-  inputs: string[]
-}
-
-/**
- * Resolver response to renderer
- */
-export interface ResolverResponse {
-  /** Whether the resolution was successful */
-  success: boolean
-  /** Resolved order mappings */
-  mappings?: OrderMapping[]
-  /** Valid production order numbers ready for use */
-  validOrderNumbers?: string[]
-  /** Warning messages for invalid inputs */
-  warnings?: string[]
-  /** Resolution statistics */
-  stats?: ResolutionStats
-  /** Error message if failed */
-  error?: string
-}
-
 /**
  * Register IPC handlers for order number resolver
  */

src/main/ipc/settings-handler.ts

@@ -28,7 +28,13 @@ export function registerSettingsHandlers(): void {
 
   ipcMain.handle(IPC_CHANNELS.SETTINGS_GET_USER_TYPE, async (): Promise<IpcResult<UserType>> => {
     return withErrorHandling(
-      async () => (sessionManager.getUserType() as UserType) || 'Guest',
+      async () => {
+        const userType = sessionManager.getUserType()
+        if (!userType) {
+          throw new ValidationError('未找到用户类型', 'VAL_INVALID_INPUT')
+        }
+        return userType as UserType
+      },
       'settings:getUserType'
     )
   })

src/main/ipc/update-handler.ts

@@ -0,0 +1,55 @@
+import { ipcMain } from 'electron'
+import { IPC_CHANNELS } from '../../shared/ipc-channels'
+import { withErrorHandling, type IpcResult } from './index'
+import { UpdateService } from '../services/update/update-service'
+import type {
+  DownloadReleaseRequest,
+  UpdateDialogCatalog,
+  UpdateStatus
+} from '../types/update.types'
+
+export function registerUpdateHandlers(): void {
+  const updateService = UpdateService.getInstance()
+
+  ipcMain.handle(IPC_CHANNELS.UPDATE_GET_STATUS, async (): Promise<IpcResult<UpdateStatus>> => {
+    return withErrorHandling(async () => updateService.getStatus(), 'update:getStatus')
+  })
+
+  ipcMain.handle(IPC_CHANNELS.UPDATE_CHECK_NOW, async (): Promise<IpcResult<UpdateStatus>> => {
+    return withErrorHandling(async () => updateService.checkForUpdates(), 'update:checkNow')
+  })
+
+  ipcMain.handle(
+    IPC_CHANNELS.UPDATE_GET_CATALOG,
+    async (): Promise<IpcResult<UpdateDialogCatalog>> => {
+      return withErrorHandling(async () => updateService.getCatalog(), 'update:getCatalog')
+    }
+  )
+
+  ipcMain.handle(
+    IPC_CHANNELS.UPDATE_GET_CHANGELOG,
+    async (_event, request: DownloadReleaseRequest): Promise<IpcResult<string>> => {
+      return withErrorHandling(
+        async () => updateService.getChangelog(request),
+        'update:getChangelog'
+      )
+    }
+  )
+
+  ipcMain.handle(
+    IPC_CHANNELS.UPDATE_DOWNLOAD_RELEASE,
+    async (_event, request: DownloadReleaseRequest): Promise<IpcResult<UpdateStatus>> => {
+      return withErrorHandling(
+        async () => updateService.downloadRelease(request),
+        'update:downloadRelease'
+      )
+    }
+  )
+
+  ipcMain.handle(IPC_CHANNELS.UPDATE_INSTALL_DOWNLOADED, async (): Promise<IpcResult<void>> => {
+    return withErrorHandling(
+      async () => updateService.installDownloadedRelease(),
+      'update:installDownloaded'
+    )
+  })
+}

src/main/ipc/validation-handler.ts

@@ -1,478 +1,50 @@
 /**
  * IPC handlers for material validation operations
- *
- * Provides endpoints for:
- * - Running material validation from database
- * - Getting/setting materials to be deleted
- * - Manager-based filtering
  */
 
 import { ipcMain } from 'electron'
-import { MySqlService } from '../services/database/mysql'
-import { SqlServerService } from '../services/database/sql-server'
 import { MaterialsToBeDeletedDAO } from '../services/database/materials-to-be-deleted-dao'
-import { DiscreteMaterialPlanDAO } from '../services/database/discrete-material-plan-dao'
-import { ConfigManager } from '../services/config/config-manager'
 import { createLogger } from '../services/logger'
+import type { MaterialStats } from '../services/database/materials-to-be-deleted-dao'
 import type {
-  ValidationRequest,
-  ValidationResponse,
-  MaterialUpsertBatchRequest,
   MaterialDeleteRequest,
   MaterialOperationResponse,
-  ValidationResult,
+  MaterialRecordSummary,
-  MaterialRecordSummary
+  MaterialUpsertBatchRequest,
+  ValidationRequest,
+  ValidationResponse
 } from '../types/validation.types'
 import { IPC_CHANNELS } from '../../shared/ipc-channels'
+import { sharedProductionIdsStore } from '../services/validation/shared-production-ids-store'
+import { validationApplicationService } from '../services/validation/validation-application-service'
 
 const log = createLogger('ValidationHandler')
 
-/**
- * Shared state for Production IDs from extractor page
- * This is a simple in-memory store for sharing Production IDs between pages
- */
-const sharedProductionIdsBySender = new Map<number, Set<string>>()
-
-/**
- * Set shared Production IDs
- */
-export function setSharedProductionIds(senderId: number, ids: string[]): void {
-  sharedProductionIdsBySender.set(senderId, new Set(ids))
-}
-
-/**
- * Get shared Production IDs
- */
-export function getSharedProductionIds(senderId: number): string[] {
-  const senderSet = sharedProductionIdsBySender.get(senderId)
-  return senderSet ? [...senderSet] : []
-}
-
-/**
- * Clear shared Production IDs
- */
-export function clearSharedProductionIds(senderId: number): void {
-  sharedProductionIdsBySender.delete(senderId)
-}
-
-/**
- * Get database service for validation operations (MySQL or SQL Server)
- */
-async function getValidationDatabaseService(): Promise<MySqlService | SqlServerService> {
-  const configManager = ConfigManager.getInstance()
-  const config = configManager.getConfig()
-  const dbType = configManager.getDatabaseType()
-
-  if (dbType === 'sqlserver') {
-    const dbConfig = config.database.sqlserver
-    const sqlServerService = new SqlServerService({
-      server: dbConfig.server,
-      port: dbConfig.port,
-      user: dbConfig.username,
-      password: dbConfig.password,
-      database: dbConfig.database,
-      options: {
-        encrypt: false,
-        trustServerCertificate: dbConfig.trustServerCertificate
-      }
-    })
-    await sqlServerService.connect()
-    return sqlServerService
-  } else {
-    const dbConfig = config.database.mysql
-    const mysqlService = new MySqlService({
-      host: dbConfig.host,
-      port: dbConfig.port,
-      user: dbConfig.username,
-      password: dbConfig.password,
-      database: dbConfig.database
-    })
-    await mysqlService.connect()
-    return mysqlService
-  }
-}
-
-/**
- * Get table name based on database type
- * Converts MySQL schema_tablename format to SQL Server [schema].[tablename] format
- * e.g., productionContractData_26年压力表合同数据 -> [productionContractData].[26年压力表合同数据]
- *      dbo_MaterialsToBeDeleted -> [dbo].[MaterialsToBeDeleted]
- */
-function getTableName(mysqlTableName: string): string {
-  const configManager = ConfigManager.getInstance()
-  const dbType = configManager.getDatabaseType()
-
-  if (dbType === 'sqlserver') {
-    // Find the FIRST underscore to split schema and table name
-    // This handles patterns like: schema_tablename
-    const firstUnderscoreIndex = mysqlTableName.indexOf('_')
-    if (firstUnderscoreIndex > 0) {
-      const schema = mysqlTableName.substring(0, firstUnderscoreIndex)
-      const tableName = mysqlTableName.substring(firstUnderscoreIndex + 1)
-      return `[${schema}].[${tableName}]`
-    }
-    // If no underscore found, default to dbo schema
-    return `[dbo].[${mysqlTableName}]`
-  }
-  return mysqlTableName
-}
-
-/**
- * Read Production IDs from file
- */
-function readProductionIds(filePath: string): string[] {
-  const fs = require('fs')
-  const content = fs.readFileSync(filePath, 'utf-8') as string
-  return content
-    .split('\n')
-    .map((line: string) => line.trim())
-    .filter((line: string) => line.length > 0)
-}
-
-/**
- * Identify input type (production ID or order number)
- */
-function identifyInputType(input: string): 'production_id' | 'order_number' | 'unknown' {
-  // Order number: SC + 14 digits
-  if (/^SC\d{14}$/.test(input)) {
-    return 'order_number'
-  }
-  // Production ID: 2 digits + 1 letter + 1-6 digits
-  if (/^\d{2}[A-Za-z]\d{1,6}$/.test(input)) {
-    return 'production_id'
-  }
-  return 'unknown'
-}
-
-/**
- * Get source numbers from inputs
- */
-async function getSourceNumbersFromInputs(
-  inputs: string[],
-  dbService: MySqlService | SqlServerService
-): Promise<string[]> {
-  const productionIds: string[] = []
-  const orderNumbers: string[] = []
-  const configManager = ConfigManager.getInstance()
-  const dbType = configManager.getDatabaseType()
-  const isSqlServer = dbType === 'sqlserver'
-
-  for (const item of inputs) {
-    const type = identifyInputType(item)
-    if (type === 'order_number') {
-      orderNumbers.push(item)
-    } else if (type === 'production_id') {
-      productionIds.push(item)
-    }
-  }
-
-  // Query production contract data for production IDs
-  // Table name in MySQL: productionContractData_26年压力表合同数据
-  // Column name: 生产订单号 (SourceNumber)
-  if (productionIds.length > 0) {
-    const contractTableName = getTableName('productionContractData_26年压力表合同数据')
-    const batchSize = 2000
-
-    if (isSqlServer) {
-      const sql = require('mssql')
-      const allOrderNumbers: string[] = []
-
-      for (let i = 0; i < productionIds.length; i += batchSize) {
-        const batch = productionIds.slice(i, i + batchSize)
-        const placeholders = batch.map((_, idx) => `@p${idx}`).join(',')
-        const params: Record<string, { value: string; type: any }> = {}
-
-        batch.forEach((id, idx) => {
-          params[`p${idx}`] = { value: id, type: sql.NVarChar }
-        })
-
-        const contractSql = `
-          SELECT DISTINCT 生产订单号
-          FROM ${contractTableName}
-          WHERE 总排号 IN (${placeholders})
-        `
-        const contractResult = await (dbService as SqlServerService).queryWithParams(
-          contractSql,
-          params
-        )
-        const dbOrderNumbers = contractResult.rows.map((row) => row.生产订单号 as string)
-        allOrderNumbers.push(...dbOrderNumbers)
-      }
-
-      orderNumbers.push(...allOrderNumbers)
-    } else {
-      const allOrderNumbers: string[] = []
-
-      for (let i = 0; i < productionIds.length; i += batchSize) {
-        const batch = productionIds.slice(i, i + batchSize)
-        const placeholders = batch.map(() => '?').join(',')
-        const contractSql = `
-          SELECT DISTINCT 生产订单号
-          FROM ${contractTableName}
-          WHERE 总排号 IN (${placeholders})
-        `
-        const contractResult = await (dbService as MySqlService).query(contractSql, batch)
-        const dbOrderNumbers = contractResult.rows.map((row) => row.生产订单号 as string)
-        allOrderNumbers.push(...dbOrderNumbers)
-      }
-
-      orderNumbers.push(...allOrderNumbers)
-    }
-  }
-
-  // Deduplicate
-  return [...new Set(orderNumbers)]
-}
-
-/**
- * Register IPC handlers for validation operations
- */
 export function registerValidationHandlers(): void {
-  // ==================== VALIDATION ====================
-
-  /**
-   * Run material validation from database
-   */
   ipcMain.handle(
     IPC_CHANNELS.VALIDATION_VALIDATE,
     async (event, request: ValidationRequest): Promise<ValidationResponse> => {
-      let dbService: MySqlService | SqlServerService | null = null
+      const sessionManager = (
+        await import('../services/user/session-manager')
+      ).SessionManager.getInstance()
 
-      try {
+      const userInfo = sessionManager.getUserInfo()
-        // Get current user info
+      if (!userInfo) {
-        const sessionManager = (
-          await import('../services/user/session-manager')
-        ).SessionManager.getInstance()
-
-        const userInfo = sessionManager.getUserInfo()
-        if (!userInfo) {
-          return {
-            success: false,
-            error: '用户未登录',
-            stats: {
-              totalRecords: 0,
-              matchedCount: 0,
-              markedCount: 0
-            }
-          }
-        }
-
-        const isAdmin = userInfo.userType === 'Admin'
-        const username = userInfo.username
-
-        log.info('Starting validation', { mode: request.mode, user: username, isAdmin })
-
-        // Connect to database
-        dbService = await getValidationDatabaseService()
-        const configManager = ConfigManager.getInstance()
-        const dbType = configManager.getDatabaseType()
-        const isSqlServer = dbType === 'sqlserver'
-
-        let sourceNumbers: string[] | null = null
-
-        // Get source numbers based on mode
-        if (request.mode === 'database_filtered') {
-          if (request.useSharedProductionIds) {
-            // Use shared Production IDs from extractor page
-            const sharedIds = getSharedProductionIds(event.sender.id)
-            log.info(`Using ${sharedIds.length} shared Production IDs`)
-
-            if (sharedIds.length === 0) {
-              return {
-                success: false,
-                error: '没有可用的共享 Production ID。请在数据提取页面输入 Production ID。',
-                stats: {
-                  totalRecords: 0,
-                  matchedCount: 0,
-                  markedCount: 0
-                }
-              }
-            }
-
-            sourceNumbers = await getSourceNumbersFromInputs(sharedIds, dbService)
-            log.info(`Got ${sourceNumbers.length} source numbers from shared Production IDs`)
-
-            // Check if we got any order numbers from the shared Production IDs
-            if (sourceNumbers.length === 0) {
-              return {
-                success: false,
-                error:
-                  '共享的 Production ID 没有找到对应的订单数据。请确保在数据提取页面输入了有效的 Production ID 并成功获取了订单数据。',
-                stats: {
-                  totalRecords: 0,
-                  matchedCount: 0,
-                  markedCount: 0
-                }
-              }
-            }
-          } else if (request.productionIdFile) {
-            // Read from file
-            const inputs = readProductionIds(request.productionIdFile)
-            log.info(`Read ${inputs.length} inputs from file`)
-            sourceNumbers = await getSourceNumbersFromInputs(inputs, dbService)
-            log.info(`Got ${sourceNumbers.length} source numbers`)
-
-            // Check if we got any order numbers from the file
-            if (sourceNumbers.length === 0) {
-              return {
-                success: false,
-                error:
-                  '文件中的 Production ID 没有找到对应的订单数据。请检查 Production ID 是否正确，或确保数据库中有对应的订单数据。',
-                stats: {
-                  totalRecords: 0,
-                  matchedCount: 0,
-                  markedCount: 0
-                }
-              }
-            }
-          }
-        }
-
-        // Get material records from DiscreteMaterialPlanData
-        const materialDao = new DiscreteMaterialPlanDAO()
-
-        let materialRecords: any[] = []
-
-        if (request.mode === 'database_full') {
-          // Full table query with deduplication by MaterialCode
-          materialRecords = await materialDao.queryAllDistinctByMaterialCode()
-        } else if (sourceNumbers && sourceNumbers.length > 0) {
-          // Filtered query by source numbers
-          materialRecords = await materialDao.queryBySourceNumbersDistinct(sourceNumbers)
-        }
-
-        if (materialRecords.length === 0) {
-          return {
-            success: false,
-            error: '未找到物料记录。请检查数据库中是否有对应订单的物料数据。',
-            stats: {
-              totalRecords: 0,
-              matchedCount: 0,
-              markedCount: 0
-            }
-          }
-        }
-
-        // Get type keywords from MaterialsTypeToBeDeleted
-        const typeKeywordTableName = getTableName('dbo_MaterialsTypeToBeDeleted')
-        const typeKeywordSql = `
-          SELECT MaterialName, ManagerName
-          FROM ${typeKeywordTableName}
-          WHERE MaterialName IS NOT NULL
-        `
-        const typeKeywordResult = isSqlServer
-          ? await (dbService as SqlServerService).query(typeKeywordSql)
-          : await (dbService as MySqlService).query(typeKeywordSql)
-
-        const typeKeywords = typeKeywordResult.rows.map((row) => ({
-          materialName: row.MaterialName as string,
-          managerName: row.ManagerName as string
-        }))
-
-        // Get marked material codes from MaterialsToBeDeleted
-        const markedTableName = getTableName('dbo_MaterialsToBeDeleted')
-        const markedSql = `
-          SELECT MaterialCode, ManagerName
-          FROM ${markedTableName}
-          WHERE MaterialCode IS NOT NULL AND ManagerName IS NOT NULL
-        `
-        const markedResult = isSqlServer
-          ? await (dbService as SqlServerService).query(markedSql)
-          : await (dbService as MySqlService).query(markedSql)
-
-        const markedCodesDict = new Map<string, string>()
-        for (const row of markedResult.rows) {
-          markedCodesDict.set(row.MaterialCode as string, row.ManagerName as string)
-        }
-
-        // Match materials
-        const results: ValidationResult[] = []
-        for (const record of materialRecords) {
-          const materialName = (record.MaterialName as string) || ''
-          const materialCode = (record.MaterialCode as string) || ''
-          const specification = (record.Specification as string) || ''
-          const model = (record.Model as string) || ''
-
-          // Priority 1: Check MaterialsToBeDeleted (MaterialCode exact match)
-          let managerName = markedCodesDict.get(materialCode) || null
-          const isMarkedForDeletion = managerName !== null
-          let matchedTypeKeyword: string | undefined = undefined
-
-          // Priority 2: Match with MaterialsTypeToBeDeleted (MaterialName contains)
-          if (!managerName) {
-            for (const typeKeyword of typeKeywords) {
-              if (typeKeyword.materialName && materialName.includes(typeKeyword.materialName)) {
-                matchedTypeKeyword = typeKeyword.materialName
-                managerName = typeKeyword.managerName
-                break
-              }
-            }
-          }
-
-          // Priority 3: User Override Match (only for non-admin users)
-          // Override with current user's typeKeyword if available
-          if (!isAdmin && username) {
-            const userKeywords = typeKeywords.filter((tk) => tk.managerName === username)
-            for (const userKeyword of userKeywords) {
-              if (userKeyword.materialName && materialName.includes(userKeyword.materialName)) {
-                matchedTypeKeyword = userKeyword.materialName
-                managerName = userKeyword.managerName
-                break // Force override with first match
-              }
-            }
-          }
-
-          results.push({
-            materialName,
-            materialCode,
-            specification,
-            model,
-            managerName: managerName || '',
-            isMarkedForDeletion,
-            matchedTypeKeyword
-          })
-        }
-
-        const markedCount = results.filter((r) => r.isMarkedForDeletion).length
-        const matchedCount = results.filter((r) => r.managerName).length
-
-        return {
-          success: true,
-          results,
-          stats: {
-            totalRecords: results.length,
-            matchedCount,
-            markedCount
-          }
-        }
-      } catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error'
-        log.error('Validation error', {
-          error: error instanceof Error ? error.message : String(error)
-        })
         return {
           success: false,
-          error: `Validation failed: ${message}`
+          error: '用户未登录',
-        }
+          stats: {
-      } finally {
+            totalRecords: 0,
-        if (dbService) {
+            matchedCount: 0,
-          try {
+            markedCount: 0
-            await dbService.disconnect()
-          } catch (closeError) {
-            log.warn('Error disconnecting database', {
-              error: closeError instanceof Error ? closeError.message : String(closeError)
-            })
           }
         }
       }
+
+      return validationApplicationService.validate(request, userInfo, event.sender.id)
     }
   )
 
-  // ==================== MATERIAL OPERATIONS ====================
-
-  /**
-   * Upsert batch materials to MaterialsToBeDeleted
-   */
   ipcMain.handle(
     IPC_CHANNELS.MATERIALS_UPSERT_BATCH,
     async (_event, request: MaterialUpsertBatchRequest): Promise<MaterialOperationResponse> => {
@@ -486,9 +58,7 @@ export function registerValidationHandlers(): void {
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown error'
-        log.error('Upsert batch error', {
+        log.error('Upsert batch error', { error: message })
-          error: error instanceof Error ? error.message : String(error)
-        })
         return {
           success: false,
           error: `Upsert failed: ${message}`
@@ -497,9 +67,6 @@ export function registerValidationHandlers(): void {
     }
   )
 
-  /**
-   * Delete materials by material codes
-   */
   ipcMain.handle(
     IPC_CHANNELS.MATERIALS_DELETE,
     async (_event, request: MaterialDeleteRequest): Promise<MaterialOperationResponse> => {
@@ -513,7 +80,7 @@ export function registerValidationHandlers(): void {
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown error'
-        log.error('Delete error', { error: error instanceof Error ? error.message : String(error) })
+        log.error('Delete error', { error: message })
         return {
           success: false,
           error: `Delete failed: ${message}`
@@ -522,28 +89,19 @@ export function registerValidationHandlers(): void {
     }
   )
 
-  /**
+  ipcMain.handle(IPC_CHANNELS.MATERIALS_GET_MANAGERS, async (): Promise<{ managers: string[] }> => {
-   * Get unique manager names
+    try {
-   */
+      const dao = new MaterialsToBeDeletedDAO()
-  ipcMain.handle(
+      const managers = await dao.getManagers()
-    IPC_CHANNELS.MATERIALS_GET_MANAGERS,
+      return { managers }
-    async (_event): Promise<{ managers: string[] }> => {
+    } catch (error) {
-      try {
+      log.error('Get managers error', {
-        const dao = new MaterialsToBeDeletedDAO()
+        error: error instanceof Error ? error.message : String(error)
-        const managers = await dao.getManagers()
+      })
-        return { managers }
+      return { managers: [] }
-      } catch (error) {
-        log.error('Get managers error', {
-          error: error instanceof Error ? error.message : String(error)
-        })
-        return { managers: [] }
-      }
     }
-  )
+  })
 
-  /**
-   * Update manager for a single material
-   */
   ipcMain.handle(
     IPC_CHANNELS.MATERIALS_UPDATE_MANAGER,
     async (
@@ -554,337 +112,108 @@ export function registerValidationHandlers(): void {
         const dao = new MaterialsToBeDeletedDAO()
         return await dao.updateManager(request.materialCode, request.managerName)
       } catch (error) {
-        log.error('Update manager error', {
+        const message = error instanceof Error ? error.message : String(error)
-          error: error instanceof Error ? error.message : String(error)
+        log.error('Update manager error', { error: message })
-        })
         return {
           success: false,
-          error: error instanceof Error ? error.message : String(error)
+          error: message
         }
       }
     }
   )
 
-  /**
-   * Get materials by manager
-   */
   ipcMain.handle(
     IPC_CHANNELS.MATERIALS_GET_BY_MANAGER,
     async (_event, managerName: string): Promise<{ materials: MaterialRecordSummary[] }> => {
-      let dbService: MySqlService | SqlServerService | null = null
-
       try {
-        dbService = await getValidationDatabaseService()
+        const materials = await validationApplicationService.getMaterialsByManager(managerName)
-        const configManager = ConfigManager.getInstance()
+        return { materials }
-        const dbType = configManager.getDatabaseType()
-        const isSqlServer = dbType === 'sqlserver'
-
-        const dao = new MaterialsToBeDeletedDAO()
-        const materials = await dao.getMaterialsByManager(managerName)
-
-        // Get material codes set for quick lookup
-        const markedCodes = await dao.getAllMaterialCodes()
-
-        // Enrich with material details from DiscreteMaterialPlanData
-        const enrichedMaterials: MaterialRecordSummary[] = []
-        const detailTableName = getTableName('dbo_DiscreteMaterialPlanData')
-
-        for (const mat of materials) {
-          let detailResult: any
-
-          if (isSqlServer) {
-            const sql = require('mssql')
-            const detailSql = `
-              SELECT TOP 1 MaterialName, Specification, Model
-              FROM ${detailTableName}
-              WHERE MaterialCode = @materialCode
-            `
-            detailResult = await (dbService as SqlServerService).queryWithParams(detailSql, {
-              materialCode: { value: mat.materialCode, type: sql.NVarChar }
-            })
-          } else {
-            const detailSql = `
-              SELECT MaterialName, Specification, Model
-              FROM ${detailTableName}
-              WHERE MaterialCode = ?
-              LIMIT 1
-            `
-            detailResult = await (dbService as MySqlService).query(detailSql, [mat.materialCode])
-          }
-
-          enrichedMaterials.push({
-            materialCode: mat.materialCode,
-            materialName:
-              detailResult.rows.length > 0 ? (detailResult.rows[0].MaterialName as string) : '',
-            specification:
-              detailResult.rows.length > 0 ? (detailResult.rows[0].Specification as string) : '',
-            model: detailResult.rows.length > 0 ? (detailResult.rows[0].Model as string) : '',
-            managerName: mat.managerName,
-            isMarked: markedCodes.has(mat.materialCode)
-          })
-        }
-
-        return { materials: enrichedMaterials }
       } catch (error) {
         log.error('Get by manager error', {
           error: error instanceof Error ? error.message : String(error)
         })
         return { materials: [] }
-      } finally {
-        if (dbService) {
-          try {
-            await dbService.disconnect()
-          } catch (closeError) {
-            log.warn('Error disconnecting database', {
-              error: closeError instanceof Error ? closeError.message : String(closeError)
-            })
-          }
-        }
       }
     }
   )
 
-  /**
-   * Get all material records
-   */
   ipcMain.handle(
     IPC_CHANNELS.MATERIALS_GET_ALL,
-    async (_event): Promise<{ materials: MaterialRecordSummary[] }> => {
+    async (): Promise<{ materials: MaterialRecordSummary[] }> => {
-      let dbService: MySqlService | SqlServerService | null = null
-
       try {
-        dbService = await getValidationDatabaseService()
+        const materials = await validationApplicationService.getAllMaterials()
-        const configManager = ConfigManager.getInstance()
+        return { materials }
-        const dbType = configManager.getDatabaseType()
-        const isSqlServer = dbType === 'sqlserver'
-
-        const dao = new MaterialsToBeDeletedDAO()
-        const materials = await dao.getAllRecords()
-        const markedCodes = await dao.getAllMaterialCodes()
-
-        const enrichedMaterials: MaterialRecordSummary[] = []
-        const detailTableName = getTableName('dbo_DiscreteMaterialPlanData')
-
-        for (const mat of materials) {
-          let detailResult: any
-
-          if (isSqlServer) {
-            const sql = require('mssql')
-            const detailSql = `
-              SELECT TOP 1 MaterialName, Specification, Model
-              FROM ${detailTableName}
-              WHERE MaterialCode = @materialCode
-            `
-            detailResult = await (dbService as SqlServerService).queryWithParams(detailSql, {
-              materialCode: { value: mat.materialCode, type: sql.NVarChar }
-            })
-          } else {
-            const detailSql = `
-              SELECT MaterialName, Specification, Model
-              FROM ${detailTableName}
-              WHERE MaterialCode = ?
-              LIMIT 1
-            `
-            detailResult = await (dbService as MySqlService).query(detailSql, [mat.materialCode])
-          }
-
-          enrichedMaterials.push({
-            materialCode: mat.materialCode,
-            materialName:
-              detailResult.rows.length > 0 ? (detailResult.rows[0].MaterialName as string) : '',
-            specification:
-              detailResult.rows.length > 0 ? (detailResult.rows[0].Specification as string) : '',
-            model: detailResult.rows.length > 0 ? (detailResult.rows[0].Model as string) : '',
-            managerName: mat.managerName,
-            isMarked: markedCodes.has(mat.materialCode)
-          })
-        }
-
-        return { materials: enrichedMaterials }
       } catch (error) {
         log.error('Get all error', {
           error: error instanceof Error ? error.message : String(error)
         })
         return { materials: [] }
-      } finally {
-        if (dbService) {
-          try {
-            await dbService.disconnect()
-          } catch (closeError) {
-            log.warn('Error disconnecting database', {
-              error: closeError instanceof Error ? closeError.message : String(closeError)
-            })
-          }
-        }
       }
     }
   )
 
-  /**
+  ipcMain.handle(
-   * Get statistics
+    IPC_CHANNELS.MATERIALS_GET_STATISTICS,
-   */
+    async (): Promise<{ stats: MaterialStats | null }> => {
-  ipcMain.handle(IPC_CHANNELS.MATERIALS_GET_STATISTICS, async (_event): Promise<{ stats: any }> => {
+      try {
-    try {
+        const dao = new MaterialsToBeDeletedDAO()
-      const dao = new MaterialsToBeDeletedDAO()
+        const stats = await dao.getStatistics()
-      const stats = await dao.getStatistics()
+        return { stats }
-      return { stats }
+      } catch (error) {
-    } catch (error) {
+        log.error('Get statistics error', {
-      log.error('Get statistics error', {
+          error: error instanceof Error ? error.message : String(error)
-        error: error instanceof Error ? error.message : String(error)
+        })
-      })
+        return { stats: null }
-      return { stats: null }
+      }
     }
-  })
+  )
 
-  /**
-   * Set shared Production IDs from extractor page
-   */
   ipcMain.handle(
     IPC_CHANNELS.VALIDATION_SET_SHARED_PRODUCTION_IDS,
     async (event, productionIds: string[]): Promise<void> => {
       log.info(`Received ${productionIds.length} shared Production IDs`)
-      setSharedProductionIds(event.sender.id, productionIds)
+      sharedProductionIdsStore.set(event.sender.id, productionIds)
     }
   )
 
-  /**
-   * Get shared Production IDs
-   */
   ipcMain.handle(
     IPC_CHANNELS.VALIDATION_GET_SHARED_PRODUCTION_IDS,
     async (event): Promise<{ productionIds: string[] }> => {
-      return { productionIds: getSharedProductionIds(event.sender.id) }
+      return { productionIds: sharedProductionIdsStore.get(event.sender.id) }
     }
   )
 
-  /**
-   * Clear shared Production IDs
-   */
   ipcMain.handle(
     IPC_CHANNELS.VALIDATION_CLEAR_SHARED_PRODUCTION_IDS,
     async (event): Promise<void> => {
       log.info('Clearing shared Production IDs')
-      clearSharedProductionIds(event.sender.id)
+      sharedProductionIdsStore.clear(event.sender.id)
     }
   )
 
-  /**
-   * Get cleaner data (order numbers from shared Production IDs + material codes from MaterialsToBeDeleted)
-   * Filters materials by current user (admin sees all, regular users see only their own)
-   */
   ipcMain.handle(
     IPC_CHANNELS.VALIDATION_GET_CLEANER_DATA,
     async (
-      _event
+      event
     ): Promise<{
       success: boolean
       orderNumbers?: string[]
       materialCodes?: string[]
       error?: string
     }> => {
-      let dbService: MySqlService | SqlServerService | null = null
       const sessionManager = (
         await import('../services/user/session-manager')
       ).SessionManager.getInstance()
+      const userInfo = sessionManager.getUserInfo()
 
-      try {
+      if (!userInfo) {
-        // Get current user
-        const userInfo = sessionManager.getUserInfo()
-        if (!userInfo) {
-          return {
-            success: false,
-            error: '用户未登录'
-          }
-        }
-
-        const isAdmin = userInfo.userType === 'Admin'
-        const username = userInfo.username
-        const configManager = ConfigManager.getInstance()
-        const dbType = configManager.getDatabaseType()
-        const isSqlServer = dbType === 'sqlserver'
-
-        log.info(`User: ${username}, isAdmin: ${isAdmin}`)
-
-        // Connect to database
-        dbService = await getValidationDatabaseService()
-
-        // 1. Get order numbers from shared Production IDs
-        const sharedIds = getSharedProductionIds(_event.sender.id)
-        let orderNumbers: string[] = []
-
-        if (sharedIds.length > 0) {
-          log.info(`Using ${sharedIds.length} shared Production IDs`)
-          orderNumbers = await getSourceNumbersFromInputs(sharedIds, dbService)
-          log.info(`Got ${orderNumbers.length} order numbers`)
-        }
-
-        // 2. Get material codes from MaterialsToBeDeleted table
-        let materialCodes: string[] = []
-        const markedTableName = getTableName('dbo_MaterialsToBeDeleted')
-
-        if (isAdmin) {
-          // Admin sees all materials
-          const allCodesSql = `
-            SELECT MaterialCode
-            FROM ${markedTableName}
-            WHERE MaterialCode IS NOT NULL
-          `
-          const result = isSqlServer
-            ? await (dbService as SqlServerService).query(allCodesSql)
-            : await (dbService as MySqlService).query(allCodesSql)
-
-          materialCodes = result.rows.map((row) => row.MaterialCode as string).filter(Boolean)
-          log.info(`Admin user: got ${materialCodes.length} materials`)
-        } else {
-          // Regular users only see their own materials
-          if (isSqlServer) {
-            const sql = require('mssql')
-            const userMaterialsSql = `
-              SELECT MaterialCode
-              FROM ${markedTableName}
-              WHERE ManagerName = @username AND MaterialCode IS NOT NULL
-            `
-            const result = await (dbService as SqlServerService).queryWithParams(userMaterialsSql, {
-              username: { value: username, type: sql.NVarChar }
-            })
-            materialCodes = result.rows.map((row) => row.MaterialCode as string).filter(Boolean)
-          } else {
-            const userMaterialsSql = `
-              SELECT MaterialCode
-              FROM ${markedTableName}
-              WHERE ManagerName = ? AND MaterialCode IS NOT NULL
-            `
-            const result = await (dbService as MySqlService).query(userMaterialsSql, [username])
-            materialCodes = result.rows.map((row) => row.MaterialCode as string).filter(Boolean)
-          }
-          log.info(`Regular user: got ${materialCodes.length} materials`)
-        }
-
-        return {
-          success: true,
-          orderNumbers,
-          materialCodes
-        }
-      } catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error'
-        log.error('CleanerData error', {
-          error: error instanceof Error ? error.message : String(error)
-        })
         return {
           success: false,
-          error: `获取清理数据失败：${message}`
+          error: '用户未登录'
-        }
-      } finally {
-        if (dbService) {
-          try {
-            await dbService.disconnect()
-          } catch (closeError) {
-            log.warn('Error disconnecting database', {
-              error: closeError instanceof Error ? closeError.message : String(closeError)
-            })
-          }
         }
       }
+
+      return validationApplicationService.getCleanerData(userInfo, event.sender.id)
     }
   )
 }

src/main/schemas/auth.schema.ts

@@ -20,7 +20,7 @@ export type LoginRequestZod = z.infer<typeof LoginRequestSchema>
 export const UserInfoSchema = z.object({
   id: z.number().int().positive(),
   username: z.string().min(1),
-  userType: z.enum(['Admin', 'User', 'Guest']),
+  userType: z.enum(['Admin', 'User']),
   computerName: z.string().optional()
 })
 

src/main/services/auth/auth-application-service.ts

@@ -0,0 +1,183 @@
+import { hostname } from 'os'
+import { SessionManager } from '../user/session-manager'
+import { UpdateService } from '../update/update-service'
+import { createLogger } from '../logger'
+import { logAudit } from '../logger/audit-logger'
+import { ValidationError } from '../../types/errors'
+import type { UserInfo } from '../../types/user.types'
+import type {
+  CurrentUserResponse,
+  LoginResponse,
+  SilentLoginResponse,
+  UserSelectionResponse
+} from '../../types/auth-ipc.types'
+
+const log = createLogger('AuthApplicationService')
+
+export class AuthApplicationService {
+  private silentLoginPromise: Promise<SilentLoginResponse> | null = null
+
+  constructor(
+    private readonly sessionManager: SessionManager = SessionManager.getInstance(),
+    private readonly updateService: UpdateService = UpdateService.getInstance()
+  ) {}
+
+  async getComputerName(): Promise<string> {
+    return hostname()
+  }
+
+  async silentLogin(): Promise<SilentLoginResponse> {
+    if (this.silentLoginPromise) {
+      log.debug('Reusing in-flight silent login request')
+      return this.silentLoginPromise
+    }
+
+    this.silentLoginPromise = this.performSilentLogin()
+    try {
+      return await this.silentLoginPromise
+    } finally {
+      this.silentLoginPromise = null
+    }
+  }
+
+  private async performSilentLogin(): Promise<SilentLoginResponse> {
+    log.info('Attempting silent login')
+    const success = await this.sessionManager.loginByComputerName()
+    const userInfo = this.sessionManager.getUserInfo()
+
+    if (!success || !userInfo) {
+      await this.updateService.setUserContext(null)
+      throw new ValidationError('无感登录失败：未找到匹配用户', 'VAL_INVALID_INPUT')
+    }
+
+    await this.updateService.setUserContext(userInfo.userType)
+
+    const requiresUserSelection = userInfo.userType === 'Admin'
+    log.info('Silent login successful', {
+      username: userInfo.username,
+      userType: userInfo.userType,
+      requiresUserSelection
+    })
+
+    this.writeAuditLog('LOGIN', String(userInfo.id), {
+      username: userInfo.username,
+      computerName: hostname(),
+      resource: 'ERP_SYSTEM',
+      status: 'success',
+      metadata: { loginType: 'silent', userType: userInfo.userType }
+    })
+
+    return {
+      success: true,
+      userInfo,
+      requiresUserSelection
+    }
+  }
+
+  async login(username: string, password: string): Promise<LoginResponse> {
+    if (!username || !password) {
+      log.warn('Login attempt with missing credentials')
+      throw new ValidationError('请输入用户名和密码', 'VAL_MISSING_REQUIRED')
+    }
+
+    log.info('Login attempt', { username })
+    const success = await this.sessionManager.login(username, password)
+    const userInfo = this.sessionManager.getUserInfo()
+
+    if (!success || !userInfo) {
+      this.writeAuditLog('LOGIN', '0', {
+        username,
+        computerName: hostname(),
+        resource: 'ERP_SYSTEM',
+        status: 'failure',
+        metadata: { loginType: 'credentials', reason: 'invalid_credentials' }
+      })
+
+      log.warn('Login failed - invalid credentials', { username })
+      await this.updateService.setUserContext(null)
+      throw new ValidationError('用户名或密码错误', 'VAL_INVALID_INPUT')
+    }
+
+    log.info('Login successful', { username, userType: userInfo.userType })
+    await this.updateService.setUserContext(userInfo.userType)
+
+    this.writeAuditLog('LOGIN', String(userInfo.id), {
+      username: userInfo.username,
+      computerName: hostname(),
+      resource: 'ERP_SYSTEM',
+      status: 'success',
+      metadata: { loginType: 'credentials', userType: userInfo.userType }
+    })
+
+    return {
+      success: true,
+      userInfo
+    }
+  }
+
+  async logout(): Promise<void> {
+    const userInfo = this.sessionManager.getUserInfo()
+    log.info('User logout', { username: userInfo?.username })
+
+    if (userInfo) {
+      this.writeAuditLog('LOGOUT', String(userInfo.id), {
+        username: userInfo.username,
+        computerName: hostname(),
+        resource: 'ERP_SYSTEM',
+        status: 'success',
+        metadata: { userType: userInfo.userType }
+      })
+    }
+
+    this.sessionManager.logout()
+    await this.updateService.setUserContext(null)
+  }
+
+  getCurrentUser(): CurrentUserResponse {
+    const isAuthenticated = this.sessionManager.isAuthenticated()
+    const userInfo = this.sessionManager.getUserInfo()
+
+    return {
+      isAuthenticated,
+      userInfo: userInfo ?? undefined
+    }
+  }
+
+  async getAllUsers(): Promise<UserInfo[]> {
+    log.debug('Fetching all users for admin selection')
+    return this.sessionManager.getAllUsers()
+  }
+
+  async switchUser(userInfo: UserInfo): Promise<UserSelectionResponse> {
+    log.info('User switch attempt', { targetUser: userInfo.username })
+    const success = this.sessionManager.switchUser(userInfo)
+
+    if (!success) {
+      log.warn('User switch failed')
+      throw new ValidationError('用户切换失败', 'VAL_INVALID_INPUT')
+    }
+
+    const newUser = this.sessionManager.getUserInfo()
+    log.info('User switch successful', { newUsername: newUser?.username })
+    await this.updateService.setUserContext(newUser?.userType ?? null)
+
+    return {
+      success: true,
+      userInfo: newUser ?? undefined
+    }
+  }
+
+  isAdmin(): boolean {
+    return this.sessionManager.isAdmin()
+  }
+
+  private writeAuditLog(
+    action: 'LOGIN' | 'LOGOUT',
+    actorId: string,
+    payload: Parameters<typeof logAudit>[2]
+  ): void {
+    logAudit(action, actorId, payload).catch((err) =>
+      log.warn('Failed to write audit log', { err })
+    )
+  }
+}

src/main/services/cleaner/cleaner-application-service.ts

@@ -0,0 +1,359 @@
+import type { WebContents } from 'electron'
+import type { MySqlService } from '../database/mysql'
+import type { SqlServerService } from '../database/sql-server'
+import { ErpAuthService } from '../erp/erp-auth'
+import { CleanerService } from '../erp/cleaner'
+import { OrderNumberResolver } from '../erp/order-resolver'
+import { MySqlService as MySqlServiceImpl } from '../database/mysql'
+import { SqlServerService as SqlServerServiceImpl } from '../database/sql-server'
+import { ConfigManager } from '../config/config-manager'
+import { ResultExporter } from '../excel/result-exporter'
+import { CleanerReportGenerator } from '../report/cleaner-report-generator'
+import { RustfsService } from '../rustfs'
+import { SessionManager } from '../user/session-manager'
+import { UserErpConfigService } from '../user/user-erp-config-service'
+import { createLogger } from '../logger'
+import { logAudit } from '../logger/audit-logger'
+import { IPC_CHANNELS } from '../../../shared/ipc-channels'
+import { DatabaseQueryError, ErpConnectionError, ValidationError } from '../../types/errors'
+import type {
+  CleanerInput,
+  CleanerProgress,
+  CleanerResult,
+  ExportResultItem,
+  ExportResultResponse
+} from '../../types/cleaner.types'
+
+const log = createLogger('CleanerApplicationService')
+
+type DatabaseService = MySqlService | SqlServerService
+
+export class CleanerApplicationService {
+  async runCleaner(eventSender: WebContents, input: CleanerInput): Promise<CleanerResult> {
+    const startTime = Date.now()
+    let authService: ErpAuthService | null = null
+    let dbService: DatabaseService | null = null
+
+    try {
+      log.info('Fetching ERP configuration from database...')
+      const erpConfig = await this.getErpConfig()
+
+      log.info('ERP config retrieved', {
+        url: erpConfig.url ? 'configured' : 'EMPTY',
+        username: erpConfig.username ? 'configured' : 'EMPTY'
+      })
+
+      const configManager = ConfigManager.getInstance()
+      const dbType = configManager.getDatabaseType()
+      log.info(
+        `Connecting to ${dbType === 'sqlserver' ? 'SQL Server' : 'MySQL'} for order resolution...`
+      )
+
+      try {
+        dbService = await this.getDatabaseService()
+      } catch (error) {
+        throw new DatabaseQueryError(
+          '数据库连接失败',
+          'DB_CONNECTION_FAILED',
+          error instanceof Error ? error : undefined
+        )
+      }
+
+      const resolver = new OrderNumberResolver(dbService)
+      const mappings = await resolver.resolve(input.orderNumbers)
+      const validOrderNumbers = resolver.getValidOrderNumbers(mappings)
+      const warnings = resolver.getWarnings(mappings)
+
+      if (warnings.length > 0) {
+        log.warn('Resolution warnings', { warnings })
+      }
+
+      if (validOrderNumbers.length === 0) {
+        throw new ValidationError(
+          '没有有效的生产订单号可处理。请检查输入的格式或数据库连接。',
+          'VAL_INVALID_INPUT'
+        )
+      }
+
+      log.info('Resolved order numbers', { count: validOrderNumbers.length })
+
+      authService = new ErpAuthService({
+        url: erpConfig.url,
+        username: erpConfig.username,
+        password: erpConfig.password,
+        headless: input.headless ?? true
+      })
+
+      log.info('Logging in to ERP...')
+      try {
+        await authService.login()
+      } catch (error) {
+        throw new ErpConnectionError(
+          'ERP 登录失败',
+          'ERP_LOGIN_FAILED',
+          error instanceof Error ? error : undefined
+        )
+      }
+      log.info('Login successful')
+
+      const totalOrders = validOrderNumbers.length
+      this.sendProgress(eventSender, 'ERP 登录成功', (1 / (1 + totalOrders)) * 100, {
+        phase: 'login',
+        currentOrderIndex: 0,
+        totalOrders,
+        currentMaterialIndex: 0,
+        totalMaterialsInOrder: 0
+      })
+
+      const cleaner = new CleanerService(authService)
+      const modifiedInput: CleanerInput = {
+        ...input,
+        orderNumbers: validOrderNumbers,
+        onProgress: (message, progress, extra) => {
+          this.sendProgress(eventSender, message, progress ?? 0, extra)
+        }
+      }
+
+      log.info('Starting cleaning', {
+        orderCount: validOrderNumbers.length,
+        queryBatchSize: input.queryBatchSize ?? 100,
+        processConcurrency: input.processConcurrency ?? 1
+      })
+
+      const result = await cleaner.clean(modifiedInput)
+
+      if (warnings.length > 0) {
+        result.errors = [...warnings, ...result.errors]
+      }
+
+      this.sendProgress(eventSender, '清理完成', 100, {
+        phase: 'complete',
+        currentOrderIndex: totalOrders,
+        totalOrders,
+        currentMaterialIndex: 0,
+        totalMaterialsInOrder: 0
+      })
+
+      log.info('Cleaning completed', {
+        processedCount: result.ordersProcessed,
+        errorCount: result.errors.length
+      })
+
+      await this.recordCleanupAudit(validOrderNumbers.length, input, result)
+      await this.generateAndUploadReport(input, result, startTime)
+
+      return result
+    } finally {
+      if (authService) {
+        try {
+          await authService.close()
+          log.debug('Browser closed')
+        } catch (closeError) {
+          log.warn('Error closing browser', {
+            error: closeError instanceof Error ? closeError.message : String(closeError)
+          })
+        }
+      }
+
+      if (dbService) {
+        try {
+          await dbService.disconnect()
+          log.debug('Database disconnected')
+        } catch (closeError) {
+          log.warn('Error disconnecting database', {
+            error: closeError instanceof Error ? closeError.message : String(closeError)
+          })
+        }
+      }
+    }
+  }
+
+  async exportResults(items: ExportResultItem[]): Promise<ExportResultResponse> {
+    log.info('Exporting validation results', { count: items.length })
+    if (!items || items.length === 0) {
+      throw new ValidationError('没有数据可导出', 'VAL_INVALID_INPUT')
+    }
+
+    const exporter = new ResultExporter()
+    return exporter.exportValidationResults(items)
+  }
+
+  private sendProgress(
+    sender: WebContents,
+    message: string,
+    progress: number,
+    extra?: Partial<CleanerProgress>
+  ): void {
+    try {
+      const progressData: CleanerProgress = {
+        message,
+        progress,
+        currentOrderIndex: extra?.currentOrderIndex ?? 0,
+        totalOrders: extra?.totalOrders ?? 0,
+        currentMaterialIndex: extra?.currentMaterialIndex ?? 0,
+        totalMaterialsInOrder: extra?.totalMaterialsInOrder ?? 0,
+        currentOrderNumber: extra?.currentOrderNumber,
+        phase: extra?.phase ?? 'processing'
+      }
+      sender.send(IPC_CHANNELS.CLEANER_PROGRESS, progressData)
+    } catch (error) {
+      log.warn('Failed to send progress event', { error })
+    }
+  }
+
+  private async getDatabaseService(): Promise<DatabaseService> {
+    const configManager = ConfigManager.getInstance()
+    const config = configManager.getConfig()
+    const dbType = configManager.getDatabaseType()
+
+    if (dbType === 'sqlserver') {
+      const dbConfig = config.database.sqlserver
+      const sqlServerService = new SqlServerServiceImpl({
+        server: dbConfig.server,
+        port: dbConfig.port,
+        user: dbConfig.username,
+        password: dbConfig.password,
+        database: dbConfig.database,
+        options: {
+          encrypt: false,
+          trustServerCertificate: dbConfig.trustServerCertificate
+        }
+      })
+      await sqlServerService.connect()
+      return sqlServerService
+    }
+
+    const dbConfig = config.database.mysql
+    const mysqlService = new MySqlServiceImpl({
+      host: dbConfig.host,
+      port: dbConfig.port,
+      user: dbConfig.username,
+      password: dbConfig.password,
+      database: dbConfig.database
+    })
+    await mysqlService.connect()
+    return mysqlService
+  }
+
+  private async getErpConfig(): Promise<{ url: string; username: string; password: string }> {
+    const configManager = ConfigManager.getInstance()
+    const globalConfig = configManager.getConfig()
+    const erpUrl = globalConfig.erp.url
+
+    const erpConfigService = UserErpConfigService.getInstance()
+    const userConfig = await erpConfigService.getCurrentUserErpConfig()
+
+    if (!userConfig || !userConfig.username || !userConfig.password) {
+      throw new ValidationError(
+        'ERP 配置不完整。请在设置中配置 ERP 用户名和密码',
+        'VAL_MISSING_REQUIRED'
+      )
+    }
+
+    return {
+      url: erpUrl,
+      username: userConfig.username,
+      password: userConfig.password
+    }
+  }
+
+  private async recordCleanupAudit(
+    orderCount: number,
+    input: CleanerInput,
+    result: CleanerResult
+  ): Promise<void> {
+    const currentUser = SessionManager.getInstance().getUserInfo()
+    if (!currentUser) {
+      return
+    }
+
+    const status: 'success' | 'failure' | 'partial' =
+      result.errors.length > 0 && result.materialsDeleted > 0
+        ? 'partial'
+        : result.errors.length > 0
+          ? 'failure'
+          : 'success'
+
+    await logAudit('CLEAN', String(currentUser.id), {
+      username: currentUser.username,
+      computerName: (await import('os')).hostname(),
+      resource: 'MATERIAL_PLAN',
+      status,
+      metadata: {
+        orderCount,
+        dryRun: input.dryRun ?? false,
+        queryBatchSize: input.queryBatchSize ?? 100,
+        processConcurrency: input.processConcurrency ?? 1,
+        materialsDeleted: result.materialsDeleted,
+        materialsSkipped: result.materialsSkipped,
+        errorCount: result.errors.length
+      }
+    }).catch((err) => log.warn('Failed to write audit log', { err }))
+  }
+
+  private async generateAndUploadReport(
+    input: CleanerInput,
+    result: CleanerResult,
+    startTime: number
+  ): Promise<void> {
+    try {
+      const endTime = Date.now()
+      const currentUser = SessionManager.getInstance().getUserInfo()
+      const username = currentUser?.username ?? 'unknown'
+
+      const reportGenerator = new CleanerReportGenerator()
+      const reportPath = await reportGenerator.generateReport(result, {
+        dryRun: input.dryRun ?? false,
+        username,
+        startTime,
+        endTime
+      })
+      log.info('Report generated', { path: reportPath })
+
+      const configManager = ConfigManager.getInstance()
+      const config = configManager.getConfig()
+
+      if (!config.rustfs?.enabled || !config.rustfs.endpoint) {
+        log.debug('RustFS is not enabled, skipping upload')
+        return
+      }
+
+      try {
+        const rustfs = new RustfsService({ config: config.rustfs })
+        const reportFileName = reportPath.split(/[\\/]/).pop() || 'report.md'
+        const storageKey = rustfs.generateReportKey(reportFileName, username)
+
+        log.info('Uploading report to RustFS', {
+          localPath: reportPath,
+          storageKey
+        })
+
+        const uploadResult = await rustfs.uploadFile(
+          reportPath,
+          storageKey,
+          'text/markdown; charset=utf-8'
+        )
+
+        if (uploadResult.success) {
+          log.info('Report uploaded to RustFS successfully', {
+            key: storageKey,
+            etag: uploadResult.etag
+          })
+        } else {
+          log.warn('Failed to upload report to RustFS', {
+            error: uploadResult.error,
+            key: storageKey
+          })
+        }
+      } catch (rustfsError) {
+        log.error('RustFS upload failed', {
+          error: rustfsError instanceof Error ? rustfsError.message : String(rustfsError)
+        })
+      }
+    } catch (reportError) {
+      log.warn('Failed to generate report', {
+        error: reportError instanceof Error ? reportError.message : String(reportError)
+      })
+    }
+  }
+}

src/main/services/config/config-manager.ts

@@ -31,6 +31,11 @@ import {
 } from '../../types/config.schema'
 
 const log = createLogger('ConfigManager')
+type DeepPartialRecord = Record<string, unknown>
+
+function formatZodIssue(issue: { path: PropertyKey[]; message: string }): string {
+  return `${issue.path.map((segment) => String(segment)).join('.')}: ${issue.message}`
+}
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -102,6 +107,18 @@ const DEFAULT_CONFIG: FullConfig = {
     secretKey: '',
     bucket: 'erpauto',
     region: 'us-east-1'
+  },
+  update: {
+    enabled: false,
+    allowDevMode: false,
+    endpoint: '',
+    accessKey: '',
+    secretKey: '',
+    bucket: '',
+    region: 'us-east-1',
+    basePrefix: 'updates/win-portable',
+    checkIntervalMinutes: 30,
+    maxAdminHistoryPerChannel: 10
   }
 }
 
@@ -116,7 +133,7 @@ export class ConfigManager {
     if (this.initialized) return
 
     // 检测是否为开发环境
-    const isDev = process.env.NODE_ENV === 'development' || !app.isPackaged
+    const isDev = process.env.NODE_ENV === 'development' || !(app?.isPackaged ?? false)
 
     if (isDev) {
       // 开发环境：配置文件放在项目根目录，方便编辑和调试
@@ -178,7 +195,7 @@ export class ConfigManager {
       log.info('Configuration loaded and validated successfully')
     } catch (error) {
       if (error instanceof z.ZodError) {
-        const messages = error.issues.map((e: any) => `${e.path.join('.')}: ${e.message}`)
+        const messages = error.issues.map(formatZodIssue)
         log.error('Configuration validation failed', { errors: messages })
         throw new Error(`配置文件验证失败:\n${messages.join('\n')}`)
       }
@@ -288,7 +305,7 @@ export class ConfigManager {
       return { success: true }
     } catch (error) {
       if (error instanceof z.ZodError) {
-        const messages = error.issues.map((e: any) => `${e.path.join('.')}: ${e.message}`)
+        const messages = error.issues.map(formatZodIssue)
         return { success: false, error: `配置验证失败:\n${messages.join('\n')}` }
       }
       return { success: false, error: error instanceof Error ? error.message : '未知错误' }
@@ -298,18 +315,27 @@ export class ConfigManager {
   /**
    * 深合并工具函数
    */
-  private deepMerge<T extends Record<string, any>>(source: T, target: Partial<T>): T {
+  private deepMerge<T extends DeepPartialRecord>(source: T, target: Partial<T>): T {
-    const result = { ...source }
+    const result: T = { ...source }
     for (const key in target) {
-      if (target[key] !== undefined) {
+      const sourceValue = result[key]
+      const targetValue = target[key]
+
+      if (targetValue !== undefined) {
         if (
-          typeof target[key] === 'object' &&
+          typeof sourceValue === 'object' &&
-          target[key] !== null &&
+          sourceValue !== null &&
-          !Array.isArray(target[key])
+          !Array.isArray(sourceValue) &&
+          typeof targetValue === 'object' &&
+          targetValue !== null &&
+          !Array.isArray(targetValue)
         ) {
-          result[key] = this.deepMerge(result[key] as any, target[key] as any)
+          result[key] = this.deepMerge(
+            sourceValue as DeepPartialRecord,
+            targetValue as Partial<DeepPartialRecord>
+          ) as T[Extract<keyof T, string>]
         } else {
-          result[key] = target[key] as any
+          result[key] = targetValue as T[Extract<keyof T, string>]
         }
       }
     }

src/main/services/database/extractor-operation-history-dao.ts

@@ -0,0 +1,623 @@
+/**
+ * Data Access Object for ExtractorOperationHistory table
+ *
+ * Handles database operations for tracking extraction operation history:
+ * - Batch record insertion
+ * - Batch status updates
+ * - Querying batches (with user filtering for non-admin users)
+ * - Getting batch details
+ * - Deleting batches
+ */
+
+import { create, type IDatabaseService } from './index'
+import { createLogger } from '../logger'
+import type {
+  OperationHistoryRecord,
+  BatchStats,
+  InsertBatchRecordInput,
+  UpdateBatchStatusResult,
+  GetBatchesOptions
+} from '../../types/operation-history.types'
+
+const log = createLogger('ExtractorOperationHistoryDAO')
+
+/**
+ * Format datetime value from database to ISO string
+ * mssql driver returns Date objects in UTC format
+ */
+function formatDateTime(value: unknown): string {
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+  return value ? String(value) : new Date().toISOString()
+}
+
+/**
+ * Configuration for ExtractorOperationHistory table
+ */
+export const EXTRACTOR_OPERATION_HISTORY_CONFIG = {
+  TABLE_NAME_SQLSERVER: '[dbo].[ExtractorOperationHistory]',
+  TABLE_NAME_MYSQL: 'dbo_ExtractorOperationHistory',
+  COLUMNS: {
+    ID: 'ID',
+    BATCH_ID: 'BatchId',
+    USER_ID: 'UserId',
+    USERNAME: 'Username',
+    PRODUCTION_ID: 'ProductionId',
+    ORDER_NUMBER: 'OrderNumber',
+    OPERATION_TIME: 'OperationTime',
+    STATUS: 'Status',
+    RECORD_COUNT: 'RecordCount',
+    ERROR_MESSAGE: 'ErrorMessage'
+  }
+} as const
+
+/**
+ * ExtractorOperationHistory DAO Class
+ */
+export class ExtractorOperationHistoryDAO {
+  private dbService: IDatabaseService | null = null
+
+  /**
+   * Get the appropriate table name based on database type
+   */
+  private getTableName(): string {
+    const isSqlServer = this.dbService?.type === 'sqlserver'
+    return isSqlServer
+      ? EXTRACTOR_OPERATION_HISTORY_CONFIG.TABLE_NAME_SQLSERVER
+      : EXTRACTOR_OPERATION_HISTORY_CONFIG.TABLE_NAME_MYSQL
+  }
+
+  /**
+   * Get database service instance using DatabaseFactory
+   */
+  private async getDatabaseService(): Promise<IDatabaseService> {
+    if (this.dbService && this.dbService.isConnected()) {
+      return this.dbService
+    }
+
+    this.dbService = await create()
+    return this.dbService
+  }
+
+  /**
+   * Build placeholders for IN clause based on database type
+   */
+  private buildPlaceholders(count: number, isSqlServer: boolean): string {
+    return isSqlServer
+      ? Array.from({ length: count }, (_, idx) => `@p${idx}`).join(',')
+      : Array.from({ length: count }, () => '?').join(',')
+  }
+
+  // ==================== INSERT ====================
+
+  /**
+   * Insert batch records for a single extraction operation
+   * @param batchId - Unique batch identifier
+   * @param userId - User ID performing the operation
+   * @param username - Username performing the operation
+   * @param records - Array of order records to insert
+   * @returns True if successful
+   */
+  async insertBatchRecords(
+    batchId: string,
+    userId: number,
+    username: string,
+    records: InsertBatchRecordInput[]
+  ): Promise<boolean> {
+    if (!records || records.length === 0) {
+      log.warn('No records to insert')
+      return false
+    }
+
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      for (const record of records) {
+        try {
+          if (isSqlServer) {
+            const sqlString = `
+              INSERT INTO ${tableName}
+                (BatchId, UserId, Username, ProductionId, OrderNumber, OperationTime, Status)
+              VALUES
+                (@p0, @p1, @p2, @p3, @p4, GETDATE(), 'pending')
+            `
+            await dbService.query(sqlString, [
+              batchId,
+              userId,
+              username,
+              record.productionId || null,
+              record.orderNumber
+            ])
+          } else {
+            const sqlString = `
+              INSERT INTO ${tableName}
+                (BatchId, UserId, Username, ProductionId, OrderNumber, OperationTime, Status)
+              VALUES
+                (?, ?, ?, ?, ?, NOW(), 'pending')
+            `
+            await dbService.query(sqlString, [
+              batchId,
+              userId,
+              username,
+              record.productionId || null,
+              record.orderNumber
+            ])
+          }
+        } catch (error) {
+          log.error('Error inserting individual record', {
+            batchId,
+            orderNumber: record.orderNumber,
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      }
+
+      log.info('Batch records inserted', { batchId, count: records.length })
+      return true
+    } catch (error) {
+      log.error('Insert batch records error', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return false
+    }
+  }
+
+  // ==================== UPDATE ====================
+
+  /**
+   * Update the status of all records in a batch
+   * @param batchId - Batch identifier
+   * @param status - New status (success, failed, partial)
+   * @returns Update result
+   */
+  async updateBatchStatus(batchId: string, status: string): Promise<UpdateBatchStatusResult> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      const sqlString = `
+        UPDATE ${tableName}
+        SET Status = ${isSqlServer ? '@p0' : '?'}
+        WHERE BatchId = ${isSqlServer ? '@p1' : '?'}
+      `
+      const params = [status, batchId]
+
+      await dbService.query(sqlString, params)
+
+      log.info('Batch status updated', { batchId, status })
+      return { success: true, updatedCount: 1 }
+    } catch (error) {
+      log.error('Update batch status error', {
+        batchId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return { success: false, updatedCount: 0 }
+    }
+  }
+
+  /**
+   * Update a single record's status, error message, and optional record count
+   * @param batchId - Batch identifier
+   * @param orderNumber - Order number
+   * @param status - New status
+   * @param errorMessage - Optional error message
+   * @param recordCount - Optional per-order record count
+   * @returns True if successful
+   */
+  async updateRecordStatus(
+    batchId: string,
+    orderNumber: string,
+    status: string,
+    errorMessage?: string,
+    recordCount?: number
+  ): Promise<boolean> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      let sqlString: string
+      let params: (string | number | null)[]
+
+      if (recordCount !== undefined) {
+        sqlString = `
+          UPDATE ${tableName}
+          SET Status = ${isSqlServer ? '@p0' : '?'},
+              ErrorMessage = ${isSqlServer ? '@p1' : '?'},
+              RecordCount = ${isSqlServer ? '@p2' : '?'}
+          WHERE BatchId = ${isSqlServer ? '@p3' : '?'}
+            AND OrderNumber = ${isSqlServer ? '@p4' : '?'}
+        `
+        params = [status, errorMessage || null, recordCount, batchId, orderNumber]
+      } else {
+        sqlString = `
+          UPDATE ${tableName}
+          SET Status = ${isSqlServer ? '@p0' : '?'},
+              ErrorMessage = ${isSqlServer ? '@p1' : '?'}
+          WHERE BatchId = ${isSqlServer ? '@p2' : '?'}
+            AND OrderNumber = ${isSqlServer ? '@p3' : '?'}
+        `
+        params = [status, errorMessage || null, batchId, orderNumber]
+      }
+
+      await dbService.query(sqlString, params)
+
+      return true
+    } catch (error) {
+      log.error('Update record status error', {
+        batchId,
+        orderNumber,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return false
+    }
+  }
+
+  // ==================== READ ====================
+
+  /**
+   * Get batch statistics with optional user filtering
+   * @param userId - Optional user ID for filtering (Admin gets all, User gets own)
+   * @param options - Query options (limit, offset, usernames)
+   * @returns Array of batch statistics
+   */
+  async getBatches(userId?: number, options?: GetBatchesOptions): Promise<BatchStats[]> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      let sqlString = `
+        SELECT
+          BatchId,
+          UserId,
+          Username,
+          MIN(OperationTime) as OperationTime,
+          MAX(Status) as Status,
+          COUNT(*) as TotalOrders,
+          SUM(COALESCE(RecordCount, 0)) as TotalRecords,
+          SUM(CASE WHEN Status = 'success' THEN 1 ELSE 0 END) as SuccessCount,
+          SUM(CASE WHEN Status = 'failed' THEN 1 ELSE 0 END) as FailedCount
+        FROM ${tableName}
+      `
+
+      const params: (number | string)[] = []
+
+      if (userId !== undefined) {
+        sqlString += isSqlServer ? ` WHERE UserId = @p0 ` : ` WHERE UserId = ? `
+        params.push(userId)
+      } else if (options?.usernames && options.usernames.length > 0) {
+        // Admin user filtering by multiple usernames using IN clause
+        const placeholders = this.buildPlaceholders(options.usernames.length, isSqlServer)
+        sqlString += ` WHERE Username IN (${placeholders}) `
+        params.push(...options.usernames)
+      }
+
+      sqlString += `
+        GROUP BY BatchId, UserId, Username
+        ORDER BY OperationTime DESC
+      `
+
+      if (options?.limit) {
+        const safeLimit = Math.floor(options.limit)
+        const safeOffset = options.offset !== undefined ? Math.floor(options.offset) : undefined
+
+        if (isSqlServer) {
+          // SQL Server: use parameterized OFFSET/FETCH
+          const offsetIndex = params.length
+          if (safeOffset !== undefined) {
+            params.push(safeOffset)
+          }
+          params.push(safeLimit)
+
+          if (safeOffset !== undefined) {
+            sqlString += ` OFFSET @p${offsetIndex} ROWS FETCH NEXT @p${offsetIndex + 1} ROWS ONLY`
+          } else {
+            sqlString += ` OFFSET 0 ROWS FETCH NEXT @p${offsetIndex} ROWS ONLY`
+          }
+        } else {
+          // MySQL: embed validated integer values directly.
+          // connection.execute() uses binary protocol prepared statements,
+          // which do not reliably support ? placeholders in LIMIT/OFFSET clauses.
+          if (safeOffset !== undefined) {
+            sqlString += ` LIMIT ${safeLimit} OFFSET ${safeOffset}`
+          } else {
+            sqlString += ` LIMIT ${safeLimit}`
+          }
+        }
+      }
+
+      const result = await dbService.query(sqlString, params)
+
+      return result.rows.map((row) => ({
+        batchId: row.BatchId as string,
+        userId: row.UserId as number,
+        username: row.Username as string,
+        operationTime: formatDateTime(row.OperationTime),
+        status: row.Status as string,
+        totalOrders: row.TotalOrders as number,
+        totalRecords: (row.TotalRecords as number) || 0,
+        successCount: (row.SuccessCount as number) || 0,
+        failedCount: (row.FailedCount as number) || 0
+      }))
+    } catch (error) {
+      log.error('Get batches error', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return []
+    }
+  }
+
+  /**
+   * Get detailed records for a specific batch
+   * @param batchId - Batch identifier
+   * @returns Array of operation records
+   */
+  async getBatchDetails(batchId: string): Promise<OperationHistoryRecord[]> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      const placeholder = isSqlServer ? '@p0' : '?'
+      const sqlString = `
+        SELECT
+          ID,
+          BatchId,
+          UserId,
+          Username,
+          ProductionId,
+          OrderNumber,
+          OperationTime,
+          Status,
+          RecordCount,
+          ErrorMessage
+        FROM ${tableName}
+        WHERE BatchId = ${placeholder}
+        ORDER BY ID
+      `
+
+      const result = await dbService.query(sqlString, [batchId])
+
+      return result.rows.map((row) => ({
+        id: row.ID as number,
+        batchId: row.BatchId as string,
+        userId: row.UserId as number,
+        username: row.Username as string,
+        productionId: row.ProductionId as string | null,
+        orderNumber: row.OrderNumber as string,
+        operationTime: new Date(row.OperationTime as string),
+        status: row.Status as string,
+        recordCount: row.RecordCount as number | null,
+        errorMessage: row.ErrorMessage as string | null
+      }))
+    } catch (error) {
+      log.error('Get batch details error', {
+        batchId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return []
+    }
+  }
+
+  /**
+   * Get a single batch's statistics
+   * @param batchId - Batch identifier
+   * @returns Batch statistics or null
+   */
+  async getBatchStats(batchId: string): Promise<BatchStats | null> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      const placeholder = isSqlServer ? '@p0' : '?'
+      const sqlString = `
+        SELECT
+          BatchId,
+          UserId,
+          Username,
+          MIN(OperationTime) as OperationTime,
+          MAX(Status) as Status,
+          COUNT(*) as TotalOrders,
+          SUM(COALESCE(RecordCount, 0)) as TotalRecords,
+          SUM(CASE WHEN Status = 'success' THEN 1 ELSE 0 END) as SuccessCount,
+          SUM(CASE WHEN Status = 'failed' THEN 1 ELSE 0 END) as FailedCount
+        FROM ${tableName}
+        WHERE BatchId = ${placeholder}
+        GROUP BY BatchId, UserId, Username
+      `
+
+      const result = await dbService.query(sqlString, [batchId])
+
+      if (result.rows.length === 0) {
+        return null
+      }
+
+      const row = result.rows[0]
+      return {
+        batchId: row.BatchId as string,
+        userId: row.UserId as number,
+        username: row.Username as string,
+        operationTime: formatDateTime(row.OperationTime),
+        status: row.Status as string,
+        totalOrders: row.TotalOrders as number,
+        totalRecords: (row.TotalRecords as number) || 0,
+        successCount: (row.SuccessCount as number) || 0,
+        failedCount: (row.FailedCount as number) || 0
+      }
+    } catch (error) {
+      log.error('Get batch stats error', {
+        batchId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return null
+    }
+  }
+
+  // ==================== DELETE ====================
+
+  /**
+   * Delete a batch with permission checking
+   * @param batchId - Batch identifier
+   * @param requestingUserId - User ID requesting the deletion
+   * @param isAdmin - Whether the requesting user is an admin
+   * @returns True if successful
+   */
+  async deleteBatch(
+    batchId: string,
+    requestingUserId: number,
+    isAdmin: boolean
+  ): Promise<{ success: boolean; error?: string }> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      // First check if the batch exists and if the user has permission
+      const batchStats = await this.getBatchStats(batchId)
+
+      if (!batchStats) {
+        return { success: false, error: '批次不存在' }
+      }
+
+      // Non-admin users can only delete their own batches
+      if (!isAdmin && batchStats.userId !== requestingUserId) {
+        return { success: false, error: '没有权限删除此批次' }
+      }
+
+      // Delete the batch
+      const placeholder = isSqlServer ? '@p0' : '?'
+      const sqlString = `
+        DELETE FROM ${tableName}
+        WHERE BatchId = ${placeholder}
+      `
+
+      const result = await dbService.query(sqlString, [batchId])
+
+      log.info('Batch deleted', { batchId, rowCount: result.rowCount })
+      return { success: true }
+    } catch (error) {
+      log.error('Delete batch error', {
+        batchId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    }
+  }
+
+  /**
+   * Delete all batches for a specific user
+   * @param userId - User ID
+   * @returns Number of batches deleted
+   */
+  async deleteByUser(userId: number): Promise<number> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      const placeholder = isSqlServer ? '@p0' : '?'
+      const sqlString = `
+        DELETE FROM ${tableName}
+        WHERE UserId = ${placeholder}
+      `
+
+      const result = await dbService.query(sqlString, [userId])
+      return result.rowCount
+    } catch (error) {
+      log.error('Delete by user error', {
+        userId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return 0
+    }
+  }
+
+  // ==================== UTILITIES ====================
+
+  /**
+   * Check if a batch exists
+   * @param batchId - Batch identifier
+   * @returns True if batch exists
+   */
+  async batchExists(batchId: string): Promise<boolean> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      const placeholder = isSqlServer ? '@p0' : '?'
+      const sqlString = `
+        SELECT COUNT(*) as count
+        FROM ${tableName}
+        WHERE BatchId = ${placeholder}
+      `
+
+      const result = await dbService.query(sqlString, [batchId])
+      return result.rows.length > 0 && (result.rows[0].count as number) > 0
+    } catch (error) {
+      log.error('Batch exists error', {
+        batchId,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return false
+    }
+  }
+
+  /**
+   * Count total batches with optional user filtering
+   * @param userId - Optional user ID for filtering
+   * @param usernames - Optional usernames filter for Admin users
+   * @returns Total number of batches
+   */
+  async countBatches(userId?: number, usernames?: string[]): Promise<number> {
+    try {
+      const dbService = await this.getDatabaseService()
+      const tableName = this.getTableName()
+      const isSqlServer = dbService.type === 'sqlserver'
+
+      let sqlString = `
+        SELECT COUNT(DISTINCT BatchId) as count
+        FROM ${tableName}
+      `
+
+      const params: (number | string)[] = []
+
+      if (userId !== undefined) {
+        sqlString += isSqlServer ? ` WHERE UserId = @p0 ` : ` WHERE UserId = ? `
+        params.push(userId)
+      } else if (usernames && usernames.length > 0) {
+        // Admin user filtering by multiple usernames using IN clause
+        const placeholders = this.buildPlaceholders(usernames.length, isSqlServer)
+        sqlString += ` WHERE Username IN (${placeholders}) `
+        params.push(...usernames)
+      }
+
+      const result = await dbService.query(sqlString, params)
+      return result.rows.length > 0 ? (result.rows[0].count as number) : 0
+    } catch (error) {
+      log.error('Count batches error', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+      return 0
+    }
+  }
+
+  /**
+   * Disconnect from database
+   */
+  async disconnect(): Promise<void> {
+    if (this.dbService) {
+      await this.dbService.disconnect()
+      this.dbService = null
+    }
+  }
+}

src/main/services/database/repositories/DiscreteMaterialPlanRepository.ts

@@ -5,7 +5,7 @@
  */
 
 import { DataSource, Repository, In } from 'typeorm'
-import { DiscreteMaterialPlan, MaterialPlanRecordData } from '../entities/DiscreteMaterialPlan'
+import { DiscreteMaterialPlan } from '../entities/DiscreteMaterialPlan'
 import { getDataSource } from '../data-source'
 import { createLogger } from '../../logger'
 

src/main/services/database/repositories/MaterialsToBeDeletedRepository.ts

@@ -124,12 +124,6 @@ export class MaterialsToBeDeletedRepository {
   async getAllMaterialCodes(): Promise<Set<string>> {
     try {
       const repo = await this.getRepository()
-      const records = await repo.find({
-        select: ['materialCode'],
-        where: { materialCode: In([]) } // This will be overridden
-      })
-
-      // Use query builder for better performance
       const result = await repo
         .createQueryBuilder('m')
         .select('m.materialCode')

src/main/services/erp/erp-auth.ts

@@ -108,7 +108,6 @@ export class ErpAuthService {
       browser,
       context,
       page,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       mainFrame: mainFrame as any, // Store forwardFrame content frame for subsequent operations
       isLoggedIn: true
     }

src/main/services/erp/extractor.ts

@@ -46,7 +46,8 @@ export class ExtractorService {
       downloadedFiles: [],
       mergedFile: null,
       recordCount: 0,
-      errors: []
+      errors: [],
+      orderRecordCounts: []
     }
 
     try {
@@ -79,6 +80,7 @@ export class ExtractorService {
         const mergeResult = await this.mergeFiles(result.downloadedFiles)
         result.mergedFile = mergeResult.mergedFile
         result.recordCount = mergeResult.recordCount
+        result.orderRecordCounts = mergeResult.orderRecordCounts
 
         // Add merge error to result if any
         if (mergeResult.error) {
@@ -123,9 +125,14 @@ export class ExtractorService {
    */
   private async mergeFiles(
     filePaths: string[]
-  ): Promise<{ mergedFile: string | null; recordCount: number; error?: string }> {
+  ): Promise<{
+    mergedFile: string | null
+    recordCount: number
+    error?: string
+    orderRecordCounts: Array<{ orderNumber: string; recordCount: number }>
+  }> {
     if (filePaths.length === 0) {
-      return { mergedFile: null, recordCount: 0 }
+      return { mergedFile: null, recordCount: 0, orderRecordCounts: [] }
     }
 
     log.info('Starting merge', { fileCount: filePaths.length })
@@ -154,15 +161,21 @@ export class ExtractorService {
 
     // Calculate total record count (total material rows)
     let recordCount = 0
+    const orderRecordCounts: Array<{ orderNumber: string; recordCount: number }> = []
     for (const order of allOrders) {
-      recordCount += order.materials.length
+      const count = order.materials.length
+      recordCount += count
+      orderRecordCounts.push({
+        orderNumber: order.orderInfo.productionOrder || '',
+        recordCount: count
+      })
     }
 
     log.info('Merge summary', { orderCount: allOrders.length, recordCount })
 
     if (recordCount === 0) {
       log.warn('No records found in any downloaded files')
-      return { mergedFile: null, recordCount: 0 }
+      return { mergedFile: null, recordCount: 0, orderRecordCounts }
     }
 
     // Generate output filename with timestamp
@@ -178,13 +191,13 @@ export class ExtractorService {
       log.info('Saving merged file', { outputPath })
       await this.saveMergedOrders(allOrders, outputPath)
       log.info('Merged file saved successfully', { recordCount })
-      return { mergedFile: outputPath, recordCount }
+      return { mergedFile: outputPath, recordCount, orderRecordCounts }
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error)
       const errorStack = error instanceof Error ? error.stack : ''
       log.error('Failed to save merged file', { error: errorMsg, stack: errorStack })
       // Return parsed record count and error info even if save fails
-      return { mergedFile: null, recordCount, error: `保存合并文件失败：${errorMsg}` }
+      return { mergedFile: null, recordCount, orderRecordCounts, error: `保存合并文件失败：${errorMsg}` }
     }
   }
 

src/main/services/erp/order-resolver.ts

@@ -13,42 +13,14 @@
 import type { IDatabaseService } from '../database'
 import { ConfigManager } from '../config/config-manager'
 import { createLogger } from '../logger'
+import type {
+  OrderMapping,
+  OrderNumberType,
+  ResolutionStats
+} from '../../types/order-resolver.types'
 
 const log = createLogger('OrderResolver')
 
-/**
- * Order mapping result
- */
-export interface OrderMapping {
-  /** Original input from user */
-  input: string
-  /** Recognized productionID (if input matches productionID pattern) */
-  productionId?: string
-  /** Final production order number to use */
-  orderNumber?: string
-  /** Whether the order number was successfully resolved */
-  resolved: boolean
-  /** Error message if resolution failed */
-  error?: string
-}
-
-/**
- * Order number type recognition result
- */
-export type OrderNumberType = 'productionId' | 'orderNumber' | 'unknown'
-
-/**
- * Resolution statistics
- */
-export interface ResolutionStats {
-  totalInputs: number
-  validOrderNumbers: number
-  validProductionIds: number
-  resolvedCount: number
-  failedCount: number
-  unknownFormat: number
-}
-
 /**
  * ProductionID pattern: 2 digits + 1 letter + 1-6 digits
  * Examples: 22A1, 22A123, 26B10617

src/main/services/excel/excel-parser.ts

@@ -70,7 +70,7 @@ export class ExcelParser {
     const allRows: any[][] = []
 
     // Read all rows into memory
-    worksheet.eachRow((row, _rowNumber) => {
+    worksheet.eachRow((row) => {
       allRows.push(row.values as any[])
     })
 

src/main/services/logger/index.ts

@@ -115,7 +115,7 @@ export function setLogLevel(level: string): void {
 }
 
 // Add error-specific file transport in production
-if (app.isPackaged) {
+if (app?.isPackaged) {
   logger.add(
     new DailyRotateFile({
       filename: path.join(getLogDir(), 'error-%DATE%.log'),

src/main/services/playwright-browser/download-service.ts

@@ -0,0 +1,407 @@
+/**
+ * Playwright Browser Download Service
+ *
+ * Downloads Playwright browser files from S3 to local directory
+ * with progress tracking and basic validation.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { S3Client, ListObjectsV2Command, GetObjectCommand } from '@aws-sdk/client-s3'
+import { createLogger } from '../logger'
+
+const log = createLogger('PlaywrightDownloadService')
+
+/**
+ * Download progress event
+ */
+export interface DownloadProgress {
+  percent: number
+  downloadedBytes: number
+  totalBytes: number
+  currentFile: string
+  speed: number
+  eta?: number
+}
+
+/**
+ * S3 Object information
+ */
+export interface S3Object {
+  key: string
+  size?: number
+  lastModified?: Date
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  success: boolean
+  message: string
+  fileCount?: number
+  chromeExeExists?: boolean
+  expectedChromePath?: string
+}
+
+/**
+ * Download configuration
+ */
+export interface DownloadConfig {
+  s3Client?: S3Client
+  bucket?: string
+  prefix?: string
+  destDir?: string
+}
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: Required<DownloadConfig> = {
+  s3Client: null as unknown as S3Client,
+  bucket: 'erpauto',
+  prefix: 'resources/ms-playwright/', // ✅ Fixed: removed 'erpauto/' prefix
+  destDir: path.join(process.env.APPDATA || '', 'erpauto', 'ms-playwright')
+}
+
+/**
+ * DownloadService class
+ * Handles downloading Playwright browser files from S3
+ */
+export class DownloadService {
+  private config: Required<DownloadConfig>
+  private s3Client: S3Client
+
+  constructor(config?: DownloadConfig) {
+    if (!config?.s3Client) {
+      throw new Error('S3Client is required')
+    }
+
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      bucket: config?.bucket || DEFAULT_CONFIG.bucket,
+      prefix: config?.prefix || DEFAULT_CONFIG.prefix,
+      destDir: config?.destDir || DEFAULT_CONFIG.destDir
+    }
+
+    this.s3Client = this.config.s3Client
+  }
+
+  /**
+   * Execute an operation with retry logic using exponential backoff
+   * @param operation - The async operation to execute
+   * @param context - Description of the operation for logging
+   * @param maxRetries - Maximum number of retry attempts (default: 3)
+   * @returns The result of the operation
+   */
+  private async withRetry<T>(
+    operation: () => Promise<T>,
+    context: string,
+    maxRetries = 3
+  ): Promise<T> {
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation()
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+
+        // Check if error is retryable
+        const isRetryable = this.isRetryableError(lastError)
+        if (!isRetryable || attempt === maxRetries) {
+          break
+        }
+
+        // Exponential backoff: 1s, 2s, 4s
+        const delay = Math.pow(2, attempt - 1) * 1000
+        log.warn(`${context} failed (attempt ${attempt}/${maxRetries}), retrying in ${delay}ms`, {
+          error: lastError.message
+        })
+
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    }
+
+    throw lastError
+  }
+
+  /**
+   * Determine if an error is retryable based on error type and message
+   * @param error - The error to classify
+   * @returns true if the error should trigger a retry
+   */
+  private isRetryableError(error: Error): boolean {
+    const message = error.message.toLowerCase()
+    const code = (error as any).code?.toLowerCase() || ''
+
+    // Retryable: network errors, timeouts
+    const retryablePatterns = [
+      'etimedout',
+      'econnreset',
+      'timeout',
+      'network',
+      'socket hang up',
+      'connection reset'
+    ]
+
+    // Not retryable: S3 errors, validation errors
+    const nonRetryablePatterns = [
+      '404',
+      '403',
+      'not found',
+      'access denied',
+      'invalid',
+      'validation'
+    ]
+
+    // Check non-retryable first
+    for (const pattern of nonRetryablePatterns) {
+      if (message.includes(pattern) || code.includes(pattern)) {
+        return false
+      }
+    }
+
+    // Check retryable
+    for (const pattern of retryablePatterns) {
+      if (message.includes(pattern) || code.includes(pattern)) {
+        return true
+      }
+    }
+
+    // Default: don't retry unknown errors
+    return false
+  }
+
+  /**
+   * List all S3 objects under the configured prefix
+   * Filters to include ALL Chromium files (regular + headless)
+   * Simple filter: includes 'chromium' keyword
+   */
+  async listObjects(): Promise<S3Object[]> {
+    log.info('Listing S3 objects', { bucket: this.config.bucket, prefix: this.config.prefix })
+
+    const objects: S3Object[] = []
+    let continuationToken: string | undefined
+
+    do {
+      const response = await this.s3Client.send(
+        new ListObjectsV2Command({
+          Bucket: this.config.bucket,
+          Prefix: this.config.prefix,
+          ContinuationToken: continuationToken
+        })
+      )
+
+      for (const obj of response.Contents || []) {
+        if (!obj.Key) continue
+
+        // Simple filter: only download Chromium-related files
+        // This includes: chromium-1200, chromium-1208, chromium_headless_shell-1200, chromium_headless_shell-1208
+        // Excludes: firefox, webkit, ffmpeg, winldd, .links, .settings
+        if (!obj.Key.includes('chromium')) {
+          continue
+        }
+
+        objects.push({
+          key: obj.Key,
+          size: obj.Size,
+          lastModified: obj.LastModified
+        })
+      }
+
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined
+    } while (continuationToken)
+
+    log.info(`Found ${objects.length} Chromium objects`)
+    return objects
+  }
+
+  /**
+   * Download a single file from S3 with retry logic
+   */
+  async downloadFile(key: string, destPath: string): Promise<void> {
+    await this.withRetry(async () => {
+      log.debug('Downloading file', { key, destPath })
+
+      await fs.promises.mkdir(path.dirname(destPath), { recursive: true })
+
+      const response = await this.s3Client.send(
+        new GetObjectCommand({
+          Bucket: this.config.bucket,
+          Key: key
+        })
+      )
+
+      const output = fs.createWriteStream(destPath)
+      const body = response.Body as NodeJS.ReadableStream
+
+      await new Promise<void>((resolve, reject) => {
+        body.on('error', reject)
+        output.on('error', reject)
+        output.on('finish', resolve)
+        body.pipe(output)
+      })
+
+      log.debug('File downloaded', { key, destPath })
+    }, `Download ${key}`)
+  }
+
+  /**
+   * Download all Chromium browser files from S3
+   * Emits progress events during download
+   */
+  async downloadAll(onProgress: (progress: DownloadProgress) => void): Promise<void> {
+    log.info('Starting download of all browser files', { destDir: this.config.destDir })
+
+    const objects = await this.listObjects()
+    if (objects.length === 0) {
+      throw new Error('No Chromium browser files found in S3')
+    }
+
+    // Calculate total bytes
+    const totalBytes = objects.reduce((sum, obj) => sum + (obj.size || 0), 0)
+    log.info(`Total files: ${objects.length}, Total bytes: ${totalBytes}`)
+
+    let downloadedBytes = 0
+    const startTime = Date.now()
+
+    for (const obj of objects) {
+      const relativePath = obj.key.replace(this.config.prefix, '')
+      const destPath = path.join(this.config.destDir, relativePath)
+
+      // Emit progress for current file
+      onProgress({
+        percent: Math.round((downloadedBytes / totalBytes) * 100),
+        downloadedBytes,
+        totalBytes,
+        currentFile: relativePath,
+        speed: 0,
+        eta: undefined
+      })
+
+      try {
+        await this.downloadFile(obj.key, destPath)
+
+        const fileSize = obj.size || 0
+        downloadedBytes += fileSize
+
+        // Calculate speed and ETA
+        const elapsedSeconds = (Date.now() - startTime) / 1000
+        const speed = Math.round(downloadedBytes / elapsedSeconds)
+        const remainingBytes = totalBytes - downloadedBytes
+        const eta = speed > 0 ? Math.round(remainingBytes / speed) : undefined
+
+        onProgress({
+          percent: Math.round((downloadedBytes / totalBytes) * 100),
+          downloadedBytes,
+          totalBytes,
+          currentFile: relativePath,
+          speed,
+          eta
+        })
+
+        log.debug('Downloaded file', {
+          key: obj.key,
+          size: fileSize,
+          speed: `${speed} bytes/s`
+        })
+      } catch (error) {
+        log.error('Failed to download file', {
+          key: obj.key,
+          error: error instanceof Error ? error.message : String(error)
+        })
+        throw new Error(
+          `Failed to download ${relativePath}: ${error instanceof Error ? error.message : String(error)}`
+        )
+      }
+    }
+
+    const totalElapsed = (Date.now() - startTime) / 1000
+    log.info('Download completed', {
+      totalFiles: objects.length,
+      totalBytes,
+      duration: `${totalElapsed.toFixed(1)}s`,
+      avgSpeed: `${Math.round(downloadedBytes / totalElapsed)} bytes/s`
+    })
+
+    // Final progress event
+    onProgress({
+      percent: 100,
+      downloadedBytes: totalBytes,
+      totalBytes,
+      currentFile: 'Complete',
+      speed: Math.round(downloadedBytes / totalElapsed),
+      eta: 0
+    })
+  }
+
+  /**
+   * Validate the downloaded files
+   * Checks if the destination directory exists and chrome.exe is present
+   */
+  async validateDownload(): Promise<ValidationResult> {
+    log.info('Validating download', { destDir: this.config.destDir })
+
+    // Check if destination directory exists
+    try {
+      await fs.promises.access(this.config.destDir)
+    } catch {
+      return {
+        success: false,
+        message: 'Download directory does not exist',
+        fileCount: 0,
+        chromeExeExists: false
+      }
+    }
+
+    // Find chrome.exe in chromium-* folders
+    const chromeExePattern = /chromium-\d+[/\\]chrome-win64[/\\]chrome\.exe$/
+    let chromeExeExists = false
+    let expectedChromePath: string | undefined
+    let fileCount = 0
+
+    const findChromeExe = async (dir: string): Promise<void> => {
+      const entries = await fs.promises.readdir(dir, { withFileTypes: true })
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name)
+
+        if (entry.isDirectory()) {
+          await findChromeExe(fullPath)
+        } else if (entry.name.toLowerCase() === 'chrome.exe') {
+          // Check if path matches chromium-*/chrome-win64/chrome.exe pattern
+          const relativePath = path.relative(this.config.destDir, fullPath)
+          if (chromeExePattern.test(relativePath.replace(/\\/g, '/'))) {
+            chromeExeExists = true
+            expectedChromePath = fullPath
+          }
+        }
+
+        fileCount++
+      }
+    }
+
+    try {
+      await findChromeExe(this.config.destDir)
+    } catch (error) {
+      log.error('Error scanning download directory', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+    }
+
+    const result: ValidationResult = {
+      success: chromeExeExists,
+      message: chromeExeExists ? 'Validation passed' : 'chrome.exe not found in expected location',
+      fileCount,
+      chromeExeExists,
+      expectedChromePath
+    }
+
+    log.info('Validation result', result)
+    return result
+  }
+}
+
+export default DownloadService

src/main/services/playwright-browser/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Playwright Browser Module Exports
+ */
+
+export { DownloadService, default } from './download-service'
+export type {
+  DownloadProgress,
+  S3Object,
+  ValidationResult,
+  DownloadConfig
+} from './download-service'

src/main/services/update/update-catalog-service.ts

@@ -0,0 +1,166 @@
+import { createLogger } from '../logger'
+import type { UpdateConfig } from '../../types/config.schema'
+import type { UserType } from '../../types/user.types'
+import type {
+  UpdateCatalog,
+  UpdateDialogCatalog,
+  UpdateRelease,
+  UpdateStatus
+} from '../../types/update.types'
+import type { UpdateInstaller } from './update-installer'
+import type { UpdateStorageClient } from './update-storage-client'
+import { isMissingObjectError } from './update-support'
+import {
+  compareVersions,
+  limitCatalogHistory,
+  normalizeReleases,
+  resolveAdminDecision,
+  resolveUserDecision
+} from './update-utils'
+
+const log = createLogger('UpdateCatalogService')
+
+export class UpdateCatalogService {
+  constructor(
+    private readonly config: UpdateConfig,
+    private readonly storageClient: UpdateStorageClient,
+    private readonly installer: UpdateInstaller
+  ) {}
+
+  public getDialogCatalog(status: UpdateStatus, catalog: UpdateCatalog): UpdateDialogCatalog {
+    const currentUserType = status.currentUserType
+    if (!status.enabled || !currentUserType) {
+      return { mode: 'disabled' }
+    }
+
+    if (currentUserType === 'User') {
+      return {
+        mode: 'user',
+        recommendedRelease: status.recommendedRelease
+      }
+    }
+
+    return {
+      mode: 'admin',
+      recommendedRelease: status.recommendedRelease,
+      channels: limitCatalogHistory(catalog, this.config.maxAdminHistoryPerChannel ?? 10)
+    }
+  }
+
+  public async loadCatalog(currentUserType: UserType | null): Promise<UpdateCatalog> {
+    return {
+      stable: await this.fetchChannelIndex('stable'),
+      preview: currentUserType === 'Admin' ? await this.fetchChannelIndex('preview') : []
+    }
+  }
+
+  public async resolveUserStatus(
+    status: UpdateStatus,
+    catalog: UpdateCatalog
+  ): Promise<Partial<UpdateStatus>> {
+    const decision = resolveUserDecision({
+      currentVersion: status.currentVersion,
+      currentChannel: status.currentChannel,
+      catalog
+    })
+
+    if (!decision.recommendedRelease || !decision.shouldOffer) {
+      return {
+        phase: 'idle',
+        recommendedRelease: undefined,
+        latestVersion: undefined,
+        latestChannel: undefined,
+        downloadedRelease: undefined,
+        progress: undefined,
+        adminHasAnyRelease: false,
+        error: undefined,
+        message: undefined
+      }
+    }
+
+    const recommended = decision.recommendedRelease
+    const existing = await this.installer.getValidDownloadedRelease(recommended)
+
+    if (existing) {
+      return {
+        phase: 'downloaded',
+        recommendedRelease: recommended,
+        latestVersion: recommended.version,
+        latestChannel: recommended.channel,
+        progress: 100,
+        downloadedRelease: {
+          version: existing.version,
+          channel: existing.channel,
+          localPath: existing.localPath
+        },
+        adminHasAnyRelease: false,
+        error: undefined,
+        message:
+          status.currentChannel === 'preview'
+            ? `稳定版 ${recommended.version} 已准备安装`
+            : `发现稳定版 ${recommended.version}`
+      }
+    }
+
+    return {
+      phase: 'available',
+      recommendedRelease: recommended,
+      latestVersion: recommended.version,
+      latestChannel: recommended.channel,
+      downloadedRelease: undefined,
+      progress: undefined,
+      adminHasAnyRelease: false,
+      error: undefined,
+      message:
+        status.currentChannel === 'preview'
+          ? `当前为预览版，可切换回稳定版 ${recommended.version}`
+          : `发现稳定版 ${recommended.version}`
+    }
+  }
+
+  public resolveAdminStatus(status: UpdateStatus, catalog: UpdateCatalog): Partial<UpdateStatus> {
+    const decision = resolveAdminDecision({
+      currentVersion: status.currentVersion,
+      currentChannel: status.currentChannel,
+      catalog,
+      maxHistoryPerChannel: this.config.maxAdminHistoryPerChannel ?? 10
+    })
+
+    const hasHigherVersion = [...catalog.stable, ...catalog.preview].some(
+      (release) => compareVersions(release.version, status.currentVersion) > 0
+    )
+    const hasCrossChannelOption = [...catalog.stable, ...catalog.preview].some(
+      (release) => release.channel !== status.currentChannel
+    )
+    const shouldOffer = hasHigherVersion || hasCrossChannelOption
+
+    return {
+      phase: shouldOffer ? 'available' : 'idle',
+      recommendedRelease: decision.recommendedRelease,
+      latestVersion: decision.recommendedRelease?.version,
+      latestChannel: decision.recommendedRelease?.channel,
+      adminHasAnyRelease: shouldOffer,
+      downloadedRelease: undefined,
+      progress: undefined,
+      error: undefined,
+      message: shouldOffer ? '发现可用版本' : undefined
+    }
+  }
+
+  private async fetchChannelIndex(channel: 'stable' | 'preview'): Promise<UpdateRelease[]> {
+    const key = `${this.config.basePrefix}/${channel}/index.json`
+
+    try {
+      const raw = await this.storageClient.readText(key)
+      const parsed = JSON.parse(raw) as unknown
+      return normalizeReleases(parsed, channel)
+    } catch (error) {
+      if (isMissingObjectError(error)) {
+        log.warn('Update channel index not found, treating as empty', { channel, key })
+        return []
+      }
+
+      throw error
+    }
+  }
+}

src/main/services/update/update-installer.ts

@@ -0,0 +1,146 @@
+import { app } from 'electron'
+import { createHash } from 'crypto'
+import * as fs from 'fs'
+import * as path from 'path'
+import { spawn } from 'child_process'
+import { createLogger } from '../logger'
+import type { DownloadedRelease, UpdateRelease } from '../../types/update.types'
+import { appendPortableLaunchLog } from './update-support'
+
+const log = createLogger('UpdateInstaller')
+
+export class UpdateInstaller {
+  public async getValidDownloadedRelease(
+    release: UpdateRelease
+  ): Promise<DownloadedRelease | null> {
+    const downloadPath = this.getDownloadPath(release)
+    if (!fs.existsSync(downloadPath)) {
+      return null
+    }
+
+    const hash = await this.calculateSha256(downloadPath)
+    if (hash.toLowerCase() !== release.sha256.toLowerCase()) {
+      await fs.promises.rm(downloadPath, { force: true })
+      return null
+    }
+
+    return {
+      ...release,
+      localPath: downloadPath
+    }
+  }
+
+  public getDownloadPath(release: Pick<UpdateRelease, 'channel' | 'version'>): string {
+    return path.join(
+      app.getPath('userData'),
+      'pending-update',
+      `${release.channel}-${release.version}.exe`
+    )
+  }
+
+  public async calculateSha256(filePath: string): Promise<string> {
+    const hash = createHash('sha256')
+    const input = fs.createReadStream(filePath)
+
+    await new Promise<void>((resolve, reject) => {
+      input.on('data', (chunk) => hash.update(chunk))
+      input.on('error', reject)
+      input.on('end', resolve)
+    })
+
+    return hash.digest('hex')
+  }
+
+  public async installDownloadedRelease(
+    downloaded: Pick<DownloadedRelease, 'version' | 'channel' | 'localPath'>
+  ): Promise<void> {
+    const updaterSourcePath = this.resolveUpdaterBinaryPath()
+    const updaterPath = await this.prepareUpdaterBinary(updaterSourcePath)
+    const targetExe = process.env.PORTABLE_EXECUTABLE_FILE || process.execPath
+    const logPath = path.join(app.getPath('userData'), 'updates', 'portable-update.log')
+    const launchLogPath = path.join(app.getPath('userData'), 'updates', 'portable-launch.log')
+    const appArgs = process.argv.slice(1)
+    const argsBase64 =
+      appArgs.length > 0 ? Buffer.from(appArgs.join('\0'), 'utf-8').toString('base64') : ''
+
+    const spawnArgs = [
+      '--targetExe',
+      targetExe,
+      '--downloadedExe',
+      downloaded.localPath,
+      '--parentPid',
+      String(process.pid),
+      '--logPath',
+      logPath
+    ]
+
+    if (argsBase64) {
+      spawnArgs.push('--argsBase64', argsBase64)
+    }
+
+    appendPortableLaunchLog(launchLogPath, 'Preparing portable updater launch', {
+      updaterSourcePath,
+      updaterPath,
+      targetExe,
+      downloadedExe: downloaded.localPath,
+      parentPid: process.pid,
+      logPath,
+      appArgs,
+      updaterExists: fs.existsSync(updaterPath),
+      spawnArgs
+    })
+
+    const child = spawn(updaterPath, spawnArgs, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true
+    })
+
+    appendPortableLaunchLog(launchLogPath, 'Spawn returned for portable updater', {
+      childPid: child.pid ?? null
+    })
+
+    child.on('error', (error) => {
+      appendPortableLaunchLog(launchLogPath, 'Portable updater executable spawn error', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+      log.error('Failed to launch portable updater executable', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+    })
+
+    child.once('spawn', () => {
+      appendPortableLaunchLog(launchLogPath, 'Portable updater executable spawned', {
+        childPid: child.pid ?? null
+      })
+    })
+
+    child.unref()
+    app.quit()
+  }
+
+  private resolveUpdaterBinaryPath(): string {
+    const packagedPath = path.join(process.resourcesPath, 'portable-updater.exe')
+    const devPath = path.resolve(process.cwd(), 'build', 'bin', 'portable-updater.exe')
+
+    if (fs.existsSync(packagedPath)) {
+      return packagedPath
+    }
+
+    if (fs.existsSync(devPath)) {
+      return devPath
+    }
+
+    throw new Error('未找到便携版更新器')
+  }
+
+  private async prepareUpdaterBinary(sourcePath: string): Promise<string> {
+    const updatesDir = path.join(app.getPath('userData'), 'updates')
+    const stagedPath = path.join(updatesDir, 'portable-updater.exe')
+
+    await fs.promises.mkdir(updatesDir, { recursive: true })
+    await fs.promises.copyFile(sourcePath, stagedPath)
+
+    return stagedPath
+  }
+}

src/main/services/update/update-service.ts

@@ -0,0 +1,288 @@
+import * as fs from 'fs'
+import { ConfigManager } from '../config/config-manager'
+import { createLogger } from '../logger'
+import type { UpdateConfig } from '../../types/config.schema'
+import type { UserType } from '../../types/user.types'
+import type {
+  DownloadReleaseRequest,
+  UpdateCatalog,
+  UpdateDialogCatalog,
+  UpdateStatus
+} from '../../types/update.types'
+import { UpdateCatalogService } from './update-catalog-service'
+import { UpdateInstaller } from './update-installer'
+import { UpdateStorageClient } from './update-storage-client'
+import { publishUpdateStatus } from './update-status-publisher'
+import { DEFAULT_STATUS, getSupportState } from './update-support'
+
+const log = createLogger('UpdateService')
+
+export class UpdateService {
+  private static instance: UpdateService | null = null
+
+  private config: UpdateConfig | null = null
+  private storageClient: UpdateStorageClient | null = null
+  private catalogService: UpdateCatalogService | null = null
+  private installer = new UpdateInstaller()
+  private status: UpdateStatus = { ...DEFAULT_STATUS }
+  private catalog: UpdateCatalog = { stable: [], preview: [] }
+  private changelogCache = new Map<string, string>()
+  private intervalHandle: NodeJS.Timeout | null = null
+  private initialized = false
+
+  public static getInstance(): UpdateService {
+    if (!UpdateService.instance) {
+      UpdateService.instance = new UpdateService()
+    }
+
+    return UpdateService.instance
+  }
+
+  public initialize(): void {
+    if (this.initialized) {
+      return
+    }
+
+    this.config = ConfigManager.getInstance().getConfig().update ?? null
+    const supportState = getSupportState(this.config)
+    const enabled = Boolean(this.config?.enabled && supportState.supported)
+
+    this.status = {
+      ...this.status,
+      enabled,
+      supported: supportState.supported,
+      message: supportState.reason
+    }
+
+    if (enabled && this.config) {
+      this.storageClient = new UpdateStorageClient(this.config)
+      this.catalogService = new UpdateCatalogService(
+        this.config,
+        this.storageClient,
+        this.installer
+      )
+    }
+
+    log.info('Update service initialized', {
+      enabled,
+      supported: supportState.supported,
+      currentVersion: this.status.currentVersion,
+      currentChannel: this.status.currentChannel
+    })
+
+    this.initialized = true
+  }
+
+  public getStatus(): UpdateStatus {
+    return { ...this.status }
+  }
+
+  public getCatalog(): UpdateDialogCatalog {
+    if (!this.catalogService) {
+      return { mode: 'disabled' }
+    }
+
+    return this.catalogService.getDialogCatalog(this.status, this.catalog)
+  }
+
+  public async getChangelog(release: DownloadReleaseRequest): Promise<string> {
+    this.ensureInitialized()
+    if (!this.status.enabled || !this.storageClient) {
+      throw new Error('自动更新不可用')
+    }
+
+    const cacheKey = `${release.channel}:${release.version}`
+    const cached = this.changelogCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const markdown = await this.storageClient.readText(release.changelogKey)
+    this.changelogCache.set(cacheKey, markdown)
+    return markdown
+  }
+
+  public async setUserContext(userType: UserType | null): Promise<void> {
+    this.ensureInitialized()
+    this.status.currentUserType = userType
+
+    if (!this.status.enabled || !userType) {
+      this.clearPolling()
+      this.catalog = { stable: [], preview: [] }
+      this.publishStatus({
+        phase: 'idle',
+        currentUserType: userType,
+        recommendedRelease: undefined,
+        latestVersion: undefined,
+        latestChannel: undefined,
+        downloadedRelease: undefined,
+        progress: undefined,
+        adminHasAnyRelease: false,
+        error: undefined,
+        message: this.status.supported ? undefined : this.status.message
+      })
+      return
+    }
+
+    // 启动异步更新检查，不阻塞登录流程
+    void this.checkForUpdates().catch((error) => {
+      log.warn('Async update check failed', {
+        error: error instanceof Error ? error.message : String(error)
+      })
+    })
+    this.startPolling()
+  }
+
+  public async checkForUpdates(): Promise<UpdateStatus> {
+    this.ensureInitialized()
+    if (!this.status.enabled || !this.storageClient || !this.catalogService) {
+      return this.getStatus()
+    }
+
+    this.publishStatus({
+      phase: 'checking',
+      error: undefined,
+      message: '正在检查更新...'
+    })
+
+    try {
+      const currentUserType = this.status.currentUserType
+      this.catalog = await this.catalogService.loadCatalog(currentUserType)
+
+      if (currentUserType === 'User') {
+        const nextStatus = await this.catalogService.resolveUserStatus(this.status, this.catalog)
+        this.publishStatus(nextStatus)
+
+        if (nextStatus.phase === 'available' && nextStatus.recommendedRelease) {
+          // 异步下载，不阻塞更新检查流程
+          void this.downloadRelease(nextStatus.recommendedRelease).catch((error) => {
+            const message = error instanceof Error ? error.message : '下载更新失败'
+            log.warn('Async update download failed', { error: message })
+            this.publishStatus({
+              phase: 'error',
+              error: message,
+              message
+            })
+          })
+        }
+      } else if (currentUserType === 'Admin') {
+        this.publishStatus(this.catalogService.resolveAdminStatus(this.status, this.catalog))
+      } else {
+        this.publishStatus({
+          phase: 'idle',
+          message: undefined,
+          error: undefined
+        })
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : '检查更新失败'
+      log.error('Failed to check for updates', { error: message })
+      this.publishStatus({
+        phase: 'error',
+        error: message,
+        message: '检查更新失败'
+      })
+    }
+
+    return this.getStatus()
+  }
+
+  public async downloadRelease(request: DownloadReleaseRequest): Promise<UpdateStatus> {
+    this.ensureInitialized()
+    if (!this.status.enabled || !this.storageClient) {
+      throw new Error('自动更新不可用')
+    }
+
+    this.publishStatus({
+      phase: 'downloading',
+      progress: 0,
+      latestVersion: request.version,
+      latestChannel: request.channel,
+      recommendedRelease: request,
+      message: `正在下载 ${request.channel} ${request.version}...`,
+      error: undefined
+    })
+
+    const downloadPath = this.installer.getDownloadPath(request)
+    await this.storageClient.downloadToFile(request.artifactKey, downloadPath)
+    const hash = await this.installer.calculateSha256(downloadPath)
+
+    if (hash.toLowerCase() !== request.sha256.toLowerCase()) {
+      await fs.promises.rm(downloadPath, { force: true })
+      throw new Error('更新包校验失败，文件哈希不匹配')
+    }
+
+    this.publishStatus({
+      phase: 'downloaded',
+      progress: 100,
+      downloadedRelease: {
+        version: request.version,
+        channel: request.channel,
+        localPath: downloadPath
+      },
+      latestVersion: request.version,
+      latestChannel: request.channel,
+      message: `已下载 ${request.channel} ${request.version}`
+    })
+
+    return this.getStatus()
+  }
+
+  public async installDownloadedRelease(): Promise<void> {
+    this.ensureInitialized()
+
+    const downloaded = this.status.downloadedRelease
+    if (!this.status.enabled || !downloaded) {
+      throw new Error('没有可安装的更新包')
+    }
+
+    this.publishStatus({
+      phase: 'installing',
+      latestVersion: downloaded.version,
+      latestChannel: downloaded.channel,
+      message: `正在安装 ${downloaded.version}...`,
+      error: undefined
+    })
+
+    await this.installer.installDownloadedRelease(downloaded)
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      this.initialize()
+    }
+  }
+
+  private publishStatus(next: Partial<UpdateStatus>): void {
+    this.status = {
+      ...this.status,
+      ...next
+    }
+
+    publishUpdateStatus(this.status)
+  }
+  private startPolling(): void {
+    this.clearPolling()
+    if (!this.config) {
+      return
+    }
+
+    this.intervalHandle = setInterval(
+      () => {
+        this.checkForUpdates().catch((error) => {
+          log.warn('Periodic update check failed', {
+            error: error instanceof Error ? error.message : String(error)
+          })
+        })
+      },
+      this.config.checkIntervalMinutes * 60 * 1000
+    )
+  }
+
+  private clearPolling(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle)
+      this.intervalHandle = null
+    }
+  }
+}

src/main/services/update/update-status-publisher.ts

@@ -0,0 +1,9 @@
+import { BrowserWindow } from 'electron'
+import { IPC_CHANNELS } from '../../../shared/ipc-channels'
+import type { UpdateStatus } from '../../types/update.types'
+
+export function publishUpdateStatus(status: UpdateStatus): void {
+  BrowserWindow.getAllWindows().forEach((window) => {
+    window.webContents.send(IPC_CHANNELS.UPDATE_STATUS_CHANGED, status)
+  })
+}

src/main/services/update/update-storage-client.ts

@@ -0,0 +1,57 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
+import type { UpdateConfig } from '../../types/config.schema'
+
+export class UpdateStorageClient {
+  private client: S3Client
+  private bucket: string
+
+  constructor(config: UpdateConfig) {
+    this.bucket = config.bucket
+    this.client = new S3Client({
+      region: config.region,
+      endpoint: config.endpoint,
+      credentials: {
+        accessKeyId: config.accessKey,
+        secretAccessKey: config.secretKey
+      },
+      forcePathStyle: true
+    })
+  }
+
+  async readText(key: string): Promise<string> {
+    const response = await this.client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key
+      })
+    )
+
+    const chunks: Buffer[] = []
+    for await (const chunk of response.Body as AsyncIterable<Uint8Array>) {
+      chunks.push(Buffer.from(chunk))
+    }
+    return Buffer.concat(chunks).toString('utf-8')
+  }
+
+  async downloadToFile(key: string, destination: string): Promise<void> {
+    const response = await this.client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key
+      })
+    )
+
+    await fs.promises.mkdir(path.dirname(destination), { recursive: true })
+    const output = fs.createWriteStream(destination)
+    const body = response.Body as NodeJS.ReadableStream
+
+    await new Promise<void>((resolve, reject) => {
+      body.on('error', reject)
+      output.on('error', reject)
+      output.on('finish', resolve)
+      body.pipe(output)
+    })
+  }
+}

src/main/services/update/update-support.ts

@@ -0,0 +1,76 @@
+import { app } from 'electron'
+import * as fs from 'fs'
+import * as path from 'path'
+import type { UpdateConfig } from '../../types/config.schema'
+import type { ReleaseChannel, UpdateStatus } from '../../types/update.types'
+
+export function appendPortableLaunchLog(
+  logPath: string,
+  message: string,
+  meta?: Record<string, unknown>
+): void {
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true })
+    const timestamp = new Date().toISOString()
+    const suffix = meta ? ` ${JSON.stringify(meta)}` : ''
+    fs.appendFileSync(logPath, `${timestamp} ${message}${suffix}\n`, 'utf-8')
+  } catch {
+    // Best-effort debug log only.
+  }
+}
+
+export function getCurrentAppVersion(): string {
+  return typeof app?.getVersion === 'function' ? app.getVersion() : '0.0.0'
+}
+
+export function getCurrentChannel(): ReleaseChannel {
+  return typeof __APP_CHANNEL__ !== 'undefined' ? __APP_CHANNEL__ : 'stable'
+}
+
+export function isMissingObjectError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false
+  }
+
+  const candidate = error as {
+    name?: string
+    Code?: string
+    code?: string
+    message?: string
+  }
+
+  return (
+    candidate.name === 'NoSuchKey' ||
+    candidate.Code === 'NoSuchKey' ||
+    candidate.code === 'NoSuchKey' ||
+    candidate.message?.includes('The specified key does not exist') === true
+  )
+}
+
+export function getSupportState(config: UpdateConfig | null): {
+  supported: boolean
+  reason?: string
+} {
+  if (process.platform !== 'win32') {
+    return { supported: false, reason: '当前仅支持 Windows 自动更新' }
+  }
+
+  if (app?.isPackaged) {
+    return { supported: true }
+  }
+
+  if (config?.allowDevMode) {
+    return { supported: true, reason: '开发模式调试已启用更新检查' }
+  }
+
+  return { supported: false, reason: '开发模式默认禁用自动更新检查' }
+}
+
+export const DEFAULT_STATUS: UpdateStatus = {
+  enabled: false,
+  supported: false,
+  phase: 'idle',
+  currentVersion: getCurrentAppVersion(),
+  currentChannel: getCurrentChannel(),
+  currentUserType: null
+}

src/main/services/update/update-utils.ts

@@ -0,0 +1,125 @@
+import type {
+  ReleaseChannel,
+  UpdateCatalog,
+  UpdateDialogCatalog,
+  UpdateRelease
+} from '../../types/update.types'
+
+export function compareVersions(left: string, right: string): number {
+  const leftParts = left.split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const rightParts = right.split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const length = Math.max(leftParts.length, rightParts.length)
+
+  for (let index = 0; index < length; index += 1) {
+    const leftValue = leftParts[index] ?? 0
+    const rightValue = rightParts[index] ?? 0
+
+    if (leftValue > rightValue) return 1
+    if (leftValue < rightValue) return -1
+  }
+
+  return 0
+}
+
+export function normalizeReleases(input: unknown, channel: ReleaseChannel): UpdateRelease[] {
+  const list = Array.isArray(input)
+    ? input
+    : input &&
+        typeof input === 'object' &&
+        Array.isArray((input as { releases?: unknown[] }).releases)
+      ? (input as { releases: unknown[] }).releases
+      : []
+
+  return list
+    .filter((item): item is Record<string, unknown> => !!item && typeof item === 'object')
+    .map((item) => ({
+      version: String(item.version ?? ''),
+      channel,
+      artifactKey: String(item.artifactKey ?? ''),
+      sha256: String(item.sha256 ?? ''),
+      size: Number(item.size ?? 0),
+      publishedAt: String(item.publishedAt ?? ''),
+      changelogKey: String(item.changelogKey ?? ''),
+      notesSummary: item.notesSummary ? String(item.notesSummary) : undefined
+    }))
+    .filter(
+      (item) =>
+        !!item.version &&
+        !!item.artifactKey &&
+        !!item.sha256 &&
+        !!item.changelogKey &&
+        !!item.publishedAt
+    )
+}
+
+export function sortReleases(releases: UpdateRelease[]): UpdateRelease[] {
+  return [...releases].sort((left, right) => {
+    const versionCompare = compareVersions(right.version, left.version)
+    if (versionCompare !== 0) {
+      return versionCompare
+    }
+
+    return new Date(right.publishedAt).getTime() - new Date(left.publishedAt).getTime()
+  })
+}
+
+export function pickLatestRelease(releases: UpdateRelease[]): UpdateRelease | undefined {
+  return sortReleases(releases)[0]
+}
+
+export function limitCatalogHistory(catalog: UpdateCatalog, maxPerChannel: number): UpdateCatalog {
+  return {
+    stable: sortReleases(catalog.stable).slice(0, maxPerChannel),
+    preview: sortReleases(catalog.preview).slice(0, maxPerChannel)
+  }
+}
+
+export function resolveUserDecision(params: {
+  currentVersion: string
+  currentChannel: ReleaseChannel
+  catalog: UpdateCatalog
+}): {
+  recommendedRelease?: UpdateRelease
+  shouldOffer: boolean
+} {
+  const latestStable = pickLatestRelease(params.catalog.stable)
+  if (!latestStable) {
+    return { recommendedRelease: undefined, shouldOffer: false }
+  }
+
+  if (params.currentChannel === 'preview') {
+    return { recommendedRelease: latestStable, shouldOffer: true }
+  }
+
+  return {
+    recommendedRelease: latestStable,
+    shouldOffer: params.currentVersion !== latestStable.version
+  }
+}
+
+export function resolveAdminDecision(params: {
+  currentVersion: string
+  currentChannel: ReleaseChannel
+  catalog: UpdateCatalog
+  maxHistoryPerChannel: number
+}): UpdateDialogCatalog {
+  const channels = limitCatalogHistory(params.catalog, params.maxHistoryPerChannel)
+  const allReleases = sortReleases([...channels.stable, ...channels.preview])
+
+  const higherVersionRelease = allReleases.find(
+    (release) => compareVersions(release.version, params.currentVersion) > 0
+  )
+
+  const preferredCrossChannelRelease = allReleases.find(
+    (release) => release.channel !== params.currentChannel
+  )
+
+  return {
+    mode: 'admin',
+    recommendedRelease:
+      higherVersionRelease ??
+      preferredCrossChannelRelease ??
+      pickLatestRelease(channels[params.currentChannel]),
+    channels
+  }
+}

src/main/services/user/bip-users-dao.ts

@@ -139,7 +139,7 @@ export class BIPUsersDAO {
           return {
             id: row.ID as number,
             username: row.UserName as string,
-            userType: row.UserType as 'Admin' | 'User' | 'Guest'
+            userType: row.UserType as 'Admin' | 'User'
           }
         }
         return null
@@ -157,7 +157,7 @@ export class BIPUsersDAO {
           return {
             id: row.ID as number,
             username: row.UserName as string,
-            userType: row.UserType as 'Admin' | 'User' | 'Guest'
+            userType: row.UserType as 'Admin' | 'User'
           }
         }
         return null
@@ -198,7 +198,7 @@ export class BIPUsersDAO {
           return {
             id: row.ID as number,
             username: row.UserName as string,
-            userType: row.UserType as 'Admin' | 'User' | 'Guest'
+            userType: row.UserType as 'Admin' | 'User'
           }
         }
         return null
@@ -216,7 +216,7 @@ export class BIPUsersDAO {
           return {
             id: row.ID as number,
             username: row.UserName as string,
-            userType: row.UserType as 'Admin' | 'User' | 'Guest'
+            userType: row.UserType as 'Admin' | 'User'
           }
         }
         return null
@@ -254,7 +254,7 @@ export class BIPUsersDAO {
       return result.rows.map((row) => ({
         id: row.ID as number,
         username: row.UserName as string,
-        userType: row.UserType as 'Admin' | 'User' | 'Guest',
+        userType: row.UserType as 'Admin' | 'User',
         createTime: row.CreateTime as Date | undefined
       }))
     } catch (error) {
@@ -270,7 +270,7 @@ export class BIPUsersDAO {
    * Create a new user
    * @param username - The username (must be unique)
    * @param password - The password
-   * @param userType - User type ('Admin', 'User', or 'Guest')
+   * @param userType - User type ('Admin' or 'User')
    * @param computerName - Optional computer name for silent login
    * @returns True if successful
    */

src/main/services/user/migration/add-erp-params-migration.ts

@@ -11,14 +11,12 @@
  *   npx tsx src/main/services/user/migration/add-erp-params-migration.ts
  */
 
-import * as fs from 'fs'
 import * as path from 'path'
 import { fileURLToPath } from 'url'
 import { dirname } from 'path'
 import { ConfigManager } from '../../config/config-manager'
 import { MySqlService } from '../../database/mysql'
 import { SqlServerService } from '../../database/sql-server'
-import yaml from 'js-yaml'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -92,62 +90,6 @@ async function addColumnSqlServer(
   console.log(`  ✓ Added column ${columnName} (${columnType})`)
 }
 
-/**
- * Initialize ERP credentials for all users in MySQL
- */
-async function initializeErpCredentialsMySQL(
-  mysqlService: MySqlService,
-  tableName: string,
-  erpUrl: string,
-  erpUsername: string,
-  erpPassword: string
-): Promise<void> {
-  const result = await mysqlService.query(`SELECT COUNT(*) as count FROM ${tableName}`)
-  const userCount = result.rows[0]?.count as number
-
-  if (userCount === 0) {
-    console.log('No users found in BIPUsers table')
-    return
-  }
-
-  console.log(`Initializing ERP credentials for ${userCount} user(s)...`)
-
-  await mysqlService.query(
-    `UPDATE ${tableName} SET ERP_URL = ?, ERP_Username = ?, ERP_Password = ?`,
-    [erpUrl, erpUsername, erpPassword]
-  )
-
-  console.log('✓ ERP credentials initialized for all users')
-}
-
-/**
- * Initialize ERP credentials for all users in SQL Server
- */
-async function initializeErpCredentialsSqlServer(
-  sqlServerService: SqlServerService,
-  tableName: string,
-  erpUrl: string,
-  erpUsername: string,
-  erpPassword: string
-): Promise<void> {
-  const result = await sqlServerService.query(`SELECT COUNT(*) as count FROM ${tableName}`)
-  const userCount = result.rows[0]?.count as number
-
-  if (userCount === 0) {
-    console.log('No users found in BIPUsers table')
-    return
-  }
-
-  console.log(`Initializing ERP credentials for ${userCount} user(s)...`)
-
-  await sqlServerService.query(
-    `UPDATE ${tableName} SET ERP_URL = @p0, ERP_Username = @p1, ERP_Password = @p2`,
-    [erpUrl, erpUsername, erpPassword]
-  )
-
-  console.log('✓ ERP credentials initialized for all users')
-}
-
 /**
  * Run migration for MySQL
  */