JX-BPOS/apps/api/src/modules/interaction/port.ts

/**
 * module: interaction —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
 */
import type { ChatMessage, StaffId, TaskId, ViewBlock } from '@contracts';
import type { InteractionPhase } from './internal/domain/control-handover.ts';
import type { NarrativeEntry } from './internal/domain/chat-projection.ts';

export type Clock = { now(): Date };
export type IdGenerator = { next(): string };

export type InteractionStore = {
  appendMessage(taskId: TaskId, message: ChatMessage): Promise<void>;
  listMessages(taskId: TaskId): Promise<ChatMessage[]>;
  putView(taskId: TaskId, view: { blocks?: readonly ViewBlock[]; html?: string }): Promise<void>;
  getView(taskId: TaskId): Promise<{ blocks?: readonly ViewBlock[]; html?: string } | undefined>;
  setPhase(taskId: TaskId, phase: InteractionPhase): Promise<void>;
  phaseOf(taskId: TaskId): Promise<InteractionPhase | undefined>;
};

/** 自由输入即人事件 —— app 注入 `event`(L1) */
export type HumanEventPublisher = {
  publishHumanEvent(input: { taskId: TaskId; cardId: string; payload: Record<string, unknown> }): Promise<void>;
};

/** 留痕 —— app 注入 `memory`(L2):时间线即任务记忆的可读投影 */
export type MemoryRecorder = {
  append(input: { taskId: TaskId; kind: 'human-input'; title: string; detail?: Record<string, unknown> }): Promise<void>;
  /**
   * 叙事条目 —— 对话流与工作日志**同源不同筛选**:
   * AI 发言与系统事件不另设写入口,一律从任务记忆投影而来(见 `chat-projection`)。
   */
  history(taskId: TaskId): Promise<readonly NarrativeEntry[]>;
};

/** 收件人解析 —— app 注入 `org`(L1):SSE 只推给有权看的人 */
export type Audience = {
  canSee(staffId: StaffId, taskId: TaskId): Promise<boolean>;
};