@qlover/create-app 0.7.15 → 0.8.0

package/dist/templates/react-app/docs/zh/development-guide.md

@@ -1,274 +1,431 @@
-# 开发规范指南
+# 开发指南
 
-## 目录
+> **📖 本文档提供完整的页面开发流程和实战指南，帮助你快速上手项目开发。**
 
-1. [项目结构规范](#项目结构规范)
-2. [代码风格规范](#代码风格规范)
-3. [组件开发规范](#组件开发规范)
-4. [状态管理规范](#状态管理规范)
-5. [路由开发规范](#路由开发规范)
-6. [国际化开发规范](#国际化开发规范)
-7. [主题样式规范](#主题样式规范)
-8. [测试规范](#测试规范)
-9. [文档规范](#文档规范)
+## 📋 目录
 
-## 项目结构规范
+- [开发一个页面需要什么](#-开发一个页面需要什么)
+- [完整开发流程](#-完整开发流程)
+- [实战示例：用户列表页](#-实战示例用户列表页)
+- [常见场景](#-常见场景)
+- [代码规范](#-代码规范)
+- [开发工具](#-开发工具)
 
-> 💡 这里仅列出基本规范，完整的项目结构说明请参考 [项目结构文档](./project-structure.md)
+---
 
-### 1. 目录结构
+## 🎯 开发一个页面需要什么
+
+### 核心清单
+
+一个完整的页面通常需要以下组成部分：
 
 ```
-src/
-├── base/               # 基础功能实现
-│   ├── cases/         # 业务场景实现
-│   ├── services/      # 核心服务实现
-│   └── types/         # 类型定义
-├── core/              # 核心功能
-│   ├── bootstraps/    # 启动相关
-│   ├── registers/     # 注册器
-│   └── IOC.ts         # IOC 容器
-├── pages/             # 页面组件
-│   ├── auth/          # 认证相关页面
-│   └── base/          # 基础页面
-├── styles/            # 样式文件
-│   └── css/
-│       ├── themes/    # 主题相关
-│       └── antd-themes/ # Ant Design 主题
-├── uikit/             # UI 组件库
-│   ├── components/    # 通用组件
-│   ├── contexts/      # React Context
-│   ├── hooks/         # 自定义 Hooks
-│   └── providers/     # 提供者组件
-└── App.tsx            # 应用入口
+✅ 1. 接口定义 (Port)           - base/port/XxxServiceInterface.ts
+✅ 2. 服务实现 (Service)         - base/services/XxxService.ts
+✅ 3. API 适配器 (可选)          - base/apis/xxxApi/XxxApi.ts
+✅ 4. 路由配置                   - config/app.router.ts
+✅ 5. i18n 文本定义              - config/Identifier/pages/page.xxx.ts
+✅ 6. 页面组件                   - pages/xxx/XxxPage.tsx
+✅ 7. IOC 注册 (如果是新服务)    - core/clientIoc/ClientIOCRegister.ts
+✅ 8. 测试文件                   - __tests__/src/pages/xxx/XxxPage.test.tsx
 ```
 
-### 2. 命名规范
+### 依赖关系图
 
-- **文件命名**：
-  - 组件文件：`PascalCase.tsx`（如：`UserProfile.tsx`）
-  - 工具文件：`camelCase.ts`（如：`formatDate.ts`）
-  - 类型文件：`PascalCase.types.ts`（如：`User.types.ts`）
-  - 样式文件：`camelCase.css`（如：`buttonStyles.css`）
+```
+┌─────────────────────────────────────────┐
+│  路由配置 (app.router.ts)                │
+│  定义页面路径和元数据                    │
+└──────────────┬──────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│  页面组件 (XxxPage.tsx)                  │
+│  - 使用 useIOC 获取服务                  │
+│  - 使用 useStore 订阅状态                │
+│  - 使用 useAppTranslation 获取翻译       │
+│  - 处理 UI 渲染和用户交互                │
+└──────────────┬──────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│  服务层 (XxxService.ts)                  │
+│  - 实现业务逻辑                          │
+│  - 继承 StoreInterface                   │
+│  - 依赖注入其他服务                      │
+└──────────────┬──────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│  接口定义 (XxxServiceInterface.ts)       │
+│  - 定义服务契约                          │
+│  - 便于测试和 mock                       │
+└─────────────────────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│  API 适配器 (XxxApi.ts)                  │
+│  - 封装 HTTP 请求                        │
+│  - 转换数据格式                          │
+└─────────────────────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│  i18n 文本 (page.xxx.ts)                 │
+│  - 定义页面所有文本的 Key                │
+│  - 自动生成翻译文件                      │
+└─────────────────────────────────────────┘
+```
 
-- **目录命名**：
-  - 全小写，使用连字符分隔（如：`user-profile/`）
-  - 功能模块使用单数形式（如：`auth/`，而不是 `auths/`）
+---
 
-## 代码风格规范
+## 🚀 完整开发流程
 
-> 💡 这里仅列出基本规范，更多 TypeScript 和 React 开发规范请参考 [TypeScript 开发规范](./typescript-guide.md)
+### 流程图
 
-### 1. TypeScript 规范
+```
+📝 1. 需求分析
+   ├── 确定页面功能
+   ├── 确定数据来源（API）
+   └── 确定交互逻辑
+       ↓
+🎨 2. 定义 i18n Key
+   ├── 页面标题、按钮文本等
+   └── 错误提示、成功提示等
+       ↓
+🔌 3. 定义接口 (Port)
+   ├── 服务接口
+   └── 数据类型
+       ↓
+⚙️ 4. 实现服务 (Service)
+   ├── 继承 StoreInterface
+   ├── 实现业务逻辑
+   └── 依赖注入
+       ↓
+🌐 5. 实现 API 适配器（如果需要）
+   ├── 封装 HTTP 请求
+   └── 数据转换
+       ↓
+🗺️ 6. 配置路由
+   ├── 添加路由配置
+   └── 设置元数据
+       ↓
+🎭 7. 实现页面组件
+   ├── 使用 useIOC 获取服务
+   ├── 使用 useStore 订阅状态
+   └── 实现 UI 渲染
+       ↓
+🔗 8. 注册到 IOC（如果是新服务）
+   └── 在 ClientIOCRegister 中注册
+       ↓
+🧪 9. 编写测试
+   ├── 服务测试（逻辑）
+   ├── UI 测试（渲染）
+   └── 集成测试（流程）
+       ↓
+✅ 10. 自测和提交
+   ├── 功能自测
+   ├── 代码检查
+   └── 提交 PR
+```
 
-```typescript
-// 使用 interface 定义对象类型
-interface UserProfile {
-  id: string;
-  name: string;
-  age?: number; // 可选属性使用 ?
-}
+---
 
-// 使用 type 定义联合类型或工具类型
-type Theme = 'light' | 'dark' | 'pink';
-type Nullable<T> = T | null;
+## 📚 实战示例：用户列表页
 
-// 使用 enum 定义常量枚举
-enum UserRole {
-  ADMIN = 'ADMIN',
-  USER = 'USER',
-  GUEST = 'GUEST'
-}
+假设我们要开发一个用户列表页面，功能包括：
 
-// 函数类型声明
-function processUser(user: UserProfile): void {
-  // 实现
-}
+- 显示用户列表
+- 搜索用户
+- 分页加载
+- 查看用户详情
 
-// 泛型使用有意义的名称
-interface Repository<TEntity> {
-  find(id: string): Promise<TEntity>;
-}
-```
+### 1. 需求分析
 
-### 2. React 规范
+**功能清单：**
 
-```tsx
-// 函数组件使用 FC 类型
-interface Props {
-  name: string;
-  age: number;
-}
+- 📄 显示用户列表（头像、姓名、邮箱、角色）
+- 🔍 搜索用户（按姓名搜索）
+- 📃 分页（每页 10 条）
+- 👁️ 查看详情（点击跳转详情页）
+- 🔄 刷新列表
 
-const UserCard: FC<Props> = ({ name, age }) => {
-  return (
-    <div>
-      <h3>{name}</h3>
-      <p>{age}</p>
-    </div>
-  );
-};
+**数据来源：**
 
-// Hooks 规范
-const useUser = (userId: string) => {
-  const [user, setUser] = useState<UserProfile | null>(null);
-  const [loading, setLoading] = useState(false);
+- API: `GET /api/users?page=1&pageSize=10&keyword=xxx`
 
-  useEffect(() => {
-    // 实现
-  }, [userId]);
+### 2. 定义 i18n Key
+
+```typescript
+// config/Identifier/pages/page.users.ts
+
+/**
+ * @description User list page title
+ * @localZh 用户列表
+ * @localEn User List
+ */
+export const PAGE_USERS_TITLE = 'page.users.title';
+
+/**
+ * @description Search user placeholder
+ * @localZh 搜索用户姓名
+ * @localEn Search user name
+ */
+export const PAGE_USERS_SEARCH_PLACEHOLDER = 'page.users.search.placeholder';
+
+/**
+ * @description View user detail button
+ * @localZh 查看详情
+ * @localEn View Detail
+ */
+export const PAGE_USERS_VIEW_DETAIL = 'page.users.viewDetail';
+
+/**
+ * @description Refresh button
+ * @localZh 刷新
+ * @localEn Refresh
+ */
+export const PAGE_USERS_REFRESH = 'page.users.refresh';
 
-  return { user, loading };
-};
+/**
+ * @description Loading message
+ * @localZh 加载中...
+ * @localEn Loading...
+ */
+export const PAGE_USERS_LOADING = 'page.users.loading';
+
+/**
+ * @description Empty message
+ * @localZh 暂无用户数据
+ * @localEn No users found
+ */
+export const PAGE_USERS_EMPTY = 'page.users.empty';
 ```
 
-## 组件开发规范
+### 3. 定义接口和类型
 
-> 💡 这里仅列出基本规范，完整的组件开发指南请参考 [组件开发指南](./component-guide.md)
+```typescript
+// base/port/UserServiceInterface.ts
 
-### 1. 组件分类
+import { StoreInterface } from '@qlover/corekit-bridge';
 
-- **页面组件**：放在 `pages/` 目录下
-- **业务组件**：放在对应业务模块目录下
-- **通用组件**：放在 `uikit/components/` 目录下
-- **布局组件**：放在 `uikit/layouts/` 目录下
+/**
+ * 用户信息
+ */
+export interface UserInfo {
+  id: string;
+  name: string;
+  email: string;
+  avatar: string;
+  role: 'admin' | 'user';
+}
 
-### 2. 组件实现
+/**
+ * 用户列表查询参数
+ */
+export interface UserListParams {
+  page: number;
+  pageSize: number;
+  keyword?: string;
+}
 
-```tsx
-// 1. 导入顺序
-import { FC, useEffect, useState } from 'react'; // React 相关
-import { useTranslation } from 'react-i18next'; // 第三方库
-import { UserService } from '@/services/user'; // 项目内部导入
-import { Button } from './Button'; // 相对路径导入
+/**
+ * 用户列表响应
+ */
+export interface UserListResponse {
+  list: UserInfo[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
 
-// 2. 类型定义
-interface Props {
-  userId: string;
-  onUpdate?: (user: User) => void;
+/**
+ * 用户服务状态
+ */
+export interface UserServiceState extends StoreStateInterface {
+  users: UserInfo[];
+  total: number;
+  page: number;
+  pageSize: number;
+  loading: boolean;
+  error: Error | null;
 }
 
-// 3. 组件实现
-export const UserProfile: FC<Props> = ({ userId, onUpdate }) => {
-  // 3.1 Hooks 声明
-  const { t } = useTranslation();
-  const [user, setUser] = useState<User | null>(null);
+/**
+ * 用户服务接口
+ */
+export abstract class UserServiceInterface extends StoreInterface<UserServiceState> {
+  /**
+   * 获取用户列表
+   */
+  abstract fetchUsers(params: UserListParams): Promise<void>;
 
-  // 3.2 副作用
-  useEffect(() => {
-    // 实现
-  }, [userId]);
+  /**
+   * 搜索用户
+   */
+  abstract searchUsers(keyword: string): Promise<void>;
 
-  // 3.3 事件处理
-  const handleUpdate = () => {
-    // 实现
-  };
+  /**
+   * 刷新列表
+   */
+  abstract refreshUsers(): Promise<void>;
 
-  // 3.4 渲染方法
-  const renderHeader = () => {
-    return <h2>{user?.name}</h2>;
+  /**
+   * 选择器
+   */
+  abstract selector: {
+    users: (state: UserServiceState) => UserInfo[];
+    loading: (state: UserServiceState) => boolean;
+    total: (state: UserServiceState) => number;
   };
-
-  // 3.5 返回 JSX
-  return (
-    <div>
-      {renderHeader()}
-      <Button onClick={handleUpdate}>{t('common.update')}</Button>
-    </div>
-  );
-};
+}
 ```
 
-## 状态管理规范
+### 4. 实现 API 适配器
 
-> 💡 这里仅列出基本规范，完整的状态管理指南请参考 [Store 开发指南](./store.md)
+```typescript
+// base/apis/userApi/UserApi.ts
 
-### 1. Store 实现
+import { injectable, inject } from 'inversify';
+import { HttpClient } from '@/base/cases/HttpClient';
+import type {
+  UserListParams,
+  UserListResponse
+} from '@/base/port/UserServiceInterface';
 
-```typescript
-// 1. 状态接口定义
-interface UserState extends StoreStateInterface {
-  currentUser: User | null;
-  loading: boolean;
-  error: string | null;
+@injectable()
+export class UserApi {
+  constructor(@inject(HttpClient) private http: HttpClient) {}
+
+  /**
+   * 获取用户列表
+   */
+  async getUserList(params: UserListParams): Promise<UserListResponse> {
+    const response = await this.http.get('/api/users', { params });
+
+    // 转换后端数据格式
+    return {
+      list: response.data.items.map((item: any) => ({
+        id: item.user_id,
+        name: item.user_name,
+        email: item.user_email,
+        avatar: item.avatar_url,
+        role: item.user_role
+      })),
+      total: response.data.total_count,
+      page: response.data.current_page,
+      pageSize: response.data.page_size
+    };
+  }
 }
+```
+
+### 5. 实现服务
+
+```typescript
+// base/services/UserService.ts
+
+import { injectable, inject } from 'inversify';
+import {
+  UserServiceInterface,
+  UserServiceState
+} from '@/base/port/UserServiceInterface';
+import { UserApi } from '@/base/apis/userApi/UserApi';
+import type { UserListParams } from '@/base/port/UserServiceInterface';
 
-// 2. Store 实现
 @injectable()
-export class UserStore extends StoreInterface<UserState> {
-  constructor() {
+export class UserService extends UserServiceInterface {
+  constructor(@inject(UserApi) private api: UserApi) {
+    // 初始化状态
     super(() => ({
-      currentUser: null,
+      users: [],
+      total: 0,
+      page: 1,
+      pageSize: 10,
       loading: false,
       error: null
     }));
   }
 
-  // 3. 选择器定义
+  /**
+   * 选择器
+   */
   selector = {
-    currentUser: (state: UserState) => state.currentUser,
-    loading: (state: UserState) => state.loading
+    users: (state: UserServiceState) => state.users,
+    loading: (state: UserServiceState) => state.loading,
+    total: (state: UserServiceState) => state.total,
+    page: (state: UserServiceState) => state.page,
+    pageSize: (state: UserServiceState) => state.pageSize
   };
 
-  // 4. 操作方法
-  async fetchUser(id: string) {
+  /**
+   * 获取用户列表
+   */
+  async fetchUsers(params: UserListParams): Promise<void> {
     try {
-      this.emit({ ...this.state, loading: true });
-      const user = await api.getUser(id);
-      this.emit({ ...this.state, currentUser: user, loading: false });
+      // 1. 设置加载状态
+      this.emit({ ...this.state, loading: true, error: null });
+
+      // 2. 调用 API
+      const response = await this.api.getUserList(params);
+
+      // 3. 更新状态
+      this.emit({
+        users: response.list,
+        total: response.total,
+        page: response.page,
+        pageSize: response.pageSize,
+        loading: false,
+        error: null
+      });
     } catch (error) {
+      // 4. 错误处理
       this.emit({
         ...this.state,
-        error: error.message,
-        loading: false
+        loading: false,
+        error: error as Error
       });
     }
   }
-}
-```
 
-### 2. Store 使用
-
-```tsx
-function UserProfile() {
-  const userStore = IOC(UserStore);
-  const user = useStore(userStore, userStore.selector.currentUser);
-  const loading = useStore(userStore, userStore.selector.loading);
+  /**
+   * 搜索用户
+   */
+  async searchUsers(keyword: string): Promise<void> {
+    await this.fetchUsers({
+      page: 1,
+      pageSize: this.state.pageSize,
+      keyword
+    });
+  }
 
-  return <div>{loading ? <Loading /> : <UserInfo user={user} />}</div>;
+  /**
+   * 刷新列表
+   */
+  async refreshUsers(): Promise<void> {
+    await this.fetchUsers({
+      page: this.state.page,
+      pageSize: this.state.pageSize
+    });
+  }
 }
 ```
 
-## 路由开发规范
+### 6. 配置路由
 
-> 💡 这里仅列出基本规范，完整的路由开发指南请参考 [路由开发指南](./router.md)
-
-### 1. 基本规范
-
-- 路由配置集中管理在 `config/app.router.ts` 中
-- 使用声明式路由配置
-- 路由组件放置在 `pages` 目录下
-- 支持路由级别的代码分割
-- 路由配置包含元数据支持
+```typescript
+// config/app.router.ts
 
-### 2. 示例
+import * as i18nKeys from './Identifier/pages/page.users';
 
-```typescript
-// 路由配置示例
 export const baseRoutes: RouteConfigValue[] = [
   {
     path: '/:lng',
     element: 'base/Layout',
-    meta: {
-      category: 'main'
-    },
     children: [
+      // ... 其他路由
       {
         path: 'users',
-        element: 'users/UserList',
+        element: 'users/UserListPage',
         meta: {
           title: i18nKeys.PAGE_USERS_TITLE,
-          auth: true
+          requiresAuth: true, // 需要登录
+          category: 'main'
         }
       }
     ]
@@ -276,248 +433,767 @@ export const baseRoutes: RouteConfigValue[] = [
 ];
 ```
 
-更多路由配置和使用示例，请参考 [路由开发指南](./router.md)。
+### 7. 实现页面组件
+
+```typescript
+// pages/users/UserListPage.tsx
+
+import { useEffect, useState } from 'react';
+import { Table, Input, Button, Avatar, Space } from 'antd';
+import { ReloadOutlined, EyeOutlined } from '@ant-design/icons';
+import { useIOC } from '@/uikit/hooks/useIOC';
+import { useStore } from '@brain-toolkit/react-kit/hooks/useStore';
+import { useAppTranslation } from '@/uikit/hooks/useAppTranslation';
+import { IOCIdentifier } from '@config/IOCIdentifier';
+import * as i18nKeys from '@config/Identifier/pages/page.users';
+import type { UserInfo } from '@/base/port/UserServiceInterface';
+
+export default function UserListPage() {
+  // 1. 获取服务
+  const userService = useIOC(IOCIdentifier.UserServiceInterface);
+  const routeService = useIOC(IOCIdentifier.RouteServiceInterface);
+  const { t } = useAppTranslation();
+
+  // 2. 订阅状态
+  const users = useStore(userService, userService.selector.users);
+  const loading = useStore(userService, userService.selector.loading);
+  const total = useStore(userService, userService.selector.total);
+  const page = useStore(userService, userService.selector.page);
+  const pageSize = useStore(userService, userService.selector.pageSize);
+
+  // 3. 本地状态
+  const [keyword, setKeyword] = useState('');
+
+  // 4. 初始化加载
+  useEffect(() => {
+    userService.fetchUsers({ page: 1, pageSize: 10 });
+  }, []);
+
+  // 5. 事件处理
+  const handleSearch = () => {
+    userService.searchUsers(keyword);
+  };
+
+  const handleRefresh = () => {
+    userService.refreshUsers();
+  };
 
-## 国际化开发规范
+  const handlePageChange = (newPage: number, newPageSize: number) => {
+    userService.fetchUsers({ page: newPage, pageSize: newPageSize, keyword });
+  };
 
-> 💡 这里仅列出基本规范，完整的国际化开发指南请参考 [国际化开发指南](./i18n.md)
+  const handleViewDetail = (userId: string) => {
+    routeService.push(`/users/${userId}`);
+  };
 
-### 1. 基本规范
+  // 6. 表格列配置
+  const columns = [
+    {
+      title: t(i18nKeys.PAGE_USERS_COLUMN_AVATAR),
+      dataIndex: 'avatar',
+      key: 'avatar',
+      render: (avatar: string) => <Avatar src={avatar} />
+    },
+    {
+      title: t(i18nKeys.PAGE_USERS_COLUMN_NAME),
+      dataIndex: 'name',
+      key: 'name'
+    },
+    {
+      title: t(i18nKeys.PAGE_USERS_COLUMN_EMAIL),
+      dataIndex: 'email',
+      key: 'email'
+    },
+    {
+      title: t(i18nKeys.PAGE_USERS_COLUMN_ROLE),
+      dataIndex: 'role',
+      key: 'role',
+      render: (role: string) => t(`common.role.${role}`)
+    },
+    {
+      title: t(i18nKeys.PAGE_USERS_COLUMN_ACTIONS),
+      key: 'actions',
+      render: (_: any, record: UserInfo) => (
+        <Button
+          type="link"
+          icon={<EyeOutlined />}
+          onClick={() => handleViewDetail(record.id)}
+        >
+          {t(i18nKeys.PAGE_USERS_VIEW_DETAIL)}
+        </Button>
+      )
+    }
+  ];
 
-- 使用标识符常量管理翻译键
-- 通过 TypeScript 注释生成翻译资源
-- 支持多语言路由
-- 集中管理翻译文件
+  // 7. 渲染
+  return (
+    <div className="p-6">
+      {/* 页面标题 */}
+      <h1 className="text-2xl font-bold mb-4">
+        {t(i18nKeys.PAGE_USERS_TITLE)}
+      </h1>
+
+      {/* 搜索栏 */}
+      <div className="mb-4 flex gap-2">
+        <Input.Search
+          placeholder={t(i18nKeys.PAGE_USERS_SEARCH_PLACEHOLDER)}
+          value={keyword}
+          onChange={(e) => setKeyword(e.target.value)}
+          onSearch={handleSearch}
+          style={{ width: 300 }}
+        />
+        <Button
+          icon={<ReloadOutlined />}
+          onClick={handleRefresh}
+          loading={loading}
+        >
+          {t(i18nKeys.PAGE_USERS_REFRESH)}
+        </Button>
+      </div>
+
+      {/* 用户表格 */}
+      <Table
+        columns={columns}
+        dataSource={users}
+        rowKey="id"
+        loading={loading}
+        pagination={{
+          current: page,
+          pageSize: pageSize,
+          total: total,
+          onChange: handlePageChange,
+          showSizeChanger: true,
+          showTotal: (total) => `${t('common.total')} ${total} ${t('common.items')}`
+        }}
+        locale={{
+          emptyText: t(i18nKeys.PAGE_USERS_EMPTY)
+        }}
+      />
+    </div>
+  );
+}
+```
 
-### 2. 示例
+### 8. 注册到 IOC（如果是新服务）
 
 ```typescript
-/**
- * @description User list page title
- * @localZh 用户列表
- * @localEn User List
- */
-export const PAGE_USERS_TITLE = 'page.users.title';
+// core/clientIoc/ClientIOCRegister.ts
+
+export class ClientIOCRegister {
+  protected registerImplement(ioc: IOCContainerInterface): void {
+    // ... 其他服务注册
+
+    // 注册 UserService
+    ioc.bind(IOCIdentifier.UserServiceInterface, ioc.get(UserService));
+  }
+}
 ```
 
-更多国际化配置和使用示例，请参考 [国际化开发指南](./i18n.md)。
+### 9. 编写测试
 
-## 主题样式规范
+```typescript
+// __tests__/src/base/services/UserService.test.ts
 
-> 💡 这里仅列出基本规范，完整的主题开发指南请参考 [主题开发指南](./theme.md)
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { UserService } from '@/base/services/UserService';
 
-### 1. 基本规范
+describe('UserService', () => {
+  let userService: UserService;
+  let mockApi: any;
 
-- 使用 CSS 变量管理主题
-- 遵循 Tailwind CSS 使用规范
-- 组件样式模块化
-- 支持多主题切换
+  beforeEach(() => {
+    mockApi = {
+      getUserList: vi.fn()
+    };
 
-### 2. 示例
+    userService = new UserService(mockApi);
+  });
 
-```css
-:root {
-  --color-brand: 37 99 235;
-  --text-primary: 15 23 42;
-}
-```
+  it('should fetch users and update state', async () => {
+    const mockResponse = {
+      list: [
+        {
+          id: '1',
+          name: 'John',
+          email: 'john@example.com',
+          avatar: '',
+          role: 'user'
+        }
+      ],
+      total: 1,
+      page: 1,
+      pageSize: 10
+    };
 
-更多主题配置和使用示例，请参考 [主题开发指南](./theme.md)。
+    mockApi.getUserList.mockResolvedValue(mockResponse);
 
-## 测试规范
+    const states: any[] = [];
+    userService.subscribe((state) => states.push({ ...state }));
 
-> 💡 这里仅列出基本规范，完整的测试指南请参考 [测试开发指南](./testing.md)
+    await userService.fetchUsers({ page: 1, pageSize: 10 });
 
-### 1. 基本规范
+    // 验证状态变化
+    expect(states).toHaveLength(2);
+    expect(states[0].loading).toBe(true);
+    expect(states[1].loading).toBe(false);
+    expect(states[1].users).toEqual(mockResponse.list);
+    expect(states[1].total).toBe(1);
+  });
 
-- 单元测试覆盖核心逻辑
-- 组件测试关注交互和渲染
-- 使用 Jest 和 Testing Library
-- 保持测试简单和可维护
+  it('should handle error when fetch fails', async () => {
+    mockApi.getUserList.mockRejectedValue(new Error('Network error'));
 
-### 2. 示例
+    await userService.fetchUsers({ page: 1, pageSize: 10 });
+
+    expect(userService.getState().error).toBeTruthy();
+    expect(userService.getState().loading).toBe(false);
+  });
+});
+```
 
 ```typescript
-describe('UserProfile', () => {
-  it('should render user info', () => {
-    const user = { id: '1', name: 'Test' };
-    render(<UserProfile user={user} />);
-    expect(screen.getByText(user.name)).toBeInTheDocument();
+// __tests__/src/pages/users/UserListPage.test.tsx
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import UserListPage from '@/pages/users/UserListPage';
+import { IOCProvider } from '@/uikit/contexts/IOCContext';
+
+describe('UserListPage', () => {
+  it('should display user list', async () => {
+    const mockUsers = [
+      {
+        id: '1',
+        name: 'John',
+        email: 'john@example.com',
+        avatar: '',
+        role: 'user'
+      }
+    ];
+
+    const mockUserService = {
+      fetchUsers: vi.fn(),
+      searchUsers: vi.fn(),
+      refreshUsers: vi.fn(),
+      subscribe: vi.fn(),
+      getState: () => ({ users: mockUsers, loading: false, total: 1 }),
+      selector: {
+        users: (state: any) => state.users,
+        loading: (state: any) => state.loading,
+        total: (state: any) => state.total
+      }
+    };
+
+    const mockIOC = (identifier: string) => {
+      if (identifier === 'UserServiceInterface') return mockUserService;
+      if (identifier === 'RouteServiceInterface') return { push: vi.fn() };
+    };
+
+    render(
+      <IOCProvider value={mockIOC}>
+        <UserListPage />
+      </IOCProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('John')).toBeInTheDocument();
+      expect(screen.getByText('john@example.com')).toBeInTheDocument();
+    });
+  });
+
+  it('should search users when search button clicked', async () => {
+    const mockUserService = {
+      fetchUsers: vi.fn(),
+      searchUsers: vi.fn(),
+      subscribe: vi.fn(),
+      getState: () => ({ users: [], loading: false }),
+      selector: {
+        users: () => [],
+        loading: () => false,
+        total: () => 0
+      }
+    };
+
+    const mockIOC = (identifier: string) => {
+      if (identifier === 'UserServiceInterface') return mockUserService;
+      if (identifier === 'RouteServiceInterface') return { push: vi.fn() };
+    };
+
+    render(
+      <IOCProvider value={mockIOC}>
+        <UserListPage />
+      </IOCProvider>
+    );
+
+    const searchInput = screen.getByPlaceholderText(/search/i);
+    fireEvent.change(searchInput, { target: { value: 'John' } });
+
+    const searchButton = screen.getByRole('button', { name: /search/i });
+    fireEvent.click(searchButton);
+
+    expect(mockUserService.searchUsers).toHaveBeenCalledWith('John');
   });
 });
 ```
 
-更多测试示例和最佳实践，请参考 [测试开发指南](./testing.md)。
+---
 
-## 文档规范
+## 🎬 常见场景
 
-> 💡 这里仅列出基本规范，完整的文档编写指南请参考 [文档编写指南](./documentation.md)
+### 场景 1：添加一个新按钮功能
 
-### 1. 代码注释
+假设要在用户列表页添加"批量删除"功能：
 
 ```typescript
+// 1. 添加 i18n Key
 /**
- * 用户服务
- *
- * @description 处理用户相关的业务逻辑
- * @example
- * const userService = IOC(UserService);
- * await userService.login(credentials);
+ * @description Delete selected users
+ * @localZh 删除选中用户
+ * @localEn Delete Selected
  */
+export const PAGE_USERS_DELETE_SELECTED = 'page.users.deleteSelected';
+
+// 2. 在服务中添加方法
 @injectable()
-export class UserService {
-  /**
-   * 用户登录
-   *
-   * @param credentials - 登录凭证
-   * @returns 登录成功的用户信息
-   * @throws {AuthError} 认证失败时抛出
-   */
-  async login(credentials: Credentials): Promise<User> {
-    // 实现
+export class UserService extends UserServiceInterface {
+  async deleteUsers(userIds: string[]): Promise<void> {
+    try {
+      this.emit({ ...this.state, loading: true });
+      await this.api.deleteUsers(userIds);
+      await this.refreshUsers();  // 刷新列表
+    } catch (error) {
+      this.emit({ ...this.state, loading: false, error: error as Error });
+    }
   }
 }
+
+// 3. 在页面中使用
+function UserListPage() {
+  const [selectedRowKeys, setSelectedRowKeys] = useState<string[]>([]);
+
+  const handleDelete = async () => {
+    await userService.deleteUsers(selectedRowKeys);
+    setSelectedRowKeys([]);
+  };
+
+  return (
+    <div>
+      <Button
+        danger
+        onClick={handleDelete}
+        disabled={selectedRowKeys.length === 0}
+      >
+        {t(i18nKeys.PAGE_USERS_DELETE_SELECTED)}
+      </Button>
+
+      <Table
+        rowSelection={{
+          selectedRowKeys,
+          onChange: setSelectedRowKeys
+        }}
+        // ...
+      />
+    </div>
+  );
+}
 ```
 
-### 2. 文档结构
+### 场景 2：添加一个弹窗表单
 
-- **README.md**：项目概述、安装说明、快速开始
-- **docs/**：
-  - `zh/`：中文文档
-  - `en/`：英文文档
-  - 按功能模块组织文档文件
+假设要添加"编辑用户"弹窗：
 
-### 3. 文档格式
+```typescript
+// 1. 创建弹窗组件
+// components/UserEditModal.tsx
+interface UserEditModalProps {
+  user: UserInfo | null;
+  visible: boolean;
+  onClose: () => void;
+  onSubmit: (user: UserInfo) => void;
+}
 
-```markdown
-# 模块名称
+export function UserEditModal({ user, visible, onClose, onSubmit }: UserEditModalProps) {
+  const [form] = Form.useForm();
+  const { t } = useAppTranslation();
 
-## 概述
+  useEffect(() => {
+    if (user) {
+      form.setFieldsValue(user);
+    }
+  }, [user]);
 
-简要说明模块的功能和用途。
+  const handleSubmit = async () => {
+    const values = await form.validateFields();
+    onSubmit(values);
+  };
 
-## 使用方式
+  return (
+    <Modal
+      title={t(i18nKeys.PAGE_USERS_EDIT_TITLE)}
+      open={visible}
+      onCancel={onClose}
+      onOk={handleSubmit}
+    >
+      <Form form={form} layout="vertical">
+        <Form.Item
+          name="name"
+          label={t(i18nKeys.PAGE_USERS_FORM_NAME)}
+          rules={[{ required: true }]}
+        >
+          <Input />
+        </Form.Item>
+        <Form.Item
+          name="email"
+          label={t(i18nKeys.PAGE_USERS_FORM_EMAIL)}
+          rules={[{ required: true, type: 'email' }]}
+        >
+          <Input />
+        </Form.Item>
+      </Form>
+    </Modal>
+  );
+}
 
-代码示例和使用说明。
+// 2. 在服务中添加更新方法
+@injectable()
+export class UserService extends UserServiceInterface {
+  async updateUser(userId: string, data: Partial<UserInfo>): Promise<void> {
+    this.emit({ ...this.state, loading: true });
+    await this.api.updateUser(userId, data);
+    await this.refreshUsers();
+  }
+}
 
-## API 文档
+// 3. 在页面中使用
+function UserListPage() {
+  const [editUser, setEditUser] = useState<UserInfo | null>(null);
+  const [modalVisible, setModalVisible] = useState(false);
 
-详细的 API 说明。
+  const handleEdit = (user: UserInfo) => {
+    setEditUser(user);
+    setModalVisible(true);
+  };
 
-## 最佳实践
+  const handleSubmit = async (values: UserInfo) => {
+    await userService.updateUser(editUser!.id, values);
+    setModalVisible(false);
+    setEditUser(null);
+  };
 
-使用建议和注意事项。
+  return (
+    <div>
+      <Table
+        columns={[
+          // ...
+          {
+            title: 'Actions',
+            render: (_, record) => (
+              <Button onClick={() => handleEdit(record)}>Edit</Button>
+            )
+          }
+        ]}
+        // ...
+      />
+
+      <UserEditModal
+        user={editUser}
+        visible={modalVisible}
+        onClose={() => setModalVisible(false)}
+        onSubmit={handleSubmit}
+      />
+    </div>
+  );
+}
 ```
 
-## Git 提交规范
+### 场景 3：添加实时搜索
 
-> 💡 这里仅列出基本规范，完整的 Git 工作流程请参考 [Git 工作流指南](./git-workflow.md)
+假设要实现"输入时自动搜索"：
 
-### 1. 提交消息格式
+```typescript
+function UserListPage() {
+  const [keyword, setKeyword] = useState('');
 
-```
-<type>(<scope>): <subject>
+  // 使用 debounce 优化搜索
+  const debouncedKeyword = useDebounce(keyword, 500);
 
-<body>
+  useEffect(() => {
+    if (debouncedKeyword !== undefined) {
+      userService.searchUsers(debouncedKeyword);
+    }
+  }, [debouncedKeyword]);
 
-<footer>
-```
+  return (
+    <Input
+      placeholder={t(i18nKeys.PAGE_USERS_SEARCH_PLACEHOLDER)}
+      value={keyword}
+      onChange={(e) => setKeyword(e.target.value)}
+    />
+  );
+}
 
-- **type**：
-  - `feat`：新功能
-  - `fix`：修复
-  - `docs`：文档更新
-  - `style`：代码格式（不影响代码运行的变动）
-  - `refactor`：重构
-  - `test`：增加测试
-  - `chore`：构建过程或辅助工具的变动
+// 自定义 Hook
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
 
-- **scope**：影响范围（可选）
-- **subject**：简短描述
-- **body**：详细描述（可选）
-- **footer**：不兼容变动、关闭 issue（可选）
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
 
-### 2. 示例
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
 
+  return debouncedValue;
+}
 ```
-feat(auth): 添加用户角色管理功能
 
-- 添加角色创建和编辑界面
-- 实现角色权限配置
-- 添加角色分配功能
+---
 
-Closes #123
-```
+## 📐 代码规范
 
-## 性能优化规范
+### 1. 命名规范
 
-> 💡 这里仅列出基本规范，完整的性能优化指南请参考 [性能优化指南](./performance.md)
+```typescript
+// ✅ 好的命名
+const userService = useIOC('UserServiceInterface'); // 服务：小驼峰
+const UserListPage = () => {
+  /* ... */
+}; // 组件：大驼峰
+const PAGE_USERS_TITLE = 'page.users.title'; // 常量：大写下划线
+interface UserInfo {
+  /* ... */
+} // 接口：大驼峰
+type UserRole = 'admin' | 'user'; // 类型：大驼峰
+
+// ❌ 不好的命名
+const UserService = useIOC('UserServiceInterface'); // 应该是小驼峰
+const userListPage = () => {
+  /* ... */
+}; // 组件应该大驼峰
+const pageUsersTitle = 'page.users.title'; // 常量应该大写
+interface userInfo {
+  /* ... */
+} // 接口应该大驼峰
+```
 
-### 1. 代码分割
+### 2. 文件组织
 
 ```typescript
-// 路由级别的代码分割
-const UserModule = lazy(() => import('./pages/users'));
+// ✅ 好的文件组织
+import { FC, useEffect, useState } from 'react'; // React
+import { Button, Table, Input } from 'antd'; // 第三方 UI
+import { useIOC } from '@/uikit/hooks/useIOC'; // 项目内部
+import { useAppTranslation } from '@/uikit/hooks/useAppTranslation';
+import * as i18nKeys from '@config/Identifier/pages/page.users';
+import './UserListPage.css'; // 样式
+
+// 类型定义
+interface Props {
+  /* ... */
+}
 
-// 组件级别的代码分割
-const HeavyComponent = lazy(() => import('./components/Heavy'));
+// 组件
+export default function UserListPage() {
+  /* ... */
+}
+
+// ❌ 不好的文件组织
+import './UserListPage.css'; // 样式不应该在最前
+import * as i18nKeys from '@config/Identifier/pages/page.users';
+import { Button } from 'antd';
+import { useIOC } from '@/uikit/hooks/useIOC';
+import { FC } from 'react';
 ```
 
-### 2. 性能考虑
+### 3. 组件结构
 
 ```typescript
-// 使用 useMemo 缓存计算结果
-const sortedUsers = useMemo(() => {
-  return users.sort((a, b) => a.name.localeCompare(b.name));
-}, [users]);
-
-// 使用 useCallback 缓存函数
-const handleUpdate = useCallback(() => {
-  // 实现
-}, [dependencies]);
-
-// 使用 React.memo 避免不必要的重渲染
-const UserCard = React.memo(({ user }) => {
-  return <div>{user.name}</div>;
-});
-```
-
-## 安全规范
+// ✅ 好的组件结构
+export default function UserListPage() {
+  // 1. Hooks
+  const userService = useIOC('UserServiceInterface');
+  const { t } = useAppTranslation();
 
-> 💡 这里仅列出基本规范，完整的安全开发指南请参考 [安全开发指南](./security.md)
+  // 2. 状态
+  const users = useStore(userService, userService.selector.users);
+  const [keyword, setKeyword] = useState('');
 
-### 1. 数据处理
+  // 3. 副作用
+  useEffect(() => {
+    userService.fetchUsers({ page: 1, pageSize: 10 });
+  }, []);
 
-```typescript
-// 敏感数据加密
-const encryptedData = encrypt(sensitiveData);
+  // 4. 事件处理
+  const handleSearch = () => {
+    userService.searchUsers(keyword);
+  };
 
-// XSS 防护
-const sanitizedHtml = sanitizeHtml(userInput);
+  // 5. 渲染函数
+  const renderActions = (record: UserInfo) => {
+    return <Button onClick={() => handleEdit(record)}>Edit</Button>;
+  };
 
-// CSRF 防护
-api.defaults.headers['X-CSRF-Token'] = getCsrfToken();
+  // 6. 返回 JSX
+  return (
+    <div>
+      {/* ... */}
+    </div>
+  );
+}
 ```
 
-### 2. 权限控制
+### 4. 注释规范
 
 ```typescript
-// 路由权限
-const PrivateRoute: FC = ({ children }) => {
-  const auth = useAuth();
-  return auth.isAuthenticated ? children : <Navigate to="/login" />;
-};
+/**
+ * 用户列表页面
+ *
+ * @description 显示用户列表，支持搜索、分页、查看详情等功能
+ */
+export default function UserListPage() {
+  /**
+   * 处理搜索
+   * 根据关键词搜索用户
+   */
+  const handleSearch = () => {
+    userService.searchUsers(keyword);
+  };
 
-// 操作权限
-function AdminPanel() {
-  const { hasPermission } = useAuth();
+  // 初始化加载用户列表
+  useEffect(() => {
+    userService.fetchUsers({ page: 1, pageSize: 10 });
+  }, []);
 
   return (
     <div>
-      {hasPermission('ADMIN') && (
-        <button>管理员操作</button>
-      )}
+      {/* 搜索栏 */}
+      <Input.Search onSearch={handleSearch} />
+
+      {/* 用户表格 */}
+      <Table dataSource={users} />
     </div>
   );
 }
 ```
+
+---
+
+## 🛠️ 开发工具
+
+### 推荐的 VSCode 插件
+
+```
+✅ ESLint - 代码检查
+✅ Prettier - 代码格式化
+✅ TypeScript Vue Plugin (Volar) - Vue/React 支持
+✅ Tailwind CSS IntelliSense - Tailwind 智能提示
+✅ i18n Ally - i18n 管理
+✅ GitLens - Git 增强
+✅ Error Lens - 错误提示
+✅ Auto Rename Tag - 标签自动重命名
+```
+
+### 快捷命令
+
+```bash
+# 开发
+npm run dev              # 启动开发服务器
+npm run dev:staging      # 启动测试环境
+
+# 构建
+npm run build            # 生产构建
+npm run preview          # 预览构建结果
+
+# 代码检查
+npm run lint             # ESLint 检查
+npm run lint:fix         # ESLint 自动修复
+npm run type-check       # TypeScript 类型检查
+
+# 测试
+npm run test             # 运行测试
+npm run test:watch       # 监听模式测试
+npm run test:coverage    # 测试覆盖率
+
+# i18n
+npm run i18n:generate    # 生成翻译文件
+```
+
+### 调试技巧
+
+```typescript
+// 1. 使用 logger
+import { logger } from '@/core/globals';
+
+logger.debug('User data:', user);
+logger.error('Failed to fetch users:', error);
+
+// 2. 使用 React DevTools
+// 安装 React Developer Tools 浏览器插件
+
+// 3. 使用 Redux DevTools（如果需要）
+// 查看 Store 状态变化
+
+// 4. 使用 VSCode 断点调试
+// 在代码行左侧点击设置断点，然后 F5 启动调试
+```
+
+---
+
+## 🎯 开发 Checklist
+
+### 功能开发
+
+- [ ] 定义 i18n Key
+- [ ] 定义接口和类型
+- [ ] 实现 API 适配器（如果需要）
+- [ ] 实现服务
+- [ ] 配置路由
+- [ ] 实现页面组件
+- [ ] 注册到 IOC（如果是新服务）
+- [ ] 功能自测
+
+### 代码质量
+
+- [ ] 通过 ESLint 检查
+- [ ] 通过 TypeScript 类型检查
+- [ ] 代码格式化（Prettier）
+- [ ] 移除 console.log 和调试代码
+- [ ] 移除未使用的导入
+
+### 测试
+
+- [ ] 编写服务测试
+- [ ] 编写 UI 测试
+- [ ] 测试覆盖率 > 80%
+- [ ] 所有测试通过
+
+### 文档
+
+- [ ] 更新相关文档
+- [ ] 添加必要的代码注释
+- [ ] 更新 API 文档（如果有）
+
+### 提交
+
+- [ ] Git commit 符合规范
+- [ ] 代码已 review
+- [ ] 合并到主分支
+
+---
+
+## 📚 相关文档
+
+- **[项目架构设计](./index.md)** - 了解整体架构
+- **[IOC 容器](./ioc.md)** - 依赖注入和 UI 分离
+- **[Store 状态管理](./store.md)** - 应用层如何通知 UI 层
+- **[Bootstrap 启动器](./bootstrap.md)** - 应用启动和初始化
+- **[环境变量管理](./env.md)** - 多环境配置
+- **[国际化](./i18n.md)** - i18n Key 和翻译管理
+
+---
+
+**问题反馈：**  
+如果你在开发过程中遇到任何问题，请在团队频道中讨论或提交 Issue。