阿乌拉裁决系统-SDK

http://198.55.109.102:3000/ranking?round_id=novel2026_kuake

http://198.55.109.102:3000/ 这是阿乌拉裁决系统，如何把它做成sdk，给其他的web应用调用呢？

Aura Judgement System 本质是 前端（约 :3000）+ 自建 JSON API（默认同机 :8888）。要做成给其它 Web 应用调用的 SDK，应围绕 API 基址，而不是只包 :3000 的页面。

1. 先分清「页面」和「接口」

  • :3000：Vite 单页应用，负责 UI。
  • :8888（或你配置的 VITE_API_BASE）：真正干活的后端，路径都是 /api/...。

前端里写得很清楚：未配 VITE_API_BASE 时，会用 当前页面 host + :8888 作为 API 根地址（见 aura-judge-buddy/src/lib/apiClient.ts 里 resolveApiBase()）。

SDK 应对接的是「API 根 URL」（例如 http://198.55.109.102:8888），而不是 :3000 的根路径。

2. 现有能力：你其实已经有一半「SDK 素材」

aura-judge-buddy/src/lib/apiClient.ts + api.ts 已经封装了：

  • API_BASE、round_id 查询拼接（withRoundQuery 等）
  • 各类 fetch 封装与类型（JudgeResult、RankingItem、AuditReport 等）

做成 npm 包时，大致就是：

  • 抽成 @your-org/aura-client（或内网私有包）
  • 构造函数里传入 baseUrl + 可选 roundId + 可选 adminWallet（管理类接口才要 X-Admin-Wallet，见 rebuild_backend.go 里 adminWalletAuthorized）
  • 去掉 对 import.meta.env、window.localStorage 的硬依赖，改为由调用方注入配置（这样 Node/其它框架都能用）

后端注册的主要路由包括（节选）：GET/POST /api/audit、GET /api/ranking、GET /api/judge-result、GET /api/files、GET /api/rules/*、提交与轮次相关接口等（见 rebuild_backend.go 里 r.GET / r.POST 注册段）。

3. 集成形态（按场景选）

场景 做法
同域 BFF（推荐） 你的业务站 自己的后端 用 Node/Go 调 Aura http(s)://host:8888/api/...，浏览器只调你自己的 API。不暴露 Aura 到公网，也省 CORS。
浏览器直连 Aura 必须在 Aura 侧配置 AURA_CORS_ORIGINS，允许你的前端 Origin（rebuild_backend.go 里 CORS 中间件）。SDK 里用 fetch + credentials 按需。
只嵌入体验 iframe 打开 :3000 某页——实现快，但不是结构化 SDK，数据回传要另想办法。

4. 安全与产品化（上线给「别的应用」必做）

当前设计里：大量读接口 + 评审接口在代码层面并非「强 API Key 模型」；管理类删除等会校验 X-Admin-Wallet 是否与 AURA_ADMIN_WALLET 一致（未设置 AURA_ADMIN_WALLET 时管理校验会放宽，见 adminWalletAuthorized）。

给外部 Web 用时建议：

  • 公网只暴露 你自己的网关，网关校验 JWT / API Key，再转发到内网 Aura。
  • 或在 Aura 前加 Nginx + proxy_set_header + IP 白名单 / mTLS。

5. SDK 包里建议包含什么

  1. 配置：baseUrl、roundId?、fetchImpl?（便于测试）、adminWallet?、defaultTimeout?
  2. 方法：与现有前端一一对应，例如 audit()、getRanking()、getJudgeResult()、getRulesActive() 等（从 api.ts / apiClient.ts 抄方法签名即可）。
  3. 类型：导出 JudgeResult、RankingItem 等（已在 api.ts）。
  4. 文档：每个接口的 query/body、长耗时（如 /api/audit 可能很久）、错误 JSON 形态。
  5. 可选：用 OpenAPI 从 Gin 生成 spec，再生成多语言客户端（需要你们在仓库里加 swagger 注解或单独维护 spec）。

6. 小结

  • SDK = 对 http(s)://<aura-api-host>:8888 上 /api/* 的类型化 HTTP 客户端，可直接以现有 apiClient.ts / api.ts 为蓝本抽包。
  • :3000 只是演示/管理 UI，不必也不应作为 SDK 的唯一入口。
  • 跨站浏览器调用 要配 CORS；严肃对外 建议业务后端代理 + 鉴权。

如果你希望我直接在仓库里拆出一个 packages/aura-sdk 并写好 package.json 导出，需要切换到 Agent 模式（当前是 Ask 模式，我只能说明思路不能改代码）。