82 lines
3.5 KiB
Markdown
82 lines
3.5 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`。客户只能看到非草稿作品；客户可通过或要求修改，要求修改必须填写原因。已通过作品只能由平台管理员或所属组管理员填写原因后重新打开，历史事件保留。
|
|||
|
|
|