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

import { environment } from '../../../environments/environment';
import { tsOf } from '../time';
import { prettifyStorageKey } from '../s3-link';
import { Scope } from '../acl';
import { FmodeApi } from './fmode-api';
import {
  Agent,
  AgentStatus,
  ChatThreadRecord,
  ChatThreadUpsert,
  WorkspaceRecord,
  WorkspaceUpsert,
  Artifact,
  ArtifactJob,
  AuthSession,
  ChannelConfig,
  Deliverable,
  DeliverableGroup,
  FileEntry,
  MatrixProvision,
  Me,
  SessionFile,
  OrgMembership,
  OrgUser,
  OrgUserPage,
  Task,
  UploadTicket,
  WorkGroup,
  UsageSession,
} from './models';

/**
 * 真实数据源实现 —— 走 fmode 平台云函数 + REST（《API-契约.md》）
 *
 * 依据《数据访问层设计.md》§一/§二：本类是 `FmodeApi` 的**真实实现**，
 * 由 `api.provider.ts` 在 `environment.useMockData === false` 时装配。
 *
 * ## 约定
 *
 * - 云函数统一入口 `POST https://server.fmode.cn/api/functions`
 *   （头 `X-Parse-Application-Id` / `X-Parse-Session-Token`；体 `{id, token, params}`）
 * - 错误处理：HTTP 200 但 `body.code` 为 401/403 → 视为业务错误并抛出，
 *   文案取 `msg` → `mess` → `message`
 * - 云函数返回的 `host` / `channels` / `balance` 是**字符串形态 JSON**，
 *   映射层兼容「已是对象」与「是字符串」两种形态（存量 `parseJsonLoose` 的教训）
 *
 * ## 前端安全边界（黄金规则 6 / NFR-03）
 *
 * 前端**不含任何服务端密钥**：无 masterKey、无 OBS AK/SK、无 Matrix 派生密码。
 * Matrix 凭据一律由 provision 云函数服务端签发。
 *
 * ## 一期未实现项
 *
 * `fetchTasks` / `fetchTaskDetail` 的云函数接收端**尚未实现**（SPEC FR-07b 依赖声明），
 * 故**显式抛错**而非静默返回空数组 —— 空数组会把「未接入」伪装成「没有数据」。
 */

/*
 * 端点来自环境配置（黄金规则 6：serverURL 只在初始化处配置一次）。
 * 见 `src/environments/environment.base.ts`。
 */
const FUNCTION_API = environment.endpoints.functionsBase;
const PARSE_BASE = environment.endpoints.parseServer;
const PARSE_APP_ID = environment.endpoints.parseAppId;

/** 云函数 objectId（《API-契约》§二） */
const FN = {
  agentStatus: 'xlosi3m46q',
  /** 容器重命名（2026-11-05 新建，独立于 agentStatus） */
  agentRename: 'AqXGNNVRNb',
  deliverables: 'lfYlgU7SkK',
  provision: 'RP5Ht55NeX',
  tokenSync: 'zl4yU8PAEB',
  uploadUrl: 'AlP56LCKFm',
  workgroup: 'V1EBgm05y2',
  /** 会话目录（2026-10-31 新建，Function.name = fmodeagent-chatthreads） */
  chatThreads: 'oR5O67i1Cm',
  /**
   * 文件台账（2026-11-10 新建，Function.name = fmode-file-hub）
   *
   * 为什么另起一个：老成果函数 `lfYlgU7SkK` 的 report 用字段白名单写入，
   * 里面没有 `threadRoot`，容器传了也被静默丢弃，成果无法归属到会话。
   * 用户裁决：现有云函数一行不动，新建独立函数走新接口。
   */
  fileHub: 'THXAOGKiPK',
  /**
   * 文件正文代理（2026-11-11 新建，Function.name = fmode-file-read）。
   *
   * 🔴 为什么要它：云盘 s3.fmode.cn 是 public-read 但**没配 CORS**，
   *    浏览器 fetch 必被拦（「加载失败：Failed to fetch」），
   *    .md / .txt 在页内根本渲染不出来。
   *    由服务端代取文本，浏览器只调本域（已配 ACAO:*）。
   *
   * ⚠️ 已部署（2026-11-11，`tocXyQjyh6`）。未部署时此 ID 为空，`readText` 会抛错，
   *    调用方回落到「在新窗口打开」。
   */
  fileRead: 'tocXyQjyh6',
  /**
   * 组织成员管理（2026-11-10 新建，Function.name = fmodeagent-users）。
   *
   * 🔴 源码见 `cloud/functions/fmodeagent-users.js`；**部署后**把真实 objectId 填到这里。
   *    未部署时该调用会 404，页面显示错误态而不是空白。
   */
  orgUsers: 'mgR4EA2n5a',
} as const;

/** 兼容「已是对象」与「是 JSON 字符串」两种形态 */
function parseJsonLoose<T = Record<string, unknown>>(v: unknown): T | undefined {
  if (v == null) return undefined;
  if (typeof v === 'object') return v as T;
  if (typeof v !== 'string' || !v.trim()) return undefined;
  try {
    return JSON.parse(v) as T;
  } catch {
    return undefined;
  }
}

export class ParseApi extends FmodeApi {
  /**
   * 会话令牌读取器 + 请求范围判定器。
   *
   * - **令牌**由 `SessionService` 唯一持有，**每次调用实时读取**（避免登录/退登后持过期副本）
   * - **scope** 由 `acl.scopeFor(me)` 判定（超管 all / 公司管理员 company / 普通用户 mine）；
   *   🔴 **不得硬编码 `'all'`** —— 那会让每个用户都看到全平台别人的容器（越权）
   */
  constructor(
    private readonly readToken: () => string = () => '',
    private readonly readScope: () => Scope = () => 'mine',
  ) {
    super();
  }

  /** 当前会话令牌（读取器为空时回落到内部缓存，供单测注入） */
  private get sessionToken(): string {
    return this.readToken() || this.fallbackToken;
  }

  /** 仅单测/无 DI 场景使用的回落令牌 */
  private fallbackToken = '';

  setToken(token: string): void {
    this.fallbackToken = token;
  }

  // ---------- 鉴权 ----------

  async sendMobileCode(mobile: string): Promise<void> {
    // R4：POST /api/apig/message {mobile, company}；🔴 code === 1 才算成功
    const res = await this.rawFetch(`${PARSE_BASE.replace('/parse', '')}/api/apig/message`, {
      method: 'POST',
      body: JSON.stringify({ mobile, company: LOGIN_COMPANY }),
    });
    const d = (await res.json()) as { code?: number; msg?: string; mess?: string };
    if (d.code !== 1) throw new Error(friendlySendCodeError(pickMessage(d), res.status));
  }

  async loginWithMobile(mobile: string, code: string): Promise<AuthSession> {
    // R5：GET /api/fmode/mobile?mobile&code&company；🔴 code === 200 && data.token
    const url = `${PARSE_BASE.replace('/parse', '')}/api/fmode/mobile?mobile=${encodeURIComponent(
      mobile,
    )}&code=${encodeURIComponent(code)}&company=${LOGIN_COMPANY}`;
    const res = await this.rawFetch(url, { method: 'GET' });
    const d = (await res.json()) as {
      code?: number;
      data?: { token?: string };
      msg?: string;
      mess?: string;
    };
    const token = d.data?.token;
    if (d.code !== 200 || !token) throw new Error(pickMessage(d) ?? '登录失败');
    this.setToken(token);
    const me = await this.fetchMe(token);
    return { token, me };
  }

  async loginWithToken(token: string): Promise<AuthSession> {
    const me = await this.fetchMe(token);
    this.setToken(token);
    return { token, me };
  }

  async fetchMe(token: string): Promise<Me> {
    // R1：**GET** /parse/users/me（头 X-Parse-Session-Token）
    // 🔴 实测教训：POST 会 404（返回 HTML 错误页）；契约文档曾误写为 POST。
    const res = await this.rawFetch(`${PARSE_BASE}/users/me`, {
      method: 'GET',
      headers: { 'X-Parse-Session-Token': token },
    });
    if (!res.ok) throw new Error(`Token 校验失败（HTTP ${res.status}）`);
    const u = (await res.json()) as Record<string, unknown>;
    const objectId = String(u['objectId'] ?? '');
    // R2：_User JSON **不透出 relation**，roles 必须单独查（存量 v0.3.3 著名坑：
    //     超管因缺 roles 被误判为 company-member → 列表空）
    const roles = objectId
      ? await this.fetchRoles(token, objectId).catch(() => [] as string[])
      : [];
    const companyId = (u['company'] as { objectId?: string } | undefined)?.objectId;
    // 所属组织名：实测 Company 表有 name（如 E4KpGvTEto → 飞码AI）。
    // 取不到时为 undefined → UI 显示占位，**不编造**。
    const companyName = companyId
      ? await this.fetchCompanyName(token, companyId).catch(() => undefined)
      : undefined;
    return {
      id: objectId,
      name: String(u['nickname'] ?? u['username'] ?? ''),
      mobile: u['mobile'] ? String(u['mobile']) : undefined,
      avatar: u['avatar'] ? String(u['avatar']) : undefined,
      companyId,
      companyName,
      roles,
    };
  }

  private async fetchRoles(token: string, userId: string): Promise<string[]> {
    // R2：GET /parse/roles?where={users:Pointer<_User>}&limit=50
    const where = JSON.stringify({
      users: { __type: 'Pointer', className: '_User', objectId: userId },
    });
    const res = await this.rawFetch(
      `${PARSE_BASE}/roles?where=${encodeURIComponent(where)}&limit=50`,
      { headers: { 'X-Parse-Session-Token': token } },
    );
    if (!res.ok) return [];
    const d = (await res.json()) as { results?: { name?: string }[] };
    return (d.results ?? []).map((r) => String(r.name ?? '')).filter(Boolean);
  }

  /** 取组织名（`Company.name`）；失败返回 undefined（不回退假值） */
  private async fetchCompanyName(token: string, companyId: string): Promise<string | undefined> {
    const res = await this.rawFetch(
      `${PARSE_BASE}/classes/Company/${encodeURIComponent(companyId)}?keys=name`,
      { headers: { 'X-Parse-Session-Token': token } },
    );
    if (!res.ok) return undefined;
    const d = (await res.json()) as { name?: string };
    return d.name ? String(d.name) : undefined;
  }

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

  async fetchAgents(): Promise<Agent[]> {
    const d = await this.callFunction<{ code: number; agents?: unknown[] }>(FN.agentStatus, {
      op: 'query',
      // 🔴 按角色判定（acl.scopeFor）—— 超管 all / 公司管理员 company / 普通用户 mine。
      //    曾硬编码 'all' → 每个用户都拿到全平台 51 个容器（越权）。
      scope: this.readScope(),
    });
    if (d.code !== 200 || !Array.isArray(d.agents)) {
      throw new Error(pickMessage(d) ?? '实况数据查询失败');
    }
    return d.agents.map((raw) => mapAgent(raw as Record<string, unknown>));
  }

  /**
   * 重命名容器（2026-11-04）。
   *
   * ## 当前状态：**后端接口未实现**
   *
   * 走**独立云函数** `fmodecontainer-rename`（2026-11-05 上线）。
   * 服务端独立校验权限：公司管理员只能改本公司容器，超管可改全部。
   *
   * 🔴 失败**如实抛错**，不写本地缓存 —— 否则会出现
   *    「我这改了、同事看到的还是旧名」的假象。
   */
  async renameAgent(agentId: string, displayName: string): Promise<Agent | null> {
    const d = await this.callFunction<{ code: number; agent?: unknown; msg?: string }>(
      FN.agentRename,
      { op: 'rename', agentId, displayName: displayName.trim() },
    );
    if (d.code !== 200) {
      throw new Error(pickMessage(d) ?? `重命名失败（服务端返回 ${d.code}）`);
    }
    return d.agent ? mapAgent(d.agent as Record<string, unknown>) : null;
  }

  async fetchAgentStatus(agentId: string): Promise<Agent | null> {
    const d = await this.callFunction<{ code: number; agent?: unknown }>(FN.agentStatus, {
      op: 'query',
      scope: this.readScope(),
      agentId,
    });
    // 单条查询：code 404/403 → 返回 null（页面自行显示「不存在/无权限」）
    if (d.code !== 200 || !d.agent) return null;
    return mapAgent(d.agent as Record<string, unknown>);
  }

  // ---------- Matrix ----------

  async provisionMatrix(agentId: string): Promise<MatrixProvision> {
    const d = await this.callFunction<MatrixProvision & { code: number }>(FN.provision, {
      agentId,
    });
    // 校验规则（《API-契约》§2.3）：必须 code===200 && accessToken && userMxId
    if (d.code !== 200 || !d.accessToken || !d.userMxId) {
      throw new Error(pickMessage(d) ?? 'FMODE 开通失败');
    }
    return d;
  }

  async validateMatrix(agentId: string): Promise<MatrixProvision> {
    const d = await this.callFunction<MatrixProvision & { code: number }>(FN.provision, {
      agentId,
      validate: 1,
    });
    if (d.code !== 200 || !d.accessToken || !d.userMxId) {
      throw new Error(pickMessage(d) ?? 'FMODE 凭据校验失败');
    }
    return d;
  }

  // ---------- 会话目录（云函数 oR5O67i1Cm / fmodeagent-chatthreads） ----------

  /**
   * 拉取当前用户的会话目录。
   *
   * 🔴 云函数按 sessionToken 强制归属当前用户；这里**不传任何用户参数**。
   *    返回结构在 function 内已归一（毫秒时间戳、驼峰字段）。
   */
  async fetchChatThreads(agentId: string, opts?: { includeDeleted?: boolean }): Promise<ChatThreadRecord[]> {
    const d = await this.callFunction<{ code: number; threads?: ChatThreadRecord[]; mess?: string }>(
      FN.chatThreads,
      { op: 'list', agentId, ...(opts?.includeDeleted ? { includeDeleted: 1 } : {}) },
    );
    if (d.code !== 200) throw new Error(d.mess ?? '会话目录读取失败');
    return Array.isArray(d.threads) ? d.threads : [];
  }

  async upsertChatThreads(items: ChatThreadUpsert[]): Promise<void> {
    if (items.length === 0) return;
    const d = await this.callFunction<{ code: number; mess?: string }>(FN.chatThreads, {
      op: 'upsert',
      items,
    });
    if (d.code !== 200) throw new Error(d.mess ?? '会话目录同步失败');
  }

  async patchChatThread(input: {
    threadRoot: string;
    title?: string;
    archived?: boolean;
    /** 归属工作区；`''` = 移回日常对话（2026-11-01 起上云，换设备可见） */
    workspaceId?: string;
  }): Promise<void> {
    const d = await this.callFunction<{ code: number; mess?: string }>(FN.chatThreads, {
      op: 'patch',
      ...input,
    });
    // 404 = 云端还没有这条（本地先建、还没同步过）→ 视为成功，下次 upsert 会补上
    if (d.code !== 200 && d.code !== 404) throw new Error(d.mess ?? '会话更新失败');
  }

  // ---------- 工作区（2026-11-01 上云） ----------

  /**
   * 拉取工作区列表。
   *
   * 与工作区相关的 op 都复用同一个云函数 `oR5O67i1Cm`（fmodeagent-chatthreads），
   * 不另开函数 —— 它们同属「用户自己的对话组织数据」，部署与回滚应该一起走。
   */
  async fetchWorkspaces(): Promise<WorkspaceRecord[]> {
    const d = await this.callFunction<{ code: number; workspaces?: WorkspaceRecord[]; mess?: string }>(
      FN.chatThreads,
      { op: 'wsList' },
    );
    if (d.code !== 200) throw new Error(d.mess ?? '工作区读取失败');
    return Array.isArray(d.workspaces) ? d.workspaces : [];
  }

  async upsertWorkspaces(items: WorkspaceUpsert[]): Promise<void> {
    if (items.length === 0) return;
    const d = await this.callFunction<{ code: number; mess?: string }>(FN.chatThreads, {
      op: 'wsUpsert',
      items,
    });
    if (d.code !== 200) throw new Error(d.mess ?? '工作区同步失败');
  }

  async removeWorkspace(id: string): Promise<void> {
    const d = await this.callFunction<{ code: number; mess?: string }>(FN.chatThreads, {
      op: 'wsRemove',
      id,
    });
    if (d.code !== 200) throw new Error(d.mess ?? '工作区删除失败');
  }

  async removeChatThread(input: { threadRoot: string; roomId?: string; agentId?: string }): Promise<void> {
    const d = await this.callFunction<{ code: number; mess?: string }>(FN.chatThreads, {
      op: 'remove',
      ...input,
    });
    if (d.code !== 200) throw new Error(d.mess ?? '会话删除失败');
  }

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

  async fetchDeliverables(opts?: { agentId?: string; limit?: number }): Promise<Deliverable[]> {
    const params: Record<string, unknown> = { action: 'list', limit: opts?.limit ?? 200 };
    if (opts?.agentId) params['agentId'] = opts.agentId;
    const d = await this.callFunction<{ code: number; deliverables?: unknown[] }>(
      FN.deliverables,
      params,
    );
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '成果查询失败');
    return (d.deliverables ?? [])
      .map((x) => mapDeliverable(x as Record<string, unknown>))
      /*
       * 🔴 过滤「非成果」记录（用户实测：右栏出现两条没有意义的文档）：
       *
       *   · `title` 为空/纯符号 → 没有任何信息，点了也看不懂是什么
       *   · `title` 恰为 `probe` 且无附件 → 上报器的**探针测试**，不是交付物
       *
       * 过滤放在映射层（全项目唯一入口），页面不必各自判断。
       */
      .filter((x) => {
        const t = x.title.trim();
        if (!t || !/[\p{L}\p{N}]/u.test(t)) return false;
        if (/^probe$/i.test(t) && x.artifacts.length === 0) return false;
        return true;
      });
  }

  async fetchDeliverablesByProject(limit?: number): Promise<DeliverableGroup[]> {
    const d = await this.callFunction<{ code: number; groups?: unknown[] }>(FN.deliverables, {
      action: 'byProject',
      limit: limit ?? 200,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '成果分组查询失败');
    return (d.groups ?? []).map((g) => {
      const raw = g as Record<string, unknown>;
      const items = Array.isArray(raw['items'])
        ? raw['items']
            .map((x) => mapDeliverable(x as Record<string, unknown>))
            // 与 fetchDeliverables 同一过滤口径（见上）
            .filter((x) => {
              const t = x.title.trim();
              if (!t || !/[\p{L}\p{N}]/u.test(t)) return false;
              if (/^probe$/i.test(t) && x.artifacts.length === 0) return false;
              return true;
            })
        : [];
      return {
        project: raw['project'] ? String(raw['project']) : undefined,
        projectName: String(raw['projectName'] ?? '未归类'),
        count: Number(raw['count']) || items.length,
        items,
      };
    });
  }

  // ---------- 任务看板（FR-07b：云函数接收端未实现） ----------

  async fetchTasks(_agentId: string): Promise<Task[]> {
    // 🔴 不得静默返回空数组（那会把「未接入」伪装成「没有数据」）
    throw new Error('任务看板数据源未就绪：云函数接收端尚未实现（SPEC FR-07b 依赖声明）');
  }

  async fetchTaskDetail(_taskId: string): Promise<Task | null> {
    throw new Error('任务看板数据源未就绪：云函数接收端尚未实现（SPEC FR-07b 依赖声明）');
  }

  // ---------- 上传（OBS / 华为云，统一走 S3 预签名） ----------

  async requestUploadUrl(
    filename: string,
    mimeType: string,
    size: number,
  ): Promise<UploadTicket> {
    const d = await this.callFunction<{
      code: number;
      uploadUrl?: string;
      key?: string;
      publicUrl?: string;
      headers?: Record<string, string>;
    }>(FN.uploadUrl, { filename, mimeType, size });
    // 《API-契约》§2.5：缺 uploadUrl 即抛错，不得静默降级为本地 blob
    if (d.code !== 200 || !d.uploadUrl || !d.key) {
      throw new Error(pickMessage(d) ?? '上传签名获取失败');
    }
    return {
      uploadUrl: d.uploadUrl,
      key: d.key,
      publicUrl: d.publicUrl ?? `https://s3.fmode.cn/${d.key}`,
      headers: d.headers,
    };
  }

  async uploadFile(
    file: File,
    onProgress?: (pct: number) => void,
  ): Promise<{ key: string; publicUrl: string }> {    const ticket = await this.requestUploadUrl(
      file.name,
      file.type || 'application/octet-stream',
      file.size,
    );
    // S3 直传（华为云 OBS 兼容 S3 协议）；前端不经手任何 AK/SK
    const headers: Record<string, string> = {
      'Content-Type': file.type || 'application/octet-stream',
      'x-obs-acl': 'public-read',
      ...ticket.headers,
    };
    await this.putWithProgress(ticket.uploadUrl, headers, file, onProgress);
    return { key: ticket.key, publicUrl: ticket.publicUrl };
  }

  // ---------- 成果文件搬运队列 ----------

  async enqueueArtifactJob(job: {
    deliverableId: string;
    agentId: string;
    source: string;
    filename: string;
    index: number;
  }): Promise<{ id: string }> {
    // 只报「传哪个」；地址与头由云函数签好写进队列（客户端不接触密钥）
    const d = await this.callFunction<{ code: number; id?: string }>(FN.deliverables, {
      action: 'enqueueArtifact',
      ...job,
    });
    if (d.code !== 200 || !d.id) {
      throw new Error(pickMessage(d) ?? '搬运任务创建失败');
    }
    return { id: d.id };
  }

  async fetchArtifactJobs(agentId: string): Promise<ArtifactJob[]> {
    const d = await this.callFunction<{ code: number; jobs?: unknown[] }>(FN.deliverables, {
      action: 'pendingArtifacts',
      agentId,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '搬运任务查询失败');
    return (d.jobs ?? []).map((x) => x as ArtifactJob);
  }

  // ---------- 文件台账（fmode-file-hub，2026-11-10） ----------

  async registerFile(entry: FileEntry): Promise<{ id: string; duplicated?: boolean }> {
    const d = await this.callFunction<{ code: number; id?: string; duplicated?: boolean }>(
      FN.fileHub,
      { action: 'registerFile', ...entry },
    );
    if (d.code !== 200 || !d.id) {
      throw new Error(pickMessage(d) ?? '文件登记失败');
    }
    return { id: d.id, duplicated: d.duplicated };
  }

  /**
   * 读云盘文本文件正文（2026-11-11）。
   *
   * 走云函数 `fmode-file-read` 代取 —— 云盘没配 CORS，浏览器直连必失败。
   *
   * @throws 未部署 / 非文本 / 过大 / 网络失败时抛错，调用方自行降级（新窗口打开）
   */
  async readText(url: string): Promise<string> {
    if (!FN.fileRead) throw new Error('文件读取服务未部署');
    const d = await this.callFunction<{ code: number; text?: string; msg?: string }>(FN.fileRead, {
      action: 'readText',
      url,
    });
    if (d.code !== 200 || typeof d.text !== 'string') {
      throw new Error(d.msg ?? '读取失败');
    }
    return d.text;
  }

  /**
   * 按**群**拉文件台账（2026-11-11，v0.2.0）。
   *
   * 服务端同时匹配 `groupId` 与 `threadRoot` —— 后者保证**没有 groupId 的
   * 存量群内上传记录**也能查到（无需数据迁移）。
   */
  async fetchFilesByGroup(groupId: string, limit = 200): Promise<SessionFile[]> {
    if (!groupId) return [];
    const d = await this.callFunction<{ code: number; files?: unknown[] }>(FN.fileHub, {
      action: 'listByGroup',
      groupId,
      limit,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '群文件加载失败');
    return (d.files ?? []).map((x) => x as SessionFile);
  }

  /**
   * 把容器产出**补归并**到群（2026-11-11，v0.2.0）。
   *
   * 服务端会把 `threadRoot` 一并改写为群 id —— 这是「不串台」的关键：
   * 搬进群之后单聊就查不到了，一条文件只出现在一个页签。
   *
   * 只接受「本人 + 容器产出 + 当前未归群」的记录，其余静默跳过。
   */
  async claimFilesToGroup(groupId: string, ids: string[]): Promise<{ claimed: number }> {
    if (!groupId || ids.length === 0) return { claimed: 0 };
    const d = await this.callFunction<{ code: number; claimed?: number; msg?: string }>(FN.fileHub, {
      action: 'claimToGroup',
      groupId,
      ids: ids.slice(0, 100),
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '归并失败');
    return { claimed: d.claimed ?? 0 };
  }

  async fetchFilesBySession(threadRoot: string, limit = 100): Promise<SessionFile[]> {
    const d = await this.callFunction<{ code: number; files?: unknown[] }>(FN.fileHub, {
      action: 'listBySession',
      threadRoot,
      limit,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '会话文件加载失败');
    return (d.files ?? []).map((x) => x as SessionFile);
  }

  // ---------- 工作组 ----------

  async createWorkGroup(input: {
    name: string;
    goal?: string;
    memberAgentIds: string[];
  }): Promise<{ id: string; roomId: string }> {
    const d = await this.callFunction<{ code: number; id?: string; roomId?: string }>(FN.workgroup, {
      action: 'create',
      name: input.name,
      goal: input.goal ?? '',
      memberAgentIds: input.memberAgentIds,
    });
    if (d.code !== 200 || !d.id || !d.roomId) {
      throw new Error(pickMessage(d) ?? '创建工作组失败');
    }
    return { id: d.id, roomId: d.roomId };
  }

  async listWorkGroups(): Promise<WorkGroup[]> {
    const d = await this.callFunction<{ code: number; groups?: unknown[] }>(FN.workgroup, {
      action: 'list',
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '工作组查询失败');
    return (d.groups ?? []) as WorkGroup[];
  }

  async inviteToWorkGroup(groupId: string, agentIds: string[]): Promise<void> {
    const d = await this.callFunction<{ code: number }>(FN.workgroup, {
      action: 'invite',
      groupId,
      agentIds,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '邀请失败');
  }

  async removeFromWorkGroup(groupId: string, agentId: string): Promise<void> {
    const d = await this.callFunction<{ code: number }>(FN.workgroup, {
      action: 'remove',
      groupId,
      agentId,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '移出失败');
  }

  async archiveWorkGroup(groupId: string): Promise<void> {
    const d = await this.callFunction<{ code: number }>(FN.workgroup, {
      action: 'archive',
      groupId,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '归档失败');
  }

  // ---------- 组织成员管理（2026-11-10） ----------
  /*
   * 🔴 这组接口**不做任何前端权限判断**：谁能调用由服务端决定，
   *    前端只负责把 403 如实显示出来。这样即使前端被改，也越不了权。
   */

  async listOrgUsers(query: {
    keyword?: string;
    page?: number;
    pageSize?: number;
  }): Promise<OrgUserPage> {
    const d = await this.callFunction<{ code: number; items?: OrgUser[]; total?: number; page?: number; pageSize?: number }>(
      FN.orgUsers,
      { op: 'list', ...query },
    );
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '成员列表加载失败');
    return {
      items: d.items ?? [],
      total: d.total ?? 0,
      page: d.page ?? query.page ?? 1,
      pageSize: d.pageSize ?? query.pageSize ?? 20,
    };
  }

  async addOrgUser(userId: string): Promise<OrgUser> {
    const d = await this.callFunction<{ code: number; item?: OrgUser }>(FN.orgUsers, {
      op: 'add',
      userId,
    });
    if (d.code !== 200 || !d.item) throw new Error(pickMessage(d) ?? '添加成员失败');
    return d.item;
  }

  async updateOrgUser(
    userId: string,
    patch: { nickname?: string; mobile?: string; password?: string },
  ): Promise<OrgUser> {
    const d = await this.callFunction<{ code: number; item?: OrgUser }>(FN.orgUsers, {
      op: 'update',
      userId,
      ...patch,
    });
    if (d.code !== 200 || !d.item) throw new Error(pickMessage(d) ?? '保存失败');
    return d.item;
  }

  async removeOrgUser(userId: string): Promise<void> {
    const d = await this.callFunction<{ code: number }>(FN.orgUsers, { op: 'remove', userId });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '删除失败');
  }

  async fetchOrgMembership(): Promise<OrgMembership> {
    const d = await this.callFunction<Partial<OrgMembership> & { code: number }>(
      FN.orgUsers,
      { op: 'me' },
    );
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '查询组织归属失败');
    return {
      userId: d.userId ?? '',
      hasOrg: !!d.hasOrg,
      companyId: d.companyId ?? '',
      companyName: d.companyName ?? '',
    };
  }

  async ackArtifactJob(input: {
    id: string;
    ok: boolean;
    publicUrl?: string;
    error?: string;
  }): Promise<void> {
    const d = await this.callFunction<{ code: number }>(FN.deliverables, {
      action: 'ackArtifact',
      objectId: input.id,
      ok: input.ok,
      publicUrl: input.publicUrl,
      error: input.error,
    });
    if (d.code !== 200) throw new Error(pickMessage(d) ?? '搬运任务回执失败');
  }



  /** PUT 直传；浏览器 XMLHttpRequest 才能拿到上传进度 */
  private putWithProgress(
    url: string,
    headers: Record<string, string>,
    file: File,
    onProgress?: (pct: number) => void,
  ): Promise<void> {
    return new Promise((resolve, reject) => {
      const xhr = new XMLHttpRequest();
      xhr.open('PUT', url, true);
      for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
      xhr.upload.onprogress = (e) => {
        if (e.lengthComputable && onProgress) onProgress(Math.round((e.loaded / e.total) * 100));
      };
      xhr.onload = () => {
        if (xhr.status >= 200 && xhr.status < 300) resolve();
        else reject(new Error(`上传失败（HTTP ${xhr.status}）`));
      };
      xhr.onerror = () => reject(new Error('上传失败：网络错误'));
      xhr.send(file);
    });
  }

  // ---------- 内部 ----------

  /**
   * 云函数统一调用（《API-契约》§1.1）。
   *
   * ## 🔴 平台抖动时的表现（2026-10-29 实测）
   *
   * 平台服务端会出现间歇性故障。实测连续 5 次请求：
   * `超时 / 超时 / 503 / 200 / 200`。
   *
   * 浏览器此时报的是 **CORS 错误**（`No 'Access-Control-Allow-Origin'`），
   * 那只是表象 —— 真正原因是服务端 503 或直接断开，
   * **连响应头都没返回**，浏览器于是判定为跨域失败。
   *
   * 所以:
   *   · 网络层失败（fetch 直接抛）→ 明确告知「连不上平台」,不是用户的操作问题
   *   · 503 / 502 / 504 → 告知「平台暂时不可用」并带上可重试的意思
   *   · 其它非 2xx → 保留原状态码
   */
  private async callFunction<T>(id: string, params: Record<string, unknown>): Promise<T> {
    /*
     * 平台抖动是**已知会发生**的（实测 5 次里 2 次超时、1 次 503）。
     * 瞬时可恢复的错误自动重试一次 —— 用户不该因为一次抖动就看到报错。
     * 只重试「网络失败 / 502 / 503 / 504」，业务错误（4xx）不重试。
     */
    const attempt = async (): Promise<Response> =>
      this.rawFetch(FUNCTION_API, {
        method: 'POST',
        headers: this.authHeaders(),
        body: JSON.stringify({ id, token: this.sessionToken, params }),
      });

    let res: Response | null = null;
    let lastErr: unknown = null;
    for (let i = 0; i < 2; i++) {
      try {
        res = await attempt();
        // 可恢复的服务端错误 → 短暂等待后重试一次
        if ((res.status === 502 || res.status === 503 || res.status === 504) && i === 0) {
          await new Promise((r) => setTimeout(r, 800));
          continue;
        }
        break;
      } catch (e) {
        lastErr = e;
        if (i === 0) {
          await new Promise((r) => setTimeout(r, 800));
          continue;
        }
        throw new Error('连不上平台服务（网络或服务端不可用），请稍后重试');
      }
    }
    if (!res) {
      void lastErr;
      throw new Error('连不上平台服务（网络或服务端不可用），请稍后重试');
    }
    if (!res.ok) {
      if (res.status === 503 || res.status === 502 || res.status === 504) {
        throw new Error(`平台暂时不可用（HTTP ${res.status}），请稍后重试`);
      }
      /*
       * 🔴 403 要翻译成人话（2026-11-12 用户实测）。
       *
       * 同公司同事打开某个容器时，provision 云函数会返回 403。
       * 原本只抛「云函数调用失败（HTTP 403）」，用户不知道是网络、账号还是权限问题。
       *
       * ⚠️ 注意：产品目标是「同公司成员可共用全部容器」（见
       *    `docs/03-interface/需求-同公司共用容器-20261112.md`），
       *    当前 403 属于服务端尚未放开的限制，不是正常状态。
       *    所以文案用「暂时不可用」而不是「你没有权限」——
       *    避免让用户以为这是永久性的个人权限问题。
       */
      if (res.status === 403) {
        throw new Error(
          '这个容器暂时无法使用（平台侧授权未开放）。同公司成员共用容器需平台侧开通，请联系管理员。',
        );
      }
      if (res.status === 401) {
        throw new Error('登录已失效，请重新登录。');
      }
      throw new Error(`云函数调用失败（HTTP ${res.status}）`);
    }
    return (await res.json()) as T;
  }

  /**
   * 云函数调用用的请求头。
   *
   * 🔴 **不要带 `X-Parse-Application-Id`**（2026-11-11 线上实测）。
   *
   * 线上 `https://ai.fmode.cn` 调用 `server.fmode.cn/api/functions` 时，
   * 浏览器预检直接被拒：
   *
   *   Request header field x-parse-application-id is not allowed
   *   by Access-Control-Allow-Headers in preflight response.
   *
   * 根因在**服务端网关**：预检响应取决于 `Access-Control-Request-Headers`
   * 里各字段的**大小写**——
   *   · 全小写 → `Access-Control-Allow-Headers: *`（放行）
   *   · 首字母大写（浏览器实际发的 `Content-Type, X-Parse-Application-Id`）
   *     → 回固定白名单，**里面没有 x-parse-application-id** → 被拒
   *
   * 而这个头对云函数**完全无用**：鉴权靠 URL 里的函数 `id` + body 里的
   * `token`（/`X-Parse-Session-Token`）。实测去掉后调用正常返回。
   *
   * 开发态之所以没暴露：`environment.ts` 的 `functionsBase` 是相对路径
   * `/api/functions`，同源、不走预检。
   */
  /**
   * 云函数调用用的请求头 —— **一个 `X-Parse-*` 都不带**。
   *
   * ## 为什么（2026-11-11 线上实测，两轮踩坑）
   *
   * 线上 `https://ai.fmode.cn` 跨域调 `server.fmode.cn/api/functions`，
   * 浏览器先发 OPTIONS 预检。**服务端的预检响应不稳定**：
   *
   * ```
   * 连续 10 次 OPTIONS 统计：
   *   Access-Control-Allow-Headers: *                        → 4 次（放行）
   *   Access-Control-Allow-Headers: Authorization,DNT,...,Content-Type,Range → 6 次（拒）
   * ```
   *
   * 后端的固定白名单里**没有任何 `x-parse-*`**。网关有多个实例、配置不一致，
   * 所以表现为「时好时坏」：4/10 成功 → 用户看到部分请求报 CORS，
   * 但因为请求彼此独立，主流程往往还能走通。
   *
   * 第一轮只去掉了 `X-Parse-Application-Id`，问题立刻在
   * `X-Parse-Session-Token` 上重现 —— 逐个删是治标的。现在**全部不带**。
   *
   * ## 不带头怎么鉴权
   *
   * 云函数从 body 的 `params.token` 取（`fmode-file-hub.js` 的 `_sessionToken()`
   * 里 `params.token` 是明确回退路径）。实测只带 body、不带任何头，
   * 云函数正常返回数据。
   *
   * ⚠️ 只对**云函数入口**这样处理；Parse REST / 登录等接口照旧带头，
   *    不走这条路径。
   */
  private authHeaders(): Record<string, string> {
    return { 'Content-Type': 'application/json' };
  }

  private rawFetch(url: string, init: RequestInit): Promise<Response> {
    /*
     * 🔴 **默认不带任何 `X-Parse-*` 头**，只有 Parse REST 白名单才带。
     *
     * ## 为什么（两次线上的 CORS 事故）
     *
     * 服务端网关有多个实例、预检响应不一致：
     *   Access-Control-Allow-Headers: *                → 放行（4/10 次）
     *   Authorization,DNT,...,Content-Type,Range       → 拒绝（6/10 次）
     * 固定白名单里**没有任何 `x-parse-*`**，命中那一台就把整条请求拦掉。
     *
     * ## 踩过的坑（两次，都是上线后才炸）
     *
     * ① 第一版只剥离「云函数入口」→ `/api/apig/message` 被拦
     * ② 第二版改成「`/api/` 路径」→ 新接口只要不在这条规则里，照样会被拦
     *
     * **教训：枚举「哪些不带」永远会漏，必须反过来枚举「哪些带」。**
     *
     * ## 现在的规则（白名单式，默认安全）
     *
     * | 目标 | 带 X-Parse-* |
     * |---|---|
     * | Parse REST（`/parse/users/me`、`/parse/roles` 等） | ✅ 带（Parse Server 硬性要求） |
     * | **其它一切**（`/api/functions`、`/api/fmode/*`、`/api/apig/*`、未来新增） | ❌ 不带 |
     *
     * 这样**新增任何接口都默认不会被 CORS 拦**，除非它确实属于 Parse REST。
     * `/api/*` 下的端点鉴权都在 body / query 里（`token` 字段），不依赖这些头。
     */
    const needsParseHeaders = /\/parse(\/|$)/.test(url);
    const incoming = (init.headers as Record<string, string>) ?? {};
    const headers: Record<string, string> = needsParseHeaders
      ? { 'X-Parse-Application-Id': PARSE_APP_ID }
      : {};
    for (const [k, v] of Object.entries(incoming)) {
      /*
       * 非 Parse REST：调用方误传的 `X-Parse-*` 也一律丢掉 ——
       * 宁可鉴权失败（有明确报错），也不要被 CORS 静默拦成 ERR_FAILED。
       */
      if (!needsParseHeaders && k.toLowerCase().startsWith('x-parse-')) continue;
      headers[k] = v;
    }
    /*
     * 🔴 有 body 的方法必须带 `Content-Type: application/json`。
     *
     * 实测教训：`POST /api/apig/message` 若**不带该头**，服务端**读不到 body**，
     * 于是报「缺少参数company」—— 而 body 里其实带了 company。
     * 这个误导性报错曾让我误判为「限流」，排查花了很久。
     *
     * 故此处对带 body 的请求**自动补默认 Content-Type**（调用方显式指定则尊重其值）。
     */
    if (init.body != null && !headers['Content-Type']) {
      headers['Content-Type'] = 'application/json';
    }
    return fetch(url, { ...init, headers });
  }
}

/** 登录公司常量（《API-契约》§1.2） */
const LOGIN_COMPANY = 'E4KpGvTEto';

/** 错误文案取值顺序：msg → mess → message */
function pickMessage(d: unknown): string | undefined {
  if (!d || typeof d !== 'object') return undefined;
  const o = d as Record<string, unknown>;
  for (const k of ['msg', 'mess', 'message']) {
    const v = o[k];
    if (typeof v === 'string' && v.trim()) return v;
  }
  return undefined;
}

/**
 * 发码错误 → 友好文案。
 *
 * ## 🔴 为什么要做这一层（实测教训）
 *
 * 服务端在**限流**状态下会返回**误导性文案**，实测对照：
 *
 * | 请求 | 服务端返回 |
 * |---|---|
 * | 带 company（首次） | `200 {"code":1,"data":{"msg":"发送成功"}}` |
 * | 带 company（频繁） | `500 {"mess":"该号码发送验证码过于频繁"}` |
 * | **不带** company | `500 {"mess":"缺少参数company"}` |
 *
 * 即：我们的请求**带了** company 且首次能成功，但**短时间重复请求**时
 * 服务端可能错报成「缺少参数company」，误导用户以为参数配错了。
 *
 * 故此处把「缺参数」在**限流上下文**（HTTP 500 而非 400）下转成更可能的真相提示，
 * 并在文案中保留原始信息以便排查（不吞掉事实）。
 */
function friendlySendCodeError(raw: string | undefined, status: number): string {
  const m = raw ?? '';
  if (/频繁|过于频繁|too many|rate/i.test(m)) {
    return '发送过于频繁，请稍后再试（同一号码通常 60 秒内只能发一次）';
  }
  // 实测：限流态下服务端会误报「缺少参数company」；保留原始信息供排查
  if (/缺少参数\s*company/i.test(m)) {
    return '验证码发送失败：服务端返回「缺少参数company」。若已多次点击，通常是发送过于频繁，请稍后再试。（原始：' +
      m +
      '）';
  }
  if (m) return m;
  return `验证码发送失败（HTTP ${status}）`;
}

/**
 * `channels` 归一：兼容**数组形态**的非标准容器上报。
 *
 * 🔴 实测（`agent-node-lj-test`）：容器发的是 `["wecom"]`，而平台契约是**对象**
 *    `{"matrix":true,"matrixConfig":{...},"wecom":true,...}`。
 *    不归一 → `channels.matrix` 为 `undefined` → `matrixReady=false` → UI 显示「未接入」，
 *    但该容器 Matrix 通道其实**是通的**（实测双向消息可达）。
 *
 * 数组语义：元素即**已点亮的通道名**，故 `["matrix","wecom"]` → 两者为 true。
 * 空数组视为「未上报通道」而非「零通道」（返回 undefined，避免 UI 显示"未接入"误导）。
 */
function normalizeChannels(v: unknown): ChannelConfig | undefined {
  const parsed = parseJsonLoose<unknown>(v);
  if (parsed == null) return undefined;

  if (Array.isArray(parsed)) {
    const names = parsed.filter((x): x is string => typeof x === 'string');
    if (names.length === 0) return undefined;
    return {
      matrix: names.includes('matrix'),
      wecom: names.includes('wecom'),
    };
  }

  // 对象形态：契约标准，原样透传（含 matrixConfig 细节）
  return parsed as ChannelConfig;
}

/**
 * `host` 归一：兼容 `cpuLoad1`（裸负载）→ `cpuPercent`（百分比）。
 *
 * 🔴 实测：容器发 `{"cpuLoad1":5.65,"cpuLoad5":5.66,"memPercent":51,...}`，
 *    缺 `cpuPercent` 键 → CPU 不显示（memPercent/diskPercent 因键名对上才正常）。
 *
 * 换算口径 `cpuLoad1 / 核数 * 100`（实测 56 核实测 9.2 → 16.4 与容器自证一致）。
 * ⚠️ 核数未知时**不猜**：宁可返回 undefined 让 UI 显示「未上报」，也不编一个假数字。
 *    核数来源优先级：`cpuCores`（容器自报）→ 无。
 */
function normalizeHost(v: unknown): Agent['host'] {
  const h = parseJsonLoose<Record<string, unknown>>(v);
  if (!h) return undefined;

  const num = (x: unknown): number | undefined =>
    typeof x === 'number' && Number.isFinite(x) ? x : undefined;

  // 契约标准的 cpuPercent 优先，不被派生值覆盖
  let cpuPercent = num(h['cpuPercent']);
  if (cpuPercent == null) {
    const load = num(h['cpuLoad1']);
    const cores = num(h['cpuCores']);
    if (load != null && cores != null && cores > 0) {
      cpuPercent = Math.min(100, Math.max(0, (load / cores) * 100));
    }
  }

  const memPercent = num(h['memPercent']);
  const diskPercent = num(h['diskPercent']);

  // 三项指标全无 → 视为未上报（避免 UI 显示 0% 误导为"机器空闲"）
  if (cpuPercent == null && memPercent == null && diskPercent == null) return undefined;

  return { cpuPercent, memPercent, diskPercent };
}

/**
 * `heartbeatAt` 归一（三级回落）。
 *
 * 🔴 实测：容器不发 `heartbeatAt`，心跳时间藏在 `host.probedAt`
 *    （采集时刻）；两者皆无时回落 `updatedAtClient.iso`（云函数写入时刻）。
 *    不回落的后果：UI 判「心跳超时」→ 在线容器被显示成离线。
 */
function normalizeHeartbeat(raw: Record<string, unknown>, host: unknown): string | undefined {
  /*
   * 🔴 必须经 `tsOf` 归一，不能 `String()`。
   *    云函数里 heartbeatAt 是 Parse Date → `{__type:'Date', iso:'…'}`，
   *    `String()` 得到 `"[object Object]"` → 下游 `Date.parse()` 得 NaN →
   *    「心跳超时」判定永远为假（实测：状态永远显示「空闲」，从不报「状态未同步」）。
   */
  const isoOf = (v: unknown): string | undefined => {
    const t = tsOf(v);
    return Number.isFinite(t) ? new Date(t).toISOString() : undefined;
  };
  const direct = isoOf(raw['heartbeatAt']);
  if (direct) return direct;
  const h = parseJsonLoose<{ probedAt?: string }>(host);
  if (h?.probedAt) return isoOf(h.probedAt);
  const uac = raw['updatedAtClient'] as { iso?: string } | undefined;
  if (uac?.iso) return isoOf(uac.iso);
  return undefined;
}

/** 云函数原始记录 → `Agent` 领域模型（映射只在此处发生） */
function mapAgent(raw: Record<string, unknown>): Agent {
  const channels = normalizeChannels(raw['channels']);
  const balance = parseJsonLoose<{
    remainCny?: number;
    remainRmb?: number;
    cny?: number;
    usedCny?: number;
    pageUrl?: string;
    source?: string;
  }>(raw['balance']);
  const host = normalizeHost(raw['host']);
  const heartbeatAt = normalizeHeartbeat(raw, raw['host']);
  const user = raw['user'] as Record<string, unknown> | undefined;

  return {
    id: String(raw['agentId'] ?? raw['objectId'] ?? ''),
    name: String(raw['botName'] ?? raw['name'] ?? ''),
    avatar: raw['botAvatar'] ? String(raw['botAvatar']) : undefined,
    gender: (raw['gender'] as Agent['gender']) ?? 'unknown',
    status: (raw['status'] as AgentStatus) ?? 'offline',
    currentTask: raw['currentTask'] ? String(raw['currentTask']) : undefined,
    currentAction: raw['currentAction'] ? String(raw['currentAction']) : undefined,
    progress: typeof raw['progress'] === 'number' ? (raw['progress'] as number) : undefined,
    heartbeatAt,
    /*
     * 心跳距今秒数（2026-11-07）：云函数直接给出，比从 heartbeatAt 推算更可靠 ——
     * 实测该字段有值而 heartbeatAt 为 undefined。供状态展示判定「其实已离线」。
     */
    heartbeatAgeSec:
      typeof raw['heartbeatAgeSec'] === 'number' ? (raw['heartbeatAgeSec'] as number) : undefined,
    updatedAt: raw['updatedAt'] ? String(raw['updatedAt']) : undefined,
    /*
     * 会话级状态（2026-11-09，方案 A）。
     *
     * 容器上报的 `status` 是**整个容器一个值**，同一容器的多个会话共用，
     * 导致「会话 A 在跑」时会话 B 也显示正在执行（用户实测）。
     * 容器把每个会话的状态写进 `extra.currentSessions`（`extra` 已在平台白名单里）。
     *
     * 形状不对一律忽略 —— 宁可回落到全局 status，也不能因解析失败显示「未知」。
     */
    currentSessions: (() => {
      const ex = parseJsonLoose<Record<string, unknown>>(raw['extra']);
      const list = ex?.['currentSessions'];
      if (!Array.isArray(list)) return undefined;
      const out = list.flatMap((it) => {
        if (!it || typeof it !== 'object') return [];
        const s = it as Record<string, unknown>;
        const key = typeof s['sessionKey'] === 'string' ? s['sessionKey'] : '';
        if (!key) return [];
        const st = s['status'] === 'running' ? 'running' : 'idle';
        /*
         * `userId`（2026-11-11）：容器共享给多人时区分「谁的会话」。
         * 形状不对就省略 —— 宁可退回 roomId 匹配，也不要拿脏值去比对。
         */
        const uid = typeof s['userId'] === 'string' && s['userId'].startsWith('@') ? s['userId'] : undefined;
        /* 会话级任务摘要（2026-11-11）：形状不对就省略，顶栏退回通用文案 */
        const task = typeof s['task'] === 'string' && s['task'].trim() ? s['task'].trim() : undefined;
        /* 最后更新时刻（2026-11-11）：用于判断 running 是否已过期 */
        const upd = typeof s['updatedAt'] === 'number' && Number.isFinite(s['updatedAt']) ? s['updatedAt'] : undefined;
        return [
          {
            sessionKey: key,
            ...(uid ? { userId: uid } : {}),
            ...(task ? { task } : {}),
            ...(upd ? { updatedAt: upd } : {}),
            status: st as 'running' | 'idle',
            turnStartAt:
              typeof s['turnStartAt'] === 'number' && Number.isFinite(s['turnStartAt'])
                ? s['turnStartAt']
                : undefined,
          },
        ];
      });
      return out.length ? out : undefined;
    })(),
    host,
    balance: balance
      ? {
          // 映射层归一：兼容旧键 remainRmb，以及容器复刻脚本发的 cny
          remainCny: balance.remainCny ?? balance.remainRmb ?? balance.cny,
          usedCny: typeof balance.usedCny === 'number' ? balance.usedCny : undefined,
          pageUrl: balance.pageUrl,
          /*
           * `source: 'owner_token'` = 云函数用**主人账号的令牌**实时取的余额。
           * 容器账单挂在主人账号上 → 同一主人的所有容器报同一个数，UI 要标注「账号余额」。
           */
          sharedAccount: balance.source === 'owner_token' ? true : undefined,
        }
      : undefined,
    channels: channels
      ? {
          matrix: channels.matrix,
          homeserver: channels.homeserver,
          matrixConfig: channels.matrixConfig,
          wecom: channels.wecom,
          wecomBotId: channels.wecomBotId,
        }
      : undefined,
    /**
     * 🔴 `usage` 此前**完全没有映射** —— 云函数返回了、映射层丢掉了，
     * 造成「Token 用量」永远空白（实测：库里 totalTokens=2238055，页面不显示）。
     *
     * 键名兼容：容器发 `inputTokens`/`outputTokens`，
     * 契约旧字段是 `promptTokens`/`completionTokens`，两者都收。
     */
    usage: (() => {
      const u = parseJsonLoose<Record<string, unknown>>(raw['usage']);
      if (!u) return undefined;
      const num = (x: unknown): number | undefined =>
        typeof x === 'number' && Number.isFinite(x) ? x : undefined;
      const usage = {
        totalTokens: num(u['totalTokens']),
        promptTokens: num(u['promptTokens']) ?? num(u['inputTokens']),
        completionTokens: num(u['completionTokens']) ?? num(u['outputTokens']),
        updatedAt: u['updatedAt'] ? String(u['updatedAt']) : undefined,
        raw: u,
      };
      // 三项全无 → 视为未上报（避免 UI 显示 0）
      return usage.totalTokens == null && usage.promptTokens == null && usage.completionTokens == null
        ? undefined
        : usage;
    })(),
    owner: user
      ? {
          id: String(user['objectId'] ?? ''),
          name: String(user['nickname'] ?? user['username'] ?? ''),
          avatar: user['avatar'] ? String(user['avatar']) : undefined,
          mobile: user['mobile'] ? String(user['mobile']) : undefined,
        }
      : undefined,
    // 容器标识（排障反查来源用；云函数读的是 hostname/containerRef）
    containerRef: raw['containerRef'] ? String(raw['containerRef']) : undefined,
    // Agent token 健康灯：expired 时余额等依赖 token 的字段会降级
    sessionStatus: (() => {
      const s = String(raw['sessionStatus'] ?? '').toLowerCase();
      return s === 'ok' || s === 'expired' ? (s as 'ok' | 'expired') : 'unknown';
    })(),
    // 会话级用量明细（可选，缺失不影响总量展示）
    usageSessions: (() => {
      const list = parseJsonLoose<unknown[]>(raw['usageSessions']);
      if (!Array.isArray(list) || list.length === 0) return undefined;
      return list as UsageSession[];
    })(),
    companyId: (raw['company'] as { objectId?: string } | undefined)?.objectId,
    // 「是否已接入 FMODE」= channels.matrix 为真（或已有 matrixConfig.userId）
    matrixReady: !!channels?.matrix || !!channels?.matrixConfig?.userId,
    // 未读数**不来自服务端**：云函数不返回该字段，真实计数由
    // `UnreadService` 依据 Matrix 事件流在客户端维护（见该服务注释）。
    // 此处恒为 0，UI 不得消费（消费点一律走 UnreadService.countOf）。
    unread: 0,
  };
}

/**
 * 从存储键里还原一个「像文件名」的展示名。
 *
 * 实现已移到 `core/s3-link.ts`（消息卡片也要用，而 `chat.service`
 * 不能反向依赖本文件）。这里重新导出，保持既有调用点不变。
 */
export { prettifyStorageKey };

/** 成果原始记录 → `Deliverable` 领域模型 */
function mapDeliverable(raw: Record<string, unknown>): Deliverable {
  const status = String(raw['status'] ?? '');
  /*
   * 🔴 `artifacts` 是**自由数组**，实测两种形态混用（同一张表里都有）：
   *
   * ```
   * ["/opt/data/git-repos/agent-status-reporter/REPORT.md"]   ← 字符串数组（容器最常这样写）
   * [{ name: "report.pdf", url: "https://…", type: "pdf" }]    ← 对象数组（契约标准）
   * ```
   *
   * 此前只处理对象数组，字符串形态进来后 `name` 变成空串 →
   * 右栏渲染成「仅有 · 的文档」（用户实测反馈）。
   *
   * 字符串形态的分辨口径：
   *   · 以 `http` 开头        → 视作已是可访问地址
   *   · 其它（容器内路径）    → **未同步**，由 `ArtifactSyncService` 交给容器上传到云盘
   */
  const rawArts = Array.isArray(raw['artifacts']) ? (raw['artifacts'] as unknown[]) : [];
  const artifacts: Artifact[] = rawArts
    .map((a): Artifact | null => {
      if (typeof a === 'string') {
        const s = a.trim();
        if (!s) return null;
        const isUrl = /^https?:\/\//i.test(s);
        // 与对象形态同口径：优先从存储键还原展示名，不直接拿末段当名字
        const name = prettifyStorageKey(s);
        return {
          name,
          url: isUrl ? s : '',
          type: name.split('.').pop() || '',
          // 非 URL 形态的原始值（容器内路径），保留给同步服务
          source: isUrl ? undefined : s,
        } as Artifact;
      }
      if (a && typeof a === 'object') {
        const o = a as Record<string, unknown>;
        const name = String(o['name'] ?? o['filename'] ?? '');
        const rawUrl = String(o['url'] ?? '');
        /*
         * 🔴 对象形态也要认 `source`（2026-11-07）。
         *
         * 容器的 artifact 常写成 `{ name, url: '/opt/data/x.md' }`（容器内路径），
         * 原实现把整个 `url` 原样带出 → 前端拿它去 fetch 必然失败，
         * 且**无法入队搬运**（同步服务只认 `source`）。
         * 现在与非 URL 字符串形态同口径：路径进 `source`，`url` 置空。
         */
        const isUrl = /^https?:\/\//i.test(rawUrl);
        const fallbackSource = String(o['source'] ?? '');
        const url = isUrl ? rawUrl : '';
        const source = isUrl ? undefined : rawUrl || fallbackSource || undefined;
        if (!name && !url && !source) return null;
        /*
         * 显示名与存储键**分离**（2026-11-10 用户裁决）。
         *
         * 存储键由服务端生成（形如 `0-mwa2gx2gog-weekly-report.md` 或纯随机 ID），
         * 中文文件名进不了签名 URL，所以**不能**拿 url 末段当显示名。
         * 优先用 `name` 字段；没有才回退，且回退时剥掉服务端加的前缀段。
         */
        const displayName =
          name || prettifyStorageKey(url) || prettifyStorageKey(source ?? '') || '未命名文件';
        return {
          name: displayName,
          url,
          type: String(o['type'] ?? ''),
          ...(source ? { source } : {}),
        };
      }
      return null;
    })
    .filter((x): x is Artifact => x != null);

  const first = artifacts[0];
  const filename = first?.name || undefined;
  const rawType = first?.type || filename?.split('.').pop() || '';
  const fileType = rawType ? rawType.replace(/^\./, '').toUpperCase() : undefined;
  return {
    id: String(raw['objectId'] ?? raw['id'] ?? ''),
    agentId: String(raw['agentId'] ?? ''),
    title: String(raw['title'] ?? ''),
    summary: raw['summary'] ? String(raw['summary']) : undefined,
    projectId: raw['project'] ? String(raw['project']) : undefined,
    projectName: raw['projectName'] ? String(raw['projectName']) : undefined,
    artifacts,
    tags: Array.isArray(raw['tags']) ? (raw['tags'] as string[]).map(String) : [],
    deliveredAt: String(raw['deliveredAt'] ?? ''),
    filename,
    fileType,
    // 契约未返回文件大小 → 保持空（UI 不该显示 0 B）
    size: raw['size'] ? String(raw['size']) : undefined,
    // 契约 §2.2：status 取值为推断 —— 含 fail/error 子串即失败
    state: /fail|error/i.test(status) ? 'failed' : 'delivered',
  };
}