多软件多语言版本发布中心 API

APay 在核心数据库层（SQLite / PostgreSQL / MySQL 三方言对齐的 releases 表）提供统一的多软件版本发布与升级检查底座，适用于 shoply、qingpu-ai、hoxi-desktop、codex、goray、gopanel 及任意自定义软件标识（appKey）的版本分发。

核心特性：

• 多软件与多发布通道隔离：通过 (app_key, channel, version) 唯一约束隔离不同软件及通道（stable 稳定版、beta 测试版、rc 候选版、nightly 每夜构建）。
• 7 语言结构化更新日志 (locales)：原生支持 zh、en、zh-TW、zh-HK、ru、ja、ko，内置多语言自动回退链（zh-HK -> zh-TW -> zh -> en；其他语种 -> en -> zh）。每个语种支持配置 title、summary、body 以及结构化变更项 items（feat、fix、perf、ui、ops、security、breaking）。
• 多平台安装包矩阵 (assets)：单个版本可挂载多个系统架构的安装包（macos、windows、linux、chrome、container、android、ios），包含 arch、package、size、sha256 校验值与多节点镜像 mirrors。
• 问题版本撤回与自动回滚 (withdrawn_at)：当某个已发布版本发现严重缺陷被标记撤回后，公开列表自动隐藏该版本；若客户端当前正运行该已撤回版本，升级检查接口会返回 isRollbackTarget: true 与上一个健康稳定版安装包，引导客户端安全回滚。

公开与客户端接口

1. 获取版本发布列表 (GET /api/releases)

按软件标识、通道与目标语言返回版本时间线及最新可用版本。

Query 参数

成功响应 (200)

{
  "code": 0,
  "msg": "ok",
  "appKey": "shoply",
  "channel": "stable",
  "lang": "zh",
  "latest": {
    "id": 1,
    "appKey": "shoply",
    "channel": "stable",
    "version": "1.8.0",
    "versionCode": 1008000,
    "tag_name": "v1.8.0",
    "title": "Shoply 1.8.0 稳定版",
    "summary": "新增一键迁移与多语言 SEO 路由",
    "body": "- 新增一键迁移\n- 修复多币种精度",
    "items": [
      { "type": "feat", "text": "新增一键迁移" },
      { "type": "fix", "text": "修复多币种精度" }
    ],
    "assets": [
      {
        "name": "ghcr.io/shoply/shoply:1.8.0",
        "platform": "container",
        "arch": "universal",
        "package": "container",
        "browser_download_url": "https://downloads.shoply.example/shoply-1.8.0.tar.gz",
        "size": 104857600,
        "sha256": "..."
      }
    ],
    "mandatory": false,
    "releasedAt": "2026-10-20T00:00:00.000Z"
  },
  "releases": []
}

2. 客户端升级与回滚检查 (GET /api/releases/check)

供桌面端、浏览器插件、容器 Agent 或 CLI 检查当前版本是否需要更新。系统会自动跳过已撤回版本，并仅匹配包含当前客户端对应 (platform, arch, package) 安装包的版本（例如 1.3.0 仅发布了 macOS 包时，Windows 客户端检查更新会精确命中含 Windows 包的 1.2.0）。

Query 参数

成功响应 (200)

{
  "code": 0,
  "msg": "ok",
  "data": {
    "appKey": "qingpu-ai",
    "channel": "stable",
    "lang": "zh",
    "currentVersion": "1.2.0",
    "currentVersionCode": 1002000,
    "needUpdate": true,
    "hasUpdate": true,
    "isRollbackTarget": false,
    "mandatory": false,
    "latestVersion": "1.3.0",
    "latestVersionCode": 1003000,
    "downloadUrl": "https://cdn.qingpu.example/Qingpu-1.3.0-arm64.dmg",
    "sha256": "...",
    "size": 94371840,
    "appcastUrl": "/api/releases/appcast.xml?app=qingpu-ai&channel=stable&lang=zh",
    "asset": {
      "name": "Qingpu-1.3.0-arm64.dmg",
      "platform": "macos",
      "arch": "arm64",
      "package": "desktop",
      "browser_download_url": "https://cdn.qingpu.example/Qingpu-1.3.0-arm64.dmg",
      "size": 94371840
    },
    "release": {
      "version": "1.3.0",
      "title": "擎蒲 1.3.0",
      "summary": "macOS 专项性能优化"
    }
  }
}

3. Sparkle 2.x / WinSparkle Appcast 自动更新源 (GET /api/releases/appcast.xml)

为 macOS 原生客户端（Sparkle 2）与 Windows 原生客户端（WinSparkle / NetSparkle）生成标准的 RSS 2.0 + xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" 自动更新 XML 订阅源（同时兼容 /api/releases/appcast）：

• 支持参数：?app=<appKey>&channel=stable&lang=zh&platform=macos&arch=arm64&limit=20；
• 自动根据 ?lang= 将多语言 summary 与 items 渲染为结构化 HTML 放入 <description><![CDATA[...]]></description>；
• 自动映射 <sparkle:version>（versionCode）、<sparkle:shortVersionString>（version）、<sparkle:criticalUpdate />（当 mandatory: true 或设定了 minUpgradeVersion）、<sparkle:minimumSystemVersion> 以及 <enclosure sparkle:os="..." sparkle:nativeArchitecture="..." sparkle:edSignature="..." />；
• 自动剔除已撤回（withdrawn_at）或未生效版本。

4. Tauri v1 / v2 自动更新清单 (GET /api/releases/check?format=tauri)

当传入 ?format=tauri 时，接口直接返回 Tauri Updater 标准 JSON 清单（{ version, notes, pub_date, platforms }），自动将 APay 安装包列表中的 (platform, arch) 映射为 darwin-aarch64、darwin-x86_64、windows-x86_64、linux-x86_64 等标准键；若同时传入了客户端当前版本 version 且无需更新，则按 Tauri 规范返回 HTTP 204 No Content。

发版流水线 / AI Agent 与管理后台接口

1. 基于 APAY_RELEASE_KEY 的统一发布接口 (POST /api/releases 与 POST /api/releases/publish)

统一读取环境变量 APAY_RELEASE_KEY=""，通过请求头 Authorization: Bearer <APAY_RELEASE_KEY> 或 x-release-key: <APAY_RELEASE_KEY> 进行常量时间安全比对鉴权：

• 发布或幂等更新版本：传入 appKey、appName、channel、version、locales、assets、mandatory、minUpgradeVersion、isActive、releasedAt（支持传 dryRun: true 进行不写库的演练校验），每次发布均自动记录管理员操作审计日志（operation_logs）；
• 管理态操作（save_app、delete_app、withdraw、restore、seed_bundled）：统一收口至 /api/admin/releases（同样支持 Authorization: Bearer <APAY_RELEASE_KEY> 鉴权并写入审计日志）。

2. 管理后台接口 (/api/admin/releases)

所有 /api/admin/releases/** 接口均受后台管理员鉴权（releases 权限模块）或 APAY_RELEASE_KEY 请求头保护，对应后台管理页面 /admin/releases。

• GET /api/admin/releases：支持按 appKey、channel、status（all / published / withdrawn / draft）及关键词分页检索，并返回各软件版本统计卡片数据（data.apps）。
• POST /api/admin/releases：
  • 创建或幂等更新指定软件版本（支持传入多语言 locales、多平台 assets、mandatory、minUpgradeVersion、isActive、releasedAt）；
  • 支持传入 { "action": "seed_bundled", "appKey": "all" } 将仓库内置的 JSON 历史版本一键幂等同步入库。
• PUT /api/admin/releases/:id：编辑指定版本记录的多语言更新说明或安装包列表。
• PATCH /api/admin/releases/:id/status：快速切换版本状态（如撤回问题版本 { "status": "withdrawn" } 或恢复上架 { "status": "published" }）。
• DELETE /api/admin/releases/:id：删除指定版本记录。