<template>
  <div class="help-content">
    <div class="content-header">
      <h2>全量用户同步 (Pull) 使用说明</h2>
      <el-button type="primary" size="small" plain @click="downloadDoc('/docs/user_sync_pull.md', 'User_Sync_Pull_Guide.md')">
        <el-icon style="margin-right: 5px"><Download /></el-icon>
        下载 开发文档
      </el-button>
    </div>
    <p class="intro">此接口用于开发者从本平台<strong>拉取全量用户数据</strong>（仅包含手机号、姓名、英文名）。<br>
    适用场景：在业务系统初始化阶段，需要将统一认证平台的所有用户同步到本地数据库。</p>

    <div class="section">
      <h3>1. 接口概述</h3>
      <ul>
        <li><strong>接口地址</strong>: <code>GET /api/v1/apps/mapping/users</code></li>
        <li><strong>认证方式</strong>: 请求头需包含 <code>X-App-Access-Token</code>（可在应用详情页查看）。</li>
        <li><strong>接口特点</strong>: 支持分页查询，只返回基础身份信息。</li>
      </ul>
    </div>

    <div class="section">
      <h3>2. 请求参数 (Query Params)</h3>
      <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>100</td><td>每页返回数量</td></tr>
        </tbody>
      </table>

      <p><strong>请求示例 (Curl):</strong></p>
      <div class="code-block">
        <pre>
curl -X GET "http://your-uap-domain/api/v1/apps/mapping/users?skip=0&limit=100" \
     -H "X-App-Access-Token: YOUR_APP_ACCESS_TOKEN"
        </pre>
      </div>
    </div>

    <div class="section">
      <h3>3. 响应说明</h3>
      <p><strong>响应成功 (200 OK):</strong></p>
      <div class="code-block">
        <pre>
{
  "total": 1250,
  "items": [
    {
      "mobile": "13800138000",
      "name": "张三",
      "english_name": "zhangsan"
    },
    {
      "mobile": "13900139000",
      "name": "李四",
      "english_name": "lisi"
    },
    // ... 更多用户
  ]
}
        </pre>
      </div>
      <ul>
        <li><code>total</code>: 系统中未删除用户的总数。</li>
        <li><code>items</code>: 当前页的用户列表。</li>
      </ul>

      <p><strong>响应失败:</strong></p>
      <ul>
        <li><code>403 Forbidden</code>: Access Token 无效、过期或无权限。</li>
      </ul>
    </div>
    
    <el-alert title="开发建议" type="success" :closable="false" show-icon class="alert-box">
      <div>建议使用循环分页拉取（例如每次 100 条），直到获取的数据条数小于 limit 或总数达到 total，以避免单次请求超时。</div>
    </el-alert>
  </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>
