cx-chat 0.0.1

package/src/_doc/table-view/props.1.create-table-view-config.md

@@ -0,0 +1,193 @@
+# 配置工厂：`createListPageConfig` / `createSelectTableConfig`
+
+> 适用范围：**整页列表**用 `ListPageView` + `createListPageConfig`；**弹层选人表**用 `SelectTableView` + `createSelectTableConfig`。  
+> 目标：页面通过配置声明行为，公共层统一处理增删查改、树、分页、搜索与提示（选人表侧默认不启用删除/导出/提交等整页能力）。
+
+## 1. 列表页（整页）
+
+```tsx
+import { ListPageView, createListPageConfig } from '@components/table-view'
+
+const useListPageConfig = createListPageConfig({
+  tableAPI: getListAPI,
+  deleteAPI: deleteItemAPI,
+  pageInfo: {
+    title: 'system.xxx.page_title',
+    subTitle: 'system.xxx.page_subtitle',
+  },
+  searchFields: [],
+  columns: [],
+})
+
+function IndexView() {
+  const pageConfig = useListPageConfig()
+  return <ListPageView pageConfig={pageConfig} />
+}
+```
+
+## 2. 弹层选人表
+
+```tsx
+import { SelectTable, createSelectTableConfig } from '@components/table-view'
+
+const useSelectTablePageConfig = createSelectTableConfig({
+  tableAPI: getUserPageAPI,
+  searchFields: [{ prop: 'keyword', label: '...', placeholder: '...' }],
+  columns: [],
+  pagination: { page: 1, pageSize: 10, total: 0 },
+  pageInfo: {},
+})
+
+function PickerPane() {
+  const pageConfig = useSelectTablePageConfig()
+  return <SelectTable pageConfig={pageConfig} selectionMode="multiple" />
+}
+```
+
+`createSelectTableConfig` 与列表工厂共用同一套请求/分页/搜索组装逻辑；默认合并上**只叠公共默认**（表、搜索、分页、树等），**不叠**列表专有默认（`deleteAPI`、`submitAction` 等），因此选人侧天然不含整页项（仍返回 `PageConfig` 形态供 `SelectTableView`；若业务确需在弹层显式传删除等，可通过 `customConfig` 覆盖，类型上仍以 `BaseTableViewFactoryConfig` 为准）。
+
+---
+
+## 3. 常用参数（两场景共用字段）
+
+### 3.1 API 相关
+
+- `tableAPI(params)`：列表查询接口（`params` 由公共层组装：**搜索条件** + **`page`（从 1 起）**、**`size`**、**`sort`**、**`order`**）
+- `deleteAPI(id)`：单条删除接口（**列表页**典型配置；选人表工厂默认不启用）
+- `batchDeleteAPI(ids)`：批量删除接口
+- `exportAPI(params)`：导出接口
+- `treeAPI()`：左侧树接口（菜单/部门等场景）
+
+### 3.2 页面与表格
+
+- `pageInfo`：标题区文案（`title`、`subTitle`、`listTitle`）
+- `columns`：表格列
+- `table`：表格行为配置（如是否显示选择列、分页、批量删除、导出）
+- `pagination`：初始分页（`page`、`pageSize`、`total`）
+  - **`page` 从 1 开始**（与 `tableAPI` 入参中的 `page` 一致；底部分页组件使用 1 基页码）
+- `pageSizeOptions`：底部分页「每页条数」下拉选项，**可选**；默认 `[10, 20, 50, 100, 200, 500, 1000]`，可按页面覆盖，例如 `pageSizeOptions: [20, 50, 100]`
+- `listQuery`：列表默认排序，**可选**；未配置时为 `sort: 'createTime'`、`order: 'desc'`；可写 `listQuery: { sort: 'name', order: 'asc' }` 覆盖其中一项或两项
+
+### 3.3 搜索区
+
+- `searchFields`：搜索项声明（详细见 `props.2.table-view-search-fields.md`）
+- `initialSearchFormData`：初始筛选值（如默认状态）
+
+### 3.4 提交与详情行为（主要面向列表页）
+
+- `submitAction`：新增/编辑入口行为
+  - `permission`
+  - `submitType: 'modal' | 'page'`
+  - `labelKey`
+- `detailAction`：详情入口行为
+  - `permission`
+  - `detailType: 'modal' | 'page'`
+  - `labelKey`
+
+### 3.5 树区域配置
+
+- `tree`：
+  - `title`
+  - `fieldNames`（`id` / `label` / `children`）
+  - `searchField`
+  - `autoSearch`
+  - `unselectText`
+  - `onSelect(node)`
+
+---
+
+## 4. 删除确认与扩展（列表页）
+
+### 4.1 `deleteConfirm`
+
+用于删除确认弹窗文案与插值参数：
+
+- `title`
+- `content`
+- `contentFields`：插值字段，支持 `string | string[]`，默认 `name`
+- `okText`
+- `cancelText`
+
+示例：
+
+```ts
+deleteConfirm: {
+  title: 'common.confirm',
+  content: 'p_system.menu.delete_confirm',
+  contentFields: ['title', 'code'],
+  okText: 'common.confirm',
+  cancelText: 'common.cancel',
+}
+```
+
+### 4.2 `afterDelete(record)`
+
+**单条删除**在 `ListPageView` 确认并调用 `deleteAPI` 成功后触发（与 `fetchTableData` 的调用顺序无关；工厂内删除成功后通常会 `fetchTableData()`，但**不 await**）。  
+适合「删完立刻要做、不必等表格重拉完」的扩展，例如只抬 `treeReloadSignal`、调与列表无关的接口。
+
+```ts
+afterDelete: async () => {
+  setTreeReloadSignal((n) => n + 1)
+  await refreshMenus()
+}
+```
+
+### 4.3 `afterStatusChange(record, nextStatus)`
+
+**单条启用/禁用**在 `updateStatusAPI` 成功后触发；与 `afterDelete` 相同，**不保证**列表 `fetchTableData` 已完成。
+
+### 4.4 `afterGetPageData()`
+
+**仅在 `fetchTableData` 成功**（已写入 `tableData`、更新 `paginationData.total`）**之后**调用，且钩子内异常会被捕获并 `console.warn`，不影响关 `loading`。
+
+典型用途：与列表数据强一致的全局缓存刷新。例如 **系统 → 数据字典** 在 `afterGetPageData` 里调用 `loadUnauthDictData()` + `loadCommonDictData(true)`（实现见 `src/meta/index-dict.ts`；说明见 [`../meta/comp.2.dict-runtime.md`](../meta/comp.2.dict-runtime.md)），避免在 `afterDelete`、各弹窗 `onOk` 等处重复书写。
+
+```ts
+import { loadCommonDictData, loadUnauthDictData } from '@/meta/index-dict'
+
+const useListPageConfig = createListPageConfig({
+  afterGetPageData: async () => {
+    loadUnauthDictData()
+    await loadCommonDictData(true)
+  },
+  tableAPI: getDictDataPageAPI,
+  // ...
+})
+```
+
+**与 `afterDelete` / `afterStatusChange` 的分工**：
+
+| 钩子 | 触发时机 | 是否等待列表拉取完成 |
+|------|-----------|----------------------|
+| `afterDelete` / `afterStatusChange` | 删/改状态 API 成功返回后 | 否（列表刷新异步发起） |
+| `afterGetPageData` | 每次 `fetchTableData` 成功落表后 | 是（在 `try` 末尾 `await`） |
+
+**注意**：`afterGetPageData` 会随**首屏、搜索、分页、删改后刷新**等所有成功拉表路径执行；若回调较重（如全量字典），可在业务侧节流或按条件短路。
+
+---
+
+## 5. 工厂返回的能力（hook → `pageConfig`）
+
+`useListPageConfig()` / `useSelectTablePageConfig()` 返回的 `pageConfig` 可直接给 `ListPageView` / `SelectTableView`。  
+常用字段/方法：
+
+- 状态：`loading`、`tableData`、`searchFormData`、`paginationData`
+- 配置回显：`listQuery`（合并默认后的排序）、`pageSizeOptions`（每页条数下拉选项）
+- 行为：`handleSearch`、`handleReset`、`handleTableChange`
+- 删除/批量/导出：`handleDelete`、`handleBatchDelete`、`handleExport`
+- 树联动：`patchSearchAndRefresh`、`replaceSearchAndRefresh`
+- 扩展回调（若配置）：`afterDelete`、`afterStatusChange`、`afterGetPageData`（回显在 `pageConfig` 上，便于调试）
+
+---
+
+## 6. 推荐实践
+
+- 整页列表用 `createListPageConfig`，hook 建议命名为 `useListPageConfig`
+- 弹层选人用 `createSelectTableConfig`，hook 建议命名为 `useSelectTablePageConfig`（或业务语义化如 `useSelectUserTablePageConfig`）
+- 页面尽量“只声明，不手写流程”，复用工厂统一行为
+- 页面特殊逻辑优先使用扩展点：**与「列表数据已更新」强绑定**时用 `afterGetPageData`；**仅跟删除/启停用动作绑定**、不必等表格时用 `afterDelete` / `afterStatusChange`
+- 搜索参数转换统一放在 `searchFields` 配置层，不在页面里做零散转换
+
+---
+
+*最后更新：2026-04-17*

package/src/_doc/table-view/props.2.table-view-search-fields.md

@@ -0,0 +1,106 @@
+# table-view：searchFields 使用说明
+
+> 适用范围：`ListPageView` / `SelectTableView` + `createListPageConfig` / `createSelectTableConfig`  
+> 目标：页面只做声明，公共层自动完成参数收集与转换
+
+## 1. 基础结构
+
+`searchFields` 是一个数组，每个对象代表一个筛选项。
+
+```ts
+searchFields: [
+  {
+    prop: 'searchQ',
+    label: 'common.search_placeholder',
+    placeholder: 'common.search_placeholder',
+    type: 'input',
+  },
+]
+```
+
+## 2. 字段说明
+
+- `prop`: 表单字段名（必填）
+- `label`: 国际化 key（必填，`SearchArea` 内会自动 `t(label)`）
+- `type`: `'input' | 'select' | 'date' | 'dateRange'`，默认 `input`
+- `placeholder`: 字符串或数组（日期范围）
+- `width`: 控件宽度（默认 `100%`）
+- `clearable`: 是否可清空（默认 `true`）
+- `multiple`: `select` 多选模式
+- `format`: 日期格式（`date` / `dateRange` 可用）
+
+### select 专用
+
+- `options: Array<{ label: string; value: any }>`
+- `label` 同样按 i18n key 处理（自动 `t(item.label)`）
+
+示例：
+
+```ts
+{
+  prop: 'status',
+  label: 'common.status',
+  type: 'select',
+  options: [
+    { label: 'common.enabled', value: 1 },
+    { label: 'common.disabled', value: 0 },
+  ],
+}
+```
+
+## 3. 日期范围（重点）
+
+`dateRange` 支持把一个范围字段自动映射成后端两个参数。
+
+### 配置项
+
+- `rangeStartProp`: 开始参数名（默认 `${prop}Start`）
+- `rangeEndProp`: 结束参数名（默认 `${prop}End`）
+- `format`: 输出格式（默认 `YYYY-MM-DD HH:mm:ss`）
+
+### 默认行为
+
+当点击“搜索”时，`ListPageView` 会自动转换：
+
+- start -> 当天 `00:00:00`
+- end -> 当天 `23:59:59`
+
+并删除原始 `prop`（范围数组）字段，避免后端收到冗余参数。
+
+### 示例（反馈页面同款）
+
+```ts
+{
+  prop: 'startDate',
+  label: 'menus.feedback.filter_content',
+  placeholder: ['提交开始时间', '提交结束时间'],
+  type: 'dateRange',
+  rangeStartProp: 'startDateStart',
+  rangeEndProp: 'startDateEnd',
+  format: 'YYYY-MM-DD HH:mm:ss',
+}
+```
+
+最终请求参数：
+
+- `startDateStart`
+- `startDateEnd`
+
+## 4. 数据流
+
+1. 用户在 `SearchArea` 输入条件
+2. 点击搜索后，`ListPageView` 读取 `form.getFieldsValue()`
+3. `ListPageView` 根据 `searchFields` 统一标准化（含 `dateRange` 映射）
+4. 标准化结果写入 `searchFormData`
+5. `pageConfig.fetchTableData()`（由配置工厂返回的 hook 提供）组装分页 + 搜索参数发起 `tableAPI`
+
+## 5. 建议
+
+- 页面不要在 `SearchArea` 里写业务参数转换逻辑
+- 所有“字段名映射”都通过 `searchFields` 配置声明
+- 新增页面优先复用该模式，保证行为一致
+
+## 6. 关联文档
+
+- 配置工厂全貌见 [`props.1.create-table-view-config.md`](./props.1.create-table-view-config.md)
+- 模块总览见 [`comp.1.table-view.md`](./comp.1.table-view.md)

package/src/api/_mock/README.md

@@ -0,0 +1,340 @@
+# Mock 数据使用指南
+
+## 🎯 快速开始
+
+### 1. 启用 Mock 模式
+
+在 `src/main.tsx` 中已经默认启用：
+
+```typescript
+import { enableMock } from './api/_mock/mod';
+
+// 启用 Mock 模式，延迟 300ms（模拟真实网络）
+enableMock(300);
+```
+
+### 2. 禁用 Mock 模式
+
+注释掉或移除这行代码即可使用真实 API：
+
+```typescript
+// enableMock(300); // 注释这行
+```
+
+---
+
+## 💡 工作原理
+
+Mock 系统已经**完全集成到 Axios** 中，所有 HTTP 请求都会自动经过 Mock 拦截器：
+
+- ✅ **自动拦截** - 无需修改任何业务代码
+- ✅ **统一处理** - 所有请求都走同一个 Mock 引擎
+- ✅ **即开即用** - 启用后立即生效
+- ✅ **无缝切换** - Mock/真实 API 一键切换
+
+当你调用任何 API（如 `api.post('/users/list', params)`）时：
+
+1. Mock 拦截器检查 URL 是否在映射表中
+2. 如果匹配，返回 Mock 数据（带延迟模拟）
+3. 如果不匹配，继续发送真实请求
+
+---
+
+## 🔧 动态切换 Mock 模式
+
+在浏览器控制台直接操作（开发环境）：
+
+```javascript
+// 启用 Mock
+window.enableMock(500); // 500ms 延迟
+
+// 禁用 Mock
+window.disableMock();
+
+// 切换模式
+window.toggleMock();
+
+// 检查状态
+window.isMockEnabled(); // true/false
+```
+
+---
+
+## 📦 已支持的 Mock API
+
+### ✅ 用户管理
+- `POST /users/list` - 获取用户列表
+- `POST /users/create` - 创建用户
+- `POST /users/update` - 更新用户
+- `POST /users/delete` - 删除用户
+
+### ✅ 角色管理
+- `POST /roles/list` - 获取角色列表
+- `POST /roles/assignable-to-user` - 获取可分配角色
+- `POST /roles/create` - 创建角色
+- `POST /roles/delete` - 删除角色
+
+### ✅ 部门管理
+- `POST /departments/tree` - 获取部门树
+- `POST /departments/members` - 获取部门成员
+- `POST /departments/create` - 创建部门
+- `POST /departments/update` - 更新部门
+- `POST /departments/delete` - 删除部门
+
+### ✅ 反馈管理
+- `POST /feedback/list` - 获取反馈列表
+- `POST /feedback/delete` - 删除反馈
+
+### ✅ 认证相关
+- `POST /auth/login` - 登录
+- `POST /auth/register` - 注册
+- `POST /auth/check-email` - 检查邮箱
+- `POST /auth/public-key` - 获取公钥
+
+---
+
+## 📝 Mock 数据示例
+
+### 用户数据
+```json
+{
+  "id": 1,
+  "email": "admin@example.com",
+  "display_name": "系统管理员",
+  "phone_number": "+86 13800138000",
+  "is_active": true,
+  "roles": ["admin"],
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### 角色数据
+```json
+{
+  "id": 1,
+  "name": "admin",
+  "description": "系统管理员",
+  "permissions": ["*"]
+}
+```
+
+### 部门数据
+```json
+{
+  "id": 1,
+  "name": "总公司",
+  "code": "HQ",
+  "level": 1,
+  "path": "/1/",
+  "children": [
+    {
+      "id": 2,
+      "name": "技术部",
+      "code": "TECH",
+      "level": 2
+    }
+  ]
+}
+```
+
+---
+
+## 🎨 自定义 Mock 数据
+
+### 修改现有数据
+
+编辑 `src/api/_mock/index.ts`：
+
+```typescript
+export const mockUsers = {
+  items: [
+    {
+      id: 1,
+      email: 'your-custom@email.com',
+      display_name: '自定义名称',
+      // ... 其他字段
+    }
+  ],
+  total: 1
+};
+```
+
+### 添加新的 Mock API
+
+1. 在 `src/api/_mock/api.ts` 中添加处理函数：
+
+```typescript
+export const yourCustomApi = {
+  getData: async (params: any) => {
+    if (!mockManager.isEnabled()) {
+      throw new Error('Not in mock mode');
+    }
+    
+    return mockManager.response({
+      data: { /* 你的数据 */ }
+    });
+  }
+};
+```
+
+2. 在拦截器中注册：
+
+```typescript
+const mockApiMap: Record<string, any> = {
+  '/your/endpoint': (data: any) => yourCustomApi.getData(data),
+  // ...
+};
+```
+
+---
+
+## 🔍 调试技巧
+
+### 查看日志
+
+打开浏览器控制台，可以看到：
+
+```
+✅ Mock mode enabled
+📝 API calls will return mock data with 300 ms delay
+[Mock] Request intercepted: /users/list
+[Mock Interceptor] Returning mock data for: /users/list
+[Mock] Response: { data: {...}, config: {...} }
+```
+
+### 检查网络请求
+
+在 Network 面板中，Mock 请求会显示为：
+- Status: 200 OK
+- Size: mock data
+- Time: ~300ms（你设置的延迟）
+
+---
+
+## ⚙️ 配置选项
+
+### 调整延迟时间
+
+```typescript
+enableMock(0);     // 无延迟，立即响应
+enableMock(300);   // 300ms 延迟（推荐）
+enableMock(1000);  // 1000ms 延迟（测试慢速网络）
+```
+
+### 关闭调试日志
+
+编辑 `src/api/_mock/index.ts`（`MockManager` 配置）：
+
+```typescript
+private config: MockApiConfig = {
+  enabled: false,
+  delay: 300,
+  debug: false  // 改为 false 关闭日志
+};
+```
+
+---
+
+## 🚀 使用场景
+
+### ✅ 适合使用 Mock 的场景
+- 在家办公，无法访问公司内网 API
+- 后端接口还未开发完成
+- 前端功能演示和原型展示
+- 单元测试和集成测试
+- 离线开发和调试
+
+### ❌ 不适合使用 Mock 的场景
+- 需要测试真实的 API 性能
+- 需要验证后端业务逻辑
+- 联调测试阶段
+- 生产环境部署
+
+---
+
+## 💡 最佳实践
+
+1. **开发时启用 Mock**
+   ```typescript
+   // main.tsx
+   if (process.env.NODE_ENV === 'development') {
+     enableMock(300);
+   }
+   ```
+
+2. **按需切换模式**
+   ```typescript
+   // 在组件内临时切换
+   useEffect(() => {
+     if (needRealAPI) {
+       disableMock();
+     } else {
+       enableMock(300);
+     }
+     
+     return () => {
+       // 清理时恢复
+       enableMock(300);
+     };
+   }, [needRealAPI]);
+   ```
+
+3. **使用环境变量控制**
+   ```typescript
+   // .env.development
+   VITE_USE_MOCK=true
+   
+   // main.tsx
+   if (import.meta.env.VITE_USE_MOCK === 'true') {
+     enableMock(300);
+   }
+   ```
+
+---
+
+## 🐛 常见问题
+
+### Q: 为什么我的请求还是失败？
+A: 检查以下几点：
+1. 确认 `enableMock()` 已调用
+2. 检查 API 路径是否在 `mockApiMap` 中
+3. 查看控制台是否有错误日志
+
+### Q: 如何添加更多 Mock 数据？
+A: 直接修改 `src/api/_mock/index.ts` 等文件中的数据数组，可以添加任意数量的测试数据。
+
+### Q: 能否模拟错误响应？
+A: 可以，使用 `mockManager.error()` 方法：
+```typescript
+if (shouldFail) {
+  return mockManager.error('模拟的错误信息', 500);
+}
+```
+
+### Q: Mock 数据会影响性能吗？
+A: 不会，Mock 数据只在开发环境使用，生产环境会自动禁用。
+
+---
+
+## 📚 文件结构
+
+```
+src/api/
+├── mock.ts              # Mock 数据定义和管理器
+├── mock.api.ts          # Mock API 接口实现
+├── mock.interceptor.ts  # Mock 拦截器
+├── mock.utils.ts        # Mock 工具函数
+└── client.ts            # Axios 客户端（已集成 Mock）
+```
+
+---
+
+## 🎉 开始使用
+
+现在你可以：
+1. ✅ 在家离线开发
+2. ✅ 无需依赖后端 API
+3. ✅ 页面正常跑起来
+4. ✅ 随时切换真实 API
+
+祝你开发顺利！🚀