# 首单付费 pilot staff-only API 实施包｜2026-08-17

本文件说明首单服务确认后台的 API 实施准备包。它承接 D1 持久化迁移包，但本轮不部署后台。

## 当前状态

- 状态：`staff-api-implementation-pack-ready-not-deployed`
- 已生成：OpenAPI 合同、权限矩阵、5 个内部接口、测试向量、上线门禁。
- 未执行：未创建 `functions/`，未部署 Worker / Pages Functions，未创建 D1，未执行迁移，未配置登录，未创建员工账号，未保存客户数据。

## 为什么做这一步

D1 SQL 只定义“数据怎么存”。真实首单 pilot 还需要定义：

1. 谁能录入服务确认单。
2. 哪些接口只能内部 staff 使用。
3. 哪些字段会阻断真实付费服务。
4. 哪些状态不能被误写成付款、合同、发布或 AI 推荐证明。
5. 后续开发时如何用固定测试向量验证门禁。

## API 合同

静态 OpenAPI 文件：

- `api-contracts/first-paid-pilot-service-confirmations.openapi-20260817.json`

接口草案：

- `POST /api/internal/service-confirmations`：创建草稿服务单。
- `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`：导出人工归档快照。

全部接口必须是 staff-only。第一阶段不开放公开客户登录，也不开放自助充值发文。

## 测试向量

静态测试向量：

- `data/first-paid-pilot-staff-api-test-vectors-20260817.json`

覆盖场景：

1. 禄城内部样板必须保持 `not-ready-for-real-paid-service`。
2. 小额诊断 pilot 只能进入 `ready-for-human-review-not-payment-proof`。
3. 未接受赞助披露必须阻断。
4. 未接受“不承诺 AI 结果”必须阻断。
5. `payment_status=paid` 也不能作为付款证明。
6. 只读授权不能用于官网发布、搜索提交或媒体投稿。

## 权限边界

- `staff-viewer`：只能查看。
- `staff-operator`：可创建草稿和重算门禁，但不能批准付款、发布或外部投稿。
- `staff-reviewer`：可导出归档，但导出不等于合同、付款、发票、发布或 AI 结果证明。

## 后续真实开发顺序

需要另行明确授权后才能执行：

1. 创建 Cloudflare D1，并先执行本地迁移。
2. 配置 staff-only 登录和角色检查。
3. 实现 readiness 计算引擎。
4. 导入 localStorage 台账导出的 JSON，全部先作为 draft。
5. 写入审计日志。
6. 本地 API 测试通过后，再请求生产迁移和 Pages Functions / Worker 部署授权。

## 仍然关闭

- 自助充值发文关闭。
- 客户公开登录关闭。
- 自动发文关闭。
- 支付、合同、发票关闭。
- 官网发布、搜索提交、外部媒体投稿关闭。
- AI 收录、排名、自然推荐、模型认知改变承诺关闭。

## 机器可读来源

- 实施包 JSON：`data/first-paid-pilot-staff-api-implementation-pack-20260817.json`
- OpenAPI：`api-contracts/first-paid-pilot-service-confirmations.openapi-20260817.json`
- 测试向量：`data/first-paid-pilot-staff-api-test-vectors-20260817.json`
- HTML：`reports/first-paid-pilot-staff-api-implementation-pack-20260817.html`