my-mom-system/erp-frontend-vue

铭奕 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. 运行与构建

# 安装依赖
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 做按钮级权限控制

在组件中通过：

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 继续追加对应的小节，保持文档与实现同步更新。