浅念
374 lines
15 KiB
TypeScript
374 lines
15 KiB
TypeScript
// services/api/src/photos/photos.service.ts —— 照片可见性生命周期（Task 24：
|
||
// updatePhoto 隐藏/恢复发布、deletePhoto 软删除）+ 管理照片列表（P1b Task 4：
|
||
// listAlbumPhotos，全状态可见 + uploader 脱敏内嵌 + (uploadedAt,id) 键集游标）。
|
||
// 契约权威：openapi.yaml tags [photos]。状态机（visibility，docs §5.5「对外可见性」）：
|
||
// unpublished ──(worker 发布事务, Task 21)──▶ published
|
||
// published ◀──────(manager)──────▶ hidden 双向，管理者可来回
|
||
// unpublished/published/hidden ──(manager)──▶ deleted 单向终态（软删除）
|
||
// · unpublished →published：发布是处理流水线（变体+outbox photo.published）
|
||
// 的产物，PATCH 不承担 —— 400（状态机拒绝，走完上传/处理链路自然发布）。
|
||
// · deleted 出态一律 400：P1a 判定 deleted 为员工侧终态，恢复/重发布仅
|
||
// P4a 管理员物理清除流程的相邻能力（重新上传即新照片新 ID）。
|
||
// · 恢复发布（hidden→published）P1a 默认仅相册创建者/公司管理员：隐藏是
|
||
// 单人可做的轻操作，重新进入公开面是运营决策——从严默认，需求侧（§2
|
||
// 「管理自己照片」边界）最终裁决前不放宽。已登记为待定需求决策。
|
||
// 权限（§2 矩阵，A02 逐次校验）：canManagePhoto = admin 全部 / 相册 owner 全部 /
|
||
// 协作者仅自己上传。404/403 映射：照片不存在或相册不可见（非成员）→ 404
|
||
// PHOTO_NOT_FOUND（防枚举）；可见但无管理权（协作者对他人照片）→ 403。
|
||
// 每次真实状态迁移：条件更新（WHERE visibility=期望前态，并发下恰一人胜出）
|
||
// + entityVersion 自增 + 事务内 outbox 事件（P2 副本按 entityVersion 单调消费）
|
||
// + audit。幂等前态（同值 PATCH / 重复 DELETE）直接回显当前记录，不产生
|
||
// 第二次事件/审计（entityVersion 不动——副本侧按版本去重的不变量）。
|
||
import { Injectable } from '@nestjs/common';
|
||
import type { components } from '@photo/contracts';
|
||
import type { Prisma } from '@photo/db-cn';
|
||
import type { AuthUser } from '../auth/session.guard';
|
||
import { PermissionsService } from '../albums/permissions.service';
|
||
import {
|
||
albumForbidden,
|
||
albumNotFound,
|
||
validationFailed,
|
||
} from '../albums/support';
|
||
import { PrismaService } from '../prisma/prisma.service';
|
||
import {
|
||
decodeKeysetCursor,
|
||
encodeKeysetCursor,
|
||
keysetWhereDesc,
|
||
} from '../shared/cursor';
|
||
import { buildPhotoPublishedPayload } from '../sync/payloads';
|
||
import type { PhotoVisibility, PhotoVisibilityTarget } from './dto';
|
||
import {
|
||
photoForbidden,
|
||
photoNotFound,
|
||
visibilityTransitionFailed,
|
||
} from './support';
|
||
|
||
export type PhotoRecord = components['schemas']['PhotoRecord'];
|
||
export type AdminPhotoListResponse = components['schemas']['AdminPhotoList'];
|
||
|
||
type PhotoRow = Prisma.photosGetPayload<Prisma.photosDefaultArgs>;
|
||
|
||
function toPhotoRecord(row: PhotoRow): PhotoRecord {
|
||
return {
|
||
photoId: row.id,
|
||
albumId: row.albumId,
|
||
categoryId: row.categoryId,
|
||
uploaderId: row.uploaderId,
|
||
visibility: row.visibility as PhotoRecord['visibility'],
|
||
processingState: row.processingState as PhotoRecord['processingState'],
|
||
bytes: row.bytes,
|
||
width: row.width,
|
||
height: row.height,
|
||
shotAt: row.shotAt === null ? null : row.shotAt.toISOString(),
|
||
// 契约 uploadedAt 必返 string；真实链路（complete）恒写入。?? 兜底仅收窄
|
||
// 类型（直种的脏行），不构成可观察行为。
|
||
uploadedAt: (row.uploadedAt ?? new Date(0)).toISOString(),
|
||
publishedAt: row.publishedAt === null ? null : row.publishedAt.toISOString(),
|
||
likeCount: row.likeCount,
|
||
};
|
||
}
|
||
|
||
@Injectable()
|
||
export class PhotosService {
|
||
constructor(
|
||
private readonly prisma: PrismaService,
|
||
private readonly permissions: PermissionsService,
|
||
) {}
|
||
|
||
/**
|
||
* 管理照片列表（P1b Task 4，契约 listAlbumPhotos）：区别于公开列表——全部
|
||
* 可见性状态可见（unpublished/published/hidden/deleted），条目内嵌 uploader
|
||
* 脱敏信息（account/displayName，无凭据字段）。权限顺序防枚举（同 members）：
|
||
* canViewAlbum=false → 404 ALBUM_NOT_FOUND；可见但 canManageAlbum=false
|
||
* （协作者）→ 403 AUTH_FORBIDDEN；admin 对幽灵 id 权限恒真，空相册兜底 404。
|
||
* 排序 (uploadedAt,id) DESC 键集游标（shared/cursor）。
|
||
*
|
||
* 未完成上传（pending_upload、uploadedAt NULL）不入列表：uploadedAt 既是契约
|
||
* 必返字段又是键集排序键——NULL 行既无法以契约形状返回（toPhotoRecord 的
|
||
* new Date(0) 兜底会伪造 1970 时间轴），也无法参与键集谓词（SQL 对 NULL 的
|
||
* 比较恒 UNKNOWN，跨页会被静默跳过）。进行中的会话由 uploads 历史端点表达。
|
||
*/
|
||
async listAlbumPhotos(
|
||
user: AuthUser,
|
||
albumId: string,
|
||
query: {
|
||
visibility?: PhotoVisibility;
|
||
categoryId?: string;
|
||
cursor?: string;
|
||
limit: number;
|
||
},
|
||
): Promise<AdminPhotoListResponse> {
|
||
if (!(await this.permissions.canViewAlbum(user, albumId))) {
|
||
throw albumNotFound();
|
||
}
|
||
if (!(await this.permissions.canManageAlbum(user, albumId))) {
|
||
throw albumForbidden('仅创建者或管理员可访问管理列表');
|
||
}
|
||
// admin 对不存在 id 的 canView/canManage 恒真（非 admin 的可见成员行本身
|
||
// 蕴含相册存在），空相册兜底同码 404——契约「相册不存在，或当前用户不可见」。
|
||
const albumExists = await this.prisma.albums.findUnique({
|
||
where: { id: albumId },
|
||
select: { id: true },
|
||
});
|
||
if (albumExists === null) {
|
||
throw albumNotFound();
|
||
}
|
||
|
||
// categoryId：须为本相册分类；幽灵/跨册同码 400（同公开列表语义，不区分
|
||
// 两种失败，防探测）。
|
||
if (query.categoryId !== undefined) {
|
||
const category = await this.prisma.categories.findUnique({
|
||
where: { id: query.categoryId },
|
||
select: { albumId: true },
|
||
});
|
||
if (category === null || category.albumId !== albumId) {
|
||
throw validationFailed('categoryId 不属于该相册');
|
||
}
|
||
}
|
||
|
||
let decoded: ReturnType<typeof decodeKeysetCursor> = null;
|
||
if (query.cursor !== undefined && query.cursor !== '') {
|
||
decoded = decodeKeysetCursor(query.cursor);
|
||
if (decoded === null) {
|
||
throw validationFailed('cursor 不合法');
|
||
}
|
||
}
|
||
|
||
const where: Prisma.photosWhereInput = {
|
||
albumId,
|
||
uploadedAt: { not: null },
|
||
...(query.visibility !== undefined
|
||
? { visibility: query.visibility }
|
||
: {}),
|
||
...(query.categoryId !== undefined
|
||
? { categoryId: query.categoryId }
|
||
: {}),
|
||
};
|
||
if (decoded !== null) {
|
||
Object.assign(where, keysetWhereDesc('uploadedAt', 'id', decoded));
|
||
}
|
||
const rows = await this.prisma.photos.findMany({
|
||
where,
|
||
orderBy: [{ uploadedAt: 'desc' }, { id: 'desc' }],
|
||
take: query.limit + 1, // 多取一条探测 hasMore（同相册/成员列表）
|
||
});
|
||
const hasMore = rows.length > query.limit;
|
||
const page = hasMore ? rows.slice(0, query.limit) : rows;
|
||
|
||
// users 无 relation（扁平外键）：二次查询应用层组装 uploader 脱敏信息。
|
||
const users =
|
||
page.length === 0
|
||
? []
|
||
: await this.prisma.users.findMany({
|
||
where: { id: { in: page.map((p) => p.uploaderId) } },
|
||
select: { id: true, account: true, displayName: true },
|
||
});
|
||
const userById = new Map(users.map((u) => [u.id, u]));
|
||
|
||
const items = page.flatMap((row) => {
|
||
const uploader = userById.get(row.uploaderId);
|
||
// 用户行缺失（P1a 无用户删除，仅可能来自手工改库）：跳过而非 5xx（同
|
||
// 成员列表先例，单条脏数据不拖垮整页）。
|
||
return uploader === undefined
|
||
? []
|
||
: [
|
||
{
|
||
...toPhotoRecord(row),
|
||
uploader: {
|
||
userId: uploader.id,
|
||
account: uploader.account,
|
||
displayName: uploader.displayName,
|
||
},
|
||
},
|
||
];
|
||
});
|
||
|
||
const last = page.at(-1);
|
||
const nextCursor =
|
||
hasMore && last !== undefined
|
||
? encodeKeysetCursor({
|
||
// where 已排除 NULL：断言收窄供类型系统（键集取页末行 DB 位置）。
|
||
sort: (last.uploadedAt ?? new Date(0)).toISOString(),
|
||
id: last.id,
|
||
})
|
||
: null;
|
||
return { items, nextCursor, hasMore: nextCursor !== null };
|
||
}
|
||
|
||
/**
|
||
* 调整可见性（契约 updatePhoto）：hidden↔published 间切换。权限 → 状态机 →
|
||
* 条件更新事务（entityVersion+1 + outbox + audit）→ 回读回显。
|
||
*/
|
||
async updateVisibility(
|
||
user: AuthUser,
|
||
photoId: string,
|
||
target: PhotoVisibilityTarget,
|
||
): Promise<PhotoRecord> {
|
||
const photo = await this.locateManagedPhoto(user, photoId);
|
||
|
||
// 幂等前态：目标即当前态——无迁移无事件，直接回显（entityVersion 不动）。
|
||
if (photo.visibility === target) {
|
||
return toPhotoRecord(photo);
|
||
}
|
||
|
||
if (target === 'hidden') {
|
||
// 仅 published → hidden：隐藏语义是「从公开面撤下」，unpublished 尚未
|
||
// 公开、deleted 已终态，均不可达。
|
||
if (photo.visibility !== 'published') {
|
||
throw visibilityTransitionFailed(photo.visibility, target);
|
||
}
|
||
return this.transition(user, photo, 'hidden');
|
||
}
|
||
|
||
// target === 'published'：仅 hidden → published（恢复发布）。unpublished 的
|
||
// 发布属 worker 处理链路；deleted 终态。
|
||
if (photo.visibility !== 'hidden') {
|
||
throw visibilityTransitionFailed(photo.visibility, target);
|
||
}
|
||
// 恢复发布 P1a 从严：仅相册创建者/公司管理员（待定需求决策，文件头注）。
|
||
if (!(await this.permissions.canManageAlbum(user, photo.albumId))) {
|
||
throw photoForbidden('仅创建者或管理员可恢复发布');
|
||
}
|
||
return this.transition(user, photo, 'published');
|
||
}
|
||
|
||
/**
|
||
* 软删除（契约 deletePhoto）：任意非 deleted 前态单向进入 deleted。行/对象/
|
||
* 变体全部保留（物理清除属 P4a 运维流程）；公开端点即刻不可见（读侧只认
|
||
* published）。重复删除幂等 204，不再发事件。
|
||
*/
|
||
async remove(user: AuthUser, photoId: string): Promise<void> {
|
||
const photo = await this.locateManagedPhoto(user, photoId);
|
||
if (photo.visibility === 'deleted') {
|
||
return;
|
||
}
|
||
await this.transition(user, photo, 'deleted');
|
||
}
|
||
|
||
/**
|
||
* 照片定位 + 权限映射：不存在 → 404；相册不可见（非成员）→ 同码 404（防
|
||
* id 枚举）；可见但无管理权 → 403。返回照片行（状态机裁决用）。
|
||
*/
|
||
private async locateManagedPhoto(
|
||
user: AuthUser,
|
||
photoId: string,
|
||
): Promise<PhotoRow> {
|
||
const photo = await this.prisma.photos.findUnique({
|
||
where: { id: photoId },
|
||
});
|
||
if (photo === null) {
|
||
throw photoNotFound();
|
||
}
|
||
if (!(await this.permissions.canViewAlbum(user, photo.albumId))) {
|
||
throw photoNotFound();
|
||
}
|
||
if (!(await this.permissions.canManagePhoto(user, photoId))) {
|
||
throw photoForbidden();
|
||
}
|
||
return photo;
|
||
}
|
||
|
||
/**
|
||
* 状态迁移事务：条件更新 WHERE visibility=前态（并发下败方 count=0 → 重读
|
||
* 后按「已达目标态」幂等回显或 400 状态冲突）+ outbox（photo.hidden/
|
||
* photo.published/photo.deleted，entityVersion=迁移后版本）+ audit
|
||
* （photo.hide/photo.publish/photo.delete）。恢复发布的 outbox 载荷复用契约
|
||
* PhotoPublishedPayload 全集（P2 副本一张照片只需一种 published 载荷形状）；
|
||
* hidden/deleted 载荷 P1a 无契约消费者，落最小事实 {photoId,albumId,
|
||
* visibility,entityVersion}。publishedAt 不随恢复发布改写——隐藏是即时
|
||
* 撤下，时间轴（列表排序依据）保持原发布时刻。
|
||
*/
|
||
private async transition(
|
||
user: AuthUser,
|
||
photo: PhotoRow,
|
||
target: 'hidden' | 'published' | 'deleted',
|
||
): Promise<PhotoRecord> {
|
||
const nextVersion = photo.entityVersion + 1;
|
||
let updatedRow: PhotoRow | null = null;
|
||
await this.prisma.$transaction(async (tx) => {
|
||
const race = await tx.photos.updateMany({
|
||
where: { id: photo.id, visibility: photo.visibility },
|
||
data: { visibility: target, entityVersion: { increment: 1 } },
|
||
});
|
||
if (race.count === 0) {
|
||
// 并发败方：不猜并发结果，交给外层重读裁决。
|
||
return;
|
||
}
|
||
if (target === 'published') {
|
||
const variants = await tx.photo_variants.findMany({
|
||
where: { photoId: photo.id },
|
||
});
|
||
// 载荷构建与 bootstrap/reconcile 快照共用同一出口（sync/payloads.ts），
|
||
// 保证两类事件逐字节同形；post-publish 不变量破坏时 5xx 回滚整个迁移。
|
||
const payload = buildPhotoPublishedPayload(photo, variants, nextVersion);
|
||
await tx.outbox_events.create({
|
||
data: {
|
||
type: 'photo.published',
|
||
albumId: photo.albumId,
|
||
photoId: photo.id,
|
||
entityVersion: nextVersion,
|
||
// P2 Task 3：恢复发布为常规优先级（显式声明，不依赖列默认）。
|
||
priority: 'normal',
|
||
// 接口类型无隐式索引签名，Prisma InputJsonValue 需显式收窄
|
||
//（同 worker publish.service 先例）。
|
||
payload: payload as unknown as Prisma.InputJsonValue,
|
||
},
|
||
});
|
||
} else {
|
||
await tx.outbox_events.create({
|
||
data: {
|
||
type: target === 'hidden' ? 'photo.hidden' : 'photo.deleted',
|
||
albumId: photo.albumId,
|
||
photoId: photo.id,
|
||
entityVersion: nextVersion,
|
||
// P2 Task 3：隐藏/删除是「即刻从公开面撤下」的墓碑类事件——高优先级，
|
||
// 发送器批次内优先投递（worker 首次发布的 photo.published 走列默认
|
||
// normal，无需改动）。
|
||
priority: 'high',
|
||
payload: {
|
||
photoId: photo.id,
|
||
albumId: photo.albumId,
|
||
visibility: target,
|
||
entityVersion: nextVersion,
|
||
},
|
||
},
|
||
});
|
||
}
|
||
await tx.audit_logs.create({
|
||
data: {
|
||
actorId: user.id,
|
||
action:
|
||
target === 'hidden'
|
||
? 'photo.hide'
|
||
: target === 'published'
|
||
? 'photo.publish'
|
||
: 'photo.delete',
|
||
resourceId: photo.id,
|
||
metadata: { from: photo.visibility, to: target },
|
||
},
|
||
});
|
||
updatedRow = {
|
||
...photo,
|
||
visibility: target,
|
||
entityVersion: nextVersion,
|
||
};
|
||
});
|
||
|
||
if (updatedRow === null) {
|
||
// 条件更新败北：重读当前态——已达目标态按幂等回显，否则 400 状态冲突
|
||
// （客户端可凭 PhotoRecord.visibility 重新裁决）。
|
||
const current = await this.prisma.photos.findUnique({
|
||
where: { id: photo.id },
|
||
});
|
||
if (current !== null && current.visibility === target) {
|
||
return toPhotoRecord(current);
|
||
}
|
||
throw visibilityTransitionFailed(
|
||
current?.visibility ?? photo.visibility,
|
||
target,
|
||
);
|
||
}
|
||
return toPhotoRecord(updatedRow);
|
||
}
|
||
}
|