docs(plan): on-demand site detail page parsing (HHClub details.php)

Co-Authored-By: Claude Fable 5.1 <[email protected]>

packages/contracts/src/organization.ts

@@ -428,11 +428,27 @@ export const InventoryResponse = z.object({ items: z.array(InventoryEntry) });
 export type InventoryResponse = z.infer<typeof InventoryResponse>;
 
 /** Emby 兼容库存:按实例分别给出 present / not_found / unknown(未知 ≠ 缺失) */
-export const MediaServerInventoryQuery = z.object({ mediaEntityId: Id });
+/**
+ * 按本地作品(用它已接受的外部身份)或按 TMDB 条目(还没建档的作品,SEARCH-2 搜索页/详情页)查 Emby。
+ * 两者给其一;都给时以 mediaEntityId 为准。
+ */
+export const MediaServerInventoryQuery = z
+  .object({
+    mediaEntityId: Id.optional(),
+    tmdbType: z.enum(["movie", "tv"]).optional(),
+    tmdbId: z
+      .string()
+      .regex(/^\d{1,12}$/)
+      .optional(),
+  })
+  .refine((q) => !!q.mediaEntityId || (!!q.tmdbType && !!q.tmdbId), {
+    message: "mediaEntityId 或 tmdbType + tmdbId 必须给一个",
+  });
 export type MediaServerInventoryQuery = z.infer<typeof MediaServerInventoryQuery>;
 
 export const MediaServerInventory = z.object({
-  mediaEntityId: Id,
+  /** 按 TMDB 条目查且本地没有建档时为 null */
+  mediaEntityId: Id.nullable(),
   instances: z.array(
     z.object({
       instanceId: Id,