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";
import { QuickFilterParam, ReleaseQuickFacets } from "./release-facets.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", "subtitle"]);
export type SiteAdapter = z.infer<typeof SiteAdapter>;

/**
 * 站点类型(IA-2):PT 站之外的下载来源都作为一种站点类型。类型声明它可能支持的获取方式,
 * 站点实际可用的方式 = 类型允许的 ∩ 适配器(站点定义)实现的,见 siteCapabilities。
 * torznab 只定义结构(Jackett / Prowlarr 的 Torznab 接口),尚未实现:不能添加,也不参与调度。
 */
export const SiteKind = z.enum(["pt", "public_bt", "rss_feed", "torznab", "subtitle"]);
export type SiteKind = z.infer<typeof SiteKind>;
/** 获取方式:搜索 / 列表抓取 / RSS / 详情页 / 登录 / 账号数据(上传量、分享率、等级) */
export const SiteCapability = z.enum(["search", "list", "rss", "detail", "login", "userinfo"]);
export type SiteCapability = z.infer<typeof SiteCapability>;

export interface SiteKindSpec {
  /** 界面名 */
  label: string;
  /** 添加站点第一步的一句说明 */
  description: string;
  /** 这类站点可能支持的获取方式 */
  capabilities: readonly SiteCapability[];
  /** false = 只定义了结构,还不能添加 */
  implemented: boolean;
  /** 需要从站点定义库里选(PT 站);否则只填名称和地址 */
  fromDefinition: boolean;
}

export const SITE_KINDS: Record<SiteKind, SiteKindSpec> = {
  pt: {
    label: "PT 站",
    description: "需要账号的私有站。从站点定义里选，支持搜索、列表抓取、RSS、登录和账号数据",
    capabilities: ["search", "list", "rss", "detail", "login", "userinfo"],
    implemented: true,
    fromDefinition: true,
  },
  public_bt: {
    label: "公开 BT 站",
    description: "不用登录的公开站：Nyaa、蜜柑、AniBT、AnimeGarden、萌番组",
    capabilities: ["search", "list", "rss", "detail"],
    implemented: true,
    fromDefinition: false,
  },
  rss_feed: {
    label: "自定义 RSS 源",
    description: "只有一个 RSS 地址的来源，不登录、不搜索",
    capabilities: ["rss"],
    implemented: true,
    fromDefinition: false,
  },
  torznab: {
    label: "Torznab 索引器",
    description: "Jackett、Prowlarr 等索引器的 Torznab 接口，还不支持",
    capabilities: ["search", "rss"],
    implemented: false,
    fromDefinition: false,
  },
  subtitle: {
    label: "字幕站",
    description: "给媒体库里的作品搜字幕、下载字幕：SubHD、字幕库",
    capabilities: [],
    implemented: true,
    fromDefinition: false,
  },
};

/** 站点定义(适配器)声明的能力;没有定义的站点传 null */
export type SiteDefinitionCaps = { search: boolean; list: boolean; detail: boolean } | null;

/**
 * 站点实际可用的获取方式:类型允许的 ∩ 适配器实现的。RSS 走通用解析器,不依赖站点定义;
 * 搜索 / 列表 / 详情要站点定义声明支持;登录与账号数据要有站点定义(没有定义就没有登录流程)。
 */
/** 内置字幕站(docs/plan/subtitles.md):站点页「字幕站」一键添加,搜索与下载在 subtitles 模块 */
export const SUBTITLE_SITES = [
  { key: "subhd", name: "SubHD", baseUrl: "https://subhd.tv/" },
  { key: "zimuku", name: "字幕库", baseUrl: "https://zmk.pw/" },
] as const;
export type SubtitleSiteKey = (typeof SUBTITLE_SITES)[number]["key"];

export function siteCapabilities(kind: SiteKind, def: SiteDefinitionCaps): SiteCapability[] {
  const spec = SITE_KINDS[kind];
  if (!spec.implemented) return [];
  return spec.capabilities.filter((c) => {
    if (c === "rss") return true;
    if (!def) return false;
    if (c === "search") return def.search;
    if (c === "list") return def.list;
    if (c === "detail") return def.detail;
    return true;
  });
}

/**
 * Torznab 索引器的站点 config(只定义结构,未实现):API 地址、API Key 的 secret 引用、分类过滤。
 * 对照 MP 的 Jackett / Prowlarr 插件:按索引器登记,搜索走 `t=search`,RSS 走不带 q 的同一接口。
 */
export const TorznabSiteConfig = z.object({
  apiUrl: z.url(),
  apiKeySecretRef: z.uuid().nullable(),
  indexerId: z.string().max(200).nullable(),
  categories: z.array(z.number().int().nonnegative()).default([]),
});
export type TorznabSiteConfig = z.infer<typeof TorznabSiteConfig>;

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 / challenge */
  status: z.string(),
  latencyMs: z.number().int().nonnegative().nullable(),
  message: z.string().nullable(),
  /**
   * 原始判定(技术信息):reason = logged_in / user_data / login_page / permission_page / challenge /
   * marker_missing / redirect_login / http;rule 命中的规则,selector 登录标志选择器。旧记录没有这个字段
   */
  detail: z.record(z.string(), z.unknown()).nullable().optional(),
});
export type SiteLastHealth = z.infer<typeof SiteLastHealth>;

/**
 * 站点的 Cloudflare 处理状态(CF-2,存 site.config.cloudflare;docs/runbook/sites.md「Cloudflare」):
 * - browserUntil:在此之前该站能走浏览器的页面请求直接由浏览器代抓(HTTP 仍被挑战时置 6 小时,到期再试 HTTP);
 * - cfReuse:浏览器拿到的 cf_clearance 给 HTTP 用的结果(ok 有效 / fails 无效,之后不再复用);
 * - lastSolvedBy:最近一次怎么过的挑战(auto 等它自己过 / vision 视觉子流程点了一下 / human 人在原站视图里过);
 * - pending = human:遇到选图 / 输码类验证码,等人在原站视图里过一次;
 * - lastAttemptAt:最近一次尝试过挑战(同站 30 分钟最多一次)。
 */
export const SiteCloudflareState = z.object({
  browserUntil: Timestamp.nullable().default(null),
  cfReuse: z.enum(["ok", "fails"]).nullable().default(null),
  lastChallengeAt: Timestamp.nullable().default(null),
  lastSolvedBy: z.enum(["auto", "vision", "human"]).nullable().default(null),
  lastSolvedAt: Timestamp.nullable().default(null),
  lastAttemptAt: Timestamp.nullable().default(null),
  pending: z.enum(["human"]).nullable().default(null),
  /** 等人处理的浏览器会话(原站视图接管入口) */
  sessionId: Id.nullable().default(null),
  /** 最近一次处理结果(技术信息):passed / reuse_ok / reuse_fails / browser / needs_human / failed / throttled / skipped */
  lastResult: z.string().nullable().default(null),
  /** 命中的挑战规则(技术信息) */
  lastRule: z.string().nullable().default(null),
  /** 最近一次失败原因(技术信息) */
  lastError: z.string().nullable().default(null),
});
export type SiteCloudflareState = z.infer<typeof SiteCloudflareState>;

/** 从 site.config 读 Cloudflare 状态;没有或格式不对返回 null */
export function siteCloudflareState(config: unknown): SiteCloudflareState | null {
  const raw = (config as { cloudflare?: unknown } | null | undefined)?.cloudflare;
  if (!raw || typeof raw !== "object") return null;
  const r = SiteCloudflareState.safeParse(raw);
  return r.success ? r.data : null;
}

export const Site = EntityBase.extend({
  key: z.string().regex(/^[a-z][a-z0-9_-]*$/),
  name: z.string().min(1),
  /** 站点类型(IA-2) */
  kind: SiteKind,
  /** 派生字段(非表列):实际可用的获取方式,见 siteCapabilities */
  capabilities: z.array(SiteCapability),
  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(),
  /** 该站资源用的下载器;null = 默认下载器(订阅 / 手动明确指定时以指定为准) */
  downloaderInstanceId: Id.nullable(),
});
export type Site = z.infer<typeof Site>;
export const SiteCreate = Site.pick({
  key: true,
  name: true,
  kind: true,
  adapter: true,
  baseUrl: true,
  enabled: true,
  rateLimit: true,
  config: true,
  snapshotEnabled: true,
  snapshotIntervalSec: true,
  proxy: true,
  searchDefault: true,
  downloaderInstanceId: true,
})
  .partial({
    key: true,
    kind: true,
    enabled: true,
    rateLimit: true,
    config: true,
    snapshotEnabled: true,
    snapshotIntervalSec: true,
    proxy: true,
    searchDefault: true,
    downloaderInstanceId: true,
  })
  .extend({
    /**
     * 非 PT 站(public_bt / rss_feed)添加时一并建的 RSS 地址(只写,存为 secret)。
     * key 缺省时按地址主机名生成(rss-<主机>,重名加序号)。
     */
    rssUrl: z.url().optional(),
  });
export type SiteCreate = z.infer<typeof SiteCreate>;
/** 类型添加后不改(换类型 = 删了重加) */
export const SiteUpdate = SiteCreate.omit({ key: true, kind: true, rssUrl: 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;空 = 不覆盖(见 userAgentSource / effectiveUserAgent) */
  userAgent: z.string().nullable(),
  /**
   * 当前生效 UA 的来源(BR-4):browser = 跟随浏览器;manual = 账号手动填写;global = 设置里的全局 UA;
   * pending = 待切换(沿用取得当前 Cookie 时的旧 UA,下次重新登录或浏览器回写 Cookie 时换成浏览器 UA)
   */
  userAgentSource: z.enum(["browser", "manual", "global", "pending"]),
  /** 当前站点请求实际发送的 UA(技术信息) */
  effectiveUserAgent: z.string(),
  /** 仅浏览器用、没有回写给站点请求的 Cookie 名(Cloudflare 验证 Cookie,不含值) */
  browserOnlyCookies: z.array(z.string()),
  /** 最近一次登录 / 校验成功(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 CredSecretKeep = z.string().max(16384).optional();
const CredUa = z.string().min(1).max(500);
/**
 * PUT /sites/{id}/credentials 新格式(按 kind 判别)。按 (siteId, label) 建立或更新账号;明文加密为 secret,不回显。
 * 更新凭证:账号回到 unknown,关闭该站 site-auth / site-login 待处理。
 * 同类账号更新时 password / cookie / apiKey 省略或空串 = 保持原值;totpSecret 省略或空串 = 保持,null = 清除。
 */
export const SiteCredentialsBody = z.discriminatedUnion("kind", [
  z.object({
    kind: z.literal("password"),
    label: CredLabel,
    username: z.string().min(1).max(200),
    password: CredSecretKeep,
    /** TOTP 密钥(base32);表单有二次验证字段时自动填当前 6 位码 */
    totpSecret: z.string().max(200).nullable().optional(),
    /** 只换 Cookie:登录成功后凭证类型落为 cookie,密码与 TOTP 丢弃 */
    saveCookieOnly: z.boolean().optional(),
    userAgent: CredUa.optional(),
    enabled: z.boolean().optional(),
  }),
  z.object({
    kind: z.literal("cookie"),
    label: CredLabel,
    cookie: CredSecretKeep,
    userAgent: CredUa.optional(),
    enabled: z.boolean().optional(),
  }),
  z.object({ kind: z.literal("api_key"), label: CredLabel, apiKey: CredSecretKeep, 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(),
  /** 集数解析结果(原始季集、规范季集、方式、规则、证据);未解析过为 null */
  episodeResolution: JsonObject.nullable(),
});
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,
  episodeResolution: 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 SiteFailureSampleKind = z.enum(["parse_error", "challenge"]);
export type SiteFailureSampleKind = z.infer<typeof SiteFailureSampleKind>;

/**
 * 站点请求失败留样(列表 / 搜索 / 详情报 parse_error / challenge 时存的脱敏页面开头,每站最近 5 份)。
 * requestKind:search / list / detail / health / other;headers 只有 server、cf-mitigated、cf-ray、content-type。
 */
export const SiteFailureSample = z.object({
  id: Id,
  siteId: Id,
  kind: SiteFailureSampleKind,
  requestKind: z.string(),
  /** 已脱敏 */
  url: z.string(),
  httpStatus: z.number().int().nullable(),
  headers: z.record(z.string(), z.string()),
  message: z.string(),
  rule: z.string().nullable(),
  /** 脱敏后的页面开头(≤ 64 KB) */
  body: z.string(),
  truncated: z.boolean(),
  createdAt: Timestamp,
});
export type SiteFailureSample = z.infer<typeof SiteFailureSample>;
/** 列表里不带页面正文,只给字节数 */
export const SiteFailureSampleSummary = SiteFailureSample.omit({ body: true }).extend({ bodyBytes: NonNegInt });
export type SiteFailureSampleSummary = z.infer<typeof SiteFailureSampleSummary>;

/** 站点访问默认(站点定义 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(),
  /** 定义对应的站点类型(PT 站;Nyaa、蜜柑等内置公开 BT 站为 public_bt) */
  kind: SiteKind,
  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(),
  /** 快速筛选(SEARCH-3,格式同 GET /search/releases 的 qf);只筛本地数据,不触发站点请求 */
  qf: QuickFilterParam,
  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,
  /** 快速筛选后的条数 */
  total: NonNegInt.optional(),
  /** 快速筛选前的条数(q / 分类 / 促销 / 识别状态筛选之后) */
  unfilteredTotal: NonNegInt.optional(),
  /** 快速筛选分面(SEARCH-3,基于本地资源表数据);site 只有本站一项 */
  facets: ReleaseQuickFacets.optional(),
});
export type WorkbenchReleasePage = z.infer<typeof WorkbenchReleasePage>;

/** MediaInfo / BDInfo 概要;字段认不出为 null */
export const SiteMediaSummary = z.object({
  kind: z.enum(["mediainfo", "bdinfo"]),
  general: z.object({
    fileName: z.string().nullable(),
    container: z.string().nullable(),
    duration: z.string().nullable(),
    overallBitrate: z.string().nullable(),
    size: z.string().nullable(),
  }),
  video: z.array(
    z.object({
      codec: z.string().nullable(),
      resolution: z.string().nullable(),
      frameRate: z.string().nullable(),
      bitrate: z.string().nullable(),
      bitDepth: z.string().nullable(),
      hdr: z.array(z.string()),
    }),
  ),
  audio: z.array(
    z.object({
      language: z.string().nullable(),
      codec: z.string().nullable(),
      channels: z.string().nullable(),
      bitrate: z.string().nullable(),
      title: z.string().nullable(),
      isDefault: z.boolean().nullable(),
    }),
  ),
  subtitles: z.array(
    z.object({
      language: z.string().nullable(),
      format: z.string().nullable(),
      title: z.string().nullable(),
      isDefault: z.boolean().nullable(),
      forced: z.boolean().nullable(),
    }),
  ),
});
export type SiteMediaSummary = z.infer<typeof SiteMediaSummary>;

/** 文件目录树(先序展平,按 depth 缩进);role:主视频 / sample / 字幕 / 附件 / 其他视频 / 其他,目录为 null */
export const SiteFileTreeRow = z.object({
  path: z.string(),
  name: z.string(),
  depth: z.number().int(),
  dir: z.boolean(),
  sizeBytes: z.number().int().nullable(),
  role: z.enum(["main", "sample", "subtitle", "extra", "video", "other"]).nullable(),
  fileCount: z.number().int().nullable(),
});
export type SiteFileTreeRow = z.infer<typeof SiteFileTreeRow>;

/**
 * 站点详情页扩展内容(按需抓详情时得到,服务端缓存 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(),
  /** 展示结构(读缓存时由上面的原文现算):信息块、正文段落、技术规格概要、文件目录树 */
  infoBlock: z.array(z.object({ key: z.string(), value: z.string() })),
  paragraphs: z.array(z.string()),
  media: SiteMediaSummary.nullable(),
  fileTree: z.array(SiteFileTreeRow),
});
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>;