快速开始
一次请求看清全站路由
请先启动后端服务（默认端口 5000，与首页管理文档一致）。根索引会列出当前已挂载模块；百科与关键词接口依赖 MySQL 与建表数据，若返回 503，请按后台提示检查数据库。
- 绝大多数资源支持
?locale=，与线上站点语言代码对齐。 - 写作台、词条与关键词的写接口需先调用
/api/v1/auth/login获取 Bearer Token。
bash
curl -sS "http://127.0.0.1:5000/api/v1" | jq .
同一套结构化数据：既可驱动 ScentWiser 前台阅读体验，也可进入您的 CI、数据仓或 Partner 门户。
已开放的公开端点
下列路径由当前仓库中的 Express 路由挂载；根路径说明中的 formulas / ai 等字段为产品与文档预留，以后端实际注册为准。
GET
/api/v1API 索引
返回版本、支持的语言列表以及各模块入口路径，适合作为健康检查与自动化发现的起点。
GET http://127.0.0.1:5000/api/v1
GET
/api/v1/herbs药材列表
分页检索药材条目；支持 locale、page、limit、search、category（具体筛选能力随后端数据接入逐步完善）。
GET http://127.0.0.1:5000/api/v1/herbs?locale=zh&page=1&limit=20
GET
/api/v1/herbs/:id药材详情
按 ID 获取单条药材的多语言详情（字段以实际响应为准）。
GET http://127.0.0.1:5000/api/v1/herbs/1?locale=en
GET
/api/v1/wiki百科列表
分页返回 Wiki 条目摘要；支持 locale、page、limit、search。
GET http://127.0.0.1:5000/api/v1/wiki?locale=zh&page=1&limit=20&search=沉香
GET
/api/v1/wiki/:slug百科正文
按 slug 获取完整词条内容；会自动累计阅读次数。
GET http://127.0.0.1:5000/api/v1/wiki/agarwood?locale=zh
GET
/api/v1/keywords/map关键词映射
获取指定语言下的关键词与站内链接映射，供前端渲染或二次处理使用。
GET http://127.0.0.1:5000/api/v1/keywords/map?locale=zh
POST
/api/v1/keywords/process正文关键词处理
对一段 Markdown/HTML 正文做关键词识别与替换，返回处理后的文本。
POST http://127.0.0.1:5000/api/v1/keywords/process
Content-Type: application/json
{"content":"……","locale":"zh"}
结构化输出，便于再加工
列表类接口统一透出 success、data 与分页字段；详情类接口在 data 内给出完整正文或对象，方便接入 GraphQL BFF、搜索索引或导出流水线。
为何适合集成
轻量 JSON
无 GraphQL 复杂度，适合脚本、边缘函数与后端聚合。
locale 一致
与前台 i18n 使用同一批语言码，减少映射层代码。
权限分层
读接口公开；写操作走 JWT，避免误操作污染线上词条。
与百科同源
Wiki 接口即站点内容源，避免「爬页面」带来的结构漂移。