delivery-desk/README.md

# 交付工作台（Delivery Desk）

面向图文作品交付与客户验收的响应式 Web 工作台。当前产品层级为“运营组 → 项目 → 作品 → 验收轮次”；每轮只有一个方案。

## 当前能力

- 平台管理员、组管理员、光影叙事三类账号及运营组数据隔离
- 项目、作品、单方案验收轮次和项目级自动验收状态
- 手动多图上传、公开图片 URL 自动归一到腾讯云 COS、拖拽排序
- 作品缩略图浏览；悬浮图片窗格中的原图查看、缩放和坐标批注
- 标题、正文和 Tag 选区批注、作品总体反馈和验收记录
- 客户项目密码、访问期限和独立验收入口
- 平台级/项目级 API Key、审计日志和账号管理
- 项目内置 Agent 安全上传 Skill，使用双阶段确认防止错组、错项目和错作品
- SQLite 本地开发、PostgreSQL 正式运行及 Docker 部署

未落地范围见 [初版交接说明](docs/handoff.md)。

## 本地开发

要求 Node.js 22+ 和 pnpm。

```bash
pnpm install
pnpm dev:start
```

- 前端：http://localhost:5180
- 后端：http://localhost:3010
- 重启：`pnpm dev:restart`
- 停止：`pnpm dev:stop`
- 查看状态：`pnpm dev:status`
- 健康检查：http://localhost:3010/api/health

未配置 `DATABASE_URL` 时使用 `data/app.db`；本地上传文件保存在 `uploads/`。两者均包含运行数据或用户文件，已排除在 Git 之外。

复制 `.env.example` 为 `.env` 后配置环境变量。生产环境至少需要 `DATABASE_URL`、`COS_CONFIG_ENCRYPTION_KEY` 和安全的初始管理员密码。真实 COS 凭证只能通过平台管理界面或部署密钥注入，不能提交到 Git。

## PostgreSQL 与 Docker

```bash
pnpm db:postgres:validate
pnpm db:postgres:migrate
docker compose up -d --build
```

目标 PostgreSQL 已有数据时迁移默认拒绝覆盖。仅确认替换时使用 `pnpm db:postgres:migrate -- --replace`。

## 检查

```bash
pnpm check
pnpm lint
pnpm build
pnpm test:review-rounds
pnpm test:collection-status
pnpm test:postgres-runtime
pnpm db:postgres:validate
python tests/test_upload_skill.py
```

修改内置 Agent 上传 Skill 后，运行 `powershell -ExecutionPolicy Bypass -File scripts/package-upload-skill.ps1` 更新 `skill-packages/upload-delivery-desk-work.zip`。该 ZIP 可直接上传到 Skill 安装器，根目录必须直接包含 `SKILL.md`。

更多资料：

- [架构与数据模型](docs/architecture.md)
- [API 接入指南](docs/integration-guide.md)
- [部署与运维手册](docs/operator-runbook.md)
- [初版交接说明](docs/handoff.md)