{% extends "admin/base.html" %}
{% load i18n static %}

{% block title %}{{ title }} - {{ site_header }}{% endblock %}

{% block extrastyle %}
{{ block.super }}
<style>
    .api-doc { max-width: 1000px; margin: 20px auto; }
    .api-section { background: #fff; border: 1px solid #ddd; border-radius: 4px; margin-bottom: 20px; }
    .api-section h2 { background: #417690; color: white; padding: 12px 15px; margin: 0; font-size: 16px; }
    .api-section .content { padding: 15px; }
    .endpoint-table { width: 100%; border-collapse: collapse; }
    .endpoint-table th, .endpoint-table td { text-align: left; padding: 10px; border-bottom: 1px solid #eee; }
    .endpoint-table th { background: #f5f5f5; font-weight: bold; }
    .endpoint-table code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
    .method-badge { display: inline-block; padding: 3px 8px; border-radius: 3px; font-size: 12px; font-weight: bold; color: white; }
    .method-get { background: #28a745; }
    .method-post { background: #007bff; }
    .method-put { background: #fd7e14; }
    .method-patch { background: #6f42c1; }
    .method-delete { background: #dc3545; }
    .auth-yes { color: #28a745; }
    .auth-no { color: #999; }
    .code-block { background: #1e1e1e; color: #d4d4d4; padding: 15px; border-radius: 4px; font-family: 'Consolas', monospace; font-size: 13px; overflow-x: auto; white-space: pre; }
    .example-block { margin: 10px 0; }
    .example-block h4 { margin: 10px 0 5px; color: #417690; font-size: 14px; }
    .error-table { width: 100%; }
    .error-table td { padding: 8px; border-bottom: 1px solid #eee; }
    .error-code { font-weight: bold; color: #dc3545; }
    .error-desc { color: #666; }
    .note-box { background: #e7f3ff; border-left: 4px solid #007bff; padding: 10px 15px; margin: 10px 0; }
</style>
{% endblock %}

{% block breadcrumbs %}
<div class="breadcrumbs">
    <a href="{% url 'admin:index' %}">{% trans 'Home' %}</a> &rsaquo;
    API 使用帮助
</div>
{% endblock %}

{% block content %}
<div class="api-doc">
    <h1>📖 API 使用帮助</h1>
    <p class="note-box">本页面提供完整的 API 文档，包括端点说明、认证流程、请求响应示例和错误处理。</p>

    <!-- Authentication Section -->
    <div class="api-section">
        <h2>🔐 认证流程</h2>
        <div class="content">
            <p>API 使用 JWT (JSON Web Token) 进行认证。访问受保护的端点需要在请求头中包含令牌。</p>

            <div class="example-block">
                <h4>1. 获取令牌</h4>
                <p>在 <a href="{% url 'admin:api_token' %}">获取访问令牌</a> 页面生成您的个人令牌。</p>
            </div>

            <div class="example-block">
                <h4>2. 在请求中使用令牌</h4>
                <div class="code-block">Authorization: Bearer YOUR_ACCESS_TOKEN</div>
            </div>

            <div class="example-block">
                <h4>3. 令牌过期处理</h4>
                <p>Access Token 过期后，使用 Refresh Token 获取新令牌：</p>
                <div class="code-block">curl -X POST "https://example.com/api/auth/token/refresh/" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'</div>
            </div>
        </div>
    </div>

    <!-- Endpoints Section -->
    <div class="api-section">
        <h2>📡 API 端点</h2>
        <div class="content">
            <table class="endpoint-table">
                <thead>
                    <tr>
                        <th>端点</th>
                        <th>方法</th>
                        <th>认证</th>
                        <th>描述</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>/api/posts/</code></td>
                        <td>
                            <span class="method-badge method-get">GET</span>
                            <span class="method-badge method-post">POST</span>
                        </td>
                        <td><span class="auth-yes">需要</span></td>
                        <td>列出所有文章 / 创建新文章</td>
                    </tr>
                    <tr>
                        <td><code>/api/posts/{id}/</code></td>
                        <td>
                            <span class="method-badge method-get">GET</span>
                            <span class="method-badge method-put">PUT</span>
                            <span class="method-badge method-patch">PATCH</span>
                            <span class="method-badge method-delete">DELETE</span>
                        </td>
                        <td><span class="auth-yes">需要</span></td>
                        <td>获取 / 更新 / 删除单篇文章</td>
                    </tr>
                    <tr>
                        <td><code>/api/categories/</code></td>
                        <td><span class="method-badge method-get">GET</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>列出所有分类</td>
                    </tr>
                    <tr>
                        <td><code>/api/tags/</code></td>
                        <td><span class="method-badge method-get">GET</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>列出所有标签</td>
                    </tr>
                    <tr>
                        <td><code>/api/auth/token/</code></td>
                        <td><span class="method-badge method-post">POST</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>获取 JWT 令牌（用户名密码）</td>
                    </tr>
                    <tr>
                        <td><code>/api/auth/token/refresh/</code></td>
                        <td><span class="method-badge method-post">POST</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>刷新 JWT 令牌</td>
                    </tr>
                    <tr>
                        <td><code>/api/auth/token/verify/</code></td>
                        <td><span class="method-badge method-post">POST</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>验证 JWT 令牌</td>
                    </tr>
                    <tr>
                        <td><code>/api/health/</code></td>
                        <td><span class="method-badge method-get">GET</span></td>
                        <td><span class="auth-no">否</span></td>
                        <td>服务存活 + DB ping（200 / 503，<code>Cache-Control: no-store</code>）</td>
                    </tr>
                    <tr>
                        <td><code>/api/me/</code></td>
                        <td><span class="method-badge method-get">GET</span></td>
                        <td><span class="auth-yes">需要</span></td>
                        <td>身份自检：<code>{id, username, email, is_staff, token_exp}</code>（<code>token_exp</code> ISO-8601）</td>
                    </tr>
                </tbody>
            </table>
        </div>
    </div>

    <!-- Request Examples -->
    <div class="api-section">
        <h2>💻 请求示例</h2>
        <div class="content">
            <div class="example-block">
                <h4>获取文章列表</h4>
                <div class="code-block">curl -X GET "https://example.com/api/posts/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"</div>
            </div>

            <div class="example-block">
                <h4>获取单篇文章</h4>
                <div class="code-block">curl -X GET "https://example.com/api/posts/1/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"</div>
            </div>

            <div class="example-block">
                <h4>创建文章</h4>
                <div class="code-block">curl -X POST "https://example.com/api/posts/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "文章标题",
    "content": "文章内容...",
    "status": "published"
  }'</div>
            </div>

            <div class="example-block">
                <h4>更新文章</h4>
                <div class="code-block">curl -X PATCH "https://example.com/api/posts/1/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "更新后的标题"}'</div>
            </div>

            <div class="example-block">
                <h4>删除文章</h4>
                <div class="code-block">curl -X DELETE "https://example.com/api/posts/1/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"</div>
            </div>

            <div class="example-block">
                <h4>健康检查（无需令牌）</h4>
                <div class="code-block">curl -X GET "https://example.com/api/health/"
# 200 OK：{"version":"1.0","status":"ok","db":"ok","django_version":"3.2.x","timestamp":"..."}
# 503 ：{"version":"1.0","status":"degraded","db":"error",...}</div>
            </div>

            <div class="example-block">
                <h4>身份自检（验证令牌是否可用）</h4>
                <div class="code-block">curl -X GET "https://example.com/api/me/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# {"version":"1.0","id":1,"username":"admin","email":"...","is_staff":true,"token_exp":"2026-06-02T12:34:56+00:00"}</div>
            </div>
        </div>
    </div>

    <!-- Response Format -->
    <div class="api-section">
        <h2>📦 响应格式</h2>
        <div class="content">
            <p>所有响应均为 JSON 格式。</p>

            <div class="example-block">
                <h4>成功响应</h4>
                <div class="code-block">{
  "id": 1,
  "title": "文章标题",
  "content": "文章内容...",
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com"
  },
  "status": "published",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}</div>
            </div>

            <div class="example-block">
                <h4>分页响应</h4>
                <div class="code-block">{
  "count": 100,
  "next": "https://example.com/api/posts/?page=2",
  "previous": null,
  "results": [...]
}</div>
            </div>

            <div class="example-block">
                <h4>错误响应</h4>
                <div class="code-block">{
  "detail": "Authentication credentials were not provided."
}</div>
            </div>
        </div>
    </div>

    <!-- Error Codes -->
    <div class="api-section">
        <h2>⚠️ 错误码</h2>
        <div class="content">
            <table class="error-table">
                <tr>
                    <td class="error-code">401 Unauthorized</td>
                    <td class="error-desc">未提供认证凭证或令牌已过期</td>
                </tr>
                <tr>
                    <td class="error-code">403 Forbidden</td>
                    <td class="error-desc">无权执行此操作</td>
                </tr>
                <tr>
                    <td class="error-code">404 Not Found</td>
                    <td class="error-desc">请求的资源不存在</td>
                </tr>
                <tr>
                    <td class="error-code">503 Service Unavailable</td>
                    <td class="error-desc">服务不可用（如数据库失联，详见 <code>/api/health/</code>）</td>
                </tr>
                <tr>
                    <td class="error-code">500 Server Error</td>
                    <td class="error-desc">服务器内部错误</td>
                </tr>
            </table>
        </div>
    </div>

    <!-- Quick Links -->
    <div class="api-section">
        <h2>🔗 快速链接</h2>
        <div class="content">
            <p>
                <a href="{% url 'admin:api_token' %}" class="bg-blue-600 text-white px-4 py-2 rounded inline-block">
                    🔑 获取访问令牌
                </a>
            </p>
        </div>
    </div>
</div>
{% endblock %}