TeamDesk 配套讲解教程#
这套教程写给有 React / TypeScript 经验、准备开始服务端开发的前端工程师。我们从一张工单出发，沿着“表单 → 接口 → 业务规则 → 数据库 → 界面更新”走完一圈，再解释这条路上为什么需要校验、事务、缓存和并发控制。
读完第一阶段，你应该能回答：点击提交后，数据究竟去了哪里？服务端凭什么接受这次修改？刷新页面后为什么还能看到结果？
读完第二阶段，你应该能继续回答：服务端怎样确认用户身份？为什么登录了仍可能没有权限？同一个人加入两个团队，数据怎样互不串用？
读完第三阶段，你还应能回答：分配与筛选有什么区别？网络失败后怎样避免重复回复？草稿、表单、Query 与 URL 分别负责什么？
读完第四阶段，你还应能回答：一条历史怎样与业务修改共同提交？网络失败与事务回滚有什么区别？怎样用数据库断言证明没有留下半笔数据？
读完第五阶段，你还应能回答：任务已受理为什么还没完成？旧提醒为何会跳过？导出怎样守住权限与快照范围？重试后旧执行者为何不能覆盖结果？
读完第六阶段，你还应能回答：CI 的绿勾分别证明什么？镜像、迁移与数据怎样各自升级？为什么探针健康仍可能业务失败？如何从 HTTP、页面与故障结果写出可复核的验收记录？
浏览器阅读#
在项目根目录运行 pnpm tutorials:dev，打开 教程阅读站 ↗。提供章节与本章目录、全文搜索、代码复制、学习进度，以及主题和字号设置。Markdown 仍是正文来源；修改后刷新即可。构建与维护说明见 阅读站说明。
第一阶段 · 工单业务闭环#
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 01 · 项目搭建与运行 | 环境、配置、数据库、启动、工程工具 | 独立运行仓库，区分每条命令的作用 |
| 02 · 架构与第一阶段地图 | 文件职责、前后端边界、接口与数据模型 | 知道一个需求该改哪些层 |
| 03 · 从创建表单到数据库 | 输入校验、tRPC、服务层、Prisma、错误返回 | 完整解释创建工单的数据流 |
| 04 · 列表、详情与缓存 | 分页、筛选、事务快照、路由、查询失效 | 解释数据如何读出，为什么有时看见旧数据 |
| 05 · 状态流转与并发 | 状态机、版本号、条件更新、原子性 | 避免两个页面互相覆盖修改 |
| 06 · 验证、排错与练习 | 手动验收、自动测试、分层定位、练习答案 | 证明业务闭环可用，并能定位失败环节 |
第二阶段 · 认证与数据隔离#
第二阶段延续第一阶段的业务链路，从身份来源出发，依次读懂成员关系、授权、并发变更和资源隔离。已完成第一阶段时，可直接进入第 07 章。
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 07 · 登录认证 | Better Auth、密码、Cookie、会话上下文 | 解释可信 userId 从哪里来 |
| 08 · 团队与成员关系 | User / Team / Membership、嵌套写入、历史迁移 | 解释同用户跨团队角色为何独立 |
| 09 · 角色与授权 | 权限矩阵、成员与角色检查、错误边界 | 区分页面体验、身份验证和业务授权 |
| 10 · 成员管理 | 添加、降级、移除、最后管理员、锁和事务 | 说明权限变更在并发下怎样保持一致 |
| 11 · 数据隔离 | 查询与更新条件、URL、缓存、退出清理 | 审查列表、详情、统计与写入的团队边界 |
| 12 · 第二阶段验收 | 多账号场景、集成测试、排错与练习 | 证明正常操作可用，越权操作被拒绝 |
第三阶段 · 协作与状态管理#
沿着“客服接单 → 双方回复 → 暂存输入 → 分享与恢复工作台”的过程，读懂协作接口与不同状态的生命周期。
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 13 · 工单分配 | 成员关系 ID、候选资格、条件更新 | 解释选人与保存、版本冲突和解除分配 |
| 14 · 工单回复 | 作者快照、资源权限、事务、分页轮询 | 说明一条可信回复如何保存与展示 |
| 15 · 重试与幂等 | 稳定请求编号、唯一约束、重复回读 | 区分网络失败、动作重复与版本冲突 |
| 16 · Zustand 草稿 | store 工厂、隔离 key、persist 与恢复 | 说明未提交内容保存在哪里、何时清理 |
| 17 · nuqs URL 状态 | parser、history、shallow、Query 输入 | 解释刷新、分享与前进后退恢复条件 |
| 18 · 第三阶段验收 | 协作故事、边界测试、排错与练习 | 证明协作闭环成立且权限边界保留 |
后半程学习路线#
后半程按“业务事实可信 → 异步处理可靠 → 部署运行可验收”推进。第 19～31 章解释当前已实现代码，第 32 章只规划尚未接入的外部服务；阅读完成不代表生产上线或外部接入完成。
教程完善状态：第一至第六阶段均已按场景、源码、原理、故障、动手验证与练习答案展开，第 32 章仍是后续规划。 正文讲解完成不表示每个环境的数据库实验、容器部署、远端 CI 或生产发布已经执行；各章明确区分已有实现、测试覆盖、手动步骤与待补证据。
| 阶段 | 章节 | 学习目标与交付 |
|---|---|---|
| 第四阶段 | 19～21 | 可追溯记录、状态说明、事务回滚和业务不变量验证 |
| 第五阶段 | 22～27 | 独立 Worker、可靠投递、提醒、导出、重试与故障验收 |
| 第六阶段 | 28～31 | CI、独立容器、健康日志、升级与完整链路验收 |
| 后续规划 | 32 | S3、Sentry 与上线保障的实施范围、依赖和验收标准 |
第四阶段 · 业务完整性与验证#
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 19 · 操作记录 | 从客户创建、分配、回复到处理中，追踪 v0～v3 | 对上每次变化的真实操作者、快照与历史读取权限 |
| 20 · 状态说明与事务 | 一次解决工单的成功与四类失败，继续推演至关闭 | 区分输入拒绝、版本冲突、回滚和提交后响应丢失 |
| 21 · 业务完整性测试 | 独立测试库、16 组状态路径、并发与触发器故障注入 | 逐项读回滚断言，辨明已有覆盖与待补验证 |
第五阶段 · 后台任务与可靠性#
用“客服导出匹配工单”和“到期提醒当前负责人”贯穿六章。每章区分源码规则、现有测试证据与补充练习；先理解受理，再追踪投递、执行和恢复。独立测试库及分层运行命令集中在第 27 章。
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 22 · 独立后台任务 | 一次导出在页面、Web、账本与 Worker 间接棒 | 区分受理、执行、完成与页面观察 |
| 23 · 事务待投递箱 | 入队前后失败窗口、重复投递、扫描恢复 | 追踪一条没有成功入队的待办 |
| 24 · 超时提醒 | 设置、取消、重设、换负责人和重开 | 用提醒版本解释旧任务失效与通知归属 |
| 25 · CSV 导出 | 205 行分批读取、固定范围、降权、转义与下载 | 说明文件完整性、快照与多次授权 |
| 26 · 重试与执行租约 | 三次失败、新轮次、E1/E2 接手与条件提交 | 区分自动重试、手动重试和旧执行资格 |
| 27 · 后台任务验收 | 独立测试库、真实 Redis、故障注入和页面故事 | 辨明每层证据，定位等待、失败与跳过 |
第六阶段 · 验证部署与运行维护#
围绕“一次版本发布”从独立检查环境走到隔离容器、运行观察与真实 HTTP 接棒。第 29～31 章统一使用自己的 teamdesk-stage6 / .env.stage6 学习部署，区分运行机制与实际验收结果，不复用日常部署的数据卷。
| 章节 | 主线 | 读完能做什么 |
|---|---|---|
| 28 · CI 流水线 | 本地跳过与 CI 实测、两个 job、镜像重建、失败定位 | 区分每个绿勾的证据与缺口 |
| 29 · 容器部署 | 三个镜像入口、Client 来源、隔离配置、网络与升级 | 分清代码、进程、迁移和持久数据 |
| 30 · 运行维护 | 日志语义、Web / 实例探针、关闭顺序与异常退出 | 解释健康与业务结果为何可能不同 |
| 31 · 部署验收 | HTTP smoke 逐请求追踪、任务定位、多角色页面和故障记录 | 据实证明接棒链路，辨明未执行范围 |
后续规划 · 尚未接入#
32 · S3 与 Sentry 后续路线 列出附件、文件存储、错误关联及上线保障的范围、执行顺序和验收点。当前没有对应外部服务接入，教程不会把规划冒充实现。
建议每次只读一章，打开对应源码，做一次操作，再用自己的话复述数据流。正文中的“扩展理解”用于把项目知识迁移到其他业务；不需要先学完所有扩展再继续主线。
跨章节操作约定#
- 环境统一按第 01 章使用 Node.js 24、pnpm 12.10.1，与 CI 和镜像一致。命令在项目根目录执行，已有环境文件只补配置、不覆盖。
- 第 01～18 章的数据库实验使用
teamdesk_test；第 21、27 章分别使用teamdesk_stage4_test、teamdesk_stage5_test；第 29～31 章另建teamdesk-stage6Compose 项目并用.env.stage6。名字可以自定，但迁移和测试必须指向同一套目标，不能跨库沿用预期数据。 - Worker 使用它自己的 DATABASE_URL；TEST_DATABASE_URL 只是测试开关，不会自动切换运行中的 Worker。不要让常驻 Worker 消费测试库。需要精确核对版本序列的第 19～20 章暂停实验 Worker，做第 24 章到期通知前再恢复。
- 多账号实验使用独立浏览器会话；同站点普通标签页通常共享 Cookie。sessionStorage 草稿清理只针对当前页面会话，和阅读站的 localStorage 学习进度不同。
- 第 19～20 章连续使用一张新工单；其他阶段若工单已关闭，后续回复、提醒实验另开未关闭工单。解决、关闭、从已解决重新打开都要各填说明，成功后输入会清空；界面无需显示 version 字段，可从请求、响应、事件与 Prisma Studio 核对。
- “已实现”“源码推导”“已有测试断言”“手动步骤”“待补验证”分别记录。正文描述规则不表示本次运行过它，命令成功退出也不代表被跳过的集成用例已通过。
源码与测试证据对照#
| 章节 | 追踪主线的源码 | 自动证据与关键边界 |
|---|---|---|
| 01～06 | 工单服务、共享规则 | 输入单元测试、工单集成；完整状态矩阵见 21，createCaller 不经过浏览器 HTTP |
| 07～12 | 认证、成员服务、访问检查 | 认证与授权集成；认证 handler 与业务 caller 分开测，不能直接推出业务 Origin 分支已测 |
| 13～18 | 协作、草稿、URL parser | 协作集成、内存草稿 / parser；真实浏览器恢复与历史需另验，无变化分配另见记录测试 |
| 19～21 | 记录服务与工单 / 成员写路径 | 状态、记录和故障注入；顺序重复与触发器回滚不覆盖所有并发字段与 HTTP 行为 |
| 22～27 | 投递器、执行器、任务服务 | 任务业务集成、真实队列、正式 Worker 消费恢复分层执行；提醒并发边界由同步关卡验证提醒 / 导出接手；覆盖导出读取中撤权、最终授权锁和结果提交回滚 |
| 28～31 | CI、镜像、Worker 启动、消费工厂、生命周期、smoke | 日志单元测试不启动进程；进程集成验证心跳与 SIGTERM / 超时恢复；HTTP smoke 只覆盖注册会话到导出下载，页面、故障、远端 CI 与生产环境分别留证据 |
先对齐学习阶段与当前仓库#
本教程以编写时的仓库代码为依据：当前代码已包含第二至第六阶段。第一阶段的主题仍是创建、分页列表、状态筛选、详情和状态修改，但这些方法如今已经接上登录、团队隔离、操作记录和后台任务。
因此，跟随教程时采用两条约定：
- 运行当前项目：按第 01 章启动，正常注册、登录、创建团队；保留现有权限检查。
- 聚焦各阶段主线：第一阶段读四个工单接口；第二阶段读认证入口、成员与授权服务；第三阶段读协作服务、草稿 store 和 URL parser。第四阶段验证业务与历史一致，第五阶段追踪任务账本和执行恢复，第六阶段阅读 CI、镜像、日志与验收脚本。
| 能力 | 最初第一阶段 | 当前运行时 |
|---|---|---|
| 接口入口 | 本地学习开关限制 | 服务端会话 + 团队成员与角色检查 |
| 服务工厂 | createTicketService(db) |
createTicketService(db, userId, teamId) |
| 工单归属 | 单表工单 | 必须归属团队，新工单记录创建者 |
| 修改状态 | 合法路径 + 版本号 | 另有重要变更说明、操作记录和提醒处理 |
| 页面筛选 | 基础状态与分页 | 还有 URL 状态、搜索、优先级、负责人 |
最初第一阶段的提交为 903d384。需要对照演进时，可以只读历史文件：
git show 903d384:src/server/services/ticket.ts
git show 903d384:prisma/schema.prisma第二阶段功能提交为 7781bb8，已用服务端会话与资源授权替换最初的学习开关。第二阶段教程仍以当前源码为准，并标明后来加入的分配与草稿等逻辑。
第三阶段功能提交为 1236559，将负责人、回复与客户端状态接上已有工单和权限链路。当前回复与分配还会保存第四阶段加入的操作记录；教程会区分阶段主线与后续扩展。
历史中的 LOCAL_LEARNING_MODE 已被移除，不要把它加入当前 .env 来尝试绕过登录。也不需要切换旧提交或回滚当前数据库。历史源码用于理解最小模型，正文中的操作步骤面向当前仓库。
使用说明#
- 路径均相对项目根目录；文中的源码链接可直接打开。
- 标注“源码节选”的片段用来定位和解释；标注“概念示意”的片段省略了配套逻辑，不应整段覆盖现有实现。
- 命令默认在项目根目录执行；示例凭据来自本地学习配置。
- Next.js 说明已对照项目安装版本附带的
node_modules/next/dist/docs/，不要将旧版 Pages Router 教程直接套到这里。 - 第 32 章的 S3、Sentry 为待实施规划。Redis、BullMQ 与 Worker 的原理及验收见第五阶段，部署与运行维护见第六阶段。
从 第 01 章 开始；若项目已经能够运行，可先完成该章验收，再进入第 02 章。