6091d61612
- 支持每轮提交 1–5 个候选稿并按指定稿验收 - 保留历史轮次只读并兼容单候选稿版本接口 - 同步 SQLite/PostgreSQL schema、迁移验证、测试与项目文档
85 lines
4.1 KiB
Markdown
85 lines
4.1 KiB
Markdown
# 架构与数据模型
|
||
|
||
## 系统边界
|
||
|
||
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
|
||
运营组
|
||
└── 项目
|
||
└── 作品交付集
|
||
└── 作品
|
||
└── 验收轮次
|
||
└── 候选稿（1–5 个）
|
||
```
|
||
|
||
- 一个运营组只能有一位组管理员，可以有多位光影叙事。
|
||
- 平台管理员可以有多位，不属于固定运营组。
|
||
- 普通工作台账号只能读写所属运营组的数据；平台管理员可跨组管理。
|
||
- 客户会话只绑定一个项目，不能跨项目浏览。
|
||
- 平台级 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` | 作品当前状态、活动轮次和选中稿 |
|
||
| `review_rounds` | 验收轮次、完成状态和选中候选稿 |
|
||
| `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`。一个验收轮次可包含 1–5 个候选稿；单稿退修时，其他待验收稿仍可继续验收。客户选中并通过任意一稿后，作品即通过，同轮其他稿标记为未选用，历史轮次只读。已通过作品只能由平台管理员或所属组管理员填写原因后重新打开，历史事件保留。
|
||
|
||
作品交付集状态由其中非草稿作品自动计算：没有已提交作品时为 `draft`，存在未通过作品时为 `reviewing`，全部已提交作品通过时为 `completed`。`archived` 是人工状态，自动计算不会覆盖。完成后客户页面只读；新增作品、新验收轮次或重新打开作品会自动恢复为验收中。
|