@qlover/create-app 0.6.2 → 0.7.0

package/dist/templates/react-app/README.md

@@ -2,6 +2,8 @@
 
 一个现代化的 React 前端项目模板，集成了多项实用功能和最佳实践。
 
+[English](./README.en.md)
+
 ## 🌟 特性亮点
 
 - 🚀 基于 Vite 的快速开发体验
@@ -64,6 +66,29 @@ pnpm build
 pnpm test
 ```
 
+## 📚 文档指南
+
+项目提供了详细的开发文档，涵盖了所有主要功能和最佳实践：
+
+### 基础文档
+- [项目概述](./docs/zh/index.md) - 项目整体介绍和快速开始指南
+- [项目结构](./docs/zh/project-structure.md) - 详细的项目目录结构说明
+- [开发指南](./docs/zh/development-guide.md) - 项目开发规范和最佳实践
+- [环境配置](./docs/zh/env.md) - 环境变量和配置管理说明
+- [全局配置](./docs/zh/global.md) - 应用全局配置和设置说明
+
+### 核心功能
+- [启动流程](./docs/zh/bootstrap.md) - 应用启动流程和生命周期管理
+- [IOC容器](./docs/zh/ioc.md) - 依赖注入系统的使用说明
+- [路由管理](./docs/zh/router.md) - 路由配置和页面导航说明
+- [状态管理](./docs/zh/store.md) - 应用状态管理方案说明
+- [请求处理](./docs/zh/request.md) - API 请求处理机制说明
+
+### 功能扩展
+- [国际化](./docs/zh/i18n.md) - 多语言支持和翻译管理
+- [主题系统](./docs/zh/theme.md) - 主题配置和暗色模式支持
+- [TypeScript指南](./docs/zh/typescript-guide.md) - TypeScript 使用规范和最佳实践
+
 ## 🔨 核心功能
 
 ### IOC 容器
@@ -72,15 +97,15 @@ pnpm test
 - 支持服务自动注册和依赖管理
 - 提供完整的类型推导
 
-### env 配置注入
+### 环境配置
 
 [vite 环境变量和模式](https://cn.vite.dev/guide/env-and-mode#env-variables-and-modes)
 
 `vite dev` 默认 NODE_ENV 表示为 development, 他会加载可能的 `.env[mode]` 文件, 比如 .env.local -> .env
 
-`vite build`默认 NODE_ENV 表示为 production, 他会加载可能的 `.env[mode]` 文件, 比如 .env.production -> .env
+`vite build` 默认 NODE_ENV 表示为 production, 他会加载可能的 `.env[mode]` 文件, 比如 .env.production -> .env
 
-Nodejs NODE_ENV 只支持 development,production,test
+Node.js NODE_ENV 只支持 development,production,test
 
 这个和 vite 中的 mode 是完全不一样的, mode 可以根据 `--mode` 指定不同模式，来加载不同的 env 配置
 
@@ -99,127 +124,6 @@ vite dev --mode local # 加载 .env.local
 - URL 路径语言检测和切换
 - 内置语言切换组件
 
-#### 国际化配置
-
-项目使用 `@brain-toolkit/ts2locales` 插件从 TypeScript 注释自动生成国际化资源：
-
-```typescript
-// config/Identifier/I18n.ts
-export const Messages = {
-  /**
-   * @description Home page welcome message
-   * @localZh 欢迎来到主页
-   * @localEn Welcome to the home page
-   */
-  HOME_WELCOME: 'home.welcome',
-
-  /**
-   * @description Get started button text
-   * @localZh 开始使用
-   * @localEn Get Started
-   */
-  HOME_GET_STARTED: 'home.get_started'
-};
-```
-
-Vite 插件配置：
-
-```typescript
-// vite.config.ts
-import ts2Locales from '@brain-toolkit/ts2locales/vite';
-import i18nConfig from './config/i18n';
-
-export default defineConfig({
-  plugins: [
-    ts2Locales({
-      locales: i18nConfig.supportedLngs,
-      options: [
-        {
-          source: './config/Identifier/error.ts',
-          target: './public/locales/{{lng}}/common.json'
-        },
-        {
-          source: './config/Identifier/index.ts',
-          target: './public/locales/{{lng}}/common.json'
-        }
-      ]
-    })
-  ]
-});
-```
-
-#### 国际化服务
-
-项目提供了 `I18nService` 用于管理国际化状态和语言切换：
-
-```typescript
-import { I18nService } from '@/base/services/I18nService';
-
-// 获取当前语言
-const currentLang = I18nService.getCurrentLanguage();
-
-// 切换语言
-await i18nService.changeLanguage('zh');
-```
-
-#### 在组件中使用
-
-```typescript
-import { useBaseRoutePage } from '@/uikit/contexts/BaseRouteContext';
-import * as i18nKeys from '@config/Identifier';
-
-function MyComponent() {
-  const { t } = useBaseRoutePage();
-
-  return (
-    <div>
-      <h1>{t(i18nKeys.HOME_WELCOME)}</h1>
-      <button>{t(i18nKeys.HOME_GET_STARTED)}</button>
-    </div>
-  );
-}
-```
-
-#### 语言切换组件
-
-项目提供了开箱即用的语言切换组件：
-
-```typescript
-import LanguageSwitcher from '@/uikit/components/LanguageSwitcher';
-
-function Header() {
-  return (
-    <header>
-      <LanguageSwitcher />
-    </header>
-  );
-}
-```
-
-#### 最佳实践
-
-1. 国际化标识符管理：
-
-   - 在 `config/Identifier/index.ts` 中集中管理UI文本
-   - 在 `config/Identifier/error.ts` 中集中管理错误信息
-   - 使用有意义的 key 命名（如：'page.home.title'）
-
-2. TypeScript 注释规范：
-
-   - 使用 `@description` 描述文本用途
-   - 使用 `@localZh` 定义中文文本
-   - 使用 `@localEn` 定义英文文本
-
-3. 路由配置：
-
-   - 使用 `LocaleLink` 组件进行页面跳转
-   - URL 格式：`/{lang}/path`（如：'/zh/about'）
-
-4. 组件开发：
-   - 使用 `useBaseRoutePage` hook 获取翻译函数
-   - 从 `@config/Identifier` 引入国际化 key
-   - 避免硬编码文本，始终使用国际化 key
-
 ### 主题系统
 
 - 基于 Tailwind CSS 的主题配置
@@ -266,106 +170,6 @@ export class RequestController extends StoreInterface<RequestControllerState> {
 }
 ```
 
-#### 请求插件系统
-
-项目内置多个实用的请求插件：
-
-1. `FetchURLPlugin`: URL 处理和构建
-2. `RequestCommonPlugin`: 通用请求配置
-3. `ApiMockPlugin`: Mock 数据支持
-4. `FetchAbortPlugin`: 请求中断控制
-5. `RequestLogger`: 请求日志记录
-6. `ApiCatchPlugin`: 统一错误处理
-
-使用示例：
-
-```typescript
-// 配置请求适配器
-const adapter = new RequestAdapter({
-  plugins: [
-    new FetchURLPlugin(),
-    new RequestCommonPlugin(),
-    new ApiMockPlugin(),
-    new FetchAbortPlugin(),
-    new RequestLogger()
-  ]
-});
-
-// 发起请求
-const response = await adapter.request({
-  url: '/api/users',
-  method: 'GET',
-  requestId: 'uniqueId', // 用于中断请求
-  mock: true // 启用 mock 数据
-});
-```
-
-#### 请求调度器
-
-使用 `RequestScheduler` 管理复杂的请求流程：
-
-```typescript
-export class FeApi extends RequestScheduler<RequestConfig> {
-  async getIpInfo() {
-    return this.request<void, IpInfo>({
-      url: '/api/ip',
-      method: 'GET'
-    });
-  }
-}
-```
-
-#### Mock 数据支持
-
-项目支持灵活的 Mock 数据配置：
-
-```typescript
-// 配置 Mock 数据
-const mockConfig = {
-  '/api/users': {
-    GET: () => ({
-      code: 200,
-      data: {
-        id: 1,
-        name: 'John Doe'
-      }
-    })
-  }
-};
-
-// 在请求中使用
-const response = await api.request({
-  url: '/api/users',
-  method: 'GET',
-  mock: true // 启用 mock
-});
-```
-
-#### 最佳实践
-
-1. API 定义：
-
-   - 在 `src/base/apis` 中集中管理 API 定义
-   - 使用 TypeScript 接口定义请求和响应类型
-   - 遵循 RESTful API 设计规范
-
-2. 错误处理：
-
-   - 使用 `ApiCatchPlugin` 统一处理错误
-   - 定义清晰的错误类型和错误码
-   - 提供友好的错误提示
-
-3. 请求状态管理：
-
-   - 使用 `SliceStore` 管理请求状态
-   - 处理加载、成功、错误等状态
-   - 实现请求防抖和节流
-
-4. Mock 数据：
-   - 提供合理的 Mock 数据结构
-   - 支持动态 Mock 数据生成
-   - 便于本地开发和测试
-
 ### 控制器模式
 
 提供多个开箱即用的控制器：
@@ -376,7 +180,7 @@ const response = await api.request({
 - UserController
 - ThemeController
 
-## 📚 开发指南
+## 🛠️ 开发指南
 
 ### API 开发规范
 
@@ -389,12 +193,6 @@ const response = await api.request({
 2. 更新 `config/app.router.json`
 3. 添加对应的控制器（如需要）
 
-### 国际化开发
-
-1. 在 `public/locales` 添加翻译文件
-2. 使用 `useTranslation` hook 进行调用
-3. 支持按需加载语言包
-
 ### 构建优化
 
 项目使用 Vite 进行构建，并进行了以下优化：

package/dist/templates/react-app/__tests__/__mocks__/I18nService.ts

@@ -0,0 +1,13 @@
+import { vi } from 'vitest';
+import { I18nService } from '@/base/services/I18nService';
+
+export class MockI18nService extends I18nService {
+  constructor() {
+    super('/');
+  }
+
+  t = vi.fn((key: string) => key);
+  changeLanguage = vi.fn();
+  changeLoading = vi.fn();
+  onBefore = vi.fn();
+}

package/dist/templates/react-app/__tests__/__mocks__/MockAppConfit.ts

@@ -0,0 +1,48 @@
+import { EnvConfigInterface } from '@qlover/corekit-bridge';
+import { name, version } from '../../package.json';
+
+export class MockAppConfig implements EnvConfigInterface {
+  appName = name;
+
+  appVersion = version;
+
+  env: string = import.meta.env.MODE;
+
+  userTokenStorageKey = '__fe_user_token__';
+
+  userInfoStorageKey = '__fe_user_info__';
+
+  openAiModels = [
+    'gpt-4o-mini',
+    'gpt-3.5-turbo',
+    'gpt-3.5-turbo-2',
+    'gpt-4',
+    'gpt-4-32k'
+  ];
+
+  openAiBaseUrl = '';
+
+  openAiToken = '';
+
+  openAiTokenPrefix = '';
+
+  openAiRequireToken = true;
+
+  loginUser = '';
+
+  loginPassword = '';
+
+  feApiBaseUrl = '';
+
+  userApiBaseUrl = '';
+
+  aiApiBaseUrl = 'https://api.openai.com/v1';
+
+  aiApiToken = '';
+
+  aiApiTokenPrefix = 'Bearer';
+
+  aiApiRequireToken = true;
+
+  bootHref = '';
+}

package/dist/templates/react-app/__tests__/__mocks__/MockDialogHandler.ts

@@ -0,0 +1,16 @@
+import { InteractionHubInterface } from '@/base/port/InteractionHubInterface';
+import { AntdStaticApiInterface } from '@brain-toolkit/antd-theme-override/react';
+import { vi } from 'vitest';
+
+export class MockDialogHandler
+  implements InteractionHubInterface, AntdStaticApiInterface
+{
+  setMessage = vi.fn();
+  setModal = vi.fn();
+  setNotification = vi.fn();
+  success = vi.fn();
+  error = vi.fn();
+  info = vi.fn();
+  warn = vi.fn();
+  confirm = vi.fn();
+}

package/dist/templates/react-app/__tests__/__mocks__/MockLogger.ts

@@ -0,0 +1,14 @@
+import { LoggerInterface } from '@qlover/logger';
+import { vi } from 'vitest';
+
+export class MockLogger implements LoggerInterface {
+  info = vi.fn();
+  error = vi.fn();
+  debug = vi.fn();
+  warn = vi.fn();
+  trace = vi.fn();
+  log = vi.fn();
+  fatal = vi.fn();
+  addAppender = vi.fn();
+  context = vi.fn();
+}

package/dist/templates/react-app/__tests__/__mocks__/createMockGlobals.ts

@@ -0,0 +1,92 @@
+import { vi } from 'vitest';
+import { MockLogger } from './MockLogger';
+import { MockAppConfig } from './MockAppConfit';
+import { MockDialogHandler } from './MockDialogHandler';
+
+export function createMockGlobals() {
+  const mockLogger = new MockLogger();
+  const mockAppConfig = new MockAppConfig();
+  const mockDialogHandler = new MockDialogHandler();
+
+  // Mock JSON serializer
+  const mockJSON = {
+    serialize: vi.fn((data) => JSON.stringify(data)),
+    deserialize: vi.fn((data) => JSON.parse(data)),
+    stringify: vi.fn((data) => JSON.stringify(data)),
+    parse: vi.fn((data) => JSON.parse(data))
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const storageOptions: Record<string, any> = {
+    localStorage: {},
+    cookieStorage: {},
+    localStorageEncrypt: {}
+  };
+
+  // Mock localStorage with actual storage simulation
+  const mockLocalStorageData = storageOptions.localStorage ?? {};
+  const mockLocalStorage = {
+    get: vi.fn((key: string) => mockLocalStorageData[key]),
+    set: vi.fn((key: string, value: unknown) => {
+      mockLocalStorageData[key] = value;
+    }),
+    getItem: vi.fn((key: string) => mockLocalStorageData[key]),
+    setItem: vi.fn((key: string, value: unknown) => {
+      mockLocalStorageData[key] = value;
+    }),
+    remove: vi.fn((key: string) => {
+      delete mockLocalStorageData[key];
+    }),
+    removeItem: vi.fn((key: string) => {
+      delete mockLocalStorageData[key];
+    }),
+    clear: vi.fn(() => {
+      Object.keys(mockLocalStorageData).forEach((key) => {
+        delete mockLocalStorageData[key];
+      });
+    }),
+    has: vi.fn((key: string) => key in mockLocalStorageData),
+    keys: vi.fn(() => Object.keys(mockLocalStorageData)),
+    size: vi.fn(() => Object.keys(mockLocalStorageData).length)
+  };
+
+  // Mock localStorageEncrypt (same as localStorage for now)
+  const mockLocalStorageEncrypt = { ...mockLocalStorage };
+
+  // Mock cookieStorage
+  const mockCookieStorageData = storageOptions.cookieStorage ?? {};
+  const mockCookieStorage = {
+    get: vi.fn((key: string) => mockCookieStorageData[key]),
+    set: vi.fn((key: string, value: unknown, _options?: unknown) => {
+      mockCookieStorageData[key] = value;
+    }),
+    getItem: vi.fn((key: string) => mockCookieStorageData[key]),
+    setItem: vi.fn((key: string, value: unknown, _options?: unknown) => {
+      mockCookieStorageData[key] = value;
+    }),
+    remove: vi.fn((key: string) => {
+      delete mockCookieStorageData[key];
+    }),
+    removeItem: vi.fn((key: string) => {
+      delete mockCookieStorageData[key];
+    }),
+    clear: vi.fn(() => {
+      Object.keys(mockCookieStorageData).forEach((key) => {
+        delete mockCookieStorageData[key];
+      });
+    }),
+    has: vi.fn((key: string) => key in mockCookieStorageData),
+    keys: vi.fn(() => Object.keys(mockCookieStorageData)),
+    size: vi.fn(() => Object.keys(mockCookieStorageData).length)
+  };
+
+  return {
+    logger: mockLogger,
+    appConfig: mockAppConfig,
+    dialogHandler: mockDialogHandler,
+    JSON: mockJSON,
+    localStorage: mockLocalStorage,
+    localStorageEncrypt: mockLocalStorageEncrypt,
+    cookieStorage: mockCookieStorage
+  };
+}

package/dist/templates/react-app/__tests__/setup/index.ts

@@ -0,0 +1,51 @@
+import { createMockGlobals } from '../__mocks__/createMockGlobals';
+
+// 设置测试环境
+beforeEach(() => {
+  // 清理DOM
+  document.body.innerHTML = '';
+
+  // 创建root元素（如果不存在）
+  if (!document.getElementById('root')) {
+    const rootElement = document.createElement('div');
+    rootElement.id = 'root';
+    document.body.appendChild(rootElement);
+  }
+});
+
+afterEach(() => {
+  // 清理所有mock
+  vi.clearAllMocks();
+});
+
+// 全局测试配置
+global.ResizeObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn()
+}));
+
+// Mock window.matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(), // deprecated
+    removeListener: vi.fn(), // deprecated
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn()
+  }))
+});
+
+// Mock IntersectionObserver
+global.IntersectionObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn()
+}));
+
+// Mock globals
+vi.mock('@/core/globals', () => createMockGlobals());

package/dist/templates/react-app/__tests__/src/App.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen } from '@testing-library/react';
+import App from '@/App';
+import { routerPrefix } from '@config/common';
+
+// Mock the dependencies
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom');
+  return {
+    ...actual,
+    createBrowserRouter: vi.fn(() => ({
+      routes: [],
+      basename: routerPrefix
+    })),
+    RouterProvider: vi.fn(({ router }) => (
+      <div data-testid="router-provider">
+        <div data-testid="router-basename">{router.basename}</div>
+        <div data-testid="router-routes-count">
+          {router.routes?.length || 0}
+        </div>
+      </div>
+    ))
+  };
+});
+
+vi.mock('@brain-toolkit/antd-theme-override/react', () => ({
+  AntdThemeProvider: vi.fn(({ children, theme }) => (
+    <div data-testid="antd-theme-provider">
+      <div data-testid="theme-key">{theme?.cssVar?.key}</div>
+      <div data-testid="theme-prefix">{theme?.cssVar?.prefix}</div>
+      {children}
+    </div>
+  ))
+}));
+
+vi.mock('@/core/IOC', () => ({
+  IOC: vi.fn((service) => {
+    if (service === 'RouteService') {
+      return {
+        routes: [
+          { path: '/', component: 'HomePage' },
+          { path: '/about', component: 'AboutPage' }
+        ]
+      };
+    }
+    if (service === 'DialogHandler') {
+      return {};
+    }
+    return {};
+  })
+}));
+
+vi.mock('@/uikit/hooks/useStore', () => ({
+  useStore: vi.fn((service, selector) => {
+    if (service && selector) {
+      return [
+        { path: '/', component: 'HomePage' },
+        { path: '/about', component: 'AboutPage' }
+      ];
+    }
+    return [];
+  })
+}));
+
+vi.mock('@/base/cases/RouterLoader', () => ({
+  RouterLoader: vi.fn().mockImplementation(() => ({
+    toRoute: vi.fn((route) => ({
+      path: route.path,
+      element: <div data-testid={`route-${route.path}`}>{route.component}</div>
+    }))
+  }))
+}));
+
+// Mock the CSS import
+vi.mock('@/styles/css/index.css', () => ({}));
+
+describe('App Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should render without crashing', () => {
+    render(<App />);
+
+    // Check if the main app structure is rendered
+    expect(screen.getByTestId('antd-theme-provider')).toBeDefined();
+    expect(screen.getByTestId('router-provider')).toBeDefined();
+  });
+
+  it('should configure theme provider correctly', () => {
+    render(<App />);
+
+    // Check theme configuration
+    expect(screen.getByTestId('theme-key').textContent).toBe('fe-theme');
+    expect(screen.getByTestId('theme-prefix').textContent).toBe('fe');
+  });
+
+  it('should configure router with correct basename', () => {
+    render(<App />);
+
+    // Check router configuration
+    expect(screen.getByTestId('router-basename')).toBeDefined();
+    expect(screen.getByTestId('router-basename').textContent).toBe(
+      routerPrefix
+    );
+  });
+
+  it('should render router provider with routes', () => {
+    render(<App />);
+
+    // Check that router provider is rendered
+    expect(screen.getByTestId('router-provider')).toBeDefined();
+    expect(screen.getByTestId('router-routes-count')).toBeDefined();
+  });
+
+  it('should have proper component structure', () => {
+    const { container } = render(<App />);
+
+    // Check the overall structure
+    expect(container.firstChild).toBeDefined();
+
+    // Check that theme provider wraps router provider
+    const themeProvider = screen.getByTestId('antd-theme-provider');
+    const routerProvider = screen.getByTestId('router-provider');
+
+    expect(themeProvider.contains(routerProvider)).toBe(true);
+  });
+
+  it('should handle empty routes gracefully', async () => {
+    // Mock useStore to return empty routes
+    const { useStore } = await import('@/uikit/hooks/useStore');
+    vi.mocked(useStore).mockReturnValueOnce([]);
+
+    render(<App />);
+
+    // Should still render without crashing
+    expect(screen.getByTestId('antd-theme-provider')).toBeDefined();
+    expect(screen.getByTestId('router-provider')).toBeDefined();
+  });
+});