ystp/frontend/src/pages/DocsPage.vue

<template>
  <div class="space-y-6">
    <div class="space-y-1">
      <h1 class="text-2xl font-semibold tracking-tight text-slate-900">开发者</h1>
      <p class="text-sm text-slate-600">完整 API 调用说明与示例，适合直接集成到服务端或脚本。</p>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">快速开始</div>
      <ol class="mt-2 list-decimal space-y-1 pl-5">
        <li>登录后在控制台创建 API Key（仅 Pro/Business）。</li>
        <li>使用 <code>X-API-Key</code> 调用压缩接口。</li>
        <li>建议为每次请求设置 <code>Idempotency-Key</code>，避免重复扣费。</li>
      </ol>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">基础信息</div>
      <ul class="mt-2 list-disc space-y-1 pl-5">
        <li>Base URL：<code>https://ys.workyai.cn/api/v1</code></li>
        <li>认证方式：<code>X-API-Key</code>（推荐）或 <code>Authorization: Bearer &lt;token&gt;</code></li>
        <li>支持格式：PNG / JPG / JPEG / WebP / AVIF / GIF（静态）/ BMP / TIFF / ICO</li>
        <li>压缩率：<code>compression_rate</code> 1-100，表示压缩后体积占原图比例，100 为不压缩</li>
        <li>计量：成功压缩 1 个文件计 1 次；若体积未变小或压缩率为 100，则不扣额度</li>
      </ul>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">同步压缩（返回 JSON + 下载链接）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress</code>，表单字段：<code>file</code>、<code>compression_rate</code>、
        <code>max_width</code>、<code>max_height</code>、<code>preserve_metadata</code>
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \\
  -H \"X-API-Key: if_live_xxx\" \\
  -F \"file=@./demo.jpg\" \\
  -F \"compression_rate=20\" \\
  -F \"max_width=2000\" \\
  https://ys.workyai.cn/api/v1/compress</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        返回字段包含 <code>download_url</code>、<code>saved_percent</code> 与 <code>billing.units_charged</code>。
      </div>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">同步压缩（直接返回二进制）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress/direct</code>，响应头包含原/压缩大小与扣费信息。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \\
  -H \"X-API-Key: if_live_xxx\" \\
  -F \"file=@./demo.jpg\" \\
  -F \"compression_rate=20\" \\
  https://ys.workyai.cn/api/v1/compress/direct -o out.jpg -D headers.txt</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        重点响应头：<code>ImageForge-Original-Size</code>、
        <code>ImageForge-Compressed-Size</code>、
        <code>ImageForge-Units-Charged</code>
      </div>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">批量压缩（异步任务）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress/batch</code>，上传多文件后返回任务 ID。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \\
  -H \"X-API-Key: if_live_xxx\" \\
  -F \"files[]=@./a.jpg\" \\
  -F \"files[]=@./b.jpg\" \\
  -F \"compression_rate=30\" \\
  https://ys.workyai.cn/api/v1/compress/batch</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        轮询任务：<code>GET /compress/tasks/&lt;task_id&gt;</code>，响应包含每个文件的 <code>download_url</code> 和 <code>download_all_url</code>（ZIP）。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -H \"X-API-Key: if_live_xxx\" \\
  https://ys.workyai.cn/api/v1/compress/tasks/550e8400-e29b-41d4-a716-446655440200</code></pre>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">下载文件</div>
      <div class="mt-2 text-xs text-slate-500">
        下载地址不在 <code>/api/v1</code> 下，需带同样的认证头。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -H \"X-API-Key: if_live_xxx\" \\
  -L https://ys.workyai.cn/downloads/&lt;file_id&gt; -o result.jpg

curl -H \"X-API-Key: if_live_xxx\" \\
  -L https://ys.workyai.cn/downloads/tasks/&lt;task_id&gt; -o batch.zip</code></pre>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">错误处理与常见问题</div>
      <ul class="mt-2 list-disc space-y-1 pl-5">
        <li><code>INVALID_REQUEST</code>：参数或文件不合法（检查格式与字段）</li>
        <li><code>QUOTA_EXCEEDED</code>：额度不足（升级套餐或等待周期重置）</li>
        <li><code>FORBIDDEN</code>：无权限下载该任务/文件（认证不一致）</li>
        <li><code>EMAIL_NOT_VERIFIED</code>：登录用户需先完成邮箱验证</li>
      </ul>
    </div>

    <div class="text-sm text-slate-600">
      更完整的字段与响应说明请查看仓库文档：<code>docs/api.md</code>。
    </div>
  </div>
</template>