cx-chat 0.0.1

package/src/_doc/table-view/comp.1.table-view.md

@@ -0,0 +1,542 @@
+# table-view 模块架构说明
+
+> 对应源码：`src/components/table-view/`。列表整页壳组件为 **`ListPageView`**，弹层内选人表为 **`SelectTableView`**（入口另导出 `SelectTable` 等别名）；配置工厂为 **`createListPageConfig`**（整页列表）与 **`createSelectTableConfig`**（弹层选人）。本文说明目录结构、职责划分与使用约定。
+
+## 📁 文件结构
+
+```
+src/components/table-view/
+├─ index.tsx                   # 统一导出（默认 `ListPageView`、`createListPageConfig`、`createSelectTableConfig` 等）
+├─ list-page-view.tsx          # 列表页主组件（核心逻辑）
+├─ select-table-view.tsx       # 弹层内选人表
+└─ components/
+   ├─ table-view.types.ts      # 类型定义
+   ├─ table-view-config.tsx    # 配置工厂（`createListPageConfig` / `createSelectTableConfig`）
+   ├─ search-area.tsx
+   └─ tree-sidebar.tsx
+```
+
+轻量原生表格组件已迁移到：`src/components/common/lite-table/`（用于简单展示/工具方法复用）。
+
+列表/选人表空状态（无数据、未选树等）使用 **`CxEmptyState`**（`import { CxEmptyState } from '@cx-ui'`），说明见 [`../cx-ui/comp.7.cx-empty-state.md`](../cx-ui/comp.7.cx-empty-state.md)。
+
+---
+
+## 🏗️ 架构设计理念
+
+### 1. 配置驱动 + 组件组合
+- **80%** 的整页列表通过 `createListPageConfig` 快速生成；弹层选人场景用 `createSelectTableConfig` 与同一套请求/搜索组装逻辑
+- **20%** 的特殊需求通过自定义组件/插槽实现
+
+### 2. 职责分离
+- **ListPageView**：带顶栏的整页列表（标题、树、搜索、表格、分页）
+- **SelectTableView**：弹层/嵌入场景的搜索 + 表格（可选树），与同一套 `pageConfig` 数据流一致
+- **子组件**（`components/` 内）：树、搜索区、纯表格等可复用块
+- **页面**：只负责业务配置与对应工厂入参（`createListPageConfig` / `createSelectTableConfig`）、少量插槽
+
+### 3. 组件自治
+- Modal 等子组件自己管理显示/隐藏状态
+- ListPageView 只通过 `ref` 触发，不管理细节
+
+### 4. Hooks 规范
+- 每个组件内部独立调用 `useTranslation` 等 hooks
+- 不通过 props 传递 hooks（如 `t` 函数）
+
+---
+
+## 📋 核心接口
+
+所有类型从 `@components/table-view` 导入：
+
+```typescript
+import type {
+  PageConfig,              // 页面配置（核心）
+  ListPageViewProps,       // 列表页组件 props
+  SearchField,             // 搜索字段配置
+  TreeConfig,              // 树形配置
+  ListRenderContext,       // 列表渲染上下文
+  TreeContext,             // 树形上下文
+} from '@components/table-view'
+```
+
+---
+
+## 🔧 使用示例
+
+### 示例 1：标准 CRUD 页面（角色管理）
+
+```tsx
+import ListPageView, { createListPageConfig } from '@components/table-view'
+import { getRoleListAPI, deleteRoleAPI } from '@api/system/role'
+import SubmitModal from './modal/submit-modal'
+import DetailModal from './modal/detail-modal'
+
+const useListPageConfig = createListPageConfig({
+  tableAPI: getRoleListAPI,
+  deleteAPI: deleteRoleAPI,
+  pageInfo: {
+    title: 'p_system.role.page_title',
+    subTitle: 'p_system.role.page_subtitle',
+  },
+  searchFields: [
+    {
+      prop: 'searchQ',
+      label: 'p_system.role.name',
+      type: 'input',
+      placeholder: 'p_system.role.search_placeholder',
+    },
+  ],
+  columns: [], // 在组件中动态定义
+  table: {
+    showSelection: true,
+    operationWidth: 250,
+  },
+  submitAction: {
+    permission: 'role:create',
+    submitType: 'modal',
+    labelKey: 'p_system.role.add',
+  },
+  detailAction: {
+    detailType: 'modal',
+    labelKey: 'p_system.role.detail_title',
+  },
+  deleteConfirm: {
+    title: 'p_system.role.delete_confirm_title',
+    content: 'p_system.role.delete_confirm_content',
+  },
+})
+
+function RolePage() {
+  const pageConfig = useListPageConfig()
+  
+  // 动态定义 columns
+  pageConfig.columns = useMemo(() => [
+    {
+      title: 'p_system.role.name',
+      dataIndex: 'name',
+      key: 'name',
+    },
+    // ... 其他列
+  ], [])
+
+  return (
+    <ListPageView
+      pageConfig={pageConfig}
+      submitModalComponent={SubmitModal}
+      detailModalComponent={DetailModal}
+    />
+  )
+}
+```
+
+---
+
+### 示例 2：带树形选择器的页面（部门管理）
+
+```tsx
+const useListPageConfig = createListPageConfig({
+  // 列表：根据 deptId 分页查询成员
+  tableAPI: async ({ page, size, sort, order, deptId }) => {
+    if (!deptId) return { data: { items: [], total: 0 }, total: 0 }
+    // 实际请求由 getDepartmentMembersAPI 消费 ListPageView 组装的整包 params（含 page/size/sort/order）
+    const res = await getDepartmentMembersAPI({ page, size, sort, order, deptId })
+    return { data: res.data, total: res.data?.total || 0 }
+  },
+  // 树：获取部门树
+  treeAPI: async () => {
+    const res = await getDepartmentTreeAPI()
+    return res.data || []
+  },
+  tree: {
+    title: 'department.title',
+    fieldNames: {
+      id: 'id',
+      label: 'name',
+      children: 'children',
+    },
+    searchField: 'deptId', // 选择树节点后，自动搜索的字段
+    autoSearch: true,      // 选择后是否自动刷新列表
+    unselectText: 'department.unselect_tree_hint',
+    // defaultSelectRoot 默认 true；部门管理常设 false（不自动选根，须点部门）
+    // fetchTableOnMount 默认等价 false：有树时挂载不拉表；须 true 时才首屏拉表，见下文
+  },
+  // ... 其他配置
+})
+
+function DepartmentPage() {
+  const pageConfig = useListPageConfig()
+
+  return (
+    <ListPageView
+      pageConfig={pageConfig}
+      tableActions={({ tree }) => {
+        // 树形上下文：tree.selectedNode, tree.selectedKey
+        if (!tree?.selectedNode) return null
+        
+        return (
+          <div>
+            <h2>{tree.selectedNode.name}</h2>
+            {/* 自定义操作按钮 */}
+          </div>
+        )
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 🌳 左侧树与表格：`defaultSelectRoot` 与 `fetchTableOnMount`
+
+当页面配置了 `treeAPI` 时，列表常依赖树上的筛选字段（如 `deptId`）。**两件事分开配置**，避免「一个布尔既管选根又管拉表」语义冲突：
+
+| 配置项 | 职责 |
+|--------|------|
+| **`defaultSelectRoot`** | 仅控制树 `treeData` 就绪后是否**自动选中第一条根**（与手动点树走同一套 `handleTreeSelect`）。默认 `true`（`TABLE_VIEW_TREE_DEFAULTS`）。设为 `false` 时不自动选根（如部门管理须手动点部门）。 |
+| **`fetchTableOnMount`** | 仅控制**挂载时**是否在配置工厂返回的 hook 内立刻调 `fetchTableData`。有左侧树时**默认为不拉**（未写或不为 `true` 即不在挂载拉表）。**仅当**设 `tree.fetchTableOnMount: true` 时，有树也会在首屏拉表。 |
+
+**树节点选中后是否拉表**：由 **`tree.autoSearch`**（及 `handleTreeSelect` 内 `patchSearchAndRefresh` / `handleSearch`）决定，与 `fetchTableOnMount` **无关**。不应出现「配置了不在挂载拉表却希望点树也不拉表」这类与列表页职责相悖的组合；若业务真要「点树只改 UI 不查表」，应关 `autoSearch` 并自行在 `onSelect` 里控制，而不是用 `fetchTableOnMount`。
+
+### 常见组合
+
+| 场景 | `defaultSelectRoot` | `fetchTableOnMount` | 效果概要 |
+|------|---------------------|---------------------|----------|
+| 通用「树+表」、须节点 ID 才能查 | 默认 `true` | 默认（不写） | 挂载不拉表 → 自动选根 → 按 `autoSearch` 拉表 |
+| **部门管理**（须选手动部门、未选不查人） | `false` | 默认（不写） | 挂载不拉表、不自动选根 → 用户点部门后 `autoSearch` 拉表 |
+| 有树但接口允许无筛选首屏也要数据 | 自定 | `true` | 挂载即拉表（仍可与自动选根并存，按业务避免重复请求） |
+
+### 配置示例（部门管理，与现有一致）
+
+```typescript
+const useListPageConfig = createListPageConfig({
+  tableAPI: getDepartmentUsersAPI,
+  treeAPI: getDepartmentTreeAPI,
+  tree: { defaultSelectRoot: false },
+  // 不写 fetchTableOnMount → 有树时挂载不拉表；点选部门后由 autoSearch 拉成员
+})
+```
+
+### 相关源码
+
+- `components/table-view.types.ts`：`TreeConfig.defaultSelectRoot`、`fetchTableOnMount`、`TABLE_VIEW_TREE_DEFAULTS`
+- `components/table-view-config.tsx`：首次 `useEffect` 仅在「无树」或 `fetchTableOnMount === true` 时 `fetchTableData`
+- `list-page-view.tsx`：`defaultSelectRoot !== false` 时树就绪后自动 `handleTreeSelect(第一条根)`
+
+---
+
+### 示例 3：完全自定义列表（反馈管理）
+
+```tsx
+function FeedbackPage() {
+  const pageConfig = useListPageConfig()
+
+  return (
+    <ListPageView
+      pageConfig={pageConfig}
+      headerActions={
+        // 自定义头部操作
+        <>
+          <button onClick={() => setExportOpen(true)}>导出</button>
+          {/* 状态筛选按钮 */}
+        </>
+      }
+      renderList={(ctx) => (
+        // 完全自定义列表渲染
+        <FeedbackDatasetList
+          pageConfig={pageConfig}
+          tableData={ctx.tableData}
+          loading={pageConfig.loading}
+        />
+      )}
+    />
+  )
+}
+```
+
+---
+
+## ⚙️ PageConfig 配置项详解
+
+### API 配置
+
+```typescript
+// 扁平化设计，直接在根级别定义
+tableAPI: (params: any) => Promise<any>    // 表格数据 API（可选）
+deleteAPI?: (id: string | number) => Promise<void>  // 删除 API（可选）
+treeAPI?: () => Promise<any[]>             // 树形数据 API（可选）
+```
+
+### 页面基本信息
+
+```typescript
+pageInfo: {
+  /** 页面标题（国际化 key） */
+  title: string
+  
+  /** 副标题（国际化 key） */
+  subTitle?: string
+  
+  /** 列表标题（显示在搜索区上方） */
+  listTitle?: string
+}
+```
+
+### 分页配置
+
+```typescript
+pagination: {
+  page: number      // 当前页码，从 1 开始（与请求参数 `page` 一致）
+  pageSize: number  // 每页数量（请求里字段名为 `size`）
+  total: number     // 总数
+}
+
+// 可选：覆盖底部分页「每页条数」下拉；默认 [10, 20, 50, 100, 200, 500, 1000]
+pageSizeOptions?: number[]
+
+// 可选：列表默认排序；默认 sort=createTime、order=desc
+listQuery?: { sort?: string; order?: 'asc' | 'desc' }
+```
+
+`tableAPI` 收到的分页与排序字段为：`page`（≥1）、`size`、`sort`、`order`，其余为搜索区与树联动字段。
+
+### 搜索表单配置
+
+```typescript
+searchFields?: Array<{
+  prop: string         // 字段名（必填）
+  label: string        // 标签（必填）
+  type?: 'input' | 'select' | 'date'  // 类型，默认为 'input'
+  placeholder?: string // 占位符
+  clearable?: boolean  // 是否可清空，默认为 true
+  options?: Array<{ label: string; value: any }> // select 选项
+  multiple?: boolean   // select 是否多选
+  format?: string      // date 格式化
+}>
+```
+
+### 表格列配置
+
+```typescript
+columns: ColumnsType<any>
+```
+
+### 表格行为配置
+
+```typescript
+table?: {
+  showSelection?: boolean   // 是否显示多选框
+  showPagination?: boolean  // 是否显示分页
+  showBatchDelete?: boolean // 是否显示批量删除
+  operationWidth?: number   // 操作列宽度
+}
+```
+
+### 新增/编辑操作配置
+
+```typescript
+submitAction?: {
+  permission: string      // 权限标识
+  submitType: 'modal' | 'page' // 提交方式
+  labelKey: string        // 按钮文案（国际化 key）
+}
+```
+
+### 详情操作配置
+
+```typescript
+detailAction?: {
+  permission: string
+  detailType: 'modal' | 'page'
+  labelKey: string
+}
+```
+
+### 删除确认弹窗配置
+
+```typescript
+deleteConfirm?: {
+  title: string
+  content: string
+  okText: string
+  cancelText: string
+}
+```
+
+### 回调函数（可选，用于完全接管）
+
+```typescript
+onAdd?: (payload: { type: 'add'; config?: any }) => void
+onEdit?: (payload: { type: 'edit'; record: any; config?: any }) => void
+onDetail?: (payload: { type: 'detail'; record: any; config?: any }) => void
+
+// 数据刷新方法（由 `createListPageConfig` / `createSelectTableConfig` 返回的 hook 自动提供）
+fetchTableData?: () => Promise<void>
+handleSearch?: () => void
+handleReset?: () => void
+patchSearchAndRefresh?: (patch: Record<string, unknown>) => void
+
+// 列表工厂可选扩展（见 props.1.create-table-view-config.md）
+afterGetPageData?: () => void | Promise<void>
+afterDelete?: (record: any) => void | Promise<void>
+afterStatusChange?: (record: any, nextStatus: number) => void | Promise<void>
+```
+
+---
+
+## 🎯 Modal 组件规范
+
+### ✅ 正确做法
+
+使用 `forwardRef` + `useImperativeHandle` 模式：
+
+```tsx
+import React, { forwardRef, useImperativeHandle, useState } from 'react'
+import { CxModal } from '@cx-ui'
+
+const RoleModal = forwardRef((props, ref) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const [formData, setFormData] = useState({})
+
+  useImperativeHandle(ref, () => ({
+    open: (payload = {}) => {
+      // 初始化数据
+      setIsOpen(true)
+    },
+    close: () => {
+      setIsOpen(false)
+    },
+  }))
+
+  const handleOk = async () => {
+    // 验证 → 提交 → 调用父组件 onOk → 关闭
+    await props.onOk?.(formData)
+    close()
+  }
+
+  return (
+    <CxModal
+      isOpen={isOpen}
+      onClose={close}
+      onOk={handleOk}
+    >
+      {/* 表单内容 */}
+    </CxModal>
+  )
+})
+```
+
+### ❌ 错误做法
+
+- ❌ 在父组件用 `useState` 控制 Modal 开关
+- ❌ Modal 没有暴露 `open/close` 方法
+- ❌ 父组件直接传递 `open/onClose` props
+
+---
+
+## 🔄 数据流
+
+### 新增流程
+
+1. 用户点击"新增"按钮
+2. `ListPageView` 内新增流程 → `submitModalRef.current?.open({ opeType: 'add' })`
+3. Modal 组件内部设置 `isOpen = true`
+4. 用户填写表单并提交
+5. Modal 内部验证 → 调用 `props.onOk(values)`
+6. ListPageView 收到 `onOk` 回调 → 调用 `fetchTableData()` 刷新列表；若配置了 `afterGetPageData`，在拉表成功后会继续执行该钩子
+7. Modal 关闭
+
+### 删除流程
+
+1. 用户点击删除按钮
+2. `pageConfig.onDelete(record)`（由 ListPageView 注入）→ 打开确认弹窗
+3. 用户确认 → `handleConfirmDelete()`
+4. 调用 `API.delete(id)`
+5. 刷新列表 → `fetchTableData()`
+6. 关闭弹窗
+
+### 树形选择流程
+
+1. （默认）树数据加载完成后，若 `defaultSelectRoot !== false`，自动选中第一条根节点，后续步骤与手动点击一致
+2. 用户点击树节点（或上一步自动选中）
+3. `TreeSidebar` → `handleTreeSelect(key)`
+4. ListPageView 将节点 ID 写入 `searchFormData` 中 `tree.searchField` 对应字段（如 `deptId`）
+5. 在 `tree.autoSearch === true` 时调用 `patchSearchAndRefresh` / `handleSearch()` 刷新列表
+6. 表格显示当前选中节点下的数据
+
+---
+
+## 📝 最佳实践
+
+### 1. 优先使用配置
+- ✅ 能用配置解决的，不要写自定义代码
+- ✅ 保持代码一致性和可维护性
+
+### 2. 按需扩展
+- ✅ 只有配置无法满足时，才使用 `onAdd/onEdit` 等回调
+- ✅ 尽量使用 `renderList/tableActions` 等插槽
+
+### 3. Modal 自治
+- ✅ Modal 组件自己管理所有内部状态
+- ✅ 父组件只负责数据刷新
+
+### 4. 类型安全
+- ✅ 所有配置都使用 TypeScript 类型
+- ✅ 从 `@components/table-view`（`components/table-view.types.ts`）导入类型
+
+### 5. 国际化
+- ✅ 所有文案使用国际化 key
+- ✅ 组件内部调用 `useTranslation()`，不要通过 props 传递
+
+---
+
+## 🐛 常见问题
+
+### Q1: Modal 不显示？
+
+**A:** 检查是否正确使用 `ref.current?.open()`，而不是试图用 props 控制
+
+### Q2: 列表数据不刷新？
+
+**A:** 确保在 Modal 的 `onOk` 回调中调用了 `fetchTableData()`
+
+### Q3: 树形选择后列表不更新？
+
+**A:** 检查 `tree.autoSearch` 是否为 true，或手动调用 `patchSearchAndRefresh()`
+
+### Q6: 有左侧树时，一进页面就请求表格报错（如缺少 deptId）？
+
+**A:** 有树时默认**不会**在挂载拉表；自动选根或用户点树后再由 `autoSearch` 拉表。若仍出现首屏拉表，检查是否误设了 `tree.fetchTableOnMount: true`。需要「无筛选也首屏拉表」时显式 `fetchTableOnMount: true` 并保证接口语义正确。
+
+### Q4: 自定义 columns 不生效？
+
+**A:** 确保在组件内使用 `useMemo` 动态赋值给 `pageConfig.columns`
+
+### Q5: 搜索表单值变化但列表不刷新？
+
+**A:** 搜索表单的值不会自动触发刷新，需要点击"搜索"按钮或按回车
+
+---
+
+## 📚 相关文件
+
+- `src/components/table-view/components/table-view-config.tsx` - 配置工厂（`createListPageConfig`、`createSelectTableConfig`），由 `index.tsx` 统一再导出
+- `src/components/cx-ui/modal` - 模态框基础组件（CxModal）；参数说明见 `src/_doc/cx-ui/comp.2.cx-modal.md`
+- `src/components/ui/Pagination.tsx` - 分页组件
+- `src/components/common/modal/confirm-dialog.tsx` - 确认对话框（列表删除等，`list-page-view` 使用；`ui/ConfirmDialog` 可作对照）
+
+---
+
+## 🎨 架构优势
+
+| 指标 | 优化前 | 优化后 | 改进 |
+|------|--------|--------|------|
+| **主文件行数** | 799 行 | 500 行 | **-37%** |
+| **最大文件** | 799 行 | 500 行 | **-37%** |
+| **文件数** | 1 个 | 6 个 | 模块化 |
+| **可读性** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +67% |
+| **可维护性** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +20% |
+
+---
+
+*最后更新：2026-04-17*