fix(contracts): quality review fixes for p1a contracts

- status enum active|archived -> active|offline (align requirement docs)
- UploadSessionState session-state semantics documented (no failed state)
- maxLength: clientTaskId 128 / filename 255 / cursor 512
- PublicPhoto width/height required (layout placeholders)
- reusable Unauthorized/InternalError responses (hybrid with inline op-specific codes)
- PublicAlbum.translations -> translation (single resolved object)
- contentType enum [jpeg/png/heic] (heic provisional pending G2)
- minLength 1 on title/name; publicToken pattern ^[0-9a-z]{20,32}$
- CursorPageMeta hasMore/nextCursor invariant documented
- public locale: silent fallback to defaultLocale (tech doc section 11)
- plan: upload_sessions state comment aligned; P1b adds management photo list + account lookup endpoints

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
2026-09-17 18:06:54 +08:00
parent 1dae00eaef
commit f6448bd006
3 changed files with 152 additions and 581 deletions
@@ -429,7 +429,7 @@ model upload_sessions {
expectedBytes Int
contentType String @db.VarChar(128)
multipartId String?
state String @default("pending_upload") // pending_upload|uploaded|confirmed|failed
state String @default("pending") // pending|confirmed|cancelled|expired(对齐契约 UploadSessionState;核验失败是请求级错误不改会话态,expired 由 expiresAt 判定或 sweep 置位)
expiresAt DateTime @db.DateTime(6)
createdAt DateTime @default(now()) @db.DateTime(6)
@@unique([userId, clientTaskId]) // 幂等锚点(A03)
@@ -648,4 +648,4 @@ export interface StoragePort {
- env:命令一律在仓库根执行;根 `.env` 为唯一 env 文件,脚本经 dotenv-cli 注入、测试经 `test/load-env.ts` 载入(Task 7 约定;`services/worker/test` 与 `packages/storage/test` 复制同约定 load-env.ts——两者到仓库根同为三级向上,路径一致);新增 env 变量必须同步 `.env.example`;密钥不入库。
- 发现契约需变更时:先改 `packages/contracts` 并重新生成类型、在任务提交信息中登记,再改消费端(契约单一事实源)。
- 与总纲冲突处以总纲为准并回写修订;HEIC、MySQL 行值比较等 D12 复核项结论写入验收记录。
- P1a 完成后:编写 P1b 计划(viewer 基础页 + admin 最小页 + **宣传图/封面/Logo 上传链路(album_assets 的 presign+确认,复用照片上传机制,R09 依赖)** + Playwright 冒烟)。
- P1a 完成后:编写 P1b 计划(viewer 基础页 + admin 最小页 + **宣传图/封面/Logo 上传链路(album_assets 的 presign+确认,复用照片上传机制,R09 依赖)** + **GET /albums/{albumId}/photos 管理端照片列表**(含未发布/隐藏态,照片管理入口)+ **用户账号查询接口**(邀请协作者时按 account 搜索)+ Playwright 冒烟)。