235 lines
23 KiB
Markdown
235 lines
23 KiB
Markdown
# 踩坑与排障记录
|
||
|
||
> 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
|
||
|
||
## 记录格式
|
||
|
||
```md
|
||
## 问题标题
|
||
|
||
- 现象：看到什么错误或异常行为
|
||
- 原因：确认后的根因
|
||
- 处理：具体修复步骤
|
||
- 验证：如何确认修复有效
|
||
- 关联：相关文件、文档、提交或 Issue
|
||
```
|
||
|
||
## OSS V4 签名时间和 bucket/object_key 兼容
|
||
|
||
- 现象：OSS V4 私有读签名在部分时间点失败，可能出现 `OSS V4 签名时间格式化失败` 或服务端判定签名格式错误；排查用例中 bucket 为 `xushi-dev`，object_key 为 `generated-square-hole-assets/.../image.png`。
|
||
- 原因：旧逻辑依赖 `time::Time::to_string()` 再去掉冒号，小时小于 10 时输出不稳定补零；同时排查时容易把 bucket 名误当成 object_key 的一部分。
|
||
- 处理：OSS V4 `x-oss-date` 使用固定宽度 `yyyyMMdd'T'HHmmss'Z'` 格式化；调用读签名或 `HEAD Object` 时只传 object_key，不要传 `bucket/object_key` 拼接路径。
|
||
- 验证：运行 `cd server-rs && cargo test -p platform-oss -- --nocapture`，并用 bucket=`xushi-dev`、object_key=`generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png` 覆盖签名生成。
|
||
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`。
|
||
|
||
## 中文乱码与编码风险
|
||
|
||
- 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
|
||
- 原因：Windows/PowerShell/终端编码不一致，或整文件重写导致编码变化。
|
||
- 处理：
|
||
- 不要直接沿用乱码文本。
|
||
- 不要用英文替换中文，除非用户明确要求翻译。
|
||
- 在 PowerShell 5.1 中显式使用 UTF-8。
|
||
- 优先用 Python/Node 或 `Get-Content -Encoding UTF8` 核对原文。
|
||
- 修改中文文件时优先局部补丁，避免无关内容重写。
|
||
- 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
|
||
- 关联：`AGENTS.md`、`npm run check:encoding`。
|
||
|
||
## `.hermes` 只放共享内容，不放个人 Hermes 配置
|
||
|
||
- 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
|
||
- 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。
|
||
- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
|
||
- 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
|
||
- 关联：`.hermes/README.md`。
|
||
|
||
## 旧后端路线文档造成判断漂移
|
||
|
||
- 现象：开发时参考到 Express、Node、PostgreSQL 或 Go 方向旧文档，导致接口、数据真相或部署路径与当前主线不一致。
|
||
- 原因：项目历史文档较多，部分旧方案仍保留作迁移参考。
|
||
- 处理：涉及服务端、数据真相、SpacetimeDB、运行时状态时，先看 `CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`，再看 DDD 总纲和具体技术方案。
|
||
- 验证：代码改动应落在 `server-rs + Axum + SpacetimeDB` 主线；旧路线只作为迁移参考，不作为兼容目标。
|
||
- 关联：`docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`、`AGENTS.md`。
|
||
|
||
## SpacetimeDB 表结构变更不能按 PostgreSQL 迁移直觉处理
|
||
|
||
- 现象：发布时 schema 冲突、自动迁移拒绝、旧客户端调用 reducer 失败、private 表数据迁移遗漏。
|
||
- 原因：SpacetimeDB 对字段删除、类型变化、索引/主键/RLS/reducer 变化有不同自动迁移边界。
|
||
- 处理：变更前阅读 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`；涉及表变化时同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 bindings；必要时走 JSON 导入导出与分片导入迁移流程。
|
||
- 验证：发布前完成 schema 检查、bindings 生成、表目录更新和相关 smoke。
|
||
- 关联：`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
|
||
|
||
## 本地 SpacetimeDB replica identity 不匹配
|
||
|
||
- 现象：本地 standalone 启动时报 `mismatched database identity`。
|
||
- 原因：root-dir / replica 数据残留与当前数据库身份不一致。
|
||
- 处理：按本地 replica identity mismatch 文档进行备份、重建和脚本诊断。
|
||
- 验证：本地 SpacetimeDB 可正常启动并 publish / 访问。
|
||
- 关联：`docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md`。
|
||
|
||
## Vite SPA fallback 吞掉 API 请求
|
||
|
||
- 现象：本地请求 `/api/profile/*` 等接口时返回 HTML，被前端当 JSON 解析报错。
|
||
- 原因：Vite 代理缺少对应 `/api/*` 前缀，API 请求落到 SPA fallback。
|
||
- 处理：补齐 Vite 代理，让 API 请求转发到 Rust `api-server`。
|
||
- 验证：请求返回 JSON，相关页面不再出现 HTML parse 错误。
|
||
- 关联：`docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md`。
|
||
|
||
## 反馈页清空 file input 前必须先拷贝 FileList
|
||
|
||
- 现象：点击上传凭证会打开文件选择框，但选择图片后页面没有展示预览，提交时也没有携带图片凭证。
|
||
- 原因：浏览器传入的 `FileList` 可能跟 `<input type="file">` 保持 live 绑定；如果先执行 `input.value = ''`，再从参数里的 `FileList` 读取文件，列表可能已经为空。
|
||
- 处理：在清空 file input 前先执行 `const selectedFiles = files ? Array.from(files) : []`，后续图片类型、大小、Data URL 读取和预览都基于这个普通数组。
|
||
- 验证：`PlatformFeedbackView.test.tsx` 用 mock `FileReader` 断言选择图片后出现 `反馈凭证预览`，且提交 payload 带 `evidenceItems[].dataUrl`。
|
||
- 关联：`src/components/platform-entry/PlatformFeedbackView.tsx`、`docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md`。
|
||
|
||
## 拼图 APIMart 图片生成密钥不能复用 DashScope / ARK key
|
||
|
||
- 现象：拼图新手引导或拼图创作点击生成后返回 `APIMart 图片生成密钥未配置`。
|
||
- 原因：拼图 `gpt-image-2` / `nanobanana2` 图片生成已按技术方案统一走 APIMart；后端只读取 `APIMART_BASE_URL`、`APIMART_API_KEY`、`APIMART_IMAGE_REQUEST_TIMEOUT_MS`，不会用 `DASHSCOPE_API_KEY`、`LLM_API_KEY` 或 `ARK_API_KEY` 兜底。
|
||
- 处理：在本机私密配置 `.env.secrets.local` 或进程环境中配置真实 `APIMART_API_KEY`，不要提交到 Git；填入后必须重启 `api-server` / `npm run dev`，运行中的进程不会自动加载新 env。
|
||
- 验证：不打印密钥内容，只检查 `APIMART_API_KEY` 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
|
||
- 关联：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`.codex/skills/gpt-image-2-apimart/SKILL.md`。
|
||
|
||
## 拼图图片生成 98% 后报 OSS V4 签名时间格式化失败
|
||
|
||
- 现象：拼图创作表单生成进度卡在 98%，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 返回 `502 Bad Gateway`，前端提示 `拼图图片生成失败：OSS V4 签名时间格式化失败`。
|
||
- 原因：`platform-oss` 曾用 `OffsetDateTime::time().to_string()` 拼接 `x-oss-date`，UTC 小时、分钟或秒为个位数时可能缺少前导零，导致 V4 签名时间不是固定 `YYYYMMDDTHHMMSSZ`。
|
||
- 处理：OSS V4 签名日期统一显式补零格式化；签名 scope 用 `YYYYMMDD`，完整签名时间用 `YYYYMMDDTHHMMSSZ`，不要再依赖 `time().to_string()`。
|
||
- 验证：运行 `cargo test -p platform-oss` 和 `cargo check -p api-server`；重启 `npm run api-server` 后检查 `/healthz`，再重新触发拼图生成。
|
||
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/assets.rs`、`docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md`。
|
||
|
||
## 拼图生成完成后图片只显示破图或 alt 文案
|
||
|
||
- 现象：拼图结果页生成完成后，“画面图”区域出现破图图标和作品名，图片无法正常预览；但打开历史拼图素材时同一张图可能可以正常预览。
|
||
- 原因：拼图正式图保存为 `/generated-puzzle-assets/*` 兼容标识，旧 `/generated-*` 直读代理已删除；如果前端没有通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签，或收到无前导斜杠的 `generated-puzzle-assets/*` object key 后未识别为 generated 私有资源，浏览器会直接请求裸路径并失败。生成完成后的结果图还会传入 `refreshKey`，它只能用于重新请求 `/api/assets/read-url`，不能给 OSS V4 签名 URL 追加 `_v`；OSS 会把 query 纳入签名，额外参数会让签名失效，历史素材常因未传 `refreshKey` 而表现正常。
|
||
- 处理：拼图结果页、发布预览、运行态和历史素材预览都走 `ResolvedAssetImage` 或 `useResolvedAssetReadUrl`；`isGeneratedLegacyPath(...)` 必须同时识别 `/generated-*` 和 `generated-*`；`refreshKey` 只绕过前端签名缓存并重新换签，不修改已返回的 OSS 签名 URL；禁止恢复 `/generated-puzzle-assets` 直读代理。
|
||
- 验证：运行 `npm run test -- src\services\assetReadUrlService.test.ts src\hooks\useResolvedAssetReadUrl.test.tsx src\components\puzzle-result\PuzzleResultView.test.tsx`，再触发一次真实生成确认 Network 中先请求 `/api/assets/read-url`，图片 `src` 为未追加 `_v` 的签名 URL。
|
||
- 关联：`src/services/assetReadUrlService.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md`。
|
||
|
||
## 本地短信登录页签突然消失
|
||
|
||
- 现象：登录弹窗只剩密码登录，短信登录页签看起来像被删掉，但 `LoginScreen` 中手机号验证码表单仍存在。
|
||
- 原因：前端根据 `GET /api/auth/login-options` 返回的 `availableLoginMethods` 渲染页签；常见根因有两类：
|
||
- 本地启动脚本没有让 `.env.local` 覆盖 `.env`，`SMS_AUTH_ENABLED=true` 不生效，后端只返回 `["password"]`。
|
||
- Rust API 直连已返回 `["phone","password"]`，但 Vite 代理目标指向未监听端口，导致 3000 域名下的 `login-options` 返回 `500`，`AuthGate` 降级成 `["password"]`。
|
||
- 3000 端口被旧 `dev:web` 占用后，新的完整栈 Vite 自动漂移到 3001/3002；浏览器仍打开旧 3000 页面，旧页面继续代理到已经下线的端口。
|
||
- 处理：优先用 `npm run api-server`、`npm run dev:rust` 或 `npm run dev` 启动，这些入口应保持 shell 环境变量最高优先级，并允许 `.env.local` 覆盖 `.env`；完整栈启动时还要确保脚本计算出的 `RUST_SERVER_TARGET` 不被 `.env.local` 里的旧值覆盖。排查时先请求 3000 域名下的 `/api/auth/login-options`，再直连 Rust API 目标，并核对 `.env.local` 的 `SMS_AUTH_ENABLED` 与代理端口；若 3001/3002 才返回正确结果，说明当前 3000 是旧前端进程，应清理旧进程后重启。
|
||
- 验证：`http://127.0.0.1:3000/api/auth/login-options` 返回至少 `{"availableLoginMethods":["phone","password"]}` 后，登录弹窗会恢复短信登录页签和“获取验证码”按钮。
|
||
- 关联：`scripts/api-server-dev.mjs`、`scripts/api-server-maincloud.mjs`、`scripts/dev-rust-stack.sh`、`scripts/dev-web-rust.mjs`、`docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md`。
|
||
|
||
## Rust 冷编译导致 api-server 健康检查误超时
|
||
|
||
- 现象：`npm run dev:rust` 在 Windows 冷编译/链接阶段误判 `/healthz` 等待超时并杀掉 `cargo run`。
|
||
- 原因：脚本把 SpacetimeDB 与 api-server 等待窗口混在一起，未考虑 Rust 冷编译耗时。
|
||
- 处理：按冷编译超时修复文档拆分等待窗口。
|
||
- 验证：冷启动时不再误杀仍在编译的 api-server。
|
||
- 关联：`docs/technical/API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md`。
|
||
|
||
## Windows debug api-server 主线程栈溢出
|
||
|
||
- 现象：`cargo check -p api-server` 和 `build_router` 测试通过，但 `npm run api-server` 在 Windows debug 启动时 `thread 'main' has overflowed its stack`。
|
||
- 原因：`api-server` Axum 路由树已经很深，debug 主线程默认栈偏小，初始化状态和构造路由时容易触顶。
|
||
- 处理：入口 `main` 用显式 16MB 栈线程启动 Tokio runtime，并把实际服务逻辑放入 `run_server()`；新增路由时优先用小 router `.merge()`，避免继续拉长主链。
|
||
- 验证：`npm run api-server` 后 `/healthz` 返回 200，相关路由冒烟通过。
|
||
- 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/app.rs`。
|
||
|
||
## Windows api-server.exe 锁文件与强杀退出码容易混淆
|
||
|
||
- 现象：`cargo run -p api-server` 或 `npm run api-server` 报 `failed to remove file ... target\debug\api-server.exe`；清理旧进程后，旧终端可能继续打印 `process didn't exit successfully: server-rs\target\debug\api-server.exe (exit code: 0xffffffff)`。
|
||
- 原因：Windows 不能覆盖仍在运行的 exe；通常是上一条 `npm run api-server` 链路仍在运行，进程树为 `npm run api-server -> node scripts/api-server-dev.mjs -> cargo run -> api-server.exe`。`0xffffffff` 常见于排障时用 `Stop-Process -Force` 强制结束旧 `api-server.exe` 后由 Cargo 回显，不一定代表新启动失败。
|
||
- 处理：先按目标路径确认并停止本仓库的旧 `api-server.exe` 及其父级 `cargo/node/cmd` 启动链路，再重新启动；不要同时开多个 `npm run api-server`。
|
||
- 验证：确认没有匹配 `C:\Genarrative\server-rs\target\debug\api-server.exe` 的进程后，`Remove-Item` 能删除旧 exe；随后 `npm run api-server` 启动并访问 `/healthz` 返回 200。
|
||
- 关联：`scripts/api-server-dev.mjs`、`server-rs/crates/api-server/src/main.rs`。
|
||
|
||
## Windows debug 长 SSE Future 触发 api-server 断连
|
||
|
||
- 现象：前端 Vite 代理请求 `/api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 报 `read ECONNRESET`，随后 `api-server.exe` 以 `0xffffffff` 退出，`dev:rust` 回收 SpacetimeDB、Vite 和后台 Vite。
|
||
- 原因：单个 `async_stream::stream!` 中塞入 Agent 执行、外部模型请求、会话更新和大量 SSE 事件，会在 Windows debug 下生成很大的 Future；真实消费 SSE body 时容易触发 worker 线程栈压力或进程级中断，单元测试若只测函数和路由状态会漏掉。
|
||
- 处理：长 SSE 路由优先使用 `tokio::spawn` 跑业务流程，通过 `mpsc` + `UnboundedReceiverStream` 向 Axum 返回轻量 stream；失败时更新会话为 `failed` 并发送 SSE `error`，不要把大段执行逻辑内联到路由返回的 stream future 中。
|
||
- 验证：补充实际 `collect()` SSE body 的路由测试，确认首轮包含 `stage`、`puzzle_template_catalog` 和 `done`，且不会提前发送 `puzzle_template_selection` / `puzzle_cost_range`；再执行 `cargo check -p api-server`、`cargo test -p api-server creative_agent`，联调时用 `npm run api-server` 检查 `/healthz`。
|
||
- 关联：`server-rs/crates/api-server/src/creative_agent.rs`、`server-rs/crates/api-server/src/app.rs`。
|
||
|
||
## creative-agent 过程项不要把历史事件渲染成运行中
|
||
|
||
- 现象：智能创作页过程中多个阶段从一开始同时转圈，生成结束或进入模板确认后仍有过程项保持转圈。
|
||
- 原因：前端把历史 `stage`、`tool_started` 和 `thought_summary_delta` 都按 active 渲染；后端工具开始/完成事件如果 `toolCallId` 不一致，也会导致开始事件无法收口。
|
||
- 处理：
|
||
- 只有最新且仍在执行的 stage 可为 active；等待确认、等待用户、target ready 和 failed 都是静态状态。
|
||
- 工具开始事件必须等同一 `toolCallId` 的 `tool_completed` 收口；兼容旧流时可按后续同名完成事件兜底。
|
||
- 思考摘要只展示用户可见摘要，且流结束或会话进入等待/完成/失败态后必须改成 done。
|
||
- 验证：前端测试断言完成后 `CreativeAgentProcessItem` 不再存在 `tone === 'active'`；后端测试确认工具开始/完成事件使用相同 `toolCallId`。
|
||
- 关联：`src/components/creative-agent/creativeAgentViewModel.ts`、`server-rs/crates/api-server/src/creative_agent.rs`、`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。
|
||
|
||
## creative-agent 会话切换要清理本地待确认模板
|
||
|
||
- 现象：用户在一个智能创作会话中点开模板确认面板后，立即切到另一条创作会话，可能看到上一会话的确认面板残留。
|
||
- 原因：模板确认面板的 `pendingSelection` 是 `CreativeAgentWorkspace` 本地 UI 状态，不属于后端 session 快照；组件复用时如果不监听 `sessionId` 清理，会跨会话泄漏。
|
||
- 处理：工作区以 `session?.sessionId` 为边界清空 `pendingSelection`；服务端仍以 `puzzleTemplateSelection` / `targetBinding` 作为正式业务状态。
|
||
- 验证：前端测试先点开模板确认面板，再 rerender 到另一 session，断言确认面板消失。
|
||
- 关联：`src/components/creative-agent/CreativeAgentWorkspace.tsx`、`src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。
|
||
|
||
## 视觉小说 VN-10 不要绕过平台资产引用
|
||
|
||
- 现象：文档、封面、场景背景、角色立绘或音乐为了预览方便被写成 Data URL、裸对象路径、外部 URL 或本地临时文件路径。
|
||
- 原因：前端上传与预览容易混在一起，若不走平台资产对象，SpacetimeDB 和长期草稿会被大文本或大二进制污染。
|
||
- 处理：VN 资产统一用 `/api/assets/direct-upload-tickets`、OSS 直传、`/api/assets/objects/confirm`，长期状态只保存 `assetObjectId` 和 `/generated-*` 引用；运行时图片用 `ResolvedAssetImage` 换签。
|
||
- 验证：文档模式 `sourceAssetIds` 为平台资产 id；草稿中不出现 `data:`；图片和音乐字段为平台 generated 引用或 null。
|
||
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`src/services/visual-novel-creation/visualNovelAssetClient.ts`。
|
||
|
||
## 视觉小说 VN-13 交接时不要再回头找旧迁移方案
|
||
|
||
- 现象：接手视觉小说的人容易重新打开旧 TXT 迁移文档，把“外部平台工程迁入”误当成当前实现目标。
|
||
- 原因：视觉小说历史资料里保留了很多迁移阶段的讨论，而当前真正的实现口径已经收口到 PRD、表目录、Prompt 工具说明、实现收口文档和负向扫描报告。
|
||
- 处理：维护视觉小说时优先看 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`、`VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md` 和 `VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`。
|
||
- 验证：新开发者只读这组文档即可继续维护，不需要把旧 TXT 迁移方案重新当作编码依据。
|
||
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md`。
|
||
|
||
## 视觉小说公开广场不要触发登录刷新
|
||
|
||
- 现象：未登录用户进入平台公开广场或从推荐流读取视觉小说公开作品时，前端可能先尝试 `/api/auth/refresh`，失败后再读取公开列表，导致无意义的鉴权噪声或 401 状态刷新。
|
||
- 原因：公开只读接口如果复用默认 `requestJson` 选项，缺少 access token 时会先走静默 refresh。
|
||
- 处理：视觉小说公开广场列表使用 `skipAuth: true` 与 `skipRefresh: true`；鉴权 mutation 仍保持默认鉴权链路。
|
||
- 验证：执行 `src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts`，确认 `/api/runtime/visual-novel/gallery` 请求携带 `skipAuth` / `skipRefresh`，而 run、重生成和存档 mutation 仍走受保护路由。
|
||
- 关联：`src/services/visual-novel-runtime/visualNovelRuntimeClient.ts`、`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
|
||
|
||
## 创作 Tab 语义迁移后，旧“新建作品”测试要改看智能创作首页
|
||
|
||
- 现象：把 `create` 从旧创作中心切到 `CreativeAgentHome` 后，旧测试仍尝试在创作页找“新建作品”类型卡，导致用例失败或定位不到元素。
|
||
- 原因：产品语义已经变成“创作 = 智能创作首页，草稿 = 旧作品架”，但测试夹具和 helper 还沿用旧入口。
|
||
- 处理：把这类测试改成验证智能创作首页、快捷胶囊、抽屉与草稿 Tab；同时给 `useRpgEntryLibraryDetail` 这类恢复路径补上 `setPlatformTabToDraft`。
|
||
- 验证：定向 `vitest`、`eslint`、`typecheck`、`check:encoding` 都通过。
|
||
- 关联：`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx`、`src/components/rpg-entry/useRpgEntryLibraryDetail.ts`。
|
||
|
||
## server-rs 默认 cargo build 不能等同于构建 SpacetimeDB 模块
|
||
|
||
- 现象：在 `server-rs` 下无参数 `cargo build` 期望同时构建 `spacetime-module`，导致链接或构建范围误判。
|
||
- 原因：workspace default-members 当前只包含 `crates/api-server`；SpacetimeDB module 有独立构建/发布方式。
|
||
- 处理：默认 Rust 构建只覆盖原生 `api-server`；模块产物继续走 `spacetime build` / publish / bindings 生成流程。
|
||
- 验证：查看 `server-rs/Cargo.toml` default-members，并按相关 SpacetimeDB 文档执行模块构建。
|
||
- 关联：`server-rs/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md`。
|
||
|
||
## Rust 构建不要让不可用的 sccache 阻断 rustc
|
||
|
||
- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`，真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
|
||
- 原因：环境或 Jenkinsfile 设置了 `RUSTC_WRAPPER=sccache`，但当前 Windows/Linux agent 上没有可执行的 `sccache`，或 PATH 中的 `sccache` shim 损坏。
|
||
- 处理：本地临时排障可执行 `Remove-Item Env:RUSTC_WRAPPER -ErrorAction SilentlyContinue` 后重跑 Cargo；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
|
||
- 验证：`rustc -Vv` 能输出版本；`cargo` 不再尝试调用不可用的 `sccache`；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
|
||
- 关联：`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
|
||
|
||
## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
|
||
|
||
- 现象：部署、回滚或 Jenkins Job 重建时参考旧发布文档，导致 systemd、Nginx、SpacetimeDB 自托管和生产包拆分不一致。
|
||
- 原因：旧 Jenkins / 旧本地远端部署脚本文档仍作为历史经验保留。
|
||
- 处理：生产相关操作先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`，再按需追溯旧文档。
|
||
- 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。
|
||
- 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
|
||
|
||
## 个人任务 scope 不得扩成 work/site/module
|
||
|
||
- 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。
|
||
- 原因：首版个人任务只支持用户维度，非 user scope 会造成任务进度读取语义错误。
|
||
- 处理：Admin 任务配置页不展示范围选择，保存时固定 `scopeKind: 'user'`；API 和领域构造层拒绝非 `User`。
|
||
- 验证：非 `user` scope 返回错误；相关测试覆盖 `Site` / `Module` / `Work` 被拒绝。
|
||
- 关联：`docs/technical/RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`docs/technical/ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。
|