feat(auth): 添加认证模块和图片批注功能(项目初始化)
- 实现用户登录、登出、密码修改等认证功能 - 添加会话管理和权限控制中间件 - 创建图片批注组件和相关API路由 - 实现批注的增删改查功能 - 添加Docker和Git忽略配置文件 - 创建系统架构文档和开发约定说明 - 集成认证模块到前端应用路由中
This commit is contained in:
81
docs/architecture.md
Normal file
81
docs/architecture.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 架构与数据模型
|
||||
|
||||
## 系统边界
|
||||
|
||||
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`。客户只能看到非草稿作品;客户可通过或要求修改,要求修改必须填写原因。已通过作品只能由平台管理员或所属组管理员填写原因后重新打开,历史事件保留。
|
||||
|
||||
Reference in New Issue
Block a user