<template>
  <div class="help-content">
    <div class="content-header">
      <h2>票据交互 (Ticket Exchange) 使用说明</h2>
      <el-button type="primary" size="small" plain @click="downloadDoc('/docs/ticket_exchange.md', 'Ticket_Exchange_Guide.md')">
        <el-icon style="margin-right: 5px"><Download /></el-icon>
        下载 开发文档
      </el-button>
    </div>
    <p class="intro">当用户已在 <strong>源应用 (Source App)</strong> 登录，需要无缝跳转到 <strong>目标应用 (Target App)</strong> 且实现免登录时，使用此接口。</p>

    <div class="section">
      <h3>1. 场景说明</h3>
      <p>用户在 App A 点击 "跳转到 App B"，App A 后端调用此接口获取 App B 的票据，然后将用户重定向到 App B。</p>
      <ul>
        <li><strong>接口地址</strong>: <code>POST /api/v1/simple/exchange</code></li>
        <li><strong>Content-Type</strong>: <code>application/json</code></li>
      </ul>
    </div>

    <div class="section">
      <h3>2. 请求参数 (JSON Body)</h3>
      <table class="param-table">
        <thead>
          <tr><th>字段</th><th>类型</th><th>必填</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr><td><code>app_id</code></td><td>string</td><td>是</td><td><strong>源应用</strong> ID (发起方)</td></tr>
          <tr><td><code>target_app_id</code></td><td>string</td><td>是</td><td><strong>目标应用</strong> ID (跳转方)</td></tr>
          <tr><td><code>user_mobile</code></td><td>string</td><td>是</td><td>用户手机号 (作为用户身份标识)</td></tr>
          <tr><td><code>timestamp</code></td><td>int</td><td>是</td><td>当前时间戳</td></tr>
          <tr><td><code>sign</code></td><td>string</td><td>是</td><td>签名 (<strong>使用源应用的 Secret 计算</strong>)</td></tr>
        </tbody>
      </table>

      <p><strong>请求示例:</strong></p>
      <div class="code-block">
        <pre>
{
  "app_id": "source_app_A",
  "target_app_id": "target_app_B",
  "user_mobile": "13800138000",
  "timestamp": 1709876545,
  "sign": "generated_signature_hex"
}
        </pre>
      </div>
    </div>

    <div class="section">
      <h3>3. 响应说明</h3>
      <p><strong>响应成功 (200 OK):</strong></p>
      <div class="code-block">
        <pre>
{
  "ticket": "TICKET-for-target-app-...",
  "redirect_url": "http://target-app-b.com/sso/callback?ticket=TICKET-..."
}
        </pre>
      </div>
      <ul>
        <li><code>ticket</code>: 专门为目标应用生成的登录票据。</li>
        <li><code>redirect_url</code>: 拼接了 ticket 的目标应用重定向地址（自动取自目标应用配置的 <code>redirect_uris</code> 的第一个地址）。</li>
      </ul>

      <p><strong>响应失败:</strong></p>
      <ul>
        <li><code>404 Not Found</code>: 源应用/目标应用未找到，或用户在平台中不存在。</li>
        <li><code>400 Bad Request</code>: 签名无效。</li>
      </ul>
    </div>

    <div class="section">
      <h3>4. 完整交互流程</h3>
      <div class="flow-chart">
        <div class="actor-row">
          <div class="actor">源应用 (Source)</div>
          <div class="actor">统一认证 (UAP)</div>
          <div class="actor">目标应用 (Target)</div>
        </div>
        
        <div class="step">
          <div class="arrow user-to-client">1. POST /exchange</div>
        </div>
        <div class="step">
          <div class="arrow client-to-user dashed">2. 返回 redirect_url</div>
        </div>
        <div class="step">
          <div class="self-action" style="margin-left: 16%;">3. 重定向用户浏览器</div>
        </div>
        <div class="step">
          <div class="arrow client-to-uap dashed" style="opacity: 0.5;">4. (跳转) GET URL</div>
        </div>
         <div class="step">
          <div class="arrow uap-to-client">5. POST /validate (目标应用验证)</div>
        </div>
        <div class="step">
          <div class="arrow client-to-uap dashed">6. 返回用户信息</div>
        </div>
      </div>
      <ol>
        <li><strong>发起请求</strong>：源应用后端调用 <code>exchange</code> 接口，使用<strong>源应用密钥</strong>签名。</li>
        <li><strong>获取跳转地址</strong>：接口返回包含 Ticket 的 <code>redirect_url</code>。</li>
        <li><strong>重定向用户</strong>：源应用前端将用户浏览器重定向到该 <code>redirect_url</code>。</li>
        <li><strong>目标应用接收</strong>：目标应用接收到请求，从 URL 参数中提取 <code>ticket</code>。</li>
        <li><strong>验证票据</strong>：目标应用后端调用 <code>/api/v1/simple/validate</code> 接口（注意：此时 <code>app_id</code> 为目标应用 ID，<code>sign</code> 使用<strong>目标应用密钥</strong>）来验证票据并获取用户信息。</li>
      </ol>
    </div>
  </div>
</template>

<script setup lang="ts">
import { Download } from '@element-plus/icons-vue'
import { useHelpDocs } from '../../composables/useHelpDocs'

const { downloadDoc } = useHelpDocs()
</script>

<style scoped>
@import './help.css';
</style>
