fmode-app/src/app/core/api/fmode-api.ts

import {
  Agent,
  ArtifactJob,
  AuthSession,
  Deliverable,
  DeliverableGroup,
  MatrixProvision,
  Me,
  Task,
  UploadTicket,
} from './models';

/**
 * 数据访问抽象接口 —— 应用层与数据源之间的**唯一闸门**
 *
 * 依据《数据访问层设计.md》§一/§四。硬约束：
 *   ① 页面/components **禁止** inject(FmodeApi) 或其实现（FR-14 AC-14.2）
 *   ② 业务服务**禁止**直接 fetch / 直接用 fmode-ng（黄金规则 5）
 *   ③ 每个数据域**只有一个** owner 服务
 *
 * 实现：`ParseApi`（真实，走 fmode-ng）/ `MockApi`（演示数据）。
 * 切换由 `environment.useMockData` 单开关控制（api.provider.ts）。
 *
 * ⚠️ `Project` / `EventItem` **不在此接口**：它们是派生投影（由 Agent + Deliverable 组合），
 *    由对应服务计算，见《数据访问层设计.md》§四.1。
 */
export abstract class FmodeApi {
  // ---------- 鉴权 ----------

  /** 发送手机验证码（REST R4：`code === 1` 才算成功） */
  abstract sendMobileCode(mobile: string): Promise<void>;

  /** 验证码登录（REST R5：`code === 200 && data.token` 才算成功） */
  abstract loginWithMobile(mobile: string, code: string): Promise<AuthSession>;

  /** Token 直登（REST R1：`POST /parse/users/me`） */
  abstract loginWithToken(token: string): Promise<AuthSession>;

  /** 用已有 token 取回身份 */
  abstract fetchMe(token: string): Promise<Me>;

  // ---------- 数字生命（实况） ----------

  /** 列表查询（云函数 xlosi3m46q，`op:'query'`） */
  abstract fetchAgents(): Promise<Agent[]>;

  /** 单条查询；`code` 404/403 时返回 null */
  abstract fetchAgentStatus(agentId: string): Promise<Agent | null>;

  // ---------- 会话（Matrix） ----------

  /** 开通 Matrix 身份（云函数 RP5Ht55NeX）；绑定表命中时 `cached: true` */
  abstract provisionMatrix(agentId: string): Promise<MatrixProvision>;

  /** 校验/刷新凭据（`validate: 1`） */
  abstract validateMatrix(agentId: string): Promise<MatrixProvision>;

  // ---------- 交付成果 ----------

  /** 列表（云函数 lfYlgU7SkK，`action:'list'`） */
  abstract fetchDeliverables(opts?: { agentId?: string; limit?: number }): Promise<Deliverable[]>;

  /** 按项目分组（`action:'byProject'`） */
  abstract fetchDeliverablesByProject(limit?: number): Promise<DeliverableGroup[]>;

  // ---------- 任务看板（FR-07b） ----------

  /**
   * 任务列表（按 agentId 过滤）。
   * 🔴 云函数接收端**尚未实现**：就绪前实现方须返回**空数组**，**禁止伪造数据**
   *    （SPEC FR-07b「依赖声明」）。
   */
  abstract fetchTasks(agentId: string): Promise<Task[]>;

  /** 任务详情（含 runs / comments / attachments） */
  abstract fetchTaskDetail(taskId: string): Promise<Task | null>;

  // ---------- 上传 ----------

  /** 取预签名（云函数 AlP56LCKFm）；缺 uploadUrl 即抛错，不得静默降级 */
  abstract requestUploadUrl(filename: string, mimeType: string, size: number): Promise<UploadTicket>;

  /** 预签名直传（前端不经手任何 OBS 密钥） */
  abstract uploadFile(
    file: File,
    onProgress?: (pct: number) => void,
  ): Promise<{ key: string; publicUrl: string }>;

  // ---------- 成果文件入库（云盘同步） ----------

  /**
   * 告诉平台「这个成果的附件在哪、该传到哪」。
   *
   * 平台侧（云函数 lfYlgU7SkK `action:'requestSync'`）：
   *   ① 按文件名取 OBS 预签名（与前端上传**同一条**上传通道）
   *   ② 把预签名地址写进该成果的待同步队列，**由容器自己下载原文件后 PUT**
   *   ③ 收到文件后回写 `artifacts[i].url` 为云盘公网地址
   *
   * 为什么不在这里直接传：文件在**容器里**（如 /opt/data/...），
   * 浏览器拿不到，只能由容器完成搬运。前端负责的是「登记 + 触发」。
   */
  abstract requestArtifactSync(input: {
    deliverableId: string;
    /** 容器内的原始路径 */
    source: string;
    filename: string;
  }): Promise<{ queued: boolean; message?: string }>;

  // ---------- 成果文件搬运队列（容器侧轮询） ----------

  /**
   * 登记一次搬运：把容器里的 `source` 文件搬到云盘。
   *
   * 🔴 **只报「传哪个」，不报「传到哪」** —— 上传地址与必需的头由云函数
   *    用服务端密钥签好后写进队列，客户端不接触任何密钥
   *    （2026-10-21 定稿；此前的「App 自签」方案已废弃）。
   *
   * @param index 附件在成果 `artifacts[]` 中的下标 —— 保证同名附件不互相覆盖
   */
  abstract enqueueArtifactJob(job: {
    deliverableId: string;
    agentId: string;
    /** 容器内的原始路径 */
    source: string;
    filename: string;
    index: number;
  }): Promise<{ id: string }>;

  /** 容器领取待办（按 agentId，只取未完成且未过期的） */
  abstract fetchArtifactJobs(agentId: string): Promise<ArtifactJob[]>;

  /** 容器回执：上传成功（带公网地址）/ 失败（带原因） */
  abstract ackArtifactJob(input: {
    id: string;
    ok: boolean;
    publicUrl?: string;
    error?: string;
  }): Promise<void>;

}