BLD-ERPAuto/BIPMaterialManager

Fork 0

Files

Misaka 180f4aab0a docs: add developer guides

2026-03-21 20:48:09 +08:00

3.1 KiB

Raw Blame History

本地开发指南

本文档说明如何在本地启动、检查、构建和验证项目。

1. 开发环境概览

flowchart LR
    Clone[拉取代码]
    Install[安装依赖]
    Config[准备配置]
    Dev[启动开发环境]
    Verify[类型检查 / lint / 测试]

    Clone --> Install --> Config --> Dev --> Verify

2. 基础要求

Node.js >= 18
npm >= 9
本地可访问 ERP 系统
可访问 MySQL 或 SQL Server

3. 安装依赖

npm install

4. 准备配置

项目使用 config.yaml 作为主配置文件。

graph TD
    Config[config.yaml]
    ERP[ERP URL]
    DB[数据库配置]
    Update[更新配置]
    Paths[路径配置]

    Config --> ERP
    Config --> DB
    Config --> Update
    Config --> Paths

至少要确认这些配置可用：

ERP URL
当前使用的数据库类型
数据库连接信息

说明：

ERP 用户名和密码不是放在 config.yaml
这部分在应用设置页中按用户存储

5. 启动开发环境

npm run dev

开发启动链路如下：

sequenceDiagram
    participant Dev as npm run dev
    participant Vite as electron-vite
    participant Main as main process
    participant Preload as preload build
    participant Renderer as renderer dev server

    Dev->>Vite: electron-vite dev
    Vite->>Main: build main
    Vite->>Preload: build preload
    Vite->>Renderer: start renderer dev server
    Vite->>Main: launch electron

6. 常用开发命令

# 启动开发环境
npm run dev

# 类型检查
npm run typecheck

# 代码格式化
npm run format

# lint
npm run lint

# 单测
npm run test:run

# E2E
npm run test:e2e

7. 构建命令

当前正式维护的是 Windows 构建链路。

# 常规构建
npm run build

# Windows 安装版
npm run build:win

# 仅生成 unpack 目录
npm run build:unpack

构建路径如下：

flowchart TD
    Build[build]
    Typecheck[typecheck]
    ElectronVite[electron-vite build]
    Updater[build:updater]
    Builder[electron-builder]

    Build --> Typecheck
    Build --> ElectronVite
    Build --> Updater
    Build --> Builder

8. 日常验证建议

修改代码后，建议至少跑：

npm run typecheck
npx eslint <changed files>

如果改到关键主链路，再补：

npx vitest run <related tests>

9. 常见本地问题

9.1 `npm run dev` 无法启动

优先检查：

config.yaml 是否存在
数据库配置是否正确
当前终端里是否残留异常环境变量

9.2 类型检查失败

flowchart TD
    TypeError[类型错误]
    Main{node 还是 web}
    Node[node tsconfig]
    Web[web tsconfig]
    Fix[修正类型引用边界]

    TypeError --> Main
    Main --> Node
    Main --> Web
    Node --> Fix
    Web --> Fix

9.3 ERP 登录相关问题