切换主题
Workbench 案例与证据地图
Workbench 是一个真实任务执行体系，为课程提供代码案例。阅读知识章节不要求先学习这个系统；需要理解机制怎样落地时，再使用这里的导航。
项目职责与知识映射
| 部分 | 案例职责 | 可学习的知识 |
|---|---|---|
| backend Server | 请求、运行、编排、调度、Worker 控制与回调 | 六边形、状态机、Outbox、调度 |
| backend Worker | 执行端协议、本地持久化、具体能力与恢复 | 依赖与模式、恢复、资源授权 |
| frontend | Vue 管理控制台、会话、API 客户端、功能路由与定义编辑 | 前端状态、契约、安全 |
| app-demo | 处理单、资源拥有者、可靠平台提交与业务投影 | DDD、事务、业务接入 |
| design | 架构、协议与决策记录 | 职责划分、方案取舍 |
| Workbench 根目录 | Compose、跨组件测试与日志栈 | 测试、交付、可观测性 |
| deploy | 可选应用和 Worker 发布仓库 | 发布证据与数据保护 |
基础设施分工
TDP PostgreSQL 保存平台事实与协调记录；App Demo PostgreSQL 保存业务事实；Worker SQLite 保存实例本地恢复状态；对象存储保存业务文件字节。
Temporal 保存耐久编排历史，NATS 提供消息传输与唤醒。数据库事实、工作流历史和传输消息是不同责任，不能随意互相代替。流程中出现某个消息不表示它已经成为业务投影。
已核对的实现 · 本地代码快照
跨项目端到端资料 workbench · 514f5a00
docs/learning/README.md · 第 11–57 行
符号：主链路与事实边界 · 核对日期 2026-10-02
来源与提交版本一致
## 最有效的学习方式
不要从目录树第一行开始顺序读完整个项目。先跟一条真实的 `ARCHIVE_CLEAN_THEN_WATERMARK` 处理单纵向走完，再回头学习每个模块的横向设计。
这条纵向链路覆盖了项目最重要的机制：
```text
浏览器上传 ZIP
→ app-demo 创建 ProcessingOrder 和本地 Command Outbox
→ app-demo 后台提交 TDP Task
→ TDP 创建 Task / Execution / Event / Outbox
→ NATS JetStream 唤醒 Temporal
→ Temporal 展开 DAG 并创建 Step / Attempt
→ PostgreSQL Command 经 SSE 到 Worker
→ Worker SQLite Inbox → archive.clean → 本地 Event Outbox
→ Server Attempt Inbox → Temporal Signal
→ archive.clean 输出经 CEL 映射给 image.watermark
→ Execution 完成并可靠 Callback
→ app-demo Callback Inbox 更新业务投影
```
完整细节见[一条处理单的数据流](business-flow.md)。
## 先建立四个“事实边界”
| 边界 | 保存内容 | 是否可由其他系统直接改写 |
|---|---|---|
| app-demo PostgreSQL | 处理单、业务状态、资源元数据、提交 Outbox、Callback Inbox | 否；TDP 只能通过 API/Callback 影响业务投影 |
| TDP PostgreSQL | Task、Execution、Step、Attempt、Worker、租约、事件和可靠消息 | 否；Temporal、NATS 和 Worker 都不能绕过应用用例直接成为事实源 |
| Worker SQLite | 当前 Worker 的命令 Inbox、Attempt、本地 Checkpoint、事件 Outbox、注册身份 | 否；只属于该 Worker，不是全局查询库 |
| MinIO | app-demo 拥有的 ZIP、PNG 和 manifest 文件字节 | 通过短期 GET/PUT 授权访问；TDP Server 不转发文件内容 |
Temporal 保存耐久编排历史，NATS 保存可靠传输中的消息；它们都不替代 PostgreSQL 查询模型。删除 Worker SQLite 也不是“清缓存”，而是放弃该实例尚未同步的恢复状态。
## 文档地图
1. [一条处理单的数据流](business-flow.md)
- 以 `ARCHIVE_CLEAN_THEN_WATERMARK` 为主线，从上传、创建、调度、Worker 执行一直跟到 Callback。
- 重点看数据在业务 ID、资源引用、AccessGrant、Step 输出和业务投影之间如何变形。
2. [数据表与一致性边界](data-model.md)
- 分别解释 app-demo PostgreSQL、TDP PostgreSQL、Worker SQLite 的表设计。
- 不只列字段，还说明每组表为何要在同一个事务里写、哪些列是事实、哪些列是投影。
3. [代码阅读与联调练习](code-reading.md)
- 给出按业务动作定位代码的方法，以及一组不会删除本地数据的观察命令。
- 用同一组 ID 串起页面、日志、两套 PostgreSQL、Temporal UI 和 NATS NUI。
已有文档仍然是重要的专题参考：片段展示核对时的源码；完整文件指纹用于检测后续变化。这里的路径用于定位，不要求手机访问源码仓库。
设计要求中的系统边界 design · fb16fc7d
README.md · 第 14–33 行
符号：核心边界 · 核对日期 2026-10-02
来源与提交版本一致
核心边界：
- 业务系统自身的任务与 TDP Task 是不同对象，通过稳定的不透明引用和 HTTP 契约关联；TDP 内部采用 `Task -> Execution -> Step -> Attempt`；
- TDP 必须将异步执行的进展和最终状态回调给业务平台，业务平台同时可通过查询 API 进行补偿；
- TDP 不理解资产、课程、妆容、镜头等具体行业模型；
- TDP Server 与 Worker 采用同一代码仓库中的两个独立应用，分别构建、发布和部署，只通过版本化协议通信；
- TDP 自有 HTTP 业务接口统一使用 `/api/v1/...`，Public、Worker、Management 边界由独立 Listener、Service 或域名区分；
- 自有接口采用“RESTful 资源 + 显式领域动作”：资源管理遵循 RESTful 风格，注册、心跳、确认、取消等命令优先保证语义清晰，并具备幂等与审计约束；
- Hroxy 与 Omni Server 处于相同架构层级，都是 Worker 的调用或调度对象；它们不替代 Worker、不注册到 Node，也不直接参与 TDP 协议；
- TDP 只调度 Worker，具体 Capability Worker 负责选择和调用可达的下游执行服务、保存其外部引用并把结果转换为 TDP Attempt 事件；并非每个 Worker 都需要下游服务；
- 原始资源和执行产物归业务平台所有，TDP 不持久化业务文件；
- 所有项目统一采用 Go、六边形架构和 DDD；
- 实现顺序优先打通核心纵向切片，但第一阶段交付完整的集群、可靠性、安全、监控和治理能力，不以最小实现名义删减；
- 第三方包优先采用当前仍受维护的最新稳定版本，并固定实际构建版本；不无依据沿用陈旧、停更或存在已知安全风险的依赖；
- 业务平台和 TDP 的服务端关系数据使用 PostgreSQL，Worker 本地结构化状态使用 SQLite；分布式协调、队列、OpenAPI/Swagger、结构化日志、本地关联、Server 指标和健康检查同属当前程序实现基线，集中指标、告警与分布式 Trace 仍属后续建设。
## 总体架构
```mermaid
flowchart LR片段展示核对时的源码；完整文件指纹用于检测后续变化。这里的路径用于定位，不要求手机访问源码仓库。
设计资料与当前实现
design 文档记录约束和未来方向，backend 的 implementation 资料解释实现。课程会用源码核对关键主张，不把计划中的下游 Worker 服务或集中 tracing 当成已实现事实。
普通开发不需要初始化 deploy。这里的发布资料只用于说明职责与流程，不查询或修改生产系统，不提供含私有配置的运行快照。
选择一个案例切面
- 想理解业务与平台边界：从 App Demo.Create 和 TDP.CreateTask 的不同模型开始。
- 想理解消息可靠性：读 OutboxDispatcher、认领 SQL 与 Callback 接收，观察三处事务窗口。
- 想理解执行恢复：读 Runtime 的持久化协作者与独立事件发送器，继续追能力的 Checkpoint。
- 想理解工程边界：读组合根、功能路由、生成目标与发布职责。