merge: database backed creation entry config

# Conflicts:
#	src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
This commit is contained in:
2026-05-11 11:25:35 +08:00
37 changed files with 1458 additions and 204 deletions

View File

@@ -0,0 +1,113 @@
# 创作入口配置数据库化与 Runtime 缺失作品返回首页
日期2026-05-10
## 背景
前端创作中心原本把新建作品入口配置保存在前端代码中,导致入口是否展示、是否开放、卡片文案和 api-server 路由可用性无法使用同一份事实源控制。
同时,用户直接访问 `/runtime/<玩法>?work=<作品号>` 时,如果作品不存在,运行态会先弹出错误提示;但弹窗关闭后仍停留在无运行数据的页面,容易出现空白页。
## 设计结论
1. 创作入口配置事实源迁入 SpacetimeDB。
2. 前端只通过 `GET /api/creation-entry/config` 读取配置并派生展示卡片。
3. api-server 使用同一份配置对相关运行时路由做熔断。
4. 直接 runtime 深链找不到作品时,弹窗确认后回到首页 `/`,避免停留在空白运行态。
## 数据模型
SpacetimeDB 新增两张表:
- `creation_entry_config`
- 全局配置头,保存创作入口主卡片和类型选择弹窗文案。
- `creation_entry_type_config`
- 每个玩法入口的展示与开关配置。
- 关键字段:
- `id`
- `title`
- `subtitle`
- `badge`
- `image_src`
- `visible`
- `open`
- `sort_order`
其中:
- `visible=false`:前端隐藏入口。
- `open=false`:前端展示为锁定/暂不可创建api-server 也可据此熔断运行时入口。
- `sort_order`:数据库排序字段,前端只做可见/锁定分组派生。
## API
新增:
```text
GET /api/creation-entry/config
```
返回 shared-contracts 中的 `CreationEntryConfigResponse`
```json
{
"startCard": {
"title": "...",
"description": "...",
"idleBadge": "...",
"busyBadge": "..."
},
"typeModal": {
"title": "...",
"description": "..."
},
"creationTypes": [
{
"id": "puzzle",
"title": "拼图",
"subtitle": "拼图关卡创作",
"badge": "可创建",
"imageSrc": "/creation-type-references/puzzle.webp",
"visible": true,
"open": true,
"sortOrder": 30,
"updatedAtMicros": 0
}
],
"updatedAtMicros": 0
}
```
## 前端约束
- 禁止再新增 `src/config/newWorkEntryConfig.ts` 这类入口事实源。
- 创作入口 UI 使用 `src/services/creationEntryConfigService.ts` 拉取后端配置。
- `src/components/platform-entry/platformEntryCreationTypes.ts` 只保留展示派生:
- `visible -> hidden`
- `open -> locked`
- `sortOrder -> 初始顺序`
- 缺失作品的 runtime 深链恢复策略放在 `src/routing/runtimeNotFoundRecovery.ts`
## Runtime 缺失作品恢复
当路径是以下任意 runtime 深链,并且作品读取/启动返回 404 或 NOT_FOUND
- `/runtime/puzzle`
- `/runtime/match3d`
- `/runtime/big-fish`
- `/runtime/square-hole`
- `/runtime/visual-novel`
前端执行:
1. 清理当前运行态选择和错误状态。
2. 弹出“作品不存在或已下架,将返回首页。”。
3. 跳转首页 `/`
## 验证命令
```bash
npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/routing/runtimeNotFoundRecovery.test.ts
npm run typecheck
cd server-rs && cargo check -p api-server -p spacetime-module --no-default-features
```