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,不要在路由里写死中文 | ... | ... |
-
Please register or login to post a comment