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]>
This commit is contained in:
rootandClaude Opus 5.5 committed 2026-09-27 21:10:02 +08:00
1 parent ea4c384664
commit d3ab54f2bd
34 files changed
+1083 -123

No files matched your search

+74 -32
View File
@@ -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,
}),
},
+2
View File
@@ -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 由服务端计算,不接受客户端传入 */
+22
View File
@@ -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>;
+25
View File
@@ -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>;
+2
View File
@@ -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>;
+21
View File
@@ -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>;
+63
View File
@@ -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,
+7
View File
@@ -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 */
+5 -5
View File
@@ -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 },
@@ -0,0 +1,29 @@
import type { Kysely } from "kysely";
import { execDdl } from "../src/migration-helpers.ts";
// W4-A 候选评估记录去重:同一 (acquisition_slot, source_release) 只保留最新一条(artifact title=candidate_evaluation)。
// 先清掉历史重复(保留 updated_at 最新的一条),再加唯一表达式索引,写入端按该键 upsert。
// biome-ignore lint/suspicious/noExplicitAny: 迁移不依赖应用表类型
export async function up(db: Kysely<any>): Promise<void> {
await execDdl(
db,
`
delete from artifact a
using artifact b
where a.title = 'candidate_evaluation' and b.title = 'candidate_evaluation'
and a.subject_type = 'acquisition_slot' and b.subject_type = 'acquisition_slot'
and a.subject_id = b.subject_id
and (a.content->>'sourceReleaseId') = (b.content->>'sourceReleaseId')
and (a.updated_at, a.id) < (b.updated_at, b.id);
create unique index artifact_candidate_slot_release
on artifact (subject_id, (content->>'sourceReleaseId'))
where title = 'candidate_evaluation' and subject_type = 'acquisition_slot';
`,
);
}
// biome-ignore lint/suspicious/noExplicitAny: 同上
export async function down(db: Kysely<any>): Promise<void> {
await execDdl(db, "drop index if exists artifact_candidate_slot_release;");
}