BIPMaterialManager/docs/internal/optimization-execution-plan.md

ERPAuto 优化执行计划文档

基于《ERPAuto 优化建议与规范指南》，本文档规划了具体的分阶段重构与优化执行步骤。每个阶段遵循“渐进式重构”原则，保证在优化期间项目依然可运行、可测试。

阶段一：基础设施建设 (Error & Logging)

在进行大规模业务逻辑重构前，首先建立坚实的基础设施，以便后续问题排查与数据追踪。

1. 引入并配置统一日志库
   • 目标: 替换分散的 console.log。
   • 执行:
     • 安装 winston (针对 Node.js 主进程)。
     • 在 src/main/services/logger 创建单例日志记录器。
     • 配置双通道输出：Console (Dev 环境) 与 File (生产环境按天切割，如 %AppData%/ERPAuto/logs/app-%DATE%.log)。
2. 定义全局错误类型与 IPC 拦截器
   • 目标: 规范前后端错误抛出与展示体系。
   • 执行:
     • 在 src/main/types/errors.ts 定义 BaseError, ErpConnectionError, DatabaseQueryError。
     • 在 src/main/ipc/index.ts 中封装高阶函数 withErrorHandling。所有 IPC Handler 统一用此高阶函数包裹，将捕获的错误统一转为 { success: false, error: string, code: string } 结构。

阶段二：数据层抽象与 ORM 改造

彻底解决 SQL 语句散落和不同数据库适配成本高的问题。

1. 选型并引入 ORM
   • 目标: 弃用原生 SQL 拼接。
   • 执行:
     • 引入 Prisma 或 TypeORM。结合当前多数据源 (MySQL + SQL Server) 需求，推荐 TypeORM 因为其在运行时切换数据源更为灵活。
2. 创建 Repository 抽象
   • 目标: 隔离数据库实现细节。
   • 执行:
     • 建立 src/main/services/database/repositories 目录。
     • 为业务实体 (如 Users, ExtractedPlans 等) 编写 Repository 类接口。
     • 将原有 mysql2 和 mssql 的调用逐步迁移至 Repository 中。
3. Zod 运行时校验
   • 目标: 保护 IPC 边界免受恶意/格式错误的 payload 影响。
   • 执行:
     • 安装 zod。
     • 对所有的 IPC Handler 的入参（如 ExtractorInput, LoginRequest）添加 zod Schema 校验。

阶段三：React 渲染层规范化

提高前端代码复用率，解耦视图与逻辑。

1. 提取 IPC Hooks
   • 目标: 清理组件中的大段异步调用。
   • 执行:
     • 在 src/renderer/src/hooks 创建 useExtractor.ts, useCleaner.ts。
     • 使用 React 的 useState 包装 window.api 调用，返回 { loading, data, error, execute }。
2. 状态管理引入 (Zustand)
   • 目标: 解决跨组件状态共享 (如全局报错信息、用户认证状态)。
   • 执行:
     • 安装 zustand。
     • 创建 useUserStore 和 useAppStore。
3. UI 组件库/公共样式提取
   • 目标: 统一 Tailwind 设计语言。
   • 执行:
     • 将高频使用的 Button, Input, Modal 抽取到 src/renderer/src/components/ui/。

阶段四：自动化服务解耦 (Domain Logic)

将基于 Playwright 的具体执行细节与业务调度逻辑分离。

1. 重构 ERP 自动化服务 (cleaner.ts / extractor.ts)
   • 目标: 遵循单一职责原则。
   • 执行:
     • 抽象出 ErpBrowserManager (负责浏览器启动与资源回收)。
     • 抽象出 ErpAuthService (专职处理登录和 Session)。
     • extractor.ts 将只负责调度：调用 Browser -> Auth -> Navigate -> Download -> Excel Parse。
2. 加强 TypeScript 严格模式
   • 目标: 提升代码健壮性。
   • 执行:
     • 开启 tsconfig.json 中的 "strict": true 和 "noImplicitAny": true。
     • 全局清理并替换现存的 any 为具体的 Type 或 unknown 并添加类型保护。

阶段五：测试覆盖率补充

确保核心流程不被破坏。

1. 补充关键服务的单元测试
   • 目标: 防止复杂转换逻辑衰退。
   • 执行:
     • 使用 Vitest 测试所有的 Repository (使用内存数据库/Mock) 和工具函数 (如 ExcelParser)。
2. 核心业务 E2E 测试
   • 目标: 确保 IPC 及 Electron 整体运行顺畅。
   • 执行:
     • 使用 Playwright 针对 Electron 的测试框架 (@playwright/test 的 electron 插件) 编写主流程测试：登录 -> 点击提取 -> 验证本地结果文件生成。

执行建议与回顾

• 每个阶段应作为一个单独的 Git 分支 (Feature Branch) 开发。
• 完成一个阶段后，必须全量运行既有的测试套件并通过 npm run typecheck。
• 本文档可作为每次 PR Review 的检查清单使用。