1

src/data/functionCatalog/npc/npcGift.ts

@@ -1,5 +1,5 @@
 import type { GiftModalState } from '../../../hooks/rpg-runtime-story/uiTypes';
-import type { Encounter, GameState } from '../../../types';
+import type { Encounter } from '../../../types';
 import type { FunctionDocumentationEntry } from '../types';
 
 /**
@@ -16,10 +16,9 @@ export function buildNpcGiftModalIntroText(encounter: Encounter) {
 }
 
 export function buildNpcGiftModalState(
-  state: GameState,
   encounter: Encounter,
   actionText: string,
-  selectedItemId: string | null = state.playerInventory[0]?.id ?? null,
+  selectedItemId: string | null,
 ): GiftModalState {
   return {
     encounter,
@@ -34,13 +33,13 @@ export const NPC_GIFT_FUNCTION: FunctionDocumentationEntry = {
   domain: 'npc',
   title: '向该角色送礼',
   source: 'src/data/functionCatalog/npc/npcGift.ts',
-  summary: '打开送礼面板并根据礼物质量结算 affinity 变化。',
+  summary: '打开送礼面板并由后端结算 affinity 变化。',
   detailedDescription:
-    '它会把当前互动引到礼物选择 modal，通过本地规则估算礼物对该 NPC 的吸引力和好感增益，避免送礼结果漂移。',
-  trigger: '玩家背包里存在可送出的物品时出现在 NPC 交互菜单里。',
+    '它会把当前互动引到礼物选择 modal，礼物列表、好感增益和不可选原因都读取后端 runtimeNpcInteraction view。',
+  trigger: '后端判断当前 NPC 可接收礼物时出现在 NPC 交互菜单里。',
   execution:
-    '首次点击只打开 gift modal，确认礼物后再调用 commitGeneratedState 把送礼结果写回主流程。',
-  result: '玩家可立即看到好感变化与送礼反馈，并影响后续交易、聊天和招募阈值。',
+    '首次点击只打开 gift modal，确认礼物后只提交 itemId 给后端结算。',
+  result: '玩家可立即看到后端结算后的好感变化与送礼反馈，并影响后续交易、聊天和招募阈值。',
   active: true,
   runtime: {
     storyMode: 'modal_then_generate',
@@ -50,7 +49,7 @@ export const NPC_GIFT_FUNCTION: FunctionDocumentationEntry = {
     animationNote: '第一次点击不驱动额外演出，重点是切到礼物面板。',
     storyNote:
       '真正的剧情推进发生在 confirmGift 之后，届时才会写入好感变化与结果文本。',
-    uiNote: '会先打开 gift modal，并默认选中当前最适合作为礼物的物品。',
+    uiNote: '会先打开 gift modal，并默认选中后端 view 中第一件可提交的礼物。',
     compactDetailText: '送礼提升好感',
   },
 };

src/data/functionCatalog/npc/npcTrade.ts

@@ -1,5 +1,5 @@
 import type { TradeModalState } from '../../../hooks/rpg-runtime-story/uiTypes';
-import type { Encounter, GameState, InventoryItem } from '../../../types';
+import type { Encounter } from '../../../types';
 import type { FunctionDocumentationEntry } from '../types';
 
 /**
@@ -16,21 +16,17 @@ export function buildNpcTradeModalIntroText(encounter: Encounter) {
 }
 
 export function buildNpcTradeModalState(
-  state: GameState,
   encounter: Encounter,
   actionText: string,
-  npcInventory: InventoryItem[],
+  selectedNpcItemId: string | null,
+  selectedPlayerItemId: string | null,
+  mode: 'buy' | 'sell' = selectedNpcItemId ? 'buy' : 'sell',
 ): TradeModalState {
-  const selectedNpcItemId =
-    npcInventory.find((item) => item.quantity > 0)?.id ?? null;
-  const selectedPlayerItemId =
-    state.playerInventory.find((item) => item.quantity > 0)?.id ?? null;
-
   return {
     encounter,
     actionText,
     introText: buildNpcTradeModalIntroText(encounter),
-    mode: 'buy',
+    mode,
     selectedNpcItemId,
     selectedPlayerItemId,
     selectedQuantity: 1,
@@ -44,11 +40,11 @@ export const NPC_TRADE_FUNCTION: FunctionDocumentationEntry = {
   source: 'src/data/functionCatalog/npc/npcTrade.ts',
   summary: '打开 NPC 交易流程并结算买卖或交换。',
   detailedDescription:
-    '它负责把当前交互引到交易面板，展示 NPC 库存、折扣和可交换物。第一次点击通常只打开 modal，真正确认后才继续推进剧情。',
+    '它负责把当前交互引到交易面板，库存、价格、折扣和不可选原因都读取后端 runtimeNpcInteraction view。第一次点击通常只打开 modal，真正确认后才继续推进剧情。',
   trigger: '当 NPC 允许交易且自身库存非空时出现在 NPC 交互菜单里。',
   execution:
-    '首次点击进入 trade modal，确认后再通过 commitGeneratedState 把结果写回主流程。',
-  result: '玩家可以买入、以物易物，或在失败时得到明确的价值差提示。',
+    '首次点击进入 trade modal，确认后只提交 mode、itemId、quantity 给后端结算。',
+  result: '玩家可以买入、出售物品，或在后端拒绝时得到明确的失败原因。',
   active: true,
   runtime: {
     storyMode: 'modal_then_generate',
@@ -58,7 +54,7 @@ export const NPC_TRADE_FUNCTION: FunctionDocumentationEntry = {
     animationNote: '第一次点击不播额外战斗或位移动画，重点是切到交易窗口。',
     storyNote:
       '真正的剧情推进发生在 confirmTrade 之后，而不是打开 modal 的瞬间。',
-    uiNote: '会先打开交易 modal，并预选 NPC 第一件商品与玩家第一件可卖物品。',
+    uiNote: '会先打开交易 modal，并预选后端 view 中第一件可提交的买入 / 卖出物品。',
     compactDetailText: '查看库存与价格',
   },
 };