feat(contracts): p4a admin governance, watermark, download and usage endpoints
P4a Task 1 契约扩展批次（36 → 51 operations，gen/redocly/枚举同步守护绿）：
- photos：POST /albums/{albumId}/photos/hide-batch（photoIds 1..200，逐项
BatchHideResult {photoId, ok, code?}，部分成功语义，A16）；
- admin：POST /admin/albums/{albumId}/transfer（owner 交接，历史上传人不动，
keepAsCollaborator，A17）；
- albums：POST/GET /albums/{albumId}/watermark-jobs（WatermarkConfig 版本化
+ 历史重生成任务 state/progress/total/failed，原子切换、原图永不覆盖，
A18/A20）；
- interactions：GET /public/albums/{token}/photos/{photoId}/download
（variant=browse|original 两级开关校验；**新增错误码 DOWNLOAD_DISABLED**，
errors.ts 与 Error enum 两侧同步，A18）；
- admin 账号治理：GET /admin/users 统一为 listAdminUsers 双模式 + PATCH
/admin/users/{userId} 与 reset-password / activate / deactivate；
- admin 用户同步：GET /admin/user-sync/{status,runs,errors} + POST runs
手动补拉（互斥复用进行中批次，A29）；
- admin 用量：GET /admin/usage/summary + PUT thresholds（null 清除、
即刻重评估，A23）。
偏差登记①——/admin/users 路径冲突（P1b lookupUsersByAccount）：P4a 决策
统一为双模式端点（前缀模式沿用 P1b 语义与任何已认证工作人员可用；管理
列表模式 query/status 过滤 + 游标 + 仅 admin），响应统一 AdminUserList
（AdminUser 字段超集，游标元信息随行）。消费方同步：admin 邀请搜索
（fetchLookupUsers/类型镜像，行为不变）与 api 过渡实现（仍仅前缀模式、
limit 对齐 1..100 缺省 20；管理列表模式与仅 admin 判定随 Task 6 落地，
users-lookup e2e 已按统一形状修订）。
偏差登记②——apps/mobile 手写镜像未随本次更新：其邀请流程仍按旧 3 字段
投影消费（AdminUserList 为超集，运行时兼容，mobile IT 不经该路径）；列
为 P4a 跟进项，仅当其 e2e 破坏时处理。
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -1,10 +1,14 @@
|
||||
// services/api/src/admin/users-lookup.controller.ts —— /admin/users 端点
|
||||
// （P1b Task 4）。方法名与契约 operationId 一一对应（lookupUsersByAccount）。
|
||||
// 控制器级 SessionGuard：访问策略=任何已认证工作人员（契约描述的 P1b 决策，
|
||||
// 见服务文件头），认证通过即可，无角色判定。控制器只做查询参数规整
|
||||
// （accountPrefix 必填 2-64 字符；limit 缺省 10、1..20——本端点独立 bounds，
|
||||
// 同公开照片列表在 public.controller 本地维护 parsePublicPhotoLimit 的先例，
|
||||
// 勿混用 shared/pagination 的 1..100）；语义在服务层。
|
||||
// （P1b Task 4 建立；P4a Task 1 契约统一为 listAdminUsers 双模式）。
|
||||
// 方法名与契约 operationId 一一对应（listAdminUsers）。
|
||||
// 控制器级 SessionGuard：访问策略=任何已认证工作人员（P1b 决策，见服务文件
|
||||
// 头——管理列表模式的仅 admin 判定由 Task 6 补齐）。控制器只做查询参数规整，
|
||||
// 语义在服务层。
|
||||
// 过渡期边界（Task 6 收口）：契约 P4a 起 accountPrefix 可选（缺省进入管理
|
||||
// 列表模式：query/status 过滤 + 游标分页 + 仅 admin）；当前实现仅前缀模式，
|
||||
// 缺 accountPrefix 仍 400——管理列表模式随 Task 6 账号管理落地。
|
||||
// limit 边界已对齐统一契约：缺省 20、上下界 1..100（P1b 时为 10/1..20；
|
||||
// 邀请搜索调用方显式传 limit=10，行为不变）。
|
||||
import {
|
||||
Controller,
|
||||
Get,
|
||||
@@ -16,18 +20,16 @@ import { ErrorCodes } from '@photo/contracts';
|
||||
import { ApiException } from '../api-exception';
|
||||
import { SessionGuard } from '../auth/session.guard';
|
||||
import { validationFailed } from '../albums/support';
|
||||
import {
|
||||
UsersLookupService,
|
||||
type AdminUserLookupListResponse,
|
||||
} from './users-lookup.service';
|
||||
import { UsersLookupService, type AdminUserListResponse } from './users-lookup.service';
|
||||
|
||||
/** 契约 lookupUsersByAccount.limit：缺省 10，上下界 1..20。 */
|
||||
export const DEFAULT_LOOKUP_LIMIT = 10;
|
||||
export const MAX_LOOKUP_LIMIT = 20;
|
||||
/** 契约 listAdminUsers.limit：缺省 20，上下界 1..100（P4a 统一分页 bounds）。 */
|
||||
export const DEFAULT_LIST_LIMIT = 20;
|
||||
export const MAX_LIST_LIMIT = 100;
|
||||
|
||||
/** accountPrefix 查询参数：必填（缺失/空串 400），长度 2..64（契约 bounds）。 */
|
||||
/** accountPrefix 查询参数（前缀模式）：2..64（契约 bounds）。 */
|
||||
export function parseAccountPrefix(raw: string | undefined): string {
|
||||
if (raw === undefined || raw === '') {
|
||||
// Task 6 起此分支消失（缺省进入管理列表模式）；当前实现仅前缀模式。
|
||||
throw validationFailed('accountPrefix 必填（2-64 字符）');
|
||||
}
|
||||
if (raw.length < 2 || raw.length > 64) {
|
||||
@@ -36,23 +38,23 @@ export function parseAccountPrefix(raw: string | undefined): string {
|
||||
return raw;
|
||||
}
|
||||
|
||||
/** limit 查询参数：缺省 10，须为 1..20 的十进制整数（契约 bounds）。 */
|
||||
export function parseLookupLimit(raw: string | undefined): number {
|
||||
/** limit 查询参数：缺省 20，须为 1..100 的十进制整数（契约 bounds）。 */
|
||||
export function parseListLimit(raw: string | undefined): number {
|
||||
if (raw === undefined || raw === '') {
|
||||
return DEFAULT_LOOKUP_LIMIT;
|
||||
return DEFAULT_LIST_LIMIT;
|
||||
}
|
||||
if (!/^\d+$/.test(raw)) {
|
||||
throw new ApiException(
|
||||
ErrorCodes.VALIDATION_FAILED,
|
||||
'limit 必须是 1-20 的整数',
|
||||
'limit 必须是 1-100 的整数',
|
||||
HttpStatus.BAD_REQUEST,
|
||||
);
|
||||
}
|
||||
const limit = Number.parseInt(raw, 10);
|
||||
if (limit < 1 || limit > MAX_LOOKUP_LIMIT) {
|
||||
if (limit < 1 || limit > MAX_LIST_LIMIT) {
|
||||
throw new ApiException(
|
||||
ErrorCodes.VALIDATION_FAILED,
|
||||
'limit 必须是 1-20 的整数',
|
||||
'limit 必须是 1-100 的整数',
|
||||
HttpStatus.BAD_REQUEST,
|
||||
);
|
||||
}
|
||||
@@ -64,15 +66,15 @@ export function parseLookupLimit(raw: string | undefined): number {
|
||||
export class UsersLookupController {
|
||||
constructor(private readonly usersLookupService: UsersLookupService) {}
|
||||
|
||||
/** 账号前缀查询：激活用户脱敏列表（account 升序，无游标）。 */
|
||||
/** 用户查询/管理列表（统一响应 AdminUserList；当前仅前缀模式，见文件头）。 */
|
||||
@Get()
|
||||
lookupUsersByAccount(
|
||||
listAdminUsers(
|
||||
@Query('accountPrefix') accountPrefix: string | undefined,
|
||||
@Query('limit') limit: string | undefined,
|
||||
): Promise<AdminUserLookupListResponse> {
|
||||
): Promise<AdminUserListResponse> {
|
||||
return this.usersLookupService.lookup(
|
||||
parseAccountPrefix(accountPrefix),
|
||||
parseLookupLimit(limit),
|
||||
parseListLimit(limit),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,10 +1,9 @@
|
||||
// services/api/src/admin/users-lookup.service.ts —— 账号前缀查询（P1b Task 4，
|
||||
// 契约 lookupUsersByAccount，tag [admin]）。邀请协作者的前置查询：按 account
|
||||
// 前缀搜索激活用户，返回 {id,account,displayName} 脱敏列表（不含邮箱/手机/
|
||||
// 状态/凭据字段）。
|
||||
// 访问策略（P1b 决策，契约描述）：任何已认证工作人员可用——邀请发起方不限于
|
||||
// 创建者/管理员，泄露面仅为激活用户的最小展示字段、接收方为已认证内部人员；
|
||||
// 未认证一律 401（控制器级 SessionGuard 承担，服务层不再重复角色判定）。
|
||||
// services/api/src/admin/users-lookup.service.ts —— 用户查询/管理列表（P1b
|
||||
// Task 4 前缀查询；P4a Task 1 契约统一为 listAdminUsers 双模式端点）。
|
||||
// P4a 契约决策：/admin/users 响应统一 AdminUserList（AdminUser 字段超集，
|
||||
// 管理端 UI 按场景裁剪展示）；本文件为**过渡实现**——仅落地前缀模式
|
||||
// （P1b 语义原样：邀请协作者前置查询），管理列表模式（query/status 过滤 +
|
||||
// 游标分页 + 仅 admin 访问）由 P4a Task 6 账号管理实现补齐。
|
||||
// 实现要点：
|
||||
// · 前缀匹配大小写敏感：库级 collation utf8mb4_0900_bin（schema.prisma 头注
|
||||
// 约定），LIKE 按二进制逐字节比较——'AL' 不命中 'alice'（契约已注明）。
|
||||
@@ -14,20 +13,28 @@
|
||||
// · 资格过滤与 SessionGuard 同一谓词（credentialStatus=active 且
|
||||
// sourceStatus≠disabled 且 !localLocked）：被停用/待激活/锁定账号不可被
|
||||
// 邀请，也就不应出现在候选列表（与 members.add 的目标校验一致）。
|
||||
// · 无游标：前缀搜索 + 小上限（1..20 缺省 10）即取即用（契约决策），按
|
||||
// account 升序返回确定性输出。
|
||||
// · 前缀模式即取即用（limit 上限内一次取回）：nextCursor=null、
|
||||
// hasMore=false；游标翻页随 Task 6 管理列表模式落地。
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import type { components } from '@photo/contracts';
|
||||
import { PrismaService } from '../prisma/prisma.service';
|
||||
|
||||
export type AdminUserLookupListResponse =
|
||||
components['schemas']['AdminUserLookupList'];
|
||||
export type AdminUserListResponse = components['schemas']['AdminUserList'];
|
||||
|
||||
/** $queryRaw 行形状（SELECT 列即脱敏字段全集——不选取任何凭据/状态列）。 */
|
||||
interface LookupRow {
|
||||
/** AdminUser 契约条目类型（枚举字段的窄化转换目标）。 */
|
||||
type AdminUserItem = AdminUserListResponse['items'][number];
|
||||
|
||||
/** $queryRaw 行形状（SELECT 列即 AdminUser 契约字段——不含任何凭据列）。 */
|
||||
interface AdminUserRow {
|
||||
id: string;
|
||||
account: string;
|
||||
displayName: string;
|
||||
role: string;
|
||||
sourceStatus: string;
|
||||
localLocked: number; // MySQL BOOLEAN 经 $queryRaw 返回 0/1
|
||||
credentialStatus: string;
|
||||
locale: string | null;
|
||||
createdAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -42,15 +49,19 @@ export function escapeLikePrefix(prefix: string): string {
|
||||
export class UsersLookupService {
|
||||
constructor(private readonly prisma: PrismaService) {}
|
||||
|
||||
/** 前缀查询（契约 lookupUsersByAccount）：激活用户、account 升序、limit 截断。 */
|
||||
/**
|
||||
* 前缀查询（契约 listAdminUsers 前缀模式）：激活资格用户、account 升序、
|
||||
* limit 截断；响应为统一 AdminUserList 形状（P4a）。
|
||||
*/
|
||||
async lookup(
|
||||
accountPrefix: string,
|
||||
limit: number,
|
||||
): Promise<AdminUserLookupListResponse> {
|
||||
): Promise<AdminUserListResponse> {
|
||||
const pattern = `${escapeLikePrefix(accountPrefix)}%`;
|
||||
// 参数经 $queryRaw 模板绑定（无拼接注入面）；LIMIT ? 为 MySQL 合法占位。
|
||||
const rows = await this.prisma.$queryRaw<LookupRow[]>`
|
||||
SELECT id, account, displayName
|
||||
const rows = await this.prisma.$queryRaw<AdminUserRow[]>`
|
||||
SELECT id, account, displayName, role, sourceStatus, localLocked,
|
||||
credentialStatus, locale, createdAt
|
||||
FROM users
|
||||
WHERE account LIKE ${pattern} ESCAPE '!'
|
||||
AND credentialStatus = 'active'
|
||||
@@ -64,7 +75,16 @@ export class UsersLookupService {
|
||||
id: row.id,
|
||||
account: row.account,
|
||||
displayName: row.displayName,
|
||||
// 库列为自由字符串（schema 约定取值集），窄化到契约枚举联合。
|
||||
role: row.role as AdminUserItem['role'],
|
||||
sourceStatus: row.sourceStatus as AdminUserItem['sourceStatus'],
|
||||
localLocked: row.localLocked !== 0,
|
||||
credentialStatus: row.credentialStatus as AdminUserItem['credentialStatus'],
|
||||
locale: row.locale,
|
||||
createdAt: row.createdAt.toISOString(),
|
||||
})),
|
||||
nextCursor: null,
|
||||
hasMore: false,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user