# Latest Updates · CRM 接入契约 v1

**职责**：Latest Updates 服务管理内容、发布和隐藏；CRM 管理登录用户、租户和已读状态。CRM 无须提供案件、客户资料或写入公告内容的接口。内容服务已实现 `/api/v1/updates/latest` 和 `/api/v1/updates/{moduleId}`；两者需要服务端 Bearer 凭证（`updates:read` 权限）。下列 `/api/crm/` 接口由 CRM 方实现；路径不是生产部署地址。

## CRM 后端实现

| 方法及路径 | 行为 |
|---|---|
| `GET /api/crm/latest-updates` | 校验 CRM 会话；后端调用内容服务 `GET /api/v1/updates/latest`，合并当前用户的 `unread`。请求本身不标记已读。 |
| `GET /api/crm/latest-updates/{moduleId}` | 后端调用 `GET /api/v1/updates/{moduleId}`；仅返回当前可见的发布快照。草稿、隐藏、删除和不存在一律 404。 |
| `PUT /api/crm/latest-updates/seen` | 弹窗成功打开后提交本次**实际展示**的 `releaseVersion`。支持重放，返回 204。不能把请求到达时的最新版本自动标记为已读。 |

所有接口从服务端会话取得 `tenantId` 和 `userId`，不接受前端指定身份；写接口验证 CSRF。个性化响应 `Cache-Control: private, no-store`。

### 列表响应 200（示例数据）
```json
{"releaseVersion":"42","releaseDate":"2026-11-02","unread":true,"modules":[{"id":"a75eed94-18fd-4ac8-91c8-63467a53916f","title":"Read documents at the right size","summary":"Fit a document to the viewer in one click.","publishedAt":"2026-11-02T16:31:00Z"}],"websitePath":"/updates"}
```
上游返回同一结构但没有 `unread`。只取可见快照中的最大 `releaseDate`，按 `publishedAt DESC, id ASC` 最多取 3 条，不用旧日期补足。摘要是简介第一句，界面最多显示两行。无发布时返回 `releaseVersion:null, releaseDate:null, modules:[], unread:false`。`websitePath` 相对于配置的公告站域名。

### 详情响应 200
```json
{"id":"a75eed94-18fd-4ac8-91c8-63467a53916f","releaseDate":"2026-11-02","title":"Read documents at the right size","intro":"Fit a document to the viewer in one click.","body":"**Fit width.** Open the viewer → select Fit width.","media":null,"caption":"","publishedAt":"2026-11-02T16:31:00Z","websitePath":"/updates#a75eed94-18fd-4ac8-91c8-63467a53916f"}
```
`media` 可以是 `{kind:"image"|"video",url:string,alt:string}`。渲染文本时先转义，仅允许受支持的加粗语法。详情不含内部标签、团队备注或草稿。

### 已读写入
```json
{"releaseVersion":"42"}
```
版本是服务生成的单调递增整数，在 JSON 中用十进制字符串表示。CRM 仅接受已向该会话提供或经上游确认的版本，拒绝负数和未来版本。`unread = 当前版本 > 已读版本`（按整数比较）；已读按 `GREATEST(old, submitted)` 更新，旧标签页不会覆盖新的已读状态。相同日期的新发布仍有新版本；仅保存草稿不改变版本。

```sql
CREATE TABLE crm_update_receipts (
  tenant_id text NOT NULL, user_id text NOT NULL,
  last_seen_version bigint NOT NULL CHECK(last_seen_version >= 0),
  seen_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY(tenant_id,user_id)
);
INSERT INTO crm_update_receipts(tenant_id,user_id,last_seen_version)
VALUES ($1,$2,$3) ON CONFLICT (tenant_id,user_id) DO UPDATE
SET last_seen_version=EXCLUDED.last_seen_version, seen_at=now()
WHERE crm_update_receipts.last_seen_version < EXCLUDED.last_seen_version;
```

### 错误与验收
401 会话失效；400 非法参数；404 不可见模块；503 上游不可用（不清空已读，不把请求失败解释成“没有更新”）。错误结构 `{"error":{"code":"UPSTREAM_UNAVAILABLE","message":"稍后重试"}}`。上游凭证如有，仅保存在 CRM 后端。

验收：同日发布第 4 条后仍只见最新 3 条；保存已发布模块的草稿不改变详情；隐藏后详情立即 404；打开列表后跨设备不再亮点；同日再次发布后重新亮点；两个用户及两个租户的已读状态互不影响。
