@liujitcn/kratos-admin-cli 0.0.1

package/README.md

@@ -0,0 +1,98 @@
+# @liujitcn/kratos-admin-cli
+
+用于创建 kratos-admin 业务项目的公开命令行工具。生成结果是一个可独立安装、开发和构建的 pnpm workspace，其中宿主保持轻量，业务实现位于可独立发布的模块包。
+
+## 目录与文件
+
+```text
+packages/cli
+├── src
+│   ├── index.ts
+│   └── index.test.ts
+├── templates/business-workspace
+│   ├── apps/admin
+│   ├── packages/modules/__MODULE_NAME__ # 可重复渲染的 module 模板
+│   ├── scripts/build-package.mjs
+│   ├── package.json
+│   ├── pnpm-workspace.yaml
+│   ├── README.md
+│   ├── tsconfig.json
+│   └── turbo.json
+├── package.json
+├── README.md
+└── tsconfig.json
+```
+
+| 路径                                                             | 作用                                                         |
+| ---------------------------------------------------------------- | ------------------------------------------------------------ |
+| `src/index.ts`                                                   | 解析 `create` 命令并生成宿主与一个或多个业务 module。        |
+| `src/index.test.ts`                                              | 验证多 module、默认 System、README 和依赖生成行为。          |
+| `templates/business-workspace/`                                  | 完整业务 workspace 模板；目录和文本中的占位符由 CLI 替换。   |
+| `templates/business-workspace/apps/admin/`                       | 生成项目的薄宿主模板。                                       |
+| `templates/business-workspace/packages/modules/__MODULE_NAME__/` | 生成项目的可发布业务模块模板。                               |
+| `templates/business-workspace/scripts/build-package.mjs`         | 生成业务模块发布源码和声明文件。                             |
+| `package.json`                                                   | 声明 `kratos-admin` 可执行命令、脚本、Node 版本和发布配置。   |
+| `README.md`                                                      | CLI 使用方法、模板结构和维护说明。                           |
+| `tsconfig.json`                                                  | CLI 源码、测试的编译配置和 `dist` 输出规则。                 |
+
+模板内部每个含 `package.json` 的目录都有同级 README，生成时目录名、包名、模块变量和文档占位符会一起替换。
+
+## 使用
+
+```bash
+pnpm dlx @liujitcn/kratos-admin-cli create shop-admin --module shop
+pnpm dlx @liujitcn/kratos-admin-cli create shop-admin --module shop,order
+pnpm dlx @liujitcn/kratos-admin-cli create shop-admin --module shop --with audit
+
+# 当前仓库开发
+pnpm module:create ../shop-admin --module shop
+pnpm module:create ../shop-admin --module shop,order
+pnpm module:create ../shop-admin --module shop --module order
+pnpm module:create ../shop-admin --module shop,order --with audit
+pnpm --filter @liujitcn/kratos-admin-cli test
+```
+
+CLI 始终先引入 `@liujitcn/kratos-admin-system`。`--module` 可重复使用，也接受逗号分隔名称，并为每个名称创建独立 module 包；`--with` 接收逗号分隔的额外已发布 module 名称，只装配依赖而不生成源码。CLI 拒绝覆盖已有目录；渲染失败时会清理本次创建的不完整目标目录。
+
+生成结果遵守以下约束：
+
+- 宿主通过 `src/module-manifest.ts` 维护装配清单，`src/modules.ts` 默认导出当前全部 module。
+- 业务视图按 `<module>/<view>` 注册，后端菜单必须使用模块前缀。
+- 业务模块只依赖 core 的公开 npm Interface，不引用 core 源码路径。
+- API 按 Proto 一级领域组织，RPC 保留完整 Proto 目录层级。
+- 静态页只能通过 `AdminModule.staticViews` 显式替换。
+
+## 模板占位符
+
+| 占位符                  | 生成内容                                 |
+| ----------------------- | ---------------------------------------- |
+| `__PROJECT_NAME__`      | 项目目录名称，例如 `shop-admin`。        |
+| `__APP_PACKAGE__`       | 宿主包名，例如 `@shop/admin-app`。       |
+| `__APP_DEPENDENCIES__`  | System、自有 module 和额外 module 依赖。 |
+| `__MODULE_NAME__`       | kebab-case 模块名，例如 `shop`。         |
+| `__MODULE_PASCAL__`     | PascalCase 模块名，例如 `Shop`。         |
+| `__MODULE_PACKAGE__`    | 模块包名，例如 `@shop/admin-module`。    |
+| `__MODULE_IDENTIFIER__` | 模块入口变量，例如 `shopAdminModule`。   |
+| `__CORE_VERSION__`      | 当前 core 包版本对应的 semver 范围。     |
+| `__MODULE_FILTERS__`    | 全部自有 module 的 workspace 过滤参数。  |
+| `__MODULE_MANIFEST__`   | 宿主模块加载器、包名和预构建依赖清单。   |
+| `__MODULE_NAMES__`      | 文档中的全部自有 module 名称。           |
+| `__MODULE_PACKAGES__`   | 文档中的全部自有 module 包名。           |
+| `__MODULE_PATHS__`      | 全部自有 module 的 TypeScript 路径映射。 |
+| `__MODULE_TREE__`       | 文档中的自有 module 目录树。             |
+| `__MODULE_TABLE_ROWS__` | 文档中的自有 module 目录说明。           |
+
+## 维护与验证
+
+修改 CLI 或模板后执行：
+
+```bash
+pnpm --filter @liujitcn/kratos-admin-cli type:check
+pnpm --filter @liujitcn/kratos-admin-cli test
+```
+
+测试会生成临时 workspace，并检查根、宿主、模块和 RPC README 中的占位符均已替换。模板新增包或改变目录职责时，必须同步更新对应目录的 README 和 `src/index.test.ts` 断言。
+
+发布包包含编译后的 `dist/index.js`、类型声明、workspace 模板和本 README。仓库级
+`make -C frontend package-admin` 会先执行测试和构建，再生成
+`@liujitcn/kratos-admin-cli` tarball。

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/** 创建业务 workspace 的参数。 */
+export interface CreateWorkspaceOptions {
+    /** 项目目录名称或路径。 */
+    projectName: string;
+    /** 需要创建的业务模块名称，使用 kebab-case。 */
+    moduleNames: string[];
+    /** 宿主额外装配的业务模块名称。 */
+    additionalModules?: string[];
+    /** 生成命令的工作目录。 */
+    cwd?: string;
+}
+/** 创建包含宿主和业务模块包的 pnpm workspace。 */
+export declare function createBusinessWorkspace(options: CreateWorkspaceOptions): Promise<string>;
+/** 解析命令行并执行对应命令。 */
+export declare function runCli(args?: string[]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const templateRoot = resolve(packageRoot, "templates/business-workspace");
+const gitignoreTemplateName = "_gitignore";
+const kebabNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const officialModuleOptimizeDependencies = {
+    system: ["swagger-ui-dist/swagger-ui-bundle.js"]
+};
+/** 创建包含宿主和业务模块包的 pnpm workspace。 */
+export async function createBusinessWorkspace(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const target = resolve(cwd, options.projectName);
+    const projectName = basename(target);
+    const moduleNames = normalizeModuleNames(options.moduleNames);
+    const primaryModuleName = moduleNames[0];
+    const additionalModules = normalizeAdditionalModules(options.additionalModules ?? [], moduleNames);
+    validateName(projectName, "项目名称");
+    if (await pathExists(target))
+        throw new Error(`目标目录已存在，拒绝覆盖: ${target}`);
+    const packageVersion = await readCorePackageVersion();
+    const primaryModuleTokens = createModuleTokens(primaryModuleName, packageVersion);
+    const moduleManifestEntries = [
+        {
+            packageName: "@liujitcn/kratos-admin-system",
+            moduleIdentifier: "systemAdminModule",
+            optimizeDependencies: officialModuleOptimizeDependencies.system
+        },
+        ...moduleNames.map(name => ({
+            packageName: `@${name}/admin-module`,
+            moduleIdentifier: `${toCamelCase(name)}AdminModule`,
+            optimizeDependencies: []
+        })),
+        ...additionalModules.map(name => ({
+            packageName: `@liujitcn/kratos-admin-${name}`,
+            moduleIdentifier: `${toCamelCase(name)}AdminModule`,
+            optimizeDependencies: officialModuleOptimizeDependencies[name] ?? []
+        }))
+    ];
+    const moduleManifest = moduleManifestEntries
+        .map(entry => {
+        const lines = [
+            "  {",
+            `    packageName: "${entry.packageName}",`,
+            `    load: async () => (await import("${entry.packageName}")).${entry.moduleIdentifier}`
+        ];
+        if (entry.optimizeDependencies.length > 0) {
+            lines[2] += ",";
+            lines.push(`    optimizeDependencies: ${JSON.stringify(entry.optimizeDependencies)}`);
+        }
+        lines.push("  }");
+        return lines.join("\n");
+    })
+        .join(",\n");
+    const modulePackages = moduleNames.map(name => `@${name}/admin-module`);
+    const appDependencies = {
+        "@liujitcn/kratos-admin-core": `^${packageVersion}`,
+        "@liujitcn/kratos-admin-system": `^${packageVersion}`,
+        ...Object.fromEntries(modulePackages.map(packageName => [packageName, "workspace:*"])),
+        ...Object.fromEntries(additionalModules.map(name => [`@liujitcn/kratos-admin-${name}`, `^${packageVersion}`]))
+    };
+    const modulePaths = Object.fromEntries(moduleNames.flatMap(name => {
+        const packageName = `@${name}/admin-module`;
+        const moduleRoot = `packages/modules/${name}`;
+        return [
+            [packageName, [`${moduleRoot}/src/index.ts`]],
+            [`${packageName}/api/*`, [`${moduleRoot}/src/api/*`]],
+            [`${packageName}/package.json`, [`${moduleRoot}/package.json`]],
+            [`${packageName}/rpc/*`, [`${moduleRoot}/src/rpc/*`]]
+        ];
+    }));
+    const tokens = {
+        ...primaryModuleTokens,
+        __PROJECT_NAME__: projectName,
+        __APP_PACKAGE__: `@${primaryModuleName}/admin-app`,
+        __APP_DEPENDENCIES__: formatJsonValue(appDependencies, "  "),
+        __MODULE_FILTERS__: modulePackages.map(packageName => `--filter=${packageName}`).join(" "),
+        __MODULE_MANIFEST__: moduleManifest,
+        __MODULE_NAMES__: moduleNames.join("、"),
+        __MODULE_PACKAGES__: modulePackages.map(packageName => `\`${packageName}\``).join("、"),
+        __MODULE_PATHS__: formatJsonValue(modulePaths, "    "),
+        __MODULE_TREE__: createModuleTree(moduleNames),
+        __MODULE_TABLE_ROWS__: createModuleTableRows(moduleNames)
+    };
+    await mkdir(target, { recursive: false });
+    try {
+        await renderDirectory(templateRoot, target, tokens);
+        const moduleTemplateRoot = resolve(templateRoot, "packages/modules/__MODULE_NAME__");
+        for (const moduleName of moduleNames.slice(1)) {
+            await renderDirectory(moduleTemplateRoot, resolve(target, "packages/modules", moduleName), {
+                ...createModuleTokens(moduleName, packageVersion),
+                __PROJECT_NAME__: projectName
+            });
+        }
+    }
+    catch (error) {
+        await rm(target, { recursive: true, force: true });
+        throw error;
+    }
+    return target;
+}
+/** 解析命令行并执行对应命令。 */
+export async function runCli(args = process.argv.slice(2)) {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        return;
+    }
+    if (args[0] !== "create")
+        throw new Error(`不支持的命令: ${args[0]}`);
+    const projectName = args[1];
+    const moduleNames = [...readOptions(args, "--module"), ...readOptions(args, "--modules")];
+    const withModules = readOptions(args, "--with");
+    if (!projectName || moduleNames.length === 0) {
+        throw new Error("用法: kratos-admin create <project> --module <module[,module...]>");
+    }
+    const target = await createBusinessWorkspace({ projectName, moduleNames, additionalModules: withModules });
+    process.stdout.write(`已创建业务 workspace: ${target}\n`);
+}
+/** 渲染模板目录中的路径和文本占位符。 */
+async function renderDirectory(source, target, tokens) {
+    await mkdir(target, { recursive: true });
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const renderedName = entry.name === gitignoreTemplateName ? ".gitignore" : replaceTokens(entry.name, tokens);
+        const sourcePath = join(source, entry.name);
+        const targetPath = join(target, renderedName);
+        if (entry.isDirectory()) {
+            await mkdir(targetPath, { recursive: true });
+            await renderDirectory(sourcePath, targetPath, tokens);
+            continue;
+        }
+        const content = await readFile(sourcePath, "utf8");
+        await writeFile(targetPath, replaceTokens(content, tokens));
+    }
+}
+/** 读取 core 版本，作为生成项目默认的公开包版本。 */
+async function readCorePackageVersion() {
+    const packageJson = JSON.parse(await readFile(resolve(packageRoot, "../core/package.json"), "utf8"));
+    return packageJson.version;
+}
+/** 读取可重复且支持逗号分隔的命令行选项值。 */
+function readOptions(args, option) {
+    return args.flatMap((argument, index) => {
+        if (argument !== option)
+            return [];
+        const value = args[index + 1];
+        if (!value || value.startsWith("--"))
+            throw new Error(`选项 ${option} 缺少值`);
+        return value
+            .split(",")
+            .map(item => item.trim())
+            .filter(Boolean);
+    });
+}
+/** 校验项目与模块名称。 */
+function validateName(value, label) {
+    if (!kebabNamePattern.test(value))
+        throw new Error(`${label}必须使用 kebab-case: ${value}`);
+}
+/** 规范化自有模块列表并校验保留名称。 */
+function normalizeModuleNames(moduleNames) {
+    const normalized = [...new Set(moduleNames.map(name => name.trim()).filter(Boolean))];
+    const primaryModuleName = normalized[0];
+    if (!primaryModuleName)
+        throw new Error("至少需要一个业务模块名称");
+    normalized.forEach(name => validateName(name, "模块名称"));
+    const reservedName = normalized.find(name => name === "system" || name === "kratos-admin");
+    if (reservedName)
+        throw new Error(`自有模块名称不能使用保留名称: ${reservedName}`);
+    return [primaryModuleName, ...normalized.slice(1)];
+}
+/** 规范化额外模块列表并去重。 */
+function normalizeAdditionalModules(moduleNames, currentModules) {
+    const normalized = [...new Set(moduleNames.map(name => name.trim()).filter(Boolean))];
+    normalized.forEach(name => validateName(name, "额外模块名称"));
+    return normalized.filter(name => name !== "system" && !currentModules.includes(name));
+}
+/** 创建单个自有模块模板使用的占位符。 */
+function createModuleTokens(moduleName, packageVersion) {
+    return {
+        __MODULE_NAME__: moduleName,
+        __MODULE_PASCAL__: toPascalCase(moduleName),
+        __MODULE_PACKAGE__: `@${moduleName}/admin-module`,
+        __MODULE_IDENTIFIER__: `${toCamelCase(moduleName)}AdminModule`,
+        __CORE_VERSION__: `^${packageVersion}`
+    };
+}
+/** 格式化嵌入模板的多行 JSON 值。 */
+function formatJsonValue(value, indentation) {
+    const lines = JSON.stringify(value, null, 2).split("\n");
+    return [lines[0], ...lines.slice(1).map(line => `${indentation}${line}`)].join("\n");
+}
+/** 创建 README 中的业务模块目录树。 */
+function createModuleTree(moduleNames) {
+    return moduleNames.map(name => `├── packages/modules/${name}`).join("\n");
+}
+/** 创建 README 中的业务模块目录说明。 */
+function createModuleTableRows(moduleNames) {
+    return moduleNames
+        .map(name => `| \`packages/modules/${name}/\` | 可独立发布的 \`@${name}/admin-module\` 业务 module。 |`)
+        .join("\n");
+}
+/** 将 kebab-case 转换为 camelCase。 */
+function toCamelCase(value) {
+    return value.replace(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
+}
+/** 将 kebab-case 转换为 PascalCase。 */
+function toPascalCase(value) {
+    const camelCase = toCamelCase(value);
+    return `${camelCase.charAt(0).toUpperCase()}${camelCase.slice(1)}`;
+}
+/** 替换模板文本中的全部占位符。 */
+function replaceTokens(value, tokens) {
+    return Object.entries(tokens).reduce((content, [token, replacement]) => content.replaceAll(token, replacement), value);
+}
+/** 判断路径是否存在。 */
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 输出 CLI 使用说明。 */
+function printHelp() {
+    process.stdout.write([
+        "kratos-admin create <project> --module <module[,module...]> [--module <module>] [--with other]",
+        "",
+        "示例:",
+        "  kratos-admin create shop-admin --module shop",
+        "  kratos-admin create shop-admin --module shop,order",
+        "  kratos-admin create shop-admin --module shop --module order",
+        "  kratos-admin create shop-admin --module shop,order --with other",
+        ""
+    ].join("\n"));
+}
+const executedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
+if (import.meta.url === executedPath) {
+    runCli().catch(error => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@liujitcn/kratos-admin-cli",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Create pnpm workspace projects for kratos-admin business modules",
+  "license": "MIT",
+  "homepage": "https://github.com/liujitcn/kratos-admin",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:liujitcn/kratos-admin.git"
+  },
+  "bin": {
+    "kratos-admin": "./dist/index.js"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "files": [
+    "dist/index.d.ts",
+    "dist/index.js",
+    "templates",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:package": "pnpm build",
+    "type:check": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test dist/index.test.js"
+  }
+}

package/templates/business-workspace/README.md

@@ -0,0 +1,63 @@
+<!-- prettier-ignore -->
+# __PROJECT_NAME__
+
+基于 kratos-admin 的独立业务管理端 workspace。默认包含一个薄宿主、System module 和自有 module（**MODULE_NAMES**）；依赖方向为 `apps/admin -> business module -> @liujitcn/kratos-admin-core`。
+
+## 目录与文件
+
+```text
+__PROJECT_NAME__
+├── apps/admin
+│   ├── src
+│   ├── package.json
+│   └── README.md
+__MODULE_TREE__
+├── scripts
+│   └── build-package.mjs
+├── .gitignore
+├── package.json
+├── pnpm-workspace.yaml
+├── README.md
+├── tsconfig.json
+└── turbo.json
+```
+
+| 路径          | 作用                                                |
+| ------------- | --------------------------------------------------- |
+| `apps/admin/` | 可运行的薄宿主，只负责启动和选择启用的业务 module。 |
+
+**MODULE_TABLE_ROWS**
+| `scripts/build-package.mjs` | 生成自有 module 的发布源码和 TypeScript 声明。 |
+| `.gitignore` | 忽略依赖、缓存和构建产物。 |
+| `package.json` | 声明 workspace 公共命令、工具依赖和运行时版本。 |
+| `pnpm-workspace.yaml` | 声明宿主和业务 module 的 workspace 范围。 |
+| `README.md` | 当前 workspace 的目录、文件和开发说明。 |
+| `tsconfig.json` | TypeScript 公共配置以及全部自有 module 的源码映射。 |
+| `turbo.json` | 定义开发、构建、发布构建和类型检查任务关系。 |
+
+每个含 `package.json` 的目录都有同级 README，可继续向对应文件查看更细的职责说明。
+
+## 开发
+
+```bash
+pnpm install
+pnpm dev
+pnpm type:check
+pnpm build
+pnpm build:package
+pnpm package
+```
+
+| 命令                 | 作用                                  |
+| -------------------- | ------------------------------------- |
+| `pnpm dev`           | 启动 `apps/admin` 开发服务器。        |
+| `pnpm type:check`    | 检查宿主和全部业务 module 类型。      |
+| `pnpm build`         | 构建宿主应用。                        |
+| `pnpm build:package` | 生成全部自有 module 的 npm 发布目录。 |
+| `pnpm package`       | 构建全部自有 module 并生成 npm 包。   |
+
+业务 API、RPC、页面和业务组件分别放在 `packages/modules/<module>/src`。业务页面对应的后端菜单组件路径必须使用 module 名称前缀，例如 `shop/index/index`。
+
+宿主 module manifest 位于 `apps/admin/src/module-manifest.ts`，默认先加载 `@liujitcn/kratos-admin-system`，再按创建参数顺序加载自有 module。`apps/admin/src/modules.ts` 加载并默认导出当前全部 module；安装其他 module 后，只需更新宿主依赖和 manifest。
+
+跨模块跳转使用 Vue Router；跨模块代码复用只允许引用对方 `package.json#exports` 公开的 Interface，不使用跨目录相对路径。

package/templates/business-workspace/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.turbo
+*.log
+.DS_Store
+.idea
+.vscode

package/templates/business-workspace/apps/admin/.env

@@ -0,0 +1,6 @@
+VITE_GLOB_APP_TITLE = __MODULE_PASCAL__ Admin
+VITE_PORT = 8848
+VITE_OPEN = true
+VITE_DEVTOOLS = false
+VITE_REPORT = false
+VITE_CODEINSPECTOR = false

package/templates/business-workspace/apps/admin/.env.development

@@ -0,0 +1,7 @@
+VITE_USER_NODE_ENV = development
+VITE_PUBLIC_PATH = /
+VITE_ROUTER_MODE = hash
+VITE_DROP_CONSOLE = true
+VITE_PWA = false
+VITE_API_URL = /api
+VITE_PROXY = [["/api","http://localhost:7001"],["/events","http://localhost:7001"]]

package/templates/business-workspace/apps/admin/.env.production

@@ -0,0 +1,8 @@
+VITE_USER_NODE_ENV = production
+VITE_PUBLIC_PATH = /admin/
+VITE_ROUTER_MODE = hash
+VITE_BUILD_COMPRESS = none
+VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
+VITE_DROP_CONSOLE = true
+VITE_PWA = true
+VITE_API_URL = /api

package/templates/business-workspace/apps/admin/README.md

@@ -0,0 +1,54 @@
+<!-- prettier-ignore -->
+# __APP_PACKAGE__
+
+`__PROJECT_NAME__` 的管理端宿主。该包私有且不实现业务，默认先组合 `@liujitcn/kratos-admin-system`，再组合自有 module **MODULE_PACKAGES** 和所选的其他业务 module。
+
+## 目录与文件
+
+```text
+apps/admin
+├── src
+│   ├── main.ts
+│   ├── module-manifest.ts
+│   ├── modules.ts
+│   └── vite-env.d.ts
+├── .env
+├── .env.development
+├── .env.production
+├── index.html
+├── package.json
+├── README.md
+├── tsconfig.json
+└── vite.config.ts
+```
+
+| 路径                     | 作用                                              |
+| ------------------------ | ------------------------------------------------- |
+| `src/main.ts`            | 将默认导出的全部 module 交给 core 启动 Vue 应用。 |
+| `src/module-manifest.ts` | 统一声明 module 加载器、包名和预构建依赖。        |
+| `src/modules.ts`         | 加载并默认导出当前宿主启用的全部 module。         |
+| `src/vite-env.d.ts`      | 引入 Vite 客户端和 core 全局类型。                |
+| `.env`                   | 所有模式共享的应用标题、端口等环境变量。          |
+| `.env.development`       | 开发模式 API 地址和代理配置。                     |
+| `.env.production`        | 生产模式 API 地址和构建配置。                     |
+| `index.html`             | Vite HTML 入口和应用挂载节点。                    |
+| `package.json`           | 声明宿主命令、core、当前模块和额外模块依赖。      |
+| `README.md`              | 当前宿主的目录和文件说明。                        |
+| `tsconfig.json`          | 宿主 TypeScript 检查配置。                        |
+| `vite.config.ts`         | 组合 core 配置与模块 manifest 派生的构建参数。    |
+
+## 模块组合
+
+`src/module-manifest.ts` 是宿主 module 配置的唯一来源，每个 manifest 项同时声明 npm 包名、运行时加载器和可选预构建依赖。`src/modules.ts` 加载并默认导出全部 module，`vite.config.ts` 从 manifest 派生构建扫描参数。新增或删除 module 时，只需修改宿主依赖和这一份 manifest。
+
+模块注册顺序只影响显式 `staticViews` 替换：后注册模块覆盖先注册模块的同一静态视图键。普通业务页面按 `<module>/<view>` 隔离，不允许通过同名页面覆盖其他模块。
+
+模块之间使用 Vue Router 跳转；跨模块复用代码时，只引用模块公开的 npm 子路径，宿主不得引用模块的 `src` 目录。
+
+## 命令
+
+```bash
+pnpm --filter __APP_PACKAGE__ dev
+pnpm --filter __APP_PACKAGE__ type:check
+pnpm --filter __APP_PACKAGE__ build
+```

package/templates/business-workspace/apps/admin/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <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/business-workspace/apps/admin/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "__APP_PACKAGE__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --configLoader runner",
+    "build": "vue-tsc --noEmit && vite build --configLoader runner --mode production",
+    "preview": "vite preview --configLoader runner",
+    "type:check": "vue-tsc --noEmit --skipLibCheck"
+  },
+  "dependencies": __APP_DEPENDENCIES__
+}

package/templates/business-workspace/apps/admin/src/main.ts

@@ -0,0 +1,4 @@
+import { bootstrapAdminApp } from "@liujitcn/kratos-admin-core";
+import adminModules from "./modules";
+
+void bootstrapAdminApp({ modules: adminModules });

package/templates/business-workspace/apps/admin/src/module-manifest.ts

@@ -0,0 +1,29 @@
+import type { AdminModule } from "@liujitcn/kratos-admin-core";
+
+/** 管理端宿主模块清单项。 */
+export interface AdminModuleManifestItem {
+  /** 业务模块 npm 包名，供 Vite 扫描模块源码。 */
+  packageName: string;
+  /** 加载业务模块运行时定义。 */
+  load: () => Promise<AdminModule>;
+  /** 业务模块需要预构建的依赖。 */
+  optimizeDependencies?: string[];
+}
+
+/** 当前宿主启用的管理端业务模块清单。 */
+export const adminModuleManifest = [
+__MODULE_MANIFEST__
+] satisfies AdminModuleManifestItem[];
+
+/** 当前宿主需要扫描的业务模块包。 */
+export const adminModulePackages = adminModuleManifest.map(item => item.packageName);
+
+/** 当前宿主需要预构建的业务模块依赖。 */
+export const adminModuleOptimizeDependencies = adminModuleManifest.flatMap(item => {
+  return item.optimizeDependencies?.map(dependency => `${item.packageName} > ${dependency}`) ?? [];
+});
+
+/** 加载当前宿主启用的全部业务模块。 */
+export async function loadAdminModules(): Promise<AdminModule[]> {
+  return Promise.all(adminModuleManifest.map(item => item.load()));
+}

package/templates/business-workspace/apps/admin/src/modules.ts

@@ -0,0 +1,6 @@
+import { loadAdminModules } from "./module-manifest";
+
+/** 当前宿主启用的全部管理端业务模块。 */
+const adminModules = await loadAdminModules();
+
+export default adminModules;

package/templates/business-workspace/apps/admin/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/business-workspace/apps/admin/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "vite.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/business-workspace/apps/admin/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineAdminViteConfig } from "@liujitcn/kratos-admin-core/vite.config";
+import { adminModuleOptimizeDependencies, adminModulePackages } from "./src/module-manifest";
+
+export default defineAdminViteConfig({
+  modulePackages: adminModulePackages,
+  optimizeDependencies: adminModuleOptimizeDependencies
+});

package/templates/business-workspace/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "turbo run dev --filter=__APP_PACKAGE__",
+    "build": "turbo run build --filter=__APP_PACKAGE__",
+    "build:package": "turbo run build:package __MODULE_FILTERS__",
+    "type:check": "turbo run type:check",
+    "package": "pnpm build:package && pnpm --recursive __MODULE_FILTERS__ pack"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "sass": "^1.100.0",
+    "turbo": "^2.5.6",
+    "typescript": "6.0.3",
+    "vite": "^8.0.14",
+    "vue-tsc": "^3.3.2"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "packageManager": "pnpm@10.33.4"
+}

package/templates/business-workspace/packages/modules/__MODULE_NAME__/README.md

@@ -0,0 +1,68 @@
+<!-- prettier-ignore -->
+# __MODULE_PACKAGE__
+
+<!-- prettier-ignore -->
+`__PROJECT_NAME__` 的 __MODULE_PASCAL__ 管理端业务模块。API、RPC、页面和业务组件同包维护，可以发布到 npm 后被不同宿主组合使用。
+
+## 目录与文件
+
+```text
+packages/modules/__MODULE_NAME__
+├── src
+│   ├── api
+│   │   └── index.ts              # 请求公开入口；按需新增 base、system 等领域目录
+│   ├── rpc
+│   │   └── README.md             # Proto 生成目录说明
+│   ├── components                # 可选的模块内共享组件
+│   ├── views
+│   │   └── index
+│   │       └── index.vue
+│   ├── index.ts
+│   └── module.ts
+├── package.json
+├── README.md
+├── tsconfig.json
+└── tsconfig.package.json
+```
+
+| 路径                        | 作用                                                            |
+| --------------------------- | --------------------------------------------------------------- |
+| `src/index.ts`              | npm 主入口，导出 `__MODULE_IDENTIFIER__`。                      |
+| `src/module.ts`             | 收集 `src/views/**/*.vue` 并声明名为 `__MODULE_NAME__` 的模块。 |
+| `src/api/index.ts`          | 当前模块请求导出入口；具体文件按 Proto 一级领域组织。           |
+| `src/rpc/README.md`         | 当前模块 RPC 生成目录说明，生成类型通过模块包子路径公开。       |
+| `src/views/index/index.vue` | 模板自带的模块首页。                                            |
+| `package.json`              | 声明依赖、模块入口、API/RPC 子路径和 npm 发布配置。             |
+| `README.md`                 | 当前业务模块的目录、文件和接入说明。                            |
+| `tsconfig.json`             | 开发态类型检查配置。                                            |
+| `tsconfig.package.json`     | npm 发布声明文件生成配置。                                      |
+
+## 开发约束
+
+- API 放在 `src/api/<proto-domain>`，例如 `src/api/base`、`src/api/system`；RPC 保留 `src/rpc/<proto-domain>/<version>` 等完整生成层级，不扁平化。
+- 页面放在 `src/views`。页面私有组件就近放置，需要模块内多个页面复用时再创建 `src/components`。
+- 底座能力通过 `@liujitcn/kratos-admin-core` 的公开子路径引用，不要依赖 core 源码目录。
+- 跨模块页面跳转使用 Vue Router；跨模块代码复用需要对方先提供 npm 公开导出。
+- 新增页面后，动态菜单组件路径必须使用 `__MODULE_NAME__/` 模块前缀；模板首页对应 `__MODULE_NAME__/index/index`，不兼容 `index/index`。
+- 需要替换 core 静态页面时，使用 core 导出的 `ADMIN_STATIC_VIEWS` 在模块 `staticViews` 中显式映射页面。
+
+模块运行时 Interface 是 `src/index.ts` 导出的 `__MODULE_IDENTIFIER__`。API 和 RPC 通过 `package.json#exports` 公开；页面只通过 `AdminModule.views` 注册，不作为 npm 子路径导出。组件需要真实跨模块复用时，按具体文件增加显式导出，不提供 `components/*` 通配入口。模块内部文件不因位于 `src` 下自动成为公共 Interface。
+
+宿主接入：
+
+```ts
+export const adminModuleManifest = [
+  {
+    packageName: "__MODULE_PACKAGE__",
+    load: async () => (await import("__MODULE_PACKAGE__")).__MODULE_IDENTIFIER__
+  }
+];
+```
+
+## 命令
+
+```bash
+pnpm --filter __MODULE_PACKAGE__ type:check
+pnpm --filter __MODULE_PACKAGE__ build:package
+pnpm --filter __MODULE_PACKAGE__ pack
+```

package/templates/business-workspace/packages/modules/__MODULE_NAME__/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "__MODULE_PACKAGE__",
+  "private": false,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "__MODULE_PASCAL__ admin business module",
+  "scripts": {
+    "build": "pnpm build:package",
+    "build:package": "node ../../../scripts/build-package.mjs .",
+    "type:check": "vue-tsc --noEmit --skipLibCheck",
+    "prepack": "pnpm build:package"
+  },
+  "devDependencies": {
+    "@liujitcn/kratos-admin-core": "__CORE_VERSION__"
+  },
+  "peerDependencies": {
+    "@liujitcn/kratos-admin-core": "__CORE_VERSION__",
+    "vue": "^3.5.35"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/package/declarations/index.d.ts",
+      "default": "./dist/package/src/index.ts"
+    },
+    "./api/*": {
+      "types": "./dist/package/declarations/src/api/*.d.ts",
+      "default": "./dist/package/src/api/*.ts"
+    },
+    "./rpc/*": {
+      "types": "./dist/package/declarations/src/rpc/*.d.ts",
+      "default": "./dist/package/src/rpc/*.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/package"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/business-workspace/packages/modules/__MODULE_NAME__/src/api/index.ts

@@ -0,0 +1,2 @@
+/** __MODULE_PASCAL__ 模块请求统一从此目录导出。 */
+export {};

package/templates/business-workspace/packages/modules/__MODULE_NAME__/src/index.ts

@@ -0,0 +1 @@
+export { __MODULE_IDENTIFIER__ } from "./module";

package/templates/business-workspace/packages/modules/__MODULE_NAME__/src/module.ts

@@ -0,0 +1,10 @@
+import type { Component } from "vue";
+import { defineAdminModule } from "@liujitcn/kratos-admin-core";
+
+const viewModules = import.meta.glob<{ default: Component }>("./views/**/*.vue");
+
+/** __MODULE_PASCAL__ 管理端业务模块。 */
+export const __MODULE_IDENTIFIER__ = defineAdminModule({
+  name: "__MODULE_NAME__",
+  views: viewModules
+});

package/templates/business-workspace/packages/modules/__MODULE_NAME__/src/rpc/README.md

@@ -0,0 +1,14 @@
+# RPC
+
+当前业务模块的 Proto TypeScript 生成目录。目录必须保留 Proto 完整层级，例如：
+
+```text
+src/rpc
+├── base/v1
+├── common/v1
+└── system/admin/v1
+```
+
+只生成当前模块 API 和页面实际依赖的服务及其传递类型。生成文件属于本模块，通过模块包的 `./rpc/*` 子路径公开；不要把业务 RPC 生成到 core，也不要在模块中重复手写等价业务模型。
+
+RPC 文件只能由接入项目约定的生成命令更新，禁止手工修改。生成器输出的相对导入保持原样，不为目录美观将 RPC 扁平化。

package/templates/business-workspace/packages/modules/__MODULE_NAME__/src/views/index/index.vue

@@ -0,0 +1,15 @@
+<template>
+  <section class="module-page">
+    <h2>__MODULE_PASCAL__</h2>
+  </section>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: "__MODULE_PASCAL__Index" });
+</script>
+
+<style scoped lang="scss">
+.module-page {
+  padding: 20px;
+}
+</style>

package/templates/business-workspace/packages/modules/__MODULE_NAME__/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": [
+    "node_modules/@liujitcn/kratos-admin-core/types/generated/auto-imports.d.ts",
+    "node_modules/@liujitcn/kratos-admin-core/types/generated/components.d.ts",
+    "src/**/*.ts",
+    "src/**/*.d.ts",
+    "src/**/*.tsx",
+    "src/**/*.vue"
+  ],
+  "exclude": ["node_modules", "dist", "**/*.js"]
+}

package/templates/business-workspace/packages/modules/__MODULE_NAME__/tsconfig.package.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": false,
+    "outDir": "./dist/declarations",
+    "declarationDir": "./dist/declarations"
+  }
+}

package/templates/business-workspace/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - apps/*
+  - packages/*
+  - packages/modules/*

package/templates/business-workspace/scripts/build-package.mjs

@@ -0,0 +1,21 @@
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+const packageRoot = resolve(process.cwd(), process.argv[2] ?? ".");
+const declarationRoot = resolve(packageRoot, "dist/declarations");
+const outputRoot = resolve(packageRoot, "dist/package");
+const packageJson = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+
+await rm(outputRoot, { recursive: true, force: true });
+await rm(declarationRoot, { recursive: true, force: true });
+execFileSync("pnpm", ["exec", "vue-tsc", "-p", "tsconfig.package.json"], {
+  cwd: packageRoot,
+  stdio: "inherit"
+});
+await mkdir(resolve(outputRoot, "src"), { recursive: true });
+await cp(resolve(packageRoot, "src"), resolve(outputRoot, "src"), { recursive: true });
+await cp(declarationRoot, resolve(outputRoot, "declarations"), { recursive: true });
+await writeFile(resolve(outputRoot, "declarations/index.d.ts"), 'export * from "./src/index";\n');
+await rm(declarationRoot, { recursive: true, force: true });
+console.log(`已生成 ${packageJson.name} 发布文件`);

package/templates/business-workspace/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "types": ["vite/client", "node"],
+    "strict": true,
+    "noImplicitAny": false,
+    "jsx": "preserve",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["ESNext", "DOM"],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "ignoreDeprecations": "6.0",
+    "baseUrl": ".",
+    "paths": __MODULE_PATHS__
+  },
+  "files": []
+}

package/templates/business-workspace/turbo.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "build:package": {
+      "dependsOn": ["^build:package"],
+      "outputs": ["dist/package/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "type:check": {
+      "dependsOn": ["^type:check"],
+      "outputs": []
+    }
+  }
+}