xinyouhe/photo-live
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1dae00eaef1cffd9f5c6a4338dccde79173d6c6f
photo-live/packages/contracts/src/generated/openapi.d.ts
T

2213 lines
76 KiB
TypeScript
Raw Normal View History

feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
/**
* This file was auto-generated by openapi-typescript.
* Do not make direct changes to the file.
*/
export interface paths {
"/auth/password": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* 密码登录
* @description 校验账号密码，签发会话令牌。
*/
post: operations["loginWithPassword"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/auth/refresh": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* 会话滑动续期
* @description 携带有效 Bearer 令牌滑动续期，返回新的过期时间。
*/
post: operations["refreshSession"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/auth/logout": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* 退出登录
* @description 使当前 Bearer 令牌失效。
*/
post: operations["logout"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
"/albums": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* 相册列表
* @description 当前用户可见（参与）的相册列表；管理员可见全部。按创建时间倒序。
*/
get: operations["listAlbums"];
put?: never;
/**
* 创建相册
* @description 创建相册并写入多语言内容；创建者自动成为 owner 成员。
* 初始默认值：uploadEnabled/publicEnabled/downloadEnabled=true、
* originalDownloadEnabled=false、status=active、watermarkVersion=0。
*/
post: operations["createAlbum"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/albums/{albumId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
/**
* 相册详情
* @description 相册完整配置、多语言内容与分类列表。
*/
get: operations["getAlbum"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
/**
* 更新相册配置
* @description 部分更新：仅提交的字段被修改，各开关互相独立。
* translations 为全量替换（须包含 defaultLocale 对应条目）。
*/
patch: operations["updateAlbum"];
trace?: never;
};
"/albums/{albumId}/members": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
/**
* 相册成员列表
* @description 相册全部成员（含 owner）。
*/
get: operations["listAlbumMembers"];
put?: never;
/**
* 添加相册成员
* @description 将已开通的同事添加为协作者；仅创建者或管理员可操作。
*/
post: operations["addAlbumMember"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/albums/{albumId}/members/{userId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
/** @description 用户 ID。 */
userId: components["parameters"]["UserId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
/**
* 移除相册成员
* @description 移除协作者；仅创建者或管理员可操作。不能移除创建者（403）。
* 目标成员不存在时幂等返回 204。
*/
delete: operations["removeAlbumMember"];
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/albums/{albumId}/categories": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
get?: never;
put?: never;
/**
* 创建分类
* @description 在相册下创建分类；仅创建者或管理员可操作。
*/
post: operations["createCategory"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/categories/{categoryId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 分类 ID。 */
categoryId: components["parameters"]["CategoryId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
/**
* 删除分类
* @description 删除分类（分类下仍有照片时是否允许删除由服务端策略决定，400 拒绝）。
*/
delete: operations["deleteCategory"];
options?: never;
head?: never;
/**
* 更新分类
* @description 部分更新；translations 为全量替换。
*/
patch: operations["updateCategory"];
trace?: never;
};
"/uploads": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* 上传会话记录
* @description 当前用户的上传会话历史（新在前），用于任务队列恢复与状态展示。
*/
get: operations["listUploads"];
put?: never;
/**
* 初始化上传任务
* @description 幂等初始化：预创建上传会话与照片 ID，返回 staging 对象的临时直传凭证。
* 相同 clientTaskId 且参数一致时返回原会话，不重复创建照片；
* 参数不一致时返回 409（UPLOAD_SESSION_CONFLICT）。
*/
post: operations["initUpload"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/uploads/{uploadId}/renew": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 上传会话 ID。 */
uploadId: components["parameters"]["UploadId"];
};
cookie?: never;
};
get?: never;
put?: never;
/**
* 续签上传凭证
* @description 为仍处于 pending 状态的会话重新签发直传凭证（结构同初始化响应）。
*/
post: operations["renewUploadCredential"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/uploads/{uploadId}/complete": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 上传会话 ID。 */
uploadId: components["parameters"]["UploadId"];
};
cookie?: never;
};
get?: never;
put?: never;
/**
* 完成核验
* @description 核验 staging 对象（存在性、字节数与可用完整性信息）后进入处理流水线。
* 幂等：核验通过的会话重复调用返回相同结果。
*/
post: operations["completeUpload"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/photos/{photoId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 照片 ID。 */
photoId: components["parameters"]["PhotoId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
/**
* 软删除照片
* @description 标记 deleted（软删除），公开端点即刻不可见；物理删除走独立运维流程。
*/
delete: operations["deletePhoto"];
options?: never;
head?: never;
/**
* 调整照片可见性
* @description 在 hidden 与 published 间切换（隐藏/恢复发布）；按相册角色与上传人共同判定权限。
*/
patch: operations["updatePhoto"];
trace?: never;
};
"/public/albums/{token}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
};
cookie?: never;
};
/**
* 公开相册信息
* @description 观众页入口：按「请求 locale → defaultLocale」回退解析为单语言对象。
* publicToken 不可枚举，但持有链接者均可访问。
*/
get: operations["getPublicAlbum"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/public/albums/{token}/photos": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
};
cookie?: never;
};
/**
* 公开照片列表
* @description 仅返回公开相册中 published 的照片，按 publishedAt 与 ID 稳定倒序游标分页。
* 签名 URL 为短期凭证，过期后凭同一入口刷新。
*/
get: operations["listPublicPhotos"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/public/albums/{token}/photos/{photoId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
/** @description 照片 ID。 */
photoId: components["parameters"]["PhotoId"];
};
cookie?: never;
};
/**
* 公开单图
* @description 深度链接定位单图，同时作为签名 URL 过期后的刷新入口。
* 服务端校验相册与照片归属；隐藏/删除后的旧链接返回 404。
*/
get: operations["getPublicPhoto"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
}
export type webhooks = Record<string, never>;
export interface components {
schemas: {
Error: {
/**
* @description 稳定错误码，与 src/errors.ts 的 ErrorCodes 一一对应。
* @enum {string}
*/
readonly code: "AUTH_INVALID_CREDENTIALS" | "AUTH_TOKEN_EXPIRED" | "AUTH_FORBIDDEN" | "ALBUM_NOT_FOUND" | "ALBUM_NOT_PUBLIC" | "ALBUM_UPLOAD_DISABLED" | "MEMBER_CONFLICT" | "UPLOAD_SESSION_CONFLICT" | "UPLOAD_VERIFY_FAILED" | "PHOTO_NOT_FOUND" | "PHOTO_NOT_PUBLIC" | "VALIDATION_FAILED" | "INTERNAL_ERROR";
/** @description 服务器生成的可读消息（诊断用，不作为客户端展示文案依据）。 */
readonly message: string;
/** @description 请求追踪 ID。 */
readonly requestId: string;
};
/** @description 游标分页元信息；各列表响应以 allOf 内嵌本结构（条目 schema 在业务端点中定义）。 */
CursorPageMeta: {
/** @description 下一页游标；null 表示没有更多数据。 */
readonly nextCursor: string | null;
/** @description 是否还有下一页。 */
readonly hasMore: boolean;
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
/**
* @description P1a 支持的语言。
* @enum {string}
*/
Locale: "zh-CN" | "en";
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
LoginRequest: {
/** @description 账号（用户名或邮箱）。 */
account: string;
/** @description 密码。 */
password: string;
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
LoginResponse: {
/** @description 会话令牌（Bearer）。 */
readonly sessionToken: string;
/**
* Format: date-time
* @description 会话过期时间。
*/
readonly expiresAt: string;
};
RefreshResponse: {
/**
* Format: date-time
* @description 续期后的过期时间。
*/
readonly expiresAt: string;
};
/** @description 相册多语言条目（创建/更新与响应共用；未填的可选字段存储为 null）。 */
AlbumTranslation: {
locale: components["schemas"]["Locale"];
/** @description 相册标题。 */
title: string;
/** @description 相册描述。 */
description?: string | null;
/** @description 场地名称。 */
venue?: string | null;
/** @description 场地地址。 */
address?: string | null;
};
AlbumCreateRequest: {
/** @description 多语言内容；必须包含 defaultLocale 对应条目。 */
translations: components["schemas"]["AlbumTranslation"][];
defaultLocale: components["schemas"]["Locale"];
/**
* Format: date-time
* @description 活动开始时间（UTC 存储，展示按 timezone）。
*/
startAt: string;
/**
* Format: date-time
* @description 活动结束时间；null 或缺省表示未定。
*/
endAt?: string | null;
/**
* @description 活动 IANA 时区。
* @default Asia/Shanghai
* @example Asia/Shanghai
*/
timezone: string;
/**
* @description 允许下载浏览版本。
* @default true
*/
downloadEnabled: boolean;
/**
* @description 允许下载原图。
* @default false
*/
originalDownloadEnabled: boolean;
};
/** @description 部分更新：仅提交的字段被修改，各开关互相独立；endAt 传 null 清除。 */
AlbumUpdateRequest: {
/** @description 全量替换多语言内容；须包含 defaultLocale 对应条目。 */
translations?: components["schemas"]["AlbumTranslation"][];
defaultLocale?: components["schemas"]["Locale"];
/**
* Format: date-time
* @description 活动开始时间。
*/
startAt?: string;
/**
* Format: date-time
* @description 活动结束时间；null 清除。
*/
endAt?: string | null;
/** @description 活动 IANA 时区。 */
timezone?: string;
/** @description 是否允许新上传任务。 */
uploadEnabled?: boolean;
/** @description 是否公开可见。 */
publicEnabled?: boolean;
/** @description 允许下载浏览版本。 */
downloadEnabled?: boolean;
/** @description 允许下载原图。 */
originalDownloadEnabled?: boolean;
};
/** @description 相册列表条目（完整开关与多语言标题，管理列表无需二次请求详情）。 */
AlbumSummary: {
/** @description 相册 ID。 */
readonly id: string;
/** @description 公开访问令牌（不可枚举）。 */
readonly publicToken: string;
/** @description 创建者用户 ID。 */
readonly ownerId: string;
/**
* @description 相册状态。
* @default active
* @enum {string}
*/
readonly status: "active" | "archived";
defaultLocale: components["schemas"]["Locale"];
/** @description 活动 IANA 时区。 */
timezone: string;
/**
* Format: date-time
* @description 活动开始时间。
*/
startAt: string;
/**
* Format: date-time
* @description 活动结束时间；null 表示未定。
*/
endAt: string | null;
/** @description 是否允许新上传任务。 */
uploadEnabled: boolean;
/** @description 是否公开可见。 */
publicEnabled: boolean;
/** @description 允许下载浏览版本。 */
downloadEnabled: boolean;
/** @description 允许下载原图。 */
originalDownloadEnabled: boolean;
/**
* @description 当前水印配置版本。
* @default 0
*/
readonly watermarkVersion: number;
/** @description 各语言内容。 */
translations: components["schemas"]["AlbumTranslation"][];
/**
* Format: date-time
* @description 创建时间。
*/
readonly createdAt: string;
/**
* Format: date-time
* @description 最近更新时间。
*/
readonly updatedAt: string;
};
AlbumList: components["schemas"]["CursorPageMeta"] & {
items: components["schemas"]["AlbumSummary"][];
};
Album: components["schemas"]["AlbumSummary"] & {
/** @description 相册分类（按 sortOrder 升序）。 */
categories: components["schemas"]["Category"][];
};
MemberAddRequest: {
/** @description 被添加用户的 ID（须为已开通账号）。 */
userId: string;
/**
* @description 成员角色；P1a 仅协作者（owner 由创建流程产生）。
* @default collaborator
* @enum {string}
*/
role: "collaborator";
};
Member: {
/** @description 用户 ID。 */
readonly userId: string;
/** @description 登录账号。 */
readonly account: string;
/** @description 展示姓名（来自用户资料同步）。 */
readonly displayName: string;
/**
* @description 相册角色。
* @enum {string}
*/
readonly role: "owner" | "collaborator";
/**
* @description 成员状态；P1a 仅 active，预留扩展。
* @enum {string}
*/
readonly status: "active";
};
MemberList: components["schemas"]["CursorPageMeta"] & {
items: components["schemas"]["Member"][];
};
CategoryTranslation: {
locale: components["schemas"]["Locale"];
/** @description 分类名称。 */
name: string;
};
CategoryCreateRequest: {
/**
* @description 排序序号（升序）。
* @default 0
*/
sortOrder: number;
/** @description 分类多语言名称。 */
translations: components["schemas"]["CategoryTranslation"][];
};
/** @description 部分更新；translations 为全量替换。 */
CategoryUpdateRequest: {
/** @description 排序序号（升序）。 */
sortOrder?: number;
/** @description 全量替换多语言名称。 */
translations?: components["schemas"]["CategoryTranslation"][];
};
Category: {
/** @description 分类 ID。 */
readonly id: string;
/** @description 所属相册 ID。 */
readonly albumId: string;
/** @description 排序序号（升序）。 */
sortOrder: number;
/** @description 各语言名称。 */
translations: components["schemas"]["CategoryTranslation"][];
};
/**
* @description 上传会话状态（服务端视角；本地任务状态见技术实施方案 §5.5）。
* @enum {string}
*/
UploadSessionState: "pending" | "confirmed" | "cancelled" | "expired";
/**
* @description 照片服务端处理状态（技术实施方案 §5.5「服务端处理」链路）。
* @enum {string}
*/
PhotoProcessingState: "pending_upload" | "uploaded" | "processing" | "ready" | "processing_failed";
/**
* @description 照片对外可见性（技术实施方案 §5.5「对外可见性」；deleted 为软删除）。
* @enum {string}
*/
PhotoVisibility: "unpublished" | "published" | "hidden" | "deleted";
UploadInitRequest: {
/** @description 目标相册 ID。 */
albumId: string;
/** @description 目标分类 ID；缺省为相册默认分类。 */
categoryId?: string;
/** @description 客户端任务幂等键；同一任务的重试必须复用（会话与照片 ID 均复用）。 */
clientTaskId: string;
/** @description 原始文件名（仅元数据，不作对象唯一标识）。 */
filename: string;
/**
* Format: int64
* @description 申明文件字节数；完成核验时逐一比对。
*/
bytes: number;
/** @description MIME 类型；仅接受图片类型（JPEG/PNG/HEIC）。 */
contentType: string;
};
/** @description staging 对象的临时直传凭证；仅可写入指定 objectKey，不可访问 originals/variants。 */
UploadCredential: {
/**
* @description 凭证模式；P1a 仅预签名 URL，预留 STS 扩展。
* @default presigned
* @enum {string}
*/
readonly mode: "presigned";
/** @description 预签名上传 URL。 */
readonly url: string;
/**
* @description 上传 HTTP 方法。
* @enum {string}
*/
readonly method: "PUT";
/** @description 上传时必须携带的请求头（如 Content-Type）。 */
readonly headers: {
[key: string]: string;
};
/**
* Format: date-time
* @description 凭证过期时间；过期后续签（renew）再重试。
*/
readonly expiresAt: string;
};
UploadInitResponse: {
/** @description 上传会话 ID。 */
readonly uploadId: string;
/** @description 预创建的照片 ID（重试复用，不重复建照片）。 */
readonly photoId: string;
/** @description staging 对象键（photo-live/{env}/staging/{uploadId}/{photoId}.{ext}）。 */
readonly objectKey: string;
credential: components["schemas"]["UploadCredential"];
};
UploadCompleteResponse: {
/** @description 照片 ID。 */
readonly photoId: string;
processingState: components["schemas"]["PhotoProcessingState"];
};
/** @description 会话关联照片的当前状态（会话记录内嵌，客户端据此展示服务端进度）。 */
UploadSessionPhoto: {
/** @description 照片 ID。 */
readonly photoId: string;
processingState: components["schemas"]["PhotoProcessingState"];
visibility: components["schemas"]["PhotoVisibility"];
};
UploadSessionRecord: {
/** @description 上传会话 ID。 */
readonly uploadId: string;
/** @description 目标相册 ID。 */
readonly albumId: string;
/** @description 客户端任务幂等键。 */
readonly clientTaskId: string;
state: components["schemas"]["UploadSessionState"];
/**
* Format: int64
* @description 申明文件字节数。
*/
readonly expectedBytes: number;
/** @description 申明 MIME 类型。 */
readonly contentType: string;
/**
* Format: date-time
* @description 会话创建时间。
*/
readonly createdAt: string;
photo: components["schemas"]["UploadSessionPhoto"];
};
UploadSessionList: components["schemas"]["CursorPageMeta"] & {
items: components["schemas"]["UploadSessionRecord"][];
};
PhotoVisibilityUpdateRequest: {
/**
* @description 目标可见性；仅允许 hidden 与 published 间切换。
* @enum {string}
*/
visibility: "hidden" | "published";
};
/** @description 管理端照片记录（技术实施方案 §4 photos 表字段）。 */
PhotoRecord: {
/** @description 照片 ID。 */
readonly photoId: string;
/** @description 所属相册 ID。 */
readonly albumId: string;
/** @description 分类 ID；null 表示未分类。 */
readonly categoryId: string | null;
/** @description 上传人用户 ID。 */
readonly uploaderId: string;
visibility: components["schemas"]["PhotoVisibility"];
processingState: components["schemas"]["PhotoProcessingState"];
/**
* Format: int64
* @description 原图字节数。
*/
readonly bytes: number;
/** @description 原图宽度（像素）；处理前为 null。 */
readonly width: number | null;
/** @description 原图高度（像素）；处理前为 null。 */
readonly height: number | null;
/**
* Format: date-time
* @description 拍摄时间（EXIF）；无有效值时为 null。
*/
readonly shotAt: string | null;
/**
* Format: date-time
* @description 上传完成时间。
*/
readonly uploadedAt: string;
/**
* Format: date-time
* @description 发布时间；未发布为 null。
*/
readonly publishedAt: string | null;
/** @description 累计点赞数。 */
readonly likeCount: number;
};
/** @description 私有对象的短期签名 URL；不得写入持久分享链接，过期后经原入口刷新。 */
SignedUrl: {
/** @description 签名访问 URL。 */
readonly url: string;
/**
* Format: date-time
* @description URL 失效时间。
*/
readonly expiresAt: string;
};
/** @description 按请求 locale 回退解析后的单语言相册内容（locale 为实际返回语言）。 */
PublicAlbumTranslation: {
locale: components["schemas"]["Locale"];
/** @description 相册标题。 */
title: string;
/** @description 相册描述；无内容为 null。 */
description: string | null;
/** @description 场地名称；无内容为 null。 */
venue: string | null;
/** @description 场地地址；无内容为 null。 */
address: string | null;
};
/** @description 公开分类（名称已按请求 locale 回退解析）。 */
PublicCategory: {
/** @description 分类 ID。 */
readonly id: string;
/** @description 分类名称。 */
readonly name: string;
/** @description 排序序号（升序）。 */
readonly sortOrder: number;
};
/** @description 观众端相册信息（不泄露工作人员信息与内部存储键）。 */
PublicAlbum: {
/** @description 相册公开令牌。 */
readonly publicToken: string;
resolvedLocale: components["schemas"]["Locale"];
defaultLocale: components["schemas"]["Locale"];
/** @description 活动 IANA 时区（展示用，不随请求语言变化）。 */
readonly timezone: string;
/**
* Format: date-time
* @description 活动开始时间（UTC，客户端按时区格式化）。
*/
readonly startAt: string;
/**
* Format: date-time
* @description 活动结束时间；未定为 null。
*/
readonly endAt: string | null;
translations: components["schemas"]["PublicAlbumTranslation"];
/** @description 分类列表（按 sortOrder 升序）。 */
categories: components["schemas"]["PublicCategory"][];
/** @description 封面图签名 URL；未设置为 null。 */
banner: components["schemas"]["SignedUrl"] | null;
/** @description P1a 占位 null；浏览计数由后续 /visits 端点提供（技术实施方案 §7.1）。 */
readonly viewCount: null;
};
/** @description 公开照片条目（仅 published 照片；URL 为短期签名，需在过期前刷新）。 */
PublicPhoto: {
/** @description 照片 ID。 */
readonly photoId: string;
/** @description 浏览图宽度（像素）；用于列表占位，减少加载跳动。 */
readonly width?: number;
/** @description 浏览图高度（像素）。 */
readonly height?: number;
thumb: components["schemas"]["SignedUrl"];
browse: components["schemas"]["SignedUrl"];
/** @description 累计点赞数。 */
readonly likeCount: number;
/**
* Format: date-time
* @description 发布时间（列表排序依据）。
*/
readonly publishedAt: string;
};
PublicPhotoDetail: components["schemas"]["PublicPhoto"] & {
/** @description 所属分类 ID；未分类为 null。 */
readonly categoryId: string | null;
};
PublicPhotoList: components["schemas"]["CursorPageMeta"] & {
items: components["schemas"]["PublicPhoto"][];
};
};
responses: never;
parameters: {
/** @description 相册 ID。 */
AlbumId: string;
/** @description 用户 ID。 */
UserId: string;
/** @description 分类 ID。 */
CategoryId: string;
/** @description 上传会话 ID。 */
UploadId: string;
/** @description 照片 ID。 */
PhotoId: string;
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
AlbumPublicToken: string;
/** @description 分页游标（上一页响应的 nextCursor）。 */
CursorQuery: string;
/** @description 请求语言；缺省时按相册 defaultLocale 回退。 */
LocaleQuery: components["schemas"]["Locale"];
};
requestBodies: never;
headers: never;
pathItems: never;
}
export type $defs = Record<string, never>;
export interface operations {
loginWithPassword: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["LoginRequest"];
};
};
responses: {
/** @description 登录成功，返回会话令牌与过期时间。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["LoginResponse"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED，经全局校验管道）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 账号或密码错误（AUTH_INVALID_CREDENTIALS）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
refreshSession: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 续期成功。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["RefreshResponse"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED，经全局校验管道）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 令牌缺失、无效或已过期（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
logout: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 已退出，无响应体。 */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description 请求体不可解析（VALIDATION_FAILED，经全局校验管道）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 令牌缺失、无效或已过期（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
listAlbums: {
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"]["AlbumList"];
};
};
/** @description 查询参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
createAlbum: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["AlbumCreateRequest"];
};
};
responses: {
/** @description 相册已创建（新相册 categories 为空数组）。 */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Album"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
getAlbum: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 相册详情。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Album"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户非成员不可见（ALBUM_NOT_FOUND，避免枚举）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
updateAlbum: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["AlbumUpdateRequest"];
};
};
responses: {
/** @description 更新后的相册详情。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Album"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 仅创建者或管理员可修改（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
listAlbumMembers: {
parameters: {
query?: {
/** @description 分页游标（上一页响应的 nextCursor）。 */
cursor?: components["parameters"]["CursorQuery"];
/** @description 每页条数。 */
limit?: number;
};
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 成员列表页。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["MemberList"];
};
};
/** @description 查询参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
addAlbumMember: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["MemberAddRequest"];
};
};
responses: {
/** @description 成员已添加。 */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Member"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 仅创建者或管理员可管理成员（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 该用户已是相册成员（MEMBER_CONFLICT）。 */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
removeAlbumMember: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
/** @description 用户 ID。 */
userId: components["parameters"]["UserId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 已移除，无响应体。 */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无管理权限，或试图移除创建者（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
createCategory: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 相册 ID。 */
albumId: components["parameters"]["AlbumId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CategoryCreateRequest"];
};
};
responses: {
/** @description 分类已创建。 */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Category"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 仅创建者或管理员可管理分类（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在，或当前用户不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
deleteCategory: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 分类 ID。 */
categoryId: components["parameters"]["CategoryId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 已删除，无响应体。 */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无所属相册的管理权限（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 分类不存在，或所属相册不存在/不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
updateCategory: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 分类 ID。 */
categoryId: components["parameters"]["CategoryId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CategoryUpdateRequest"];
};
};
responses: {
/** @description 更新后的分类。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Category"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无所属相册的管理权限（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 分类不存在，或所属相册不存在/不可见（ALBUM_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
listUploads: {
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"]["UploadSessionList"];
};
};
/** @description 查询参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
initUpload: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadInitRequest"];
};
};
responses: {
/** @description 上传会话已创建（幂等重复调用返回原会话）。 */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadInitResponse"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED）：文件超过大小限额或类型不接受。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无该相册的上传权限（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/**
* @description 相册已关闭上传（ALBUM_UPLOAD_DISABLED），或同 clientTaskId 已存在
* 且参数不一致（UPLOAD_SESSION_CONFLICT）。
*/
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
renewUploadCredential: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 上传会话 ID。 */
uploadId: components["parameters"]["UploadId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 新凭证已签发（credential 为新值，其余字段回显原会话）。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadInitResponse"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无权操作该会话或会话不存在（AUTH_FORBIDDEN，不区分以避免枚举）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
/**
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
* @description 相册已关闭上传（ALBUM_UPLOAD_DISABLED），或会话状态不允许续签
* （已完成/取消/过期，UPLOAD_SESSION_CONFLICT）。
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
*/
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
};
completeUpload: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 上传会话 ID。 */
uploadId: components["parameters"]["UploadId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 核验通过，照片进入处理流水线。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadCompleteResponse"];
};
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
/**
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
* @description 核验失败（UPLOAD_VERIFY_FAILED）：对象缺失、字节数与申明不符
* 或完整性信息不可用。
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
*/
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无权操作该会话或会话不存在（AUTH_FORBIDDEN，不区分以避免枚举）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 会话状态不允许完成（已取消或已过期，UPLOAD_SESSION_CONFLICT）。 */
409: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
deletePhoto: {
parameters: {
query?: never;
header?: never;
path: {
/** @description 照片 ID。 */
photoId: components["parameters"]["PhotoId"];
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 已软删除，无响应体。 */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无该照片的管理权限（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 照片不存在（PHOTO_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
updatePhoto: {
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
parameters: {
query?: never;
header?: never;
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
path: {
/** @description 照片 ID。 */
photoId: components["parameters"]["PhotoId"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
cookie?: never;
};
requestBody: {
content: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
"application/json": components["schemas"]["PhotoVisibilityUpdateRequest"];
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
responses: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
/** @description 更新后的照片记录。 */
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
200: {
headers: {
[name: string]: unknown;
};
content: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
"application/json": components["schemas"]["PhotoRecord"];
};
};
/** @description 参数校验失败（VALIDATION_FAILED，visibility 取值非法）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 未认证（AUTH_TOKEN_EXPIRED）。 */
401: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 无该照片的管理权限（AUTH_FORBIDDEN）。 */
403: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 照片不存在（PHOTO_NOT_FOUND）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
};
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
getPublicAlbum: {
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
parameters: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
query?: {
/** @description 请求语言；缺省时按相册 defaultLocale 回退。 */
locale?: components["parameters"]["LocaleQuery"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
header?: never;
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
cookie?: never;
};
requestBody?: never;
responses: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
/** @description 相册公开信息。 */
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
200: {
headers: {
[name: string]: unknown;
};
content: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
"application/json": components["schemas"]["PublicAlbum"];
};
};
/** @description 查询参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在或未公开（ALBUM_NOT_PUBLIC，不区分以避免枚举）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
};
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
listPublicPhotos: {
parameters: {
query?: {
/** @description 分类 ID 过滤（来自 PublicAlbum.categories 的 id）。 */
category?: string;
/** @description 请求语言；缺省时按相册 defaultLocale 回退。 */
locale?: components["parameters"]["LocaleQuery"];
/** @description 分页游标（上一页响应的 nextCursor）。 */
cursor?: components["parameters"]["CursorQuery"];
/** @description 每页张数（技术实施方案 §7 建议 30-60）。 */
limit?: number;
};
header?: never;
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description 公开照片列表页。 */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PublicPhotoList"];
};
};
/** @description 查询参数校验失败（VALIDATION_FAILED）。 */
400: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 相册不存在或未公开（ALBUM_NOT_PUBLIC，不区分以避免枚举）。 */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
getPublicPhoto: {
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
parameters: {
query?: never;
header?: never;
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
path: {
/** @description 相册公开令牌（不可枚举，持有即可访问）。 */
token: components["parameters"]["AlbumPublicToken"];
/** @description 照片 ID。 */
photoId: components["parameters"]["PhotoId"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
cookie?: never;
};
requestBody?: never;
responses: {
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
/** @description 单图信息（含新签名的 thumb/browse URL）。 */
200: {
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
headers: {
[name: string]: unknown;
};
feat(contracts): p1a endpoint contracts
2026-09-17 17:31:11 +08:00
content: {
"application/json": components["schemas"]["PublicPhotoDetail"];
};
};
/**
* @description 相册不存在或未公开（ALBUM_NOT_PUBLIC），或照片不存在、未发布、
* 不属于该相册（PHOTO_NOT_PUBLIC）。
*/
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
/** @description 服务器内部错误（INTERNAL_ERROR）。 */
500: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
feat(contracts): openapi base, error codes, type generation
2026-09-17 17:04:12 +08:00
};
};
};
}
Reference in New Issue Copy Permalink