后端重写提交

docs/technical/README.md

@@ -4,6 +4,8 @@
 
 ## 文档列表
 
+- [PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md](./PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md)：`platform-llm` 文本模型网关首版设计，冻结 OpenAI 兼容 `/chat/completions`、SSE 增量解析、错误模型与重试边界。
+- [API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md](./API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md)：`api-server` 接入 `platform-llm` 的最小代理设计，冻结 `/api/llm/chat/completions` 的配置、状态注入与首版非流式兼容边界。
 - [PHONE_SMS_LOGIN_STAGE_A_IMPLEMENTATION_2026-04-21.md](./PHONE_SMS_LOGIN_STAGE_A_IMPLEMENTATION_2026-04-21.md)：冻结手机号验证码登录第一阶段的真实落地边界，明确游客兜底默认关闭、公开请求不污染登录态，以及 smoke 必须覆盖短信登录主链。
 - [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` 语义。
@@ -19,6 +21,13 @@
 - [PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` 首版 JWT 适配设计，冻结 `JwtConfig`、claims 结构、`HS256` 签发/校验、`api-server` Bearer 中间件与内部验收路由边界。
 - [OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](./OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)：面向 Axum、`platform-auth` 与 `SpacetimeDB` 身份透传的 OIDC 风格 JWT claims 设计，冻结 `iss/sub/sid/provider/roles` 等关键字段。
 - [RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md](./RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md)：Rust 工作区统一日志模块 `shared-logging` 的职责边界、API、输出风格与 `api-server` 迁移规则。
+- [RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md](./RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md)：把 `shared-contracts` 从占位目录推进成真实共享协议 crate，冻结统一 envelope、`auth/*`、`runtime/settings`、`assets/*` 与 `story-sessions/*` 首批公开 DTO 的迁移边界。
+- [RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md](./RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md)：继续把 `assets/*` 与 `story-sessions/*` 的成功响应从 handler 内 `json!` 手拼收口到 `shared-contracts`，冻结显式响应 DTO 与适配边界。
+- [RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md](./RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md)：把 `shared-kernel` 从目录占位推进到首批真实共享内核，冻结第一阶段只允许上提的基础字符串、ID 与时间处理能力，以及首批接入 crate 范围。
+- [RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md](./RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md)：在不扩公共 API 的前提下，把 `shared-kernel` 第一阶段已冻结的字符串、UUID 与时间处理能力继续接入 `module-runtime`、`module-story`、`spacetime-client` 与 `api-server`。
+- [RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md)：继续把 `shared-kernel` 扩到跨多个纯领域 crate 已稳定重复的字符串列表归一化与前缀种子 ID 拼接能力，明确第三阶段仍不进入 JSON、配置与平台语义处理。
+- [RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md)：继续把 `shared-kernel::normalize_required_string(...)` 接入更多纯领域 crate，收口跨模块重复的“trim + 判空 + 映射字段错误”逻辑，同时明确不进入平台与 JSON 语义。
+- [RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md)：继续把 `shared-kernel::normalize_required_string(...)` 接入 `module-runtime` 与 `module-assets` 剩余的纯字段级归一化逻辑，保留 `object_key` 等模块局部语义不变。
 - [SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md)：`M2` 第七张微信 OAuth 状态表 `wechat_auth_state` 的字段、过期/消费语义、`wechat/start` 与 `wechat/callback` 的单次消费规则，以及多实例下的清理策略。
 - [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` 的作用域、活跃态、刷新/解除规则与读取派生约束。
@@ -29,9 +38,16 @@
 - [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于当前 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。
 - [M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md](./M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md)：冻结 M6 剩余的 STS 与服务端上传 helper 落地口径，明确当前上传主链为服务器上传 OSS，Web 端只负责签名读下载。
 - [AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md](./AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md)：冻结 `POST /api/assets/objects/confirm` 从 Axum 通过 Rust SDK 调用 `SpacetimeDB procedure` 的最小落地方案，明确本地 server、数据库名、procedure/reducer 分工与 `spacetime-client` 边界。
+- [M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)：冻结 `M3` 首批 `runtime settings` 纵向切片的表字段、默认值、procedure、Axum facade、错误 contract 与测试策略。
+- [SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)：冻结 `M5` Agent session create / snapshot 的最小 SpacetimeDB 与 Axum facade 闭环，明确本轮不迁移 LLM、SSE、卡片更新和完整 action registry。
+- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md)：冻结 `M5` Agent `message submit / operation query` 的 deterministic 最小闭环，明确同步写入 user/assistant 消息、`process_message` operation 与 session 进度推进规则。
+- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md)：冻结 `M5` Agent `/messages/stream` 的最小兼容 SSE facade，明确复用 Stage 7 的同步写表逻辑，只输出当前前端真实消费的 `reply_delta / session / done / error` 事件。
+- [SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md)：补齐 `M5` Stage 5 遗漏的 owner-only `GET /api/runtime/custom-world-library/:profileId` 设计，冻结单条 profile detail 的 SpacetimeDB procedure、client facade、404 语义与 Axum 路由扩展方式。
+- [M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)：冻结 `M3` 第二批 `browse history` 纵向切片的 `user_browse_history` 表、双路径 facade、宽松归一化、去重排序规则与测试策略。
 - [ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](./ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)：冻结已确认 `asset_object` 绑定到业务实体槽位的首版 reducer/procedure、通用 `asset_entity_binding` 表与 Axum facade。
 - [FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md](./FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md)：把鉴权、浏览历史、runtime story 快照、NPC 待接委托与正式生成编排继续后移到 Express 后端的实施方案与验收口径。
 - [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
+- [ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md](./ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md)：冻结编码检查不扫描临时 Cargo / verify 工作区、同时把 Rust 源文件纳入 UTF-8 校验的修复口径。
 - [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
 - [CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md](./CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md)：世界草稿生成失败后等待页误显示为“卡在编译草稿卡”的根因拆解、主链与增强链路边界，以及本次修复策略。
 - [CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md](./CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md)：世界草稿里“资产已生成但结果页看不到”的根因拆解，包含角色主形象展示、分幕背景露出和 fallback 资源格式修复。
@@ -51,6 +67,23 @@
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md)：记录工作包 E 已完成的前端 runtime story 主链真实迁移、NPC 交互与 gateway/client 收口、旧入口兼容降级，以及定向回归验证结果。
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md)：记录工作包 G 已完成的后端 runtime session / action service 物理迁移、新域原语导出、旧热点兼容降级，以及定向 runtime story 回归验证结果。
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md)：记录工作包 H 已完成的 RPG 运行时仓储拆分、shared runtime contract 分文件、旧 `story.ts` façade 兼容与定向回归结果。
+- [M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `M4` 首轮已落地的 `story_session / story_event` SpacetimeDB 基座、`begin_story_session / continue_story` reducer、同步返回快照的 story procedure、`spacetime-client` facade 与新的 `/api/story/sessions*` Axum 接口，以及当前尚未兼容旧 `runtime story` 路由的边界。
+- [M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md](./M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/story/sessions/:storySessionId/state` 这条最小 story state 查询切片，明确当前只返回 `storySession + storyEvents`，不等价于旧 `runtime story state` 兼容完成。
+- [M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md](./M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md)：冻结旧 `POST /api/runtime/story/state/resolve` 兼容桥的首版边界，明确先补 `RuntimeStoryActionResponse` DTO 与状态桥，再继续进入 Rust `actions/resolve` 与正式 snapshot projection。
+- [M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md](./M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md)：冻结 `module-ai` 首版的任务/阶段/流式片段/结果引用领域模型、最小内存服务与后续 `platform-llm` / `api-server` / `spacetime-module` 的边界。
+- [M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-ai` 在 `spacetime-module` 中首轮已落地的 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 真相表、最小 reducer/procedure 与当前仍未扩到真实模型调用和 Axum facade 的边界。
+- [M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md](./M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md)：冻结 `module-ai` 从 `shared-contracts`、`spacetime-client` 到 `api-server` 的最小 AI task mutation facade，明确 `start` 路由当前只返回 `202 Accepted`。
+- [M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-quest` 首轮已落地的 `quest_record / quest_log` 字段模型、`accept_quest / apply_quest_signal / acknowledge_quest_completion / turn_in_quest` reducer 边界，以及当前刻意未扩到奖励结算和 Axum facade 的范围。
+- [M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-runtime-item` 首轮已落地的 `treasure_record` 字段模型、奖励快照 contract、`resolve_treasure_interaction` reducer/procedure 边界，以及当前刻意未扩到 `inventory_slot` 和 Axum facade 的范围。
+- [M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md)：冻结 `module-combat` 首版 `battle_state`、`resolve_combat_action`、`fight / spar` 收束规则与 `spacetime-module` 接线边界，明确当前暂不接入 `inventory_use` 与跨子域奖励联动。
+- [M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md](./M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md)：冻结 `module-combat` 从 `spacetime-module procedure` 到 `spacetime-client` 再到 `api-server` 的最小同步返回链，明确当前只新增独立 battle facade，不直接兼容旧 runtime story 总入口。
+- [M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md](./M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/story/battles/:battleStateId` 这条最小 battle state 查询切片，明确当前只返回单个 `battleState` 真相态，不等价于旧 runtime story state 兼容完成。
+- [M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md](./M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/runtime/sessions/:runtimeSessionId/inventory` 这条最小 inventory 查询切片，明确当前只返回 `inventory_slot` 真相表拆分后的 `backpackItems + equipmentItems`。
+- [M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `module-npc` 首轮已落地的 `npc_state / relation_state / stance_profile` 领域 contract、`resolve_npc_social_action` 规则原语，以及 `spacetime-module` 的最小 reducer / procedure 接线边界。
+- [M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md](./M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md)：冻结 `npc_fight / npc_spar` 在 `spacetime-module` 聚合层初始化 `battle_state` 的最小联合 procedure 边界，明确仍不把战斗初始化字段回灌到 `module-npc` 纯领域 crate。
+- [M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md](./M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md)：冻结 `resolve_npc_battle_interaction_and_return` 向上接入 `spacetime-client` 与 `api-server` 的最小同步返回链，明确当前只新增独立 `POST /api/story/npc/battle` facade。
+- [M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `module-progression` 首轮已落地的 `player_progression / chapter_progression` 字段模型、成长曲线、章节预算与记账 reducer / procedure 边界，以及当前刻意未扩到完整章节蓝图迁移和 quest/combat 自动联动的范围。
+- [M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md](./M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md)：冻结 `turn_in_quest` 与 `resolve_combat_action(Victory)` 到 `player_progression / chapter_progression` 的最小联动口径，明确 battle 奖励字段、章节账本静默跳过规则与本轮不扩到的范围。
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md)：对照执行计划逐项复核第一批与第二批并行工作的真实落地状态，记录本轮确认到的测试合流收口遗漏与文档索引补齐结果。
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md)：记录 RPG 执行计划第三批收口已完成的前端新域主链接回、后端新仓储接线、shared contract 直连收紧、旧兼容脚本物理删除，以及明确未扩到 UI 和无关历史文档的边界。
 - [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md)：记录 RPG 主链旧 `GameShell`、`useGame*`、`hooks/story`、`runtimeRoutes`、`modules/story/*`、`contracts/story.ts` 脚本的物理删除范围、残留依赖扫描和定向验证结果。