@farris/cli 2.3.7 → 2.3.9

package/templates/lib/farris.config.mjs

@@ -11,8 +11,8 @@ export default {
       return `index.${format}.js`;
     }
   },
-  outDir: './lib',
-  componentOutDir: './lib/components',
+  outDir: './dist',
+  componentOutDir: './dist/components',
   externalDependencies: true,
   minify: true
 };

package/templates/lib/package.json

@@ -16,7 +16,7 @@
     "url": "git@gitee.com:ubml/farris-vue.git"
   },
   "files": [
-    "lib"
+    "dist"
   ],
   "sideEffects": [
     "**/*.css",

package/templates/lib/tsconfig.json

@@ -2,8 +2,7 @@
   "extends": "@vue/tsconfig/tsconfig.dom.json",
   "include": [
     "components/**/*",
-    "src/**/*",
-    "test/**/*"
+    "src/**/*"
   ],
   "compilerOptions": {
     "strict": true

package/templates/lib/vitest.config.ts

@@ -1,10 +1,12 @@
 import vue from '@vitejs/plugin-vue';
-import { defineConfig } from 'vitest/config';
+import { configDefaults, defineConfig } from 'vitest/config';
 
 export default defineConfig({
   plugins: [vue()],
   test: {
     environment: 'jsdom',
-    include: ['test/**/*.spec.{ts,tsx}']
+    // 官方默认收集范围（**/*.{test,spec}.*），源码旁的测试才会被收集
+    include: [...configDefaults.include],
+    exclude: [...configDefaults.exclude, '**/__sandbox_*/**']
   }
 });

package/templates/micro/.eslintrc.cjs

@@ -0,0 +1,15 @@
+/* eslint-env node */
+require('@rushstack/eslint-patch/modern-module-resolution');
+
+module.exports = {
+  root: true,
+  'extends': [
+    'plugin:vue/vue3-essential',
+    'eslint:recommended',
+    '@vue/eslint-config-typescript',
+    '@vue/eslint-config-prettier/skip-formatting'
+  ],
+  parserOptions: {
+    ecmaVersion: 'latest'
+  }
+};

package/templates/micro/.gitignore.tpl

@@ -0,0 +1,33 @@
+# 依赖与产物
+node_modules/
+dist/
+dist-es/
+dist-ssr/
+coverage/
+*.tsbuildinfo
+.pnpm-store/
+
+# 日志与本地文件
+*.log
+.DS_Store
+*.local
+.env
+.env.*
+!.env.example
+package-lock.json
+
+# 编辑器
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
+.history
+*.sw?
+
+# AI 工具
+.codebuddy/
+.cursor/
+.claude/
+.windsurf/
+.trae/
+.opencode/

package/templates/micro/.gitlab-ci.yml

@@ -0,0 +1,59 @@
+image: registry.inspures.com/public/docker.io/library/node:22
+
+variables:
+  NPM_REGISTRY: "https://repos.iec.io/repository/npm-igix/"
+  NPM_RELEASE_REGISTRY: "https://repos.iec.io/repository/npm-igix-release/"
+
+stages:
+  - build
+  - publishproject
+
+build-job:
+  stage: build
+  tags:
+    - environment:cloud
+  before_script:
+    - |
+      if [ -z "${ARTIFACTS_REPO_USERNAME}" ] || [ -z "${ARTIFACTS_REPO_PASSWORD}" ]; then
+        echo "ARTIFACTS_REPO_USERNAME or ARTIFACTS_REPO_PASSWORD is empty on ${CI_COMMIT_REF_NAME}."
+        echo "If these GitLab CI/CD variables are Protected, they are not available on unprotected branches."
+        exit 1
+      fi
+    - if [ ! -f .npmrc ]; then wget -O - https://repos.iec.io/gitlab-ci/template/experimental/script/npmrc | sh; fi
+    - echo _auth=$(echo -n ${ARTIFACTS_REPO_USERNAME}:${ARTIFACTS_REPO_PASSWORD} | base64) >> .npmrc
+    - echo always-auth=true >> .npmrc
+    - sed -i "s#registry=.*#registry=$NPM_REGISTRY#g" $CI_PROJECT_DIR/.npmrc
+    - cp .npmrc ~/
+    - npm config fix
+  script:
+    - npm i --no-package-lock
+    - npm test
+    - npm run build
+  artifacts:
+    expire_in: '5days'
+    name: 'dist'
+    paths:
+      - $CI_PROJECT_DIR/dist
+
+publish-project:
+  stage: publishproject
+  tags:
+    - environment:cloud
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d/
+  before_script:
+    - |
+      if [ -z "${ARTIFACTS_REPO_USERNAME}" ] || [ -z "${ARTIFACTS_REPO_PASSWORD}" ]; then
+        echo "ARTIFACTS_REPO_USERNAME or ARTIFACTS_REPO_PASSWORD is empty on ${CI_COMMIT_REF_NAME}."
+        echo "If these GitLab CI/CD variables are Protected, they are not available on unprotected branches."
+        exit 1
+      fi
+    - if [ ! -f .npmrc ]; then wget -O - https://repos.iec.io/gitlab-ci/template/experimental/script/npmrc | sh; fi
+    - echo _auth=$(echo -n ${ARTIFACTS_REPO_USERNAME}:${ARTIFACTS_REPO_PASSWORD} | base64) >> .npmrc
+    - echo always-auth=true >> .npmrc
+    - sed -i "s#registry=.*#registry=$NPM_RELEASE_REGISTRY#g" $CI_PROJECT_DIR/.npmrc
+    - cp .npmrc ~/
+    - npm config fix
+  script:
+    - npm config set //repos.iec.io/repository/npm-igix-release/:_auth=$(echo -n ${ARTIFACTS_REPO_USERNAME}:${ARTIFACTS_REPO_PASSWORD} | base64)
+    - cd dist && npm publish

package/templates/micro/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "semi": false,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "none"
+}

package/templates/micro/farris.config.mjs

@@ -0,0 +1,34 @@
+import { fileURLToPath, URL } from 'node:url';
+
+export default {
+  // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
+  base: './',
+  routerMode: 'hash',
+  // 微应用交付：默认 iife 单文件（IBP 微前端）；需要普通 ESM 产物时执行 pnpm build:es
+  format: "<%= format %>",
+  // 输出目录  App/Lib 模式默认值均为 './dist'
+  // outDir: fileURLToPath(new URL('./dist', import.meta.url)),
+  // 最小化 默认值 true
+  minify: true,
+  // 外部依赖排除项 默认值 { include: [], exclude: [] }
+  // externals: {
+  //   include: [],
+  //   exclude: []
+  // },
+  // 是否排除 package.json 中 dependencies和 peerDependencies 依赖的包; App模式默认值 false Lib模式默认值 true
+  externalDependencies: false,
+  // 路径别名 默认值 null
+  alias: [
+    { find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }
+  ],
+  // 插件 默认值 [vue(), vueJsx()] 不要重复添加
+  // plugins: [],
+  // 开发期 mock 默认开启：接口数据来自工程内 mock/ 目录，未命中的请求按下方 proxy 转发
+  // mock: true,
+  // 开发代理：未命中 mock 的接口转发到真实后端；联调时执行 pnpm dev --no-mock 可整体关闭 mock
+  // proxy: {
+  //   '/api': { target: 'http://localhost:8080', changeOrigin: true }
+  // },
+  // viteConfig 配置项
+  viteConfig: {}
+};

package/templates/micro/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= title %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/micro/mock/README.md

@@ -0,0 +1,53 @@
+# mock 目录
+
+开发期接口数据。用 MSW 写法，库本身的用法见 MSW 官方文档。一个领域一个文件，命名 `*.mock.ts`，只导出 handler 数组：
+
+```ts
+import { http, HttpResponse, delay } from 'msw';
+
+export const handlers = [
+  http.get('/api/v1/users', async ({ request }) => {
+    const keyword = new URL(request.url).searchParams.get('keyword') ?? '';
+    await delay(300); // 可选：模拟延迟，单位毫秒
+    return HttpResponse.json({ data: [], total: 0 }); // 形状跟客户端出口走
+  }),
+  http.get('/api/v1/users/:id', ({ params }) => HttpResponse.json({ data: { id: params.id } })),
+  http.post('/api/v1/users', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: 'u-new', ...body }, { status: 201 });
+  })
+];
+```
+
+## 加一条 mock 并验证
+
+1. 先在 `src/api/` 里确认实际请求路径（例如 `/api/v1/users`），逐字抄进 handler 路径，前缀也要带上。
+2. 新建或追加 `mock/<领域>.mock.ts`，按上面的形状写 handler；同一前缀下字面量路径写在 `:参数名` 之前。
+3. 在工程目录执行 `pnpm dev`，打开用到该接口的页面，**验证**返回的是 mock 数据。
+4. 需要联调真实后端时执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
+
+规则：
+
+- url 必须与代码实际发出的请求路径逐字一致，前缀也要带上；请求路径见 `src/api/` 下的接口模块。
+- url 只写路径，以 `/` 开头，不要写协议与主机。写 `/api/v1/users`，不要写 `http://localhost:3000/api/v1/users`；主机或端口不同时不会命中。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`。查询参数不写进 url，用 `new URL(request.url).searchParams` 读取。
+- 同一前缀下同时有字面量路径与 `:参数名` 路径时，字面量写在前面。MSW 取第一个匹配的 handler，`/api/v1/users/current` 排在 `/api/v1/users/:id` 后面会被 `:id` 接走。
+- 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。数据要有业务语义，用中文姓名、机构、单据号这类内容，不要用占位文本。
+- 关键场景要模拟：空态、错误、慢响应。错误用 `HttpResponse.json(..., { status: 500 })`；慢响应用 `delay`。
+- 目录里只放 handler 文件。共享数据或工具函数要放进 `_` 开头的文件，例如 `_data.ts`，加载时会跳过；其他文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
+- 同一路径不允许在多个 mock 文件中重复定义，重复时开发服务启动或请求即报错。
+- 文件只导出 handler 数组，写 `export const handlers = [...]` 或 `export default [...]`。不需要 `setupServer` / `setupWorker` 接线；接线由脚手架完成。
+- `msw` 已由模板放进应用 `devDependencies`，版本随工作区 catalog 统一。不要把它加到 `dependencies`，也不要在 `mock/` 之外引用它，否则构建期会报错。
+- mock 只用于开发期，不参与构建，也不要在组件里散落假数据。
+
+行为：
+
+- 命中 mock 时返回 mock 数据。
+- 未命中时按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。
+
+类型：本目录附带独立的 `tsconfig.json`，只服务于编辑器与按需类型检查。应用自身的 `typecheck` 不包含本目录，mock 也不参与构建。
+
+约定版本 2026-09。本文件随 `@farris/cli` 模板发布，AI 协作以本文件为准。

package/templates/micro/mock/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  // mock 目录的独立 TS 工程：只服务于编辑器与按需类型检查（应用自身的 typecheck 不含本目录）。
+  // msw 是应用的开发期依赖（见 package.json 的 devDependencies），按常规模块解析即可。
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.d.ts"]
+}

package/templates/micro/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "<%= name %>",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "farris": {
+    "type": "micro"
+  },
+  "scripts": {
+    "dev": "farris-cli dev",
+    "build": "farris-cli build -ep --format iife",
+    "build:es": "farris-cli build -ep --format es",
+    "preview": "farris-cli preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "vue-tsc --noEmit",
+    "lint": "eslint . --ext .vue,.ts,.tsx --fix",
+    "format": "prettier --write src/",
+    "i18n": "farris-cli extract-i18n"
+  },
+  "dependencies": {
+    "@farris/ui-vue": "latest",
+    "vue": "^3.4.29",
+    "vue-router": "^4.3.0"
+  },
+  "devDependencies": {
+    "@farris/cli": "<%= cliVersion %>",
+    "@rushstack/eslint-patch": "^1.8.0",
+    "@vitejs/plugin-vue": "^5.2.4",
+    "@vitejs/plugin-vue-jsx": "^3.0.0",
+    "@vue/eslint-config-prettier": "^9.0.0",
+    "@vue/eslint-config-typescript": "^13.0.0",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.5.1",
+    "eslint": "^8.57.0",
+    "eslint-plugin-vue": "^9.23.0",
+    "jsdom": "^25.0.1",
+    "msw": "^2.15.0",
+    "prettier": "^3.2.5",
+    "typescript": "~5.4.0",
+    "vite": "^5.4.19",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^2.2.0",
+    "sass": "^1.90.0"
+  }
+}

package/templates/micro/src/App.tsx

@@ -0,0 +1,25 @@
+import { defineComponent } from 'vue';
+import { RouterLink, RouterView } from 'vue-router';
+import { setupMicroAppContext } from './micro/context';
+
+export default defineComponent({
+  name: 'App',
+  setup() {
+    // 微前端环境：订阅主应用下发的上下文（语言 / 主题）
+    setupMicroAppContext();
+
+    return () => (
+      <>
+        <header>
+          <div class="wrapper">
+            <nav>
+              <RouterLink to="/">Home</RouterLink>
+              <RouterLink to="/about">About</RouterLink>
+            </nav>
+          </div>
+        </header>
+        <RouterView />
+      </>
+    );
+  }
+});

package/templates/micro/src/locales/index.ts

@@ -0,0 +1,5 @@
+import zhCHS from './zh-CHS.json';
+
+export const localResources = {
+    'zh-CHS': zhCHS
+};

package/templates/micro/src/locales/zh-CHS.json

@@ -0,0 +1 @@
+{}

package/templates/micro/src/main.ts

@@ -0,0 +1,47 @@
+import { createApp, type App as VueApp } from 'vue';
+import FarrisVue from '@farris/ui-vue';
+import '@farris/ui-vue/index.css';
+import App from './App';
+import router from './router';<%= styleImport %>
+import { localResources } from './locales';
+
+let app: VueApp | null = null;
+
+/** 挂载应用（微前端宿主会调用 window.mount） */
+function mount(): void {
+  if (app) {
+    return;
+  }
+  app = createApp(App);
+  app.use(FarrisVue, { basePath: '', locale: 'zh-CHS', localResources });
+  app.use(router);
+  app.mount('#app');
+
+  // 微前端环境：按平台下发的 initialPath 定位菜单配置的页面（fullPath）
+  // hash 路由必须保留这段兜底；history 路由下平台 defaultPage 已能直接命中，这里是幂等兜底
+  if (window.__MICRO_APP_ENVIRONMENT__) {
+    const rawPath = window.microApp?.getData?.()?.initialPath;
+    if (typeof rawPath === 'string' && rawPath !== '') {
+      // 平台下发的 initialPath 通常不带前导斜杠（如 'form'），这里统一归一化
+      const initialPath = rawPath.startsWith('/') ? rawPath : '/' + rawPath;
+      if (initialPath !== '/') {
+        router.isReady().then(() => router.replace(initialPath)).catch(() => undefined);
+      }
+    }
+  }
+}
+
+/** 卸载应用（微前端宿主会调用 window.unmount） */
+function unmount(): void {
+  app?.unmount();
+  app = null;
+}
+
+// 微前端（micro-app）生命周期契约：必须暴露到 window
+window.mount = mount;
+window.unmount = unmount;
+
+// 独立运行（浏览器直接访问 / iframe 嵌入）时自动挂载
+if (!window.__MICRO_APP_ENVIRONMENT__) {
+  mount();
+}

package/templates/micro/src/router/index.ts

@@ -0,0 +1,24 @@
+import { createRouter, createWebHashHistory, type RouteRecordRaw } from 'vue-router';
+
+// 生成器（farris-cli generate view --with-route）依赖下面的 routes 数组赋值形式；
+// 改动结构会导致路由无法自动注册。
+export const routes: RouteRecordRaw[] = [
+  {
+    path: '/',
+    name: 'Home',
+    component: () => import('../views/HomeView')
+  },
+  {
+    path: '/about',
+    name: 'About',
+    component: () => import('../views/AboutView')
+  }
+];
+
+const router = createRouter({
+  // hash 路由：微前端（IBP）下子应用 location 由宿主接管，hash 模式最稳妥
+  history: createWebHashHistory(),
+  routes
+});
+
+export default router;

package/templates/micro/src/views/AboutView.tsx

@@ -0,0 +1,12 @@
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+  name: 'AboutView',
+  setup() {
+    return () => (
+      <div class="about">
+        <h1>This is an about page</h1>
+      </div>
+    );
+  }
+});

package/templates/micro/src/views/HomeView.tsx

@@ -0,0 +1,13 @@
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+  name: 'HomeView',
+  setup() {
+    return () => (
+      <main>
+        <h1>Home</h1>
+        <p>在 src/views/ 下新增页面；通用组件按需创建在 src/components/ 下。</p>
+      </main>
+    );
+  }
+});

package/templates/micro/src/views/__tests__/AboutView.spec.tsx

@@ -0,0 +1,11 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import AboutView from '../AboutView';
+
+describe('AboutView', () => {
+  it('mounts', () => {
+    const wrapper = mount(AboutView);
+
+    expect(wrapper.exists()).toBe(true);
+  });
+});

package/templates/micro/src/views/__tests__/HomeView.spec.tsx

@@ -0,0 +1,11 @@
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import HomeView from '../HomeView';
+
+describe('HomeView', () => {
+  it('mounts', () => {
+    const wrapper = mount(HomeView);
+
+    expect(wrapper.exists()).toBe(true);
+  });
+});

package/templates/micro/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "@vue/tsconfig/tsconfig.dom.json",
+  "include": [
+    "env.d.ts",
+    "src/**/*",
+    "src/**/*.vue"
+  ],
+  "compilerOptions": {
+    "composite": true,
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  }
+}

package/templates/micro/vitest.config.ts

@@ -0,0 +1,12 @@
+import vue from '@vitejs/plugin-vue';
+import { configDefaults, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'jsdom',
+    // 官方默认收集范围（**/*.{test,spec}.*），源码旁的测试才会被收集
+    include: [...configDefaults.include],
+    exclude: [...configDefaults.exclude, '**/__sandbox_*/**']
+  }
+});

package/templates/mobile/.gitignore.tpl

@@ -1,32 +1,33 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-lerna-debug.log*
+# 依赖与产物
+node_modules/
+dist/
+dist-es/
+dist-ssr/
+coverage/
+*.tsbuildinfo
+.pnpm-store/
 
-node_modules
-package-lock.json
+# 日志与本地文件
+*.log
 .DS_Store
-dist
-dist-es
-dist-ssr
-coverage
 *.local
+.env
+.env.*
+!.env.example
+package-lock.json
 
-/cypress/videos/
-/cypress/screenshots/
-
-# Editor directories and files
+# 编辑器
 .vscode/*
 !.vscode/extensions.json
-.idea
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
+!.vscode/settings.json
+.idea/
+.history
 *.sw?
 
-*.tsbuildinfo
+# AI 工具
+.codebuddy/
+.cursor/
+.claude/
+.windsurf/
+.trae/
+.opencode/

package/templates/mobile/farris.config.mjs

@@ -4,9 +4,9 @@ export default {
   // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
   base: './',
   routerMode: 'hash',
-  // iife: IBP 微前端单文件产物（默认）；如需普通 ESM 站点产物，执行 pnpm build:es
+  // 默认交付格式；pnpm build 会依次产出 es / umd / systemjs（iife 见 --format iife）
   format: "<%= format %>",
-  // 输出目录  App模式默认值 './dist' Lib模式 './lib'
+  // 输出目录  App/Lib 模式默认值均为 './dist'
   // outDir: fileURLToPath(new URL('./dist', import.meta.url)),
   // 最小化 默认值 true
   minify: true,