docs: update agent and release guides
This commit is contained in:
Misaka
214
CLAUDE.md
214
CLAUDE.md
@@ -1,141 +1,165 @@
|
|||||||
# CLAUDE.md
|
# 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
|
```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
|
```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
|
```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/` 下的专题文档中。
|
||||||
|
|||||||
199
docs/build-and-release-guide.md
Normal file
199
docs/build-and-release-guide.md
Normal file
@@ -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>
|
||||||
|
```
|
||||||
|
|
||||||
|
只有在排查问题或需要特殊处理时，再退回分步命令。
|
||||||
Reference in New Issue
Block a user