93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
|
# 交付工作台（Delivery Desk）
|
|||
|
|
|
|||
|
|
面向图文作品交付与客户验收的响应式 Web 工作台。业务层级为“运营组 → 项目 → 作品交付集 → 作品 → 版本”。运营人员负责上传和处理反馈，客户通过项目链接完成查看、批注与验收。
|
|||
|
|
|
|||
|
|
## 当前能力
|
|||
|
|
|
|||
|
|
- 平台管理员、组管理员、光影叙事三类账号及运营组数据隔离
|
|||
|
|
- 项目、作品交付集、作品和作品版本管理
|
|||
|
|
- 多图上传、封面预览、图片排序和腾讯云 COS 存储
|
|||
|
|
- 图片坐标批注、标题/正文批注、总体反馈和验收记录
|
|||
|
|
- 客户项目密码、访问期限和独立验收入口
|
|||
|
|
- 平台级/项目级 API Key、审计日志和账号管理
|
|||
|
|
- SQLite 本地开发、PostgreSQL 正式运行及迁移脚本
|
|||
|
|
- Docker 单机部署
|
|||
|
|
|
|||
|
|
尚未落地的范围见 [初版交接说明](docs/handoff.md)。
|
|||
|
|
|
|||
|
|
## 技术结构
|
|||
|
|
|
|||
|
|
- React 18、TypeScript、Vite、Tailwind CSS
|
|||
|
|
- Express API
|
|||
|
|
- 本地开发：SQLite 与本地 `uploads`
|
|||
|
|
- 正式环境：PostgreSQL、腾讯云 COS
|
|||
|
|
- COS SecretId/SecretKey 由平台管理员在前端配置，服务端使用 AES-256-GCM 加密，接口不返回明文
|
|||
|
|
|
|||
|
|
## 本地开发
|
|||
|
|
|
|||
|
|
要求 Node.js 22+ 和 pnpm。
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm install
|
|||
|
|
pnpm dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 前端：`http://localhost:5173`
|
|||
|
|
- API：`http://localhost:3001`
|
|||
|
|
- 健康检查：`http://localhost:3001/api/health`
|
|||
|
|
|
|||
|
|
未配置 `DATABASE_URL` 时使用 `data/app.db`；本地图片保存在 `uploads/`。这两个目录包含运行数据、账号信息或用户文件，已排除在 Git 之外。
|
|||
|
|
|
|||
|
|
SQLite 首次启动会创建开发账号并要求首次登录改密。不要把这些开发账号用于公网环境。
|
|||
|
|
|
|||
|
|
## 环境配置
|
|||
|
|
|
|||
|
|
复制 `.env.example` 为 `.env`，再按环境填写。关键变量：
|
|||
|
|
|
|||
|
|
| 变量 | 用途 |
|
|||
|
|
|---|---|
|
|||
|
|
| `DATABASE_URL` | PostgreSQL 连接串；留空时使用 SQLite |
|
|||
|
|
| `PGSSL` / `PG_POOL_MAX` | PostgreSQL SSL 与连接池配置 |
|
|||
|
|
| `CORS_ORIGIN` | 允许携带凭据访问 API 的前端来源，多个值以逗号分隔 |
|
|||
|
|
| `COS_CONFIG_ENCRYPTION_KEY` | 加密前端保存的 COS 凭证，至少 32 个随机字符 |
|
|||
|
|
| `INITIAL_ADMIN_PASSWORD` | 空 PostgreSQL 首次初始化的平台管理员临时密码 |
|
|||
|
|
|
|||
|
|
`COS_CONFIG_ENCRYPTION_KEY` 一经用于保存 COS 配置后必须稳定保管，更换会导致旧密文无法解密。真实 COS 凭证不得写入 `.env.example`、源码、镜像或日志。
|
|||
|
|
|
|||
|
|
## PostgreSQL 迁移
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm db:postgres:validate
|
|||
|
|
pnpm db:postgres:migrate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
目标数据库已有数据时迁移会拒绝覆盖。确认替换时才可执行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm db:postgres:migrate -- --replace
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Docker 部署
|
|||
|
|
|
|||
|
|
在 `.env` 中至少设置 `POSTGRES_PASSWORD`、`COS_CONFIG_ENCRYPTION_KEY` 和 `INITIAL_ADMIN_PASSWORD`，然后运行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
docker compose up -d --build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
应用通过 `http://服务器地址:3001` 同时提供前端与 API。公网环境应在前面配置 HTTPS 反向代理；生产 Cookie 会自动添加 `Secure`。
|
|||
|
|
|
|||
|
|
## 文档与检查
|
|||
|
|
|
|||
|
|
- [架构与数据模型](docs/architecture.md)
|
|||
|
|
- [API 接入指南](docs/integration-guide.md)
|
|||
|
|
- [部署与运维手册](docs/operator-runbook.md)
|
|||
|
|
- [初版交接说明](docs/handoff.md)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm check
|
|||
|
|
pnpm lint
|
|||
|
|
pnpm build
|
|||
|
|
pnpm test:postgres-runtime
|
|||
|
|
```
|