lead-storage

在 Supervisor 提供明确确认后，通过只写存储操作保留已验证的主导对象。当用户要求将批准的潜在客户保存到 Google 表格或数据库时使用，包括规范化位置和优先级字段。推荐链端：主管确认后引导入库。请勿用于解析、提取、分析或操作推荐。

# Lead Storage

Store validated leads with strict confirmation gating.

## Quick Triggers

- Save approved leads to Google Sheets.
- Persist these normalized records after confirmation.
- Commit validated leads with confirmation token.

## Recommended Chain

`... -> supervisor confirmation -> lead-storage`

## Execute Workflow

1. Accept payload from Supervisor.
2. Validate payload with `references/storage-input.schema.json`.
3. Verify `confirmation_token` is present and non-empty.
4. Write leads to storage through write-only interfaces.
5. Preserve optional extraction/normalization/scoring metadata when present:
   - extraction: `deal_type`, `asset_class`, `price_basis`, `area_sqft`, `area_basis`
   - record typing: `dataset_mode`, `record_type`
   - location: `city`, `city_canonical`, `locality_canonical`, `micro_market`, `location_hint`
   - prioritization: `urgency`, `priority_bucket`
6. Enforce idempotency by `lead_id` and avoid duplicate inserts for repeated broker forwards.
7. Return result using `references/storage-output.schema.json`.
8. On partial failures, return `status: "failure"` and a populated `error_message`.

## Enforce Boundaries

- Never parse raw messages.
- Never extract new lead entities.
- Never perform read queries for analytics or summaries.
- Never generate suggested actions.
- Never write anything when confirmation token is missing or invalid.
- Never self-approve writes.

## Reliability Rules

1. Prefer idempotent writes keyed by `lead_id`.
2. Log rejected writes with validation reason.
3. Fail closed on any permission ambiguity.

---

## 中文说明

# 潜在客户存储（Lead Storage）

在严格的确认门控下存储已验证的潜在客户。

## 快速触发条件

- 将已批准的潜在客户保存到 Google Sheets。
- 在确认后持久化这些已规范化的记录。
- 凭确认令牌提交已验证的潜在客户。

## 推荐链

`... -> supervisor confirmation -> lead-storage`

## 执行工作流

1. 接收来自 Supervisor 的载荷。
2. 使用 `references/storage-input.schema.json` 校验载荷。
3. 验证 `confirmation_token` 存在且非空。
4. 通过只写接口将潜在客户写入存储。
5. 当可选的提取/规范化/评分元数据存在时予以保留：
   - 提取：`deal_type`、`asset_class`、`price_basis`、`area_sqft`、`area_basis`
   - 记录类型：`dataset_mode`、`record_type`
   - 位置：`city`、`city_canonical`、`locality_canonical`、`micro_market`、`location_hint`
   - 优先级：`urgency`、`priority_bucket`
6. 按 `lead_id` 强制保证幂等性，避免因经纪人重复转发而造成的重复插入。
7. 使用 `references/storage-output.schema.json` 返回结果。
8. 发生部分失败时，返回 `status: "failure"` 并填充 `error_message`。

## 强制边界

- 切勿解析原始消息。
- 切勿提取新的潜在客户实体。
- 切勿为分析或摘要执行读取查询。
- 切勿生成建议操作。
- 当确认令牌缺失或无效时，切勿写入任何内容。
- 切勿自行批准写入。

## 可靠性规则

1. 优先使用以 `lead_id` 为键的幂等写入。
2. 记录被拒绝的写入及其校验原因。
3. 在任何权限不明确的情况下采取失败关闭（fail closed）策略。