# 按合同号定位档案

`archive-oa.archive.locate`：按合同号在档案系统定位档案记录，返回档案记录 ID / 题名 / 合同号。

## 命令

Windows PowerShell：

```powershell
weaver-work-cli --json archive-oa run archive-oa.archive.locate --input-json '{"contractNo":"PLACEHOLDER_CONTRACT_NO"}'
weaver-work-cli archive-oa locate --contract-no "PLACEHOLDER_CONTRACT_NO"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json archive-oa run archive-oa.archive.locate --input-json '{"contractNo":"PLACEHOLDER_CONTRACT_NO"}'
weaver-work-cli archive-oa locate --contract-no "PLACEHOLDER_CONTRACT_NO"
```

## 输入

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `contractNo` | string | 是 | 合同号，对应接口顶层 `htbh` |
| `pageNo` | integer | 否 | 页码，从 1 开始，缺省 1 |

## 接口契约要点

- 请求：`POST /api/ebuilder/form/formdata/v2/getFormDataList/getArcIdByContractNo`。
- 合同号**必须放在 body 顶层 `htbh`**；放进 `datajson.mainTable` 会被忽略并返回整表默认列表（发现结果里混入无关档案时按此排查）。
- 响应取 `datajson.datas[*].mainTable.{id, folder_title, hth}`；未命中时 `datas` 为空数组，业务状态仍为 `true`。

## 输出处理

- `rows[].id`：档案记录 ID，静默缓存供后续 operation 使用，**不要展示给最终用户**。
- `rows[].title` / `rows[].contractNo`：题名与合同号，可展示。
- `matched=false` 时提示未找到对应档案，不擅自改用其它合同号或改查其它链路。
- 命中多条时最多展示前 20 条；定位结果不做翻页。

## 失败处理

| 场景 | 处理 |
| --- | --- |
| `authentication` / `session_expired` | 停止，按共享规则让用户重新登录后再继续 |
| 接口未发布（`datajson.status=false`、`接口标识不存在`） | 提示联系管理员发布 `getArcIdByContractNo`，不切换到其它接口 |
| `contractNo` 为空 | 先向用户要合同号，不要猜测 |

档案操作/利用记录（借阅、下载、浏览日志）接口尚未收录，拿到 `id` 后不要声称可以查询这些记录。