<template>
  <div class="help-content">
    <div class="content-header">
      <h2>平台账号管理接口文档</h2>
      <el-button type="primary" size="small" plain @click="downloadDoc('/docs/account_management_api.md', 'Account_Management_API.md')">
        <el-icon style="margin-right: 5px"><Download /></el-icon>
        下载 开发文档
      </el-button>
    </div>
    <p class="intro">平台账号管理接口允许用户查询和管理自己在各个第三方应用中的账号映射关系，并支持通过 SSO 方式快速登录到目标应用。</p>

    <div class="section">
      <h3>1. 核心概念</h3>
      <ul>
        <li><strong>账号映射 (User Mapping)</strong>: 统一认证平台用户与第三方应用账号的关联关系</li>
        <li><strong>映射账号 (Mapped Key)</strong>: 用户在第三方系统中的唯一标识</li>
        <li><strong>映射邮箱 (Mapped Email)</strong>: 用户在第三方系统中的邮箱地址</li>
        <li><strong>SSO 登录</strong>: 单点登录，用户无需再次输入密码即可进入第三方应用</li>
      </ul>
    </div>

    <div class="section">
      <h3>1.1 接口权限说明</h3>
      <table class="param-table">
        <thead>
          <tr><th>接口</th><th>认证方式</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr>
            <td><code>GET /simple/me/mappings</code></td>
            <td>Bearer Token (用户认证)</td>
            <td>仅用户可查询自己的账号映射</td>
          </tr>
          <tr>
            <td><code>POST /simple/sso-login</code></td>
            <td>Bearer Token (可选) 或 用户名密码</td>
            <td>支持会话认证和凭据认证两种模式</td>
          </tr>
        </tbody>
      </table>
    </div>

    <div class="section">
      <h3>2. 认证方式</h3>
      
      <h4>2.1 用户认证 (Bearer Token)</h4>
      <p>适用于前端应用或已登录的用户。</p>
      <p><strong>请求头格式:</strong></p>
      <div class="code-block">
        <pre>Authorization: Bearer {access_token}</pre>
      </div>
      <p><strong>获取 Token:</strong></p>
      <ul>
        <li>通过 <code>POST /auth/login/json</code> 接口登录获取</li>
        <li>或通过 <code>POST /simple/login</code> 接口（不提供 app_id）获取平台 access_token</li>
      </ul>

      <h4>2.2 凭据认证 (用户名密码)</h4>
      <p>适用于用户未登录 UAP 平台的场景，直接使用用户名和密码进行认证。</p>
    </div>

    <div class="section">
      <h3>3. 接口定义</h3>
      
      <h4>3.1 获取我的账号映射列表</h4>
      <p>查询当前用户在所有第三方应用中的账号映射关系。</p>
      <ul>
        <li><strong>接口地址</strong>: <code>GET /api/v1/simple/me/mappings</code></li>
        <li><strong>认证方式</strong>: Bearer Token (用户认证)</li>
        <li><strong>Content-Type</strong>: <code>application/json</code></li>
      </ul>

      <h5>3.1.1 请求参数 (Query Parameters)</h5>
      <table class="param-table">
        <thead>
          <tr><th>字段</th><th>类型</th><th>必填</th><th>默认值</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr>
            <td><code>skip</code></td>
            <td>integer</td>
            <td><span class="tag-optional">否</span></td>
            <td>0</td>
            <td>跳过的记录数（用于分页）</td>
          </tr>
          <tr>
            <td><code>limit</code></td>
            <td>integer</td>
            <td><span class="tag-optional">否</span></td>
            <td>10</td>
            <td>每页返回的记录数</td>
          </tr>
          <tr>
            <td><code>app_name</code></td>
            <td>string</td>
            <td><span class="tag-optional">否</span></td>
            <td>-</td>
            <td>应用名称（支持模糊搜索）</td>
          </tr>
        </tbody>
      </table>

      <h5>3.1.2 响应格式</h5>
      <p><strong>成功响应 (200 OK):</strong></p>
      <div class="code-block">
        <pre>
{
  "total": 25,
  "items": [
    {
      "app_name": "OA办公系统",
      "app_id": "oa_system_001",
      "protocol_type": "SIMPLE_API",
      "mapped_key": "zhangsan_oa",
      "mapped_email": "zhangsan@company.com",
      "is_active": true
    }
  ]
}
        </pre>
      </div>

      <h5>3.1.3 请求示例</h5>
      <p><strong>cURL:</strong></p>
      <div class="code-block">
        <pre v-pre>
curl -X GET "{{API_BASE_URL}}/simple/me/mappings?skip=0&limit=10&app_name=OA" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        </pre>
      </div>

      <p><strong>JavaScript (Fetch API):</strong></p>
      <div class="code-block">
        <pre v-pre>
const response = await fetch('{{API_BASE_URL}}/simple/me/mappings?skip=0&limit=10&app_name=OA', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log('总记录数:', data.total);
console.log('映射列表:', data.items);
        </pre>
      </div>
    </div>

    <div class="section">
      <h3>3.2 SSO 单点登录</h3>
      <p>通过 SSO 方式登录到目标应用，支持两种认证模式：</p>
      <ol>
        <li><strong>会话认证模式</strong>: 用户已登录 UAP 平台，使用 Bearer Token</li>
        <li><strong>凭据认证模式</strong>: 用户未登录，使用用户名和密码</li>
      </ol>
      <ul>
        <li><strong>接口地址</strong>: <code>POST /api/v1/simple/sso-login</code></li>
        <li><strong>认证方式</strong>: Bearer Token (会话认证，推荐) 或 用户名密码 (凭据认证)</li>
        <li><strong>Content-Type</strong>: <code>application/json</code></li>
        <li><strong>限制</strong>: 仅支持 <code>SIMPLE_API</code> 协议类型的应用</li>
      </ul>

      <h5>3.2.1 请求参数 (Request Body)</h5>
      <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><span class="tag-required">是</span></td>
            <td>目标应用的ID</td>
          </tr>
          <tr>
            <td><code>username</code></td>
            <td>string</td>
            <td><span class="tag-conditional">条件必填</span></td>
            <td>用户名（手机号、映射key或映射email）。如果已登录UAP平台，可不提供</td>
          </tr>
          <tr>
            <td><code>password</code></td>
            <td>string</td>
            <td><span class="tag-conditional">条件必填</span></td>
            <td>用户密码。如果已登录UAP平台，可不提供</td>
          </tr>
        </tbody>
      </table>

      <p><strong>注意:</strong> 如果用户已登录 UAP 平台（请求头包含有效的 Bearer Token），则 <code>username</code> 和 <code>password</code> 可以省略。</p>

      <h5>3.2.2 响应格式</h5>
      <p><strong>成功响应 (200 OK):</strong></p>
      <div class="code-block">
        <pre>
{
  "redirect_url": "https://oa.company.com/login?ticket=TICKET-7f8e9d0a-1234-5678-9abc-def012345678"
}
        </pre>
      </div>

      <h5>3.2.3 请求示例</h5>
      <p><strong>场景1: 用户已登录 UAP 平台（会话认证）</strong></p>
      <div class="code-block">
        <pre v-pre>
// JavaScript (Fetch API)
const response = await fetch('{{API_BASE_URL}}/simple/sso-login', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    app_id: 'oa_system_001'
  })
});

const data = await response.json();
if (data.redirect_url) {
  // 在新标签页中打开
  window.open(data.redirect_url, '_blank');
}
        </pre>
      </div>

      <p><strong>场景2: 用户未登录（凭据认证）</strong></p>
      <div class="code-block">
        <pre v-pre>
// JavaScript (Fetch API)
const response = await fetch('{{API_BASE_URL}}/simple/sso-login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    app_id: 'oa_system_001',
    username: '13800138000',
    password: 'user_password_123'
  })
});

const data = await response.json();
if (data.redirect_url) {
  window.open(data.redirect_url, '_blank');
}
        </pre>
      </div>
    </div>

    <div class="section">
      <h3>4. 注意事项</h3>
      
      <div class="feature-card">
        <h4>⚠️ 协议类型限制</h4>
        <ul>
          <li><code>GET /simple/me/mappings</code> 接口返回所有类型的应用映射</li>
          <li><code>POST /simple/sso-login</code> 接口<strong>仅支持 <code>SIMPLE_API</code> 协议类型</strong>的应用</li>
          <li>对于 <code>OIDC</code> 协议类型的应用，请使用标准的 OIDC 流程进行登录</li>
        </ul>
      </div>

      <div class="feature-card">
        <h4>🔒 安全建议</h4>
        <ul>
          <li><strong>Token 安全</strong>: Bearer Token 应妥善保管，避免泄露</li>
          <li><strong>HTTPS</strong>: 生产环境必须使用 HTTPS 协议</li>
          <li><strong>Token 过期</strong>: 注意处理 Token 过期的情况，及时刷新或重新登录</li>
          <li><strong>错误处理</strong>: 建议实现完善的错误处理和重试机制</li>
        </ul>
      </div>
    </div>

    <div class="section">
      <h3>5. 常见问题 (FAQ)</h3>
      
      <div class="faq-item">
        <h4>Q1: 为什么 SSO 登录返回 400 错误，提示"协议不支持"？</h4>
        <p><strong>A:</strong> <code>POST /simple/sso-login</code> 接口仅支持 <code>SIMPLE_API</code> 协议类型的应用。如果您的应用是 <code>OIDC</code> 类型，请使用标准的 OIDC 认证流程。</p>
      </div>

      <div class="faq-item">
        <h4>Q2: 如何判断用户是否已登录 UAP 平台？</h4>
        <p><strong>A:</strong> 如果您的应用中有有效的 <code>access_token</code>，可以在请求头中携带 <code>Authorization: Bearer {token}</code>。如果 Token 有效，则无需提供 <code>username</code> 和 <code>password</code>。</p>
      </div>

      <div class="faq-item">
        <h4>Q3: 账号映射列表中的 <code>mapped_email</code> 为什么可能为空？</h4>
        <p><strong>A:</strong> 不是所有第三方应用都要求或提供邮箱信息，因此 <code>mapped_email</code> 字段可能为 <code>null</code>。这是正常情况。</p>
      </div>

      <div class="faq-item">
        <h4>Q4: SSO 登录后，Ticket 的有效期是多久？</h4>
        <p><strong>A:</strong> Ticket 的有效期由平台配置决定，通常为 5-10 分钟。建议在获取 <code>redirect_url</code> 后立即跳转，避免 Ticket 过期。</p>
      </div>
    </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>
