/**
 * Copyright (c) 2025 TWork Team. All rights reserved.
 * This source code is licensed under the TWork License.
 */

/**
 * Host Adapter 契约类型
 *
 * 这些接口是「闭源核心（@twork/*）」与「Electron 壳（apps/electron）」之间的唯一契约面。
 * 核心逻辑只依赖这些抽象，由壳层提供具体实现并注入，从而让核心彻底摆脱对
 * `electron`（app / BrowserWindow / ipcMain）的直接依赖。
 *
 * 设计原则（见 Electron 壳子化规划）：
 *   - 路径（TworkPaths）与广播（TworkEventBus）作为两个薄接缝，永久保留在壳中。
 *   - 存储优先「下沉」：better-sqlite3 是 Node 原生模块、不绑定 Electron，
 *     直接把 database 模块搬进 @twork/shared 即可，无需 TworkStorage 全量透传。
 *     TworkStorage 仅用于「无法下沉」的窄接口场景（如 enhance 历史写入）。
 */

/**
 * 路径接缝：取代核心里的 `app.getPath` / `userData` / `process.env.HOME` 解析。
 * 壳层用 Electron `app.getPath('userData')` 等实现；非 Electron 宿主可用任意实现。
 */
export interface TworkPaths {
  /** 应用数据根目录（Electron: app.getPath('userData')） */
  readonly userDataDir: string
  /** 用户主目录（process.env.HOME || USERPROFILE） */
  readonly homeDir: string
  /** 全局记忆目录，通常为 {userDataDir}/.twork/memory 或 {homeDir}/.twork/memory */
  readonly globalMemoryDir: string
  /** 解析某个工作区的根目录 */
  getWorkspaceDir(workspaceId: string): string
  /** 解析某个工作区的记忆目录（{workspace}/.twork/memory） */
  getWorkspaceMemoryDir(workspaceId: string): string
}

/**
 * 广播接缝：取代 `BrowserWindow.webContents.send`。
 * 核心只「发事件」，由壳层决定如何转成 IPC / WebSocket / 其它传输。
 */
export interface TworkEventBus {
  /**
   * 向宿主（通常是渲染进程）广播一个事件。
   * @param channel 事件通道名（对应现有 IPCChannels 常量或字符串字面量）
   * @param payload 事件负载，需可结构化克隆
   */
  emit(channel: string, payload?: unknown): void
}

/**
 * 存储接缝（窄接口）：仅用于「无法随 DB 层一并下沉」的持久化点。
 * 默认策略是把整个 database 模块下沉进包，此时不需要实现本接口。
 *
 * 本接口聚焦 enhance（提示词增强）引擎所需的历史 / 指标持久化能力，
 * 由壳层用 better-sqlite3 database 实现并注入。
 */
export interface EnhanceStorage {
  /** 批量写入增强历史记录 */
  batchInsertEnhanceHistory(records: readonly unknown[]): void
  /** 更新某条历史记录的「用户接受/拒绝」标记（1=接受，-1=拒绝） */
  updateEnhanceHistoryAccepted(historyId: number, accepted: number): { success: boolean; error?: string }
  /** 对旧记录应用质量权重衰减 */
  applyQualityDecay(): void
  /** 物理清理过期的增强历史（按 TTL 与最大行数） */
  cleanupExpiredEnhanceHistory(ttlMs: number, maxRows: number): void
  /** 写入按天聚合的缓存指标 */
  upsertDailyMetrics(dailyMetrics: unknown): void
  /** 读取模型配置（enhance 用于选取增强模型；只读） */
  getModelConfigs(): Promise<readonly unknown[]>
}

/**
 * 统一的宿主适配聚合：核心初始化时接收一份完整的宿主能力集合。
 */
export interface TworkHost {
  readonly paths: TworkPaths
  readonly events: TworkEventBus
  /** 可选：仅在存储未下沉时提供 */
  readonly enhanceStorage?: EnhanceStorage
}
