docs: initialize shared Hermes project memory

.hermes/shared-memory/pitfalls.md

@@ -0,0 +1,102 @@
+# 踩坑与排障记录
+
+> 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
+
+## 记录格式
+
+```md
+## 问题标题
+
+- 现象：看到什么错误或异常行为
+- 原因：确认后的根因
+- 处理：具体修复步骤
+- 验证：如何确认修复有效
+- 关联：相关文件、文档、提交或 Issue
+```
+
+---
+
+## 中文乱码与编码风险
+
+- 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
+- 原因：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`。
+
+## 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`。
+
+## 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`。
+
+## 生产发布入口不要沿用旧 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`。