# M3：browse history Axum + SpacetimeDB 落地设计

日期：`2026-04-21`

关联任务：

- [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)
- [./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)

关联现状：

- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
- `packages/shared/src/contracts/runtime.ts`

## 1. 文档目的

`02_M3_RUNTIME_PROFILE.md` 已经把 `user_browse_history` 和 `browse history` facade 列入 M3，但还没有冻结到可直接编码的字段、去重规则、路由兼容方式和错误语义。

本文只解决 `browse history` 这一个最小闭环切片：

1. `user_browse_history` 真相表
2. `GET /api/runtime/profile/browse-history`
3. `POST /api/runtime/profile/browse-history`
4. `DELETE /api/runtime/profile/browse-history`
5. `/api/profile/browse-history` 兼容路径

本文不新建 checklist，不替代 [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)，只补足本轮编码所需的冻结口径。

## 2. 旧实现冻结口径

当前 Node 侧行为来自：

- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`

冻结行为如下。

### 2.1 路由

主路径与兼容路径都必须保留：

1. `GET /api/runtime/profile/browse-history`
2. `POST /api/runtime/profile/browse-history`
3. `DELETE /api/runtime/profile/browse-history`
4. `GET /api/profile/browse-history`
5. `POST /api/profile/browse-history`
6. `DELETE /api/profile/browse-history`

所有路径都要求 Bearer JWT。

### 2.2 数据字段

单条浏览记录字段与 `packages/shared/src/contracts/runtime.ts` 保持一致：

1. `ownerUserId`
2. `profileId`
3. `worldName`
4. `subtitle`
5. `summaryText`
6. `coverImageSrc`
7. `themeMode`
8. `authorDisplayName`
9. `visitedAt`

### 2.3 POST 请求体兼容

`POST` 同时支持两种形态：

1. 单条对象
2. `{ entries: [...] }` 批量对象

批量最多 `100` 条。

### 2.4 归一化规则

旧 Node 仓储不是严格校验，而是宽松归一化：

1. `ownerUserId`、`profileId`、`worldName` 去首尾空白后必须非空，否则该条忽略。
2. `subtitle`、`summaryText`、`coverImageSrc` 去首尾空白，空串按空值处理。
3. `themeMode` 不做严格枚举校验，未知值统一回落到 `mythic`。
4. `authorDisplayName` 空值回落到 `玩家`。
5. `visitedAt` 缺失时回落到当前时间。

### 2.5 去重与排序规则

旧 Node 仓储的关键行为必须保持：

1. 去重键：`ownerUserId + profileId`
2. 同一批写入时，先按 `visitedAt DESC` 排序，再去重，只保留最新一条
3. 表内最终查询结果按 `visitedAt DESC` 返回

### 2.6 清空行为

`DELETE` 清空当前用户的全部浏览历史，并返回：

```json
{
  "entries": []
}
```

## 3. Rust 落位决议

### 3.1 crate 分工

本切片固定按以下边界落位：

1. `crates/module-runtime`
   - 定义 `browse history` DTO、字段校验、去重排序与宽松归一化规则。
2. `crates/spacetime-module`
   - 定义 `user_browse_history` 表。
   - 提供 `list / upsert / clear` 三个 procedure。
3. `crates/spacetime-client`
   - 提供 `list_platform_browse_history`
   - 提供 `upsert_platform_browse_history_entries`
   - 提供 `clear_platform_browse_history`
4. `crates/shared-contracts`
   - 冻结 Axum facade 的请求/响应 DTO。
5. `crates/api-server`
   - 提供双路径兼容 facade。
   - 保持 envelope / 错误格式与当前 `runtime settings` 一致。

### 3.2 身份边界

本轮仍沿用 Axum Bearer JWT 作为唯一鉴权边界：

1. `require_bearer_auth` 校验 token。
2. 从 claims 中提取 `user_id`。
3. `user_id` 作为 procedure 入参传入 SpacetimeDB。

当前阶段不把浏览历史直接暴露给前端直连订阅。

## 4. SpacetimeDB 表设计

### 4.1 表名

`user_browse_history`

### 4.2 字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `browse_history_id` | `String` | 主键，格式为 `user_id:owner_user_id:profile_id` |
| `user_id` | `String` | 当前登录用户 |
| `owner_user_id` | `String` | 被浏览世界所属用户 |
| `profile_id` | `String` | 被浏览世界 profile |
| `world_name` | `String` | 世界名 |
| `subtitle` | `String` | 副标题 |
| `summary_text` | `String` | 摘要 |
| `cover_image_src` | `Option<String>` | 封面图 |
| `theme_mode` | `RuntimeBrowseHistoryThemeMode` | 主题枚举 |
| `author_display_name` | `String` | 作者显示名 |
| `visited_at` | `Timestamp` | 最近访问时间 |
| `created_at` | `Timestamp` | 首次写入时间 |
| `updated_at` | `Timestamp` | 最近更新时间 |

### 4.3 索引

至少保留以下访问路径：

1. 主键 `browse_history_id`
2. `(user_id, visited_at)` 用于当前用户按时间倒序列出
3. `(user_id, owner_user_id, profile_id)` 用于幂等 upsert

### 4.4 设计决议

1. 不额外引入自增 ID，直接把幂等键收口成主键。
2. `visited_at` 单独持久化成 `Timestamp`，避免把时间排序退回字符串比较。
3. `theme_mode` 在表内固定为枚举，但 Axum 输入仍宽松接受字符串。

## 5. Procedure 设计

### 5.1 procedure 列表

1. `list_platform_browse_history`
2. `upsert_platform_browse_history_and_return`
3. `clear_platform_browse_history_and_return`

统一返回：

```text
RuntimeBrowseHistoryProcedureResult {
  ok
  entries
  error_message
}
```

### 5.2 行为约束

`list_platform_browse_history`

1. 校验 `user_id`
2. 读取当前用户所有记录
3. 按 `visited_at DESC` 返回

`upsert_platform_browse_history_and_return`

1. 校验 `user_id`
2. 接受单批最多 `100` 条
3. 先按旧 Node 规则宽松归一化
4. 先按 `visitedAt DESC` 排序，再按 `ownerUserId + profileId` 去重
5. 用 `browse_history_id` 幂等 upsert
6. 返回当前用户完整倒序列表

`clear_platform_browse_history_and_return`

1. 校验 `user_id`
2. 删除当前用户全部记录
3. 返回空列表

## 6. Axum facade 设计

### 6.1 双路径兼容

两组路径必须共用同一组 handler：

1. `/api/runtime/profile/browse-history`
2. `/api/profile/browse-history`

只允许路由名不同，不允许行为分叉。

### 6.2 GET

行为：

1. Bearer JWT 校验
2. 读取 claims 中的 `user_id`
3. 调 `spacetime_client.list_platform_browse_history`
4. 返回 `PlatformBrowseHistoryResponse`

### 6.3 POST

行为：

1. Bearer JWT 校验
2. 通过 `serde(untagged)` 同时接单条和批量 shape
3. 不对 `themeMode` 做严格 400 拒绝
4. 对 `ownerUserId`、`profileId`、`worldName` 的缺失或空串按旧 Node 路由规则直接返回 `400`
5. 写入成功后返回最新完整列表

### 6.4 DELETE

行为：

1. Bearer JWT 校验
2. 清空当前用户全部记录
3. 返回 `entries: []`

### 6.5 错误映射

1. JSON 解析失败：`400 BAD_REQUEST`
2. DTO 构建失败：`400 BAD_REQUEST`
3. SpacetimeDB 调用失败：`502 BAD_GATEWAY`
4. JWT 缺失或失效：沿用当前 `401 UNAUTHORIZED`

错误 `details.provider` 固定为：

1. `browse-history`
2. `spacetimedb`

## 7. 测试策略

### 7.1 必跑测试

1. `module-runtime`
   - 宽松 theme 归一化
   - `visitedAt` 默认值
   - 去重与倒序逻辑
2. `api-server`
   - 未登录返回 `401`
   - 兼容路径与主路径一致
   - `POST` 同时支持单条和批量
   - envelope 打开时错误结构稳定

### 7.2 可选联调测试

保留 `#[ignore]` 的本地 SpacetimeDB 集成测试：

1. `POST -> GET`
2. `DELETE -> GET`

## 8. 本文完成定义

当以下条件成立时，本设计视为完成：

1. `user_browse_history` 表字段、主键和排序规则已冻结。
2. 双路径 facade、请求 shape 和错误契约已冻结。
3. 后续编码不再需要猜测：
   - `themeMode` 是否严格校验
   - `POST` 是否支持单条/批量双 shape
   - 去重时机与排序依据

## 9. 2026-04-22 实际落地进度

1. `module-runtime` 已切换为“API 入口严格校验 + 领域层静默过滤”的旧 Node 对齐模式。
2. `api-server` 已补齐双路径 browse history handler，并补 `401`、`400`、批量 shape、兼容路径一致性测试。
3. 剩余阻塞主要在工作树内其他并行任务带来的 Rust 编译占用与跨模块联调，不属于 browse history 方案本身。