GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
23ba2703b43cfb73f204fdcd5af614991bf797e1
Genarrative/.hermes/shared-memory/pitfalls.md
高物 23ba2703b4
Some checks failed
CI / verify (push) Has been cancelled
Details
Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative
2026-05-08 22:12:10 +08:00

23 KiB
Raw Blame History

踩坑与排障记录

用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。

记录格式

## 问题标题

- 现象：看到什么错误或异常行为
- 原因：确认后的根因
- 处理：具体修复步骤
- 验证：如何确认修复有效
- 关联：相关文件、文档、提交或 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。
Reference in New Issue View Git Blame Copy Permalink