UHD_Media_Tool/packages/contracts/src/sources.ts

import { z } from "zod";
import { CursorQuery, DateOnly, EntityBase, Id, JsonObject, NonNegInt, SERVER_MANAGED, Timestamp } from "./common.ts";

// 来源域:站点、站点账号、Feed、站点资源、观察(REQ §4)
// 含 passkey 的 Feed URL 只以 urlSecretRef 保存,对外只给脱敏的 urlDisplay。

/** api = MP 专用 API spider(Haidan/HDDolby/RousiPro/SunnyPT/TNode/TorrentLeech/Yema) */
export const SiteAdapter = z.enum(["nexusphp", "mteam_api", "api", "generic_rss"]);
export type SiteAdapter = z.infer<typeof SiteAdapter>;
export const SiteHealth = z.enum(["unknown", "healthy", "degraded", "failing", "disabled"]);
export type SiteHealth = z.infer<typeof SiteHealth>;
export const CircuitState = z.enum(["closed", "open", "half_open"]);
export type CircuitState = z.infer<typeof CircuitState>;

/** 站点级限流(快照、实时搜索、浏览器共享) */
export const SiteRateLimit = z.object({
  requestsPerMinute: z.number().int().positive().optional(),
  minIntervalMs: z.number().int().nonnegative().optional(),
  concurrency: z.number().int().positive().optional(),
});
export type SiteRateLimit = z.infer<typeof SiteRateLimit>;

/** 站点行 last_health:最近一次健康检测结果 */
export const SiteLastHealth = z.object({
  ok: z.boolean(),
  /** ok / auth_missing / auth_expired / auth_invalid / rate_limited / unreachable / site_maintenance / parse_error */
  status: z.string(),
  latencyMs: z.number().int().nonnegative().nullable(),
  message: z.string().nullable(),
});
export type SiteLastHealth = z.infer<typeof SiteLastHealth>;

export const Site = EntityBase.extend({
  key: z.string().regex(/^[a-z][a-z0-9_-]*$/),
  name: z.string().min(1),
  adapter: SiteAdapter,
  baseUrl: z.url(),
  enabled: z.boolean(),
  rateLimit: SiteRateLimit,
  config: JsonObject,
  healthStatus: SiteHealth,
  circuitState: CircuitState,
  circuitOpenUntil: Timestamp.nullable(),
  snapshotEnabled: z.boolean(),
  snapshotIntervalSec: z.number().int().positive().nullable(),
  lastSnapshotAt: Timestamp.nullable(),
  snapshotCursor: JsonObject,
  /** 最近一次健康检测(手动或定时 sites.healthCheck);从未检测为 null */
  lastHealth: SiteLastHealth.nullable(),
  lastHealthAt: Timestamp.nullable(),
  /** 使用全局代理(settings.sites.proxyUrl) */
  proxy: z.boolean(),
  /** 默认参与资源搜索(站点选择弹层的"默认"集合) */
  searchDefault: z.boolean(),
});
export type Site = z.infer<typeof Site>;
export const SiteCreate = Site.pick({
  key: true,
  name: true,
  adapter: true,
  baseUrl: true,
  enabled: true,
  rateLimit: true,
  config: true,
  snapshotEnabled: true,
  snapshotIntervalSec: true,
  proxy: true,
  searchDefault: true,
}).partial({
  enabled: true,
  rateLimit: true,
  config: true,
  snapshotEnabled: true,
  snapshotIntervalSec: true,
  proxy: true,
  searchDefault: true,
});
export type SiteCreate = z.infer<typeof SiteCreate>;
export const SiteUpdate = SiteCreate.omit({ key: true }).partial();
export type SiteUpdate = z.infer<typeof SiteUpdate>;

export const SiteAuthKind = z.enum(["cookie", "passkey", "api_key", "password"]);
export type SiteAuthKind = z.infer<typeof SiteAuthKind>;
/**
 * 账号登录状态(site-center §4.6):unknown 未验证 → active 正常;expired 失效(自动重登也失败);
 * invalid 密码错 / 封禁;challenge 需人工验证(验证码 / 二次验证 / Cloudflare)。
 */
export const SiteAccountStatus = z.enum(["unknown", "active", "invalid", "expired", "challenge"]);
export type SiteAccountStatus = z.infer<typeof SiteAccountStatus>;

/** 登录 / 校验失败的分类(NexusPHP takelogin、Cookie / API Key 校验) */
export const SiteLoginFailureReason = z.enum([
  "captcha",
  "two_factor",
  "bad_credentials",
  "account_blocked",
  "challenge",
  "auth_expired",
  "network",
  "unsupported",
  "unknown",
]);
export type SiteLoginFailureReason = z.infer<typeof SiteLoginFailureReason>;

export const SiteAccountError = z.object({
  reason: SiteLoginFailureReason,
  /** 中文一句;站点原文截 200 字 */
  message: z.string(),
  at: Timestamp,
});
export type SiteAccountError = z.infer<typeof SiteAccountError>;

/**
 * 站点用户数据(refreshSiteUserData 的 SiteUserInfo 去掉 raw / 消息正文 / 做种明细)。
 * 字节数为 number;ratio null = 站点未给且无法计算;download=0 时前端显示 ∞。
 * bonus null = 站点不提供魔力;vip null = 无法判定(不显示)。
 */
export const SiteAccountUserData = z.object({
  schema: z.string().nullable(),
  userId: z.string().nullable(),
  username: z.string().nullable(),
  userLevel: z.string().nullable(),
  vip: z.boolean().nullable(),
  joinAt: z.string().nullable(),
  upload: z.number().nonnegative(),
  download: z.number().nonnegative(),
  ratio: z.number().nullable(),
  bonus: z.number().nullable(),
  seeding: NonNegInt,
  seedingSize: z.number().nonnegative(),
  leeching: NonNegInt,
  leechingSize: z.number().nonnegative(),
  messageUnread: NonNegInt,
});
export type SiteAccountUserData = z.infer<typeof SiteAccountUserData>;

export const SiteAccount = EntityBase.extend({
  siteId: Id,
  label: z.string().min(1),
  /** 主凭证类型;passkey 另见 hasPasskey */
  authKind: SiteAuthKind,
  secretRef: Id.nullable(),
  enabled: z.boolean(),
  status: SiteAccountStatus,
  lastVerifiedAt: Timestamp.nullable(),
  /** @deprecated 只读兼容一版;登录名见 loginName,用户数据见 userData */
  userInfo: JsonObject,
  /** 账密登录名 */
  loginName: z.string().nullable(),
  /** 空 = 全局默认 UA(settings.sites.userAgent) */
  userAgent: z.string().nullable(),
  /** 最近一次登录 / 校验成功(Cookie、API Key 校验成功也算) */
  lastLoginAt: Timestamp.nullable(),
  lastError: SiteAccountError.nullable(),
  /** 最近一次成功的用户数据;从未成功为 null */
  userData: SiteAccountUserData.nullable(),
  userDataAt: Timestamp.nullable(),
  hasTotp: z.boolean(),
  /** 账密登录得到的会话 Cookie 已保存 */
  hasSession: z.boolean(),
  hasPasskey: z.boolean(),
});
export type SiteAccount = z.infer<typeof SiteAccount>;
/** @deprecated 新客户端用 PUT /sites/{id}/credentials(SiteCredentialsBody) */
export const SiteAccountCreate = SiteAccount.pick({ siteId: true, label: true, authKind: true, enabled: true })
  .partial({ enabled: true })
  .extend({ credential: z.string().min(1).max(16384) });
export type SiteAccountCreate = z.infer<typeof SiteAccountCreate>;
/** @deprecated 凭证部分改走 PUT /sites/{id}/credentials;label / enabled 仍可用 */
export const SiteAccountUpdate = SiteAccountCreate.omit({ siteId: true }).partial();
export type SiteAccountUpdate = z.infer<typeof SiteAccountUpdate>;

// ── W9-A 站点中心(docs/design/site-center.md) ──

/** POST /sites/{id}/health-check:首页连通 + 登录态 */
export const SiteHealthResult = SiteLastHealth.extend({
  siteId: Id,
  checkedAt: Timestamp,
  /** 登录态:true 已登录;false 未登录 / 失效;null 未能判定(网络失败、无凭证) */
  loggedIn: z.boolean().nullable(),
  /** 写回后的站点健康 */
  healthStatus: SiteHealth,
});
export type SiteHealthResult = z.infer<typeof SiteHealthResult>;

const CredLabel = z.string().min(1).max(80).default("default");
const CredSecret = z.string().min(1).max(16384);
const CredUa = z.string().min(1).max(500);
/**
 * PUT /sites/{id}/credentials 新格式(按 kind 判别)。按 (siteId, label) 建立或更新账号;明文加密为 secret,不回显。
 * 更新凭证:账号回到 unknown,关闭该站 site-auth / site-login 待处理。
 */
export const SiteCredentialsBody = z.discriminatedUnion("kind", [
  z.object({
    kind: z.literal("password"),
    label: CredLabel,
    username: z.string().min(1).max(200),
    password: CredSecret,
    /** TOTP 密钥(base32);表单有二次验证字段时自动填当前 6 位码 */
    totpSecret: z.string().min(1).max(200).optional(),
    /** 只换 Cookie:登录成功后凭证类型落为 cookie,密码与 TOTP 丢弃 */
    saveCookieOnly: z.boolean().optional(),
    userAgent: CredUa.optional(),
    enabled: z.boolean().optional(),
  }),
  z.object({
    kind: z.literal("cookie"),
    label: CredLabel,
    cookie: CredSecret,
    userAgent: CredUa.optional(),
    enabled: z.boolean().optional(),
  }),
  z.object({ kind: z.literal("api_key"), label: CredLabel, apiKey: CredSecret, enabled: z.boolean().optional() }),
  /** passkey 附加到同账号(RSS / 下载用,不参与登录);账号不存在时新建 passkey 型账号 */
  z.object({ kind: z.literal("passkey"), label: CredLabel, passkey: CredSecret, enabled: z.boolean().optional() }),
]);
export type SiteCredentialsBody = z.infer<typeof SiteCredentialsBody>;

/** POST /sites/{id}/refresh-login */
export const SiteRefreshLoginInput = z.object({
  /** 缺省:该站第一个启用账号 */
  accountId: Id.optional(),
  /** true:同步执行并返回结果(≤ 30 s,添加站点第 ③ 步用);缺省异步入队返回 taskId */
  wait: z.boolean().optional(),
});
export type SiteRefreshLoginInput = z.infer<typeof SiteRefreshLoginInput>;

export const SiteLoginResult = z.object({
  siteId: Id,
  accountId: Id,
  ok: z.boolean(),
  /** 处理后的账号状态;网络失败时不变 */
  status: SiteAccountStatus,
  reason: SiteLoginFailureReason.nullable(),
  message: z.string().nullable(),
  /** 成功时的用户数据(拉取失败为 null,不影响登录结果) */
  userData: SiteAccountUserData.nullable(),
  /** 失败时开出的待处理事项 */
  decisionId: Id.nullable(),
});
export type SiteLoginResult = z.infer<typeof SiteLoginResult>;
export const SiteRefreshLoginAccepted = z.object({
  /** 异步时的引擎任务 ID;wait=true 为 null */
  taskId: Id.nullable(),
  /** wait=true 时的结果 */
  result: SiteLoginResult.nullable(),
});
export type SiteRefreshLoginAccepted = z.infer<typeof SiteRefreshLoginAccepted>;

/** site_user_data 表行:用户数据按天一行(同日 upsert 取最新),随账号删除 */
export const SiteUserData = EntityBase.extend({
  siteAccountId: Id,
  day: DateOnly,
  upload: z.number().nonnegative(),
  download: z.number().nonnegative(),
  ratio: z.number().nullable(),
  bonus: z.number().nullable(),
  seeding: NonNegInt,
  seedingSize: z.number().nonnegative(),
  leeching: NonNegInt,
  userLevel: z.string().nullable(),
  vip: z.boolean().nullable(),
  messageUnread: NonNegInt,
  joinAt: z.string().nullable(),
  /** SiteUserInfo 其余字段(不含凭据、消息正文、做种明细) */
  raw: JsonObject,
  capturedAt: Timestamp,
});
export type SiteUserData = z.infer<typeof SiteUserData>;
/** GET /sites/{id}/user-data 的一点 */
export const SiteUserDataPoint = SiteUserData.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
  raw: true,
  joinAt: true,
});
export type SiteUserDataPoint = z.infer<typeof SiteUserDataPoint>;
export const SiteUserDataQuery = z.object({
  accountId: Id.optional(),
  days: z.coerce.number().int().min(1).max(400).default(30),
});
export type SiteUserDataQuery = z.infer<typeof SiteUserDataQuery>;

/** 站点整体账号状态:多账号取最差;无启用账号 = unconfigured */
export const SiteAccountOverall = z.enum(["unconfigured", ...SiteAccountStatus.options]);
export type SiteAccountOverall = z.infer<typeof SiteAccountOverall>;

/** GET /sites?include=accounts 的条目(不带 include 时两个附加字段缺省) */
export const SiteListItem = Site.extend({
  accounts: z.array(SiteAccount).optional(),
  accountStatus: SiteAccountOverall.optional(),
});
export type SiteListItem = z.infer<typeof SiteListItem>;
export const SiteListQuery = CursorQuery.extend({ include: z.enum(["accounts"]).optional() });
export type SiteListQuery = z.infer<typeof SiteListQuery>;

export const FeedPurpose = z.enum(["movie", "series", "variety", "promotion", "search", "generic"]);
export type FeedPurpose = z.infer<typeof FeedPurpose>;
export const FeedKind = z.enum(["rss", "atom", "list", "query"]);
export type FeedKind = z.infer<typeof FeedKind>;
export const FeedHealth = z.enum(["unknown", "healthy", "degraded", "failing", "circuit_open", "disabled"]);
export type FeedHealth = z.infer<typeof FeedHealth>;

export const FeedSource = EntityBase.extend({
  siteId: Id.nullable(),
  siteAccountId: Id.nullable(),
  name: z.string().min(1),
  purpose: FeedPurpose,
  kind: FeedKind,
  urlSecretRef: Id.nullable(),
  /** 脱敏 URL(passkey 等参数替换为 [REDACTED]) */
  urlDisplay: z.string(),
  parserVersion: z.string(),
  enabled: z.boolean(),
  pollIntervalSec: z.number().int().min(60),
  filter: JsonObject,
  cursor: JsonObject,
  etag: z.string().nullable(),
  lastModified: z.string().nullable(),
  lastFetchAt: Timestamp.nullable(),
  lastSuccessAt: Timestamp.nullable(),
  nextFetchAt: Timestamp.nullable(),
  consecutiveFailures: NonNegInt,
  backoffUntil: Timestamp.nullable(),
  healthStatus: FeedHealth,
  lastError: JsonObject.nullable(),
  /**
   * 派生字段(非表列):最近一次抓取发现与上次窗口零重叠 → 疑似漏项,已排站点补漏。
   * 下一次抓取窗口重新衔接后清空。站点未登记的 Feed 无法补漏(backfillQueued=false)。
   */
  possibleGap: z
    .object({ detectedAt: Timestamp, previousFetchedAt: Timestamp.nullable(), backfillQueued: z.boolean() })
    .nullable(),
  /** 只在创建响应里出现:不拦截的提示(如地址域名与所选站点不一致) */
  warnings: z.array(z.string()).optional(),
});
export type FeedSource = z.infer<typeof FeedSource>;
/**
 * url 为只写明文(可能含 passkey),服务端加密存为 secret 并生成 urlDisplay。
 * 带 siteId 时可只给 url(+ purpose):账号缺省取该站启用账号(优先带 passkey)、解析器按站点定义、名称缺省「站点名 RSS」;
 * 不带 siteId 时名称缺省为地址主机名。
 */
export const FeedSourceCreate = FeedSource.pick({
  siteId: true,
  siteAccountId: true,
  name: true,
  purpose: true,
  kind: true,
  enabled: true,
  pollIntervalSec: true,
  filter: true,
})
  .partial({
    siteId: true,
    siteAccountId: true,
    name: true,
    purpose: true,
    kind: true,
    enabled: true,
    pollIntervalSec: true,
    filter: true,
  })
  .extend({ url: z.url() });
export type FeedSourceCreate = z.infer<typeof FeedSourceCreate>;
export const FeedSourceUpdate = FeedSourceCreate.partial();
export type FeedSourceUpdate = z.infer<typeof FeedSourceUpdate>;

export const ResolutionStatus = z.enum(["unresolved", "resolved", "ambiguous", "unidentifiable", "rejected"]);
export type ResolutionStatus = z.infer<typeof ResolutionStatus>;
export const ReleaseAvailability = z.enum(["active", "site_disabled", "expired", "unknown"]);
export type ReleaseAvailability = z.infer<typeof ReleaseAvailability>;

/** 促销状态必须带观察时间与过期时间,下单前按策略复核(REQ §4.3) */
export const Promotion = z.object({
  kind: z.string().optional(),
  observedAt: Timestamp.optional(),
  expiresAt: Timestamp.nullable().optional(),
  raw: z.unknown().optional(),
});
export type Promotion = z.infer<typeof Promotion>;

export const TorrentFileEntry = z.object({
  path: z.string(),
  size: NonNegInt,
});
export type TorrentFileEntry = z.infer<typeof TorrentFileEntry>;

export const SourceRelease = EntityBase.extend({
  siteId: Id,
  siteReleaseId: z.string().min(1),
  title: z.string(),
  subtitle: z.string().nullable(),
  categoryRaw: z.string().nullable(),
  tagsRaw: z.array(z.string()),
  sizeBytes: NonNegInt.nullable(),
  infohashV1: z.string().nullable(),
  infohashV2: z.string().nullable(),
  fileList: z.array(TorrentFileEntry).nullable(),
  promotion: Promotion,
  promotionExpiresAt: Timestamp.nullable(),
  seeders: z.number().int().nullable(),
  leechers: z.number().int().nullable(),
  /** 站点发布时间;区别于 firstSeenAt(本系统首次发现) */
  sourcePublishedAt: Timestamp.nullable(),
  firstSeenAt: Timestamp,
  lastSeenAt: Timestamp,
  detailFetchedAt: Timestamp.nullable(),
  /** 标题解析结果(标题/年份/季集/分辨率/来源/编码/发布组…) */
  parsed: JsonObject,
  parserVersion: z.string().nullable(),
  mediaEntityId: Id.nullable(),
  contentUnitId: Id.nullable(),
  resolutionStatus: ResolutionStatus,
  resolutionEvidence: JsonObject,
  availability: ReleaseAvailability,
  raw: JsonObject,
  /** 人工确认的身份关联:自动识别/复查不得改写 mediaEntityId/contentUnitId */
  resolutionLocked: z.boolean(),
});
export type SourceRelease = z.infer<typeof SourceRelease>;
/** 由适配器/任务写入(按 siteId+siteReleaseId upsert) */
export const SourceReleaseCreate = SourceRelease.omit({
  ...SERVER_MANAGED,
  firstSeenAt: true,
  lastSeenAt: true,
}).partial({
  subtitle: true,
  categoryRaw: true,
  tagsRaw: true,
  sizeBytes: true,
  infohashV1: true,
  infohashV2: true,
  fileList: true,
  promotion: true,
  promotionExpiresAt: true,
  seeders: true,
  leechers: true,
  sourcePublishedAt: true,
  detailFetchedAt: true,
  parsed: true,
  parserVersion: true,
  mediaEntityId: true,
  contentUnitId: true,
  resolutionStatus: true,
  resolutionEvidence: true,
  availability: true,
  raw: true,
  resolutionLocked: true,
});
export type SourceReleaseCreate = z.infer<typeof SourceReleaseCreate>;
export const SourceReleaseUpdate = SourceReleaseCreate.omit({ siteId: true, siteReleaseId: true }).partial();
export type SourceReleaseUpdate = z.infer<typeof SourceReleaseUpdate>;

export const ObservationStatus = z.enum(["new", "linked", "ignored", "error"]);
export type ObservationStatus = z.infer<typeof ObservationStatus>;

export const Observation = EntityBase.extend({
  feedId: Id,
  guid: z.string().min(1),
  contentDigest: z.string().min(1),
  sourceReleaseId: Id.nullable(),
  title: z.string(),
  /** 已脱敏的链接;原始下载链接不对外 */
  linkRedacted: z.string().nullable(),
  raw: JsonObject,
  sourcePublishedAt: Timestamp.nullable(),
  fetchedAt: Timestamp,
  firstSeenAt: Timestamp,
  lastSeenAt: Timestamp,
  status: ObservationStatus,
  resolveAttempts: NonNegInt,
  nextResolveAt: Timestamp.nullable(),
  lastError: JsonObject.nullable(),
});
export type Observation = z.infer<typeof Observation>;
export const ObservationCreate = Observation.pick({
  feedId: true,
  guid: true,
  contentDigest: true,
  sourceReleaseId: true,
  title: true,
  linkRedacted: true,
  raw: true,
  sourcePublishedAt: true,
  fetchedAt: true,
}).partial({ sourceReleaseId: true, linkRedacted: true, raw: true, sourcePublishedAt: true, fetchedAt: true });
export type ObservationCreate = z.infer<typeof ObservationCreate>;
export const ObservationUpdate = Observation.pick({
  contentDigest: true,
  sourceReleaseId: true,
  title: true,
  raw: true,
  status: true,
  resolveAttempts: true,
  nextResolveAt: true,
  lastError: true,
}).partial();
export type ObservationUpdate = z.infer<typeof ObservationUpdate>;

// ── W2-B:站点快照、调度事件与站点工作台 ──

export const SiteSnapshotKind = z.enum(["periodic", "backfill", "live_search", "manual"]);
export type SiteSnapshotKind = z.infer<typeof SiteSnapshotKind>;
export const SiteSnapshotStatus = z.enum(["running", "ok", "partial", "failed"]);
export type SiteSnapshotStatus = z.infer<typeof SiteSnapshotStatus>;

/** 一次列表快照 / 实时补查 / 补漏的覆盖范围与结果(不把一次分页伪称全站快照,REQ §4.6) */
export const SiteSnapshot = EntityBase.extend({
  siteId: Id,
  kind: SiteSnapshotKind,
  query: z.string().nullable(),
  filters: JsonObject,
  /** 实际抓取的页码(1 起) */
  pages: z.array(z.number().int().positive()),
  itemCount: NonNegInt,
  newCount: NonNegInt,
  status: SiteSnapshotStatus,
  error: JsonObject.nullable(),
  definitionVersion: z.string().nullable(),
  startedAt: Timestamp,
  finishedAt: Timestamp.nullable(),
});
export type SiteSnapshot = z.infer<typeof SiteSnapshot>;

/** 站点访问默认(站点定义 umt.defaults 与 settings.sites 合并后,取更保守的一方) */
export const SiteAccessDefaults = z.object({
  snapshotIntervalSec: z.number().int(),
  snapshotMaxPages: z.number().int(),
  healthCheckIntervalSec: z.number().int(),
  detailCacheSec: z.number().int(),
  searchConcurrency: z.number().int(),
});
export type SiteAccessDefaults = z.infer<typeof SiteAccessDefaults>;

/** 站点请求统计:每从站点限流器拿到一个令牌记一次(列表 / 搜索 / 详情 / 下载 / 登录 / 用户数据 / 原站视图) */
export const SiteRequestStats = z.object({
  siteId: z.string(),
  last24h: z.number().int(),
  /** 最近 24 个整点小时(旧 → 新),没有请求的小时计 0 */
  hourly: z.array(z.object({ hour: z.string(), count: z.number().int() })),
  /** 快照实际周期(站点行设置优先) */
  snapshotIntervalSec: z.number().int(),
  access: SiteAccessDefaults,
});
export type SiteRequestStats = z.infer<typeof SiteRequestStats>;

/** 站点注册表条目(随产品发布的适配器定义)+ 是否已在本系统登记 */
export const SiteDefinitionView = z.object({
  key: z.string(),
  name: z.string(),
  adapter: SiteAdapter,
  baseUrl: z.string(),
  /** 定义是否随产品启用(未实测站点为 false) */
  shippedEnabled: z.boolean(),
  definitionVersion: z.string(),
  capabilities: z.object({
    list: z.boolean(),
    search: z.boolean(),
    detail: z.boolean(),
    download: z.boolean(),
    rss: z.boolean(),
  }),
  defaultRateLimit: z.object({ minIntervalMs: NonNegInt, burst: z.number().int().positive() }),
  authSupported: z.array(z.string()),
  /** 已登记的 site 行 ID;未登记为 null */
  siteId: Id.nullable(),
});
export type SiteDefinitionView = z.infer<typeof SiteDefinitionView>;

/** Feed 到期(调度器发出,outbox 路由到 ingestFeed) */
export const FeedDuePayload = z.object({ feedId: Id, reason: z.enum(["schedule", "manual"]) });
/** 新的 source_release 被观察到(或同一资源标题更新),outbox 路由到 resolveObservation */
export const ReleaseObservedPayload = z.object({
  sourceReleaseId: Id,
  observationId: Id.nullable(),
  siteId: Id,
  isNew: z.boolean(),
});
/** Feed 窗口与上次零重叠:疑似缺口,路由到有预算的列表补漏(snapshotSite backfill) */
export const FeedGapSuspectedPayload = z.object({
  feedId: Id,
  siteId: Id.nullable(),
  previousFetchedAt: Timestamp.nullable(),
  detectedAt: Timestamp,
});

/** 站点工作台列表查询(整理视图):快照优先,必要时实时补查 */
export const WorkbenchReleaseQuery = z.object({
  q: z.string().trim().min(1).max(200).optional(),
  category: z.string().max(100).optional(),
  /** 只看某类促销(free/2xfree/50%…) */
  promotion: z.string().max(20).optional(),
  resolution: ResolutionStatus.optional(),
  /** true = 强制实时补查;false = 只看本地快照;缺省 = 本地无结果或快照过期时补查 */
  live: z.enum(["true", "false"]).optional(),
  cursor: z.string().min(1).optional(),
  limit: z.coerce.number().int().min(1).max(200).default(50),
});
export type WorkbenchReleaseQuery = z.infer<typeof WorkbenchReleaseQuery>;

/** 数据来源:快照 / Feed 观察 / 实时补查 */
export const ReleaseOrigin = z.enum(["snapshot", "feed", "live", "unknown"]);
export type ReleaseOrigin = z.infer<typeof ReleaseOrigin>;

/**
 * 工作台条目:source_release + 来源标注 + 本地实体关联。
 * 库存叠加(已有资产/Slot/下载状态)由前端按 mediaEntityId 二次查询 W2-C 端点,不在这里猜。
 */
export const WorkbenchRelease = SourceRelease.extend({
  origin: ReleaseOrigin,
  /** 本条数据最近一次被站点确认的时间(快照/Feed/实时) */
  dataUpdatedAt: Timestamp,
  observedByFeeds: NonNegInt,
  entity: z.object({ id: Id, title: z.string(), year: z.number().int().nullable(), kind: z.string() }).nullable(),
});
export type WorkbenchRelease = z.infer<typeof WorkbenchRelease>;

export const WorkbenchCoverage = z.object({
  siteEnabled: z.boolean(),
  lastSnapshotAt: Timestamp.nullable(),
  /** 快照过期(超过 2 个周期或从未快照) */
  stale: z.boolean(),
  fromSnapshot: z.boolean(),
  live: z.boolean(),
  liveError: z.string().nullable(),
  /** 同一搜索正在进行时合并到已有请求 */
  coalesced: z.boolean(),
});
export type WorkbenchCoverage = z.infer<typeof WorkbenchCoverage>;

export const WorkbenchReleasePage = z.object({
  items: z.array(WorkbenchRelease),
  nextCursor: z.string().nullable(),
  coverage: WorkbenchCoverage,
});
export type WorkbenchReleasePage = z.infer<typeof WorkbenchReleasePage>;

/**
 * 站点详情页扩展内容(按需抓详情时得到,服务端缓存 24 小时;过期后需再次复核详情)。
 * 截图地址是服务端图片代理路径(/api/v1/img/site-detail/{releaseId}/{index}),不直连外站。
 */
export const SiteReleasePage = z.object({
  fetchedAt: Timestamp,
  descriptionText: z.string().nullable(),
  mediaInfo: z.string().nullable(),
  screenshots: z.array(z.object({ url: z.string(), host: z.string() })),
  imdbId: z.string().nullable(),
  doubanId: z.string().nullable(),
  tmdb: z.object({ type: z.enum(["movie", "tv"]), id: z.string() }).nullable(),
  files: z.array(z.object({ name: z.string(), sizeBytes: z.number().int().nullable() })),
  tags: z.array(z.string()),
  uploader: z.string().nullable(),
});
export type SiteReleasePage = z.infer<typeof SiteReleasePage>;

export const WorkbenchReleaseDetail = z.object({
  release: WorkbenchRelease,
  observations: z.array(
    z.object({
      observationId: Id,
      feedId: Id,
      feedName: z.string(),
      firstSeenAt: Timestamp,
      lastSeenAt: Timestamp,
    }),
  ),
  /** 易变字段的复核时间:缓存命中不能替代下载前复核(REQ §4.6) */
  volatile: z.object({
    promotionObservedAt: Timestamp.nullable(),
    promotionExpiresAt: Timestamp.nullable(),
    peersObservedAt: Timestamp,
    detailFetchedAt: Timestamp.nullable(),
    recheckBeforeDownload: z.literal(true),
  }),
  /** 刷新详情失败时保留既有数据并给出原因 */
  refreshError: z.string().nullable(),
  /** 详情页扩展内容;没抓过、缓存已过期或站点不支持详情页时为 null */
  page: SiteReleasePage.nullable(),
  /** 站点能否抓详情页(false 时前端不自动抓) */
  detailSupported: z.boolean(),
});
export type WorkbenchReleaseDetail = z.infer<typeof WorkbenchReleaseDetail>;