# CMS Service API（概览）

CMS 对外暴露 RESTful API，并提供 Scalar 文档：

- `GET /scalar`

## 通用约定

- Header：
  - `Authorization: Bearer <access_token>`
  - `X-Tenant-ID: <tenant_uuid>`
- JWT 校验：默认从 IAM 的 `/.well-known/jwks.json` 获取公钥（也可配置 `JWT_PUBLIC_KEY_PEM` 静态公钥）
- 所有资源均为多租户数据：所有表均包含 `tenant_id` 字段，并在查询/写入时强制按 `tenant_id` 过滤。
- 权限校验：CMS 侧不实现 RBAC 规则聚合，仅通过 iam-client 调用 IAM `POST /authorize/check` 由 IAM 裁决。

## 接口清单（v1）

### 栏目（Column）

- `POST /v1/columns`（`cms:column:write`）
- `GET /v1/columns`（`cms:column:read`，分页/搜索）
- `GET /v1/columns/{id}`（`cms:column:read`）
- `PATCH /v1/columns/{id}`（`cms:column:write`）
- `DELETE /v1/columns/{id}`（`cms:column:write`）

### 标签/分类（Tag）

- `POST /v1/tags`（`cms:tag:write`，`kind` 支持 `tag|category`）
- `GET /v1/tags`（`cms:tag:read`，分页/搜索/按 kind 过滤）
- `GET /v1/tags/{id}`（`cms:tag:read`）
- `PATCH /v1/tags/{id}`（`cms:tag:write`）
- `DELETE /v1/tags/{id}`（`cms:tag:write`）

### 媒体库（Media）

- `POST /v1/media`（`cms:media:manage`，登记 URL/元数据）
- `GET /v1/media`（`cms:media:read`，分页/搜索）
- `GET /v1/media/{id}`（`cms:media:read`）
- `DELETE /v1/media/{id}`（`cms:media:manage`）

### 文章（Article）

- `POST /v1/articles`（`cms:article:write`，创建草稿）
- `GET /v1/articles`（`cms:article:read`，分页/搜索/按状态/栏目/标签过滤）
- `GET /v1/articles/{id}`（`cms:article:read`）
- `PATCH /v1/articles/{id}`（`cms:article:write`）
- `POST /v1/articles/{id}/publish`（`cms:article:publish`，发布并生成版本）
- `POST /v1/articles/{id}/rollback`（`cms:article:rollback`，回滚到指定版本并生成新版本）
- `GET /v1/articles/{id}/versions`（`cms:article:read`，版本列表分页）