stack/apps/tutorial/OUTLINE.md

全栈教程大纲（AI 时代版）

依据 [ai-era-tutorial] skill 重构：靶子先行、步骤=目标+验收产物、每步分类代理区/价值区、指派学习三样、脱靶提醒备注在指派后、认知基础就地露出、不写死任何 AI 使用规则。

教程靶子（全局）

• 目标：带着你的 agent 入门全栈 Web 开发——你负责指挥与核对，长出识别力。
• 预期结果：在你的真机上，一个「React 前端 + Node API + SQLite」的 todo 应用跑起来；每一章的产物都能对照验收，刷新页面数据还在。
• 积木清单：HTTP 请求/响应、静态文件服务、HTML 骨架、React 组件、state/props、Vite 工程、REST 路由、ORM（Prisma）、构建产物、部署容器。

六章

ch1 快速开始 🚀 —— 让第一个网页从你的服务器跑起来

• 靶子：目标＝页面由你的服务器返回，不是双击打开的文件。预期＝地址栏是 http://localhost:端口，Network 面板有一次 200。积木＝HTTP 请求/响应、静态文件服务、HTML 骨架。
• 步骤：
  1. 写第一个页面【价值区】——HTML 三件套结构就地露出。验收：浏览器渲染出标题与一句话。
  2. 起最简服务器【价值区】——积木「静态文件服务」三句话。验收：localhost 返回你的页面。
  3. 环境安装（node / 编辑器）【代理区】——交给 agent。真机验收：node -v 有版本、服务器能启动。
• 认知基础：终端、node、编辑器——第一次用到就地露出，不前置背景章。
• 指派学习：HTTP 协议。位置＝Web 通信的地基，旁边是 DNS/TCP。预期＝能向 agent 讲清一次请求的往返。场景＝看 Network 面板复述一次加载；用 curl 拿一个网页。
• 脱靶提醒：装了但没跑——命令成功、页面空白，缺「真机验收」这块积木。

ch2 React ⚛️ —— 用组件拼出可增删的 todo

• 靶子：目标＝组件化 todo。预期＝增删待办界面即时变化，不手改 DOM。积木＝组件、props、state、Vite 工程。
• 步骤：
  1. 建 Vite 工程【代理区】——交给 agent。验收：dev 服务器起来，改一行看到变化。
  2. 组件拆分【价值区】——输入框/列表/按钮各司其职。验收：删掉列表组件，其余不塌。
  3. state 驱动界面【价值区】——数据变了界面跟着变。验收：增删后不碰 DOM，界面也更新。
• 指派学习：受控 vs 非受控。位置＝表单一族。预期＝两种写法各写一遍，能说清差别。场景＝把输入框两种写法互换。
• 脱靶提醒：组件跑通但答不出「数据从哪来、到哪去」——缺 state 数据流这块。

ch3 更多示例 🧪 —— 按需专题，指派为主

• 靶子：目标＝遇到布局/效果问题，知道缺哪块积木。积木＝文档流、flex、grid（一族）。
• 指派学习：布局一族。位置＝CSS 排版。预期＝同一张卡片用三种布局各摆一遍。场景＝侧栏、居中、等宽多列。
• 脱靶提醒：抄了 CSS 能用但换张卡就摆不平——没有把「布局」当一族学。

ch4 更多 📦 —— 构建在做什么

• 靶子：目标＝看懂源码怎么变成产物。预期＝能指出 dist 里每个文件对应源码哪部分、说清 dev 与 prod 的差别。积木＝打包、静态产物。
• 步骤：
  1. 构建并解剖产物【价值区】——验收：dist 文件与源码逐个对上。
  2. 部署脚本【代理区】——交给 agent。验收：产物在静态服务器上可访问。
• 认知基础：dev server 与构建产物的差别，就地露出。

ch5 全栈基础 🌐 —— 接上数据库与 API（旧仓库空栏目，本章新写）

• 靶子：目标＝todo 数据存下来。预期＝刷新页面数据还在；API 返回 JSON；数据落在 SQLite 文件。积木＝REST 路由、ORM（Prisma）、联调（CORS）。
• 步骤：
  1. 设计 API【价值区】——GET/POST/DELETE /todos。验收：curl 三条全通。
  2. 建 Prisma 工程【代理区】——交给 agent。验收：migration 生成、库文件出现。
  3. 前后端联调【价值区】——CORS 三句话。验收：前端读写走 API，Network 可见请求。
• 指派学习：数据库迁移一族。位置＝schema 演进。预期＝加一个字段走完迁移全流程。场景＝给 todo 加截止日期。
• 脱靶提醒：前端直连数据库「也能跑」——架构上少了 API 这层，撞上并发/换端就疼。

ch6 高级教程 🧠 —— 识别力专题

• 靶子：目标＝读得懂 agent 给的代码，错的你看得出来。积木＝数据流、纯函数、协作流程。
• 素材：data_flow（状态从哪来到哪去）、pure_function（什么函数值得信赖）、协同编程探索。
• 验收：每个专题拿一段 agent 生成的代码，能指出数据流向与不纯之处。

与旧教程的映射

新章	旧素材
ch1	web/hello_world（first_page / simple_server / use_vscode）
ch2	web/hello_react（create_react_app / how_react_start / start_react_app / todo_app）
ch3	web/more_example（float）
ch4	web/more（build）
ch5	无（旧 full-stack 空壳）——全新写
ch6	advance（data_flow / pure_function / 协同编程探索）

旧 web/archive（垃圾桶 9 篇）不迁移。

站点结构（apps/tutorial，Vite MPA）

• index.html——课程书架：六章 CourseCard + RouteLine 推荐线 + 三画像入口 + 进度票券
• ch1.html … ch6.html——章节页：章头靶子卡（▲○●）→ 步骤列（价值区荧光标记 / 代理区波浪）→ 积木三句话 → 指派块（位置/预期/场景＋脱靶）→ 认知基础
• 页面切换用 Cross-document View Transitions（@view-transition { navigation: auto }）避免 MPA 白屏闪烁；书架相框 ↔ 章节页章头做同名共享元素变形（view-transition-name: ch-<id>）；prefers-reduced-motion 下禁用。