@qlover/create-app 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @qlover/create-app
 
+## 0.3.5
+
+### Patch Changes
+
+#### ✨ Features
+
+- enhance Vite configuration and add new dependencies for improved build performance ([e14ee42](https://github.com/qlover/fe-base/commit/e14ee428d46fc48decb99762103c25d6e6c8535e)) ([#418](https://github.com/qlover/fe-base/pull/418))
+
+- Added `terser` for advanced minification options, including console log removal and improved compression.
+- Introduced `vite-plugin-imp` to optimize Ant Design imports, reducing bundle size and improving load times.
+- Updated Vite configuration to define manual chunks for better code splitting and chunk management.
+
+
+    Co-authored-by: QRJ <renjie.qin@brain.im>
+
+## 0.3.4
+
+### Patch Changes
+
+#### ✨ Features
+
+- enhance React app with Ant Design integration and theming improvements ([374eaa3](https://github.com/qlover/fe-base/commit/374eaa36ab85b71543668721888823c41793aa23)) ([#414](https://github.com/qlover/fe-base/pull/414))
+
+- Added Vite as a dependency for improved build performance.
+- Introduced new Ant Design components and updated existing ones for a consistent UI experience.
+- Enhanced theming capabilities with new CSS variables and custom themes (default, dark, pink).
+- Updated localization keys for the About page and added new messages for better user feedback.
+- Refactored DialogHandler to manage Ant Design's static APIs globally.
+- Improved overall code structure and organization for better maintainability.
+
+  Co-authored-by: QRJ <renjie.qin@brain.im>
+
+- enhance React app with improved configuration management and new components ([67f88cb](https://github.com/qlover/fe-base/commit/67f88cbc7cc0ebab51cbd33be66f98117fc2cf21)) ([#414](https://github.com/qlover/fe-base/pull/414))
+
+- Introduced centralized AppConfig class for managing application settings and environment variables.
+- Added DialogHandler for handling notifications and confirmations using Ant Design components.
+- Refactored RouterLoader to support dynamic route configurations and lazy loading of components.
+- Updated various API adapters to utilize the new AppConfig structure for better maintainability.
+- Removed outdated DialogHandler implementation and reorganized related files for improved clarity.
+
+  Co-authored-by: QRJ <renjie.qin@brain.im>
+
+- integrate @brain-toolkit/antd-theme-override for improved Ant D… ([4ebb081](https://github.com/qlover/fe-base/commit/4ebb081d89397424c459dd7f885817152098e322)) ([#414](https://github.com/qlover/fe-base/pull/414))
+
+  - feat: integrate @brain-toolkit/antd-theme-override for improved Ant Design support
+
+  * Added @brain-toolkit/antd-theme-override as a dependency to enhance theming capabilities.
+  * Updated imports to utilize the new theming library, replacing the deprecated antd-overried references.
+  * Removed outdated files related to the previous Ant Design integration to streamline the codebase.
+  * Refactored components to leverage the new theme provider and static API interface for notifications and modals.
+
+  Co-authored-by: QRJ <renjie.qin@brain.im>
+
+  - feat(I18nService): add translation method for improved localization support
+
+  * Implemented a new `t` method in the I18nService class to facilitate key-based translations.
+  * The method accepts a translation key and optional parameters, returning the translated value or the key if no translation is found.
+  * Enhanced localization handling to improve user experience across the application.
+
+  ***
+
+  Co-authored-by: QRJ <renjie.qin@brain.im>
+
 ## 0.3.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlover/create-app",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "private": false,
   "main": "./dist/index.cjs",
@@ -51,8 +51,8 @@
     "inquirer": "^12.3.2",
     "ora": "^8.1.1",
     "lodash": "^4.17.21",
-    "@qlover/logger": "0.1.1",
     "@qlover/scripts-context": "0.2.1",
+    "@qlover/logger": "0.1.1",
     "@qlover/fe-corekit": "1.4.0"
   },
   "scripts": {

package/templates/react-app/README.md

@@ -2,185 +2,376 @@
 
 一个现代化的 React 前端项目模板，集成了多项实用功能和最佳实践。
 
-## 特性亮点
+## 🌟 特性亮点
 
 - 🚀 基于 Vite 的快速开发体验
 - 🎨 集成 Tailwind CSS 的主题系统
-- 🌍 完善的国际化支持
-- 🔄 IOC 容器的依赖注入
+- 🌍 完善的国际化支持（中英文）
+- 🔄 基于 TypeScript 的 IOC 容器
 - 📡 统一的 API 请求处理
 - 🎮 控制器模式的状态管理
+- 📦 使用 pnpm 进行包管理
+- 🧪 内置测试支持
 
-## 环境要求
+## 🔧 环境要求
 
 - Node.js >= 16
 - pnpm >= 8.0
 
-## 配置说明
+## 📁 项目结构
+
+```tree
+├── config/                 # 配置文件目录
+│   ├── app.router.json     # 路由页面配置
+│   ├── common.ts           # 应用通用配置
+│   ├── app.router.json     # 路由配置
+│   ├── i18n.ts             # 国际化配置
+│   └── theme.json          # 主题配置
+├── lib/                    # 公共库目录
+├── public/                 # 静态资源目录
+├── src/
+│   ├── base/           # 基础代码
+│   ├── core/           # 核心代码
+│   ├── pages/          # 页面组件
+│   ├── services/       # 服务层
+│   └── uikit/          # UI 组件库
+└── vite.config.ts      # Vite 配置文件
+```
 
-项目配置文件位于 `config/` 目录：
+## 🚀 快速开始
 
-- `app.common.ts`: 应用通用配置，包含 API 配置、默认登录信息等
-- `app.router.json`: 路由配置，定义应用的路由结构
-- `i18n.ts`: 国际化配置，支持中英文切换
-- `theme.json`: 主题配置，定义应用的主题系统
+### 安装依赖
 
-## 项目结构
+```bash
+pnpm install
+```
 
-├── config/ # 配置文件目录
-│ ├── app.common.ts # 应用通用配置
-│ ├── app.router.json # 路由配置
-│ ├── i18n.ts # 国际化配置
-│ └── theme.json # 主题配置
-├── lib/ # 公共库目录
-│ ├── fe-react-controller/ # React 控制器库
-│ ├── fe-react-theme/ # React 主题库
-│ ├── openAiApi/ # OpenAI API 封装
-│ ├── request-common-plugin/ # 请求公共插件
-│ └── tw-root10px/ # Tailwind 10px 根字体配置
-├── public/ # 静态资源目录
-│ └── locales/ # 国际化资源文件
-├── src/ # 源代码目录
-│ ├── base/ # 基础代码
-│ │ ├── apis/ # API 接口定义
-│ │ ├── cases/ # 业务用例
-│ │ ├── port/ # 接口定义
-│ │ └── types/ # 类型定义
-│ ├── core/ # 核心代码
-│ │ └── feIOC/ # IOC 容器实现
-│ │ └── globals.ts # 全局变量
-│ │ └── bootstrap.ts # 启动器
-│ ├── pages/ # 页面组件
-│ ├── services/ # 服务层
-│ └── uikit/ # UI 组件库
-└── vite.config.ts # Vite 配置文件
+### 开发模式
 
-## 目录结构说明
+```bash
+pnpm dev
+```
 
-1. `config/`: 集中管理配置文件，便于统一维护和修改
-2. `lib/`: 可复用的独立功能库，方便跨项目使用
-3. `src/base/`: 基础代码层，定义接口和类型
-4. `src/core/`: 核心功能实现，包含 IOC 容器等基础设施
-5. `src/pages/`: 页面组件，按功能模块组织
-6. `src/services/`: 服务层，处理业务逻辑
-7. `src/uikit/`: UI 组件库，提供可复用的界面组件
+### 构建项目
 
-## 核心特性
+```bash
+pnpm build
+```
 
-### 1. IOC 容器
+### 运行测试
 
-项目使用依赖注入容器管理依赖，主要包含:
+```bash
+pnpm test
+```
 
-- `FeIOC`: IOC 容器的核心实现
-- `RegisterApi`: API 服务注册
-- `RegisterCommon`: 通用服务注册
-- `RegisterControllers`: 控制器注册
+## 🔨 核心功能
 
-### 2. 国际化支持
+### IOC 容器
 
-- 支持中文和英文
-- 使用 i18next 实现
-- 按模块划分语言文件
+- 基于 TypeScript 的依赖注入系统
+- 支持服务自动注册和依赖管理
+- 提供完整的类型推导
 
-### 3. 主题系统
+### 国际化支持
 
-- 支持主题切换
-- 基于 Tailwind CSS
-- 自定义 10px 根字体配置
+- 基于 i18next 的完整国际化解决方案
+- 支持中文(zh)和英文(en)双语切换
+- 基于 TypeScript 注释的自动国际化资源生成
+- URL 路径语言检测和切换
+- 内置语言切换组件
 
-### 4. API 请求处理
+#### 国际化配置
 
-- 统一的请求处理机制
-- 支持请求拦截和响应处理
-- Mock 数据支持
-- OpenAI API 集成
+项目使用 `@brain-toolkit/ts2locales` 插件从 TypeScript 注释自动生成国际化资源：
 
-### 5. 控制器模式
+```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'
+};
+```
 
-- `JSONStorageController`: JSON 存储控制
-- `RequestController`: 请求控制
-- `RouterController`: 路由控制
-- `UserController`: 用户控制
-- `ThemeController`: 主题控制
+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.I18n.ts',
+          target: './public/locales/{{lng}}/common.json'
+        }
+      ]
+    })
+  ]
+});
+```
 
-## 技术栈
+#### 国际化服务
 
-- React
-- TypeScript
-- Vite
-- Tailwind CSS
-- i18next
+项目提供了 `I18nService` 用于管理国际化状态和语言切换：
 
-## 开发
+```typescript
+import { I18nService } from '@/base/services/I18nService';
 
-项目使用 pnpm 管理依赖，请先安装 pnpm
+// 获取当前语言
+const currentLang = I18nService.getCurrentLanguage();
 
-```bash
-npm install -g pnpm
+// 切换语言
+await i18nService.changeLanguage('zh');
 ```
 
-## 开发指南
+#### 在组件中使用
 
-### API 开发
+```typescript
+import { useBaseRoutePage } from '@/uikit/contexts/BaseRouteContext';
+import * as i18nKeys from '@config/Identifier.I18n';
 
-项目使用统一的 API 请求处理机制：
+function MyComponent() {
+  const { t } = useBaseRoutePage();
 
-- 支持请求拦截和响应处理
-- 内置 Mock 数据支持
-- 集成 OpenAI API
+  return (
+    <div>
+      <h1>{t(i18nKeys.HOME_WELCOME)}</h1>
+      <button>{t(i18nKeys.HOME_GET_STARTED)}</button>
+    </div>
+  );
+}
+```
 
-### 控制器开发
+#### 语言切换组件
 
-项目采用控制器模式管理业务逻辑：
+项目提供了开箱即用的语言切换组件：
 
-- `JSONStorageController`: 处理 JSON 数据存储
-- `RequestController`: 处理 API 请求
-- `UserController`: 处理用户认证
-- `ThemeController`: 处理主题切换
+```typescript
+import LanguageSwitcher from '@/uikit/components/LanguageSwitcher';
 
-### 国际化开发
+function Header() {
+  return (
+    <header>
+      <LanguageSwitcher />
+    </header>
+  );
+}
+```
 
-语言文件位于 `public/locales/` 目录：
+#### 最佳实践
 
-- `zh/`: 中文语言包
-- `en/`: 英文语言包
+1. 国际化标识符管理：
 
-### 安装依赖
+   - 在 `config/Identifier.I18n.ts` 中集中管理UI文本
+   - 在 `config/Identifier.Error.ts` 中集中管理错误信息
+   - 使用有意义的 key 命名（如：'page.home.title'）
 
-```bash
-pnpm install
-```
+2. TypeScript 注释规范：
 
-### 开发模式
+   - 使用 `@description` 描述文本用途
+   - 使用 `@localZh` 定义中文文本
+   - 使用 `@localEn` 定义英文文本
 
-```bash
-pnpm run dev
-```
+3. 路由配置：
 
-### 构建
+   - 使用 `LocaleLink` 组件进行页面跳转
+   - URL 格式：`/{lang}/path`（如：'/zh/about'）
 
-```bash
-pnpm run build
+4. 组件开发：
+   - 使用 `useBaseRoutePage` hook 获取翻译函数
+   - 从 `@config/Identifier.I18n` 引入国际化 key
+   - 避免硬编码文本，始终使用国际化 key
+
+### 主题系统
+
+- 基于 Tailwind CSS 的主题配置
+- 支持暗色/亮色模式
+- 自定义设计令牌系统
+
+### API 集成
+
+项目提供了强大的 API 请求处理机制，基于插件化架构设计：
+
+#### 请求控制器
+
+使用 `RequestController` 统一管理 API 请求：
+
+```typescript
+@injectable()
+export class RequestController extends SliceStore<RequestControllerState> {
+  constructor(
+    @inject(FeApi) private readonly feApi: FeApi,
+    @inject(UserApi) private readonly userApi: UserApi
+  ) {
+    super(createDefaultState);
+  }
+
+  // API 调用示例
+  async onRandomUser() {
+    if (this.state.randomUserState.loading) return;
+
+    this.setState({
+      randomUserState: { loading: true, result: null, error: null }
+    });
+
+    try {
+      const result = await this.userApi.getRandomUser();
+      this.setState({
+        randomUserState: { loading: false, result, error: null }
+      });
+    } catch (error) {
+      this.setState({
+        randomUserState: { loading: false, result: null, error }
+      });
+    }
+  }
+}
 ```
 
-### 测试
+#### 请求插件系统
+
+项目内置多个实用的请求插件：
+
+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 数据
+});
+```
 
-```bash
-pnpm run test
+#### 请求调度器
+
+使用 `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
+});
+```
 
-### Q: 如何切换主题？
+#### 最佳实践
 
-A: 项目支持主题切换功能，通过 ThemeController 进行控制。
+1. API 定义：
 
-### Q: 如何添加新的语言支持？
+   - 在 `src/base/apis` 中集中管理 API 定义
+   - 使用 TypeScript 接口定义请求和响应类型
+   - 遵循 RESTful API 设计规范
 
-A: 在 `public/locales/` 目录下添加新的语言文件，并在 `i18n.ts` 中配置。
+2. 错误处理：
 
-## 许可证
+   - 使用 `ApiCatchPlugin` 统一处理错误
+   - 定义清晰的错误类型和错误码
+   - 提供友好的错误提示
+
+3. 请求状态管理：
+
+   - 使用 `SliceStore` 管理请求状态
+   - 处理加载、成功、错误等状态
+   - 实现请求防抖和节流
+
+4. Mock 数据：
+   - 提供合理的 Mock 数据结构
+   - 支持动态 Mock 数据生成
+   - 便于本地开发和测试
+
+### 控制器模式
+
+提供多个开箱即用的控制器：
+
+- JSONStorageController
+- RequestController
+- RouterController
+- UserController
+- ThemeController
+
+## 📚 开发指南
+
+### API 开发规范
+
+1. 在 `src/base/apis` 定义接口
+2. 支持 Mock 数据配置
+
+### 新增页面流程
+
+1. 在 `src/pages` 创建页面组件
+2. 更新 `config/app.router.json`
+3. 添加对应的控制器（如需要）
+
+### 国际化开发
 
-ISC
+1. 在 `public/locales` 添加翻译文件
+2. 使用 `useTranslation` hook 进行调用
+3. 支持按需加载语言包