@qlover/create-app 0.8.0 → 0.10.0

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

@@ -0,0 +1,270 @@
+# 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)
+

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

@@ -0,0 +1,172 @@
+# MessageBaseList 组件文档
+
+## 📋 组件概述
+
+`MessageBaseList` 是一个简单的单向消息组件，用于测试消息网关（Gateway）功能。用户发送消息后，等待网关响应并显示结果。
+
+## ✨ 功能特性
+
+- ✅ 发送消息到网关
+- ✅ 实时显示消息状态（发送中、成功、失败）
+- ✅ 美观的聊天界面样式
+- ✅ 完整的国际化支持（中英文）
+- ✅ 错误处理和重试机制
+- ✅ 响应式设计
+
+## 🎨 界面特点
+
+### 消息显示
+
+- **用户消息**：蓝色气泡，右对齐
+- **网关响应**：
+  - **处理中**：灰色背景，带动画加载点
+  - **成功**：绿色背景，显示响应结果
+  - **失败**：红色背景，显示错误信息
+
+### 空状态
+
+当没有消息时，显示友好的提示文本，引导用户发送第一条消息。
+
+## 🔧 使用方式
+
+### 在页面中使用
+
+```tsx
+import { MessageBaseList } from '@/uikit/components/MessageBaseList';
+
+export default function MessagePage() {
+  return (
+    <div className="min-h-screen bg-primary py-8 px-4 sm:px-6 lg:px-8">
+      <MessageBaseList />
+    </div>
+  );
+}
+```
+
+## 🌐 国际化配置
+
+### 文件结构
+
+- **标识符定义**：`config/Identifier/components/component.messageBaseList.ts`
+- **i18n 配置**：`config/i18n/messageBaseListI18n.ts`
+
+### 支持的文本
+
+| 文本项 | 中文 | 英文 |
+|--------|------|------|
+| 标题 | 消息网关测试 | Message Gateway Test |
+| 描述 | 发送消息并等待网关响应 | Send messages and wait for gateway response |
+| 空状态 | 暂无消息 | No messages yet |
+| 用户标签 | 你 | You |
+| 网关标签 | 网关 | Gateway |
+| 处理中 | 处理中... | Processing... |
+| 失败标签 | 网关（失败） | Gateway (Failed) |
+| 网关响应 | 网关响应 | Gateway Response |
+| 发送按钮 | 发送 | Send |
+
+## 🧪 测试功能
+
+### 模拟网关行为
+
+组件内置了 `MessageBaseApi` 类，模拟真实的网关行为：
+
+- **正常响应**：200-1000ms 延迟，返回确认消息
+- **触发错误**：
+  - 发送包含 "error" 或 "Failed" 的消息
+  - 随机网络错误（延迟能被 5 整除时）
+
+### 测试建议
+
+```
+# 正常消息
+Hello World
+
+# 触发错误
+error
+Failed
+test error message
+```
+
+## 📦 依赖的核心功能
+
+### @qlover/corekit-bridge
+
+- `MessagesStore` - 消息状态管理
+- `MessageSender` - 消息发送器
+- `SenderStrategyPlugin` - 发送策略插件
+- `SendFailureStrategy.KEEP_FAILED` - 保留失败消息的策略
+
+### 功能特点
+
+1. **自动状态管理**：消息的加载、成功、失败状态自动更新
+2. **失败保留**：失败的消息会保留在列表中，方便查看错误
+3. **防重复发送**：发送中时禁用输入和按钮
+
+## 🎯 样式系统
+
+### Tailwind CSS 类
+
+组件使用了项目的主题系统：
+
+- `bg-primary` - 主背景色
+- `bg-secondary` - 次级背景色
+- `bg-base` - 基础背景色
+- `text-text` - 主文本色
+- `text-text-secondary` - 次级文本色
+- `border-primary` - 主边框色
+
+### 响应式设计
+
+- 消息最大宽度：70%（适应不同屏幕）
+- 消息列表最大高度：96（约 384px）
+- 消息列表最小高度：64（约 256px）
+- 自动滚动：overflow-y-auto
+
+## 💡 使用场景
+
+1. **开发调试**：测试消息网关功能
+2. **演示展示**：展示消息发送和响应流程
+3. **集成测试**：验证消息系统集成是否正常
+4. **用户培训**：教学和培训用途
+
+## 🔄 状态流转
+
+```
+用户输入消息
+    ↓
+点击发送 / 回车
+    ↓
+messagesSender.send()
+    ↓
+消息状态: loading = true
+    ↓
+调用 MessageBaseApi.sendMessage()
+    ↓
+[成功] → status: SENT, result: 响应内容
+[失败] → status: FAILED, error: 错误信息
+    ↓
+UI 自动更新显示
+```
+
+## 📝 注意事项
+
+1. **清空输入**：发送成功后自动清空输入框
+2. **禁用控制**：发送中时禁用输入和发送按钮
+3. **错误处理**：使用 `(message as any).error` 访问错误信息（类型安全）
+4. **样式兼容**：使用 `wrap-break-word` 替代 `break-words`
+
+## 🚀 未来扩展
+
+可能的功能扩展方向：
+
+- [ ] 支持图片、文件发送
+- [ ] 支持消息编辑和删除
+- [ ] 支持消息搜索
+- [ ] 支持消息导出
+- [ ] 支持自定义网关 API
+- [ ] 支持 WebSocket 实时通信
+
+## 🎉 总结
+
+`MessageBaseList` 是一个功能完整、样式美观的消息组件，完全支持国际化，适合用于测试和展示消息网关功能。
+

package/dist/templates/react-app/eslint.config.mjs

@@ -7,10 +7,7 @@ import unusedImports from 'eslint-plugin-unused-imports';
 import qloverEslint from '@qlover/eslint-plugin';
 import tseslint from 'typescript-eslint';
 import globals from 'globals';
-import {
-  disableGlobals,
-  restrictSpecificGlobals
-} from './makes/eslint-utils.mjs';
+import { restrictSpecificGlobals } from './makes/eslint-utils.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -186,10 +183,14 @@ const eslintConfig = [
       'prettier/prettier': [
         'error',
         {
-          semi: true,
           singleQuote: true,
           trailingComma: 'none',
           endOfLine: 'lf'
+        },
+        {
+          // 仅用于单独部署时对 eslint prettier 插件自动查找 prettierrc 时报错
+          // 注意: vscode 等编辑器会失效, 作为单独项目开发时可以去掉
+          usePrettierrc: false
         }
       ],
       // 默认禁用 export default

package/dist/templates/react-app/package.json

@@ -32,7 +32,7 @@
     "dev:force": "vite --mode localhost --force",
     "dev:staging": "vite --mode staging",
     "dev:prod": "vite --mode production",
-    "build": "npm run lint && vite build",
+    "build": "vite build",
     "build:staging": "npm run lint && vite build --mode staging",
     "build:prod": "npm run lint && vite build --mode production",
     "build:analyze": "vite build --mode production && start dist/stats.html",

package/dist/templates/react-app/playwright.config.ts

@@ -29,25 +29,25 @@ export default defineConfig({
     baseURL: 'http://localhost:3200',
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
-    trace: 'on-first-retry',
+    trace: 'on-first-retry'
   },
 
   /* Configure projects for major browsers */
   projects: [
     {
       name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
+      use: { ...devices['Desktop Chrome'] }
     },
 
     {
       name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
+      use: { ...devices['Desktop Firefox'] }
     },
 
     {
       name: 'webkit',
-      use: { ...devices['Desktop Safari'] },
-    },
+      use: { ...devices['Desktop Safari'] }
+    }
 
     /* Test against mobile viewports. */
     // {
@@ -68,7 +68,7 @@ export default defineConfig({
     //   name: 'Google Chrome',
     //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
     // },
-  ],
+  ]
 
   /* Run your local dev server before starting the tests */
   // webServer: {

package/dist/templates/react-app/public/locales/en/common.json

@@ -188,5 +188,48 @@
   "page_request:trigger_abort": "Trigger Abort Request",
   "page_request:stop_abort": "Stop Abort Request",
   "page_request:trigger_api_catch": "Trigger API Catch Result",
-  "page_request:stop_api_catch": "Stop API Catch Result"
+  "page_request:stop_api_catch": "Stop API Catch Result",
+  "page_message:title": "Message Test",
+  "page_message:description": "Message gateway test page",
+  "page_message:keywords": "Message, Gateway, Test",
+  "page_message:search_placeholder": "Search message content",
+  "page_message:mark_read": "Mark as Read",
+  "page_message:mark_unread": "Mark as Unread",
+  "page_message:delete": "Delete",
+  "page_message:delete_selected": "Delete Selected",
+  "page_message:refresh": "Refresh",
+  "page_message:loading": "Loading...",
+  "page_message:empty": "No messages found",
+  "page_message:column_title": "Title",
+  "page_message:column_content": "Content",
+  "page_message:column_status": "Status",
+  "page_message:column_time": "Time",
+  "page_message:column_actions": "Actions",
+  "page_message:status_read": "Read",
+  "page_message:status_unread": "Unread",
+  "page_message:delete_confirm_title": "Confirm Delete",
+  "page_message:delete_confirm_content": "Are you sure you want to delete the selected messages?",
+  "page_message:delete_success": "Deleted successfully",
+  "page_message:mark_success": "Marked successfully",
+  "component_message_base_list:title": "Message Gateway Test",
+  "component_message_base_list:description": "Send messages and wait for gateway response",
+  "component_message_base_list:no_messages": "No messages yet",
+  "component_message_base_list:get_started": "Send your first message to get started",
+  "component_message_base_list:user": "You",
+  "component_message_base_list:gateway": "Gateway",
+  "component_message_base_list:processing": "Processing...",
+  "component_message_base_list:gateway_failed": "Gateway (Failed)",
+  "component_message_base_list:send_failed": "Failed to send message",
+  "component_message_base_list:gateway_response": "Gateway Response",
+  "component_message_base_list:input_placeholder": "Type your message here...",
+  "component_message_base_list:send_button": "Send",
+  "component_message_base_list:error_tip": "Tip: Try sending \"error\" or \"Failed\" to test error handling",
+  "component_chat:send": "Send",
+  "component_chat:stop": "Stop",
+  "component_chat:loading": "Loading...",
+  "component_chat:input_placeholder": "Type a message... (Ctrl+Enter to send)",
+  "component_chat:empty": "No messages yet",
+  "component_chat:start": "Start a conversation",
+  "component_chat:retry": "Retry",
+  "component_chat:duration": "Duration"
 }

package/dist/templates/react-app/public/locales/zh/common.json

@@ -188,5 +188,48 @@
   "page_request:trigger_abort": "触发中止请求",
   "page_request:stop_abort": "停止中止请求",
   "page_request:trigger_api_catch": "触发 API 捕获结果",
-  "page_request:stop_api_catch": "停止 API 捕获结果"
+  "page_request:stop_api_catch": "停止 API 捕获结果",
+  "page_message:title": "消息测试",
+  "page_message:description": "消息网关测试页面",
+  "page_message:keywords": "消息, 网关, 测试",
+  "page_message:search_placeholder": "搜索消息内容",
+  "page_message:mark_read": "标记为已读",
+  "page_message:mark_unread": "标记为未读",
+  "page_message:delete": "删除",
+  "page_message:delete_selected": "删除选中",
+  "page_message:refresh": "刷新",
+  "page_message:loading": "加载中...",
+  "page_message:empty": "暂无消息",
+  "page_message:column_title": "标题",
+  "page_message:column_content": "内容",
+  "page_message:column_status": "状态",
+  "page_message:column_time": "时间",
+  "page_message:column_actions": "操作",
+  "page_message:status_read": "已读",
+  "page_message:status_unread": "未读",
+  "page_message:delete_confirm_title": "确认删除",
+  "page_message:delete_confirm_content": "确定要删除选中的消息吗？",
+  "page_message:delete_success": "删除成功",
+  "page_message:mark_success": "标记成功",
+  "component_message_base_list:title": "消息网关测试",
+  "component_message_base_list:description": "发送消息并等待网关响应",
+  "component_message_base_list:no_messages": "暂无消息",
+  "component_message_base_list:get_started": "发送第一条消息开始使用",
+  "component_message_base_list:user": "你",
+  "component_message_base_list:gateway": "网关",
+  "component_message_base_list:processing": "处理中...",
+  "component_message_base_list:gateway_failed": "网关（失败）",
+  "component_message_base_list:send_failed": "发送消息失败",
+  "component_message_base_list:gateway_response": "网关响应",
+  "component_message_base_list:input_placeholder": "在此输入您的消息...",
+  "component_message_base_list:send_button": "发送",
+  "component_message_base_list:error_tip": "提示：尝试发送 \"error\" 或 \"Failed\" 来测试错误处理",
+  "component_chat:send": "发送",
+  "component_chat:stop": "停止",
+  "component_chat:loading": "加载中...",
+  "component_chat:input_placeholder": "输入消息... (Ctrl+Enter 发送)",
+  "component_chat:empty": "暂无对话",
+  "component_chat:start": "开始对话",
+  "component_chat:retry": "重试",
+  "component_chat:duration": "耗时"
 }