连接地址：https://gitee.com/fang_xue_liang/vue-platforms
1. 引言
1.1 编写目的
说明本系统在工程层面的总体结构、主要模块职责、构建与插件技术选型、仓库目录约定、技术优势与工程化收益，供研发、测试、运维及后续扩展子应用时对齐边界与约束。
1.2 范围
| 在内 |
不在内（除非另行约定） |
Monorepo 内门户、系统管理子应用、共享包 @common/* 的职责划分与协作方式 |
|
| 微前端（Qiankun）激活规则、宿主与子应用边界 |
具体业务需求说明书、详细测试用例 |
| 构建、目录与版本管理策略（pnpm catalog、可选 Turbo）；Vite 插件与工程化选型概要 |
|
1.3 术语与缩写
| 术语 |
含义 |
| 宿主 / 主应用 |
app-portal，负责壳、登录、布局、菜单与权限路由，并挂载子应用 |
| 子应用 |
如 app-system，独立构建部署的 Vue 应用，由 Qiankun 按 URL 激活 |
@common/* |
workspace 内共享包（组件、样式、工具、i18n 等），由各应用以依赖方式引用 |
| HTML Entry |
子应用以部署后的 index.html 为入口被宿主拉取解析 |
| catalog |
pnpm-workspace.yaml 中集中锁定依赖版本的机制 |
2. 总体架构
2.1 逻辑架构
2.2 仓库与目录结构说明
本仓库采用 pnpm workspace 管理多包；业务应用集中在 vue-apps/，共享能力集中在 vue-common/（多子包），设计文档在 docs/。
2.2.1 顶层一览
| 路径 |
说明 |
vue-apps/app-portal |
门户宿主：登录、主布局、路由权限、Qiankun 注册与启动、标签页等 |
vue-apps/app-system |
系统管理子应用：用户/角色/菜单/应用/按钮权限等页面，独立 dev/build，由宿主按路由激活 |
vue-common |
共享库根包（文档站 @common）及 vue-common/* 子包（components、styles、utils 等） |
docs/ |
概要设计、微前端、权限菜单、构建插件选型等 Markdown文档 |
pnpm-workspace.yaml |
声明 workspace 包路径 + catalog 统一版本 |
turbo.json |
任务管道与构建缓存（可选；根脚本 build:all 使用 pnpm -r run build，dev:all 使用 pnpm --parallel） |
根 package.json |
聚合脚本、全仓开发依赖（如 ESLint、Turbo） |
2.2.2 门户 app-portal/src（摘要）
| 目录 / 文件 |
职责 |
main.js / App.vue |
应用入口与根组件 |
permission.js |
路由守卫：Token、菜单拉取、白名单与权限路径校验 |
assets/ |
门户专用静态资源 |
layout/ |
主框架，布局 |
micro/ |
microApps.config.ts：子应用注册配置 |
router/ |
路由表 |
store/ |
Pinia：modules/ 按域拆分，index.ts 统一导出 |
utils/ |
门户专用工具，如 Axios request 封装 |
views/ |
登录、系统内页、微应用壳组件等 |
2.2.3 子应用 app-system/src（摘要）
| 目录 |
职责 |
api/ |
子应用接口模块 |
common/ |
子应用本地方法 |
components/ |
子应用专用组件 |
router/ |
子应用路由 |
store/ |
Pinia：modules/ + index.ts |
utils/ |
工具方法 |
views/ |
各业务页面（用户列表、角色、菜单管理等） |
2.2.4 共享库 vue-common（摘要）
| 路径 |
npm 作用域（示例） |
职责 |
vue-common/components/ |
@common/components |
Base 系列表格、查询条、图表、流媒体播放器等可复用 UI |
vue-common/styles/ |
@common/styles |
全局 SCSS、主题变量、暗色覆盖 |
vue-common/utils/ |
@common/utils |
权限 session、通用工具等 |
vue-common/i18n/ |
@common/i18n |
国际化资源与插件封装 |
vue-common/directives/ |
@common/directives |
如权限类指令 |
vue-common/src/ |
（文档站源码） |
组件演示、路由与页面，本地 pnpm dev 浏览 |
各子目录下若有 README.md，说明该目录用途与引用方式；版本与依赖以各包 package.json 及 catalog 为准。
2.3 技术栈（与仓库一致）
- 前端框架：Vue 3、Vue Router 4、Pinia
- 构建：Vite 5；微前端：qiankun +
vite-plugin-qiankun
- 工程：pnpm workspace、catalog；Turbo 可选（根脚本默认不依赖 Turbo 二进制）；TypeScript（各包按需）
- 国际化与工具：
vue-i18n、@vueuse/core（与 Element Plus、自动导入插件协同）
2.4 插件与构建技术选型（概要）
以下聚焦 Vite 插件与工程化关键依赖；版本号以 pnpm-workspace.yaml 的 catalog 为准，逐项设计理由与接入细节见 BUILD_PLIGIN_MODELS.md。
| 类别 |
选型 |
在本仓库中的作用 |
| 核心构建 |
vite + @vitejs/plugin-vue |
开发期 ESM、生产 Rollup 打包；Vue SFC 编译 |
| 开发体验 |
unplugin-auto-import |
自动导入 Vue/Pinia/Router 等 API，减少样板 import |
| 开发体验 |
unplugin-vue-components + Element Plus Resolver |
组件按需解析注册，控制包体 |
| 门户构建 |
vite-plugin-html |
index.html 注入环境变量与页面元信息 |
| 门户构建（可选） |
vite-plugin-ali-oss |
构建产物上传 OSS，适配静态托管流水线 |
| 微前端 |
qiankun + vite-plugin-qiankun |
HTML Entry、子应用生命周期；Vite 子应用 dev/prod 与宿主对接 |
| 资源 |
vite-svg-loader（如 app-system） |
.svg 以 Vue 组件形式使用 |
| 样式 |
sass、postcss、autoprefixer |
主题与原子类、前缀处理 |
| Monorepo |
pnpm workspace + catalog |
单一版本源，降低依赖漂移 |
| 任务编排 |
turbo（可选） |
turbo.json 定义管线；需要远程缓存时可 pnpm exec turbo run build；默认全量构建为 pnpm -r run build |
| 质量 |
eslint、eslint-plugin-vue、@typescript-eslint/parser |
静态检查 |
| 类型 |
typescript、vue-tsc |
TS 与 SFC 类型检查 |
| 运行时补充 |
vue-i18n、@vueuse/core、axios、dayjs 等 |
国际化、浏览器/响应式工具、HTTP 等 |
设计原则简述：构建链以 Vite 官方插件 + 社区成熟 unplugin 为主；微前端 qiankun + 官方桥接插件 降低手写胶水代码；样式 SCSS 主题 + Tailwind 按需 兼顾设计系统与迭代效率；依赖 catalog 集中治理 适配多应用并行演进。
2.5 技术优势与工程化收益
| 维度 |
说明 |
| 微前端解耦 |
宿主统一认证、菜单与壳；子应用独立仓库边界清晰，可单独发版、技术栈升级窗口更可控（在约定内）。 |
| 共享层复用 |
@common/* 沉淀组件、样式、工具与 i18n，避免多应用复制粘贴；文档站便于组件契约对齐。 |
| 构建与体验 |
Vite 冷启动与 HMR 适合 Monorepo 多入口并行开发；自动导入与按需组件减少重复代码。 |
| 依赖治理 |
catalog 统一版本，升级一处、全仓可审计；pnpm 节省磁盘与安装时间。 |
| 流水线与缓存 |
可选用 Turbo 对 build 等任务做缓存与拓扑排序；默认根脚本以 pnpm -r 保证 workspace 构建顺序。 |
| 权限与路由一致性 |
门户集中守卫与菜单合并；子应用按钮权限与 session 策略可与 @common/utils 对齐（详见权限相关文档）。 |
| 扩展性 |
新子应用按 Qiankun 约定注册即可挂载；新共享能力优先放入 vue-common 子包并纳入 workspace。 |
3. 模块与子系统设计
3.1 门户（app-portal）
| 职责 |
说明 |
| 认证与路由守卫 |
未登录跳转登录页；登录后拉取用户与菜单；路由与权限白名单见 permission.ts |
| 布局与导航 |
顶栏、侧栏、标签页等；主内容区提供子应用挂载容器 |
| 微前端生命周期 |
registerMicroApps / start / 预取；配置见 micro/microApps.config.ts、micro/bootstrap.ts |
| 国际化与主题 |
vue-i18n、@common/i18n；主题与暗色变量与 Element Plus 协同 |
3.2 系统管理子应用（app-system）
| 职责 |
说明 |
| 业务页面 |
如用户列表、权限等页面，在宿主内以 URL 前缀（如 /main/system/...）呈现 |
| 独立构建 |
自有 vite.config.ts、base 与 Qiankun 插件配置，可与门户并行 dev |
| 共享能力 |
按需依赖 @common/*，与宿主共用设计令牌与组件时保持 catalog 版本一致 |
3.3 共享层（vue-common / @common/*）
| 子包 |
用途 |
| components |
业务无关或可复用组件（表格、查询条、图表、BaseMpegTsPlayer / mpegts.js 流媒体等） |
| styles |
全局 SCSS、主题变量、暗色覆盖 |
| utils / directives / i18n / assets / tailwind |
工具函数、指令、文案、静态资源、Tailwind 预设；组合式能力由业务应用按需依赖 @vueuse/core（catalog 版本） |
vue-common src |
公共组件文档与演示站点（Vite），便于离线查看组件用法 |
4. 关键技术方案
4.1 微前端集成（Qiankun）
- 激活：以
pathname 匹配子应用 activeRule，与菜单跳转的 URL 一致；无权限则不展示菜单，用户不进入对应路径，子应用资源不加载。
- 宿主启动顺序：在应用初始化时注册微应用并启动 qiankun，具体配置见
app-portal/src/main.js。
- 样式隔离：使用
experimentalStyleIsolation: true 实现样式隔离，具体配置见 app-portal/src/main.js。
- 微应用配置：通过
microApps.config.ts 配置微应用信息，包括名称、入口地址、容器选择器和激活规则。
4.2 路由与权限（门户）
- 路由表预先定义；菜单与权限由后端（或 mock）下发后与本地路由元数据合并，形成可访问路径集合。
- 守卫配置见
app-portal/src/permission.js。
4.3 依赖与版本管理
- catalog：单一来源锁定依赖主版本，子包通过
catalog: 引用，升级时改 pnpm-workspace.yaml 后全仓 pnpm install。
- Turbo（可选）：
turbo.json 中 build 等任务可声明依赖 ^build；与 pnpm -r run build 拓扑顺序目标一致，按需选用。
4.4 构建与部署（概要）
- 门户与子应用可 独立产出 静态资源；子应用
base 需与网关或 CDN 路径一致。
- 门户可选 OSS 上传等插件（见根 README 与门户配置）。
- 环境变量：门户以
VITE_* 为主，示例见 vue-apps/app-portal/.env.example。
5. 接口与数据（概要）
5.1 前端视角的接口
- 认证：登录、Token 存储与请求头携带（以门户
request 封装为准）。
- 用户与菜单：登录后拉取用户信息、菜单树；用于侧栏渲染与权限校验。
- 业务接口：子应用内按模块调用；错误码与分页结构宜与门户约定一致，便于统一拦截与提示。
5.2 数据流（概要）
- 门户：
Pinia 用户与标签等状态 + session 等本地存储（见 store 与 storageManage）。
- 子应用：自有状态与接口层；与宿主共享登录态依赖同源 Cookie/Token 策略。
6. 非功能需求（概要）
| 类别 |
要求 |
| 浏览器 |
以现代 Chromium /主流浏览器为准；具体最低版本由项目约定 |
| 性能 |
子应用按需加载；门户侧可对微应用 entry 预取；大列表需分页与虚拟化（已有组件能力时复用） |
| 安全 |
HTTPS 部署；Token 防 XSS策略按公司规范；子应用避免污染宿主全局 |
| 可维护性 |
新子应用须登记 microApps.config.ts；路由 name/path 与菜单配置对齐，避免 401/404 误配 |
7. 开发与运维要点
| 场景 |
命令或说明 |
| 仅门户 |
pnpm dev:app-portal |
| 仅子应用 |
pnpm dev:app-system |
| 联调微前端 |
pnpm dev:all（并行启动 app-portal 与 app-system，见根 package.json） |
| 公共组件文档 |
pnpm dev:vue-common |
| 全量构建 |
pnpm build:all（pnpm -r run build） |
8. 文档与代码映射
9. AI coding infra
本期先聚焦落地三部分：AI规范、Context管理、skills 管理；其余工程化约束后续再补充。
9.1 AI规范（AGENTS.md）
- 开发前如涉及架构调整、公共能力抽取、目录变更或跨模块联动，需先阅读
context/project 中的设计文档。
- 所有任务遵循 先 plan、后编码 的基本要求，不跳过分析直接进入实现。
- 涉及方案设计、页面造型、交互调整时，需先在
context 中补充目标、约束与方案说明。
- AI 生成内容应可复核、可追踪，避免仅凭猜测直接修改。
- 不允许直接提交代码，提交代码之与务必与用户确认。
- 提交代码的message中增加前缀"[AI generated.]"，用于区分本批次代码主要由AI完成。
- 定期更新/Context/Task目录下的开发进度文档。
9.2 Context管理
Project
Team
Task
9.3 skills
- skills 设计为软链接，由
.github/.cursor 中的 skill 目录指向统一维护位置，便于 Git 管理与团队共享。
- 建议按框架能力、业务域知识、调试排障、发布运维、设计规范等维度分类。
- skills 内容应聚焦可复用步骤、注意事项与示例输入输出。
9
0
已为社区贡献1条内容
所有评论(0)