GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

1

Browse Source
This commit is contained in:
高物
2026-04-26 17:53:31 +08:00
parent 06d49c0ad2 a0d1cb86f0
commit 39f679d1ea
46 changed files with 1027 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md Normal file
View File

@@ -0,0 +1,56 @@
# 前端首次加载慢修复记录
日期：`2026-04-26`
## 1. 背景
网站启动后首次打开页面约需三分钟才出现可用界面。已确认 Vite dev server 本身可在数秒内 ready，浏览器 Network 面板中主要等待项集中在 `.tsx` 模块请求，因此本次不继续扩大 `api-server` 冷编译等待窗口，而是收口浏览器首屏 `.tsx` 冷转译与默认路由依赖图。
## 2. 现象与根因
本次排查发现三个会放大首屏等待的前端问题：
1. 默认路由进入 `AuthenticatedApp -> App -> RpgRuntimeShell -> PlatformEntryFlowShellImpl`，首屏虽然只显示平台首页，但入口文件静态导入了创作中心、拼图 Agent、拼图结果页、拼图运行态等非首屏阶段组件。Vite dev 首次访问时需要逐个请求并转译这些 `.tsx`，表现为浏览器长时间卡在加载 `.tsx`。
2. `RouteImageReadyGate` 会先挂载真实业务页面但把整页 `visibility: hidden`，扫描路由 DOM 中所有 `<img>` 和 CSS 图片，等全部图片 settled 后才显示页面。图片不是本轮确认到的主等待项，但会放大 `.tsx` 冷转译后的可见延迟。
3. Vite dev server 监听范围过宽，日志中可见 `docs/`、`scripts/`、`server-rs/` 和测试文件变更都会触发 `page reload`。后端编译、文档更新或测试文件保存会让浏览器反复全量重载，叠加 `.tsx` 冷转译后表现为“首次加载一直等”。
## 3. 修复口径
### 3.1 首屏 `.tsx` 冷转译
默认首页入口先做低风险依赖图收敛：
- `App`、运行时阶段路由、面板路由避免从 barrel 文件导入，改为直连具体实现文件或类型文件。
- `PlatformEntryFlowShellImpl` 将拼图 Agent、拼图结果页、拼图详情页、拼图运行态、创作货架等非默认首屏组件改为 `lazy`。
- 平台首页 Tab 保留已访问页面的挂载状态，但首访只挂载当前 Tab，避免隐藏的创作页提前触发创作中心等懒加载模块。
- RPG 运行态画布和 overlay host 只在已经进入 RPG 世界后挂载，平台首页不再同步拉取运行态画布链路。
- 默认 `App` 不再首屏调用 `useRpgRuntimeSession`。平台首页先挂载轻量 `PlatformEntryFlowShell`，用户选择世界、恢复存档或进入 RPG 运行态深链后，才懒加载完整 `RpgRuntimeApp` 和故事/战斗/NPC 交互 hooks。
- 平台入口 props 移除未使用的 `gameState`，避免轻量首页为了兼容旧签名初始化完整 RPG `GameState`。
- 平台首页资料服务直连 `rpgProfileClient`，避免经过 `services/rpg-entry/index.ts` 把同域其它 client 一并纳入冷转译链路。
### 3.2 首屏图片门控
图片门控从“等待所有图片加载完成”改为“短暂稳态等待后放行”：
- 页面仍先真实挂载，保留极短等待窗口，避免首帧布局剧烈闪动。
- 达到最大阻塞时间后必须显示页面，慢图片由浏览器渐进加载，不再隐藏整页。
- 页面已经显示后，不再因为新增图片或图片地址变化重新隐藏页面。
- 图片预加载继续保留，用于提前触发浏览器缓存，但不得成为首屏可见的硬阻塞。
### 3.3 Vite 监听范围
Vite dev server 只对前端真实运行入口保持热更新敏感：
- 忽略 `docs/`、`server-rs/`、`scripts/`、`backend-rewrite-tasklist/`、`media/` 等非前端首屏运行目录。
- 忽略 `*.test.ts(x)` / `*.spec.ts(x)`，避免测试文件保存触发页面 reload。
- 保留 `src/` 与 `packages/shared/` 的正常变更反馈，因为它们仍是前端运行时依赖。
## 4. 验收标准
1. Vite ready 后，默认站点首屏不再一次性转译明显非首屏的拼图/玩法结果/运行态组件。
2. 默认首页冷加载 `.tsx` 请求数量下降，创作、拼图、运行态等阶段在用户进入时再加载对应 chunk。
3. 默认首页不再同步加载 RPG story / combat / NPC interaction 运行态 hooks；进入自定义世界或恢复存档后再加载完整运行态。
4. 慢图片、失败图片或生成资源代理慢时，页面主体仍能先显示并保持可操作。
5. 修改 `docs/`、`server-rs/`、`scripts/` 或测试文件时，不再触发前端页面 reload。
6. `RouteImageReadyGate` 工具测试覆盖慢图片仍会放行首屏的行为。
7. 修改中文文件后运行编码检查，确保没有破坏 UTF-8 文本。

13
docs/technical/M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md
View File

@@ -51,6 +51,19 @@
1. `content-type`：优先使用 OSS 响应头。
2. `cache-control`：`private, max-age=60`。
3. `x-genarrative-asset-object-key`：回写解析后的 OSS object key，方便调试。
4. `content-length`：成功读取 OSS 对象后按二进制体长度显式回写，避免开发代理或浏览器把已成功读取的图片误判为空响应。
## 3.1 成功对象响应稳定性补充
日期：`2026-04-26`
本次排查发现 `/generated-characters/storynpcs-0/visual/visual-storynpcs-0-aitask_65048e86d04f7/master.png` 在 OSS 签名 URL 下可正常返回 `200 image/png`，但 Rust 同源代理成功读取对象后曾对客户端返回空响应，Vite 开发代理进一步表现为 `500 Internal Server Error`。
修复口径：
1. 成功分支不再依赖隐式 `error_for_status()` 后继续用 builder 拼装响应，而是先判断上游状态，再用明确的 `(status, headers, bytes)` 二进制响应返回。
2. 非 `2xx` 上游状态统一映射为 `404` 或 `502` JSON 错误，禁止把 OSS 上游异常表现成连接中断。
3. 成功响应必须保留 `content-type`，并显式回写 `content-length`、`cache-control` 与 `x-genarrative-asset-object-key`。
## 4. 对象键约定

6
docs/technical/M7_TEST_DEPLOY_CUTOVER_EXECUTION_PLAN_2026-04-22.md
View File

@@ -2,6 +2,8 @@
日期：`2026-04-22`
归档说明：截至 `2026-04-26`，Rust 迁移已完成，旧 `server-node/` 已删除，M7 阶段性预检包装入口已移除。后续长期检查统一使用 `server-rs/scripts/check.ps1`、`server-rs/scripts/smoke.ps1`、`server-rs/scripts/oss-smoke.ps1` 与 `npm run api-server:maincloud`。
## 1. 文档目标
这份文档把 `M7：联调、回归、部署与切流任务清单` 从高层勾选项细化为可直接执行的工程方案。
@@ -34,7 +36,7 @@ M7 固定四层测试入口：
推荐本地顺序：
```powershell
.\server-rs\scripts\m7-preflight.ps1
.\server-rs\scripts\check.ps1
.\server-rs\scripts\smoke.ps1
```
@@ -91,7 +93,7 @@ OSS / CDN / 域名方案：
第一批删除后不再保留 Node/Rust 对比脚本，M7 回归改为 Rust 主线 contract 验证：
1. `server-rs/scripts/m7-preflight.ps1` 覆盖 Rust 工作区构建、测试与关键脚本门禁。
1. `server-rs/scripts/check.ps1` 覆盖 Rust 工作区格式、clippy、构建与测试门禁。
2. `server-rs/scripts/smoke.ps1` 覆盖 `/healthz`、envelope 与 request id 基础 contract。
3. `server-rs/scripts/oss-smoke.ps1` 覆盖真实 OSS 链路。
4. 新增只读 contract 时优先补进 Rust 侧 smoke 或 handler 测试，不恢复 Node 对比脚本。

28
docs/technical/PUZZLE_BIG_FISH_INITIAL_CREATION_PROGRESS_ZERO_FIX_2026-04-26.md Normal file
View File

@@ -0,0 +1,28 @@
# 拼图与大鱼吃小鱼初始创作进度归零修复 2026-04-26
## 背景
拼图与大鱼吃小鱼 Agent 新建会话时，后端会先写入欢迎消息和初始锚点草稿。此前这两个模板把欢迎消息和种子推断视为创作推进，导致新会话一进入工作区就显示非 `0%` 的创作进度。
这与创作工作区的统一约束冲突：新会话必须如实展示后端 session 的 `progressPercent`，初始值为 `0` 时前端数字与进度条都保持 `0%`，不能让用户误判已经完成了创作推进。
## 设计约束
1. 拼图与大鱼吃小鱼新建 Agent session 时，`progress_percent` 固定写入 `0`。
2. 欢迎消息、种子文本和初始锚点推断只作为对话上下文与占位结构，不计入创作进度。
3. 首次用户消息提交后，进度才允许由模型回包或后续 action 写回推进。
4. 前端不为这两个模板额外兜底抬高初始进度，进度真相继续来自 `server-rs` 的 SpacetimeDB session。
## 落地点
1. `server-rs/crates/spacetime-module/src/big_fish/session.rs`
- `create_big_fish_session_tx` 初始化 `progress_percent = 0`。
2. `server-rs/crates/spacetime-module/src/puzzle.rs`
- `create_puzzle_agent_session_tx` 初始化 `progress_percent = 0`。
## 验收
1. 新建大鱼吃小鱼创作工作区后，顶部创作进度显示 `0%`。
2. 新建拼图创作工作区后，顶部创作进度显示 `0%`。
3. 发送第一条用户消息后，进度按模型回包或后续操作正常推进。
4. 生成草稿、生成资产、发布等后续阶段的进度值不受本次调整影响。

1
docs/technical/README.md
View File

@@ -7,6 +7,7 @@
- [RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md](./RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md)：记录 RPG 战斗血条安全锚点、服务端战斗回包前端短表现，以及 `battle_use_skill` 指定技能兜底结算的修复口径。
- [SPACETIMEDB_TABLE_CATALOG.md](./SPACETIMEDB_TABLE_CATALOG.md)：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 `spacetime sql` 查询模板。
- [RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md](./RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md)：记录开局场景与普通场景复用同一场景展示解析服务，修复列表幕缩略图和详情幕背景预览图片不一致的问题。
- [FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md](./FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md)：记录网站启动后首次加载约三分钟的前端根因，收口 `RouteImageReadyGate` 首屏图片门控和 Vite dev server 无关文件监听范围。
- [RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md](./RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md)：记录 RPG 作品删除时报 `No such procedure` 的根因，补齐 `delete_custom_world_agent_session` 在有效 SpacetimeDB 模块入口中的导出，并要求发布后核验 Maincloud schema。
- [CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md](./CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md)：冻结当前后端唯一落地口径，明确新功能以 `server-rs + Axum + SpacetimeDB` 为准，旧 `server-node` / Express / PostgreSQL 与 Go 方向只允许作为迁移参考。
- [RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md](./RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md)：记录世界草稿生成失败/中断后进度不再误到 `100%`、主按钮改为“继续生成草稿”并复用已保存底稿续跑，以及按阶段耗时模型估算预计等待时间的修复口径。