UHD_Media_Tool/packages/contracts/src/sources.ts

import { z } from "zod";
import { 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>;

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,
});
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,
}).partial({ enabled: true, rateLimit: true, config: true, snapshotEnabled: true, snapshotIntervalSec: 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>;
export const SiteAccountStatus = z.enum(["unknown", "active", "invalid", "expired"]);
export type SiteAccountStatus = z.infer<typeof SiteAccountStatus>;

export const SiteAccount = EntityBase.extend({
  siteId: Id,
  label: z.string().min(1),
  authKind: SiteAuthKind,
  secretRef: Id.nullable(),
  enabled: z.boolean(),
  status: SiteAccountStatus,
  lastVerifiedAt: Timestamp.nullable(),
  userInfo: JsonObject,
});
export type SiteAccount = z.infer<typeof SiteAccount>;
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>;
export const SiteAccountUpdate = SiteAccountCreate.omit({ siteId: true }).partial();
export type SiteAccountUpdate = z.infer<typeof SiteAccountUpdate>;

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(),
});
export type FeedSource = z.infer<typeof FeedSource>;
/** url 为只写明文(可能含 passkey),服务端加密存为 secret 并生成 urlDisplay */
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,
    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>;

/** 站点注册表条目(随产品发布的适配器定义)+ 是否已在本系统登记 */
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>;

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(),
});
export type WorkbenchReleaseDetail = z.infer<typeof WorkbenchReleaseDetail>;