feat(contracts): embed slots admin and public endpoints

Co-Authored-By: Claude Code <noreply@anthropic.com>

packages/contracts/src/generated/openapi.d.ts

@@ -760,6 +760,61 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/admin/embed-slots": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * 展示位列表
+         * @description 展示位（悬浮轮播组件挂载点）治理列表，游标分页（按 createdAt 与 ID
+         *     稳定倒序）；仅公司 admin 可用（P4b 权限简化：成员授权面 P5 按需补）。
+         */
+        get: operations["listEmbedSlots"];
+        put?: never;
+        /**
+         * 创建展示位
+         * @description 创建展示位（仅 admin）：服务端生成不可枚举 publicToken（嵌入代码
+         *     data-slot 引用）；初始 enabled=true、albumId=null（未绑定，公开端
+         *     404）、configVersion=1。settings 整体缺省时按各字段缺省值落库。
+         */
+        post: operations["createEmbedSlot"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/admin/embed-slots/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description 展示位 ID。 */
+                id: components["parameters"]["EmbedSlotId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * 更新展示位
+         * @description 展示位部分更新（仅 admin）：name/enabled/settings/albumId 任一管理面
+         *     变更均递增 configVersion 并触发 slot-state 同步事件（嵌入端配置版本
+         *     变化即整体重置渲染）。albumId 语义：非 null 为绑定/换绑目标相册
+         *     （相册须存在，不存在 404 ALBUM_NOT_FOUND），null 为解绑（公开端随即
+         *     404）；albumId 值本身变化（含换绑与解绑）即视为配置变更。settings
+         *     为整体替换（提供时字段齐全）。无删除端点：enabled=false 即下线。
+         */
+        patch: operations["updateEmbedSlot"];
+        trace?: never;
+    };
     "/public/albums/{token}": {
         parameters: {
             query?: never;
@@ -834,6 +889,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/public/embed-slots/{slotToken}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description 展示位公开令牌（不可枚举，持有即可访问；格式见 EmbedSlot.publicToken）。 */
+                slotToken: components["parameters"]["EmbedSlotToken"];
+            };
+            cookie?: never;
+        };
+        /**
+         * 展示位公开数据（嵌入组件数据源）
+         * @description 悬浮轮播组件的数据源（ov 域部署，匿名只读；嵌入 iframe 轮询调用）：
+         *     返回展示位绑定相册的近期已发布照片（≤20，按 publishedAt 与 ID 稳定
+         *     倒序，小尺寸缩略图省流量）与相册摘要。lang 语义：auto（缺省）或取值
+         *     不支持时按相册 defaultLocale 回退（不报 400，与公开相册一致）。
+         *
+         *     - 防探测：slotToken 不存在、展示位停用（enabled=false）或未绑定相册
+         *       一律 404 NOT_FOUND（同码同文案，不区分原因，避免枚举探测）。
+         *     - 条件请求（A23 省流量）：200/304 响应携带强 ETag，取值为四元组
+         *       `"{configVersion}-{photoCount}-{maxPublishedAtMs}-{maxPhotoId}"`
+         *       （含照片条数与最新发布时间——新照片发布必变，避免仅比对实体版本
+         *       时新照片小版本导致 304 陈旧）；请求携带 If-None-Match 且匹配时
+         *       返回 304（无响应体，仍携带 ETag）。
+         */
+        get: operations["getPublicEmbedSlot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/public/albums/{token}/photos/{photoId}/likes": {
         parameters: {
             query?: never;
@@ -1945,6 +2034,93 @@ export interface components {
             /** @description 告警列表（createdAt 倒序，含已解除）。 */
             alerts: components["schemas"]["UsageAlert"][];
         };
+        /**
+         * @description 展示位内容语言（设置与公开查询共用）：auto=按相册 defaultLocale，
+         *     其余为指定语言（取值不支持时服务端静默回退相册 defaultLocale）。
+         * @enum {string}
+         */
+        EmbedSlotLang: "auto" | "zh-CN" | "en";
+        /**
+         * @description 展示位展示设置。整体提交语义：创建时 settings 可整体缺省（各字段按
+         *     下列缺省值落库），提供时字段齐全；更新为整体替换（未单独提交
+         *     settings 则保持不变）。响应中字段恒齐全。
+         */
+        EmbedSlotSettings: {
+            /**
+             * @description 悬浮位置（宿主页面左/右侧）。
+             * @default right
+             * @enum {string}
+             */
+            position: "left" | "right";
+            /**
+             * @description 组件尺寸（sm=窄屏降级档，宿主 viewport<480px 时自动降为 sm）。
+             * @default md
+             * @enum {string}
+             */
+            size: "sm" | "md";
+            /**
+             * @description 轮播切换间隔毫秒。
+             * @default 5000
+             */
+            intervalMs: number;
+            lang: components["schemas"]["EmbedSlotLang"];
+            /**
+             * @description 初始是否收起（收起后仅展示小把手，点击展开）。
+             * @default false
+             */
+            collapsedDefault: boolean;
+        };
+        /**
+         * @description 展示位条目（管理视角）。albumId/albumTitle 为当前绑定相册（null=未
+         *     绑定，公开端 404）；albumTitle 按相册 defaultLocale 解析（管理列表
+         *     展示用）。任一管理面变更递增 configVersion。
+         */
+        EmbedSlot: {
+            /** @description 展示位 ID。 */
+            readonly id: string;
+            /** @description 展示位公开令牌（嵌入代码 data-slot 引用，不可枚举）。 */
+            readonly publicToken: string;
+            /** @description 展示位名称（管理标识）。 */
+            name: string;
+            /** @description 是否启用；false 即下线（公开端 404，等同删除语义）。 */
+            enabled: boolean;
+            /** @description 绑定相册 ID；未绑定为 null。 */
+            readonly albumId: string | null;
+            /** @description 绑定相册标题（按相册 defaultLocale 解析）；未绑定为 null。 */
+            readonly albumTitle: string | null;
+            /** @description 配置版本（任一管理面变更递增；嵌入端据此整体重置渲染，亦为公开端 ETag 组成部分）。 */
+            readonly configVersion: number;
+            settings: components["schemas"]["EmbedSlotSettings"];
+            /**
+             * Format: date-time
+             * @description 最近更新时间。
+             */
+            readonly updatedAt: string;
+        };
+        EmbedSlotList: components["schemas"]["CursorPageMeta"] & {
+            /** @description 展示位条目（按 createdAt 与 ID 稳定倒序）。 */
+            items: components["schemas"]["EmbedSlot"][];
+        };
+        /** @description 创建展示位请求；settings 可整体缺省（各字段按缺省值落库），提供时字段齐全。 */
+        EmbedSlotCreateRequest: {
+            /** @description 展示位名称。 */
+            name: string;
+            settings?: components["schemas"]["EmbedSlotSettings"];
+        };
+        /**
+         * @description 展示位部分更新请求（仅提交的字段被修改，空请求体 400）。settings 为
+         *     整体替换（提供时字段齐全）；albumId：非 null 绑定/换绑目标相册（相册
+         *     须存在），null 解绑（公开端随即 404）——albumId 值变化即 configVersion+1。
+         */
+        EmbedSlotUpdateRequest: {
+            /** @description 展示位名称。 */
+            name?: string;
+            /** @description 启停；false 即下线（软停用，无删除端点）。 */
+            enabled?: boolean;
+            settings?: components["schemas"]["EmbedSlotSettings"];
+            /** @description 绑定相册 ID；null 解绑。 */
+            albumId?: string | null;
+        };
         /** @description 私有对象的短期签名 URL；不得写入持久分享链接，过期后经原入口刷新。 */
         SignedUrl: {
             /** @description 签名访问 URL。 */
@@ -2042,6 +2218,43 @@ export interface components {
         PublicPhotoList: components["schemas"]["CursorPageMeta"] & {
             items: components["schemas"]["PublicPhoto"][];
         };
+        /** @description 展示位绑定相册摘要（title 已按 lang→相册 defaultLocale 回退解析）。 */
+        PublicEmbedAlbum: {
+            /** @description 相册公开令牌（点击照片跳转 viewer 相册页用）。 */
+            readonly publicToken: string;
+            /** @description 相册标题（实际返回语言）。 */
+            readonly title: string;
+            defaultLocale: components["schemas"]["Locale"];
+        };
+        /**
+         * @description 展示位照片条目（小尺寸缩略图省流量，与公开列表的 browse 大图区分；
+         *     签名 URL 为短期凭证，过期后经本端点刷新）。
+         */
+        PublicEmbedPhoto: {
+            /** @description 照片 ID（跳转 viewer 单图定位用）。 */
+            readonly photoId: string;
+            thumb: components["schemas"]["SignedUrl"];
+            /** @description 缩略图宽度（像素）；用于占位，减少加载跳动。 */
+            readonly width: number;
+            /** @description 缩略图高度（像素）。 */
+            readonly height: number;
+        };
+        /**
+         * @description 展示位公开数据（嵌入组件数据源；ov 只读副本）。photos 为近期已发布
+         *     照片，按 publishedAt 与 ID 稳定倒序，上限 20（空数组=相册暂无已发布
+         *     照片，嵌入端展示空态卡）。album 当前恒非 null（未绑定/停用的展示位
+         *     公开端一律 404 防探测）；null 为契约前瞻保留，嵌入端按空态处理。
+         */
+        PublicEmbedSlot: {
+            /** @description 展示位公开令牌（回显请求路径）。 */
+            readonly slotToken: string;
+            /** @description 配置版本（嵌入端变更检测：版本变化即整体重置渲染）。 */
+            readonly configVersion: number;
+            /** @description 绑定相册摘要；未绑定为 null（当前部署不会出现，见 schema 描述）。 */
+            album: components["schemas"]["PublicEmbedAlbum"] | null;
+            /** @description 近期照片（publishedAt 与 ID 稳定倒序，小尺寸缩略图）。 */
+            photos: components["schemas"]["PublicEmbedPhoto"][];
+        };
         /**
          * @description 下载版本（P4a A18）：browse=当前生效浏览图（水印版）；
          *     original=原图（需 originalDownloadEnabled 更高级开关）。
@@ -2332,6 +2545,10 @@ export interface components {
         PhotoId: string;
         /** @description 相册公开令牌（不可枚举，持有即可访问）。 */
         AlbumPublicToken: string;
+        /** @description 展示位 ID。 */
+        EmbedSlotId: string;
+        /** @description 展示位公开令牌（不可枚举，持有即可访问；格式见 EmbedSlot.publicToken）。 */
+        EmbedSlotToken: string;
         /** @description 分页游标（上一页响应的 nextCursor）。 */
         CursorQuery: string;
         /** @description 请求语言；缺省或取值不支持时按相册 defaultLocale 回退（不报 400，响应 resolvedLocale 指示实际返回语言）。 */
@@ -4132,6 +4349,151 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    listEmbedSlots: {
+        parameters: {
+            query?: {
+                /** @description 分页游标（上一页响应的 nextCursor）。 */
+                cursor?: components["parameters"]["CursorQuery"];
+                /** @description 每页条数。 */
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description 展示位列表页。 */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["EmbedSlotList"];
+                };
+            };
+            /** @description 查询参数校验失败（VALIDATION_FAILED；cursor/limit 非法）。 */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description 仅 admin 可管理展示位（AUTH_FORBIDDEN）。 */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+        };
+    };
+    createEmbedSlot: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["EmbedSlotCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description 创建后的展示位条目。 */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["EmbedSlot"];
+                };
+            };
+            /** @description 请求体校验失败（VALIDATION_FAILED；name 长度非法、settings 字段越界或取值非法）。 */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description 仅 admin 可管理展示位（AUTH_FORBIDDEN）。 */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+        };
+    };
+    updateEmbedSlot: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description 展示位 ID。 */
+                id: components["parameters"]["EmbedSlotId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["EmbedSlotUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description 更新后的展示位条目。 */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["EmbedSlot"];
+                };
+            };
+            /** @description 参数校验失败（VALIDATION_FAILED；name 长度非法、settings 字段越界或取值非法、空请求体）。 */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description 仅 admin 可管理展示位（AUTH_FORBIDDEN）。 */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description 展示位不存在（NOT_FOUND），或绑定目标相册不存在（ALBUM_NOT_FOUND）。 */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+        };
+    };
     getPublicAlbum: {
         parameters: {
             query?: {
@@ -4273,6 +4635,65 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    getPublicEmbedSlot: {
+        parameters: {
+            query?: {
+                /** @description 内容语言；auto（缺省）按相册 defaultLocale，取值不支持时静默回退（不报 400）。 */
+                lang?: components["schemas"]["EmbedSlotLang"];
+            };
+            header?: {
+                /** @description 条件请求：先前响应返回的 ETag 值；匹配则返回 304。 */
+                "If-None-Match"?: string;
+            };
+            path: {
+                /** @description 展示位公开令牌（不可枚举，持有即可访问；格式见 EmbedSlot.publicToken）。 */
+                slotToken: components["parameters"]["EmbedSlotToken"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description 展示位公开数据。 */
+            200: {
+                headers: {
+                    /** @description 强校验器（组成与失效语义见端点 description）。 */
+                    ETag?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicEmbedSlot"];
+                };
+            };
+            /** @description 内容未变（If-None-Match 匹配）；无响应体。 */
+            304: {
+                headers: {
+                    /** @description 当前 ETag（与匹配值一致）。 */
+                    ETag?: string;
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description 查询参数校验失败（VALIDATION_FAILED；lang 取值不支持时不报错，按相册 defaultLocale 回退）。 */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description 展示位不存在、已停用或未绑定相册（NOT_FOUND；不区分以避免枚举）。 */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            500: components["responses"]["InternalError"];
+        };
+    };
     likePhotoBatch: {
         parameters: {
             query?: never;