<div align="center">
  <img src="https://img.alicdn.com/imgextra/i3/O1CN01X7B4kK1YXeKtEDpBZ_!!6000000003069-2-tps-720-720.png" align="center" width="100px">
  <h2> cn-domain-ai-table </h2>
  <h4>菜鸟前端 AI 表格业务组件｜<a href="https://cone.cainiao-inc.com/dsm/cnui/material/pc/overview">cn-ui 文档</a></h4>
</div>

<div style="font-size: 14px">
  <a href="#快速开始">快速开始</a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="#组件-api">组件 API</a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="#主题定制">主题定制</a>
</div>

---

<span id="快速开始"/>

## 快速开始

### 安装

```bash
npm install @cainiaofe/cn-domain-ai-table
```

### 基础用法

```tsx
import { CnAiTable, ConfigProvider } from '@cainiaofe/cn-domain-ai-table';
import '@cainiaofe/cn-domain-ai-table/style.css';

function App() {
  return (
    <ConfigProvider>
      <CnAiTable id="my-table" columns={columns} remote={{ url: '/api/list' }} />
    </ConfigProvider>
  );
}
```

### 对等依赖

请确保安装以下对等依赖：

- `react` / `react-dom`（^16.8.0 || ^18.3.0）
- `@cainiaofe/cn-ui` (^0.12.59)

---

<span id="组件-api"/>

## 组件 API

### CnAiTable

AI 驱动的多视图表格组件，支持表格、任务、智能跟单等多种视图类型。

#### 基础属性

| 属性            | 类型                 | 必填 | 说明                                 |
| --------------- | -------------------- | :--: | ------------------------------------ |
| `id`            | `string`             |  是  | 表格唯一标识，视图持久化依赖此值     |
| `columns`       | `ColumnDefinition[]` |  是  | 列定义数组                           |
| `remote`        | `{ url: string }`    |  是  | 数据源配置（CnTable.useRemote 风格） |
| `operateColumn` | `object`             |  否  | 操作列配置                           |

#### 字段配置

| 属性                | 类型                                | 默认值 | 说明                                 |
| ------------------- | ----------------------------------- | ------ | ------------------------------------ |
| `enabledFieldTypes` | `('ai' \| 'lookup' \| 'formula')[]` | `[]`   | 启用的自定义字段类型                 |
| `fieldTypeOptions`  | `object`                            | —      | 字段类型高级选项（如 lookup 的回调） |

```tsx
// 启用全部字段类型
<CnAiTable
  enabledFieldTypes={['ai', 'lookup', 'formula']}
  fieldTypeOptions={{
    lookup: {
      hiddenSubTable: true,
      addFieldCallback: async (params) => {
        /* ... */
      },
      deleteFieldCallback: async (params) => {
        /* ... */
      },
    },
  }}
/>
```

#### 视图配置 `viewTypes`

控制可用视图及视图内功能开关：

| 视图          | 默认状态 | 说明                               |
| ------------- | -------- | ---------------------------------- |
| `grid`        | 始终启用 | 表格视图，不可关闭，可配置 toolbar |
| `task`        | 启用     | 任务视图，`false` 关闭             |
| `smartFollow` | 关闭     | 智能跟单视图，`true` 启用          |

```tsx
<CnAiTable
  viewTypes={{
    grid: {
      toolbar: {
        fieldManagement: true,
        filter: true,
        sort: true,
        group: true,
        colorFill: true,
      },
    },
    task: { enableSummary: false, toolbar: false },
    smartFollow: { enableDetailSummary: true },
  }}
/>
```

#### 列宽自动计算

| 属性                  | 类型      | 默认值 | 说明             |
| --------------------- | --------- | ------ | ---------------- |
| `columnsAutoWidth`    | `boolean` | `true` | 是否自动计算列宽 |
| `columnsAutoWidthOpt` | `object`  | —      | 列宽调优参数     |

```tsx
// 限制最大列宽并优化大数据量性能
<CnAiTable columnsAutoWidthOpt={{ maxWidth: 360, sampleRate: 0.2 }} />
```

`columnsAutoWidthOpt` 推荐参数：

| 参数                 | 类型      | 默认值 | 说明                                         |
| -------------------- | --------- | ------ | -------------------------------------------- |
| `maxWidth`           | `number`  | `460`  | 单列最大宽度                                 |
| `sampleRate`         | `number`  | 自适应 | 行采样率（0~1），数据 > 200 行时自动降为 0.3 |
| `fillContainerWidth` | `boolean` | `true` | 是否将剩余空间分配给可伸缩列                 |

#### 业务请求配置 `bizRequestConfig`

通过 `bizRequestConfig` 自定义各能力的接口地址：

```tsx
<CnAiTable
  id="my-table"
  bizRequestConfig={{
    cubePlatform: {
      getListRequestConfig: {
        url: 'https://your-domain/api/views/getList',
        data: { pageId: 'xxx', appCode: 'xxx', userId: 'current-user' },
      },
      createOrUpdateRequestConfig: {
        url: 'https://your-domain/api/views/createOrUpdate',
        data: { pageId: 'xxx', appCode: 'xxx', userId: 'current-user' },
      },
    },
    subTableConfig: {
      url: '/api/sub-table/config',
      method: 'POST',
      data: { tableId: 'xxx' },
    },
    aiColumn: {
      queryTableTasksUrl: 'https://your-domain/api/ai/tasks',
      submitTasksUrl: 'https://your-domain/api/ai/submit',
    },
    smartFollow: {
      queryTasksUrl: 'https://your-domain/api/follow/tasks',
    },
    agent: {
      queryResponseUrl: 'https://your-domain/api/agent/query',
    },
  }}
/>
```

可配置的子项：

| 子项             | 说明                                     |
| ---------------- | ---------------------------------------- |
| `cubePlatform`   | 视图持久化（getList / createOrUpdate）   |
| `subTableConfig` | 引用字段子表配置接口                     |
| `aiColumn`       | AI 字段相关接口（提交/轮询/预览/删除等） |
| `smartFollow`    | 智能跟单接口                             |
| `agent`          | AI 助理接口                              |

> 未配置的项走组件内置默认逻辑，建议逐项替换，优先替换只读接口。

### CnAiFilter

AI 智能筛选组件，支持自然语言转结构化查询条件。

```tsx
<CnAiFilter
  bizRequestConfig={{
    filter: {
      fieldTransformUrl: '/api/filter/transform',
      suggestionUrl: '/api/filter/suggestions',
    },
  }}
/>
```

### CnAiAgent

AI 助理组件，提供对话式交互能力。

```tsx
<CnAiAgent
  bizRequestConfig={{
    agent: {
      submitPromptUrl: '/api/agent/submit',
      queryResponseUrl: '/api/agent/query',
    },
  }}
/>
```

---

### 视图持久化

通过 `bizRequestConfig.cubePlatform` 对接业务后端，实现视图配置的保存与恢复。

**接口协议：**

- `getList`：页面加载时拉取已保存的视图配置
- `createOrUpdate`：用户操作视图后自动触发保存

**`data` 参数说明：**

| 参数      | 必填 | 说明                                      |
| --------- | :--: | ----------------------------------------- |
| `pageId`  |  是  | 页面唯一标识，隔离不同页面的视图配置      |
| `appCode` |  否  | 应用编码，多应用共用后端时需传            |
| `userId`  |  否  | 当前用户 ID，不传则所有用户共享同一份视图 |

> 完整接口协议文档见 [docs/view-config-api-spec.md](./docs/view-config-api-spec.md)。

---

<span id="主题定制"/>

## 主题定制

### 快速上手

通过 `ConfigProvider` 组件覆盖主题 Token 和视觉资产：

```tsx
import { ConfigProvider } from '@cainiaofe/cn-domain-ai-table';

<ConfigProvider
  theme={{
    token: {
      'cnai-color-brand-primary': '#ff6a00',
      'cnai-gradient-brand': 'linear-gradient(135deg, #ff9500 36%, #ff6a00 96%)',
      'cnai-agent-bubble-user-bg': '#fff3e6',
    },
    components: {
      agent: { avatarUrl: 'https://my-cdn.com/avatar.png' },
      filter: { sendButtonIconUrl: 'https://my-cdn.com/search.png' },
    },
  }}
>
  <CnAiAgent />
  <CnAiFilter />
  <CnAiTable />
</ConfigProvider>;
```

### ThemeConfig API

| 属性         | 类型                               | 说明                                                  |
| ------------ | ---------------------------------- | ----------------------------------------------------- |
| `token`      | `Record<string, string \| number>` | CSS Token 覆盖映射，key 为 token 名（不含 `--` 前缀） |
| `components` | `{ agent?, filter?, table? }`      | 主题视觉资产覆盖（按组件维度）                        |

### Hooks

| Hook               | 返回类型          | 说明                                         |
| ------------------ | ----------------- | -------------------------------------------- |
| `useTheme()`       | `ThemeConfig`     | 获取当前作用域的主题配置                     |
| `useBrandAssets()` | `BrandAssetGroup` | 获取当前作用域的主题资产（已与默认资产合并） |

请使用主题配置Skill进行操作

## 公式字段

CnAiTable 支持类 Excel 的公式字段，用户可基于已有字段值进行自动计算。

### 启用

```tsx
<CnAiTable enabledFieldTypes={['formula']} />
```

### 支持的函数

| 分类 | 函数                                                                                                 |
| ---- | ---------------------------------------------------------------------------------------------------- |
| 数学 | `SUM`, `AVERAGE`, `MAX`, `MIN`, `COUNT`, `ABS`, `ROUND`, `CEILING`, `FLOOR`, `MOD`, `POWER`, `FIXED` |
| 逻辑 | `IF`, `TRUE`, `FALSE`                                                                                |
| 时间 | `TODAY`, `YEAR`, `MONTH`, `HOUR`, `MINUTE`, `DAYS`                                                   |
| 文本 | `CONCATENATE`, `LEFT`, `RIGHT`, `MID`, `REPLACE`, `REPT`                                             |

### 运算符

支持标准算术和比较运算符：`+` `-` `*` `/` `%` `==` `!=` `>` `<` `>=` `<=`

```
ROUND({单价} * {数量} * 0.9, 2)
```

> 完整使用指南见 [docs/字段使用指南/公式字段使用方式.md](./docs/字段使用指南/公式字段使用方式.md)。

---

### npm 消费（ESM / CJS）

```bash
npm install @cainiaofe/cn-domain-ai-table
```

```tsx
import { CnAiTable, CnAiFilter, CnAiAgent, ConfigProvider } from '@cainiaofe/cn-domain-ai-table';
import '@cainiaofe/cn-domain-ai-table/style.css';
```

对等依赖：`react`、`react-dom`、`@cainiaofe/cn-ui`。

---

<span id="常见问题"/>
