hookehuyr

docs: 添加面向web-ele的改造说明文档

添加详细的README文档,说明基于Vben Admin的monorepo模板仓库改造指南。包含目录结构、启动链路、路由权限、接口请求、业务模块落地方式等核心内容,并提供实际改造建议顺序和客户列表示例模块的具体实现方式。
Showing 1 changed file with 96 additions and 0 deletions
1 +## 改造说明(面向 apps/web-ele)
2 +
3 +这是一个基于 Vben Admin(Element Plus 版本)的 monorepo 模板仓库。你已经删除了一部分不需要的功能后,下一步建议把“真实业务开发”需要的接入点理清,并落地一套最小业务模块骨架,后续所有业务都沿用同一套组织方式。
4 +
5 +### 你真正需要关心的目录
6 +
7 +- `apps/web-ele/`:Element Plus 版本前端应用(你主要改造的地方)
8 +- `apps/backend-mock/`:本地 mock 服务(仅开发用,生产请接真实后端)
9 +- `packages/`:框架能力与通用包(尽量别在这里写业务)
10 +
11 +### web-ele 启动链路与接入点
12 +
13 +- 应用入口:`apps/web-ele/src/main.ts``apps/web-ele/src/bootstrap.ts`
14 +- 全局样式:`apps/web-ele/src/bootstrap.ts` 中引入 `@vben/styles``@vben/styles/ele`
15 +- 组件适配:`apps/web-ele/src/adapter/`(表单、组件库、vxe-table 等适配层)
16 +- 全局配置覆盖:`apps/web-ele/src/preferences.ts`(建议在这里覆盖 `accessMode`、默认首页、刷新 token 等)
17 +- 状态管理:`apps/web-ele/src/store/`(业务 store 建议新建 `biz-*` 或按模块拆分)
18 +
19 +### 路由与权限的工作方式(你最需要先打通的)
20 +
21 +框架会在登录后,执行“权限守卫”来生成可访问的菜单与路由:
22 +
23 +- 路由入口:`apps/web-ele/src/router/index.ts`
24 +- 守卫逻辑:`apps/web-ele/src/router/guard.ts`
25 +- 生成菜单/路由:`apps/web-ele/src/router/access.ts`(内部会调用 `generateAccessible`
26 +- 本地路由模块:`apps/web-ele/src/router/routes/modules/` 下的 `*.ts` 会自动合并为动态路由
27 +
28 +你需要做的决策是:权限模式 `accessMode` 选哪个(在 `apps/web-ele/src/preferences.ts` 里覆盖)。
29 +
30 +- `frontend`:主要根据前端路由配置生成菜单,并结合角色/权限码控制访问
31 +- `backend`:主要依赖后端返回菜单数据,前端按约定把菜单转换成路由
32 +- `mixed`:两者混合
33 +
34 +相关思路可以参考官方文档:
35 +
36 +- 权限模式说明:https://doc.vben.pro/guide/in-depth/access.html
37 +- 路由和菜单说明:https://doc.vben.pro/guide/essentials/route.html
38 +
39 +### 接口请求(API)接入点
40 +
41 +- 请求封装:`apps/web-ele/src/api/request.ts`
42 +- API 入口聚合:`apps/web-ele/src/api/index.ts`
43 +- 现有核心 API:`apps/web-ele/src/api/core/*`
44 +
45 +建议你的业务 API 按模块分目录放在 `apps/web-ele/src/api/biz/*`,并统一从 `#/api` 导出,避免页面里散落相对路径导入。
46 +
47 +### 推荐的业务模块落地方式(统一套路)
48 +
49 +以“客户列表”为例(本次已新增完整示例):
50 +
51 +- 路由:`apps/web-ele/src/router/routes/modules/biz.ts`
52 +- 页面:`apps/web-ele/src/views/biz/customers/index.vue`
53 +- API:`apps/web-ele/src/api/biz/customers.ts`
54 +- mock 接口:`apps/backend-mock/api/biz/customers/list.ts`
55 +- 文案:`apps/web-ele/src/locales/langs/*/page.json`
56 +
57 +页面里通过 `listCustomersApi` 请求 `/biz/customers/list`,并使用 `params` 传分页/筛选条件。
58 +
59 +### 实际改造的建议顺序(最省心的一条路)
60 +
61 +1. 先把业务模块目录结构定下来(views/api/router 三件套),后续所有功能照着加
62 +2. 明确 `accessMode`,决定菜单由前端写死还是由后端驱动
63 +3. 把鉴权/登录态这条链路接到你的真实后端(替换 `apps/web-ele/src/api/core/*`
64 +4. 删除 demos 与无用模块(同时把路由模块文件删掉,避免菜单里残留入口)
65 +5. 按业务域拆 store、API、路由模块,形成稳定“可扩展骨架”
66 +
67 +### 客户列表示例模块的实际落地(可直接对照抄)
68 +
69 +#### 1) 路由如何挂载
70 +
71 +- 路由文件:`apps/web-ele/src/router/routes/modules/biz.ts`
72 +- 菜单标题:`meta.title` 推荐使用 i18n key(例如 `page.biz.customers`
73 +- 实战建议:业务模块统一挂到一个顶层路由(例如 `/biz`)下面,避免路由文件散落
74 +
75 +#### 2) 页面如何组织
76 +
77 +- 页面文件:`apps/web-ele/src/views/biz/customers/index.vue`
78 +- 页面职责:只负责“UI 交互 + 调用 API + 渲染数据”,不要在页面里写通用组件
79 +- 实战建议:把筛选条件、表格列配置等抽成局部常量,保持页面结构清晰
80 +
81 +#### 3) API 如何分层
82 +
83 +- API 文件:`apps/web-ele/src/api/biz/customers.ts`
84 +- 请求方式:统一走 `requestClient`,不要在业务代码里直接用 `fetch/axios`
85 +- 返回约定:建议业务层把后端返回统一成 `{ code, data, msg }`,页面只判断 `code === 1`
86 +
87 +#### 4) mock 如何与真实后端切换
88 +
89 +- mock 文件:`apps/backend-mock/api/biz/customers/list.ts`
90 +- 开发阶段:后端未就绪时先写 mock,前端联调通过后再切真实接口
91 +- 上线阶段:生产环境禁用 mock,只保留真实后端请求链路
92 +
93 +#### 5) 文案如何维护
94 +
95 +- 文案文件:`apps/web-ele/src/locales/langs/zh-CN/page.json``apps/web-ele/src/locales/langs/en-US/page.json`
96 +- 维护原则:路由/菜单只引用 key,不要在路由里写死中文
......