{
  "schemaVersion": "0.1",
  "id": "first-paid-pilot-staff-api-implementation-pack-20260817",
  "generatedAt": "2026-08-17T23:18:00+08:00",
  "status": "staff-api-implementation-pack-ready-not-deployed",
  "purpose": "Turn the D1 persistence migration design into a staff-only API implementation package for the first paid pilot service confirmation workflow, without deploying any backend code or mutating Cloudflare resources.",
  "productionPage": "/reports/first-paid-pilot-staff-api-implementation-pack-20260817.html",
  "humanReport": "/docs/FIRST_PAID_PILOT_STAFF_API_IMPLEMENTATION_PACK_20260817.md",
  "openApiContract": "/api-contracts/first-paid-pilot-service-confirmations.openapi-20260817.json",
  "testVectors": "/data/first-paid-pilot-staff-api-test-vectors-20260817.json",
  "sourceD1MigrationPack": "/data/first-paid-pilot-d1-persistence-migration-pack-20260817.json",
  "sourceSqlMigration": "/migrations/0001_first_paid_pilot_service_confirmations.sql",
  "currentExecutionState": {
    "functionsDirectoryCreated": false,
    "workerOrPagesFunctionsDeployed": false,
    "d1DatabaseCreated": false,
    "d1MigrationApplied": false,
    "authProviderConfigured": false,
    "staffUsersCreated": false,
    "customerDataStoredServerSide": false,
    "paymentEnabled": false,
    "officialSitePublishingEnabled": false,
    "externalSubmissionEnabled": false
  },
  "recommendedImplementationOrderAfterExplicitAuthorization": [
    {
      "step": "create-d1-local-first",
      "description": "Create D1 only after explicit authorization, then apply migration locally before any production migration."
    },
    {
      "step": "staff-auth",
      "description": "Add staff-only authentication and role checks before exposing any write endpoint."
    },
    {
      "step": "api-readiness-engine",
      "description": "Implement deterministic readiness computation using the static test vectors."
    },
    {
      "step": "draft-import",
      "description": "Import localStorage ledger exports as draft rows and keep source_payload_json for audit."
    },
    {
      "step": "audit-logging",
      "description": "Write every create, recompute and export action to geo_service_confirmation_audit_logs."
    },
    {
      "step": "local-e2e-test",
      "description": "Run API tests against local D1 before asking for production deployment authorization."
    },
    {
      "step": "production-migration-and-deploy",
      "description": "Ask for separate approval before applying production migration or deploying Pages Functions / Worker."
    }
  ],
  "apiEndpoints": [
    {
      "method": "POST",
      "path": "/api/internal/service-confirmations",
      "role": "staff-operator",
      "purpose": "Create a draft service confirmation from form JSON or localStorage ledger export.",
      "requiredAuditAction": "service-confirmation.create-draft"
    },
    {
      "method": "GET",
      "path": "/api/internal/service-confirmations",
      "role": "staff-viewer",
      "purpose": "List internal service confirmations using readiness, payment and brand filters.",
      "requiredAuditAction": "service-confirmation.list"
    },
    {
      "method": "GET",
      "path": "/api/internal/service-confirmations/:id",
      "role": "staff-viewer",
      "purpose": "Read one service confirmation and all associated units, authorizations, AI test plan, acceptance rows and audit logs.",
      "requiredAuditAction": "service-confirmation.read"
    },
    {
      "method": "POST",
      "path": "/api/internal/service-confirmations/:id/recompute-readiness",
      "role": "staff-operator",
      "purpose": "Recompute readiness blockers and warnings without granting payment, publishing or AI outcome proof.",
      "requiredAuditAction": "service-confirmation.recompute-readiness"
    },
    {
      "method": "POST",
      "path": "/api/internal/service-confirmations/:id/export",
      "role": "staff-reviewer",
      "purpose": "Export a human archive snapshot; export is not contract, payment, invoice, publishing or AI proof.",
      "requiredAuditAction": "service-confirmation.export"
    }
  ],
  "roles": [
    {
      "role": "staff-viewer",
      "allowed": [
        "list",
        "read"
      ],
      "notAllowed": [
        "create",
        "recompute-readiness",
        "export",
        "external-action"
      ]
    },
    {
      "role": "staff-operator",
      "allowed": [
        "list",
        "read",
        "create",
        "recompute-readiness"
      ],
      "notAllowed": [
        "export-as-approved",
        "payment-approval",
        "official-site-publish",
        "external-media-submit"
      ]
    },
    {
      "role": "staff-reviewer",
      "allowed": [
        "list",
        "read",
        "export"
      ],
      "notAllowed": [
        "payment-approval-without-finance-evidence",
        "ai-result-claim-approval",
        "external-write-without-explicit-authorization"
      ]
    }
  ],
  "hardGuards": [
    "All endpoints are staff-only. No public customer portal in this phase.",
    "Default external_action_authorization is none.",
    "Read-only authorization never permits publishing, payment, DNS, ICP, search submission or external media submission.",
    "payment_status=paid must produce a warning unless external finance evidence is linked.",
    "p0_evidence_status not accepted blocks strong claims and natural recommendation success claims.",
    "Planned AI test rows are not AI adoption evidence.",
    "Exported records are archives only and not contract, payment, invoice, publishing or AI proof."
  ],
  "validationPlan": [
    "Parse OpenAPI JSON.",
    "Parse test vectors JSON.",
    "Verify SQL migration still creates geo_service_confirmations.",
    "Run static site validator.",
    "Run local full live check after gray deployment build.",
    "Run production full live check after Cloudflare Pages deployment."
  ],
  "commercialBoundary": "This staff API package is a static implementation contract and test-fixture pack. It does not deploy a backend, create D1, configure auth, create staff users, store customer data, collect money, publish articles, submit search tools or prove AI indexing/recommendation."
}