my-mom-system/erp-frontend-vue/README.md

# 铭奕 ERP 前端（erp-frontend-vue）

基于 **Vue 3 + TypeScript + Vite + Element Plus** 实现的 ERP Web 前端，覆盖主数据、销售、采购、生产计划、仓储、系统管理等业务模块。

本文档用于说明项目整体架构和约定，方便后续功能迭代、Bug 修复以及测试用例编写。

---

## 1. 技术栈与关键依赖

- **框架**：Vue 3（`<script setup>` 语法）
- **语言**：TypeScript（严格类型约束，配合 `vue-tsc` 做构建时类型检查）
- **构建工具**：Vite
- **UI 组件库**：Element Plus（含图标集 `@element-plus/icons-vue`）
- **路由**：Vue Router 4
- **HTTP 客户端**：Axios（统一封装在 `src/api/request.ts`）
- **测试**：Vitest + @vue/test-utils + jsdom

主要脚本（见 `package.json`）：

- `npm run dev`：启动开发服务器
- `npm run build`：先运行 `vue-tsc -b` 做类型检查，再用 Vite 打生产包
- `npm run preview`：预览生产构建
- `npm run test`：一次性运行所有 Vitest 用例
- `npm run test:watch`：watch 模式运行 Vitest

---

## 2. 目录结构概览

仅列出与前端业务开发关系最密切的部分：

- `src/main.ts`：应用入口，创建 Vue 应用，注册 Element Plus 图标，挂载路由与权限守卫
- `src/App.vue`：根组件
- `src/router/index.ts`：路由配置（按业务域划分路由树）
- `src/permission.ts`：路由前置守卫，处理登录校验、用户信息加载、白名单路由等
- `src/layout/`  
  - `index.vue`：主布局（侧边菜单 + 顶部导航 + 面包屑 + 内容区域）
- `src/stores/`  
  - `user.ts`：用户状态与权限校验（登录、退出、获取用户信息等）
- `src/api/`  
  - `request.ts`：Axios 实例及请求/响应拦截器
  - 业务 API 模块（每个文件对应一个业务域，内部定义 TypeScript 接口与请求方法），例如：
    - `auth.ts`：认证登录/获取用户信息
    - `productionPlan.ts`：生产计划单
    - `mbom.ts`：物料清单 / MRP
    - `purchasePlan.ts`：采购计划
    - `purchaseOrder.ts`：采购订单
    - `salesOrder.ts`：销售订单
    - `deliver.ts` / `invoice.ts` / `saleback.ts`：销售相关单据
    - `masterdata/*`：物料、计量单位、车间、工作站等主数据
    - `system/*`：组织架构（部门、岗位、角色、用户）
    - `warehouse/*`：生产领料相关接口
    - `rd/ebom.ts`：研发 BOM
- `src/views/`：按业务域划分的页面组件
  - `MasterData/`：主数据
  - `Sales/`：销售管理与销售报表
  - `Purchasing/`：采购管理与采购报表
  - `Production/`：生产计划、MBOM/MRP、采购计划、生产报表
  - `Warehouse/Issue/`：生产领料单
  - `RD/Ebom/`：研发 EBOM
  - `System/`：用户、角色、部门、岗位
  - 每个业务通常使用：
    - `index.vue`：列表/查询页
    - `form.vue`：单据编辑/查看页
- `src/utils/`：通用工具（如 token 存取等）

---

## 3. 运行与构建

```bash
# 安装依赖
npm install

# 开发调试
npm run dev

# 类型检查 + 构建生产包
npm run build

# 本地预览生产包
npm run preview

# 运行单元测试
npm run test
```

> 建议在提交代码前至少保证 `npm run build` 通过，以防止 TypeScript 类型错误和明显的构建问题进入主分支。

---

## 4. 前端架构设计

### 4.1 路由与布局

- 路由配置集中在 `src/router/index.ts`，采用**按业务域分组**的嵌套路由结构：
  - `/sales/*`：销售管理模块
  - `/purchasing/*`：采购管理模块
  - `/production/*`：生产计划模块
  - `/masterdata/*`：主数据维护
  - `/system/*`：系统管理
  - `/warehouse/*`：仓储/生产领料
  - `/rd/*`：研发
- 所有业务路由均以 `Layout` 作为父路由，实现统一的侧边菜单 + 顶部导航 + 面包屑结构。
- 每个路由都带有 `meta.title`，用于：
  - 页面标题（`permission.ts` 中设置 `document.title`）
  - 面包屑显示
  - 侧边菜单高亮匹配

### 4.2 权限与认证流程

相关文件：

- `src/stores/user.ts`：维护用户 token、基本信息、角色、权限等
- `src/utils/auth.ts`：token 的本地存储读写
- `src/api/auth.ts`：登录、获取用户信息、注销
- `src/permission.ts`：全局路由守卫

核心逻辑：

1. 路由进入前，`permission.ts` 会检查：
   - 当前是否在白名单（如 `/login` 等）
   - 本地是否存在 token
2. 若有 token 但 `userStore.state.userInfo.roles` 为空，则会调用 `userStore.getUserInfo()` 拉取用户信息。
3. 若认证失败或接口错误，会调用 `fedLogout` 清理本地状态，并跳转登录页。
4. 在开发模式下支持 `DEV_SKIP_AUTH`（通过 `import.meta.env` 控制），方便后端未就绪时调试页面。

### 4.3 API 封装与数据访问

统一入口：`src/api/request.ts`

- 使用 Axios 创建单例 `request`，通过请求拦截器自动处理：
  - 按 URL 前缀自动拼接 `/erp`、`/mes`、`/system` 等前缀
  - 附加 `Authorization: Bearer <token>` 头
- 响应拦截器统一处理：
  - `code === 401`：弹出重新登录提示，清理 token 并跳转登录
  - 其他非 200 code：使用 `ElMessage.error` 提示
  - 成功时统一返回包裹后的 `res` 对象（通常包含 `data`、`rows`、`total` 等）

业务 API 模块模式（以 `src/api/productionPlan.ts` 为例）：

- 在文件顶部定义接口类型，如 `ProductionPlan`、`PlanLine` 等。
- 导出对应的请求方法：
  - `getProductionPlanList(params: PlanQuery)`
  - `createProductionPlan(data: Partial<ProductionPlan>)`
  - `approveProductionPlan(planId: number)` 等。
- 列表接口通常约定返回 `{ rows: T[]; total: number }` 结构，方便列表分页展示。

> **建议**：新增接口时先定义好 TypeScript 接口类型，再在页面组件中通过 `type Xxx` 引用，保持前后端字段的一致性与可维护性。

### 4.4 状态管理

当前项目使用 **轻量级的自实现 store**（并未引入 Pinia/Vuex），例如：

- `src/stores/user.ts` 使用 `reactive` 维护用户状态，并暴露：
  - `loginAction` / `logoutAction` / `getUserInfo`
  - `hasRole`、`hasPermission` 做按钮级权限控制

在组件中通过：

```ts
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
```

来访问和修改全局用户状态。

### 4.5 业务模块划分

按典型业务流程进行模块化：

- **主数据（MasterData）**：物料、分类、计量单位、车间/工作站等基础资料。
- **销售（Sales）**：客户、销售订单、发货通知单、开票结算单、退货通知单以及相关报表。
- **采购（Purchasing）**：供应商、采购订单、到货单、发票、退货及采购执行报表。
- **生产（Production）**：生产计划单、MBOM/MRP 运算、采购计划及生产执行报表。
- **仓储/生产领料（Warehouse/Issue）**：工单领料单及出库明细。
- **研发（RD/Ebom）**：工程 BOM（EBOM）维护。
- **系统管理（System）**：用户、角色、部门、岗位等组织架构。

各模块页面组件基本遵循：

- `index.vue`：列表、搜索、分页、批量操作
- `form.vue`：单据新增/编辑/查看（通常由路由 `new` / `edit/:id` / `view/:id` 复用）

---

## 5. 开发约定与最佳实践

1. **类型优先**
   - 所有接口数据结构优先在 `src/api/*` 中通过 `interface`/`type` 定义。
   - 组件中通过 `import type Xxx from '@/api/xxx'` 复用类型，避免魔法字符串和隐式 `any`。

2. **单据模式一致**
   - 列表页负责查询、分页、批量操作。
   - 单据表单页负责单据的增删改查、审批、导出、引入等。
   - 路由命名尽量统一（如 `XxxList`、`XxxNew`、`XxxEdit`、`XxxView`）。

3. **API 调用约定**
   - 列表类：`getXxxList(params)` / `getXxxDocList(params)` / `getXxxSummary(params)`。
   - 单据类：`getXxx(id)` / `createXxx(data)` / `updateXxx(data)` / `deleteXxx(id)` / `approveXxx(id)`。
   - 导出类：`exportXxx(params)` 返回 `Blob`，前端统一通过 `URL.createObjectURL` 下载。

4. **错误处理**
   - 全局拦截器负责大部分 HTTP 错误提示。
   - 业务逻辑错误（如必填字段缺失、状态不允许操作）应在组件内通过 `ElMessage` 或 `ElMessageBox` 友好提示。

5. **国际化与文案**
   - 当前以中文为主，业务文案尽量统一、简洁。
   - 后续如需多语言，可在布局和组件中收口文案位置，方便替换。

---

## 6. 新功能迭代指南

以新增一个简单业务模块为例，推荐步骤如下：

1. **定义后端接口与数据结构**
   - 与后端约定好 URL、请求方式以及返回结构。
   - 在 `src/api/<module>.ts` 中新增对应的接口类型定义与请求函数。

2. **新增页面组件**
   - 在 `src/views/<Module>/<Feature>/` 下创建：
     - `index.vue`：列表页
     - `form.vue`：单据表单页（可根据是否需要拆分为 new/edit/view 来复用）
   - 使用 `<script setup lang="ts">`，并引入上一步定义的类型。

3. **注册路由**
   - 在 `src/router/index.ts` 中对应业务分组下新增子路由：
     - 列表：`/module/feature`
     - 新增：`/module/feature/new`
     - 编辑：`/module/feature/edit/:id`
     - 查看：`/module/feature/view/:id`
   - 配置好 `name` 和 `meta.title`，以便面包屑与标题显示。

4. **加入侧边菜单**
   - 在 `src/layout/index.vue` 左侧菜单中增加对应菜单项，index 与路由 path 对齐。

5. **权限控制（如需要）**
   - 后端返回对应的角色/权限字符串。
   - 在前端根据 `userStore.hasRole` / `hasPermission` 决定是否展示按钮或入口。

6. **编写/更新测试**
   - 对复杂的计算逻辑或数据加工函数，建议抽到独立模块并使用 Vitest 编写单元测试。
   - 对关键表单组件或流程，使用 `@vue/test-utils` + Vitest 编写基础渲染和交互用例。

7. **自测与提交**
   - 运行 `npm run dev` 手动验证主要流程。
   - 运行 `npm run test` 和 `npm run build` 确认无测试失败与类型错误。

---

## 7. Bug 修复与调试建议

1. **快速定位问题**
   - TS 编译错误：优先通过 `npm run build` 或 `vue-tsc -b` 定位。
   - 运行时错误：查看浏览器控制台和网络请求（Network）日志。

2. **保持类型一致**
   - 修复字段名或结构变更时，同步更新：
     - 对应的 API 接口类型定义（`src/api/*`）
     - 所有使用该类型的组件

3. **避免静默失败**
   - catch 到错误时，优先使用 `ElMessage.error` 告知用户（同时 `console.error` 方便开发排查）。

4. **回归检查**
   - 对涉及核心单据（生产计划、采购计划、销售订单、领料单等）的改动，建议：
     - 至少完成一次完整的“从主数据 → 业务单据 → 报表/导出”的端到端手工验证。
     - 补充或更新相应的单元测试。

---

## 8. 测试用例编写建议

项目已集成 Vitest 与 Vue Test Utils，可按以下思路补充测试：

1. **纯逻辑/工具函数**
   - 放在独立的 `utils` 或 `helpers` 文件中。
   - 使用 Vitest 编写函数级单元测试，覆盖数字计算、状态映射等逻辑。

2. **API 封装**
   - 使用 Vitest 的 mocking 能力（如 `vi.mock('axios')`）对 API 模块进行单元测试，确保在不同返回结构下都有正确行为。

3. **组件/页面**
   - 使用 `@vue/test-utils` 挂载组件，测试：
     - 基本渲染是否正常（必需字段/按钮是否存在）
     - 关键交互（点击按钮后是否发出预期事件或调用 API）
     - 表单校验逻辑（缺失必填项时是否提示）

4. **回归测试**
   - 对已修复的 Bug，尽量补一条对应的测试用例，避免同类问题再次出现。

---

如需在后续迭代中扩展架构（例如引入 Pinia、国际化、多布局支持等），可以在本 README 继续追加对应的小节，保持文档与实现同步更新。