补开放接口文档

frontend/src/pages/OpenApiDocs.tsx

@@ -28,6 +28,20 @@ const preStyle: CSSProperties = {
   wordBreak: 'break-all',
 }
 
+const deliveryModes = [
+  {
+    mode: 'Web 发货页',
+    scene: '商户想要“只返回一个链接”，让用户直接打开平台页面填写 UID',
+    interfaces: '/api/client/v1/orders/{order_no}/delivery-link',
+  },
+  {
+    mode: '自建发货页',
+    scene: '商户自己有前端页面，想在自己的系统里完成发货流程',
+    interfaces:
+      '/api/client/v1/orders/{order_no}/delivery\n/api/client/v1/orders/{order_no}/delivery/bind\n/api/client/v1/orders/{order_no}/delivery/submit',
+  },
+]
+
 export default function OpenApiDocs() {
   return (
     <div>
@@ -37,10 +51,13 @@ export default function OpenApiDocs() {
       <Paragraph type="secondary">
         面向商户系统调用的开放 API。凭证在「商户中心 / API 客户端」创建，
         采用 <Text code>X-App-Key</Text> + HMAC-SHA256 签名鉴权。
-        <Text code>/api/open/v1</Text> 仅保留给发货平台查询与回传，不在本页展示。
+        发货链路同时支持「返回签名链接」和「返回结构化数据」两种模式。
+        <Text code>/api/open/v1</Text> 仍是上游回调链路，和本页的商户 API 分开。
       </Paragraph>
 
       <Tabs
+        tabPosition="left"
+        style={{ minHeight: 680 }}
         items={[
           {
             key: 'overview',
@@ -57,6 +74,11 @@ export default function OpenApiDocs() {
             label: '接口列表',
             children: <EndpointsTab />,
           },
+          {
+            key: 'delivery',
+            label: '发货模式',
+            children: <DeliveryModeTab />,
+          },
           {
             key: 'status',
             label: '状态说明',
@@ -80,10 +102,29 @@ function OverviewTab() {
             <li>在「商户中心 / API 客户端」创建凭证，获得 <Text code>AppKey</Text> 与 <Text code>AppSecret</Text>。</li>
             <li>每次请求携带 <Text code>X-App-Key / X-Timestamp / X-Nonce / X-Sign</Text> 四个鉴权头。</li>
             <li>调用「商品列表」拿到可售 <Text code>sku</Text>，调用「下单」创建订单并扣款。</li>
-            <li>拿到 <Text code>order_no</Text> 后进入发货链接；订单状态由发货平台回调更新，可通过「查询订单」轮询。</li>
+            <li>拿到 <Text code>order_no</Text> 后，可选择返回发货链接，或者用结构化发货接口完成自建页面流程。</li>
           </ol>
         }
       />
+      <Card size="small" title="发货链路概览">
+        <Table
+          size="small"
+          pagination={false}
+          rowKey="mode"
+          dataSource={deliveryModes}
+          columns={[
+            { title: '模式', dataIndex: 'mode', width: 140 },
+            { title: '适用场景', dataIndex: 'scene' },
+            {
+              title: '相关接口',
+              dataIndex: 'interfaces',
+              render: (v: string) => (
+                <pre style={preStyle}>{v}</pre>
+              ),
+            },
+          ]}
+        />
+      </Card>
       <Card size="small" title="环境信息">
         <Descriptions size="small" column={1} bordered>
           <Descriptions.Item label="Base URL">
@@ -101,6 +142,32 @@ function OverviewTab() {
   )
 }
 
+function DeliveryModeTab() {
+  return (
+    <Space direction="vertical" size="middle" style={{ width: '100%' }}>
+      <Card size="small" title="推荐用法">
+        <Descriptions size="small" column={1} bordered>
+          <Descriptions.Item label="只想给用户一个链接">
+            用 <Text code>delivery-link</Text>，后端直接返回签名后的 Web 发货页地址，前端只负责跳转或复制。
+          </Descriptions.Item>
+          <Descriptions.Item label="想自建发货页面">
+            用 <Text code>delivery</Text> 获取订单数据，再按需调用 <Text code>bind</Text> 和 <Text code>submit</Text>。
+          </Descriptions.Item>
+          <Descriptions.Item label="取消作废">
+            取消作废属于商户后台操作，恢复后会重新签发新有效期和新签名。
+          </Descriptions.Item>
+        </Descriptions>
+      </Card>
+      <Alert
+        type="info"
+        showIcon
+        message="两种模式共用同一套底层履约逻辑"
+        description="不管是 Web 发货页还是商户自建页面，最终都会走同一套订单校验、绑定和提交逻辑，只是前端形态不同。"
+      />
+    </Space>
+  )
+}
+
 function AuthTab() {
   return (
     <Space direction="vertical" size="middle" style={{ width: '100%' }}>