Hooke / vben-admin

改造说明（面向 apps/web-ele）

这是一个基于 Vben Admin（Element Plus 版本）的 monorepo 模板仓库。你已经删除了一部分不需要的功能后，下一步建议把“真实业务开发”需要的接入点理清，并落地一套最小业务模块骨架，后续所有业务都沿用同一套组织方式。

你真正需要关心的目录

• apps/web-ele/：Element Plus 版本前端应用（你主要改造的地方）
• apps/backend-mock/：本地 mock 服务（仅开发用，生产请接真实后端）
• packages/：框架能力与通用包（尽量别在这里写业务）

web-ele 启动链路与接入点

• 应用入口：apps/web-ele/src/main.ts → apps/web-ele/src/bootstrap.ts
• 全局样式：apps/web-ele/src/bootstrap.ts 中引入 @vben/styles 与 @vben/styles/ele
• 组件适配：apps/web-ele/src/adapter/（表单、组件库、vxe-table 等适配层）
• 全局配置覆盖：apps/web-ele/src/preferences.ts（建议在这里覆盖 accessMode、默认首页、刷新 token 等）
• 状态管理：apps/web-ele/src/store/（业务 store 建议新建 biz-* 或按模块拆分）

路由与权限的工作方式（你最需要先打通的）

框架会在登录后，执行“权限守卫”来生成可访问的菜单与路由：

• 路由入口：apps/web-ele/src/router/index.ts
• 守卫逻辑：apps/web-ele/src/router/guard.ts
• 生成菜单/路由：apps/web-ele/src/router/access.ts（内部会调用 generateAccessible）
• 本地路由模块：apps/web-ele/src/router/routes/modules/ 下的 *.ts 会自动合并为动态路由

你需要做的决策是：权限模式 accessMode 选哪个（在 apps/web-ele/src/preferences.ts 里覆盖）。

• frontend：主要根据前端路由配置生成菜单，并结合角色/权限码控制访问
• backend：主要依赖后端返回菜单数据，前端按约定把菜单转换成路由
• mixed：两者混合

相关思路可以参考官方文档：

• 权限模式说明：https://doc.vben.pro/guide/in-depth/access.html
• 路由和菜单说明：https://doc.vben.pro/guide/essentials/route.html

接口请求（API）接入点

• 请求封装：apps/web-ele/src/api/request.ts
• API 入口聚合：apps/web-ele/src/api/index.ts
• 现有核心 API：apps/web-ele/src/api/core/*

建议你的业务 API 按模块分目录放在 apps/web-ele/src/api/biz/*，并统一从 #/api 导出，避免页面里散落相对路径导入。

推荐的业务模块落地方式（统一套路）

以“客户列表”为例（本次已新增完整示例）：

• 路由：apps/web-ele/src/router/routes/modules/biz.ts
• 页面：apps/web-ele/src/views/biz/customers/index.vue
• API：apps/web-ele/src/api/biz/customers.ts
• mock 接口：apps/backend-mock/api/biz/customers/list.ts
• 文案：apps/web-ele/src/locales/langs/*/page.json

页面里通过 listCustomersApi 请求 /biz/customers/list，并使用 params 传分页/筛选条件。

实际改造的建议顺序（最省心的一条路）

1. 先把业务模块目录结构定下来（views/api/router 三件套），后续所有功能照着加
2. 明确 accessMode，决定菜单由前端写死还是由后端驱动
3. 把鉴权/登录态这条链路接到你的真实后端（替换 apps/web-ele/src/api/core/*）
4. 删除 demos 与无用模块（同时把路由模块文件删掉，避免菜单里残留入口）
5. 按业务域拆 store、API、路由模块，形成稳定“可扩展骨架”

客户列表示例模块的实际落地（可直接对照抄）

1) 路由如何挂载

• 路由文件：apps/web-ele/src/router/routes/modules/biz.ts
• 菜单标题：meta.title 推荐使用 i18n key（例如 page.biz.customers）
• 实战建议：业务模块统一挂到一个顶层路由（例如 /biz）下面，避免路由文件散落

2) 页面如何组织

• 页面文件：apps/web-ele/src/views/biz/customers/index.vue
• 页面职责：只负责“UI 交互 + 调用 API + 渲染数据”，不要在页面里写通用组件
• 实战建议：把筛选条件、表格列配置等抽成局部常量，保持页面结构清晰

3) API 如何分层

• API 文件：apps/web-ele/src/api/biz/customers.ts
• 请求方式：统一走 requestClient，不要在业务代码里直接用 fetch/axios
• 返回约定：建议业务层把后端返回统一成 { code, data, msg }，页面只判断 code === 1

4) mock 如何与真实后端切换

• mock 文件：apps/backend-mock/api/biz/customers/list.ts
• 开发阶段：后端未就绪时先写 mock，前端联调通过后再切真实接口
• 上线阶段：生产环境禁用 mock，只保留真实后端请求链路

5) 文案如何维护

• 文案文件：apps/web-ele/src/locales/langs/zh-CN/page.json、apps/web-ele/src/locales/langs/en-US/page.json
• 维护原则：路由/菜单只引用 key，不要在路由里写死中文