# Text Encoding and Excel Write-Back Rules

These rules are mandatory for every script, temporary repair, and manual write-back that touches Excel text fields such as customer notes, outreach status, follow-up status, Chinese summaries, or HTML previews.

## Why this exists

Windows PowerShell inline scripts can corrupt Chinese text when a command contains Chinese literals inside a here-string, heredoc-like block, or inline Python source. The corrupted text appears in Excel or HTML as repeated question marks. This has already happened in the workbook notes after email status write-back, so future runs must treat encoding as a hard safety rule.

## Hard rules

- Do not write Chinese customer notes, status text, field names, or HTML labels by embedding Chinese literals directly inside PowerShell inline Python scripts.
- For temporary Python scripts launched from PowerShell, use one of these safe methods:
  - read Chinese text from an existing UTF-8 file;
  - build Chinese strings with Unicode escape sequences such as `\u90ae\u4ef6\u53d1\u9001\u8bb0\u5f55`;
  - call a shared skill script that already stores its source as UTF-8;
  - pass structured JSON generated by a UTF-8 script, not handwritten Chinese snippets from the shell command.
- Use `encoding="utf-8"` or `encoding="utf-8-sig"` explicitly when reading or writing JSON, Markdown, HTML, CSV, or text artifacts.
- Before saving Excel after any text write-back, scan the target values for repeated question marks. If found, abort the save or immediately repair before reporting success.
- After saving Excel, reopen the workbook and scan all written cells for repeated question marks. Verification must include `备注`, `建联状态`, `下次跟进`, `客户属性`, `客户类型`, and generated HTML preview labels when applicable.
- Do not trust a successful SMTP send, workbook save, or preview generation as proof that text is clean. Encoding verification is a separate step.
- When a workbook is locked, write a pending JSON file using UTF-8 and do not handwrite Chinese additions later from PowerShell. The later write-back must consume the pending JSON or a UTF-8 script.

## Required verification snippets

Every write-back report should include these counts:

- `question_mark_cells`: number of workbook cells containing repeated question marks after save.
- `question_mark_note_rows`: number of note rows containing repeated question marks after save.
- `html_question_mark_groups`: number of repeated-question-mark groups in generated HTML previews.

If any count is greater than zero, the task is not complete.

## Recommended note construction

For email write-back notes, prefer structured data first:

```json
{
  "event": "email_sent",
  "sent_at": "2026-07-29 12:40:58",
  "template_kind": "auto_channel_partner",
  "emails": ["example@company.com"],
  "send_log": "runs/YYYYMMDD/<run_id>/send-log.jsonl"
}
```

Then render the Chinese note inside a UTF-8 Python module or via Unicode escapes. Do not render it inside a PowerShell command containing raw Chinese.

## Standard clean Chinese phrases

Use these meanings consistently when rendering from safe code:

- email send record: `邮件发送记录：... 已按...模板发送至 ...；发送日志：...。`
- email status repair: `邮件状态修复：发送日志确认已于 ... 向 ... 发送邮件；原状态为 ...。`
- wait for reply: `等待回复`
- sent email status: `已发送邮件`

## Failure handling

If repeated question marks appear:

1. Stop further write-back or sending-related status updates.
2. Backup the workbook before repair.
3. Reconstruct the affected notes from source JSON/send logs, not from the corrupted text.
4. Save and rescan the entire workbook.
5. Only report completion when `question_mark_cells = 0`.