delivery-desk/docs/architecture.md

# 架构与数据模型

## 系统边界

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

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

## 业务层级

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

- 一个运营组只能有一位组管理员，可以有多位光影叙事。
- 平台管理员可以有多位，不属于固定运营组。
- 普通工作台账号只能读写所属运营组的数据；平台管理员可跨组管理。
- 客户会话只绑定一个项目，不能跨项目浏览。
- 平台级 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/` 路径依次上传、读取并删除一个临时对象。启用后，新上传文件写入：

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

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

## 验收状态

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

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