PLS Kolable order payment control tower - job 4e3e7736

acceptance-tests.md

E2E Acceptance Tests

A. Date Range Import

Given order-payment-export-template.csv, when import runs, then all rows must have order_date between 2026-05-12 and 2026-05-21.

Pass: invalid_date_rows = 0.

B. Payment Status Completeness

Given imported orders, when reconciliation runs, then every row must map to paid/pending/failed/refunded/unknown.

Pass: null_payment_status = 0.

C. Fulfillment Gate

Given payment_status is pending/failed/unknown, when fulfillment gate runs, then fulfillment_status must be hold.

Pass: no unpaid order is marked ready/delivered.

D. Refund Risk

Given refund_status is requested/refunded, when revenue report runs, then amount is excluded from confirmed revenue until Louis review.

Pass: refund_risk_amount is shown separately.

E. Wade Export SLA

Given Wade has not uploaded export by due time, when watchdog runs, then people_sync escalation asks for blocker or alternate source.

Pass: escalation contains owner, due time, required columns, and fallback.

Current Verification

• HTML control tower is openable.
• learning-memory.json parses.
• Gist returns HTTP 200.
• Gist file list includes required files.
• PLS upload-files reports uploaded count.

artifact-url-or-pr.md

Artifact URL / PR Record

Primary artifact URL: https://gist.github.com/esz135888/623ecb5f27ca72a9d2e23fc947c105f8

Type

Shared-cloud Gist artifact pack. No GitHub PR or deployment is claimed for this job.

Verification

• Gist HTTP status: HTTP/2 200 verified on 2026-05-24 Asia/Taipei.
• Gist file list: 13 files verified by gh gist view 623ecb5f27ca72a9d2e23fc947c105f8 --files.
• PLS upload-files: pending before final PLS sync.

Required Contract Kinds

primary_artifact, solution_selection, skill_usage, market_context, market_maturity, production_readiness, production_acceptance, e2e_verification, people_sync, learning_memory, landing_record, tool, dashboard, doc.

data-model.md

Data Model / API / Sync / Permission Spec

Tables

kolable_order_exports

column	type	required	note
order_id	text	yes	unique order id
buyer_name_hash	text	yes	anonymized buyer id
buyer_contact_hash	text	no	anonymized contact
order_date	date	yes	expected 2026-05-12 to 2026-05-21
product_name	text	yes	Kolable course/product
course_version	text	yes	old_6_modules/new_12_chapters/unknown
amount	numeric	yes	gross order amount
payment_status	enum	yes	paid/pending/failed/refunded/unknown
paid_at	timestamptz	no	payment confirmed time
refund_status	enum	yes	none/requested/refunded/unknown
fulfillment_status	enum	yes	hold/ready/delivered/unknown

kolable_payment_reconciliation

column	type	required	note
recon_id	uuid	yes	reconciliation id
order_id	text	yes	order join
payment_source	text	yes	gateway/bank/manual/export
payment_reference	text	no	transaction id
matched_amount	numeric	yes	matched payment amount
match_confidence	numeric	yes	0-1
exception_type	enum	no	missing_payment/amount_mismatch/refund_risk/duplicate/unknown
review_owner	text	yes	Wade/Louis/makarove
review_due	date	yes	exception due date

API / Sync

• POST /api/kolable/orders/import accepts order-payment-export-template.csv.
• GET /api/kolable/orders/reconciliation?date_from=2026-05-12&date_to=2026-05-21 returns paid/pending/refund/unknown counts.
• POST /api/kolable/orders/:order_id/review records manual review and reason.
• POST /api/kolable/orders/:order_id/fulfillment-gate blocks or releases fulfillment after payment review.

Permissions / Audit

• Wade can upload raw order/payment export.
• Louis can approve revenue status and fulfillment release.
• makarove can contact buyer but cannot change payment status.
• zihrou can review high-risk refund or communication exceptions.
• Audit log records status change, actor, source file, old/new status, timestamp, and review reason.

Rollback / Failure

• Missing required columns: reject import and send Wade column error.
• payment_status=unknown: hold fulfillment and assign Wade review.
• refund_status=requested: block external revenue reporting until Louis approves.
• Duplicate order_id: create exception and block auto-merge.

decision-record.md

Decision Record

Decision

Build Kolable Order Payment Control Tower for this round.

Problem

The task asks Wade to export orders and payment status, but without a standard template and review gate, the export may not resolve the actual business risk: confirmed revenue, refund exposure, and fulfillment eligibility.

Options Considered

1. Send only a LINE reminder to Wade.
   • Rejected: insufficient; no data schema or validation.
2. Build full backend integration immediately.
   • Rejected: real export source and fields are not yet verified.
3. Build control tower + CSV template + API/data spec.
   • Recommended: fastest production artifact that supports immediate adoption and future backend integration.

Recommendation

Use the CSV template first. If Wade's export passes schema and unknown <= 2, dispatch repo_change/API integration next. If not, keep it as manual control tower and fix source data.

Adoption Status

Proposed for job 4e3e7736-c433-433c-8102-a93879ff96c9.

Landing Path

Owner: Louis. Data source owner: Wade. Customer communication: makarove. Supervisor / risk review: zihrou. Due: 2026-05-24 18:00 Asia/Taipei for first export.

Feedback If Not Adopted

Return actual export file, source system limitation, missing permissions, or a decision to postpone fulfillment/revenue reporting until data is clean.

kolable-order-payment-control-tower.html

<!doctype html>
<html lang="zh-Hant">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kolable 訂單付款對帳 Control Tower</title>
  <style>
    :root { --ink:#172033; --muted:#617086; --line:#d8dee9; --bg:#f5f7fb; --panel:#fff; --green:#087443; --red:#b42318; --amber:#a15c07; --blue:#175cd3; }
    * { box-sizing:border-box; }
    body { margin:0; background:var(--bg); color:var(--ink); font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }
    header { background:var(--panel); border-bottom:1px solid var(--line); padding:28px 32px; }
    h1 { margin:0 0 6px; font-size:26px; letter-spacing:0; }
    h2 { margin:0 0 12px; font-size:17px; }
    main { max-width:1240px; margin:0 auto; padding:22px 18px 42px; display:grid; gap:16px; }
    section { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:18px; }
    .grid { display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:12px; }
    .card { border:1px solid var(--line); border-radius:8px; background:#fbfcff; padding:14px; min-height:116px; }
    .label { color:var(--muted); font-size:12px; text-transform:uppercase; }
    .value { font-size:24px; font-weight:750; margin-top:4px; }
    .green { color:var(--green); } .red { color:var(--red); } .amber { color:var(--amber); } .blue { color:var(--blue); }
    table { width:100%; border-collapse:collapse; }
    th,td { text-align:left; vertical-align:top; border-bottom:1px solid var(--line); padding:10px 8px; }
    th { color:var(--muted); font-size:12px; }
    code { background:#eef2f7; border-radius:4px; padding:1px 5px; }
    .small { color:var(--muted); font-size:12px; }
    .pill { display:inline-block; border:1px solid var(--line); border-radius:999px; padding:2px 9px; background:#fff; }
    @media (max-width:900px){ header{padding:22px 18px;} .grid{grid-template-columns:1fr;} }
  </style>
</head>
<body>
  <header>
    <h1>Kolable 訂單付款對帳 Control Tower</h1>
    <div class="small">Job 4e3e7736-c433-433c-8102-a93879ff96c9 · export owner Wade · owner Louis · due 2026-05-24 18:00</div>
  </header>
  <main>
    <section>
      <h2>目前管制點</h2>
      <div class="grid">
        <div class="card"><div class="label">Date Range</div><div class="value blue">5/12-5/21</div><div class="small">只收此區間訂單。</div></div>
        <div class="card"><div class="label">Export SLA</div><div class="value amber">18:00</div><div class="small">Wade 未回即升級 Louis。</div></div>
        <div class="card"><div class="label">Fulfillment Gate</div><div class="value red">hold unknown</div><div class="small">未付款/未知不可履約。</div></div>
        <div class="card"><div class="label">Upgrade Gate</div><div class="value green"><=2 unknown</div><div class="small">達標才接後台 API。</div></div>
      </div>
    </section>
    <section>
      <h2>必填欄位</h2>
      <table>
        <tr><th>欄位</th><th>用途</th><th>失敗處理</th></tr>
        <tr><td><code>order_id</code></td><td>唯一訂單鍵</td><td>缺少即退回 Wade。</td></tr>
        <tr><td><code>payment_status</code></td><td>paid/pending/failed/refunded/unknown</td><td>unknown 進人工 review。</td></tr>
        <tr><td><code>refund_status</code></td><td>none/requested/refunded/unknown</td><td>requested/refunded 不列 confirmed revenue。</td></tr>
        <tr><td><code>fulfillment_status</code></td><td>hold/ready/delivered/unknown</td><td>未付款不可 ready。</td></tr>
        <tr><td><code>course_version</code></td><td>課綱升級溝通</td><td>unknown 由 makarove 補溝通狀態。</td></tr>
      </table>
    </section>
    <section>
      <h2>例外分流</h2>
      <table>
        <tr><th>條件</th><th>路由</th><th>Owner</th></tr>
        <tr><td>payment_status=unknown</td><td><span class="pill">manual_review</span></td><td>Wade</td></tr>
        <tr><td>refund_status=requested</td><td><span class="pill">revenue_hold</span></td><td>Louis</td></tr>
        <tr><td>course_version=old_6_modules</td><td><span class="pill">upgrade_comm</span></td><td>makarove</td></tr>
        <tr><td>unknown_payment_count > 2</td><td><span class="pill">source_fix</span></td><td>Louis + Wade</td></tr>
      </table>
    </section>
  </main>
</body>
</html>

learning-memory.json

{
  "job_id": "4e3e7736-c433-433c-8102-a93879ff96c9",
  "project": "AI 自建專案：Kolable - 直播銷講工具平台",
  "learned_at": "2026-05-24T07:00:00+08:00",
  "solution_selection": "tool + spreadsheet + system + communication",
  "market_context": [
    {
      "source": "Shopify/Adobe Commerce order workflow",
      "lesson": "Payment confirmation and fulfillment readiness should be separate states."
    },
    {
      "source": "Ecommerce reconciliation practices",
      "lesson": "Reliable revenue reporting needs order, payment, refund, and payout matching with exception queues."
    }
  ],
  "pls_next_checks": [
    "Check whether Wade uploaded the required export by due time.",
    "Reject export rows that lack order_id, amount, payment_status, or fulfillment_status.",
    "Hold fulfillment for pending, failed, unknown, or refund-requested orders.",
    "Do not upgrade to backend integration until unknown_payment_count <= 2."
  ],
  "assumptions_overturned": [
    "A raw export request is not enough to resolve revenue risk.",
    "Paid orders and fulfilled orders must not be treated as the same state.",
    "Course upgrade communication depends on knowing who paid and what version they purchased."
  ],
  "next_iteration_condition": "Import Wade's real export and produce the first paid/pending/refund/unknown report."
}

market-maturity.md

Market Maturity

Current Practice Check

Checked on 2026-05-24 Asia/Taipei using web search.

Mature Market Pattern

Mature ecommerce and live commerce operations separate order creation, payment capture, risk/fraud review, refund status, fulfillment release, and accounting reconciliation. Payment confirmation should gate fulfillment; exceptions should be visible with owners and due dates.

Comparable Practices

• Shopify and Adobe Commerce order workflows treat payment receipt/authorization as a separate status before fulfillment.
• Shopify fraud/risk workflows can hold or cancel risky orders before fulfillment.
• Ecommerce reconciliation practice matches records across order, payment gateway, bank/payout, refunds, fees, and taxes rather than trusting a single export.
• Reconciliation systems increasingly use confidence scoring and exception queues, not only exact 1:1 matching.

PLS Gap

Kolable currently has a person-dependent export request. It lacks a standardized order/payment schema, fulfillment gate, refund risk separation, and exception workflow.

This Round's Upgrade

This pack adds:

• required columns for Wade export.
• payment/fulfillment/refund status model.
• manual review ownership.
• control tower surface.
• API/sync path for future backend integration.

order-payment-export-template.csv

production-acceptance.md

Production Acceptance

Pass Conditions

• Primary artifact opens through shared-cloud Gist.
• Required files exist: production brief, solution selection, skill usage, market maturity, production acceptance, data model, acceptance tests, decision record, sources, learning memory, control tower HTML, export CSV, artifact URL record.
• Artifacts JSON includes primary_artifact, solution_selection, skill_usage, market_context, market_maturity, production_readiness, production_acceptance, e2e_verification, people_sync, and learning_memory.
• Owner/due/acceptance are explicit.

Metric Gates

• Wade export received by 2026-05-24 18:00 Asia/Taipei.
• 100% rows have required columns.
• paid_confirmed_rate >= 95% or exceptions assigned.
• unknown_payment_count <= 2 before backend/API upgrade.
• no pending/failed/unknown payment is marked fulfillment ready.

Fail Conditions

• Summary-only completion.
• No openable artifact.
• No CSV template.
• No data/API/permission path.
• No refund/fulfillment guard.
• No owner for unknown payment exceptions.

Owner / Due / Acceptance

• Owner: Louis.
• Export owner: Wade.
• Customer communication: makarove.
• Supervisor: zihrou.
• Due: 2026-05-24 18:00 Asia/Taipei.
• Acceptance: export imported, payment statuses mapped, exceptions assigned, fulfillment gate applied.

production-brief.md

Production Brief：Kolable 訂單付款對帳 Control Tower

場景

Kolable 需要 Wade 匯出 2026-05-12 至 2026-05-21 訂單與付款狀態。這不是單純催辦，因為訂單、付款、退款、出貨、課綱升級溝通會直接影響營收、履約與學員信任。本輪交付可用的對帳控制台、CSV 匯入模板、資料/API/權限規格、驗收與 people sync，讓 PLS 可以追 Wade，也可以在資料回來後立刻判斷收款缺口、出貨 hold、退款/補差額風險。

Solution Selection

選型：tool + spreadsheet + system + communication。

不是更小的 communication：只催 Wade 匯出會拿到雜亂檔案，無法判斷付款狀態與營收風險。

不是更大的 agent：目前缺真實匯出資料，不應自動退款、通知客戶或更改履約狀態。先用 control tower 建立資料標準與人審 gate。

30 天路徑

• D1：Wade 匯出 5/12-5/21 訂單與付款；PLS 用模板匯入並標記 paid/pending/refund/unknown。
• D7：建立營收缺口、待補款、待退款、出貨 hold 清單；Louis 判斷是否需要學員溝通。
• D14：把對帳流程接進 Kolable 後台/API，付款狀態改變時自動更新 fulfillment gate。
• D30：形成直播銷講營收控制系統：訂單 → 付款 → 課程版本 → 履約 → 退款/升級溝通 → 週報。

目的到目的 E2E

原始目的：確認 Kolable 在 5/12-5/21 的訂單與付款狀態，避免營收與履約失真。 產出物：HTML control tower、CSV 匯入模板、data model、acceptance tests、decision record、market maturity、production acceptance、learning memory。 人採用：Wade 匯出資料；Louis 判斷營收/履約處理；makarove 協助客戶溝通；zihrou 監督風險與升級決策。 指標改善：paid_confirmed_rate、unknown_payment_count、refund_risk_amount、fulfillment_hold_count、time_to_reconcile。

價值 / 錢路徑

• 營收：快速確認已付款與未付款，避免漏收或誤認收入。
• 降風險：未付款或高風險訂單不進履約，避免免費交付與後續爭議。
• 提高轉換：課綱升級時能精準對已購買者溝通升級/退款選項。
• 釋放人力：把人工翻訂單與付款紀錄轉成狀態欄與例外清單。

提升人的能力

Louis 能用對帳數據判斷 Kolable 是否該繼續加碼；Wade 知道匯出欄位與截止時間；makarove 能用訂單狀態準確溝通；zihrou 能看到營收與履約風險，不只看聊天紀錄。

Solution Stack

• 脈絡框架：order export → payment reconciliation → fulfillment gate → customer communication → revenue report。
• 作業流程：Wade 匯出 CSV；PLS 匯入；control tower 分流 paid/pending/refund/unknown；人審例外。
• 資料模型：見 data-model.md。
• 可操作工具：kolable-order-payment-control-tower.html、order-payment-export-template.csv。
• 驗收指標：見 acceptance-tests.md 與 production-acceptance.md。
• 採用與下一輪升級：資料回來後若 unknown <= 2 且 paid_confirmed_rate >= 95%，下一輪接 API/後台。

People Sync / LINE 草稿

Louis → Wade：請今天 18:00 前匯出 Kolable 5/12-5/21 訂單與付款狀態，欄位請含 order_id、buyer、order_date、amount、payment_status、paid_at、refund_status、course_version、fulfillment_status。缺欄位請直接標 unknown，不要口頭補。

若 Wade 未回：這批資料會影響已購買學員的課綱升級溝通與退款/履約判斷。若 18:00 前無法匯出，請先回覆卡在哪個系統或權限，我會改派 Louis 決定替代資料源。

上一版問題 → 本輪修改 → 驗證結果 → 下一輪建議

上一版問題：只有「由 Louis 追 Wade 匯出」的人工作業，缺資料標準與付款/履約分流。 本輪修改：交付 control tower、CSV 模板、資料模型、API/權限、驗收與 people sync。 驗證結果：本地 JSON 驗證、Gist HTTP 200、Gist file list、PLS upload-files。 下一輪建議：拿 Wade 真實匯出後跑 paid/unknown/refund report，決定是否接後台同步。

skill-usage.md

Skill / Tool Usage

Selected Skills / Tools

• purpose_e2e_toolbox_v2: used for D1/D7/D14/D30, E2E, value path, human capability, solution stack, data model, acceptance, and decision record.
• PLS solution catalog: selected tool + spreadsheet + system + communication.
• Web search: used for current market maturity on ecommerce order/payment reconciliation and fulfillment gating.
• Shell tools: python3 -m json.tool, find, rg.
• GitHub CLI: used to publish and verify shared-cloud Gist.
• URL verification: curl -I -L -s verifies HTTP 200.
• PLS helper: doctor, touch, claim, context, progress, upload-files, complete.

Why These Tools

This job needs immediate human adoption plus a future backend path. HTML gives an openable control tower, CSV gives Wade a concrete export target, Markdown specs provide API/permissions/acceptance, and Gist gives a durable shared artifact.

Evidence / Test Result

• kolable-order-payment-control-tower.html is the primary artifact.
• order-payment-export-template.csv defines required import fields.
• learning-memory.json passes JSON parsing.
• Gist HTTP 200 and file list are verified before complete.
• PLS upload-files must return uploaded file count.

solution-selection.md

Solution Selection

Selected Type

tool + spreadsheet + system + communication

Why

訂單付款對帳同時需要人取得資料、表格標準、控制台分流、以及未來後台接入。只做訊息催辦會缺少可驗收資料；只做系統規格又太慢。

Why Not Smaller

• communication 只能催 Wade，不能判斷資料完整性。
• doc 只能說明流程，無法讓 Louis 直接看營收與履約風險。

Why Not Bigger

• agent 或自動退款/出貨目前太早，因為真實訂單資料尚未回來。付款與退款屬高風險行為，必須先有人工審核與 audit。

Adoption Condition

Wade 匯出後，PLS 匯入模板且所有 order rows 都能落到 paid/pending/refund/unknown 四類；unknown <= 2 才進下一輪後台/API 實作。

sources.md

Market Context Sources

Checked date: 2026-05-24 Asia/Taipei.

1. Shopify Help Center, "Preventing fraud". URL: https://help.shopify.com/en/manual/payments/fraud-prevention/preventing-fraud Use: supports hold/cancel/review workflows before fulfillment.

2. Shopify Help Center, "Understanding Shopify Payments risk evaluation process". URL: https://help.shopify.com/en/manual/payments/shopify-payments/payouts/risk-evaluation-process Use: supports payment/risk evaluation as a separate operational layer.

3. Adobe Commerce, "Order workflow and processing". URL: https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/order-management/orders/order-processing Use: supports separate order status and payment received/authorized workflow.

4. Inyo, "Payment Reconciliation: How to Match Transactions at Scale", published 2026-03-05. URL: https://www.inyoglobal.com/news/payment-reconciliation-guide Use: supports multi-source reconciliation and exception workflow.

5. Webgility, "Shopify Payments Xero Reconciliation". URL: https://www.webgility.com/blog/how-to-reconcile-shopify-payments-in-xero Use: supports payment gateway, refund, tax, fee, and payout complexity.