内容发布接口文档

通过本接口，已授权的服务端应用可以查询和发布官网知识库文章与资讯，并查询知识库页面的访问统计。新增内容直接发布到 COS 内容快照，经官网现有接口和页面对外提供。

1. 接口一览与凭证

生产 API 地址：https://project.xiaotunqifu.com。请求使用 HTTPS、POST 和 Content-Type: application/json。

所有接口使用同一套凭证：分配的 KNOWLEDGE_RELEASE_SECRET_ID 和 KNOWLEDGE_RELEASE_SECRET_KEY。Secret Key 是 64 位十六进制字符串，解码为 32 字节密钥。凭证应在调用方服务端配置；网页端不需要持有凭证。

2. 加密、鉴权与解密（所有接口通用）

请求和成功响应使用 AES-256-GCM。UTF-8 编码的 JSON 为明文，每次加密生成新的 12 字节随机 IV，认证标签为 16 字节。iv、ciphertext、tag 使用标准 Base64 编码（带 padding），标签独立于密文。

请求 JSON 包含以下字段：

附加认证数据 AAD 是以下各行用 \n 连接后的 UTF-8 字节，末尾没有换行。path 为第 1 节表中本次调用的完整路径，不包含域名、查询参数或末尾斜杠；每个接口的 AAD 绑定各自路径，为一个接口加密的请求不能用于另一个接口：

BW-RELEASE-V1
request
POST
{path}
{secretId}
{timestamp}
{nonce}

成功响应为 {"code":0,"status":200,"data":{...加密信封...}}。取出 data，使用同一密钥解密；AAD 第二行改为 response，时间戳使用响应中的值，其余规则相同。响应 nonce 与本次请求一致。必须校验 GCM tag，并确认 Secret ID、nonce 和时间戳后再使用结果。HTTP 错误返回未加密的错误对象，含 message 和 status。

每个 nonce 仅可使用一次。超时或重试时重新生成 nonce、时间戳和 IV，文章 ID 与文章内容保持一致。Node.js Crypto 文档提供 GCM、AAD 和认证标签的实现说明。

3. 错误处理（所有接口通用）

4. 知识库文章列表 POST /api/openapi/knowledge/list

入参（加密前的 JSON）：

{"page":1,"size":20}

解密后返回 version、page、size、total 和 records。每条记录包含 id、routeSlug、aliases、hash 及 zh、en 元数据（标题、摘要、分类、标签、更新时间），列表不含正文。中文地址为 /faq/{routeSlug}，英文地址为 /en/faq/{routeSlug}。

5. 新增知识库文章 POST /api/openapi/knowledge/create

入参：

{
  "id": "faq-api-crm-approval-guide",
  "zh": {
    "q": "CRM 审批流程如何设计？",
    "summary": "从审批角色、权限和记录追溯规划 CRM 审批。",
    "category": "软件定制",
    "tags": ["CRM", "审批流程"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## 审批角色\n\n先确定发起人、审批人和可见范围。"
  },
  "en": {
    "q": "How to design CRM approval workflows",
    "summary": "Plan approval roles, permissions and an auditable history for your CRM.",
    "category": "Custom Software",
    "tags": ["CRM", "Approvals"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## Approval roles\n\nDefine who submits, who approves and who can view each request."
  }
}

本接口提供新增功能。相同 ID、相同内容可安全重试；相同 ID、不同内容返回 409；URL 与现有文章或专题冲突时返回 409。

成功解密后的结果示例：

{
  "id": "faq-api-crm-approval-guide",
  "version": "64位发布版本摘要",
  "created": true,
  "published": true,
  "status": "complete",
  "pending": [],
  "urls": {
    "zh": "/faq/how-to-design-crm-approval-workflows",
    "en": "/en/faq/how-to-design-crm-approval-workflows"
  }
}

published: true 表示 COS 已发布；status: complete 表示搜索与网页缓存同步完成。status: pending 时，pending 会包含 search 或 website-cache，可再次提交相同文章恢复同步。重复提交时 created: false。若请求超时或返回 503，发布结果可能尚不确定，同样使用原 ID 和原内容重试。

6. 知识库访问统计 POST /api/openapi/knowledge/statistics

查询官网 boilingwater.cn 知识库页面在所选时间段内的访问表现，中文和英文路径分别统计。

入参（传入 {} 使用默认条件）：

返回示例（解密后）：

{
  "generatedAt": "2026-09-27T02:00:00.000Z",
  "site": "boilingwater.cn",
  "timezone": "Asia/Shanghai",
  "startDate": "2026-09-24",
  "endDate": "2026-09-26",
  "startedAt": "2026-09-01T01:00:00.000Z",
  "visitorsStartedAt": "2026-09-23T01:00:00.000Z",
  "visitorsComplete": true,
  "page": 1,
  "size": 10,
  "sortBy": "views",
  "sortOrder": "desc",
  "total": 1,
  "totalPages": 1,
  "records": [{
    "path": "/faq/example", "title": "示例文章", "locale": "zh",
    "views": 12, "visitors": 8, "durationMs": 240000, "averageMs": 20000
  }]
}

total 是筛选后的页面数；超过总页数返回空 records。先聚合完整日期范围，再筛选、排序、分页；同分按路径排序，缺失指标始终排在最后。统计会随访问继续更新，跨页查询不是冻结快照。

访问量来自官网浏览器统计采集，不合并旧版文章访问计数；心跳和重试不会增加访问量。停留时间只累计页面可见时上报的时长，按访问开始日归属；averageMs = durationMs / views，四舍五入到毫秒，没有访问样本时为 null。统计包含已采集的全部流量，未进行机器人过滤。

visitors 按浏览器标识跨所选日期去重，同一访客在同一页面多次访问只计一次；它不等于实名人数，也不能通过累加不同页面访客数得到全站人数。页面人数从本功能上线后的采集起点开始记录；visitorsStartedAt 为起点，无采集时为 null。若查询包含起点当日或更早日期，visitorsComplete=false 且 visitors=null，历史缺失不作零处理。选择起点之后的完整日期范围可按人数比较；今天的数据仍会增长。startedAt 为整体浏览器统计采集起点，早于该起点的数据不完整。

本接口仅返回时间段内有采集记录的知识库路径，可能包含曾经访问的历史页面，不代表当前已发布文章清单。需要文章元数据时另用 list。筛选字段非法返回 HTTP 400；日期范围非法返回 HTTP 422。查询不会发布或修改文章。

7. 资讯列表 POST /api/openapi/news/list

分页查询官网资讯（资讯中心）元数据，按 createTime 与 id 倒序。

入参：

解密后返回 version、page、size、total 和 records。每条记录为一条资讯的元数据：id、title、description、image、type、flag、status、siteStatus、siteHiddenStatus、wxStatus、appStatus、createTime、updateTime、labels，以及可选的 url、feedId、contentType 等历史字段；列表不含正文 content。flag=0 的记录为已删除（保留但不展示），status=0 为已撤下列表。

8. 新增资讯 POST /api/openapi/news/create

入参：

{
  "id": "8001790000000000000",
  "type": 1,
  "title": "【今日资讯】示例主标题",
  "description": "本期 5 条，覆盖平台规则与产品动态。",
  "image": "https://file.boilingwater.cn/website/news/2026-09-27-example-cover.png",
  "labels": ["日资讯"],
  "markdown": "## 主资讯\n\n正文内容。"
}

本接口提供新增功能。相同 ID、相同内容可安全重试（返回 created: false）；相同 ID、不同内容返回 409；正在发布时返回 409，稍后用相同内容重试。请求超时或返回 503 时发布结果可能尚不确定，使用原 ID 和原内容重试。

成功解密后的结果示例：

{
  "id": "8001790000000000000",
  "version": "64位快照版本摘要",
  "created": true,
  "published": true,
  "urls": { "zh": "/article/8001790000000000000/1", "en": "/en/article/8001790000000000000/1" },
  "record": { "id": "8001790000000000000", "title": "…", "content": "<h2>主资讯</h2>…" }
}

urls 规则：type 1/2/3 为 /article/{id}/{type}，type 4 为 /info/{id}；英文地址加 /en 前缀。record 是完整入库记录（含转换后的 HTML 正文）。

发布后须知：

• 资讯写入 COS 快照后与既有资讯内容同源，运行中的 Server 最迟约 30 秒自动刷新，经 /api/news 与资讯中心页面对外提供；官网 sitemap 动态读取资讯接口，无需额外更新。
• 如需保留仓库源文件备份，将返回的 record 保存为 website/src/content/news/{id}.json（该目录为资讯源文件备份目录）。
• 本接口只新增；修改状态（撤稿、撤下列表、恢复上架）使用 news.update，不要直接改动 COS 快照。

9. 更新资讯状态 POST /api/openapi/news/update

更新已发布资讯的展示与撤稿状态。只接受状态字段；标题、正文、类型、创建时间等内容字段不可通过本接口修改。典型用途：撤稿、撤下列表、分端显示控制与恢复上架。

入参：

flag、status、siteStatus、siteHiddenStatus、wxStatus、appStatus 六个状态字段至少提供一个，不接受其他字段。完整撤稿通常同时传 flag: 0、status: 0、siteStatus: 0；仅隐藏列表传 status: 0（详情仍可按地址访问）。flag 是共享内容删除状态，记录同时面向小程序/App 时，仅撤官网不要顺带把多端状态置 0。

{"id":"8001790000000000000","flag":0,"status":0,"siteStatus":0}

成功解密后的结果示例：

{
  "id": "8001790000000000000",
  "version": "64位快照版本摘要",
  "updated": true,
  "published": true,
  "record": { "id": "8001790000000000000", "flag": 0, "status": 0, "updateTime": "2026-09-28T09:00:00+08:00" }
}

updated: false 表示目标状态与现状一致，为空操作，不产生新版本；相同请求可安全重试。未知 ID 返回 404；正在发布时返回 409，稍后重试；超时或 503 时用相同请求重试（状态修改幂等）。状态变更最迟约 30 秒经 /api/news 列表与详情生效。

10. Node.js 完整调用示例

下载 release-client.mjs，它包含请求加密、HTTP 调用和响应解密，适用于 Node.js 24。将凭证设置到环境变量后：

import { readFile } from 'node:fs/promises';
import { releaseRequest } from './release-client.mjs';

// 知识库接口：action 为 list / create / statistics；
// 资讯接口：action 为 news.list / news.create。
console.log(await releaseRequest('list', { page: 1, size: 20 }));
console.log(await releaseRequest('news.list', { page: 1, size: 20 }));

// article.json 使用第 5 节结构，news.json 使用第 8 节结构；仅在准备发布时执行。
const article = JSON.parse(await readFile('./article.json', 'utf8'));
console.log(await releaseRequest('create', article));
const news = JSON.parse(await readFile('./news.json', 'utf8'));
console.log(await releaseRequest('news.create', news));

可通过 KNOWLEDGE_RELEASE_BASE_URL 指定其他已配置的 API 环境。调用函数也支持第三个参数 { baseUrl, secretId, secretKey }。