# CMS Service

内容管理系统（CMS）微服务，遵循 DDD 分层（api/application/domain/infrastructure），并与 IAM 服务集成实现“认证 + 租户隔离 + 权限裁决”：

- 认证/租户隔离：复用 [auth-kit](file:///home/shay/project/backend/auth-kit/README.md) 中间件（JWT 验签 + `X-Tenant-ID` 一致性校验）
- 权限裁决：通过 iam-client 调用 IAM `POST /authorize/check`（CMS 不内置 RBAC 聚合逻辑）

## 技术栈

- Rust：edition 2024 / Tokio
- Web：Axum
- DB：PostgreSQL / SQLx（启动时自动运行 migrations）
- 文档：utoipa + Scalar（`GET /scalar`）
- 观测：tracing + `common-telemetry`
- 鉴权集成：
  - JWT：RS256（优先 JWKS 拉取，或配置静态公钥 PEM）
  - RBAC：由 IAM 统一裁决

## 项目结构

DDD 分层目录：

- [src/api](file:///home/shay/project/backend/cms-service/src/api)：HTTP 层（路由/handlers/中间件/OpenAPI）
- [src/application](file:///home/shay/project/backend/cms-service/src/application)：应用服务编排（面向用例）
- [src/domain](file:///home/shay/project/backend/cms-service/src/domain)：领域模型（实体/DTO）
- [src/infrastructure](file:///home/shay/project/backend/cms-service/src/infrastructure)：基础设施（DB、repositories、iam-client）

关键入口文件：

- [main.rs](file:///home/shay/project/backend/cms-service/src/main.rs)：配置加载、Telemetry、DB 连接、迁移、JWT/Tenant 中间件挂载
- [api/mod.rs](file:///home/shay/project/backend/cms-service/src/api/mod.rs)：路由组装（`/v1`、`/scalar`、`/healthz`）
- [docs/API.md](file:///home/shay/project/backend/cms-service/docs/API.md)：接口概览与权限点

## 快速开始（本地开发）

1. 复制并修改环境变量：
   - `cp .env.example .env`
2. 准备 PostgreSQL 并配置 `DATABASE_URL`
3. 执行数据库迁移（推荐使用脚本体系）：
   - `./scripts/db/migrate.sh`
   - `./scripts/db/verify.sh`
4. 启动服务：
   - `cargo run`

## 文档

- Scalar：`GET /scalar`
- 健康检查：`GET /healthz`
- SSO 回调（code → token → Set-Cookie）：`GET /auth/callback?code=...&next=...`

## API（v1）

资源入口：

- 栏目：`/v1/columns`
- 标签/分类：`/v1/tags`
- 媒体库：`/v1/media`
- 文章：`/v1/articles`

更完整的接口清单与权限点见： [docs/API.md](file:///home/shay/project/backend/cms-service/docs/API.md)

## 鉴权与租户隔离

- 必须携带：
  - `Authorization: Bearer <access_token>`
  - `X-Tenant-ID: <tenant_uuid>`（与 token 内 tenant_id 不一致将被拒绝）
- CMS 侧 JWT 校验基于 IAM 的公钥：
  - 优先读 `JWT_PUBLIC_KEY_PEM`（静态公钥，无需访问 IAM）
  - 否则读取 `IAM_JWKS_URL`（未配置则默认 `IAM_BASE_URL + /.well-known/jwks.json`）
- 权限校验由 IAM 统一裁决（CMS 侧仅通过 iam-client 调用 IAM `/authorize/check`）。

## 配置项（环境变量）

基础：

- `DATABASE_URL`：PostgreSQL 连接串（必填）
- `PORT`：监听端口（默认 3100）
- `SERVICE_NAME` / `LOG_LEVEL` / `LOG_TO_FILE` / `LOG_DIR` / `LOG_FILE_NAME`：日志与 Telemetry

IAM 集成：

- `IAM_BASE_URL`：IAM 服务地址（默认 `http://localhost:3000`）
- `IAM_JWKS_URL`：JWKS 地址（可选；未配置时使用 `IAM_BASE_URL + /.well-known/jwks.json`）
- `JWT_PUBLIC_KEY_PEM`：静态公钥 PEM（可选；配置后不走 JWKS 拉取）
- `IAM_TIMEOUT_MS`：调用 IAM 超时（默认 2000ms）
- `IAM_CACHE_TTL_SECONDS`：鉴权结果缓存 TTL（默认 10s）
- `IAM_STALE_IF_ERROR_SECONDS`：IAM 不可用时使用 stale cache 的窗口（默认 60s）
- `IAM_CACHE_MAX_ENTRIES`：缓存最大条目数（默认 50000，超过会清空）

示例配置见： [.env.example](file:///home/shay/project/backend/cms-service/.env.example)

## 与 IAM 的对接约束

CMS 运行时依赖 IAM 提供以下能力：

- 公钥发布：`GET /.well-known/jwks.json`（用于 RS256 验签；若使用 `JWT_PUBLIC_KEY_PEM` 可不依赖此端点）
- 权限裁决：`POST /authorize/check`（由 iam-client 调用；用于 `cms:*` 权限点校验）

## 数据库迁移

- 迁移文件目录： [migrations](file:///home/shay/project/backend/cms-service/migrations)
- 启动时默认不执行迁移；如需在本地启动时自动执行，设置 `RUN_MIGRATIONS=1`
- 服务内迁移入口：见 [db::run_migrations](file:///home/shay/project/backend/cms-service/src/infrastructure/db/mod.rs#L14-L16)
- 运维脚本（migrate/verify/rollback）：见 [scripts/db/README.md](file:///home/shay/project/backend/cms-service/scripts/db/README.md)

## 测试

```bash
cargo test
```

当前包含：

- iam-client 缓存/降级测试： [iam_client_cache.rs](file:///home/shay/project/backend/cms-service/tests/iam_client_cache.rs)