@qlover/create-app 1.1.0 → 2.0.2

package/dist/templates/react-app/docs/zh/components/chat-message-component.md

@@ -1,320 +0,0 @@
-# ChatMessage 聊天组件系统
-
-## 📋 概述
-
-ChatMessage 是一个完整的聊天组件系统，支持实时对话、流式输出、错误处理等功能。适合用于 AI 对话、客服聊天等场景。
-
-## ✨ 核心功能
-
-- ✅ **流式输出**：支持逐字显示 AI 回复（类似 ChatGPT）
-- ✅ **停止控制**：可随时停止正在生成的消息
-- ✅ **重试机制**：失败消息可一键重试
-- ✅ **草稿管理**：自动保存输入中的草稿消息
-- ✅ **加载状态**：清晰的消息发送和接收状态
-- ✅ **错误处理**：完善的错误提示和处理
-- ✅ **快捷键**：Ctrl+Enter 快速发送
-- ✅ **国际化**：完整的中英文支持
-- ✅ **响应式设计**：适配不同屏幕尺寸
-
-## 📁 文件结构
-
-```
-src/uikit/components/chatMessage/
-├── ChatRoot.tsx              # 根组件（组装所有部分）
-├── MessagesList.tsx          # 消息列表组件
-├── MessageItem.tsx           # 单个消息项组件
-├── FocusBar.tsx             # 输入栏组件
-├── ChatMessageBridge.ts     # 桥接层（连接UI和逻辑）
-└── MessageApi.ts            # API层（模拟/真实后端）
-
-config/
-├── Identifier/components/component.chatMessage.ts  # i18n 标识符
-├── i18n/chatMessageI18n.ts                        # 组件 i18n 配置
-├── Identifier/pages/page.chat.ts                  # 页面 i18n 标识符
-└── i18n/chatI18n.ts                               # 页面 i18n 配置
-
-src/pages/base/
-└── ChatMessagePage.tsx       # 聊天页面
-```
-
-## 🎯 核心概念
-
-### 1. ChatMessageBridge（桥接层）
-
-连接 UI 和数据层的桥梁，处理：
-
-- 消息发送逻辑
-- 草稿管理
-- 状态控制
-- 停止机制
-
-### 2. MessageApi（网关层）
-
-模拟后端 API，支持三种模式：
-
-#### 流式模式 (stream: true)
-
-```typescript
-{
-  stream: true; // 逐字输出，可停止
-}
-```
-
-#### 可中断普通模式
-
-```typescript
-{
-  stream: false; // 一次性返回，可停止
-}
-```
-
-#### 快速普通模式
-
-```typescript
-// 不传 options，一次性返回，不可停止
-```
-
-### 3. ChatMessageStore（状态管理）
-
-管理所有消息状态：
-
-- `messages` - 历史消息列表
-- `draftMessages` - 草稿消息列表
-- `streaming` - 是否正在流式输出
-- `disabledSend` - 是否禁用发送
-
-## 🚀 使用方式
-
-### 基本使用
-
-```typescript
-import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
-
-export default function ChatMessagePage() {
-  return (
-    <div className="h-screen">
-      <ChatRoot />
-    </div>
-  );
-}
-```
-
-### 访问路径
-
-- `/en/chat` - 英文
-- `/zh/chat` - 中文
-
-## 🎨 界面设计
-
-### 消息样式
-
-**用户消息**：
-
-- 蓝色背景
-- 右对齐
-- 最大宽度 80%
-- 显示耗时
-- 带重试按钮
-
-**AI 消息**：
-
-- 浅色背景 + 边框
-- 左对齐
-- 最大宽度 85%
-- 支持流式显示
-- 显示加载状态
-
-### 输入栏
-
-- 自动调整高度（2-6 行）
-- Ctrl+Enter 发送
-- 禁用状态控制
-- 发送/停止按钮切换
-
-## 📝 关键API
-
-### ChatMessageBridge 方法
-
-```typescript
-interface ChatMessageBridgeInterface<T> {
-  // 发送消息
-  send(message?: ChatMessage<T>): Promise<ChatMessage<T>>;
-
-  // 停止发送
-  stop(messageId?: string): boolean;
-
-  // 停止所有
-  stopAll(): void;
-
-  // 更新内容
-  onChangeContent(content: T): void;
-
-  // 获取消息存储
-  getMessageStore(): ChatMessageStore<T>;
-
-  // 获取第一个草稿消息
-  getFirstDraftMessage(): ChatMessage<T> | null;
-
-  // 获取正在发送的消息
-  getSendingMessage(): ChatMessage<T> | null;
-
-  // 是否禁用发送
-  getDisabledSend(): boolean;
-}
-```
-
-### MessageApi 模式
-
-```typescript
-class MessageApi {
-  async sendMessage<M>(message: M, options?: GatewayOptions<M>): Promise<M>;
-}
-
-interface GatewayOptions<M> {
-  stream?: boolean; // 是否流式
-  signal?: AbortSignal; // 停止信号
-  onConnected?: () => void; // 连接成功
-  onChunk?: (msg: M) => void; // 流式块回调
-  onProgress?: (p: number) => void; // 进度回调
-  onComplete?: (msg: M) => void; // 完成回调
-  onAborted?: (msg: M) => void; // 停止回调
-  onError?: (err: any) => void; // 错误回调
-}
-```
-
-## 🔧 自定义配置
-
-### 1. 切换发送模式
-
-```typescript
-// 修改 ChatRoot.tsx
-const [bridge] = useState(() => {
-  return new ChatMessageBridge<string>(messagesStore, {
-    gateway: messageApi,
-    logger: logger,
-    senderName: 'ChatSender',
-    gatewayOptions: {
-      stream: true // 改为 false 使用普通模式
-    }
-  }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
-});
-```
-
-### 2. 自定义消息组件
-
-```typescript
-<MessagesList
-  bridge={bridge}
-  getMessageComponent={(props) => CustomMessageItem}
-/>
-```
-
-### 3. 连接真实 API
-
-修改 `MessageApi.ts`：
-
-```typescript
-async sendMessage<M>(message: M, options?: GatewayOptions<M>): Promise<M> {
-  // 替换为真实 API 调用
-  const response = await fetch('/api/chat', {
-    method: 'POST',
-    body: JSON.stringify(message),
-    signal: options?.signal
-  });
-
-  // 处理流式响应
-  if (options?.stream) {
-    const reader = response.body?.getReader();
-    // ... 处理流式数据
-  }
-
-  return response.json();
-}
-```
-
-## 💡 使用建议
-
-### 测试功能
-
-**正常消息**：
-
-```
-Hello
-你好
-测试消息
-```
-
-**触发错误**：
-
-```
-error
-Failed
-test error
-```
-
-**查看流式效果**：
-
-- 发送任意消息
-- 观察逐字输出效果
-- 点击停止按钮测试中断
-
-### 快捷键
-
-- `Ctrl + Enter` - 发送消息
-- 输入中自动保存草稿
-
-## 🎯 适用场景
-
-1. **AI 对话应用**：类似 ChatGPT 的对话界面
-2. **客服系统**：实时客服聊天
-3. **问答系统**：Q&A 交互
-4. **代码助手**：代码生成和解释
-5. **教学助手**：在线学习辅导
-
-## 🔄 消息流转
-
-```
-用户输入 → 草稿消息
-    ↓
-点击发送/Ctrl+Enter
-    ↓
-Bridge.send()
-    ↓
-MessageSender → MessageApi
-    ↓
-[流式模式]
-  onConnected → onChunk(逐字) → onComplete
-
-[普通模式]
-  onConnected → onComplete
-
-[错误]
-  onError
-
-[停止]
-  onAborted
-    ↓
-更新 ChatMessageStore
-    ↓
-UI 自动更新
-```
-
-## 📊 状态管理
-
-### 消息状态
-
-- `DRAFT` - 草稿
-- `SENDING` - 发送中
-- `SENT` - 已发送
-- `FAILED` - 失败
-- `STOPPED` - 已停止
-
-### 消息角色
-
-- `USER` - 用户消息
-- `ASSISTANT` - AI/助手消息
-- `SYSTEM` - 系统消息
-
-## 🎉 总结
-
-ChatMessage 是一个功能完整、设计优雅的聊天组件系统，开箱即用，支持流式输出、错误处理、状态管理等核心功能。可以直接用于生产环境，也可以根据需要进行扩展和定制。

package/dist/templates/react-app/docs/zh/components/chat-message-refactor.md

@@ -1,283 +0,0 @@
-# ChatMessage 重构说明
-
-## 重构内容
-
-将 ChatMessage 从独立页面重构为可复用组件，集成到 MessagePage 中，并通过 props 传递国际化对象 `tt`，确保组件的高度可复用性。
-
-## 改动说明
-
-### 1. ChatRoot 组件改造
-
-**文件：** `src/uikit/components/chatMessage/ChatRoot.tsx`
-
-**改动：**
-
-- 移除了内部的 `ChatMessageStore`、`MessageApi` 和 `ChatMessageBridge` 创建逻辑
-- 改为接收 `bridge` 和 `tt`（国际化对象）作为 props
-- 添加了 `ChatRootProps` 接口定义
-- 移除了内部的 `useI18nInterface` 调用
-
-**改造前：**
-
-```typescript
-export function ChatRoot() {
-  const messagesStore = useFactory(ChatMessageStore<string>);
-  const messageApi = useFactory(MessageApi, messagesStore);
-  const [bridge] = useState(() => {
-    return new ChatMessageBridge<string>(messagesStore, {
-      gateway: messageApi,
-      logger: logger,
-      senderName: 'ChatSender',
-      gatewayOptions: { stream: true }
-    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
-  });
-
-  return (
-    <div data-testid="ChatRoot">
-      <MessagesList bridge={bridge} />
-      <FocusBar bridge={bridge} />
-    </div>
-  );
-}
-```
-
-**改造后：**
-
-```typescript
-export interface ChatRootProps {
-  bridge: ChatMessageBridge<string>;
-  tt: ChatMessageI18nInterface;
-}
-
-export function ChatRoot({ bridge, tt }: ChatRootProps) {
-  return (
-    <div data-testid="ChatRoot">
-      <MessagesList bridge={bridge} tt={tt} />
-      <FocusBar bridge={bridge} tt={tt} />
-    </div>
-  );
-}
-```
-
-### 2. MessagePage 集成 ChatRoot
-
-**文件：** `src/pages/base/MessagePage.tsx`
-
-**改动：**
-
-- 在 MessagePage 中使用 `useI18nInterface` 获取国际化对象 `tt`
-- 在 MessagePage 中创建 `ChatMessageStore`、`MessageApi` 和 `ChatMessageBridge`
-- 将 `bridge` 和 `tt` 通过 props 传递给 `ChatRoot` 组件
-- 同时集成了 `MessageBaseList` 组件
-
-**实现：**
-
-```typescript
-import { useFactory } from '@brain-toolkit/react-kit';
-import { chatMessageI18n } from '@config/i18n/chatMessageI18n';
-import {
-  ChatMessageStore,
-  ChatSenderStrategy,
-  SendFailureStrategy
-} from '@qlover/corekit-bridge';
-import { useState } from 'react';
-import { logger } from '@/core/globals';
-import { ChatMessageBridge } from '@/uikit/components/chatMessage/ChatMessageBridge';
-import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
-import { MessageApi } from '@/uikit/components/chatMessage/MessageApi';
-import { MessageBaseList } from '@/uikit/components/MessageBaseList';
-import { useI18nInterface } from '@/uikit/hooks/useI18nInterface';
-
-export default function MessagePage() {
-  const tt = useI18nInterface(chatMessageI18n);
-  const messagesStore = useFactory(ChatMessageStore<string>);
-  const messageApi = useFactory(MessageApi, messagesStore);
-
-  const [bridge] = useState(() => {
-    return new ChatMessageBridge<string>(messagesStore, {
-      gateway: messageApi,
-      logger: logger,
-      senderName: 'ChatSender',
-      gatewayOptions: { stream: true }
-    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
-  });
-
-  return (
-    <div
-      data-testid="MessagePage"
-      className="min-h-screen bg-primary py-8 px-4 sm:px-6 lg:px-8"
-    >
-      <MessageBaseList />
-      <ChatRoot bridge={bridge} tt={tt} />
-    </div>
-  );
-}
-```
-
-### 3. 子组件改造（MessagesList、FocusBar、MessageItem）
-
-**改动：**
-
-- 移除了所有子组件内部的 `useI18nInterface` 调用
-- 改为通过 props 接收 `tt` 参数
-- 更新了各组件的 Props 接口定义
-
-**示例 - MessagesList：**
-
-```typescript
-// 改造前
-export function MessagesList({ bridge, ... }: MessagesListProps) {
-  const tt = useI18nInterface(chatMessageI18n);
-  // ...
-}
-
-// 改造后
-export interface MessagesListProps {
-  bridge: ChatMessageBridgeInterface<T>;
-  tt: ChatMessageI18nInterface;
-  // ...
-}
-
-export function MessagesList({ bridge, tt, ... }: MessagesListProps) {
-  // 直接使用传入的 tt
-}
-```
-
-### 4. 删除独立的 ChatMessagePage
-
-**删除的文件：**
-
-- `src/pages/base/ChatMessagePage.tsx`
-- `config/Identifier/pages/page.chat.ts`
-- `config/i18n/chatI18n.ts`
-
-**更新的文件：**
-
-- `config/app.router.ts` - 移除了 `/chat` 路由配置
-- `config/Identifier/pages/index.ts` - 移除了 `page.chat` 导出
-
-## 重构优势
-
-### 1. 提高组件复用性
-
-- `ChatRoot` 现在是一个纯展示组件，可以在任何地方使用
-- `bridge` 和 `tt` 的创建和配置由父组件控制，更加灵活
-- 父组件可以自定义国际化内容，支持不同语言环境
-
-### 2. 简化路由结构
-
-- 减少了不必要的路由层级
-- 将聊天功能直接集成到消息页面中，符合业务逻辑
-
-### 3. 更好的关注点分离
-
-- `ChatRoot` 及其子组件只关注 UI 展示
-- 业务逻辑（store、api、bridge）在页面层管理
-- 国际化配置在页面层统一管理
-- 更容易测试和维护
-
-### 4. 减少样板代码
-
-- 不需要为聊天功能创建单独的页面
-- 不需要为页面创建单独的 i18n 配置
-- 子组件不需要重复调用 `useI18nInterface`
-
-### 5. 提升性能
-
-- 减少了 hook 调用次数（多个子组件共享同一个 `tt` 对象）
-- 避免了重复的国际化配置解析
-
-## 使用示例
-
-### 基本用法
-
-如果需要在其他地方使用 `ChatRoot`：
-
-```typescript
-import { useFactory } from '@brain-toolkit/react-kit';
-import { chatMessageI18n } from '@config/i18n/chatMessageI18n';
-import {
-  ChatMessageStore,
-  ChatSenderStrategy,
-  SendFailureStrategy
-} from '@qlover/corekit-bridge';
-import { useState } from 'react';
-import { logger } from '@/core/globals';
-import { useI18nInterface } from '@/uikit/hooks/useI18nInterface';
-import { ChatMessageBridge } from '@/uikit/components/chatMessage/ChatMessageBridge';
-import { ChatRoot } from '@/uikit/components/chatMessage/ChatRoot';
-import { MessageApi } from '@/uikit/components/chatMessage/MessageApi';
-
-function MyCustomChatPage() {
-  // 获取国际化对象
-  const tt = useI18nInterface(chatMessageI18n);
-
-  const messagesStore = useFactory(ChatMessageStore<string>);
-  const messageApi = useFactory(MessageApi, messagesStore);
-
-  const [bridge] = useState(() => {
-    return new ChatMessageBridge<string>(messagesStore, {
-      gateway: messageApi,
-      logger: logger,
-      senderName: 'MyCustomSender',
-      gatewayOptions: {
-        stream: true,
-        // 可以自定义其他选项
-      }
-    }).use(new ChatSenderStrategy(SendFailureStrategy.KEEP_FAILED, logger));
-  });
-
-  return (
-    <div>
-      <h1>My Custom Chat</h1>
-      <ChatRoot bridge={bridge} tt={tt} />
-    </div>
-  );
-}
-```
-
-### 自定义国际化
-
-如果需要使用自定义的国际化配置：
-
-```typescript
-import { useState } from 'react';
-import type { ChatMessageI18nInterface } from '@config/i18n/chatMessageI18n';
-
-// 自定义的国际化对象
-const customI18n: ChatMessageI18nInterface = {
-  title: 'custom.chat.title',
-  empty: 'custom.chat.empty',
-  start: 'custom.chat.start',
-  // ... 其他配置
-};
-
-function MyCustomChatPage() {
-  const tt = useI18nInterface(customI18n);
-  // ... 其他逻辑
-
-  return <ChatRoot bridge={bridge} tt={tt} />;
-}
-```
-
-## 注意事项
-
-1. `ChatRoot` 组件需要通过 props 接收两个必需参数：
-   - `bridge`: `ChatMessageBridge` 实例
-   - `tt`: `ChatMessageI18nInterface` 国际化对象
-
-2. `bridge` 的创建和配置应该在父组件中完成
-
-3. 确保 `bridge` 使用 `useState` 创建，避免重复初始化
-
-4. 国际化对象 `tt` 应该在父组件使用 `useI18nInterface` 获取，然后传递给 `ChatRoot`
-
-5. `ChatRoot` 依赖的所有子组件（`MessagesList`、`FocusBar`、`MessageItem`）都通过 props 接收 `bridge` 和 `tt`
-
-6. 所有子组件都不再自己调用 `useI18nInterface`，而是使用父组件传递的 `tt`
-
-## 相关文档
-
-- [ChatMessage 组件文档](./chat-message-component.md)
-- [MessagePage 简化说明](./message-page-简化说明.md)
-- [开发指南](./development-guide.md)