@4399ywkf/cli 1.0.7 → 1.0.9

package/dist/templates/docs/DIRECTORY_STRUCTURE.md

@@ -0,0 +1,141 @@
+# 企业脚手架目录规划说明
+
+## 1. 现状概览
+
+```
+app/
+├── config/           # 构建 + 运行时配置混放
+│   ├── env/          # 环境变量文件
+│   ├── jwt/          # 运行时
+│   ├── request/      # 运行时
+│   ├── router/       # 渲染入口（renderClient）
+│   └── rspack/       # 构建
+├── locales/          # 文案 JSON（与 src/locales 双源）
+├── public/
+├── scripts/
+├── src/
+│   ├── bootstrap/
+│   ├── color/        # 设计 token 色板
+│   ├── components/
+│   ├── config/       # 仅 env.ts（与根 config 易混淆）
+│   ├── const/
+│   ├── layout/
+│   ├── locales/      # i18n 逻辑 + TS 文案
+│   ├── micro/
+│   ├── pages/
+│   ├── routes.tsx
+│   ├── styles/       # 全局样式 + theme 算法
+│   ├── types/
+│   └── utils/
+└── store/            # 与 src 平级
+    ├── middleware/
+    └── user/
+```
+
+---
+
+## 2. 结论：整体可用，有几处需约定或收敛
+
+- **做得好的**：`store` 独立、按 agent/slice 拆分；`pages` + `layout` + `components` 分层清晰；构建配置集中在 `config/rspack`、环境变量在 `config/env`，便于维护。
+- **需要约定的**：根目录 `config` 与 `src/config` 的职责边界、`locales` 双源、`color`/`styles`/`theme` 的归属。
+- **可优化项**：收敛「配置与文案」的入口、统一命名（如 `const` vs `constants`）、可选能力（如 `micro`）在文档中说明。
+
+---
+
+## 3. 问题与建议
+
+### 3.1 config 双位置（根 config vs src/config）
+
+| 位置       | 内容           | 问题                         |
+|------------|----------------|------------------------------|
+| 根 `config/` | env 文件、rspack、request、jwt、router | 构建与运行时混在同一层       |
+| `src/config/` | 仅 `env.ts`（zod 解析）     | 新人易困惑「改 env 改哪边」 |
+
+**建议（二选一或折中）：**
+
+- **方案 A（推荐）**：约定「根 `config/` = 仅构建与环境文件」：只放 `env/`、`rspack/`；把 `request/`、`jwt/`、`router/` 迁到 `src/config/`（或 `src/core/`），alias 保持 `@config` 指向 `src/config`，构建配置单独用 `config/rspack` 路径。这样「构建配置在根 config，运行时配置在 src」边界清晰。
+- **方案 B**：维持现状，在 README 中明确写清：「环境变量与构建用根 `config/`，运行时解析用 `src/config/env.ts`；请求/路由等由根 `config/` 的模块提供」，减少误改。
+
+### 3.2 locales 双源（根 locales vs src/locales）
+
+- 根 `locales/zh-CN/common.json` 与 `src/locales/default/common.ts` 内容重复，且有脚本把 TS 转 JSON。
+- **建议**：选单一数据源。若以 i18n 代码为主，保留 `src/locales`，删除根 `locales/` 和转换脚本，构建或运行时从 `src/locales` 生成/加载；若以 JSON 为主，则只保留根 `locales/`，在 README 中说明「文案只放根 locales」。
+
+### 3.3 store 与 src 平级
+
+- `store/` 在项目根与 `src/` 平级，符合「状态与 UI 分离」的常见企业习惯；alias `@store` 指向根下 `store` 也合理。
+- **建议**：保持现状；在 README 或本说明中写一句：「业务 UI 在 `src/`，领域状态在 `store/`，按 agent/slice 拆分」，避免被误挪进 `src`。
+
+### 3.4 src 内部：color / styles / theme
+
+- `color/`：色板与 token 数据；`styles/`：全局样式、antd 覆盖、**theme 算法与 customToken**；`types/` 中还有 `customStylish`、`customToken`。
+- 问题：主题相关分散在 `color`、`styles/theme`、`styles`、`types`，新人找「改主题」入口不直观。
+- **建议**：
+  - 要么保留 `color/` 但在 README 标明「设计 token 与色板，被 `styles/theme` 消费」；
+  - 要么将 `color/` 收进 `styles/theme/`（如 `styles/theme/color/`），入口统一为 `styles/theme`，减少顶层目录。
+- 不强求一步到位，但需在文档中画一条线：**主题与 token 的入口是 `src/styles/theme`（及可选 `src/color`）**。
+
+### 3.5 横切目录：const / types / utils
+
+- `const/`、`types/`、`utils/` 是常见横切层，结构合理。
+- 小问题：`const/constants.ts` 当前为空；`types` 里既有全局类型又有与 theme 强相关的类型。
+- **建议**：`const` 保留，删除或补全 `constants.ts`，避免空文件；在 README 或本说明中约定「全局业务常量放 `const/`，组件/页面私有常量随模块」。`types` 可注明「与 theme/样式强相关的类型与 `styles/theme` 同目录或在本目录集中维护」，二选一即可。
+
+### 3.6 可选能力：micro、bootstrap
+
+- `micro/` 仅 Garfish，已作为可选项；`bootstrap/` 仅应用启动逻辑。
+- **建议**：保持 `micro/` 在 `src` 下，README 中说明「微前端为可选项，入口与配置见 xxx」。`bootstrap/` 可保留；若希望根入口更短，可把 `bootstrapWithEnv()` 的实现迁到 `src/index.tsx` 或 `src/config/bootstrap.ts`，只保留单文件也可。
+
+### 3.7 pages 与路由
+
+- `pages/` 下有 404、base、index 等；路由定义在 `src/routes.tsx`，渲染入口在 `config/router/index.tsx`。
+- **建议**：约定「路由表仅由 `src/routes.tsx` 维护；`config/router` 只负责 `renderClient` 与挂载」，在 README 或本说明写清，避免在 `config/router` 里再配路由造成双源。
+
+### 3.8 根目录与脚本
+
+- 根目录的 `tsconfig`、`tailwind`、`postcss`、`scripts/` 等符合常规，无需调整。
+- `scripts/` 若仅剩「locales 转 JSON」且已决定废弃根 `locales/`，可删除该脚本；否则保留并注明用途。
+
+---
+
+## 4. 推荐约定（最小改动版）
+
+在不做大范围迁移的前提下，建议先做「约定文档化 + 少量收敛」：
+
+1. **配置**：在 README 中写清「根 `config/` = 构建与环境文件；运行时配置与请求/路由实现来自 `@config`（当前指向根 config，或你们改为 src/config）」。  
+2. **文案**：选定 locales 单一数据源（推荐 `src/locales`），删除或弃用另一侧及转换脚本。  
+3. **主题**：在 README 中标明「主题与 token 入口：`src/styles/theme`，色板数据见 `src/color`（可选）」。  
+4. **store**：说明「全局状态在根 `store/`，按 agent/slice 划分，与 `src` 并列」。  
+5. **路由**：说明「路由表只在 `src/routes.tsx` 维护；`config/router` 仅负责渲染与挂载」。  
+6. **空文件**：删除或补全 `src/const/constants.ts`。
+
+若后续要做更大调整，再考虑：把 request/jwt/router 迁入 `src/config` 或 `src/core`、将 `color` 并入 `styles/theme` 等。
+
+---
+
+## 5. 可选：目标结构示意（供长期演进参考）
+
+```
+app/
+├── config/                 # 仅构建与环境
+│   ├── env/
+│   └── rspack/
+├── public/
+├── scripts/
+├── src/
+│   ├── config/             # 运行时：env 解析、request、router 挂载等
+│   ├── core/                # 可选：bootstrap、微前端入口等
+│   ├── layout/
+│   ├── pages/
+│   ├── components/
+│   ├── styles/              # 全局样式 + theme（含 token/color 或引用）
+│   ├── locales/             # 单一 i18n 数据源
+│   ├── const/
+│   ├── types/
+│   ├── utils/
+│   ├── routes.tsx
+│   └── index.tsx
+└── store/
+```
+
+当前模板不必立刻改成上述结构，可先落实「约定 + 文档 + 删除冗余」，再按团队习惯逐步演进。

package/dist/templates/docs/glossary.md

@@ -0,0 +1,11 @@
+# Glossary
+
+以下是一些词汇的固定翻译：
+
+| develop key | zh-CN (中文) | en-US(English) |
+| ----------- | ------------ | -------------- |
+| agent       | 助理         | Agent          |
+| agentGroup  | 群组         | Group          |
+| page        | 文稿         | Page           |
+| topic       | 话题         | Topic          |
+| thread      | 子话题       | Thread         |

package/dist/templates/env/.env.public.tpl

@@ -1,5 +1,5 @@
 API_PREFIX="/api"
-API_TIMEOUT=60 * 1000
+API_TIMEOUT=60000
 
 COOKIE_NAME='ywkf_jwt'
 
@@ -9,23 +9,6 @@ OUTPUT_PATH='dist'
 BASENAME='/'
 
 PUBLIC_PATH='/s{{{ name }}}/'
-VERSION_NOTIFY_TIME=30000
-
-
-# Sentry 配置 - (官网)
-# REACT_APP_SENTRY_DSN="https://95add4dc797c22aa2224494e4abd4d71@o4509466151878656.ingest.us.sentry.io/4509466153058304"
-# SENTRY_PROJECT="javascript-react"
-# SENTRY_ORG="test-x6m"
-# SENTRY_AUTH_TOKEN="d477b94cfe375f5b4e4e88ac4fc15a8be8557652cea424710b6f7f19be4f0b3d"
-# SENTRY_URL="https://test-x6m.sentry.io/"
 
 # 帮助中心
-HELP_CENTER_URL="https://im-support.gz4399.com/"
-
-# 是否开启Sentry
-SENTRY_ENABLED='{{SENTRY_ENABLED}}'  
-REACT_APP_SENTRY_DSN='{{SENTRY_DSN}}'
-SENTRY_PROJECT='{{{ name }}}'
-SENTRY_ORG="sentry"
-SENTRY_AUTH_TOKEN="f13c66cd7a3629c8324cceb62fdb65aae1f337abbec4ebbadbe0a22447708994"
-SENTRY_URL="https://sentry.gz4399.com/"
+HELP_CENTER_URL="https://im-support.gz4399.com/"

package/dist/templates/env.ts

@@ -1,3 +1,84 @@
-export const isDev = process.env.NODE_ENV === 'development';
+import { z } from "zod";
 
-export const isOnServerSide = typeof window === 'undefined';
+/**
+ * 环境变量 Schema 定义
+ */
+const envSchema = z.object({
+  // Node 环境
+  NODE_ENV: z
+    .enum(["development", "test", "testDevelopment", "production"])
+    .default("development"),
+
+  // 应用配置
+  APP_NAME: z.string().min(1, "应用名称不能为空").default("app"),
+  APP_CNAME: z.string().default("应用"),
+  BASENAME: z.string().optional(),
+
+  // API 配置
+  API_PREFIX: z.string().default("/api"),
+  API_TIMEOUT: z
+    .string()
+    .transform(Number)
+    .pipe(z.number().positive())
+    .default(30000),
+
+  // Cookie 配置
+  COOKIE_NAME: z.string().default("access_token"),
+
+  // 其他配置
+  HELP_CENTER_URL: z.string().url().optional(),
+  OUTPUT_PATH: z.string().default("dist"),
+  PUBLIC_PATH: z.string().default("/"),
+});
+
+/**
+ * 安全解析环境变量（开发模式下使用默认值）
+ */
+function safeParseEnv() {
+  const result = envSchema.safeParse(process.env);
+
+  if (!result.success) {
+    if (process.env.NODE_ENV === "production") {
+      // 生产环境严格校验
+      console.error("❌ 环境变量验证失败:");
+      result.error.issues.forEach((err) => {
+        console.error(`  - ${err.path.join(".")}: ${err.message}`);
+      });
+      throw new Error("环境变量配置错误");
+    } else {
+      // 开发环境警告但不中断
+      console.warn("⚠️ 环境变量验证警告:");
+      result.error.issues.forEach((err) => {
+        console.warn(`  - ${err.path.join(".")}: ${err.message}`);
+      });
+    }
+  }
+
+  return result.success ? result.data : envSchema.parse({});
+}
+
+/**
+ * 导出类型安全的环境变量
+ */
+export const env = safeParseEnv();
+
+/**
+ * 环境变量类型
+ */
+export type Env = z.infer<typeof envSchema>;
+
+/**
+ * 工具函数：判断是否为开发环境
+ */
+export const isDev = env.NODE_ENV === "development";
+
+/**
+ * 工具函数：判断是否为生产环境
+ */
+export const isProd = env.NODE_ENV === "production";
+
+/**
+ * 工具函数：判断是否为测试环境
+ */
+export const isTest =
+  env.NODE_ENV === "test" || env.NODE_ENV === "testDevelopment";

package/dist/templates/error-handler.ts

@@ -0,0 +1,67 @@
+import { message as antdMessage } from "antd";
+import type { AxiosError } from "axios";
+import type { RequestConfig, ApiResponse } from "./types";
+
+/**
+ * 错误处理器
+ */
+export class ErrorHandler {
+  /**
+   * 处理请求错误
+   */
+  handle(error: any, config?: RequestConfig): void {
+    const messageConfig = config?.message;
+
+    // 如果明确禁用错误提示
+    if (messageConfig?.showError === false) {
+      return;
+    }
+
+    const axiosError = error as AxiosError<ApiResponse>;
+    let errorMessage = messageConfig?.errorMessage;
+
+    // 如果没有自定义错误消息，使用默认逻辑
+    if (!errorMessage) {
+      if (axiosError.response) {
+        const { status, data } = axiosError.response;
+
+        // 优先使用后端返回的消息
+        errorMessage = data?.message;
+
+        // 如果后端没有返回消息，使用默认消息
+        if (!errorMessage) {
+          errorMessage = this.getDefaultErrorMessage(status);
+        }
+      } else if (axiosError.request) {
+        errorMessage = "网络错误，请检查您的网络连接";
+      } else {
+        errorMessage = axiosError.message || "请求失败";
+      }
+    }
+
+    // 显示错误提示
+    antdMessage.error(errorMessage);
+  }
+
+  /**
+   * 获取默认错误消息
+   */
+  private getDefaultErrorMessage(status: number): string {
+    const errorMessages: Record<number, string> = {
+      400: "请求参数错误",
+      401: "未授权，请重新登录",
+      403: "拒绝访问",
+      404: "请求的资源不存在",
+      405: "请求方法不允许",
+      408: "请求超时",
+      500: "服务器内部错误",
+      502: "网关错误",
+      503: "服务暂时不可用",
+      504: "网关超时",
+    };
+
+    return errorMessages[status] || `请求失败 (${status})`;
+  }
+}
+
+export const errorHandler = new ErrorHandler();

package/dist/templates/flattenLocaleKeys.ts

@@ -0,0 +1,139 @@
+/* eslint-disable unicorn/prefer-top-level-await */
+import prettier from '@prettier/sync';
+import { consola } from 'consola';
+import { colors } from 'consola/utils';
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { toLodashPath } from '../../src/locales/utils';
+import { localeDir, localeDirJsonList, localesDir, srcDefaultLocales } from './const';
+
+const prettierOptions = prettier.resolveConfig(resolve(__dirname, '../../.prettierrc.js')) ?? {};
+
+const DEFAULT_SKIP_FILES = new Set(['index.ts', 'models.ts', 'providers.ts']);
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (!value || typeof value !== 'object') return false;
+  return Object.prototype.toString.call(value) === '[object Object]';
+};
+
+const shouldPreserveObject = (value: Record<string, unknown>) => {
+  const keys = Object.keys(value);
+  if (keys.length === 0) return true;
+  return keys.every((key) => /^\d+$/.test(key));
+};
+
+const flattenObject = (input: Record<string, unknown>) => {
+  const output: Record<string, unknown> = {};
+
+  const addEntry = (pathSegments: Array<number | string>, value: unknown) => {
+    const key = toLodashPath(pathSegments);
+    if (Object.prototype.hasOwnProperty.call(output, key)) {
+      throw new Error(`Duplicate i18n key detected: ${key}`);
+    }
+    output[key] = value;
+  };
+
+  const visit = (value: unknown, pathSegments: Array<number | string>) => {
+    if (Array.isArray(value)) {
+      addEntry(pathSegments, value);
+      return;
+    }
+
+    if (isPlainObject(value)) {
+      if (shouldPreserveObject(value)) {
+        addEntry(pathSegments, value);
+        return;
+      }
+
+      const entries = Object.entries(value);
+      if (entries.length === 0) {
+        addEntry(pathSegments, value);
+        return;
+      }
+
+      for (const [childKey, childValue] of entries) {
+        visit(childValue, [...pathSegments, childKey]);
+      }
+      return;
+    }
+
+    addEntry(pathSegments, value);
+  };
+
+  for (const [key, value] of Object.entries(input)) {
+    visit(value, [key]);
+  }
+
+  return output;
+};
+
+const writeTs = (filePath: string, data: Record<string, unknown>) => {
+  const content = `export default ${JSON.stringify(data, null, 2)};\n`;
+  const formatted = prettier.format(content, {
+    ...prettierOptions,
+    parser: 'typescript',
+  });
+  writeFileSync(filePath, formatted, 'utf8');
+};
+
+const writeJson = (filePath: string, data: Record<string, unknown>) => {
+  const json = JSON.stringify(data, null, 2);
+  const formatted = prettier.format(json, {
+    ...prettierOptions,
+    parser: 'json',
+  });
+  writeFileSync(filePath, formatted, 'utf8');
+};
+
+const flattenDefaultLocales = async () => {
+  const files = readdirSync(srcDefaultLocales).filter((file) => file.endsWith('.ts'));
+
+  for (const file of files) {
+    if (DEFAULT_SKIP_FILES.has(file)) continue;
+
+    const filePath = resolve(srcDefaultLocales, file);
+    const fileUrl = pathToFileURL(filePath).href;
+    const loaded = await import(fileUrl);
+    const data = loaded.default ?? loaded;
+
+    const flat = flattenObject(data as Record<string, unknown>);
+    writeTs(filePath, flat);
+    consola.success(colors.cyan(file), colors.gray('flattened'));
+  }
+};
+
+const flattenLocaleJsons = () => {
+  const localeFolders = readdirSync(localesDir).filter((dir) =>
+    statSync(localeDir(dir)).isDirectory(),
+  );
+
+  for (const locale of localeFolders) {
+    const jsonFiles = localeDirJsonList(locale);
+    for (const jsonFile of jsonFiles) {
+      const filePath = resolve(localeDir(locale), jsonFile);
+      const raw = readFileSync(filePath, 'utf8');
+      const data = JSON.parse(raw);
+      const flat = flattenObject(data);
+      writeJson(filePath, flat);
+      consola.success(colors.cyan(`${locale}/${jsonFile}`), colors.gray('flattened'));
+    }
+  }
+};
+
+const run = async () => {
+  consola.start('Flattening src/locales/default...');
+  await flattenDefaultLocales();
+
+  consola.start('Flattening locales JSON files...');
+  flattenLocaleJsons();
+
+  consola.success('Flattening completed.');
+};
+
+run().catch((error) => {
+  consola.error(error);
+  // eslint-disable-next-line unicorn/no-process-exit
+  process.exit(1);
+});

package/dist/templates/garfish.ts

@@ -0,0 +1,53 @@
+import type { Root } from "react-dom";
+import { renderClient } from "@config/router";
+import { createRouter } from "@/routes";
+
+interface GarfishProvider {
+  render: (props: { basename: string }) => void;
+  destroy: () => void;
+}
+
+interface RenderContext {
+  basename?: string;
+  rootElement: HTMLElement | null;
+}
+
+/**
+ * Garfish 微前端生命周期适配器
+ */
+export function createGarfishProvider(appName: string): GarfishProvider {
+  let root: Root | null = null;
+
+  return {
+    render({ basename }: { basename: string }) {
+      const context: RenderContext = {
+        basename,
+        rootElement: document.getElementById(appName) ?? document.body,
+      };
+
+      root = renderClient(context);
+
+      // 向主应用通知路由信息
+      if (window.Garfish?.channel) {
+        window.Garfish.channel.emit("router", {
+          name: appName,
+          routes: createRouter(basename),
+        });
+      }
+    },
+
+    destroy() {
+      if (root) {
+        root.unmount();
+        root = null;
+      }
+    },
+  };
+}
+
+/**
+ * 判断是否在微前端环境中运行
+ */
+export function isMicroApp(): boolean {
+  return typeof window !== "undefined" && Boolean(window.__GARFISH__);
+}

package/dist/templates/genDefaultLocale.ts

@@ -0,0 +1,19 @@
+import { consola } from 'consola';
+import { colors } from 'consola/utils';
+
+import { entryLocaleJsonFilepath, i18nConfig, srcDefaultLocales } from './const';
+import { tagWhite, writeJSONWithPrettier } from './utils';
+
+export const genDefaultLocale = () => {
+  consola.info(`Default locale is ${i18nConfig.entryLocale}...`);
+
+  const resources = require(srcDefaultLocales);
+  const data = Object.entries(resources.default);
+  consola.start(`Generate default locale json, found ${data.length} namespaces...`);
+
+  for (const [ns, value] of data) {
+    const filepath = entryLocaleJsonFilepath(`${ns}.json`);
+    writeJSONWithPrettier(filepath, value);
+    consola.success(tagWhite(ns), colors.gray(filepath));
+  }
+};

package/dist/templates/genDiff.ts

@@ -0,0 +1,49 @@
+import { consola } from 'consola';
+import { colors } from 'consola/utils';
+import { unset } from 'es-toolkit/compat';
+import { diff } from 'just-diff';
+import { existsSync } from 'node:fs';
+
+import {
+  entryLocaleJsonFilepath,
+  i18nConfig,
+  outputLocaleJsonFilepath,
+  srcDefaultLocales,
+} from './const';
+import { readJSON, tagWhite, writeJSONWithPrettier } from './utils';
+
+export const genDiff = () => {
+  consola.start(`Remove diff analysis...`);
+
+  const resources = require(srcDefaultLocales);
+  const data = Object.entries(resources.default);
+
+  for (const [ns, devJSON] of data) {
+    const filepath = entryLocaleJsonFilepath(`${ns}.json`);
+    if (!existsSync(filepath)) continue;
+    const previousProdJSON = readJSON(filepath);
+
+    const diffResult = diff(previousProdJSON, devJSON as any);
+    if (diffResult.length === 0) {
+      consola.success(tagWhite(ns), colors.gray(filepath));
+      continue;
+    }
+
+    const clearLocals = [];
+
+    for (const locale of i18nConfig.outputLocales) {
+      const localeFilepath = outputLocaleJsonFilepath(locale, `${ns}.json`);
+      if (!existsSync(localeFilepath)) continue;
+      const localeJSON = readJSON(localeFilepath);
+
+      for (const item of diffResult) {
+        unset(localeJSON, item.path);
+      }
+
+      writeJSONWithPrettier(localeFilepath, localeJSON);
+      clearLocals.push(locale);
+    }
+    consola.info('clear', clearLocals);
+    consola.success(tagWhite(ns), colors.gray(filepath));
+  }
+};

package/dist/templates/global.d.ts

@@ -0,0 +1,19 @@
+import type { Env } from "@/config/env";
+
+declare global {
+  interface Window {
+    __GARFISH__?: boolean;
+    Garfish?: {
+      channel: {
+        emit: (event: string, data: any) => void;
+        on: (event: string, handler: (data: any) => void) => void;
+      };
+    };
+  }
+
+  namespace NodeJS {
+    interface ProcessEnv extends Env {}
+  }
+}
+
+export {};

package/dist/templates/glossary.md

@@ -0,0 +1,11 @@
+# Glossary
+
+以下是一些词汇的固定翻译：
+
+| develop key | zh-CN (中文) | en-US(English) |
+| ----------- | ------------ | -------------- |
+| agent       | 助理         | Agent          |
+| agentGroup  | 群组         | Group          |
+| page        | 文稿         | Page           |
+| topic       | 话题         | Topic          |
+| thread      | 子话题       | Thread         |

package/dist/templates/i18nConfig.ts

@@ -0,0 +1,7 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const config = require('../../.i18nrc');
+
+export default config;