@qlover/create-app 0.6.2 → 0.7.0

package/dist/templates/react-app/docs/zh/global.md

@@ -23,6 +23,8 @@
 ### 3. 文件结构
 
 ```
+config/
+├── common.ts               # 全局变量名称配置
 src/
 ├── core/
 │   ├── globals.ts              # 全局变量定义
@@ -105,8 +107,8 @@ const bootstrap = new Bootstrap({
     register: new IocRegisterImpl({ pathname, appConfig })
   },
   globalOptions: {
-    sources: globals,           // 全局变量源
-    target: browserGlobalsName  // 注入目标名称
+    sources: globals, // 全局变量源
+    target: browserGlobalsName // 注入目标名称
   }
 });
 ```
@@ -131,7 +133,7 @@ export class InjectGlobal implements BootstrapExecutorPlugin {
 
   onBefore(context: BootstrapContext): void {
     const { sources, target } = this.config;
-    
+
     // 如果 target 是字符串，注入到 root 对象
     if (typeof target === 'string') {
       Object.assign(context.parameters.root!, {
@@ -192,13 +194,13 @@ window = {
 function someFunction() {
   // 访问全局日志器
   window.feGlobals.logger.info('这是一条日志');
-  
+
   // 访问应用配置
   const appName = window.feGlobals.appConfig.appName;
-  
+
   // 访问本地存储
   window.feGlobals.localStorage.set('key', 'value');
-  
+
   // 访问对话框处理器
   window.feGlobals.dialogHandler.showMessage('Hello World');
 }
@@ -213,16 +215,12 @@ function MyComponent() {
   const handleClick = () => {
     // 使用全局日志器
     window.feGlobals.logger.info('用户点击了按钮');
-    
+
     // 使用全局对话框
     window.feGlobals.dialogHandler.showMessage('操作成功');
   };
 
-  return (
-    <button onClick={handleClick}>
-      点击我
-    </button>
-  );
+  return <button onClick={handleClick}>点击我</button>;
 }
 ```
 
@@ -234,14 +232,14 @@ export class SomeService {
   async doSomething() {
     // 使用全局日志器记录操作
     window.feGlobals.logger.info('开始执行操作');
-    
+
     try {
       // 业务逻辑
       const result = await this.performOperation();
-      
+
       // 使用全局对话框显示结果
       window.feGlobals.dialogHandler.showMessage('操作完成');
-      
+
       return result;
     } catch (error) {
       // 使用全局日志器记录错误
@@ -260,10 +258,10 @@ export function saveUserData(data: any) {
   try {
     // 使用全局存储
     window.feGlobals.localStorage.set('userData', data);
-    
+
     // 使用全局日志器
     window.feGlobals.logger.info('用户数据已保存');
-    
+
     return true;
   } catch (error) {
     window.feGlobals.logger.error('保存用户数据失败:', error);
@@ -324,7 +322,7 @@ if (window.feGlobals) {
   // 扩展可以访问应用的全局服务
   const appConfig = window.feGlobals.appConfig;
   const logger = window.feGlobals.logger;
-  
+
   // 执行扩展逻辑
   logger.info('浏览器扩展已加载');
 }
@@ -337,10 +335,10 @@ if (window.feGlobals) {
 ```tsx
 // ✅ 好的设计：只暴露核心服务
 export const globals = {
-  appConfig,      // 应用配置
-  logger,         // 日志服务
-  localStorage,   // 存储服务
-  dialogHandler,  // 对话框服务
+  appConfig, // 应用配置
+  logger, // 日志服务
+  localStorage, // 存储服务
+  dialogHandler // 对话框服务
   // 其他核心服务...
 };
 
@@ -409,17 +407,19 @@ console.log('日志器:', window.feGlobals?.logger);
 ### 2. 常见问题
 
 **问题 1：全局变量未注入**
+
 ```tsx
 // 检查 Bootstrap 配置
 const bootstrap = new Bootstrap({
   globalOptions: {
-    sources: globals,           // 确保 sources 正确
-    target: browserGlobalsName  // 确保 target 正确
+    sources: globals, // 确保 sources 正确
+    target: browserGlobalsName // 确保 target 正确
   }
 });
 ```
 
 **问题 2：类型错误**
+
 ```tsx
 // 检查类型声明
 declare global {
@@ -430,6 +430,7 @@ declare global {
 ```
 
 **问题 3：全局变量被修改**
+
 ```tsx
 // 确保使用 Object.freeze
 Object.freeze(Object.assign({}, sources));
@@ -466,8 +467,8 @@ export const globals = {
   appConfig,
   logger,
   // 不要暴露 API 密钥、密码等敏感信息
-  apiKey: 'secret_key',  // 危险！
-  password: 'password'    // 危险！
+  apiKey: 'secret_key', // 危险！
+  password: 'password' // 危险！
 };
 
 // ✅ 只暴露必要的服务
@@ -507,4 +508,4 @@ export const browserGlobalsName = 'feGlobals'; // 而不是通用的 'globals'
 4. **第三方集成**：便于与第三方库集成
 5. **开发体验**：提升开发效率和调试体验
 
-通过合理使用全局变量注入，可以让应用的核心服务在任何地方都能方便地访问，同时保持代码的整洁和类型安全。 
+通过合理使用全局变量注入，可以让应用的核心服务在任何地方都能方便地访问，同时保持代码的整洁和类型安全。

package/dist/templates/react-app/docs/zh/i18n.md

@@ -0,0 +1,268 @@
+# 国际化系统
+
+## 概述
+
+国际化系统采用基于标识符别名的方案，结合 i18next 和 TypeScript 注释，实现了一个类型安全、易维护的国际化解决方案。主要特点：
+
+- **标识符别名**：使用常量而非字符串作为翻译键
+- **TypeScript 注释**：通过注释自动生成翻译资源
+- **类型安全**：完整的类型检查和自动补全
+- **路由集成**：支持 URL 路径中的语言参数
+- **自动生成**：自动从源码生成翻译文件
+- **开发友好**：完整的开发工具支持
+
+## 核心概念
+
+### 1. 标识符别名
+
+使用常量替代字符串键值，提供更好的类型安全和维护性：
+
+```typescript
+// config/Identifier/common.ts
+
+/**
+ * @description Theme switcher default theme label
+ * @localZh 默认主题
+ * @localEn Default Theme
+ */
+export const HEADER_THEME_DEFAULT = 'header.theme.default';
+
+/**
+ * @description Theme switcher dark theme label
+ * @localZh 暗色主题
+ * @localEn Dark Theme
+ */
+export const HEADER_THEME_DARK = 'header.theme.dark';
+```
+
+### 2. 自动生成配置
+
+在 `vite.config.ts` 中配置自动生成：
+
+```typescript
+import ts2Locales from '@brain-toolkit/ts2locales/vite';
+
+export default defineConfig({
+  plugins: [
+    ts2Locales({
+      locales: ['en', 'zh'],
+      options: [
+        {
+          source: './config/Identifier/common.ts',
+          target: './public/locales/{{lng}}/common.json'
+        },
+        {
+          source: './config/Identifier/error.ts',
+          target: './public/locales/{{lng}}/common.json'
+        }
+      ]
+    })
+  ]
+});
+```
+
+### 3. i18n 服务配置
+
+```typescript
+// config/i18n.ts
+export default {
+  fallbackLng: 'en',
+  debug: false,
+  interpolation: {
+    escapeValue: false
+  },
+  ns: ['common'],
+  defaultNS: 'common',
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json'
+  },
+  supportedLngs: ['en', 'zh']
+} as const;
+```
+
+## 使用方式
+
+### 1. 定义翻译键
+
+```typescript
+// config/Identifier/page.ts
+
+/**
+ * @description Home page title
+ * @localZh 首页
+ * @localEn Home
+ */
+export const PAGE_HOME_TITLE = 'page.home.title';
+
+/**
+ * @description Home page welcome message
+ * @localZh 欢迎来到我们的应用
+ * @localEn Welcome to our application
+ */
+export const PAGE_HOME_WELCOME = 'page.home.welcome';
+```
+
+### 2. 在组件中使用
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import * as i18nKeys from '@config/Identifier/page';
+
+function HomePage() {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t(i18nKeys.PAGE_HOME_TITLE)}</h1>
+      <p>{t(i18nKeys.PAGE_HOME_WELCOME)}</p>
+    </div>
+  );
+}
+```
+
+### 3. 带参数的翻译
+
+```typescript
+/**
+ * @description Welcome user message
+ * @localZh 欢迎，{{name}}！
+ * @localEn Welcome, {{name}}!
+ */
+export const USER_WELCOME = 'user.welcome';
+
+function Welcome({ username }: { username: string }) {
+  const { t } = useTranslation();
+  return <h1>{t(i18nKeys.USER_WELCOME, { name: username })}</h1>;
+}
+```
+
+### 4. 语言切换
+
+```tsx
+import { IOC } from '@/core/IOC';
+import { I18nService } from '@/base/services/I18nService';
+
+function LanguageSwitcher() {
+  const i18nService = IOC(I18nService);
+  const currentLang = i18nService.getCurrentLanguage();
+
+  const handleChange = (lang: string) => {
+    i18nService.changeLanguage(lang);
+  };
+
+  return (
+    <select value={currentLang} onChange={(e) => handleChange(e.target.value)}>
+      <option value="zh">中文</option>
+      <option value="en">English</option>
+    </select>
+  );
+}
+```
+
+## 最佳实践
+
+### 1. 标识符组织
+
+- **命名规范**：
+
+  ```typescript
+  // 页面相关
+  PAGE_HOME_TITLE;
+  PAGE_ABOUT_DESCRIPTION;
+
+  // 功能模块相关
+  AUTH_LOGIN_BUTTON;
+  AUTH_LOGOUT_CONFIRM;
+
+  // 公共组件相关
+  COMMON_SUBMIT_BUTTON;
+  COMMON_CANCEL_BUTTON;
+  ```
+
+- **文件组织**：
+  ```
+  config/
+  ├── Identifier/
+  │   ├── common.ts     // 公共文本
+  │   ├── page.ts       // 页面文本
+  │   ├── error.ts      // 错误信息
+  │   └── auth.ts       // 认证相关
+  ```
+
+### 2. 注释规范
+
+```typescript
+/**
+ * @description 简短的描述，说明文本用途
+ * @localZh 中文翻译文本
+ * @localEn 英文翻译文本
+ */
+```
+
+### 3. 类型安全
+
+```typescript
+// 使用类型导入确保键值存在
+import * as i18nKeys from '@config/Identifier';
+
+// 类型检查会捕获错误的键值
+t(i18nKeys.NONEXISTENT_KEY); // TS 错误
+```
+
+### 4. 动态内容
+
+```typescript
+/**
+ * @description File upload progress
+ * @localZh 已上传 {{count}} 个文件，共 {{total}} 个
+ * @localEn Uploaded {{count}} files out of {{total}}
+ */
+export const UPLOAD_PROGRESS = 'upload.progress';
+
+// 使用
+t(i18nKeys.UPLOAD_PROGRESS, { count: 3, total: 10 });
+```
+
+## 工作流程
+
+1. **开发阶段**：
+   - 在 Identifier 文件中定义翻译键和注释
+   - 使用标识符别名在代码中引用翻译
+   - 运行开发服务器时自动生成翻译文件
+
+2. **构建阶段**：
+   - 自动检查翻译完整性
+   - 生成生产环境翻译文件
+   - 优化翻译资源加载
+
+3. **运行时**：
+   - 根据 URL 检测语言
+   - 按需加载翻译资源
+   - 响应语言切换事件
+
+## 常见问题
+
+### 1. 翻译未生效
+
+检查以下几点：
+
+- 确保标识符正确导出
+- 检查注释格式是否规范
+- 验证翻译文件是否生成
+- 确认语言检测正确
+
+### 2. 类型错误
+
+可能的解决方案：
+
+- 检查标识符导入路径
+- 确保使用正确的标识符
+- 更新 TypeScript 类型定义
+
+### 3. 性能优化
+
+开发建议：
+
+- 合理拆分翻译文件
+- 使用翻译资源预加载
+- 避免重复翻译键

package/dist/templates/react-app/docs/zh/index.md

@@ -0,0 +1,173 @@
+# React 应用开发文档
+
+## 简介
+
+这是一个基于 React 18 的现代化前端应用模板，集成了完整的开发框架和工具链。本模板提供了一套完整的开发解决方案，包括状态管理、路由管理、国际化、主题系统等核心功能。
+
+### 主要特性
+
+- 🚀 **现代化技术栈**：基于 React 18、TypeScript、Vite
+- 🎨 **主题定制**：支持动态主题切换，深色模式
+- 🌍 **国际化**：内置多语言支持
+- 📦 **状态管理**：基于发布订阅的响应式状态管理
+- 🔑 **认证系统**：完整的用户认证解决方案
+- 🛠️ **开发工具**：ESLint、Prettier、TypeScript
+- 📱 **响应式设计**：支持多端适配
+- 🧪 **测试支持**：集成单元测试和组件测试
+
+## 快速开始
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建生产版本
+npm run build
+```
+
+## 文档导航
+
+### 架构指南
+
+- [项目结构说明](./project-structure.md)
+- [开发规范指南](./development-guide.md)
+- [构建部署指南](./deployment.md)
+
+### 核心功能
+
+- [路由开发指南](./router.md)
+- [状态管理指南](./store.md)
+- [国际化开发指南](./i18n.md)
+- [主题开发指南](./theme.md)
+- [请求系统指南](./request.md)
+
+### 组件开发
+
+- [组件开发指南](./component-guide.md)
+- [TypeScript 开发规范](./typescript-guide.md)
+- [样式开发指南](./styling-guide.md)
+
+### 工具和测试
+
+- [测试开发指南](./testing.md)
+- [Git 工作流指南](./git-workflow.md)
+- [性能优化指南](./performance.md)
+
+### 安全和最佳实践
+
+- [安全开发指南](./security.md)
+- [文档编写指南](./documentation.md)
+
+## 目录结构
+
+```
+docs/zh/
+├── index.md                # 本文档
+├── project-structure.md    # 项目结构说明
+├── development-guide.md    # 开发规范指南
+├── router.md              # 路由开发指南
+├── store.md               # 状态管理指南
+├── i18n.md                # 国际化开发指南
+├── theme.md               # 主题开发指南
+└── ...
+```
+
+## 核心概念
+
+### 1. 启动流程
+
+应用采用插件化的启动流程：
+
+```
+Bootstrap 初始化 → 加载插件 → 初始化服务 → 渲染应用
+```
+
+### 2. 状态管理
+
+基于发布订阅模式的响应式状态管理：
+
+```
+Action 触发 → Store 更新 → 组件重渲染
+```
+
+### 3. 路由系统
+
+配置式路由管理：
+
+```
+路由配置 → 自动生成路由 → 代码分割 → 按需加载
+```
+
+### 4. 国际化
+
+基于 TypeScript 注释的自动国际化：
+
+```
+注释定义 → 自动生成资源 → 动态加载 → 语言切换
+```
+
+## 开发流程
+
+1. **需求分析**
+   - 理解业务需求
+   - 设计技术方案
+   - 评估开发周期
+
+2. **开发阶段**
+   - 遵循开发规范
+   - 编写单元测试
+   - 进行代码审查
+
+3. **测试阶段**
+   - 单元测试
+   - 集成测试
+   - 性能测试
+
+4. **部署上线**
+   - 构建优化
+   - 部署配置
+   - 监控告警
+
+## 常见问题
+
+### 1. 开发环境配置
+
+- 确保 Node.js 版本 >= 16
+- 使用推荐的 IDE 配置
+- 安装必要的开发工具
+
+### 2. 构建相关
+
+- 常见构建错误解决
+- 性能优化建议
+- 部署注意事项
+
+### 3. 开发相关
+
+- 代码规范问题
+- 类型系统使用
+- 组件开发规范
+
+## 贡献指南
+
+1. Fork 项目
+2. 创建特性分支
+3. 提交变更
+4. 发起 Pull Request
+
+## 更新日志
+
+查看 [CHANGELOG.md](../../CHANGELOG.md) 了解详细的更新历史。
+
+## 支持和帮助
+
+- 提交 Issue
+- 查看 Wiki
+- 参与讨论
+
+## 许可证
+
+本项目基于 [ISC 许可证](../../LICENSE) 开源。