# 说明文档 ## 一、业务项目目录 从 `mode` 模板复制一份就是业务项目,结构如下。`★` 是日常要动的目录。 ``` 业务项目/ ├─ index.html # 只改了 title 注入,一般不动 ├─ vite.config.js # 端口、代理、别名、dedupe(见 05-工具配置文档) ├─ .env / .env.development / .env.production ├─ src/ │ ├─ main.js # 入口:注册基座 + 页面 glob,不动 │ ├─ App.vue # 根组件,不动 │ ├─ assets/main.less # 全局样式变量,可按需加 │ ├─ config/ │ │ ├─ web-config.js # 运行时可改的配置(会被打进 config.json) │ │ └─ app-config.js # 构建期配置:覆盖登录页/首页、静态路由、语言包 │ ├─ router/page-entries.js # 老项目兼容用的页面登记表,新项目留空 │ ├─ locales/components/i18n.js # 公共词条(按钮名等),靠基座 components 命名空间兜底 │ ├─ api/ ★ 接口层,按后端模块建文件 │ └─ views/ ★ 页面层 │ └─ <模块>/<页面>/index.vue └─ refresh-mode.ps1 / refresh-build.ps1 # 基座更新后重新拉依赖再起服务 ``` ## 二、页面怎么被路由到 启动链路:`main.js` 用 `import.meta.glob('@/views/**/*.vue')` 收集所有页面 → 交给基座 → 基座按**后端菜单的 `hrefs`** 去匹配页面文件。 匹配规则:把菜单的 `hrefs` 和 glob 出来的 key 一起转小写,找包含 `//index.vue` 的那一项。 | 菜单 hrefs | 页面必须放的路径 | |---|---| | `position` | `src/views/任意模块/position/index.vue` | | `basicData/position` | `src/views/basicData/position/index.vue` | | `system/user` | `src/views/system/user/index.vue` | 要点: - **只有 `index.vue` 参与匹配**。同目录下的 `form.vue`、`view.vue`、`components/*.vue` 由 `index.vue` 自己 import,不要指望被路由到。 - 后端只给一段(如 `position`)时,任意模块下叫 `position` 的目录都能命中;给全路径时目录层级必须一致。 - 大小写不敏感,但建议目录名和 hrefs 完全一致。 ### 不依赖后端菜单的固定页面 在 `src/config/app-config.js` 的 `staticRoutes` 里配: ```js export default { staticRoutes: [ { path: '/developmentProcess', name: 'developmentProcess', layout: false, // false = 不带侧边栏和头部,独立整页 component: () => import('@/views/static/page/DevelopmentProcess.vue'), meta: { title: '开发流程', public: true, hidden: true } } ] } ``` `public: true` 免登录,`hidden: true` 不进侧边菜单。 ## 三、页面文件怎么组织 一个业务模块推荐这样放: ``` src/views/<模块>/<页面>/ ├─ index.vue # 列表页,被路由到 ├─ form.vue # 弹窗表单 / 新增编辑页,index.vue import ├─ view.vue # 详情页 ├─ components/ # 本页面私有子组件 └─ i18n.js # 本模块词条(可选) ``` 页面上的 `name` 用 `defineOptions({ name: 'XxxList' })` 显式声明,方便 keep-alive 和调试。 ## 四、国际化 基座按目录自动分配命名空间:`views/<模块>/i18n.js` → 命名空间 `<模块>`。 ```js // src/views/position/i18n.js export default { 岗位名称: 'Position Name', 请输入岗位名称: 'Please enter position name' } ``` 页面里二选一: ```js // 写法一:setup 里拿到 $l(推荐,模板和脚本都能用) const { $l } = window.useI18n('position') ``` ```vue {{ $l('添加') }} ``` 规则: - 词条 key 就是**中文原文**,值是对应英文。没配英文时英文环境会显示中文,不会空白。 - 按钮、通用提示(添加/删除/保存/操作成功)基座已内置,不用自己配。 - `$l('中文')` 里的中文必须是字面量,不要拼变量,否则切语言不生效。 ## 五、按钮级权限 后端返回的 `button_code` 与指令值**整体相等**才通过。 ```vue 添加 修改 ``` ```js // 或/且这类指令表达不了的场景,用函数 const canEdit = window.$utils.hasAction('edit') || window.$utils.hasAction('add') ``` 列表工具栏按钮也会自动挂 `v-action`,`key` 就是按钮编码(`add` / `remove` / `import` / `export`)。 ## 六、全局方法与工具 组件内用 `this.$xxx`,`