cx-chat 0.0.1

package/src/_doc/cx-ui/comp.5.cx-fields.md

@@ -0,0 +1,76 @@
+# 表单与搜索控件（CxInput 等）说明
+
+> 适用范围：`input`、`input-number`、`select`、`multi-select`、`date-picker`、`range-picker`、`tree-select`、`switch`  
+> 目标：统一 **表单区** 与 **搜索区** 控件高度与圆角，其余行为以 antd 为准。
+
+## 1. 通用约定：`variant`
+
+多数控件支持可选属性：
+
+| `variant` | 典型高度 | 使用场景 |
+|-----------|----------|----------|
+| `'cxForm'` | **42px**（日期/范围通过 class 与 less 控制视觉） | 表单、弹窗 |
+| `'cxSearch'` | **40px** | `ListPageView` 搜索区等 |
+
+未传时默认为 **`cxForm`**。
+
+其余 props **透传对应 antd 组件**（`value`、`onChange`、`options`、`disabled` 等），请参考 [Ant Design](https://ant.design/) 文档。
+
+---
+
+## 2. 各组件摘要
+
+### CxInput（`input/index.jsx`）
+
+- antd `Input`；`type="textarea"` 时使用 `Input.TextArea`（高度由 TextArea 自身控制，仍带 `cx-input` 与圆角）。
+- 单行：`height` 由 `variant` 决定（42 / 40）。
+
+### CxInputNumber（`input-number/index.jsx`）
+
+- antd `InputNumber`；默认 **`width: 100%`**（可被 `style.width` 覆盖）。
+- `variant` 控制高度 42 / 40。
+
+### CxSelect（`select/index.jsx`）
+
+- antd `Select`，固定 **`size="large"`**，与高度样式配合。
+- `variant` 控制外层高度 42 / 40。
+
+### CxMultiSelect（`multi-select/index.jsx`）
+
+- antd `Select` **`mode="multiple"`**。
+- 下拉顶部提供 **全选 / 取消全选**（文案为中文「全选」「取消全选」）。
+- **`options`**：业务应传入真实选项；未传时组件内有占位示例数据（开发时注意替换）。
+- `variant` 控制高度 42 / 40。
+
+> **说明**：同目录另有 `index2.tsx` 为自绘多选（Portal、Lucide 图标等），**未从 `@cx-ui` 根导出**。包内默认导出为 `index.jsx`。
+
+### CxDatePicker（`date-picker/index.jsx`）
+
+- antd `DatePicker`；**宽度 100%**。
+- 根据 **`document.documentElement.lang`** 选择 antd locale 与 **dayjs** locale（支持 `zh-CN` / `en-US` 及简写 `zh` / `en`），并在 `useEffect` 中 `dayjs.locale(...)`。
+- `className` 含 `cx-date-picker--cxForm` / `cx-date-picker--cxSearch`。
+
+### CxRangePicker（`range-picker/index.jsx`）
+
+- antd `DatePicker.RangePicker`；行为与日期 locale、`variant`、宽度约定同 `CxDatePicker`。
+
+### CxTreeSelect（`tree-select/index.jsx`）
+
+- antd `TreeSelect`，**`size="large"`**。
+- **`treeDefaultExpandAll`**：在「非受控展开」场景下，内部会随 **`treeData` 变化** 重新计算可展开 key，避免异步树数据仅首次展开的问题；若同时传入 **`treeExpandedKeys`** 则视为受控，不启用该内部逻辑。
+- `variant` 控制高度 42 / 40。
+
+### CxSwitch（`switch/index.tsx`）
+
+- antd `Switch`，增加 **`cx-switch`** class。
+- **`variant`**：`default` | **`text`**（`checkedText` / `uncheckedText` 轨道内文案）| **`dual`**（`leftLabel` / `rightLabel` + `dualUncheckedValue` / `dualCheckedValue`，选中侧主题色）。
+
+---
+
+## 3. 相关文件
+
+- 各组件目录下 `index.jsx` / `index.tsx` 与 `index.less`（若有）
+
+---
+
+*最后更新：2026-04*

package/src/_doc/cx-ui/comp.6.cx-tag.md

@@ -0,0 +1,57 @@
+# CxTag 说明
+
+> 适用范围：`src/components/cx-ui/tag`  
+> 目标：在 antd [Tag](https://ant.design/components/tag-cn) 上挂根类 `cx-tag`，默认 **`variant="filled"`**；列表里「启用/禁用、是/否」等状态与用户管理状态列**同色**；圆角与主题对齐，并支持胶囊形态与自定义。
+
+## 1. 与 antd 的关系
+
+| 项 | 说明 |
+|----|------|
+| 基础 | 封装 `Tag`，根节点增加 `cx-tag`，样式见 `tag/index.less`（并由 `cx-ui/styles/index.less` 聚合引入） |
+| `TagProps` | **透传**（`color`、`icon`、`closable`、`onClose`、`href`、`styles`、`classNames` 等与官方一致） |
+| `variant` | **默认 `filled`**；可改为 `solid`、`outlined` |
+| `color` | 与 antd 一致：语义色 `success`、`error`、`warning`、`processing`、`default`，或**色值**（如 `#6366f1`）；自定义色时仍按 antd 规则计算背景/边框等 |
+| `pill` | **CxTag 扩展**：为 `true` 时使用胶囊全圆角及固定字号/内边距（与用户管理表格状态列一致） |
+
+组件使用 `forwardRef` + `memo`，表格列以纯展示为主时可减轻无关重渲染。
+
+```tsx
+import { CxTag } from '@cx-ui'
+```
+
+## 2. 样式约定（`tag/index.less`）
+
+- **默认圆角**：`border-radius: var(--ant-border-radius-sm, 6px)`，与 antd 主题 token 对齐；无变量时回退 `6px`。
+- **`pill`**：全圆角 + `font-size: 12px`、`font-weight: 500`、内边距与用户管理状态列一致。
+- **`filled` + `success` / `error`**：在 `.cx-tag` 下覆盖背景与文字色，与用户管理启用/禁用**对齐**（含 `.dark` 变体）。其它语义色仍走 antd 默认。
+- **自定义**：通过 `className`、`style` 或 antd `styles` / `classNames`（6.x 语义化 DOM）覆盖即可。
+
+## 3. 示例
+
+```tsx
+// 与用户管理状态列同观感（推荐）
+<CxTag color={status === 1 ? 'success' : 'error'} pill>
+  {status === 1 ? t('user.table.status_active') : t('user.table.status_disabled')}
+</CxTag>
+
+// 是 / 否
+<CxTag color={enabled ? 'success' : 'error'} pill>
+  {enabled ? t('common.yes') : t('common.no')}
+</CxTag>
+
+// 普通标签：主题圆角 + filled，自定义色值
+<CxTag color="#6366f1">标签</CxTag>
+
+// 仅改圆角
+<CxTag color="processing" style={{ borderRadius: 2 }} />
+```
+
+## 4. 类型导出
+
+- `CxTagProps`：`TagProps & { pill?: boolean }`
+
+源码：`src/components/cx-ui/tag/index.tsx`；样式：`src/components/cx-ui/tag/index.less`。
+
+---
+
+*最后更新：2026-04*

package/src/_doc/cx-ui/comp.7.cx-empty-state.md

@@ -0,0 +1,29 @@
+# CxEmptyState
+
+> 源码：`src/components/cx-ui/empty-state/index.tsx`。列表/选人表在无数据、未选树节点等场景下使用的居中空状态展示。
+
+## 导出
+
+从 `@cx-ui` 与包内其它组件一致：
+
+```ts
+import { CxEmptyState } from '@cx-ui'
+import type { CxEmptyStateProps } from '@cx-ui'
+```
+
+## Props
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `message` | `string` | 主文案（由业务传入，多为 i18n 结果） |
+
+## 使用场景
+
+- **`ListPageView`**：未选树节点时的 `unselectText`、表格无数据时的 `common.no_data` 等。
+- **`SelectTableView`**：同上。
+
+与旧路径 `src/components/common/empty-state` 脱钩后，空状态统一走 **cx-ui**，便于样式与依赖收敛。
+
+---
+
+*最后更新：2026-04-17*

package/src/_doc/meta/0.docs-overview.md

@@ -0,0 +1,24 @@
+# meta 文档总览
+
+> 对应源码 **`src/meta/`**：前端运行时元数据（**静态枚举** + **动态数据字典**）。对外入口为 **`@/meta`**（`src/meta/index.ts` 再导出 `index-enum` / `index-dict`）。
+
+## 文档列表
+
+| 文档 | 内容 |
+|------|------|
+| [`comp.1.enum-runtime.md`](./comp.1.enum-runtime.md) | `index-enum.ts`：`enumRegistry`、`ENUM_DATA`、`getEnumOptions` 等 |
+| [`comp.2.dict-runtime.md`](./comp.2.dict-runtime.md) | `index-dict.ts`：注册表、`DICT_KEY` / `DICT_DATA`、加载、`loadCommonDictData(true)`、与 React 同步 |
+
+## 阅读顺序
+
+1. 区分两类数据：**枚举**不请求后端；**字典**由后端分类 code 拉取。
+2. 改配置：枚举改 `index-enum.ts` 的 `enumRegistry`；字典改 `index-dict.ts` 的 `unauthDictRegistry` / `commonDictRegistry`。
+3. 业务页刷新字典：见 `comp.2` 与列表工厂 `afterGetPageData`（[`../table-view/props.1.create-table-view-config.md`](../table-view/props.1.create-table-view-config.md)）。
+
+## 关联
+
+- 组件与列表：[`../0.docs-overview.md`](../0.docs-overview.md)
+
+---
+
+*最后更新：2026-04-17*

package/src/_doc/meta/comp.1.enum-runtime.md

@@ -0,0 +1,33 @@
+# 静态枚举运行时（`index-enum`）
+
+> 主文件：`src/meta/index-enum.ts`。实现：`src/meta/module/enum-data/runtime.ts`。
+
+## 职责
+
+- 在构建期/启动期把 **`enumRegistry`** 注入 **`ENUM_DATA`** 各槽位：`option`、`valueMap`、`defaultValue`、`tagColorMap`（可选）。
+- 与字典对称：枚举 **不发起 HTTP**，适合状态码、是否、HTTP 方法等固定集合。
+
+## 改配置
+
+在 `index-enum.ts` 中编辑 **`enumRegistry`**（键 = 稳定访问键，与 `ENUM_DATA` 槽位一致），然后由 **`initEnumDataRuntime({ enumRegistry })`** 初始化（文件底部已调用）。
+
+## 常用 API
+
+| 导出 | 说明 |
+|------|------|
+| `ENUM_DATA` | 按访问键读槽位 |
+| `getEnumOptions(key)` | 选项列表 |
+| `getEnumLabelKey` / `getEnumDefaultValue` | 见 runtime 导出 |
+
+## 类型
+
+- **`EnumRegistryKey`**：`keyof typeof enumRegistry`
+
+## 与字典对照（摘自文件头注释）
+
+- 字典：`DICT_DATA[DICT_KEY.permission].option`、`getDictOptions(DICT_KEY.xxx)`
+- 枚举：`ENUM_DATA['commonStatus'].option`、`getEnumOptions('commonStatus')`
+
+---
+
+*最后更新：2026-04-17*

package/src/_doc/meta/comp.2.dict-runtime.md

@@ -0,0 +1,39 @@
+# 数据字典运行时（`index-dict`）
+
+> 主文件：`src/meta/index-dict.ts`。实现：`src/meta/module/dict-data/runtime.ts`。
+
+## 职责
+
+- 通过 **`unauthDictRegistry`**（免登录分类）与 **`commonDictRegistry`**（登录后 batch 分类）声明后台 **分类 code** 与前端 **`constKey`（访问键）** 的对应关系。
+- **`initDictDataRuntime`** 初始化 **`DICT_KEY`**（访问键 → code）与 **`DICT_DATA`** 槽位（`option`、`valueMap`、`defaultValue`）。
+- **`loadUnauthDictData()`**：按分类逐个 `getDictDataAPI`；可重复调用，每次重新发起请求。
+- **`loadCommonDictData(force?)`**：**登录后** `batchGetDictDataAPI` 拉取 `commonDictRegistry` 中所有分类。
+  - 默认 **`force === false`** 时，首次请求后的 Promise 会被缓存；再次调用**不会**重新打接口。
+  - **`loadCommonDictData(true)`**：清空缓存后重新拉取，用于 **管理端数据字典** 等场景在数据变更后刷新前端缓存（常与列表 `afterGetPageData` 搭配，见 [`../table-view/props.1.create-table-view-config.md`](../table-view/props.1.create-table-view-config.md) §4.4 示例）。
+
+## 与 React 同步
+
+- `useAuth().commonDictRevision`（若项目已接）
+- **`registerDictDataLoadedNotifier`**（或已废弃别名的 `registerCommonDictLoadedNotifier`）：在字典数据写入 `DICT_DATA` 后通知订阅方。
+
+## 管理端变更后的推荐调用
+
+```ts
+import { loadCommonDictData, loadUnauthDictData } from '@/meta/index-dict'
+
+loadUnauthDictData()
+await loadCommonDictData(true)
+```
+
+## 常用导出
+
+`DICT_KEY`、`DICT_DATA`、`publicDictsReady`、`getDictOptions`、`getDictDefaultValue`、`loadUnauthDictData`、`loadCommonDictData`、注册 notifier 等——以 `index-dict.ts` 的 `export { … } from './module/dict-data/runtime'` 为准。
+
+## 类型
+
+- **`DictAccessKey`**：各 `constKey` 联合
+- **`DictCategoryCode`**：`unauthDictRegistry` / `commonDictRegistry` 的 key
+
+---
+
+*最后更新：2026-04-17*

package/src/_doc/router/0.docs-overview.md

@@ -0,0 +1,14 @@
+# 路由与菜单文档总览
+
+本目录包含路由自动注册和菜单组件配置的相关文档。
+
+## 文档列表
+
+1. [菜单组件配置指南](./guide.1.menu-component-config.md) - 解决组件未找到的警告问题
+2. [动态路由自动注册功能](./guide.2.router-auto-registration.md) - submit.tsx 和 detail.tsx 的自动扫描与注册
+
+## 相关代码
+
+- 路由配置：`src/router/index.tsx`
+- 菜单路由注册：`src/utils/menuRouteRegistry.ts`
+- 侧边栏组件：`src/components/layout/components/Sidebar.tsx`

package/src/_doc/router/guide.1.menu-component-config.md

@@ -0,0 +1,181 @@
+# 菜单组件配置指南
+
+## 问题说明
+
+如果你在控制台看到类似以下的警告：
+
+```
+[Router] 组件未找到: /page-menus/business-rules/index, 尝试路径: /page-menus/business-rules
+[Router] 组件未找到: /, 尝试路径: /
+```
+
+这是因为后台菜单配置中的 `component` 字段值不正确或对应的组件文件不存在。
+
+## 解决方案
+
+### 1. 检查后台菜单配置
+
+登录后台管理系统，检查菜单管理中的配置：
+
+**错误的配置示例：**
+```json
+{
+  "component": "/page-menus/business-rules/index",  // ❌ 前导斜杠和 /index 后缀
+  "path": "/business-rules"
+}
+```
+
+**正确的配置示例：**
+```json
+{
+  "component": "page-menus/knowledge",  // ✅ 不带前导斜杠，不带 /index
+  "path": "/menus/knowledge"
+}
+```
+
+### 2. Component 字段规范
+
+Component 字段应该遵循以下规则：
+
+| 规则 | 说明 | 示例 |
+|------|------|------|
+| ✅ 不带前导斜杠 | 不要以 `/` 开头 | `page-menus/knowledge` |
+| ✅ 不带 /index 后缀 | 系统会自动查找 index.tsx | `page-menus/knowledge` |
+| ✅ 相对于 pages 目录 | 从 `src/pages/` 开始的路径 | `page-system/role` |
+| ❌ 不要使用特殊值 | 避免使用 `/`, `Main`, `Root` 等 | - |
+
+### 3. 文件结构对应关系
+
+```
+src/pages/
+├── page-menus/
+│   ├── knowledge/
+│   │   ├── index.tsx      ← component: "page-menus/knowledge"
+│   │   ├── detail.tsx     ← 自动注册为 "page-menus/knowledge/detail"
+│   │   └── submit.tsx     ← 自动注册为 "page-menus/knowledge/submit"
+│   └── feedback/
+│       └── index.tsx      ← component: "page-menus/feedback"
+└── page-system/
+    ├── role/
+    │   └── index.tsx      ← component: "page-system/role"
+    └── user/
+        └── index.tsx      ← component: "page-system/user"
+```
+
+### 4. 特殊菜单项处理
+
+对于不需要跳转的菜单项（如父级菜单），应该设置：
+
+```json
+{
+  "component": "Main",     // 或 "Root"
+  "path": "/",
+  "children": [...]
+}
+```
+
+系统会自动跳过这些菜单项，不会尝试加载组件。
+
+### 5. 调试方法
+
+在开发环境下，系统会打印所有已注册的组件路径：
+
+```javascript
+[Router] Registered components: [
+  "/page-menus/feedback",
+  "/page-menus/knowledge",
+  "/page-menus/knowledge/detail",
+  "/page-system/role",
+  "/page-system/user",
+  ...
+]
+```
+
+你可以通过这个列表来确认：
+1. 哪些组件已被正确注册
+2. 菜单配置中的 component 字段应该使用什么值
+
+### 6. 常见问题
+
+#### Q1: 为什么会有 `/` 这样的路径？
+
+A: 这通常是因为菜单配置中某个父级菜单的 component 字段设置为 `/`。应该改为 `Main` 或留空。
+
+#### Q2: 新增了页面文件但路由不生效？
+
+A: 
+1. 确保文件命名正确（index.tsx、submit.tsx、detail.tsx）
+2. 确保文件在正确的目录下
+3. 重启开发服务器（Vite 需要重新扫描 glob）
+4. 检查控制台输出的已注册组件列表
+
+#### Q3: 如何查看当前注册了哪些组件？
+
+A: 打开浏览器控制台，在开发环境下会看到：
+```
+[Router] Registered components: [...]
+```
+
+或者在代码中添加：
+```javascript
+console.log(Object.keys(componentMap).sort())
+```
+
+### 7. 修复步骤
+
+如果遇到"组件未找到"的警告：
+
+1. **确认文件存在**
+   ```bash
+   # 检查文件是否存在
+   ls src/views/page-menus/business-rules/index.tsx
+   ```
+
+2. **如果文件不存在**
+   - 选项 A：创建对应的页面文件
+   - 选项 B：在后台菜单管理中删除或禁用该菜单项
+
+3. **如果文件存在但路径不对**
+   - 检查后台菜单配置中的 component 字段
+   - 确保与文件路径匹配（去掉前导斜杠和 /index）
+
+4. **重启开发服务器**
+   ```bash
+   npm run dev
+   ```
+
+## 示例：知识库模块
+
+**文件结构：**
+```
+src/pages/page-menus/knowledge/
+├── index.tsx      # 列表页
+├── detail.tsx     # 详情页（文档列表）
+└── modal/
+    ├── submit-modal.tsx
+    └── detail-modal.tsx
+```
+
+**后台菜单配置：**
+```json
+{
+  "id": 100,
+  "name": "知识库管理",
+  "path": "/menus/knowledge",
+  "component": "page-menus/knowledge",  // ✅ 正确
+  "icon": "BookOpen",
+  "sortOrder": 1
+}
+```
+
+**自动生成的路由：**
+- `/menus/knowledge` → index.tsx
+- `/menus/knowledge/detail/:id` → detail.tsx
+
+## 总结
+
+- ✅ Component 字段格式：`page-xxx/module-name`
+- ❌ 不要加前导斜杠：`/page-xxx/module-name`
+- ❌ 不要加 /index 后缀：`page-xxx/module-name/index`
+- 🔍 开发环境下会打印已注册的组件列表
+- 🔄 新增文件后需要重启开发服务器

package/src/_doc/router/guide.2.router-auto-registration.md

@@ -0,0 +1,114 @@
+# 动态路由自动注册功能
+
+## 功能说明
+
+在 `src/router/index.tsx` 中实现了自动扫描并注册 `submit.tsx` 和 `detail.tsx` 页面的功能。
+
+## 实现原理
+
+### 1. 组件扫描与注册
+
+系统会自动扫描以下三种页面文件：
+- `pages/**/index.tsx` - 列表页（主页面）
+- `pages/**/submit.tsx` - 新增/编辑页
+- `pages/**/detail.tsx` - 详情页
+
+扫描后的组件会被注册到 `componentMap` 中，路径规则如下：
+- `/page-system/role` → 对应 `pages/page-system/role/index.tsx`
+- `/page-system/role/submit` → 对应 `pages/page-system/role/submit.tsx`
+- `/page-system/role/detail` → 对应 `pages/page-system/role/detail.tsx`
+
+### 2. 路由自动生成
+
+在 `generateAdminRoutes` 函数中，对于每个菜单项：
+1. 首先注册主路由（index）
+2. 如果存在对应的 submit.tsx，自动注册：
+   - `/{path}/submit` - 新增页面
+   - `/{path}/submit/:id` - 编辑页面（带 ID 参数）
+3. 如果存在对应的 detail.tsx，自动注册：
+   - `/{path}/detail/:id` - 详情页面（必须带 ID 参数）
+
+## 使用方式
+
+### 场景 1：submitType 为 'page'
+
+当在 `createListPageConfig` 中配置 `submitType: 'page'` 时：
+
+```typescript
+const useListPageConfig = createListPageConfig({
+  // ... 其他配置
+  submitAction: {
+    permission: 'knowledge:create',
+    submitType: 'page',  // 使用页面跳转方式
+    labelKey: 'knowledge.add',
+  },
+})
+```
+
+点击"新增"按钮时，会自动跳转到 `/{path}/submit` 页面。
+
+### 场景 2：detailType 为 'page'
+
+当配置 `detailType: 'page'` 时：
+
+```typescript
+const useListPageConfig = createListPageConfig({
+  // ... 其他配置
+  detailAction: {
+    detailType: 'page',  // 使用页面跳转方式
+    labelKey: 'common.view',
+  },
+})
+```
+
+点击"查看"按钮时，会自动跳转到 `/{path}/detail/:id` 页面。
+
+### 场景 3：手动 URL 跳转
+
+也可以直接使用 URL 进行跳转：
+
+```typescript
+// 跳转到新增页面
+window.location.href = '/menus/knowledge/submit'
+
+// 跳转到编辑页面
+window.location.href = `/menus/knowledge/submit/${id}`
+
+// 跳转到详情页面（必须带 ID）
+window.location.href = `/menus/knowledge/detail/${id}`
+```
+
+## 示例：知识库管理模块
+
+以知识库管理为例：
+
+**文件结构：**
+```
+src/pages/page-menus/knowledge/
+├── index.tsx          # 知识库列表页
+├── detail.tsx         # 知识库文档列表页（详情页）
+└── modal/
+    ├── submit-modal.tsx
+    └── detail-modal.tsx
+```
+
+**自动生成的路由：**
+- `/menus/knowledge` → 知识库列表页（index.tsx）
+- `/menus/knowledge/submit` → 新增知识库
+- `/menus/knowledge/submit/:id` → 编辑知识库（带 ID 参数）
+- `/menus/knowledge/detail/:id` → 知识库文档列表（带 knowledgeId 参数）
+
+## 注意事项
+
+1. **文件命名规范**：必须使用 `index.tsx`、`submit.tsx`、`detail.tsx` 作为文件名
+2. **目录结构**：这些文件应该在同一目录下
+3. **组件导出**：每个文件必须使用 `export default` 导出 React 组件
+4. **路由参数**：如果需要传递 ID，使用 `useParams` hook 获取
+5. **权限控制**：路由本身不做权限控制，需要在页面内部通过 `useAuth` 检查权限
+
+## 优势
+
+1. **自动化**：无需手动配置路由，系统自动扫描注册
+2. **一致性**：所有模块遵循相同的路由规则
+3. **灵活性**：支持弹框和页面两种交互方式
+4. **易维护**：新增模块只需创建对应文件，无需修改路由配置

package/src/_doc/table-view/0.docs-overview.md

@@ -0,0 +1,30 @@
+# table-view 文档总览
+
+> 本目录说明 **`src/components/table-view/`** 模块（`ListPageView`、`SelectTableView`、`createListPageConfig`、`createSelectTableConfig` 等）。文档物理路径：`src/_doc/table-view/`。单文件命名：`类型.序号.主题.md`。
+
+## 命名规则
+
+- `0.*.md`：总入口/导航文档
+- `comp.N.*.md`：**模块/组件**总体说明（架构、职责、协作方式）
+- `props.N.*.md`：**配置项、参数字典**（如 `createListPageConfig`、`searchFields` 的字段说明）
+- `examples.N.*.md`：示例与最佳实践文档（预留）
+
+## 当前文档
+
+- `comp.1.table-view.md`：目录结构、`ListPageView` / `SelectTableView` 职责与协作方式
+- `props.1.create-table-view-config.md`：`createListPageConfig` / `createSelectTableConfig` 参数与扩展点
+- `props.2.table-view-search-fields.md`：`searchFields` 配置与参数映射
+
+## 阅读建议
+
+1. 先阅读 `comp.1.table-view.md` 了解整体架构
+2. 再阅读 `props.1.create-table-view-config.md` 了解配置工厂
+3. 最后阅读 `props.2.table-view-search-fields.md` 关注筛选配置细节
+
+列表拉取成功后的扩展点 **`afterGetPageData`** 见 `props.1.create-table-view-config.md` §4.4。
+
+## 关联
+
+- 弹窗基座见 `../cx-ui/comp.2.cx-modal.md`
+- 列表空状态见 `../cx-ui/comp.7.cx-empty-state.md`
+- 全局索引见 [`../0.docs-overview.md`](../0.docs-overview.md)；`@/meta` 字典/枚举见 [`../meta/0.docs-overview.md`](../meta/0.docs-overview.md)