# 交付工作台（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:5180`
- API：`http://localhost:3010`
- 健康检查：`http://localhost:3010/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://服务器地址:3010` 同时提供前端与 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
```