内容与分类 API

内容平台（content）

路径前缀：/content/v1/**

创建内容类型（先定义 schema）

POST /content/v1/content-types
{
  "code": "blog",
  "name": "文章",
  "schema_json": {
    "type": "object",
    "properties": {
      "blocks": { "type": "array" },
      "author": { "type": "string" }
    }
  }
}

创建内容

POST /content/v1/contents
{
  "type_code": "blog",
  "title": "你好，世界",
  "summary": "摘要",
  "body_json": { "blocks": [{ "type": "text", "text": "正文..." }] },
  "lang": "cn",
  "slug": "hello-world",          # 可选，默认自动生成
  "status": "draft",              # draft → review → published
  "seo": { "title": "SEO 标题", "description": "描述", "keywords": "a,b" }
}

列表与过滤

GET /content/v1/contents?status=published&lang=cn&type=blog&category_id={id}&keyword=hello&page=1&page_size=20
GET /content/v1/contents/by-slug/{slug}        # SEO 直达
GET /content/v1/contents/{id}

公开读取仅返回 published；运营 scope 可读内部状态。

发布状态机

POST /content/v1/contents/{id}/submit-review   # draft → review
POST /content/v1/contents/{id}/publish         # review → published
POST /content/v1/contents/{id}/offline         # published → offline
POST /content/v1/contents/{id}/review          # 审核 approved/rejected

评论与统计

POST /content/v1/contents/{id}/comments
GET  /content/v1/contents/{id}/comments
POST /content/v1/contents/{id}/like
GET  /content/v1/contents/{id}/stats          # views/likes/shares/favorites

分类平台（category）

路径前缀：/category/v1/**

# 分类树（导航用）
GET /category/v1/categories?tree=true&type=nav&page_size=300

# 按 slug 直达
GET /category/v1/categories/by-slug/{slug}

# 创建分类
POST /category/v1/categories
{
  "code": "flathead",
  "name": "平头塞",
  "name_json": { "en": "Flathead", "cn": "平头塞" },
  "parent_id": null,
  "type": "product",
  "sort": 1
}

实践建议

slug 就是 SEO 资产：分类/内容 slug 一旦上线尽量不变，URL 结构保持稳定；
分页拉全量：page_size 有上限，批量任务要翻页（cursor 或 page 循环）；
软删除：DELETE 是软删，列表默认过滤，审计可查。