From c8ce67dc75686d91c63ff86acbc2675fad4cdde5 Mon Sep 17 00:00:00 2001 From: Misaka Date: Fri, 20 Mar 2026 23:15:41 +0800 Subject: [PATCH] docs: update agent and release guides --- CLAUDE.md | 214 ++++++++++++++++++-------------- docs/build-and-release-guide.md | 199 +++++++++++++++++++++++++++++ 2 files changed, 318 insertions(+), 95 deletions(-) create mode 100644 docs/build-and-release-guide.md diff --git a/CLAUDE.md b/CLAUDE.md index 87cb544..62311f5 100644 --- a/CLAUDE.md +++ b/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 build # Full build with type checking -npm run build:win # Build Windows executable +npm run dev +npm run build +npm run build:win ``` -### Code Quality +质量检查： ```bash -npm run lint # ESLint check -npm run format # Prettier format -npm run typecheck # TypeScript check (both main and renderer) -npm run typecheck:node # TypeScript check for main process only -npm run typecheck:web # TypeScript check for renderer only +npm run typecheck +npm run typecheck:node +npm run typecheck:web +npm run lint +npm run format ``` -### Testing +测试： ```bash -npm run test # Run unit tests (Vitest) -npm run test:coverage # Run tests with coverage report -npm run test:e2e # Run E2E tests (Playwright) -npm run test:e2e:ui # Run E2E tests with UI -npm run test:e2e:report # Show E2E test report +npm run test +npm run test:coverage +npm run test:e2e ``` -## 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/`) - - React 19 + TypeScript UI - - Uses exposed preload APIs for all main process communication - - Authentication-based routing with role-based access control +- 路径：`src/main/` +- 入口：`src/main/index.ts` +- 职责： + - 应用生命周期管理 + - 配置加载 + - 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 - - `MySqlService` / `mysql.ts` - MySQL operations - - `SqlServerService` / `sql-server.ts` - SQL Server operations - - DAO pattern: `discrete-material-plan-dao.ts`, `materials-to-be-deleted-dao.ts` +- 路径：`src/renderer/` +- 技术：React + TypeScript +- 特点： + - 通过 preload 暴露的 API 调用主进程 + - 以登录状态和角色控制主要功能入口 -- **User Services** (`services/user/`): Authentication and session management - - `BipUsersDao` - User data access - - `SessionManager` - Active session tracking +### 服务层 -- **Other Services**: - - `config/` - Configuration management - - `excel/` - Excel file parsing +主进程服务集中在 `src/main/services/`，按领域拆分： -### 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 -2. **Fallback**: Shows login dialog if silent login fails -3. **Admin User Selection**: Admin users can switch to other user accounts -4. **Session Management**: Persistent sessions with role-based permissions (Admin/User/Guest) +- 所有 IPC handler 在 `src/main/ipc/` +- 每个领域一个 handler 模块 +- 统一在 `src/main/ipc/index.ts` 注册 +- 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) -- Types are co-located with features: `src/main/types/` contains domain-specific type definitions -- The preload script exposes a typed API surface that's available in renderer +- `Admin` +- `User` +- `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) -- **Database**: MySQL and SQL Server connection configs (dual support) -- **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 +- [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) -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 -- **Playwright 1.58** - Browser automation for ERP interaction -- **electron-vite + Vite 7** - Build tooling -- **Zod** - Runtime validation -- **Vitest** - Unit tests -- **Playwright Test** - E2E tests +## 代理优先查看的文档 + +- [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/` 下的专题文档中。 diff --git a/docs/build-and-release-guide.md b/docs/build-and-release-guide.md new file mode 100644 index 0000000..4584bdf --- /dev/null +++ b/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/-rebuild.md` +2. 如果不存在，再查找 `docs/releases/.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//artifacts/...` +- `release-output/updates/win-portable//changelogs/...` +- `release-output/updates/win-portable//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--stable-portable.exe +│ ├── changelogs/ +│ │ └── .md +│ └── index.json +└── preview/ + ├── artifacts/ + │ └── erpauto--preview-portable.exe + ├── changelogs/ + │ └── .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 +``` + +只有在排查问题或需要特殊处理时，再退回分步命令。