# 数据操作指南

数据操作流程完整链路：**周报生成 → 信息抽取 → 客户校验与录入 → 商机任务创建**。

---

## 1. 周报生成

Agent 调用 Python 脚本生成一份随机模拟周报，内部数据填充逻辑对 Agent 透明。

```bash
# 从 SKILL 根目录执行
/tmp/ont_env/bin/python scripts/weekly-report/generate_weekly_report.py
```

**可选参数**：

| 参数 | 说明 | 示例 |
|------|------|------|
| `--output json` | 输出 JSON 格式（含结构化字段） | `--output json` |
| `--seed <int>` | 指定随机种子，可复现结果 | `--seed 42` |

Agent 拿到周报文本后进入下一步：信息抽取。

---

## 2. 信息抽取

Agent 从周报文本中按字段位置提取结构化信息。

### 2.1 抽取字段

| 分类 | 字段 |
|------|------|
| 客户 | 客户编码、客户名称、所属行业、所属省份、所属城市、所属领域、所属销售用户编码、所属销售姓名、所属组织名称 |
| 商机 | 商机编码、商机名称、商机状态、预测金额、计划签约日期、所属产品编码 |

### 2.2 周报格式字段映射

Agent 按以下位置从周报文本中定位各字段：

```
一、拜访概况
● 拜访客户：{客户名称}
● 拜访人员：{所属销售姓名}（所属销售用户编码：{所属销售用户编码}）
● 所属组织：{所属组织名称}（组织编码：{组织编码}）

二、客户基础信息
客户编码
{客户编码}
所属行业
{所属行业}
所属省份
{所属省份}
所属城市
{所属城市}
所属领域
{所属领域}

三、商机详情
商机编码
{商机编码}
商机名称
{商机名称}
商机状态
{商机状态码}（{商机状态名}）
预测金额
{预测金额} 元
计划签约日期
{计划签约日期}
```

### 2.3 输出格式

抽取结果以表格形式呈现：

| 客户编码 | 客户名称 | 所属行业 | 所属省份 | 所属城市 | 所属领域 | 所属销售用户编码 | 所属销售姓名 | 所属组织名称 |
|----------|----------|----------|----------|----------|----------|------------------|--------------|--------------|
| CUST100001 | 北京国投中债资产管理有限公司 | 金融 | 北京 | 北京 | 1 | 0027024630 | 黄药师 | 华北-金融组 |

| 商机编码 | 商机名称 | 商机状态 | 预测金额 | 计划签约日期 | 所属产品编码 |
|----------|----------|----------|----------|--------------|--------------|
| OPP03000001 | 数据工厂-项目 | 1（线索获取） | 500,000.00 | 2026-05-01 | WHALE_DF |

### 2.4 新客户 vs 已有客户判断

抽取完成后，Agent 需要判断客户是否已在系统中存在：

| 周报提供的信息 | 判断逻辑 | 处理方式 |
|---------------|---------|---------|
| 提供客户编码 + 客户名称 | 查询系统是否有该编码，且名称匹配 | 匹配 → 已有客户，更新即可；不匹配 → 新客户（编码可能属于其他客户） |
| 只提供客户名称，无编码 | 查询系统是否有同名客户 | 有 → 已有客户；无 → 新客户 |
| 客户编码标注"系统已有"但实际查询不到 | 视为无效编码 | 按新客户处理，分配新编码 |

---

## 3. 客户校验与录入

### 3.1 校验规则

录入前必须校验以下内容：

| 校验项 | 规则 | 示例 |
|--------|------|------|
| 编码与名称匹配 | 周报中的客户编码若查到的名称与周报中不同，说明编码属于另一客户 | 周报编码 CUST000001 查出来是北京公司，但周报客户名是广州公司 → 编码不匹配，需分配新编码 |
| 省份编码纠错 | 周报中省份若为数字编码格式（如 `11（北京）`），需去掉编码只保留城市名 | `11（北京）` → 省份 `北京`；若客户名以城市前缀开头但与省份冲突，以客户名为准 |
| 城市一致性 | 城市名与省份必须匹配，以客户名为准判断 | 客户名为"广州XX公司"但省份标"北京" → 纠正省份为"广东"、城市为"广州" |

### 3.2 预览确认

校验修正后，Agent 以表格展示待录入信息，等待用户确认：

```
【待录入客户信息】

| 字段 | 值 | 备注 |
|------|-----|------|
| 客户编码 | CUST100001 | 新编码（周报中 CUST000001 为其他客户） |
| 客户名称 | 广州国投中债资产管理有限公司 | |
| 所属行业 | 金融 | |
| 所属省份 | 广东 | 已纠正（周报中为 "11（北京）"，以客户名"广州"为准） |
| 所属城市 | 广州 | |
| 所属领域 | 1 | |
| 所属销售用户编码 | 0027024630 | |
| 所属销售姓名 | 黄药师 | |
| 所属组织名称 | 华北-金融组 | |

是否确认录入？
```

### 3.3 执行录入

用户确认后，Agent 通过 `baiying_call` 新增客户数据：
- 先执行 `list_mounted_resources.py` 查询"客户"获取 `by_customer` 的 numeric `resource_id`
- 调用 `baiying_call`，resource_type=`OBJECT`，resource_id=上一步获取的 ID

**录入模式**：确认后执行（confirm-then-execute），任何数据操作类 API 在执行前必须经用户二次确认。

---

## 4. 商机任务创建

客户录入完成后，通过 `baiying_call` 创建商机待办任务。

### 4.1 创建待办任务

- 先执行 `list_mounted_resources.py` 查询"任务"获取 `by_opp_task` 的 numeric `resource_id`
- 调用 `baiying_call`，resource_type=`OBJECT`，resource_id=上一步获取的 ID
- query 描述：任务标题、执行人、截止日期、关联客户和商机信息

### 4.2 任务内容字段

| 字段 | 值 | 说明 |
|------|-----|------|
| 任务标题 | 拜访客户落地合同推进 | 固定模板 |
| 所属客户 | {客户名称} | 从抽取结果填入 |
| 负责销售 | {销售姓名}（{用户编码}） | 从抽取结果填入 |
| 截止时间 | 本月底 | 动态计算 |
| 任务描述 | 拜访客户，推进合同签订，落地 {产品名称} 项目 | 产品名从商机所属产品编码获取 |

---

## 执行顺序总结

1. **周报生成** — `generate_weekly_report.py` 输出随机周报文本
2. **信息抽取** — Agent 按字段映射从文本中解析客户和商机信息
3. **客户校验** — 检查编码匹配性、纠正省份/城市错误
4. **预览确认** — 表格展示待录入数据，等待用户确认
5. **客户录入** — 用户确认后通过 `baiying_call`（resource_type=OBJECT）写入
6. **任务创建** — 通过 `baiying_call`（resource_type=OBJECT）创建商机待办任务
