From bf058077cd937d4a59a20658b360e24cd74cd6d3 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 9 Jul 2026 23:18:53 +0800
Subject: [PATCH] =?UTF-8?q?docs(pay):=20=E8=A1=A5=E4=B8=A4=E8=A1=A8?=
 =?UTF-8?q?=E5=88=86=E5=B7=A5=E4=B8=8E=E5=88=9B=E5=BB=BA=E6=97=B6=E6=9C=BA?=
 =?UTF-8?q?(4.3),SKU=20=E5=AE=9A=E4=BB=B7=E6=94=B9=204.4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/pay-orchestration-design.html | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/pay-orchestration-design.html b/docs/pay-orchestration-design.html
index a97a423..715012d 100644
--- a/docs/pay-orchestration-design.html
+++ b/docs/pay-orchestration-design.html
@@ -206,7 +206,20 @@ status        TEXT            -- created|pending|paid|failed|expired
 created_at / paid_at DATETIME
 UNIQUE(provider, provider_ref)   -- 回调幂等的命门</pre>
 
-<h3>4.3 SKU 目录 + 定价 <span class="tag ok">已定</span></h3>
+<h3>4.3 两表分工与创建时机(一对多)</h3>
+<table>
+<thead><tr><th></th><th><code>pay_orders</code> 业务订单</th><th><code>pay_attempts</code> 支付尝试</th></tr></thead>
+<tbody>
+<tr><td>回答</td><td><b>谁买了什么、开通谁</b>(购买/权益)</td><td><b>用哪个平台怎么付、平台单号</b>(收款)</td></tr>
+<tr><td>何时创建</td><td>用户选套餐点「购买」确认那刻 —— <code>POST /v1/pay/orders</code>,<b>一次购买一行</b></td><td>每次选定支付方式建 provider 会话 —— 同一 <code>POST /v1/pay/orders</code>(首选渠道),或 <code>/retry</code>(换渠道)</td></tr>
+<tr><td>数量</td><td>1 笔购买 = 1 行(<code>order_no</code> 唯一)</td><td>1 笔购买 = <b>N 行</b>(每次换渠道重试各一行)</td></tr>
+<tr><td>锁定</td><td>建单即锁 user/plan/天数/金额 → 回调改不了(防伪造)</td><td>绑 provider + provider_ref → <code>UNIQUE</code> 幂等</td></tr>
+<tr><td>生命周期</td><td>created→pending→paid/expired/canceled(长)</td><td>created→pending→paid/failed/expired(短,可弃)</td></tr>
+</tbody>
+</table>
+<p class="small">典型:用户买 pro-year 选哪吒 → 建 order + attempt#1(nazha);扫码超时 → attempt#1 expired;点「换 crypto」→ order <b>不变</b>,新建 attempt#2(crypto);链上付款回调 → 按 provider_ref 定位 attempt#2 → 幂等 → order 与 attempt#2 一起置 paid、开通订阅。attempt#1 保留 expired 留痕。<b>拆两层就是为了「换渠道重试不污染订单状态机」+「订单是开通谁的唯一真相」。</b></p>
+
+<h3>4.4 SKU 目录 + 定价 <span class="tag ok">已定</span></h3>
 <p>SKU → (plan, 天数, 各币种价格)。哪吒收人民币(支付宝)、crypto 收 USDT,故<b>按币种各定一价</b>(不做实时汇率换算,固定价是产品决策)。首版 SKU 目录作为控制面代码常量(后续可迁 DB)。</p>
 <table>
 <thead><tr><th>SKU</th><th>plan</th><th>天数</th><th>USDT(crypto)</th><th>CNY(哪吒/支付宝)</th></tr></thead>