@qlover/create-app 0.6.1 → 0.6.3

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

@@ -0,0 +1,408 @@
+# 路由系统
+
+## 概述
+
+路由系统采用配置式路由，通过 `RouteService` 和 `RouterLoader` 实现了一个灵活、可扩展的路由管理方案。主要特点：
+
+- **配置驱动**：通过配置文件定义路由，无需手动编写路由组件
+- **代码分割**：自动处理组件的懒加载
+- **类型安全**：完整的 TypeScript 类型支持
+- **状态管理**：与 Store 系统无缝集成
+- **国际化支持**：内置多语言路由支持
+- **元数据扩展**：支持路由级别的元数据配置
+
+## 路由配置
+
+### 1. 路径配置（path）
+
+`path` 定义了路由的 URL 路径模式：
+
+```typescript
+{
+  // 基础路径
+  path: '/about',                  // 匹配 /about
+
+  // 动态参数
+  path: '/user/:id',              // 匹配 /user/123
+
+  // 可选参数
+  path: '/posts/:id?',            // 匹配 /posts 和 /posts/1
+
+  // 多层级路径
+  path: '/blog/:category/:id',    // 匹配 /blog/tech/123
+
+  // 通配符
+  path: '*',                      // 匹配任何未定义的路径
+
+  // 国际化路径
+  path: '/:lng/dashboard',        // 匹配 /en/dashboard, /zh/dashboard
+
+  // 索引路由（默认子路由）
+  index: true                     // 父路由的默认渲染内容
+}
+```
+
+### 2. 组件配置（element）
+
+`element` 使用字符串标识符来引用实际的组件，这种设计有以下优势：
+
+1. **自动代码分割**：
+
+```typescript
+// App.tsx
+function getAllPages() {
+  // 自动扫描 pages 目录下的所有组件
+  const modules = import.meta.glob('./pages/**/*.tsx');
+  return Object.keys(modules).reduce((acc, path) => {
+    // 将文件路径转换为组件标识符
+    const componentName = path.replace(/^\.\/pages\/(.*)\.tsx$/, '$1');
+    // 创建懒加载组件
+    acc[componentName] = () =>
+      lazy(
+        modules[path] as () => Promise<{
+          default: React.ComponentType<unknown>;
+        }>
+      );
+    return acc;
+  }, {} as ComponentValue);
+}
+```
+
+2. **组件映射规则**：
+
+```typescript
+{
+  // 基础组件映射
+  element: 'HomePage',           // 映射到 pages/HomePage.tsx
+
+  // 子目录组件
+  element: 'user/Profile',      // 映射到 pages/user/Profile.tsx
+
+  // 布局组件
+  element: 'layouts/Default',   // 映射到 pages/layouts/Default.tsx
+
+  // 特殊页面
+  element: '404',              // 映射到 pages/404.tsx
+
+  // 认证相关页面
+  element: 'auth/LoginPage'    // 映射到 pages/auth/LoginPage.tsx
+}
+```
+
+3. **组件加载过程**：
+
+```typescript
+class RouterLoader {
+  // 获取组件实现
+  getComponent(element: string): () => RouteComponentType {
+    const maps = this.getComponentMaps();
+    const component = maps[element];
+
+    if (!component) {
+      throw new Error(`Component not found: ${element}`);
+    }
+
+    return component;
+  }
+
+  // 转换为路由对象
+  toRoute(route: RouteConfigValue): RouteObject {
+    const { element, children, ...rest } = route;
+    const component = this.getComponent(element || '404');
+
+    return {
+      ...rest,
+      element: this.render({ ...rest, element: component }),
+      children: children?.map((child) => this.toRoute(child))
+    };
+  }
+}
+```
+
+4. **组件渲染流程**：
+
+```tsx
+// RouterRenderComponent.tsx
+export const RouterRenderComponent: RouterLoaderRender = (route) => {
+  const Component = route.element(); // 懒加载组件
+
+  return (
+    <Suspense fallback={<Loading fullscreen />}>
+      <BaseRouteProvider {...route.meta}>
+        <Component />
+      </BaseRouteProvider>
+    </Suspense>
+  );
+};
+```
+
+### 3. 完整路由示例
+
+```typescript
+export const baseRoutes: RouteConfigValue[] = [
+  // 重定向路由
+  {
+    path: '/',
+    element: 'base/RedirectPathname' // 处理默认语言重定向
+  },
+
+  // 主布局路由
+  {
+    path: '/:lng', // 语言参数
+    element: 'base/Layout', // 主布局组件
+    meta: {
+      category: 'main'
+    },
+    children: [
+      // 首页路由
+      {
+        index: true, // 默认子路由
+        element: 'base/HomePage', // 首页组件
+        meta: {
+          title: 'PAGE_HOME_TITLE',
+          icon: 'home',
+          localNamespace: 'common'
+        }
+      },
+
+      // 功能页面路由
+      {
+        path: 'dashboard', // 仪表盘页面
+        element: 'base/DashboardPage',
+        meta: {
+          title: 'PAGE_DASHBOARD_TITLE',
+          icon: 'dashboard'
+        }
+      }
+    ]
+  },
+
+  // 认证布局路由
+  {
+    path: '/:lng',
+    element: 'auth/Layout',
+    meta: {
+      category: 'auth'
+    },
+    children: [
+      {
+        path: 'login',
+        element: 'auth/LoginPage',
+        meta: {
+          title: 'PAGE_LOGIN_TITLE'
+        }
+      }
+    ]
+  }
+];
+```
+
+### 2. 路由类型定义
+
+```typescript
+interface RouteConfigValue {
+  path?: string; // 路由路径
+  element: string; // 组件标识符
+  children?: RouteConfigValue[]; // 子路由
+  meta?: RouteMeta; // 路由元数据
+  index?: boolean; // 是否为索引路由
+}
+
+interface RouteMeta {
+  title?: string; // 页面标题
+  description?: string; // 页面描述
+  icon?: string; // 页面图标
+  category?: string; // 路由分类
+  localNamespace?: string; // 国际化命名空间
+}
+```
+
+## 核心组件
+
+### 1. RouterLoader
+
+`RouterLoader` 负责将路由配置转换为实际的路由组件：
+
+```typescript
+class RouterLoader {
+  constructor(private readonly options: RouterLoaderOptions) {
+    if (!options.render) {
+      throw new Error('RouterLoader render is required');
+    }
+  }
+
+  // 转换路由配置为 React Router 路由对象
+  toRoute(route: RouteConfigValue): RouteObject {
+    const { render } = this.options;
+    const { element, children, ...rest } = route;
+
+    const component = this.getComponent(element || '404');
+    const Element = render({ ...rest, element: component });
+
+    return {
+      ...rest,
+      element: Element,
+      children: children?.map((child) => this.toRoute(child))
+    };
+  }
+}
+```
+
+### 2. RouteService
+
+`RouteService` 管理路由状态和导航：
+
+```typescript
+class RouteService extends StoreInterface<RouterServiceState> {
+  // 组合路径（添加语言前缀）
+  composePath(path: string): string {
+    const targetLang = I18nService.getCurrentLanguage();
+    return `/${targetLang}${path}`;
+  }
+
+  // 路由跳转
+  goto(path: string, options?: NavigateOptions): void {
+    path = this.composePath(path);
+    this.navigate?.(path, options);
+  }
+
+  // 更新路由配置
+  changeRoutes(routes: RouteConfigValue[]): void {
+    this.emit({ routes });
+  }
+}
+```
+
+### 3. RouterRenderComponent
+
+路由渲染组件，处理懒加载和页面上下文：
+
+```tsx
+export const RouterRenderComponent: RouterLoaderRender = (route) => {
+  const Component = route.element();
+
+  return (
+    <Suspense fallback={<Loading fullscreen />}>
+      <BaseRouteProvider {...route.meta}>
+        <Component />
+      </BaseRouteProvider>
+    </Suspense>
+  );
+};
+```
+
+## 使用方式
+
+### 1. 应用配置
+
+在应用入口处配置路由系统：
+
+```tsx
+function App() {
+  // 初始化路由加载器
+  const routerLoader = new RouterLoader({
+    componentMaps: getAllPages(),
+    render: RouterRenderComponent
+  });
+
+  // 获取路由配置
+  const routes = useStore(IOC(RouteService), (state) => state.routes);
+
+  // 创建路由器
+  const routerBase = useMemo(() => {
+    const routeList = routes.map((route) => routerLoader.toRoute(route));
+    return createBrowserRouter(routeList, {
+      basename: routerPrefix
+    });
+  }, [routes]);
+
+  return <RouterProvider router={routerBase} />;
+}
+```
+
+### 2. 页面导航
+
+在组件中使用路由服务进行导航：
+
+```tsx
+function LoginButton() {
+  const routeService = IOC(RouteService);
+
+  const handleLogin = () => {
+    routeService.goto('/login');
+  };
+
+  return <button onClick={handleLogin}>登录</button>;
+}
+```
+
+### 3. 路由守卫
+
+通过 `BaseRouteProvider` 实现路由级别的功能：
+
+```tsx
+function BaseRouteProvider(props: PropsWithChildren<RouteMeta>) {
+  const { t } = useTranslation();
+
+  // 自动设置页面标题
+  useDocumentTitle(props.title ? t(props.title) : IOC('AppConfig').appName);
+
+  return (
+    <BaseRoutePageContext.Provider value={props}>
+      {props.children}
+    </BaseRoutePageContext.Provider>
+  );
+}
+```
+
+## 最佳实践
+
+1. **路由组织**
+   - 按功能模块组织路由配置
+   - 使用嵌套路由处理复杂页面结构
+   - 合理使用路由元数据
+
+2. **代码分割**
+   - 对大型页面组件进行代码分割
+   - 使用 Suspense 处理加载状态
+   - 预加载关键路由组件
+
+3. **类型安全**
+   - 为所有路由配置定义类型
+   - 使用常量管理路由路径
+   - 避免硬编码路由字符串
+
+4. **国际化**
+   - 使用路由参数处理多语言
+   - 配置页面级别的翻译命名空间
+   - 自动处理标题和描述的翻译
+
+## 常见问题
+
+### 1. 路由不生效
+
+检查以下几点：
+
+- 确保路由配置格式正确
+- 检查组件映射是否正确配置
+- 验证路径是否包含语言前缀
+
+### 2. 页面加载失败
+
+可能的解决方案：
+
+- 检查组件是否正确导出
+- 确保懒加载配置正确
+- 查看网络请求是否正常
+
+### 3. 类型错误
+
+常见解决方法：
+
+- 确保路由配置符合类型定义
+- 检查组件属性是否完整
+- 使用正确的路由元数据类型
+
+```
+
+```

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

@@ -0,0 +1,321 @@
+# Store 状态管理
+
+## 核心思想
+
+Store 的设计理念基于以下几个核心思想：
+
+1. **逻辑与 UI 分离**
+   - 业务逻辑集中在 Store 中管理
+   - UI 组件只负责渲染和用户交互
+   - 通过 IOC 容器实现逻辑的依赖注入
+
+2. **响应式数据流**
+   - 基于发布订阅模式
+   - 状态变更自动触发 UI 更新
+   - 精确的组件重渲染控制
+
+3. **状态分片管理**
+   - 将复杂状态分解为独立的分片
+   - 每个分片负责特定的业务领域
+   - 分片之间可以组合和通信
+
+## 工作原理
+
+### 1. 状态订阅机制
+
+```typescript
+// Store 内部实现了发布订阅机制
+class SliceStore<T> {
+  private listeners = new Set<(state: T) => void>();
+
+  // 发布状态更新
+  protected emit(newState: T) {
+    this.state = newState;
+    this.listeners.forEach((listener) => listener(this.state));
+  }
+
+  // 订阅状态变化
+  subscribe(listener: (state: T) => void) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}
+```
+
+### 2. 状态更新流程
+
+```
+用户操作 → 调用 Store 方法 → 更新状态 → 通知订阅者 → UI 更新
+```
+
+1. 用户触发操作（如点击按钮）
+2. 调用 Store 中的方法
+3. Store 使用 emit 发布新状态
+4. 订阅该状态的组件收到通知
+5. 组件重新渲染，显示最新状态
+
+### 3. 组件集成
+
+```tsx
+// 在组件中使用 Store
+function UserProfile() {
+  // useStore hook 自动处理订阅和取消订阅
+  const user = useStore(IOC(UserService), (state) => state.userInfo);
+
+  return <div>{user.name}</div>;
+}
+```
+
+### 4. 状态分片示例
+
+```typescript
+// 用户认证分片
+class AuthStore extends StoreInterface<AuthState> {
+  constructor() {
+    super(() => ({
+      isLoggedIn: false,
+      user: null
+    }));
+  }
+
+  login(credentials: Credentials) {
+    // 处理登录逻辑
+    this.emit({
+      isLoggedIn: true,
+      user: userData
+    });
+  }
+}
+
+// 主题设置分片
+class ThemeStore extends StoreInterface<ThemeState> {
+  constructor() {
+    super(() => ({
+      mode: 'light',
+      colors: defaultColors
+    }));
+  }
+
+  toggleTheme() {
+    const mode = this.state.mode === 'light' ? 'dark' : 'light';
+    this.emit({
+      ...this.state,
+      mode
+    });
+  }
+}
+```
+
+## 概述
+
+Store 是应用的状态管理解决方案，基于 `@qlover/slice-store-react` 实现。它采用分片（Slice）的方式来管理状态，具有以下特点：
+
+- **类型安全**：基于 TypeScript，提供完整的类型推导
+- **轻量级**：无需复杂的配置，易于使用
+- **高性能**：精确的组件更新，避免不必要的渲染
+- **模块化**：支持状态分片，便于管理大型应用
+- **IOC 集成**：与依赖注入系统完美配合
+
+## 核心概念
+
+### 1. Store 接口
+
+Store 系统基于两个核心接口：
+
+#### StoreStateInterface
+
+```typescript
+/**
+ * Store 状态接口
+ *
+ * 作用：定义 store 状态对象的契约
+ * 核心思想：为 store 状态强制实施一致的结构
+ * 主要功能：作为所有 store 状态类型的基础
+ * 主要目的：确保状态类型安全和可扩展性
+ */
+interface StoreStateInterface {
+  // 可以在这里定义自己的属性
+  // ...
+}
+```
+
+#### StoreInterface
+
+```typescript
+/**
+ * Store 接口
+ *
+ * 作用：所有状态存储的抽象基类
+ * 核心思想：提供统一的状态管理 API，包含重置和克隆辅助方法
+ * 主要功能：扩展 SliceStore，添加 resetState 和 cloneState 工具方法
+ * 主要目的：简化 store 实现并确保一致性
+ */
+abstract class StoreInterface<
+  T extends StoreStateInterface
+> extends SliceStore<T> {
+  constructor(protected stateFactory: () => T) {
+    super(stateFactory);
+  }
+
+  // 重置 store 状态
+  resetState(): void {
+    this.emit(this.stateFactory());
+  }
+
+  // 克隆 store 状态
+  cloneState(source?: Partial<T>): T {
+    const cloned = clone(this.state);
+    if (typeof cloned === 'object' && cloned !== null) {
+      Object.assign(cloned, source);
+    }
+    return cloned;
+  }
+}
+```
+
+### 2. 状态分片
+
+状态分片（Slice）是将应用状态分割成独立的部分：
+
+```typescript
+// 用户状态分片示例
+class UserState implements StoreStateInterface {
+  isLoggedIn: boolean = false;
+  userInfo: {
+    name: string;
+    role: string;
+  } | null = null;
+}
+
+// Store 实现示例
+export class UserStore extends StoreInterface<UserState> {
+  constructor() {
+    super(() => new UserState());
+  }
+}
+```
+
+## 在项目中使用
+
+### 1. 创建 Store Controller
+
+```typescript
+import { StoreInterface, StoreStateInterface } from '@qlover/corekit-bridge';
+
+interface ExecutorState extends StoreStateInterface {
+  helloState: string;
+  tasks: Task[];
+}
+
+@injectable()
+export class ExecutorController extends StoreInterface<ExecutorState> {
+  constructor() {
+    super(() => ({
+      helloState: '',
+      tasks: []
+    }));
+  }
+
+  // 选择器
+  selector = {
+    helloState: (state: ExecutorState) => state.helloState,
+    tasks: (state: ExecutorState) => state.tasks
+  };
+}
+```
+
+### 2. 在组件中使用
+
+使用 `useStore` Hook 访问状态：
+
+```tsx
+function MyComponent() {
+  // 获取完整状态
+  const state = useStore(IOC(ExecutorController));
+
+  // 使用选择器获取特定状态
+  const helloState = useStore(
+    IOC(ExecutorController),
+    (controller) => controller.selector.helloState
+  );
+
+  return (
+    <div>
+      <h1>{helloState}</h1>
+    </div>
+  );
+}
+```
+
+### 3. 更新状态
+
+通过 controller 方法更新状态：
+
+```typescript
+@injectable()
+class ExecutorController extends StoreInterface<ExecutorState> {
+  // ... 构造函数等其他代码
+
+  updateHelloState(newState: string) {
+    this.emit({ ...this.state, helloState: newState });
+  }
+
+  async fetchTasks() {
+    const tasks = await api.getTasks();
+    this.emit({ ...this.state, tasks });
+  }
+
+  // 使用 cloneState 进行状态更新
+  updateWithClone(newState: Partial<ExecutorState>) {
+    this.emit(this.cloneState(newState));
+  }
+}
+```
+
+## 最佳实践
+
+1. **状态组织**
+   - 按功能模块划分状态
+   - 避免状态冗余
+   - 保持状态扁平化
+
+2. **性能优化**
+   - 使用选择器获取状态，避免不必要的重渲染
+   - 合理拆分组件，避免大组件订阅过多状态
+   - 使用 `cloneState` 方法确保状态更新的不可变性
+
+3. **类型安全**
+   - 为所有状态定义接口
+   - 使用 TypeScript 的类型推导
+   - 避免使用 any 类型
+
+4. **与启动器集成**
+   - 在 Bootstrap 阶段初始化 store
+   - 通过 IOC 容器管理 store 实例
+   - 使用插件系统扩展功能
+
+## 常见问题
+
+### 1. 状态更新不生效
+
+检查以下几点：
+
+- 确保正确使用 `emit` 方法更新状态
+- 使用 `cloneState` 方法确保状态不可变性
+- 检查组件是否正确订阅了状态
+
+### 2. 组件重复渲染
+
+可能的解决方案：
+
+- 使用选择器只订阅需要的状态
+- 检查依赖项是否正确设置
+- 考虑使用 React.memo 优化组件
+
+### 3. TypeScript 类型报错
+
+常见解决方法：
+
+- 确保正确继承 StoreInterface
+- 检查泛型参数是否正确
+- 确保状态类型实现了 StoreStateInterface