T

浅念 8a8ad8a18d 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>

2026-09-20 15:56:38 +08:00