hookehuyr

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

添加详细的README文档,说明基于Vben Admin的monorepo模板仓库改造指南。包含目录结构、启动链路、路由权限、接口请求、业务模块落地方式等核心内容,并提供实际改造建议顺序和客户列表示例模块的具体实现方式。
Showing 1 changed file with 96 additions and 0 deletions
## 改造说明(面向 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,不要在路由里写死中文
......