166 lines
4.0 KiB
Markdown
166 lines
4.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件用于给 AI 编程代理提供本项目的最小必要指导。
|
||
目标不是替代 `README` 或 `docs/`，而是帮助代理快速理解项目结构、工作方式和关键约束。
|
||
|
||
## 项目概览
|
||
|
||
ERPAuto 是一个基于 Electron 的桌面应用，用于自动化处理 ERP 系统中的数据提取、清理、校验和配置管理。
|
||
|
||
技术栈：
|
||
|
||
- Electron 39
|
||
- React 19
|
||
- TypeScript 5.9
|
||
- electron-vite / Vite 7
|
||
- Playwright 1.58
|
||
- Vitest
|
||
|
||
## 常用命令
|
||
|
||
开发与构建：
|
||
|
||
```bash
|
||
npm run dev
|
||
npm run build
|
||
npm run build:win
|
||
```
|
||
|
||
质量检查：
|
||
|
||
```bash
|
||
npm run typecheck
|
||
npm run typecheck:node
|
||
npm run typecheck:web
|
||
npm run lint
|
||
npm run format
|
||
```
|
||
|
||
测试：
|
||
|
||
```bash
|
||
npm run test
|
||
npm run test:coverage
|
||
npm run test:e2e
|
||
```
|
||
|
||
发布：
|
||
|
||
```bash
|
||
npm run release:publish -- --channel stable
|
||
npm run release:publish -- --channel preview
|
||
```
|
||
|
||
详细发布流程见：
|
||
[docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
|
||
|
||
## 代码结构
|
||
|
||
### 主进程
|
||
|
||
- 路径：`src/main/`
|
||
- 入口：`src/main/index.ts`
|
||
- 职责：
|
||
- 应用生命周期管理
|
||
- 配置加载
|
||
- IPC 注册
|
||
- 更新服务初始化
|
||
|
||
### 预加载层
|
||
|
||
- 路径：`src/preload/`
|
||
- 职责：
|
||
- 暴露 `window.electron` API
|
||
- 作为 renderer 和 main 之间的安全桥
|
||
|
||
### 渲染进程
|
||
|
||
- 路径：`src/renderer/`
|
||
- 技术：React + TypeScript
|
||
- 特点：
|
||
- 通过 preload 暴露的 API 调用主进程
|
||
- 以登录状态和角色控制主要功能入口
|
||
|
||
### 服务层
|
||
|
||
主进程服务集中在 `src/main/services/`，按领域拆分：
|
||
|
||
- `erp/`：ERP 浏览器自动化
|
||
- `database/`：MySQL / SQL Server
|
||
- `user/`：登录、会话、用户切换
|
||
- `config/`：YAML 配置管理
|
||
- `update/`：便携版更新
|
||
- `excel/`：Excel 处理
|
||
|
||
## 关键事实
|
||
|
||
### 配置系统
|
||
|
||
- 使用 YAML 配置
|
||
- 模板文件：`config.template.yaml`
|
||
- 开发环境通常使用项目根目录下的 `config.yaml`
|
||
- 生产环境会将配置放到用户目录
|
||
|
||
### IPC 组织方式
|
||
|
||
- 所有 IPC handler 在 `src/main/ipc/`
|
||
- 每个领域一个 handler 模块
|
||
- 统一在 `src/main/ipc/index.ts` 注册
|
||
- channel 命名遵循 `domain:action`
|
||
|
||
### 认证与角色
|
||
|
||
当前主要角色是：
|
||
|
||
- `Admin`
|
||
- `User`
|
||
- `Guest`
|
||
|
||
登录流程支持：
|
||
|
||
- 静默登录
|
||
- 普通登录
|
||
- 管理员切换用户
|
||
|
||
### 便携版自动更新
|
||
|
||
项目已实现 Windows 便携版更新，关键点：
|
||
|
||
- 更新检查基于登录用户角色
|
||
- 支持 `stable` / `preview` 双通道
|
||
- `User` 只看 `stable`
|
||
- `Admin` 同时看 `stable` 和 `preview`
|
||
- 使用原生 `portable-updater.exe` 完成替换，不依赖 PowerShell
|
||
|
||
相关文档：
|
||
|
||
- [docs/portable-auto-update-architecture.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/portable-auto-update-architecture.md)
|
||
- [docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
|
||
|
||
## 代理工作约束
|
||
|
||
1. 优先修改现有文件，不要随意新建同类文件。
|
||
2. 变更前先理解对应模块的现有模式，尽量保持风格一致。
|
||
3. renderer 不要直接访问 Node/Electron 能力，统一走 preload。
|
||
4. 配置、IPC、类型定义通常需要同步更新，避免只改一层。
|
||
5. 涉及发布、更新、构建链路时，优先复用现有脚本，不要重复实现。
|
||
6. 涉及浏览器部署或更新流程时，先看 `docs/` 里的专题文档。
|
||
|
||
## 代理优先查看的文档
|
||
|
||
- [README.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/README.md)
|
||
- [docs/build-and-release-guide.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/build-and-release-guide.md)
|
||
- [docs/portable-auto-update-architecture.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/portable-auto-update-architecture.md)
|
||
- [docs/browser/PLAYWRIGHT_DEPLOYMENT.md](/d:/FileLib/Projects/CodeMigration/ERPAuto/docs/browser/PLAYWRIGHT_DEPLOYMENT.md)
|
||
|
||
## 不放在这里的内容
|
||
|
||
以下内容不应继续堆在本文件中：
|
||
|
||
- 详细用户使用说明
|
||
- 大段业务流程说明
|
||
- 重复的架构长文
|
||
- 版本发布记录
|
||
|
||
这些内容应继续放在 `README` 或 `docs/` 下的专题文档中。
|