GenarrativeAI/Genarrative
10
0
Fork 0
Code Issues 21 Pull Requests 6 Actions 1 Packages Projects 1 Releases Wiki Activity

Merge branch 'master' of https://git.genarrative.world/GenarrativeAI/Genarrative

Browse Source
This commit is contained in:
高物
2026-05-14 13:42:12 +08:00
parent 2dc9d752e4 166544fae6
commit 7a75f5d612
112 changed files with 5766 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
-44
View File
@@ -1,44 +0,0 @@
name: CI
on:
pull_request:
push:
branches:
- main
- master
jobs:
verify:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20.19.0
cache: npm
- name: Install dependencies
run: npm ci
- name: Check encoding
run: npm run check:encoding
- name: Lint
run: npm run lint:eslint
- name: Typecheck
run: npm run typecheck
- name: Test
run: npm run test
- name: Build
run: npm run build
- name: Validate content
run: npm run check:content
.hermes/plans/2026-05-13_112225-visual-novel-one-line-genarrative-plan.md
+343
View File
@@ -0,0 +1,343 @@
# Genarrative 视觉小说“一句话生成”最小闭环落地计划
生成时间：2026-05-13 11:22
工作区：`C:/proj/Genarrative/.worktrees/hermes-visual-novel`
参考文档：`C:/Users/DSK/Documents/Interactive-fiction/一句话生成视觉小说整体流程总结.md`
## 1. 目标
把 Interactive-fiction 总结文档中的“一句话生成视觉小说”流程，映射并落地到 Genarrative 现有视觉小说能力中，优先做成一个可端到端验证的最小闭环：
1. 用户在视觉小说入口输入一句话并选择画风。
2. 前端进入生成过程页，展示分阶段进度。
3. 后端创建视觉小说创作会话，并基于 seedText 生成 `VisualNovelResultDraft`。
4. 生成完成后进入草稿结果页，可看到世界观、角色、场景、剧情阶段、开场选择。
5. 草稿可编译/保存为作品 profile，并进入视觉小说运行态测试/正式游玩。
本计划只覆盖 Genarrative 内部最小闭环，不引入 Interactive-fiction 原项目的独立 TXT 播放记录、分享播放包、外部活动运营、独立账号/交易/资产系统。
## 2. 当前上下文与已发现实现
### 2.1 Interactive-fiction 总结文档提炼
参考文档将整体流程分为：
- 输入侧：一句话创意、主题/风格、可选文档或素材。
- 生成侧：理解意图、扩展世界观、角色、场景、剧情阶段、开场与选择。
- 编辑侧：草稿页可查看和调整生成结果。
- 运行侧：从草稿进入视觉小说游玩，支持剧情推进、玩家选择、历史与状态。
- 资产侧：角色立绘、背景、音乐/音效可作为后续增强，最小闭环可先使用文字描述与空资产占位。
### 2.2 Genarrative 已有实现基础
已确认项目中视觉小说相关能力并非从零开始：
- 前端入口表单：
- `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
- 已有“一句话创作” textarea、6 个视觉画风选项、提交按钮“生成视觉小说草稿”。
- 前端入口 payload/progress：
- `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
- 已有 `VisualNovelEntryFormPayload`、锚点展示、一句话/画风生成进度步骤。
- 前端平台主流程：
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
- 已接入 `createVisualNovelDraftFromForm`，会创建 session、stream message、进入 `visual-novel-generating`，完成后进入 `visual-novel-result`。
- 前端 API client：
- `src/services/visual-novel-creation/visualNovelCreationClient.ts`
- 已封装 session/message/action/compile 接口。
- 共享契约：
- `packages/shared/src/contracts/visualNovel.ts`
- 已定义 `VisualNovelResultDraft`、world/characters/scenes/storyPhases/opening/runtimeConfig/work/run/history 等结构。
- 后端 API：
- `server-rs/crates/api-server/src/visual_novel.rs`
- 已有创建 session、发消息、流式消息、执行 action、compile、work、runtime run 等接口。
- 后端 prompt：
- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
- 已有 `VISUAL_NOVEL_CREATION_SYSTEM_PROMPT`、结构化输出契约、runtime GM prompt、repair prompt。
- SpacetimeDB 模块：
- `server-rs/crates/spacetime-module/src/visual_novel.rs`
- 已有 session/message/work/run/history/event 表与 procedure。
- 文档参考：
- `docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`
- `docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`
- `docs/technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`
### 2.3 关键实现判断
当前项目已经实现了视觉小说的主要骨架，本次不应大规模重写。更合理的落地方式是补齐“一句话生成”闭环中最容易断裂的点：
- 入口输入与画风信息是否被稳定传给后端 prompt。
- 后端生成 draft 后是否自动保存/关联可编辑 work profile。
- 生成过程页是否能清晰展示 Interactive-fiction 文档中提到的阶段。
- 结果页是否有足够的字段展示与继续游玩入口。
- 运行态是否能基于 opening/choices 正常启动，而不依赖尚未生成的图片/音乐资产。
## 3. 拟采用方案
### 3.1 最小闭环范围
本次优先实现：
1. “一句话 + 视觉画风”作为 `sourceMode: 'idea'` 的 seedText。
2. 后端生成完整 `VisualNovelResultDraft`，包括：
- world
- 3-6 个角色
- 3-8 个场景
- 3-6 个剧情阶段
- opening narration/firstDialogue/2-4 个 choices
- runtimeConfig
3. 若 LLM 输出失败，使用 repair 或确定性 fallback，保证可回到草稿页并显示错误/警告。
4. 结果页支持保存/编译为 work profile。
5. work profile 支持启动 runtime run，opening 能展示初始场景、旁白、对话和选择。
暂不做或仅预留：
- 真实图片/音乐生成队列。
- 多文档解析导入的完整链路。
- 复杂分镜/节点图编辑器。
- 外部 Interactive-fiction 项目的播放器、TXT 记录包、分享活动、独立账号系统。
### 3.2 与 Genarrative 架构的映射
| Interactive-fiction 概念 | Genarrative 落点 |
| --- | --- |
| 一句话创意 | `VisualNovelEntryFormPayload.ideaText` / `seedText` |
| 画风/主题 | `seedText` 中的“视觉画风/画风要求”，后续可结构化为 metadata |
| 世界观设定 | `VisualNovelResultDraft.world` |
| 角色设定 | `VisualNovelResultDraft.characters` |
| 场景设定 | `VisualNovelResultDraft.scenes` |
| 剧情阶段/章节 | `VisualNovelResultDraft.storyPhases` |
| 开场文本与选项 | `VisualNovelResultDraft.opening` |
| 运行时剧情推进 | `VisualNovelRuntimeStep[]` + run snapshot/history |
| 发布/作品库 | `VisualNovelWorkProfileRecord` / works API |
## 4. 分步计划
### Step 1：补齐入口 payload 与生成过程语义
涉及文件：
- `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
- `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
任务：
1. 保持现有 6 个画风选项，但确认每个 option 的 prompt 会进入 `seedText`。
2. 将生成过程阶段从当前 3 步细化为更贴合参考文档的 4-5 步，例如：
- 理解一句话创意
- 扩展世界观与玩家身份
- 设计角色/场景/剧情阶段
- 生成开场与选择
- 准备可编辑草稿
3. 生成过程页的 anchor 保留“一句话”和“视觉画风”，必要时增加“生成目标：视觉小说草稿”。
4. 确认 `createVisualNovelDraftFromForm` 对失败状态会保留返回入口/重试能力。
验收点：提交一句话后能进入 `visual-novel-generating`，看到阶段进度；完成后进入 `visual-novel-result`。
### Step 2：增强后端 creation prompt 与 fallback 约束
涉及文件：
- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
- `server-rs/crates/api-server/src/visual_novel.rs`
- 如已有 domain crate：`server-rs/crates/module-visual-novel/**` 或相关 normalize/validate 文件
任务：
1. 在 creation prompt 中显式吸收 Interactive-fiction 的“一句话生成”目标：
- 从 seedText 提取核心创意、视觉风格、故事类型。
- 生成可直接运行的 opening 和 choices。
- 图片/音乐资产先置 null，但必须有可生成图像的描述。
2. 强化输出约束：
- `opening.sceneId` 必须指向存在且 availability 为 `opening` 的 scene。
- `opening.initialChoices` 必须 2-4 个。
- `storyPhases[0]` 必须包含 opening scene 和主要角色。
- `publishReady` 的判定与 validationIssues 一致。
3. 检查 `submit_visual_novel_message_turn` / `resolve_action_draft` / compile 相关代码：
- 如果 LLM 失败，是否已有 fallback；没有则补确定性 fallback draft。
- 如果 draft 不完整，是否会 normalize/repair 并写入 session。
4. 保留现有“不要输出旧 TXT 播放记录、分享播放包、外部商业字段”的约束，避免把参考项目的外部概念误并入 Genarrative。
验收点：后端给定 seedText 时，返回 session.draft 不为空且满足共享契约。
### Step 3：确认草稿结果页、保存/编译与作品库链路
涉及文件：
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
- `src/components/visual-novel-creation/**`
- `src/services/visual-novel-works*` 或相关 visual novel works client
- `server-rs/crates/api-server/src/visual_novel.rs`
- `packages/shared/src/contracts/visualNovel.ts`
任务：
1. 查找并确认 `visual-novel-result` 页面组件：
- 是否显示 workTitle/workDescription/world/characters/scenes/storyPhases/opening。
- 是否有保存/发布/开始试玩按钮。
2. 确认 `compileVisualNovelWorkProfile` 或 `executeVisualNovelAction({kind:'compile_work_profile'})` 会生成/更新 work profile。
3. 确认作品架上使用 `profileId` 而不是 sessionId 作为稳定作品 ID。
4. 如果结果页缺少“一句话来源/画风”的可视化提示，可在结果页或 summary 中补轻量展示，避免用户以为画风丢失。
验收点：生成完成后能保存为作品；作品出现在“我的作品/创作架”；再次打开能读取同一 draft。
### Step 4：确认运行态 opening 闭环
涉及文件：
- `src/components/visual-novel-runtime/**`
- `src/services/visual-novel-runtime*`
- `server-rs/crates/api-server/src/visual_novel.rs`
- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
- `packages/shared/src/contracts/visualNovel.ts`
任务：
1. 启动 visual novel work run 时，优先使用 `draft.opening` 生成第一轮 runtime snapshot/history。
2. 如果没有图片/音乐，前端 runtime shell 必须可用文字 fallback，不应白屏或阻断游玩。
3. 玩家选择 `choice` 后，后端 runtime GM prompt 生成下一轮 `VisualNovelRuntimeStep[]`。
4. 确认正式游玩入口调用 `work_play_start`，并满足已有埋点约定：
- `scope_kind=work`
- `scope_id=稳定作品 ID`
- metadata 包含 `playType/workId/sourceRoute/userId` 等。
验收点：从生成出的作品进入运行态，能看到 opening 并点击至少一个选择推进一轮。
### Step 5：补测试与文档
涉及文件：
- 前端测试：按仓库现有测试布局查找 `*.test.ts` / `*.test.tsx`
- Rust 测试：`server-rs/crates/api-server/src/**` 或 domain crate tests
- 文档：可追加到 `docs/technical/` 或 `.hermes/shared-memory/decision-log.md`（如团队约定需要）
建议测试：
1. TypeScript 单元测试：
- `buildVisualNovelEntryGenerationProgress` 阶段输出。
- `buildVisualNovelEntryGenerationAnchorEntries` 能展示一句话和画风。
2. Rust 单元测试：
- creation prompt 包含 seedText、sourceMode、输出契约。
- draft normalize/fallback 能生成合法 opening/choices。
- runtime opening 或 first-step 构造不依赖图片/音乐。
3. 集成/手工测试文档：
- 访问平台视觉小说入口。
- 输入一句话。
- 选择画风。
- 点击生成。
- 查看结果页。
- 保存作品。
- 启动试玩并点击选择。
## 5. 可能改动文件清单
高概率改动：
- `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
- `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
- `server-rs/crates/api-server/src/visual_novel.rs`
- `packages/shared/src/contracts/visualNovel.ts`
中概率改动：
- `src/components/visual-novel-runtime/**`
- `src/services/visual-novel-creation/**`
- `src/services/visual-novel-runtime/**`
- `src/services/visual-novel-works/**`
- `server-rs/crates/spacetime-module/src/visual_novel.rs`
- `server-rs/crates/spacetime-client/**` 生成/绑定文件，若 SpacetimeDB contract 需要更新
低概率/仅文档：
- `docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`
- `docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`
- `.hermes/shared-memory/decision-log.md`
## 6. 验证计划
### 6.1 静态检查
在 worktree 根目录执行：
```bash
npm run typecheck
```
如仓库无统一 typecheck，则按 package scripts 选择最接近的前端类型检查命令。
### 6.2 前端定向测试
优先运行与 visual novel / platform entry 相关测试，如存在：
```bash
npm test -- visual-novel
npm test -- platform-entry
```
若仓库使用 vitest：
```bash
npm run test -- visual-novel
```
### 6.3 Rust 定向测试
在 `server-rs` 下运行 visual novel 相关测试：
```bash
cargo test -p api-server visual_novel
cargo test -p shared-contracts visual_novel
```
如改动 SpacetimeDB module：
```bash
cargo test -p spacetime-module visual_novel
```
### 6.4 人工验收步骤
1. 启动本地 dev 栈。
2. 访问 Genarrative 主站。
3. 进入创作/视觉小说入口。
4. 输入：`一个雨夜，失忆的高中生在旧图书馆发现一本会回应她心声的日记。`
5. 选择任一画风，例如“映画动画”。
6. 点击“生成视觉小说草稿”。
7. 预期：进入生成过程页，能看到分阶段进度。
8. 预期：完成后进入草稿结果页，包含标题、简介、世界观、角色、场景、剧情阶段和 opening choices。
9. 点击保存/编译作品。
10. 从作品入口进入试玩。
11. 预期：opening 文本出现，至少 2 个选择可点击；点击后剧情继续推进一轮。
## 7. 风险、权衡与开放问题
### 7.1 风险
- 现有视觉小说代码已较完整，贸然新增一套 parallel pipeline 会制造重复逻辑；应复用当前 `VisualNovelResultDraft` 与 creation agent flow。
- LLM 输出不稳定可能导致草稿结构不完整；需要 normalize/repair/fallback 确保最小闭环。
- 视觉/音乐资产生成未接入时，UI 必须接受 null asset，否则运行态可能白屏。
- `PlatformEntryFlowShellImpl.tsx` 文件很大，改动需局部、谨慎，避免影响其他玩法入口。
- 若改动 SpacetimeDB 表结构，可能牵涉 publish、client binding、清库/迁移；最小闭环阶段应尽量避免 schema 变更。
### 7.2 权衡
- 先让文字版视觉小说完整跑通，再补角色立绘/背景图生成。
- 先用 `seedText` 承载画风，再考虑把 `visualStyleId/Label/Prompt` 结构化进 draft metadata。
- 先用现有 result/work/runtime 页面闭环，不引入新编辑器。
### 7.3 开放问题
1. 用户是否要求把 Interactive-fiction 原项目中的具体 UI 样式/页面布局迁移到 Genarrative？当前计划只迁移流程语义，不迁移独立 UI。
2. 画风是否需要成为作品可编辑字段？当前以 seedText/prompt 影响生成内容，后续可在 draft 中增加 metadata。
3. 文档导入模式是否本期要做？当前计划聚焦一句话模式，document 模式只保留契约能力。
4. 是否需要真实图片/音乐生成？当前计划作为后续增强，不纳入最小闭环。
## 8. 建议实施顺序
1. 先做只改 prompt/progress/少量前端展示的轻量闭环修补。
2. 运行前后端定向测试，确认现有能力是否已足够。
3. 如果后端没有 fallback 或 normalize，再补 Rust 层确定性兜底。
4. 手工跑通“一句话 -> 生成 -> 结果页 -> 保存 -> 试玩”。
5. 最后再考虑是否需要资产生成、文档导入、结构化画风 metadata。
.hermes/shared-memory/decision-log.md
+26 -27
View File
@@ -16,42 +16,42 @@
---
## 2026-05-14 抓大鹅草稿计划同时产出作品信息和默认封面
## 2026-05-13 认证运行期同步直接导入正式认证表
- 背景：抓大鹅草稿生成原本重点在物品名称和素材生成，作品名称、作品描述、作品标签和封面容易在结果页保持空值或只靠用户手动补齐。
- 决策：`match3d_compile_draft` 的作品生成计划必须同时返回 `gameName`、`summary`、`tags`、背景音乐、背景提示词和物品计划。后端先把 `gameName` 与 `summary` 写入 `match3d_work_profile`，再基于题材、作品名和描述自动调用作品标签生成器；标签生成失败时才合并计划 tags 与本地兜底。若作品尚无用户封面，草稿生成完成后默认使用生成的抓大鹅容器 UI 图作为 `coverImageSrc`，容器图缺失时才回退到纯背景图。
- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、Match3D works shared contracts、`Match3DResultView` 手动标签生成、抓大鹅草稿素材生成流水线文档。
- 验证方式：执行 `cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
- 背景：`auth_store_snapshot` 是 Stage 1 整包快照过渡表，主键固定 `default`，会让所有用户状态集中在一条 `snapshot_json` 中；Stage 2/3 已有 `user_account/auth_identity/refresh_session` 正式认证表，继续刷新 `default` 容易让运行时真相和表拆分目标混在一起。
- 决策：运行期认证变更继续由 `module-auth` 生成一致内存快照，但 `api-server` 改为调用 `import_auth_store_snapshot_json` 直接覆盖导入 `user_account/auth_identity/refresh_session`；`auth_store_projection_meta/default` 只记录正式认证表最近一次导入时间；`upsert_auth_store_snapshot` 与 `import_auth_store_snapshot` 仅保留为旧库迁移和兜底入口。
- 影响范围：`spacetime-module` auth procedures/tables、`spacetime-client` auth facade/bindings、`api-server` 认证同步和启动恢复、SpacetimeDB 表目录与认证 Stage 3 文档。
- 验证方式：执行 `npm run spacetime:generate -- --rust-only`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、认证相关定向测试和 `npm run check:encoding`。
- 关联文档：`docs/technical/AUTH_SPACETIMEDB_FORMAL_TABLE_RECOVERY_STAGE3_2026-04-24.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
## 2026-05-13 抓大鹅草稿生成固定 10 光点且入口不生成点击音效
## 2026-05-13 微信小程序支付以后端通知为唯一入账事实
- 背景：抓大鹅入口草稿生成需要有明确、稳定的光点成本，且入口不再把点击音效作为草稿生成选项暴露，避免一次草稿生成混入额外音效任务与扣费。
- 决策：`match3d_compile_draft` 草稿生成固定预扣 `10` 光点，失败时按钱包流水退款；创作页按钮展示 `消耗10光点`，不展示 `生成音效` Toggle，入口表单和重试均固定传 `generateClickSound = false`。物品点击音效只保留在结果页 `素材配置 > 物品` 详情面板手动生成，并按独立音效任务扣费。
- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-creation/Match3DAgentWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、抓大鹅 PRD、F1 入口文档、素材生成流水线文档和音频 Tab 文档。
- 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`npm run typecheck`、`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`cargo check -p api-server --manifest-path server-rs\Cargo.toml`、`npm run check:encoding`。
- 背景：“我的”账户充值需要接入微信小程序支付，同时保留本地 / H5 mock 支付联调能力。
- 决策：`paymentChannel = "mock"` 继续创建即 paid 订单并立即入账；`paymentChannel = "wechat_mp"` 先在 `profile_recharge_order` 写入 `pending` 订单，再由 `api-server` 调微信支付 JSAPI 下单并返回小程序 `wx.requestPayment` 参数。小程序或 H5 的支付成功回调只触发刷新，不直接发放光点或会员；最终入账只由 `/api/profile/recharge/wechat/notify` 验签、解密并确认 `trade_state = SUCCESS` 后完成。`provider_transaction_id` 保存微信支付平台交易号，用于对账、查单、退款和客服排障。
- 影响范围：`profile_recharge_order` 表、SpacetimeDB 充值 procedure、`api-server` 微信支付客户端、小程序 native 支付页、H5 充值弹窗与共享 contract。
- 验证方式：执行 `npm run typecheck`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`cargo test -p module-runtime recharge --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wechat_pay --manifest-path server-rs/Cargo.toml`，后端联调仍用 `npm run api-server` 和 `/healthz`。
- 关联文档：`docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
## 2026-05-13 抓大鹅 5x5 物品素材固定绿幕生成并本地转透明
## 2026-05-13 修改密码后全设备强制下线
- 背景：抓大鹅 2D 五视角素材如果继续让上游自由生成白底、灰底、纹理底或透明感背景，切割后的物品图会带底色块，运行态叠加到中心容器时观感不稳定。
- 决策：抓大鹅物品素材 sheet 的 VectorEngine prompt 固定要求每格使用统一纯绿色绿幕背景；`api-server` 在按 5x5 切割前先对整张素材图执行绿幕 alpha 处理，再做格内前景边界校准和 PNG 上传。物品本体不得使用与绿幕相同的纯绿色，天然绿色物品需要用描边和不同绿相区分。
- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、抓大鹅素材生成 prompt、5x5 切图、OSS 视角图上传和 Match3D 素材生成技术文档。
- 验证方式：`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml` 覆盖 prompt 中的绿幕约束、绿幕转透明和主体保留；执行 `npm run check:encoding`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
- 背景：修改密码原本只递增 `token_version`，旧 access token 会失效，但旧 refresh cookie 仍可通过 `/api/auth/refresh` 重新签发新 token，不符合“改密后全设备强制下线”的账号安全预期。
- 决策：`POST /api/auth/password/change` 成功后必须在同一认证真相更新中撤销该用户全部 active `refresh_session`，继续递增 `token_version`，响应清除当前 refresh cookie；前端 `changePassword` 成功后清空本地 access token 并回到未登录态。用户需要使用新密码重新登录。
- 影响范围：`module-auth` 修改密码用例、`api-server` password management route、`AuthGate`、`authService`、密码登录/重置技术文档。
- 验证方式：执行 `cargo test -p api-server --manifest-path server-rs/Cargo.toml password_change_allows_login_with_new_password_only -- --nocapture`、`npm run test -- AuthGate.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`、`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`。
## 2026-05-13 拼图和抓大鹅 UI 生图拆分为纯背景与运行态默认 UI
## 2026-05-13 refresh_session 会话组后端聚合与远端踢下线
- 背景：拼图和抓大鹅此前的 UI 背景生成容易把拼图槽、锅状竞技区或其它 UI 元素烘进背景图，导致运行态默认 UI、真实物品和生成图层重复。
- 决策：拼图只生成 `9:16` 纯题材背景图，不携带拼图槽、棋盘框、按钮、HUD、文字或物品，拼图槽继续使用运行态默认样式。抓大鹅生成 `9:16` 纯背景图和一张独立 `1:1` 中心容器 UI 图；纯背景不得包含锅/圆盘/托盘/物品槽/HUD/文字/物品，容器图单独贴合题材设定并覆盖运行态中心容器，底部备选栏继续使用默认 UI。
- 影响范围：拼图 UI 背景 prompt、抓大鹅 `backgroundAsset` JSON、Match3D shared contracts、运行态背景/容器渲染、生成进度工作量和对应 PRD/技术文档。
- 验证方式：检查 VectorEngine 请求 prompt 不要求背景图生成锅或槽位；运行态有 `containerImageSrc/containerImageObjectKey` 时使用容器图，否则默认容器兜底；执行拼图/抓大鹅定向测试、`npm run typecheck` 和 `npm run check:encoding`。
- 关联文档：`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`。
- 背景：账号安全页中同设备同 IP 的多条 active `refresh_session` 会重复展示；退出登录没有稳定撤销当前 refresh session；前端“踢下线”只做本地状态变化，未真正让远端设备失效。
- 决策：`GET /api/auth/sessions` 由后端按“同设备 + 同 IP”聚合 active refresh sessions，响应保留代表 `sessionId` 并新增 `sessionIds/sessionCount`；组内包含当前 refresh hash 或 Bearer `sid` 时整组视为当前设备组，前端不展示踢下线。新增 `POST /api/auth/sessions/{session_id}/revoke`，只允许撤销当前用户自己的非当前会话，不递增 `token_version`，但认证中间件会校验 access token `sid` 对应 active refresh session，使被踢设备立即失效。`/api/auth/logout` 在 refresh cookie 缺失时回退用 Bearer `sid` 撤销当前 session，并继续递增 `token_version`。
- 影响范围：`module-auth` refresh session service、`api-server` auth middleware/logout/sessions route、`shared-contracts`/TS auth contract、`AuthGate`、`AccountModal`、认证会话技术文档和路由/埋点索引。
- 验证方式：执行 `cargo test -p module-auth --manifest-path server-rs/Cargo.toml refresh_session`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml auth_sessions -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml revoke_auth_session -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml logout_succeeds_without_refresh_cookie_when_bearer_token_is_valid -- --nocapture`、`npm run test -- AuthGate.test.tsx AccountModal.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`，并用 `npm run api-server` 检查 `/healthz`。
- 关联文档：`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`、`docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md`、`docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`。
## 2026-05-12 抓大鹅入口素材风格改为 2D 常见素材风格
- 背景：抓大鹅草稿素材生成已经收敛为多视角 2D 图片素材，但入口页和旧参考图仍沿用黏土、低多边形、塑料、木雕、体素、金属等偏 3D 素材语言，容易让后续生成链路和用户预期继续漂移。
- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成，输出到 `public/match3d-style-references/`。2026-05-13 起，入口参考图固定只展示 `1` 个完整独立物品，不能展示 `5` 个物品样张或多物品散点图。旧 3D 风格参考图不再保留为入口资产。
- 2026-05-13 补充：`像素复古` 不能只写“复古像素”或“有限色板”；前端、参考图脚本和后端素材图 prompt 必须要求约 `64x64` 低分辨率像素块、整数倍放大、硬边方块像素、`12-24` 色有限色板，并禁止抗锯齿、柔焦、平滑渐变、真实 3D 渲染、PBR 材质和摄影光照。后端收到 `assetStyleId = pixel-retro` 或 `assetStyleLabel = 像素复古` 时必须兜底补齐这些约束。
- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成，输出到 `public/match3d-style-references/`。旧 3D 风格参考图不再保留为入口资产。
- 影响范围：`Match3DAgentWorkspace`、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。
- 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。
- 关联文档：`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md`。
@@ -87,7 +87,6 @@
- 影响范围：平台个人页、登录弹窗、法律 Markdown 渲染和前端认证交互测试。
- 验证方式：执行 `npm run test -- src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、触碰文件 ESLint、`npm run check:encoding`。
- 关联文档：`docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md`。
## 2026-05-12 微信小程序待绑定手机号优先走原生手机号授权
- 背景：微信小程序 `web-view` 壳登录后若返回 `pending_bind_phone`，H5 仍会展示手输手机号和短信验证码绑定页，体验上多了一步。
@@ -417,4 +416,4 @@
- 决策：埋点原始事实进入 `tracking_event`，聚合投影进入 `tracking_daily_stat`；个人任务配置/进度/领奖/钱包分别进入 `profile_task_config`、`profile_task_progress`、`profile_task_reward_claim`、`profile_wallet_ledger`；首版个人任务 scope 仅支持 `user`。
- 影响范围：用户侧任务中心、后台任务配置、运营查询、埋点查询、钱包流水。
- 验证方式：非 `user` scope 的个人任务配置应被 API 和领域构造层拒绝；任务查询与埋点查询分别放在 `docs/operations/` 和 `docs/tracking/`。
- 关联文档：`PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md`、`RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。
- 关联文档：`PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md`、`RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。
.hermes/shared-memory/pitfalls.md
+24
View File
@@ -493,6 +493,22 @@
- 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。
- 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
## Release Web 产物通过内网 rsync 拉取
- 现象：`Genarrative-Web-Deploy` 发布到 `release` 目标时，release agent 本地没有 `/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/web.tar.gz`，但 Jenkins controller 又只归档轻量元数据，导致发布阶段找不到 Web 大包。
- 原因：Web 大包为了避免从 Linux 构建机拉回 Jenkins controller，默认留在构建机稳定缓存目录；development 目标与构建机同机可直接读取，release 目标是独立机器，需要内网同步。
- 处理：release 服务器的 Jenkins 运行用户配置 SSH Host `genarrative-build-internal` 指向构建机内网地址，`Genarrative-Web-Deploy` 在 `DEPLOY_TARGET=release` 且本地缺少大包时默认执行 `rsync` 拉取同一路径内容；真实内网 IP、用户和私钥路径只放在服务器本机 SSH config，不写入 Jenkinsfile。
- 验证：在 release 服务器上先手工跑通 `rsync -av --progress "genarrative-build-internal:${SRC}/" "${DST}/"`，再运行 Web Deploy；流水线会继续执行 `web.tar.gz.sha256` 校验。
- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
## Jenkins 生产流水线拉 Git 先本机再域名备用
- 现象：生产发布、数据库导入导出或服务器配置流水线在目标 Linux agent 上执行 `GitSCM checkout` 时，`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达，导致脚本还没拉下来就失败；若 fallback 到公网 Git 时没有限制 refspec、浅克隆和 tags，还可能在约 10 分钟后出现 `git-remote-https died of signal 15`、`early EOF`、`invalid index-pack output`。
- 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。
- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；首次 checkout 必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有以 `127.0.0.1:3000` 拉 Git 且运行在 Linux agent 的生产 Jenkinsfile，确认存在 `GIT_REMOTE_FALLBACK_URL`、`EFFECTIVE_GIT_REMOTE_URL` 和脚本层 `GIT_REMOTE_FALLBACK_URL` 透传；运行 `bash -n scripts/jenkins-checkout-source.sh`。
- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
## Jenkins 可选参数在 set -u 下不能裸读
- 现象：数据库导入或导出流水线报 `INCLUDE_TABLES: unbound variable`，或其它可选参数在 Bash 中未定义即退出。
@@ -588,6 +604,14 @@
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 覆盖抓大鹅和拼图生成后自动试玩 / 返回结果页。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
## 微信支付回调验签不要用商户私钥
- 现象：微信小程序支付下单能返回 `prepay_id`，但真实支付通知验签失败，或者本地实现误把商户 API 私钥当作回调验签 key。
- 原因：商户私钥只用于商户请求微信支付和生成小程序 `paySign`；微信支付通知的 `Wechatpay-Signature` 需要使用微信支付平台公钥或平台证书公钥验签，并按通知头里的平台序列号匹配。
- 处理：api-server 真实微信支付配置同时需要商户私钥与微信平台公钥：`WECHAT_PAY_PRIVATE_KEY_*` 用于签名，`WECHAT_PAY_PLATFORM_PUBLIC_KEY_*` 与 `WECHAT_PAY_PLATFORM_SERIAL_NO` 用于通知验签，`WECHAT_PAY_API_V3_KEY` 只用于解密通知 resource。支付成功后只通过通知里的 `out_trade_no` 确认本地 pending 订单，并保存 `transaction_id` 到 `profile_recharge_order.provider_transaction_id`。
- 验证：mock 通知测试只能覆盖本地回调推进；真实环境还需用微信支付平台公钥、真实通知头和 API v3 密钥验证签名与解密链路。
- 关联：`server-rs/crates/api-server/src/wechat_pay.rs`、`docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md`。
## 抓大鹅历史草稿外部 Rodin GLB 链接必须转存后再试玩或发布
- 现象：草稿页预览模型失败并报 `GL_INVALID_ENUM: Invalid cap.`，或结果页能看到历史生成记录但试玩、发布和正式运行态仍显示默认积木。
docs/agents/issue-tracker.md
+1 -1
View File
@@ -2,7 +2,7 @@
Issues and PRDs for this repo live as issues in the self-hosted Gitea remote:
- Remote: `http://82.157.175.59:3000/GenarrativeAI/Genarrative.git`
- Remote: `https://git.genarrative.world/GenarrativeAI/Genarrative.git`
- Tracker type: Gitea Issues
## Conventions
docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md
+54 -12
View File
@@ -10,6 +10,7 @@
2. 当前设备识别方式与 `isCurrent` 语义
3. 多端登录识别字段如何从 `refresh_session` 派生到 DTO
4. Rust 首版在 Axum + 进程内 `module-auth` 下的最小实现边界
5. `2026-05-13` 会话组合并展示与远端踢下线闭环修复口径
## 2. 当前基线
@@ -46,11 +47,16 @@
3. 登录创建 session 时落库结构化客户端身份字段
4. 会话列表返回多端识别所需字段，并兼容旧 `clientLabel`
本阶段明确不包含：
`2026-05-13` 起，本接口同时承担账号安全页的会话组读模型：
1. `/api/auth/sessions/:sessionId/revoke`
2. 前端完整消费全部新增字段
3. SpacetimeDB reducer / view 正式读表
1. 后端按“同设备 + 同 IP”聚合活跃 `refresh_session`
2. 前端只消费后端聚合结果，不自行推断合并
3. `POST /api/auth/sessions/{sessionId}/revoke` 已纳入 Rust 实现，用于踢下线非当前会话
本阶段仍明确不包含：
1. SpacetimeDB reducer / view 正式读表
2. 登录方式、refresh token 轮换策略或账号安全页整体重设计
## 5. 请求与响应 contract
@@ -70,6 +76,8 @@
"sessions": [
{
"sessionId": "usess_xxx",
"sessionIds": ["usess_xxx", "usess_yyy"],
"sessionCount": 2,
"clientType": "web_browser",
"clientRuntime": "chrome",
"clientPlatform": "windows",
@@ -90,9 +98,12 @@
字段说明：
1. `clientLabel` 当前阶段继续兼容旧前端字段，值固定与 `deviceDisplayName` 保持一致
2. `clientRuntime`、`clientPlatform`、`deviceDisplayName` 是多端识别首版最小新增字段
3. 小程序来源额外暴露 `miniProgramAppId`、`miniProgramEnv`
1. `sessionId` 是聚合组代表会话 ID；若组内包含当前 `sid`，代表 ID 必须使用当前会话 ID
2. `sessionIds` 是该聚合组内全部活跃 session ID，前端批量踢下线时逐个调用 revoke
3. `sessionCount` 是聚合组内 session 数量
4. `clientLabel` 当前阶段继续兼容旧前端字段，值固定与 `deviceDisplayName` 保持一致
5. `clientRuntime`、`clientPlatform`、`deviceDisplayName` 是多端识别首版最小新增字段
6. 小程序来源额外暴露 `miniProgramAppId`、`miniProgramEnv`
### 5.3 失败响应
@@ -110,12 +121,25 @@
1. 从 refresh cookie 读取当前原始 refresh token
2. 在 Axum 侧计算 `sha256(refresh_token)`
3. 与会话列表中的 `refresh_token_hash` 比较
4. 命中则 `isCurrent = true`
4. 同时读取 Bearer access token claims 中的 `sid`
5. 聚合组内任意 session 命中当前 refresh hash 或当前 `sid`，则整组 `isCurrent = true`
说明：
1. 如果请求没有携带 refresh cookie，本接口仍可返回会话列表
2. 此时全部会话的 `isCurrent` 都为 `false`
2. 此时仍可通过 Bearer `sid` 标记当前组
3. 当前组不允许在前端显示“踢下线”，当前设备退出必须走 `/api/auth/logout`
## 6.1 会话组合并规则
同设备同 IP 的 active refresh sessions 在后端合并为一条 DTO：
1. 优先使用 `device_fingerprint + ip` 作为聚合 key
2. 无 `device_fingerprint` 时退化为 `client_type + client_runtime + client_platform + device_display_name + user_agent + ip`
3. `createdAt` 取组内最早 `created_at`
4. `lastSeenAt` 取组内最新 `last_seen_at`
5. `expiresAt` 取组内最新 `expires_at`
6. `ipMasked` 仍只返回脱敏 IP
## 7. 多端标识派生规则
@@ -161,8 +185,21 @@
负责：
1. 读取 Bearer JWT 与 refresh cookie
2. 把活跃会话映射成旧接口兼容 DTO
3. 派生 `ipMasked` 与 `isCurrent`
2. 按同设备同 IP 聚合活跃会话
3. 把活跃会话组映射成旧接口兼容 DTO
4. 派生 `ipMasked` 与 `isCurrent`
5. 暴露 `POST /api/auth/sessions/{sessionId}/revoke`
## 8.3 指定会话吊销接口
`POST /api/auth/sessions/{sessionId}/revoke` 固定规则：
1. Bearer JWT 必填
2. 仅允许吊销当前用户自己的非当前会话
3. 当前会话自吊销返回业务错误，提示使用退出登录
4. 只撤销目标 `refresh_session`，不递增 `token_version`
5. 撤销后同步 auth store 到 SpacetimeDB
6. 认证中间件会校验 access token `sid` 对应 active `refresh_session`，因此被踢设备已有 access token 会立即失效
## 9. 测试策略
@@ -172,6 +209,9 @@
2. 微信内 H5 登录后，会话列表返回 `wechat_h5 + wechat_embedded_browser`
3. 显式小程序头优先于 `User-Agent` 判断
4. 请求携带当前 refresh cookie 时，只有当前会话 `isCurrent = true`
5. 同设备同 IP 会话会合并，并返回 `sessionIds/sessionCount`
6. 合并组包含当前 `sid` 或当前 refresh hash 时，整组 `isCurrent = true`
7. 指定远端会话吊销后，被踢设备 access token 立即无法通过认证
## 10. 完成定义
@@ -181,4 +221,6 @@
2. 会话列表可区分普通浏览器、微信内 H5、小程序来源
3. 同设备不同浏览器可在会话列表中清晰区分
4. `clientLabel` 与新增多端字段都已稳定返回
5. 文档、任务清单与测试已同步更新
5. 同设备同 IP 的重复 active refresh sessions 已合并展示
6. 非当前会话可通过真实 revoke 接口踢下线
7. 文档、任务清单与测试已同步更新
docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md
+3 -3
View File
@@ -40,12 +40,12 @@ HTTP status server error (503 Service Unavailable)
### 3.1 认证快照同步改为非阻断
`AppState::sync_auth_store_snapshot_to_spacetime` 保持导出本地快照、写入 SpacetimeDB、导入正式表的顺序，但当远端写入或导入失败时只写 warn 日志并返回 `Ok(())`。
`AppState::sync_auth_store_snapshot_to_spacetime` 保持先导出本地认证快照，但运行期会直接调用 `import_auth_store_snapshot_json` 覆盖导入 SpacetimeDB 正式认证表，不再刷新 `auth_store_snapshot/default`；当远端导入失败时只写 warn 日志并返回 `Ok(())`。
设计边界：
1. 当前认证请求的即时真相源是本地 `auth_store`。
2. SpacetimeDB 认证快照用于跨进程恢复和正式表投影。
2. SpacetimeDB 正式认证表用于跨进程恢复；`auth_store_snapshot/default` 只保留为历史迁移和兜底恢复记录。
3. 远端库挂起或网络异常只降级远端恢复能力，不回滚已经成功的登录、刷新、退出和资料更新。
### 3.2 Vite 补齐创作接口代理
@@ -98,7 +98,7 @@ npm run dev:web
1. `GET http://127.0.0.1:3000/api/auth/login-options` 返回 `["phone","password"]`。
2. `GET http://127.0.0.1:3000/api/runtime/match3d/gallery` 返回 `{"items":[]}`，不再返回 SpacetimeDB 503。
3. 未登录请求 `POST http://127.0.0.1:3000/api/creation/match3d/sessions` 返回 `401`，说明同源请求已进入 Rust 鉴权层，不再被 Vite `404`。
4. 隔离端口指向挂起的远端库并使用 mock 短信时，手机号验证码登录返回 `200` 和 token；日志只记录“认证快照写入 SpacetimeDB 失败，当前认证流程继续”。
4. 隔离端口指向挂起的远端库并使用 mock 短信时，手机号验证码登录返回 `200` 和 token；日志只记录“认证快照导入 SpacetimeDB 正式表失败，当前认证流程继续”。
## 6. 后续
docs/technical/AUTH_SPACETIMEDB_FORMAL_TABLE_RECOVERY_STAGE3_2026-04-24.md
+7 -5
View File
@@ -6,8 +6,9 @@
落地口径：
- `user_account`、`auth_identity`、`refresh_session` 作为 SpacetimeDB 中的正式认证持久化表。
- `auth_store_projection_meta` 只记录正式认证表最近一次由认证快照导入的时间，不保存用户快照内容。
- API 启动时优先从正式表导出兼容 `module-auth` 的认证快照，再恢复到内存认证服务。
- 运行期认证变更仍先复用现有 `module-auth` 逻辑生成一致快照，随后同步快照并导入正式表，保证正式表与快照一致。
- 运行期认证变更仍先复用现有 `module-auth` 逻辑生成一致快照，随后调用 `import_auth_store_snapshot_json` 直接覆盖导入正式表；不再继续刷新 `auth_store_snapshot/default`。
- 本阶段不重写登录、刷新、登出内部业务规则，避免在 JWT、refresh rotation、微信绑定合并等复杂语义中引入行为漂移。
## 2. 非目标
@@ -21,7 +22,7 @@
### 3.1 启动恢复
1. API 调用 `export_auth_store_snapshot_from_tables`。
2. 若正式表已有用户、身份或会话数据，则返回兼容 `module-auth` 的 JSON 快照。
2. 若正式表已有用户、身份或会话数据，则返回兼容 `module-auth` 的 JSON 快照，并带上 `auth_store_projection_meta/default.updated_at`。
3. API 用 `InMemoryAuthStore::from_snapshot_json` 恢复认证服务。
4. 若正式表为空或调用失败，则回退到 Stage 1 的 `auth_store_snapshot`。
5. 若 Stage 1 也不可用，则回退本地 JSON 热修复文件。
@@ -29,9 +30,10 @@
### 3.2 运行期同步
1. 登录、刷新、登出等路径继续调用当前内存认证服务。
2. 每次认证状态变更后调用 `upsert_auth_store_snapshot`。
3. 快照写入成功后调用 `import_auth_store_snapshot`，覆盖导入正式表。
4. 导入失败时返回错误，避免用户误以为状态已经持久化。
2. 每次认证状态变更后导出当前内存认证快照 JSON。
3. API 调用 `import_auth_store_snapshot_json`，在同一 SpacetimeDB transaction 中清空并重建 `user_account/auth_identity/refresh_session`，同时更新 `auth_store_projection_meta/default.updated_at`。
4. `upsert_auth_store_snapshot` 和 `import_auth_store_snapshot` 保留为旧库迁移入口，只服务 `auth_store_snapshot/default` 到正式认证表的历史导入，不作为运行期同步路径。
5. 远端导入失败只记录 warn 并继续当前认证响应，避免远端库挂起时回滚已经成功的登录、刷新、退出和资料更新。
## 4. 数据重建规则
docs/technical/AUTH_SPACETIMEDB_TABLE_SPLIT_STAGE2_2026-04-24.md
+1 -2
View File
@@ -23,7 +23,7 @@ Stage 1 已把 Rust 鉴权快照同步到 SpacetimeDB 的 `auth_store_snapshot`
1. `POST /api/auth/refresh` 改写 `refresh_session` 表。
2. 登录成功写 `user_account/auth_identity/refresh_session`。
3. `logout/logout-all/revoke-session` 改写细粒度表。
4. `auth_store_snapshot` 退化为迁移备份。
4. `auth_store_snapshot` 退化为迁移备份；运行期若仍复用内存认证快照，也应通过 `import_auth_store_snapshot_json` 直接导入正式认证表，不再刷新 `auth_store_snapshot/default`。
## 3. 表设计落地口径
@@ -94,4 +94,3 @@ Stage 1 已把 Rust 鉴权快照同步到 SpacetimeDB 的 `auth_store_snapshot`
2. Rust bindings 已刷新。
3. `spacetime-client` 暴露导入 procedure facade。
4. `api-server/spacetime-client/module-auth` 定向检查通过。
docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md
+1
View File
@@ -94,6 +94,7 @@ API Server 新增统一 helper：
| `auth_phone_login_success` | `POST /api/auth/phone/login` |
| `auth_me_view` | `GET /api/auth/me` |
| `auth_sessions_view` | `GET /api/auth/sessions` |
| `auth_revoke_session` | `POST /api/auth/sessions/{session_id}/revoke` |
| `auth_refresh_success` | `POST /api/auth/refresh` |
| `auth_logout` | `POST /api/auth/logout` |
| `auth_logout_all` | `POST /api/auth/logout-all` |
docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md
+58 -19
View File
@@ -9,30 +9,30 @@
1. `光点充值`
2. `会员卡充值`
前端只负责展示与发起购买，套餐、价格、赠送规则、会员权益、生效时间、钱包余额与交易流水统一由 `server-rs` 后端返回。当前没有真实支付网关，本轮采用服务端模拟支付成功：创建订单后立即写入余额或会员状态，并返回最新账户中心快照。后续接入真实支付时，只替换订单支付状态推进，不改前端套餐与账户快照 contract。
前端只负责展示与发起购买，套餐、价格、赠送规则、会员权益、生效时间、钱包余额与交易流水统一由 `server-rs` 后端返回。普通 H5 / 本地联调继续使用 `mock` 渠道：创建订单后立即写入余额或会员状态，并返回最新账户中心快照。微信小程序 web-view 使用 `wechat_mp` 渠道：创建订单时只写入 `pending` 订单并返回小程序 `wx.requestPayment` 参数，真实到账以后端微信支付通知为准。
## 2. 产品规则
### 2.1 光点充值套餐
| productId | 光点 | 金额分 | 徽标 | 说明 |
| --- | ---: | ---: | --- | --- |
| `points_60` | 60 | 600 | 首充双倍 | 首充送60光点 |
| `points_180` | 180 | 1800 | 首充双倍 | 首充送180光点 |
| `points_300` | 300 | 3000 | 首充双倍 | 首充送300光点 |
| `points_680` | 680 | 6800 | 首充双倍 | 首充送680光点 |
| `points_1280` | 1280 | 12800 | 首充双倍 | 首充送1280光点 |
| `points_3280` | 3280 | 32800 | 首充双倍 | 首充送3280光点 |
| productId | 光点 | 金额分 | 徽标 | 说明 |
| ------------- | ---: | -----: | -------- | -------------- |
| `points_60` | 60 | 600 | 首充双倍 | 首充送60光点 |
| `points_180` | 180 | 1800 | 首充双倍 | 首充送180光点 |
| `points_300` | 300 | 3000 | 首充双倍 | 首充送300光点 |
| `points_680` | 680 | 6800 | 首充双倍 | 首充送680光点 |
| `points_1280` | 1280 | 12800 | 首充双倍 | 首充送1280光点 |
| `points_3280` | 3280 | 32800 | 首充双倍 | 首充送3280光点 |
光点充值固定为 `¥6 / ¥18 / ¥30 / ¥68 / ¥128 / ¥328` 六个档位。全部档位参与首充双倍：用户历史上没有 `points_recharge` 流水时，本次购买到账光点为基础光点与等额赠送光点之和；已有充值流水后只到账基础光点。实际到账光点写入交易流水，余额以 SpacetimeDB projection 为准。
### 2.2 会员卡套餐
| productId | 类型 | 天数 | 金额分 | 权益 |
| --- | --- | ---: | ---: | --- |
| `member_month` | 月卡 | 30 | 2800 | 免光点回合数100，每日签到加成0% |
| `member_season` | 季卡 | 90 | 7800 | 免光点回合数100，每日签到加成100% |
| `member_year` | 年卡 | 365 | 24800 | 免光点回合数100，每日签到加成210% |
| productId | 类型 | 天数 | 金额分 | 权益 |
| --------------- | ---- | ---: | -----: | --------------------------------- |
| `member_month` | 月卡 | 30 | 2800 | 免光点回合数100，每日签到加成0% |
| `member_season` | 季卡 | 90 | 7800 | 免光点回合数100，每日签到加成100% |
| `member_year` | 年卡 | 365 | 24800 | 免光点回合数100，每日签到加成210% |
购买会员时，如果当前会员仍有效，则从当前到期时间顺延；如果已过期或从未购买，则从当前服务端时间开始计算。状态只区分 `普通` 与已生效会员，前端不自行推断。
@@ -63,19 +63,58 @@
行为：
1. 校验 `productId`
2. 后端创建已支付订单
3. 光点套餐写入钱包余额与流水
4. 会员套餐写入会员状态
5. 返回最新账户中心快照与订单摘要
2. `paymentChannel = "mock"` 时后端创建已支付订单
3. `paymentChannel = "wechat_mp"` 时后端创建待支付订单，并调用微信支付 JSAPI 下单生成小程序支付参数
4. mock 光点套餐立即写入钱包余额与流水，mock 会员套餐立即写入会员状态
5. wechat_mp 订单不提前发光点或会员，只返回待支付订单、账户中心快照与 `wechatMiniProgramPayParams`
兼容路径：`POST /api/runtime/profile/recharge/orders`
响应里的 `wechatMiniProgramPayParams` 只在微信小程序支付渠道返回，字段直接对应 `wx.requestPayment`：
```json
{
"wechatMiniProgramPayParams": {
"timeStamp": "1777110165",
"nonceStr": "nonce",
"package": "prepay_id=wx201410272009395522657a690389285100",
"signType": "RSA",
"paySign": "..."
}
}
```
### 3.3 `POST /api/profile/recharge/wechat/notify`
微信支付通知地址，无需 Bearer JWT。行为：
1. 真实渠道使用微信支付平台公钥和 `Wechatpay-*` 请求头验签。
2. 使用 `WECHAT_PAY_API_V3_KEY` 解密通知 `resource`。
3. 仅当 `trade_state = "SUCCESS"` 时确认订单支付。
4. 使用微信通知里的 `out_trade_no` 查本地 `profile_recharge_order.order_id`，把订单从 `pending` 改为 `paid`。
5. 将微信平台订单号写入 `provider_transaction_id`，用于对账、查单、退款和客服排障。
6. 在同一 SpacetimeDB procedure 内写入钱包流水或会员到期时间，确保重复通知幂等。
关键环境变量：
| 变量 | 说明 |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `WECHAT_PAY_ENABLED` | 是否启用微信支付客户端 |
| `WECHAT_PAY_PROVIDER` | `mock` 或 `real` |
| `WECHAT_PAY_MCH_ID` | 微信支付商户号 |
| `WECHAT_PAY_MERCHANT_SERIAL_NO` | 商户 API 证书序列号，用于请求微信支付签名头 |
| `WECHAT_PAY_PRIVATE_KEY_PEM` / `WECHAT_PAY_PRIVATE_KEY_PATH` | 商户 API 私钥 |
| `WECHAT_PAY_PLATFORM_PUBLIC_KEY_PEM` / `WECHAT_PAY_PLATFORM_PUBLIC_KEY_PATH` | 微信支付平台公钥或平台证书公钥，用于回调验签 |
| `WECHAT_PAY_PLATFORM_SERIAL_NO` | 微信支付通知头里的平台证书/公钥序列号 |
| `WECHAT_PAY_API_V3_KEY` | 32 字节 API v3 密钥，用于解密通知资源 |
| `WECHAT_PAY_NOTIFY_URL` | 公网 HTTPS 通知地址，通常为 `/api/profile/recharge/wechat/notify` |
## 4. 前端交互
1. “我的”页会员充值按钮打开独立弹窗，不在当前面板下方展开。
2. 弹窗顶部标题为 `账户充值`，右上角关闭。
3. 默认打开 `光点充值`，可切换到 `会员卡充值`。
4. 点击套餐后调用下单接口，按钮进入处理中状态，成功后刷新 `profileDashboard`。
4. 点击套餐后调用下单接口，按钮进入处理中状态；小程序环境走 native 支付页拉起 `wx.requestPayment`，支付页返回后刷新 `profileDashboard`。
5. 弹窗内不写大段说明文案，只保留必要金额、光点、会员权益和状态反馈。
6. 会员卡充值区以套餐卡片优先展示周期、价格和处理状态；移动端单列，桌面端三列，权益表允许横向滚动，避免小屏挤压。
docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md
+3 -2
View File
@@ -32,7 +32,8 @@
2. 请求字段：`currentPassword`、`newPassword`。
3. 若账号未设置过密码，允许 `currentPassword` 为空并设置首个密码。
4. 若账号已有密码，必须校验 `currentPassword` 后才能写入 `newPassword`。
5. 修改成功后递增用户 `token_version`，使旧 access token 失效；前端沿用当前 refresh 会话刷新登录态。
5. 修改成功后递增用户 `token_version`，使旧 access token 失效。
6. `2026-05-13` 起，修改密码成功后必须撤销该用户全部 active `refresh_session`，并在响应中清除当前 refresh cookie；前端清空本地 access token 并回到未登录态。用户需要使用新密码重新登录。
### 2.3 重置密码
@@ -79,7 +80,7 @@
## 5. 2026-05-12 快照同步修复
重置密码和修改密码都会改变认证真相：`password_hash`、`password_login_enabled`、`token_version`，重置密码还会立即创建新的 refresh session。因此 API 层在 `POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后，必须和密码登录、手机号登录、刷新、退出一样调用 `sync_auth_store_snapshot_to_spacetime()`。
重置密码和修改密码都会改变认证真相：`password_hash`、`password_login_enabled`、`token_version`，重置密码还会立即创建新的 refresh session，修改密码还会撤销全部旧 refresh session。因此 API 层在 `POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后，必须和密码登录、手机号登录、刷新、退出一样调用 `sync_auth_store_snapshot_to_spacetime()`。
若只更新本地 `InMemoryAuthStore` 而不同步 SpacetimeDB 认证快照，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态，表现为用户已通过忘记密码重设成功，但再次密码登录仍返回“手机号或密码错误”。启动恢复时应从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照；当本地文件更新且远端表无更新时间戳时，优先使用本地文件并尝试回写 SpacetimeDB，避免旧远端状态覆盖刚重设的密码。
docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md
+12 -10
View File
@@ -132,8 +132,8 @@ SpacetimeDB 公网路由默认保持收敛，只按实际前端 SDK 需要暴露
Nginx 配置文件分为两类：
- `deploy/nginx/genarrative.conf`：生产正式域名 HTTPS 配置，`genarrative.example.com` 只是占位域名，安装时必须替换为真实 `SERVER_NAME`，并要求 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `privkey.pem` 已存在。
- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名。它仍复用同一套静态目录、后台 API 反代、临时主站 `/api/*` 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/generated-*` 或公网 `/healthz`。
- `deploy/nginx/genarrative.conf`：生产正式域名 HTTPS 配置，`genarrative.example.com` 只是占位域名，安装时必须替换为真实 `SERVER_NAME`，并要求 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `privkey.pem` 已存在。`SERVER_NAME` 只填证书主目录名对应的单个域名；`www` 等额外域名通过 `SERVER_ALIASES` 写入 Nginx `server_name`，不参与证书目录拼接。
- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名；如有多个入口，额外域名或 IP 填 `SERVER_ALIASES`。它仍复用同一套静态目录、后台 API 反代、临时主站 `/api/*` 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/generated-*` 或公网 `/healthz`。
## 维护模式
@@ -272,13 +272,14 @@ journalctl -u 'jenkins-agent@*.service' -f
Jenkins controller 与 Linux agent 看到的 Git 服务地址不同，必须拆成两层配置：
- Jenkins Job 的 `Pipeline script from SCM` 由 controller 执行，SCM URL 使用 controller 可访问的公网地址：`http://82.157.175.59:3000/GenarrativeAI/Genarrative.git`。
- Jenkinsfile 内部的源码、脚本 checkout 在 Linux agent 上执行，`GIT_REMOTE_URL` 使用 agent 本机可访问地址：`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`。
- Jenkins Job 的 `Pipeline script from SCM` 由 controller 执行，SCM URL 使用 controller 可访问的公网域名：`https://git.genarrative.world/GenarrativeAI/Genarrative.git`。
- Jenkinsfile 内部的源码、脚本 checkout 在 Linux agent 上执行，`GIT_REMOTE_URL` 优先使用 agent 本机可访问地址：`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`。
- 若 `127.0.0.1` Git 服务在当前 Linux agent 上不可达，发布、数据库和服务器配置类 Jenkinsfile 会用 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git` 重新 checkout。该首次 checkout 只拉 `SOURCE_BRANCH` 单分支、`depth=1` 且不拉 tags，避免 release agent 通过公网备用地址拉取全仓库历史时被 Jenkins Git checkout timeout 杀掉；`scripts/jenkins-checkout-source.sh` 后续 fetch 也会按主地址、域名备用地址顺序重试，并在日志中输出最终使用的远端。
- 这里的 `3000` 是 Git/Web 服务端口，不是 SpacetimeDB 端口；生产 SpacetimeDB 固定使用 `http://127.0.0.1:3101`，避免流水线部署时与本机 Git 服务抢端口。
因此生产 Jenkinsfile 不使用 `checkout scm` 作为构建源码入口，而是显式 `checkout([$class: 'GitSCM', userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]], ...])`。后续 `scripts/jenkins-checkout-source.sh` 会继续把 `origin` 设置为 `GIT_REMOTE_URL`，并按 `SOURCE_BRANCH` / `COMMIT_HASH` 拉取和校验目标提交。
因此生产 Jenkinsfile 不使用 `checkout scm` 作为构建源码入口，而是显式 `checkout([$class: 'GitSCM', userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"]], ...])`。首次 checkout 先尝试 `GIT_REMOTE_URL`，失败后尝试 `GIT_REMOTE_FALLBACK_URL`，两次都必须保持单分支浅克隆和 `noTags=true`；后续 `scripts/jenkins-checkout-source.sh` 会继续把 `origin` 设置为实际可用远端，并按 `SOURCE_BRANCH` / `COMMIT_HASH` 拉取和校验目标提交。
`127.0.0.1` 只代表当前执行该阶段的 Linux agent 自身；如果 release agent 与 Git 服务不在同一台机器，必须把对应 Jenkinsfile 的 `GIT_REMOTE_URL` 改成 release agent 可访问的内网地址，不能让 release 发布阶段回退到 controller 公网拉取。
`127.0.0.1` 只代表当前执行该阶段的 Linux agent 自身；如果 release agent 与 Git 服务不在同一台机器，`GIT_REMOTE_FALLBACK_URL` 统一使用 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不要再配置内网 IP 备用地址。
### SSH PEM 凭证
@@ -323,7 +324,7 @@ Jenkins controller 与 Linux agent 看到的 Git 服务地址不同，必须拆
构建流水线运行在当前 Linux agent 的脱敏 label expression `linux && genarrative-build`。发布、导入导出和服务器配置流水线通过 `DEPLOY_TARGET` 映射到 Linux-only 脱敏部署表达式；其中 `development` 映射到当前 Linux 开发/构建/开发部署 agent 的 `linux && genarrative-build`，`release` 映射到独立 Linux 生产部署 agent 的 `linux && genarrative-release-deploy`，不能复用当前开发/构建/开发部署 agent。真实机器名、IP 和带 IP 的 Jenkins label 只允许留在 Jenkins 节点连接配置中，不能暴露为 Job 参数默认值、调度标签或文档推荐值。
发布流水线通过 Jenkins `copyArtifacts(...)` 从对应构建 Job 获取归档产物，因此 Jenkins 需要安装并启用 Copy Artifact 插件。Web 大包例外：`Genarrative-Web-Build` 只把轻量元数据归档到 Jenkins controller，`web.tar.gz` 保留在 Linux 构建机稳定目录 `/var/cache/genarrative-build/web-artifacts/`，`Genarrative-Web-Deploy` 在部署目标机器上按构建 Job、构建号和版本号读取该目录。development 目标天然共享当前 Linux 开发/构建/开发部署机；release 目标若不是同一台机器，必须先把该目录通过共享存储、rsync 或其它内网同步方式提供给 release 部署 agent。数据库导入流水线的手动上传模式使用 `stashedFile` 文件参数，因此 Jenkins 还需要安装并启用 File Parameter 插件。所有生产 Pipeline 日志必须带时间戳以便审计，Jenkins 需要安装 Timestamper 插件，并在全局配置中启用 `Enabled for all Pipeline builds`。邮件通知流水线使用 Jenkins Pipeline `mail` step，Jenkins 需要安装/启用 Mailer 能力，并在系统配置中配置 SMTP。生产发布不能退回到读取构建 workspace 本地目录的旧模式。
发布流水线通过 Jenkins `copyArtifacts(...)` 从对应构建 Job 获取归档产物，因此 Jenkins 需要安装并启用 Copy Artifact 插件。Web 大包例外：`Genarrative-Web-Build` 只把轻量元数据归档到 Jenkins controller，`web.tar.gz` 保留在 Linux 构建机稳定目录 `/var/cache/genarrative-build/web-artifacts/`，`Genarrative-Web-Deploy` 在部署目标机器上按构建 Job、构建号和版本号读取该目录。development 目标天然共享当前 Linux 开发/构建/开发部署机；release 目标若不是同一台机器，发布流水线默认在本地缓存缺少 `web.tar.gz` 时通过 `rsync` 从 SSH Host `genarrative-build-internal` 拉取同一路径内容。该 Host 必须配置在 release 服务器上 Jenkins 运行用户的 SSH config 中，真实内网 IP、用户和私钥路径只保存在服务器本机；如需改名或指定 config，可通过 `WEB_ARTIFACT_SYNC_HOST` / `WEB_ARTIFACT_SYNC_SSH_CONFIG` 参数覆盖。也可以提前通过共享存储或其它内网同步方式提供该目录。数据库导入流水线的手动上传模式使用 `stashedFile` 文件参数，因此 Jenkins 还需要安装并启用 File Parameter 插件。所有生产 Pipeline 日志必须带时间戳以便审计，Jenkins 需要安装 Timestamper 插件，并在全局配置中启用 `Enabled for all Pipeline builds`。邮件通知流水线使用 Jenkins Pipeline `mail` step，Jenkins 需要安装/启用 Mailer 能力，并在系统配置中配置 SMTP。生产发布不能退回到读取构建 workspace 本地目录的旧模式。
邮件通知的持久收件人不写入 Git，由 Jenkins `Secret text` 凭据 `genarrative-notification-emails` 保存，凭据内容为逗号分隔邮箱。所有生产流水线仍提供 `NOTIFICATION_EMAILS` 参数作为本次运行的追加收件人；通知 Job 会把持久收件人凭据与本次 `NOTIFICATION_EMAILS` 合并去重后发送，参数留空时只发送给持久收件人。流水线结束时在 `post { always { ... } }` 中异步触发 `Genarrative-Notify-Email`，把来源 Job、构建号、构建 URL、结果、源码分支、源码 commit、发布版本、部署目标和数据库名传给通知 Job。通知 Job 失败不能反向改变业务流水线结果，只在来源流水线日志中记录触发失败。
@@ -424,8 +425,8 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
执行规则：
- 流水线先按 Jenkins SCM 配置 checkout 仓库，再执行 `git fetch --tags --prune origin "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"`。
- 如果工作区是浅克隆，流水线必须尝试 `git fetch --unshallow --tags`，确保能验证目标 commit 与分支关系。
- 流水线先按 Jenkins SCM 配置 checkout 仓库，再执行单分支 `git fetch --no-tags --prune origin "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"`；`COMMIT_HASH` 为空时追加 `--depth=1`。
- 如果工作区是浅克隆，只有在 `COMMIT_HASH` 非空、需要验证指定提交属于目标分支时，流水线才尝试 `git fetch --unshallow --no-tags`。`COMMIT_HASH` 为空时只需要目标分支 HEAD，必须保持 `--depth=1 --no-tags`，避免普通发布或服务器配置任务拉取全仓库历史。
- `COMMIT_HASH` 为空时，detached checkout 到 `refs/remotes/origin/<SOURCE_BRANCH>` 当前最新 commit。
- `COMMIT_HASH` 非空时，先解析到完整 commit，再用 `git merge-base --is-ancestor <commit> refs/remotes/origin/<SOURCE_BRANCH>` 校验该提交属于指定分支，校验通过后 detached checkout。
- 流水线日志必须输出最终 `SOURCE_BRANCH` 与实际 `SOURCE_COMMIT`。
@@ -462,7 +463,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
该流水线属于高风险操作，默认要求人工确认后执行。
已落地的 Jenkinsfile 为 `jenkins/Jenkinsfile.production-server-provision`。该流水线默认 `DRY_RUN=true`，只打印将执行的初始化动作；真正写入系统用户、目录、systemd、环境文件并启动服务时，必须设置 `DRY_RUN=false` 且勾选 `CONFIRM_PROVISION`。当 `DEPLOY_TARGET=release` 时，还必须勾选 `CONFIRM_RELEASE_DEPLOY_AGENT`，并通过 `linux && genarrative-release-deploy` 调度到独立 release 部署 agent。
首次真实初始化默认保持 `NGINX_CONFIG_MODE=none`，先完成系统用户、目录、SpacetimeDB、systemd unit 与 `/etc/genarrative/api-server.env` 落盘。开发服没有域名时，使用 `DEPLOY_TARGET=development` + `NGINX_CONFIG_MODE=development-http` 安装 `deploy/nginx/genarrative-dev-http.conf`，并把 `SERVER_NAME` 填为开发机 IP 或临时主机名。等正式域名确定，并且目标机已经存在 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `/etc/letsencrypt/live/<SERVER_NAME>/privkey.pem` 后，再把 `SERVER_NAME` 改成真实域名，并设置 `NGINX_CONFIG_MODE=production-https` 安装 Nginx HTTPS 配置。流水线会拒绝 release 目标安装 `development-http`，也会拒绝用占位域名或缺失证书安装 `production-https`。Nginx 配置写入后必须先 `nginx -t`，再 `nginx -s reload`，不能只验证配置而不重载当前进程。
首次真实初始化默认保持 `NGINX_CONFIG_MODE=none`，先完成系统用户、目录、SpacetimeDB、systemd unit 与 `/etc/genarrative/api-server.env` 落盘。开发服没有域名时，使用 `DEPLOY_TARGET=development` + `NGINX_CONFIG_MODE=development-http` 安装 `deploy/nginx/genarrative-dev-http.conf`，并把 `SERVER_NAME` 填为开发机 IP 或临时主机名。等正式域名确定，并且目标机已经存在 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `/etc/letsencrypt/live/<SERVER_NAME>/privkey.pem` 后，再把 `SERVER_NAME` 改成证书主域名，并设置 `NGINX_CONFIG_MODE=production-https` 安装 Nginx HTTPS 配置。如果同一张证书同时覆盖根域名和 `www` 域名，`SERVER_NAME` 仍只填证书目录名，例如 `genarrative.world`，`SERVER_ALIASES` 填 `www.genarrative.world`。流水线会拒绝 release 目标安装 `development-http`，也会拒绝用占位域名或缺失证书安装 `production-https`。Nginx 配置写入后必须先 `nginx -t`，再 `nginx -s reload`，不能只验证配置而不重载当前进程。
若误用占位域名执行过真实初始化，失败通常发生在 `nginx -t`，错误表现为找不到 `/etc/letsencrypt/live/genarrative.example.com/fullchain.pem` 或 `privkey.pem`。新版初始化在 `NGINX_CONFIG_MODE=none` 时会检测并禁用上一轮留下的占位域名 Nginx 配置，避免它继续影响后续 `nginx -t`。
@@ -482,6 +483,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
- 先按 `SOURCE_BRANCH` / `COMMIT_HASH` 解析并 checkout 部署脚本源码，默认使用 `origin/master` 最新 commit；上游构建触发时使用上游传入的实际构建 commit。
- 通过 Jenkins 归档获取 `web.tar.gz.sha256`、`release-manifest.json` 和 `web-artifact-pointer.txt`，再从 `/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/` 读取 `web.tar.gz`；先校验 checksum，再解压到 `/opt/genarrative/releases/<version>/web`。
- 当 `DEPLOY_TARGET=release` 且 release 服务器本地缓存缺少 `web.tar.gz` 时，默认先执行 `rsync -av --progress <WEB_ARTIFACT_SYNC_HOST>:/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/ /var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/`，再继续校验 checksum；默认 Host 为 `genarrative-build-internal`，由 release 服务器本机 SSH config 解析。
- 更新 `/opt/genarrative/current` 与 `/srv/genarrative/web` 指向。
- 执行 Nginx 配置测试和静态页面 smoke test。
- 不进入维护模式。
docs/technical/README.md
+2 -2
View File
@@ -175,7 +175,7 @@
- [AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md](./AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md)：`/api/auth/login-options` 首版设计，冻结登录方式列表 contract、配置开关来源与返回顺序。
- [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)：`/api/auth/me` 首版查询设计，冻结 Bearer JWT 衔接、`user + availableLoginMethods` 返回 contract，以及用户不存在时的 `401` 语义。
- [AUTH_LOGOUT_ALL_DESIGN_2026-04-21.md](./AUTH_LOGOUT_ALL_DESIGN_2026-04-21.md)：`/api/auth/logout-all` 全端登出设计，冻结全部 refresh session 吊销、`token_version` 递增、清 cookie 语义与 Rust 首版接口边界。
- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)：`/api/auth/sessions` 会话列表设计，冻结当前设备识别、多端登录字段映射、`clientLabel` 兼容策略与 Rust 首版接口边界。
- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)：`/api/auth/sessions` 会话列表设计，冻结当前设备识别、多端登录字段映射、同设备同 IP 会话组合并、`clientLabel` 兼容策略与 Rust 接口边界。
- [PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md](./PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md)：手机号验证码登录最小闭环设计，冻结 mock 验证码规则、`send-code` / `phone/login` contract 与 crate 边界。
- [PHONE_AUTH_AXUM_RATE_LIMIT_AND_FAILURE_DESIGN_2026-04-21.md](./PHONE_AUTH_AXUM_RATE_LIMIT_AND_FAILURE_DESIGN_2026-04-21.md)：手机号验证码冷却与失败次数限制设计，冻结同手机号同场景发送冷却、错误次数耗尽、`429` 与 `Retry-After` contract。
- [PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md](./PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md)：冻结 Rust `api-server + module-auth + platform-auth` 接入真实阿里云短信 provider 的 crate 边界、发送与校验职责、配置项和错误语义。
@@ -207,7 +207,7 @@
- [SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md)：`M2` 第六张短信鉴权统计表 `sms_auth_event` 的事件范围、统计口径、索引与和风控/审计表的协作边界。
- [SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md)：`M2` 第五张风控状态表 `auth_risk_block` 的作用域、活跃态、刷新/解除规则与读取派生约束。
- [SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md)：`M2` 第四张鉴权审计表 `auth_audit_log` 的事件范围、追加写规则、索引与对外 DTO 派生约束。
- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)：`M2` 第三张会话表 `refresh_session` 的 cookie/hash 边界、轮换与吊销语义、索引与迁移规则。
- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)：`M2` 第三张会话表 `refresh_session` 的 cookie/hash 边界、轮换、logout fallback、指定会话吊销语义、索引与迁移规则。
- [SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md)：`M2` 第二张身份表 `auth_identity` 的 provider 范围、唯一约束、手机号/微信身份写入规则与迁移策略。
- [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)：`M2` 第一张身份主表 `user_account` 的职责边界、字段、唯一约束、状态迁移、旧 `users` 映射与落地约束。
- [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于旧 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。
docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md
+10 -9
View File
@@ -1,6 +1,6 @@
# Rust API Server 路由索引（2026-04-23）
更新时间：`2026-05-01`
更新时间：`2026-05-13`
> 2026-04-29 补充：本文件保留为迁移期路由快照。DDD G1 后续并行工作的契约冻结口径以 [`SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`](./SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md) 为准，尤其是新增的 Big Fish、Puzzle、profile、runtime chat、story facade 和兼容路由删除计划。
>
@@ -20,7 +20,7 @@
2. 内部鉴权调试接口：`2` 条。
3. AI task 接口：`9` 条。
4. assets / OSS 接口：`15` 条。
5. auth 接口：`12` 条。
5. auth 接口：`13` 条。
6. custom world / agent 接口：`23` 条。
7. match3d creation / runtime 接口：`14` 条。
8. llm proxy 接口：`1` 条。
@@ -84,13 +84,14 @@
3. `POST /api/auth/logout`
4. `POST /api/auth/logout-all`
5. `GET /api/auth/sessions`
6. `POST /api/auth/refresh`
7. `POST /api/auth/phone/send-code`
8. `POST /api/auth/phone/login`
9. `GET /api/auth/wechat/start`
10. `GET /api/auth/wechat/callback`
11. `POST /api/auth/wechat/bind-phone`
12. `POST /api/auth/entry`
6. `POST /api/auth/sessions/{session_id}/revoke`
7. `POST /api/auth/refresh`
8. `POST /api/auth/phone/send-code`
9. `POST /api/auth/phone/login`
10. `GET /api/auth/wechat/start`
11. `GET /api/auth/wechat/callback`
12. `POST /api/auth/wechat/bind-phone`
13. `POST /api/auth/entry`
### 3.6 Custom World / Agent
docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md
+2 -2
View File
@@ -31,7 +31,7 @@ G1 单 owner 文件范围：
| 管理兑换码 | `POST /admin/api/profile/redeem-codes`、`POST /admin/api/profile/redeem-codes/disable` | 收敛 | 继续走 admin 路由，DTO 归入 profile/runtime 管理命令组 | WP-RT、WP-API |
| 内部鉴权调试 | `GET /_internal/auth/claims`、`GET /_internal/auth/refresh-cookie` | 删除 | 只允许本地诊断脚本或 admin debug 能力使用，不作为前端契约 | WP-DEL |
| 鉴权公开查询 | `GET /api/auth/login-options`、`GET /api/auth/public-users/by-code/{code}`、`GET /api/auth/public-users/by-id/{user_id}` | 保留 | `AuthLoginOptionsResponse`、`PublicUserSearchResponse` | WP-A |
| 鉴权会话 | `GET /api/auth/me`、`GET /api/auth/sessions`、`POST /api/auth/refresh`、`POST /api/auth/logout`、`POST /api/auth/logout-all` | 保留 | `AuthMeResponse`、`AuthSessionsResponse`、`RefreshSessionResponse`、`LogoutResponse`、`LogoutAllResponse` | WP-A |
| 鉴权会话 | `GET /api/auth/me`、`GET /api/auth/sessions`、`POST /api/auth/sessions/{session_id}/revoke`、`POST /api/auth/refresh`、`POST /api/auth/logout`、`POST /api/auth/logout-all` | 保留 | `AuthMeResponse`、`AuthSessionsResponse`、`RevokeAuthSessionResponse`、`RefreshSessionResponse`、`LogoutResponse`、`LogoutAllResponse` | WP-A |
| 鉴权登录 | `POST /api/auth/phone/send-code`、`POST /api/auth/phone/login`、`GET /api/auth/wechat/start`、`GET /api/auth/wechat/callback`、`POST /api/auth/wechat/bind-phone`、`POST /api/auth/entry`、`POST /api/auth/password/change`、`POST /api/auth/password/reset` | 保留 | TS 命名统一使用 `Auth*` 前缀，Rust 命名维持领域语义 | WP-A |
| 旧本地生成资产代理 | `GET /generated-character-drafts/{*path}`、`/generated-characters/{*path}`、`/generated-animations/{*path}`、`/generated-big-fish-assets/{*path}`、`/generated-puzzle-assets/{*path}`、`/generated-custom-world-scenes/{*path}`、`/generated-custom-world-covers/{*path}`、`/generated-qwen-sprites/{*path}` | 已删除 | 正式读取统一走 `GET /api/assets/read-url` 或 asset object projection；`/generated-*` 仅允许作为 legacyPublicPath/object key 标识，不再作为可裸读路由 | WP-AS、WP-FE、WP-DEL |
| LLM 代理 | `POST /api/llm/chat/completions` | 收敛 | 仅作为平台能力代理；玩法 prompt 不允许由前端直接传入 | WP-PF、WP-API |
@@ -59,7 +59,7 @@ G1 单 owner 文件范围：
| --- | --- |
| `shared-contracts/src/api.rs` | `ApiResponseMeta`、`ApiErrorPayload`、`ApiSuccessEnvelope<T>`、`ApiErrorEnvelope` |
| `shared-contracts/src/admin.rs` | `AdminLoginRequest/Response`、`AdminSessionPayload`、`AdminMeResponse`、`AdminOverviewResponse`、`AdminDebugHttpRequest/Response` |
| `shared-contracts/src/auth.rs` | `AuthLoginOptionsResponse`、`AuthUserPayload`、`PublicUserSummaryPayload`、`PublicUserSearchResponse`、`PasswordEntry*`、`PasswordChange*`、`PasswordReset*`、`AuthMeResponse`、`AuthSessionsResponse`、`RefreshSessionResponse`、`Logout*`、`Phone*`、`Wechat*` |
| `shared-contracts/src/auth.rs` | `AuthLoginOptionsResponse`、`AuthUserPayload`、`PublicUserSummaryPayload`、`PublicUserSearchResponse`、`PasswordEntry*`、`PasswordChange*`、`PasswordReset*`、`AuthMeResponse`、`AuthSessionsResponse`、`RevokeAuthSessionResponse`、`RefreshSessionResponse`、`Logout*`、`Phone*`、`Wechat*` |
| `shared-contracts/src/ai.rs` | `CreateAiTaskRequest`、`AppendAiTextChunkRequest`、`CompleteAiStageRequest`、`AttachAiResultReferenceRequest`、`FailAiTaskRequest`、`AiTask*Payload`、`AiTaskMutationResponse`、`AiTaskAcceptedResponse` |
| `shared-contracts/src/assets.rs` | Direct upload、read url、asset object、asset binding、asset history、character visual/animation、workflow cache、role asset workflow 相关 DTO |
| `shared-contracts/src/creation_agent_document_input.rs` | `ParseCreationAgentDocumentInputRequest/Response`、`CreationAgentDocumentInputPayload` |
docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md
+36 -5
View File
@@ -115,6 +115,8 @@
1. 从 cookie 读出原始 refresh token
2. 计算 hash
3. 与 `refresh_session.refresh_token_hash` 比较
4. 若 refresh cookie 缺失或不可用，再使用 Bearer access token claims 中的 `sid` 与 `refresh_session.session_id` 比较
5. 会话列表按“同设备 + 同 IP”聚合时，组内任一 session 命中当前 hash 或当前 `sid`，整组都视为当前设备组
## 5. 表访问级别
@@ -228,9 +230,10 @@
写入规则：
1. 按当前 cookie 找 session
2. 写 `revoked_at = now`
3. 写 `revoked_reason_code = logout`
4. 同时提升 `user_account.token_version`
2. 如果 refresh cookie 缺失，则回退用 Bearer access token claims 中的 `sid` 找当前 session
3. 写 `revoked_at = now`
4. 写 `revoked_reason_code = logout`
5. 同时提升 `user_account.token_version`
### 8.4 吊销全部会话
@@ -248,7 +251,7 @@
触发点：
1. `POST /api/auth/sessions/:sessionId/revoke`
1. `POST /api/auth/sessions/{sessionId}/revoke`
写入规则：
@@ -257,6 +260,13 @@
3. 只改目标 `refresh_session`
4. `revoked_reason_code = session_revoke`
5. 不提升 `token_version`
6. 撤销后必须同步 auth store 到 SpacetimeDB
读取约束：
1. Bearer JWT 中的 `sid` 必须对应 active `refresh_session`
2. 被该接口撤销的设备即使 access token 未过期，后续请求也必须立刻返回未授权
3. 该接口不承担当前设备退出语义；当前设备退出固定走 `/api/auth/logout`
### 8.6 账号被禁用或并入
@@ -315,13 +325,18 @@
1. `clientLabel` 当前阶段继续兼容保留，但固定与 `deviceDisplayName` 对齐。
2. `ipMasked`、`isCurrent` 继续在 Axum 侧派生。
3. 同设备同 IP 的 active sessions 由 Axum 聚合后返回一条记录。
4. `sessionId` 是代表 ID；当前组代表 ID 使用当前 `sid` 对应 session。
5. `sessionIds` 返回组内全部 active session ID，`sessionCount` 返回组内数量。
6. 聚合组时间语义：`createdAt` 取最早创建时间，`lastSeenAt` 与 `expiresAt` 取最新值。
### 10.3 `POST /api/auth/logout`
依赖：
1. 当前 cookie 命中的 `refresh_session`
2. `user_account.token_version`
2. cookie 缺失时 Bearer `sid` 命中的 `refresh_session`
3. `user_account.token_version`
### 10.4 `POST /api/auth/logout-all`
@@ -330,6 +345,22 @@
1. 当前 `user_id` 下全部活跃 `refresh_session`
2. `user_account.token_version`
### 10.5 `POST /api/auth/sessions/{sessionId}/revoke`
依赖：
1. 当前 Bearer JWT 的 `user_id`
2. 当前 Bearer JWT 的 `sid`
3. 目标 `refresh_session.session_id`
4. `refresh_session.revoked_at`
5. `refresh_session.expires_at`
固定行为：
1. 目标 session 必须属于当前用户
2. 目标 session 不能是当前 `sid`
3. 成功只撤销目标 session，不递增 `token_version`
## 11. 与当前 Node `user_sessions` 的映射关系
| Node `user_sessions` 列 | 新 `refresh_session` 字段 | 迁移规则 |
docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+15 -3
View File
@@ -23,7 +23,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
| 领域 | 表 |
| --- | --- |
| 运维迁移 | `database_migration_operator`, `database_migration_import_chunk` |
| 认证 | `auth_store_snapshot`, `user_account`, `auth_identity`, `refresh_session` |
| 认证 | `auth_store_snapshot`, `auth_store_projection_meta`, `user_account`, `auth_identity`, `refresh_session` |
| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `analytics_date_dimension`, `tracking_event`, `tracking_daily_stat`, `profile_task_config`, `profile_task_progress`, `profile_task_reward_claim`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_invite_code`, `profile_referral_relation`, `profile_played_world`, `profile_membership`, `profile_recharge_order`, `profile_feedback_submission`, `profile_save_archive` |
| RPG 运行时 | `story_session`, `story_event`, `npc_state`, `inventory_slot`, `battle_state`, `treasure_record`, `quest_record`, `quest_log`, `player_progression`, `chapter_progression` |
| 世界创作 | `custom_world_profile`, `custom_world_session`, `custom_world_agent_session`, `custom_world_agent_message`, `custom_world_agent_operation`, `custom_world_draft_card`, `custom_world_gallery_entry` |
@@ -60,7 +60,7 @@ SELECT * FROM database_migration_operator WHERE operator_identity = '<identity>'
### `auth_store_snapshot`
- 作用：保存旧内存认证仓储的整份 JSON 快照，用于迁移和恢复；后续正式表拆分后仍可作为导入/导出桥。
- 作用：保存旧内存认证仓储的整份 JSON 快照，用于历史迁移和兜底恢复；运行期认证同步不再继续刷新 `snapshot_id = 'default'`，而是直接导入正式认证表。
- 结构：`snapshot_id PK: String`, `snapshot_json: String`, `updated_at: Timestamp`。
- 索引：主键 `snapshot_id`。
@@ -69,6 +69,17 @@ SELECT * FROM auth_store_snapshot;
SELECT * FROM auth_store_snapshot WHERE snapshot_id = 'default';
```
### `auth_store_projection_meta`
- 作用：记录正式认证表最近一次由认证快照导入的时间，避免启动恢复时旧 `auth_store_snapshot/default` 因带有时间戳而覆盖较新的正式认证表。
- 结构：`meta_id PK: String`, `updated_at: Timestamp`。
- 索引：主键 `meta_id`。
```sql
SELECT * FROM auth_store_projection_meta;
SELECT * FROM auth_store_projection_meta WHERE meta_id = 'default';
```
### `user_account`
- 作用：用户账号主表，保存用户名、公开百梦号、手机号掩码、登录方式、密码登录开关、token 版本和默认不前端展示的运营标签。
@@ -328,7 +339,8 @@ SELECT * FROM profile_membership WHERE user_id = '<user_id>';
### `profile_recharge_order`
- 作用：充值订单表，记录用户购买光点或会员的订单、支付渠道、支付时间、积分变更和会员到期时间。
- 结构：`order_id PK: String`, `user_id: String`, `product_id: String`, `product_title: String`, `kind: RuntimeProfileRechargeProductKind`, `amount_cents: u64`, `status: RuntimeProfileRechargeOrderStatus`, `payment_channel: String`, `paid_at: Timestamp`, `created_at: Timestamp`, `points_delta: i64`, `membership_expires_at: Option<Timestamp>`。
- 结构：`order_id PK: String`, `user_id: String`, `product_id: String`, `product_title: String`, `kind: RuntimeProfileRechargeProductKind`, `amount_cents: u64`, `status: RuntimeProfileRechargeOrderStatus`, `payment_channel: String`, `paid_at: Option<Timestamp>`, `provider_transaction_id: Option<String>`, `created_at: Timestamp`, `points_delta: i64`, `membership_expires_at: Option<Timestamp>`。
- 支付口径：`mock` 渠道创建后立即 `paid` 并入账；微信小程序 `wechat_mp` 渠道创建时为 `pending`，微信支付通知确认后改为 `paid`，`provider_transaction_id` 保存微信支付平台订单号。
- 索引：`user_id`, `(user_id, created_at)`。
```sql
docs/technical/WECHAT_LOGIN_REAL_INTEGRATION_RUNBOOK_2026-04-21.md
+2
View File
@@ -290,6 +290,8 @@ POST /api/auth/wechat/miniprogram-login
4. 若 `auth_binding_status=pending_bind_phone`，页面必须进入绑定手机号界面
5. 绑定成功后，应切回正常已登录状态
小程序原生手机号授权链路中，请求体应携带 `wechatPhoneCode`。后端调用微信 `getuserphonenumber` 后，需要按微信原始响应字段 `phoneNumber` / `purePhoneNumber` / `countryCode` 解析手机号；如果误按 Rust 字段名 `phone_number` / `pure_phone_number` / `country_code` 解析，会出现已传 `wechatPhoneCode` 但返回“微信手机号授权失败：缺少手机号”的假失败。
## 10. 后端验收点
当前后端至少应满足以下检查：
docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md
+1 -1
View File
@@ -132,7 +132,7 @@ Content-Type: application/json
}
```
9. `api-server` 通过微信 `stable_token` 获取小程序 `access_token`，再调用 `getuserphonenumber` 换取平台验证后的手机号，并复用现有微信待绑定账号合并逻辑。成功后重新签发 `active` 系统 token。
9. `api-server` 通过微信 `stable_token` 获取小程序 `access_token`，再调用 `getuserphonenumber` 换取平台验证后的手机号，并复用现有微信待绑定账号合并逻辑。微信返回的手机号字段使用 `phoneNumber` / `purePhoneNumber` / `countryCode`，后端解析时必须兼容这些原始 camelCase 字段；否则会在已收到 `wechatPhoneCode` 的情况下误报“微信手机号授权失败：缺少手机号”。成功后重新签发 `active` 系统 token。
10. H5 复用 `consumeAuthCallbackResult()` 消费 `auth_token` 并进入现有登录态恢复流程。
补充：H5 里的旧短信验证码绑定页继续保留为非小程序环境兜底；小程序原生手机号授权只替代“手动输入手机号 + 短信验证码”这一步，不代表后台静默读取本机号码。
jenkins/Jenkinsfile.production-api-build
+1 -1
View File
@@ -10,7 +10,7 @@ pipeline {
}
environment {
GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
CARGO_HOME = '/home/dsk/.cache/genarrative-jenkins/api-server/cargo-home'
CARGO_TARGET_DIR = '/home/dsk/.cache/genarrative-jenkins/api-server/cargo-target/prod-release'
CARGO_INCREMENTAL = '0'
jenkins/Jenkinsfile.production-api-deploy
+25 -8
View File
@@ -9,6 +9,7 @@ pipeline {
environment {
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
}
parameters {
@@ -66,13 +67,28 @@ pipeline {
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
}
steps {
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [[$class: 'CleanBeforeCheckout']],
userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
])
script {
def checkoutFromRemote = { String remoteUrl ->
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [
[$class: 'CleanBeforeCheckout'],
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
],
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
])
}
try {
checkoutFromRemote(env.GIT_REMOTE_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
} catch (error) {
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
}
}
script {
if (params.COMMIT_HASH?.trim()) {
echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
@@ -84,7 +100,8 @@ pipeline {
chmod +x scripts/jenkins-checkout-source.sh
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
COMMIT_HASH="" \
GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
scripts/jenkins-checkout-source.sh
'
jenkins/Jenkinsfile.production-database-export
+25 -8
View File
@@ -9,6 +9,7 @@ pipeline {
environment {
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
}
parameters {
@@ -82,20 +83,36 @@ pipeline {
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
}
steps {
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [[$class: 'CleanBeforeCheckout']],
userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
])
script {
def checkoutFromRemote = { String remoteUrl ->
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [
[$class: 'CleanBeforeCheckout'],
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
],
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
])
}
try {
checkoutFromRemote(env.GIT_REMOTE_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
} catch (error) {
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
}
}
sh '''
bash -lc '
set -euo pipefail
chmod +x scripts/jenkins-checkout-source.sh
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
COMMIT_HASH="${COMMIT_HASH:-}" \
GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
scripts/jenkins-checkout-source.sh
'
jenkins/Jenkinsfile.production-database-import
+25 -8
View File
@@ -9,6 +9,7 @@ pipeline {
environment {
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
}
parameters {
@@ -140,20 +141,36 @@ pipeline {
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
}
steps {
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [[$class: 'CleanBeforeCheckout']],
userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
])
script {
def checkoutFromRemote = { String remoteUrl ->
checkout([
$class: 'GitSCM',
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
doGenerateSubmoduleConfigurations: false,
extensions: [
[$class: 'CleanBeforeCheckout'],
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
],
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
])
}
try {
checkoutFromRemote(env.GIT_REMOTE_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
} catch (error) {
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
}
}
sh '''
bash -lc '
set -euo pipefail
chmod +x scripts/jenkins-checkout-source.sh
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
COMMIT_HASH="${COMMIT_HASH:-}" \
GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
scripts/jenkins-checkout-source.sh
'
jenkins/Jenkinsfile.production-full-build-and-deploy
+1 -1
View File
@@ -12,7 +12,7 @@ pipeline {
}
environment {
GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
}
parameters {

Some files were not shown because too many files have changed in this diff Show More