# 首单付费 pilot Cloudflare D1 持久化迁移包｜2026-08-17

本文件说明 `migrations/0001_first_paid_pilot_service_confirmations.sql` 和 `data/first-paid-pilot-d1-persistence-migration-pack-20260817.json` 的用途、表结构和执行边界。

## 当前状态

- 状态：`d1-persistence-migration-pack-ready-not-executed`
- 作用：把首单服务确认表单和 localStorage 台账推进到 Cloudflare D1 可落库方案。
- 已生成：D1 SQL 迁移、6 张最小后台表、字段映射、API 草案、部署前门禁。
- 未执行：未创建 D1 数据库、未执行迁移、未绑定 Worker/Pages Functions、未配置登录、未保存客户数据、未收款、未发布文章。

## 为什么现在做 D1 持久化

localStorage 台账只能证明“内部流程可以跑通”，不能承担真实客户服务。真实首单付费 pilot 至少需要：

1. 服务确认记录可追溯。
2. 客户授权、赞助披露和不承诺 AI 结果条款可留档。
3. 交付单元、AI 复测计划、验收证据和审核日志可关联。
4. 付款、发票、发布、搜索提交等外部动作必须有独立授权和证据。

D1 迁移包解决第 1-3 点的数据结构准备；第 4 点仍需单独的财务、合同和外部动作授权流程。

## 最小表结构

- `geo_service_confirmations`：服务确认主表，保存客户主体、品牌、授权范围、赞助披露、不承诺 AI 结果、付款/发票状态、P0 证据状态和门禁判断。
- `geo_service_confirmation_units`：交付单元表，保存诊断、内容、复测、报告等子任务。
- `geo_service_confirmation_authorizations`：授权表，保存品牌资料公开使用、赞助披露、不承诺 AI 结果、外部动作和服务条款确认。
- `geo_service_confirmation_ai_test_plan`：AI 复测计划表，保存平台、问法组、目标 URL、计划日期、结果记录。
- `geo_service_confirmation_acceptance`：验收表，保存交付项是否通过、证据路径和人工复核。
- `geo_service_confirmation_audit_logs`：审计日志表，保存导入、修改、重算门禁、导出等后台动作。

## API 草案

- `POST /api/internal/service-confirmations`：从表单 JSON 或台账 JSON 创建草稿。
- `GET /api/internal/service-confirmations`：按门禁、付款、复核状态列出内部服务单。
- `GET /api/internal/service-confirmations/:id`：读取单个服务单及关联授权、交付、复测、验收和审计记录。
- `POST /api/internal/service-confirmations/:id/recompute-readiness`：重新计算门禁状态。
- `POST /api/internal/service-confirmations/:id/export`：导出人工归档 JSON。

所有接口都必须是内部 staff-only。第一阶段不开放公开客户登录、不开放自助充值发文。

## 执行顺序

以下步骤需要再次获得明确授权后才能执行：

1. 创建 D1：`wrangler d1 create lucheng_geo_pilot`
2. 绑定数据库：`LUCHENG_GEO_DB`
3. 本地执行迁移：`wrangler d1 migrations apply lucheng_geo_pilot --local`
4. 实现 staff-only API。
5. 导入 localStorage 台账导出的 JSON，状态只能是草稿。
6. 本地 API 测试通过后，再请求生产迁移授权。

本轮没有执行以上步骤。

## 仍然关闭的门

- 自助充值发文关闭。
- 自动发文关闭。
- AI 收录、自然推荐、排名、模型认知改变承诺关闭。
- `payment_status=paid` 不能作为付款证明。
- 未明确列入 `external_action_authorization_json` 的动作一律不能执行。
- P0 证据未通过前，不能使用强推荐、首选、最好、稳定推荐等口径。

## 机器可读来源

- 迁移包 JSON：`data/first-paid-pilot-d1-persistence-migration-pack-20260817.json`
- SQL：`migrations/0001_first_paid_pilot_service_confirmations.sql`
- HTML：`reports/first-paid-pilot-d1-persistence-migration-pack-20260817.html`
- 来源台账原型：`reports/first-paid-pilot-service-confirmation-ledger-prototype-20260817.html`