init with react+axum+spacetimedb

docs/technical/CUSTOM_WORLD_PHASE4_COUNT_SEMANTICS_ALIGNMENT_2026-04-20.md

@@ -0,0 +1,115 @@
+# 自定义世界 Phase4 数量字段语义对齐说明 2026-04-20
+
+更新时间：`2026-04-20`
+
+## 1. 背景
+
+在排查世界草稿生成等待页问题后，继续执行 `server-node` 相关测试时，发现 Phase4 仍有两处失败：
+
+1. `generate_characters` 后草稿作品卡的角色数量没有按预期增长。
+2. `generate_landmarks` 的 HTTP 用例对地点数量使用了过时的固定基线。
+
+这两个问题本质上都和“数量字段语义不一致”有关。
+
+## 2. 当前产品语义
+
+创作中心草稿卡在前端展示的是：
+
+```text
+角色 X
+地点 Y
+```
+
+这里的“角色”从产品感知上表示：
+
+**当前草稿中已经长出来、可继续精修的全部角色对象数量。**
+
+而不是：
+
+**仅 playable / 仅主角位角色数量。**
+
+对应地，“地点”表示：
+
+**当前草稿中已经存在的地点对象数量。**
+
+## 3. 之前的偏差
+
+### 3.1 角色数量偏差
+
+`server-node/src/services/customWorldWorkSummaryService.ts` 在草稿态里原先只统计：
+
+```ts
+draftProfile.playableNpcs.length
+```
+
+但 Phase4 `generate_characters` 的实现是把新增角色插入：
+
+```ts
+draftProfile.storyNpcs
+```
+
+所以会出现：
+
+1. 角色卡确实新增了
+2. `storyNpcs` 也确实变多了
+3. 创作中心草稿卡上的“角色数”却没有同步增加
+
+这会让产品表现和数据真实状态不一致。
+
+### 3.2 地点数量断言偏差
+
+`server-node/src/app.test.ts` 的 `generate_landmarks` HTTP 用例里，之前写死了：
+
+```ts
+assert.ok((sessionPayload.draftProfile?.landmarks?.length ?? 0) >= 6);
+```
+
+但当前基础草稿阶段的地点基线已经调整为：
+
+```ts
+FOUNDATION_DRAFT_LANDMARK_COUNT = 2
+```
+
+所以 Phase4 的正确断言应该是：
+
+```text
+在当前会话已有地点基线上，再新增 2 个地点
+```
+
+而不是继续沿用旧版本里“基础草稿默认至少 4 个地点”的固定假设。
+
+## 4. 本次修正
+
+### 4.1 草稿摘要角色数
+
+草稿态 `playableNpcCount` 在工作摘要里继续沿用既有字段名，但统计语义调整为：
+
+```text
+全部草稿角色数量 = playableNpcs + storyNpcs 去重后的总数
+```
+
+原因：
+
+1. 前端现有 contract 和展示字段已经复用 `playableNpcCount`
+2. 这次目标是最小修复，不额外扩 contract
+3. 草稿态 UI 标签本身展示的是“角色”，不是“可扮演角色”
+
+因此这次保留字段名，修正其在草稿态的统计语义。
+
+### 4.2 Phase4 地点断言
+
+`generate_landmarks` 的 HTTP 用例改为基于当前会话的 `draftProfile.landmarks.length` 做增量校验：
+
+```text
+新增后数量 >= 基线数量 + 2
+```
+
+这样可以避免未来基础草稿默认地点数再次调整时，Phase4 用例继续被写死基线误伤。
+
+## 5. 约束建议
+
+后续涉及草稿作品卡数量字段时，统一遵守：
+
+1. 草稿态“角色”展示全部草稿角色数，不只统计 playable。
+2. 已发布态如果 UI 明确写“可扮演角色”，再单独按 playable 统计。
+3. 所有数量断言优先使用“当前基线 + 增量”的写法，不要硬编码旧阶段默认数量。