---
name: mvframe-app-init
description: >-
  Scaffolds or audits Vue 3 + Vite host apps that use MVFrame: install order
  (Element Plus, mvframe plugin, styles), Frame/menu/routes, Pinia options,
  global config (iconfont, table.summaryMetric), Vite aliases, and views/layout
  conventions. Use when the user initializes a project with mvframe, wires a
  new app to @vue/mvframe, asks for MVFrame bootstrap or “same architecture
  as mvframe”, or reviews structure against this library’s demo and rules.
---

# MVFrame 应用初始化与架构对齐

在**消费方项目**（或 monorepo 业务包）中接入 MVFrame 时，按下列顺序与约定执行，并与本仓库 `demo/`、`.cursor/rules/` 保持一致。显式触发：用户说「初始化 / 脚手架 / 接入 mvframe / 与 mvframe 架构统一」。

## 1. 依赖与入口顺序

1. `createApp(App)`
2. **`app.use(ElementPlus)`**（使用 Form / Table 等依赖 EP 的能力时）
3. **`import` 本库样式**：`mvframe` 源码路径或 monorepo 下的 `.../src/style/index.scss`
4. **`app.use(mvframe, options)`** — 见下节
5. **`app.mount('#app')`**

`mvframe` 默认导出为 **install 函数**；注册顺序在库内为：`config` → 全局组件 → `util` → `directive` → `store` → `router`（见 `src/index.js`），调用方勿拆分或颠倒。

## 2. `app.use(mvframe, options)` 必备形状

```js
app.use(mvframe, {
  vueRouter: {
    routes, // required
    // guard, useAdmin, adminPermission, noaccess — 按需
  },
  pinia: {
    useTab: true, // 多 Tab + localStorage 恢复时启用
    // storeChips: import.meta.glob('./pinia/chip/*.js', { eager: true }),
  },
  config: {
    iconfont: { url: '//...', prefix: '...' }, // Frame 挂载时注入 script
    table: {
      summaryMetric: { /* 或 (prop) => metric */ }, // 多表共用汇总/$fu 格式，可选
    },
    // 会与 src/config/chip/base.js 合并 → globalThis.$config
  },
});
```

- **`globalThis.$router`** 由库在安装路由后赋值。
- **Store**：组件内 `inject('store')` 取工厂，如 `store.tab()`。
- **Table 汇总**：单列优先 `summary-metric` prop，否则 `$config.table.summaryMetric`；`$fu` 与 `formatSummaryCell` 共用同一套 metric 配置。

## 3. 根组件与路由表

- 根布局使用 **`Frame`**，传入 `menu: { iconClass, routes }`（与 `demo/App.vue` 一致）；`logo` / `logomini` 用插槽。
- **路由 `meta`**：至少 `title`（守卫里写 `document.title`）；侧栏图标可用 `meta.icon`。
- **跳转**：优先 **`name`** 跳转，避免裸 `path`（见 `.cursor/rules/router.mdc`）。

## 4. Vite 对齐（消费方）

与库内一致可减少样式与路径问题：

| 项 | 建议 |
|----|------|
| `resolve.alias` | `@` → 业务 `src`；若直接引用 composition：`@cps` → `mvframe/.../composition` 或封装路径 |
| `css.preprocessorOptions.scss.additionalData` | 注入 mvframe 的 `chip/mixin.scss`（或与业务统一的 mixin） |
| 类型 | 若用 auto-import，为 `vue` / `vue-router` 生成 d.ts |

## 5. views 与应用层结构（消费方）

遵循 `.cursor/rules/views.mdc`：

- **`views` 下一级目录**：**PascalCase 模块名**；模块默认入口 **`Home.vue`**。
- **页面子组件**：与 `Xxx.vue` **同级**建 **`Xxx/`** 文件夹；子组件 `defineOptions({ name })` 使用 `{模块}{页面}{语义}` 拼接 PascalCase。

库内全局组件根 class：**`Mvc` + 组件名**；内部子 class **camelCase**（`.cursor/rules/component-hierarchy.mdc`）。业务页优先用库已注册组件名（`Frame`、`Page`、`Table` 等），勿重复注册。

## 6. 自检清单（Agent 生成/审查时用）

- [ ] Element Plus 在 mvframe 之前 `use`
- [ ] 已引入 `index.scss`（或等价主题入口），且 SCSS 与 mixin 策略与库一致
- [ ] `routes` 已传入，`Frame` 的 `menu.routes` 同源
- [ ] 需要多 Tab 时 `pinia.useTab: true`
- [ ] 需汇总格式化时配置 `config.table.summaryMetric` 或 Table `summary-metric`
- [ ] 路由跳转以 `name` 为主
- [ ] 业务 `views` 符合模块 / 同名文件夹 / 子组件命名规则

## 7. 参考文件（本仓库）

- `demo/main.js`、`demo/App.vue`、`demo/routes.js` — 最小可运行骨架
- `README.md` / `README.cn.md` — 目录与安装总览
- `.cursor/rules/*.mdc` — 组件 class、样式单位、router、views、util

在 **mvframe 仓库内开发库本身**时，改动以 `src/`、`demo/` 为准；技能主要面向 **引用 mvframe 的业务工程** 的初始化与对齐。

## 安装到业务工程

- **目录雏形（推荐）**：`yarn exec mvframe-init-app` 或 `node <mvframe>/scripts/scaffold-app.js`，生成 `src/views`、`router`、`pinia/chip`、`config` 等并写好 `main.js` + `App.use(mvframe)`，同时将包内 **`.cursor/rules/*.mdc`** 复制到目标项目（与仓库规范一致）；说明见目标项目根 `MVFRAME-SCAFFOLD.md`。
- **仅 Cursor Skill**：`yarn exec mvframe-install-cursor-skill` 或 `node <mvframe>/scripts/install-cursor-skill.js`（`MVFRAME_CURSOR_SKILL_OUT` 可选）。

详见仓库 `README.md` / `README.cn.md`。
