83 lines
3.8 KiB
Markdown
83 lines
3.8 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
|
||
运营组
|
||
└── 项目
|
||
└── 作品交付集
|
||
└── 作品
|
||
└── 版本
|
||
```
|
||
|
||
- 一个运营组只能有一位组管理员，可以有多位光影叙事。
|
||
- 平台管理员可以有多位，不属于固定运营组。
|
||
- 普通工作台账号只能读写所属运营组的数据；平台管理员可跨组管理。
|
||
- 客户会话只绑定一个项目，不能跨项目浏览。
|
||
- 平台级 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` 是人工状态，自动计算不会覆盖。完成后客户页面只读；新增作品、新版本或重新打开作品会自动恢复为验收中。
|