cx-chat 0.0.2 → 0.0.3

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

@@ -1,542 +0,0 @@
-# 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*