<template>
  <div class="help-content">
    <div class="content-header">
      <h2>账号同步 (M2M) 使用说明</h2>
      <el-button type="primary" size="small" plain @click="downloadDoc('/docs/account_sync.md', 'Account_Sync_Guide.md')">
        <el-icon style="margin-right: 5px"><Download /></el-icon>
        下载 开发文档
      </el-button>
    </div>
    <p class="intro">此接口用于将外部业务系统（如 OA、CRM）的用户账号关系同步到本平台。支持批量调用，实现“本平台用户（手机号）”与“外部应用账号（ID/邮箱）”的绑定。</p>

    <div class="section">
      <h3>1. 接口概述</h3>
      <ul>
        <li><strong>接口地址</strong>: <code>POST /api/v1/apps/mapping/sync</code></li>
        <li><strong>认证方式</strong>: 请求头需包含 <code>X-App-Access-Token</code>（可在应用详情页查看）。</li>
        <li><strong>支持操作</strong>: 增改 (UPSERT) 和 删除 (DELETE)。</li>
      </ul>
      
      <div class="feature-card">
        <h4>🛠️ 接口逻辑 (UPSERT 模式)</h4>
        <ol>
          <li>根据 <code>mobile</code> 查找用户。</li>
          <li><strong>新建用户</strong>：
            <ul>
              <li>必须提供 <code>name</code>（姓名）。</li>
              <li><code>english_name</code>（英文名）可选，如未提供会自动生成并确保唯一性。</li>
            </ul>
          </li>
          <li><strong>已有用户</strong>：
            <ul>
              <li><strong>不允许修改</strong>：<code>name</code>、<code>mobile</code>、<code>english_name</code> 等用户基本信息。</li>
              <li><strong>可以修改</strong>：映射信息（<code>mapped_key</code>、<code>mapped_email</code>、<code>is_active</code>）。</li>
            </ul>
          </li>
          <li>将该用户与当前应用建立或更新映射关系（绑定 <code>mapped_key</code> 和 <code>mapped_email</code>）。</li>
        </ol>
      </div>

      <div class="feature-card">
        <h4>🗑️ 删除逻辑 (DELETE 模式)</h4>
        <ul>
          <li>仅删除用户在当前应用下的映射关系。</li>
          <li><strong>不删除</strong>平台上的用户账号。</li>
        </ul>
      </div>
    </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>mobile</code></td><td>string</td><td><span class="tag-required">是</span></td><td>用户手机号（平台唯一标识），须为 11 位中国大陆手机号（1[3-9] 开头）</td></tr>
          <tr><td><code>name</code></td><td>string</td><td><span class="tag-conditional">条件</span></td><td>姓名（新建用户必填，已有用户不允许修改）</td></tr>
          <tr><td><code>english_name</code></td><td>string</td><td><span class="tag-optional">否</span></td><td>英文名（新建用户可选，如未提供会自动生成；已有用户不允许修改）</td></tr>
          <tr><td><code>mapped_key</code></td><td>string</td><td><span class="tag-required">是</span></td><td>外部系统中的用户 ID（映射账号，1～100 字符；在该应用下唯一，可修改）。删除时须与平台记录一致</td></tr>
          <tr><td><code>mapped_email</code></td><td>string</td><td><span class="tag-optional">否</span></td><td>外部系统中的邮箱（在该应用下唯一，可修改）</td></tr>
          <tr><td><code>is_active</code></td><td>boolean</td><td><span class="tag-optional">否</span></td><td>映射关系状态（<code>true</code>启用，<code>false</code>禁用，可修改）</td></tr>
          <tr><td><code>sync_action</code></td><td>string</td><td><span class="tag-optional">否</span></td><td><code>UPSERT</code> (默认) 或 <code>DELETE</code></td></tr>
        </tbody>
      </table>

      <p><strong>请求示例 1: 新建用户 (UPSERT):</strong></p>
      <div class="code-block">
        <pre>
curl -X POST "http://your-uap-domain/api/v1/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: YOUR_APP_ACCESS_TOKEN" \
     -d '{
           "mobile": "13800138000",
           "name": "张三",
           "mapped_key": "user_1001",
           "mapped_email": "zhangsan@example.com",
           "sync_action": "UPSERT"
         }'
        </pre>
      </div>
      <p class="note">注意：<code>english_name</code> 可以不提供，系统会自动生成。</p>

      <p><strong>请求示例 2: 更新已有用户的映射信息 (UPSERT):</strong></p>
      <div class="code-block">
        <pre>
curl -X POST "http://your-uap-domain/api/v1/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: YOUR_APP_ACCESS_TOKEN" \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "mapped_email": "zhangsan_new@example.com",
           "is_active": true,
           "sync_action": "UPSERT"
         }'
        </pre>
      </div>
      <p class="note">注意：已有用户不能修改 <code>name</code>、<code>mobile</code>、<code>english_name</code>，只能修改映射信息。</p>

      <p><strong>请求示例 3: 删除映射 (DELETE):</strong></p>
      <div class="code-block">
        <pre>
curl -X POST "http://your-uap-domain/api/v1/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: YOUR_APP_ACCESS_TOKEN" \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "sync_action": "DELETE"
         }'
        </pre>
      </div>
    </div>

    <div class="section">
      <h3>3. 响应说明</h3>
      <p><strong>响应成功 (200 OK):</strong></p>
      <div class="code-block">
        <pre>
{
  "id": 123,
  "app_id": 1,
  "user_id": 456,
  "mapped_key": "user_1001",
  "mapped_email": "zhangsan@example.com",
  "user_mobile": "13800138000",
  "user_status": "ACTIVE",
  "is_active": true
}
        </pre>
      </div>

      <p><strong>响应失败:</strong></p>
      <ul>
        <li><code>400 Bad Request</code>: 
          <ul>
            <li>新建用户未提供 <code>name</code></li>
            <li>已有用户尝试修改 <code>name</code>、<code>mobile</code> 或 <code>english_name</code></li>
            <li><code>mapped_key</code> 或 <code>mapped_email</code> 已被其他用户占用</li>
          </ul>
        </li>
        <li><code>403 Forbidden</code>: Access Token 无效或过期。</li>
      </ul>
    </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>
