Imported from Aliax-LI/kuaimai-erp-toolkit (AGENTS.md). Install upstream with npx skills add Aliax-LI/kuaimai-erp-toolkit. Copyright stays with the author.

快麦 ERP 桌面小工具

定义 技术框架、目录、UI 布局、数据存储、配置、打包 六类规范。业务细节见各工具 PRD 与 docs/superpowers/specs/。

1. 技术框架

架构

Renderer（React）→ preload（contextBridge）→ Main（Node）→ Core / Tools（纯 TS）

• 三进程：main / preload / renderer 分离编译。
• 构建：Vite 分别使用 vite.main.config.ts、vite.preload.config.ts、vite.renderer.config.ts。
• 安装包：electron-builder，配置位于 package.json 的 build 字段。
• 渲染进程：contextIsolation: true，nodeIntegration: false，sandbox: true。
• 特权能力（文件、网络、存储）仅主进程；渲染进程经 preload 窄接口 IPC 访问。

技术选型

命令

pnpm install
pnpm start                    # 开发预览：先构建，再启动 Electron
pnpm run typecheck
pnpm run test
pnpm run package              # 仅生成目录版应用，不生成安装包
pnpm run make                 # 生成当前平台安装包
pnpm run make:win             # Windows NSIS 安装包
pnpm run make:mac             # macOS arm64 dmg + zip，必须在 macOS 上执行
pnpm run make:mac:x64         # macOS x64 dmg + zip
pnpm run make:mac:universal   # macOS universal dmg + zip
pnpm run make:linux           # Linux deb + rpm

2. 目录规范

kuaimai-erp-toolkit/
├── package.json、pnpm-workspace.yaml、tsconfig.json
├── vite.main.config.ts、vite.preload.config.ts、vite.renderer.config.ts
├── resources/           # 应用图标（icon.svg → png / ico / icns）
├── docs/、scripts/、tests/
└── src/
    ├── main/            index.ts、ipc/、services/、windows/
    ├── preload/         index.ts、api.d.ts、apis/
    ├── renderer/        pages/、routes/、components/、hooks/、tools/<tool-id>/
    ├── shared/          types/、constants/、schemas/、ipc-channels.ts
    ├── core/            通用纯 TS
    └── tools/<tool-id>/ 工具业务逻辑

后端逻辑封装（IPC / API）

Renderer  →  window.kuaimai.*  →  preload/apis/  →  main/ipc/  →  main/services/  →  core/ | tools/

新增能力按域拆分：先 shared 定 channel 与类型 → core / tools 写逻辑 → main/services + main/ipc → preload/apis → build-api.ts 汇总。渲染进程只调 window.kuaimai，禁止直接 fs/网络/读 secrets。

3. UI 布局规范

设计体系

• 组件：自定义 primitives + components/shared/；图标：lucide-react；字体：Noto Sans SC。
• 仅浅色暖色主题（cream / amber / charcoal）；无暗色切换。
• 无登录页：启动直达工作台；侧栏无用户头像、登录/退出。

应用骨架（强制：顶栏 + 侧栏 + 主区）

┌─────────────────────────────────────────────────────────────┐
│ Logo + 标题                              [连接状态 · 只读]   │  Header h-14
├──────────┬──────────────────────────────────────────────────┤
│ ● 工作台 │                                                  │
│ ● 历史记录│           PageContent（max-w-6xl 居中）            │
│ ● 配置管理│                                                  │
│ v2.0     │                                                  │
└──────────┴──────────────────────────────────────────────────┘
  Sidebar（188px）          Main（flex-1，overflow-y-auto）

PageContent 常用模式：

• 最小窗口 1024 × 640；侧栏始终可见，不得完全隐藏。

导航与路由（强制项）

4. 数据存储规范

根路径：app.getPath('userData')，禁止写入安装目录或源码目录。

userData/
├── store.json                    # 全局配置（敏感字段加密）
├── jobs/sku-import/<uuid>.json   # 建货号任务快照
├── config/<tool-id>/             # 工具业务配置 JSON
├── logs/                         # JSONL，按日滚动
└── cache/                        # 临时文件，可清理

5. 配置规范

interface AppSettings {
  theme: 'light' | 'dark' | 'system';
  locale: 'zh-CN';
  erpBaseUrl: string; // 默认 https://erp.superboss.cc
}

• 读写统一经 main/services/store.ts；ERP 请求配置见 main/services/erp-web.ts（getErpWebConfig）。
• schema 定义于 shared/schemas/store.ts，损坏回退默认并 .bak 备份。
• Electron 运行时不读根目录 .env；.env 只供 CLI / smoke 脚本使用。

6. 打包与图标

• 图标源文件：resources/icon.svg。
• pnpm run icons:generate 或 scripts/build-app.mjs 会生成 resources/icon.png、resources/icon.ico、resources/icon.icns。
• package.json 的 build 字段是安装包唯一配置源。
• 构建输出：
  • .vite/build/：main / preload 产物。
  • .vite/renderer/main_window/：renderer 产物。
  • out/make/：electron-builder 打包产物。
• 平台建议：
  • Windows NSIS：Windows CI。
  • macOS dmg / zip：macOS CI；对外分发建议配置 Developer ID 签名与 notarization。
  • Linux deb / rpm：Linux CI。
• 项目代码由 Vite 打包进产物。除非明确需要运行时动态加载包，否则不要把业务依赖移回 dependencies；新增动态运行时依赖时必须同步检查 electron-builder 的 files 配置。