<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>
    <div class="revision-history">
      <h3>修订历史</h3>
      <ul>
        <li>
          <strong>2026-05-13</strong>：增补「修订历史」；补充
          <code>GET /api/v1/users/m2m/by-platform-id/{user_id}</code>
          的请求参数、返回字段说明与示例；映射同步成功响应补齐与后端 <code>MappingResponse</code> 一致的字段说明。
        </li>
      </ul>
    </div>

    <p class="intro">本文说明 M2M 相关能力：将外部业务系统（如 OA、CRM）的用户账号关系同步到本平台（映射增删改），以及按<strong>平台用户主键 ID</strong>查询用户详情。均使用应用 <code>X-App-Access-Token</code>，请在服务端调用，勿暴露给前端。</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,
  "new_user_created": false,
  "generated_password": null
}
        </pre>
      </div>
      <table class="param-table">
        <thead>
          <tr><th>字段</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr><td><code>id</code></td><td>映射记录主键</td></tr>
          <tr><td><code>app_id</code></td><td>应用数据库主键（整数）</td></tr>
          <tr><td><code>user_id</code></td><td>平台用户 ID，可作为 §4「按 ID 查询用户」的路径参数</td></tr>
          <tr><td><code>mapped_key</code> / <code>mapped_email</code></td><td>当前映射账号与邮箱</td></tr>
          <tr><td><code>user_mobile</code></td><td>用户手机号</td></tr>
          <tr><td><code>user_status</code></td><td>用户状态概要描述</td></tr>
          <tr><td><code>is_active</code></td><td>映射是否启用（DELETE 后为 <code>false</code>）</td></tr>
          <tr><td><code>new_user_created</code></td><td>本次请求是否新建了平台用户（UPSERT 时可能为 <code>true</code>）</td></tr>
          <tr><td><code>generated_password</code></td><td>若平台为新用户生成了初始密码则可能返回；否则多为 <code>null</code></td></tr>
        </tbody>
      </table>

      <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 class="section">
      <h3>4. 按平台用户 ID 查询用户（M2M）</h3>
      <p>当业务侧已保存统一认证平台的用户主键（例如同步映射响应中的 <code>user_id</code>、或一键登录校验结果中的平台 <code>user_id</code>），可通过本接口拉取该用户在平台上的公开档案字段。<strong>路径中的 ID 是平台 <code>users</code> 表主键，不是外部系统的 <code>mapped_key</code>。</strong>按手机号或关键词查找请仍使用 <code>GET /api/v1/users/search</code>。</p>

      <ul>
        <li><strong>方法与地址</strong>: <code>GET /api/v1/users/m2m/by-platform-id/{user_id}</code></li>
        <li><strong>认证</strong>: 请求头 <code>X-App-Access-Token</code>，值与应用详情中的永久 Access Token（库表 <code>Application.access_token</code>）一致。</li>
        <li><strong>限制</strong>: 仅接受<strong>应用</strong>凭证。若请求里带有有效的用户 JWT（<code>Authorization: Bearer</code> 且会先被识别为用户），将返回 <code>403</code>「仅支持应用凭证访问」——服务端调用时请避免同时携带业务用户 Bearer，或勿带 <code>Authorization</code>。</li>
        <li><strong>与 <code>/auth/app-token</code> 的区别</strong>: 客户端凭证换发的 Bearer JWT（<code>sub</code> 形如 <code>app:123</code>）<strong>不能</strong>替代本接口所需的 <code>X-App-Access-Token</code>。</li>
        <li><strong>可见性</strong>: 仅当用户 <code>status=ACTIVE</code> 且未删除（<code>is_deleted=0</code>）时返回 200；否则 404。</li>
      </ul>

      <h4>4.1 请求参数</h4>
      <table class="param-table">
        <thead>
          <tr><th>位置</th><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr><td>Path</td><td><code>user_id</code></td><td>integer</td><td><span class="tag-required">是</span></td><td>平台用户主键 ID（正整数）</td></tr>
          <tr><td>Header</td><td><code>X-App-Access-Token</code></td><td>string</td><td><span class="tag-required">是</span></td><td>应用 M2M 永久访问令牌</td></tr>
        </tbody>
      </table>

      <p><strong>请求示例:</strong></p>
      <div class="code-block">
        <pre>
curl -X GET "http://your-uap-domain/api/v1/users/m2m/by-platform-id/456" \
     -H "X-App-Access-Token: YOUR_APP_ACCESS_TOKEN"
        </pre>
      </div>

      <h4>4.2 响应说明（HTTP 200）</h4>
      <p>响应体为用户对象（与开放 API 中的用户模型一致），<strong>不包含密码</strong>。</p>
      <table class="param-table">
        <thead>
          <tr><th>字段</th><th>类型</th><th>说明</th></tr>
        </thead>
        <tbody>
          <tr><td><code>id</code></td><td>integer</td><td>平台用户主键</td></tr>
          <tr><td><code>mobile</code></td><td>string</td><td>手机号</td></tr>
          <tr><td><code>name</code></td><td>string | null</td><td>姓名</td></tr>
          <tr><td><code>english_name</code></td><td>string | null</td><td>英文名</td></tr>
          <tr><td><code>organization_id</code></td><td>integer | null</td><td>所属组织 ID</td></tr>
          <tr><td><code>organization_name</code></td><td>string | null</td><td>所属组织名称（关联展开）</td></tr>
          <tr><td><code>status</code></td><td>string</td><td>用户状态，本接口成功时恒为 <code>ACTIVE</code></td></tr>
          <tr><td><code>role</code></td><td>string | null</td><td>角色，如 <code>ORDINARY_USER</code></td></tr>
          <tr><td><code>is_deleted</code></td><td>integer</td><td>软删除标记，成功时恒为 <code>0</code></td></tr>
          <tr><td><code>created_at</code></td><td>string (ISO 8601)</td><td>创建时间</td></tr>
          <tr><td><code>updated_at</code></td><td>string (ISO 8601)</td><td>更新时间</td></tr>
        </tbody>
      </table>

      <p><strong>响应示例 (200 JSON):</strong></p>
      <div class="code-block">
        <pre>
{
  "id": 456,
  "mobile": "13800138000",
  "name": "张三",
  "english_name": "zhangsan",
  "organization_id": 10,
  "organization_name": "研发部",
  "status": "ACTIVE",
  "role": "ORDINARY_USER",
  "is_deleted": 0,
  "created_at": "2025-01-10T08:00:00",
  "updated_at": "2025-06-01T12:00:00"
}
        </pre>
      </div>

      <p><strong>常见错误:</strong></p>
      <ul>
        <li><code>401 Unauthorized</code>：缺少或错误的 <code>X-App-Access-Token</code>。</li>
        <li><code>403 Forbidden</code>：未以应用凭证访问（例如仅带用户 JWT）。</li>
        <li><code>404 Not Found</code>：该 <code>user_id</code> 不存在，或用户已删除 / 非 <code>ACTIVE</code>。</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';

.revision-history {
  margin-bottom: 20px;
  padding: 12px 16px;
  background: #fdf6ec;
  border-radius: 4px;
  border-left: 4px solid #e6a23c;
}

.revision-history h3 {
  margin-top: 0;
  margin-bottom: 10px;
  font-size: 16px;
  color: #303133;
  font-weight: 600;
  border-left: none;
  padding-left: 0;
}

.revision-history ul {
  margin-bottom: 0;
  padding-left: 22px;
}
</style>
