# Field Schema

## Encoding Safety for Text Fields

All text fields that may contain non-ASCII content must follow `references/encoding-and-excel-writeback.md`. This applies especially to notes, outreach status, follow-up status, customer attribute, customer type, business summary, and generated HTML preview labels.

- Do not construct Chinese note/status strings inside PowerShell inline Python commands. Use UTF-8 files, Unicode escapes, or shared UTF-8 scripts.
- After any workbook write-back, reopen the file and scan for repeated question marks.
- A write-back is not complete unless the verification report shows `question_mark_cells = 0`.
- If corrupted text is found, reconstruct from source JSON, send logs, or scrape records. Do not keep or manually edit around corrupted text.

## 工作簿优先级与空白模板

- 正常运行优先使用用户传入的 `--excel`。
- 未传 `--excel` 时，在当前项目目录和上级目录查找已有建联表，优先匹配 `摩洛哥客户建联表-按渠道分类.xlsx` 或同名带空格版本。
- 查找时必须排除 `~$`、`_backup_`、`backup_before`、`_with_`、`sent_`、`preview`、`candidate`、`filtered`、预览和临时工作簿。
- Skill 内置空白建联表模板：`assets/blank_customer_outreach_workbook.xlsx`。
- 模板由正式建联表 `摩洛哥客户建联表-按渠道分类.xlsx` 生成，保留当前 Sheet、表头、列宽、基础格式、`填写说明` 和 `附件`，清空所有客户数据行。
- 模板只在全新环境兜底使用：当项目目录没有建联表且用户明确写表时，先复制到运行目录，再写复制品。
- 禁止把客户数据、发送状态或采集结果写入 skill 内的模板文件。
- 预览模式不需要创建建联表；只有写表模式才允许自动复制空白模板。

## 字段口径

- `客户属性`：客户大类，只填写分类结果，例如 `汽车渠道合作伙伴`、`批量采购与运营客户`、`二手车转型候选`、`平台与行业渠道`、`生态支持资源`。
- `客户类型`：细分客户类型，例如 `汽车进口商`、`全国代理商`、`区域分销商`、`多品牌经销商`、`汽车交易平台`、`汽车租赁公司`、`实体二手车企业` 等。
- `主营业务`：客户实际经营内容和业务摘要，保持业务描述用途，不改名、不删除、不用于存放大类。
- `备注`：结构化证据、来源判断、批量采购潜力、风险和待确认项。

## 人工确认标记边界

以下内容是人工确认/风险标记，不是客户分类。禁止写入 `客户属性` 或 `客户类型`，只能写入候选预览 JSON 的 `risk_flags`、`备注` 或人工复核预览中：

- `主体归属待确认`：汽车渠道线索中，无法判断是独立公司，还是品牌官方主体、进口商直营网点或普通分店。
- `新车业务待确认`：汽车渠道线索中，无法判断主营新整车，还是二手车、维修、配件、轮胎等业务。
- `平台与行业渠道主体待确认`：平台与行业渠道线索中，无法确认是否为真实机构主体，还是普通个人页、内容号或非正式资源页。
- `平台与行业渠道作用待确认`：平台与行业渠道线索中，无法确认是否具备汽车行业资源、渠道引荐、媒体传播或行业活动组织作用。
- `仅电话/WhatsApp待人工确认`：线索已有目标价值信号，但只有电话或 WhatsApp，缺少官网、Facebook、LinkedIn、Google Maps 等可复核资料，需要人工联系确认主体和实际业务。
- `详细信息待确认`：当 AI 因登录限制、页面屏蔽、地区限制或网站无法访问，不能读取 Facebook、LinkedIn、官网等内容时填写。

客户分类仍必须严格保持五大客户属性和表内细分客户类型；不要用上述风险标记作为兜底分类值。

人工复核不是低质线索兜底池。只有已经显示出渠道价值、但缺少一个关键确认点的客户，才标记为需人工复核。

输出人工复核名单时，不要输出通用复核规则；只列出那些已经值得推进、但需要人工确认一个关键点的客户。低价值或无关客户应写为跳过/低优先级，不要包装成“建议人工复核”。

### 两段式人工复核标准

人工复核必须先看客户是否有目标价值，再看是否缺少需人工确认的关键点。只有两部分同时成立，才能列为需人工复核。

第一部分：客户属性信号至少满足其一。

- 汽车渠道合作伙伴信号：新车销售、汽车进口、分销、授权经销、汽车展厅、showroom、库存、dealer network 等。
- 平台与行业渠道信号：汽车协会、商会、汽车行业平台、汽车媒体、行业活动组织、车商联盟、经销商资源平台或引荐机构等。

第二部分：人工复核条件至少满足其一。

- 汽车渠道类：主体归属待确认，或新车业务待确认。
- 平台与行业渠道类：真实机构主体待确认，或汽车行业资源/渠道作用待确认。
- 只有电话或 WhatsApp：线索已有目标价值信号，但缺少官网、Facebook、LinkedIn、Google Maps 等可复核资料，需要人工联系确认其主体和实际业务。

不要把“只有电话/WhatsApp”单独作为人工复核理由。如果客户没有汽车渠道价值或平台行业价值，应跳过或标记低优先级，不列入人工复核名单。


- 可进入人工复核的前提：至少有一个明确正向价值信号，例如汽车渠道、进口/分销、多品牌、showroom/展厅、库存/stock、中国品牌经验、商用车/车队场景、平台/协会/商会资源或可建联入口。
- 人工复核的典型原因：看起来有渠道价值，但独立主体待确认、新整车业务待确认、或因页面/登录/地区限制导致详细信息无法读取。
- 不进入人工复核的情况：纯维修/配件/轮胎/保险/洗车、个人卖家、OEM 官方主页/当地分公司、无汽车渠道价值信号且无可建联入口的记录。这些应该跳过或标记低优先级，而不是写成“需人工复核”。

## 客户属性与细分类型

| 客户属性 | 细分客户类型 |
|---|---|
| `汽车渠道合作伙伴` | 汽车进口商、全国代理商、全国分销商、区域分销商、多品牌经销商、商用车渠道商、中国品牌经销商、新能源或小型车渠道商 |
| `批量采购与运营客户` | 汽车租赁公司、长期租赁公司、企业车队、物流配送企业、政府或机构采购方 |
| `二手车转型候选` | 连锁二手车企业、实体二手车企业、进口二手车企业、新车与二手车综合企业 |
| `平台与行业渠道` | 汽车交易平台、汽车协会、商会、车商联盟、经销商资源引荐机构 |
| `生态支持资源` | 售后服务网络、备件供应与仓储企业、进口认证与上牌机构、金融保险机构、车辆物流企业 |

分类优先级：先识别 `平台与行业渠道`，再识别更明确的 `批量采购与运营客户` 和 `二手车转型候选`，最后识别泛经销/进口/分销类的 `汽车渠道合作伙伴`。明显 `Occaz/occasion/二手` 的客户优先归为 `二手车转型候选`，除非证据显示其主要身份是汽车进口商或分销商。分类必须严格落入表内five customer attributes and matching subtypes；证据不足时必须继续用公开来源或 Playwright 浏览器补搜，不允许为了填满字段而默认塞进 `汽车渠道合作伙伴 / 多品牌经销商`。

汽车渠道合作伙伴的字段判定必须满足：有实际新整车销售或分销业务、可识别独立经营主体、存在新增品牌可能、具有可建联入口。纯维修/配件/轮胎/个人卖家不写入汽车渠道合作伙伴；纯租车公司写入 `批量采购与运营客户 / 汽车租赁公司`；独立单品牌新车经销商可保留，但 `备注` 必须写明 `排他协议及新增品牌权限待确认`。

## Sheets

| Sheet | Purpose | Notes |
|---|---|---|
| `客户信息汇总表` | Consolidated master customer table | Generated after platform searches; includes `客户属性` and `客户来源`. |
| `Facebook` | Facebook dealer and page collection | Standard columns plus optional `公司官网`. |
| `LinkedIn` | Company/person outreach collection | Supports old and normalized LinkedIn headers. |
| `Google Maps` | Google Maps local business collection | Supports public email extraction from merchant websites. |
| `TikTok` | TikTok account collection | Placeholder / reserved channel. |
| `测评博主` | Automotive KOLs | Reference channel, not priority dealer target. |
| `协会商会` | Associations and chambers | Platform and industry channel source. |
| `政府采购投标` | Government and tender channels | Reference channel. |
| `本地汽车网站` | Local vertical auto websites | Local auto website leads. |
| `汽车网站精选线索` | Curated local auto website leads | Standard fields plus `来源网站`. |
| `填写说明` | Field guidance | Reference only. |
| `附件` | Related links | Reference only. |

## Standard Columns

Standard sheets use:

`序号`, `客户姓名/公司`, `国家`, `城市`, `客户属性`, `客户类型`, `主页/链接`, `联系人`, `职位`, `电话/WhatsApp`, `邮箱`, `主营业务`, `建联状态`, `下次跟进`, `备注`

Meaning:

- `客户姓名/公司`: company, account, or person name.
- `国家`: target country, for example `摩洛哥`.
- `城市`: city or cities; use `摩洛哥全国` when the lead covers the whole country.
- `客户属性`: broad customer class.
- `客户类型`:細分客户类型；不要把长业务描述放这里。
- `主页/链接`: source URL from Facebook, TikTok, Google Maps, LinkedIn, or website.
- `邮箱`: only public, traceable email; do not guess.
- `主营业务`: Chinese business summary. Keep necessary professional terms such as showroom, importation, fleet, location, and vehicules neufs.
- `建联状态`: outreach status.
- `备注`: structured business notes, activity, brand signals, evidence, and risk notes.

## LinkedIn Columns

Preferred columns:

`公司名称`, `国家`, `城市`, `客户属性`, `客户类型`, `linkin链接`, `联系人`, `职位`, `公司公共电话`, `公司公共邮箱（任一有效即可）`, `个人邮箱（不一定有效）`, `公司主营业务`, `建联状态`, `备注`

Accepted aliases:

- Link: `linkin链接`, `linkin连接`, `LinkedIn链接`, `主页/链接`
- Attribute: `客户属性`, `客户大类`, `大类`
- Type: `客户类型`, `细分客户类型`
- Company phone: `公司公共电话`, `电话/WhatsApp`
- Company email: `公司公共邮箱（任一有效即可）`, `公司公共邮箱`, `公共邮箱`, `邮箱`
- Personal email: `个人邮箱（不一定有效）`, `个人邮箱`
- Business: `公司主营业务`, `主营业务`
- Status: `建联状态`, `建联情况`

Do not collapse company email and personal email when writing back to the LinkedIn sheet.

## Google Maps Columns

Google Maps uses:

`客户姓名/公司`, `国家`, `城市`, `客户属性`, `客户类型`, `主页/链接`, `联系人`, `职位`, `电话/WhatsApp`, `邮箱`, `主营业务`, `建联状态`, `下次跟进`, `备注`

Write the Google Maps place URL to `主页/链接`. Write only public emails found on Google Maps text, `mailto:` links, or the merchant website into `邮箱`. If no public email is found, leave `邮箱` blank and summarize `官网未发现公开邮箱` or `无官网，未发现公开邮箱` in `备注`.

## Local Auto Website Columns

`汽车网站精选线索` uses:

`序号`, `客户姓名/公司`, `国家`, `城市`, `客户属性`, `客户类型`, `主页/链接`, `来源网站`, `联系人`, `职位`, `电话/WhatsApp`, `邮箱`, `主营业务`, `建联状态`, `下次跟进`, `备注`

Rules:

- `来源网站` must name the evidence source, such as `OtoMoto.ma`, `Wandaloo`, `Kerix`, `Kompass`, `Maroc Annuaire`, or `Telecontact`.
- `主页/链接` should prefer the company website when known; otherwise use the source listing or directory URL.
- `邮箱` must come from public page text, `mailto:`, directory listing, or merchant website Contact/About pages.
- Duplicates are handled within this sheet by website, normalized company name, phone, email, or source-detail URL.
- `备注` must summarize source evidence, business type, batch purchase capacity, inventory/branch/rental/import signals, contact evidence, and risks.

## Customer Summary Sheet

`客户信息汇总表` 是搜索完成后的汇总 Sheet，不作为单个平台的原始写入目标。Facebook、LinkedIn、Google Maps、当地汽车网站、Moteur.ma、汽车网站精选线索、协会商会等渠道采集完成后，统一用 `scripts/common/build_customer_summary.py` 生成或覆盖。

Columns must exactly match the reference key-account workbook header:

`公司姓名`, `国家`, `城市`, `客户类型`, `官网链接`, `联系人`, `职位`, `个人邮箱`, `联系人电话`, `Facebook主页链接`, `linkined主页链接`, `google map链接`, `公共电话/WhatsApp`, `公共邮箱`, `客户属性`, `建联状态`, `下次跟进`, `备注`

Source mapping:

- `Facebook` Sheet -> `Facebook`
- `LinkedIn` Sheet -> `LinkedIn`
- `Google Maps` Sheet -> `Google Maps`
- `TikTok` Sheet -> `TikTok`
- `协会商会` Sheet -> `平台与行业渠道`
- `本地汽车网站` Sheet -> `当地汽车网站`
- `Sheet11` -> `Moteur.ma`
- `汽车网站精选线索` -> prefer row field `来源网站`; if empty, use `汽车网站精选线索`

Summary rules:

- Platform sheets are the source of truth. Do not write newly discovered leads directly to `客户信息汇总表` during browsing or scraping.
- Rebuild `客户信息汇总表` only after a platform search round is complete or when the user explicitly asks to refresh the master table.
- Merge duplicates first by public email, phone, normalized homepage/source link, and company website; then by conservative normalized company name.
- Keep Google Maps query/cid/place identifiers when normalizing links so different Maps businesses do not collapse into one row.
- Merge multiple contacts, positions, personal emails, public emails, contact phones, public phones, platform links, website links, and notes with `；` after de-duplication.
- Do not add separate `来源Sheet`, `客户来源`, `来源链接汇总`, or `重复来源数` columns to the master sheet when the user asks to follow the key-account reference format.
- Preserve source information inside `备注` in the format `合并来源数量：N；客户来源：...；来源Sheet：...；来自 <Sheet> row <n>`.
- `合并来源数量` must be computed from the number of merged source rows, never from the serial number or Excel row number.
- Merchant homepages are evidence fields, but should not be used alone as strong duplicate keys because group websites can represent multiple brands, branches, or dealer pages.

## Duplicate Handling Before Scraping

Before opening a Facebook homepage, LinkedIn About page, Google Maps place detail, local auto website listing, or merchant website for detail scraping, load the target sheet and normalize existing links and company names. If a collected URL or company name already exists in the sheet, skip it immediately and do not visit the homepage/detail page again.

## Status Values

Use these values consistently:

- `未联系`
- `已加好友`
- `已加好友,待私信`
- `已加好友,已发私信`
- `已发私信`
- `已发送邮件`
- `已加 WhatsApp,待跟进`
- `加好友失败`
- `发送失败`


For email sending, treat `已发送邮件`, `已发邮件`, `邮件已发送`, and `邮件发送成功` as already-sent statuses.

## Notes Field

`备注` should be a concise structured summary. Do not paste one raw post as the whole note. Synthesize business-relevant observations such as main business, activity, recent posts, China-brand signals, batch purchase capacity, contact evidence, and risks.

## Facebook 公司官网字段

Facebook Sheet supports an additional field: `公司官网`.

- `主页/链接`: the Facebook Page URL, used for duplicate checks, Facebook outreach, and status tracking.
- `公司官网`: the merchant's external official website discovered from Facebook Page/About/action links.
- If the workbook does not already contain `公司官网`, write-enabled scripts may append this column to the Facebook Sheet header.
- Do not store Instagram, WhatsApp, YouTube, TikTok, LinkedIn, Google Maps, or other social/platform URLs in `公司官网`.
- `客户信息汇总表` includes `公司官网` after `主页/链接`; duplicate company websites are merged with `；`.


## Customer Attribute And Type Taxonomy

`客户属性` may contain only the five broad classes below. `客户类型` may contain only a matching subtype from the same row. Do not write combined categories, multi-line labels, custom labels, or fallback unknown values into official workbook fields.

| Customer attribute | Allowed customer types |
|---|---|
| `汽车渠道合作伙伴` | `汽车进口商` ; `全国代理商` ; `全国分销商` ; `区域分销商` ; `多品牌经销商` ; `商用车渠道商` ; `中国品牌经销商` ; `新能源或小型车渠道商` |
| `批量采购与运营客户` | `汽车租赁公司` ; `长期租赁公司` ; `企业车队` ; `物流配送企业` ; `政府或机构采购方` |
| `二手车转型候选` | `连锁二手车企业` ; `实体二手车企业` ; `进口二手车企业` ; `新车与二手车综合企业` |
| `平台与行业渠道` | `汽车交易平台` ; `汽车协会` ; `商会` ; `车商联盟` ; `经销商资源引荐机构` |
| `生态支持资源` | `售后服务网络` ; `备件供应与仓储企业` ; `进口认证与上牌机构` ; `金融保险机构` ; `车辆物流企业` |

`主营业务` remains the business-description field and must not be renamed or used as a classification substitute.