官网内容 API

> ## ⚠️ 写操作前必读
>
> 写接口直接落到线上，对外公开可见，而且没有删除接口。
>
> - 内容提交后立即生效 —— 官网是 SSR 实时读取，不走"构建 → 发布"流程，没有缓冲期
> - 写错了删不掉。只能改成草稿/隐藏让它从官网消失，或者让客户去后台处理
> - 因此：动手前先跟用户确认目标站点和要发的内容，确认后再调接口
> - 内容还没定稿时，先发草稿态：文章 is_draft: 1、产品 is_hidden: 1。
> 案例没有草稿开关，只能直接发或发完再改
> - 一次提交多个语言时逐条检查 —— 失败的语言不影响其他语言，results[] 里逐条看

一、准备

WEBSITE_API_TOKEN 是读写凭据，能改客户线上的公开内容。不要把它打印到日志、
写进文件或贴进对话；怀疑泄露就让客户在后台停用并重新生成。

自建/本地环境可把 base 换成 https://{站点}/index.php?s=/v1。

curl -s "$WEBSITE_API_BASE/website.post/lists?lang=zh-CN&limit=5" \
  -H "Authorization: Bearer $WEBSITE_API_TOKEN"

二、认证

Token 放 Authorization: Bearer tok_xxx，也接受 ?token=tok_xxx。

写操作（add / edit）强制校验：无 Token → 401；Token 无效或已停用 → 401；
Token 是只读权限 → 403。不接受任何兜底方式。

读操作（lists / detail）按以下顺序兜底：

1. 有效 Token → 用该 Token 的租户
2. ?domain=www.example.com → 查 website_domain 表定位租户
3. 服务端开了 WEBSITE_DEMO 时 → 用演示租户

都拿不到租户时，读接口返回 invalid token。

三、接口一览

同一套能力也通过 MCP 暴露，路由 website.mcp/{tool}，工具名 postAdd / postEdit /
postList / postDetail，产品与案例同理（productAdd、caseList…共 12 个），
外加 taxonomy（归属字典，MCP 工具名 websiteTaxonomy）。
MCP 是薄代理，行为与 HTTP API 完全一致，上面所有参数规则都适用。

⚠️ 产品要填归属时，先调 taxonomy 拿字典：province/city/area 是行政区划代码、
industry 是模板定义的 slug，填中文名或随便编的码会被服务端当非法值清成 ''（不报错，静默丢失）。

• 接口默认只返回省 + 市（约 20KB）；要区县码传 depth=3（3437 个区县，约 160KB，
  注意会占用较多上下文）。取值为 regions[].children[].value 与 regions[].children[].children[].value。
• 离线全量码表：references/region-codes.csv（3835 行 = 34 省 + 364 市 + 3437 区县），
  列 层级,名称,adcode,上级adcode,上级名称，可直接 join。字段语义与省市码表见 references/fields.md。
• 产业 slug 以接口返回为准（它随模板而变，静态表只能列当前模板的）。

四、请求格式（写接口三选一）

// ① items[] —— 各语言自带文案。多语言首选（服务端不做翻译，文案由调用方准备）
{ "items": [
    { "lang": "zh-CN", "title": "AI 帮企业把客户找回来", "body": "<p>…</p>" },
    { "lang": "en",    "title": "Let AI bring your customers back", "body": "<p>…</p>" }
]}

// ② langs[] —— 把顶层字段复制给每个语言。只适合内容本就一致的场景
{ "langs": ["zh-CN", "en"], "title": "…", "body": "…" }

// ③ 单条 —— 不传 lang 时默认 zh-CN
{ "lang": "en", "title": "…", "body": "…" }

传的 lang 必须正好等于该站点已启用的语言代码。不是格式归一化 —— 不在启用列表里
就直接回退成站点默认语言，而且不报错。所以 en-US 这种写法会静默写成一篇默认语言
（通常是 zh-CN）的内容。发多语言之前先确认客户启用了哪些语言代码，发完用 lists
按语言复核一遍。

五、字段参考

只列白名单内的字段；传白名单外的字段会被静默丢弃，不报错。

文章 post

产品 product

> province / city / area / industry（产品归属，2026-10 新增）
>
> 给「有地图能力的模板」用（模板 manifest 声明 capabilities.geo，目前是 jingdian）：
> 填了才会出现在官网「产业地理」地图与产业筛选里，留空则不进地图（会列在「未标注产地」分组）。
>
> - 存的是标识符不是文案，语言无关 —— 所以 items[] 多语言提交时每条都要带，不要只给默认语言那条。
> 服务端不会替你在语言之间同步（API 的 items[] 是「每个语言各自为准」，互推会覆盖调用方意图）；
> 只有后台表单保存时会按 slug 自动同步到其他语言行。
> - 三级是逐级包含的：city 挂在 province 下、area 挂在 city 下。省为空时会连市/区县一起清掉，
> 市为空时清掉区县。产地只能精确到区县的项目（德化瓷、英吉沙土陶、雷山苗绣）就填 area，
> 不要把区县码塞进 city。
> - province 必须是省级 adcode：填城市码、乱填、或填区划表里没有的码，一律按空处理（存 ''）。
> 跨产区项目写 MULTI。city 只在模板有该省下钻图时才有意义（目前仅广东）；area 只记精度，
> 地图不画到区县。填了不显示不报错。
> - 写入侧不校验「市属不属于该省、区县属不属于该市」—— 跨级错配会被照收，拼错了自己负责。
> - 读接口（product/lists、product/detail）会原样返回这四个字段，可以读出来核对。
> - 不要凭标题猜产地：填错等于在官网上挂错地理信息。产地拿不准就留空，让运营在后台补。

案例 case

六、接口详解

新增 POST website.post/add

请求体按「四、请求格式」三选一。每个语言条目独立处理：

• title 为空 → 该条失败，错误 title 必填，其他语言照常写入
• 成功条目的 slug 冲突时自动加 -2、-3…

curl -s "$WEBSITE_API_BASE/website.post/add" \
  -H "Authorization: Bearer $WEBSITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items":[
        {"lang":"zh-CN","title":"AI 帮企业把客户找回来","body":"<p>…</p>"},
        {"lang":"en","title":"Let AI bring your customers back","body":"<p>…</p>"}
      ]}'

编辑 POST website.post/edit

部分更新 —— 只传要改的字段，没传的保持原值。

定位方式二选一：

{ "id": 78, "lang": "zh-CN", "description": "改过的描述" }         // 按 id
{ "slug": "about-us", "lang": "en", "seo_title": "About XiongTao" } // 按 slug + lang

⚠️ 按 id 定位时，务必带上该行原本的 lang。 更新语句会把 lang 一起写回，
而 lang 缺省是 zh-CN —— 想改一篇英文内容却漏了 lang，它会被改成中文行。

⚠️ 同理，slug 也会被写回。按 id 编辑时若不传 slug，用的是该行原值（不会清空）；
但传了错的值就会改掉它的 URL，线上的旧链接会失效。

按 slug + lang 定位时两个都要传，定位不到 → 该条失败，错误 内容不存在。

items[] 批量编辑时，每条都要带自己的 id 或 slug+lang。

列表 GET website.post/lists

过滤与排序：

返回 {"list": [...], "total": N}。草稿/隐藏的内容在列表里查不到，
写完想复核草稿要先在后台确认。

详情 GET website.post/detail

参数 slug + lang，返回 {"detail": {...}}。查不到返回错误 not found。

七、返回值与错误

成功

{
  "status": 200,
  "message": "添加完成",
  "data": {
    "results": [ {"lang": "zh-CN", "ok": true, "id": 78, "slug": "ai-3f2a"} ],
    "saved": 1,
    "failed": 0
  }
}

部分语言失败时 message 会变成 添加完成(1 条失败)，results[] 里失败那条带 error。
必须逐语言看 results[].ok，不能只看 status。

错误

认证失败返回真正的 HTTP 401 / 403（ThinkPHP 异常）。而业务失败返回 HTTP 200，
错误藏在 body 里：

{"status": 500, "message": "title 必填", "data": []}

所以判断成败要看 body.status，不能只看 HTTP 状态码。

八、服务端自动处理

会被打码的字段：

• post：title、description、tags、body、seo_title、seo_desc
• product：title、subtitle、summary、features、body、seo_title、seo_desc
• case：title、industry、service、summary、body、seo_title、seo_desc

九、多语言

服务端不做翻译。 要发哪几个语言由用户决定 —— 先问清楚，不要默认"中文优先"或
自动补英文。确定后用 items[] 一次带上各语言文案（语言代码必须是站点已启用的，
见「四、请求格式」的坑）。

确实需要翻译时，注意这几点：

• 长度只是建议，不是限制。 后端没有任何长度校验；title ≤ 25 字、seo_title ≤ 60 字符、
  seo_desc ≤ 150 字符 只出现在 AI 生成提示词里，作为写作目标。超了不会报错
• 术语按客户给的对照处理：品牌名、产品名、以及客户指定的专有名词保持原样，
  不要自行意译。拿不准就先问
• 结构保持不变：body 的 <p>/<h2>/<ul>/<li>/<a> 标签、href/src/alt 属性、
  URL、数字、日期都原样保留，只翻标签之间的文字
• 广告法：避免「最 / 第一 / 唯一 / 国家级 / 100%」这类绝对化用语。
  服务端会自动打码，但别依赖它 —— 打码后内容就残缺了

十、限制

• 图片只收 URL，不提供上传。先把图片放到图床或后台图库，再传地址过来
• 字段白名单外的字段会被静默丢弃，传错字段名不会报错
• 下线已有内容：产品置 is_hidden=1、文章置 is_draft=1，列表和官网都不再显示。
  案例没有开关 —— 只能改内容，或者让客户在后台删