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]>

apps/server/src/modules/acquisition-organize/index.ts

@@ -3,6 +3,7 @@ import type { ServerContext, ServerModule } from "../types.ts";
 import { registerAoCapabilities } from "./capabilities.ts";
 import { registerAoTasks } from "./handlers.ts";
 import { type AoOptions, type AoPorts, createPorts } from "./ports.ts";
+import { registerAssetRoutes } from "./routes/assets.ts";
 import { registerDashboardRoutes } from "./routes/dashboard.ts";
 import { registerDownloadRoutes } from "./routes/downloads.ts";
 import { registerLibraryRoutes } from "./routes/library.ts";
@@ -67,6 +68,7 @@ export function createAcquisitionOrganizeModule(overrides: AoOverrides = {}): Se
       registerOrganizationRoutes(app, d);
       registerLibraryRoutes(app, d);
       registerDashboardRoutes(app, d);
+      registerAssetRoutes(app, d);
     },
     registerTasks(registry, ctx) {
       registerAoTasks(registry, lazy(ctx));

apps/server/src/modules/acquisition-organize/routes/assets.ts

@@ -0,0 +1,100 @@
+import { Api, type EndpointDef } from "@umt/contracts";
+import type { ModuleApp } from "../../types.ts";
+import type { AoDeps } from "../services/common.ts";
+import { notFound, toApi, toApiList } from "../util.ts";
+import { mount, paginate } from "./helpers.ts";
+
+// 资产 / 位置 / 覆盖 / 路径绑定 / 校验运行 / 库存映射:只读列表与详情。
+// 这些表只由整理、对账、媒体服务器同步流程写入,不开放直接修改(api.ts 已移除对应写端点)。
+
+const TAG = "assets";
+
+type Table =
+  | "media_asset"
+  | "asset_unit_coverage"
+  | "asset_location"
+  | "path_binding"
+  | "reconcile_run"
+  | "server_mapping";
+
+interface ReadOnly {
+  list: EndpointDef;
+  get: EndpointDef;
+  table: Table;
+  what: string;
+  /** query 字段 → 列名 */
+  filters: Record<string, string>;
+}
+
+const READ_ONLY: ReadOnly[] = [
+  {
+    ...Api.mediaAssets,
+    table: "media_asset",
+    what: "资产",
+    filters: { mediaEntityId: "media_entity_id", status: "status" },
+  },
+  {
+    ...Api.assetUnitCoverage,
+    table: "asset_unit_coverage",
+    what: "资产覆盖",
+    filters: { mediaAssetId: "media_asset_id", contentUnitId: "content_unit_id" },
+  },
+  {
+    ...Api.assetLocations,
+    table: "asset_location",
+    what: "资产位置",
+    filters: { mediaAssetId: "media_asset_id", status: "status" },
+  },
+  {
+    ...Api.pathBindings,
+    table: "path_binding",
+    what: "路径绑定",
+    filters: { mediaEntityId: "media_entity_id", status: "status" },
+  },
+  {
+    ...Api.reconcileRuns,
+    table: "reconcile_run",
+    what: "校验运行",
+    filters: { kind: "kind", status: "status" },
+  },
+  {
+    ...Api.serverMappings,
+    table: "server_mapping",
+    what: "库存映射",
+    filters: {
+      mediaServerInstanceId: "media_server_instance_id",
+      mediaEntityId: "media_entity_id",
+      matchStatus: "match_status",
+    },
+  },
+];
+
+export function registerAssetRoutes(app: ModuleApp, d: AoDeps) {
+  const db = () => d.ctx.db;
+  for (const r of READ_ONLY) {
+    mount(
+      app,
+      r.list,
+      async (_c, { query }) => {
+        // biome-ignore lint/suspicious/noExplicitAny: 表名在 READ_ONLY 里枚举,列名随表变化
+        let q = (db() as any).selectFrom(r.table).selectAll();
+        for (const [key, col] of Object.entries(r.filters)) {
+          const v = (query as Record<string, unknown>)[key];
+          if (v !== undefined) q = q.where(col, "=", v);
+        }
+        const p = await paginate(q, query);
+        return { items: toApiList(p.rows as object[]), nextCursor: p.nextCursor };
+      },
+      { tag: TAG },
+    );
+    mount(
+      app,
+      r.get,
+      async (_c, { params }) => {
+        const row = await db().selectFrom(r.table).selectAll().where("id", "=", params.id).executeTakeFirst();
+        return toApi((row as object | undefined) ?? notFound(r.what));
+      },
+      { tag: TAG },
+    );
+  }
+}

apps/server/src/modules/acquisition-organize/routes/library.ts

@@ -317,6 +317,42 @@ export function registerLibraryRoutes(app: ModuleApp, d: AoDeps) {
           .where("dt.status", "in", [...ACTIVE_DL])
           .execute(),
       ]);
+      const [subs, cands] = await Promise.all([
+        db()
+          .selectFrom("subscription")
+          .select("media_entity_id")
+          .where("media_entity_id", "in", ids)
+          .where("status", "=", "active")
+          .execute(),
+        db()
+          .selectFrom("artifact as a")
+          .innerJoin("acquisition_slot as s", (j) =>
+            j.on(sql<boolean>`a.subject_id = s.id and a.subject_type = 'acquisition_slot'`),
+          )
+          .select(["s.media_entity_id", "s.name as slot_name", "a.content"])
+          .where("a.title", "=", CANDIDATE_ARTIFACT_TITLE)
+          .where("s.media_entity_id", "in", ids)
+          .orderBy("a.updated_at", "desc")
+          .limit(50 * ids.length)
+          .execute(),
+      ]);
+      const subscribed = new Set(subs.map((r) => r.media_entity_id));
+      const reasonsOf = (entityId: string) =>
+        cands
+          .filter((c) => c.media_entity_id === entityId)
+          .slice(0, 50)
+          .map((c) => {
+            const ev = c.content as CandidateEvaluation;
+            return {
+              slotId: ev.slotId,
+              slotName: c.slot_name,
+              sourceReleaseId: ev.sourceReleaseId,
+              decision: ev.decision,
+              reasons: [...new Set([...(ev.rejected ?? []).map((r) => r.message), ...(ev.reasons ?? [])])],
+              planId: ev.planId ?? null,
+              evaluatedAt: ev.evaluatedAt,
+            };
+          });
       return {
         items: ids.map((entityId) => ({
           entityId,
@@ -340,6 +376,8 @@ export function registerLibraryRoutes(app: ModuleApp, d: AoDeps) {
           downloading: dts
             .filter((t) => t.entity_id === entityId)
             .map((t) => ({ downloadTaskId: t.id, name: t.name, status: t.status, progress: t.progress })),
+          subscribed: subscribed.has(entityId),
+          candidateReasons: reasonsOf(entityId),
         })),
       };
     },

apps/server/src/modules/acquisition-organize/routes/organization.ts

@@ -23,6 +23,7 @@ export function registerOrganizationRoutes(app: ModuleApp, d: AoDeps) {
       if (query.status) q = q.where("status", "=", query.status);
       if (query.trigger) q = q.where("trigger", "=", query.trigger);
       if (query.mediaEntityId) q = q.where("media_entity_id", "=", query.mediaEntityId);
+      if (query.downloadTaskId) q = q.where("download_task_id", "=", query.downloadTaskId);
       if (query.q) {
         const like = `%${String(query.q).replace(/[\\%_]/g, (m) => `\\${m}`)}%`;
         q = q.where((eb) =>

apps/server/src/modules/acquisition-organize/routes/rules.ts

@@ -10,6 +10,8 @@ import {
 import { type DB, sql, type Transaction } from "@umt/db";
 import { evaluateCandidate, parseRelease } from "@umt/domain";
 import { slotSpecFromRow } from "@umt/mapping";
+import type { Context } from "hono";
+import type { AuthEnv } from "../../../http/auth.ts";
 import { ApiException } from "../../../http/errors.ts";
 import type { ModuleApp } from "../../types.ts";
 import { createSlotsFromTemplates, publishedAcquisitionPolicies } from "../services/acquisition.ts";
@@ -34,6 +36,48 @@ async function kickEvaluate(d: AoDeps, input: { subscriptionId?: string; acquisi
   }
 }
 
+/** 偏好标签写入审计(修订历史端点据此回放):payload 带写入后快照与改动字段 */
+async function auditPref(
+  trx: Transaction<DB>,
+  c: Context<AuthEnv>,
+  action: "created" | "updated" | "deleted",
+  row: {
+    id: string;
+    label: string;
+    kind: string;
+    status: string;
+    scope: unknown;
+    rule: unknown;
+    description: string | null;
+    revision: number;
+  },
+  changedFields: string[],
+) {
+  const actor = c.get("actor");
+  await trx
+    .insertInto("audit_event")
+    .values({
+      actor_type: actor?.type === "api_key" ? "api_key" : "user",
+      actor_id: actor?.id ?? null,
+      action: `preference_tag.${action}`,
+      target_type: "preference_tag",
+      target_id: row.id,
+      payload: jsonb({
+        revision: row.revision,
+        changedFields,
+        snapshot: {
+          label: row.label,
+          kind: row.kind,
+          status: row.status,
+          scope: row.scope,
+          rule: row.rule,
+          description: row.description,
+        },
+      }),
+    })
+    .execute();
+}
+
 export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
   const db = () => d.ctx.db;
 
@@ -42,10 +86,32 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
     app,
     Api.subscriptions.list,
     async (_c, { query }) => {
-      let q = db().selectFrom("subscription").selectAll();
-      if (query.status) q = q.where("status", "=", query.status);
-      if (query.mediaEntityId) q = q.where("media_entity_id", "=", query.mediaEntityId);
-      const p = await paginate(q, query);
+      let q = db()
+        .selectFrom("subscription as s")
+        .leftJoin("media_entity as e", "e.id", "s.media_entity_id")
+        .selectAll("s")
+        .select("e.title as media_entity_title");
+      if (query.status) q = q.where("s.status", "=", query.status);
+      if (query.mediaEntityId) q = q.where("s.media_entity_id", "=", query.mediaEntityId);
+      if (query.mediaKind) q = q.where("s.media_kind", "=", query.mediaKind);
+      if (query.q) {
+        const like = `%${String(query.q).replace(/[\\%_]/g, (m) => `\\${m}`)}%`;
+        q = q.where((eb) =>
+          eb.or([
+            eb("e.title", "ilike", like),
+            eb("e.original_title", "ilike", like),
+            eb("s.title_query", "ilike", like),
+            eb.exists(
+              eb
+                .selectFrom("title_alias as t")
+                .select("t.id")
+                .whereRef("t.media_entity_id", "=", "s.media_entity_id")
+                .where("t.alias", "ilike", like),
+            ),
+          ]),
+        );
+      }
+      const p = await paginate(q, query, "s.");
       return { items: toApiList<Subscription>(p.rows), nextCursor: p.nextCursor };
     },
     { tag: TAG },
@@ -152,8 +218,34 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
       let q = db().selectFrom("acquisition_slot").selectAll();
       if (query.mediaEntityId) q = q.where("media_entity_id", "=", query.mediaEntityId);
       if (query.status) q = q.where("status", "=", query.status);
+      if (query.subscriptionId) q = q.where("subscription_id", "=", query.subscriptionId);
       const p = await paginate(q, query);
-      return { items: toApiList<AcquisitionSlot>(p.rows), nextCursor: p.nextCursor };
+      const assetIds = p.rows.map((r) => r.current_asset_id).filter((x): x is string => !!x);
+      const assets = assetIds.length
+        ? await db()
+            .selectFrom("media_asset")
+            .select(["id", "delivery", "size_bytes", "status"])
+            .where("id", "in", assetIds)
+            .execute()
+        : [];
+      const items = p.rows.map((r) => {
+        const a = assets.find((x) => x.id === r.current_asset_id);
+        const dv = (a?.delivery ?? {}) as { resolution?: string; sourceType?: string; releaseGroup?: string };
+        return {
+          ...toApi<AcquisitionSlot>(r),
+          currentAsset: a
+            ? {
+                id: a.id,
+                resolution: dv.resolution ?? null,
+                sourceType: dv.sourceType ?? null,
+                releaseGroup: dv.releaseGroup ?? null,
+                sizeBytes: a.size_bytes,
+                status: a.status,
+              }
+            : null,
+        };
+      });
+      return { items, nextCursor: p.nextCursor };
     },
     { tag: TAG },
   );
@@ -484,6 +576,7 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
             .returningAll()
             .executeTakeFirst();
           if (!ins) conflict("已存在同一语义的偏好标签");
+          await auditPref(trx, c, "created", ins!, []);
           return ins!;
         });
       return toApi<PreferenceTag>(r);
@@ -519,7 +612,10 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
           }
           if (fp !== cur!.fingerprint && cur!.status === "active")
             await suppress(trx, cur!.id, cur!.fingerprint, actorOf(c), "edited");
-          return trx
+          const changed = (["label", "kind", "scope", "rule", "description", "evidence", "status"] as const).filter(
+            (k) => body[k] !== undefined && JSON.stringify(body[k]) !== JSON.stringify(toApi<PreferenceTag>(cur!)[k]),
+          );
+          const next_ = await trx
             .updateTable("preference_tag")
             .set({
               ...(body.label !== undefined ? { label: body.label } : {}),
@@ -535,6 +631,8 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
             .where("id", "=", params.id)
             .returningAll()
             .executeTakeFirstOrThrow();
+          await auditPref(trx, c, "updated", next_, changed);
+          return next_;
         });
       return toApi<PreferenceTag>(r);
     },
@@ -559,6 +657,7 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
             .set({ status: "deleted", revision: cur!.revision + 1 })
             .where("id", "=", params.id)
             .execute();
+          await auditPref(trx, c, "deleted", { ...cur!, status: "deleted", revision: cur!.revision + 1 }, []);
           await suppress(trx, cur!.id, cur!.fingerprint, actorOf(c), "deleted");
         });
       return { ok: true as const };
@@ -566,6 +665,53 @@ export function registerRuleRoutes(app: ModuleApp, d: AoDeps) {
     { tag: TAG, status: 200 },
   );
 
+  mount(
+    app,
+    Api.preferenceTags.revisions,
+    async (_c, { params }) => {
+      const tag = await db().selectFrom("preference_tag").select("id").where("id", "=", params.id).executeTakeFirst();
+      if (!tag) notFound("偏好标签");
+      const rows = await db()
+        .selectFrom("audit_event")
+        .selectAll()
+        .where("target_type", "=", "preference_tag")
+        .where("target_id", "=", params.id)
+        .where("action", "like", "preference_tag.%")
+        .orderBy("at", "desc")
+        .orderBy("id", "desc")
+        .limit(200)
+        .execute();
+      return {
+        items: rows.map((r) => {
+          const p = (r.payload ?? {}) as {
+            revision?: number;
+            changedFields?: string[];
+            snapshot?: Record<string, unknown>;
+          };
+          const snap = p.snapshot ?? {};
+          return {
+            id: r.id,
+            at: r.at.toISOString(),
+            action: r.action.slice("preference_tag.".length),
+            actorType: r.actor_type,
+            actorId: r.actor_id,
+            revision: p.revision ?? null,
+            changedFields: p.changedFields ?? [],
+            snapshot: {
+              label: String(snap.label ?? ""),
+              kind: String(snap.kind ?? ""),
+              status: String(snap.status ?? ""),
+              scope: (snap.scope ?? {}) as Record<string, unknown>,
+              rule: (snap.rule ?? {}) as Record<string, unknown>,
+              description: (snap.description as string | null | undefined) ?? null,
+            },
+          };
+        }),
+      };
+    },
+    { tag: TAG },
+  );
+
   // ── 抑制记录 ──
   mount(
     app,
@@ -696,7 +842,14 @@ export async function previewPolicy(d: AoDeps, rules: unknown) {
     .execute();
   let matched = 0;
   let excluded = 0;
-  const samples: { sourceReleaseId: string; template: string; decision: string }[] = [];
+  const samples: {
+    sourceReleaseId: string;
+    title: string;
+    sizeBytes: number | null;
+    template: string;
+    decision: string;
+    reasons: string[];
+  }[] = [];
   for (const rel of rels) {
     const parsed = {
       ...parseRelease(rel.title, rel.subtitle ? { subtitle: rel.subtitle } : {}),
@@ -715,7 +868,24 @@ export async function previewPolicy(d: AoDeps, rules: unknown) {
       const ev = evaluateCandidate(spec, parsed, null);
       if (ev.decision === "accept") matched++;
       else excluded++;
-      if (samples.length < 20) samples.push({ sourceReleaseId: rel.id, template: t.name, decision: ev.decision });
+      if (samples.length < 20) {
+        const reasons =
+          ev.decision === "reject"
+            ? ev.violations.map((v) => `${v.field}:${v.code}`)
+            : ev.decision === "unknown_field"
+              ? ev.missing.map((m) => `missing:${m}`)
+              : "reasons" in ev
+                ? (ev.reasons ?? [])
+                : [];
+        samples.push({
+          sourceReleaseId: rel.id,
+          title: rel.title,
+          sizeBytes: rel.size_bytes,
+          template: t.name,
+          decision: ev.decision,
+          reasons,
+        });
+      }
     }
   }
   return {

apps/server/src/modules/acquisition-organize/services/common.ts

@@ -56,6 +56,10 @@ export async function upsertDecision(d: AoDeps, exec: Exec, input: DecisionInput
 
 export const CANDIDATE_ARTIFACT_TITLE = "candidate_evaluation";
 
+/**
+ * 同一 (Slot, 来源资源) 只保留最新一条评估(唯一索引 artifact_candidate_slot_release);
+ * 重复评估覆盖内容与 updated_at,不再追加新行。
+ */
 export async function recordCandidate(exec: Exec, ev: CandidateEvaluation): Promise<void> {
   const content = { ...ev };
   const contentHash = hashJson({
@@ -66,32 +70,12 @@ export async function recordCandidate(exec: Exec, ev: CandidateEvaluation): Prom
     reasons: ev.reasons,
     planId: ev.planId,
   });
-  const dup = await exec
-    .selectFrom("artifact")
-    .select("id")
-    .where("subject_type", "=", "acquisition_slot")
-    .where("subject_id", "=", ev.slotId)
-    .where("content_hash", "=", contentHash)
-    .executeTakeFirst();
-  if (dup) {
-    await exec
-      .updateTable("artifact")
-      .set({ content: jsonb(content), updated_at: new Date() })
-      .where("id", "=", dup.id)
-      .execute();
-    return;
-  }
-  await exec
-    .insertInto("artifact")
-    .values({
-      kind: "evidence",
-      subject_type: "acquisition_slot",
-      subject_id: ev.slotId,
-      title: CANDIDATE_ARTIFACT_TITLE,
-      content: jsonb(content),
-      content_hash: contentHash,
-    })
-    .execute();
+  await sql`
+    insert into artifact (kind, subject_type, subject_id, title, content, content_hash)
+    values ('evidence', 'acquisition_slot', ${ev.slotId}, ${CANDIDATE_ARTIFACT_TITLE}, ${jsonb(content)}::jsonb, ${contentHash})
+    on conflict (subject_id, (content->>'sourceReleaseId'))
+      where title = 'candidate_evaluation' and subject_type = 'acquisition_slot'
+    do update set content = excluded.content, content_hash = excluded.content_hash, updated_at = now()`.execute(exec);
 }
 
 // ── 业务任务行(task 表:时间线投影;引擎只管推进) ──

apps/server/src/modules/acquisition-organize/services/organize.ts

@@ -1222,6 +1222,7 @@ export async function loadRecordsPublic(exec: Exec, rows: OrganizationRecordRow[
     return {
       id: r.id,
       taskId: r.task_id,
+      downloadTaskId: r.download_task_id,
       operationIds: ops.filter((o) => o.organization_record_id === r.id).map((o) => o.id),
       media: e
         ? {