# 泛微商务合同查询与搜索字段

- `archive-oa.contract.list`：查询泛微商务合同列表。
- `archive-oa.contract.fields`：查询可搜索字段配置（构造搜索条件时用）。

## 命令

Windows PowerShell：

```powershell
weaver-work-cli archive-oa contract fields
weaver-work-cli --json archive-oa run archive-oa.contract.list --input-json '{"pageNo":1,"fields":[{"field":"hth","value":"PLACEHOLDER_CONTRACT_NO"}]}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli archive-oa contract fields
weaver-work-cli --json archive-oa run archive-oa.contract.list --input-json '{"pageNo":1,"fields":[{"field":"hth","value":"PLACEHOLDER_CONTRACT_NO"}]}'
```

## 输入（`archive-oa.contract.list`）

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNo` | integer | 否 | 页码，从 1 开始，缺省 1 |
| `fields` | array | 否 | 搜索条件数组，元素 `{ field, conditionType, value }` |
| `matchType` | string | 否 | `and`（默认）或 `or`；源资料约定默认「且」 |

`conditionType` 取值：

| 取值 | value 形态 | 用途 |
| --- | --- | --- |
| `like`（缺省） | 字符串 | 模糊匹配，如合同号、客户名称、合同类型 |
| `between` | `{min,max}` 或 `[起,止]` | 金额区间（`htzje`，单位元、字符串数字）、日期区间（`qdrq` / `ysrq`） |
| `in` | 数组 | 复选框多选，如 `sfxc`、`hsgs` |
| `inC` | 数组 | 浏览按钮/下拉多选，如 `zxfa`（合同专项模块）、`tjry`（提交人） |

常用字段：`hth`（合同号）、`khmc`（签约方）、`zzyhmc`（最终客户名称）、`htmc`（合同名称）、`htlx`（合同类型）、`qdrq`（签订日期）、`ysrq`（验收日期）、`htzje`（合同总金额）、`zxfa`（合同专项模块）。字段名不确定时先跑 `archive-oa.contract.fields`。

### 合同专项模块（`zxfa`）

用 `inC` + 对象数组，不要用 `like` 或字符串：文书定-档案管理、齐业成-费控管理等专项模块按浏览按钮取值传入。

## 输出处理

- 行数据在 `rows`（`data[*]`），列定义在 `meta.columns`（`title` ↔ `dataIndex`）。
- `rows[].id` 是合同数据行的内部 ID，**静默缓存**供 `archive-oa.borrow-car.add.prepare` 的 `dataIds` 使用，不展示给最终用户。
- **展示列固定为 11 列**（与系统列表页一致，其余字段一律不展示）：合同号 `hth`、签约方 `khmc`、最终客户名称 `zzyhmc`、合同名称 `htmc`、提交人 `tjry`（数组取 `name`，多人用「、」连接）、合同类型 `htlx`、签订日期 `qdrq`、验收日期 `ysrq`、产品版本号 `cpbbh`（数组取 `name`）、是否有发票 `sfyfp`（数组取 `name`，值即「有」/「没有」）、是否有回单 `someyhhd`（扁平字符串，**空值按「没有」展示**）。
- 后三列（`cpbbh` / `sfyfp` / `someyhhd`）**仅泛微商务合同返回**；契约锁协作采纳不返回这三个字段，契约锁仍按其固定 8 列展示，不得套用泛微这 3 列。
- **其余字段（`byx`、`daxtbs`、`ebrecord_rowkey`、`form_data_id`、`id`、`isFollow`、`sfyhd`、`somefph`、`unique_key`、`ysd`、`zbgg`、`zbtzs`）一律不展示**，即使接口返回了也不要追加到表格里；`id` 等内部标识只作 `dataIds` 入参使用。
- 响应 `total=0` 但 `rows` 非空属于正常现象，不要据此判定为无数据。
- **禁止翻页**：只查询 `pageNo=1`，**不得请求 `pageNo≥2`**、不做循环翻页累加；单次最多展示 20 条。命中超过 20 条时说明总数，并提示用户缩小筛选条件（签订日期 / 客户类型 / 签约方关键词），**不得通过翻页获取更多数据**。
- 结果默认用 Markdown 表格输出（第一列「序号」从 1 递增，分隔行 `| :---: |` 居中）。

## 失败处理

| 场景 | 处理 |
| --- | --- |
| `authentication` / `session_expired` | 停止并让用户重新登录 |
| `enum_invalid`（`matchType` 非法） | 改为 `and` / `or` |
| `search_value_invalid` | 检查 `between` 是否为 `{min,max}` 或二元数组、`in`/`inC` 是否为数组 |
| 字段不存在导致查不到数据 | 用 `archive-oa.contract.fields` 核对字段名后重试，不要猜测字段 |