架构与数据模型

系统边界

Delivery Desk 是单体 Web 应用：React 前端调用 Express API，前后端共享 shared/types.ts 类型。开发环境使用 SQLite 和本地上传目录；正式环境使用 PostgreSQL 和腾讯云 COS。

flowchart LR
  browser["浏览器"] --> app["Express / React 应用"]
  app --> database["SQLite 或 PostgreSQL"]
  app --> local["本地 uploads（开发）"]
  app --> cos["腾讯云 COS（正式）"]
  customer["客户验收链接"] --> app
  client["外部 API 客户端"] --> app

业务层级

运营组
└── 项目
    └── 作品交付集
        └── 作品
            └── 版本

一个运营组只能有一位组管理员，可以有多位光影叙事。
平台管理员可以有多位，不属于固定运营组。
普通工作台账号只能读写所属运营组的数据；平台管理员可跨组管理。
客户会话只绑定一个项目，不能跨项目浏览。
平台级 API Key 可创建项目；项目级 API Key 只能操作指定项目。

运行结构

src/：React 页面、组件、状态和 API 客户端。
api/routes/：HTTP 路由与输入校验。
api/services/：作品、存储等业务编排。
api/repositories/：查询封装。
api/database.ts：SQLite/PostgreSQL 统一查询接口和事务。
api/db.ts：SQLite 初始化及增量迁移。
db/postgres/schema.sql：PostgreSQL 当前完整 schema。
shared/types.ts：前后端共享领域类型。

DATABASE_URL 存在时使用 PostgreSQL，否则使用 SQLite。两套数据库必须保持相同业务约束；涉及表或字段的修改必须同时更新 api/db.ts、db/postgres/schema.sql 及迁移验证脚本。

主要数据表

表	用途
`operation_groups`	运营组及启停状态
`users` / `sessions`	工作台账号、角色和登录会话
`customer_sessions`	客户项目级验收会话
`projects`	项目、客户访问密码和访问期限
`collections`	项目下的作品交付集
`notes`	作品当前状态和当前版本
`work_versions`	各版本标题、正文、标签和状态快照
`images`	版本图片、顺序、存储提供方和对象 Key
`annotations`	图片坐标批注
`text_annotations`	标题或正文的版本级批注
`work_comments`	作品总体反馈与回复
`review_events`	提交、修改、通过、重新打开等验收记录
`api_keys`	平台级或项目级 API Key 的哈希与状态
`storage_configs`	加密后的 COS 配置及启用状态
`audit_logs`	管理和业务操作审计

存储流程

平台管理员在管理页新增 COS 配置。SecretId 和 SecretKey 使用 COS_CONFIG_ENCRYPTION_KEY 派生的 AES-256-GCM 密钥加密后写入数据库，读取配置的接口不会返回明文。

启用配置前会在目标桶的 .delivery-desk-check/ 路径依次上传、读取并删除一个临时对象。启用后，新上传文件写入：

<path-prefix>/originals/YYYY/MM/<uuid>.<ext>

未启用 COS 时，上传文件保存在本地 uploads/。图片 URL 按产品约定为公开随机地址，不提供对象级访问鉴权。

验收状态

作品状态为 draft、pending、changes_requested、approved。客户只能看到非草稿作品；客户可通过或要求修改，要求修改必须填写原因。已通过作品只能由平台管理员或所属组管理员填写原因后重新打开，历史事件保留。

作品交付集状态由其中非草稿作品自动计算：没有已提交作品时为 draft，存在未通过作品时为 reviewing，全部已提交作品通过时为 completed。archived 是人工状态，自动计算不会覆盖。完成后客户页面只读；新增作品、新版本或重新打开作品会自动恢复为验收中。

3.8 KiB Raw Blame History Unescape Escape