@qlover/create-app 0.3.2 → 0.3.4

package/templates/react-app/src/base/cases/AppConfig.ts

@@ -0,0 +1,103 @@
+import type { EnvConfigInterface } from '@qlover/corekit-bridge';
+
+/**
+ * Application Configuration Management
+ *
+ * Significance: Centralized configuration management for the application
+ * Core idea: Single source of truth for all environment and application settings
+ * Main function: Provide typed access to application configuration values
+ * Main purpose: Maintain consistent configuration across the application
+ *
+ * Configuration values are automatically injected from the project's .env files:
+ * - .env: Default environment variables
+ * - .env.development: Development environment variables
+ * - .env.production: Production environment variables
+ * - .env.local: Local overrides (git ignored)
+ *
+ * Environment variables should be prefixed with VITE_ to be exposed to the client side.
+ * Example .env file:
+ * ```
+ * VITE_APP_NAME=MyApp
+ * VITE_API_BASE_URL=http://api.example.com
+ * VITE_USER_TOKEN_KEY=user_token
+ * ```
+ *
+ * @example
+ * const config = new AppConfig();
+ * console.log(config.appName); // Value from VITE_APP_NAME
+ * console.log(config.aiApiBaseUrl); // Value from VITE_AI_API_BASE_URL
+ */
+export class AppConfig implements EnvConfigInterface {
+  /**
+   * Application name identifier
+   * @description Injected from VITE_APP_NAME environment variable
+   */
+  readonly appName = '';
+
+  /**
+   * Current version of the application
+   * @description Injected from VITE_APP_VERSION environment variable
+   */
+  readonly appVersion = '';
+
+  /**
+   * Current environment mode for Vite
+   * @description Represents the running environment (development, production, etc.)
+   * Automatically set based on the current .env file being used
+   */
+  readonly env: string = '';
+
+  /**
+   * Storage key for user authentication token
+   * @description Injected from VITE_USER_TOKEN_STORAGE_KEY environment variable
+   */
+  readonly userTokenStorageKey = '';
+
+  /**
+   * Available OpenAI model configurations
+   * @description List of supported OpenAI models for the application
+   */
+  readonly openAiModels = [
+    'gpt-4o-mini',
+    'gpt-3.5-turbo',
+    'gpt-3.5-turbo-2',
+    'gpt-4',
+    'gpt-4-32k'
+  ];
+
+  /** Base URL for OpenAI API endpoints */
+  readonly openAiBaseUrl = '';
+
+  /** Authentication token for OpenAI API */
+  readonly openAiToken = '';
+
+  /** Prefix for OpenAI authentication token */
+  readonly openAiTokenPrefix = '';
+
+  /** Flag indicating if OpenAI token is required */
+  readonly openAiRequireToken = true;
+
+  /** Default login username */
+  readonly loginUser = '';
+
+  /** Default login password */
+  readonly loginPassword = '';
+
+  /** Base URL for frontend API endpoints */
+  readonly feApiBaseUrl = '';
+
+  /** Base URL for user-related API endpoints */
+  readonly userApiBaseUrl = '';
+
+  /** Base URL for AI service API endpoints */
+  readonly aiApiBaseUrl = 'https://api.openai.com/v1';
+
+  /** Authentication token for AI service API */
+  readonly aiApiToken = '';
+
+  /** Prefix for AI service authentication token */
+  readonly aiApiTokenPrefix = 'Bearer';
+
+  /** Flag indicating if AI service token is required */
+  readonly aiApiRequireToken = true;
+}

package/templates/react-app/src/base/cases/{appError/AppError.ts → AppError.ts}

@@ -1,8 +1,5 @@
 import { ExecutorError } from '@qlover/fe-corekit';
 
-/**
- * 统一当前项目中开发的错误
- */
 export class AppError extends ExecutorError {
   constructor(
     public readonly id: string,

package/templates/react-app/src/base/cases/DialogHandler.ts

@@ -0,0 +1,86 @@
+import type {
+  AntdStaticApiInterface,
+  MessageApi,
+  ModalApi,
+  NotificationApi
+} from '@brain-toolkit/antd-theme-override/react';
+import type {
+  InteractionHubInterface,
+  InteractionOptions,
+  ConfirmOptions
+} from '../port/InteractionHubInterface';
+
+/**
+ * Dialog Handler Implementation
+ *
+ * Implements the InteractionHubInterface using Ant Design components.
+ * Provides concrete implementations for displaying notifications and confirmation dialogs.
+ *
+ * Features:
+ * - Uses Ant Design's message component for notifications
+ * - Uses Ant Design's Modal component for confirmations
+ * - Supports customizable display durations
+ * - Handles error objects appropriately
+ *
+ * @example
+ * const dialog = new DialogHandler();
+ * dialog.success('Data saved successfully');
+ * dialog.confirm({
+ *   title: 'Confirm Delete',
+ *   content: 'Are you sure you want to delete this item?',
+ *   onOk: () => handleDelete(),
+ * });
+ */
+export class DialogHandler
+  implements InteractionHubInterface, AntdStaticApiInterface
+{
+  private antds: {
+    message?: MessageApi;
+    modal?: ModalApi;
+    notification?: NotificationApi;
+  } = {};
+
+  setMessage(message: MessageApi): void {
+    this.antds.message = message;
+  }
+
+  setModal(modal: ModalApi): void {
+    this.antds.modal = modal;
+  }
+
+  setNotification(notification: NotificationApi): void {
+    this.antds.notification = notification;
+  }
+
+  /**
+   * Formats error message from various error types
+   */
+  private formatErrorMessage(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (typeof error === 'string') return error;
+    return 'An unknown error occurred';
+  }
+
+  public success(msg: string, options?: InteractionOptions): void {
+    this.antds.message?.success({ content: msg, ...options });
+  }
+
+  public error(msg: string, options?: InteractionOptions): void {
+    this.antds.message?.error({
+      content: options?.error ? this.formatErrorMessage(options.error) : msg,
+      ...options
+    });
+  }
+
+  public info(msg: string, options?: InteractionOptions): void {
+    this.antds.message?.info({ content: msg, ...options });
+  }
+
+  public warn(msg: string, options?: InteractionOptions): void {
+    this.antds.message?.warning({ content: msg, ...options });
+  }
+
+  public confirm(options: ConfirmOptions): void {
+    this.antds.modal?.confirm(options);
+  }
+}

package/templates/react-app/src/base/cases/RequestLogger.ts

@@ -3,7 +3,7 @@ import {
   type ExecutorPlugin,
   type ExecutorContext,
   type RequestAdapterFetchConfig,
-  type RequestAdapterResponse,
+  type RequestAdapterResponse
 } from '@qlover/fe-corekit';
 import {
   type ApiCatchPluginConfig,

package/templates/react-app/src/base/cases/RouterLoader.ts

@@ -0,0 +1,166 @@
+import type { ComponentType, LazyExoticComponent, ReactNode } from 'react';
+import { RouteObject } from 'react-router-dom';
+import isString from 'lodash/isString';
+
+/**
+ * Component mapping type for lazy-loaded components
+ * @description Maps component identifiers to their lazy-loaded implementations
+ */
+export type ComponentValue = Record<string, () => unknown>;
+
+/**
+ * Route component type definition supporting both regular and lazy-loaded components
+ */
+type RouteComponentType<T = unknown> =
+  | ComponentType<T>
+  | LazyExoticComponent<ComponentType<T>>;
+
+/**
+ * Extended route configuration interface
+ * @description Extends React Router's RouteObject with additional meta information
+ */
+export type RouteConfigValue = Omit<RouteObject, 'element' | 'children'> & {
+  /**
+   * Component identifier string that maps to a component in componentMaps
+   *
+   * TODO: support `ReactNode`
+   *
+   * @description Used to lookup the actual component implementation
+   */
+  element?: string;
+
+  /**
+   * Nested route configurations
+   */
+  children?: RouteConfigValue[];
+
+  /**
+   * Additional metadata for the route
+   * @description Can store any route-specific data like permissions, titles, etc.
+   */
+  meta?: Record<string, unknown>;
+};
+
+/**
+ * Route rendering function type
+ * @description Function to customize how route components are rendered
+ */
+export type RouterLoaderRender = (
+  route: Omit<RouteConfigValue, 'element'> & {
+    element: () => RouteComponentType;
+  }
+) => ReactNode;
+
+/**
+ * Router loader configuration options
+ */
+export type RouterLoaderOptions = {
+  /**
+   * Route configuration array
+   * @description Defines the application's routing structure
+   */
+  routes?: RouteConfigValue[];
+
+  /**
+   * Component mapping object
+   * @description Maps component identifiers to their actual implementations
+   * @example
+   * {
+   *   'Home': () => import('./pages/Home'),
+   *   'About': () => import('./pages/About')
+   * }
+   */
+  componentMaps?: ComponentValue;
+
+  /**
+   * Custom route rendering function
+   * @description Controls how route components are rendered
+   * @required
+   */
+  render: RouterLoaderRender;
+};
+
+/**
+ * Router Configuration Loader
+ *
+ * Significance: Manages dynamic route configuration and component loading
+ * Core idea: Separate route definitions from component implementations
+ * Main function: Transform route configurations into React Router compatible routes
+ * Main purpose: Enable dynamic and code-split routing with lazy loading
+ *
+ * @example
+ * const loader = new RouterLoader({
+ *   routes: [{
+ *     path: '/',
+ *     element: 'Home',
+ *     children: [{
+ *       path: 'about',
+ *       element: 'About'
+ *     }]
+ *   }],
+ *   componentMaps: {
+ *     'Home': () => import('./pages/Home'),
+ *     'About': () => import('./pages/About')
+ *   },
+ *   render: (route) => <Suspense><route.element /></Suspense>
+ * });
+ */
+export class RouterLoader {
+  constructor(private readonly options: RouterLoaderOptions) {
+    if (!options.render) {
+      throw new Error('RouterLoader render is required');
+    }
+  }
+
+  /**
+   * Get the component mapping object
+   * @returns Component mapping dictionary
+   */
+  getComponentMaps(): ComponentValue {
+    const { componentMaps = {} } = this.options;
+    return componentMaps;
+  }
+
+  /**
+   * Retrieve a component implementation by its identifier
+   * @param element Component identifier string
+   * @returns Component loader function
+   * @throws Error if component is not found in componentMaps
+   */
+  getComponent(element: string): () => RouteComponentType {
+    const maps = this.getComponentMaps();
+    const component = maps[element];
+
+    if (!component) {
+      throw new Error(`Component not found: ${element}`);
+    }
+
+    return component as () => RouteComponentType;
+  }
+
+  /**
+   * Transform a route configuration into a React Router compatible route
+   * @param route Route configuration object
+   * @returns React Router route object
+   */
+  toRoute(route: RouteConfigValue): RouteObject {
+    const { render } = this.options;
+    const { element, children, ...rest } = route;
+
+    if (!element || !isString(element)) {
+      console.warn(
+        `Invalid route, path is: ${route.path}, element is: ${element}`
+      );
+    }
+
+    const componet = this.getComponent(element || '404');
+    const Element = render({ ...rest, element: componet });
+
+    // @ts-expect-error
+    return {
+      ...rest,
+      element: Element,
+      children: children?.map((child) => this.toRoute(child))
+    };
+  }
+}

package/templates/react-app/src/base/port/InteractionHubInterface.ts

@@ -0,0 +1,94 @@
+import type { ModalFuncProps } from 'antd';
+
+/**
+ * Confirmation dialog configuration options
+ * Extends Ant Design's ModalFuncProps and requires a title
+ */
+export interface ConfirmOptions extends ModalFuncProps {
+  content: string;
+}
+
+/**
+ * Basic dialog configuration options
+ */
+export interface InteractionOptions {
+  /** Display duration (milliseconds) */
+  duration?: number;
+  /** Close callback function */
+  onClose?: () => void;
+  /** Error object */
+  error?: unknown;
+}
+
+/**
+ * Interaction Hub Interface
+ *
+ * This interface serves as the central interaction layer for the application,
+ * managing all user interface interactions, notifications, and feedback functionality.
+ * Main responsibilities include:
+ * 1. Providing a unified message notification mechanism (success/error/info/warn)
+ * 2. Handling user interaction confirmation scenarios (confirm)
+ * 3. Unified error display and handling approach
+ *
+ * Design Goals:
+ * - Uniformity: Provide consistent user interaction experience
+ * - Extensibility: Easy to add new interaction types
+ * - Configurability: Support custom interaction behaviors
+ * - Decoupling: Separate UI interaction layer from business logic
+ *
+ * Use Cases:
+ * - Operation success/failure feedback
+ * - Important operation confirmation prompts
+ * - System message notifications
+ * - Warning message display
+ *
+ * Implementation Notes:
+ * - Currently implemented based on Ant Design component library
+ * - Supports other UI libraries through different adapters
+ * - Supports global configuration of default behaviors
+ *
+ * @example
+ * // Success notification
+ * interactionHub.success("Operation successful", { duration: 3000 });
+ *
+ * // Confirmation dialog
+ * interactionHub.confirm({
+ *   content: "Are you sure you want to delete?",
+ *   onOk: () => handleDelete()
+ * });
+ */
+export interface InteractionHubInterface {
+  /**
+   * Display success notification
+   * @param message Notification message
+   * @param options Configuration options
+   */
+  success(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display error notification
+   * @param message Error message
+   * @param options Configuration options
+   */
+  error(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display information notification
+   * @param message Information message
+   * @param options Configuration options
+   */
+  info(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display warning notification
+   * @param message Warning message
+   * @param options Configuration options
+   */
+  warn(message: string, options?: InteractionOptions): void;
+
+  /**
+   * Display confirmation dialog
+   * @param options Confirmation dialog configuration options
+   */
+  confirm(options: ConfirmOptions): void;
+}

package/templates/react-app/src/base/services/I18nService.ts

@@ -4,17 +4,37 @@ import LanguageDetector from 'i18next-browser-languagedetector';
 import HttpApi from 'i18next-http-backend';
 import merge from 'lodash/merge';
 import i18nConfig from '@config/i18n';
-import type { BootstrapExecutorPlugin } from '@qlover/corekit-bridge';
+import {
+  SliceStore,
+  type BootstrapExecutorPlugin
+} from '@qlover/corekit-bridge';
 
 const { supportedLngs, fallbackLng } = i18nConfig;
 
 export type I18nServiceLocale = (typeof supportedLngs)[number];
 
-export class I18nService implements BootstrapExecutorPlugin {
+export class I18nServiceState {
+  loading: boolean = false;
+  constructor(public language: I18nServiceLocale) {}
+}
+
+export class I18nService
+  extends SliceStore<I18nServiceState>
+  implements BootstrapExecutorPlugin
+{
   readonly pluginName = 'I18nService';
 
-  constructor(private pathname: string) {}
+  selector = {
+    loading: (state: I18nServiceState) => state.loading
+  };
+
+  constructor(private pathname: string) {
+    super(() => new I18nServiceState(i18n.language as I18nServiceLocale));
+  }
 
+  /**
+   * @override
+   */
   onBefore(): void {
     const debug = false;
 
@@ -48,6 +68,14 @@ export class I18nService implements BootstrapExecutorPlugin {
     i18n.services.languageDetector.addDetector(pathLanguageDetector);
   }
 
+  async changeLanguage(language: I18nServiceLocale): Promise<void> {
+    await i18n.changeLanguage(language);
+  }
+
+  changeLoading(loading: boolean): void {
+    this.emit({ ...this.state, loading });
+  }
+
   static getCurrentLanguage(): I18nServiceLocale {
     return i18n.language as I18nServiceLocale;
   }
@@ -60,4 +88,23 @@ export class I18nService implements BootstrapExecutorPlugin {
   static isValidLanguage(language: string): language is I18nServiceLocale {
     return supportedLngs.includes(language as I18nServiceLocale);
   }
+
+  /**
+   * translate the key
+   * @param key - key to translate
+   * @param params - params to pass to the translation
+   * @returns translated value
+   */
+  t(key: string, params?: Record<string, unknown>): string {
+    const i18nValue = i18n.t(key, {
+      lng: i18n.language,
+      ...params
+    });
+
+    if (!i18nValue || i18nValue === key) {
+      return key;
+    }
+
+    return i18nValue;
+  }
 }

package/templates/react-app/src/base/services/ProcesserService.ts

@@ -3,7 +3,6 @@ import { IOCIdentifier } from '@/core/IOC';
 import { injectable, inject } from 'inversify';
 import type { LoggerInterface } from '@qlover/logger';
 
-
 @injectable()
 export class ProcesserService {
   constructor(

package/templates/react-app/src/base/types/deprecated-antd.d.ts

@@ -0,0 +1,60 @@
+import AntdMessageStatic from 'antd/es/message';
+import { TypeOpen } from 'antd/es/message/interface';
+import AntdModalStatic from 'antd/es/modal';
+
+import { ModalFunc } from 'antd/es/modal/confirm';
+
+declare module 'antd' {
+  /**
+   * @deprecated Please use alternative message implementation instead
+   */
+  export const message: typeof AntdMessageStatic & {
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    info: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    success: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    error: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warning: TypeOpen;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    loading: TypeOpen;
+  };
+
+  export const Modal: typeof AntdModalStatic & {
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    confirm: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    info: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    success: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    error: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warn: ModalFunc;
+    /**
+     * @deprecated Please use alternative message implementation instead
+     */
+    warning: ModalFunc;
+  };
+}

package/templates/react-app/src/core/IOC.ts

@@ -11,8 +11,22 @@ import {
 } from '@qlover/corekit-bridge';
 import type { JSONSerializer, JSONStorage } from '@qlover/fe-corekit';
 import type { LoggerInterface } from '@qlover/logger';
+import type { AppConfig } from '@/base/cases/AppConfig';
 import { Container } from 'inversify';
-import { InversifyRegisterInterface } from '@/base/port/InversifyIocInterface';
+import { IOCRegisterInterface } from '@qlover/corekit-bridge';
+import { DialogHandler } from '@/base/cases/DialogHandler';
+
+export type IocRegisterOptions = {
+  pathname: string;
+  appConfig: AppConfig;
+};
+
+export type InversifyRegisterContainer = Container;
+/**
+ * Inversify register interface.
+ */
+export interface InversifyRegisterInterface
+  extends IOCRegisterInterface<InversifyContainer, IocRegisterOptions> {}
 
 export class InversifyContainer implements IOCContainerInterface {
   private container: Container;
@@ -26,12 +40,6 @@ export class InversifyContainer implements IOCContainerInterface {
     });
   }
 
-  configure(registers?: InversifyRegisterInterface[]): void {
-    if (registers) {
-      registers.forEach((register) => register.register(this.container, this));
-    }
-  }
-
   bind<T>(key: ServiceIdentifier<T>, value: T): void {
     this.container.bind<T>(key).toConstantValue(value);
   }
@@ -67,7 +75,8 @@ export const IOCIdentifier = Object.freeze({
   FeApiCommonPlugin: 'FeApiCommonPlugin',
   AppConfig: 'AppConfig',
   ApiMockPlugin: 'ApiMockPlugin',
-  ApiCatchPlugin: 'ApiCatchPlugin'
+  ApiCatchPlugin: 'ApiCatchPlugin',
+  DialogHandler: 'DialogHandler'
 });
 
 /**
@@ -82,6 +91,7 @@ export interface IOCIdentifierMap {
   [IOCIdentifier.AppConfig]: EnvConfigInterface;
   [IOCIdentifier.ApiMockPlugin]: ApiMockPlugin;
   [IOCIdentifier.ApiCatchPlugin]: ApiCatchPlugin;
+  [IOCIdentifier.DialogHandler]: DialogHandler;
 }
 
 export const IOC = createIOCFunction<IOCIdentifierMap>(