agent_backend

术核 AI · 后端工程课件

面向掌握 Python 基础、需要补齐后端工程经验的开发者。用轻量电商商品服务 shop-service 贯穿 API、数据库、持久化服务、任务、缓存、容器、部署、排障与分布式系统设计。共 10 个模块：前九个技术模块含 110 节教学课，末尾复盘模块含 9 个自测单元，共 119 项。首页保留服务端 Agent 参考架构，说明这些后端能力的扩展用途。

模块	标识	课时
API 服务开发	api	16
数据库开发	database	12
API + 数据库	api-database	12
异步任务开发	tasks	16
Redis 缓存	redis	10
Docker 容器化	docker	10
Linux 部署	linux	10
线上问题排查	troubleshooting	12
分布式系统设计	distributed	12
复盘与自测	review	9 个自测单元

前九个模块的教学课按自学顺序组织：具体问题与起点 → 可见目标 → 逐步操作或推演 → 核对结果 → 图解串联 → 进一步验证与练习 → 核心概念回顾。每一步都分别交代做什么、应该看到什么、刚才为什么会这样；首次出现的术语结合当步操作解释。文字课件可独立阅读，视频作为补充。数据库至排障七个模块另有生产场景、实现决策、故障演练和恢复验收。各模块概览与关键课时共配有 38 幅 SVG 图解，包含文字读图步骤和易错提示；首页另有一幅完整 Agent 参考架构图。

业务限定为商品管理、分类、评价和商品清单导出。商品接口统一 /products，核心字段为 name、description、price_cents 和 is_active；金额用整数分表示，默认 0 表示免费教学样品，上架状态默认 false。订单、支付、库存和促销不纳入实战，保证每次增加内容都用于解释技术。

数据库第 02 课从需求推导商品表，讲清实体、字段字典、类型、主键、非空、默认值、检查约束和 UTC 时间；第 04 课设计 categories 与 product_categories，讲清关系基数、联合主键、外键和删除策略。新增商品关系图，并让后续索引、迁移与恢复练习沿用同一模型。保持原有课时编号及链接。

分布式系统设计是纯理论模块：场景推演、理解自检、常见误区、面试问答与设计练习，不包含环境安装、实战代码或故障注入操作。涵盖架构模式、高可用、复制分片、一致性、缓存、消息、事务、幂等、分布式锁、容错、容量与容灾。

复盘与自测位于课程末尾，九个单元分别对应九个技术模块，每单元含六个理解问题、两个情境推演及四项掌握标准，共 72 个问题与 36 项证据要求。网页默认收起参考要点，学员先独立回答，再核对误区并沿链接回学。八项问题均自评可独立完成、四项证据均核对后，才显示本轮自评达标；网页不自动判断文字答案。回答和自评只保存在当前浏览器，题目实质更新后保留旧笔记并要求重新自评。下载版将参考要点放在每个单元末尾，适合离线复盘。

首页架构展示后端底座在完整 Agent 服务中的位置；当前可运行参考代码仍是 shop-service 基础项目。Agent 编排、模型与外部工具用于说明目标场景，不代表仓库已实现完整 Agent 运行系统。

本地运行

需要 Node.js 22.13 或更新版本。

npm install
npm run dev

访问终端显示的地址进入课程总览。原有 ?lesson=01 链接继续指向 API 课时，API 概览使用 ?module=api。其他模块使用 ?module=database&lesson=01，模块概览使用 ?module=database，理论课使用 ?module=distributed&lesson=01。浏览器前进、后退和移动端目录均可用。

内容维护

• app/lessons.json：API 模块数据。
• public/content/{模块标识}.json：后续八个模块。按需载入，切换模块时显示载入或重试状态。
• app/module-catalog.ts：名称、前置关系、工程边界、完成标准和课时数量。
• app/course.tsx：通用课件页面，不需要为每个新模块复制页面代码。
• app/course-home.tsx、app/course-home.css：课程总览、Agent 参考架构、长任务流程与模块定位。
• app/diagram-catalog.ts、app/teaching-diagrams.tsx、app/teaching-diagrams.css：教学图数据、课时映射与可访问 SVG 渲染。修改映射时检查对应模块及课时编号。
• app/lesson-types.ts：教学与复盘的联合类型；以下字段约束用于 TeachingLesson。intro 必须包含场景、起点和可见终点；每个步骤的 body、expected、explanation 分别描述操作、现象和解释，concepts 用于课末回顾。每个模块内部课时从 01 连续编号；不保存教师视图或录制时长字段。
• app/review-page.tsx、app/review-state.ts、app/review.css：复盘页面及本地自评记录。ReviewLesson 与教学课件分开建模，包含原模块、理解问题、情境题、参考要点、回学课时和掌握证据。
• app/demos.tsx、app/task-delivery-demo.tsx：浏览器内概念演示。模型演示不发送实际后端请求。
• app/globals.css：正文、导航和响应式样式。
• public/brand/：从 shuh.ai 下载的原始 Logo、favicon 和来源记录。
• scripts/build-course-content.mjs：验证课件结构、课时数、自学起点、逐步观察与解释、生产练习字段及文档链接格式，全部验证通过后生成各模块 Markdown 下载；理论课另外验证面试问答，并禁止代码和生产演练字段。
• scripts/check-self-study.mjs：检查前九个技术模块的下载课件是否保持问题在前、操作先于现象和解释、核心概念在最后的阅读顺序，并逐段核对内容没有在导出时丢失。
• scripts/review-content.mjs、scripts/check-review.mjs：校验九模块覆盖、问题与证据数量、回学链接和原标题，生成复盘讲义，并检查参考答案后置、自评门槛、本地恢复、模块隔离及损坏记录处理。

增加课时后同步修改目录数量；分组从每节 group 字段自动生成。修改内容后运行：

npm run content
node scripts/check-self-study.mjs
node --experimental-strip-types scripts/check-review.mjs
python scripts/check-python-snippets.py
node --experimental-strip-types scripts/test-course-navigation.mjs
node --experimental-strip-types scripts/check-course-diagrams.mjs
npm exec tsc -- --noEmit
npm run build

接入视频

在 app/videos.json 中使用“模块标识/课时编号”作为键。未配置视频时，不显示播放器或空占位。旧 API 编号键仍兼容。

{
  "api/01": { "type": "file", "url": "/videos/api-01.mp4" },
  "database/01": {
    "type": "link",
    "url": "https://你的课程平台/实际视频地址",
    "title": "MySQL 练习环境"
  }
}

file 用于浏览器支持的 MP4/WebM 文件，可用 captions 指定 WebVTT 中文字幕地址；link 在视频平台打开。视频文件放在 public/videos/，或使用可访问的 HTTPS 媒体地址。这里不提供上传、转码或视频平台授权功能。

实战代码与验证边界

examples/ 和 public/downloads/api-lab.zip 是已运行验证的 FastAPI 商品服务基础项目，包含 41 项测试。其接口不自动包含后续课程新增的 ORM、队列和部署配置。本次运行环境与此前 requirements.txt 锁定环境存在版本差异，实际版本和真实网络验收见 examples/VERIFICATION.md。

后续模块在课件中按步骤创建和演进 shop-service，提供 SQL、Python、Compose、systemd 和 Nginx 等示例。模块 Markdown 可从网页下载。代码片段必须遵循每一步的文件路径、前置定义和替换说明，不能全部无差别追加到一个文件。外部服务实验需要学员具备对应环境。

自学编排校验覆盖全部 110 节课的准备说明、每步操作/观察/解释及末尾回顾，并逐段核对下载讲义。API 第 01 课的健康检查、文档入口和修改返回值使用 TestClient 验证；第 16 课前四步的测试逐段运行，累计结果为 1、2、4、6 项通过。浏览器抽查覆盖九个模块，确认步骤展示、图解位置和原有概念锚点可用。这些检查不代替全部外部服务实验的运行验证。

本次电商改版在隔离的 MySQL 8.4.11 容器实测了商品/分类/关联表 DDL、默认值、非法价格、时间与版本更新、唯一约束、外键、RESTRICT/CASCADE 和组合索引。缓存课件使用内存适配器验证商品字段往返、非法金额和坏缓存恢复；任务第 08/09 课直接调用导出函数，验证含价格的商品快照和重复执行。本次未重跑完整 ORM 迁移、Celery 拓扑、Ubuntu/systemd 发布或全部故障演练；此前底层 MySQL 事务隔离、并发锁、任务 outbox、排障 SQL 与备份恢复记录不等于本次改版全链路实测。Python 3.11 语法检查与实际运行验证分别统计。

内容校验、课时导航、38 幅图解校验、TypeScript 检查和生产构建通过。本次涉及的 app/ lint 通过；全库 lint 仍报告 19 处未修改的基础组件及 hook 问题。

数据库统一使用 MySQL 8.4 LTS、InnoDB 和 utf8mb4。API 使用 SQLAlchemy 2 + asyncmy；同步数据库、缓存和任务示例使用 PyMySQL。时间统一按 UTC 写入 DATETIME(6)，课程区分 MySQL 默认 REPEATABLE READ 与应用显式 READ COMMITTED，并按 MySQL 处理自增主键、JSON、行锁和 DDL 隐式提交。

数据库使用独立 shop_lab，Alembic 迁移实验使用 shop_lab_migration，示例宿主端口为 MySQL 3307、Redis 缓存 6380、任务 broker 6384；Redis 容量、AOF、复制实验分别使用 6381、6382、6383。容器内部使用服务名和 3306/6379，不能把宿主地址机械复制到容器里。数据库备份、停止进程、锁等待、资源限制等故障操作均限于课件指定的隔离环境。

发布

继续使用 .openai/hosting.json 中已有 Sites 项目。发布会更新既有网页，访问范围保持现有设置。页面上线只提供课件和静态下载，不会在 Sites 中启动 MySQL、Celery 或 Python 示例服务。