wmailhub/console/frontend/src/pages/Docs.tsx

/**
 * 文档页(/docs,v2.7.0):MCP 与 Console API(/api/v1)的使用说明。
 * 纯静态展示,接口地址按当前访问 origin 动态拼接;顶栏文档图标进入。
 */
import { Alert, Card, Space, Table, Tag, Typography } from "antd";
import { KeyOutlined, ApiOutlined, CodeOutlined } from "@ant-design/icons";

/** # 成员变量: 接口基地址与 MCP 端点(跟随当前访问域名) **/
const API_BASE = `${window.location.origin}/api/v1`;
const MCP_URL = `${window.location.origin}/api/v1/mcp`;

/** # 成员变量: MCP 工具清单(与 /api/v1/mcp tools/list 一致) **/
const MCP_TOOLS = [
  { name: "list_domains", params: "—", desc: "列出可用域名(创建邮箱的 domain_id 由此获取)" },
  { name: "list_mailboxes", params: "—", desc: "列出所有邮箱(域名、catch-all 标记、保留秒数)" },
  { name: "list_emails", params: "mailbox_id? / limit?", desc: "列出未过期邮件,limit 默认 20、最大 100" },
  { name: "get_email", params: "id", desc: "单封邮件详情(正文 + 附件元数据);过期邮件报错" },
  { name: "create_mailbox", params: "domain_id? / address / retention_seconds? / webhook?", desc: "创建邮箱;省略 domain_id 时随机分配一个已启用 Email Workers 的域名(address 须为本地部分)" },
  { name: "delete_mailbox", params: "id", desc: "删除邮箱" },
];

/** # 成员变量: REST API 端点清单(与 routes/apiv1.ts 一致) **/
const API_ENDPOINTS = [
  { method: "GET", path: "/accounts", desc: "账号列表(不含已撤销)" },
  { method: "GET", path: "/domains", desc: "域名列表" },
  { method: "GET", path: "/mailboxes", desc: "邮箱列表" },
  { method: "POST", path: "/mailboxes", desc: "创建邮箱,body: { address, domain_id?, retention_seconds?, webhook? };省略 domain_id 随机分配;409 已存在/无可用域名" },
  { method: "DELETE", path: "/mailboxes/:id", desc: "删除邮箱" },
  { method: "GET", path: "/emails", desc: "未过期邮件列表,query: mailbox_id? / limit / offset" },
  { method: "GET", path: "/emails/:id", desc: "邮件详情 + 附件元数据;410 已过期" },
];

/** # 函数
 * 方法名 -> 彩色 Tag
 */
function MethodTag({ method }: { method: string }) {
  const color = method === "GET" ? "blue" : method === "POST" ? "green" : "red";
  return <Tag color={color} style={{ fontFamily: "ui-monospace, Menlo, monospace", minWidth: 56, textAlign: "center" }}>{method}</Tag>;
}

/** # 函数
 * 文档页:认证说明 + MCP 接入(客户端配置、工具清单)+ REST API(端点清单、curl 示例)
 */
export function DocsPage() {
  return (
    <Space direction="vertical" size={16} style={{ width: "100%" }}>
      <Card
        title={
          <span>
            <KeyOutlined style={{ marginRight: 8 }} />
            认证
          </span>
        }
      >
        <Typography.Paragraph>
          Console API 与 MCP 共用同一个 <b>API/MCP Key</b>(<code className="mono">wmh_</code> 前缀):右上角头像 →{" "}
          <b>设置</b> → <b>API / MCP Key</b> 生成。明文仅在生成时显示一次;生成新 Key 后旧 Key 立即失效。
        </Typography.Paragraph>
        <Typography.Paragraph>
          所有请求携带请求头:<code className="mono">Authorization: Bearer wmh_xxxxxxxx</code>
        </Typography.Paragraph>
      </Card>

      <Card
        title={
          <span>
            <ApiOutlined style={{ marginRight: 8 }} />
            MCP 接入(Model Context Protocol)
          </span>
        }
      >
        <Typography.Paragraph>
          端点:<code className="mono">{MCP_URL}</code>(Streamable HTTP,JSON-RPC 2.0,协议版本 2025-06-18;仅接受
          POST,无 SSE 流)
        </Typography.Paragraph>
        <Typography.Paragraph style={{ marginBottom: 8 }}>MCP 客户端配置示例:</Typography.Paragraph>
        <pre className="docs-pre">{`{
  "mcpServers": {
    "wmailhub": {
      "type": "http",
      "url": "${MCP_URL}",
      "headers": { "Authorization": "Bearer wmh_你的Key" }
    }
  }
}`}</pre>
        <Table
          size="small"
          rowKey="name"
          style={{ marginTop: 8 }}
          pagination={false}
          columns={[
            { title: "工具", dataIndex: "name", width: 160, render: (v: string) => <code className="mono">{v}</code> },
            { title: "参数", dataIndex: "params", width: 260, render: (v: string) => <code className="mono">{v}</code> },
            { title: "说明", dataIndex: "desc" },
          ]}
          dataSource={MCP_TOOLS}
        />
      </Card>

      <Card
        title={
          <span>
            <CodeOutlined style={{ marginRight: 8 }} />
            REST API
          </span>
        }
      >
        <Typography.Paragraph>
          基地址:<code className="mono">{API_BASE}</code>
        </Typography.Paragraph>
        <Table
          size="small"
          rowKey="path"
          pagination={false}
          columns={[
            {
              title: "方法",
              dataIndex: "method",
              width: 90,
              render: (v: string) => <MethodTag method={v} />,
            },
            {
              title: "路径",
              dataIndex: "path",
              width: 220,
              render: (v: string) => <code className="mono">{v}</code>,
            },
            { title: "说明", dataIndex: "desc" },
          ]}
          dataSource={API_ENDPOINTS}
        />
        <Typography.Paragraph style={{ margin: "16px 0 8px" }}>curl 示例:</Typography.Paragraph>
        <pre className="docs-pre">{`# 列出邮箱
curl -H "Authorization: Bearer wmh_你的Key" ${API_BASE}/mailboxes

# 创建邮箱(保留 7 天)
curl -X POST -H "Authorization: Bearer wmh_你的Key" \\
  -H "Content-Type: application/json" \\
  -d '{"domain_id":"dom_xxx","address":"hello","retention_seconds":604800}' \\
  ${API_BASE}/mailboxes

# 最新 10 封未过期邮件
curl -H "Authorization: Bearer wmh_你的Key" "${API_BASE}/emails?limit=10"`}</pre>
      </Card>

      <Alert
        type="info"
        showIcon
        message="备注"
        description={
          <ul style={{ margin: 0, paddingLeft: 18 }}>
            <li>邮件读取强制检查未过期:列表不返回过期邮件,详情对已过期邮件返回 410 Gone。</li>
            <li>邮箱保留时长默认 86400 秒(1 天);catch-all 邮箱地址形如 <code className="mono">*@域名</code>。</li>
            <li>常见状态码:401 未认证(Key 缺失或已失效)、404 资源不存在、409 邮箱已存在、410 邮件已过期。</li>
          </ul>
        }
      />
    </Space>
  );
}