feat(server): W4-A integration endpoints and contract gaps

- POST /acquisition-plans: manual submit via download.plan -> download.submit (same authorization/audit/idempotency path as the agent), slotId or entityId - read-only /media-assets, /asset-locations, /asset-unit-coverage, /path-bindings, /reconcile-runs, /server-mappings, /artifacts, GET /title-aliases/{id}; unimplemented write endpoints removed from api.ts; registry test now checks both directions - candidate evaluation upsert per (slot, source_release) + migration 0022 dedupe/unique index - organization records expose downloadTaskId (+ list filter); inventory adds subscribed/candidateReasons; feed sources expose derived possibleGap - GET /events?after=&limit= JSON replay page for API key callers (same sse_event table) - preference tag revision history from audit_event; subscriptions/identities/aliases lists carry mediaEntityTitle; subscription q/mediaKind search; slot subscriptionId filter + currentAsset summary; policy preview samples carry title/reasons - DecisionSummary, IdentityRevisionList, ReleaseIdentityResult, PolicyPreviewSummary exported from contracts Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-09-27 21:10:02 +08:00
1 parent ea4c384664
commit d3ab54f2bd
@@ -5,6 +5,7 @@ import * as auth from "./auth.ts";
 import { CapabilityDescriptor, KnownCapabilityId } from "./capability.ts";
 import { type ApiScope, CursorQuery, cursorPage, HealthStatus, Id, IdParam } from "./common.ts";
 import * as content from "./content.ts";
+import * as events from "./events.ts";
 import * as execution from "./execution.ts";
 import * as identity from "./identity.ts";
 import * as instances from "./instances.ts";
@@ -111,10 +112,16 @@ const instanceTest = (path: string, summary: string) =>
  ep({ method: "post", path, scope: "admin", summary, params: IdParam, response: instances.InstanceTestResult });

 /** 入队后台任务的受理结果(taskId = 引擎 run id) */
-const Accepted = z.object({ taskId: Id });
+export const TaskAccepted = z.object({ taskId: Id });
+export type TaskAccepted = z.infer<typeof TaskAccepted>;

-/** 人工指定来源资源身份的结果 */
-const ReleaseIdentityResult = z.object({ mediaEntityId: Id, contentUnitIds: z.array(Id) });
+/** 人工指定来源资源身份的结果(待识别池 assign / source-releases identity) */
+export const ReleaseIdentityResult = z.object({ mediaEntityId: Id, contentUnitIds: z.array(Id) });
+export type ReleaseIdentityResult = z.infer<typeof ReleaseIdentityResult>;
+
+/** 身份修订历史 */
+export const IdentityRevisionList = z.object({ items: z.array(identity.IdentityRevision) });
+export type IdentityRevisionList = z.infer<typeof IdentityRevisionList>;

 /** 字段覆盖/取消覆盖的结果 */
 const FieldOverrideResult = z.object({
@@ -128,7 +135,7 @@ const FieldParam = z.object({ id: Id, field: content.EntityMetadataField });
 const EngineRunIdParam = z.object({ id: z.string().min(1).max(200) });

 /** 待处理事项聚合分组 */
-const DecisionSummaryGroup = z.object({
+export const DecisionSummaryGroup = z.object({
  kind: agent.DecisionKind,
  mediaEntityId: Id.nullable(),
  mediaEntityTitle: z.string().nullable(),
@@ -136,6 +143,9 @@ const DecisionSummaryGroup = z.object({
  maxSeverity: z.enum(["info", "warning", "critical"]),
  latestAt: z.string(),
 });
+export type DecisionSummaryGroup = z.infer<typeof DecisionSummaryGroup>;
+export const DecisionSummary = z.object({ total: z.number().int(), groups: z.array(DecisionSummaryGroup) });
+export type DecisionSummary = z.infer<typeof DecisionSummary>;

 export const Api = {
  // ── 内容 / 身份 ──
@@ -192,7 +202,7 @@ export const Api = {
      scope: "organize.execute",
      summary: "刷新元数据(字段级;用户锁优先,不动路径)",
      params: IdParam,
-      response: Accepted,
+      response: TaskAccepted,
    }),
    setField: ep({
      method: "put",
@@ -217,7 +227,6 @@ export const Api = {
    "内容单元",
    {
      row: content.ContentUnit,
-      create: content.ContentUnitCreate,
      update: content.ContentUnitUpdate,
      filters: { mediaEntityId: Id.optional(), seasonNumber: z.coerce.number().int().optional() },
    },
@@ -230,7 +239,6 @@ export const Api = {
      {
        row: content.TitleAlias,
        create: content.TitleAliasCreate,
-        update: content.TitleAliasUpdate,
        filters: { mediaEntityId: Id.optional(), q: z.string().max(200).optional() },
      },
      R,
@@ -259,17 +267,16 @@ export const Api = {
      scope: "read",
      summary: "身份修订历史",
      params: IdParam,
-      response: z.object({ items: z.array(identity.IdentityRevision) }),
+      response: IdentityRevisionList,
    }),
  },

-  // ── 文件 ──
+  // ── 文件(只读;写入只经整理/对账流程,不开放直接改) ──
  mediaAssets: crud(
    "/media-assets",
    "资产",
    {
      row: assets.MediaAsset,
-      update: assets.MediaAssetUpdate,
      filters: { mediaEntityId: Id.optional(), status: assets.AssetStatus.optional() },
    },
    R,
@@ -279,8 +286,6 @@ export const Api = {
    "资产覆盖",
    {
      row: assets.AssetUnitCoverage,
-      create: assets.AssetUnitCoverageCreate,
-      update: assets.AssetUnitCoverageUpdate,
      filters: { mediaAssetId: Id.optional(), contentUnitId: Id.optional() },
    },
    R,
@@ -290,7 +295,6 @@ export const Api = {
    "资产位置",
    {
      row: assets.AssetLocation,
-      update: assets.AssetLocationUpdate,
      filters: { mediaAssetId: Id.optional(), status: assets.LocationStatus.optional() },
    },
    R,
@@ -300,8 +304,6 @@ export const Api = {
    "路径绑定",
    {
      row: assets.PathBinding,
-      create: assets.PathBindingCreate,
-      update: assets.PathBindingUpdate,
      filters: { mediaEntityId: Id.optional(), status: assets.BindingStatus.optional() },
    },
    R,
@@ -405,7 +407,7 @@ export const Api = {
      summary: "立即同步站点快照(受站点限流)",
      params: IdParam,
      body: z.object({ maxPages: z.number().int().min(1).max(20).optional() }),
-      response: Accepted,
+      response: TaskAccepted,
    }),
    snapshots: ep({
      method: "get",
@@ -544,7 +546,7 @@ export const Api = {
      scope: "organize.execute",
      summary: "解除来源资源的人工锁并重新识别",
      params: IdParam,
-      response: Accepted,
+      response: TaskAccepted,
    }),
  },
  observations: crud(
@@ -565,7 +567,13 @@ export const Api = {
      row: policy.Subscription,
      create: policy.SubscriptionCreate,
      update: policy.SubscriptionUpdate,
-      filters: { status: policy.SubscriptionStatus.optional(), mediaEntityId: Id.optional() },
+      filters: {
+        status: policy.SubscriptionStatus.optional(),
+        mediaEntityId: Id.optional(),
+        mediaKind: policy.SubscriptionMediaKind.optional(),
+        /** 作品标题 / 原名 / 别名 / 未建档检索词,模糊匹配 */
+        q: z.string().max(200).optional(),
+      },
    },
    R,
  ),
@@ -614,7 +622,11 @@ export const Api = {
      row: policy.AcquisitionSlot,
      create: policy.AcquisitionSlotCreate,
      update: policy.AcquisitionSlotUpdate,
-      filters: { mediaEntityId: Id.optional(), status: policy.SlotStatus.optional() },
+      filters: {
+        mediaEntityId: Id.optional(),
+        status: policy.SlotStatus.optional(),
+        subscriptionId: Id.optional(),
+      },
    },
    R,
  ),
@@ -632,6 +644,14 @@ export const Api = {
    ),
    /** 删除 = 标记 deleted + 写抑制记录 */
    remove: del("/preference-tags/{id}", "删除偏好标签(留抑制记录)"),
+    revisions: ep({
+      method: "get",
+      path: "/preference-tags/{id}/revisions",
+      scope: "read",
+      summary: "偏好标签修订历史(新→旧;取自审计事件)",
+      params: IdParam,
+      response: policy.PreferenceTagRevisionList,
+    }),
  },
  preferenceSuppressions: crud(
    "/preference-suppressions",
@@ -686,15 +706,26 @@ export const Api = {
      response: z.object({ items: z.array(execution.AssetOperation) }),
    }),
  },
-  acquisitionPlans: crud(
-    "/acquisition-plans",
-    "下载计划",
-    {
-      row: execution.AcquisitionPlan,
-      filters: { slotId: Id.optional(), status: execution.PlanStatus.optional() },
-    },
-    R,
-  ),
+  acquisitionPlans: {
+    ...crud(
+      "/acquisition-plans",
+      "下载计划",
+      {
+        row: execution.AcquisitionPlan,
+        filters: { slotId: Id.optional(), status: execution.PlanStatus.optional() },
+      },
+      R,
+    ),
+    create: ep({
+      method: "post",
+      path: "/acquisition-plans",
+      scope: "organize.execute",
+      summary:
+        "手动提交下载:与自动收录同一流程(download.plan → download.submit,含硬条件/预算/缓存阈值/授权检查);未生成计划时返回拒绝原因",
+      body: execution.ManualAcquisitionRequest,
+      response: execution.ManualAcquisitionResult,
+    }),
+  },
  downloadTasks: {
    ...crud(
      "/download-tasks",
@@ -753,7 +784,7 @@ export const Api = {
      scope: "read",
      summary: "未关闭待处理事项按作品与问题类型聚合",
      query: z.object({ status: agent.DecisionStatus.optional() }),
-      response: z.object({ total: z.number().int(), groups: z.array(DecisionSummaryGroup) }),
+      response: DecisionSummary,
    }),
  },
  approvals: {
@@ -849,7 +880,6 @@ export const Api = {
    "校验运行",
    {
      row: ops.ReconcileRun,
-      create: ops.ReconcileRunCreate,
      filters: { kind: ops.ReconcileKind.optional(), status: ops.ReconcileStatus.optional() },
    },
    R,
@@ -859,7 +889,6 @@ export const Api = {
    "库存映射",
    {
      row: ops.ServerMapping,
-      update: ops.ServerMappingUpdate,
      filters: {
        mediaServerInstanceId: Id.optional(),
        mediaEntityId: Id.optional(),
@@ -1056,6 +1085,19 @@ export const Api = {
    }),
  },

+  // ── 事件 ──
+  events: {
+    list: ep({
+      method: "get",
+      path: "/events",
+      scope: "read",
+      summary:
+        "事件流:控制台用 SSE(text/event-stream,cookie 会话);API Key 调用者带 limit 取 JSON 补读页(after=上次 nextAfter)",
+      query: events.EventReplayQuery,
+      response: events.EventReplayPage,
+    }),
+  },
+
  // ── 系统 ──
  system: {
    health: ep({
@@ -1137,7 +1179,7 @@ export const Api = {
      scope: "organize.execute",
      summary: "立即重新识别",
      params: IdParam,
-      response: Accepted,
+      response: TaskAccepted,
    }),
  },

@@ -113,6 +113,8 @@ export const TitleAlias = EntityBase.extend({
  kind: AliasKind,
  source: AliasSource,
  locked: z.boolean(),
+  /** 派生字段(列表返回):作品标题 */
+  mediaEntityTitle: z.string().nullable().optional(),
 });
 export type TitleAlias = z.infer<typeof TitleAlias>;
 /** normalized 由服务端计算,不接受客户端传入 */
@@ -216,3 +216,25 @@ export function parseEventPayload<T extends EventType>(type: T, payload: unknown
  const r = schema.safeParse(payload);
  return r.success ? (r.data as EventPayload<T>) : null;
 }
+
+/**
+ * 事件补读(JSON,给 API Key 调用者轮询;EventSource 带不了 Bearer)。
+ * GET /events 带 limit 参数(或 Accept 只要 application/json)时返回这一页,否则是 SSE 流。
+ */
+export const EventReplayQuery = z.object({
+  after: z.coerce.number().int().nonnegative().default(0),
+  limit: z.coerce.number().int().min(1).max(1000).optional(),
+});
+export type EventReplayQuery = z.infer<typeof EventReplayQuery>;
+
+export const EventReplayPage = z.object({
+  items: z.array(EventEnvelope),
+  /** 下次请求的 after(本页最后一条 seq;空页时等于请求的 after) */
+  nextAfter: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+  /** 当前最大 seq */
+  latestSeq: z.number().int().nonnegative(),
+  /** true:after 早于保留窗口(已裁剪),应重新拉取业务快照后从 latestSeq 续读 */
+  gap: z.boolean(),
+});
+export type EventReplayPage = z.infer<typeof EventReplayPage>;
@@ -123,6 +123,31 @@ export const AcquisitionPlanCreate = AcquisitionPlan.omit({ ...SERVER_MANAGED, s
  statusReason: true,
 });
 export type AcquisitionPlanCreate = z.infer<typeof AcquisitionPlanCreate>;
+
+/**
+ * 手动提交下载(工作台下载入口,POST /acquisition-plans):与自动收录同一流程——
+ * download.plan(evaluateAcquisition,硬条件/预算/阈值/Slot 忙)→ download.submit(预留 + submitDownload 任务)。
+ * 目标 Slot:slotId 优先;否则 entityId(缺省取来源资源已识别的作品)下按创建顺序逐个尝试,第一个生成计划的 Slot 胜出。
+ */
+export const ManualAcquisitionRequest = z.object({
+  sourceReleaseId: Id,
+  slotId: Id.optional(),
+  entityId: Id.optional(),
+  note: z.string().max(2000).optional(),
+});
+export type ManualAcquisitionRequest = z.infer<typeof ManualAcquisitionRequest>;
+
+export const ManualAcquisitionResult = z.object({
+  /** true = 计划已预留并入队 submitDownload */
+  submitted: z.boolean(),
+  plan: AcquisitionPlan.nullable(),
+  slotId: Id.nullable(),
+  /** 业务任务 ID(submitDownload) */
+  taskId: Id.nullable(),
+  /** 未生成计划时逐个 Slot 的拒绝原因 */
+  rejected: z.array(z.object({ slotId: Id.nullable(), code: z.string(), message: z.string() })),
+});
+export type ManualAcquisitionResult = z.infer<typeof ManualAcquisitionResult>;
 export const AcquisitionPlanUpdate = AcquisitionPlan.pick({ status: true, taskId: true, statusReason: true }).partial();
 export type AcquisitionPlanUpdate = z.infer<typeof AcquisitionPlanUpdate>;

@@ -34,6 +34,8 @@ export const ExternalIdentity = EntityBase.extend({
  verifyStatus: IdentityVerifyStatus,
  /** 附属字段,如 TMDB episode_group */
  extra: JsonObject,
+  /** 派生字段(列表返回):作品标题(挂在内容单元上时取所属作品) */
+  mediaEntityTitle: z.string().nullable().optional(),
 });
 export type ExternalIdentity = z.infer<typeof ExternalIdentity>;

@@ -201,6 +201,8 @@ export const PublicOrganizationRecord = z.object({
  /** 稳定记录 ID */
  id: Id,
  taskId: Id.nullable(),
+  /** 来源下载任务(手动整理本地路径时为 null) */
+  downloadTaskId: Id.nullable(),
  /** 相关资产操作账本 ID */
  operationIds: z.array(Id),
  media: z
@@ -265,6 +267,7 @@ export const OrganizationListQuery = z.object({
  status: OrganizationStatus.optional(),
  trigger: OrganizationTrigger.optional(),
  mediaEntityId: Id.optional(),
+  downloadTaskId: Id.optional(),
  q: z.string().max(200).optional(),
 });
 export type OrganizationListQuery = z.infer<typeof OrganizationListQuery>;
@@ -384,6 +387,24 @@ export const InventoryEntry = z.object({
  downloading: z.array(
    z.object({ downloadTaskId: Id, name: z.string(), status: DownloadStatus, progress: z.number().min(0).max(1) }),
  ),
+  /** 有生效中的订阅(active) */
+  subscribed: z.boolean(),
+  /**
+   * 候选理由:该作品各 Slot 对来源资源的最近一次评估(每个 (Slot, 资源) 一条,新→旧,最多 50 条)。
+   * 工作台按 sourceReleaseId 取当前资源"为什么选 / 不选"。
+   */
+  candidateReasons: z.array(
+    z.object({
+      slotId: Id,
+      slotName: z.string(),
+      sourceReleaseId: Id,
+      decision: CandidateEvaluation.shape.decision,
+      /** 拒绝原因 message + 评估说明,已合并去重 */
+      reasons: z.array(z.string()),
+      planId: Id.nullable(),
+      evaluatedAt: Timestamp,
+    }),
+  ),
 });
 export type InventoryEntry = z.infer<typeof InventoryEntry>;

@@ -72,6 +72,8 @@ export const Subscription = EntityBase.extend({
  statusReason: z.string().nullable(),
  lastCheckedAt: Timestamp.nullable(),
  createdBy: z.string().nullable(),
+  /** 派生字段(列表返回):作品标题,未建档时为 null */
+  mediaEntityTitle: z.string().nullable().optional(),
 });
 export type Subscription = z.infer<typeof Subscription>;
 export const SubscriptionCreate = Subscription.pick({
@@ -145,6 +147,18 @@ export const AcquisitionSlot = EntityBase.extend({
  lastEvaluatedAt: Timestamp.nullable(),
  nextEvaluateAt: Timestamp.nullable(),
  revision: z.number().int().min(1),
+  /** 派生字段(列表返回):当前资产的交付特征摘要,无资产为 null */
+  currentAsset: z
+    .object({
+      id: Id,
+      resolution: z.string().nullable(),
+      sourceType: z.string().nullable(),
+      releaseGroup: z.string().nullable(),
+      sizeBytes: z.number().int().nullable(),
+      status: z.string(),
+    })
+    .nullable()
+    .optional(),
 });
 export type AcquisitionSlot = z.infer<typeof AcquisitionSlot>;
 export const AcquisitionSlotCreate = AcquisitionSlot.pick({
@@ -206,6 +220,55 @@ export const PreferenceTag = EntityBase.extend({
  policyRevisionId: Id.nullable(),
 });
 export type PreferenceTag = z.infer<typeof PreferenceTag>;
+
+/** 偏好标签修订历史:取自 audit_event(target_type=preference_tag),新→旧 */
+export const PreferenceTagRevision = z.object({
+  /** audit_event id */
+  id: Id,
+  at: Timestamp,
+  action: z.enum(["created", "updated", "deleted"]),
+  actorType: z.string(),
+  actorId: z.string().nullable(),
+  /** 该次写入后的 revision */
+  revision: z.number().int().min(1).nullable(),
+  /** 本次改动的字段(created/deleted 为空) */
+  changedFields: z.array(z.string()),
+  /** 写入后的快照 */
+  snapshot: z.object({
+    label: z.string(),
+    kind: z.string(),
+    status: z.string(),
+    scope: JsonObject,
+    rule: JsonObject,
+    description: z.string().nullable(),
+  }),
+});
+export type PreferenceTagRevision = z.infer<typeof PreferenceTagRevision>;
+export const PreferenceTagRevisionList = z.object({ items: z.array(PreferenceTagRevision) });
+export type PreferenceTagRevisionList = z.infer<typeof PreferenceTagRevisionList>;
+
+/** 策略预览结果(policy_revision.preview):最近 200 条来源资源按模板回放 */
+export const PolicyPreviewSummary = z.object({
+  evaluatedAt: z.string(),
+  sampleSize: z.number(),
+  templates: z.number(),
+  matched: z.number(),
+  excluded: z.number(),
+  samples: z.array(
+    z.object({
+      sourceReleaseId: z.string(),
+      /** 资源标题(W4 起提供) */
+      title: z.string().optional(),
+      sizeBytes: z.number().nullable().optional(),
+      template: z.string(),
+      decision: z.string(),
+      /** 拒绝/接受理由摘要 */
+      reasons: z.array(z.string()).optional(),
+    }),
+  ),
+  valid: z.boolean(),
+});
+export type PolicyPreviewSummary = z.infer<typeof PolicyPreviewSummary>;
 /** fingerprint 由服务端计算 */
 export const PreferenceTagCreate = PreferenceTag.pick({
  label: true,
@@ -105,6 +105,13 @@ export const FeedSource = EntityBase.extend({
  backoffUntil: Timestamp.nullable(),
  healthStatus: FeedHealth,
  lastError: JsonObject.nullable(),
+  /**
+   * 派生字段(非表列):最近一次抓取发现与上次窗口零重叠 → 疑似漏项,已排站点补漏。
+   * 下一次抓取窗口重新衔接后清空。站点未登记的 Feed 无法补漏(backfillQueued=false)。
+   */
+  possibleGap: z
+    .object({ detectedAt: Timestamp, previousFetchedAt: Timestamp.nullable(), backfillQueued: z.boolean() })
+    .nullable(),
 });
 export type FeedSource = z.infer<typeof FeedSource>;
 /** url 为只写明文(可能含 passkey),服务端加密存为 secret 并生成 urlDisplay */
@@ -38,7 +38,7 @@ type Obj = z.ZodObject;
 /** 表(PascalCase)→ Row schema 与允许的差异 */
 const ROWS: Record<string, { row: Obj; dbOnly?: string[]; apiOnly?: string[] }> = {
  AcquisitionPlan: { row: C.AcquisitionPlan },
-  AcquisitionSlot: { row: C.AcquisitionSlot },
+  AcquisitionSlot: { row: C.AcquisitionSlot, apiOnly: ["currentAsset"] },
  AgentRun: { row: C.AgentRun },
  AgentRunEvent: { row: C.AgentRunEventRow },
  AgentRunMessage: { row: C.AgentRunMessage },
@@ -55,8 +55,8 @@ const ROWS: Record<string, { row: Obj; dbOnly?: string[]; apiOnly?: string[] }>
  Decision: { row: C.Decision },
  DownloadTask: { row: C.DownloadTask },
  DownloaderInstance: { row: C.DownloaderInstance },
-  ExternalIdentity: { row: C.ExternalIdentity },
-  FeedSource: { row: C.FeedSource },
+  ExternalIdentity: { row: C.ExternalIdentity, apiOnly: ["mediaEntityTitle"] },
+  FeedSource: { row: C.FeedSource, apiOnly: ["possibleGap"] },
  IdentityRevision: { row: C.IdentityRevision },
  LibraryRoot: { row: C.LibraryRoot },
  MediaAsset: { row: C.MediaAsset },
@@ -78,9 +78,9 @@ const ROWS: Record<string, { row: Obj; dbOnly?: string[]; apiOnly?: string[] }>
  Site: { row: C.Site },
  SiteAccount: { row: C.SiteAccount },
  SourceRelease: { row: C.SourceRelease },
-  Subscription: { row: C.Subscription },
+  Subscription: { row: C.Subscription, apiOnly: ["mediaEntityTitle"] },
  Task: { row: C.Task },
-  TitleAlias: { row: C.TitleAlias },
+  TitleAlias: { row: C.TitleAlias, apiOnly: ["mediaEntityTitle"] },
  // W2-B 来源/身份/元数据(0018–0020)
  FieldOverride: { row: C.FieldOverride },
  IdentityCandidate: { row: C.IdentityCandidate },