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

import {
  Agent,
  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 }>;
}