Web 前端进阶（Vue/React 双版本）

📄 教程规格与维护指南（BLUEPRINT） BLUEPRINT.md✓ 标记已学

本文件是《Web 前端开发进阶教程（Vue / React 双版本）》的唯一规格基准。 所有章节作者（人与 AI）写章节前必须通读本文件并严格遵守。 后续维护者增补章节时，也以本文件为准，保证两版始终一一对应。

1. 项目定位

• 目标读者：从初级程序员到企业级资深开发的前端工程师；也适合需要「双栈对照」的团队（一部分人写 Vue，一部分人写 React）。
• 交付形态：两套完全独立的 Markdown 教程——vue-edition/ 与 react-edition/，两版章节编号、目录结构、实战任务、自查清单一一对应，可逐章对照学习。
• 组织方式：四个阶段递进
  • 第一部分 · 初级阶段：基础语法与组件化开发（第 01–06 章）
  • 第二部分 · 中级阶段：状态管理、路由与服务端交互（第 07–12 章）
  • 第三部分 · 高级阶段：性能优化、测试与工程化（第 13–18 章）
  • 第四部分 · 资深阶段：架构设计、团队协作与技术选型（第 19–24 章）
• 贯穿项目：企业级 B2B 订单管理 SaaS「轻订单」（详见根目录《附录A-贯穿项目「轻订单」需求说明书.md》）。四个阶段共用同一业务域：门户首页 → 中后台管理系统 → 性能与质量治理 → 架构演进，确保练习是真实企业场景而非玩具 demo。

2. 目录结构（最终交付物）

frontend-vue-react-tutorial/
├── README.md                          # 总览：两版对照使用说明
├── BLUEPRINT.md                       # 本文件（规格与维护指南）
├── 附录A-贯穿项目「轻订单」需求说明书.md   # 两版共用业务需求
├── vue-edition/
│   ├── 00-导读.md
│   ├── part1-junior/
│   │   ├── 01-走进Vue3-框架概览与环境搭建.md
│   │   ├── 02-模板语法与数据绑定.md
│   │   ├── 03-组件化开发基础.md
│   │   ├── 04-响应式系统核心.md
│   │   ├── 05-生命周期与组件通信.md
│   │   ├── 06-初级实战-企业门户首页.md
│   │   └── 阶段自查-初级能力清单.md
│   ├── part2-intermediate/
│   │   ├── 07-路由系统-VueRouter全解.md
│   │   ├── 08-状态管理-Pinia实战.md
│   │   ├── 09-服务端交互与接口层设计.md
│   │   ├── 10-表单处理与校验.md
│   │   ├── 11-登录鉴权与权限控制.md
│   │   ├── 12-中级实战-轻订单管理系统.md
│   │   └── 阶段自查-中级能力清单.md
│   ├── part3-advanced/
│   │   ├── 13-渲染性能优化.md
│   │   ├── 14-加载性能优化.md
│   │   ├── 15-组件测试.md
│   │   ├── 16-E2E测试与质量保障.md
│   │   ├── 17-工程化实践-TypeScript与Vite.md
│   │   ├── 18-CICD部署与前端监控.md
│   │   └── 阶段自查-高级能力清单.md
│   ├── part4-senior/
│   │   ├── 19-大型项目架构设计.md
│   │   ├── 20-设计系统与组件库建设.md
│   │   ├── 21-微前端与跨团队协作.md
│   │   ├── 22-团队协作规范.md
│   │   ├── 23-技术选型决策.md
│   │   ├── 24-资深实战-技术方案与架构评审.md
│   │   └── 阶段自查-资深能力清单.md
│   └── appendix/
│       ├── 附录B-面试题精选.md
│       └── 附录C-学习路线图与资源.md
└── react-edition/
    ├── 00-导读.md
    ├── part1-junior/
    │   ├── 01-走进React-框架概览与环境搭建.md
    │   ├── 02-JSX与渲染模型.md
    │   ├── 03-组件化开发基础.md
    │   ├── 04-Hooks核心.md
    │   ├── 05-副作用生命周期与组件通信.md
    │   ├── 06-初级实战-企业门户首页.md
    │   └── 阶段自查-初级能力清单.md
    ├── part2-intermediate/
    │   ├── 07-路由系统-ReactRouter全解.md
    │   ├── 08-状态管理-ReduxToolkit与Zustand.md
    │   ├── 09-服务端交互与TanStackQuery.md
    │   ├── 10-表单处理与校验.md
    │   ├── 11-登录鉴权与权限控制.md
    │   ├── 12-中级实战-轻订单管理系统.md
    │   └── 阶段自查-中级能力清单.md
    ├── part3-advanced/                  # 13–18 与 vue-edition 同名
    ├── part4-senior/                    # 19–24 与 vue-edition 同名
    └── appendix/
        ├── 附录B-面试题精选.md
        └── 附录C-学习路线图与资源.md

文件命名规则：全小写目录名（part1-junior 等）；文件名 两位章节号-短标题.md；两版编号必须一致；文件名不得含空格；编码 UTF-8（无 BOM）。

3. 章节总表与每章内容要点

「要点」是该章必须覆盖的最低知识面。作者可自行加深，不得缺项。

第一部分 · 初级阶段（基础语法与组件化开发）

第二部分 · 中级阶段（状态管理、路由与服务端交互）

第三部分 · 高级阶段（性能优化、测试与工程化）

第四部分 · 资深阶段（架构设计、团队协作与技术选型）

阶段自查清单（4 个文件/版）

• 命名固定：阶段自查-初级能力清单.md 等，两版同名。
• 结构：① 阶段画像（这个阶段的工程师在企业里能做什么）② 能力清单 12–16 条，按「能独立完成 / 能讲清原理 / 能落地规范」三组，用 - [ ] 复选框 ③ 每条注明「未达标 → 回看第 X 章 §Y」④ 一份 30 分钟自测小考（5–8 题，附答案折叠块 <details>）⑤ 升级下一阶段的判断标准。

附录

• 附录B-面试题精选.md：对应四阶段各 6–8 题，含考察点、参考答案要点（<details> 折叠）、两版差异化题（框架原理题必须针对本框架）。
• 附录C-学习路线图与资源.md：ASCII 学习路线图；官方文档与权威资料清单（只列稳定、长期维护的官方资源）；本教程与路线图的章节映射表。

4. 单章写作模板（强制）

# 第 XX 章 · 章节标题

> 📍 **阶段**：初级阶段（第 1–6 章）｜⏱ 预计学时：X 小时｜🔗 前置：第 X 章
>
> [⬅ 上一章](相对链接) ｜ [📖 本版目录](../00-导读.md) ｜ [➡ 下一章](相对链接)
>
> 💡 **对照学习**：本页是 *Vue 版*第 XX 章。React 版对应章节为 [第 XX 章](../../react-edition/partX-xxx/XX-xxx.md)，概念映射：Vue 的「A」≈ React 的「B」。

## 🎯 学习目标

学完本章，你将能够：
1. （可验证的行为动词：说出/搭建/封装/排查/设计……）
2. …（5–8 条）

## 📖 核心知识点

### 4.1 小节标题
（概念 → 为什么 → 怎么做 → 代码 → 图示/表格）

## 🛠 渐进式实战练习

### 练习 1 · 基础（10–20 min）
### 练习 2 · 进阶（30–60 min）
### 练习 3 · 挑战（选做，60+ min）

（每题给「任务描述 + 提示 + 验收标准」，关键处给参考答案 <details> 折叠）

## ⚠️ 常见易错点

（❌ 错误代码 + 错误现象/原因 → ✅ 正确写法；每章 ≥4 个）

## ✅ 最佳实践

（企业级落地建议，编号列表，每条一两句「为什么」）

## 📌 本章小结

（3–5 条要点 + 下一章预告一两句）

硬性要求：

• 每章 450–700 行（Markdown 行数）；代码块总行数占比 ≥ 35%。
• 六大板块标题一字不差（便于全书检索）：## 🎯 学习目标、## 📖 核心知识点、## 🛠 渐进式实战练习、## ⚠️ 常见易错点、## ✅ 最佳实践、## 📌 本章小结。
• 代码围栏语言标注：Vue 用 vue（或 ts/js/bash）；React 用 tsx/jsx（或 ts/bash）。代码必须语法正确、可直接运行（配合本章语境），命名与业务词贴合「轻订单」。
• 导航链接：章与章之间用相对路径（06-xxx.md、../part2-intermediate/07-xxx.md）；引用根附录用 ../../附录A-贯穿项目「轻订单」需求说明书.md。
• 章内小节编号 ## 4.1 形式只在「核心知识点」内使用（编号 = 章号.小节号）。

5. 技术栈基线（两版对照）

安全红线（全教程适用）：任何代码示例不得出现真实凭据、token、密钥字面量；一律使用环境变量（import.meta.env.VITE_* / process.env.*）或 <your-token> 类占位符。示例中的测试账号一律 demo@qingorder.com 这类虚构值。

写作口径：不贬低另一框架；对比时给事实与适用条件；涉及「两版差异」处使用对照表而非散文。凡引用官方行为（API 签名、默认值），以官方文档为准，不杜撰 API；不确定的 API 细节改为讲原理+给官方链接。

6. 验收标准（章节作者自查）

1. 文件路径、文件名与第 2 节完全一致。
2. 六大板块齐全、标题一字不差；学习目标 5–8 条且可验证。
3. 每章含 ≥3 个渐进式练习（基础/进阶/挑战），每个有验收标准。
4. 易错点 ≥4 组，均有 ❌/✅ 对照代码。
5. 行数 450–700，代码占比 ≥35%，围栏语言已标注。
6. 导航块、对照学习框存在且链接可达（相对路径正确）。
7. 无真实凭据字面量。
8. 实战任务与《附录A》业务一致（订单/客户/商品/报表领域词）。

7. 维护指引

• 新增章节：先在本文件登记（编号、两版标题、要点、目录位置），再动笔，保持两版同步。
• 版本升级（如 React 20/Vue 4）：只改受影响章节并在本文件记录变更日志。
• 变更日志：
  • 2026-09-29 初版定稿（24 章 × 2 版 + 4 清单 × 2 版 + 附录 B/C × 2 版 + 共用附录 A）。

📄 附录 A · 贯穿项目「轻订单」需求说明书 附录A-贯穿项目「轻订单」需求说明书.md✓ 标记已学

本附录是 Vue 版与 React 版教程共用的业务需求基准。所有阶段的实战练习都围绕本项目展开，两版教程的练习任务保持一致，因此对照学习时可以精确比较「同一个需求，两种框架怎么落地」。

「轻订单」是虚构公司「青云科技」的内部 SaaS 产品，所有名称、数据、接口均为教学虚构。

1. 产品背景

青云科技是一家做智能硬件的 B2B 公司，销售渠道包括直销、代理商与电商代运营。随着订单量增长，原来靠 Excel + 微信群接单的方式出了三类高频事故：

1. 漏单：微信里的订单没人跟进；
2. 改单无痕：折扣随便改，财务对不上账；
3. 权限混乱：实习生能改全公司的价格。

于是立项「轻订单」：一个面向内部员工的 B2B 订单管理系统，分两期交付：

• 一期 · 官网门户：面向潜在客户的品牌官网（首页、产品介绍、联系方式），用于获客；
• 二期 · 管理后台：面向内部员工的中后台系统，覆盖订单全生命周期。

2. 角色与权限模型

权限按三级控制：

1. 菜单级：不同角色登录后侧边栏菜单不同；
2. 页面级：直接输入 URL 访问无权限页面时拦截到 403 页；
3. 按钮级：例如「删除订单」按钮仅 super_admin 与 operator 可见；「折扣审批」按钮仅 finance 可见。

3. 功能模块清单

3.1 认证与个人中心

• 账密登录（含图形验证码，输错 5 次锁定 10 分钟）；
• JWT 鉴权：accessToken（2 小时）+ refreshToken（7 天），支持无感刷新；
• 个人中心：修改密码、查看本人操作日志。

3.2 工作台（Dashboard）

• 今日概览卡片：今日新增订单数、待审核数、本月 GMV、异常订单数；
• 近 30 天订单量与 GMV 趋势折线图；
• 我的待办：待我审批 / 待我跟进的订单列表（前 10 条）。

3.3 订单管理（核心模块）

订单状态机：

草稿 draft → 待审核 pending_review → 已审核 approved → 已发货 shipped → 已完成 completed
                    │
                    └─审核拒绝 rejected → （可编辑后重新提交）
任何非终态 → 已取消 cancelled（只能取消人本人或超管操作，需填原因）

• 列表页：分页（20/页）、筛选（关键词、状态、日期区间、销售归属）、排序（创建时间/金额）；
• 详情页：基本信息、明细行、操作日志时间线、状态流转按钮；
• 新建/编辑订单：
  • 选择客户（搜索下拉）→ 添加明细行（商品搜索、数量、单价、行折扣）；
  • 明细金额 = 数量 × 单价 × 行折扣，订单总额自动汇总；
  • 整单折扣 >10% 时提交后进入 pending_review，需财务审批；
  • 表单校验：数量 1–9999、行折扣 0–100%、必填项即时校验。
• 批量操作：批量导出选中订单为 CSV；批量指派销售（仅超管/运营）。

3.4 客户管理

• 客户列表（名称/等级/所属销售筛选）；
• 客户详情：基本信息、历史订单、应收账款汇总；
• 新建客户：统一社会信用代码格式校验、去重校验（后端返回 409 时前端提示）。

3.5 商品目录

• 商品列表（SKU、名称、分类、单价、上下架状态）；
• 上下架切换；商品仅超管/运营可编辑。

3.6 报表中心

• 销售报表：按销售/按月/按商品维度聚合；
• 导出 Excel（前端请求导出接口，展示进度条，完成后触发下载）。

3.7 系统设置（仅超管）

• 成员管理：增删改查、角色分配、停用；
• 操作日志查询。

4. 非功能需求（性能与质量目标）

5. 接口约定（教学用约定，前后端以此对齐）

• Base URL：https://api.qingorder.example.com/api/v1（开发期用 Vite 代理指向本地 mock）；
• 认证：Authorization: Bearer <accessToken>；
• 统一响应体：

{
  "code": 0,
  "message": "ok",
  "data": { }
}

• code 语义：0 成功；4xx01 参数错误；40101 未登录；40102 token 过期；40301 无权限；40901 资源冲突；5xxxx 服务端错误；
• 分页响应：data: { list: [...], total: 0, page: 1, pageSize: 20 }；
• 错误处理约定：业务错误 toast 展示 message；40102 触发无感刷新；40301 跳转 403 页。

核心实体（TypeScript 口径，两版通用）：

type OrderStatus =
  | 'draft' | 'pending_review' | 'approved'
  | 'shipped' | 'completed' | 'rejected' | 'cancelled';

interface OrderItem {
  skuId: string;
  skuName: string;
  quantity: number;        // 1–9999
  unitPrice: number;       // 单位：分，避免浮点误差
  discountPercent: number; // 0–100，100 表示无折扣
}

interface Order {
  id: string;
  orderNo: string;          // 规则：QO + yyyyMMdd + 6 位序号
  customerId: string;
  customerName: string;
  ownerName: string;        // 归属销售
  status: OrderStatus;
  items: OrderItem[];
  wholeDiscountPercent: number; // 整单折扣，≤90 才免审批
  totalAmount: number;          // 单位：分
  createdAt: string;            // ISO 8601
}

💡 金额单位用「分」是真实企业惯例，教程会在易错点中专门讲浮点求和陷阱。

6. 各阶段里程碑映射

7. 教学口径说明

• 后端与数据库不是本教程主角：练习阶段统一使用 Mock 数据（教程内给出 mock 方案），接口约定以上文为准，保证两版教程、前后章节的数据形状完全一致；
• 所有公司、人名、账号均为虚构；示例邮箱统一使用 *@qingorder.example.com；
• 教程代码以「能被同事接手」为质量底线：命名可读、关键逻辑有注释、魔法数字收敛为常量。

📄 React 版 · 导读 00-导读.md✓ 标记已学

欢迎来到《Web 前端开发进阶教程》React 版。本版基于 React 19（仅函数组件 + Hooks），带你从初级程序员一路走到企业级资深开发。如果你同时也在学 Vue，本教程有章节一一对应的 Vue 版，可以逐章对照（见「双栈对照学习」）。

1. 技术栈基线

版本号会持续演进，具体 API 以官方文档为准；教程讲解的是长期稳定的核心概念与工程方法。

2. 章节地图

3. 每章的固定结构

1. 🎯 学习目标：5–8 条可验证的能力描述；
2. 📖 核心知识点：概念 → 为什么 → 怎么做 → 可运行代码；
3. 🛠 渐进式实战练习：基础 / 进阶 / 挑战三档，均附验收标准；
4. ⚠️ 常见易错点：❌/✅ 对照代码，全部来自企业代码评审高频问题；
5. ✅ 最佳实践：可直接落进团队规范的条目；
6. 📌 本章小结：要点回顾 + 下一章预告。

4. 贯穿项目：「轻订单」

全书所有练习围绕虚构企业级 SaaS「轻订单」展开（B2B 订单管理系统）。四个阶段在同一业务上递进：门户首页 → 中后台系统 → 性能与质量治理 → 架构演进。开工前请先通读 附录A（约 15 分钟），里面有你写练习时要反复使用的角色、状态机、接口约定与 TypeScript 实体。

5. 双栈对照学习（可选）

本教程与 Vue 版章节完全对应（同编号、同练习、同自查清单）。每章开头有「💡 对照学习」框，标注本章概念与 Vue 的对应关系，例如：

6. 环境准备清单（开工前完成）

• [ ] Node.js 20 LTS 及以上：node -v
• [ ] pnpm 9+：npm i -g pnpm && pnpm -v
• [ ] VS Code + 插件：ESLint、Prettier（可选： React Developer Tools 浏览器扩展）
• [ ] Chrome + React Developer Tools 扩展
• [ ] Git 基础（第四部分会讲团队协作规范，但克隆/提交要会）

7. 学习节奏建议

• 在职自学：每周 6–8 小时，初级约 3 周、中级约 5 周、高级约 6 周、资深约 4 周（含练习）。
• 突击面试：按阶段读「学习目标 + 易错点 + 自查清单」，配合附录 B 面试题定向突破。
• 团队内训：直接以各阶段「渐进式实战练习」为作业，自查清单作为结业考核。

准备好了？打开 第 01 章 · 走进 React。

📄 第 01 章 · 走进 React —— 框架概览与环境搭建 01-走进React-框架概览与环境搭建.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：3 小时｜🔗 前置：导读

⬅ 上一章：导读 ｜ 📖 本版目录 ｜ ➡ 下一章：JSX 与渲染模型

💡 对照学习：本页是 React 版第 01 章，对应 Vue 版第 01 章 · 走进 Vue3。概念映射：createRoot().render(<App />) ≈ createApp(App).mount('#app')、App.jsx ≈ App.vue、React Developer Tools ≈ Vue Devtools。两版的环境搭建与目录解读思路一致，差异集中在「入口文件写法」与「组件文件形态」上。

🎯 学习目标

学完本章，你将能够：

1. 用「轻订单」项目里的三类真实事故，说出框架三件武器（声明式 UI、组件化、状态驱动更新）分别解决了什么问题；
2. 区分 MPA 与 SPA 的加载与交互模型，说清 React 应用从 index.html 到可见页面的完整渲染链路；
3. 使用 Vite 脚手架创建 React 项目，用 pnpm 安装依赖并启动开发服务器；
4. 逐项解读 Vite React 模板的目录结构，并向同事解释入口文件 main.jsx 三行核心代码的职责；
5. 修改组件内容并验证热更新（HMR）生效，说出 HMR 相比整页刷新对开发效率的意义；
6. 安装并使用 React Developer Tools 浏览器扩展，在组件树中定位目标组件并查看其 props；
7. 完成「接手『轻订单』仓库的第一天」企业场景任务，产出一份可复用的接手清单页面。

📖 核心知识点

1.1 为什么需要框架：从三起「轻订单」事故说起

先读一遍贯穿项目需求：附录A。青云科技立项「轻订单」的起因是三类事故：漏单、改单无痕、权限混乱。把它们翻译到前端视角，就是三类高频工程问题：

没有框架时，你用「命令式」代码一步步指挥浏览器，每处状态变化都要手工更新 DOM：

// 命令式（jQuery 时代的写法）：自己动手，一步一步改 DOM
const listEl = document.querySelector('#order-list');

fetch('/api/orders?status=pending_review')
  .then((res) => res.json())
  .then((data) => {
    listEl.innerHTML = ''; // 第 1 步：清空（忘了这步就会重复叠加）
    data.list.forEach((order) => {
      const li = document.createElement('li'); // 第 2 步：手动造节点
      li.className = 'tag tag--pending';
      li.textContent = `${order.orderNo} 待审核`;
      listEl.appendChild(li); // 第 3 步：手动插入（位置插错就是事故）
    });
  });

React 的思路是反过来：你只「声明」界面在当前数据下应该长什么样，数据一变，框架负责算出最小 DOM 改动并执行：

// 声明式（React）：只描述「待审核订单列表长什么样」
function PendingOrderList({ orders }) {
  return (
    <ul id="order-list">
      {orders.map((order) => (
        <li key={order.id} className="tag tag--pending">
          {order.orderNo} 待审核
        </li>
      ))}
    </ul>
  );
}
// orders 变化时，React 自动算出最小 DOM 改动，无需手工同步

React 用「虚拟 DOM + 协调（reconciliation）」来找出两次渲染之间的差异，直觉解释见第 02 章 §2.7；原理细节以官方文档 react.dev/learn 为准。

1.2 SPA、MPA 与 React 的渲染心智模型

React 应用默认是 SPA。它从「一张 HTML」到「完整页面」的链路如下：

浏览器请求 index.html
      │  （SPA 只有一张「壳」HTML）
      ▼
加载 /src/main.jsx ──► createRoot(#root).render(<App />)
      ▼
React 渲染组件树：<App /> → <NavBar /> → <Banner /> → ...
      ▼
此后所有交互都在 JS 里完成，页面不再整页刷新

「服务端渲染（SSR）/ 静态生成」能让 SPA 的首屏更快，属于资深阶段的内容，本章只需知道 SPA ≠ 只能客户端渲染。

1.3 环境搭建：Node + pnpm + Vite

先确认工具链版本（Node 20 LTS 起，包管理用 pnpm，与全书技术栈基线一致）：

# 1. 确认 Node 版本（20 LTS 及以上）
node -v

# 2. 安装 pnpm（本书统一使用 pnpm 管理依赖）
npm i -g pnpm
pnpm -v

# 3. 用 Vite 官方脚手架创建 React 项目（react 模板 = JavaScript + JSX）
npm create vite@latest qingorder-portal -- --template react

# 4. 进入项目，安装依赖并启动
cd qingorder-portal
pnpm install
pnpm dev

终端输出类似：

  VITE v6.x  ready in 312 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

打开 http://localhost:5173，看到 Vite + React 的默认页面，说明环境就绪。仓库会提交一个 pnpm-lock.yaml，它锁定依赖版本，保证团队每个人装到的依赖完全一致。

1.4 项目结构逐项解读：接手「轻订单」仓库的第一天

qingorder-portal/
├── index.html              # 唯一的 HTML：SPA 的「壳」，含 #root 挂载点
├── package.json            # 依赖清单与脚本（dev / build / lint / preview）
├── vite.config.js          # Vite 配置：插件、端口、开发代理
├── eslint.config.js        # ESLint 9 扁平配置（含 react / react-hooks 规则）
├── public/                 # 原样拷贝的静态资源（favicon 等，不参与打包）
│   └── vite.svg
└── src/
    ├── main.jsx            # JS 入口：createRoot + 挂载 <App />
    ├── App.jsx             # 根组件：整个页面从这里「长」出来
    ├── App.css             # 根组件的局部样式
    ├── index.css           # 全局样式（重置、字体、CSS 变量）
    └── assets/             # 参与打包的静态资源（图片、字体等）
        └── react.svg

逐个打开关键文件。index.html——整张应用只有这一张 HTML：

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>轻订单 · 青云科技</title>
  </head>
  <body>
    <!-- SPA 的挂载点：React 会把整棵组件树渲染进这个 div -->
    <div id="root"></div>
    <!-- type="module" 让浏览器以 ES Module 方式加载入口，Vite 在此接管 -->
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

src/main.jsx——JS 世界的入口，三行核心代码各司其职：

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.jsx';

// 1. 找到挂载点，创建 React 根
createRoot(document.getElementById('root')).render(
  // 2. StrictMode 只在开发环境生效：主动暴露不安全的写法（第 05 章详解）
  <StrictMode>
    {/* 3. 渲染根组件：整个应用都是 <App /> 的子树 */}
    <App />
  </StrictMode>,
);

vite.config.js——构建工具的配置，本章重点认识开发代理：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    // 开发期把 /api 代理到本地 mock 服务，避免浏览器跨域（附录A 接口约定）
    proxy: {
      '/api': {
        target: 'http://localhost:3000', // 本地 mock 服务地址，按环境修改
        changeOrigin: true,
      },
    },
  },
});

1.5 Dev Server 与热更新（HMR）

package.json 中的脚本是日常开发的入口：

{
  "name": "qingorder-portal",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

• pnpm dev：启动开发服务器（默认 5173 端口），按需编译、秒级启动；
• pnpm build：产出生产构建（默认在 dist/）；
• pnpm preview：本地预览构建产物，验证「上线后」的样子。

现在做一个小实验：打开 App.jsx，把标题文字改掉并保存——页面不刷新就更新了。这就是 HMR（Hot Module Replacement，模块热替换）：Vite 只把被修改的那个模块推给浏览器替换，整页不重载。React 侧配合 Fast Refresh，还能在替换组件的同时保留组件当前的 state——你输入了一半的表单不会因为改了一行样式而丢失。

整页刷新 = 回到初始状态，所有现场丢失；HMR = 只换「零件」，现场保留。在中大型项目里，这个差距会按「每次保存」放大。

1.6 第一个组件：把首页骨架跑起来

把模板自带的演示内容替换成「轻订单」门户的最小骨架。先认识组件的解剖图：

// src/App.jsx
const PENDING_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸' },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造' },
];

// 一个 React 组件就是一个「返回 JSX 的函数」：
//   名字必须大写开头（区别于普通 HTML 标签）
//   入参是 props（本章先不深入，第 03 章专门讲）
function App() {
  return (
    <header className="page-header">
      <h1>轻订单 · 青云科技</h1>
      <p>让每一张 B2B 订单都被看见、被追踪、被审计。</p>
      <ul className="pending-list">
        {PENDING_ORDERS.map((order) => (
          <li key={order.id}>
            {order.orderNo} · {order.customerName}
          </li>
        ))}
      </ul>
    </header>
  );
}

export default App;

保存后浏览器自动更新。这里的 {...} 花括号语法、map 渲染列表的细节就是第 02 章的主角，本章先「照着写、跑起来」。

1.7 官方调试工具：React Developer Tools

1. 在 Chrome / Edge 应用商店安装扩展 React Developer Tools（React 官方出品）；
2. 打开你的页面，按 F12，面板里会多出 Components 和 Profiler 两个标签页。

Components 面板能力（企业里天天用）：

• 以树状结构查看组件层级，等价于把「设计稿 → 组件树」的关系可视化；
• 点击任意组件，右侧可查看它的 props、hooks 状态、所属文件（点击可跳转源码）；
• 顶部搜索框可直接按组件名过滤，接手陌生仓库时先靠它建立全局感。

Profiler 面板用于录制「哪些组件因什么原因重渲染」，是第 13 章性能优化主角，初级阶段知道即可。

企业场景：接手「轻订单」仓库的第一天，按这个顺序走一遍，半天即可建立掌控感：

① 跑通：pnpm install && pnpm dev，确认页面能打开
② 读壳：index.html → main.jsx → App.jsx，画出入口链路
③ 认树：React DevTools 里从 <App /> 往下展开组件树，截图存档
④ 找配置：vite.config.js 的代理指向哪、.env 系列文件里有哪些约定
⑤ 读规范：README、目录约定、ESLint 规则——先遵守，再谈改进

🛠 渐进式实战练习

练习 1 · 基础（15 min）：跑通「轻订单」门户骨架

任务描述：从零创建 qingorder-portal 项目，把 App.jsx 的演示内容替换为「门户骨架」（标题 + 一句 slogan + 一个待办订单列表），验证热更新。

提示：

• 使用 npm create vite@latest qingorder-portal -- --template react；
• 列表数据可以直接写在组件文件顶部；
• 每次保存后观察浏览器是否「不刷新就更新」。

验收标准：

• [ ] pnpm dev 启动无报错，页面显示自定义标题与 slogan；
• [ ] 列表至少渲染 2 条订单，每条含订单号与客户名；
• [ ] 故意写错一行保存，观察报错出现在终端与浏览器控制台，再改回来。

// src/App.jsx
const PENDING_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸' },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造' },
];

function App() {
  return (
    <header className="page-header">
      <h1>轻订单 · 青云科技</h1>
      <p>让每一张 B2B 订单都被看见、被追踪、被审计。</p>
      <ul className="pending-list">
        {PENDING_ORDERS.map((order) => (
          <li key={order.id}>
            {order.orderNo} · {order.customerName}
          </li>
        ))}
      </ul>
    </header>
  );
}

export default App;

练习 2 · 进阶（30 min）：环境变量与目录改造

任务描述：企业项目不允许把接口地址写死在代码里。请：① 新建 .env.development，定义应用名与 API 地址；② 在组件里读取环境变量渲染；③ 把「订单列表」抽到 src/data/ 目录，初步实践「配置与视图分离」。

提示：

• Vite 只暴露 VITE_ 前缀的变量，代码里通过 import.meta.env.VITE_XXX 访问；
• 环境变量在构建时被静态替换，改完 .env 需要重启 dev server；
• 详细规则见官方文档：Vite · Env Variables。

验收标准：

• [ ] .env.development 中定义了 VITE_APP_NAME 与 VITE_API_BASE_URL；
• [ ] 页面标题来自环境变量，改 .env 并重启后生效；
• [ ] 订单数据移入 src/data/，App.jsx 通过 import 使用；
• [ ] 确认 .env 已被 Git 跟踪（团队共享），而含密钥的 .env.local 永远不提交。

# .env.development —— 变量必须以 VITE_ 开头才会暴露给客户端代码
VITE_APP_NAME=轻订单
VITE_API_BASE_URL=http://localhost:3000/api/v1

// src/data/orders.js —— 数据配置与视图分离
export const PENDING_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸' },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造' },
];

// src/App.jsx
import { PENDING_ORDERS } from './data/orders';

function App() {
  // import.meta.env 是 Vite 注入的环境对象；?? 提供兜底，避免变量缺失时渲染 undefined
  const appName = import.meta.env.VITE_APP_NAME ?? '轻订单';

  return (
    <header className="page-header">
      <h1>{appName} · 青云科技</h1>
      <ul className="pending-list">
        {PENDING_ORDERS.map((order) => (
          <li key={order.id}>
            {order.orderNo} · {order.customerName}
          </li>
        ))}
      </ul>
    </header>
  );
}

export default App;

练习 3 · 挑战（选做，45 min+）：产出《接手仓库第一天》页面

任务描述：把 §1.7 的「第一天清单」做成一个真实的入门页面：应用名与 API 地址读环境变量；任务清单来自 src/data/onboarding.js；页面顶部显示完成进度（如 2/4）。这个页面未来可以放进团队 wiki 的 onboarding 手册。

提示：

• 进度 = 已完成数 / 总数，用 filter + length 计算；
• 清单项先用静态只读渲染（勾选交互在第 04 章学完 useState 后回填）；
• 保持 App.jsx 只做拼装，数据与文案都在 data/ 里。

验收标准：

• [ ] 页面包含：应用名（环境变量）、API 地址（环境变量）、任务清单、进度统计；
• [ ] 任务清单由 map 渲染，每项有稳定的 key；
• [ ] 新增一条任务只需改 data/onboarding.js，组件零改动。

// src/data/onboarding.js —— 第一天任务清单（配置与视图分离）
export const ONBOARDING_TASKS = [
  { id: 't1', title: '读完附录A《轻订单》需求说明书', done: true },
  { id: 't2', title: '跑通 pnpm dev 并验证热更新', done: true },
  { id: 't3', title: '用 React DevTools 对照组件树与源码', done: false },
  { id: 't4', title: '认领第一个 issue：门户 StatusTag 组件', done: false },
];

// src/App.jsx
import { ONBOARDING_TASKS } from './data/onboarding';

function App() {
  const appName = import.meta.env.VITE_APP_NAME ?? '轻订单';
  const apiBase = import.meta.env.VITE_API_BASE_URL ?? '（未配置）';
  const doneCount = ONBOARDING_TASKS.filter((task) => task.done).length;

  return (
    <main className="welcome">
      <h1>欢迎接手 {appName}</h1>
      <p>API 地址：{apiBase}</p>
      <p>
        进度：{doneCount}/{ONBOARDING_TASKS.length}
      </p>
      <ul>
        {ONBOARDING_TASKS.map((task) => (
          <li key={task.id}>
            <label>
              <input type="checkbox" checked={task.done} readOnly />
              {task.title}
            </label>
          </li>
        ))}
      </ul>
    </main>
  );
}

export default App;

⚠️ 常见易错点

易错点 1：组件名小写开头

// ❌ 组件名小写开头：React 把 <orderCard /> 当成未知 HTML 标签
// 现象：页面空白，控制台警告 “<orderCard /> is acting as an unknown element”
function orderCard() {
  return <div>QO20260929-000001</div>;
}

function App() {
  return <orderCard />;
}

// ✅ 组件名必须大写开头，React 才会把它识别为组件
function OrderCard() {
  return <div>QO20260929-000001</div>;
}

function App() {
  return <OrderCard />;
}

易错点 2：JSX 返回多个并列根元素

// ❌ 相邻的 JSX 根元素：一个表达式只能有一个根
// 现象：编译报错 “Adjacent JSX elements must be wrapped in an enclosing tag”
function Header() {
  return (
    <h1>轻订单</h1>
    <p>让每一张订单都被看见</p>
  );
}

// ✅ 用一个父元素或 Fragment 包起来；Fragment 不会产生多余的 DOM 节点
import { Fragment } from 'react';

function Header() {
  return (
    <Fragment>
      <h1>轻订单</h1>
      <p>让每一张订单都被看见</p>
    </Fragment>
  );
}
// 简写：<h1>…</h1><p>…</p> 外面直接包 <>…</>（不需要 key 时用简写）

易错点 3：照搬 HTML 的 class / for 属性

// ❌ JSX 里写了 HTML 的 class 和 for
// 现象：控制台警告 “Invalid DOM property `class`. Did you mean `className`?”
function SearchBar() {
  return (
    <div>
      <label for="keyword">关键词</label>
      <input class="search-input" id="keyword" />
    </div>
  );
}

// ✅ 用 className / htmlFor（避免与 JS 的 class 关键字冲突）
function SearchBar() {
  return (
    <div>
      <label htmlFor="keyword">关键词</label>
      <input id="keyword" className="search-input" />
    </div>
  );
}

易错点 4：绕过 React 直接操作 DOM

// ❌ 在渲染期间手动改 DOM：下次渲染会被 React 覆盖回去，状态与视图打架
// 现象：改了又被还原，且调试时「看不出是谁改的」
function App() {
  document.getElementById('title').innerText = '被篡改的标题';
  return <h1 id="title">轻订单</h1>;
}

// ✅ 视图永远是状态的函数：想改什么，就改驱动它的数据
function App() {
  const title = '轻订单 · 企业门户';
  return <h1 id="title">{title}</h1>;
}

✅ 最佳实践

1. 脚手架起手，团队同款：新项目统一用 Vite 官方模板创建，模板自带的 ESLint 与目录结构是团队协作的最大公约数。
2. 提交锁文件：pnpm-lock.yaml 必须进 Git，保证全组依赖版本一致；Node 版本用 package.json 的 engines 字段声明。
3. 配置走环境变量：接口地址、应用名等一切随环境变化的值进 .env 系列文件；.env 共享提交，含密钥的 .env.local 加入 .gitignore 永不提交。
4. 接手仓库先「跑 + 认树」：先跑通 dev server，再用 React DevTools 建立组件树全局感，最后才逐行读源码——顺序错了效率减半。
5. 一个文件一个组件：组件文件名与组件名一致（OrderCard.jsx 导出 OrderCard），新人检索零成本。
6. 保持模板整洁：删掉脚手架的演示代码与未用资源（logo、示例样式），避免「演示残留」混入业务代码。

📌 本章小结

1. 框架的三件武器——声明式 UI、组件化、状态驱动更新——分别对应「漏单、改单无痕、权限混乱」这类真实工程问题的解法。
2. React 默认是 SPA：一张壳 HTML + createRoot 挂载 + 客户端渲染，之后不再整页刷新。
3. Vite 模板的关键链路：index.html → main.jsx（createRoot + StrictMode）→ App.jsx；vite.config.js 管插件与开发代理。
4. HMR 只替换改动模块并保留现场；React DevTools 是接手仓库时建立全局感的第一工具。
5. 环境变量一律走 .env 系列文件与 VITE_ 前缀，任何真实密钥都不允许出现在代码里。

下一章预告：你已经在页面里见过 {}、map 和 key 了。第 02 章系统拆解 JSX 的全部语法——插值、条件、列表、受控表单——并给出虚拟 DOM diff 的正确直觉。

📄 第 02 章 · JSX 与渲染模型 02-JSX与渲染模型.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：3.5 小时｜🔗 前置：第 01 章

⬅ 上一章：走进 React ｜ 📖 本版目录 ｜ ➡ 下一章：组件化开发基础

💡 对照学习：本页是 React 版第 02 章，对应 Vue 版第 02 章 · 模板语法与数据绑定。概念映射：Vue 的指令体系 ≈ JSX 的「纯表达式」写法——{{ }} ≈ { }、v-if ≈ 三元 / &&、v-for + :key ≈ map + key、v-show ≈ style.display、v-model ≈ 受控组件（value + onChange）。JSX 没有「指令」，一切皆 JavaScript 表达式。

🎯 学习目标

学完本章，你将能够：

1. 说出 JSX 中花括号里「只能写表达式、不能写语句」的规则，并解释原因；
2. 用 className、对象形式的 style 与 htmlFor 正确完成属性与样式绑定；
3. 用 onClick / onChange / onSubmit 完成事件绑定，说清「传函数引用」与「立即调用」的区别；
4. 针对不同场景在三元、&&、提前 return 三种条件渲染写法中做出正确选择；
5. 用 map + key 渲染订单列表，并解释 key 的「身份证」作用与下标作 key 的风险；
6. 用「受控组件」模式实现 React 版的 v-model，覆盖输入框、下拉框与复选框；
7. 建立虚拟 DOM diff 的正确直觉，能预测「同类型元素更新」与「不同类型元素替换」时组件状态是否保留；
8. 独立实现企业场景：订单状态标签列表与筛选栏。

📖 核心知识点

2.1 JSX 与插值：花括号里只能写表达式

JSX 看起来像 HTML，实质是 JavaScript。花括号 {} 里可以放任何表达式（有值的东西），不能放语句（if、for、声明）：

const order = { orderNo: 'QO20260929-000001', totalAmount: 128000 }; // 金额单位：分

function OrderLine() {
  return (
    <div className="order-line">
      {/* 花括号里：变量、运算、函数调用都是表达式，可以 */}
      <span className="order-line__no">{order.orderNo}</span>
      <span>金额：¥{(order.totalAmount / 100).toFixed(2)}</span>
      <span>客户：{order.customerName ?? '未填写'}</span>
    </div>
  );
}

复杂逻辑放在 JSX 外面算好，花括号只做「最后的组装」，可读性立刻上一个台阶：

function Amount({ fen }) {
  // 金额展示是高频操作：收敛成一个组件（分 → 元），全站复用
  const yuan = (fen / 100).toLocaleString('zh-CN', { minimumFractionDigits: 2 });
  return <strong className="amount">¥{yuan}</strong>;
}

2.2 属性绑定：className、htmlFor 与 style

JSX 的属性与 HTML 有几处关键差异，对照记住：

const status = 'pending_review';

function Tag() {
  const isActive = status === 'pending_review';
  return (
    <span
      // class → className；动态拼接用模板字符串
      className={`tag ${isActive ? 'tag--active' : ''}`}
      // style 接收对象，属性名用小驼峰（CSS 的 font-size → fontSize）
      // 数值型属性自动补 px（width: 120 → 120px）
      style={{ fontSize: 12, padding: '2px 8px' }}
      // data-* 与 aria-* 保持原样书写
      data-status={status}
      aria-label="订单状态：待审核"
    >
      待审核
    </span>
  );
}

「透传 props」时注意展开顺序——后写的属性生效：

function TextField(props) {
  // 默认值写在前面，调用方的同名属性写在后面即可覆盖
  return <input className="search-input" {...props} />;
}

2.3 事件绑定：onClick 与「传引用还是调用」

React 事件名用小驼峰，处理器是普通函数。最容易踩的坑是「传函数引用」与「调用函数」：

function OrderActions({ orderId }) {
  function cancel() {
    console.log('取消订单', orderId);
  }
  function approve() {
    console.log('通过审核', orderId);
  }
  return (
    <div className="order-actions">
      {/* ❌ 写成 onClick={cancel()} 会在渲染时立刻执行一次，点击反而无效 */}
      {/* ✅ 传「函数引用」：把执行时机交给点击事件 */}
      <button onClick={cancel}>取消订单</button>
      {/* ✅ 需要带参数时，用箭头函数包一层，同样把执行时机留给点击 */}
      <button onClick={() => approve()}>通过审核</button>
    </div>
  );
}

表单提交要主动阻止浏览器默认行为（整页刷新）：

function FilterForm() {
  function handleSubmit(e) {
    e.preventDefault(); // 与原生一致：拦截表单默认提交
    console.log('触发筛选');
  }
  return (
    <form onSubmit={handleSubmit}>
      <input name="keyword" placeholder="搜索订单号 / 客户名" />
      <button type="submit">筛选</button>
    </form>
  );
}

React 17 起事件对象不再池化，可以在异步回调里安全使用；事件的底层是「合成事件」统一封装，日常开发按原生事件的直觉写即可。

2.4 条件渲染：三元、&& 与提前 return

对应 Vue 的 v-if / v-else，React 有三种惯用写法，按场景选择：

// 写法一：三元 —— 两个分支二选一
function StatusBadge({ status }) {
  return status === 'pending_review' ? (
    <span className="tag tag--warning">待审核</span>
  ) : (
    <span className="tag">{status}</span>
  );
}

// 写法二：&& —— 满足条件才渲染（false / null / undefined 不渲染任何东西）
function VipMark({ isVip }) {
  return (
    <span>
      {isVip && <em className="vip-mark">VIP 客户</em>}
    </span>
  );
}

// 写法三：提前 return —— 分支多时比嵌套三元清爽得多
function StatusText({ status }) {
  if (status === 'draft') return <span className="tag">草稿</span>;
  if (status === 'pending_review') return <span className="tag tag--warning">待审核</span>;
  if (status === 'cancelled') return <span className="tag tag--danger">已取消</span>;
  return <span className="tag tag--success">进行中</span>;
}

Vue 的 v-show（隐藏但保留 DOM）对应「始终渲染 + CSS 控制显隐」：

function AdvancedFilter({ visible }) {
  // 适合频繁切换、需要保留内部输入状态的场景
  return <div style={{ display: visible ? 'block' : 'none' }}>高级筛选区</div>;
}

选择建议：用不上就不渲染（&& / 提前 return，组件卸载、状态释放）；频繁切换且要保留状态（display 显隐）。

2.5 列表渲染与 key：map 的正确姿势

对应 Vue 的 v-for + :key。map 出多少个节点，就渲染多少个；key 是每个节点的「身份证」：

const ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', status: 'pending_review' },
  { id: '1002', orderNo: 'QO20260929-000002', status: 'approved' },
  { id: '1003', orderNo: 'QO20260929-000003', status: 'shipped' },
];

function OrderList() {
  return (
    <ul className="order-list">
      {ORDERS.map((order) => (
        // key 放在这层 map 返回的最外层元素上；兄弟之间必须唯一且稳定
        <li key={order.id} className="order-item">
          <span>{order.orderNo}</span>
          <StatusText status={order.status} />
        </li>
      ))}
    </ul>
  );
}

key 的三条纪律：

1. 唯一：同一列表的兄弟节点之间不重复；
2. 稳定：重渲染前后，同一条数据的 key 不变（优先用后端主键 / 业务 ID）；
3. 不折腾：key 是给 React 用的，不要渲染到 DOM 上，也不要用随机数。

为什么不能用数组下标当 key？因为 diff 按位置对号入座：删除第 2 项后，原来的第 3 项「顶替」了第 2 项的位置，React 认为位置 2 上的元素还是原来那个——组件内部状态（输入框内容、勾选、展开）会串到错误的行上。规则：列表会插入、删除、排序，就绝不用下标。

key 还有一个进阶用途：换 key 强制重建。给输入框换一个不同的 key，React 会销毁旧的并新建，其内部状态（光标、已输入文字、文本选区）随之清空——这是「清空表单」的正规手段之一，也是 key 与 selection 状态相关的原因。

2.6 受控输入：React 版的 v-model

Vue 的 v-model 是语法糖；React 里对应「受控组件」：表单值被 React 状态「钉住」，每次输入通过 onChange 回写。value 与 onChange 成对出现：

import { useState } from 'react';

function OrderSearch() {
  const [keyword, setKeyword] = useState('');

  return (
    <form onSubmit={(e) => e.preventDefault()}>
      <label htmlFor="kw">搜索订单</label>
      {/* value 被 React 钉住 + onChange 回写 = React 版的 v-model */}
      <input
        id="kw"
        value={keyword}
        onChange={(e) => setKeyword(e.target.value)}
        placeholder="输入订单号或客户名"
      />
      <p>当前关键词：{keyword}</p>
    </form>
  );
}

下拉框与复选框的受控写法（筛选栏高频三件套）：

function StatusFilter({ status, onChange }) {
  const STATUS_OPTIONS = [
    { value: '', label: '全部状态' },
    { value: 'pending_review', label: '待审核' },
    { value: 'approved', label: '已审核' },
    { value: 'shipped', label: '已发货' },
  ];
  return (
    <select value={status} onChange={(e) => onChange(e.target.value)}>
      {STATUS_OPTIONS.map((opt) => (
        <option key={opt.value} value={opt.value}>
          {opt.label}
        </option>
      ))}
    </select>
  );
}

function OnlyMineCheck({ checked, onChange }) {
  return (
    <label>
      {/* 复选框用 checked 而不是 value，取 e.target.checked */}
      <input type="checkbox" checked={checked} onChange={(e) => onChange(e.target.checked)} />
      只看我的订单
    </label>
  );
}

2.7 渲染模型直觉：虚拟 DOM 与 diff

先建立两层认知：

① JSX 只是「描述」：编译后是一棵普通的 JS 对象树（元素树）
② 渲染是「对比 + 补丁」：
   组件函数重跑 → 得到新元素树 → 与上一次的树按层对比（diff）
   → 只把差异应用到真实 DOM

diff 的两条核心规则，决定了一个组件的状态是否保留：

一句话直觉：React 按「位置 + 类型 + key」认人，认得出就保留状态，认不出就重建。这就是 §2.5 「换 key 清空状态」能用、而下标 key 会串状态的原因。

这是面试与排错都够用的心智模型。真正的调度细节（Fiber、优先级）见官方文档 react.dev/learn/render-and-commit，第 13 章讲性能时会回来深化。

🛠 渐进式实战练习

练习 1 · 基础（15 min）：状态标签列表

任务描述：附录A 定义了订单 7 种状态（draft / pending_review / approved / shipped / completed / rejected / cancelled）。请实现 StatusTag 组件：输入 status，输出带语义色类的中文标签；再用它渲染一份含全部 7 种状态的订单列表。

提示：

• 状态 → 文案 / 颜色的映射用配置对象驱动，不要写 7 个 if；
• 未知状态要有兜底（显示原始值），不能白屏；
• 每个列表项要有稳定 key。

验收标准：

• [ ] 7 种状态全部正确渲染出中文与对应颜色类；
• [ ] 传入不存在的状态（如 'unknown'）不崩溃、有兜底展示；
• [ ] 列表项 key 使用数据 ID。

// src/data/statusMeta.js —— 状态 → 展示配置的映射表（配置驱动，别写 7 个 if）
export const STATUS_META = {
  draft: { label: '草稿', className: 'tag--default' },
  pending_review: { label: '待审核', className: 'tag--warning' },
  approved: { label: '已审核', className: 'tag--info' },
  shipped: { label: '已发货', className: 'tag--primary' },
  completed: { label: '已完成', className: 'tag--success' },
  rejected: { label: '已拒绝', className: 'tag--danger' },
  cancelled: { label: '已取消', className: 'tag--muted' },
};

// src/components/StatusTag.jsx
import { STATUS_META } from '../data/statusMeta';

function StatusTag({ status }) {
  // ?? 兜底：未知状态不崩溃
  const meta = STATUS_META[status] ?? { label: status, className: 'tag--default' };
  return <span className={`tag ${meta.className}`}>{meta.label}</span>;
}

export default StatusTag;

// src/App.jsx
import StatusTag from './components/StatusTag';

const ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', status: 'draft' },
  { id: '1002', orderNo: 'QO20260929-000002', status: 'pending_review' },
  { id: '1003', orderNo: 'QO20260929-000003', status: 'approved' },
  { id: '1004', orderNo: 'QO20260929-000004', status: 'shipped' },
  { id: '1005', orderNo: 'QO20260929-000005', status: 'completed' },
  { id: '1006', orderNo: 'QO20260929-000006', status: 'rejected' },
  { id: '1007', orderNo: 'QO20260929-000007', status: 'cancelled' },
];

function App() {
  return (
    <ul className="order-list">
      {ORDERS.map((order) => (
        <li key={order.id} className="order-item">
          <span>{order.orderNo}</span>
          <StatusTag status={order.status} />
        </li>
      ))}
    </ul>
  );
}

export default App;

练习 2 · 进阶（30–45 min）：订单筛选栏

任务描述：实现 OrderBoard：顶部一个筛选栏（关键词输入框 + 状态下拉 + 「只看我的订单」复选框），下方渲染按条件过滤后的订单列表；无匹配时显示空态「没有匹配的订单」。

提示：

• 三个筛选条件都是受控组件，状态放在 OrderBoard（最近的公共父级）；
• 过滤结果在渲染时直接派生（filter 链），先不要用任何缓存优化；
• 复选框的值是布尔，注意取 e.target.checked。

验收标准：

• [ ] 输入关键词即时过滤（订单号或客户名命中即可）；
• [ ] 状态下拉与「只看我的」复选框独立生效且可叠加；
• [ ] 过滤结果为空时展示空态，而不是渲染一个空列表。

// src/pages/OrderBoard.jsx
import { useState } from 'react';
import StatusTag from '../components/StatusTag';

const MOCK_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸', ownerName: '张晓', status: 'pending_review' },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造', ownerName: '李慕', status: 'approved' },
  { id: '1003', orderNo: 'QO20260929-000003', customerName: '星辰商贸', ownerName: '张晓', status: 'draft' },
  { id: '1004', orderNo: 'QO20260929-000004', customerName: '云杉实业', ownerName: '王砚', status: 'shipped' },
];

const CURRENT_USER = '张晓'; // 教学用：真实项目里来自登录态（第 11 章）

function OrderBoard() {
  const [keyword, setKeyword] = useState('');
  const [status, setStatus] = useState('');
  const [onlyMine, setOnlyMine] = useState(false);

  // 派生数据：渲染时直接算，三个条件链式叠加
  const filtered = MOCK_ORDERS.filter((order) => {
    const hitKeyword =
      keyword === '' ||
      order.orderNo.includes(keyword) ||
      order.customerName.includes(keyword);
    const hitStatus = status === '' || order.status === status;
    const hitOwner = !onlyMine || order.ownerName === CURRENT_USER;
    return hitKeyword && hitStatus && hitOwner;
  });

  return (
    <div className="order-board">
      <div className="order-board__filters">
        <input
          value={keyword}
          onChange={(e) => setKeyword(e.target.value)}
          placeholder="搜索订单号 / 客户名"
        />
        <select value={status} onChange={(e) => setStatus(e.target.value)}>
          <option value="">全部状态</option>
          <option value="draft">草稿</option>
          <option value="pending_review">待审核</option>
          <option value="approved">已审核</option>
          <option value="shipped">已发货</option>
        </select>
        <label>
          <input
            type="checkbox"
            checked={onlyMine}
            onChange={(e) => setOnlyMine(e.target.checked)}
          />
          只看我的订单
        </label>
      </div>

      {filtered.length === 0 ? (
        <p className="empty">没有匹配的订单</p>
      ) : (
        <ul className="order-list">
          {filtered.map((order) => (
            <li key={order.id} className="order-item">
              <span>{order.orderNo}</span>
              <span>{order.customerName}</span>
              <span>{order.ownerName}</span>
              <StatusTag status={order.status} />
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

export default OrderBoard;

练习 3 · 挑战（选做，60 min+）：排序 + 关键词高亮

任务描述：在练习 2 基础上追加：① 排序切换（按创建时间 / 按金额）；② 列表中订单号与客户名的命中片段高亮（<mark>）；③ 高亮要正确处理「多次命中」。

提示：

• 排序前先浅拷贝数组（sort 会原地修改）；
• 高亮思路：text.split(keyword) 切片，切片之间插 <mark>，注意用 Fragment 包住 map 的输出；
• 渲染文本时 React 会自动转义，不用担心注入。

验收标准：

• [ ] 排序切换后列表顺序正确，且原数组未被改动；
• [ ] 关键词命中的片段全部高亮，未命中时列表原样展示；
• [ ] map 中需要 key 的位置都补上了 key（含 Fragment）。

import { Fragment, useState } from 'react';
import StatusTag from '../components/StatusTag';

function Highlight({ text, keyword }) {
  if (!keyword || !text.includes(keyword)) return text;
  const parts = text.split(keyword);
  return (
    <>
      {/* 切片数量随输入变化、无稳定 ID，此处用下标作 key 是可接受的例外 */}
      {parts.map((part, i) => (
        <Fragment key={i}>
          {part}
          {i < parts.length - 1 && <mark>{keyword}</mark>}
        </Fragment>
      ))}
    </>
  );
}

function OrderBoard() {
  const [sortBy, setSortBy] = useState('createdAt'); // 'createdAt' | 'totalAmount'
  const [keyword, setKeyword] = useState('');

  const MOCK_ORDERS = [
    { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸', createdAt: '2026-09-01', totalAmount: 128000 },
    { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造', createdAt: '2026-09-03', totalAmount: 66000 },
    { id: '1003', orderNo: 'QO20260929-000003', customerName: '星辰商贸', createdAt: '2026-09-05', totalAmount: 9200 },
  ];

  // 排序：先拷贝再排序，避免原地修改依赖数据
  const sorted = [...MOCK_ORDERS].sort((a, b) =>
    sortBy === 'totalAmount' ? b.totalAmount - a.totalAmount : a.createdAt.localeCompare(b.createdAt),
  );
  const displayed = keyword
    ? sorted.filter((o) => o.orderNo.includes(keyword) || o.customerName.includes(keyword))
    : sorted;

  return (
    <div className="order-board">
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} placeholder="高亮关键词" />
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value)}>
        <option value="createdAt">按创建时间</option>
        <option value="totalAmount">按金额</option>
      </select>
      <ul className="order-list">
        {displayed.map((order) => (
          <li key={order.id} className="order-item">
            <span>
              <Highlight text={order.orderNo} keyword={keyword} />
            </span>
            <span>
              <Highlight text={order.customerName} keyword={keyword} />
            </span>
            <StatusTag status={order.status} />
          </li>
        ))}
      </ul>
    </div>
  );
}

export default OrderBoard;

⚠️ 常见易错点

易错点 1：&& 渲染出孤零零的「0」

// ❌ 当 orders.length 为 0 时，页面上出现一个「0」
// 原因：0 是假值，但 && 会直接返回左侧操作数，而 React 会把 0 渲染成文本
function OrderCount({ orders }) {
  return <div>{orders.length && <span>共 {orders.length} 单</span>}</div>;
}

// ✅ 把左侧显式变成布尔值，短路结果只剩 true/false
function OrderCount({ orders }) {
  return <div>{orders.length > 0 && <span>共 {orders.length} 单</span>}</div>;
}

易错点 2：用数组下标当 key

// ❌ 下标作 key：删除 / 排序后 React 按「位置」对号入座
// 现象：输入框内容串行、勾选错位、动画错乱
{orders.map((order, index) => (
  <OrderRow key={index} order={order} />
))}

// ✅ 用数据里稳定的唯一 ID（后端主键 / 业务编号）
{orders.map((order) => (
  <OrderRow key={order.id} order={order} />
))}

易错点 3：style 传字符串、class 照搬 HTML

// ❌ style 接收字符串、class 用了 HTML 写法：双双报错或告警
<span class="tag" style="color: red;">待审核</span>

// ✅ className 接收字符串，style 接收对象（值跟 CSS 一样用字符串/数值）
<span className="tag" style={{ color: 'red' }}>待审核</span>

易错点 4：受控输入只给 value 不给 onChange

// ❌ 只钉住 value 却没有回写通道：输入框永远打不进字
// 现象：控制台警告 “You provided a `value` prop to a form field without an `onChange` handler”
<input value={keyword} />

// ✅ value 与 onChange 成对出现；明确要「非受控」时用 defaultValue（第 05 章 §5.5）
<input value={keyword} onChange={(e) => setKeyword(e.target.value)} />

易错点 5：花括号里写语句

// ❌ if 是语句，表达式位置容不下它：直接编译报错
function StatusBar({ loading }) {
  return <div>{if (loading) '加载中…'}</div>;
}

// ✅ 三元是表达式可以直接放；复杂逻辑提到 return 之前算好
function StatusBar({ loading }) {
  return <div>{loading ? '加载中…' : '加载完成'}</div>;
}

✅ 最佳实践

1. 配置驱动展示：状态、枚举类 UI 一律收敛成 STATUS_META 这样的映射表，新增状态只改一处。
2. key 一律来自业务 ID：把「下标作 key」写进团队 code review 红线，除非列表完全静态。
3. 派生数据不存状态：过滤、排序、汇总在渲染时计算，避免「同一份数据存两份、改一处忘一处」。
4. 表达式短小、逻辑前置：花括号里最多一层三元，复杂判断提成变量或提前 return。
5. 受控优先：筛选、表单类输入默认走受控组件，保证「数据 → 视图」单向可追踪；确有性能或文件输入等场景再考虑非受控（第 05 章 §5.5）。
6. 空态是需求的一部分：列表必有空态文案与样式，验收时把「过滤到 0 条」当作必测用例。

📌 本章小结

1. JSX 是带糖的 JavaScript：{} 里只能写表达式；属性用 className / 对象 style；事件用小驼峰且传「函数引用」。
2. 条件渲染三板斧：三元（二选一）、&&（要么渲染要么不渲染）、提前 return（多分支）；v-show 对应 CSS 显隐。
3. 列表渲染 = map + key；key 是节点的身份证，必须唯一且稳定；换 key 即重建，可用于重置组件状态。
4. 受控组件是 React 版 v-model：value + onChange 成对出现，数据单向流动。
5. diff 直觉：「位置 + 类型 + key」认得出就保留状态，认不出就重建——这解释了 key 的一系列行为。

下一章预告：单文件里的组件已经不够用了。第 03 章讲组件化开发基础——props 单向数据流、回调通信、children 与组合，并把 StatusTag、OrderCard、SearchBar 一次性拆出来。

📄 第 03 章 · 组件化开发基础 03-组件化开发基础.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：3.5 小时｜🔗 前置：第 02 章

⬅ 上一章：JSX 与渲染模型 ｜ 📖 本版目录 ｜ ➡ 下一章：Hooks 核心

💡 对照学习：本页是 React 版第 03 章，对应 Vue 版第 03 章 · 组件化开发基础。概念映射：defineProps ≈ 函数参数解构、emit ≈ 回调 props（onXxx）、默认插槽 <slot> ≈ children、具名插槽 ≈ JSX props、作用域插槽 ≈ render props（传函数）。两版共同纪律：props 单向数据流、组件单一职责。

🎯 学习目标

学完本章，你将能够：

1. 用「返回 JSX 的函数」定义组件，说清组件文件的组织约定（一文件一组件、命名一致）；
2. 为组件设计 props 接口，用 JSDoc 注明类型约束，并用默认值处理可选项；
3. 解释 props 单向数据流：「数据向下流、事件向上冒」在企业代码里如何落地；
4. 用回调 props（onXxx）实现子 → 父通信，并在回调中正确携带参数；
5. 用 children 与 JSX props 实现 Vue 插槽的三种对应写法（默认 / 具名 / 作用域）；
6. 按「单一职责、复用 vs 组合」原则拆分组件，说清什么时候不该拆；
7. 独立完成企业场景：OrderCard、StatusTag、SearchBar 三个可复用业务组件。

📖 核心知识点

3.1 组件即函数：定义与使用

React 组件没有独立语法，它就是接收 props、返回 JSX 的函数。组织约定：一个文件一个组件，文件名与组件名一致，默认导出：

// src/components/StatusTag.jsx
// 组件 = 接收 props、返回 JSX 的函数；命名大写开头
function StatusTag({ status }) {
  return <span className="tag tag--default">{status}</span>;
}

export default StatusTag;

// src/App.jsx —— 使用：当成 HTML 标签写，必须是「大写开头」的标识符
import StatusTag from './components/StatusTag';

function App() {
  return (
    <div className="order-board">
      <StatusTag status="pending_review" />
      <StatusTag status="approved" />
    </div>
  );
}

export default App;

第 02 章的 STATUS_META 配置可以直接搬进来，让这个组件立刻具备业务语义（见本章练习 1）。

3.2 props：单向数据流与类型约束

props 是组件的只读入参。两版框架共同的纪律是单向数据流：数据从父到子单向流动，子组件想改变数据，只能「提出请求」，不能擅自动手：

父组件 OrderBoard
   │  props（数据向下流）
   ▼
子组件 OrderCard ── 回调 props（事件向上冒）
   ▲
   │ 用户点击「查看详情」等操作，由父组件决定怎么改数据

用 JSDoc 给 props 写类型约束（JavaScript 阶段的推荐做法，第三部分会全面转 TypeScript）：

/**
 * 订单卡片
 * @param {object}  props
 * @param {{ id: string, orderNo: string, customerName: string,
 *           ownerName: string, status: string }} props.order - 订单实体（附录A）
 * @param {boolean} [props.compact=false] - 紧凑模式（列表页用）
 * @param {(orderId: string) => void} [props.onOpen] - 点击卡片时触发
 */
function OrderCard({ order, compact = false, onOpen }) {
  const className = compact ? 'order-card order-card--compact' : 'order-card';
  return (
    <article
      className={className}
      onClick={() => onOpen?.(order.id)}
      role={onOpen ? 'button' : undefined}
    >
      <header className="order-card__header">
        <strong>{order.orderNo}</strong>
      </header>
      <p>客户：{order.customerName}</p>
      <p>归属销售：{order.ownerName}</p>
    </article>
  );
}

export default OrderCard;

三个要点：

• 可选 props 给默认值：compact = false 用参数默认值实现，调用方不传也不崩；
• 回调可以缺省：onOpen?.() 可选链调用，组件在没有父级监听时也能独立渲染；
• 运行时校验可选装 prop-types：npm i prop-types 后声明 OrderCard.propTypes，团队二选一（JSDoc 或 prop-types）并写进规范，保持全组一致即可。

3.3 子 → 父通信：回调 props

Vue 用 emit 抛事件；React 更直接——子组件调用父组件传下来的函数。命名约定：on + 动词（onSearch、onApprove、onOpen）：

// src/components/SearchBar.jsx —— 子组件：负责「收集」，不负责「处理」
function SearchBar({ onSearch }) {
  function handleSubmit(e) {
    e.preventDefault();
    // 从表单一次性取值（这里用非受控思路，第 05 章 §5.5 系统对比）
    const keyword = new FormData(e.currentTarget).get('keyword') ?? '';
    onSearch(keyword.trim()); // 把数据交给父组件处理
  }
  return (
    <form className="search-bar" onSubmit={handleSubmit}>
      <input name="keyword" placeholder="搜索订单号 / 客户名" />
      <button type="submit">搜索</button>
    </form>
  );
}

export default SearchBar;

// src/App.jsx —— 父组件：负责「处理」，状态只在父级变更
import { useState } from 'react';
import SearchBar from './components/SearchBar';

function App() {
  const [keyword, setKeyword] = useState('');
  return (
    <div className="page">
      {/* 回调 props ≈ Vue 的 emit：子发「请求」，父改状态 */}
      <SearchBar onSearch={setKeyword} />
      <p>当前筛选：{keyword || '（无）'}</p>
    </div>
  );
}

export default App;

状态放在哪？ 放在「需要它的组件的最近公共父级」。关键词被 SearchBar 和下方列表同时需要，所以关键词状态上提到父级——这就是「状态提升」，第 04 章会反复用到。

3.4 children 与组合：slot 的 React 写法

Vue 的插槽体系在 React 里的对应物是「把 JSX 当 props 传」：

// src/components/Panel.jsx —— children ≈ 默认插槽，footer ≈ 具名插槽
function Panel({ title, footer, children }) {
  return (
    <section className="panel">
      <header className="panel__header">{title}</header>
      <div className="panel__body">{children}</div>
      {/* 可选区块：传了才渲染 */}
      {footer && <footer className="panel__footer">{footer}</footer>}
    </section>
  );
}

export default Panel;

// 使用：开闭标签之间的内容就是 children，任意 JSX 都可以
<Panel title="待审核订单" footer={<small>共 12 单待处理</small>}>
  <OrderCard order={orders[0]} compact />
  <OrderCard order={orders[1]} compact />
</Panel>

作用域插槽的思路（render props，先认识即可，中级阶段封装列表组件时会常用）：

// 子组件把「每一行的数据」交给调用方决定怎么渲染
function OrderList({ orders, renderItem }) {
  return (
    <ul className="order-list">
      {orders.map((order) => (
        <li key={order.id}>{renderItem(order)}</li>
      ))}
    </ul>
  );
}

// 调用方控制每一行长什么样：数据来自 OrderList，结构由使用者定
<OrderList
  orders={orders}
  renderItem={(order) => <OrderCard order={order} compact />}
/>

3.5 组件拆分原则：单一职责与复用 vs 组合

什么时候该拆出一个组件？四个信号满足其一：

1. 重复出现：同样的结构在两处以上出现（复用信号）；
2. 超过一屏：一个函数上百行 JSX，读不动了（可读性信号）；
3. 独立状态：某块 UI 拥有自己的状态（如弹窗开合），独立成组件边界更清晰（状态信号）;
4. 独立演进：它可能被单独修改、测试或替换（变更信号）。

以订单看板为例，拆出这条组件树：

OrderBoard（页面容器：持有筛选状态，负责数据加工）
├── SearchBar          —— 只管收集关键词，搜什么它不管
├── OrderFilter        —— 只管状态下拉与归属筛选
└── OrderList          —— 只管把订单数组渲染成列表
    └── OrderCard      —— 只管一张订单的展示
        └── StatusTag  —— 只管一个状态标签

拆分的同时要警惕两个反模式：

• 过度拆分：两三行 JSX 就拆一个组件、为「可能复用」提前抽象——组件数量爆炸比重复代码更难维护；
• 万能组件：一个 OrderCard 通过十几个 props 开关变换出所有形态——改用组合（外部传 children / JSX props）代替配置开关。

判断口诀：复用靠抽组件，变化靠组合；先写出重复的两份，确认稳定后再抽象。

🛠 渐进式实战练习

练习 1 · 基础（20 min）：业务化的 StatusTag

任务描述：把第 01 章练习里的 StatusTag 升级为正式组件：基于 STATUS_META 配置渲染语义色标签；补充 JSDoc；提供 size 可选 prop（'md' | 'sm'，默认 'md'）。

提示：

• 映射表放 src/data/statusMeta.js，未知状态兜底；
• size 只影响类名，不要出现两套结构；
• 导出方式与文件名遵守 §3.1 约定。

验收标准：

• [ ] 7 种状态渲染正确，未知状态有兜底；
• [ ] size="sm" 时类名含 tag--sm，不传时默认 md；
• [ ] JSDoc 完整，组件从独立文件默认导出。

// src/data/statusMeta.js
export const STATUS_META = {
  draft: { label: '草稿', className: 'tag--default' },
  pending_review: { label: '待审核', className: 'tag--warning' },
  approved: { label: '已审核', className: 'tag--info' },
  shipped: { label: '已发货', className: 'tag--primary' },
  completed: { label: '已完成', className: 'tag--success' },
  rejected: { label: '已拒绝', className: 'tag--danger' },
  cancelled: { label: '已取消', className: 'tag--muted' },
};

// src/components/StatusTag.jsx
import { STATUS_META } from '../data/statusMeta';

/**
 * 订单状态标签
 * @param {object} props
 * @param {string} props.status - 订单状态（附录A 状态机）
 * @param {'md'|'sm'} [props.size='md'] - 尺寸
 */
function StatusTag({ status, size = 'md' }) {
  const meta = STATUS_META[status] ?? { label: status, className: 'tag--default' };
  return <span className={`tag tag--${size} ${meta.className}`}>{meta.label}</span>;
}

export default StatusTag;

练习 2 · 进阶（40 min）：OrderCard + 回调上抛

任务描述：实现 OrderCard（展示 orderNo、customerName、ownerName、状态标签、金额），并支持两个回调：onOpen(orderId)、onApprove(orderId)（通过审核按钮）。父组件 OrderBoard 持有订单数组，点「通过审核」后该单状态变为 approved（先直接改数组元素也先不做，用「整份替换」思路：map 生成新数组，下一章细讲）。

提示：

• 金额单位是「分」，展示组件负责转「元」并保留两位小数；求和才会涉及浮点问题，单笔换算安全；
• 子组件只调用 onApprove(order.id)，怎么改数据是父组件的事；
• 卡片整体可点打开详情，内部按钮阻止事件冒泡或分开布局，避免误触。

验收标准：

• [ ] OrderBoard 渲染 3 张卡片，字段完整；
• [ ] 点击「通过审核」后对应卡片状态标签变为「已审核」；
• [ ] OrderCard 内部没有出现任何「修改 order 对象」的代码。

// src/components/OrderCard.jsx
import StatusTag from './StatusTag';

/**
 * 订单卡片
 * @param {object} props
 * @param {{ id: string, orderNo: string, customerName: string,
 *           ownerName: string, status: string, totalAmount: number }} props.order
 * @param {(orderId: string) => void} [props.onOpen]
 * @param {(orderId: string) => void} [props.onApprove]
 */
function OrderCard({ order, onOpen, onApprove }) {
  const yuan = (order.totalAmount / 100).toLocaleString('zh-CN', {
    minimumFractionDigits: 2,
  });
  return (
    <article className="order-card" onClick={() => onOpen?.(order.id)}>
      <header className="order-card__header">
        <strong>{order.orderNo}</strong>
        <StatusTag status={order.status} />
      </header>
      <p>客户：{order.customerName}</p>
      <p>归属销售：{order.ownerName}</p>
      <footer className="order-card__footer">
        <strong>¥{yuan}</strong>
        <button
          onClick={(e) => {
            e.stopPropagation(); // 避免触发卡片的 onOpen
            onApprove?.(order.id);
          }}
        >
          通过审核
        </button>
      </footer>
    </article>
  );
}

export default OrderCard;

// src/pages/OrderBoard.jsx
import { useState } from 'react';
import OrderCard from '../components/OrderCard';

const INITIAL_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸', ownerName: '张晓', status: 'pending_review', totalAmount: 128000 },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造', ownerName: '李慕', status: 'draft', totalAmount: 66000 },
  { id: '1003', orderNo: 'QO20260929-000003', customerName: '云杉实业', ownerName: '王砚', status: 'pending_review', totalAmount: 245000 },
];

function OrderBoard() {
  const [orders, setOrders] = useState(INITIAL_ORDERS);

  function handleApprove(orderId) {
    // 不可变更新：map 造新数组，被改的元素展开造新对象（第 04 章系统讲）
    setOrders(orders.map((o) => (o.id === orderId ? { ...o, status: 'approved' } : o)));
  }

  function handleOpen(orderId) {
    console.log('打开订单详情', orderId); // 第 07 章接路由后跳详情页
  }

  return (
    <div className="order-board">
      {orders.map((order) => (
        <OrderCard key={order.id} order={order} onOpen={handleOpen} onApprove={handleApprove} />
      ))}
    </div>
  );
}

export default OrderBoard;

练习 3 · 挑战（选做，60 min+）：用 Panel 组合出订单看板

任务描述：实现通用容器 Panel（title、footer、children），用两个 Panel 组合出完整看板：「筛选面板」（含 SearchBar）+「订单列表面板」（含 OrderCard 列表与统计 footer）；再把列表渲染升级为 render props 版 OrderList，让 OrderBoard 自定义每行渲染。

提示：

• Panel 是纯展示组件：不含任何订单业务逻辑；
• 统计文案（如「共 N 单待处理」）由 OrderBoard 算好传入 footer；
• OrderList 只负责遍历与 key，行结构交给 renderItem。

验收标准：

• [ ] Panel 可复用（两处使用结构一致、样式统一）；
• [ ] 搜索后列表与 footer 统计同步更新；
• [ ] OrderList 通过 renderItem 渲染行，内部不知道 OrderCard 的存在。

// src/components/OrderList.jsx —— render props：数据由我给，结构由你定
function OrderList({ orders, renderItem, emptyText = '暂无订单' }) {
  if (orders.length === 0) return <p className="empty">{emptyText}</p>;
  return (
    <ul className="order-list">
      {orders.map((order) => (
        <li key={order.id}>{renderItem(order)}</li>
      ))}
    </ul>
  );
}

export default OrderList;

// src/pages/OrderBoard.jsx（组合部分）
import OrderList from '../components/OrderList';
import Panel from '../components/Panel';
// SearchBar、OrderCard、STATUS_META 同练习 1/2

function OrderBoard() {
  // keyword / orders 状态同练习 2，此处省略
  const pendingCount = orders.filter((o) => o.status === 'pending_review').length;

  return (
    <div className="dashboard">
      <Panel title="订单筛选">
        <SearchBar onSearch={setKeyword} />
      </Panel>
      <Panel title="订单列表" footer={<small>共 {pendingCount} 单待处理</small>}>
        <OrderList
          orders={orders.filter((o) => o.orderNo.includes(keyword))}
          renderItem={(order) => <OrderCard order={order} onApprove={handleApprove} compact />}
        />
      </Panel>
    </div>
  );
}

export default OrderBoard;

⚠️ 常见易错点

易错点 1：在子组件里直接修改 props

// ❌ 在子组件里直接改 props：单向数据流被破坏
// 现象：数据「到底谁在改」无法追踪，父组件的其他依赖处可能不更新
function OrderCard({ order, orders }) {
  return (
    <button
      onClick={() => {
        order.status = 'approved'; // 偷偷改了父组件的数据！
        orders.push(order);        // 数组也被动了
      }}
    >
      通过审核
    </button>
  );
}

// ✅ 改数据是父组件的事：子组件通过回调 props「提出请求」
function OrderCard({ order, onApprove }) {
  return <button onClick={() => onApprove(order.id)}>通过审核</button>;
}

易错点 2：把「调用函数」当成「传函数」

// ❌ onClick={handleApprove(order.id)}：渲染时立刻执行一次，点击无效
function OrderCard({ order, onApprove }) {
  return <button onClick={onApprove(order.id)}>通过审核</button>;
}

// ✅ 传函数引用：箭头函数包一层，把执行时机交给点击事件
function OrderCard({ order, onApprove }) {
  return <button onClick={() => onApprove(order.id)}>通过审核</button>;
}

易错点 3：导入导出方式不一致

// ❌ 文件里是命名导出，调用处按默认导出导入
// OrderCard.jsx
export function OrderCard() { /* ... */ }

// App.jsx —— OrderCard 实际是 undefined
import OrderCard from './components/OrderCard';
// 现象：报错 “Element type is invalid: expected a string ... but got: undefined”

// ✅ 导入导出保持一致：本书约定「一文件一组件 + 默认导出」
// OrderCard.jsx
export default function OrderCard() { /* ... */ }

// App.jsx
import OrderCard from './components/OrderCard';

易错点 4：假设 children 一定存在

// ❌ 没处理空内容：调用方条件渲染后 children 可能为空，页面渲染出空面板
<Panel title="审批记录">{hasRecords && <RecordList records={records} />}</Panel>

// ✅ 容器组件对空内容做兜底，体验与健壮性双收
function Panel({ title, footer, children }) {
  return (
    <section className="panel">
      <header className="panel__header">{title}</header>
      {children ? (
        <div className="panel__body">{children}</div>
      ) : (
        <p className="panel__empty">暂无内容</p>
      )}
      {footer && <footer className="panel__footer">{footer}</footer>}
    </section>
  );
}

易错点 5：props 展开顺序导致默认值覆盖调用方

// ❌ 先展开 props 再写 className：调用方传的自定义样式被悄悄覆盖
<input {...props} className="search-input" />

// ✅ 后写的属性生效：默认值在前，调用方覆盖在后
<input className="search-input" {...props} />

✅ 最佳实践

1. 一文件一组件、命名一致：OrderCard.jsx 只导出 OrderCard；公共小组件放 components/，页面放 pages/。
2. props 命名词法：数据用名词（order、orders），回调一律 on + 动词（onApprove）；布尔用 is/has/only 前缀（onlyMine）。
3. 回调参数写进 JSDoc：onApprove(orderId) 的参数类型与含义必须注明——回调是组件对外的「API 文档」。
4. 子组件零 mutation：review 时见到「子组件改 props 对象 / 数组」直接打回，一律改为回调上抛。
5. 先重复后抽象：同一结构出现两次前不抽组件；抽出的组件先做纯展示，状态上提。
6. 状态放最近公共父级：需要跨层共享的状态上提，用不到的状态下沉，避免「状态悬浮」在无关层级。

📌 本章小结

1. React 组件 = 返回 JSX 的函数；一文件一组件、默认导出、文件名与组件名一致。
2. props 只读、单向数据流：数据向下、事件向上；子组件改数据只能通过 onXxx 回调请求父组件。
3. 插槽对应关系：children ≈ 默认插槽、JSX props ≈ 具名插槽、函数 props（render props）≈ 作用域插槽。
4. 拆分信号：重复、超长、独立状态、独立演进；反模式是过度拆分与万能配置组件。
5. 状态放最近公共父级——这句话会在第 04 章变成具体代码：useState 的正确打开方式。

下一章预告：组件会「记东西」了才算完整。第 04 章讲 Hooks 核心：useState 的不可变更新、useMemo 的缓存语义、useEffect 的依赖与清理、过期闭包陷阱，并完成「订单筛选联动」的真实业务闭环。

📄 第 04 章 · Hooks 核心 04-Hooks核心.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：4.5 小时｜🔗 前置：第 03 章

⬅ 上一章：组件化开发基础 ｜ 📖 本版目录 ｜ ➡ 下一章：副作用生命周期与组件通信

💡 对照学习：本页是 React 版第 04 章，对应 Vue 版第 04 章 · 响应式系统核心。概念映射：ref / reactive ≈ useState、computed ≈ useMemo（以及渲染中直接派生）、watch / watchEffect ≈ useEffect（依赖数组即「监听目标」）、Vue「解构丢响应式」陷阱 ≈ React「过期闭包」陷阱。最大差异：Vue 改数据（可变响应式），React 换数据（不可变更新）。

🎯 学习目标

学完本章，你将能够：

1. 说出 Hooks 的两条使用规则及其背后的原因（调用顺序一致性）；
2. 用 useState 管理基础类型与对象 / 数组状态，并坚持不可变更新（展开、map、filter）；
3. 在「新状态依赖旧状态」时使用函数式更新 setState(prev => ...)；
4. 区分「渲染中直接派生」与「useMemo 缓存」，为昂贵计算正确选择后者；
5. 写出依赖数组完整、带清理函数的 useEffect，解释三种依赖写法的执行时机；
6. 用 useCallback 稳定函数引用，说清它解决的是「引用相等」问题；
7. 识别并修复过期闭包陷阱（定时器、事件回调中读到旧状态）；
8. 抽取自定义 Hook（如 useDebouncedValue），并完成「订单筛选联动」业务闭环。

📖 核心知识点

4.1 Hooks 与两条规则

Hooks 让函数组件拥有状态与副作用能力。useState、useEffect 等都是普通函数，但它们依赖调用顺序来对应每个状态的存储槽位，因此有两条铁律（官方 eslint-plugin-react-hooks 会自动检查，Vite 模板已内置）：

// ❌ Hook 藏进了条件分支：提前 return 后它可能「不存在」，顺序错乱
function OrderBoard({ loading }) {
  if (loading) return <Spinner />; // 提前 return
  const [orders, setOrders] = useState([]); // React 报错：Hooks 顺序不稳定
  return <OrderList orders={orders} />;
}

// ✅ 所有 Hook 都在组件顶层调用，条件判断放在 Hook 之后
function OrderBoard({ loading }) {
  const [orders, setOrders] = useState([]);
  if (loading) return <Spinner />;
  return <OrderList orders={orders} />;
}

两条规则：只在最顶层调用（不进 if / 循环 / 嵌套函数）；只在 React 函数组件或自定义 Hook 中调用（普通 JS 函数里不行）。

4.2 useState：不可变更新

与 Vue 直接改数据不同，React 要求换掉旧数据而不是修改它——React 靠引用是否变化来判断「状态变了，需要重渲染」：

import { useState } from 'react';

const INITIAL_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', status: 'draft', totalAmount: 128000 },
  { id: '1002', orderNo: 'QO20260929-000002', status: 'pending_review', totalAmount: 66000 },
];

function OrderBoard() {
  const [orders, setOrders] = useState(INITIAL_ORDERS);
  // 新增：不 push，展开造新数组
  function addOrder(order) {
    setOrders([order, ...orders]);
  }

  // 更新：map 造新数组；被改的元素展开造新对象
  function approveOrder(orderId) {
    setOrders(orders.map((o) => (o.id === orderId ? { ...o, status: 'approved' } : o)));
  }

  // 删除：filter 天然返回新数组
  function removeOrder(orderId) {
    setOrders(orders.filter((o) => o.id !== orderId));
  }
  return (
    <ul className="order-list">
      {orders.map((o) => (
        <li key={o.id}>
          {o.orderNo} · {o.status}
          <button onClick={() => approveOrder(o.id)}>通过审核</button>
          <button onClick={() => removeOrder(o.id)}>删除</button>
        </li>
      ))}
    </ul>
  );
}

函数式更新：新状态依赖旧状态时，传函数而不是值——React 保证拿到的是最新状态（连续多次 setState、异步回调里都安全）：

// ✅ 推荐写法：prev 一定是最新值
function addOrder(order) {
  setOrders((prev) => [order, ...prev]);
}

多个 setState 在同一次事件里会自动合并成一次重渲染（自动批处理），无需担心性能；也不要在 setState 之后立刻读变量——它要等下一次渲染才生效（易错点 3）。

4.3 派生数据：渲染中直接算 vs useMemo

Vue 的 computed 在 React 里有两档对应：

• 第一档（默认）：直接在渲染中计算。简单派生就该这么写，直白且没有额外心智负担；
• 第二档：计算昂贵（如上千条订单聚合）或结果要作为依赖参与其他 Hook 时，用 useMemo 缓存。

import { useMemo } from 'react';

function OrderStats({ orders }) {
  // 第一档：便宜的计算直接算，每次渲染重算也无所谓
  const pendingCount = orders.filter((o) => o.status === 'pending_review').length;
  // 第二档：上千条订单分组统计，orders 不变就复用上次结果
  const topSkus = useMemo(() => {
    const qtyBySku = new Map();
    for (const order of orders) {
      for (const item of order.items) {
        qtyBySku.set(item.skuName, (qtyBySku.get(item.skuName) ?? 0) + item.quantity);
      }
    }
    return [...qtyBySku.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
  }, [orders]); // 依赖数组：orders 变了才重算

  return (
    <div className="stats">
      <p>待审核订单：{pendingCount} 单</p>
      <p>热销 SKU Top5：{topSkus.map(([name, qty]) => `${name}×${qty}`).join('、')}</p>
    </div>
  );
}

两点纪律：派生值绝不存进 state（否则两份数据要人肉同步）；useMemo 的缓存只是优化提示，React 不保证永不重算，所以缓存里不能放「有副作用」的逻辑。

4.4 useEffect：依赖数组与清理

useEffect 让组件与「外部世界」同步：发请求、订阅、改标题、操作 localStorage。它在渲染提交到屏幕之后执行，三种依赖写法决定执行时机：

import { useEffect, useState } from 'react';

// 教学 mock：真实项目放 src/api/ 目录（中级阶段封装 axios）
function fetchLogs(orderId) {
  return Promise.resolve([
    { id: 'l1', content: `订单 ${orderId} 创建于 2026-09-29 10:00` },
    { id: 'l2', content: `订单 ${orderId} 提交审核` },
  ]);
}
function OrderTimeline({ orderId }) {
  const [logs, setLogs] = useState([]);

  useEffect(() => {
    let ignore = false; // 竞态保护：只有最后一次请求的结果生效（第 05 章 §5.3 细讲）
    fetchLogs(orderId).then((data) => {
      if (!ignore) setLogs(data);
    });
    // 清理函数：下一次 effect 执行前 / 组件卸载时调用
    return () => {
      ignore = true;
    };
  }, [orderId]); // 依赖数组：orderId 变了才重新拉取

  return <ul>{logs.map((log) => <li key={log.id}>{log.content}</li>)}</ul>;
}

依赖数组是「监听目标」：React 用 Object.is 逐项比较。引用类型是重灾区——对象、数组、函数每次渲染都是新引用，放进依赖会导致 effect 反复执行（易错点 5）。原则：effect 里用到的响应式值，全部写进依赖，漏写就等着读到旧数据。

4.5 useCallback 与引用相等

函数在组件里每次渲染都会重新创建——handleA !== handleA（上一次的与这一次的不是同一个引用）。当这个函数被 依赖数组 或 子组件的 props 消费时，新引用会引发连锁反应：

import { useCallback, useState } from 'react';
function OrderRow({ order, onApprove }) {
  // 若 OrderRow 未来被 React.memo 包裹（第 13 章），每次新函数会让缓存失效
  return (
    <li>
      {order.orderNo}
      <button onClick={() => onApprove(order.id)}>通过</button>
    </li>
  );
}

function OrderBoard() {
  const [orders, setOrders] = useState([]);

  // useCallback：依赖不变时返回同一个函数引用
  const handleApprove = useCallback((orderId) => {
    setOrders((prev) => prev.map((o) => (o.id === orderId ? { ...o, status: 'approved' } : o)));
  }, []); // 函数体只用了 setState，依赖为空是安全的
  return (
    <ul className="order-list">
      {orders.map((o) => (
        <OrderRow key={o.id} order={o} onApprove={handleApprove} />
      ))}
    </ul>
  );
}

判断口诀：useCallback 解决的是「引用相等」，不是性能万能药——函数没有传给依赖数组 / memo 子组件 / 其他 Hook 依赖时，不需要包。

4.6 过期闭包陷阱

这是 React 新手最容易「见到鬼」的地方：回调函数捕获的是创建那一刻的状态快照，之后状态变了，回调里的旧值不变——Vue 的「解构丢响应式」在 React 里的对应物：

// ❌ 定时器把首次渲染的 count 锁进了闭包：计数永远停在 1
function OrderPoller() {
  const [count, setCount] = useState(0);
  useEffect(() => {
    const timer = setInterval(() => {
      setCount(count + 1); // count 永远是 0（首次渲染的快照）
    }, 1000);
    return () => clearInterval(timer);
  }, []); // 空依赖 = 定时器只用第一帧的变量
  return <p>已轮询 {count} 次</p>;
}

// ✅ 解法一（推荐）：函数式更新，不依赖外部快照
function OrderPoller() {
  const [count, setCount] = useState(0);
  useEffect(() => {
    const timer = setInterval(() => setCount((prev) => prev + 1), 1000);
    return () => clearInterval(timer);
  }, []);
  return <p>已轮询 {count} 次</p>;
}
// 解法二：把 count 写进依赖数组——值变则销毁旧定时器、重建新定时器（见易错点 4 对照）

4.7 自定义 Hook 入门

自定义 Hook 就是名字以 use 开头、内部调用了其他 Hook 的普通函数。它是 React 版的「组合式函数」：把「状态 + 逻辑」打包复用，每个调用方拿到独立的一份状态：

// src/hooks/useDebouncedValue.js —— 输入防抖：值停稳 delayMs 后才「放行」
import { useEffect, useState } from 'react';

function useDebouncedValue(value, delayMs = 300) {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(timer); // 值再次变化：重置计时器
  }, [value, delayMs]);

  return debounced;
}
export default useDebouncedValue;

// 使用：每个组件里调用一次，各有一份独立的 debounced 状态
const [keyword, setKeyword] = useState('');
const debouncedKeyword = useDebouncedValue(keyword, 300); // 输入停 300ms 才变

自定义 Hook 的边界：只封装逻辑（状态、副作用、计算），不渲染任何 JSX；命名必须 use 开头，否则 ESLint 无法识别其中的 Hook 调用。

4.8 实战整合：订单筛选联动

企业场景（对应附录A 订单列表）：关键词 + 状态 + 分页共同驱动请求参数。整合本章全部知识点：

// src/data/mockOrders.js —— 教学 mock：形状与附录A一致（金额单位：分）
export const MOCK_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', customerName: '星辰商贸', ownerName: '张晓', status: 'pending_review', totalAmount: 128000 },
  { id: '1002', orderNo: 'QO20260929-000002', customerName: '恒远智造', ownerName: '李慕', status: 'approved', totalAmount: 66000 },
  { id: '1003', orderNo: 'QO20260929-000003', customerName: '星辰商贸', ownerName: '张晓', status: 'draft', totalAmount: 9200 },
  { id: '1004', orderNo: 'QO20260929-000004', customerName: '云杉实业', ownerName: '王砚', status: 'shipped', totalAmount: 245000 },
];

// src/pages/OrderBoard.jsx —— 关键词(防抖) + 状态 + 分页 → 请求参数 → 列表
import { useEffect, useMemo, useState } from 'react';
import useDebouncedValue from '../hooks/useDebouncedValue';
import { MOCK_ORDERS } from '../data/mockOrders';
import StatusTag from '../components/StatusTag';

const PAGE_SIZE = 20; // 附录A：分页 20/页；魔法数字收敛为常量
function fetchOrderList({ keyword, status, page }) {
  const all = MOCK_ORDERS.filter(
    (o) =>
      (status === '' || o.status === status) &&
      (keyword === '' || o.orderNo.includes(keyword) || o.customerName.includes(keyword)),
  );
  const start = (page - 1) * PAGE_SIZE;
  // 返回形状与附录A分页响应一致
  return Promise.resolve({ list: all.slice(start, start + PAGE_SIZE), total: all.length, page, pageSize: PAGE_SIZE });
}

function OrderBoard() {
  const [keyword, setKeyword] = useState('');
  const [status, setStatus] = useState('');
  const [page, setPage] = useState(1);
  const [result, setResult] = useState({ list: [], total: 0 });
  const [loading, setLoading] = useState(false);

  const debouncedKeyword = useDebouncedValue(keyword, 300);

  // 请求参数：由三个状态「派生」，useMemo 保证引用稳定
  const query = useMemo(() => ({ keyword: debouncedKeyword, status, page }), [debouncedKeyword, status, page]);
  useEffect(() => {
    let ignore = false; // 快速连续请求时，只认最后一次
    setLoading(true);
    fetchOrderList(query).then((data) => {
      if (!ignore) {
        setResult(data);
        setLoading(false);
      }
    });
    return () => {
      ignore = true;
    };
  }, [query]);

  // 筛选条件变化：回到第 1 页
  function handleKeywordChange(value) {
    setKeyword(value);
    setPage(1);
  }
  function handleStatusChange(value) {
    setStatus(value);
    setPage(1);
  }
  const totalPages = Math.max(1, Math.ceil(result.total / PAGE_SIZE));
  return (
    <div className="order-board">
      <input value={keyword} onChange={(e) => handleKeywordChange(e.target.value)} placeholder="搜索订单号 / 客户名" />
      <select value={status} onChange={(e) => handleStatusChange(e.target.value)}>
        <option value="">全部状态</option>
        <option value="draft">草稿</option>
        <option value="pending_review">待审核</option>
        <option value="approved">已审核</option>
      </select>
      {loading ? <p>加载中…</p> : <StatusList orders={result.list} />}
      <p>
        第 {page} / {totalPages} 页（共 {result.total} 条）
        <button disabled={page <= 1} onClick={() => setPage((p) => p - 1)}>上一页</button>
        <button disabled={page >= totalPages} onClick={() => setPage((p) => p + 1)}>下一页</button>
      </p>
    </div>
  );
}

function StatusList({ orders }) {
  if (orders.length === 0) return <p className="empty">没有匹配的订单</p>;
  return (
    <ul className="order-list">
      {orders.map((o) => (
        <li key={o.id}>
          {o.orderNo} · {o.customerName} <StatusTag status={o.status} />
        </li>
      ))}
    </ul>
  );
}
export default OrderBoard;

数据流一句话：用户改状态 → query 派生变化 → effect 重新同步 → 列表更新。整个链条只有一条「数据 → 视图」的单行道，没有任何手工同步。

🛠 渐进式实战练习

练习 1 · 基础（20 min）：订单状态统计面板

任务描述：实现 OrderStatsPanel：展示 7 种状态各自的订单数量；提供「通过全部待审核」按钮（一键把所有 pending_review 改为 approved）和「移除草稿」按钮。

提示：

• 状态计数是派生数据，渲染时用 filter().length 或一次 reduce 算出；
• 「通过全部」用 map 造新数组；「移除草稿」用 filter；
• 计数展示用第 02 章的 STATUS_META 遍历，别写 7 行硬编码。

验收标准：

• [ ] 7 种状态计数正确显示，操作后即时更新；
• [ ] 「通过全部」只影响 pending_review 的订单，其他状态不变；
• [ ] 全程没有出现 push / 直接改对象属性的写法。

// src/components/OrderStatsPanel.jsx
import { useState } from 'react';
import { STATUS_META } from '../data/statusMeta';

const INITIAL_ORDERS = [
  { id: '1001', orderNo: 'QO20260929-000001', status: 'pending_review' },
  { id: '1002', orderNo: 'QO20260929-000002', status: 'pending_review' },
  { id: '1003', orderNo: 'QO20260929-000003', status: 'draft' },
  { id: '1004', orderNo: 'QO20260929-000004', status: 'approved' },
];

function OrderStatsPanel() {
  const [orders, setOrders] = useState(INITIAL_ORDERS);
  // 派生：一次遍历统计各状态数量
  const countByStatus = orders.reduce((acc, o) => {
    acc[o.status] = (acc[o.status] ?? 0) + 1;
    return acc;
  }, {});

  function approveAllPending() {
    setOrders((prev) =>
      prev.map((o) => (o.status === 'pending_review' ? { ...o, status: 'approved' } : o)),
    );
  }
  function removeDrafts() {
    setOrders((prev) => prev.filter((o) => o.status !== 'draft'));
  }
  return (
    <section className="stats-panel">
      <ul>
        {Object.entries(STATUS_META).map(([status, meta]) => (
          <li key={status}>
            {meta.label}：{countByStatus[status] ?? 0} 单
          </li>
        ))}
      </ul>
      <button onClick={approveAllPending}>通过全部待审核</button>
      <button onClick={removeDrafts}>移除草稿</button>
    </section>
  );
}

export default OrderStatsPanel;

练习 2 · 进阶（40 min）：独立实现筛选联动

任务描述：不看 §4.8 的代码，独立实现 OrderBoard：关键词（防抖 300ms）+ 状态 + 分页驱动 fetchOrderList，含 loading 态与空态；用「快速翻页 + 快速输入」自测竞态保护是否生效。

提示：

• 状态 → query（useMemo）→ useEffect 的三段式结构；
• 竞态测试方法：连续快速点「下一页」10 次，最终列表必须是最后一页的数据；
• ignore 标志是初级阶段最简竞态方案，AbortController 方案在第 05 章 §5.3。

验收标准：

• [ ] 输入停止 300ms 后才触发过滤，输入过程中列表不闪；
• [ ] 切换关键词 / 状态后回到第 1 页；
• [ ] 快速连续翻页后展示的是最后一次请求的结果，无乱序。

// 三段式骨架（自查用）
const query = useMemo(() => ({ keyword: debouncedKeyword, status, page }), [debouncedKeyword, status, page]);
useEffect(() => {
  let ignore = false;
  fetchOrderList(query).then((data) => {
    if (!ignore) setResult(data);
  });
  return () => {
    ignore = true; // 每次依赖变化先「作废」上一次
  };
}, [query]);

练习 3 · 挑战（选做，60 min+）：抽出自定义 Hook useOrderFilter

任务描述：把练习 2 的状态与请求逻辑抽成 useOrderFilter 自定义 Hook，组件里只剩渲染；再补一个 usePagination 管理页码与翻页边界。

提示：

• Hook 返回「状态 + 处理函数」的普通对象：{ keyword, setKeyword, status, ..., orders, loading }；
• Hook 内部不 import 任何组件、不返回 JSX；
• 抽完后用练习 2 的验收标准回归测试，行为必须完全一致。

验收标准：

• [ ] useOrderFilter.js 内零 JSX，可被任意页面复用；
• [ ] OrderBoard.jsx 中没有任何 fetch / 防抖 / 分页细节，只剩布局与渲染；
• [ ] 回归测试全部通过。

// src/hooks/useOrderFilter.js —— 筛选联动的逻辑收口
import { useEffect, useMemo, useState } from 'react';
import useDebouncedValue from './useDebouncedValue';
import { fetchOrderList } from '../api/orders'; // mock 函数挪到 api 层

const PAGE_SIZE = 20;

function useOrderFilter() {
  const [keyword, setKeyword] = useState('');
  const [status, setStatus] = useState('');
  const [page, setPage] = useState(1);
  const [result, setResult] = useState({ list: [], total: 0 });
  const [loading, setLoading] = useState(false);
  const debouncedKeyword = useDebouncedValue(keyword, 300);
  const query = useMemo(
    () => ({ keyword: debouncedKeyword, status, page }),
    [debouncedKeyword, status, page],
  );

  useEffect(() => {
    let ignore = false;
    setLoading(true);
    fetchOrderList(query).then((data) => {
      if (!ignore) {
        setResult(data);
        setLoading(false);
      }
    });
    return () => {
      ignore = true;
    };
  }, [query]);

  return {
    keyword,
    setKeyword: (v) => {
      setKeyword(v);
      setPage(1); // 筛选变化重置页码，逻辑收在 Hook 内
    },
    status,
    setStatus: (v) => {
      setStatus(v);
      setPage(1);
    },
    page,
    setPage,
    pageSize: PAGE_SIZE,
    orders: result.list,
    total: result.total,
    loading,
  };
}
export default useOrderFilter;

// src/pages/OrderBoard.jsx —— 组件只剩「渲染」
import useOrderFilter from '../hooks/useOrderFilter';
import StatusTag from '../components/StatusTag';

function OrderBoard() {
  const {
    keyword, setKeyword, status, setStatus,
    page, setPage, pageSize, orders, total, loading,
  } = useOrderFilter();
  const totalPages = Math.max(1, Math.ceil(total / pageSize));

  return (
    <div className="order-board">
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} placeholder="搜索订单号 / 客户名" />
      <select value={status} onChange={(e) => setStatus(e.target.value)}>
        <option value="">全部状态</option>
        <option value="draft">草稿</option>
        <option value="pending_review">待审核</option>
      </select>
      {loading ? <p>加载中…</p> : null}
      <ul>
        {orders.map((o) => (
          <li key={o.id}>{o.orderNo} · {o.customerName} <StatusTag status={o.status} /></li>
        ))}
      </ul>
      <button disabled={page <= 1} onClick={() => setPage((p) => p - 1)}>上一页</button>
      <button disabled={page >= totalPages} onClick={() => setPage((p) => p + 1)}>下一页</button>
    </div>
  );
}
export default OrderBoard;

⚠️ 常见易错点

易错点 1：直接修改 state（可变更新）

// ❌ push / 直接改属性：引用没变，React 认为状态没变，界面不更新
function handleAdd(order) {
  orders.push(order); // 修改了原数组
  setOrders(orders);  // 同一个引用，重渲染被跳过
}

// ✅ 不可变更新：造新数组、新对象，引用变化驱动重渲染
function handleAdd(order) {
  setOrders((prev) => [order, ...prev]);
}

易错点 2：effect 依赖漏写

// ❌ effect 里用了 page，依赖却只写 [keyword]
// 现象：翻页后列表纹丝不动——effect 拿到的还是旧 page
useEffect(() => {
  fetchOrderList({ keyword, page }).then(setResult);
}, [keyword]);

// ✅ 用到的响应式值全部进依赖（eslint react-hooks/exhaustive-deps 会帮你盯）
useEffect(() => {
  fetchOrderList({ keyword, page }).then(setResult);
}, [keyword, page]);

易错点 3：setState 后立刻读旧值

// ❌ setPage 之后读到的 page 还是旧值：状态更新要等下一次渲染
function handleNext() {
  setPage(page + 1);
  fetchOrderList({ page }); // 这里 page 还是旧值！
}

// ✅ 让请求参数「从状态派生」，而不是在事件里手工拼接
const query = useMemo(() => ({ keyword, page }), [keyword, page]);
useEffect(() => {
  fetchOrderList(query).then(setResult);
}, [query]);

易错点 4：定时器 / 回调里的过期闭包

// ❌ 定时器闭包捕获了首次渲染的 count：setCount(count + 1) 永远算出 1
useEffect(() => {
  const timer = setInterval(() => setCount(count + 1), 1000);
  return () => clearInterval(timer);
}, []);

// ✅ 函数式更新基于最新值计算；或者把 count 写进依赖数组（代价是定时器重建）
useEffect(() => {
  const timer = setInterval(() => setCount((prev) => prev + 1), 1000);
  return () => clearInterval(timer);
}, []);

易错点 5：把「每次都是新引用」的值放进依赖

// ❌ query 每次渲染都是新对象：effect 每次渲染后都执行 → 请求风暴
const query = { keyword, status, page };
useEffect(() => {
  fetchOrderList(query).then(setResult);
}, [query]);

// ✅ useMemo 缓存参数对象；或把原始值逐个写进依赖
const query = useMemo(() => ({ keyword, status, page }), [keyword, status, page]);

✅ 最佳实践

1. 一个 state 一件事：{ keyword, status, page } 拆成三个独立 state，更新逻辑互不牵连；真正需要原子性一起变的再合并。
2. 派生值不入 state：计数、过滤、汇总在渲染时算；「存一份再同步」是 bug 之源。
3. effect 只做与外部世界的同步：请求、订阅、DOM 副作用；纯数据转换留在渲染里。怀疑滥用时读官方文章 You Might Not Need an Effect。
4. 依赖数组宁可多写，不可漏写：先写全让 ESLint 闭嘴，再做引用稳定优化（useMemo / useCallback）。
5. 魔法数字收敛为常量：PAGE_SIZE = 20 放模块顶层并注释出处（附录A），评审时一眼可查。
6. 逻辑复用走自定义 Hook：同一套「状态 + 副作用」出现在第二个组件之前，先忍住；出现时立刻抽 useXxx。

📌 本章小结

1. Hooks 两条规则的本质是「调用顺序一致」；ESLint 插件是第一道防线。
2. useState 的世界只有不可变更新：新增用展开、更新用 map、删除用 filter；依赖旧值时用函数式更新。
3. 派生数据两档写法：便宜的直接算，昂贵的 useMemo；缓存是优化提示而非保证。
4. useEffect = 与外部世界同步：依赖数组定时机、清理函数定退场；引用类型依赖要先用 useMemo / useCallback 稳定。
5. 过期闭包 = 回调捕获旧快照：函数式更新是首选解法；逻辑复用抽 useXxx 自定义 Hook。

下一章预告：useEffect 的时机与清理还有更多讲究——组件的一生如何用「挂载 / 更新 / 卸载」三段表达？跨层共享的主题状态、受控弹窗、可复用表格，正是第 05 章的主题。

📄 第 05 章 · 副作用生命周期与组件通信 05-副作用生命周期与组件通信.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：4.5 小时｜🔗 前置：第 04 章

⬅ 上一章：Hooks 核心 ｜ 📖 本版目录 ｜ ➡ 下一章：初级实战 · 企业门户首页

💡 对照学习：本页是 React 版第 05 章，对应 Vue 版第 05 章 · 生命周期与组件通信。概念映射：mounted / updated / unmounted ≈ useEffect 的三种依赖写法与清理函数、provide / inject ≈ Context、v-model 组件封装 ≈ 受控组件（value + onChange 下传）、<component :is> ≈ 「组件当值用」、递归组件两版同思路。

🎯 学习目标

学完本章，你将能够：

1. 画出 React 组件「渲染 → 提交 → 副作用」的三段时序，并说出它与 Vue 生命周期钩子的对应关系；
2. 为定时器、事件监听编写成对的清理函数，解释清理缺失在 StrictMode 下暴露的问题；
3. 用 AbortController / ignore 标志处理异步竞态，保证「最后一次请求说了算」；
4. 用 createContext + useContext 实现跨层通信（主题、当前用户），并说明 Context 的适用边界；
5. 区分受控与非受控组件，为表单组件封装出 React 版 v-model（value + onChange 接口）；
6. 用「组件当值用」实现动态视图切换，用递归组件渲染不定层级的数据树；
7. 独立实现企业场景：可复用 Table + Pagination、受控 ConfirmDialog。

📖 核心知识点

5.1 生命周期全景：从「钩子」到「同步」

Vue 提供了一组生命周期钩子；React 的函数组件只有一个心智模型——组件函数在每次渲染时重跑，副作用由 useEffect 在正确的时机同步：

setState / 父组件重渲染
   ▼
① 渲染（Render）：调用组件函数，算出新 JSX 树（必须保持纯净，不动外部世界）
   ▼
② 提交（Commit）：React 把差异更新到真实 DOM
   ▼
③ 副作用（Effect）：执行 useEffect 回调（屏幕绘制之后）
   ▼
状态再变 → 回到 ①；组件卸载 → 执行清理函数

与 Vue 生命周期的对应关系（够用版）：

一个关键事实：开发模式下 <StrictMode> 会把每个组件「挂载 → 卸载 → 再挂载」跑两遍，用来主动暴露「没写清理函数」的副作用。所以你在 DevTools 里看到 effect 执行两次，不是 bug，是 React 在帮你做压力测试（详见 react.dev 文档）。写好清理函数，双挂载零感知；不写清理，双挂载立刻现形。

5.2 副作用清理：定时器与事件监听

清理函数的纪律：有订阅就要有退订，成对出现。

import { useEffect, useState } from 'react';

function ElapsedTimer() {
  const [seconds, setSeconds] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => setSeconds((s) => s + 1), 1000);
    // ✅ 卸载时停表：避免内存泄漏与「组件已卸载还在 setState」的幽灵更新
    return () => clearInterval(timer);
  }, []);

  return <p>本次会话已浏览 {seconds} 秒</p>;
}

事件监听的清理要「同一个函数引用才能移除」：

function useWindowWidth() {
  const [width, setWidth] = useState(window.innerWidth);

  useEffect(() => {
    function handleResize() {
      setWidth(window.innerWidth);
    }
    window.addEventListener('resize', handleResize);
    // ✅ 移除时必须是同一个引用（所以 handler 要提到外面，不能写箭头内联两次）
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return width;
}

不清理的后果清单：定时器越积越多、监听器叠加触发、组件卸载后还在更新不存在的状态、StrictMode 下双份订阅导致「一次点击触发两次」。code review 看到 addEventListener / setInterval / setTimeout 后面没有 return 清理，直接打回。

5.3 异步副作用与竞态处理

两个纪律：effect 回调不能是 async 函数（它必须返回清理函数或 nothing）；请求要能「作废」：

import { useEffect, useState } from 'react';

function OrderDetail({ orderId }) {
  const [order, setOrder] = useState(null);

  useEffect(() => {
    const controller = new AbortController(); // 每个 orderId 一张「作废票」

    async function load() {
      try {
        const res = await fetch(`/api/orders/${orderId}`, { signal: controller.signal });
        const data = await res.json();
        setOrder(data);
      } catch (err) {
        if (err.name !== 'AbortError') {
          console.error('加载订单失败', err); // 主动取消不算错误
        }
      }
    }
    load();
    return () => controller.abort(); // orderId 变化 / 卸载：上一个请求作废
  }, [orderId]);

  if (!order) return <p>加载中…</p>;
  return <h2>{order.orderNo}</h2>;
}

没有 abort 时，快速切换 orderId 可能出现「慢的旧请求后到，覆盖新数据」。初级阶段用第 04 章的 ignore 标志也够；进入中级（第 09 章）后，这类「请求缓存 + 竞态」整体交给 TanStack Query。

5.4 跨层通信：Context

props 要一层层传七八层才能到深层组件（「props 钻井」），Vue 用 provide / inject，React 用 Context：

// src/context/ThemeContext.jsx
import { createContext, useContext, useMemo, useState } from 'react';

const ThemeContext = createContext(null); // 没有 Provider 时的兜底值

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');
  // ✅ useMemo 缓存 value：theme 不变就不产生新对象（易错点 3）
  const value = useMemo(() => ({ theme, setTheme }), [theme]);
  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

export function useTheme() {
  const ctx = useContext(ThemeContext); // ≈ Vue 的 inject
  if (!ctx) throw new Error('useTheme 必须在 <ThemeProvider> 内使用');
  return ctx;
}

// 任意深层的组件都能拿到主题，无需层层传 props
function ThemeButton() {
  const { theme, setTheme } = useTheme();
  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      当前主题：{theme}（点击切换）
    </button>
  );
}

// 应用根部包一层 Provider
<ThemeProvider>
  <App />
</ThemeProvider>

Context 的适用边界，初级阶段记三条：

• 适合：低频变化的全局 UI 态——主题、语言、当前登录用户、弹窗容器；
• 不适合：高频变化的业务数据（订单列表等）——所有消费者会一起重渲染，那是第 08 章状态库的活；
• 封装习惯：createContext + Provider + useXxx 三件套放一个文件，消费方只 import Hook，不直接碰 Context。

5.5 受控与非受控组件

第 02 章的受控输入升级到组件设计层面：受控组件 = value 进、onChange 出——这正是 Vue「v-model 组件封装」的 React 对应物：

// src/components/OrderRemark.jsx —— 受控封装：自己不存值，值的真相在父级
function OrderRemark({ value, onChange }) {
  return (
    <label>
      订单备注：
      <textarea value={value} onChange={(e) => onChange(e.target.value)} rows={3} />
    </label>
  );
}

// 父组件持有唯一数据源
function NewOrderForm() {
  const [remark, setRemark] = useState('');
  return <OrderRemark value={remark} onChange={setRemark} />;
}

反向选择是非受控：DOM 自己管值，提交时一次性读取，适合文件输入、超大表单的性能豁免：

import { useRef } from 'react';

function QuickSearch() {
  const inputRef = useRef(null);

  function handleSubmit(e) {
    e.preventDefault();
    console.log('提交关键词：', inputRef.current.value); // 用时才读
  }
  return (
    <form onSubmit={handleSubmit}>
      <input defaultValue="" ref={inputRef} name="keyword" />
      <button type="submit">搜索</button>
    </form>
  );
}

React 19 起，函数组件的 ref 可以直接作为普通 prop 接收并转发，不再需要 forwardRef 包裹；旧项目里的 forwardRef 依然兼容。细节见 React 19 发布说明。

5.6 组合模式：动态组件与递归组件

Vue 的 <component :is> 在 React 里是「组件当值用」——组件本来就是函数/变量：

const TAB_VIEWS = {
  list: OrderList,   // 组件作为值存进配置
  stats: OrderStats,
};

function OrderTabs({ activeTab }) {
  const CurrentView = TAB_VIEWS[activeTab] ?? OrderList;
  // 大写变量直接当标签渲染
  // 注意：切换组件类型 = 换「人」= 状态清空（第 02 章 §2.7 的 diff 直觉）
  // 若要各 Tab 保留状态，可全部渲染并用 CSS 显隐（v-show 思路）
  return <CurrentView />;
}

递归组件渲染不定层级的数据（商品分类树、组织架构）：

// src/components/CategoryNode.jsx —— 自己渲染自己，深度驱动缩进
import { useState } from 'react';
function CategoryNode({ node, depth = 0 }) {
  const [open, setOpen] = useState(depth < 1); // 第一层默认展开

  return (
    <div style={{ paddingLeft: depth * 16 }}>
      <button onClick={() => setOpen(!open)}>
        {node.children?.length ? (open ? '▼' : '▶') : '•'} {node.name}
      </button>
      {open &&
        node.children?.map((child) => (
          <CategoryNode key={child.id} node={child} depth={depth + 1} />
        ))}
    </div>
  );
}

export default CategoryNode;

5.7 业务组件落地：Table + Pagination + ConfirmDialog

通用表格：列配置驱动 + render 函数（Ant Design / Element Plus 同款思路的极简版，render 即「作用域插槽」）：

// src/components/Table.jsx
function Table({ columns, rows, emptyText = '暂无数据' }) {
  if (rows.length === 0) return <p className="table-empty">{emptyText}</p>;
  return (
    <table className="table">
      <thead>
        <tr>
          {columns.map((col) => (
            <th key={col.key}>{col.title}</th>
          ))}
        </tr>
      </thead>
      <tbody>
        {rows.map((row) => (
          <tr key={row.id}>
            {columns.map((col) => (
              <td key={col.key}>
                {/* render 优先：调用方决定单元格内容；否则直接取字段 */}
                {col.render ? col.render(row) : row[col.key]}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

export default Table;

// src/pages/OrderBoard.jsx 中的列配置与使用
const ORDER_COLUMNS = [
  { key: 'orderNo', title: '订单号' },
  { key: 'customerName', title: '客户' },
  { key: 'status', title: '状态', render: (order) => <StatusTag status={order.status} /> },
  {
    key: 'totalAmount',
    title: '金额',
    render: (order) => <strong>¥{(order.totalAmount / 100).toFixed(2)}</strong>,
  },
];

<Table columns={ORDER_COLUMNS} rows={orders} emptyText="没有匹配的订单" />

分页器：受控数值 + 回调上抛，边界由组件内部兜底：

// src/components/Pagination.jsx
function Pagination({ page, pageSize, total, onPageChange }) {
  const totalPages = Math.max(1, Math.ceil(total / pageSize));
  return (
    <nav className="pagination" aria-label="分页">
      <button disabled={page <= 1} onClick={() => onPageChange(page - 1)}>
        上一页
      </button>
      <span>
        第 {page} / {totalPages} 页（共 {total} 条）
      </span>
      <button disabled={page >= totalPages} onClick={() => onPageChange(page + 1)}>
        下一页
      </button>
    </nav>
  );
}

export default Pagination;

确认弹窗：显隐状态由父组件持有（受控模式），内容区用 children 组合：

// src/components/ConfirmDialog.jsx
function ConfirmDialog({ open, title, children, onConfirm, onCancel }) {
  if (!open) return null; // 关闭即不渲染
  return (
    <div className="dialog-mask" onClick={onCancel}>
      <div
        className="dialog"
        role="dialog"
        aria-modal="true"
        onClick={(e) => e.stopPropagation()} // 点内容区不关闭
      >
        <h3>{title}</h3>
        <div className="dialog__body">{children}</div>
        <footer className="dialog__footer">
          <button onClick={onCancel}>取消</button>
          <button className="btn-danger" onClick={onConfirm}>确认</button>
        </footer>
      </div>
    </div>
  );
}
export default ConfirmDialog;

// 使用：附录A 约定「取消订单必须填原因并记日志」，先做确认流骨架
function OrderRowActions({ order }) {
  const [confirming, setConfirming] = useState(false);

  function handleConfirm() {
    console.log('取消订单', order.id); // 中级阶段接真实 API
    setConfirming(false);
  }

  return (
    <>
      <button onClick={() => setConfirming(true)}>取消订单</button>
      <ConfirmDialog
        open={confirming}
        title={`确认取消订单 ${order.orderNo}？`}
        onConfirm={handleConfirm}
        onCancel={() => setConfirming(false)}
      >
        <p>取消后需填写原因，该操作会记入操作日志。</p>
      </ConfirmDialog>
    </>
  );
}

🛠 渐进式实战练习

练习 1 · 基础（20 min）：受控弹窗接入订单列表

任务描述：基于 §5.7 的 ConfirmDialog，为订单列表的每一行接入「取消订单」确认流：点击按钮 → 弹窗出现 → 确认后该行状态变为 cancelled（不可变更新）→ 弹窗关闭。

提示：

• confirming 状态放在行组件里；确认逻辑回调给父级改数据；
• 弹窗打开时页面其余内容应不可操作（遮罩已实现，检查点击穿透）；
• 确认按钮文案含订单号，验证 props 传递链路。

验收标准：

• [ ] 点击「取消订单」出现弹窗，点遮罩或「取消」关闭，点「确认」执行变更；
• [ ] 变更后行内状态标签更新为「已取消」，且用的是不可变更新；
• [ ] ConfirmDialog 组件内部零业务逻辑，可原样搬到其他页面复用。

// src/components/OrderRow.jsx
import { useState } from 'react';
import ConfirmDialog from './ConfirmDialog';
import StatusTag from './StatusTag';

function OrderRow({ order, onCancel }) {
  const [confirming, setConfirming] = useState(false);

  return (
    <li className="order-row">
      <span>{order.orderNo}</span>
      <StatusTag status={order.status} />
      <button onClick={() => setConfirming(true)}>取消订单</button>
      <ConfirmDialog
        open={confirming}
        title={`确认取消订单 ${order.orderNo}？`}
        onConfirm={() => {
          onCancel(order.id);
          setConfirming(false);
        }}
        onCancel={() => setConfirming(false)}
      >
        <p>取消后需填写原因，该操作会记入操作日志。</p>
      </ConfirmDialog>
    </li>
  );
}
export default OrderRow;

// 父组件中的取消逻辑（不可变更新）
function handleCancel(orderId) {
  setOrders((prev) => prev.map((o) => (o.id === orderId ? { ...o, status: 'cancelled' } : o)));
}

练习 2 · 进阶（45 min）：Table + Pagination 组合成订单列表页

任务描述：把 §5.7 的 Table 与 Pagination 组合进 OrderBoard：列配置含状态标签与金额（分转元）；接上分页状态；数据为空时展示空态文案。

提示：

• page 状态放 OrderBoard，onPageChange 直接传 setPage；
• 列配置数组定义在组件外（它不含状态，无需每次渲染重建）；
• 组合后用「翻页 → 状态标签颜色正确」验证 render 函数生效。

验收标准：

• [ ] 表格四列渲染正确，状态列是彩色标签、金额列保留两位小数；
• [ ] 「上一页 / 下一页」在边界处禁用；
• [ ] 列表为空时显示 emptyText，分页器仍然可用且显示正确总数。

// src/pages/OrderBoard.jsx
import { useState } from 'react';
import Table from '../components/Table';
import Pagination from '../components/Pagination';
import StatusTag from '../components/StatusTag';
import { MOCK_ORDERS } from '../data/mockOrders';

const PAGE_SIZE = 20;

const ORDER_COLUMNS = [
  { key: 'orderNo', title: '订单号' },
  { key: 'customerName', title: '客户' },
  { key: 'status', title: '状态', render: (order) => <StatusTag status={order.status} /> },
  {
    key: 'totalAmount',
    title: '金额',
    render: (order) => <strong>¥{(order.totalAmount / 100).toFixed(2)}</strong>,
  },
];

function OrderBoard() {
  const [page, setPage] = useState(1);
  const start = (page - 1) * PAGE_SIZE;
  const pageRows = MOCK_ORDERS.slice(start, start + PAGE_SIZE); // 教学：本地分页

  return (
    <div className="order-board">
      <Table columns={ORDER_COLUMNS} rows={pageRows} emptyText="没有匹配的订单" />
      <Pagination page={page} pageSize={PAGE_SIZE} total={MOCK_ORDERS.length} onPageChange={setPage} />
    </div>
  );
}

export default OrderBoard;

练习 3 · 挑战（选做，60 min+）：主题 Context + 键盘无障碍

任务描述：把 §5.4 的 ThemeContext 补完整：主题初始值从 localStorage 读取（异常兜底 light）；useEffect 把主题同步到 <html data-theme> 并持久化；给 ConfirmDialog 加「按 ESC 关闭」——注意用带清理的事件监听。

提示：

• 读写 localStorage 都要 try/catch（隐私模式会抛错）；
• ESC 监听在 open === true 时才挂，依赖数组写 [open, onCancel]；
• 验证 StrictMode 下控制台没有「监听器泄漏」迹象（切几次弹窗，DevTools 的 Event Listeners 面板只有一份）。

验收标准：

• [ ] 刷新页面主题保持；清掉 localStorage 后回到 light；
• [ ] 弹窗打开时按 ESC 关闭，关闭后监听器被移除；
• [ ] useTheme() 在 Provider 外调用时抛出可读的错误提示。

// src/context/ThemeContext.jsx（完整版）
import { createContext, useContext, useEffect, useMemo, useState } from 'react';
const ThemeContext = createContext(null);
const THEME_STORAGE_KEY = 'qingorder-theme';

function readInitialTheme() {
  try {
    const saved = localStorage.getItem(THEME_STORAGE_KEY);
    if (saved === 'light' || saved === 'dark') return saved; // 白名单校验，防脏数据
  } catch {
    /* localStorage 不可用（如隐私模式）：走兜底 */
  }
  return 'light';
}

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState(readInitialTheme);

  // 副作用：state → DOM + 持久化
  useEffect(() => {
    document.documentElement.dataset.theme = theme;
    try {
      localStorage.setItem(THEME_STORAGE_KEY, theme);
    } catch {
      /* 写入失败不阻塞 UI */
    }
  }, [theme]);

  const value = useMemo(() => ({ theme, setTheme }), [theme]);
  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error('useTheme 必须在 <ThemeProvider> 内使用');
  return ctx;
}

// ConfirmDialog 的 ESC 关闭（组件内部新增）
import { useEffect } from 'react';

function ConfirmDialog({ open, title, children, onConfirm, onCancel }) {
  useEffect(() => {
    if (!open) return; // 关闭状态不挂监听
    function handleKeydown(e) {
      if (e.key === 'Escape') onCancel();
    }
    window.addEventListener('keydown', handleKeydown);
    return () => window.removeEventListener('keydown', handleKeydown);
  }, [open, onCancel]); // onCancel 变化时同步重建监听

  if (!open) return null;
  // ……其余同 §5.7
}
export default ConfirmDialog;

⚠️ 常见易错点

易错点 1：订阅不清理

// ❌ 只订阅不退订：组件反复进出页面后监听器越积越多，StrictMode 下一次挂载订阅两份
useEffect(() => {
  window.addEventListener('resize', handleResize);
}, []);

// ✅ 订阅与退订成对出现，且用同一个函数引用
useEffect(() => {
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

易错点 2：effect 回调写成 async

// ❌ useEffect 的回调必须是同步函数：async 函数会返回 Promise，React 会把它当清理函数
useEffect(async () => {
  const data = await fetchOrderList(query);
  setResult(data);
}, [query]);

// ✅ 内部定义 async 函数再调用，effect 本身保持同步
useEffect(() => {
  async function load() {
    const data = await fetchOrderList(query);
    setResult(data);
  }
  load();
}, [query]);

易错点 3：Context value 每次渲染都是新对象

// ❌ value 内联对象字面量：每次渲染都是新引用，所有消费者被迫跟着重渲染
<ThemeContext.Provider value={{ theme, setTheme }}>
  {children}
</ThemeContext.Provider>

// ✅ useMemo 缓存 value：theme 不变就给同一个引用
const value = useMemo(() => ({ theme, setTheme }), [theme]);
<ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>

易错点 4：没有依赖数组引发死循环

// ❌ 忘写依赖数组：每次渲染后执行 → setState 又触发渲染 → 再执行 → 死循环
useEffect(() => {
  setLogs(fetchLogsSync());
});

// ✅ 明确依赖：只在相关数据变化时同步；同时自问「这真的需要存 state 吗」
useEffect(() => {
  setLogs(fetchLogsSync(orderId));
}, [orderId]);

易错点 5：受控链路断裂

// ❌ 封装了受控组件，父级却没接 onChange：输入框永远是死的
// 现象：敲键盘毫无反应，控制台告警 value 无 onChange
<OrderRemark value={remark} />

// ✅ value 与 onChange 成对下传，数据单向流动，父级仍是唯一真相
<OrderRemark value={remark} onChange={setRemark} />

✅ 最佳实践

1. 清理是副作用的另一半：定时器、监听器、订阅、请求Abort，写副作用时先想「退场时怎么撤销」。
2. 一个 effect 只做一件事：同步主题与上报埋点拆成两个 effect，依赖数组各自最小化。
3. Context 只装低频全局态：主题 / 语言 / 当前用户；高频业务数据走 props 或（中级起）状态库与请求库。
4. Context 三件套封装：createContext + Provider + useXxx 收在一个文件，消费方只见 Hook 不见 Context。
5. 表单组件默认受控：value + onChange 是团队约定的「v-model 接口」；非受控仅用于文件输入等豁免场景，并在 JSDoc 标注。
6. 弹窗类组件一律受控显隐：开合权在父级，组件只负责呈现与回调，这样才有动画与联动设计的空间。

📌 本章小结

1. React 没有「生命周期钩子数组」，有的是「渲染 → 提交 → 副作用」三段时序 + 清理函数；mounted/updated/unmounted 全部映射到 useEffect 的三种写法。
2. StrictMode 开发期双挂载是「清理函数体检仪」：订阅与退订成对，双挂载零感知。
3. 异步副作用两条纪律：effect 本体保持同步；用 ignore 标志或 AbortController 保证最后一次请求说了算。
4. 跨层通信用 Context（≈ provide/inject），value 用 useMemo 稳定；受控组件（value + onChange）是 React 版 v-model 封装。
5. 「组件当值用」替代动态组件，递归组件渲染树形数据；Table（列配置 + render）、Pagination、ConfirmDialog 是本阶段的组件设计毕业作。

下一章预告：零件都齐了。第 06 章把它们组装成完整的企业门户首页——组件树设计先行、目录组织、暗色主题、FAQ 手风琴，并附上 props 接口评审清单与验收标准。

📄 第 06 章 · 初级实战 —— 企业门户首页 06-初级实战-企业门户首页.md✓ 标记已学

📍 阶段：初级阶段（第 1–6 章）｜⏱ 预计学时：6 小时｜🔗 前置：第 05 章 + 附录A

⬅ 上一章：副作用生命周期与组件通信 ｜ 📖 本版目录 ｜ ➡ 下一章：第二部分 · 路由系统

💡 对照学习：本页是 React 版第 06 章，对应 Vue 版第 06 章 · 初级实战。两版练习任务完全一致（导航 / Banner / 特性区 / FAQ 手风琴 / 页脚 / 暗色主题切换），可对照实现差异。概念映射：App.vue ≈ App.jsx、<script setup> 组合式函数 ≈ 自定义 Hook、provide/inject ≈ Context、v-model 封装 ≈ 受控组件。

🎯 学习目标

学完本章，你将能够：

1. 从需求出发先画组件树，再动手编码，并解释每个组件的职责边界；
2. 按 components/ / data/ / hooks/ 的约定组织项目目录，做到「改文案不碰组件、改逻辑不碰样式」；
3. 用「数据配置驱动」实现导航、特性区与 FAQ 内容，新增内容零组件改动；
4. 实现单开模式的 FAQ 手风琴，并使用 aria-expanded 完成基础无障碍；
5. 实现 useTheme 自定义 Hook 驱动的暗色主题：CSS 变量 + data-theme + localStorage 持久化；
6. 用本章的「props 接口设计评审清单」审查自己与同伴的组件 API；
7. 对照验收标准完成门户首页整页联调，并通过初级阶段能力自查。

📖 核心知识点

6.1 需求分析与组件树设计先行

附录A 一期需求：面向潜在客户的品牌官网首页（导航、产品介绍、联系方式），目标 LCP ≤ 2.0s。初级阶段的实现范围是静态内容 + 两个交互（FAQ 手风琴、主题切换）。

先画组件树，再写代码——这一步在企业里叫「拆页评审」，5 分钟能省掉半天返工：

App（只做拼装 + 全局状态）
├── NavBar
│   ├── Logo（内联文本即可）
│   ├── NavLinks（data 驱动锚点链接）
│   └── ThemeToggle（接收 theme + onToggle）
├── main
│   ├── Banner（主视觉 + CTA）
│   ├── FeatureGrid
│   │   └── FeatureCard × 6（map 渲染）
│   ├── FaqAccordion（持有 openId 状态）
│   │   └── FaqItem × N（展开 / 收起）
│   └── （联系方式区块并入 Footer）
└── Footer（商务信息 + 备案占位）

设计决策记录（每个决策都能追溯 to 前五章）：

• 主题状态放 App（useTheme Hook），通过 props 下发——全局唯一数据源（第 03 章 §3.3）；
• FAQ 开合状态收在 FaqAccordion 内部——外部无人需要它（第 03 章 §3.5 状态下沉）；
• 文案与列表数据全部进 data/ 目录——配置驱动（第 02 章 §2.5）；
• FeatureCard、FaqItem 保持纯展示组件——零状态、零副作用（第 05 章受控思想）。

6.2 项目目录组织

src/
├── main.jsx                  # 入口：createRoot + StrictMode
├── App.jsx                   # 根组件：只做拼装与全局状态
├── index.css                 # 全局样式 + CSS 变量（主题令牌）
├── data/                     # 内容配置：改文案不碰组件
│   ├── navLinks.js
│   ├── features.js
│   └── faqs.js
├── hooks/                    # 可复用逻辑：状态 + 副作用
│   └── useTheme.js
└── components/               # 展示组件：一文件一组件
    ├── NavBar.jsx
    ├── ThemeToggle.jsx
    ├── Banner.jsx
    ├── FeatureGrid.jsx
    ├── FeatureCard.jsx
    ├── FaqAccordion.jsx
    └── Footer.jsx

约定解读：data/ 是「内容」、hooks/ 是「逻辑」、components/ 是「视图」。三者的依赖方向永远是从视图 import 逻辑与内容，不允许反向（data/ 里绝不 import 组件）。

6.3 数据层：把内容变成配置

// src/data/navLinks.js
export const NAV_LINKS = [
  { id: 'features', label: '产品能力' },
  { id: 'faq', label: '常见问题' },
  { id: 'contact', label: '联系我们' },
];

// src/data/features.js —— 文案取材于附录A 的产品能力
export const FEATURES = [
  { id: 'f1', icon: '📦', title: '订单全生命周期', desc: '草稿到完成，7 种状态流转全程留痕。' },
  { id: 'f2', icon: '🔍', title: '多维筛选检索', desc: '关键词、状态、日期、销售归属，秒级定位订单。' },
  { id: 'f3', icon: '🛡️', title: '三级权限管控', desc: '菜单、页面、按钮三级权限，杜绝越权操作。' },
  { id: 'f4', icon: '📊', title: '经营报表', desc: '按销售、按月、按商品聚合，一键导出。' },
  { id: 'f5', icon: '⚡', title: '万级列表流畅', desc: '虚拟滚动加持，大促期间也不卡顿。' },
  { id: 'f6', icon: '🧾', title: '财务对账友好', desc: '金额以「分」存储，折扣审批全程可审计。' },
];

// src/data/faqs.js
export const FAQS = [
  { id: 'q1', q: '轻订单适合什么规模的团队？', a: '从 5 人销售团队到千人分销体系均可使用，权限模型可按角色裁剪。' },
  { id: 'q2', q: '支持哪些部署方式？', a: '提供 SaaS 与私有化两种交付形态，私有化支持内网部署。' },
  { id: 'q3', q: '订单数据如何保障安全？', a: '传输全程 TLS，关键操作二次确认并写入审计日志。' },
  { id: 'q4', q: '能否对接现有 ERP？', a: '开放 REST API 与 Webhook，支持与主流 ERP 集成。' },
];

6.4 NavBar 与 ThemeToggle：状态上提 + props 下发

主题逻辑收口到 useTheme（第 05 章挑战练习的正式版），副作用同步 DOM 与持久化：

// src/hooks/useTheme.js —— 主题 = 状态 + 同步副作用 + 持久化
import { useEffect, useState } from 'react';

const THEME_STORAGE_KEY = 'qingorder-theme';

function readInitialTheme() {
  try {
    const saved = localStorage.getItem(THEME_STORAGE_KEY);
    if (saved === 'light' || saved === 'dark') return saved; // 白名单校验
  } catch {
    /* localStorage 不可用（隐私模式）：走兜底 */
  }
  return 'light';
}

function useTheme() {
  const [theme, setTheme] = useState(readInitialTheme);

  // 副作用：state → <html data-theme> + 持久化（渲染保持纯净）
  useEffect(() => {
    document.documentElement.dataset.theme = theme;
    try {
      localStorage.setItem(THEME_STORAGE_KEY, theme);
    } catch {
      /* 写入失败不阻塞 UI */
    }
  }, [theme]);

  function toggleTheme() {
    setTheme((t) => (t === 'light' ? 'dark' : 'light'));
  }

  return { theme, toggleTheme };
}

export default useTheme;

组件层只认 props，不关心主题从哪来（复用第 03 章「受控 + 上抛」模式）：

// src/components/ThemeToggle.jsx
function ThemeToggle({ theme, onToggle }) {
  return (
    <button className="theme-toggle" onClick={onToggle} aria-label="切换深色模式">
      {theme === 'light' ? '深色模式' : '浅色模式'}
    </button>
  );
}

export default ThemeToggle;

// src/components/NavBar.jsx
import { NAV_LINKS } from '../data/navLinks';
import ThemeToggle from './ThemeToggle';

function NavBar({ activeId, onNavigate, theme, onToggleTheme }) {
  return (
    <header className="navbar">
      <a className="navbar__logo" href="#top">轻订单</a>
      <nav className="navbar__links" aria-label="主导航">
        {NAV_LINKS.map((link) => (
          <a
            key={link.id}
            href={`#${link.id}`}
            className={activeId === link.id ? 'is-active' : ''}
            onClick={() => onNavigate(link.id)}
          >
            {link.label}
          </a>
        ))}
      </nav>
      <ThemeToggle theme={theme} onToggle={onToggleTheme} />
    </header>
  );
}

export default NavBar;

主题的「皮肤」由 CSS 变量承担——组件与样式通过变量解耦，暗色只是一张变量覆盖表：

/* src/index.css —— 主题令牌：组件只认变量，不认具体颜色 */
:root {
  --color-bg: #ffffff;
  --color-text: #1f2328;
  --color-primary: #2563eb;
  --color-card: #f6f8fa;
}

[data-theme='dark'] {
  --color-bg: #0d1117;
  --color-text: #e6edf3;
  --color-primary: #3b82f6;
  --color-card: #161b22;
}

body {
  background: var(--color-bg);
  color: var(--color-text);
  transition: background 0.2s ease, color 0.2s ease;
}

.navbar {
  display: flex;
  align-items: center;
  gap: 24px;
  padding: 12px 32px;
  border-bottom: 1px solid var(--color-card);
}

.feature-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: 16px;
  padding: 48px 32px;
}

.feature-card {
  background: var(--color-card);
  border-radius: 12px;
  padding: 20px;
}

.faq__question {
  width: 100%;
  text-align: left;
  padding: 12px 0;
  background: none;
  border: none;
  color: var(--color-text);
  font-size: 16px;
  cursor: pointer;
}

.faq__answer {
  margin: 0 0 12px;
  color: var(--color-text);
  opacity: 0.75;
}

6.5 Banner 与 FeatureGrid：纯展示组件

// src/components/Banner.jsx
function Banner() {
  return (
    <section className="banner" id="top">
      <h1 className="banner__title">让每一张 B2B 订单都被看见</h1>
      <p className="banner__desc">
        轻订单 · 青云科技自研订单管理系统：接单、审核、发货、对账，全流程数字化。
      </p>
      <a className="banner__cta" href="#contact">预约演示</a>
    </section>
  );
}

export default Banner;

// src/components/FeatureCard.jsx —— 零状态展示组件：props 进、JSX 出
function FeatureCard({ feature }) {
  return (
    <article className="feature-card">
      <div className="feature-card__icon" aria-hidden="true">{feature.icon}</div>
      <h3>{feature.title}</h3>
      <p>{feature.desc}</p>
    </article>
  );
}

export default FeatureCard;

// src/components/FeatureGrid.jsx —— 容器只负责 map + key
import { FEATURES } from '../data/features';
import FeatureCard from './FeatureCard';

function FeatureGrid() {
  return (
    <section className="feature-grid" id="features" aria-label="产品能力">
      {FEATURES.map((feature) => (
        <FeatureCard key={feature.id} feature={feature} />
      ))}
    </section>
  );
}

export default FeatureGrid;

6.6 FaqAccordion：单开手风琴

交互设计决策：同一时刻只展开一项（openId 收敛为单值状态，天然互斥）；再次点击收起全部：

// src/components/FaqAccordion.jsx
import { useState } from 'react';
import { FAQS } from '../data/faqs';

function FaqAccordion() {
  const [openId, setOpenId] = useState(null); // 当前展开项；null = 全部收起

  return (
    <section className="faq" id="faq">
      <h2>常见问题</h2>
      {FAQS.map((faq) => {
        const isOpen = openId === faq.id;
        return (
          <div className="faq__item" key={faq.id}>
            <button
              className="faq__question"
              aria-expanded={isOpen} // 无障碍：告诉读屏器当前展开状态
              onClick={() => setOpenId(isOpen ? null : faq.id)}
            >
              {faq.q} {isOpen ? '▲' : '▼'}
            </button>
            {isOpen && <p className="faq__answer">{faq.a}</p>}
          </div>
        );
      })}
    </section>
  );
}

export default FaqAccordion;

要点回顾：UI 状态（openId）归组件，内容数据（FAQS）保持只读——不要把 open 塞进数据数组再直接改（易错点 3）。若产品后续要求「可多开」，把状态换成 Set 做不可变更新即可，组件结构不变。

6.7 Footer 与页面组装

// src/components/Footer.jsx
function Footer() {
  return (
    <footer className="footer" id="contact">
      <p>青云科技 · 轻订单（教学虚构项目）</p>
      <p>商务合作：demo@qingorder.example.com</p>
      <p>© 2026 Qingyun Tech. 本页面为教程演示，非真实产品。</p>
    </footer>
  );
}

export default Footer;

// src/App.jsx —— 根组件只做拼装：全局状态在此，交互逻辑已收进 Hook
import { useState } from 'react';
import NavBar from './components/NavBar';
import Banner from './components/Banner';
import FeatureGrid from './components/FeatureGrid';
import FaqAccordion from './components/FaqAccordion';
import Footer from './components/Footer';
import useTheme from './hooks/useTheme';

function App() {
  const { theme, toggleTheme } = useTheme();
  const [activeId, setActiveId] = useState('features');

  return (
    <div className="page">
      <NavBar activeId={activeId} onNavigate={setActiveId} theme={theme} onToggleTheme={toggleTheme} />
      <main>
        <Banner />
        <FeatureGrid />
        <FaqAccordion />
      </main>
      <Footer />
    </div>
  );
}

export default App;

6.8 props 接口设计评审清单

企业 code review 中，组件 API 先于实现被评审。提交前逐条自检：

• [ ] 命名词法统一：数据用名词（order、feature），回调 on + 动词（onToggle、onNavigate），布尔带前缀（isActive、onlyMine）；
• [ ] 单向数据流无破坏：子组件零 mutation，所有变更经回调上抛；
• [ ] 可选 props 有默认值，必传 props 有 JSDoc 类型注释；
• [ ] 回调参数写进文档：onNavigate(linkId) 的参数含义与类型可从 JSDoc 一眼读出；
• [ ] 列表 key 有保障：由调用方数据提供稳定唯一 ID，组件内部不生成随机 key；
• [ ] 纯展示组件零副作用：FeatureCard / FaqItem 这类组件不碰 DOM、不发请求、不写存储；
• [ ] 状态放对位置：全局态（主题）在顶层，局部态（openId、confirming）在最近消费者；
• [ ] 配置与视图分离：新增一条 FAQ 只改 data/faqs.js，零组件改动。

6.9 验收标准

按附录A「门户首页」需求逐条验收，全部通过才算完成初级阶段实战：

• [ ] pnpm dev 启动无报错，五个区块（导航 / Banner / 特性区 / FAQ / 页脚）完整呈现；
• [ ] 导航锚点可滚动到对应区块，当前区块高亮；
• [ ] 特性区 6 张卡片响应式排布（窄屏单列，宽屏多列）；
• [ ] FAQ 同一时刻至多展开一项，再次点击可收起，aria-expanded 状态正确；
• [ ] 暗色主题切换即时生效，刷新页面后保持上次选择；
• [ ] 控制台无 error 与 warning；pnpm lint 通过；
• [ ] 目录结构与 §6.2 一致，所有文案可在 data/ 目录中找到；
• [ ] pnpm build 构建成功，pnpm preview 预览功能无回归。

🛠 渐进式实战练习

练习 1 · 基础（30 min）：页面骨架 —— NavBar + Banner + Footer

任务描述：从空项目（或本章示例仓库）出发，先完成三个静态区块：数据驱动的 NavBar（含锚点与高亮）、Banner（标题 + slogan + CTA）、Footer。主题切换暂用占位按钮。

提示：

• 先建 data/navLinks.js，再写组件——「内容先行」是本章的肌肉记忆；
• activeId 状态放 App，NavBar 是受控组件；
• 样式只需要「能看出结构」，不必追求像素级还原。

验收标准：

• [ ] 三个区块渲染完整，导航点击后锚点滚动 + 高亮切换；
• [ ] 新增一个导航项只需改 navLinks.js；
• [ ] NavBar、Banner、Footer 均为一文件一组件、默认导出。

// src/App.jsx
import { useState } from 'react';
import NavBar from './components/NavBar';
import Banner from './components/Banner';
import Footer from './components/Footer';

function App() {
  const [activeId, setActiveId] = useState('features');

  return (
    <div className="page">
      <NavBar activeId={activeId} onNavigate={setActiveId} />
      <main>
        <Banner />
      </main>
      <Footer />
    </div>
  );
}

export default App;

练习 2 · 进阶（60 min）：FeatureGrid + FaqAccordion

任务描述：完成特性区与 FAQ 手风琴，要求：卡片响应式排布；手风琴单开模式 + aria-expanded；FAQS / FEATURES 数据独立成文件。

提示：

• 手风琴状态用 openId（单值），展开逻辑一行：setOpenId(isOpen ? null : faq.id)；
• 展开内容用条件渲染 {isOpen && ...}，组件卸载即收起；
• 网格布局交给 CSS（auto-fill + minmax），React 侧零介入。

验收标准：

• [ ] 6 张特性卡片在窄屏 / 宽屏下分别呈单列 / 多列；
• [ ] FAQ 点击展开、再点收起、点另一项时旧项自动收起；
• [ ] DevTools 中能看到 aria-expanded="true/false" 随点击切换；
• [ ] 两组件均为纯展示（除 FaqAccordion 持有 openId 外无其他状态）。

const [openId, setOpenId] = useState(null);

// 展开项与当前点击项相同时收起（置 null），否则切换到新项
<button
  aria-expanded={isOpen}
  onClick={() => setOpenId(isOpen ? null : faq.id)}
>

练习 3 · 挑战（选做，90 min+）：主题系统完整版

任务描述：实现生产级暗色主题：① useTheme 支持「localStorage → 系统偏好 → light」三级兜底；② 消除「暗色用户刷新时白屏闪烁」（FOUC）；③ 主题切换按钮带过渡动画。

提示：

• 三级兜底的读取顺序：localStorage 白名单 → matchMedia('(prefers-color-scheme: dark)') → 'light'；
• FOUC 的根因：React 挂载前页面用默认浅色渲染了第一帧。解法是在 index.html 里、React 脚本之前放一段内联脚本提前设置 data-theme；
• 这是企业门户的真实需求——附录A 要求首页 LCP ≤ 2.0s，视觉闪烁直接影响体验评审。

验收标准：

• [ ] 系统偏好为暗色的新用户，首次打开即是暗色；
• [ ] 暗色用户刷新页面无白屏闪烁（可用 DevTools 性能面板逐帧验证）；
• [ ] localStorage 被禁用时页面不报错、主题回落 light。

<!-- index.html：在 React 加载前设置主题，消除 FOUC -->
<body>
  <script>
    (function () {
      try {
        var theme = localStorage.getItem('qingorder-theme');
        if (theme !== 'light' && theme !== 'dark') {
          theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
        }
        document.documentElement.dataset.theme = theme;
      } catch (e) {
        /* localStorage 不可用：保持默认浅色 */
      }
    })();
  </script>
  <div id="root"></div>
  <script type="module" src="/src/main.jsx"></script>
</body>

// src/hooks/useTheme.js —— 三级兜底版（只列差异）
function readInitialTheme() {
  try {
    const saved = localStorage.getItem(THEME_STORAGE_KEY);
    if (saved === 'light' || saved === 'dark') return saved;
  } catch {
    /* 忽略 */
  }
  // 兜底 2：跟随系统偏好
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}

⚠️ 常见易错点

易错点 1：主题状态散落在多个组件里

// ❌ NavBar 和 Footer 各自维护 theme：两个开关互相不知道，页面一半黑一半白
function NavBar() {
  const [theme, setTheme] = useState('light'); // 状态分裂了
  // ...
}

// ✅ 主题是全局 UI 态：收口到顶层 useTheme（多层级消费时升级为 Context），向下分发
function App() {
  const { theme, toggleTheme } = useTheme();
  return <NavBar theme={theme} onToggleTheme={toggleTheme} />;
}

易错点 2：localStorage 读写无防护

// ❌ 初始化时直接解析 localStorage：隐私模式抛异常、脏数据炸页面
const [theme, setTheme] = useState(JSON.parse(localStorage.getItem('theme')));

// ✅ try/catch + 白名单校验，异常时回退默认主题（readInitialTheme 内部已处理）
const [theme, setTheme] = useState(readInitialTheme);

易错点 3：把 UI 状态塞进数据数组

// ❌ 把 open 写进 FAQ 数据并直接修改：数据与 UI 状态混在一起，还破坏了不可变纪律
import { FAQS } from '../data/faqs';

function FaqAccordion() {
  FAQS[0].open = true; // 直接改了导入的常量数组！
  // ...
}

// ✅ UI 状态归组件（openId），内容数据保持只读
const [openId, setOpenId] = useState(null);
// 点击时：setOpenId(isOpen ? null : faq.id)

易错点 4：渲染期间操作外部世界

// ❌ 在渲染过程中直接改 DOM 属性：渲染必须保持「纯」，副作用属于 useEffect
function App() {
  const [theme] = useState('light');
  document.documentElement.dataset.theme = theme; // 渲染期间动了外部世界
  return <NavBar theme={theme} />;
}

// ✅ 副作用放进 useEffect：提交渲染之后、且依赖变化时才执行（useTheme 内部已处理）
function App() {
  const { theme, toggleTheme } = useTheme();
  return <NavBar theme={theme} onToggleTheme={toggleTheme} />;
}

易错点 5：把所有逻辑堆进 App.jsx

// ❌ 700 行的 App.jsx：导航、FAQ、主题全部纠缠在一个函数里，谁都不敢改
function App() {
  const [openId, setOpenId] = useState(null);
  const [theme, setTheme] = useState('light');
  const [activeId, setActiveId] = useState('');
  // ……300 行 JSX，FAQ 与导航互相嵌套引用
}

// ✅ 按「组件树设计先行」拆分：App 只负责拼装，每个文件单一职责
function App() {
  return (
    <div className="page">
      <NavBar activeId={activeId} onNavigate={setActiveId} theme={theme} onToggleTheme={toggleTheme} />
      <main>
        <Banner />
        <FeatureGrid />
        <FaqAccordion />
      </main>
      <Footer />
    </div>
  );
}

✅ 最佳实践

1. 组件树设计先行：编码前先画树、标注每个组件的状态与 props，评审成本远低于返工。
2. 内容进 data/、逻辑进 hooks/、视图进 components/：三个目录依赖方向单一，改文案不碰组件。
3. 主题令牌化：颜色、间距全部收敛为 CSS 变量，暗色主题只是一张变量覆盖表，组件代码零感知。
4. 无障碍是验收项：交互元素用语义标签（button / nav / section），展开类组件带 aria-expanded，弹窗带 role="dialog"。
5. 渲染保持纯净：渲染函数里不发请求、不改 DOM、不写存储；一切「对外动作」进 useEffect。
6. 验收即清单：上线前按 §6.9 逐条打勾，把「控制台无警告」与 pnpm lint 通过设为硬门槛。

📌 本章小结

1. 实战方法论：需求 → 组件树 → 目录结构 → 数据配置 → 组件实现 → 清单验收，顺序不可颠倒。
2. 门户首页五大区块全部由「配置数据 + 纯展示组件 + 容器组件」构成，新增内容零组件改动。
3. 主题系统 = useTheme（状态 + 副作用 + 持久化）+ CSS 变量令牌 + 可选的防闪烁内联脚本。
4. FAQ 手风琴的关键是把 UI 状态（openId）与内容数据严格分离，单开模式天然互斥。
5. props 评审清单是初级阶段的「组件 API 合格证」，每一次 code review 都应该过一遍。

📋 初级阶段毕业检查：完成本章即完成初级阶段全部学习。请打开《阶段自查 · 初级能力清单》，用 30 分钟完成能力勾选与自测小考；达标后即可进入第二部分 · 中级阶段——多页面、全局状态与服务端交互的世界。

📄 第 07 章 · 路由系统 —— React Router 全解 07-路由系统-ReactRouter全解.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：5 小时｜🔗 前置：第 04 章、第 06 章

⬅ 上一章：初级实战 · 企业门户首页 ｜ 📖 本版目录 ｜ ➡ 下一章：状态管理

💡 对照学习：本页是 React 版第 07 章，对应 Vue 版第 07 章 · 路由系统，两版练习任务完全一致（中后台骨架 → 订单详情/面包屑/筛选回传 → 权限路由 + 403）。概念映射：<Routes>/<Route> ≈ routes 配置数组；<Outlet /> ≈ <router-view>（嵌套出口）；useNavigate ≈ router.push/replace；useSearchParams ≈ route.query 读写；ProtectedRoute 组件 ≈ router.beforeEach 导航守卫；React.lazy + Suspense ≈ 路由懒加载；路由 handle 元信息 ≈ meta 字段。

🎯 学习目标

学完本章，你将能够：

1. 说出 React Router 7 的两种使用模式（组件式 <Routes> 与数据模式 createBrowserRouter）的差别，并解释本教程为什么主讲组件式；
2. 用嵌套路由 + <Outlet /> 搭出「轻订单」中后台 Layout 骨架：侧边菜单常驻、内容区随路由切换；
3. 用 React.lazy + Suspense 完成路由级代码分割，并用 DevTools 验证每个页面一个 chunk；
4. 使用 useParams 读取动态参数，并解释「参数变化时组件被复用」的原因与两种解法；
5. 用 useSearchParams 把订单列表的筛选条件写进 URL，实现刷新回填与可分享链接；
6. 封装 ProtectedRoute 守卫组件完成登录拦截与 redirect 回跳，对照说出它与 Vue 导航守卫的异同；
7. 用路由元信息驱动面包屑导航，并理解「单一事实源」在路由配置上的体现；
8. 说出 history 路由的工作原理、部署时刷新 404 的原因与 Nginx 回退方案。

📖 核心知识点

7.1 安装与两种心智模型

React Router 7 把包合并为单一的 react-router（旧的 react-router-dom 作为兼容层继续存在，内部重导出）。安装：

pnpm add react-router

它同时支持两种写法，API 兼容、心智不同：

本教程主讲组件式——它与第 09 章的 TanStack Query 配合最自然，也是存量企业项目的主流形态；数据模式在需要时（如希望导航守卫更像 Vue 的 beforeEach）一句话就能迁移。本节代码全部可以在两种模式下复用。

入口挂载（第 06 章项目继续演进）：

// src/main.jsx —— 挂载路由：整个 SPA 从这里变成「多页面」
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter } from 'react-router'
import App from './App'
import './index.css'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>,
)

⚙️ @ 别名指向 src/ 在第 01 章已配置（vite.config.js 的 resolve.alias），后续代码沿用。

7.2 路由表、嵌套路由与 Outlet：中后台 Layout

中后台系统的经典形态是「登录页独立、其余页面共享一个 Layout（侧边栏 + 顶栏 + 内容区）」。React Router 的表达方式是嵌套路由：父路由渲染 Layout，子路由渲染进 Layout 里的 <Outlet /> 占位。

// src/App.jsx —— 路由表：哪个路径显示哪个组件的唯一事实源
import { Routes, Route, Navigate } from 'react-router'
import { lazy, Suspense } from 'react'
import AdminLayout from './layouts/AdminLayout'
import Login from './views/Login'
import NotFound from './views/NotFound'

// 页面级懒加载：每个页面单独一个 chunk，首屏只带 Login + Layout
const Dashboard = lazy(() => import('./views/Dashboard'))
const OrderList = lazy(() => import('./views/orders/OrderList'))
const OrderDetail = lazy(() => import('./views/orders/OrderDetail'))
const OrderCreate = lazy(() => import('./views/orders/OrderCreate'))
const CustomerList = lazy(() => import('./views/customers/CustomerList'))

/** 统一给懒加载页面套 Suspense，避免每处重复写 */
function LazyPage({ children }) {
  return (
    <Suspense fallback={<div className="page-loading">页面加载中…</div>}>
      {children}
    </Suspense>
  )
}

export default function App() {
  return (
    <Routes>
      <Route path="/login" element={<Login />} />
      {/* 嵌套：所有后台页面渲染进 AdminLayout 的 <Outlet /> */}
      <Route path="/" element={<AdminLayout />}>
        <Route index element={<Navigate to="/dashboard" replace />} />
        <Route path="dashboard" element={<LazyPage><Dashboard /></LazyPage>} />
        <Route path="orders" element={<LazyPage><OrderList /></LazyPage>} />
        <Route path="orders/new" element={<LazyPage><OrderCreate /></LazyPage>} />
        <Route path="orders/:id" element={<LazyPage><OrderDetail /></LazyPage>} />
        <Route path="customers" element={<LazyPage><CustomerList /></LazyPage>} />
      </Route>
      <Route path="*" element={<NotFound />} />
    </Routes>
  )
}

Layout 本身不需要知道「内容是什么」，它只负责壳 + <Outlet />：

// src/layouts/AdminLayout.jsx —— 中后台外壳：侧边菜单 + 顶栏 + 内容出口
import { Outlet, NavLink } from 'react-router'
import { Layout as AntLayout, Menu } from 'antd'
import { MENU_ITEMS } from '@/router/menus'

const { Sider, Header, Content } = AntLayout

export default function AdminLayout() {
  return (
    <AntLayout style={{ minHeight: '100vh' }}>
      <Sider>
        <div className="logo">轻订单</div>
        <Menu theme="dark" mode="inline" items={MENU_ITEMS} />
      </Sider>
      <AntLayout>
        <Header className="topbar">
          <Breadcrumbs /> {/* §7.8 实现 */}
        </Header>
        <Content className="page-container">
          {/* 子路由渲染在这里；参数变化时页面组件被「复用」而非重建 */}
          <Outlet />
        </Content>
      </AntLayout>
    </AntLayout>
  )
}

三个必须内化的规则：

1. 子路径不带 / 开头（path="orders"），相对父路径拼接——写成 /orders 虽然多数场景也能跑，但嵌套迁移时会踩坑；
2. index 路由匹配「父路径本身」，用它把 / 重定向到 /dashboard；
3. path="*" 是 404 兜底，必须放最后——React Router 按声明顺序匹配，兜底放前面会吞掉所有路由。

7.3 懒加载：React.lazy + Suspense

lazy(() => import('./x')) 让 Vite 把该模块拆成独立 chunk，首次渲染到它时才加载。配合第 14 章的加载性能指标（首屏 gzip ≤ 300KB），路由级分割是性价比最高的一刀：

# 构建后观察产物：每个页面一个 chunk
pnpm build
# dist/assets/Dashboard-xxxx.js  dist/assets/OrderList-xxxx.js ...

两个纪律：

• lazy() 必须配合 <Suspense>，否则 React 会在模块未就绪时抛错（React 19 中懒组件挂起时必须有边界接住）；
• fallback 要设计成与页面骨架高度相近的占位（骨架屏），避免「白屏 → 内容」的跳变。

数据模式还有另一种懒法：路由对象上的 lazy 导出（按路由拆模块、loader 与组件一起懒加载），细节见官方文档 https://reactrouter.com/start/data/routers ——组件式用 React.lazy 即可覆盖本章需求。

7.4 动态参数 useParams 与组件复用

订单详情页 /orders/:id 是典型动态路由。useParams 读取路径参数：

// src/views/orders/OrderDetail.jsx —— 订单详情（数据部分第 09 章补全）
import { useParams, Link } from 'react-router'
import { useEffect, useState } from 'react'
import { fetchOrderDetail } from '@/api/orders'

export default function OrderDetail() {
  const { id } = useParams() // 字符串！'/orders/1001' → { id: '1001' }
  const [order, setOrder] = useState(null)

  useEffect(() => {
    let active = true
    fetchOrderDetail(id).then((data) => {
      if (active) setOrder(data)
    })
    return () => { active = false } // 竞态防护，第 09 章换成 TanStack Query 后自动消失
  }, [id]) // ← 关键：id 变化时重新拉取

  if (!order) return <div className="page-loading">加载中…</div>
  return (
    <div>
      <h2>{order.orderNo}</h2> {/* QO20260929 + 6 位序号，见附录A */}
      <Link to="/orders">← 返回列表</Link>
    </div>
  )
}

必须理解的机制：从 /orders/1001 跳到 /orders/1002 时，React Router 匹配到的还是同一个 <OrderDetail />，React 会复用组件实例（只更新 props），状态不会被重置，也不会自动重新请求。这与 Vue 版「params 变化组件复用」是同一个问题，两个解法也一一对应：

推荐解法一（useEffect 依赖数组），第 09 章接入 TanStack Query 后，queryKey 里的 id 变化会自动重新请求并保留缓存，这个问题直接消失。

7.5 搜索参数 useSearchParams：筛选状态的唯一事实源

订单列表的关键词、状态、页码（附录A §3.3：分页 20/页 + 多维筛选）放组件 state 还是 URL？答案是 URL——刷新不丢、可分享、可回退，这也是第 09 章 useOrderList 的地基：

// src/views/orders/OrderList.jsx（节选）—— 筛选条件与 URL 双向同步
import { useSearchParams } from 'react-router'

export default function OrderList() {
  const [searchParams, setSearchParams] = useSearchParams()
  const filters = {
    keyword: searchParams.get('keyword') ?? '',
    status: searchParams.get('status') ?? '',
    page: Number(searchParams.get('page') ?? 1),
  }

  // 更新筛选：始终基于当前 searchParams 生成新对象，避免互相覆盖
  const setFilter = (patch) => {
    const next = new URLSearchParams(searchParams)
    Object.entries(patch).forEach(([key, value]) => {
      if (value === '' || value == null) next.delete(key) // 空值不留在地址栏
      else next.set(key, String(value))
    })
    if (!('page' in patch)) next.set('page', '1') // 改筛选必须回第一页
    setSearchParams(next) // 默认 push（可回退）；想「替换历史」传 { replace: true }
  }

  return (
    <div>
      <input
        value={filters.keyword}
        placeholder="搜订单号 / 客户名"
        onChange={(e) => setFilter({ keyword: e.target.value })}
      />
      <button onClick={() => setFilter({ status: 'pending_review' })}>看待审核</button>
      <button onClick={() => setFilter({ page: filters.page + 1 })}>下一页</button>
    </div>
  )
}

useSearchParams 返回 [searchParams, setSearchParams]，前者是 URLSearchParams 实例（.get/.set/.delete），后者用法近似 useNavigate。URL 是唯一事实源：输入框的 value、表格的数据请求参数，全部从 searchParams 派生，刷新后状态原样还原。

7.6 编程式导航 useNavigate

表单提交成功后跳转、登录后回跳——这些「代码里决定去哪」的场景用 useNavigate（≈ router.push/replace）：

import { useNavigate } from 'react-router'

function OrderActions({ orderId }) {
  const navigate = useNavigate()

  const handleSubmitSuccess = () => {
    navigate(`/orders/${orderId}`, { replace: true }) // 提交页不可「后退」回来
  }
  const handleCancel = () => {
    navigate(-1) // 等价于 history.back()
  }
  // 还可以携带 state：给目标页传「不进 URL」的数据（刷新即丢）
  // navigate('/login', { state: { from: '/orders' } })
  return <button onClick={handleSubmitSuccess}>提交订单</button>
}

三条纪律：事件处理函数与 useEffect 里调用，绝不在渲染期间调用（见易错点 2）；跳详情用模板字符串拼 /orders/${id}；replace 用于「逻辑上替换当前步骤」的场景（登录、提交成功）。

7.7 守卫：ProtectedRoute（对应导航守卫）

Vue Router 用全局 beforeEach 一次拦住所有路由；React Router 没有全局守卫 API，惯用法是把守卫做成路由元素：包住需要保护的路由分支，未登录就渲染 <Navigate> 重定向。第 08 章接入全局状态后，判断条件会换成 store；本章先用一个独立的 auth 工具保持自洽：

// src/utils/auth.js —— 本章最小实现；第 11 章会升级为双令牌 + store 管理
const TOKEN_KEY = 'qing_access_token'

export const auth = {
  isLoggedIn: () => Boolean(localStorage.getItem(TOKEN_KEY)),
  setToken: (token) => localStorage.setItem(TOKEN_KEY, token),
  clear: () => localStorage.removeItem(TOKEN_KEY),
}

// src/router/ProtectedRoute.jsx —— 守卫组件：包住谁，谁就需要登录
import { Navigate, Outlet, useLocation } from 'react-router'
import { auth } from '@/utils/auth'

export default function ProtectedRoute() {
  if (!auth.isLoggedIn()) {
    // state.from 记录来源路径，登录成功后回跳（第 11 章完整实现）
    return <Navigate to="/login" replace state={{ from: location.pathname + location.search }} />
  }
  return <Outlet />
}

⚠️ 上面 location 需要配合 const location = useLocation() 使用，完整版见练习 3 答案。

接入路由表——守卫是嵌套结构，天然分层：

// App.jsx 中：用 ProtectedRoute 包住整个后台分支
<Route element={<ProtectedRoute />}>
  <Route path="/" element={<AdminLayout />}>
    {/* ...各页面路由 */}
  </Route>
</Route>
<Route path="/login" element={<Login />} /> {/* 白名单：在守卫之外 */}

第 11 章会给 ProtectedRoute 加上 roles 参数与 403 分流，实现附录A 的页面级权限（直接输 URL 也进不来）。它就是 React 世界的「导航守卫」——只是从「框架钩子」变成了「组合进路由树」。

7.8 路由元信息与面包屑

Vue Router 每条路由可以挂 meta；React Router 的对应物是路由对象上的 handle（数据模式配合 useMatches 读取）。组件式模式下，更通用的做法是元信息配置表——面包屑、菜单、守卫规则都从这一份配置派生（单一事实源，第 12 章 M1 直接复用）：

// src/router/routeMeta.js —— 路径模式 → 面包屑链；roles 在练习 3 与第 11 章启用
export const routeMeta = {
  '/dashboard': [{ title: '工作台' }],
  '/orders': [{ title: '订单管理' }],
  '/orders/new': [{ title: '订单管理', to: '/orders' }, { title: '新建订单' }],
  '/orders/:id': [{ title: '订单管理', to: '/orders' }, { title: '订单详情' }],
  '/customers': [{ title: '客户管理' }],
}

// src/layouts/Breadcrumbs.jsx —— 面包屑：支持 :id 参数模式匹配
import { useLocation, Link } from 'react-router'
import { routeMeta } from '@/router/routeMeta'

function matchMeta(pathname) {
  // 先精确匹配，再按「路径段数相同 + 动态段」匹配（/orders/1001 → /orders/:id）
  if (routeMeta[pathname]) return routeMeta[pathname]
  const segs = pathname.split('/').filter(Boolean)
  for (const pattern of Object.keys(routeMeta)) {
    const pSegs = pattern.split('/').filter(Boolean)
    if (pSegs.length !== segs.length) continue
    const matched = pSegs.every((seg, i) => seg.startsWith(':') || seg === segs[i])
    if (matched) return routeMeta[pattern]
  }
  return []
}

export default function Breadcrumbs() {
  const { pathname } = useLocation()
  const chain = matchMeta(pathname)
  if (chain.length === 0) return null
  return (
    <nav className="breadcrumbs" aria-label="面包屑">
      {chain.map((item, i) =>
        item.to && i < chain.length - 1 ? (
          <Link key={item.title} to={item.to}>{item.title}</Link>
        ) : (
          <span key={item.title}>{item.title}</span>
        ),
      )}
    </nav>
  )
}

7.9 滚动行为、路由过渡与部署回退

三个真实项目都会遇到的话题，点到为止（细节见官方文档，不杜撰 API 细节）：

• 滚动行为：SPA 切页不会自动回顶。数据模式提供 <ScrollRestoration />（仅数据路由可用）；组件式模式常见做法是在 Layout 里监听 location.pathname 变化后 window.scrollTo(0, 0)，或交给第 14 章统一治理。
• 路由过渡：React Router 的 Link/useNavigate 支持 viewTransition 选项启用浏览器 View Transitions API（Chrome/Edge 支持），一行属性即可获得淡入切换，进阶可配 CSS。
• history 路由与刷新 404：BrowserRouter 基于 History API，/orders/1001 是前端路由——用户刷新时浏览器会真的向服务器请求这个路径，服务器没有该文件就 404。解法是 Nginx try_files $uri /index.html; 把所有路径回退到 index.html（Vue 版第 07 章同款配置，两版部署完全一致）。若部署到对象存储子目录，BrowserRouter 换 HashRouter 是零成本兜底。

🛠 渐进式实战练习

所有练习在「轻订单」仓库的 react-app/ 中进行；Mock 数据先写死在 api/ 模块内（第 09 章换成真实请求层）。

练习 1 · 基础（10–20 min）：搭出中后台骨架

任务描述：完成 §7.2 的骨架——AdminLayout（Sider 菜单 + Content）、嵌套路由（dashboard / orders / customers）、/ 重定向到 /dashboard、404 页；Dashboard、OrderList、CustomerList 三个页面全部 React.lazy 懒加载，菜单用 NavLink 或 AntD Menu 实现当前页高亮。

提示：404 放路由表最后；菜单高亮判断当前路径前缀可用 useLocation().pathname.startsWith(key)；lazyPage 辅助组件直接抄 §7.2。

验收标准：

• [ ] 直接访问 / 显示工作台且地址栏变为 /dashboard；
• [ ] 刷新 /orders 页面内容不丢（开发服务器已处理回退）；DevTools Network 里三个页面各自按需加载 chunk；
• [ ] 访问 /not-exist 显示 404 页，菜单不高亮任何项；
• [ ] 控制台零警告。

// src/layouts/AdminLayout.jsx（完整版）
import { Outlet, NavLink } from 'react-router'
import { Layout as AntLayout, Menu } from 'antd'

const { Sider, Header, Content } = AntLayout

const MENU_ITEMS = [
  { key: '/dashboard', label: <NavLink to="/dashboard">工作台</NavLink> },
  { key: '/orders', label: <NavLink to="/orders">订单管理</NavLink> },
  { key: '/customers', label: <NavLink to="/customers">客户管理</NavLink> },
]

export default function AdminLayout() {
  return (
    <AntLayout style={{ minHeight: '100vh' }}>
      <Sider>
        <div className="logo">轻订单</div>
        <Menu theme="dark" mode="inline" items={MENU_ITEMS} />
      </Sider>
      <AntLayout>
        <Header className="topbar"><Breadcrumbs /></Header>
        <Content className="page-container"><Outlet /></Content>
      </AntLayout>
    </AntLayout>
  )
}

练习 2 · 进阶（30–60 min）：订单详情 + 面包屑 + 筛选回传

任务描述：①实现 /orders/:id 详情页：读取 useParams，从 mock 列表找到对应订单（orderNo 形如 QO20260929000001），展示基本信息；列表页点行进入详情。②按 §7.8 实现面包屑，详情页显示「订单管理 / 订单详情」且可点回列表。③订单列表的关键词、状态、页码写入 URL（§7.5），刷新后筛选与页码原样还原；从详情页返回列表，筛选仍在。

提示：详情页匹配 mock 数据找不到时显示「订单不存在」而不是白屏；返回列表用 navigate(-1) 还是 Link to="/orders"？想清楚「用户可能直接刷新进详情页」的场景（此时没有历史可退），用 Link 更稳。

验收标准：

• [ ] /orders/任意假id 不白屏，有「订单不存在」提示；
• [ ] 面包屑对 /orders/new、/orders/1001 都正确（不把动态段当死路径）；
• [ ] 设置筛选后刷新页面，keyword/status/page 从 URL 还原，表格数据与筛选一致；
• [ ] 改状态筛选时页码自动回 1。

练习 3 · 挑战（选做，60+ min）：权限路由 + 403 页 + 登录回跳

任务描述：①封装 ProtectedRoute（补全 §7.7 中 useLocation 的使用），包住整个后台分支；②路由元信息 routeMeta 每项增加 roles 数组（如 /settings 仅 super_admin），ProtectedRoute 读元信息：已登录但无角色 → 重定向 /403；③新建 403 页（显示「无权限访问」+ 返回工作台按钮）；④未登录访问 /orders 跳登录页，登录页读取 location.state.from，登录成功后回跳原路径。

提示：mock 登录：localStorage.setItem('qing_access_token', 'mock-token') + localStorage.setItem('qing_role', 'sales') 即可；from 回跳要校验必须以 / 开头（防开放重定向，第 11 章展开）。

验收标准：

• [ ] 未登录直接输 URL /orders → 落在 /login；登录后回到 /orders 且筛选参数不丢；
• [ ] 把 qing_role 设为 sales 后访问 /settings → 403 页；设为 super_admin 后可访问；
• [ ] 登录页直接访问时点登录回 /dashboard（from 为空的兜底）。

// src/router/ProtectedRoute.jsx —— 登录 + 页面级权限双拦截
import { Navigate, Outlet, useLocation } from 'react-router'
import { auth } from '@/utils/auth'
import { matchMeta } from '@/layouts/Breadcrumbs' // 把匹配逻辑导出复用
import { routeMeta } from '@/router/routeMeta'

export default function ProtectedRoute() {
  const location = useLocation()
  if (!auth.isLoggedIn()) {
    const from = location.pathname + location.search
    return <Navigate to="/login" replace state={{ from }} />
  }
  const chain = matchMeta(location.pathname)
  const pattern = Object.keys(routeMeta).find((p) => routeMeta[p] === chain)
  const requiredRoles = routeMeta[pattern]?.roles
  const role = localStorage.getItem('qing_role')
  if (requiredRoles?.length > 0 && !requiredRoles.includes(role)) {
    return <Navigate to="/403" replace />
  }
  return <Outlet />
}

const handleSubmit = (e) => {
  e.preventDefault()
  auth.setToken('mock-token')
  const from = location.state?.from ?? '/dashboard'
  // 只允许站内路径，防开放重定向：外部链接一律回工作台
  navigate(from.startsWith('/') ? from : '/dashboard', { replace: true })
}

⚠️ 常见易错点

易错点 1 · params 变化，页面「不动」

❌ 错误代码：

// /orders/1001 → /orders/1002 后界面还是 1001 的数据
export default function OrderDetail() {
  const { id } = useParams()
  useEffect(() => { loadOrder('1001') }, []) // 依赖数组为空：只在挂载时拉一次
  // ...
}

错误原因：同一路由组件在参数变化时被复用，不会重新挂载，空依赖的 useEffect 不再执行；而闭包里还可能固化了旧 id（闭包过期，第 04 章讲过）。

✅ 正确写法：

export default function OrderDetail() {
  const { id } = useParams()
  useEffect(() => { loadOrder(id) }, [id]) // id 变化 → 重新拉取
  // ...
}

（临时兜底也可用 key 强制重建，但优先治本。）

易错点 2 · 渲染期间调用 useNavigate

❌ 错误代码：

function Login() {
  const navigate = useNavigate()
  if (auth.isLoggedIn()) {
    navigate('/dashboard') // 💥 Cannot update a component while rendering…
  }
  return <form>…</form>
}

错误原因：渲染函数必须是纯的；渲染期间触发导航会引发「渲染中更新其他组件」的警告与不可预测的循环。

✅ 正确写法：

function Login() {
  const navigate = useNavigate()
  useEffect(() => {
    if (auth.isLoggedIn()) navigate('/dashboard', { replace: true })
  }, [navigate]) // 副作用放 useEffect；事件回调里调用同理安全
  return <form>…</form>
}

易错点 3 · 懒加载没包 Suspense

❌ 错误代码：

const OrderList = lazy(() => import('./views/orders/OrderList'))
// ...
<Route path="orders" element={<OrderList />} /> // 💥 chunk 未就绪时抛错/白屏

错误原因：lazy() 组件在模块加载完成前处于「挂起」状态，必须存在 Suspense 边界提供 fallback，否则整树报错。

✅ 正确写法：

<Suspense fallback={<div className="page-loading">页面加载中…</div>}>
  <Route path="orders" element={<OrderList />} />
</Suspense>
// 更优：像 §7.2 一样用 LazyPage 统一包裹，或把 Suspense 放在 <Outlet /> 外层

易错点 4 · NavLink 高亮「传染」：/orders 把 /orders/new 也点亮

❌ 错误代码：

<NavLink to="/orders" className="active-when-matched">订单管理</NavLink>
// 结果：进入 /orders/new、/orders/1001 时「订单管理」一直处于选中态

错误原因：NavLink 默认「当前路径以 to 开头」即激活（这是刻意的，菜单场景多数时候正确）；但需要「仅自身激活」时必须显式声明。

✅ 正确写法：

<NavLink to="/orders" end className={({ isActive }) => (isActive ? 'active' : '')}>
  订单管理
</NavLink>

end 表示「完整匹配才激活」；/orders 与 /orders/:id 共用菜单时，就保留默认前缀匹配并自行取舍。

易错点 5 · useSearchParams 增删互相覆盖

❌ 错误代码：

setSearchParams({ status: 'approved' })           // 把 keyword、page 全弄丢了
setSearchParams(new URLSearchParams())            // 一次性清空，误伤其他筛选

错误原因：setSearchParams(对象) 是整体替换，不是增量合并——只传一个字段就等于「其他字段全部删除」。

✅ 正确写法：

setFilter({ status: 'approved' }) // 始终基于当前 searchParams 构造新对象再增删
// 即 §7.5 的 setFilter：new URLSearchParams(searchParams) → 增删 → setSearchParams(next)

易错点 6 · 直接改 searchParams 对象

❌ 错误代码：

searchParams.set('page', '2') // 顺手改了对象……地址栏却纹丝不动

错误原因：useSearchParams 返回的实例是不可变快照，直接 .set 不触发任何更新，React Router 感知不到变化。

✅ 正确写法：

const next = new URLSearchParams(searchParams)
next.set('page', '2')
setSearchParams(next) // 让 Router 感知：通过 setter 提交新值

✅ 最佳实践

1. 路由表是唯一事实源：路径、嵌套、重定向、404 全在 App.jsx 一处；元信息（标题/roles）收敛进 routeMeta，菜单、面包屑、守卫都从它派生，改一处全局生效。
2. 页面全部懒加载 + 统一 Suspense：路由级分割是首屏体积的最大杠杆，LazyPage 一个辅助组件让纪律零成本。
3. 筛选条件住进 URL：列表页状态用 useSearchParams 而不是 useState，刷新回填、可分享、可回退，还天然成为第 09 章请求参数的来源。
4. 守卫即组件：ProtectedRoute 组合进路由树，登录拦截与角色拦截分层；不要在各个页面里散落「if (!登录) 跳转」。
5. replace 用在「步骤替换」语义处：登录、重定向、提交成功跳详情，避免用户后退回到过期页面。
6. 部署配好 SPA 回退：Nginx try_files $uri /index.html; 与 Vue 版完全一致，上线检查单里永远有这一条。
7. params 组件复用问题靠 useEffect 依赖治本：key 重建只做兜底；第 09 章接入 TanStack Query 后此问题自动消失。
8. 404 与异常路径有兜底：* 路由 + 详情页「订单不存在」分支，任何 URL 都不给用户白屏。

📌 本章小结

1. React Router 7 组件式用 <Routes>/<Route> 声明路由，<Outlet /> 是嵌套出口，Layout 壳与内容彻底解耦。
2. 路由懒加载 = React.lazy + Suspense，每个页面独立 chunk；守卫 = ProtectedRoute 组件组合进路由树，Navigate 承担重定向。
3. useParams 读动态参数（组件会被复用），useSearchParams 让筛选住进 URL 成为唯一事实源，useNavigate 负责编程式导航。
4. 元信息驱动面包屑/菜单/权限，单一事实源思想贯穿配置层；history 路由必须配服务端回退。
5. 下一章把「登录用户态、字典缓存、订单暂存区」从组件里搬出来——Redux Toolkit 与 Zustand 登场，ProtectedRoute 里的 auth.isLoggedIn() 也会升级为真正的全局状态。

📄 第 08 章 · 状态管理 —— Redux Toolkit 与 Zustand 08-状态管理-ReduxToolkit与Zustand.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：6 小时｜🔗 前置：第 07 章

⬅ 上一章：路由系统 ｜ 📖 本版目录 ｜ ➡ 下一章：服务端交互

💡 对照学习：本页是 React 版第 08 章，对应 Vue 版第 08 章 · Pinia 实战，两版练习任务完全一致（用户态 store → 字典缓存 → 订单暂存区）。概念映射：slice ≈ Pinia store（defineStore）；reducer + action ≈ store 的 state + 函数；useSelector ≈ storeToRefs / getter；createAsyncThunk ≈ actions 里的异步函数；extraReducers ≈ 监听自身/外部 action；RTK 内置 Immer 的「看似直接改」≈ Pinia proxy 的「直接改」；Zustand ≈ Pinia 的轻量体感；persist 中间件 ≈ pinia-plugin-persistedstate；Redux DevTools ≈ Vue Devtools 的状态面板。

🎯 学习目标

学完本章，你将能够：

1. 用「本地 UI 态 / 服务端态 / 跨页共享态」三分法判断一段状态该放哪里，说出把服务端数据塞进全局 store 的代价；
2. 用 configureStore 组装 RTK store 并挂上 Provider，说出中间件与 DevTools 的默认配置；
3. 用 createSlice 编写 userSlice，理解 RTK 内置 Immer 后「写法像直接改、实际是不可变更新」的机制；
4. 用 useSelector 订阅状态，解释「selector 返回新引用导致重渲染风暴」的成因并用 createSelector 治理；
5. 用 createAsyncThunk + extraReducers 编写带 pending/fulfilled/rejected 三态的异步逻辑，并用 unwrap 在组件里接住错误；
6. 用 Zustand 5 实现同一个用户态，对比两种方案在样板量、订阅粒度、中间件上的差异并给出选型结论；
7. 实现订单暂存区（跨页草稿）并用 persist 中间件完成持久化，说出哪些状态不该持久化。

📖 核心知识点

8.1 何时需要全局状态：状态三分法

React 组件间共享数据有两条路：props 逐层传递与全局状态。判断标准不是「几层」而是「谁在用」：

初学者最常见的两种病：什么都不敢放全局（props 穿五六层）与什么都放全局（把接口数据、表单草稿、甚至路由参数全塞 store，最后没人敢动）。三分法是第 09 章的心智地基：服务端态交给请求库，store 只管「应用自己的状态」。

React 生态里跨页共享态的两个主流答案：

• Redux Toolkit（RTK）：规范最全（slice/thunk/selector/中间件生态/DevTools），团队协作友好，企业存量项目多；
• Zustand：极简（一个 create），订阅粒度天然到 selector 级，中小项目与局部状态岛首选。

本章两个都教：先 RTK 建立规范心智，再 Zustand 体会轻量取舍——面试与存量代码都躲不开 RTK，新项目里 Zustand 的占比在快速上升。

8.2 RTK 快速上手：configureStore 与 Provider

pnpm add @reduxjs/toolkit react-redux

// src/store/index.js —— 组装 store：reducer 目录 + 默认内置 DevTools
import { configureStore } from '@reduxjs/toolkit'
import userReducer from './userSlice'
import dictReducer from './dictSlice'

export const store = configureStore({
  reducer: {
    user: userReducer, // state.user
    dict: dictReducer, // state.dict
  },
  // middleware 与 devTools 有合理默认值（含 thunk 中间件、Redux DevTools 开关），
  // 没有明确理由不要手写覆盖——这是 RTK 的设计立场
})

// src/main.jsx —— Provider 包住整棵树（在 BrowserRouter 内外均可，习惯放外层）
import { Provider } from 'react-redux'
import { store } from './store'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <Provider store={store}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </Provider>
  </StrictMode>,
)

要点：一个应用一个 store（不像 Pinia 可以多个 store 实例并存）；store 内部按 slice 分区；安装 Redux DevTools 浏览器扩展后，RTK 默认接好，无需配置。

8.3 createSlice：reducer、action 与不可变更新

第 04 章讲过 React 的铁律「state 不可变更新」。RTK 的答案是内置 Immer：reducer 里可以「像直接改一样写」，Immer 在背后生成不可变新对象——写法手感与 Pinia 的 proxy 直改几乎一样，但机制（Proxy 拦截写操作、产出新引用）是纯不可变。

// src/store/userSlice.js —— 用户态 slice（对应 Vue 版 useUserStore）
import { createSlice } from '@reduxjs/toolkit'

const initialState = {
  profile: null,      // { id, name, role } role: super_admin | operator | sales | finance
  status: 'idle',     // idle | loading | succeeded | failed
  error: '',
}

const userSlice = createSlice({
  name: 'user', // 前缀：action.type 形如 'user/clearUser'
  initialState,
  reducers: {
    // Immer 生效：可以「直接赋值」，无需展开拷贝
    setUser(state, action) {
      state.profile = action.payload // 看似直接改，实际产出不可变新 state
    },
    clearUser(state) {
      state.profile = null
      state.status = 'idle'
      state.error = ''
    },
  },
})

export const { setUser, clearUser } = userSlice.actions
export default userSlice.reducer

组件中使用（dispatch + useSelector）：

// src/views/ProfileCard.jsx —— 读写用户态
import { useDispatch, useSelector } from 'react-redux'
import { setUser, clearUser } from '@/store/userSlice'

export default function ProfileCard() {
  const dispatch = useDispatch()
  const profile = useSelector((s) => s.user.profile) // 订阅：store 变化 → 重新计算 → 按需重渲染

  if (!profile) return <p>未登录</p>
  return (
    <div>
      <p>{profile.name}（{profile.role}）</p>
      <button onClick={() => dispatch(setUser({ ...profile, name: '青云-运营小李' }))}>
        改名（演示 dispatch）
      </button>
      <button onClick={() => dispatch(clearUser())}>登出</button>
    </div>
  )
}

心智对照：state.user ≈ Pinia 的 store state；setUser ≈ store 里的一个 action 函数；区别是 React 版必须显式 dispatch，且读数据走 useSelector 订阅。

8.4 selector 与引用稳定性

useSelector 每次 store 变化都会重跑，用返回值引用决定要不要重渲染。这带来一个 RTK 世界的经典陷阱：selector 里每次返回新数组/新对象 → 引用永远不同 → 组件无意义重渲染甚至死循环：

// ❌ 每次调用 filter 都产生新数组引用
const pendingOrders = useSelector((s) => s.orders.list.filter((o) => o.status === 'pending_review'))

治理方案是 memoized selector（RTK 内置 reselect 的 createSelector）：输入不变就复用上次输出：

// src/store/ordersSlice.js —— 导出 selector，与 reducer 放一起内聚
import { createSelector } from '@reduxjs/toolkit'

export const selectPendingOrders = createSelector(
  [(s) => s.orders.list], // 输入
  (list) => list.filter((o) => o.status === 'pending_review'), // 输入不变则不重算、引用复用
)

// 组件里：const pendingOrders = useSelector(selectPendingOrders) ✅

三条纪律：订阅最小面（s.user.profile.name 只订阅名字，别订阅整个 user）；派生数据放 selector 不放 state（能算出来的不存储，≈ Pinia getter 的缓存语义）；selector 返回引用稳定值（原始值、既有引用或 createSelector 产物）。

8.5 异步：createAsyncThunk 与 extraReducers

reducer 必须是纯函数，异步逻辑住进 thunk。createAsyncThunk 自动派发 pending/fulfilled/rejected 三种 action，在 extraReducers 里响应（对应 Vue 版在 store action 里自己管理 loading 三态）：

// src/store/userSlice.js 追加 —— 登录 thunk
import { createSlice, createAsyncThunk } from '@reduxjs/toolkit'
import { login as loginApi } from '@/api/auth' // 第 09 章补全真正实现，先 mock

export const login = createAsyncThunk('user/login', async (credentials, { rejectWithValue }) => {
  try {
    const data = await loginApi(credentials) // { profile, accessToken, refreshToken }
    return data
  } catch (err) {
    return rejectWithValue(err.message ?? '登录失败') // 把业务错误变成 action.payload
  },
})

const userSlice = createSlice({
  // ...reducers 同上
  extraReducers: (builder) => {
    builder
      .addCase(login.pending, (state) => {
        state.status = 'loading'
        state.error = ''
      })
      .addCase(login.fulfilled, (state, action) => {
        state.status = 'succeeded'
        state.profile = action.payload.profile
        // token 的存储位置与 XSS 权衡是第 11 章专题，这里先随 payload 记录
        state.token = action.payload.accessToken
      })
      .addCase(login.rejected, (state, action) => {
        state.status = 'failed'
        state.error = action.payload // rejectWithValue 的产物
      })
  },
})

组件里两种消费姿势：

// 姿势一：订阅三态渲染 UI（受控感强，适合登录页大表单）
const status = useSelector((s) => s.user.status)
const error = useSelector((s) => s.user.error)

// 姿势二：unwrap 把 thunk 当 Promise 用（轻快，适合按钮动作）
import { unwrapResult } from '@reduxjs/toolkit'
try {
  const data = await dispatch(login(credentials)).unwrap() // rejected 时真正 throw
  navigate('/dashboard', { replace: true })
} catch (err) {
  message.error(err.message)
}

thunk 第二个参数还能拿到 getState/dispatch——跨 slice 协作（Vue 版「store 互相调用」的对应物）：先读 getState().user.profile 做前置校验，或 dispatch(另一个slice的action)。

8.6 实战一：字典缓存 dictSlice（并发去重）

商品分类、客户等级这类字典全站共用，进多个页面都触发请求就浪费了。用 thunk 的 condition 选项做加载中去重 + 成功后复用（对应 Vue 版字典 store 的并发去重）：

// src/store/dictSlice.js —— 字典缓存：一份字典全站复用
import { createSlice, createAsyncThunk } from '@reduxjs/toolkit'
import { fetchSkuCategories as fetchApi } from '@/api/dict'

export const loadSkuCategories = createAsyncThunk(
  'dict/loadSkuCategories',
  fetchApi,
  {
    condition: (_arg, { getState }) => {
      const { status } = getState().dict.skuCategories
      return status !== 'loading' // 加载中 → 直接跳过本次 dispatch，天然防重复请求
    },
  },
)

const dictSlice = createSlice({
  name: 'dict',
  initialState: {
    skuCategories: { status: 'idle', data: [] },
  },
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(loadSkuCategories.pending, (state) => { state.skuCategories.status = 'loading' })
      .addCase(loadSkuCategories.fulfilled, (state, action) => {
        state.skuCategories = { status: 'succeeded', data: action.payload }
      })
      .addCase(loadSkuCategories.rejected, (state) => { state.skuCategories.status = 'failed' })
  },
})

export default dictSlice.reducer

组件里「没数据就触发一次」，其余组件只管订阅：

// src/components/CategoryFilter.jsx —— 字典消费组件
import { useEffect } from 'react'
import { useDispatch, useSelector } from 'react-redux'
import { loadSkuCategories } from '@/store/dictSlice'

export default function CategoryFilter({ value, onChange }) {
  const dispatch = useDispatch()
  const { status, data } = useSelector((s) => s.dict.skuCategories)

  useEffect(() => {
    if (status === 'idle') dispatch(loadSkuCategories()) // 只在从未加载过时发请求
  }, [status, dispatch])

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">全部分类</option>
      {data.map((c) => <option key={c.id} value={c.id}>{c.name}</option>)}
    </select>
  )
}

8.7 Zustand 5：更轻的选择

Zustand 把「全局状态」压缩到一个 create 调用：没有 Provider、没有 dispatch、没有 slice 边界，一个 hook 就是 store：

pnpm add zustand

// src/store/useUserStore.js —— Zustand 版用户态（与 userSlice 同职责）
import { create } from 'zustand'
import { login as loginApi } from '@/api/auth'

export const useUserStore = create((set, get) => ({
  profile: null,
  isReady: false, // 会话恢复是否完成（第 11 章使用）
  async login(credentials) {
    const data = await loginApi(credentials) // 异步直接写，无需 thunk
    set({ profile: data.profile })
    return data
  },
  logout() {
    set({ profile: null })
  },
  setReady: (ready) => set({ isReady: ready }),
}))

// 消费：selector 订阅到「字段级」，粒度天然最优
const profile = useUserStore((s) => s.profile) // 只订阅 profile
const login = useUserStore((s) => s.login)     // 函数引用稳定，可安全进 useEffect 依赖

<button onClick={() => login(credentials)}>登录</button>

与 RTK 的核心差异：

• 没有 dispatch：调 action 就是调函数；没有 Provider：hook 直接用；
• 订阅粒度：Zustand 的 selector 只在返回值变化（默认严格相等）时重渲染，写字段级 selector 天然精确；需要返回对象时配 useShallow（从 zustand/react/shallow 导入）做浅比较；
• 异步零样板：不需要 thunk，async 函数直接写进 store。

8.8 选型决策表 + DevTools + 持久化

怎么选（两版教程口径保持一致）：

两者都不该装服务端态——那是第 09 章 TanStack Query 的领地。

调试：RTK 默认接 Redux DevTools（时间旅行、action 流、diff）；Zustand 加 devtools 中间件（zustand/middleware）即可同样接入。装浏览器扩展 + console.log 退役。

持久化：Vue 版用 pinia-plugin-persistedstate，React 版对应物是 persist 中间件（Zustand 原生支持最顺，示例见练习 3）；RTK 生态用 redux-persist（样板较多，本教程不展开，官网 https://redux-toolkit.js.org 检索 persist）。记住红线：token 是否持久化要过安全评审（第 11 章），用户敏感数据与大面积服务端数据不进 localStorage。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）：用户态 store

任务描述：用 RTK 实现 userSlice：setUser / clearUser 两个 reducer；profile 形如 { id: 'u001', name: '青云-运营小李', role: 'operator' }。在顶栏加一个 ProfileBadge 组件显示姓名与角色，未登录显示「未登录」；再提供一个「切换角色」按钮循环 operator → sales → finance → super_admin（为第 11 章权限调试埋点）。

提示：先写 slice 再挂 store 最后在组件订阅，三步各验证一次 DevTools 里的 action 流；「切换角色」一个 action 就够，别写四个。

验收标准：

• [ ] DevTools 能看到 user/setUser、user/clearUser 的完整 action 与 state diff；
• [ ] 切换角色后顶栏徽标即时更新，且只有顶栏重渲染（React DevTools Highlight updates 验证）；
• [ ] useSelector 无「每次返回新对象」的写法。

// userSlice reducers 追加
const ROLE_CYCLE = ['operator', 'sales', 'finance', 'super_admin']

const userSlice = createSlice({
  name: 'user',
  initialState,
  reducers: {
    setUser(state, action) { state.profile = action.payload },
    clearUser(state) { state.profile = null },
    cycleRole(state) {
      if (!state.profile) return
      const next = ROLE_CYCLE[(ROLE_CYCLE.indexOf(state.profile.role) + 1) % ROLE_CYCLE.length]
      state.profile = { ...state.profile, role: next } // Immer 下也可直接 state.profile.role = next
    },
  },
  extraReducers: { /* 登录 thunk 略 */ },
})
export const { setUser, clearUser, cycleRole } = userSlice.actions

练习 2 · 进阶（30–60 min）：字典缓存与并发去重

任务描述：实现 dictSlice + loadSkuCategories thunk（§8.6 可直接参考）：mock 接口延迟 800ms 返回 [{ id: 'c01', name: '智能硬件' }, { id: 'c02', name: '配件耗材' }, { id: 'c03', name: '软件服务' }]。在「新建订单」与「商品目录」两个页面都放分类下拉。用 DevTools Network（或 console 计数）验证：两页切换来回多次，只有第一次真正发请求；加载中有「字典加载中…」占位。

提示：去重靠 condition 选项 + status !== 'loading'；「已成功就不再请求」要在 condition 里同时判断 status !== 'succeeded'？想清楚：练习要求是「只发一次」还是「失败后可重试」——推荐 loading 拦截 + 组件层 status === 'idle' 才 dispatch，失败态（failed）下次仍可重试。

验收标准：

• [ ] 首次进入任一页面发 1 次请求；800ms 内火速切到另一页，第二页不发请求且拿到同一份数据；
• [ ] 请求失败后再进页面能重试（failed → 重新 dispatch 可发请求）；
• [ ] 下拉渲染期间无重复 key 警告。

export const loadSkuCategories = createAsyncThunk(
  'dict/loadSkuCategories',
  async (_arg, { getState, rejectWithValue }) => {
    try {
      return await fetchSkuCategories() // mock: new Promise(r => setTimeout(() => r(DATA), 800))
    } catch (err) {
      return rejectWithValue(err.message)
    }
  },
  {
    condition: (_arg, { getState }) => {
      const { status } = getState().dict.skuCategories
      return status === 'idle' || status === 'failed' // 加载中/已成功都不发；失败可重试
    },
  },
)

练习 3 · 挑战（选做，60+ min）：订单暂存区完整闭环

任务描述：用 Zustand + persist 实现订单暂存区（对应附录A「草稿 draft」状态的业务事实：新建订单填一半离开页面，回来还在）：useDraftStore 维护 customerId、items（明细行数组）；action：setCustomerId / addItem / updateItem(key, patch) / removeItem(key) / clear；持久化到 localStorage（key 用 qing-draft-order）；在「新建订单」页添加一行、跳到「订单列表」再回来，草稿仍在；「清空草稿」按钮带确认。

提示：明细行要带自增 _key 作稳定标识（删除不串位，第 10 章 useFieldArray 会再遇到同一个问题）；persist 的 partialize 可以只存业务字段不存临时态。

验收标准：

• [ ] 刷新浏览器后草稿仍在（persist 生效）；清空后 localStorage 中 qing-draft-order 被清理；
• [ ] 删除中间一行后，其余行的内容不错位（key 稳定）；
• [ ] store 代码里没有「直接修改返回对象」的写法，全部经 set 产出新 state。

// src/store/useDraftStore.js —— 订单暂存区：Zustand + persist
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

let seq = 0
const nextKey = () => `item_${Date.now()}_${seq++}` // 行级稳定标识

export const useDraftStore = create(
  persist(
    (set) => ({
      customerId: '',
      items: [],
      setCustomerId: (customerId) => set({ customerId }),
      addItem: (item) => set((s) => ({ items: [...s.items, { ...item, _key: nextKey() }] })),
      updateItem: (key, patch) =>
        set((s) => ({
          items: s.items.map((it) => (it._key === key ? { ...it, ...patch } : it)),
        })),
      removeItem: (key) => set((s) => ({ items: s.items.filter((it) => it._key !== key) })),
      clear: () => set({ customerId: '', items: [] }),
    }),
    {
      name: 'qing-draft-order',
      partialize: (s) => ({ customerId: s.customerId, items: s.items }), // 只持久化业务数据
    },
  ),
)

const items = useDraftStore((s) => s.items)
const removeItem = useDraftStore((s) => s.removeItem)
// 渲染明细行时：items.map(it => <Row key={it._key} ... onRemove={() => removeItem(it._key)} />)

⚠️ 常见易错点

易错点 1 · 绕过 store 直接改数据

❌ 错误代码：

const profile = useSelector((s) => s.user.profile)
profile.name = '改个名'          // 💥 直接改订阅来的对象
useUserStore.setState((s) => { s.items.push(newItem) }) // Zustand 里绕过 set 直接改

错误原因：RTK 的 Immer 只在 reducer 内部生效；组件里拿到的是真实引用，直接改不会触发订阅更新（或触发后引用混乱），且 DevTools 里看不到任何 action。Zustand 同理，一切变更必须走 set。

✅ 正确写法：

dispatch(setUser({ ...profile, name: '改个名' })) // RTK：action 驱动
useUserStore.setState((s) => ({ items: [...s.items, newItem] })) // Zustand：set 产新引用

（在 reducer 内写 state.profile = payload 是正确且推荐的——那是 Immer 的合法语法，别混淆边界。）

易错点 2 · selector 返回新引用 → 重渲染风暴

❌ 错误代码：

const pending = useSelector((s) => s.orders.list.filter((o) => o.status === 'pending_review'))
const summary = useSelector((s) => ({ total: s.orders.total, count: s.orders.count }))

错误原因：filter 每次返回新数组、对象字面量每次是新引用；任何无关 action 导致 store 变化时，useSelector 严格比较引用失败 → 组件重渲染，大列表下性能崩塌（第二种写法还可能引发「store 变化 → setState → 再渲染」的循环警告）。

✅ 正确写法：

const pending = useSelector(selectPendingOrders) // createSelector：输入不变引用复用

import { useShallow } from 'zustand/react/shallow' // Zustand 的对应解法
const summary = useUserStore(useShallow((s) => ({ total: s.total, count: s.count })))

易错点 3 · 把异步逻辑塞进 reducer

❌ 错误代码：

const userSlice = createSlice({
  reducers: {
    async login(state, action) { // 💥 reducer 不允许是异步函数
      const data = await loginApi(action.payload)
      state.profile = data.profile
    },
  },
})

错误原因：reducer 必须是同步纯函数（Redux 的时间旅行、日志、回放全都建立在「同一 action 必产出同一 state」之上）。异步副作用属于 thunk 或 Zustand 的 action 函数。

✅ 正确写法：

export const login = createAsyncThunk('user/login', (credentials) => loginApi(credentials))
// 异步在 thunk，结果经 extraReducers 写回 state（见 §8.5）

易错点 4 · thunk 报错被吞：组件里 try/catch 捕不到

❌ 错误代码：

try {
  await dispatch(login(credentials)) // rejected 时并不会 throw！
  navigate('/dashboard')             // 💥 登录失败也会跳转
} catch (err) {
  message.error('登录失败')
}

错误原因：dispatch(thunk) 返回的 Promise 默认不会 reject（错误被装进 action.error/payload 交给 extraReducers），try/catch 形同虚设。

✅ 正确写法：

try {
  await dispatch(login(credentials)).unwrap() // unwrap：rejected 转成真正的 throw
  navigate('/dashboard', { replace: true })
} catch (err) {
  message.error(err.message) // rejectWithValue 的内容在这里接住
}

（Zustand 版没有这个问题——async action 就是普通 Promise。）

易错点 5 · 状态放错层：什么都进全局 store

❌ 错误代码：

// 把「服务端缓存」和「页面临时态」都塞进 store
ordersSlice: 存订单列表数据（要自己处理 loading/竞态/失效……）
uiSlice:    存「弹窗是否打开」「表格选中行」（切页即弃的 UI 态全局化）

错误原因：订单列表是服务端态——放 store 意味着你要自己实现缓存失效、竞态取消、重试，等于手写半个请求库；弹窗开关这类本地态进全局，导致 store 膨胀、组件无法独立复用。

✅ 正确写法：

// 三分法归位：
// 服务端态 → TanStack Query（第 09 章）
// 跨页共享态 → store（用户态/字典/草稿，本章内容）
// 本地 UI 态 → useState 留在组件里

易错点 6 · 持久化不加节制

❌ 错误代码：

persist(store, { name: 'qing-app' }) // 整棵 state 树原样落盘
// 结果：用户 token、草稿、字典、甚至临时 loading 态全部进 localStorage

错误原因：localStorage 无过期、无加密、XSS 可读（第 11 章专题）；把易变的服务端数据落盘还会造成「缓存了旧数据还不知道」的幽灵 bug。

✅ 正确写法：

persist(api, {
  name: 'qing-draft-order',
  partialize: (s) => ({ customerId: s.customerId, items: s.items }), // 白名单：只存该存的
})
// 清单：草稿 ✅；token → 第 11 章单独评审；字典/订单数据 ❌（它们有各自的缓存层）

✅ 最佳实践

1. 先过三分法再写 store：任何「要不要放全局」的争论，用「本地 UI 态 / 服务端态 / 跨页共享态」一句话裁决。
2. slice 即模块：RTK 里 reducer、action、selector、thunk 写在同一个 slice 文件里内聚导出，找代码只认 slice 名（≈ Pinia 一个 store 一个文件）。
3. selector 订阅最小面：订阅到字段级；派生计算进 createSelector，组件里零 filter/map。
4. Immer 双面记牢：reducer 内可直改（Immer 代理），reducer 外一切走 dispatch/set——把这条写进团队 ESLint 心智。
5. 异步三态显式建模：idle/loading/succeeded/failed 四态是字典类数据的通用模板；组件里永远有 loading 与 error 分支。
6. Zustand selector 一律带函数：useUserStore((s) => s.x) 而非整个 store；返回对象配 useShallow。
7. 持久化走白名单：partialize 列字段，敏感数据不落盘，落盘 key 统一 qing- 前缀可识别。
8. DevTools 参与开发流：提 PR 前自己先看一遍 action 流是否干净——能被回放的状态才有可调试性。

📌 本章小结

1. 状态三分法：本地 UI 态留组件、服务端态交给第 09 章的 TanStack Query、跨页共享态进 store——选型先于写码。
2. RTK 四件套：configureStore（默认带 DevTools）、createSlice（内置 Immer，reducer 内可直改）、useSelector + createSelector（订阅与引用稳定性）、createAsyncThunk + extraReducers（异步三态，unwrap 让错误真正可捕获）。
3. Zustand 用一个 create 覆盖同职责场景：无 Provider、无 dispatch、selector 级订阅、persist 一行持久化；选型看团队规模与存量约束。
4. 用户态、字典缓存、订单暂存区三个「轻订单」真实状态已就位，第 11 章的鉴权体系直接复用。
5. 下一章进入服务端交互：axios 请求层与拦截器两版同构，而 TanStack Query 会把本章里你差点手写的「缓存、失效、竞态」全部接管——store 从此更瘦。

📄 第 09 章 · 服务端交互与 TanStack Query 09-服务端交互与TanStackQuery.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：7 小时｜🔗 前置：第 08 章

⬅ 上一章：状态管理 ｜ 📖 本版目录 ｜ ➡ 下一章：表单处理

💡 对照学习：本页是 React 版第 09 章，对应 Vue 版第 09 章 · 服务端交互与接口层设计，两版练习任务完全一致（request 实例 → 无感刷新并发验证 → useOrderList 强化版）。概念映射：axios 实例与拦截器两版完全同构；本页的 useOrderList（TanStack Query 版）≈ Vue 版自研 useOrderList composable；queryKey ≈ 请求依赖参数；useQuery 的缓存/去重/竞态取消 ≈ Vue 版手写的 AbortController + 缓存 Map；invalidateQueries ≈ 手动 reload()；useMutation 乐观更新 ≈ 「先改本地再同步服务端」手写逻辑。两章读完你会发现：手写过的每一行基建，Query 都有对应物。

🎯 学习目标

学完本章，你将能够：

1. 按四层分工（请求层 / API 模块 / 数据编排 Hook / 视图）组织接口代码，说出每层的禁止事项；
2. 封装 axios 实例：baseURL 环境变量化、token 注入、统一解包、ApiError 错误归一化、silent 静默选项；
3. 实现附录A 的 40102 无感刷新：单飞锁 + 请求重放 + _retried 死循环防护，并画出完整时序；
4. 解释竞态（先发后至）的成因，用 AbortController 与「查询键变更丢弃旧结果」两种手段治理；
5. 配置 TanStack Query v5（QueryClientProvider），用 useQuery 声明式获取数据并说出 staleTime 与缓存策略的关系；
6. 用 useMutation + invalidateQueries 完成写操作后的缓存失效，用 onMutate 实现乐观更新与回滚；
7. 编写并复用 useOrderList Hook：URL 筛选 → 防抖 → Query 缓存 → 分页翻页不闪烁，对应 Vue 版同名 composable。

📖 核心知识点

9.1 接口层的四层分工

企业项目接口代码混乱的根源是不分层：组件里直接 axios.get、错误处理五花八门、同一接口三处重复。约定四层：

src/utils/request.js       —— 传输层：axios 实例、拦截器、token、错误归一化（全站唯一）
src/api/*.js               —— 接口层：一个业务域一个文件，只描述「接口长什么样」
src/hooks/useOrderList.js  —— 数据编排层：缓存、分页、防抖、失效（业务无感知）
src/views/orders/*.jsx     —— 视图层：只消费数据与动作，禁止 import axios

四条禁令：视图层禁止直接 import axios；API 层禁止出现组件逻辑（loading、跳转）；数据编排只写在 hooks 里；错误 toast 全站只在请求层弹一次。这四条让「改接口超时时间」「换错误提示组件」变成一处改动。

9.2 axios 实例与环境变量

pnpm add axios @tanstack/react-query antd

# .env.development —— 开发环境：走 Vite 代理打本地 mock（vite.config.js 里配 proxy）
VITE_API_BASE_URL=/api/v1
# .env.production
VITE_API_BASE_URL=https://api.qingorder.example.com/api/v1

// src/utils/request.js —— 传输层：全站唯一的 axios 实例
import axios from 'axios'
import { message } from 'antd'

// 安全红线：接口地址一律来自环境变量，代码里不出现真实域名/密钥
const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? '/api/v1'

const request = axios.create({
  baseURL: BASE_URL,
  timeout: 10_000,
})

export default request

/** 业务错误对象：code 沿用附录A 语义（40101 未登录 / 40102 token 过期 / 40301 无权限 / 40901 冲突） */
export class ApiError extends Error {
  constructor(code, message, raw) {
    super(message)
    this.name = 'ApiError'
    this.code = code
    this.raw = raw
  }
}

💡 AntD 5 的静态 message 在多实例主题场景建议改用 <App> 组件包裹 + App.useApp() 获取实例；教学代码从简，生产规范见 https://ant.design/components/app-cn 。

9.3 请求拦截器：token 注入

// src/utils/request.js 追加
const ACCESS_TOKEN_KEY = 'qing_access_token' // 存储位置的 XSS 权衡是第 11 章专题

request.interceptors.request.use((config) => {
  const token = localStorage.getItem(ACCESS_TOKEN_KEY)
  if (token) config.headers.Authorization = `Bearer ${token}` // 附录A 认证约定
  return config
})

两个细节：token 读一次存内存也行，但登出/刷新跨模块同步麻烦，教学版直接读 localStorage；拦截器必须 return config——忘写是新手第一大事故（请求头全丢，还没有任何报错）。

9.4 响应拦截器：解包、错误归一化与静默选项

附录A 统一响应体 { code, message, data }。拦截器做三件事：code === 0 时直接返回 data（调用方永远拿业务数据）；非 0 归一化成 ApiError；40102 转交无感刷新（§9.5）：

// src/utils/request.js 追加
request.interceptors.response.use(
  (response) => {
    const res = response.data
    if (res.code === 0) return res.data // 解包：api 层与组件拿到的直接是 data
    return handleBusinessError(res, response.config) // 业务错误：40102 走刷新，其余抛 ApiError
  },
  (error) => {
    // HTTP 层错误：网络断开、超时、5xx
    const isTimeout = error.code === 'ECONNABORTED'
    const err = new ApiError(-1, isTimeout ? '请求超时，请重试' : '网络异常，请稍后重试', error)
    if (!error.config?.silent) message.error(err.message)
    return Promise.reject(err)
  },
)

function handleBusinessError(res, config) {
  if (res.code === 40102) return refreshAndRetry(res, config) // §9.5 无感刷新
  if (res.code === 40101) {
    // 真未登录：清会话，交给守卫跳登录（第 11 章接入 store 后在此 dispatch clearUser）
    localStorage.removeItem('qing_refresh_token')
  }
  const err = new ApiError(res.code, res.message, res)
  if (!config.silent) message.error(err.message) // 静默页面可传 silent: true 自行处理
  return Promise.reject(err)
}

silent 是重要的产品级设计：轮询、后台预取类请求不该每次失败都弹 toast，调用方在 config 里显式申请静默，责任就清晰了。

9.5 40102 无感刷新：单飞锁 + 请求重放

双令牌机制（accessToken 2 小时 / refreshToken 7 天，附录A §3.1）下，token 过期不该打断用户。完整时序：

请求A、B、C 同时收到 40102
  → 响应拦截器发现 refreshingPromise 不存在：A 创建刷新 Promise（单飞锁）
  → B、C await 同一个 Promise（等待队列），refresh 只发一次
  → 刷新成功：A/B/C 各自带新 token 重放原请求（打 _retried 标记）
  → 重放若再 40102：说明 refreshToken 也失效 → 清会话跳登录，绝不再刷（死循环防护）

// src/utils/request.js 追加 —— 无感刷新核心（与 Vue 版逐行同构）
const REFRESH_TOKEN_KEY = 'qing_refresh_token'
const rawAxios = axios.create() // 裸 axios：不经拦截器，避免刷新请求自身 40102 时递归

let refreshingPromise = null // 单飞锁：同一时刻最多一个刷新请求

function refreshAccessToken() {
  if (!refreshingPromise) {
    refreshingPromise = rawAxios
      .post(`${BASE_URL}/auth/refresh`, { refreshToken: localStorage.getItem(REFRESH_TOKEN_KEY) })
      .then(({ data }) => {
        if (data.code !== 0) throw new ApiError(data.code, data.message) // refreshToken 也失效
        localStorage.setItem(ACCESS_TOKEN_KEY, data.data.accessToken)
        return data.data.accessToken
      })
      .finally(() => { refreshingPromise = null }) // 成败都放锁，后续请求可重新触发
  }
  return refreshingPromise
}

async function refreshAndRetry(res, config) {
  if (config._retried) {
    // 重放后仍 40102：refreshToken 已死，清会话、抛未登录，绝不无限刷新
    localStorage.removeItem(ACCESS_TOKEN_KEY)
    localStorage.removeItem(REFRESH_TOKEN_KEY)
    return Promise.reject(new ApiError(40101, '登录已过期，请重新登录', res))
  }
  try {
    const token = await refreshAccessToken()
    config._retried = true
    config.headers.Authorization = `Bearer ${token}`
    return request(config) // 用原 config 重放（拦截器会重新走一遍）
  } catch (err) {
    localStorage.removeItem(ACCESS_TOKEN_KEY)
    localStorage.removeItem(REFRESH_TOKEN_KEY)
    return Promise.reject(new ApiError(40101, '登录已过期，请重新登录', res))
  }
}

必须用裸 axios 发刷新请求——刷新接口的响应也走响应拦截器的话，它自己 40102 会再次触发刷新，无限递归（Vue 版易错点 5 同款）。

9.6 取消、防抖与竞态

竞态：搜索框快速输入「订单 → 订单A → 订单AB」，三个请求并发，先发的可能后到，旧结果覆盖新结果。React 里必须显式治理：

// 手动版：AbortController 取消上一个请求（视图层/编排层写法）
let controller = null

async function search(keyword, signal) {
  controller?.abort() // 取消上一次
  controller = new AbortController()
  try {
    return await fetchOrders({ keyword }, { signal: controller.signal })
  } catch (err) {
    if (err.name !== 'CanceledError') throw err // 取消不算错误
  }
}

防抖：关键词输入 400ms 才真正生效，用一个可复用 Hook：

// src/hooks/useDebouncedValue.js —— 防抖：值稳定后再交给请求层
import { useEffect, useState } from 'react'

export function useDebouncedValue(value, delay = 400) {
  const [debounced, setDebounced] = useState(value)
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay)
    return () => clearTimeout(timer) // 值又变了：清掉旧定时器
  }, [value, delay])
  return debounced
}

好消息是：接入 TanStack Query 后，竞态取消是内置的——queryKey 变化视为新查询，旧查询的结果自动丢弃（且框架把 signal 递给 queryFn 让你顺手取消请求）；防抖也可以通过 placeholderData 缓解翻页闪烁。手写版的意义在于理解原理、以及维护没有 Query 的存量项目。

9.7 TanStack Query v5 入门：useQuery

Query 的世界观：服务端数据不是你的 state，是「远程数据的缓存视图」。你声明「这个数据依赖什么参数」（queryKey），框架负责缓存、去重、后台刷新、竞态、重试。

pnpm add @tanstack/react-query

// src/main.jsx —— QueryClientProvider 挂载
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { Provider } from 'react-redux'
import { store } from './store'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000, // 30s 内数据视为新鲜：切页回来不重新请求
      retry: 1,          // 失败重试 1 次（默认 3 次）；写操作用 mutation，默认不重试
    },
  },
})

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <Provider store={store}>
      <QueryClientProvider client={queryClient}>
        <BrowserRouter>
          <App />
        </BrowserRouter>
      </QueryClientProvider>
    </Provider>
  </StrictMode>,
)

// src/views/orders/OrderDetail.jsx —— 最小可用 useQuery
import { useQuery } from '@tanstack/react-query'
import { useParams } from 'react-router'
import { fetchOrderDetail } from '@/api/orders'

export default function OrderDetail() {
  const { id } = useParams()

  const { data: order, isPending, isError, error } = useQuery({
    queryKey: ['orders', 'detail', id], // ① 身份证：参数进 key，id 变化 → 自动重新请求
    queryFn: ({ signal }) => fetchOrderDetail(id, { signal }), // ② signal 透传给 axios 取消请求
    enabled: Boolean(id), // ③ 条件查询：id 不存在就不发请求
  })

  if (isPending) return <div className="page-loading">加载中…</div>
  if (isError) return <div>加载失败：{error.message} <button onClick={() => refetch()}>重试</button></div>
  return <h2>{order.orderNo}</h2>
}

v5 三个必知：

1. 对象签名：v5 只接受 useQuery({ ... }) 对象写法（v4 的位置参数已移除）；
2. isPending 取代 isLoading 表达「首次加载无数据」；isFetching 表示「含后台刷新在内的取数中」——翻页时想保留旧数据不闪 loading，见 §9.9；
3. queryKey 是结构化哈希：['orders', 'list', { page: 1, status: 'draft' }] 中对象成员顺序无关、内容变化即视为新 key——把请求参数全部放进 queryKey 是缓存正确性的根基（易错点 4 的反面）。

9.8 API 模块化：一个业务域一个文件

// src/api/orders.js —— 订单域接口：只描述接口，不含任何组件逻辑
import request from '@/utils/request'

export function fetchOrders(params, config = {}) {
  return request.get('/orders', { params, ...config }) // 附录A 分页：{ list, total, page, pageSize }
}
export function fetchOrderDetail(id, config = {}) {
  return request.get(`/orders/${id}`, config)
}
export function createOrder(payload) {
  return request.post('/orders', payload)
}
export function submitOrder(id) {
  return request.post(`/orders/${id}/submit`) // draft → pending_review
}
export function reviewOrder(id, action, reason) {
  // 财务审批：approve / reject（>10% 折扣需 finance 角色，附录A §2）
  return request.post(`/orders/${id}/${action}`, { reason })
}
export function cancelOrder(id, reason) {
  return request.post(`/orders/${id}/cancel`, { reason }) // 需填原因，附录A 状态机
}

api 层因为拦截器已解包，返回值就是 data 本体——层与层的契约靠「返回值口径一致」维持（易错点 2）。

9.9 useOrderList 完整示例：本章集大成之作

把 URL 筛选（第 07 章）、防抖（§9.6）、Query 缓存（§9.7）、翻页保旧（placeholderData）全部收进一个 Hook，组件只剩「用」——它与 Vue 版 useOrderList composable 职责完全一致，可直接对照：

// src/hooks/useOrderList.js —— 订单列表数据编排（本章集大成，第 12 章实战直接复用）
import { useMemo } from 'react'
import { useSearchParams } from 'react-router'
import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { fetchOrders } from '@/api/orders'
import { useDebouncedValue } from './useDebouncedValue'

/** @param {object} initialQuery 初始筛选兜底（URL 为空时使用） */
export function useOrderList(initialQuery = {}) {
  const [searchParams, setSearchParams] = useSearchParams()

  // 1. URL 是筛选状态的唯一事实源（第 07 章练习 2 的成果）
  const filters = useMemo(
    () => ({
      keyword: searchParams.get('keyword') ?? initialQuery.keyword ?? '',
      status: searchParams.get('status') ?? initialQuery.status ?? '',
      page: Number(searchParams.get('page') ?? 1),
      pageSize: 20, // 附录A：20/页
    }),
    [searchParams, initialQuery],
  )

  // 2. 关键词防抖：输入即时写 URL（体验），请求用防抖后的值（性能）
  const debouncedKeyword = useDebouncedValue(filters.keyword, 400)
  const effectiveFilters = useMemo(
    () => ({ ...filters, keyword: debouncedKeyword }),
    [filters, debouncedKeyword],
  )

  // 3. 筛选变更：增量更新 searchParams（空值删除、改筛选回第一页）
  const setFilters = (patch) => {
    const next = new URLSearchParams(searchParams)
    Object.entries(patch).forEach(([key, value]) => {
      if (value === '' || value == null) next.delete(key)
      else next.set(key, String(value))
    })
    if (!('page' in patch)) next.set('page', '1')
    setSearchParams(next)
  }

  // 4. Query：参数全在 queryKey → 缓存正确、竞态自动取消
  const query = useQuery({
    queryKey: ['orders', 'list', effectiveFilters],
    queryFn: ({ signal }) => fetchOrders(effectiveFilters, { signal }),
    placeholderData: keepPreviousData, // 翻页/防抖期间保留上一份结果，界面不闪空
  })

  return {
    filters,
    setFilters,
    list: query.data?.list ?? [],
    total: query.data?.total ?? 0,
    isPending: query.isPending,   // 首次加载（无任何数据）
    isFetching: query.isFetching, // 翻页后台刷新中（可用于进度条）
    error: query.error,
    reload: () => query.refetch(), // 手动刷新（invalidateQueries 是更常用的失效方式）
  }
}

// src/views/orders/OrderListView.jsx —— 消费 useOrderList（组件薄如纸）
import { useOrderList } from '@/hooks/useOrderList'
import { OrderTable, OrderFilters } from './components'
import { ORDER_STATUS_OPTIONS } from '@/constants/orderStatus'

export default function OrderListView() {
  const { filters, setFilters, list, total, isPending, isFetching, reload } = useOrderList()

  return (
    <div>
      <OrderFilters value={filters} onChange={setFilters} statusOptions={ORDER_STATUS_OPTIONS} />
      <OrderTable list={list} loading={isPending} />
      {/* 分页、导出等在第 12 章 M2 补全 */}
    </div>
  )
}

9.10 useMutation：写操作、失效与乐观更新

读用 useQuery，写用 useMutation。三种用法逐级递进：

// 用法一：基础提交（新建订单）
const createMutation = useMutation({ mutationFn: createOrder })
// 调用：createMutation.mutate(payload)；isPending 做防重复提交（第 10 章）

// 用法二：成功后失效缓存（提交草稿 → 列表与详情都要刷新）
const queryClient = useQueryClient()
const submitMutation = useMutation({
  mutationFn: submitOrder,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['orders'] }) // 粗粒度：orders 下全部标记过期
    message.success('已提交审核')
  },
})
// 精确版：invalidateQueries({ queryKey: ['orders', 'detail', id] }) 只失效这一单

// 用法三：乐观更新（财务审批「通过」：先改界面，服务端确认，失败回滚）
const approveMutation = useMutation({
  mutationFn: (id) => reviewOrder(id, 'approve'),
  onMutate: async (id) => {
    await queryClient.cancelQueries({ queryKey: ['orders', 'detail', id] }) // 停掉在途请求防覆盖
    const prev = queryClient.getQueryData(['orders', 'detail', id])         // 快照
    queryClient.setQueryData(['orders', 'detail', id], (old) =>
      old ? { ...old, status: 'approved' } : old, // 乐观：UI 立即变成已审核
    )
    return { prev } // 上下文传给 onError
  },
  onError: (_err, id, ctx) => {
    if (ctx?.prev) queryClient.setQueryData(['orders', 'detail', id], ctx.prev) // 回滚
    message.error('审核失败，已还原状态')
  },
  onSettled: (_d, _e, id) => {
    // 无论成败：与服务端对齐一次（成功拿确认，失败拿真实状态）
    queryClient.invalidateQueries({ queryKey: ['orders', 'detail', id] })
  },
})

乐观更新的适用判断：操作成功率极高、用户对即时反馈敏感（审批、点赞、上下架）才用；涉及钱的金额变动，宁可等真实响应。

🛠 渐进式实战练习

延续第 07 章仓库；mock 数据统一放 mock/orders.js（导出 30+ 条订单，字段严格按附录A：orderNo = 'QO' + yyyyMMdd + 6 位序号、金额单位分）。

练习 1 · 基础（10–20 min）：request 实例 + 静默选项

任务描述：完成 §9.2–9.4 的 request.js（不含无感刷新）：解包、ApiError、超时与网络错误归一化、silent 选项。写一个 api/health.js：ping() 正常返回、pingSilent() 带 silent: true。用两个按钮触发，验证：普通请求失败弹一次 toast；静默请求失败不弹，但 catch 里能拿到 err.code。

提示：mock 失败可以直接请求一个不存在的路径触发 404，或临时把拦截器里 res.code 改成 4xx01 分支验证业务错误路径；silent 从 response.config / error.config 读。

验收标准：

• [ ] code === 0 时调用方拿到的直接是 data（console 打印验证）；
• [ ] 业务错误与 HTTP 错误都抛 ApiError，且 toast 各只弹一次；
• [ ] silent: true 时零 toast，错误对象上有 code。

// api/health.js
import request from '@/utils/request'
export function ping() {
  return request.get('/ping') // mock 返回 { code: 40901, message: '模拟业务错误' }
}
export function pingSilent() {
  return request.get('/ping', { silent: true }) // config 上的自定义字段会被 axios 透传保留
}

// 组件里：
try {
  await pingSilent()
} catch (err) {
  if (err.code === 40901) message.info('冲突但静默：' + err.message) // 自行决定呈现方式
}

练习 2 · 进阶（30–60 min）：无感刷新并发验证

任务描述：实现 §9.5 完整无感刷新。mock 层做一个「40102 制造机」：第一次请求任意接口返回 code: 40102，刷新接口 /auth/refresh 延迟 1s 后返回新 token；之后所有请求正常。在一个页面用 Promise.all 同时发 3 个请求。验证：Network 面板里 /auth/refresh 只出现 1 次，3 个请求全部重放成功；再 mock「刷新也失败」的场景，验证清 token + 抛 40101，无死循环。

提示：单飞锁 = 模块级 refreshingPromise 变量；重放标记挂 config._retried；mock 刷新失败时返回 code: 40102 试试你的防护是否兜住。

验收标准：

• [ ] 3 个并发 40102 → 1 次刷新 + 3 次重放，界面无感知；
• [ ] 刷新接口自身失败 → token 被清、ApiError(40101) 抛给调用方、没有第二次 /auth/refresh；
• [ ] 刷新过程中新发起的请求（第 4 个）也等到同一个 Promise，拿到新 token 直接成功。

练习 3 · 挑战（选做，60+ min）：useOrderList 强化版

任务描述：在 §9.9 useOrderList 基础上追加：①排序参数 sort（createdAt / totalAmount，附录A：按创建时间/金额排序）与 order（asc/desc），由表头点击触发并写入 URL；②暴露 exportSelected(ids)，调用 exportOrdersCsv（返回 CSV 文本）后用 Blob 触发浏览器下载；③用 React DevTools Profiler 验证：输入关键词打字过程中，表格组件的重渲染次数 ≤ 防抖后的请求次数 + 2。

提示：导出是「拿到文本 → new Blob([text]) → URL.createObjectURL → <a download> 点击」三步，记得 revokeObjectURL；排序变化也属于 filters 的一部分，自然进 queryKey——这正是 Query 的舒服之处。

验收标准：

• [ ] 点表头切换排序，URL 出现 sort=totalAmount&order=desc，刷新后排序保持；
• [ ] 导出的 CSV 用 Excel 打开列头正确、金额为分（附一行表头注释「金额单位：分」）；
• [ ] 翻页时表格不闪 loading（placeholderData 生效），底部出现「数据更新中…」细进度条（isFetching 驱动）。

// src/api/orders.js 追加
export function exportOrdersCsv(ids) {
  return request.post('/orders/export-csv', { ids }) // mock 返回 CSV 文本
}

// src/hooks/useOrderList.js 追加/修改
export function useOrderList(initialQuery = {}) {
  // ...filters 增加：
  //   sort: searchParams.get('sort') ?? 'createdAt',
  //   order: searchParams.get('order') ?? 'desc',
  const exportSelected = async (ids) => {
    const csv = await exportOrdersCsv(ids)
    const blob = new Blob(['\ufeff' + csv], { type: 'text/csv;charset=utf-8' }) // BOM 防中文乱码
    const url = URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.href = url
    a.download = `orders-${Date.now()}.csv`
    a.click()
    URL.revokeObjectURL(url) // 释放，防内存泄漏
  }
  return { /* ...原有返回值, */ exportSelected }
}

⚠️ 常见易错点

易错点 1 · 金额浮点求和陷阱（附录A：金额单位为分）

❌ 错误代码：

// 前端把分转成元再求和、再累加折扣
const total = items.reduce((s, it) => s + (it.unitPrice / 100) * it.quantity, 0)
// unitPrice=129900(分) × 3 件 → 3897.0000000000005 元
// 展示 ¥3897.00 看似没事，但对账 diff 0.0000000000005，财务对不上账

错误原因：IEEE 754 二进制浮点无法精确表示 0.1 这类十进制小数（0.1 + 0.2 === 0.30000000000000004）。只要出现「分转元的小数运算」，误差就进来了。

✅ 正确写法：

// 全程以「分」为最小单位做整数运算，只在展示层转一次元
const totalFen = items.reduce(
  (sum, it) => sum + Math.round(it.quantity * it.unitPrice * (it.discountPercent / 100)),
  0, // 整数加减完全精确；除法仅发生在最后 formatFen
)
export const formatFen = (fen) => (fen / 100).toFixed(2) // 仅渲染层调用

易错点 2 · 拦截器返回值口径不一致

❌ 错误代码：

request.interceptors.response.use((response) => {
  if (response.data.code === 0) console.log('ok') // 忘了 return！结果：所有调用方拿到 undefined
})

错误原因：拦截器是管道，每个函数的返回值是下一站的输入；不 return 就断流。口径（返回 data 还是 response）必须全站唯一。

✅ 正确写法：

request.interceptors.response.use(
  (response) => (response.data.code === 0 ? response.data.data : handleBusinessError(response)),
  // 全站约定：api 层拿到的永远是业务 data；错误永远是 ApiError
)

易错点 3 · 竞态：先发后至，旧数据覆盖新数据

❌ 错误代码：

useEffect(() => {
  fetchOrders({ keyword }).then(setList) // 快速输入时：慢的旧响应最后到达，覆盖新结果
}, [keyword])

错误原因：网络时延不可控，「请求发出顺序 ≠ 响应到达顺序」。没有取消/丢弃机制时，界面会「输入完却显示旧关键词的结果」。

✅ 正确写法：

// 首选：TanStack Query —— key 变化即新查询，旧响应自动丢弃
useQuery({
  queryKey: ['orders', 'list', { keyword }],
  queryFn: ({ signal }) => fetchOrders({ keyword }, { signal }), // 顺带真正取消请求
})
// 手写场景：AbortController abort 上一个 + 组件卸载清理（§9.6）

易错点 4 · 筛选参数没进 queryKey：界面与缓存「对不上」

❌ 错误代码：

const { data } = useQuery({
  queryKey: ['orders', 'list'],              // 💥 key 里没有筛选条件
  queryFn: () => fetchOrders(filters),       // filters 变了，key 没变
})
// 现象：切状态筛选 → 命中同一缓存 → 界面永远显示第一次的数据

错误原因：Query 用 queryKey 识别「这是哪份数据」。参数在闭包里而不在 key 里，框架无法感知请求语义变化——这是 React 版「query string 变化不触发请求」的最常见根因。

✅ 正确写法：

const { data } = useQuery({
  queryKey: ['orders', 'list', filters], // 参数全量进 key（结构化哈希，对象顺序无关）
  queryFn: ({ signal }) => fetchOrders(filters, { signal }),
})
// 自检口诀：queryFn 里用到的每个「会变的值」，都必须出现在 queryKey 里

易错点 5 · 刷新请求自身走了拦截器，刷新失败成死循环

❌ 错误代码：

const { data } = await request.post('/auth/refresh', { refreshToken })
// request 带 token、带响应拦截器：刷新接口返回 40102 → 再次触发 refreshAccessToken → 无限循环

错误原因：刷新接口用「带拦截器的实例」发出，它的 40102 响应又进入刷新逻辑，递归到网络层限流为止。

✅ 正确写法：

const rawAxios = axios.create() // 裸实例：无拦截器、无 token 注入
const { data } = await rawAxios.post(`${BASE_URL}/auth/refresh`, { refreshToken })
// 双保险：重放请求打 _retried 标记，二次 40102 直接清会话抛 40101（§9.5）

易错点 6 · queryFn 吞错误，Query 以为成功

❌ 错误代码：

useQuery({
  queryKey: ['orders', 'list', filters],
  queryFn: async () => {
    try {
      return await fetchOrders(filters)
    } catch (err) {
      message.error(err.message)
      return [] // 💥 错误被吞：isError 永远 false，空数组进了缓存还被视为「新鲜」
    },
})

错误原因：queryFn 必须让错误抛出去，Query 才能标记 isError、触发重试、暴露给错误边界。catch 里 return 兜底值等于向缓存注入假数据。

✅ 正确写法：

useQuery({
  queryKey: ['orders', 'list', filters],
  queryFn: ({ signal }) => fetchOrders(filters, { signal }), // 错误自然上抛
})
// 呈现层处理：if (isError) return <ErrorState onRetry={refetch} />
// 请求层 toast 已由拦截器负责，queryFn 里不要重复弹

✅ 最佳实践

1. 四层分工写进目录约定：utils/request.js 全站唯一；api/ 一个业务域一个文件；数据编排进 hooks；视图层禁止 import axios——code review 一眼可查。
2. 错误两通道：业务错误 toast 在请求层统一弹一次；需要定制处理（409 冲突、静默轮询）走 ApiError.code 分支与 silent 选项，禁止组件里再 try/catch 弹第二遍。
3. 无感刷新三件套缺一不可：单飞锁（防并发刷新）、_retried 标记（防重放循环）、裸 axios 发刷新（防自递归）——对照 Vue 版逐行同构，双栈团队可共用时序图评审。
4. queryKey 即依赖：请求参数全量进 key；列表类 key 用 ['orders', 'list', filters]，详情 ['orders', 'detail', id]；失效时按前缀 ['orders'] 粗失效、按完整 key 细失效。
5. staleTime 显式声明：全局默认 30s，关键列表可调；不配置意味着 0（每次挂载都后台刷新），切页频繁时请求数失控。
6. placeholderData: keepPreviousData 用于翻页：界面不闪空、体验平滑；首次加载仍用 isPending 渲染骨架屏。
7. 防抖收口在一个 Hook：useDebouncedValue 全站复用，禁止各页面自己写 setTimeout（清理逻辑十写九漏）。
8. 环境变量分层：VITE_API_BASE_URL 按环境拆 .env.development/.env.production，开发走 Vite proxy 打本地 mock——密钥类变量永远不进前端代码。

📌 本章小结

1. 接口层四层分工（传输/API/编排/视图），视图不碰 axios、错误只弹一次——分层是可维护性的第一杠杆。
2. axios 封装三件套：token 注入、统一解包 + ApiError 归一化、40102 无感刷新（单飞锁 + 重放 + _retried 防护），与 Vue 版逐行同构。
3. TanStack Query 的世界观：服务端数据是「缓存的视图」，queryKey 声明依赖、staleTime 声明新鲜度、竞态与去重框架全包；useMutation + invalidateQueries 管写操作，onMutate 乐观更新要配快照回滚。
4. useOrderList 是本章集大成：URL 事实源 + 防抖 + Query 缓存 + 翻页保旧，与 Vue 版同名 composable 职责完全对应，第 12 章实战直接复用。
5. 下一章处理「写」的另一半：React Hook Form + Zod 接管复杂表单——新建订单的动态明细行、金额联动与校验契约。

📄 第 10 章 · 表单处理与校验 10-表单处理与校验.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：6 小时｜🔗 前置：第 09 章

⬅ 上一章：服务端交互 ｜ 📖 本版目录 ｜ ➡ 下一章：登录鉴权

💡 对照学习：本页是 React 版第 10 章，对应 Vue 版第 10 章 · 表单处理与校验，两版练习任务完全一致（静态字段校验 → 动态明细行 + 金额联动 → 草稿暂存 + 审批闭环）。概念映射：register ≈ v-model + :rules 绑定二合一；zodResolver(schema) ≈ ElForm 的 :rules 规则对象（但校验规则与 UI 彻底解耦、可单测）；formState.errors ≈ formRef.validate() 回调的错误对象；useFieldArray ≈ 动态 v-for 明细行 + prop="items.${i}.quantity" 路径；Controller ≈ v-model 封装到第三方组件；reset ≈ resetFields；useWatch ≈ 精确 watch 表单字段。

🎯 学习目标

学完本章，你将能够：

1. 说出受控与非受控两种表单模式的心智差异，解释复杂中后台表单为什么选 React Hook Form；
2. 用 RHF 三件套（register / handleSubmit / formState）实现带校验时机的静态表单；
3. 把附录A 的校验规则（数量 1–9999、行折扣 0–100%、必填项）写成 Zod schema，并解释「校验契约与 UI 解耦」带来的可测试性；
4. 用 Controller 桥接 AntD 受控组件（Select / InputNumber），说出为什么 register 对它们不生效；
5. 用 useFieldArray 实现明细行的增删改，并解释 fields.id 作 key 与「用 index 作 key」的差别；
6. 实现「明细金额 → 订单总额 → 整单折扣 → 审批提示」的联动链，金额全程以分为单位；
7. 处理编辑回填（reset）与防重复提交（isSubmitting），排查 defaultValues 不更新类问题。

📖 核心知识点

10.1 受控与非受控，以及为什么选 React Hook Form

第 02 章讲过：受控输入每个键击都触发重渲染。三种规模下的选择：

RHF 的核心卖点恰好命中中后台表单的痛点：非受控注册（输入值存在表单内部 ref，打字不触发整棵组件树重渲染）、schema 化校验（规则一处定义、可单测、与 UI 解耦）、字段级订阅（useWatch 只重渲染需要的部分）。安装：

pnpm add react-hook-form zod @hookform/resolvers

10.2 最小可用：register / handleSubmit / formState

以「新建订单」的静态字段开刀（客户、备注），体会三件套：

// src/views/orders/OrderCreate.jsx —— 骨架版：先跑通三件套
import { useForm } from 'react-hook-form'
import { createOrder } from '@/api/orders'

export default function OrderCreate() {
  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
    defaultValues: { customerId: '', remark: '' }, // 非受控模式的初始值入口
  })

  const onSubmit = async (values) => {
    // values 已通过全部校验，类型形状即 schema（配合 TS 后是强类型）
    await createOrder(values)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label>
        客户 ID
        {/* register 返回 ref/onChange/onBlur 并注入 input —— 这就是「非受控注册」 */}
        <input {...register('customerId', { required: '请选择客户' })} />
      </label>
      {errors.customerId && <p className="error">{errors.customerId.message}</p>}

      <label>
        备注
        <textarea {...register('remark', { maxLength: { value: 200, message: '最多 200 字' } })} />
      </label>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? '提交中…' : '创建订单'}
      </button>
    </form>
  )
}

四个语义要点：handleSubmit 先跑校验、全过了才调 onSubmit（校验失败只渲染 errors，不会提交）；register 的第二参是内联规则，简单规则够用；isSubmitting 天然覆盖提交期间，是防重复提交的第一道闸；校验时机默认 onSubmit + onBlur 后首次出错转为 onChange（输入错误字段时即时纠正），无特殊需求不要手写触发时序。

10.3 Zod schema：把附录A 的校验规则写成契约

内联规则一多就散。企业口径：校验规则收敛进 Zod schema——一份文件描述「合法的订单长什么样」，表单、API 提交前、单元测试共用：

// src/schemas/order.js —— 订单校验契约（附录A §3.3：数量 1–9999、行折扣 0–100%、必填）
import { z } from 'zod'

export const orderSchema = z.object({
  customerId: z.string().min(1, '请选择客户'),
  items: z.array(
    z.object({
      skuId: z.string().min(1, '请选择商品'),
      quantity: z.coerce
        .number({ message: '数量必须是数字' })
        .int('数量必须是整数')
        .min(1, '数量至少为 1')
        .max(9999, '数量不能超过 9999'),
      unitPriceFen: z.coerce.number().int('单价必须是整数分').min(1, '单价必须大于 0'),
      discountPercent: z.coerce
        .number()
        .min(0, '折扣不能为负')
        .max(100, '折扣不能超过 100%'),
    }),
  ),
  remark: z.string().max(200, '备注最多 200 字').optional(),
})

接上 resolver，校验逻辑整体替换掉 §10.2 的内联规则：

import { zodResolver } from '@hookform/resolvers/zod'
import { orderSchema } from '@/schemas/order'

const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
  resolver: zodResolver(orderSchema), // 校验全部交给 schema
  defaultValues: { customerId: '', items: [emptyItem()], remark: '' },
})

两个 Zod 细节：输入框拿到的数字是字符串（'3'），z.coerce.number() 负责转数字并校验——这直接消灭「数字输入是字符串」这类经典 bug；emptyItem() 是工厂函数（{ skuId: '', quantity: 1, unitPriceFen: 0, discountPercent: 100 }），保证新行结构与 schema 对齐。schema 是纯函数，第 15 章可以直接对它写单测：orderSchema.safeParse(非法数据) 的用例先于组件存在。

10.4 AntD 组件接入：Controller

register 的原理是把 ref/onChange 注入原生 input。AntD 的 Select / InputNumber / DatePicker 是受控 React 组件（不透传原生 ref 语义），必须用 Controller 桥接——它把 RHF 的字段状态交给你的 render 函数：

import { useForm, Controller } from 'react-hook-form'
import { Select, InputNumber, Input } from 'antd'
import { fetchCustomers } from '@/api/customers'

export default function OrderCreate() {
  // ...useForm 同上

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label>客户</label>
      <Controller
        name="customerId"
        control={control}
        render={({ field, fieldState }) => (
          <Select
            {...field}                       // value / onChange / onBlur 一次性接好
            showSearch
            optionFilterProp="label"
            placeholder="搜索并选择客户"
            options={customers.map((c) => ({ value: c.id, label: `${c.name}（${c.level}）` }))}
            status={fieldState.error ? 'error' : undefined} // AntD 5 的错误态视觉
          />
        )}
      />
      {errors.customerId && <p className="error">{errors.customerId.message}</p>}
      {/* InputNumber 同理：<Controller><InputNumber {...field} /></Controller> */}
    </form>
  )
}

分工口诀：原生 input 用 register，AntD 组件用 Controller。混用时先问一句「这个组件是不是受控 React 组件」，答案决定用哪把刀。

10.5 动态明细行：useFieldArray

附录A 的新建订单需要「添加明细行（商品、数量、单价、行折扣），可增删」——useFieldArray 专门为此而生：

import { useFieldArray, useWatch, useForm, Controller } from 'react-hook-form'
import { Button, Select, InputNumber } from 'antd'
import { calcItemFen, formatFen } from '@/utils/money'

export default function OrderItems({ control, errors }) {
  const { fields, append, remove } = useFieldArray({ control, name: 'items' })
  const items = useWatch({ control, name: 'items' }) ?? [] // 字段级订阅：只重渲染明细区

  return (
    <div className="order-items">
      <table>
        <thead>
          <tr><th>商品</th><th>数量</th><th>单价(分)</th><th>行折扣%</th><th>行金额</th><th /></tr>
        </thead>
        <tbody>
          {fields.map((field, index) => (
            <tr key={field.id}> {/* ✅ fields.id 是 RHF 生成且随行存亡的稳定标识 */}
              <td>
                <Controller
                  name={`items.${index}.skuId`} // 路径精确到第 index 行
                  control={control}
                  render={({ field: f }) => (
                    <Select {...f} showSearch placeholder="选择商品" options={SKU_OPTIONS} />
                  )}
                />
              </td>
              <td>
                <Controller
                  name={`items.${index}.quantity`}
                  control={control}
                  render={({ field: f }) => <InputNumber {...f} min={1} max={9999} />}
                />
              </td>
              <td>
                <Controller name={`items.${index}.unitPriceFen`} control={control}
                  render={({ field: f }) => <InputNumber {...f} min={1} precision={0} />} />
              </td>
              <td>
                <Controller name={`items.${index}.discountPercent`} control={control}
                  render={({ field: f }) => <InputNumber {...f} min={0} max={100} />} />
              </td>
              <td>{formatFen(calcItemFen(items[index] ?? {}))} 元</td>
              <td>
                {/* 只有一行时不允许删，规避「数组为空」的边界（schema 层也可加 min(1) 双保险） */}
                <Button danger size="small" disabled={fields.length === 1}
                  onClick={() => remove(index)}>删除</Button>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
      <Button type="dashed" block onClick={() => append(emptyItem())}>+ 添加明细行</Button>
    </div>
  )
}

fields.map 是铁律：遍历 fields（渲染元数据，带稳定 id）而不是 watch 出来的值数组——值的数组在编辑中随时变，用它渲染会让输入框失焦、删除行内容串位（易错点 3）。行内校验错误通过父组件传入的 errors.items?.[index]?.quantity?.message 呈现。

10.6 金额汇总与联动校验：整单折扣 → 审批提示

附录A 的两条业务规则：明细金额 = 数量 × 单价 × 行折扣，订单总额自动汇总；整单折扣 >10%（即 wholeDiscountPercent < 90）提交后进入 pending_review 需财务审批。联动链如下：

// src/views/orders/OrderCreate.jsx —— 联动区（追加在表单底部）
import { useMemo } from 'react'
import { Alert } from 'antd'
import { useWatch } from 'react-hook-form'
import { sumFen, calcWholeDiscountPercent, formatFen } from '@/utils/money'

function OrderSummary({ control }) {
  const items = useWatch({ control, name: 'items' }) ?? []

  const { totalFen, wholeDiscountPercent } = useMemo(() => {
    if (items.length === 0) return { totalFen: 0, wholeDiscountPercent: 0 }
    // ① 明细金额（分）：整数运算，见 utils/money（金额单位为分，附录A 约定）
    const totalFen = sumFen(items)
    // ② 整单折扣% = 实收合计 / 原价合计 × 100（≤90 免审批）
    const originalFen = items.reduce(
      (s, it) => s + Math.round((it.quantity ?? 0) * (it.unitPriceFen ?? 0)), 0,
    )
    const wholeDiscountPercent = originalFen > 0 ? Math.round((totalFen / originalFen) * 100) : 0
    return { totalFen, wholeDiscountPercent }
  }, [items])

  const needReview = wholeDiscountPercent > 0 && wholeDiscountPercent < 90 // 折扣超过 10%

  return (
    <div className="order-summary">
      <p>订单总额：<strong>{formatFen(totalFen)}</strong> 元</p>
      {needReview && (
        <Alert type="warning" showIcon
          message={`整单折扣 ${wholeDiscountPercent}%（超过 10%），提交后将进入待审核，需财务审批`} />
      )}
    </div>
  )
}

// src/utils/money.js —— 金额工具：全程「分」，展示层才转元（与第 09 章同一份，两处共用）
export function calcItemFen({ quantity = 0, unitPriceFen = 0, discountPercent = 100 }) {
  return Math.round(quantity * unitPriceFen * (discountPercent / 100))
}
export function sumFen(items) {
  return items.reduce((sum, it) => sum + calcItemFen(it), 0) // 整数累加，无浮点误差
}
export function calcWholeDiscountPercent(items) { /* 同 §10.6 内联逻辑，抽出复用 */ }
export function formatFen(fen) {
  return (fen / 100).toFixed(2)
}

联动校验属于「跨字段规则」，优先放在展示层提示 + schema refine 双轨：schema 里用 .superRefine 校验「折扣范围与总额关系」，UI 上用 Alert 提前告知审批后果——用户不必等提交失败才知道。

10.7 编辑回填与提交态：reset、values 与防重复

编辑订单 = 异步取数 + 回填表单。defaultValues 只在挂载时生效，数据后到必须用 reset：

// src/views/orders/OrderEdit.jsx —— 编辑回填（易错点 1 的正确姿势）
import { useEffect } from 'react'
import { useQuery } from '@tanstack/react-query'
import { fetchOrderDetail, updateOrder } from '@/api/orders'

export default function OrderEdit({ id }) {
  const { data: order } = useQuery({
    queryKey: ['orders', 'detail', id],
    queryFn: ({ signal }) => fetchOrderDetail(id, { signal }),
  })

  const { reset, handleSubmit, formState: { isSubmitting } } = useForm({
    resolver: zodResolver(orderSchema),
    defaultValues: emptyForm(), // 先给骨架，避免受控告警
  })

  useEffect(() => {
    if (order) {
      reset({
        customerId: order.customerId,
        items: order.items.map((it) => ({ ...it })), // 拷贝，避免直接改缓存对象
        remark: order.remark ?? '',
      })
    }
  }, [order, reset]) // reset 引用稳定，可安全进依赖

  const onSubmit = async (values) => {
    await updateOrder(id, values) // RHF 已把数值字段经 z.coerce 转为 number
  }
  // 提交按钮：disabled={isSubmitting} —— 提交期间不可再点，后端幂等是第二道保险
}

补充两点：RHF 也提供 useForm({ values }) 选项在数据变化时自动同步表单（比 reset 更声明式，详见 https://react-hook-form.com/docs/useform ），团队二选一即可，但必须写进规范统一；「防重复提交」是三层闸门：isSubmitting 禁用按钮 → 请求层去重（第 09 章）→ 后端幂等键，前端只负责前一层。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）：静态字段 + 校验时机

任务描述：实现新建订单的静态区：客户（AntD Select，必选）、备注（最多 200 字）。规则进 orderSchema；客户未选时失焦即出红字，选完后红字即时消失；备注超限时按钮仍可点但提交被拦截并高亮错误。

提示：Select 记得用 Controller；errors.xxx.message 渲染在字段下方；先故意提交一次空表单观察校验触发顺序。

验收标准：

• [ ] 提交空表单：客户字段红字「请选择客户」，onSubmit 未被调用（console 验证）；
• [ ] 选中客户后红字立即消失（onChange 即时重校验）；
• [ ] 备注输入 201 字被拦截提示，200 字不报错。

// src/schemas/order.js（先只保留静态部分）
import { z } from 'zod'
export const orderSchema = z.object({
  customerId: z.string().min(1, '请选择客户'),
  remark: z.string().max(200, '备注最多 200 字').optional(),
})

const { control, handleSubmit, formState: { errors, isSubmitting } } = useForm({
  resolver: zodResolver(orderSchema),
  defaultValues: { customerId: '', remark: '' },
})
// <Controller name="customerId" control={control} render={({ field, fieldState }) => (
//   <Select {...field} status={fieldState.error ? 'error' : undefined} ... />
// )} />

练习 2 · 进阶（30–60 min）：动态明细行 + 金额联动

任务描述：按 §10.5–10.6 完成明细行区：商品搜索下拉、数量（1–9999）、单价（分）、行折扣（0–100），行金额实时计算；添加/删除行；底部汇总订单总额与整单折扣，折扣 >10% 时出现「需财务审批」警告。行级校验错误显示在对应单元格下方。

提示：fields.map 渲染、useWatch 订阅值、useMemo 算汇总；删中间一行后检查「其余行的输入与校验红字是否串位」——串位了说明 key 用错了。

验收标准：

• [ ] 数量输 0、10000、1.5 分别被拦截（schema 三条规则逐一命中）；
• [ ] 行金额 = 数量 × 单价(分) × 折扣%，与手算一致且为整数分；
• [ ] 添加 3 行后删除第 2 行，第 1、3 行内容与红字位置不错乱；
• [ ] 折扣合计恰为 85% 时出现审批警告；折扣 100% 时不出现。

// 行内错误：errors 由 useForm 顶层取，按路径下钻
<td>
  <Controller name={`items.${index}.quantity`} control={control}
    render={({ field: f, fieldState }) => (
      <>
        <InputNumber {...f} min={1} max={9999} precision={0}
          status={fieldState.error ? 'error' : undefined} />
        {fieldState.error && <div className="cell-error">{fieldState.error.message}</div>}
      </>
    )} />
</td>

// 汇总联动放在独立组件 OrderSummary（§10.6 原文），
// 它内部 useWatch('items')——输入只重渲染明细与汇总，不重渲染整个表单

练习 3 · 挑战（选做，60+ min）：草稿暂存 + 联动审批闭环

任务描述：把第 08 章练习 3 的 useDraftStore 接进表单：进入新建页时从草稿 store 回填，字段变更防抖 500ms 写回 store（persist 自动落盘）；提交成功后 clear()；提交时按整单折扣走「双分支」——折扣 ≤10% 直接 createOrder，>10% 提交后跳详情页并 toast「已提交审核，等待财务审批」（状态应为 pending_review）。

提示：回填用 reset(draft)；写回草稿在 useEffect 里订阅 useWatch 的值；两个分支只是提交后的提示与跳转不同，接口按附录A 语义是同一个 POST /orders。

验收标准：

• [ ] 填一半切到订单列表再回来，表单内容完整还原（含明细行行数）；
• [ ] 提交成功后草稿清空、localStorage 中 qing-draft-order 内容重置；
• [ ] 构造折扣 85% 的订单提交：mock 返回状态 pending_review，界面跳详情并出现审批提示；折扣 100% 的订单状态为 draft。

export default function OrderCreate() {
  const draft = useDraftStore((s) => s) // 演示取整仓；生产建议字段级 selector
  const setDraft = useDraftStore.getState

  const form = useForm({ resolver: zodResolver(orderSchema), defaultValues: emptyForm() })
  const { reset, handleSubmit, formState: { isSubmitting } } = form
  const values = useWatch({ control: form.control }) // 整表单值

  // ① 进页回填：persist 恢复是同步的，直接 reset 一次
  useEffect(() => {
    if (draft.items.length > 0) reset({ customerId: draft.customerId, items: draft.items, remark: '' })
    // eslint-disable-next-line -- 只需在挂载时执行一次
  }, [])

  // ② 变更防抖写回草稿
  useEffect(() => {
    const timer = setTimeout(() => {
      useDraftStore.getState().setCustomerId(values.customerId ?? '')
      useDraftStore.setState({ items: values.items ?? [] })
    }, 500)
    return () => clearTimeout(timer)
  }, [values])

  const onSubmit = async (payload) => {
    const created = await createOrder(payload)
    useDraftStore.getState().clear()
    message.success(created.wholeDiscountPercent < 90 ? '已提交审核，等待财务审批' : '订单已创建')
    navigate(`/orders/${created.id}`, { replace: true })
  }
}

⚠️ 常见易错点

易错点 1 · defaultValues 不更新：编辑页表单一直是旧值

❌ 错误代码：

const { data: order } = useQuery({ /* 异步取数 */ })
const form = useForm({
  defaultValues: order ?? emptyForm(), // 💥 首次渲染时 order 还是 undefined，之后永远不生效
})

错误原因：defaultValues 只在表单挂载那一刻被读取；异步数据后到，RHF 不会自动把新值灌进已挂载的非受控字段——这是 React 版「编辑回填丢失」的第一大来源。

✅ 正确写法：

useEffect(() => {
  if (order) reset({ customerId: order.customerId, items: order.items.map((it) => ({ ...it })) })
}, [order, reset]) // 数据到达后 reset 灌值；或 useForm({ values: order })（7.42+，团队统一其一）

易错点 2 · 金额在表单里转成元做浮点运算

❌ 错误代码：

const total = items.reduce((s, it) => s + it.quantity * (it.unitPriceFen / 100) * (it.discountPercent / 100), 0)
// 展示 ¥3897.0000000000005；提交的 totalAmount 再 ×100 回分，误差已固化进数据

错误原因：把「分」转「元」参与中间计算，浮点误差从中作梗（第 09 章易错点 1 在表单场景的重演）。

✅ 正确写法：

// utils/money.js：全程分，展示层才 formatFen
const totalFen = items.reduce((s, it) => s + calcItemFen(it), 0)
<p>订单总额：{formatFen(totalFen)} 元</p>

易错点 3 · useFieldArray 用 index 当 key，删行全串位

❌ 错误代码：

{items.map((item, index) => (
  <tr key={index}> {/* 💥 删除第 2 行后：原第 3 行「变成」第 2 行，输入框内容/红字跟着错位 */}
    ...

错误原因：index 是「位置」不是「身份」。删除中间行后，后续行的 index 全部前移，React 按位置复用节点，把旧内容留在错误的位置上（第 02 章 key 原则在动态表单里的重演）。

✅ 正确写法：

const { fields, append, remove } = useFieldArray({ control, name: 'items' })
{fields.map((field, index) => (
  <tr key={field.id}> {/* ✅ fields.id：RHF 生成、随行存亡 */}
    ...

易错点 4 · 给 AntD 受控组件用 register

❌ 错误代码：

<Select {...register('customerId')} options={customers} /> // 💥 值永远进不了表单 state

错误原因：register 通过原生 ref/onChange 注入，AntD 组件是受控封装、不接原生 DOM 语义，注册静默失效——字段「看起来能选」，提交时却报必填错误。

✅ 正确写法：

<Controller
  name="customerId"
  control={control}
  render={({ field, fieldState }) => (
    <Select {...field} options={customers} status={fieldState.error ? 'error' : undefined} />
  )}
/>
// 口诀：原生 input → register；受控 React 组件（AntD/自研）→ Controller

易错点 5 · 数字输入是字符串：比较与计算全乱

❌ 错误代码：

<input {...register('quantity', { max: 9999 })} /> // 输入 '10'，values.quantity 是 '10'
values.quantity > 9 // '10' > 9 → true（字符串比较侥幸对）… '9' > 10 → true 💥
Math.round('3.5')   // 字符串直接进金额计算，schema 才发现不是整数

错误原因：DOM input 的值永远是字符串；不做类型归一，比较与算术全靠隐式转换的运气。

✅ 正确写法：

// schema 层统一归一：z.coerce.number() 把 '3' 转成 3 再校验
quantity: z.coerce.number().int().min(1, '数量至少为 1').max(9999, '数量不能超过 9999')
// 原生 input 也可 register('quantity', { valueAsNumber: true })，但 schema 方案对 AntD 同样有效

易错点 6 · watch 整个表单，每敲一键全页重渲染

❌ 错误代码：

const allValues = watch() // 💥 订阅整表单：任何字段键入都重渲染整棵表单树（含大表格）

错误原因：watch() 无参调用订阅全部字段，中后台表单字段上百时，打字卡顿立刻出现——这正是 RHF 非受控模式要避免的事。

✅ 正确写法：

const items = useWatch({ control, name: 'items' }) // 字段级订阅：只重渲染消费它的组件
// 且把消费端收进小组件（OrderSummary），配合 useMemo 缓存计算结果（§10.6 结构）

✅ 最佳实践

1. schema 是唯一的校验事实源：规则全进 src/schemas/*.js，组件里零内联 max/min；schema 可单测、可复用于提交前兜底校验，对应 Vue 版把 rules 收进独立文件的同款纪律。
2. register 与 Controller 按组件类型分流：原生 input 用 register 享受非受控性能，AntD 组件一律 Controller——混用前先确认组件是否受控封装。
3. 渲染 fields、计算 watch：useFieldArray 的 fields（带稳定 id）负责渲染，useWatch 的值负责计算，两者绝不能互换用途。
4. 金额链路全程分：输入（分）→ 计算（整数）→ 校验（整数）→ 提交（分）→ 展示（formatFen 转元），单位转换只发生在渲染层，写入 utils/money.js 全站共用。
5. 联动规则双轨：能自动算的（总额、整单折扣）算给用户看；会导致后果的（>10% 折扣需审批）用 Alert 提前告知；跨字段硬校验进 schema refine——别让用户提交后才挨打。
6. 编辑回填只有两种合法姿势：useEffect + reset 或 useForm({ values })，团队规范二选一；defaultValues 只用于「确定存在的初值」。
7. 提交三层闸门：isSubmitting 禁用按钮 → 请求层防抖/去重 → 后端幂等；前端永远假设用户会双击。
8. 校验时机尊重默认：RHF 的「提交全量 + 出错后即时」覆盖 95% 场景，改 mode 前先想清楚产品诉求，不要为了「高级感」调参。

📌 本章小结

1. RHF 三件套跑通静态表单，Zod schema 把附录A 校验规则收敛成可单测的契约，zodResolver 一行接入。
2. AntD 受控组件走 Controller 桥接；原生 input 走 register；选错注册方式是最常见的「静默失效」。
3. 动态明细行 = useFieldArray（fields 渲染 + watch 计算）+ 行级路径 items.${index}.quantity；金额联动全程以分为单位，useWatch + useMemo 保证联动不拖垮性能。
4. 编辑回填用 reset（或 values），defaultValues 不更新的根因是「只读挂载那一刻」；防重复提交从 isSubmitting 开始。
5. 下一章进入鉴权：把第 08 章的 user store、第 09 章的无感刷新、本章的表单（登录页）与第 07 章的守卫拼成完整的三级权限体系——登录、动态菜单、按钮级 <Auth> 与 403 页。

📄 第 11 章 · 登录鉴权与权限控制 11-登录鉴权与权限控制.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：6 小时｜🔗 前置：第 08 章、第 09 章、第 10 章

⬅ 上一章：表单处理与校验 ｜ 📖 本版目录 ｜ ➡ 下一章：中级实战

💡 对照学习：本页是 React 版第 11 章，对应 Vue 版第 11 章 · 登录鉴权与权限控制，两版练习任务完全一致（登录页 + 守卫白名单 → 按钮权限 + 403 + 动态菜单 → 无感刷新联调 + 登出闭环）。概念映射：ProtectedRoute 组件 ≈ router.beforeEach 全局守卫（白名单/角色分流逻辑同构）；<Auth> 权限组件 ≈ v-permission 自定义指令；菜单配置 roles 过滤两版同构；useNavigate + state.from ≈ router.push({ query: { redirect } }) 回跳；无感刷新请求队列两版共用第 09 章的同一份实现；useDispatch(clearUser) + queryClient.clear() ≈ Vue 版登出时的全量状态清理。

🎯 学习目标

学完本章，你将能够：

1. 画出「输入账密 → 校验验证码 → 换取双令牌 → 注入请求头 → 渲染受保护页面」的完整认证时序，并指出每一环的前端职责边界；
2. 对比 localStorage 与 HttpOnly Cookie 存储 token 的 XSS/CSRF 权衡，为内部中后台给出推荐方案并说明缓解措施；
3. 用第 10 章的 RHF + Zod 实现含图形验证码的登录页，验证码输错后可无刷新换图；
4. 强化 ProtectedRoute：会话恢复期防闪跳、roles 参数做页面级拦截、403 页分流；
5. 用「菜单配置 + 角色过滤」实现动态菜单，保证菜单与页面守卫共用同一份权限配置（单一事实源）；
6. 实现 usePermission Hook 与 <Auth> 按钮级权限组件，把附录A 的按钮权限（删除订单、折扣审批）落成声明式代码；
7. 实现登出闭环：令牌、store、Query 缓存、表单草稿四类状态全量清理，并说出「清理不彻底」导致的越权数据残留问题。

📖 核心知识点

11.1 认证全景图：从前端视角拆解一次登录

附录A §3.1 的认证需求：账密 + 图形验证码（输错 5 次锁 10 分钟）、JWT 双令牌、无感刷新。前端视角的完整时序：

① 进入登录页：GET /auth/captcha → { captchaId, imageBase64 }，展示图形验证码
② 用户提交：POST /auth/login { username, password, captchaId, captchaCode }
   —— 账密错误 / 验证码错误：后端返回业务错误码，前端 toast 并换一张验证码
③ 登录成功：返回 { profile, accessToken(2h), refreshToken(7d) }
   —— 前端写 token（§11.3 讨论）、写 user store、跳 redirect 来源页
④ 之后每个请求：拦截器注入 Authorization: Bearer <accessToken>（第 09 章 §9.3）
⑤ accessToken 过期：40102 → 单飞刷新 + 请求重放（第 09 章 §9.5，本章联调验证）
⑥ 登出：POST /auth/logout → 前端全量清理（§11.8）

职责边界一句话：前端管「令牌的携带与呈现层的拦截」，后端管「真伪与权限」。验证码次数锁定、角色判断的服务端复核、接口鉴权全部在后端——前端任何权限代码都只是体验优化，不是安全边界。

11.2 双令牌与无感刷新：本章要接的线

第 09 章已实现 refreshAccessToken（单飞锁 + _retried 重放）与 ApiError 归一化，本章补上认证域 API 与「会话恢复」，让刷新机制第一次真实运转：

// src/api/auth.js —— 认证域接口（示例账号一律虚构：demo@qingorder.example.com）
import request, { ApiError } from '@/utils/request'

export function fetchCaptcha() {
  return request.get('/auth/captcha', { silent: true }) // 换图失败不必 toast 打扰
}
export function login(payload) {
  return request.post('/auth/login', payload) // { username, password, captchaId, captchaCode }
}
export function logout() {
  return request.post('/auth/logout', {}, { silent: true }) // 就算后端异常前端也要清理（§11.8）
}
export function fetchProfile() {
  return request.get('/auth/profile') // 恢复会话时用 refreshToken 换新 accessToken 后调用
}

11.3 token 存储的 XSS 权衡：localStorage vs Cookie

这是每个团队都要正式做的决策，用对照表而不是拍脑袋：

教程推荐口径（写入团队规范 / ADR，并说清缓解措施）：

• accessToken 放内存（user store）——最短暴露窗口，刷新页面即失效；
• refreshToken 最小化持久化到 localStorage——换取「刷新页面免重新登录」的体验；
• 配套缓解：严格 CSP、不引入不可信第三方脚本、依赖及时升级；
• 若产品面向公网/高安全要求，切换 HttpOnly Cookie（SameSite=Lax 起）并把 CSRF 防护写进后端方案。

本章代码沿用第 09 章 request.js 的 localStorage 口径（qing_access_token / qing_refresh_token），并在第 12 章验收清单里复查这一决策记录。

11.4 登录页实战：账密 + 图形验证码

用第 10 章的 RHF + Zod 写登录页——schema 先行，验证码状态独立管理：

// src/schemas/auth.js —— 登录校验契约
import { z } from 'zod'

export const loginSchema = z.object({
  username: z.string().min(1, '请输入账号'),
  password: z.string().min(6, '密码至少 6 位'),
  captchaCode: z.string().min(1, '请输入图形验证码'),
})

// src/views/Login.jsx —— 登录页（RHF + Zod + 验证码无刷新换图）
import { useEffect, useState, useCallback } from 'react'
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { useNavigate, useLocation } from 'react-router'
import { useDispatch, useSelector } from 'react-redux'
import { message, Input, Button } from 'antd'
import { loginSchema } from '@/schemas/auth'
import { login, fetchCaptcha } from '@/api/auth'
import { setCredentials } from '@/store/userSlice'

export default function Login() {
  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
    resolver: zodResolver(loginSchema),
    defaultValues: { username: '', password: '', captchaCode: '' },
  })
  const [captcha, setCaptcha] = useState({ captchaId: '', imageBase64: '' })
  const navigate = useNavigate()
  const location = useLocation()
  const dispatch = useDispatch()
  const profile = useSelector((s) => s.user.profile)

  // 已登录访问登录页 → 直接送走（第 07 章易错点 2 的正确姿势）
  useEffect(() => {
    if (profile) navigate('/dashboard', { replace: true })
  }, [profile, navigate])

  const reloadCaptcha = useCallback(async () => {
    const data = await fetchCaptcha()
    setCaptcha(data) // { captchaId, imageBase64 }
  }, [])

  useEffect(() => { reloadCaptcha() }, [reloadCaptcha])

  const onSubmit = async (values) => {
    try {
      const data = await login({ ...values, captchaId: captcha.captchaId })
      dispatch(setCredentials(data)) // { profile, accessToken, refreshToken } 写入 store 与存储
      const from = location.state?.from ?? '/dashboard'
      navigate(from.startsWith('/') ? from : '/dashboard', { replace: true }) // 防开放重定向
    } catch (err) {
      message.error(err.message) // 验证码错误/锁定提示由后端 message 决定
      reloadCaptcha() // 无论何种失败：换一张验证码（旧的必然作废）
    }
  }

  return (
    <form className="login-page" onSubmit={handleSubmit(onSubmit)}>
      <h1>轻订单 · 登录</h1>
      <label>账号 <input {...register('username')} placeholder="demo@qingorder.example.com" /></label>
      {errors.username && <p className="error">{errors.username.message}</p>}
      <label>密码 <input type="password" {...register('password')} /></label>
      {errors.password && <p className="error">{errors.password.message}</p>}
      <label>验证码</label>
      <div className="captcha-row">
        <input {...register('captchaCode')} maxLength={4} />
        {/* 点击换图：验证码失败不刷新整页 */}
        <img src={captcha.imageBase64} alt="图形验证码" title="点击刷新"
          onClick={reloadCaptcha} />
      </div>
      {errors.captchaCode && <p className="error">{errors.captchaCode.message}</p>}
      <Button htmlType="submit" type="primary" block loading={isSubmitting}>登 录</Button>
    </form>
  )
}

setCredentials 是第 08 章 userSlice 的新 action，负责「store + 存储」一起落账：

// src/store/userSlice.js 追加
reducers: {
  setCredentials(state, action) {
    state.profile = action.payload.profile
    state.token = action.payload.accessToken // accessToken 进内存（§11.3 口径）
    // refreshToken 持久化由 request/auth 工具负责（与拦截器同源，避免两处写 key）
  },
  // ...setUser / clearUser
}

11.5 守卫强化：会话恢复、roles 拦截与 403 页

第 07 章 ProtectedRoute 只判断了「token 是否存在」，生产版要补两件事：会话恢复期不能误判（刷新页面时 store 是空的、refreshToken 还在恢复中，直接跳登录会闪跳）；页面级角色拦截（附录A：直输 URL 无权限 → 403）：

// src/store/userSlice.js 追加 —— 会话恢复 thunk
export const restoreSession = createAsyncThunk('user/restore', async (_, { rejectWithValue }) => {
  if (!localStorage.getItem('qing_refresh_token')) return rejectWithValue('no-session')
  try {
    return await fetchProfile() // 拦截器会先完成无感刷新（40102 → refresh → 重放）
  } catch (err) {
    return rejectWithValue(err.code ?? 'restore-failed')
  }
})
// extraReducers：fulfilled → profile 就位、isReady = true；rejected → 清存储、isReady = true

// src/router/ProtectedRoute.jsx —— 生产版：isReady 防闪跳 + roles 页面级拦截
import { Navigate, Outlet, useLocation } from 'react-router'
import { useSelector } from 'react-redux'
import { FullPageSpinner } from '@/components/FullPageSpinner'

export default function ProtectedRoute({ roles }) {
  const { profile, isReady } = useSelector((s) => s.user)
  const location = useLocation()

  if (!isReady) return <FullPageSpinner /> // ① 恢复中：不判不跳（防闪跳，易错点 2）
  if (!profile) {
    const from = location.pathname + location.search
    return <Navigate to="/login" replace state={{ from }} /> // ② 未登录 → 登录页
  }
  if (roles && !roles.includes(profile.role)) {
    return <Navigate to="/403" replace /> // ③ 页面级权限：附录A 三级模型的第二级
  }
  return <Outlet />
}

// App.jsx 路由树：守卫分层组合，每层 roles 精确声明
<Route path="/login" element={<Login />} />
<Route path="/403" element={<Forbidden />} />
<Route element={<ProtectedRoute />}> {/* 第一层：登录即可 */}
  <Route path="/" element={<AdminLayout />}>
    <Route path="dashboard" element={<Dashboard />} />
    <Route path="orders" element={<OrderListView />} />
    {/* 第二层：页面级角色 —— 报表中心仅运营/财务，系统设置仅超管（附录A §2） */}
    <Route element={<ProtectedRoute roles={['super_admin', 'operator', 'finance']} />}>
      <Route path="reports" element={<Reports />} />
    </Route>
    <Route element={<ProtectedRoute roles={['super_admin']} />}>
      <Route path="settings" element={<Settings />} />
    </Route>
  </Route>
</Route>

403 页是「拦得住」的另一半——给出路（回工作台/切账号），而不是一句冷冰冰的 403：

// src/views/Forbidden.jsx
import { Link } from 'react-router'
import { Button, Result } from 'antd'

export default function Forbidden() {
  return (
    <Result status="403" title="403" subTitle="抱歉，您没有权限访问该页面。"
      extra={<Link to="/dashboard"><Button type="primary">返回工作台</Button></Link>} />
  )
}

11.6 动态菜单：角色过滤与单一事实源

菜单级权限（三级模型第一级）的关键不是「过滤」这个动作，而是菜单与守卫共用一份配置——否则改角色必然漏改一处：

// src/router/menus.js —— 菜单配置：roles 为空数组 = 所有已登录角色可见
export const MENUS = [
  { key: '/dashboard', label: '工作台', roles: [] },
  { key: '/orders', label: '订单管理', roles: [] },
  { key: '/customers', label: '客户管理', roles: ['super_admin', 'operator', 'sales'] },
  { key: '/reports', label: '报表中心', roles: ['super_admin', 'operator', 'finance'] },
  { key: '/settings', label: '系统设置', roles: ['super_admin'] },
]

export function filterMenus(role) {
  return MENUS.filter((m) => m.roles.length === 0 || m.roles.includes(role))
}

// src/layouts/SideMenu.jsx —— 登录后按角色渲染
import { useSelector } from 'react-redux'
import { Menu } from 'antd'
import { filterMenus } from '@/router/menus'

export default function SideMenu() {
  const role = useSelector((s) => s.user.profile?.role)
  const items = filterMenus(role).map((m) => ({ key: m.key, label: m.label }))
  return <Menu theme="dark" mode="inline" items={items} />
}

📌 企业进阶：角色 → 菜单的映射应由后端下发（profile.menus），前端只做渲染与兜底过滤。硬编码 roles 的版本是教学简化，切换数据源时只需改 filterMenus 一处——这正是「单一事实源」设计预留的接缝。

11.7 按钮级权限：usePermission 与 <Auth> 组件

附录A §2 的按钮级规则：「删除订单」仅 super_admin 与 operator；「折扣审批」仅 finance。Vue 版用 v-permission 指令；React 没有指令，惯用法是权限 Hook + 包装组件：

// src/constants/permissions.js —— 按钮权限表：一处声明，处处引用
export const BUTTON_PERMISSIONS = {
  'order:delete': ['super_admin', 'operator'],
  'order:approve': ['finance'],
  'order:assign': ['super_admin', 'operator'],   // 批量指派销售
  'order:export': ['super_admin', 'operator', 'finance'],
}

// src/hooks/usePermission.js —— 权限判断 Hook
import { useCallback } from 'react'
import { useSelector } from 'react-redux'
import { BUTTON_PERMISSIONS } from '@/constants/permissions'

export function usePermission() {
  const role = useSelector((s) => s.user.profile?.role)
  const hasPermission = useCallback(
    (perm) => {
      const allowed = typeof perm === 'string'
        ? BUTTON_PERMISSIONS[perm] ?? [] // 未登记的权限码默认拒绝（安全默认）
        : perm // 也支持直接传角色数组
      return allowed.includes(role)
    },
    [role],
  )
  return { hasPermission }
}

// src/components/Auth.jsx —— 按钮级权限组件（对应 Vue 版 v-permission 指令）
export default function Auth({ allow, children, fallback = null }) {
  const { hasPermission } = usePermission()
  return hasPermission(allow) ? children : fallback
}

// 用法：声明式、可组合，权限码零魔法字符串
<Auth allow="order:delete">
  <Button danger onClick={() => handleDelete(order.id)}>删除订单</Button>
</Auth>
<Auth allow="order:approve">
  <Button type="primary" onClick={() => approveMutation.mutate(order.id)}>审核通过</Button>
</Auth>

与 Vue 指令的差异值得记一笔：指令是「命令式 DOM 移除」（el.remove()），组件是「声明式不渲染」——React 生态更倾向后者，因为它与虚拟 DOM 的心智一致，且 fallback 可以渲染「无权限占位」而非彻底消失。

11.8 登出清理与全局兜底

登出不是「删个 token」。四类状态漏一类都会出事故：

// src/hooks/useLogout.js —— 登出闭环：四类状态全量清理
import { useNavigate } from 'react-router'
import { useQueryClient } from '@tanstack/react-query'
import { useDispatch } from 'react-redux'
import { logout as logoutApi } from '@/api/auth'
import { clearUser } from '@/store/userSlice'
import { useDraftStore } from '@/store/useDraftStore'
import { auth } from '@/utils/auth'

export function useLogout() {
  const navigate = useNavigate()
  const queryClient = useQueryClient()
  const dispatch = useDispatch()

  return async function logout() {
    try { await logoutApi() } catch { /* 后端不可达也要继续本地清理 */ }
    // ① 令牌与存储
    auth.clear()                                   // accessToken / refreshToken
    // ② 全局 store
    dispatch(clearUser())                          // profile/token 归零
    useDraftStore.getState().clear()               // 订单草稿含敏感商机信息，一并清理
    // ③ 服务端缓存：换账号后旧数据绝不能残留（易错点 6）
    queryClient.clear()
    // ④ 页面状态：跳登录页本身即重置组件树；state.from 不传，登出默认不回跳
    navigate('/login', { replace: true })
  }
}

queryClient.clear() 是 React 版最容易漏的一步：TanStack Query 的缓存独立于 Redux/Zustand，只清 store 不清缓存，切换账号后第一个请求会先渲染上一个账号的缓存数据——真实的越权数据泄漏。全局兜底方面，第 09 章拦截器里 40101 的清理逻辑与本节 useLogout 收敛到同一个 auth.clear()，保证「任何路径的会话失效」行为一致。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）：登录页 + 守卫白名单

任务描述：实现 §11.4 登录页（mock：任意账密 + 验证码 1234 通过，返回 { profile, accessToken: 'mock-access', refreshToken: 'mock-refresh' }）；ProtectedRoute 接入 store 判断；未登录访问 /orders 跳登录并带 state.from；登录成功回跳原路径（含筛选参数）。

提示：setCredentials 里同时写 localStorage 与 store；回跳校验 from.startsWith('/')；mock 验证码错误返回 code: 4xx01，前端 toast 后换图。

验收标准：

• [ ] 未登录访问 /orders?status=draft → 登录页；登录后回到 /orders?status=draft；
• [ ] 验证码输错：toast 提示 + 图形自动更换 + 账号密码保留不重填；
• [ ] 已登录再访问 /login 自动跳工作台。

// 回跳核心（onSubmit 内）：
const from = location.state?.from ?? '/dashboard'
navigate(from.startsWith('/') ? from : '/dashboard', { replace: true })

// 失败保字段的原理：RHF 非受控值存在表单内部，catch 里不调 reset 就天然保留；
// 只需重置验证码一项：
//   setValue('captchaCode', '') + reloadCaptcha()

练习 2 · 进阶（30–60 min）：<Auth> + 403 页 + 动态菜单

任务描述：①实现 BUTTON_PERMISSIONS / usePermission / <Auth>（§11.7），在订单详情页按角色渲染「删除订单」「审核通过」按钮；②实现 403 页并接入 ProtectedRoute roles：/reports 允许运营/财务，/settings 仅超管；③SideMenu 按 filterMenus 渲染。用「切换角色」按钮（第 08 章练习 1）快速验证四种角色看到的菜单与按钮差异。

提示：切换角色后注意——菜单与 <Auth> 会因 store 变化自动重渲染，但页面级 403 不会自动重定向（守卫在路由切换时才求值），这正好是「当前页面权限失效」的观察点，验收时说明即可。

验收标准：

• [ ] sales 角色看不到「删除订单」「审核通过」；finance 只见「审核通过」；operator 两者都见；
• [ ] sales 直输 /settings → 403 页；super_admin 可进；
• [ ] 四种角色的侧边菜单项与 MENUS.roles 配置一一对应，配置表之外无任何角色硬编码。

// src/views/orders/OrderDetail.jsx（操作区节选）
import Auth from '@/components/Auth'
import { usePermission } from '@/hooks/usePermission'

function OrderActions({ order }) {
  const { hasPermission } = usePermission()
  return (
    <div className="order-actions">
      <Auth allow="order:approve">
        <Button type="primary" loading={approveMutation.isPending}
          onClick={() => approveMutation.mutate(order.id)}>审核通过</Button>
      </Auth>
      <Auth allow="order:delete">
        <Button danger onClick={() => handleDelete(order.id)}>删除订单</Button>
      </Auth>
      {/* 状态机限制（能点）与权限限制（可见）是两道独立闸门，第 12 章合流 */}
      <Auth allow={['super_admin', 'operator']}> {/* 也支持临时传角色数组 */}
        <Button onClick={() => navigate(`/orders/${order.id}/edit`)}>编辑</Button>
      </Auth>
    </div>
  )
}

练习 3 · 挑战（选做，60+ min）：无感刷新联调 + 登出闭环

任务描述：①把「40102 制造机」（第 09 章练习 2）接入登录后的真实流程：登录 → 停 2 秒 → 任意请求触发 40102 → 观察自动刷新 + 重放 + 界面无感；②手动把 qing_refresh_token 改成非法值再触发刷新，验证「清会话 → 跳登录」且不出现死循环；③实现 §11.8 useLogout，验证登出后 DevTools 里 localStorage 无 token、Redux DevTools 中 user 为空、React Query Devtools 缓存为空。

提示：恢复会话（restoreSession）也要联调：登录后刷新浏览器，应静默恢复到登录态而不是闪跳登录页；isReady 未就位期间 ProtectedRoute 渲染 spinner。

验收标准：

• [ ] 40102 触发后 Network 仅出现 1 次 /auth/refresh，原请求重放成功，无任何 toast；
• [ ] refreshToken 非法：清存储 → 跳登录 → 不再有第二次刷新请求；
• [ ] 刷新浏览器静默恢复登录态（无登录页闪现）；登出后三类调试工具均无残留数据。

extraReducers: (builder) => {
  builder
    .addCase(restoreSession.fulfilled, (state, action) => {
      state.profile = action.payload.profile ?? action.payload
      state.isReady = true
    })
    .addCase(restoreSession.rejected, (state, action) => {
      state.profile = null
      state.isReady = true // 关键：失败也要「就绪」，否则守卫永远 spinner
      if (action.payload !== 'no-session') {
        localStorage.removeItem('qing_access_token')
        localStorage.removeItem('qing_refresh_token')
      }
    })
}

// App.jsx 挂载时触发一次：
// const dispatch = useDispatch()
// useEffect(() => { dispatch(restoreSession()) }, [dispatch])

⚠️ 常见易错点

易错点 1 · token 一把梭进 localStorage，不做权衡记录

❌ 错误代码：

localStorage.setItem('qing_access_token', token)
localStorage.setItem('qing_refresh_token', token) // 双令牌全落盘，且没有任何决策说明

错误原因：localStorage 对 XSS 完全不设防——任何一个被注入的第三方脚本都能读走双令牌，7 天内冒充用户。问题不在「不能用」，而在「没权衡、没缓解、没记录」。

✅ 正确写法：

// 口径（§11.3）：accessToken 进内存 store，refreshToken 最小化持久化 + CSP 缓解
// 并把决策写入 ADR：「为什么内部中后台选择 localStorage + 缓解措施清单」
state.token = action.payload.accessToken      // 内存
localStorage.setItem('qing_refresh_token', data.refreshToken) // 仅 refreshToken

易错点 2 · 会话恢复完成前，守卫就跳了登录页

❌ 错误代码：

export default function ProtectedRoute() {
  const profile = useSelector((s) => s.user.profile) // 刷新后 store 初始为 null
  if (!profile) return <Navigate to="/login" replace /> // 💥 refreshToken 还没来得及恢复
}

错误原因：刷新页面后 Redux store 是全新的，profile 必然先为 null；此时「异步恢复会话」还在路上，守卫抢先判定未登录 → 已登录用户被闪跳到登录页。

✅ 正确写法：

const { profile, isReady } = useSelector((s) => s.user)
if (!isReady) return <FullPageSpinner /> // 恢复期只等待，不判定
if (!profile) return <Navigate to="/login" replace state={{ from }} />

易错点 3 · 权限判断散落魔法字符串

❌ 错误代码：

{role === 'super_admin' && <Button danger>删除订单</Button>}
{role === 'super_admin' || role === 'operator' ? <Button>审核通过</Button> : null} // 条件还写错了

错误原因：权限规则内联在 JSX 各处，改权限 = 全局搜字符串；第二个判断甚至与附录A 冲突（审批只属 finance）。条件写错还静默通过是权限代码最危险的特征。

✅ 正确写法：

<Auth allow="order:delete"><Button danger>删除订单</Button></Auth>   // 权限码 → 常量表
<Auth allow="order:approve"><Button>审核通过</Button></Auth>
// 规则只在 BUTTON_PERMISSIONS 一处；未登记的权限码默认拒绝

易错点 4 · 401 后只清 token 不跳转，或跳转后死循环

❌ 错误代码：

if (res.code === 40101) {
  localStorage.clear() // 清了，但用户停在当前页，后续每个请求继续 401
}
// 或：在拦截器里 navigate('/login') —— 模块层拿不到 Router 上下文，写成 window.location 循环刷新

错误原因：会话失效后没有任何「送客」动作，页面留在需登录的界面不断报错；而试图在非组件层直接路由跳转，又容易写出整页 reload 的循环。

✅ 正确写法：

// 请求层：清会话 + 抛 ApiError(40101)（§9.4）
// 组件层兜底：根组件监听全局错误/状态，统一跳登录
if (err.code === 40101) navigate('/login', { replace: true, state: { from: location.pathname } })
// 职责分离：拦截器管清理与抛错，路由跳转交给组件层（有 Router 上下文）

易错点 5 · 登出/切号不清 Query 缓存

❌ 错误代码：

dispatch(clearUser())
auth.clear()
navigate('/login') // 💡 TanStack Query 缓存原封不动
// 新账号登录后访问列表页：先渲染上一账号的缓存数据（isPending 都不会出现）

错误原因：React Query 的缓存挂在 QueryClient 上，独立于 Redux/Zustand 与 localStorage；只清后两者，等于给下个用户留了一份「上个账号的数据快照」——真实系统里属于越权数据泄漏事故。

✅ 正确写法：

queryClient.clear() // 登出闭环第 ③ 步（§11.8）；或 removeQueries({ queryKey: ['orders'] })

易错点 6 · redirect 回跳不做校验（开放重定向）

❌ 错误代码：

navigate(location.state?.from, { replace: true }) // from 可以是 https://evil.com 或 javascript: URL

错误原因：state.from 是客户端可控数据；攻击者构造诱导链接即可把登录用户送往外部站点（开放重定向），配合钓鱼页面危害放大。

✅ 正确写法：

const from = location.state?.from ?? '/dashboard'
navigate(from.startsWith('/') ? from : '/dashboard', { replace: true }) // 只允许站内路径

✅ 最佳实践

1. 权限三级各归其位：菜单级 filterMenus(role)、页面级 ProtectedRoute roles、按钮级 <Auth allow>——三级共用「角色/权限码」一份事实源，改权限永远只改配置。
2. 前端权限是体验，后端鉴权是底线：把这句话写进新人 onboarding 文档；<Auth> 隐藏按钮的同时，接口层的 40301 处理（toast + 引导）必须存在。
3. token 存储走 ADR：localStorage vs Cookie 的权衡、缓解措施、切换条件成文；accessToken 内存化 + refreshToken 最小化持久化是内部系统的默认起点。
4. 会话恢复必须显式建模：isReady 状态 + restoreSession thunk，守卫「恢复期不判定」；任何「刷新闪跳登录页」都是这个状态缺失的症状。
5. 无感刷新复用第 09 章三件套：单飞锁、_retried、裸 axios；联调时必测「并发 40102」「刷新自身失败」「恢复会话」三条路径。
6. 登出四清：令牌、store、queryClient.clear()、草稿等本地持久化——用 useLogout 收口成唯一入口，禁止散落清理。
7. 验证码交互零刷新：失败只换图不刷页，silent: true 让换图请求的失败不打扰用户；锁定提示如实透传后端 message。
8. 权限码语义化 + 默认拒绝：order:delete 这类「域:动作」命名写进常量表；查无此码一律视为无权限，宁可多拦不可漏放。

📌 本章小结

1. 认证全景：验证码 → 登录 → 双令牌 → 拦截器注入 → 40102 无感刷新 → 登出清理，前端管携带与呈现拦截，后端管真伪。
2. ProtectedRoute 是 React 版导航守卫：isReady 防闪跳、未登录重定向带 from、roles 页面级拦截进 403；403 页要给出路。
3. 动态菜单 = 配置表 + filterMenus；按钮级 = usePermission + <Auth> 组件（对应 v-permission），权限码常量化、默认拒绝。
4. 登出四清（令牌/store/Query 缓存/草稿）缺一不可，queryClient.clear() 是 React 版特有且最易漏的一步。
5. 至此零件全部齐备：路由（07）、状态（08）、请求层（09）、表单（10）、鉴权（11）。下一章把它们装配成完整的「轻订单管理系统」——四个里程碑 M1–M4，交付附录A §3.1–3.3 的可用版本。

📄 第 12 章 · 中级实战 —— 轻订单管理系统 12-中级实战-轻订单管理系统.md✓ 标记已学

📍 阶段：中级阶段（第 7–12 章）｜⏱ 预计学时：14–18 小时（分四个里程碑）｜🔗 前置：第 07–11 章 全部完成 + 附录A

⬅ 上一章：登录鉴权与权限控制 ｜ 📖 本版目录 ｜ ➡ 下一章：阶段自查 · 中级能力清单

💡 对照学习：本页是 React 版第 12 章，对应 Vue 版第 12 章 · 中级实战，里程碑 M1–M4、验收清单、自测用例两版逐条一致——同一个需求，两种生态的装配现场。差异只在实现选型：路由守卫（ProtectedRoute ≈ 导航守卫）、状态（slice/Zustand store ≈ Pinia store）、请求层（useOrderList + TanStack Query ≈ composable + 自研缓存）、表单（RHF + Zod ≈ ElForm rules）、按钮权限（<Auth> ≈ v-permission）。完成本章后，建议打开 Vue 版同章互相 review 对方代码。

🎯 学习目标

学完本章，你将能够：

1. 把第 07–11 章的全部零件装配成「轻订单」中后台：登录 → 动态菜单 → 订单列表/详情/新建 → 三级权限的完整链路；
2. 按企业惯例组织整合后的目录结构（api / hooks / schemas / store / constants / router / views），说出每个目录的准入标准；
3. 用状态机映射表驱动订单详情页的操作按钮（什么状态显示什么按钮），替代散落的 if/else；
4. 按里程碑 M1–M4 拆解交付：每个里程碑有明确的验收标准，做到「每 3–4 小时可验收一次」；
5. 在列表页完成「筛选 + 分页 + 防抖 + URL 回填」的完整体验，并保证万级数据演进（第 13 章）时不推翻结构；
6. 按附录A §3.1–3.3 逐条自查功能覆盖，跑通 10 条功能验收与 5 条自测用例；
7. 沉淀交付物：里程碑验收记录 + 遗留问题清单，让同事可以直接接手你的模块。

📖 核心知识点

12.1 本章目标：从零件到系统

第 07–11 章你在「练零件」，本章交付附录A §3.1–3.3 的可用版本：

登录鉴权（3.1）   —— 账密 + 图形验证码、双令牌无感刷新、个人中心入口
订单管理（3.3）   —— 列表（分页/筛选/排序）、详情（状态机/操作日志/流转按钮）、新建/编辑（明细行/金额汇总/审批分流）
权限模型（§2）    —— 菜单级（动态侧边栏）、页面级（守卫 + 403）、按钮级（<Auth>）

范围红线（高级阶段再做的，本章不碰）：工作台 Dashboard、客户/商品/报表完整模块、批量导出（练习中已给出导出钩子）、性能指标达标——它们分别是第 13–18 章的主菜。克制范围是里程碑能按时验收的前提。

12.2 目录结构全览

react-app/src/
├── main.jsx                    # 入口：Provider(store) + QueryClientProvider + BrowserRouter
├── App.jsx                     # 路由表：唯一事实源（07）
├── api/                        # 接口层：一域一文件（09）
│   ├── auth.js                 #   captcha / login / logout / profile
│   └── orders.js               #   fetchOrders / detail / create / submit / review / cancel
├── schemas/                    # 校验契约（10）
│   ├── auth.js                 #   loginSchema
│   └── order.js                #   orderSchema（数量/折扣/必填）
├── hooks/                      # 数据编排（09）/ 权限（11）/ 登出（11）
│   ├── useOrderList.js         #   筛选+分页+防抖+缓存+翻页保旧
│   ├── useDebouncedValue.js
│   ├── usePermission.js
│   └── useLogout.js
├── store/                      # 跨页共享态（08）
│   ├── index.js                #   configureStore
│   ├── userSlice.js            #   profile/token/isReady + login/restoreSession thunk
│   ├── dictSlice.js            #   字典缓存
│   └── useDraftStore.js        #   订单暂存区（Zustand + persist）
├── constants/                  # 业务常量：零魔法字符串（12 章新增）
│   ├── orderStatus.js          #   状态机字典 + 状态→动作映射
│   └── permissions.js          #   BUTTON_PERMISSIONS
├── router/                     # 路由资产（07/11）
│   ├── ProtectedRoute.jsx      #   登录 + roles 双拦截
│   ├── menus.js                #   菜单配置 + filterMenus
│   └── routeMeta.js            #   面包屑元信息
├── utils/
│   ├── request.js              #   axios + 拦截器 + 无感刷新（09）
│   ├── auth.js                 #   token 存取（11）
│   └── money.js                #   金额工具：全程分（09/10）
├── components/                 # 跨页面复用
│   ├── Auth.jsx                #   按钮级权限（11）
│   ├── StatusTag.jsx           #   状态标签（本章 §12.5）
│   └── FullPageSpinner.jsx
├── layouts/
│   ├── AdminLayout.jsx         #   Sider + Header + <Outlet />
│   ├── SideMenu.jsx            #   动态菜单（11）
│   └── Breadcrumbs.jsx         #   面包屑（07）
└── views/
    ├── Login.jsx  /  Forbidden.jsx  /  NotFound.jsx
    └── orders/
        ├── OrderListView.jsx   #   列表（12.5）
        ├── OrderDetailView.jsx #   详情 + 状态流转（12.6）
        ├── OrderCreate.jsx     #   新建（复用 10 章表单）
        └── components/         #   OrderFilters / OrderTable / OrderActions

准入标准一句话：api 只描述接口、schemas 只写规则、hooks 只做编排、views 只消费——任何跨目录的越界依赖都是 review 拦截项。

12.3 基础设施盘点与装配顺序

各章零件在本章的位置（装配顺序即依赖顺序）：

Mock 方案（附录A §7：教学阶段统一 mock）：mock/db.js 导出 30+ 条订单（字段与附录A 实体逐字一致，orderNo = QO + yyyyMMdd + 6 位序号，金额单位分），mock/server.js 拦截 api/ 的调用并模拟 200ms 延迟、40102 制造机与登录态校验。mock 的响应形状必须以附录A 统一响应体为准——后端接入时只换 request.js 的 baseURL，业务代码零改动。

12.4 状态机映射表：详情页操作按钮的引擎

附录A 订单状态机是业务的心脏。把它翻译成数据而不是 if/else——UI 从映射表派生，加状态只改表：

// src/constants/orderStatus.js —— 状态机字典：唯一事实源
export const ORDER_STATUS = {
  draft:          { label: '草稿',   color: 'default' },
  pending_review: { label: '待审核', color: 'orange' },
  approved:       { label: '已审核', color: 'blue' },
  shipped:        { label: '已发货', color: 'cyan' },
  completed:      { label: '已完成', color: 'green' },
  rejected:       { label: '已拒绝', color: 'red' },
  cancelled:      { label: '已取消', color: 'gray' },
}

// 状态 → 允许的操作（附录A：rejected 可编辑后重新提交；非终态可取消且需填原因）
export const STATUS_ACTIONS = {
  draft:          ['submit', 'edit', 'cancel'],
  pending_review: ['approve', 'reject', 'cancel'],   // 仅 finance 可见 approve/reject（权限层过滤）
  approved:       ['ship', 'cancel'],
  shipped:        ['complete'],
  completed:      [],
  rejected:       ['edit', 'submit', 'cancel'],
  cancelled:      [],
}

export const STATUS_OPTIONS = Object.entries(ORDER_STATUS)
  .map(([value, { label }]) => ({ value, label }))

// src/views/orders/components/StatusTag.jsx —— 状态标签：从字典渲染
import { Tag } from 'antd'
import { ORDER_STATUS } from '@/constants/orderStatus'

export default function StatusTag({ status }) {
  const meta = ORDER_STATUS[status]
  return <Tag color={meta?.color ?? 'default'}>{meta?.label ?? status}</Tag>
}

12.5 M2 的核心：订单列表页（筛选/分页/URL 回填）

列表页 = 第 09 章 useOrderList + AntD Table + 状态标签，几乎没有新代码——这正是「分层」的回报：

// src/views/orders/OrderListView.jsx —— 列表页装配
import { Table, Input, Select, Button, Space } from 'antd'
import { Link } from 'react-router'
import { useOrderList } from '@/hooks/useOrderList'
import StatusTag from './components/StatusTag'
import { STATUS_OPTIONS } from '@/constants/orderStatus'
import { formatFen } from '@/utils/money'
import { fetchOrders } from '@/api/orders' // mock 直连；生产走 useOrderList 内部
import { useState } from 'react'

export default function OrderListView() {
  const { filters, setFilters, list, total, isPending, isFetching } = useOrderList()
  const [rows, setRows] = useState([]) // 渲染数据：mock 阶段用 effect 填充，详见参考答案

  const columns = [
    { title: '订单号', dataIndex: 'orderNo',
      render: (no, record) => <Link to={`/orders/${record.id}`}>{no}</Link> },
    { title: '客户', dataIndex: 'customerName' },
    { title: '归属销售', dataIndex: 'ownerName' },
    { title: '状态', dataIndex: 'status', render: (s) => <StatusTag status={s} /> },
    { title: '总金额（元）', dataIndex: 'totalAmount',
      render: (fen) => formatFen(fen), align: 'right' }, // 分 → 元，仅展示层
    { title: '创建时间', dataIndex: 'createdAt' },
  ]

  return (
    <div>
      <Space style={{ marginBottom: 16 }}>
        <Input placeholder="订单号 / 客户名" value={filters.keyword}
          onChange={(e) => setFilters({ keyword: e.target.value })} allowClear />
        <Select placeholder="状态" style={{ width: 140 }} value={filters.status || undefined}
          options={STATUS_OPTIONS} onChange={(v) => setFilters({ status: v ?? '' })} allowClear />
        <Button type="primary"><Link to="/orders/new">新建订单</Link></Button>
      </Space>
      <Table
        rowKey="id"
        loading={isPending}
        columns={columns}
        dataSource={list}
        pagination={{
          current: filters.page, pageSize: filters.pageSize, total,
          showSizeChanger: false, // 附录A 固定 20/页
          onChange: (page) => setFilters({ page }),
        }}
      />
      {isFetching && <div className="updating-hint">数据更新中…</div>}
    </div>
  )
}

真实链路中 list 已由 useOrderList 从 Query 缓存返回；教学 mock 阶段可让 api/orders.js 直接返回 mock/server.js 的 Promise，useOrderList 的 queryFn 无需感知。不要为了 mock 在组件里另开一条数据通道。

12.6 M3 的核心：详情页状态流转 + 新建订单

详情页三块：基本信息（含明细行金额）、操作日志时间线（mock 数组渲染）、状态流转按钮区——由「状态机允许的操作 × 按钮级权限」双重过滤：

// src/views/orders/components/OrderActions.jsx —— 状态机 × 权限 的合流点
import { Button, Space, Modal, Input } from 'antd'
import { STATUS_ACTIONS } from '@/constants/orderStatus'
import { usePermission } from '@/hooks/usePermission'
import { useOrderActions } from '../../hooks/useOrderActions' // 本页动作集，见下

const ACTION_META = {
  submit:   { label: '提交审核', danger: false, perm: null },          // 运营/销售本人
  approve:  { label: '审核通过', danger: false, perm: 'order:approve' }, // 仅 finance
  reject:   { label: '拒绝',     danger: true,  perm: 'order:approve' },
  ship:     { label: '发货',     danger: false, perm: null },
  complete: { label: '完成',     danger: false, perm: null },
  edit:     { label: '编辑',     danger: false, perm: null },
  cancel:   { label: '取消订单', danger: true,  perm: null, needReason: true }, // 附录A：需填原因
}

export default function OrderActions({ order }) {
  const { hasPermission } = usePermission()
  const { runAction, pendingAction } = useOrderActions(order.id)

  const allowed = (STATUS_ACTIONS[order.status] ?? [])
    .filter((a) => !ACTION_META[a].perm || hasPermission(ACTION_META[a].perm))

  const handleClick = (action) => {
    if (ACTION_META[action].needReason) {
      let reason = ''
      Modal.confirm({
        title: '取消订单需要填写原因',
        content: <Input.TextArea onChange={(e) => { reason = e.target.value }} />,
        onOk: () => runAction(action, { reason }), // 附录A：取消必须带原因
      })
      return
    }
    runAction(action)
  }

  return (
    <Space>
      {allowed.map((a) => (
        <Button key={a} danger={ACTION_META[a].danger}
          loading={pendingAction === a} onClick={() => handleClick(a)}>
          {ACTION_META[a].label}
        </Button>
      ))}
    </Space>
  )
}

// src/views/orders/hooks/useOrderActions.js —— 动作集：mutation + 失效
import { useState } from 'react'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { message } from 'antd'
import { submitOrder, reviewOrder, cancelOrder } from '@/api/orders'

export function useOrderActions(orderId) {
  const queryClient = useQueryClient()
  const [pendingAction, setPendingAction] = useState(null)

  const mutation = useMutation({
    mutationFn: ({ action, payload }) => {
      setPendingAction(action)
      switch (action) {
        case 'submit':   return submitOrder(orderId)
        case 'approve':  return reviewOrder(orderId, 'approve')
        case 'reject':   return reviewOrder(orderId, 'reject', payload?.reason)
        case 'cancel':   return cancelOrder(orderId, payload?.reason)
        default:         return Promise.reject(new Error('未实现的动作: ' + action))
      }
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['orders', 'detail', orderId] }) // 详情刷新
      queryClient.invalidateQueries({ queryKey: ['orders', 'list'] })            // 列表刷新
    },
    onSettled: () => setPendingAction(null),
  })

  return { runAction: mutation.mutate, pendingAction }
}

新建订单复用第 10 章全部成果（schema、useFieldArray、金额联动、草稿 store），唯一新增是提交后的状态分流——折扣 >10% 时提示「已提交审核，等待财务审批」，跳详情确认状态为 pending_review。

12.7 里程碑拆解：M1–M4

每个里程碑 3–4 小时，完成即可独立验收——不许攒到最后一起测：

M1 骨架与登录（第 07/11 章成果落地）
   路由树 + Layout + 动态菜单 + 登录页（验证码）+ ProtectedRoute + 403/404
M2 订单列表（第 08/09 章成果落地）
   useOrderList + Table + 筛选/分页/排序 + URL 回填 + 防抖 + StatusTag
M3 详情与新建（第 10 章成果落地）
   详情页（时间线 + 状态流转）+ 新建/编辑（明细行 + 金额联动 + 审批分流）
M4 权限收口与整体验收（第 11 章成果落地）
   <Auth> 按钮权限 + roles 页面拦截复验 + 登出闭环 + 全链路自测用例

12.8 与附录A 的对照与验收

功能验收清单（10 条，附录A §3.1–3.3 口径）：

• [ ] 1. 账密 + 图形验证码登录；验证码错误 toast 且自动换图；
• [ ] 2. 登录后按角色渲染侧边栏（sales 无「系统设置」等）；
• [ ] 3. sales 直输无权限 URL → 403 页，给出返回路径；
• [ ] 4. 订单列表：分页 20/页、关键词/状态/日期筛选、按创建时间/金额排序；
• [ ] 5. 刷新/回退后筛选、页码、排序从 URL 完整还原；
• [ ] 6. 订单详情：基本信息、明细行金额、操作日志时间线、状态流转按钮；
• [ ] 7. 新建订单：客户搜索、明细行增删、数量 1–9999 与行折扣 0–100% 即时校验、总额自动汇总；
• [ ] 8. 整单折扣 >10% 提交后状态为 pending_review，finance 角色可见审批按钮；
• [ ] 9. 取消订单强制填写原因（draft 等非终态）；
• [ ] 10. 双令牌：过期自动无感刷新（Network 仅 1 次刷新 + 重放成功），登出四清（token/store/缓存/草稿）。

全链路自测用例（5 条，手工跑通）：

1. operator 登录 → 新建订单（2 行明细，折扣 100%）→ 状态 draft → 提交 → pending_review；
2. 构造整单折扣 85% 的新建 → 提交 → 详情提示待财务审批 → finance 登录 → 审批通过 → approved；
3. sales 登录 → 列表仅见本人订单（ownerName 过滤由 mock 支撑）→ 尝试直输 /settings → 403；
4. 停放 mock 的 40102 触发器 → 任意操作触发无感刷新 → 操作无中断、无重复 toast；
5. 任一账号登出 → 重新以另一角色登录 → 列表、菜单、按钮与角色一致，无上账号数据残留。

交付物模板（每个里程碑提交时填写，进 PR 描述）：

## M2 验收记录
- 通过项：验收清单 #4 #5（勾选并附截图/录屏路径）
- 遗留问题：日期区间筛选暂用文本占位（M2.1 跟进）；mock 不校验 sales 归属（M4 复验）
- 自测用例：用例 1 通过；用例 2 阻塞（等待审批接口 mock）

🛠 渐进式实战练习

练习 1 · 基础（M1，3–4 h）：骨架、登录与动态菜单

任务描述：装配 M1——完整路由树（含懒加载与 404）、AdminLayout（Sider + 面包屑 + 内容区）、登录页（账密 + 验证码 + 失败换图）、ProtectedRoute（isReady 防闪跳 + redirect 回跳）、filterMenus 动态侧边栏、403 页。mock 支持四种角色切换登录（演示账号：demo@qingorder.example.com，角色由验证码输入框旁边的下拉临时控制，仅教学用）。

提示：先让「登录 → 菜单 → 空白页面」跑通再填页面；routeMeta 与 menus 的 key 保持同源；会话恢复 restoreSession 在本里程碑就要接上（刷新不丢登录态）。

验收标准：

• [ ] 刷新浏览器登录态保持（无登录页闪现）；登出后刷新停在登录页；
• [ ] 四种角色登录后菜单项与附录A §2 权限表一致；
• [ ] sales 直输 /settings → 403；super_admin 可进；
• [ ] 构建产物中登录页与业务页分离（每个页面独立 chunk）。

// src/App.jsx —— M1 完成后的路由树（M2–M4 往里挂页面即可）
import { Routes, Route, Navigate } from 'react-router'
import { lazy, Suspense } from 'react'
import ProtectedRoute from './router/ProtectedRoute'
import AdminLayout from './layouts/AdminLayout'
import Login from './views/Login'
import Forbidden from './views/Forbidden'
import NotFound from './views/NotFound'

const Dashboard = lazy(() => import('./views/Dashboard'))
const OrderListView = lazy(() => import('./views/orders/OrderListView'))
const OrderDetailView = lazy(() => import('./views/orders/OrderDetailView'))
const OrderCreate = lazy(() => import('./views/orders/OrderCreate'))
const Settings = lazy(() => import('./views/Settings'))

function LazyPage({ children }) {
  return <Suspense fallback={<div className="page-loading">加载中…</div>}>{children}</Suspense>
}

export default function App() {
  return (
    <Routes>
      <Route path="/login" element={<Login />} />
      <Route path="/403" element={<Forbidden />} />
      <Route element={<ProtectedRoute />}>
        <Route path="/" element={<AdminLayout />}>
          <Route index element={<Navigate to="/dashboard" replace />} />
          <Route path="dashboard" element={<LazyPage><Dashboard /></LazyPage>} />
          <Route path="orders" element={<LazyPage><OrderListView /></LazyPage>} />
          <Route path="orders/new" element={<LazyPage><OrderCreate /></LazyPage>} />
          <Route path="orders/:id" element={<LazyPage><OrderDetailView /></LazyPage>} />
          <Route element={<ProtectedRoute roles={['super_admin']} />}>
            <Route path="settings" element={<LazyPage><Settings /></LazyPage>} />
          </Route>
        </Route>
      </Route>
      <Route path="*" element={<NotFound />} />
    </Routes>
  )
}

练习 2 · 进阶（M2 + M3，7–9 h）：订单列表、详情与新建

任务描述：装配 M2 + M3——mock/db.js 造 30+ 条合规订单 → useOrderList 驱动列表页（筛选/分页/排序/URL 回填/防抖）→ 详情页（基本信息 + 明细金额 + 操作日志时间线 + OrderActions 状态流转）→ 新建/编辑页（第 10 章表单 + 草稿 store + 提交分流）。提交草稿、审批（approve/reject）、取消（带原因）三条 mutation 全部接通并失效缓存。

提示：时间线用 AntD Timeline 渲染 order.logs（mock 数组：{ at, operator, action, detail }）；审批走乐观更新（第 09 章 §9.10）体验更佳但必须有回滚；OrderActions 的按钮集合 = STATUS_ACTIONS[status] ∩ hasPermission。

验收标准：

• [ ] 表单通过第 10 章练习 2/3 的全部验收标准，用例「折扣 85 → pending_review」成立；
• [ ] 详情页执行「提交审核」后：状态标签即时更新、操作日志新增一条、列表页返回时数据已刷新；
• [ ] 筛选（关键词防抖 400ms）、翻页、排序全部写 URL；翻页无 loading 闪烁（placeholderData）；
• [ ] 取消订单必须填原因（空原因不可提交）；cancelled 后无任何操作按钮。

// mock/db.js —— 造数：字段与附录A 实体逐字一致（金额单位分）
const SKUS = [
  { skuId: 'sku001', skuName: '智能网关 X1', unitPriceFen: 129900 },
  { skuId: 'sku002', skuName: '温湿度传感器', unitPriceFen: 19900 },
]

function makeOrder(seq, overrides = {}) {
  const date = new Date(Date.now() - seq * 86_400_000)
  const ymd = date.toISOString().slice(0, 10).replaceAll('-', '')
  const items = overrides.items ?? [
    { skuId: 'sku001', skuName: '智能网关 X1', quantity: 3, unitPriceFen: 129900, discountPercent: 100 },
  ]
  const totalAmount = items.reduce(
    (s, it) => s + Math.round(it.quantity * it.unitPriceFen * (it.discountPercent / 100)), 0,
  )
  return {
    id: `o_${1000 + seq}`,
    orderNo: `QO${ymd}${String(seq).padStart(6, '0')}`, // 附录A：QO + yyyyMMdd + 6 位序号
    customerId: 'c_001',
    customerName: '华信电子',
    ownerName: '青云-销售小王',
    status: overrides.status ?? 'draft',
    items,
    wholeDiscountPercent: overrides.wholeDiscountPercent ?? 100,
    totalAmount,
    createdAt: date.toISOString(),
    logs: [{ at: date.toISOString(), operator: 'system', action: '创建订单', detail: '-' }],
  }
}

export const db = { orders: Array.from({ length: 32 }, (_, i) => makeOrder(i + 1, seed(i))) }
// seed(i) 可按序号轮换 status/ownerName/wholeDiscountPercent，覆盖全部状态用于联调

// mock/server.js 节选
export function listOrders({ keyword, status, page = 1, pageSize = 20, sort = 'createdAt', order = 'desc' }) {
  let list = db.orders.filter((o) =>
    (!keyword || o.orderNo.includes(keyword) || o.customerName.includes(keyword))
    && (!status || o.status === status))
  list = [...list].sort((a, b) => (order === 'asc' ? 1 : -1) * (a[sort] > b[sort] ? 1 : -1))
  return { list: list.slice((page - 1) * pageSize, page * pageSize), total: list.length, page, pageSize }
}

练习 3 · 挑战（M4，2–3 h）：权限收口 + 完整验收

任务描述：装配 M4——<Auth> 接入所有操作按钮（删除、审批、批量指派入口）、roles 页面拦截复验（报表/设置）、useLogout 登出闭环、批量导出选中订单为 CSV（第 09 章练习 3 的 exportSelected 挂上 AntD Table 的 rowSelection）。然后跑 §12.8 的 10 条验收 + 5 条自测用例，填写两份交付物模板。

提示：验收时切换四种角色各过一遍「菜单 → 页面 → 按钮」矩阵，建议画成表格逐格打勾；无感刷新用例要在「列表页翻页中」触发才最接近真实。

验收标准：

• [ ] 10 条功能验收全绿；5 条自测用例全链路通过；
• [ ] 「删除订单」按钮仅 super_admin/operator 可见；「审批」仅 finance；权限矩阵表格无一处不符；
• [ ] 登出后以 finance 重新登录：菜单、缓存、草稿均无前一账号痕迹；
• [ ] 交付物模板两份已填（每里程碑一份），遗留问题都有跟进编号。

// OrderListView 追加批量导出
import { Auth } from '@/components/Auth' // named export 亦可，团队统一即可
import { useOrderList } from '@/hooks/useOrderList'

const [selectedIds, setSelectedIds] = useState([])
const { exportSelected } = useOrderList()

<Table
  rowSelection={{ onChange: (keys) => setSelectedIds(keys) }}
  /* ...其余 props 同 §12.5 */ />

<Auth allow="order:export">
  <Button disabled={selectedIds.length === 0} loading={exporting}
    onClick={async () => { setExporting(true); await exportSelected(selectedIds); setExporting(false) }}>
    导出选中（CSV）
  </Button>
</Auth>

⚠️ 常见易错点

易错点 1 · 状态/权限魔法字符串散落各页

❌ 错误代码：

{order.status === 'pendding_review' && <Button>审核通过</Button>} // 拼错 + 散落三处
{role === 'admin' && <Button danger>删除</Button>}              // 角色名还与附录A 不一致

错误原因：状态机与权限模型是业务契约，散落成字符串后，附录A 改一处（比如角色更名）就是全局捉虫；拼写错误还静默通过（'pendding' 永远不相等）。

✅ 正确写法：

<Auth allow="order:approve"><Button>审核通过</Button></Auth>
// 状态判断走 STATUS_ACTIONS 映射表（§12.4），角色判断走 BUTTON_PERMISSIONS
// ESLint 层面可加 no-restricted-syntax 禁止裸写状态字符串

易错点 2 · 菜单与守卫两处维护角色

❌ 错误代码：

// menus.js：{ key: '/reports', label: '报表中心', roles: ['operator', 'finance'] }
// App.jsx： <Route element={<ProtectedRoute roles={['super_admin', 'operator']} />}>  // 忘了 finance
// 结果：finance 看得到菜单、点进去 403 —— 用户视角「权限系统抽风」

错误原因：同一份权限规则写在两个文件，改配置必然漏改；这不是粗心问题，是结构问题。

✅ 正确写法：

// 菜单 roles 与路由 roles 由同一常量派生（单一事实源）：
import { MENUS } from '@/router/menus'
const REPORT_ROLES = MENUS.find((m) => m.key === '/reports').roles
<Route element={<ProtectedRoute roles={REPORT_ROLES} />}>…</Route>
// 更进一步（企业口径）：roles 由后端 profile.menus 下发，前端只渲染

易错点 3 · 详情页参数变化不刷新，或 mock 与真实接口 shape 漂移

❌ 错误代码：

// 详情页从 /orders/1001 点「下一单」到 /orders/1002，界面还是 1001
useEffect(() => { load(id) }, [])              // 依赖数组漏了 id（第 07 章易错点 1 重演）
// 同时：mock 返回 { list, rows }，真实附录A 契约是 { list, total, page, pageSize }

错误原因：两件事同根——契约没有单一事实源。参数契约（URL→数据）与数据契约（响应 shape）只要有一处靠「记忆」维护，联调时就会爆炸。

✅ 正确写法：

useQuery({ queryKey: ['orders', 'detail', id], queryFn: ({ signal }) => fetchOrderDetail(id, { signal }) })
// id 进 key：参数变化自动重查（07 章问题的 Query 解）
// mock 的返回结构对照附录A §5 逐字段核对，统一响应体 { code, message, data } 不准走样

易错点 4 · 金额展示层转换失控：分/元混用

❌ 错误代码：

<td>{order.totalAmount / 100} 元</td>        {/* A 页面手除 100 */}
<td>¥{(order.totalAmount / 100).toFixed(1)}</td> {/* B 页面留 1 位小数 */}
<InputNumber value={form.unitPriceFen / 100} /> {/* C 处把「分」的字段直接当元展示 */}

错误原因：转换逻辑散落，精度与格式各自为政；一旦有人把「元」写回数据层，误差固化进库（第 09/10 章易错点的系统集成版）。

✅ 正确写法：

// 全站唯一入口：utils/money.js 的 formatFen / calcItemFen / sumFen
<td>{formatFen(order.totalAmount)} 元</td>
// review 清单加一条：任何 /100 或 *100 必须出现在 money.js 内

易错点 5 · 提交与流转不加锁：双击两笔订单 / 连点两次审批

❌ 错误代码：

<Button type="primary" onClick={() => createMutation.mutate(payload)}>提交订单</Button>
// isSubmitting 没接：双击 = 两次 POST /orders = 两笔真实订单（附录A 一期事故清单复刻）

错误原因：mutation 未连接 pending 态，按钮永远可点；后端幂等是最后防线，前端连第一道闸都没关。

✅ 正确写法：

<Button type="primary" loading={createMutation.isPending} disabled={createMutation.isPending}
  onClick={() => createMutation.mutate(payload)}>提交订单</Button>
// useOrderActions 的 pendingAction 同理：流转按钮逐个 loading（§12.6 已内置）

易错点 6 · 状态流转只改前端字段，不失效缓存

❌ 错误代码：

const handleApprove = async () => {
  await reviewOrder(order.id, 'approve')
  order.status = 'approved' // 直接改 props/缓存对象；列表页还是「待审核」
}

错误原因：直接修改只影响当前内存引用；Query 缓存与列表页毫不知情，跨页状态不一致直到刷新才「治好」。直接改 props 还违反单向数据流（第 03 章）。

✅ 正确写法：

onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: ['orders', 'detail', order.id] })
  queryClient.invalidateQueries({ queryKey: ['orders', 'list'] }) // 相关缓存全部标记过期
}
// 需要瞬时反馈的场景用乐观更新（§9.10）：onMutate 快照 + onError 回滚，而不是裸改

✅ 最佳实践

1. 里程碑即验收：M1–M4 每个 3–4 小时一个可验收切片，验收记录进 PR 描述——「攒到大爆炸式联调」是学生作品与企业交付的第一区别。
2. 常量先行：orderStatus.js / permissions.js 在写任何页面前就位；状态机映射表让「加一个状态」变成改一张表。
3. 契约即文档：mock 响应逐字段对照附录A §5（统一响应体、分页结构、实体定义），后端接入时只换 VITE_API_BASE_URL。
4. 单一事实源三连：路由表（页面）、routeMeta（面包屑/roles）、menus（菜单）同源派生；权限矩阵表格作为验收工具随代码提交。
5. 金额纪律写进 review 清单：/100、*100 只允许出现在 money.js；列表、详情、表单、导出四处展示统一 formatFen。
6. 每个写操作都有三层防护：按钮 loading/disabled → 请求层防抖/去重 → 后端幂等；涉及审批的动作优先乐观更新 + 回滚。
7. 缓存失效粒度刻意为之：动作成功后「详情精确失效 + 列表前缀失效」，跨页一致性由 Query 保证，不靠手改对象。
8. 交付可接手：目录准入标准、遗留问题编号、自测用例记录——第 22 章团队协作规范的预演，从现在开始养成。

📌 本章小结

1. 中级实战 = 装配：07 路由、08 状态、09 请求层、10 表单、11 鉴权六个零件按 M1–M4 组装成附录A §3.1–3.3 的可用版本。
2. 状态机映射表（STATUS_ACTIONS）与权限常量表（BUTTON_PERMISSIONS）的交集决定每个按钮的命运——业务规则数据化，UI 只是投影。
3. 列表、详情、新建三个页面几乎没有「新代码」，全是既有 Hook/组件的复用与组合——分层的回报在本章兑现。
4. 验收驱动交付：10 条功能验收 + 5 条全链路用例 + 权限矩阵 + 里程碑记录，全部通过才算毕业。
5. 中级阶段的最后一站是自查：打开《阶段自查 · 中级能力清单》完成 16 条能力勾选与 30 分钟自测小考；达标后进入第三部分 · 高级阶段，开始治理万级列表、首屏性能与质量保障。

📄 第 13 章 · 渲染性能优化 13-渲染性能优化.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：6–8 小时｜🔗 前置：第 12 章 · 中级实战 完成 + 附录A §4 非功能需求

⬅ 上一章：中级实战 · 轻订单管理系统 ｜ 📖 本版目录 ｜ ➡ 下一章：加载性能优化

💡 对照学习：本页是 React 版第 13 章，对应 Vue 版第 13 章 · 渲染性能优化。概念映射：React.memo ≈ v-memo、useMemo ≈ computed 的缓存语义、Profiler ≈ Vue Devtools 性能面板、TanStack Virtual ≈ vue-virtual-scroller、用 key 重置组件状态 ≈ 动态 :key 强制重建子树。核心心智差异：Vue 靠依赖收集做到「谁用了数据谁更新」，React 默认「父渲染 → 子树全渲染」，优化手段偏手动声明。从本章起，全书代码全面切换为 TypeScript（.jsx → .tsx），工程化配置在第 17 章展开。

🎯 学习目标

学完本章，你将能够：

1. 说出 React 重渲染的三大触发条件，解释「渲染阶段 / 提交阶段」的划分，以及为什么子组件没有任何 props 变化也会跟着父组件重渲染；
2. 使用 React DevTools Profiler 录制一次真实交互，读出「谁在重渲染、渲染原因、实际耗时」三个关键信息；
3. 恰当使用 React.memo / useMemo / useCallback，并能识别让 memo 失效的典型写法（内联对象、内联函数、未缓存的 Context value）；
4. 用「状态下放」与「children 组合」两种结构性手段缩小重渲染范围，而不是到处包 memo；
5. 用 key 重置组件状态（如切换客户后清空明细表单），避免为「重置」编写 effect；
6. 从零实现一个简化版虚拟滚动 hook 讲清原理，再用 TanStack Virtual 替换为生产级实现；
7. 完成万级订单列表卡顿治理：滚动掉帧 < 5%（附录A §4 目标），并输出优化前后的 Profiler 对比记录。

📖 核心知识点

13.1 渲染机制原理：Fiber 与「重渲染」到底指什么

先统一词汇。React 把一次更新分成两个阶段：

• 渲染阶段（render phase）：重新调用组件函数，得到新的元素树，与旧树 diff（这一步纯计算，不碰 DOM）。Fiber 架构把这项工作拆成一个个可中断、可恢复的小单元（Fiber 节点），让 React 可以按优先级让路给高优先级更新——这是 React 18+ 并发特性的地基。
• 提交阶段（commit phase）：把 diff 结果一次性应用到 DOM，同步执行 useLayoutEffect，随后浏览器异步执行 useEffect。

「卡」通常来自两处：渲染阶段耗时太长（大列表全量 diff），或提交阶段 DOM 变更太多（大量节点重建）。优化前先分清是哪一种。

重渲染的触发条件只有三类：

1. 组件自身的 state 或 reducer dispatch 变化（useState / useReducer / useSyncExternalStore 等）；
2. 父组件重渲染（React 默认递归重渲染整棵子树，与 props 变没变无关）；
3. Context value 变化（消费该 Context 的子树整体重渲染）。

// 父组件重渲染，子组件必然重渲染——哪怕它没接收任何 props
function Parent() {
  const [keyword, setKeyword] = useState('')
  console.log('Parent 渲染')
  return (
    <div>
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
      {/* Child 没有任何 props，仍会随每次按键重渲染 */}
      <Child />
    </div>
  )
}

function Child() {
  console.log('Child 渲染')
  return <footer>轻订单 · 内部系统</footer>
}

对照 Vue：Vue 组件在渲染时收集依赖，没用到 keyword 的组件不会被触发；React 没有依赖追踪，默认「自上而下全量执行函数，diff 兜底」。这不是谁优谁劣——React 换来的是「渲染是纯函数、可预测」的心智模型，代价是优化要手动声明（memo）。理解这一点，后面所有手段才不玄学。

13.2 定位工具：React DevTools Profiler 与 <Profiler> API

先测量，再优化。React DevTools 的 Profiler 面板是最常用的定位工具：

1. 打开 Profiler 面板 → 点录制 → 在页面上复现卡顿操作 → 停止录制；
2. 火焰图按「渲染耗时」排序，宽 = 耗时长；颜色越黄越慢；
3. 在设置里勾选 「Highlight updates when components render」 可实时看到谁在闪；勾选 「Record why each component rendered」 后，点选任意 Fiber 节点可看到渲染原因（如 Parent component rendered、Props changed）。

组件级埋点用官方 <Profiler> API，可以精确到某个子树：

import { Profiler, type OnRenderCallback } from 'react'

const onOrderListRender: OnRenderCallback = (id, phase, actualDuration) => {
  // phase: 'mount' | 'update' | 'nested-update'
  if (actualDuration > 16) {
    // 超过一帧预算（60fps ≈ 16.7ms）才记录，避免日志噪音
    console.warn(`[${id}] ${phase} 耗时 ${actualDuration.toFixed(1)}ms`)
  }
}

export function OrderListEntry({ orders }: { orders: Order[] }) {
  return (
    <Profiler id="OrderList" onRender={onOrderListRender}>
      <OrderListView orders={orders} />
    </Profiler>
  )
}

两个时长字段要分清：actualDuration 是本次实际渲染耗时（含子组件）；baseDuration 是「不 memo 时的估计耗时」。baseDuration 大而 actualDuration 小，说明 memo 生效了；两者都大，说明这条子树本身就是热点，优先结构性优化。

API 细节以官方文档为准：https://react.dev/reference/react/Profiler

13.3 memo 三件套：React.memo / useMemo / useCallback 的恰当使用

三者解决的问题不同：

import { memo, useCallback, useMemo } from 'react'

interface OrderRowProps {
  order: Order
  active: boolean
  onOpen: (id: string) => void
}

// memo：props 浅比较相同 → 跳过整行渲染
const OrderRow = memo(function OrderRow({ order, active, onOpen }: OrderRowProps) {
  return (
    <tr className={active ? 'row row--active' : 'row'} onClick={() => onOpen(order.id)}>
      <td>{order.orderNo}</td>
      <td>{order.customerName}</td>
      <td>{formatAmount(order.totalAmount)}</td>
      <td><StatusTag status={order.status} /></td>
    </tr>
  )
})

export function OrderTable({ orders, activeId }: { orders: Order[]; activeId: string | null }) {
  // useMemo：1 万条的 filter + sort 是贵计算，只有依赖变化才重算
  const sortedOrders = useMemo(
    () => [...orders].sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
    [orders],
  )

  // useCallback：保证 onOpen 引用稳定，否则下面每行 memo 全部失效
  const handleOpen = useCallback((id: string) => {
    setActiveId(id) // 稳定的 setState 引用，依赖数组为空
  }, [])

  return (
    <table>
      <tbody>
        {sortedOrders.map((order) => (
          <OrderRow key={order.id} order={order} active={order.id === activeId} onOpen={handleOpen} />
        ))}
      </tbody>
    </table>
  )
}

判断准则一句话：memo 是「逃逸舱」不是「默认装备」。先问三个问题——渲染真的贵吗？props 真的少变吗？props 引用真的稳定吗？三问有两次「否」，就不要包。

13.4 结构性优化：状态下放与 children 组合

比 memo 更治本的是改结构，让高频变化的状态影响范围天然变小。

手段一：状态下放。搜索关键词每敲一个字变一次，但只有 FilterBar 需要它——那就把 state 移进 FilterBar，而不是放在列表页顶层：

// ❌ 状态放顶层：每敲一个字，整个列表页（含 1 万行）重渲染
export function OrderListViewV1() {
  const [keyword, setKeyword] = useState('')
  const debounced = useDebouncedValue(keyword, 300)
  const { data } = useQuery({ queryKey: ['orders', debounced], queryFn: fetchOrders })
  return (
    <>
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
      <OrderTable orders={data?.list ?? []} />
    </>
  )
}

// ✅ 状态下放：输入态只影响 FilterBar；防抖值经回调上抛后才触发列表更新
export function OrderListView() {
  const [query, setQuery] = useState('')
  const { data } = useQuery({ queryKey: ['orders', query], queryFn: () => fetchOrders(query) })
  return (
    <>
      <OrderFilters onSearch={setQuery} /> {/* keyword 的 state 在 OrderFilters 内部 */}
      <OrderTable orders={data?.list ?? []} />
    </>
  )
}

手段二：children 组合。如果一个组件自己有易变 state，又包着渲染很贵的 children，把 children 当 props 传进来——children 是父组件创建好的元素对象，内部 state 变化不会重新创建它：

function ScrollTracker({ children }: { children: ReactNode }) {
  const [scrollTop, setScrollTop] = useState(0)
  return (
    <div
      style={{ height: 600, overflow: 'auto' }}
      onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)}
    >
      <div className="scroll-hud">已滚动 {Math.round(scrollTop)}px</div>
      {/* scrollTop 变化只重渲染本组件；children 引用不变 → React 直接复用，不重渲染子树 */}
      {children}
    </div>
  )
}

// 使用方：OrderTable 是父组件里创建好的元素，滚动再频繁它也不重渲染
;<ScrollTracker>
  <OrderTable orders={orders} />
</ScrollTracker>

这就是官方文档说的「lifting content up」。对比 Vue：Vue 里靠 <KeepAlive> 或 v-once 这类机制缓存，React 里靠调整元素创建的位置，殊途同归。

13.5 key 重置组件状态

key 不只是列表 diff 的身份牌——key 变化会让 React 卸载旧实例、挂载新实例，状态随之归零。这是最干净的重置手段：

// 切换编辑的订单时，用 order.id 作为 key：表单内部所有 useState 自动回到初始值
function OrderEditEntry({ order }: { order: Order }) {
  return <OrderEditForm key={order.id} initialOrder={order} />
}

function OrderEditForm({ initialOrder }: { initialOrder: Order }) {
  const [items, setItems] = useState<OrderItem[]>(initialOrder.items)
  // 不需要 useEffect 监听 order.id 变化来「重置表单」——key 变化时本组件整体重建
  return <OrderItemsEditor items={items} onChange={setItems} />
}

典型场景：客户切换后清空明细行、Tab 切换后重置滚动位置、弹窗复用同一组件但要求每次打开是全新状态。比写「监听 props 变化再 setState」的 effect 更少、更不出错。

13.6 虚拟滚动：自研简化版 + TanStack Virtual

万级数据的终解是虚拟滚动：DOM 里只渲染可视区附近的几十行。原理三步：

1. 容器固定高度、内部撑一个总高度占位（count × itemHeight），撑出真实滚动条；
2. 监听滚动，算出可视区间 [startIndex, endIndex]，只渲染这段；
3. 渲染的行用 translateY(start) 定位到正确位置。

先自研一个固定行高的简化版，把原理焊进脑子：

interface VirtualItem { index: number; offsetTop: number }
interface UseVirtualListOptions { count: number; itemHeight: number; viewportHeight: number; overscan?: number }

export function useVirtualList({ count, itemHeight, viewportHeight, overscan = 5 }: UseVirtualListOptions) {
  const [scrollTop, setScrollTop] = useState(0)

  const start = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan)
  const visibleCount = Math.ceil(viewportHeight / itemHeight)
  const end = Math.min(count, start + visibleCount + overscan)

  const items: VirtualItem[] = []
  for (let i = start; i < end; i++) items.push({ index: i, offsetTop: i * itemHeight })

  return {
    items,
    totalHeight: count * itemHeight,
    onScroll: (e: React.UIEvent<HTMLDivElement>) => setScrollTop(e.currentTarget.scrollTop),
  }
}

export function OrderVirtualTable({ orders }: { orders: Order[] }) {
  const { items, totalHeight, onScroll } = useVirtualList({
    count: orders.length, itemHeight: 48, viewportHeight: 600,
  })
  return (
    <div style={{ height: 600, overflow: 'auto' }} onScroll={onScroll}>
      <div style={{ height: totalHeight, position: 'relative' }}>
        {items.map(({ index, offsetTop }) => (
          <div key={orders[index].id} style={{ position: 'absolute', top: offsetTop, height: 48, width: '100%' }}>
            <OrderRow order={orders[index]} active={false} onOpen={() => {}} />
          </div>
        ))}
      </div>
    </div>
  )
}

生产环境用 @tanstack/react-virtual（TanStack Virtual v3），支持动态行高、横向虚拟、网格等：

pnpm add @tanstack/react-virtual

import { useVirtualizer } from '@tanstack/react-virtual'
import { useRef } from 'react'

export function OrderVirtualTableV2({ orders }: { orders: Order[] }) {
  const scrollRef = useRef<HTMLDivElement>(null)

  const virtualizer = useVirtualizer({
    count: orders.length,               // 数据总量（可以远超 1 万）
    getScrollElement: () => scrollRef.current,
    estimateSize: () => 48,             // 行高估计值，动态行高时可传测量函数
    overscan: 8,                        // 上下各多渲染 8 行，滚动更顺滑
  })

  return (
    <div ref={scrollRef} style={{ height: 600, overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualRow) => {
          const order = orders[virtualRow.index]
          return (
            <div
              key={order.id} // 稳定业务 id，见「易错点 13-3」
              style={{
                position: 'absolute', top: 0, left: 0, width: '100%',
                height: virtualRow.size,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              <OrderRow order={order} active={false} onOpen={noop} />
            </div>
          )
        })}
      </div>
    </div>
  )
}

大表格优化清单（逐项自查，命中一条治一条）：

13.7 企业案例：万级订单列表卡顿治理

第 12 章交付的 OrderListView 在联调环境只有 30 条数据，直到灰度环境灌入 1 万条真实分布的订单 后，销售反馈：每敲一个字列表卡 300ms，滚动表格像幻灯片。Profiler 现场记录：

治理五步（每步可独立验收）：

1. 状态下放：keyword 移入 OrderFilters 内部 + 300ms 防抖，输入时列表页零渲染；
2. 虚拟滚动：全量渲染替换为 TanStack Virtual，DOM 行数从 10000 降到 ~30；
3. 行 memo 化：OrderRow 包 memo，回调引用用 useCallback 固定；
4. 预计算展示字段：后端返回后统一格式化 orderNoDate / amountText / statusLabel，行渲染只读字段；
5. CSS 收口：滚动容器加 contain: strict，行内去除每行渐变阴影。

结果（同一台中端安卓机、同一数据集）：

把这份对比表存进仓库 docs/perf/order-list-2026Q3.md——性能治理没有「完成」，只有「回归前」，记录就是下一次治理的起点。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：从第 12 章仓库检出 OrderListView，先用 React DevTools Profiler 录制「在搜索框输入 华东」的操作，记录重渲染最贵的 3 个组件及其耗时；然后给 OrderRow 加上 memo，并修复让它失效的引用问题（onOpen 回调）。

提示：Profiler 面板设置里打开「Record why each component rendered」；memo 失效不代表没包，可能是父组件每次传了新函数——顺着渲染原因找。

验收标准：再次录制同样操作，OrderRow 在「父组件重渲染但 props 未变」时不再出现在火焰图中；把前后两次 Profiler 截图存入 docs/perf/。

const OrderRow = memo(function OrderRow({ order, onOpen }: OrderRowProps) {
  return (
    <tr onClick={() => onOpen(order.id)}>
      <td>{order.orderNo}</td>
      <td>{order.customerName}</td>
      <td>{formatAmount(order.totalAmount)}</td>
    </tr>
  )
})

// 父组件中：回调引用必须稳定，否则 memo 形同虚设
export function OrderTable({ orders }: { orders: Order[] }) {
  const handleOpen = useCallback((id: string) => {
    openOrderDetail(id) // setState 或跳转，依赖稳定
  }, [])
  return <tbody>{orders.map((o) => <OrderRow key={o.id} order={o} onOpen={handleOpen} />)}</tbody>
}

练习 2 · 进阶（30–60 min）

任务描述：用「状态下放 + children 组合」重构 OrderListView：搜索关键词的 state 收进 OrderFilters 内部，防抖后通过 onSearch 上抛；再把 OrderTable 放进一个带滚动进度 HUD 的 ScrollTracker 组件中，验证 HUD 实时刷新时表格不重渲染。

提示：OrderFilters 内部自己 useDebouncedValue；ScrollTracker 接收 children: ReactNode；用 Profiler 的「why did it render」确认 OrderTable 的渲染原因是 Props changed（数据变了）而不是 Parent rendered。

验收标准：连续输入 10 个字符期间，Profiler 中 OrderTable 渲染次数 ≤ 2 次（防抖上抛）；滚动时 OrderTable 零渲染。

function OrderFilters({ onSearch }: { onSearch: (q: string) => void }) {
  const [keyword, setKeyword] = useState('') // 状态下放：高频态只属于过滤器
  const debounced = useDebouncedValue(keyword, 300)
  useEffect(() => { onSearch(debounced) }, [debounced, onSearch])
  return <SearchInput value={keyword} onChange={setKeyword} />
}

function ScrollTracker({ children }: { children: ReactNode }) {
  const [progress, setProgress] = useState(0)
  return (
    <div style={{ height: 600, overflow: 'auto' }}
         onScroll={(e) => setProgress(e.currentTarget.scrollTop / (e.currentTarget.scrollHeight - e.currentTarget.clientHeight))}>
      <div className="hud">阅读进度 {Math.round(progress * 100)}%</div>
      {children}
    </div>
  )
}

练习 3 · 挑战（选做，60+ min）

任务描述：给「轻订单」列表页接入虚拟滚动：先接入 TanStack Virtual 跑通 1 万条 mock 数据；挑战部分是给简化版 useVirtualList 增加动态行高支持（行高 40–64px 不定），并对比两者的滚动表现。

提示：固定行高时位置可算 index × h；动态行高的经典做法是「估计 + 事后校正」——先用 estimateSize 渲染，真实 DOM 挂载后 ResizeObserver 量出实际高度回写缓存，TanStack Virtual 内部就是这么做的。1 万条 mock 用 mock/db.js 的生成器循环放大，字段保持附录A 实体一致。

验收标准：1 万条数据滚动掉帧 < 5%（用 DevTools Performance 面板录 10 秒滚动验证）；快速滚到第 9000 条再回滚，行高不跳动（校正逻辑生效）；切换筛选后列表状态正确重置。

// 动态行高的最小可运行思路：估计 → 测量 → 回写
const rowHeights = useRef(new Map<number, number>()) // index -> 实测高度

const virtualizer = useVirtualizer({
  count: orders.length,
  getScrollElement: () => scrollRef.current,
  estimateSize: (i) => rowHeights.current.get(i) ?? 48, // 优先用实测值
  measureElement: (el) => el?.getBoundingClientRect().height ?? 48, // 挂载后测量
  overscan: 8,
})

// 行节点用 ref 挂给 virtualizer，交给它测量：
;<div key={order.id} data-index={virtualRow.index} ref={virtualizer.measureElement} style={{...}} />

⚠️ 常见易错点

易错点 1：在 render 中创建新对象/函数传给 memo 组件，优化全部失效

// ❌ 每次渲染都是新的 rowStyle 对象、新的 onOpen 函数
//    props 浅比较必然不同 → memo 的 OrderRow 每次都照常重渲染
<OrderRow order={order} style={{ height: 48 }} onOpen={(id) => openOrder(id)} />

// ✅ 引用稳定：对象用 useMemo，函数用 useCallback（或提升到模块层）
const rowStyle = useMemo<CSSProperties>(() => ({ height: 48 }), [])
const handleOpen = useCallback((id: string) => openOrder(id), [])
;<OrderRow order={order} style={rowStyle} onOpen={handleOpen} />

现象：明明包了 memo，Profiler 里它还是每帧都渲染。记住：memo 比较的是引用，不是值。

易错点 2：useEffect 里加监听不清理，监听器越积越多

// ❌ 组件卸载/依赖变化时旧的监听器没人摘
//    现象：页面来回切换后，一次 resize 触发 N 次回调，内存曲线只升不降
useEffect(() => {
  window.addEventListener('resize', recalcVirtualHeight)
}, [])

// ✅ 每次 effect 返回清理函数；依赖变化时 React 先执行旧清理再跑新 effect
useEffect(() => {
  window.addEventListener('resize', recalcVirtualHeight)
  return () => window.removeEventListener('resize', recalcVirtualHeight)
}, [])

在虚拟列表里这最隐蔽：滚动相关监听堆积后，「越滚越卡」常被误判成虚拟滚动本身不行。

易错点 3：虚拟列表用 index 当 key，DOM 复用与数据错位

// ❌ 筛选变化后 index 对应的数据完全不同，key 还是 0..n
//    行内如果有 checkbox / 展开态 / 输入框，状态会「串行」到错误的数据行上
{items.map((item, index) => <OrderRow key={index} order={orders[index]} />)}

// ✅ key 用稳定业务 id（订单号全局唯一），数据 ↔ DOM 复用关系永远正确
{items.map(({ index }) => <OrderRow key={orders[index].id} order={orders[index]} />)}

配合虚拟滚动时更危险：DOM 节点被大量复用，错误 key 的错位会从「偶现」变成「高频」。

易错点 4：Context value 每次渲染都新建，下游 memo 集体失效

// ❌ Provider value 是内联对象：每次 Provider 所在组件渲染，value 都是新引用
//    所有消费者重渲染，消费者内部包的 memo 全部白包
<OrderContext.Provider value={{ orders, onOpen }}>
  {children}
</OrderContext.Provider>

// ✅ value 用 useMemo 固定引用；或把 state 与 dispatch 拆成两个 Context 减少误伤
const value = useMemo(() => ({ orders, onOpen }), [orders, onOpen])
;<OrderContext.Provider value={value}>{children}</OrderContext.Provider>

易错点 5：useMemo/useCallback 依赖数组遗漏或撒谎，缓存了脏数据

// ❌ sortKey 变了但依赖里没有它 → 永远用旧排序，还以为 memo 「生效」了
const sorted = useMemo(() => [...orders].sort(comparator(sortKey)), [])

// ✅ 依赖如实声明；靠 eslint-plugin-react-hooks 的 exhaustive-deps 规则兜底，别手工豁免
const sorted = useMemo(() => [...orders].sort(comparator(sortKey)), [orders, sortKey])

缓存正确性的代价是「依赖必须诚实」。如果一段计算简单到不值得维护依赖，就别 memo——这也是它不能当默认装备的原因。

✅ 最佳实践

1. 先 Profiler 后动手：没有「渲染原因 + 耗时」证据的优化都是猜；优化前后的 Profiler 截图要归档（本章案例放 docs/perf/）。
2. 结构性优化优先于 memo：状态下放、children 组合、key 重置是零运行时成本的改造；memo 三件套留给「渲染贵 + props 少变」的组件。
3. 行组件必配稳定引用：任何 memo 化的列表行，它的回调 props 必须来自 useCallback/稳定 setState，对象 props 必须来自 useMemo。
4. 万级数据直接上虚拟滚动：不要用「分页 + 懒加载」硬扛交互型大列表；固定行高先跑通，动态行高交给 TanStack Virtual 测量机制。
5. 展示字段预计算：formatAmount、状态文案这类派生值在数据入库/入查询缓存时算好，别放在每行 render 里。
6. key 永远用业务稳定 id：列表 diff 与「key 重置状态」共用同一条纪律；index key 只允许在「纯展示、无内部状态、列表永不重排」三条件同时满足时使用。
7. 监听器必须成对出现：addEventListener 与移除写在同一个 effect 里，团队 lint 强制 react-hooks/exhaustive-deps。
8. 性能治理写成记录：指标（掉帧率、DOM 数、渲染耗时）+ 手段 + 截图三要素齐全，交给下一位接手人而不是烂在聊天记录里。

📌 本章小结

• React 重渲染的触发条件只有三类（自身 state、父渲染、Context value 变化），渲染阶段是纯计算、可中断，提交阶段才碰 DOM——「卡」先分清卡在哪一阶段。
• Profiler 先行：谁在重渲染、为什么、多久，三个答案齐了再动手。
• memo 三件套是逃逸舱不是默认装备，引用不稳定时它们是安慰剂；状态下放、children 组合、key 重置往往更治本。
• 万级列表的终解是虚拟滚动：自研版讲原理，TanStack Virtual 讲生产，key 用业务 id 防错位。
• 「轻订单」万级订单列表已从 300ms 输入卡顿治理到掉帧 3%，记录沉淀在 docs/perf/。

渲染变快了，但首屏还是慢——门户要 4 秒才能看到主视觉。下一章我们把矛头转向加载性能：代码分割、图片优化、核心指标测量，目标是把门户 LCP 从 4s 压到 1.8s（附录A 目标 ≤ 2.0s）。

📄 第 14 章 · 加载性能优化 14-加载性能优化.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：5–7 小时｜🔗 前置：第 06 章门户首页 + 第 07 章路由 + 第 13 章

⬅ 上一章：渲染性能优化 ｜ 📖 本版目录 ｜ ➡ 下一章：组件测试

💡 对照学习：本页是 React 版第 14 章，对应 Vue 版第 14 章 · 加载性能优化。概念映射：React.lazy + <Suspense> ≈ defineAsyncComponent + <Suspense>、骨架屏 fallback ≈ 同名机制、web-vitals / Lighthouse / preload / prefetch / gzip / brotli 与框架无关两版完全一致。唯一差异：Vite 对 React 与 Vue 的懒加载产物都是原生动态 import()，分包思路通用，只是入口组件写法不同。

🎯 学习目标

学完本章，你将能够：

1. 画出首屏加载瀑布图，把「首屏时间」拆解为传输字节、请求数、JS 执行、渲染路径四类开销，并对号入座选优化手段；
2. 用 React.lazy + <Suspense> 完成路由级与组件级代码分割，说清哪些组件不该懒加载；
3. 对首页图片实施懒加载、宽高占位、WebP/AVIF、响应式尺寸（srcset/sizes）四项优化；
4. 区分 preload / prefetch / dns-prefetch / modulepreload 的语义，并按用户动线落地关键资源预加载；
5. 说清 LCP / FCP / CLS / INP 的定义、达标线与测量方式，用 web-vitals 库采集并上报；
6. 用 Lighthouse 建立基线，配置性能预算（LCP ≤ 2.0s、首屏 gzip ≤ 300KB）并卡进 CI；
7. 实现路由级 + 组件级骨架屏，并完成「门户 LCP 4s → 1.8s」优化复盘，输出措施-收益对照表。

📖 核心知识点

14.1 全景图：首屏时间到底花在哪里

打开门户首页到用户「看到并可用」，时间花在四个地方：

DNS/TCP/TLS ──► HTML 下载解析 ──► CSS/JS 下载 ──► JS 执行 ──► 渲染 LCP
   网络层            文档层             传输层           运行层        渲染层

附录A §4 对「轻订单」门户的硬性目标：LCP ≤ 2.0s（4G 网络、中端安卓机）、JS 首屏 gzip ≤ 300KB。每层开销对应一类优化手段：

优化顺序：先用 Lighthouse 建基线 → 找最大头（通常是图片和首包 JS）→ 逐项治理 → 复测记录。没有基线的优化等于盲打。

14.2 代码分割：React.lazy + Suspense

Vite 打包时默认把所有代码打进一个 bundle。React.lazy 让你把「用户此刻不需要的页面」从首包里拆出去，变成按需加载的独立 chunk：

import { lazy, Suspense } from 'react'
import { createBrowserRouter } from 'react-router'

// 路由级懒加载：访问到才加载，且 Vite 会自动拆成独立 chunk
const HomeView = lazy(() => import('@/views/HomeView'))
const OrderListView = lazy(() => import('@/views/orders/OrderListView'))
const OrderDetailView = lazy(() => import('@/views/orders/OrderDetailView'))
const ReportView = lazy(() => import('@/views/reports/ReportView'))

export const router = createBrowserRouter([
  {
    path: '/',
    element: <AppLayout />, // 布局壳常驻，不懒加载
    children: [
      { index: true, element: <HomeView /> },
      { path: 'orders', element: <OrderListView /> },
      { path: 'orders/:id', element: <OrderDetailView /> },
      { path: 'reports', element: <ReportView /> },
    ],
  },
])

lazy 返回的组件必须挂在 <Suspense> 边界内，否则加载期间会向上抛起悬挂态。把边界放在布局的内容出口处：切换路由时只有内容区闪骨架，侧边栏与顶栏保持稳定：

import { Suspense } from 'react'
import { Outlet } from 'react-router'
import { AppSkeleton } from '@/components/AppSkeleton'

export function AppLayout() {
  return (
    <div className="app-shell">
      <SideMenu />
      <Header />
      {/* Suspense 边界就近包裹会悬挂的内容，而不是包住整个应用 */}
      <main>
        <Suspense fallback={<AppSkeleton />}>
          <Outlet />
        </Suspense>
      </main>
    </div>
  )
}

React Router 7 还提供路由对象上的 lazy 属性（配合 loader 的数据路由模式），可以实现「加载模块 + 拉数据」并行；本教程主讲组件式写法，两者可共存。细节见 https://reactrouter.com 。

不该懒加载的清单：登录鉴权逻辑、全局 Layout、首屏关键组件（门户 Hero 区）、体积很小的高频组件（拆出去反而多一次请求往返）。代码分割的收益 = 「非首屏代码量」，拆 5KB 的小页面纯属折腾。

14.3 图片优化：往往比 JS 更大的那座山

真实项目的首屏字节大头通常是图片。四件套依次上：

interface HeroImageProps { srcBase: string; alt: string }

export function HeroImage({ srcBase, alt }: HeroImageProps) {
  return (
    <img
      // 1. 现代格式优先，浏览器自选；fallback 到 jpg
      srcSet={`${srcBase}-480.avif 480w, ${srcBase}-768.avif 768w, ${srcBase}-1280.avif 1280w, ${srcBase}-1280.webp 1280w`}
      src={`${srcBase}-1280.jpg`}
      // 2. 响应式尺寸：让浏览器按视口宽度选最合适的文件
      sizes="(max-width: 768px) 100vw, 50vw"
      // 3. 显式宽高，预留布局空间，防 CLS
      width={1280}
      height={720}
      // 4. 首屏 LCP 图不懒加载（见易错点 14-4）；列表图才 loading="lazy"
      decoding="async"
      alt={alt}
    />
  )
}

// 非首屏图片：懒加载 + 占位
;<img src="/images/customer-cases/3.webp" loading="lazy" decoding="async" width={640} height={360} alt="客户案例" />

配合 CDN 参数按需裁剪（示例为通用约定，具体参数看所用 CDN 文档）：?w=768&format=avif&q=80。原则：给多大的显示区域，就传多大的图。

14.4 预加载：preload / prefetch / dns-prefetch / modulepreload

<!-- index.html：LCP 图提前加载，赢在起跑线 -->
<link rel="preload" as="image" href="/images/hero-1280.avif" fetchpriority="high" />
<link rel="preload" as="font" type="font/woff2" href="/fonts/InterVar.woff2" crossorigin />
<link rel="dns-prefetch" href="//cdn.qingorder.example.com" />

路由级 prefetch 在 React 里没有框架自动档（Next.js 的 <Link prefetch> 除外），常见做法是「悬停即预取」：

import { useEffect } from 'react'
import { Link } from 'react-router'

export function NavToReports() {
  useEffect(() => {
    // 用户动线：从门户进入报表的概率高，hover 200ms 后预取该 chunk
    const timer = window.setTimeout(() => import('@/views/reports/ReportView'), 200)
    return () => window.clearTimeout(timer)
  }, [])
  return <Link to="/reports">销售报表</Link>
}

服务端数据也可以配合 TanStack Query 预取（第 09 章 queryClient.prefetchQuery），chunk 与数据一起抢跑，进页面即可用。

14.5 核心指标与测量：LCP / FCP / CLS / INP

用官方 web-vitals 库采集，一次接入四个指标全拿：

pnpm add web-vitals

// src/monitor/vitals.ts
import { onCLS, onINP, onFCP, onLCP, onTTFB, type Metric } from 'web-vitals'

function reportMetric(metric: Metric) {
  // 开发期打表观察；生产期上报到监控（第 18 章），用 sendBeacon 保证页面卸载时不丢
  const body = JSON.stringify({
    name: metric.name,       // 'LCP' | 'CLS' | 'INP' | ...
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
    id: metric.id,           // 同一指标多次上报的关联 id
    page: location.pathname,
  })
  navigator.sendBeacon('/api/v1/metrics/vitals', body)
  if (import.meta.env.DEV) console.log(`[vitals] ${metric.name}`, metric.value)
}

export function initVitals() {
  onCLS(reportMetric)
  onINP(reportMetric)
  onFCP(reportMetric)
  onLCP(reportMetric)
  onTTFB(reportMetric)
}

注意：Lighthouse 是实验室数据（模拟环境、单次），web-vitals 是真实用户数据（RUM）。上线判断看 LCP p75（75 分位），上线前看实验室跑分，两者互补。

14.6 Lighthouse 与性能预算

基线测量：Chrome DevTools → Lighthouse 面板 → 选 Performance + Mobile + Slow 4G → Analyze。更重要的是把预算卡进 CI，防止优化成果被下一个迭代悄悄吃掉：

// budget.json —— 性能预算：超线即 CI 失败
[
  {
    "path": "/*",
    "timings": [
      { "metric": "largest-contentful-paint", "budget": 2000 },
      { "metric": "cumulative-layout-shift", "budget": 100 }
    ],
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "image", "budget": 600 }
    ]
  }
]

脚本体积预算可以先用最朴素的 Node 脚本卡住——首屏 gzip ≤ 300KB（附录A）：

// scripts/check-budget.ts —— 构建后运行：对 dist 里的 js 求 gzip 总量
import { readdirSync, readFileSync, statSync } from 'node:fs'
import { gzipSync } from 'node:zlib'
import { join } from 'node:path'

const BUDGET_KB = 300
const dist = 'dist/assets'
const total = readdirSync(dist)
  .filter((f) => f.endsWith('.js'))
  .reduce((sum, f) => sum + gzipSync(readFileSync(join(dist, f))).length, 0)
const totalKB = Math.round(total / 1024)
console.log(`首屏 JS gzip 合计：${totalKB}KB / 预算 ${BUDGET_KB}KB`)
if (totalKB > BUDGET_KB) {
  console.error('❌ 超出性能预算，禁止合并')
  process.exit(1)
}
console.log('✅ 性能预算通过')

// package.json scripts
{
  "scripts": {
    "build": "tsc -b && vite build",
    "check:budget": "tsx scripts/check-budget.ts && npx lhci autorun"
  }
}

Lighthouse CI（@lhci/cli）负责跑分与断言，budget.json 是它的预算格式；本地无头环境跑分有波动，CI 里固定机器规格与网络节流后数据才可比。

14.7 骨架屏、HTTP 缓存与压缩

骨架屏替代 spinner 的价值：提前给出布局形状，降低用户感知等待，且不引发布局跳变。路由级骨架（14.2 的 AppSkeleton）与组件级骨架可以复用同一套原语：

export function Skeleton({ width = '100%', height = 16 }: { width?: string; height?: number }) {
  return <div className="skeleton" style={{ width, height }} aria-hidden />
}

export function OrderListSkeleton() {
  return (
    <div role="status" aria-label="订单列表加载中">
      <Skeleton height={32} />
      {Array.from({ length: 8 }, (_, i) => (
        <Skeleton key={i} height={48} />
      ))}
    </div>
  )
}

HTTP 缓存策略一句话：带 hash 的资源永久缓存，HTML 永不缓存。Vite 产物自带内容 hash（如 OrderDetailView-Cj8x2b.js），服务器配置见第 18 章 Nginx 小节。

压缩：文本资源开 gzip（兼容性广）或 brotli（压缩率再高 15–20%，需 HTTPS）。Vite 侧可用 vite-plugin-compression 预生成 .gz/.br，或交给 Nginx 动态压缩（第 18 章配置）。

14.8 企业案例：门户 LCP 4s → 1.8s 优化复盘

第 06 章交付的门户首页，在中端安卓机 + Slow 4G 实验室环境下 LCP 是 4.1s，距离附录A 的 2.0s 目标差一倍。Lighthouse 定位的瀑布图显示三个大头：一张 2.4MB 的 Hero JPG、1.1MB 的单包 JS（含报表页的图表库）、阻塞渲染的字体。

最终实验室 LCP 1.8s（目标 ≤ 2.0s ✅）、首屏 JS gzip 286KB（≤ 300KB ✅）、CLS 0.03。复盘沉淀两条规矩：① 所有性能改动必须附 Lighthouse 前后对比，无数据不合并；② 预算进 CI（14.6），回归自动拦截。完整治理记录存 docs/perf/portal-lcp-2026Q3.md。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：给第 06 章门户项目的路由做代码分割：把 HomeView 之外的所有路由视图改为 React.lazy，配置好就近的 <Suspense> 边界，然后运行 pnpm build 观察 dist/assets 里的 chunk 划分。

提示：lazy() 包的是「默认导出」组件；先跑一次 pnpm build 记录 chunk 数量，改完再跑一次对比。检查 dist/index.html 是否变瘦。

验收标准：构建产物中出现每个路由视图的独立 chunk；pnpm dev 下打开 Network 面板，访问 /reports 时才请求报表页 chunk；首屏 HTML 不再引用非首屏 JS。

const HomeView = lazy(() => import('@/views/HomeView'))
const OrderListView = lazy(() => import('@/views/orders/OrderListView'))
const ReportView = lazy(() => import('@/views/reports/ReportView'))

;<Suspense fallback={<AppSkeleton />}>
  <Routes>
    <Route element={<AppLayout />}>
      <Route index element={<HomeView />} />
      <Route path="orders" element={<OrderListView />} />
      <Route path="reports" element={<ReportView />} />
    </Route>
  </Routes>
</Suspense>

练习 2 · 进阶（30–60 min）

任务描述：优化门户 LCP 元素（Hero 图）：换成 AVIF/WebP + srcset/sizes，加显式宽高与 preload，并在 main.tsx 接入 web-vitals 采集。用 Lighthouse 对比优化前后 LCP 与 CLS，把数据记进 docs/perf/。

提示：LCP 图不要 loading="lazy"；fetchpriority="high" 只给 LCP 图；sizes 按布局断点写。Lighthouse 用「移动端 + Slow 4G + 禁用缓存」跑，避免本地缓存干扰。

验收标准：优化后 Lighthouse 移动端 LCP 相比基线下降 ≥ 30%；CLS ≤ 0.1；控制台能看到四项 vitals 上报日志。

<!-- index.html -->
<link rel="preload" as="image" href="/images/hero-1280.avif" fetchpriority="high" />

// Hero.tsx —— 与 14.3 相同的四件套写法
;<img
  srcSet="/images/hero-480.avif 480w, /images/hero-1280.avif 1280w"
  src="/images/hero-1280.jpg"
  sizes="(max-width: 768px) 100vw, 50vw"
  width={1280} height={720}
  decoding="async"
  alt="轻订单 —— 让 B2B 订单不再漏单"
/>

// main.tsx 中
import { initVitals } from '@/monitor/vitals'
initVitals()

练习 3 · 挑战（选做，60+ min）

任务描述：把性能预算接入 CI：配置 Lighthouse CI 断言（LCP ≤ 2000ms、CLS ≤ 100、script 资源 ≤ 300KB）+ 14.6 的 gzip 体积检查脚本，接到第 18 章将要搭建的 GitHub Actions 里（本章先本地跑通 npx lhci autorun）。

提示：lhci autorun 需要 lighthouserc.json 声明 collect.staticDistDir 与 assert.assertions；本地跑分波动大，断言阈值建议比预算放宽 10% 容忍抖动，严格线留给 CI 固定环境。

验收标准：故意把一个大依赖（如 echarts）引回首屏入口，lhci 报红且退出码非 0；恢复后通过；两次运行的报告 JSON 存档对比。

{
  "ci": {
    "collect": { "staticDistDir": "./dist", "numberOfRuns": 3 },
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", { "maxNumericValue": 2200 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "resource-summary:script:size": ["error", { "maxNumericValue": 330000 }]
      }
    }
  }
}

pnpm build && npx lhci autorun

⚠️ 常见易错点

易错点 1：Suspense 边界设置不当，整页白屏/闪烁

// ❌ 边界包住整个应用：任何懒加载块在加载中，侧边栏顶栏一起消失
//    切路由时整页骨架闪烁，体验比 spinner 还差；lazy 抛错时也没有就近边界可兜
;<Suspense fallback={<AppSkeleton />}>
  <BrowserRouter>
    <AppLayout />
  </BrowserRouter>
</Suspense>

// ✅ 边界放在「会悬挂的最小子树」：布局常驻，只有内容区出骨架
export function AppLayout() {
  return (
    <div className="app-shell">
      <SideMenu />
      <main>
        <Suspense fallback={<AppSkeleton />}>
          <Outlet />
        </Suspense>
      </main>
    </div>
  )
}

配合第 18 章的 ErrorBoundary 一起用：Suspense 管「等」，ErrorBoundary 管「挂」。

易错点 2：图片不给宽高，页面加载时疯狂跳动（CLS 爆表）

// ❌ 浏览器不知道图多大：图片加载前后布局反复跳动，CLS 0.25
;<img src="/images/case-3.webp" alt="客户案例" />

// ✅ 显式宽高 + CSS 约束比例，加载前就占好位
;<img src="/images/case-3.webp" width={640} height={360}
      style={{ width: '100%', height: 'auto' }} alt="客户案例" />

现象是「读着读着文字突然被顶下去」——这在 Lighthouse 里直接扣分，在真实用户那里直接掉转化。

易错点 3：把 prefetch 当 preload 滥用，首屏被「预取」拖垮

// ❌ 把所有路由 chunk 都 preload：和不做代码分割一样，还多了排队开销
document.head.insertAdjacentHTML('beforeend',
  '<link rel="preload" as="script" href="/assets/ReportView-xxx.js">')

// ✅ preload 只给本页必用资源；下页资源交给 prefetch / 悬停预取，空闲时低优拉
;<link rel="prefetch" href="/assets/ReportView-xxx.js" as="script" />

区分口诀：preload 是「这一页就要」，prefetch 是「下一页可能要」。方向搞反，预加载就是预浪费。

易错点 4：给 LCP 图加 loading="lazy"，主指标自己优化死自己

// ❌ Hero 图懒加载：浏览器要等布局确定才加载，LCP 被自己推后几百毫秒
;<img src="/images/hero-1280.avif" loading="lazy" alt="主视觉" />

// ✅ LCP 图立即加载并提权；loading="lazy" 只用于视口外的列表图/配图
;<img src="/images/hero-1280.avif" fetchpriority="high" decoding="async"
      width={1280} height={720} alt="主视觉" />

优化前先弄清「当前页的 LCP 元素是谁」（Lighthouse 报告会标出来），针对它做减法，别的都要让路。

易错点 5：性能埋点用普通 XHR/fetch 上报，页面卸载时数据全丢

// ❌ 用户关页面瞬间，正在飞的 fetch 被取消——最关键的 LCP 恰恰在那时才完成采集
fetch('/api/v1/metrics/vitals', { method: 'POST', body: JSON.stringify(metric) })

// ✅ sendBeacon 专为「页面要关了也要送到」设计，浏览器保证排队发送
navigator.sendBeacon('/api/v1/metrics/vitals', JSON.stringify(metric))

监控数据的丢失规律很讽刺：丢的永远是最慢、最需要优化的那次访问。

✅ 最佳实践

1. 先基线后优化：Lighthouse（实验室）+ web-vitals（真实用户）双轨测量，任何优化改动都要附前后数据。
2. 代码分割按「路由 > 重型组件」两级做：路由级用 React.lazy；图表、编辑器等重型库在组件内部再 lazy 一层。
3. 首屏三件套纪律：LCP 图 preload + 提权、关键字体 swap、首包 gzip ≤ 300KB，三项写进团队验收标准。
4. 图片四件套默认值：现代格式、显式宽高、sizes 响应式、视口外 loading="lazy"——新组件不遵守不合并。
5. 预加载跟着用户动线走：数据驱动地挑「高概率下一跳」做 prefetch，宁缺毋滥。
6. 缓存策略一刀切：带 hash 资源 immutable 一年，index.html 用 no-cache，发版不靠玄学。
7. 预算进 CI：LCP / CLS / 包体积超线即红，性能回归和功能 bug 同级对待。
8. 骨架屏就近放置：Suspense fallback 表达「这块在加载」，而不是整页转圈；骨架形状要和真实内容一致，否则骨架本身在制造 CLS。

📌 本章小结

• 首屏时间 = 传输字节 + 请求数 + 执行时间 + 渲染路径，先测量定位大头再动手。
• React.lazy + <Suspense> 就近边界做路由级分割；重型库组件内再懒一层；布局壳和关键路径不懒。
• 图片是大多数门户的第一座山：AVIF/WebP、srcset、显式宽高、LCP 图 preload 是默认动作。
• preload（本页必用）与 prefetch（下页可能用）语义不能混；web-vitals 四指标 + Lighthouse 预算是防回归的闸门。
• 门户 LCP 已从 4.1s 治理到 1.8s（目标 2.0s ✅），措施-收益表沉淀在 docs/perf/portal-lcp-2026Q3.md。

加载快了、跑得也顺了——但你敢在没有测试的情况下发版吗？下一章进入质量保障：用 Vitest + Testing Library 为核心模块（订单金额计算、权限判断）建立覆盖率 ≥ 80% 的单元测试防线。

📄 第 15 章 · 组件测试 15-组件测试.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：6–8 小时｜🔗 前置：第 10 章表单 + 第 12 章实战 + 第 17 章 §17.1（TS 基线，可后置）

⬅ 上一章：加载性能优化 ｜ 📖 本版目录 ｜ ➡ 下一章：E2E 测试与质量保障

💡 对照学习：本页是 React 版第 15 章，对应 Vue 版第 15 章 · 组件测试。概念映射：Testing Library ≈ Vue Test Utils + @testing-library/vue、renderHook ≈ 测组合式函数的 withSetup 套路、Vitest / vi.mock / msw 两版完全同款。理念差异一句话：Vue Test Utils 允许你大量探组件实例内部（wrapper.vm），Testing Library 则拒绝访问内部实现，只认「用户看得见、摸得着」的 DOM——这也是本章反复强调的用户中心理念。

🎯 学习目标

学完本章，你将能够：

1. 画出前端测试金字塔（单元/集成/E2E），按「投入产出比」说出哪类代码值得测、哪类不值得；
2. 配置 Vitest 工程：jsdom 环境、setup 文件、路径别名、覆盖率阈值 ≥ 80%（附录A 目标）；
3. 为纯函数写单元测试，覆盖金额计算的浮点陷阱与边界值（数量 1–9999、折扣 0–100%）；
4. 用 renderHook + fake timers 测试自定义 Hook（防抖、请求竞态）；
5. 用 Testing Library 以「用户视角」写组件测试：getByRole 定位 + userEvent 交互；
6. 分清 vi.mock 与 msw 的分工，用 msw 隔离网络层并测出错误分支与竞态；
7. 克制地使用快照测试，说清何时快照是负资产；
8. 把「轻订单」核心模块（订单金额计算、权限判断、工具函数）的覆盖率提至 ≥ 80% 并接入覆盖率门禁。

📖 核心知识点

15.1 测试金字塔与投入策略

企业前端的测试投入应该长这样（越往上单条越贵、越慢、越少）：

        ╱  E2E 少量   ╲   关键链路冒烟（第 16 章）：登录→下单→审批→导出
       ╱  集成 中量     ╲  组件 + 交互 + 数据流：OrderCard、订单表单
      ╱  单元 大量       ╲ 纯函数与 Hook：金额计算、权限判断、formatAmount

值得测的（出 bug 贵、逻辑可枚举）：金额计算、权限判断、状态机流转、表单校验规则、工具函数。 不值得测的：纯样式类名、第三方库内部、useState 本身、一次性营销页。

「轻订单」附录A 的覆盖率目标只锁三个核心模块——订单金额计算、权限判断、工具函数 ≥ 80%。这是真实企业的做法：全局覆盖率是虚荣指标，核心模块覆盖率才是质量底线。

15.2 Vitest 配置：与 Vite 同源，零割裂

Vitest 直接复用项目的 Vite 配置（别名、插件全通），这是它在 Vite 项目里胜出的原因：

pnpm add -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom @vitest/coverage-v8

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import { fileURLToPath } from 'node:url'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
  },
  test: {
    environment: 'jsdom',              // 组件测试需要 DOM
    globals: true,                     // describe/it 可免导入直接用（仍推荐显式导入）
    setupFiles: ['./src/test/setup.ts'],
    css: false,                        // 不解析 CSS，加速
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html', 'lcov'],
      include: ['src/**'],
      // 入口文件与类型声明不参与统计，避免分母注水
      exclude: ['src/main.tsx', 'src/**/*.d.ts', 'src/test/**', 'src/**/index.ts'],
      // 附录A：核心模块覆盖率 ≥ 80%，直接做成门禁
      thresholds: { lines: 80, functions: 80, branches: 80, statements: 80 },
    },
  },
})

// src/test/setup.ts —— 每个测试文件运行前的公共准备
import '@testing-library/jest-dom/vitest' // toBeInTheDocument 等断言
import { cleanup } from '@testing-library/react'
import { afterEach } from 'vitest'

afterEach(() => {
  cleanup() // 卸载所有已渲染组件，测试间互不污染
})

// package.json scripts
{
  "scripts": {
    "test": "vitest",
    "test:ci": "vitest run --coverage"
  }
}

15.3 纯函数测试：从金额计算开始（浮点陷阱）

src/utils/money.ts 是「轻订单」的钱袋子——明细金额 = 数量 × 单价 × 行折扣，全程用分（附录A §5）：

// src/utils/money.ts
import type { OrderItem } from '@/types/order'

/** 计算单条明细行金额（单位：分）。行折扣 0–100，100 表示无折扣。 */
export function calcItemAmount(item: Pick<OrderItem, 'quantity' | 'unitPrice' | 'discountPercent'>): number {
  return Math.round((item.quantity * item.unitPrice * item.discountPercent) / 100)
}

/** 订单总额 = 明细行金额之和（单位：分） */
export function calcOrderTotal(items: Array<Pick<OrderItem, 'quantity' | 'unitPrice' | 'discountPercent'>>): number {
  return items.reduce((sum, item) => sum + calcItemAmount(item), 0)
}

/** 分 → 「¥1,234.56」展示字符串 */
export function formatAmount(fen: number): string {
  const yuan = (fen / 100).toFixed(2)
  return `¥${yuan.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}`
}

// src/utils/money.test.ts
import { describe, expect, it } from 'vitest'
import { calcItemAmount, calcOrderTotal, formatAmount } from './money'

describe('calcItemAmount（明细金额，单位分）', () => {
  it('常规计算：2 件 × 1250 分 × 80% 折扣 = 2000 分', () => {
    expect(calcItemAmount({ quantity: 2, unitPrice: 1250, discountPercent: 80 })).toBe(2000)
  })

  it('边界：数量最小 1、最大 9999（附录A 校验范围）', () => {
    expect(calcItemAmount({ quantity: 1, unitPrice: 100, discountPercent: 100 })).toBe(100)
    expect(calcItemAmount({ quantity: 9999, unitPrice: 100, discountPercent: 100 })).toBe(999900)
  })

  it('浮点陷阱：0.1 元 + 0.2 元 = 0.3 元，绝不能出 0.30000000000000004', () => {
    // 10 分 + 20 分 = 30 分；若在「元」域直接加浮点数就会翻车
    expect(calcOrderTotal([
      { quantity: 1, unitPrice: 10, discountPercent: 100 },
      { quantity: 1, unitPrice: 20, discountPercent: 100 },
    ])).toBe(30)
  })

  it('四舍五入：1 件 × 999 分 × 85% = 849.15 → 849 分（金额必须为整数分）', () => {
    expect(calcItemAmount({ quantity: 1, unitPrice: 999, discountPercent: 85 })).toBe(849)
  })
})

describe('formatAmount（分 → 展示）', () => {
  it('千分位与两位小数', () => {
    expect(formatAmount(1234567)).toBe('¥12,345.67')
  })
  it('0 分显示 ¥0.00 而不是空值', () => {
    expect(formatAmount(0)).toBe('¥0.00')
  })
})

纯函数测试的模板：输入 → 期望输出，重点喂边界值和历史上翻过车的用例（浮点求和就是「轻订单」真实翻过的车，见附录A §5 提示）。

15.4 Hook 测试：renderHook 与 fake timers

自定义 Hook 是逻辑复用的载体，renderHook（Testing Library 提供）让它在测试里「挂在隐形组件上」运行。以第 09 章的防抖 Hook 为例：

// src/hooks/useDebouncedValue.ts —— 被测对象
import { useEffect, useState } from 'react'

export function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value)
  useEffect(() => {
    const timer = window.setTimeout(() => setDebounced(value), delay)
    return () => window.clearTimeout(timer)
  }, [value, delay])
  return debounced
}

// src/hooks/useDebouncedValue.test.ts
import { act, renderHook } from '@testing-library/react'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { useDebouncedValue } from './useDebouncedValue'

beforeEach(() => vi.useFakeTimers())   // 用假时钟，测试瞬时完成
afterEach(() => vi.useRealTimers())

describe('useDebouncedValue', () => {
  it('300ms 内连续输入只有最后一次生效', async () => {
    const { result, rerender } = renderHook(({ v }) => useDebouncedValue(v, 300), {
      initialProps: { v: '' },
    })

    rerender({ v: '华' })
    act(() => vi.advanceTimersByTime(100))
    rerender({ v: '华东' })
    act(() => vi.advanceTimersByTime(200)) // 距上次变更仅 200ms，未到 300ms

    expect(result.current).toBe('')        // 仍在防抖窗口内

    act(() => vi.advanceTimersByTime(300))
    expect(result.current).toBe('华东')     // 防抖到期，取最后值
  })
})

要点：fake timers 让 300ms 的等待在 0ms 内完成；rerender 模拟 props 变化；result.current 永远读最新返回值。

15.5 组件测试：Testing Library 的用户中心理念

Testing Library 的核心信条只有一句：测试应该像用户一样使用组件——用户不关心你的 useState 叫什么，用户只关心「我看到什么、点什么、结果是什么」。推论：

1. 查询用 getByRole 优先（它走可访问性语义，顺带逼你写好 a11y），getByLabelText 次之，getByText 谨慎用；
2. 交互用 userEvent（模拟完整事件序列：焦点、按键、输入），而不是 fireEvent（只派发单个事件）；
3. 禁止通过 props 或实例内部状态断言，只看渲染结果。

被测组件（第 03/12 章的 OrderCard 与 StatusTag）：

// src/components/StatusTag.tsx
import { Tag } from 'antd'
import { ORDER_STATUS } from '@/constants/orderStatus'
import type { OrderStatus } from '@/types/order'

export function StatusTag({ status }: { status: OrderStatus }) {
  const meta = ORDER_STATUS[status]
  return <Tag color={meta.color}>{meta.label}</Tag>
}

// src/components/OrderCard.tsx
import { memo } from 'react'
import { formatAmount } from '@/utils/money'
import { StatusTag } from './StatusTag'
import type { Order } from '@/types/order'

export interface OrderCardProps {
  order: Order
  onOpen: (id: string) => void
}

export const OrderCard = memo(function OrderCard({ order, onOpen }: OrderCardProps) {
  return (
    <article aria-label={`订单 ${order.orderNo}`}>
      <header>
        <span>{order.orderNo}</span>
        <StatusTag status={order.status} />
      </header>
      <p>{order.customerName} · {formatAmount(order.totalAmount)}</p>
      <button type="button" onClick={() => onOpen(order.id)}>查看详情</button>
    </article>
  )
})

// src/components/OrderCard.test.tsx
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { describe, expect, it, vi } from 'vitest'
import { OrderCard } from './OrderCard'
import { makeOrder } from '@/test/factories'

describe('OrderCard', () => {
  it('渲染订单号、客户名与格式化金额', () => {
    const order = makeOrder({ orderNo: 'QO20260929000001', customerName: '青云硬件华东代理', totalAmount: 1234567 })
    render(<OrderCard order={order} onOpen={vi.fn()} />)

    expect(screen.getByRole('article', { name: '订单 QO20260929000001' })).toBeVisible()
    expect(screen.getByText('青云硬件华东代理')).toBeInTheDocument()
    expect(screen.getByText('¥12,345.67')).toBeInTheDocument()          // 分 → 元展示正确
    expect(screen.getByText('待审核')).toBeInTheDocument()               // StatusTag 文案
  })

  it('点击「查看详情」时以订单 id 触发 onOpen', async () => {
    const user = userEvent.setup()
    const onOpen = vi.fn()
    const order = makeOrder({ id: 'ord_001' })
    render(<OrderCard order={order} onOpen={onOpen} />)

    await user.click(screen.getByRole('button', { name: '查看详情' }))

    expect(onOpen).toHaveBeenCalledExactlyOnceWith('ord_001')
  })
})

// src/test/factories.ts —— 测试数据工厂：默认合法 + 按需覆盖，避免每个用例手搓 20 个字段
import type { Order } from '@/types/order'
export function makeOrder(overrides: Partial<Order> = {}): Order {
  return {
    id: 'ord_test_1',
    orderNo: 'QO20260929000001',
    customerId: 'cus_001',
    customerName: '青云科技测试客户',
    ownerName: '测试销售',
    status: 'pending_review',
    items: [{ skuId: 'sku_001', skuName: '智能网关 X1', quantity: 2, unitPrice: 1250, discountPercent: 100 }],
    wholeDiscountPercent: 100,
    totalAmount: 2500,
    createdAt: '2026-09-29T10:00:00Z',
    ...overrides,
  }
}

上面工厂里的 @/types/order 即附录A §5 的 Order 实体——两版教程共用同一数据形状，测试用例可以直接逐行对照 Vue 版。

15.6 异步与 Mock：vi.mock 与 msw 的分工

两者解决的问题不同，不是二选一：

msw（Mock Service Worker）在 jsdom 里拦截 fetch，请求路径、参数、状态码都是真的：

// src/test/handlers.ts
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/v1/orders', ({ request }) => {
    const keyword = new URL(request.url).searchParams.get('keyword') ?? ''
    return HttpResponse.json({
      code: 0, message: 'ok',
      data: { list: [{ id: 'ord_1', orderNo: 'QO20260929000001', customerName: `客户-${keyword}` }],
              total: 1, page: 1, pageSize: 20 },
    })
  }),
]

// src/test/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

export const server = setupServer(...handlers)

// src/hooks/useOrderList.test.ts —— 测「订单列表 Hook」的错误分支与竞态
import { renderHook, waitFor } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { http, HttpResponse } from 'msw'
import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'
import { server } from '@/test/server'
import { useOrderList } from './useOrderList'
import type { ReactNode } from 'react'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers()) // 每个用例后恢复默认 handlers
afterAll(() => server.close())

function createWrapper() {
  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
  return ({ children }: { children: ReactNode }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  )
}

describe('useOrderList', () => {
  it('接口失败时暴露 error 而不是静默白屏', async () => {
    server.use(http.get('/api/v1/orders', () =>
      HttpResponse.json({ code: 50001, message: '服务开小差了' }, { status: 500 })))

    const { result } = renderHook(() => useOrderList({ keyword: '', page: 1 }), { wrapper: createWrapper() })
    await waitFor(() => expect(result.current.isError).toBe(true))
  })

  it('快速连续翻页时以最后一次请求为准（竞态）', async () => {
    const { result, rerender } = renderHook(({ page }) => useOrderList({ keyword: '', page }), {
      initialProps: { page: 1 }, wrapper: createWrapper(),
    })
    rerender({ page: 2 })
    await waitFor(() => expect(result.current.data?.page).toBe(2))
  })
})

vi.mock 的典型用法（隔离副作用模块）：

// 路由跳转不便在单测中发生，mock 掉 react-router 的导航
import { vi } from 'vitest'
vi.mock('react-router', async (importOriginal) => ({
  ...(await importOriginal<typeof import('react-router')>()), // 保留其余导出
  useNavigate: () => vi.fn(), // 只有 useNavigate 换成空函数
}))

15.7 快照测试的克制使用与可维护的测试结构

快照（toMatchSnapshot / toEqual）是「把当前输出整个存下来，以后对比」。它只适合：纯展示型、结构稳定的小组件（如 StatusTag 的 7 个状态文案表）。它不适合：任何包含时间戳、随机 id、频繁迭代 UI 的组件——你会养成「红了就 -u 更新快照」的坏习惯，测试从此形同虚设。

可维护的测试结构遵循 AAA（Arrange-Act-Assert）+ 工厂函数 + 每个 it 只验证一件事：

it('折扣超过 10% 时展示「需财务审批」提示', async () => {
  // Arrange：工厂造数 + 渲染
  const order = makeOrder({ wholeDiscountPercent: 88 })
  render(<OrderCard order={order} onOpen={vi.fn()} />)
  // Act：（交互类用例在这里 user.click(...)）
  // Assert：只断言这一件事
  expect(screen.getByText('需财务审批')).toBeInTheDocument()
})

15.8 覆盖率与门禁

pnpm test:ci

File            % Stmts  % Branch  % Funcs  % Lines
utils/money.ts     100       90      100      100   ← 核心，必须满分或接近
utils/auth.ts       85       78       88       85   ← 权限判断
hooks/useOrderList  82       75       80       82
All files           84       79       83       84   ✅ ≥ 80 门禁通过

三条解读纪律：① 看分支覆盖率（% Branch）比行覆盖率更诚实，if 没走到 false 分支行数照样算「覆盖」；② 覆盖率 80% 是底线不是目标——为凑数给 getter 写断言是负资产；③ 修 bug 前先写一个「能复现 bug 的失败测试」，修完转绿，测试即回归保险。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：为本章 money.ts 补一个 calcOrderTotal 的测试组：空明细返回 0、多明细求和正确、单条折扣 0% 时金额为 0。然后故意把 calcItemAmount 改错（去掉 Math.round），验证测试能拦住。

提示：折扣 0% 是附录A 允许的边界（0–100）；「改错验证测试会红」是检验测试有效性的经典手法（变异测试的思想）。

验收标准：pnpm test 全绿；临时注入的 bug 使测试变红，还原后恢复绿。

describe('calcOrderTotal（订单总额）', () => {
  it('空明细返回 0 分', () => {
    expect(calcOrderTotal([])).toBe(0)
  })
  it('多明细求和：各行金额相加', () => {
    expect(calcOrderTotal([
      { quantity: 2, unitPrice: 1250, discountPercent: 80 },
      { quantity: 1, unitPrice: 500,  discountPercent: 100 },
    ])).toBe(2500)
  })
  it('行折扣 0% 时该行金额为 0（边界合法性）', () => {
    expect(calcItemAmount({ quantity: 5, unitPrice: 1000, discountPercent: 0 })).toBe(0)
  })
})

练习 2 · 进阶（30–60 min）

任务描述：为第 10 章的「新建订单表单」写组件测试：① 必填项（客户、明细行）为空时提交展示校验错误；② 数量填 0 或 10000 时展示「数量 1–9999」错误；③ 全部合法时提交按钮触发 onSubmit 且载荷里金额汇总正确。

提示：React Hook Form + Zod 的校验是异步的，断言错误文案要 await user.click(...) 后用 findByText；提交载荷用 vi.fn() 接住后检查 calls[0][0]。

验收标准：三个用例覆盖「阻塞提交 + 错误文案 + 成功载荷」三条路径；不访问任何组件内部状态，断言全部面向用户可见文本。

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { describe, expect, it, vi } from 'vitest'
import { OrderForm } from './OrderForm'

async function fillValidForm(user: ReturnType<typeof userEvent.setup>) {
  await user.type(screen.getByLabelText('客户'), '青云华东代理')
  await user.type(screen.getByLabelText('商品'), '智能网关 X1')
  await user.type(screen.getByLabelText('数量'), '2')
}

describe('OrderForm（新建订单）', () => {
  it('数量 0 触发「数量 1–9999」校验且不提交', async () => {
    const user = userEvent.setup()
    const onSubmit = vi.fn()
    render(<OrderForm onSubmit={onSubmit} />)

    await fillValidForm(user)
    const qty = screen.getByLabelText('数量')
    await user.clear(qty)
    await user.type(qty, '0')
    await user.click(screen.getByRole('button', { name: '提交订单' }))

    expect(await screen.findByText('数量 1–9999')).toBeInTheDocument()
    expect(onSubmit).not.toHaveBeenCalled()
  })

  it('合法表单提交时载荷金额汇总正确（2 × 1250 分）', async () => {
    const user = userEvent.setup()
    const onSubmit = vi.fn()
    render(<OrderForm onSubmit={onSubmit} />)

    await fillValidForm(user)
    await user.click(screen.getByRole('button', { name: '提交订单' }))

    expect(onSubmit).toHaveBeenCalledExactlyOnceWith(
      expect.objectContaining({ items: [expect.objectContaining({ quantity: 2, unitPrice: 1250 })] }),
    )
  })
})

练习 3 · 挑战（选做，60+ min）

任务描述：为权限判断模块建立测试防线：hasPermission(role, action)（附录A §2：折扣审批仅 finance、删除订单仅 super_admin/operator、销售仅本人订单）。要求：全部角色 × 全部动作的决策表测试 + usePermission Hook 的组件级测试（<Auth need="order:review"> 的可见性）+ 把核心模块覆盖率门禁设为 80% 并让 test:ci 真实拦截。

提示：决策表用 it.each 生成最紧凑；Hook 测试用 renderHook；门禁即 15.2 配置里的 thresholds——先故意写一个低覆盖模块让 CI 红，再补齐。

验收标准：it.each 决策表 ≥ 20 行覆盖四角色三动作；<Auth> 在「有权限渲染子节点 / 无权限渲染 fallback 或 null」两个分支都有断言；vitest run --coverage 退出码能真实反映门禁结果。

import { describe, expect, it } from 'vitest'
import { hasPermission } from './auth'

const cases: Array<[role: string, action: string, expected: boolean]> = [
  // [角色, 动作, 期望] —— 附录A §2 三级权限模型
  ['sales', 'order:review', false],      // 折扣审批仅 finance
  ['finance', 'order:review', true],
  ['operator', 'order:review', false],
  ['super_admin', 'order:review', true],
  ['sales', 'order:delete', false],      // 删除仅超管/运营
  ['operator', 'order:delete', true],
  ['super_admin', 'order:delete', true],
  ['finance', 'order:delete', false],
  ['sales', 'order:create', true],       // 销售可建单（仅本人名下，归属由后端校验）
  ['finance', 'order:create', false],
  ['finance', 'report:export', true],    // 导出报表仅财务
  ['operator', 'report:export', false],
  // ……继续补齐至四角色 × 全动作，见练习要求
]

describe('hasPermission 决策表', () => {
  it.each(cases)('%s 执行 %s 应为 %s', (role, action, expected) => {
    expect(hasPermission(role, action)).toBe(expected)
  })
})

⚠️ 常见易错点

易错点 1：getByText 脆弱断言，文案一改测试全崩

// ❌ 文案是设计最常改的东西；「提交」两个字还可能同时匹配按钮和提示语（multiple elements 报错）
expect(screen.getByText('提交')).toBeInTheDocument()

// ✅ 按「角色 + 可访问名称」定位，稳定且顺带保障 a11y；真有歧义再用 data-testid 兜底
expect(screen.getByRole('button', { name: '提交订单' })).toBeInTheDocument()

现象：改个错别字，二十个测试文件一起红。定位器选择的优先级记住口诀：Role > Label > Text > TestId。

易错点 2：异步更新没等，断言在「过去」执行

// ❌ 点击后校验/请求是异步的，同步的 getBy 在 DOM 更新前就查了 → 偶发红
user.click(screen.getByRole('button', { name: '提交订单' }))
expect(screen.getByText('请选择客户')).toBeInTheDocument()

// ✅ userEvent 加 await；异步出现的元素用 findBy* 或 waitFor
await user.click(screen.getByRole('button', { name: '提交订单' }))
expect(await screen.findByText('请选择客户')).toBeInTheDocument()

典型症状是「单跑绿、全跑红」或「CI 红、本地绿」——都是时序问题。

易错点 3：真时钟测防抖/超时，测试又慢又偶发失败

// ❌ 真等 300ms：网络抖一下 CI 就红；一个套件里 50 个防抖用例就是 15 秒
await new Promise((r) => setTimeout(r, 350))
expect(result.current).toBe('华东')

// ✅ fake timers 手动推时钟：零等待、零抖动、还能精确测「窗口内未生效」
vi.useFakeTimers()
act(() => { vi.advanceTimersByTime(300) })
expect(result.current).toBe('华东')
// 用完记得 vi.useRealTimers()（放 afterEach），否则污染后续用例

易错点 4：mock 无限扩散，测试之间互相污染

// ❌ 在 describe 顶层 mock + 改实现，却没有恢复；下一个文件/用例拿到的是被污染的模块
vi.spyOn(console, 'error').mockImplementation(() => {})
// ……整个文件不再恢复，别的测试里 console.error 也静默了

// ✅ msw 用 resetHandlers，spy 用 mockRestore，fake timers 用 useRealTimers
//    统一收口在生命周期钩子里，谁污染谁恢复
afterEach(() => {
  server.resetHandlers()
  vi.restoreAllMocks()
})

判断标准：任何一个测试单独跑和和别人一起跑结果必须一致，否则就是泄漏。

易错点 5：快照里混入波动字段，快照永远在「更新」

// ❌ 快照包含时间戳/随机 id：每次跑都不同 → 习惯性 -u 更新 → 快照测试报废
const { container } = render(<OrderCard order={makeOrder()} />)
expect(container.firstChild).toMatchSnapshot() // makeOrder 里 new Date() / crypto.randomUUID()

// ✅ 工厂固定波动字段；或者干脆不用快照，改成对关键文本的行为断言
export function makeOrder(overrides: Partial<Order> = {}): Order {
  return { createdAt: '2026-09-29T10:00:00Z', id: 'ord_fixed_1', /* … */ ...overrides }
}

快照审批的铁律：diff 里出现日期/uuid，先修数据再修快照；如果一份快照三个月没被认真看过，删掉它。

✅ 最佳实践

1. 测试即需求说明书：测试名写成句子（「折扣超过 10% 时展示需财务审批提示」），业务同学也能读懂。
2. 核心模块先测：金额计算、权限判断、状态机这三个「出事就赔钱」的模块优先补测试并钉住 80% 门禁。
3. 行为断言替代实现断言：永远问「用户会看到什么」，不问「state 变了吗」——这类测试在重构后依然全绿。
4. msw 管 HTTP，vi.mock 管模块：网络交互用真实语义（路径/参数/状态码），副作用模块才 mock，不混用。
5. 数据工厂替代手搓夹具：makeOrder() 默认合法 + 按需覆盖，新增字段不用改二十个测试文件。
6. fake timers + restore 收口：所有「改变全局状态」的 mock（时钟、监听、spy）统一在 afterEach 恢复。
7. 快照只给稳定展示组件：动态内容、频繁迭代 UI 一律行为断言。
8. 红灯先于修复：修 bug 前先写复现测试，保证每个 bug 至少换回一条回归保险。

📌 本章小结

• 测试金字塔：单元大量、集成中量、E2E 少量；核心模块（金额/权限/工具）≥ 80% 是附录A 的硬目标，已做成 Vitest 门禁。
• Testing Library 用户中心三原则：Role 定位、userEvent 交互、只断言用户可见结果。
• renderHook + fake timers 测 Hook 又快又稳；msw 在网络层给真实语义，vi.mock 只负责副作用模块。
• 快照是双刃剑：只给稳定展示组件用，diff 出波动字段先修数据。
• 「轻订单」money.ts、hasPermission、OrderCard、OrderForm 的测试防线已就位，pnpm test:ci 就是质量闸门。

单元与集成防线建好了，但「登录 → 下单 → 审批 → 导出」这条完整链路还没有任何自动化验证。下一章用 Playwright 把这条冒烟链路变成每天在 CI 里自动奔跑的 E2E 用例。

📄 第 16 章 · E2E 测试与质量保障 16-E2E测试与质量保障.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：6–8 小时｜🔗 前置：第 12 章实战 + 第 15 章组件测试

⬅ 上一章：组件测试 ｜ 📖 本版目录 ｜ ➡ 下一章：工程化实践 · TypeScript 与 Vite

💡 对照学习：本页是 React 版第 16 章，对应 Vue 版第 16 章 · E2E 测试与质量保障。Playwright 与框架无关——配置、定位器、storageState、trace、flaky 治理、CI 接入两版逐字通用，练习任务也一致（附录A 冒烟集：登录 → 下单 → 审批 → 导出）。唯一差异是「被测应用」：React 版跑的是第 12 章的 React 实现，用例里的业务断言（状态机、权限、金额）与框架无关。

🎯 学习目标

学完本章，你将能够：

1. 说明 E2E 在质量体系中的位置，按「冒烟集 vs 全量回归」两级制定 E2E 覆盖策略；
2. 搭建 Playwright 工程：webServer 自动拉起应用、多浏览器 projects、产物目录规范；
3. 按「用户可见性」选择定位器（getByRole/getByLabel 优先），避免脆弱的 CSS/XPath 选择器；
4. 用 storageState 复用登录态，把每条用例的登录开销降到零，同时保留一条「真登录」链路验证；
5. 用 API 造数准备测试数据并实现用例间隔离（唯一后缀 + 清理钩子）；
6. 开启 trace / 截图 / 视频，在 HTML 报告中还原失败现场，并说清 flaky 的四大来源与治理手段；
7. 把 E2E 接入 CI：PR 跑冒烟集、主干跑全量，失败自动上传报告工件；
8. 完成「轻订单」下单主流程 E2E：登录 → 下单 → 审批 → 导出全链路通过（附录A 冒烟集目标）。

📖 核心知识点

16.1 E2E 在质量体系中的位置

第 15 章的单元/集成测试验证「零件正确」，E2E 验证「整车能跑」——真实浏览器、真实路由、真实登录态、真实接口（或高保真 mock）。它的特点是贵（慢、环境依赖重、易 flaky），所以覆盖策略必须分层：

原则一句话：冒烟集答「敢不敢发版」，全量答「质量水位如何」。把 80 条全量塞进 PR 流水线是新人最常犯的错误——PR 要 40 分钟，最后大家学会绕过 CI。

16.2 安装与配置

pnpm add -D @playwright/test
pnpm exec playwright install chromium   # 按需装浏览器；CI 装系统依赖加 --with-deps

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'

const AUTH_FILE = 'playwright/.auth/operator.json'
const BASE_URL = process.env.E2E_BASE_URL ?? 'http://localhost:5173'

export default defineConfig({
  testDir: './e2e',
  timeout: 30_000,
  expect: { timeout: 5_000 },
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,          // 只在 CI 重试，本地失败直接暴露
  workers: process.env.CI ? 2 : undefined,  // CI 并发收敛，减少环境抖动
  reporter: process.env.CI ? [['html', { open: 'never' }], ['github']] : [['html', { open: 'never' }]],

  use: {
    baseURL: BASE_URL,
    trace: 'on-first-retry',        // 第一次重试才录制 trace（失败现场还原）
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  projects: [
    // 项目 0：登录态准备，只跑 auth.setup.ts
    { name: 'setup', testMatch: /auth\.setup\.ts/ },
    // 项目 1+：复用登录态跑业务用例，依赖 setup 先完成
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], storageState: AUTH_FILE },
      dependencies: ['setup'],
    },
    // 附录A 兼容目标：Chrome/Edge 最近两个大版本 —— 本地加 webkit/firefox 抽查即可
  ],

  // CI 里自动拉起被测应用；本地若已启动则直接复用
  webServer: {
    command: 'pnpm dev --port 5173',
    url: BASE_URL,
    reuseExistingServer: !process.env.CI,
  },
})

16.3 定位器策略：面向用户可见性

Playwright 的定位器哲学与第 15 章 Testing Library 完全同源：像用户一样找元素。优先级：getByRole > getByLabel > getByPlaceholder/getByText > getByTestId，CSS/XPath 只做最后手段。

// ✅ 推荐写法：语义定位 + 用户可读的名称
await page.getByRole('link', { name: '订单管理' }).click()
await page.getByLabel('客户名称').fill('青云华东代理')
await page.getByRole('button', { name: '提交订单' }).click()
await expect(page.getByRole('cell', { name: 'QO20260929000001' })).toBeVisible()

// 无原生 role 可用的自定义组件，才用 data-testid 兜底（写进团队规范）
await page.getByTestId('order-status-filter').click()

三个内建机制让断言更稳：自动等待（定位器在动作前自动等元素可见可用，不需要手写 sleep）、严格模式（定位器匹配到多个元素直接报错，逼你写精确）、Web 优先断言（expect(locator).toBeVisible() 会自动重试到超时）。

16.4 登录态复用：storageState

每条用例都走一遍登录页又慢又增加失败面。标准做法是「setup 项目登录一次 → 存 storageState → 业务项目全量复用」：

// e2e/auth.setup.ts
import { expect, test as setup } from '@playwright/test'

const authFile = 'playwright/.auth/operator.json'

setup('以运营角色登录', async ({ page }) => {
  await page.goto('/login')
  await page.getByLabel('邮箱').fill('operator@qingorder.example.com') // 教学虚构账号
  await page.getByLabel('密码').fill('demo-password-123')
  await page.getByRole('button', { name: '登录' }).click()
  await expect(page).toHaveURL(/\/dashboard/)   // 确认真的登录成功才落盘
  await page.context().storageState({ path: authFile })
})

# .gitignore —— 登录态是环境产物，不入库
playwright/.auth/

角色不止一个时按角色建多个 setup 项目（operator.json / finance.json），业务用例用 test.use({ storageState: 'playwright/.auth/finance.json' }) 切换。注意：冒烟集里要保留一条从登录页开始的真实登录用例——storageState 复用得再好，也不能让登录功能本身失去 E2E 验证。

16.5 测试数据准备与隔离

E2E 最隐蔽的坑是用例间共享数据：并行 worker 同时操作「同一张测试订单」，结果互相踩。纪律两条：

1. 用例数据自造自用：通过 API 造数（request fixture 直接调后端），数据带唯一后缀，不用别人造的数；
2. afterEach 清理：造了什么删什么，数据库不随用例数量无限膨胀。

// e2e/helpers/api.ts —— API 造数封装：走真实接口，语义与前端一致
import type { APIRequestContext, Page } from '@playwright/test'
import { expect } from '@playwright/test'

export async function login(request: APIRequestContext): Promise<string> {
  const res = await request.post('/api/v1/auth/login', {
    data: { email: 'operator@qingorder.example.com', password: 'demo-password-123' },
  })
  expect(res.ok()).toBeTruthy()
  const body = await res.json()
  return body.data.accessToken
}

export async function createOrder(request: APIRequestContext, token: string, customerName: string) {
  const res = await request.post('/api/v1/orders', {
    headers: { Authorization: `Bearer ${token}` },
    data: {
      customerId: 'cus_e2e_001',
      customerName,
      items: [{ skuId: 'sku_001', skuName: '智能网关 X1', quantity: 2, unitPrice: 1250, discountPercent: 100 }],
      wholeDiscountPercent: 100,
    },
  })
  expect(res.ok()).toBeTruthy()
  return (await res.json()).data as { id: string; orderNo: string }
}

// e2e/order-crud.spec.ts —— 每条用例独立造数，天然支持并行
import { test, expect } from '@playwright/test'
import { login, createOrder } from './helpers/api'

test.afterEach(async ({ request }) => {
  // 清理本用例造的数据（按唯一前缀删），保证环境可重复
  await request.post('/api/v1/test/cleanup', { data: { prefix: 'E2E-' } })
})

test('订单列表能按客户名筛选到 API 造的订单', async ({ page, request }) => {
  const token = await login(request)
  const marker = `E2E-${Date.now()}-华东代理`
  const { orderNo } = await createOrder(request, token, marker)

  await page.goto('/orders')
  await page.getByLabel('关键词').fill(marker)
  await expect(page.getByRole('cell', { name: orderNo })).toBeVisible()
})

连不上真实后端的环境（本地/PR），用 page.route 拦截关键接口返回 mock 数据——第 12 章 mock 服务的响应形状与附录A 完全一致，可以平移。

16.6 trace / 截图 / 视频：失败现场还原

E2E 失败在「别人电脑上」是常态，报告要能自证现场。三件产物的分工：

• trace（首选）：一整条时间线——每步操作前后的 DOM 快照、网络请求、console。失败用例在 HTML 报告里点开就能「回放」，本地查看 pnpm exec playwright show-trace trace.zip；
• screenshot：失败瞬间一帧，快速人肉判断「页面长什么样」；
• video：完整过程录像，trace 不可用时兜底。

配置见 16.2（trace: 'on-first-retry'、screenshot: 'only-on-failure'、video: 'retain-on-failure'）。本地调试时 pnpm exec playwright test --headed --debug 可单步执行、实时看定位器匹配。

16.7 flaky 治理：四大来源与对策

flaky（偶红偶绿）是 E2E 头号杀手——它让团队学会无视红色，CI 从此失效。四大来源与对策：

// ❌ 硬编码等待：慢 3 秒还偶发失败
await page.getByLabel('关键词').fill('华东')
await page.waitForTimeout(3000)
await expect(page.getByRole('cell', { name: 'QO20260929000001' })).toBeVisible()

// ✅ 轮询断言：条件满足立刻通过，最迟 5 秒
await page.getByLabel('关键词').fill('华东')
await expect(page.getByRole('cell', { name: 'QO20260929000001' })).toBeVisible({ timeout: 5_000 })

治理流程：标记重试后仍失败的用例为「真缺陷或真脆弱」→ 看 trace 定位根因 → 修代码或修用例，不允许用「再加一层 sleep」过关。CI 上可配置：重试 2 次后仍红即流水线失败（retries 只救环境抖动，不救真 bug）。

16.8 CI 接入

PR 跑冒烟集（--grep @smoke），主干合入后跑全量；报告工件总是上传（失败排查靠它）：

# .github/workflows/e2e.yml —— 完整流水线见第 18 章，这里只看 E2E job
name: e2e
on:
  pull_request:
  push:
    branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm exec playwright test --grep @smoke     # PR 冒烟；主干用 playwright test 全量
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}                          # 失败更要上传报告
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

给冒烟用例打标签：test('...下单主流程...', { tag: '@smoke' }, async ({ page }) => {...})。

16.9 企业案例：下单主流程 E2E（冒烟集）

附录A §4 的冒烟集定义：登录 → 下单 → 审批 → 导出，全链路通过。实现上拆成一条 test.describe.serial 主链路（步骤间有先后依赖）+ 若干独立回归用例（storageState 加速）：

// e2e/order-flow.spec.ts
import { test, expect } from '@playwright/test'
import { login, createOrder } from './helpers/api'

test.describe.serial('下单主流程（冒烟集 @smoke）', () => {
  let orderNo: string
  let token: string

  test('1. 运营登录成功', async ({ page }) => {
    await page.goto('/login')
    await page.getByLabel('邮箱').fill('operator@qingorder.example.com')
    await page.getByLabel('密码').fill('demo-password-123')
    await page.getByRole('button', { name: '登录' }).click()
    await expect(page).toHaveURL(/\/dashboard/)
  })

  test('2. 创建订单（折扣 ≤ 90% 免审批）', async ({ page, request }) => {
    token = await login(request)
    await page.getByRole('link', { name: '新建订单' }).click()
    await page.getByLabel('客户').fill('青云华东代理')
    await page.getByLabel('商品').fill('智能网关 X1')
    await page.getByLabel('数量').fill('2')
    await page.getByRole('button', { name: '提交订单' }).click()

    await expect(page.getByText(/订单创建成功/)).toBeVisible()
    orderNo = (await page.getByTestId('created-order-no').textContent())!
    expect(orderNo).toMatch(/^QO\d{14}$/) // 附录A：QO + yyyyMMdd + 6 位序号
  })

  test('3. 财务审批通过', async ({ page, request }) => {
    // 切换财务角色：用财务账号登录态操作（多角色 setup 见 16.4）
    await page.getByRole('link', { name: '订单管理' }).click()
    await page.getByLabel('关键词').fill(orderNo)
    await page.getByRole('row', { name: new RegExp(orderNo) }).getByRole('button', { name: '审核' }).click()
    await page.getByRole('button', { name: '通过' }).click()
    await expect(page.getByRole('cell', { name: '已审核' })).toBeVisible()
  })

  test('4. 导出选中订单为 CSV', async ({ page }) => {
    await page.getByLabel('关键词').fill(orderNo)
    await page.getByRole('row', { name: new RegExp(orderNo) }).getByRole('checkbox').check()
    const downloadPromise = page.waitForEvent('download')
    await page.getByRole('button', { name: '批量导出' }).click()
    const download = await downloadPromise
    expect(download.suggestedFilename()).toMatch(/orders.*\.csv$/)
  })
})

配套回归集（storageState 版，节选）：无权限访问 /system/settings 落 403 页（附录A 页面级权限）、销售看不到「删除订单」按钮（按钮级权限）、新建订单整单折扣 92% 后状态为 pending_review（审批分流）。至此附录A 的 E2E 冒烟集目标达成：全链路在 CI 稳定通过。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：搭起 Playwright 工程（16.2 配置），写第一条用例：访问登录页 → 输入错误密码 → 断言展示「邮箱或密码错误」且不跳转；再用正确账密走通登录。跑一次 --headed 亲眼看看，然后人为制造一次失败，查看自动生成的失败截图。

提示：错误提示是异步出现的，用 expect(locator).toBeVisible() 的自动重试；「制造失败」可以直接把一个断言改错。

验收标准：两条用例都绿；改错后的失败报告里有截图与错误上下文，html-report 能打开。

// e2e/login.spec.ts
import { test, expect } from '@playwright/test'

test('错误密码提示且不跳转', async ({ page }) => {
  await page.goto('/login')
  await page.getByLabel('邮箱').fill('operator@qingorder.example.com')
  await page.getByLabel('密码').fill('wrong-password')
  await page.getByRole('button', { name: '登录' }).click()

  await expect(page.getByText('邮箱或密码错误')).toBeVisible()
  await expect(page).toHaveURL(/\/login/) // 仍在登录页
})

练习 2 · 进阶（30–60 min）

任务描述：实现登录态复用与订单筛选回归集：① 按 16.4 配置 setup 项目 + storageState；② 写用例：API 造 3 条不同状态的订单 → 列表页按状态 已审核 筛选 → 断言只出现目标订单；③ afterEach 清理造数。

提示：造数时把状态直接置为 approved（接口若不支持，先造草稿再走一次提交/审核接口）；断言「只出现目标订单」用 toHaveCount(1) 而不是只断言可见。

验收标准：连续运行 pnpm exec playwright test 三次全部通过（隔离生效）；单条用例耗时 < 3s（登录态复用生效）。

// e2e/order-filter.spec.ts
import { test, expect } from '@playwright/test'
import { login, createOrder } from './helpers/api'

let orderNos: string[] = []

test.afterEach(async ({ request }) => {
  await request.post('/api/v1/test/cleanup', { data: { orderNos } })
  orderNos = []
})

test('按「已审核」状态筛选', async ({ page, request }) => {
  const token = await login(request)
  const marker = `E2E-${Date.now()}`
  for (const status of ['draft', 'approved', 'cancelled'] as const) {
    const { orderNo } = await createOrder(request, token, `${marker}-${status}`)
    await request.post(`/api/v1/orders/${orderNo}/transition`, {
      headers: { Authorization: `Bearer ${token}` }, data: { status },
    })
    orderNos.push(orderNo)
  }

  await page.goto('/orders')
  await page.getByTestId('order-status-filter').click()
  await page.getByRole('option', { name: '已审核' }).click()

  await expect(page.getByRole('row')).toHaveCount(1 + 1) // 表头 + 目标行
  await expect(page.getByRole('cell', { name: /approved/ })).toHaveCount(1)
})

练习 3 · 挑战（选做，60+ min）

任务描述：完整实现 16.9 的下单主流程冒烟集（登录 → 下单 → 审批 → 导出），接进 CI（PR 只跑 @smoke），并做一次 flaky 演练：在审批步骤注入 800ms 延迟 mock，验证用例依靠自动等待依然稳定；然后故意改成硬 sleep 版本，观察其在并发 worker 下的失败率。

提示：导出下载用 page.waitForEvent('download')（16.9 已给样例）；CI 里先本地模拟 CI=true pnpm exec playwright test；演练数据写成对比表存进 docs/qa/flaky-drill.md。

验收标准：CI 冒烟集全绿且耗时 < 2 分钟；延迟注入下 10 次运行 0 失败；硬 sleep 版本在 workers: 2 下至少出现 1 次失败，用 trace 能定位到等待竞态。

// 给审核接口注入延迟，验证自动等待的健壮性
await page.route('**/api/v1/orders/*/review', async (route) => {
  await new Promise((r) => setTimeout(r, 800)) // 模拟慢接口
  await route.continue()
})
// 之后照常点击与断言：expect 的自动重试会等到响应完成，不需要 sleep
await page.getByRole('button', { name: '通过' }).click()
await expect(page.getByRole('cell', { name: '已审核' })).toBeVisible({ timeout: 5_000 })

⚠️ 常见易错点

易错点 1：waitForTimeout 硬等待，又慢又 flaky

// ❌ 「等 3 秒应该够了吧」：环境快时白等 3 秒，环境慢时照样失败
await page.getByRole('button', { name: '提交订单' }).click()
await page.waitForTimeout(3000)
await expect(page.getByText('订单创建成功')).toBeVisible()

// ✅ Web 断言自带轮询重试：条件满足立即通过，最迟 5 秒
await page.getByRole('button', { name: '提交订单' }).click()
await expect(page.getByText('订单创建成功')).toBeVisible({ timeout: 5_000 })

评审规则：PR 里出现 waitForTimeout 直接打回——它是 flaky 的第一来源。

易错点 2：CSS 层级选择器，重构一次崩一片

// ❌ 依赖 DOM 结构与 className：改个布局、换套样式，测试全红
await page.click('.orders-page > div:nth-child(2) .btn-primary')

// ✅ 按用户看见的语义定位：改布局不改语义，测试零维护
await page.getByRole('button', { name: '提交订单' }).click()

定位器不稳定时，先怀疑「组件的可访问性命名没写好」——修 a11y 比修选择器一劳永逸。

易错点 3：用例依赖前序用例的数据，并行下互相踩踏

// ❌ test 2 假设 test 1 造的订单还在第一条：workers=2 时执行顺序不保证，偶发红
test('创建订单', ...)   // 造了订单 A
test('查看第一条订单', ...) // 断言列表第一条是订单 A

// ✅ 每条用例自带夹具：自己造数、自己断言、自己清理；有先后依赖的才用 serial 主链路
test('创建订单并查看详情', async ({ page, request }) => {
  const { orderNo } = await createOrder(request, token, `E2E-${Date.now()}`)
  await page.goto(`/orders/${orderNo}`)
  await expect(page.getByText(orderNo)).toBeVisible()
})

判断口诀：任何用例单独跑、乱序跑、并行跑，结果都必须一致。

易错点 4：storageState 一刀切，登录功能本身失去验证

// ❌ 所有用例都吃现成登录态：登录页改坏了 CI 全绿，上线当天翻车
//    （projects 里只剩 storageState 项目，没有真登录用例）

// ✅ 复用态项目 + 保留一条真实登录冒烟用例，两层各有职责
test('登录页可用（真登录链路 @smoke）', async ({ page }) => {
  await page.goto('/login')
  await page.getByLabel('邮箱').fill('operator@qingorder.example.com')
  await page.getByLabel('密码').fill('demo-password-123')
  await page.getByRole('button', { name: '登录' }).click()
  await expect(page).toHaveURL(/\/dashboard/)
})

易错点 5：trace/视频全量常开，CI 时间与磁盘双爆

// ❌ 每条用例都录 trace + video：几十条用例的 CI 产物几个 GB，上传比测试还久
use: { trace: 'on', video: 'on', screenshot: 'on' }

// ✅ 失败导向：第一次重试才录 trace、失败才截图/录像，正常路径零开销
use: { trace: 'on-first-retry', video: 'retain-on-failure', screenshot: 'only-on-failure' }

诊断产物是「失败保险」，不是「全程行车记录仪」——按需开启才是工程化做法。

✅ 最佳实践

1. 两层覆盖策略：PR 只跑冒烟集（@smoke，5–10 条），全量回归放主干定时任务；冒烟答「敢不敢发」。
2. 定位器三优先：Role / Label / 用户可见文本，data-testid 只兜底；把这条写进 PR 模板。
3. 登录态两级制：storageState 提速日常用例，但永远保留一条真登录冒烟用例。
4. 数据自治：每条用例 API 造数 + 唯一后缀 + afterEach 清理；共享数据的用例一律视为 flaky 候选。
5. 失败现场三件套：trace（主）、截图（快）、视频（兜底），配置为失败导向而非全量开启。
6. flaky 零容忍：重试后仍红的用例当日处理（修或删），禁止「失败重跑就绿」积攒成 CI 噪音。
7. 环境动画归零：测试环境关闭过渡动画（prefers-reduced-motion），消除一整类不稳定。
8. 报告是交付物：CI 失败时报告工件自动上传，任何人不本地复现也能定位失败步骤。

📌 本章小结

• E2E 验证「整车能跑」：冒烟集（登录→下单→审批→导出）卡发布，全量回归看水位；PR 只跑冒烟。
• Playwright 三大稳定性机制（自动等待、严格模式、Web 断言重试）+ 用户可见性定位器，从源头消灭 flaky。
• storageState 复用登录态提效，但真登录链路必须有专属用例；数据 API 造数 + 唯一后缀 + 清理实现隔离。
• trace/screenshot/video 是失败现场三件套，按需开启；flaky 用例当日治理，不允许积攒。
• 附录A E2E 冒烟集目标达成：「轻订单」下单主流程已在 CI 每日自动验证。

测试防线齐了，但团队还缺两样东西：让代码风格与类型纪律自动执行的工程化链路（ESLint/Prettier/husky、tsconfig、Vite 进阶），以及让每次提交自动变成本次可发布产物的交付流水线。下一章先补前者。

📄 第 17 章 · 工程化实践：TypeScript 与 Vite 17-工程化实践-TypeScript与Vite.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：7–9 小时｜🔗 前置：第 12 章实战（本章把它的 JS 代码全面迁移到 TS）

⬅ 上一章：E2E 测试与质量保障 ｜ 📖 本版目录 ｜ ➡ 下一章：CI/CD 部署与前端监控

💡 对照学习：本页是 React 版第 17 章，对应 Vue 版第 17 章 · 工程化实践。概念映射：泛型组件 Table<T> ≈ Vue 3.3+ 的 defineProps<{...}>() 泛型 props、PropsWithChildren ≈ 具名插槽默认内容、类型守卫 ≈ 同一概念两版通用。tsconfig / ESLint / Prettier / husky / lint-staged / Vite 插件 / 环境变量 / pnpm workspace 与框架无关，两版逐字通用；差异集中在框架类型层：React 的 props 是显式 interface，Vue 的 props 走运行时声明+类型推导。

🎯 学习目标

学完本章，你将能够：

1. 配置 tsconfig 关键项并说出 strict 家族各开关分别拦住什么，把「strict 全开 + 禁新增 any」定为团队纪律；
2. 为组件书写清晰的 props 类型，会写泛型组件（DataTable<T>）并正确处理 children 类型（PropsWithChildren / ReactNode）；
3. 用类型守卫收窄 API 响应类型，让「编译期类型」与「运行时数据」闭环；
4. 搭通 ESLint（flat config）+ Prettier + husky + lint-staged 的提交前质量链路；
5. 配置 Vite 的插件、开发代理与分环境环境变量，并给 import.meta.env 补全类型；
6. 用 rollup-plugin-visualizer 分析构建产物，用 manualChunks 做分包优化并对照第 14 章预算验证；
7. 搭建 pnpm workspace 骨架，把 money 工具与类型定义抽成可共享的内部包；
8. 为存量 JS 项目制定渐进式 TS 迁移方案（轻订单 .jsx → .tsx 迁移路线 M1–M4）。

📖 核心知识点

17.1 TS 基线：tsconfig 关键项与 strict 纪律

Vite 的 React 模板默认给出三份配置（tsconfig.json 引用 tsconfig.app.json + tsconfig.node.json），业务代码的关键项在 tsconfig.app.json：

// tsconfig.app.json（关键项 + 注释说明为什么）
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",      // 配合 Vite 的打包语义，支持扩展名省略
    "jsx": "react-jsx",                 // React 17+ 自动 JSX 转换，无需 import React
    "strict": true,                     // 全家桶：null 检查/this/初始化检查等
    "noUncheckedIndexedAccess": true,   // arr[i] 类型为 T | undefined——索引访问必须判空
    "noUnusedLocals": true,             // 未用变量报错，防「注释式代码」
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true, // switch 忘 break 直接报错
    "verbatimModuleSyntax": true,       // type-only import 必须写 import type（见易错点 17-4）
    "skipLibCheck": true,               // 跳过第三方 .d.ts 检查，提速
    "noEmit": true,                     // 类型检查与构建分离，产物交给 Vite
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

strict 是底线，noUncheckedIndexedAccess 是进阶——它把「数组越界」从运行时炸点变成编译期红波浪线，代价是老代码要补判空，所以渐进迁移时可以后开。

// package.json —— 类型检查独立成脚本：CI 与编辑器跑的是同一套标准
{
  "scripts": {
    "typecheck": "tsc -b --noEmit"
  }
}

strict 纪律两条：① 全仓库 strict: true，不允许用 @ts-nocheck 整文件豁免；② 禁止新增 any（ESLint 层面卡死，见 17.4），存量 any 允许存在但只减不增。

17.2 组件类型：props、Children 与泛型组件

基础 props 类型：React 的 props 就是普通 TypeScript interface，必选/可选/联合类型直接表达业务约束：

// src/components/StatusTag.tsx —— props 用 interface，状态用附录A 的字面量联合
import type { OrderStatus } from '@/types/order'

interface StatusTagProps {
  status: OrderStatus
  size?: 'sm' | 'md' // 可选属性必须显式处理 undefined
}

export function StatusTag({ status, size = 'md' }: StatusTagProps) {
  const meta = ORDER_STATUS[status]
  return <Tag color={meta.color} className={`tag--${size}`}>{meta.label}</Tag>
}

Children 类型：三兄弟要分清——ReactNode（一切可渲染物：元素、字符串、数组、null）最常用；PropsWithChildren<P> 是「P 加一个 children」的快捷类型；ReactElement 只接受单个元素对象（例如明确要求 <X/> 而不是一段文字时）：

import type { PropsWithChildren, ReactNode, ReactElement } from 'react'

// 写法一：PropsWithChildren 快捷方式
function Card(props: PropsWithChildren<{ title: string }>) {
  return <section className="card"><h3>{props.title}</h3>{props.children}</section>
}

// 写法二：显式声明，语义等价
function Card2({ title, children }: { title: string; children?: ReactNode }) { /* … */ }

泛型组件：列表页的 DataTable 天然是「类型随数据变」的场景——用泛型让列定义与数据行强关联：

// src/components/DataTable.tsx —— 泛型组件：T 由 items 推导，column.key 必须是 T 的键
import type { ReactNode } from 'react'

export interface DataTableColumn<T> {
  key: keyof T & string
  title: string
  render?: (row: T) => ReactNode
  width?: number
}

interface DataTableProps<T> {
  items: T[]
  columns: DataTableColumn<T>[]
  rowKey: (row: T) => string
  loading?: boolean
  empty?: ReactNode
}

export function DataTable<T>({ items, columns, rowKey, loading, empty }: DataTableProps<T>) {
  if (loading) return <DataTableSkeleton />
  if (items.length === 0) return <>{empty ?? <Empty text="暂无数据" />}</>
  return (
    <table>
      <thead>
        <tr>{columns.map((c) => <th key={c.key}>{c.title}</th>)}</tr>
      </thead>
      <tbody>
        {items.map((row) => (
          <tr key={rowKey(row)}>
            {columns.map((c) => (
              <td key={c.key}>{c.render ? c.render(row) : String(row[c.key] ?? '—')}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  )
}

// 使用处：T 被自动推导为 Order，写错列名或返回类型直接编译报错
;<DataTable
  items={orders}
  rowKey={(o) => o.id}
  columns={[
    { key: 'orderNo', title: '订单号' },
    { key: 'totalAmount', title: '金额', render: (o) => formatAmount(o.totalAmount) },
    { key: 'status', title: '状态', render: (o) => <StatusTag status={o.status} /> },
  ]}
/>

Ant Design 5 的 <Table<T>> 就是这套机制；手写一遍泛型组件是为了让你看懂它的类型签名。

17.3 API 响应类型与类型守卫

interface Order 只是编译期的「承诺」——接口真的返回这个形状吗？类型守卫在边界处做运行时校验，把 unknown 安全收窄为业务类型：

// src/types/api.ts —— 统一响应体（附录A §5）
export interface ApiResponse<T> {
  code: number
  message: string
  data: T
}

export interface PageData<T> {
  list: T[]
  total: number
  page: number
  pageSize: number
}

// src/api/guards.ts —— 类型守卫：运行时校验 + 编译期收窄
import type { ApiResponse, PageData } from '@/types/api'
import type { Order } from '@/types/order'

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null
}

export function isOrder(value: unknown): value is Order {
  if (!isRecord(value)) return false
  return typeof value.id === 'string'
    && typeof value.orderNo === 'string'
    && Array.isArray(value.items)
}

export function isOrderPage(value: unknown): value is PageData<Order> {
  if (!isRecord(value) || !Array.isArray(value.list)) return false
  return value.list.every(isOrder) // 列表里混进一条脏数据也拦得住
}

// src/api/orders.ts —— 在数据进入应用的边界处校验
import { request } from '@/utils/request'

export async function fetchOrders(params: { keyword: string; page: number }): Promise<PageData<Order>> {
  const body = await request.get<unknown>('/orders', { params })
  const page: unknown = (body as ApiResponse<unknown>).data
  if (!isOrderPage(page)) {
    throw new Error('订单列表响应结构异常，请检查接口契约') // 快速失败，好过脏数据流入 UI
  }
  return page
}

对照 Vue：Vue 版同样用守卫，只是入口在 api/ 模块；React 版多了 TanStack Query 一层，守卫放在 queryFn 里效果相同——校验发生的位置不重要，「数据入口必校验」这条纪律才重要。更重的场景（表单契约、多态响应）可以直接上 Zod（第 10 章已学），守卫是零依赖的最小方案。

17.4 质量链路：ESLint + Prettier + husky + lint-staged

目标：开发者 git commit 的瞬间，风格问题已被机器拦下，Code Review 只看逻辑。

pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-react-hooks eslint-plugin-react-refresh prettier husky lint-staged
pnpm exec husky init

// eslint.config.js —— ESLint 9 flat config
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'

export default tseslint.config(
  { ignores: ['dist', 'coverage', 'playwright-report'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    plugins: { 'react-hooks': reactHooks, 'react-refresh': reactRefresh },
    rules: {
      ...reactHooks.configs.recommended.rules, // hooks 依赖检查：第 13 章易错点 5 的机器防线
      '@typescript-eslint/no-explicit-any': 'error',        // 禁新增 any（strict 纪律第 2 条）
      '@typescript-eslint/consistent-type-imports': 'error', // type-only import 必须带 type
      'no-console': ['warn', { allow: ['warn', 'error'] }],
    },
  },
)

// .prettierrc —— 团队风格唯一事实源；与 ESLint 分工：Prettier 管格式，ESLint 管质量
{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "all"
}

// package.json —— 只 lint 暂存区文件：秒级反馈，不阻塞全仓提交
{
  "scripts": { "prepare": "husky" },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

# .husky/pre-commit —— husky 初始化后生成的钩子
pnpm exec lint-staged

链路全景：git commit → husky pre-commit → lint-staged → ESLint（质量）+ Prettier（格式）→ 有问题则提交中止。CI 里再跑一遍全量 pnpm lint（第 18 章），双保险防绕过（--no-verify）。

17.5 Vite 进阶：插件、代理与环境变量分环境

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  return {
    plugins: [
      react(),
      // 构建产物分析：跑 pnpm build 后打开 dist/stats.html（常驻，发布前看一眼）
      visualizer({ filename: 'dist/stats.html', gzipSize: true }),
    ],
    server: {
      proxy: {
        // 开发期把 /api 转发到本地 mock 或联调环境（附录A：开发期代理指向本地 mock）
        '/api': {
          target: env.VITE_PROXY_TARGET ?? 'http://localhost:8787',
          changeOrigin: true,
        },
      },
    },
    build: {
      sourcemap: false, // 生产默认不出 sourcemap；要出只能 'hidden'，见第 18 章安全红线
      chunkSizeWarningLimit: 500,
      rollupOptions: {
        output: {
          // 大体积、低频变动的库单独分包：命中浏览器长缓存，业务代码改动不影响它们
          manualChunks: {
            vendor: ['react', 'react-dom', 'react-router'],
            antd: ['antd'],
          },
        },
      },
    },
  }
})

环境变量分环境：Vite 按 mode 加载对应文件，pnpm build --mode test 时加载 .env.test：

.env.development   # pnpm dev 加载：VITE_API_BASE_URL=/api（走代理）
.env.test          # --mode test：VITE_API_BASE_URL=https://api-test.qingorder.example.com/api/v1
.env.production    # pnpm build 加载：VITE_API_BASE_URL=https://api.qingorder.example.com/api/v1

# .env.development —— 只有 VITE_ 前缀的变量会暴露给客户端代码！
VITE_API_BASE_URL=/api
VITE_PROXY_TARGET=http://localhost:8787

// src/vite-env.d.ts —— 给 import.meta.env 补全类型（IDE 自动补全 + 拼错变量名编译报错）
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_PROXY_TARGET?: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

⚠️ 安全红线再强调一次：所有 VITE_* 变量都会被打进客户端产物，任何人打开 DevTools 都能看到。放公开配置（API 地址、开关）没问题；放密钥是事故（易错点 17-3）。需要保密的配置要么走后端，要么走第 18 章的运行时注入。

17.6 构建分析与产物优化

dist/stats.html 是一张 Treemap：方块越大占字节越多。看三件事——「不该在首包里的东西」（第 14 章分割是否真的生效）、「重复依赖」（lodash 全量 vs 按需）、「意外的大头」（moment 时区数据之类）。manualChunks（17.5）之外还有两个常见动作：

// ① 按需引入组件库：Ant Design 5 默认支持 tree-shaking，但要防「顺手全量引」
import { Button, Table } from 'antd'           // ✅ ESM 具名导入，可摇树
import * as antd from 'antd'                   // ❌ 全量命名空间导入，摇树失效

// ② 动态 import 拆重库（与第 14 章 React.lazy 配合）
const { default: ECharts } = await import('echarts') // 报表页才加载图表库

优化后验证闭环：pnpm build → 看 stats.html → 跑第 14 章的 check:budget（gzip ≤ 300KB 门禁）→ 数据归档进 docs/perf/。

17.7 pnpm workspace 初探

当「轻订单」要抽出内部组件库 qing-ui（第 20 章）、或多个应用共享 money 工具时，Monorepo 就登场了。pnpm workspace 是最轻的起步方式：

# pnpm-workspace.yaml —— 声明哪些目录是工作区包
packages:
  - 'apps/*'      # 应用：qingorder-portal / qingorder-admin
  - 'packages/*'  # 内部包：shared（工具+类型）、qing-ui（第 20 章）

qingorder/
├── pnpm-workspace.yaml
├── apps/
│   └── admin/                 # 现在的 React 应用整体迁进来
│       ├── package.json       #   "name": "@qingorder/admin"
│       └── src/...
└── packages/
    └── shared/
        ├── package.json       #   "name": "@qingorder/shared", "type": "module"
        └── src/
            ├── money.ts       # 第 15 章测试过的金额工具，原样迁出
            └── types/order.ts # 附录A 实体类型，两应用共用

// apps/admin/package.json —— 用 workspace: 协议引用内部包
{
  "dependencies": {
    "@qingorder/shared": "workspace:*"
  }
}

// apps/admin/src/utils/format.ts —— 业务代码里像普通包一样 import
import { formatAmount } from '@qingorder/shared'

三个立刻能兑现的收益：依赖只装一份（pnpm 硬链接省磁盘）、内部包改动即时生效（无需发布 npm）、money.ts 的 80% 覆盖率测试跟着包走，谁用谁受益。深入玩法（changesets 版本管理、私有 npm 源）在第 20 章组件库建设里展开。

17.8 企业案例：轻订单渐进式 TS 迁移方案

第 12 章交付的 React 应用是纯 JS（.jsx）。直接「一夜全转 TS」的方案在真实团队必然烂尾：几万行代码的报错墙会压垮业务迭代。给「轻订单」定渐进方案 M1–M4：

三条迁移战术：① JSDoc → interface：先给 JS 里的注释类型补上真实类型，机械改写风险最低；② 临时逃逸要留痕：卡住的类型用 // TODO(ts-migration) + @ts-expect-error 标记（它会在这行被修好后自动报错提醒你删掉），绝不用 @ts-ignore（静默）；③ .jsx 与 .tsx 可以长期共存，Vite 原生支持混编，迁移不阻塞任何业务需求。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：把第 12 章的 StatusTag.jsx 与 Auth.jsx 迁移为 .tsx：补全 props interface、给默认值标注类型、处理可选属性，并让 pnpm typecheck 通过。

提示：Auth 的 need prop 是附录A 权限动作的字面量联合（'order:delete' | 'order:review' | ...），从 @/types/permissions 导入而不是写内联联合；状态机字典 ORDER_STATUS 用 Record<OrderStatus, { label: string; color: string }> 收敛。

验收标准：两个文件零 any；故意给 StatusTag 传 'shipped '（多空格的非法状态）时编译报错；typecheck 脚本可重复运行。

import { Tag } from 'antd'
import type { OrderStatus } from '@/types/order'

type TagSize = 'sm' | 'md'

interface StatusTagProps {
  status: OrderStatus
  size?: TagSize
}

const ORDER_STATUS: Record<OrderStatus, { label: string; color: string }> = {
  draft:          { label: '草稿',   color: 'default' },
  pending_review: { label: '待审核', color: 'orange' },
  approved:       { label: '已审核', color: 'blue' },
  shipped:        { label: '已发货', color: 'cyan' },
  completed:      { label: '已完成', color: 'green' },
  rejected:       { label: '已拒绝', color: 'red' },
  cancelled:      { label: '已取消', color: 'gray' },
}

export function StatusTag({ status, size = 'md' }: StatusTagProps) {
  const meta = ORDER_STATUS[status]
  return <Tag color={meta.color} className={`tag tag--${size}`}>{meta.label}</Tag>
}

练习 2 · 进阶（30–60 min）

任务描述：① 用 17.2 的泛型 DataTable<T> 同时替换订单列表与客户列表的表格实现；② 按 17.3 给 fetchCustomers 补类型守卫（isCustomer：校验 id/customerName/level 三个关键字段），并让守卫拦下一次「后端把 level 返回成数字」的模拟脏数据。

提示：两个列表共用 DataTable 后，差异只剩 columns 定义——这正是泛型组件的价值；守卫测试直接在 Vitest 里喂脏数据（第 15 章的设施复用）。

验收标准：两个列表的类型互不干扰（DataTable<Customer> 的列里返回 Order 字段会编译报错）；脏数据测试用例红转绿；noUncheckedIndexedAccess 开启下无新增报错。

// src/api/guards.ts
export interface Customer {
  id: string
  customerName: string
  level: 'A' | 'B' | 'C'
}

export function isCustomer(value: unknown): value is Customer {
  if (!isRecord(value)) return false
  return typeof value.id === 'string'
    && typeof value.customerName === 'string'
    && (value.level === 'A' || value.level === 'B' || value.level === 'C')
}

// src/api/guards.test.ts
import { describe, expect, it } from 'vitest'
import { isCustomer } from './guards'

describe('isCustomer 类型守卫', () => {
  it('合法客户通过', () => {
    expect(isCustomer({ id: 'c1', customerName: '青云华东', level: 'A' })).toBe(true)
  })
  it('level 返回数字（后端脏数据）被拦截', () => {
    expect(isCustomer({ id: 'c1', customerName: '青云华东', level: 1 })).toBe(false)
  })
  it('非对象输入被拦截', () => {
    expect(isCustomer(null)).toBe(false)
    expect(isCustomer('c1')).toBe(false)
  })
})

练习 3 · 挑战（选做，60+ min）

任务描述：完成轻订单 Monorepo 化第一步：建立 pnpm workspace，把 money.ts + 附录A 类型抽成 @qingorder/shared，admin 应用通过 workspace:* 引用；然后用 rollup-plugin-visualizer 分析 admin 产物，调整 manualChunks 并通过第 14 章的 gzip 预算检查。

提示：shared 包要有自己的 package.json（"type": "module"，main/exports 指向 src/index.ts 即可让 Vite 直接吃 TS 源码）；stats.html 里确认 vendor 与 antd 分包是否如预期切开了。

验收标准：pnpm -r test（递归跑所有包的测试）全绿；admin 构建产物中 shared 的代码被正确打进业务 chunk；check:budget 通过；monorepo 目录结构与 17.7 一致。

// packages/shared/package.json
{
  "name": "@qingorder/shared",
  "version": "0.1.0",
  "type": "module",
  "exports": { ".": "./src/index.ts" },
  "scripts": { "test": "vitest run" }
}

// packages/shared/src/index.ts
export { calcItemAmount, calcOrderTotal, formatAmount } from './money'
export type { Order, OrderItem, OrderStatus } from './types/order'

pnpm install                    # workspace 重新链接
pnpm --filter @qingorder/shared test
pnpm -r test

⚠️ 常见易错点

易错点 1：用 any 兜 API 响应，类型体系从源头失守

// ❌ 类型只是「看起来安全」：level 拼写错了、结构变了，编译器都哑巴
const res = await axios.get('/api/v1/customers')
const list = res.data.data.list as Customer[] // as 是谎言，不是保障

// ✅ unknown + 类型守卫：先运行时校验再收窄，契约漂移当场爆炸而不是线上爆炸
const body: unknown = (await axios.get('/api/v1/customers')).data
if (!isCustomerPage((body as ApiResponse<unknown>).data)) {
  throw new Error('客户列表响应结构异常')
}

as 断言是「我对类型负责」，守卫是「代码对类型负责」——边界处只允许后者。

易错点 2：props 类型用 Partial/any 偷懒，丢掉必填约束

// ❌ 全可选：忘传 customerName 编译器不吭声，运行时列表出现「undefined 客户」
interface OrderCardProps { order?: Partial<Order> }
export function OrderCard({ order }: OrderCardProps) {
  return <span>{order?.customerName}</span> // 展示 undefined 的 bug 就这么来的
}

// ✅ 必填与可选如实声明；确实「两种形态」的组件用显式联合类型
interface OrderCardProps { order: Order }
// 真需要部分数据时，用工具类型精确表达：Pick<Order, 'id' | 'orderNo'>

类型是文档也是测试：interface 上的每个 ? 都是你在承诺「缺了它能跑」，想清楚再写。

易错点 3：把密钥塞进 VITE_ 环境变量，直接打进公开产物

# ❌ .env.production —— 构建后打开任意 chunk 就能搜到，等于公开泄露
VITE_API_SECRET_KEY=<your-api-secret>
VITE_SENTRY_AUTH_TOKEN=<your-sentry-auth-token>

# ✅ VITE_ 只放公开配置；机密值留占位符，真实值走 CI secrets 或服务端（第 18 章）
VITE_API_BASE_URL=https://api.qingorder.example.com/api/v1
# Sentry sourcemap 上传用的 token 属于构建机，放 CI secrets：${{ secrets.SENTRY_AUTH_TOKEN }}

判断标准一句话：能在浏览器 Network/Source 面板里看到的东西，就别指望 VITE_ 能保密。

易错点 4：类型导入不写 import type，verbatimModuleSyntax 下翻车

// ❌ Order 只是类型却被当成值导入：verbatimModuleSyntax 开启时，
//    打包器原样保留这条 import，types/order.ts 若无运行时导出直接报「找不到模块」
import { Order } from '@/types/order'

// ✅ 纯类型一律 import type：编译期擦除，不产生运行时代价
import type { Order, OrderStatus } from '@/types/order'

开了 verbatimModuleSyntax 后这是最常见的红波浪线——但它换来的回报是「类型与值在产物层面彻底分离」，值得。

易错点 5：@ts-ignore 一盖了之，类型债静默复利

// ❌ 报错看着烦，注释一盖：这一行从此对编译器隐身，
//    三个月后接口加了字段，唯一的哨兵正是你亲手禁言的它
// @ts-ignore
submitOrder(payload)

// ✅ 明确承认「我知道为什么报错、何时处理」，且修好后 @ts-expect-error 会提醒你删掉它
// TODO(ts-migration): 审批接口 v2 契约定稿后移除
// @ts-expect-error 旧版审批接口暂缺 discountPercent 字段
submitOrder(payload)

团队规范写作口径：PR 里新增 @ts-ignore = 打回；@ts-expect-error 必须带 TODO 与原因。

✅ 最佳实践

1. strict 全开是团队纪律不是个人偏好：tsc -b --noEmit 进 CI，编辑器与流水线同一把尺。
2. 契约层先行迁移：api/types/utils 先 .ts 化——类型收益最大、依赖最少，为组件层迁移铺路。
3. 泛型组件服务「同构异形」：列表、下拉、表单这类结构固定数据多变的组件用 <T> 收敛，别为每种实体复制粘贴。
4. 数据入口必校验：unknown + 守卫（或 Zod）位于唯一入口（api 层/queryFn），UI 层可以放心相信类型。
5. 风格与质量分权：Prettier 管格式、ESLint 管质量、husky + lint-staged 管门禁，三者不重复不缺位。
6. 环境变量分环境 + 类型补全：ImportMetaEnv 声明进仓库，新增变量先补类型；VITE_ 前缀 = 公开承诺。
7. 产物分析常态化：每次大依赖变更跑一次 visualizer + 预算检查，与第 14 章的性能预算形成闭环。
8. Monorepo 只在真有共享时上：先抽 shared（工具与类型），组件库（第 20 章）再扩——为了「看起来架构好」拆包是负债。

📌 本章小结

• TS 基线 = strict 全开 + 索引访问判空 + 禁新增 any；typecheck 独立成脚本并与 CI 同尺。
• 组件类型三件套：显式 props interface、ReactNode/PropsWithChildren 处理 children、泛型组件收敛「同构异形」。
• unknown + 类型守卫让编译期类型与运行时数据闭环，守卫放在数据入口（api 层 / queryFn）。
• 质量链路四件套（ESLint flat config + Prettier + husky + lint-staged）把风格问题拦截在 commit 瞬间。
• Vite 进阶四板斧：代理、分环境变量（VITE_ 只放公开配置）、manualChunks 分包、visualizer 分析。
• 轻订单 M1–M4 渐进迁移方案落定：契约层先行、@ts-expect-error 留痕逃逸、门禁逐步收紧。

代码已经「规范得能被同事接手」，最后一块拼图是交付：每次合并如何自动构建、多环境如何注入配置、发错了如何秒级回滚、线上挂了谁在几秒内知道——下一章把 CI/CD 流水线与前端监控一起搭起来。

📄 第 18 章 · CI/CD 部署与前端监控 18-CICD部署与前端监控.md✓ 标记已学

📍 阶段：高级阶段（第 13–18 章）｜⏱ 预计学时：6–8 小时｜🔗 前置：第 16 章 E2E + 第 17 章工程化

⬅ 上一章：工程化实践 · TypeScript 与 Vite ｜ 📖 本版目录 ｜ ➡ 下一章：大型项目架构设计

💡 对照学习：本页是 React 版第 18 章，对应 Vue 版第 18 章 · CI/CD 部署与前端监控。CI/CD、Docker、Nginx、灰度回滚、sourcemap、告警 SOP 与框架完全无关，两版逐字通用。框架差异只有两处：错误监控接入用 Sentry React SDK（@sentry/react ≈ Vue 版的 @sentry/vue），错误兜底用 ErrorBoundary（≈ Vue 的 onErrorCaptured + 全局 errorHandler）。学完本章，高级阶段全部目标（附录A §6「性能与质量治理」）交付完毕。

🎯 学习目标

学完本章，你将能够：

1. 设计并落地 GitHub Actions 流水线：lint → typecheck → test → build → deploy 五段，PR 与主干差异化触发；
2. 区分「构建时注入」与「运行时注入」配置的适用场景，实现 dev/test/pre/prod 四环境的配置管理；
3. 编写多阶段 Dockerfile 与 Nginx 配置：SPA 回退、哈希资源长缓存、index.html 不缓存、brotli/gzip 压缩；
4. 实现按版本目录发布 + 符号链接切换的部署方式，支持灰度放量与秒级回滚；
5. 接入 Sentry 错误监控：ErrorBoundary 兜底 + sourcemap 还原，同时保证 sourcemap 不泄漏到公网；
6. 埋点 web-vitals 性能指标并实现白屏检测，形成「错误 + 性能 + 可用性」三类监控面；
7. 制定告警阈值与上线响应 SOP，完成一次「发布 → 告警 → 回滚 → 复盘」的完整演练；
8. 交付高级阶段验收：附录A §6「性能与质量治理」的全部目标逐项核对通过。

📖 核心知识点

18.1 流水线全景

把第 13–17 章攒下的质量资产（性能预算、单测门禁、E2E 冒烟、lint/typecheck）串成一条机器执行的发布铁律：

git push / PR
   │
   ▼
┌────────────── quality job ──────────────┐   ┌──── e2e job ────┐
│ lint → typecheck → test(--coverage 80%) │   │ 冒烟集 @smoke    │
│ → build(性能预算 check:budget)           │   │ (16 章)          │
└───────────────┬─────────────────────────┘   └────────┬────────┘
                │            两者并行，都绿才继续         │
                ▼◄──────────────────────────────────────┘
          ┌── deploy job（仅主干 main）──┐
          │ 构建产物 → Sentry sourcemap  │
          │ → 上传版本目录 → 链接切换灰度 │
          └─────────────────────────────┘

设计原则：PR 阶段挡质量（lint/test/冒烟，10 分钟内出结果），主干阶段管交付（build/deploy），失败在任何一段都要「红得清楚、拦得住」。

18.2 GitHub Actions 编排

# .github/workflows/ci-cd.yml
name: qingorder-web

on:
  pull_request:
  push:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true # 同分支新提交自动取消旧构建，省资源

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint                    # 第 17 章链路
      - run: pnpm typecheck               # tsc -b --noEmit
      - run: pnpm test:ci                 # vitest run --coverage（80% 门禁，15 章）
      - run: pnpm build
      - run: pnpm check:budget            # LCP/包体积预算，14 章
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm exec playwright test --grep @smoke   # PR 只跑冒烟（16 章）
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: [quality, e2e]
    runs-on: ubuntu-latest
    environment: production           # 环境级 secrets 与审批规则在仓库设置里配置
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist
      - name: 发布到版本目录并切换
        env:
          SSH_HOST: ${{ secrets.DEPLOY_HOST }}       # 所有凭据一律走 secrets，绝不写字面量
          SSH_USER: ${{ secrets.DEPLOY_USER }}
          SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
          RELEASE: ${{ github.sha }}
        run: |
          echo "$SSH_KEY" > deploy_key && chmod 600 deploy_key
          ssh -i deploy_key -o StrictHostKeyChecking=accept-new "$SSH_USER@$SSH_HOST" "mkdir -p /srv/qingorder/releases/$RELEASE"
          rsync -az --delete -e "ssh -i deploy_key" dist/ "$SSH_USER@$SSH_HOST:/srv/qingorder/releases/$RELEASE/"
          ssh -i deploy_key "$SSH_USER@$SSH_HOST" "ln -sfn /srv/qingorder/releases/$RELEASE /srv/qingorder/current"
          rm deploy_key

三处工程细节值得记住：concurrency 防止同一分支的构建排队爆炸；needs: [quality, e2e] 表达「全绿才部署」；environment: production 把密钥与审批策略绑定到环境而不是散落在 job 里。

18.3 多环境与配置注入

「轻订单」有 dev / test / pre / prod 四环境（附录A 上线节奏推演）。配置注入有两种路线，取舍如下：

企业实践首选运行时注入——「一次构建、多环境部署」能从根本上保证「测试过的就是上线的」：

<!-- index.html：在 bundle 之前加载 -->
<script src="/config.js"></script>

// public/config.js —— 不入 git；由各环境的部署系统按环境生成/覆盖
// 教学占位值，真实环境由运维注入，不含任何密钥（密钥永远在服务端）
window.__APP_CONFIG__ = {
  apiBaseUrl: 'https://api.qingorder.example.com/api/v1',
  sentryDsn: '<your-sentry-dsn>',
  release: 'dev',
}

// src/config.ts —— 应用内统一读取，带默认值兜底
interface AppConfig {
  apiBaseUrl: string
  sentryDsn: string
  release: string
}

declare global {
  interface Window { __APP_CONFIG__?: Partial<AppConfig> }
}

export const appConfig: AppConfig = {
  apiBaseUrl: 'https://api.qingorder.example.com/api/v1',
  sentryDsn: '',
  release: 'dev',
  ...window.__APP_CONFIG__,
}

构建时注入（第 17 章的 .env.*）仍可用于「与产物绑定」的值，比如构建模式、版本号；两者并存，各管各的。

18.4 Docker + Nginx：静态部署与 SPA 回退

SPA 只有一个 index.html，用户直接访问 /orders/QO1 刷新时服务器找不到这个文件——必须回退到 index.html。多阶段 Docker 构建把「构建环境」与「运行环境」分离，最终镜像只有 Nginx + 静态产物：

# Dockerfile
FROM node:20-alpine AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

# nginx.conf —— 静态站的四条铁律都在这里
server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;

  # 1. 带 hash 的静态资源：内容不变则永久缓存
  location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
  }

  # 2. sourcemap 永不出网（第 17 章红线 + 18.6 配合）
  location ~* \.map$ { return 404; }

  # 3. SPA 回退 + HTML 永不缓存（发版后用户立即拿到新入口）
  location / {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "no-cache";
  }

  # 4. 文本压缩（gzip 兜底，有条件上 brotli 模块）
  gzip on;
  gzip_types text/css application/javascript application/json image/svg+xml;
  gzip_min_length 1k;

  # 基础安全头
  add_header X-Content-Type-Options nosniff;
  add_header X-Frame-Options SAMEORIGIN;
}

本地验证：docker build -t qingorder-web . && docker run -p 8080:80 qingorder-web，浏览器直访 http://localhost:8080/orders/whatever 刷新，不 404 即回退生效。

18.5 灰度发布与回滚

18.2 的「版本目录 + current 符号链接」结构让灰度和回滚都变成一次软链切换：

# 服务器目录结构：每个版本一个目录，current 指向当前版本
/srv/qingorder/
├── releases/
│   ├── a1b2c3...   # 上一版
│   └── d4e5f6...   # 最新版（灰度中）
└── current -> releases/a1b2c3...

# 灰度：带灰度 cookie 的用户访问新版本，其余用户走稳定版
map $cookie_qo_gray $root_dir {
  default /srv/qingorder/current;                  # 稳定版
  "on"    /srv/qingorder/releases/d4e5f6...;       # 灰度版（部署脚本写入具体版本号）
}
server {
  root $root_dir;
  # …其余配置同 18.4
}

放量节奏推荐：内部员工（发灰度 cookie）→ 5% → 50% → 100%，每档观察 30 分钟监控大盘。回滚则是秒级动作：

# rollback.sh —— 回滚 = 把 current 指回上一个版本 + reload
ln -sfn /srv/qingorder/releases/a1b2c3... /srv/qingorder/current
nginx -s reload   # Nginx 读取新软链；静态站回滚无需重启任何进程

演练要求：每个新接手的发布负责人，入职一周内必须在测试环境完整跑一次「发布 → 回滚」，做不到就不许碰生产。

18.6 错误监控：Sentry 接入与 sourcemap 还原

接入（React SDK）三步：初始化、ErrorBoundary 兜底、手动埋点。

pnpm add @sentry/react

// src/monitor/sentry.ts
import * as Sentry from '@sentry/react'
import { appConfig } from '@/config'

Sentry.init({
  dsn: appConfig.sentryDsn,             // 运行时注入（18.3），不写死
  environment: appConfig.release === 'prod' ? 'production' : appConfig.release,
  release: appConfig.release,           // 与部署版本号（git sha）对齐，还原 sourcemap 的钥匙
  tracesSampleRate: 0.2,                // 性能采样 20%，按流量成本调整
  beforeSend(event) {
    // 顺手脱敏：请求串里的 token 不进监控
    if (event.request?.query_string) delete event.request.query_string
    return event
  },
})

// src/main.tsx —— ErrorBoundary 包根组件：渲染期错误被捕获并展示兜底 UI
import { createRoot } from 'react-dom/client'
import * as Sentry from '@sentry/react'
import { App } from './App'

createRoot(document.getElementById('root')!).render(
  <Sentry.ErrorBoundary
    fallback={<ErrorPage title="页面开小差了，正在上报修复" />}
    onError={(error) => console.error('[boundary]', error)}
  >
    <App />
  </Sentry.ErrorBoundary>,
)

sourcemap 还原：压缩后的报错栈是 chunk-3f9.js:1:8842，没人看得懂。解法是构建时生成 sourcemap 并只上传给 Sentry：

// vite.config.ts —— 构建 Sentry 插件只在 CI 生效
import { sentryVitePlugin } from '@sentry/vite-plugin'

export default defineConfig({
  build: {
    // 'hidden'：生成 .map 但产物 JS 不引用它——用户侧不可见，Sentry 可上传
    sourcemap: process.env.CI ? 'hidden' : false,
  },
  plugins: [
    react(),
    process.env.CI && sentryVitePlugin({
      org: 'qingtech',
      project: 'qingorder-web',
      authToken: process.env.SENTRY_AUTH_TOKEN, // CI secrets 注入，绝不写进仓库
    }),
  ].filter(Boolean),
})

双保险缺一不可：sourcemap: 'hidden'（产物不含引用）+ Nginx location ~* \.map$ { return 404; }（18.4，物理拒绝下载）。生产 sourcemap 泄漏等于公开源码，这是监控接入时最容易出也最危险的事故。

18.7 性能埋点与白屏检测

性能埋点复用第 14 章的 web-vitals 采集，把上报目标从自建接口换成监控平台（示例继续用自建接口，生产可替换为 Sentry 自定义指标或专用 RUM 平台）。

白屏检测：SPA 最严重的故障形态是「页面 200 但内容为空」（JS 报错、接口失败、版本错配都可能）。用「关键时机 + 一次性判定」实现：

// src/monitor/blank-screen.ts
import { appConfig } from '@/config'
import { reportEvent } from './reporter'

export function initBlankScreenDetection() {
  const check = () => {
    const root = document.querySelector('#root')
    const isBlank = !root || root.childElementCount === 0
    if (isBlank) {
      reportEvent('blank_screen', {
        url: location.href,
        release: appConfig.release,
        userAgent: navigator.userAgent,
      })
    }
  }

  // 两个时机各查一次：load（资源就绪）+ load 后 3s（异步渲染兜底），均只判一次
  window.addEventListener('load', () => { check(); window.setTimeout(check, 3000) })
  // 资源加载失败（chunk 404 是白屏高发原因）也作为信号
  window.addEventListener('error', (e) => {
    const target = e.target as HTMLElement | null
    if (target && (target.tagName === 'SCRIPT' || target.tagName === 'LINK')) {
      reportEvent('resource_error', { src: (target as HTMLScriptElement).src, release: appConfig.release })
    }
  }, true) // 捕获阶段才能拿到资源加载错误
}

注意两点：判定用事件驱动（load/error），不是轮询 DOM（省性能也不误报）；上报带上 release，能直接回答「哪个版本引入的白屏」。

18.8 告警策略与响应 SOP

监控的终点不是看板，是「对的人在对的时间被叫醒」。给「轻订单」定的告警阈值（按 p75 / 全量错误率，初期从宽、稳定后收紧）：

响应 SOP 五步（写成值班手册，不是口头传统）：

1. 发现（分钟级）：告警触达值班人；先看 Sentry issue 的 release 与告警时间是否吻合新版本；
2. 定位（5 分钟内）：issue 聚合的报错栈（sourcemap 还原后的）+ 影响用户数 + 白屏率三项定级；确认是新版本引入还是存量问题爆发；
3. 止损（10 分钟内）：新版本引入且影响面大 → 执行 18.5 回滚（秒级），先恢复再排查；定位不清但错误持续 → 同样回滚；
4. 修复：在测试环境复现 → 按第 15 章纪律「先写失败测试再修」→ 走完整流水线重新发布；
5. 复盘（48 小时内）：一页纸复盘（时间线 / 根因 / 为什么测试没拦住 / 行动项），行动项落进 backlog 追踪。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）

任务描述：为「轻订单」仓库编写 quality job（18.2 的前 8 个 step），在 PR 上触发，并故意制造一次 typecheck 失败验证流水线真的会红。

提示：pnpm/action-setup 与 setup-node 的 cache: pnpm 缓存第二次运行才命中；本地验证可用 act 或直接推一个测试分支。

验收标准：PR 上流水线全绿；把 formatAmount 的参数类型改成 string 后 push，流水线在 typecheck 步骤失败且日志可读；还原后恢复绿。

name: quality
on: [pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 9 }
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint && pnpm typecheck && pnpm test:ci

练习 2 · 进阶（30–60 min）

任务描述：编写 Dockerfile 与 nginx.conf（18.4），本地 docker build + docker run 后完成三项验证：① 直访 http://localhost:8080/orders/QO20260929000001 刷新不 404（SPA 回退）；② DevTools Network 里 assets/* 响应头含 immutable，index.html 含 no-cache；③ 请求任意 .map 文件返回 404。

提示：.dockerignore 里排除 node_modules 与 dist，否则构建上下文巨大；验证缓存头用 curl -I 更快。

验收标准：三项验证全部通过并把 curl -I 结果贴进练习记录；镜像体积 < 100MB（nginx:alpine + 静态产物）。

node_modules
dist
coverage
playwright-report
.git

docker build -t qingorder-web .
docker run -d -p 8080:80 --name qo-web qingorder-web
curl -I http://localhost:8080/orders/QO20260929000001   # HTTP 200，Cache-Control: no-cache
curl -I http://localhost:8080/assets/                   # 任意真实资源：immutable
curl -I http://localhost:8080/assets/whatever.js.map    # HTTP 404

练习 3 · 挑战（选做，60+ min）

任务描述：完成一次「发布 → 告警 → 回滚 → 复盘」全链路演练：接好 deploy job（secrets 用占位值在本机演练）与 Sentry；故意在 pre 环境发布一个「点击提交订单必报错」的版本，观察 Sentry 告警（release 字段对齐），执行回滚脚本，最后写一页复盘（SOP 五步格式）。

提示：Sentry 免费额度足够教学使用，DSN 用 appConfig.sentryDsn 运行时注入；演练环境的「必报错版本」可以在提交按钮 onClick 里 throw new Error('drill: intentional')，标签注明 drill 用完即删。

验收标准：Sentry issue 携带还原后的源码栈（sourcemap 生效）且 release 显示演练版本号；从告警触达到回滚完成 < 15 分钟；复盘文档含时间线、根因、测试缺口、行动项四节，存 docs/qa/drill-2026Q4.md。

#!/usr/bin/env bash
# scripts/rollback.sh <release-sha>
set -euo pipefail
TARGET="/srv/qingorder/releases/${1:?usage: rollback.sh <release-sha>}"
[ -d "$TARGET" ] || { echo "版本不存在: $TARGET"; exit 1; }
ln -sfn "$TARGET" /srv/qingorder/current
nginx -s reload
echo "已回滚至 $1，请立即观察监控大盘确认错误率回落"

⚠️ 常见易错点

易错点 1：生产环境 sourcemap 直接暴露，等于公开源码

// ❌ sourcemap: true 直接部署：.map 文件任何人可下载，
//    DevTools 里能看到全部业务源码，商业逻辑与接口结构一并泄露
build: { sourcemap: true }

// ✅ hidden 模式 + Nginx 拒绝 .map + 只上传 Sentry：报错栈可还原，公网拿不到
build: { sourcemap: process.env.CI ? 'hidden' : false },
// nginx.conf: location ~* \.map$ { return 404; }

验证方法：发布后 curl -I https://web.qingorder.example.com/assets/xxx.js.map，必须 404。

易错点 2：密钥写进工作流文件或构建日志，secrets 形同虚设

# ❌ 凭据硬编码进 yaml（会进 git 历史）；或 debug 时 echo 出来（进构建日志人人可见）
deploy:
  run: |
    echo "password=<your-password>"    # 形式上像假值，但硬编码行为本身已泄漏，立即轮换
    scp -o StrictHostKeyChecking=no ...

# ✅ 一律 secrets.* 注入 env；日志脱敏；万一泄漏第一步是轮换而不是删除提交
deploy:
  env:
    SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
  run: |
    echo "$SSH_KEY" > deploy_key && chmod 600 deploy_key   # 写文件而非 echo 到日志

规则：CI 日志、错误监控、前端产物三个地方，任何密钥字面量出现即为 P0 事故，处置顺序是先轮换后清理。

易错点 3：index.html 强缓存，发版后用户拿到旧入口指向已删除的 chunk

# ❌ 对整站一刀切强缓存：新版发布删除旧 chunk 后，
#    老用户缓存的 index.html 仍引用已 404 的 chunk → 白屏
location / { add_header Cache-Control "public, max-age=31536000"; }

# ✅ 缓存策略按文件类型分层：哈希资源永久缓存，HTML 必须每次协商缓存
location /assets/ { add_header Cache-Control "public, max-age=31536000, immutable"; }
location /        { try_files $uri $uri/ /index.html; add_header Cache-Control "no-cache"; }

配套保险：发布脚本保留最近 2 个版本的 releases 目录（不立刻删旧 chunk），给「标签页开了一整天的用户」留缓冲期。

易错点 4：白屏检测靠轮询 DOM，既费性能又误报

// ❌ setInterval 每 200ms 查一次 #root：常驻定时器拖性能；
//    且在应用「本来就该空」的时刻（路由切换中）误报
setInterval(() => {
  if (document.querySelector('#root')!.childElementCount === 0) reportBlank()
}, 200)

// ✅ 事件驱动 + 关键时机一次性判定：零常驻开销，误报可控（见 18.7 实现）
window.addEventListener('load', () => { check(); window.setTimeout(check, 3000) })
window.addEventListener('error', reportResourceError, true) // 捕获阶段拿资源错误

易错点 5：发布后没有版本标识，出问题不知道线上是哪一版

// ❌ 无版本注入：Sentry issue 里 release 为空，用户截图只有「线上坏了」，
//    团队第一句永远是「现在线上到底是哪个版本？」

// ✅ release 贯穿三处：部署目录名（git sha）、config.js、Sentry.init——同一把钥匙
// deploy job: RELEASE: ${{ github.sha }} → /srv/qingorder/releases/$RELEASE
// config.js : { release: 'd4e5f6...' }（部署时写入）
// sentry.ts : release: appConfig.release → issue 可按版本过滤、sourcemap 可按版本还原

排查效率的分水岭就在这里：有 release 的团队 5 分钟定位「哪版引入」，没有的团队靠回忆和抽签。

✅ 最佳实践

1. 流水线是发布唯一通道：任何「紧急直推服务器」都在制造不可回溯的版本，紧急需求走加速审批而不是绕过 CI。
2. 一次构建、多环境部署：运行时注入 config.js，保证测试过的产物与上线产物字节级一致。
3. 缓存分层铁律：哈希资源 immutable、HTML no-cache、旧版本保留 2 个发布周期，三者缺一就会复现「发版白屏」。
4. 回滚先于修复：止损目标 10 分钟，回滚是脚本不是操作指南；每个发布负责人必须演练过一次。
5. sourcemap 双保险：hidden + Nginx 拒绝 .map，Sentry 是唯一读者。
6. release 字段贯穿全链路：部署目录、config、Sentry 对齐同一 git sha，版本可问、可查、可回滚。
7. 告警必须带行动：每条告警阈值都对应 SOP 的一步动作；天天响却没人理的告警等于已下线，要么修阈值要么删掉。
8. 演练常态化：回滚演练（新人必做）+ 故障演练（每季度一次），SOP 写下来只是第一步，跑起来才算数。

📌 本章小结

• 流水线五段式（lint → typecheck → test → build → deploy）把第 13–17 章的质量资产变成机器铁律；PR 挡质量、主干管交付。
• 配置注入首选运行时 config.js：一次构建多环境部署，测试过的就是上线的。
• Docker + Nginx 四铁律：SPA 回退、资源 immutable、HTML no-cache、sourcemap 拒绝外泄。
• 版本目录 + 软链切换让灰度放量与秒级回滚成为日常；release 字段贯穿部署、配置、监控三方。
• 监控三面：Sentry 错误（ErrorBoundary + sourcemap 还原）、web-vitals 性能、白屏检测；告警阈值与 SOP 五步（发现→定位→止损→修复→复盘）让监控真正闭环。
• 至此附录A §6 高级阶段目标全部交付：万级列表达标（13 章）、门户 LCP 1.8s（14 章）、核心模块覆盖率 ≥ 80%（15 章）、E2E 冒烟集通过（16 章）、TS 与规范链路（17 章）、发布与监控体系（本章）。完成 阶段自查 · 高级能力清单 的 30 分钟自测后，即可进入 第四部分 · 资深阶段——那里的问题是「系统该怎么长」，而不再只是「代码该怎么写」。

📄 第 19 章 · 大型项目架构设计 19-大型项目架构设计.md✓ 标记已学

📍 阶段：资深阶段（第 19–24 章）｜⏱ 预计学时：8–10 小时｜🔗 前置：第 12 章实战 + 第 17 章工程化 + 第 18 章 CI/CD

⬅ 上一章：CI/CD 部署与前端监控 ｜ 📖 本版目录 ｜ ➡ 下一章：设计系统与组件库建设

💡 对照学习：本页是 React 版第 19 章，对应 Vue 版第 19 章 · 大型项目架构设计。本章方法两版通用，示例代码为 React 生态：复杂度评估、分层与依赖规则、初始化编排、ADR 决策记录都是与框架无关的方法论；生态差异仅在于示例使用 React Router 7（≈ Vue Router 4）、Redux Toolkit/Zustand（≈ Pinia）、TanStack Query v5（≈ Vue 适配版 TanStack Query）。

进入资深阶段，问题从「代码怎么写」升级为「系统怎么长」。本章用「轻订单」完成第一次架构演进：从第 12 章的单体 admin，演进为分层清晰、依赖可约束、决策可追溯的多模块工程。先学评估，再学拆分——顺序不能反。

🎯 学习目标

学完本章，你将能够：

1. 用「业务复杂度评估表」对一个真实前端项目做出架构分区判断，并说出「单体分区 / 模块化单体 / 微前端」三条路线的触发条件；
2. 按 app / pages / widgets / features / entities / shared 分层组织 React 项目目录，并为每一层写出「能依赖谁」的规则；
3. 配置 ESLint 边界规则（eslint-plugin-boundaries），让跨层 import 在本地与 CI 阶段直接报错；
4. 制定大型 React 应用的路由层、状态层、请求层组织约定：路由片段按业务域拆分、状态三分法、queryKey 工厂；
5. 实现应用初始化编排：把配置加载、会话探测、字典预取收敛为显式 bootstrap() 流程，并区分「阻塞挂载」与「后台预取」；
6. 用插件化方式抽离埋点、监控等横切关注点，做到业务代码零侵入；
7. 在 pnpm workspace 中规划多包结构（apps/ + packages/），配置内部包引用并说明 source 引用与产物引用的取舍；
8. 使用 ADR 模板记录架构决策，产出两份可直接归档的决策文档（状态库选 Zustand、服务端状态引入 TanStack Query）。

📖 核心知识点

19.1 什么时候需要谈架构：业务复杂度评估法

架构不是简历素材，是对复杂度的响应。复杂度没到，任何「高级结构」都是负债；复杂度到了，没有结构就是灾难。动手拆分前，先量化五个维度：

把五个分数相加（8–15 分），对照决策矩阵选路线：

总分 8–10  ──►  单体 + 目录分区（第 12 章的做法已经够用，重点是纪律）
总分 11–13 ──►  模块化单体：分层 + 依赖规则 + 按业务域切片（本章主角）
总分 14–15 ──►  模块化单体已到收益上限，评估微前端（先过第 21 章「要不要拆」清单）

任一单项打满 3 分且与跨团队相关（如「多团队并行交付同一仓库」）
          ──►  无论总分，优先考虑物理隔离（独立仓库 + 微前端聚合，见第 21 章）

轻订单现状盘点（对照附录A §3）：admin 已有认证、工作台、订单、客户、商品、报表、系统设置 7 个一级模块，核心实体 4 个（订单/客户/商品/用户），团队 6 人且运营侧需求月均 25+ 个，近一个月发生 2 次「改商品模块弄坏订单列表」。逐项打分：2 + 2 + 2 + 2 + 2 = 10 分——处在「单体分区」与「模块化单体」的临界点。而未来 3 个月确定要接入第三方营销子系统（跨团队、独立发布节奏），复杂度即将上台阶。结论：现在做模块化单体改造，为第 21 章的微前端留好接缝。

⚠️ 这一步的产出物（评分表 + 结论）应当写进 ADR 或方案文档归档，而不是停留在口头。「为什么拆」比「怎么拆」更值得记录。

19.2 分层架构：功能切片 × 依赖规则

模块化单体的经典组织方式是两条正交的轴：横切面分「技术层」，纵切面按「业务域」切片。业界通行的分层参考（源自 Feature-Sliced Design 等方法，层名通用）：

┌─────────────────────────────────────────────────────────┐
│  app      应用装配层：providers、bootstrap、全局路由汇总    │  ← 只做装配，无业务
├─────────────────────────────────────────────────────────┤
│  pages    页面层：路由出口、页面级拼装（薄）                 │
├─────────────────────────────────────────────────────────┤
│  widgets  业务组合块：跨 feature 的复合区块                 │
│           （订单时间线、审批面板、工作台待办）               │
├─────────────────────────────────────────────────────────┤
│  features 用户操作单元：一个完整交互闭环                    │
│           （新建订单、折扣审批、登录、批量导出）             │
├─────────────────────────────────────────────────────────┤
│  entities 业务实体层：领域模型 + 实体级读写                  │
│           （order、customer、product、user）               │
├─────────────────────────────────────────────────────────┤
│  shared   技术基座：与业务无关（api 基座、ui 基件、lib 工具） │
└─────────────────────────────────────────────────────────┘

依赖铁律：只能「向下」依赖，禁止「向上」与「跨层跳跃」。
同级之间：features 之间不互相 import（需要共享就上提 widgets 或下沉 entities）。

落到轻订单 admin，目录树长这样（与第 12 章的单体结构对比，变化是每个业务域有了自己的领地）：

apps/admin/src
├── app/
│   ├── bootstrap.ts          # 初始化编排（§19.5）
│   ├── providers.tsx         # Router/Query/Theme/Store Provider 组合
│   ├── routes.tsx            # 汇总各 pages 的路由片段
│   └── store.ts              # configureStore 汇总各 slice
├── pages/
│   ├── orders/               # 订单列表/详情页（薄壳：拼装 widgets/features）
│   │   ├── OrderListPage.tsx
│   │   ├── OrderDetailPage.tsx
│   │   └── routes.tsx
│   ├── dashboard/
│   └── settings/
├── widgets/
│   ├── order-timeline/       # 操作日志时间线：详情页与工作台待办共用
│   └── approval-panel/       # 折扣审批面板：财务视角
├── features/
│   ├── order-create/         # 新建订单：表单 + 提交 + 乐观更新
│   │   ├── ui/OrderCreateForm.tsx
│   │   ├── model/orderCartSlice.ts
│   │   └── index.ts          # 公共出口（Public API）
│   ├── order-approve/
│   ├── order-export/
│   └── auth-login/
├── entities/
│   ├── order/
│   │   ├── model/types.ts        # Order / OrderStatus（附录A §5 口径）
│   │   ├── model/statusMachine.ts # 状态机规则（哪些流转合法）
│   │   ├── model/queryKeys.ts    # queryKey 工厂（§19.4）
│   │   ├── api/orderApi.ts
│   │   └── index.ts
│   ├── customer/
│   └── product/
└── shared/
    ├── api/                  # axios 实例、拦截器、错误归一化（第 09 章产出）
    ├── ui/                   # Button/Table 基件（第 20 章上提为 qing-ui）
    ├── lib/                  # 金额计算（分单位）、日期、权限判断
    └── config/               # 环境变量与常量

每层「能依赖谁」用一张表钉死，并立刻翻译成机器可执行的 ESLint 规则：

// eslint.config.js（flat config 片段）—— 违反依赖规则 = lint error = CI 红灯
import boundaries from 'eslint-plugin-boundaries';

export default [
  // ...其他配置
  {
    plugins: { boundaries },
    settings: {
      'boundaries/include': ['src/**/*.{ts,tsx}'],
      'boundaries/elements': [
        { type: 'app',      pattern: 'src/app/**' },
        { type: 'pages',    pattern: 'src/pages/**' },
        { type: 'widgets',  pattern: 'src/widgets/**' },
        { type: 'features', pattern: 'src/features/**' },
        { type: 'entities', pattern: 'src/entities/**' },
        { type: 'shared',   pattern: 'src/shared/**' },
      ],
    },
    rules: {
      'boundaries/element-types': ['error', {
        default: 'disallow',
        message: '${file.type} 不允许依赖 ${dependency.type}（依赖规则见 docs/architecture.md）',
        rules: [
          { from: 'app',      allow: ['pages', 'widgets', 'features', 'entities', 'shared'] },
          { from: 'pages',    allow: ['widgets', 'features', 'entities', 'shared'] },
          { from: 'widgets',  allow: ['features', 'entities', 'shared'] },
          { from: 'features', allow: ['entities', 'shared'] },
          { from: 'entities', allow: ['shared'] },
          { from: 'shared',   allow: ['shared'] },
        ],
      }],
    },
  },
];

两个配套纪律让规则真正生效：① 每个切片只暴露一个 index.ts（Public API），外部只允许从出口导入，内部文件路径不外泄——重构内部实现时不会波及调用方；② features 之间禁止互相 import 是最容易破也最值得守的一条，破口一开就退化回面条单体。

19.3 路由层组织：路由片段按业务域拆分

路由是 pages 层的「目录索引」。约定三条：① 每个业务域导出自己的路由片段；② 页面组件一律 React.lazy 懒加载（第 14 章的分包策略，按域分包正好对齐）；③ 权限元信息（菜单、面包屑、守卫）继续沿用第 07 章的「元信息配置表」，路由片段只负责结构。

// src/pages/orders/routes.tsx —— 订单域路由片段
import { lazy, Suspense } from 'react';
import { Route } from 'react-router';
import { PageSkeleton } from '@/shared/ui/PageSkeleton';
import { RequireAuth } from '@/features/auth-login/RequireAuth'; // 第 11 章的守卫组件

const OrderListPage = lazy(() => import('./OrderListPage'));
const OrderDetailPage = lazy(() => import('./OrderDetailPage'));

export const orderRoutes = (
  <Route path="orders" element={<RequireAuth roles={['operator', 'sales', 'finance', 'super_admin']} />}>
    <Route index element={<Suspense fallback={<PageSkeleton />}><OrderListPage /></Suspense>} />
    <Route path=":orderId" element={<Suspense fallback={<PageSkeleton />}><OrderDetailPage /></Suspense>} />
  </Route>
);

// src/app/routes.tsx —— app 层只做汇总，一眼看清全站路由地图
import { Routes, Route, Navigate } from 'react-router';
import { AdminLayout } from './AdminLayout';
import { orderRoutes } from '@/pages/orders/routes';
import { dashboardRoutes } from '@/pages/dashboard/routes';
import { settingsRoutes } from '@/pages/settings/routes';

export function AppRoutes() {
  return (
    <Routes>
      <Route element={<AdminLayout />}>
        {orderRoutes}
        {dashboardRoutes}
        {settingsRoutes}
      </Route>
      <Route path="*" element={<Navigate to="/orders" replace />} />
    </Routes>
  );
}

新增一个业务域 = 新建一个 pages 目录 + 导出一个路由片段 + 在 app/routes.tsx 加一行。路由对「这个域有哪些页面、什么角色能进」的回答是局部的，不用全仓搜索。

19.4 状态层组织：三分法 + slice 就近 + queryKey 工厂

第 08 章的三分法在大型项目里升格为硬性归置约定：

第一条纪律是slice/store 就近放置：订单暂存区的 slice 不放全局 store/ 目录，而放在 features/order-create/model/ 里，由 app/store.ts 聚合。删掉一个 feature = 删掉一个目录，状态随之干净。

// src/features/order-create/model/orderCartSlice.ts —— slice 就近
import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
import type { OrderItem } from '@/entities/order';

interface OrderCartState {
  customerId: string | null;
  items: OrderItem[];
}

const initialState: OrderCartState = { customerId: null, items: [] };

export const orderCartSlice = createSlice({
  name: 'orderCart',
  initialState,
  reducers: {
    pickCustomer(state, action: PayloadAction<string>) {
      state.customerId = action.payload;
    },
    addItem(state, action: PayloadAction<OrderItem>) {
      state.items.push(action.payload);
    },
    removeItem(state, action: PayloadAction<string>) {
      state.items = state.items.filter((it) => it.skuId !== action.payload);
    },
  },
});

第二条纪律是服务端态绝不进 Redux，统一走 Query，并且 key 必须经由工厂函数生成——散落的字符串 key 是缓存失效（invalidate）失效的第一根源：

// src/entities/order/model/queryKeys.ts —— queryKey 工厂
import type { OrderListFilters } from '../api/orderApi';

export const orderKeys = {
  all: ['orders'] as const,                                   // 域根：一键失效全域
  lists: () => [...orderKeys.all, 'list'] as const,
  list: (filters: OrderListFilters) => [...orderKeys.lists(), filters] as const,
  details: () => [...orderKeys.all, 'detail'] as const,
  detail: (id: string) => [...orderKeys.details(), id] as const,
  timeline: (id: string) => [...orderKeys.detail(id), 'timeline'] as const,
};

// 使用侧：失效「该订单的一切」只需一句话
import { useQueryClient } from '@tanstack/react-query';

const qc = useQueryClient();
await qc.invalidateQueries({ queryKey: orderKeys.detail(orderId) });
// 列表、详情、时间线全部标记过期并按需重取——不需要记住每一个 key 的字符串长什么样

19.5 请求层组织：基座 + 领域 API

请求层延续第 09 章的产出，只增加两条归置约定：① shared/api 只放「协议能力」（axios 实例、token 注入、40102 无感刷新、错误归一化），不知道任何业务路径；② 各实体的接口定义收敛到 entities/*/api/，feature 层不直接拼 URL。

// src/entities/order/api/orderApi.ts —— 领域 API：入参出参全类型化
import { http } from '@/shared/api/http';
import type { Order, OrderStatus } from '../model/types';

export interface OrderListFilters {
  keyword?: string;
  status?: OrderStatus;
  dateFrom?: string;
  dateTo?: string;
  page: number;
  pageSize: number;
}

export interface PageResult<T> {
  list: T[];
  total: number;
  page: number;
  pageSize: number;
}

export function fetchOrderList(filters: OrderListFilters) {
  return http.get<PageResult<Order>>('/orders', { params: filters });
}

export function fetchOrderDetail(orderId: string) {
  return http.get<Order>(`/orders/${orderId}`);
}

export function updateOrderStatus(orderId: string, action: 'submit' | 'approve' | 'ship' | 'cancel', reason?: string) {
  return http.post<Order>(`/orders/${orderId}/${action}`, { reason });
}

19.6 应用初始化编排与插件化

单体项目最常见的隐形债：初始化逻辑散落在各个模块文件顶层——dict.ts 一 import 就发请求、埋点 SDK 在 main.tsx 之前已经偷偷加载。后果是启动顺序不可控、失败无从降级、测试无法隔离。解法是把「应用启动」收敛为一个显式编排函数，同时把横切关注点做成插件。

bootstrap() 启动编排时序（阻塞 vs 后台，一图定分晓）
────────────────────────────────────────────────────────────
① loadRuntimeConfig()        阻塞  读 window.__APP_CONFIG__（第 18 章运行时注入）
② await probeAuthSession()   阻塞  会话探测，失败 → 匿名态（不白屏，路由守卫接管）
③ initPlugins(config)        同步  埋点/监控/权限插件注册（§19.6 下方）
④ mountApp()                 挂载  用户此刻看到骨架屏 ← 阻塞到此为止
⑤ preloadDicts()             后台  字典预取，失败 toast 降级，不阻塞首屏
────────────────────────────────────────────────────────────
原则：影响「能否渲染」的才阻塞；影响「数据全不全」的一律后台 + 降级。

// src/app/bootstrap.ts —— 显式启动编排
import { loadRuntimeConfig, type RuntimeConfig } from './config';
import { probeAuthSession, type AuthSession } from '@/entities/user/session';
import { initPlugins } from './plugins';
import { mountApp } from './mount';
import { preloadDicts } from '@/entities/dict/api';

export async function bootstrap(): Promise<void> {
  const config: RuntimeConfig = loadRuntimeConfig();          // ① 同步读取，失败即 fail-fast
  const session: AuthSession = await probeAuthSession();       // ② 静默失败 → 匿名态，绝不抛出
  initPlugins(config, session);                                // ③ 插件注册（埋点/监控/权限）
  mountApp(config, session);                                   // ④ 挂载，用户看到 UI
  void preloadDicts().catch((err) => console.warn('字典预取失败，进入懒加载降级', err)); // ⑤ 后台
}

// src/app/plugins/types.ts —— 插件契约：横切关注点的统一入口
export interface PluginContext {
  config: RuntimeConfig;
  session: AuthSession;
}

export interface AppPlugin {
  name: string;
  setup(ctx: PluginContext): void;
}

// src/app/plugins/index.ts —— 注册表：新增横切能力 = 加一行，业务代码零改动
import { trackingPlugin } from './tracking';
import { monitoringPlugin } from './monitoring';
import type { AppPlugin, PluginContext } from './types';

const plugins: AppPlugin[] = [trackingPlugin, monitoringPlugin];

export function initPlugins(config: RuntimeConfig, session: AuthSession): void {
  const ctx: PluginContext = { config, session };
  for (const p of plugins) {
    try {
      p.setup(ctx);
    } catch (err) {
      console.error(`插件 ${p.name} 初始化失败（不阻塞启动）`, err);
    }
  }
}

对比一下：改造前埋点调用散落在 23 个组件里（track('order_submit') 手写 23 次）；改造后在 trackingPlugin 里统一给 axios 挂拦截器、给路由挂 afterEach 钩子，业务代码一行不改。这就是插件化的价值——新横切关注点（如未来接入 A/B 实验 SDK）只是注册表里的一个新条目。

19.7 Monorepo 多包策略：为共享资产留位置

分层解决了「仓库内」的秩序，Monorepo 解决「跨应用」的复用：门户 portal 与后台 admin 要共享设计令牌、HTTP 基座、领域类型，第 20 章的 qing-ui 也要有独立的家。pnpm workspace 是成本最低的方案：

# pnpm-workspace.yaml —— 仓库根目录
packages:
  - 'apps/*'       # portal / admin；第 21 章的 marketing 壳也落在这里
  - 'packages/*'   # qing-ui / shared-types / api-base ……

// packages/qing-ui/package.json —— 内部包：source 引用（内部应用推荐）
{
  "name": "@qing/ui",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": "./src/index.ts",
    "./tokens.css": "./src/tokens.css"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

// apps/admin/package.json（节选）—— workspace:* 永远指向工作区内的包
{
  "name": "@qing/admin",
  "dependencies": {
    "@qing/ui": "workspace:*",
    "@qing/shared-types": "workspace:*"
  }
}

内部包有两种引用策略，取舍要写进约定：

// vite.config.ts（apps/admin，节选）—— workspace 包无需特殊配置，
// Vite 6 对 pnpm workspace 链接的包默认走源码编译；如遇特殊包再显式声明：
export default defineConfig({
  resolve: { alias: { '@': '/src' } },
});

Monorepo 的纪律只有两条，却决定成败：① 依赖方向单一——packages/ 不允许 import 任何 apps/ 的代码，方向反了复用立刻变纠缠；② 公共代码进包前先在应用内生长——被两个应用用到第三次才下沉，避免造出没人用的「假共享层」。

19.8 ADR：把架构决策变成可追溯的文档

ADR（Architecture Decision Record）是一篇 300 字左右的小文档，回答一个问题：当时为什么这么定。半年后新人问「为什么新代码用 Zustand 而存量是 Redux」，你不用再翻聊天记录。模板固定五段：

# ADR-<编号> · <一句话决策>

- **状态**：提议 / 已接受 / 已废弃（被 ADR-XXX 取代）
- **日期 / 决策人**：
- **关联**：受影响的其他 ADR

## 背景与问题
两三段说清「遇到了什么问题、约束是什么」。只写事实，不写情绪。

## 备选方案
表格列出 2–3 个候选，各自优点与代价——「没有备选的决策」通常意味着没有思考。

## 决策
选了什么，附加哪些约束条件（重要：决策常伴随约束，约束是方案的一部分）。

## 后果
正面收益 / 负面代价都要写；给出「回顾触发条件」——出现什么信号时重开此决策。

样例一：轻订单 ADR-008（状态库）——它演示了如何处理「存量与增量不一致」的现实约束：

# ADR-008 · 客户端状态库：新增模块统一采用 Zustand，存量 Redux 保留

- **状态**：已接受（2026-04-08）
- **决策人**：前端组 6 人 + 技术负责人
- **关联**：ADR-004（中级阶段引入 Redux Toolkit）、ADR-009（服务端状态迁移 TanStack Query）

## 背景与问题
ADR-009 落地后，Redux 承担的服务端缓存职责已移交给 TanStack Query，剩余
slice（登录用户态、字典缓存、订单暂存区）都是轻量客户端态。继续用 RTK
意味着每个新模块都要写 slice + thunk 样板；而查询类页面越来越多，样板占比
明显上升。同时团队即将扩编 2 人，新人上手成本需要纳入考量。

## 备选方案
| 方案 | 优点 | 代价 |
|------|------|------|
| A. 维持全 RTK | 单一技术栈、DevTools 强、中间件生态成熟 | 样板代码多；轻状态书写繁琐 |
| B. 新增模块用 Zustand，存量保留 | 增量零迁移成本；Zustand 无 Provider、样板极少 | 双库共存的心智成本；状态分散两处 |
| C. 全量迁移到 Zustand | 长期单一栈 | 26 个存量 slice 迁移约 3 人周，业务高峰期不可行 |

## 决策
选 B，附加三条约束：
1. Zustand 仅用于「纯客户端态」；任何服务端数据一律 TanStack Query（ADR-009）；
2. 禁止在 Zustand store 内发请求绕过 Query；
3. 新模块评审时由 reviewer 检查状态归置是否符合 §19.4 三分法。

## 后果
- 正面：新模块状态代码量约减半；新人 1 天内可独立写 store。
- 负面：仓库同时存在两套范式，onboarding 手册需增加「何时用哪个」一节（第 22 章落地）。
- 回顾触发条件：若 6 个月内出现 ≥3 次「Zustand 模块需要 Redux 级中间件能力」的真实诉求，重开本 ADR。

样例二：轻订单 ADR-009（请求库）——它演示了「痛点驱动」的论证方式，注意每一条后果都能追溯到附录A的具体痛点：

# ADR-009 · 服务端数据管理统一引入 TanStack Query v5

- **状态**：已接受（2026-03-20）
- **决策人**：前端组 6 人 + 技术负责人
- **关联**：ADR-008、第 09 章接口层设计

## 背景与问题
高级阶段性能治理（第 13 章）与监控（第 18 章）暴露出三类重复实现的手写逻辑：
1. 订单列表翻页/筛选的竞态控制靠 AbortController 手写，三个页面三份实现，监控
   归因到「旧响应覆盖新数据」的脏数据告警 2 起；
2. 提交订单后需要手动 refetch 列表与详情，漏掉一处就出现「审核通过了列表还
   显示待审核」的客诉；
3. 每个列表页各自维护 loading/error/分页 state，加起来 400+ 行高度相似代码。

## 备选方案
| 方案 | 优点 | 代价 |
|------|------|------|
| A. 继续手写 hooks | 零依赖 | 三类问题持续复发；人力成本随页面数线性增长 |
| B. RTK Query | 与存量 RTK 同构 | 强绑定 Redux；缓存生命周期控制粒度粗 |
| C. TanStack Query v5 | 独立于状态库；缓存/失效/乐观更新/竞态开箱即用；社区事实标准 | 新概念学习成本（约 2 天）；需配套 queryKey 规范 |

## 决策
选 C。约束：
1. queryKey 一律经实体层工厂生成（见 §19.4），禁止裸字符串 key；
2. 服务端类型定义收敛在 entities/*/api，与后端 OpenAPI 对齐（第 22 章契约）；
3. 存量手写 hooks 按「改哪个页面迁哪个」的节奏渐进替换，不设一刀切死线。

## 后果
- 正面：三类手写逻辑归零；乐观更新在订单审核场景上线后审批列表交互明显顺滑；
  团队预计节省的维护成本 ≈ 每迭代 0.5 人日。
- 负面：引入约 13KB gzip 依赖；DevTools 调试面板成为团队必修项。
- 回顾触发条件：若出现「服务端数据需要复杂跨页联动派生」而 Query 表达吃力的场景超过 2 个，重评。

ADR 的存放位置固定在 docs/adr/（Monorepo 根），编号递增、只追加不修改——推翻旧决策就写新 ADR 并把旧状态改为「已废弃（被取代）」。这份不可变性正是它作为「决策日志」的价值。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）：给现状做一次「架构体检」

任务描述：打开你第 12 章产出的轻订单 admin 仓库，完成三件事：① 用 §19.1 的评估表逐项打分并得出总分与路线建议；② 画出当前 src 目录树；③ 找出 3 处以上「跨域/跨层 import」违规点（例如 pages/orders 直接 import 了 pages/customers 的组件、或 features 互相引用），列成清单。

提示：违规点可以用 grep -rn "from '@/pages" src/features 这类命令半自动排查；「list 里有几条」不重要，「知道去哪找」才重要。

验收标准：产出 docs/architecture-audit.md，含评分表（5 维度 + 总分 + 路线结论）、目录树、违规 import 清单（文件路径 + 违规原因）。

练习 2 · 进阶（30–60 min）：分层重构 + 让机器守规矩

任务描述：把练习 1 审计出的仓库重构为 §19.2 的六层结构（不必一步到位，至少完成订单域：entities/order + features/order-create + pages/orders 三个切片），每个切片提供 index.ts 公共出口；然后安装并配置 eslint-plugin-boundaries，把练习 1 的违规清单逐条修复到 lint 全绿；最后把 pnpm lint 挂进第 18 章的 CI 流水线。

提示：重构顺序自底向上——先建 entities，再迁移 features，最后改 pages；每完成一层跑一次 pnpm build 确认无回归，利用第 15 章的单测与第 16 章的冒烟 E2E 兜底。

验收标准：① 目录树与 §19.2 六层对齐；② pnpm lint 对人为制造的跨层 import 报 error（可临时写一个违规文件验证后删除）；③ CI 流水线包含 lint 门禁且通过；④ 重构后 E2E 冒烟集（登录→下单→审批→导出）保持全绿。

// src/entities/order/index.ts —— 公共出口：外部只能从这里拿东西
export type { Order, OrderItem, OrderStatus } from './model/types';
export { isTransitionAllowed, canCancel } from './model/statusMachine';
export { orderKeys } from './model/queryKeys';
export { fetchOrderList, fetchOrderDetail, updateOrderStatus } from './api/orderApi';

// src/features/order-create/index.ts
export { OrderCreateForm } from './ui/OrderCreateForm';
// 注意：orderCartSlice 不导出！它由 app/store.ts 显式聚合，
// 对外只暴露表单组件——调用方不需要知道内部用什么状态库（这是 ADR-008 的隐藏收益）

// src/app/store.ts —— 聚合点
import { configureStore } from '@reduxjs/toolkit';
import { userSlice } from '@/entities/user/model/userSlice';
import { orderCartSlice } from '@/features/order-create/model/orderCartSlice';

export const store = configureStore({
  reducer: {
    user: userSlice.reducer,
    orderCart: orderCartSlice.reducer,
  },
});

练习 3 · 挑战（选做，60+ min）：为「营销子系统接入」写第一份架构 ADR

任务描述：青云科技计划接入第三方供应商开发的「营销活动子系统」（优惠券领取页、活动报名页，供应商有自己的技术栈与发布节奏，无法合入主仓）。请撰写 ADR-011：判断营销子系统以什么形态接入（独立域名跳转 / iframe / 微前端子应用），给出备选方案对比与决策约束。本章先写「决策依据」，具体技术方案到第 21 章完成后再补充「实施附录」。

提示：评估维度至少包含——团队边界（谁维护）、发布节奏（能否同频）、视觉一致性要求、共享登录态的耦合深度、SEO 需求（营销页可能需要）。结论可以留给第 21 章推翻，但论证过程必须完整。

验收标准：产出 docs/adr/ADR-011-营销子系统接入形态.md，五段结构完整，备选 ≥3 个且各有代价分析，含「回顾触发条件」。

⚠️ 常见易错点

易错点 19-1：过度设计——为小团队上微前端 / 过早分层

❌ 错误做法：3 人团队、5 个页面的内部工具，第一周就搭 qiankun 基座 + 四层目录 + Monorepo 八个包。结果是：新人光读懂架构就要一周，改一行文案要跨三个包，构建时间翻倍——架构复杂度远超业务复杂度。

✅ 正确做法：架构分级响应复杂度（§19.1 决策矩阵）。先跑 §19.1 评估表拿分数：8–10 分用「单体 + 目录纪律」，11–13 分上分层切片，14 分以上且跨团队才谈微前端。判断标准不是「我想不想用」，而是「当前结构的痛点是否有数据支撑」——月度「改 A 坏 B」事故数、跨域 import 数、需求吞吐都是现成证据。

易错点 19-2：分层僵化——跨层 import 与「万物下沉 shared」

❌ 错误做法：features/order-create 里 import @/features/order-approve 的内部组件（feature 互引）；或者反过来，为了「复用」把只被订单模块用的组件塞进 shared/，半年后 shared 长出 40 个只有单一调用方的文件——shared 变成了「另一个 features 目录」。

✅ 正确做法：feature 间需要共享时做两个动作之一——上提（多个 feature 要用 → 升级为 widgets）或下沉（本质属于某实体 → 归入 entities）；shared/ 的准入标准是「与业务词无关」：shared/lib/money.ts（金额分转元）可以，shared/ui/OrderStatusTag 不行（它属于 entities/order/ui）。这条准入标准与 ESLint 规则一起写进 docs/architecture.md。

易错点 19-3：状态大一统——服务端缓存塞进 Redux

❌ 错误做法：把订单列表数据存进 Redux slice（orders: { list, loading, error, page }），提交审核后手动 dispatch(setList(updated)) 同步——结果审核通过了、详情页还是旧状态；换个页面又得再造一份同款 slice。

✅ 正确做法：三分法归置（§19.4）。服务端数据只活在 TanStack Query 的缓存里，提交后 invalidateQueries({ queryKey: orderKeys.all })，列表、详情、时间线同时过期重取。Redux/Zustand 只管「客户端态」。检查口诀：这个 state 的真值在数据库里吗？在 → Query。

易错点 19-4：初始化散落——import 即副作用

❌ 错误做法：dict.ts 模块顶层直接发请求（getDicts() 写在文件顶层）、埋点 SDK 在某个 util 文件 import 时自动 init。后果：测试一 import 就报网络错误；启动顺序取决于打包产物的模块执行顺序，等于把关键路径交给 bundler 抽签。

✅ 正确做法：模块只导出函数与常量，一切副作用收敛到 bootstrap() 显式编排（§19.6），并区分阻塞任务与后台任务；后台任务必须配降级路径（字典预取失败 → 使用时懒加载）。

易错点 19-5：决策靠群聊——ADR 缺位

❌ 错误做法：状态库选型在群里吵两天，最后以「 leader 说用哪个就用哪个」收场，没有留痕。半年后新人问为什么，没人答得上来，于是有人开始悄悄引入第三种方案——架构在无声中腐烂。

✅ 正确做法：任何影响「多模块/多人/超过一个迭代」的技术决策写 ADR（§19.8）。ADR 的价值不在长而在可追溯：五段结构、300 字即可，重点是备选方案的代价与「回顾触发条件」。团队约定：Code Review 中出现「为什么不用 XX」的讨论超过 10 条评论，就该沉淀一篇 ADR 了。

✅ 最佳实践

1. 先评估后动手：任何架构改造前先产出复杂度评分表，写进 ADR 或方案文档——「为什么拆」比「怎么拆」更需要被记录与挑战；
2. 依赖规则交给机器：分层写在 wiki 上没人看，写进 ESLint 才有人守；lint 门禁进 CI（第 18 章流水线），违规 PR 无法合入；
3. 每个切片一个公共出口：index.ts 之外的内部路径禁止外部 import，这是「重构自由」的来源；
4. 状态归置口诀进 onboarding：「真值在数据库 → Query；跨树共享客户端态 → store 就近；只有自己用 → useState」，三条覆盖 95% 的场景；
5. queryKey 工厂强制化：用 ESLint 自定义规则或 Code Review 清单确保没有裸字符串 key——缓存失效的正确性全押在 key 的一致性上；
6. bootstrap 只允许一条：全仓搜索 createRoot( 只允许出现在 app/mount.tsx 一处，副作用入口唯一；
7. 公共代码「三次法则」：被第二个使用方引用时复制不抽取，第三次引用才下沉为包——过度抽象比重复代码更难还；
8. Monorepo 起步只建两个目录：apps/ + packages/，包数量 = 真实共享需求，不为「看起来专业」制造空包。

📌 本章小结

• 架构是对复杂度的响应：先用五维评估表打分，再在「单体分区 / 模块化单体 / 微前端」三条路线里选——轻订单 10 分 + 跨团队信号，选择模块化单体并预留微前接缝；
• 模块化单体 = 六层结构（app/pages/widgets/features/entities/shared）× 依赖铁律，规则必须配置成 ESLint 边界检查进 CI，靠自觉的架构活不过三个月；
• 路由按域拆片段、状态三分法归置、queryKey 工厂化、请求层「基座 + 领域 API」——四个子系统的组织约定让每个业务域自成一体；
• 初始化收敛为显式 bootstrap() 编排，横切关注点插件化；Monorepo 用 pnpm workspace，公共代码遵守「三次法则」；
• 所有重要决策写 ADR 留痕：五段结构 + 备选代价 + 回顾触发条件，让半年后的新人能站在决策现场。

下一章解决分层结构里最容易失控的一层——shared/ui。当 Button、Table、StatusTag 在三个应用里被复制出五种样式，「抽内部组件库 qing-ui」就从可选项变成了必答题：设计令牌、组件 API 设计、Storybook 文档站与 changesets 版本发布，将把它从零做到一。

📄 第 20 章 · 设计系统与组件库建设 20-设计系统与组件库建设.md✓ 标记已学

📍 阶段：资深阶段（第 19–24 章）｜⏱ 预计学时：8–10 小时｜🔗 前置：第 06 章暗色主题 + 第 19 章 Monorepo

⬅ 上一章：大型项目架构设计 ｜ 📖 本版目录 ｜ ➡ 下一章：微前端与跨团队协作

💡 对照学习：本页是 React 版第 20 章，对应 Vue 版第 20 章 · 设计系统与组件库建设。本章方法两版通用，示例代码为 React 生态：设计令牌三层体系、组件 API 设计原则、a11y、changesets 发布流程完全与框架无关；生态差异在于 UI 基座用 Ant Design 5（≈ Element Plus）、文档站用 Storybook React-Vite（≈ Storybook Vue3-Vite）、组件以函数组件 + Hooks 编写（≈ <script setup> SFC）。

第 19 章的分层结构里，shared/ui 是最容易失控的一层：StatusTag 在 admin、portal、营销子系统里被复制了三份，品牌色改一次要发三版。本章把这一层升级为独立内部包 qing-ui——不是重造 Ant Design，而是「设计令牌 + 品牌封装 + 业务组件」的三层体系，并配齐文档站、视觉回归、版本发布与 0→1 路线图。

🎯 学习目标

学完本章，你将能够：

1. 建立「原始令牌 → 语义令牌 → 组件令牌」三层设计令牌体系，并说明它与第 06 章 data-theme 暗色方案如何衔接；
2. 使用 Ant Design 5 的 ConfigProvider token 体系完成品牌定制（主色、圆角、暗色算法），解释为什么定制要走 token 层而不是 CSS 覆盖；
3. 应用组件 API 设计四原则（受控优先、组合优于配置、最小 API 面、可预测命名）评审并重构一个组件；
4. 实现「受控/非受控」双模式组件（useControllableState 模式），并举出各自的适用场景；
5. 对比 CSS-in-JS、CSS Modules、Tailwind 三种样式方案，并为内部组件库做出有理由的选型；
6. 搭建 Storybook 文档站：CSF3 stories、autodocs、a11y 检查与截图视觉回归；
7. 完成 StatusTag / AmountInput 的无障碍改造（键盘可达、不单靠颜色传达信息、对比度达标）；
8. 配置 changesets 版本管理流程并演练发布到 npm 私服（.npmrc 全部走环境变量），输出 qing-ui 0→1 路线图。

📖 核心知识点

20.1 qing-ui 的定位：三层封装，而不是重造轮子

内部组件库的第一课是想清楚不做什么。Ant Design 5 的通用组件（Table、Form、DatePicker）比任何内部团队维护得都好，qing-ui 重写它们是纯亏损。正确的定位是三层：

┌────────────────────────────────────────────────────────────┐
│  第三层 · 业务组件（qing-ui 独有价值）                        │
│  OrderStatusTag / AmountInput / CustomerPicker /             │
│  OrderTimeline —— 领域词直接出现在 API 里                     │
├────────────────────────────────────────────────────────────┤
│  第二层 · 基础组件封装（薄壳：默认值 + 行为统一）              │
│  QButton（默认 size/风险色策略）/ QTable（分页默认 20、       │
│  空态统一文案）/ QModal（危险操作二次确认协议）                │
├────────────────────────────────────────────────────────────┤
│  第一层 · 设计令牌（品牌规范唯一的机器可读事实源）             │
│  品牌色板 / 语义色 / 圆角 / 间距 / 字号 —— 驱动 AntD 主题     │
└────────────────────────────────────────────────────────────┘
依赖方向：业务组件 → 基础封装 → 令牌；AntD 作为 peerDependency 只从令牌层接触。

收益立竿见影：运营提「把品牌主色从蓝换成青」，改的是令牌层一个值；「所有删除操作必须二次确认」，改的是 QModal 的协议；「订单状态标签统一加图标」，改的是 OrderStatusTag 一处。业务语义沉淀一次，全应用生效——这正是第 19 章「三次法则」等到的那个下沉时刻。

20.2 设计令牌三层体系与暗色主题

令牌分三层，层与层之间有严格的引用方向：

// packages/qing-ui/src/tokens/primitive.ts —— 原始层：与「用途」无关
export const palette = {
  blue500: '#2f6bff',
  blue600: '#1f52d6',
  gray50: '#f7f8fa',
  gray900: '#1c2333',
  green600: '#16a34a',
  amber600: '#d97706',
  red600: '#dc2626',
} as const;

/* packages/qing-ui/src/tokens/semantic.css —— 语义层：亮色为默认，暗色覆盖
   与第 06 章门户的 data-theme 方案完全同构——同一套令牌，两个应用共享 */
:root {
  --qing-color-primary: #2f6bff;
  --qing-color-bg-surface: #ffffff;
  --qing-color-bg-page: #f7f8fa;
  --qing-color-text-primary: #1c2333;
  --qing-color-success: #16a34a;
  --qing-color-warning: #d97706;
  --qing-color-danger: #dc2626;
}

:root[data-theme='dark'] {
  --qing-color-primary: #5c8dff;
  --qing-color-bg-surface: #1e2432;
  --qing-color-bg-page: #141926;
  --qing-color-text-primary: #e8ecf5;
  --qing-color-success: #4ade80;
  --qing-color-warning: #fbbf24;
  --qing-color-danger: #f87171;
}

Ant Design 5 的主题定制走 ConfigProvider 的 token（不要用 CSS 选择器硬覆盖，原因见易错点 20-2）。暗色模式由 darkAlgorithm 算法负责推导，与上面的 CSS 变量层各管各的生态：

// packages/qing-ui/src/providers/QingProvider.tsx —— 主题入口：一处配置全库生效
import { ConfigProvider, theme as antdTheme, App as AntdApp } from 'antd';
import zhCN from 'antd/locale/zh_CN';
import type { ReactNode } from 'react';
import '../tokens/semantic.css';

export interface QingProviderProps {
  themeMode: 'light' | 'dark';
  children: ReactNode;
}

export function QingProvider({ themeMode, children }: QingProviderProps) {
  return (
    <ConfigProvider
      locale={zhCN}
      theme={{
        token: {
          colorPrimary: '#2f6bff',
          colorSuccess: '#16a34a',
          colorWarning: '#d97706',
          colorError: '#dc2626',
          borderRadius: 6,
          fontFamily: "'PingFang SC', 'Microsoft YaHei', sans-serif",
        },
        algorithm: themeMode === 'dark' ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm,
      }}
    >
      <AntdApp>{children}</AntdApp>
    </ConfigProvider>
  );
}

衔接第 06 章：门户的 useTheme Hook 读写 localStorage 并切换 document.documentElement.dataset.theme——这个值现在同时驱动两件事：CSS 变量层（:root[data-theme='dark']）和 AntD 算法层（QingProvider 的 themeMode）。一个状态源，两个消费方，这就是「三层方案衔接」的全部含义：不另起炉灶，把门户已有的主题开关升级为全站主题的事实源。

20.3 组件 API 设计原则：让组件「猜得到用法」

组件库的寿命由 API 质量决定。四条原则，按优先级排列：

1. 受控优先，但保留非受控：value/onChange 受控满足表单联动（订单金额汇总），defaultValue 非受控满足简单场景（弹窗开关）；
2. 组合优于配置：需求开始「堆 prop」时（closable、footerRender、extraButton...），改用组合把结构交给调用方；
3. 最小 API 面：每个 prop 都是长期维护承诺。加一个 prop 只要 5 分钟，养它三年；
4. 命名词法可预测：遵循社区惯例（见下表），调用方「猜」的应该是对的一半以上。

双模式组件的通用实现模式是 useControllableState——这是写「表单级」组件的基本功：

// packages/qing-ui/src/hooks/useControllableState.ts
import { useCallback, useState } from 'react';

export interface ControllableOptions<T> {
  value?: T;                        // 受控值：调用方持有真值
  defaultValue?: T;                 // 非受控初值：组件内部持有真值
  onChange?: (value: T) => void;    // 两种模式都要回调，调用方永远不丢事件
}

export function useControllableState<T>({ value, defaultValue, onChange }: ControllableOptions<T>) {
  const isControlled = value !== undefined;
  const [inner, setInner] = useState<T>(defaultValue as T);
  const current = isControlled ? (value as T) : inner;

  const set = useCallback(
    (next: T) => {
      if (!isControlled) setInner(next); // 非受控：内部更新
      onChange?.(next);                  // 受控：真值由外部 onChange 改
    },
    [isControlled, onChange],
  );

  return [current, set] as const;
}

组合优于配置的典型对照——需求是「危险确认弹窗」：

// 配置式：每加一种按钮组合就要加一个 prop，API 面无限膨胀（反例）
<QConfirmModal okText="确认" cancelText="再想想" dangerType="primary"
  iconPlacement="left" footerAlign="end" showCloseButton={false} ... />

// 组合式：结构交给调用方，qing-ui 只固化「协议」（推荐）
import { QModal, QButton } from '@qing/ui';

<QModal open={open} onClose={close} role="alertdialog">
  <QModal.Title>删除订单 {order.orderNo}？</QModal.Title>
  <QModal.Body>删除后不可恢复，操作将记入审计日志。</QModal.Body>
  <QModal.Footer>
    <QButton variant="text" onClick={close}>再想想</QButton>
    <QButton variant="danger" onClick={confirmDelete}>确认删除</QButton>
  </QModal.Footer>
</QModal>

20.4 样式方案取舍：给组件库选一种，给应用层留自由

轻订单结论：qing-ui 包内用 CSS Modules + CSS 变量令牌——零运行时、与第 06 章变量方案无缝、封装第三方（AntD）时无样式冲突；应用层（admin 页面、portal 门户）允许 Tailwind 提效，但规定 Tailwind 只通过配置读取 --qing-* 变量做颜色，禁止硬编码色值。这个组合的判断依据记入 ADR-012，供未来推翻。

// packages/qing-ui/src/components/StatusTag/StatusTag.module.css
.tag {
  display: inline-flex;
  align-items: center;
  gap: 4px;
  padding: 2px 10px;
  border-radius: calc(var(--qing-radius-base, 6px) - 2px);
  font-size: 12px;
  line-height: 20px;
}
.pending { background: color-mix(in srgb, var(--qing-color-warning) 12%, transparent); }
/* ...每个状态一个 modifier，色值全部来自语义令牌 */

20.5 Storybook：文档站、a11y 检查与视觉回归

组件库没有文档站等于不存在——「看代码才知道怎么用」的库一定会被绕过。Storybook 三件套配置如下：

// packages/qing-ui/.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: ['@storybook/addon-essentials', '@storybook/addon-a11y'],
  framework: { name: '@storybook/react-vite', options: {} },
  staticDirs: ['../public'],
};
export default config;

// packages/qing-ui/src/components/StatusTag/StatusTag.stories.tsx —— CSF3 写法
import type { Meta, StoryObj } from '@storybook/react';
import { StatusTag } from './StatusTag';

const meta: Meta<typeof StatusTag> = {
  title: 'Business/StatusTag',
  component: StatusTag,
  tags: ['autodocs'],                       // 自动生成 API 文档页
  argTypes: {
    status: {
      control: 'select',
      options: ['draft', 'pending_review', 'approved', 'shipped', 'completed', 'rejected', 'cancelled'],
    },
    showIcon: { control: 'boolean' },
  },
};
export default meta;
type Story = StoryObj<typeof StatusTag>;

export const Default: Story = { args: { status: 'pending_review', showIcon: true } };

export const AllStatuses: Story = {        // 一屏看全部状态：视觉回归的主战场
  render: () => (
    <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
      {(['draft', 'pending_review', 'approved', 'shipped', 'completed', 'rejected', 'cancelled'] as const)
        .map((s) => <StatusTag key={s} status={s} showIcon />)}
    </div>
  ),
};

视觉回归的务实做法（不必上重型平台也能起步）：用 Playwright 对关键 story 截图，与基线 diff——

// packages/qing-ui/scripts/visual.spec.ts —— 关键组件截图比对（Playwright）
import { test, expect } from '@playwright/test';

test('StatusTag 全状态快照', async ({ page }) => {
  await page.goto('/iframe.html?id=business-statustag--all-statuses&viewMode=story');
  const story = page.locator('#storybook-root');
  await expect(story).toBeVisible();
  await expect(story).toHaveScreenshot('statustag-all.png', {
    maxDiffPixelRatio: 0.01,   // 容忍 1% 像素差（抗渲染抖动）
  });
});

流程约定：改动视觉 → 本地 pnpm visual 生成 diff 图 → diff 贴进 PR → reviewer 审「像素变化是否与意图一致」→ 确认后 --update-snapshots 更新基线。CI 里截图不符即红灯（接第 18 章流水线）。组件数量超过 30 个、截图任务超 10 分钟时，再评估迁移到 Chromatic 这类托管平台（占位符 --project-token=<your-chromatic-token>，token 走 CI secrets）。

20.6 a11y 基础：StatusTag 的三处改造

无障碍不是合规清单，是「信息传达的健壮性」。用贯穿项目的 StatusTag 演示三个最常见问题：

// packages/qing-ui/src/components/StatusTag/StatusTag.tsx
import { useId } from 'react';
import styles from './StatusTag.module.css';
import type { OrderStatus } from '@qing/shared-types';

const STATUS_META: Record<OrderStatus, { label: string; mod: string }> = {
  draft: { label: '草稿', mod: 'draft' },
  pending_review: { label: '待审核', mod: 'pending' },
  approved: { label: '已审核', mod: 'approved' },
  shipped: { label: '已发货', mod: 'shipped' },
  completed: { label: '已完成', mod: 'completed' },
  rejected: { label: '已拒绝', mod: 'rejected' },
  cancelled: { label: '已取消', mod: 'cancelled' },
};

export interface StatusTagProps {
  status: OrderStatus;
  showIcon?: boolean;   // 改造②：不单靠颜色——图标 + 文字双通道传达
}

export function StatusTag({ status, showIcon = true }: StatusTagProps) {
  const meta = STATUS_META[status];
  return (
    <span
      className={[styles.tag, styles[meta.mod]].join(' ')}
      // 改造①：给纯视觉标记补语义；③：文字对比度 ≥ 4.5:1 在 CSS 层保证
    >
      {showIcon && <StatusDot mod={meta.mod} aria-hidden="true" />}
      {meta.label}
    </span>
  );
}

三处改造对应三条 a11y 基线，写进组件库验收清单：① 信息不单靠颜色（色盲用户能看到图标与文字）；② 语义完整（装饰性图形 aria-hidden，交互控件保证键盘可达与焦点可见，outline 不许被随手删掉）；③ 对比度达标（正文 ≥ 4.5:1，大字 ≥ 3:1）。Storybook 的 a11y addon 会用 axe 在每个 story 上自动跑这三条，红灯挡在合并前。

20.7 changesets：多人协作的版本与发布流水线

内部库发布的三大乱象：版本号手改、changelog 凭记忆、 breaking change 无声上线。changesets 用一套流程根治：

开发者提 PR ──► 附带一个 changeset 文件（声明改了什么包、什么级别、写了什么说明）
     │
     ▼
CI（changesets/action）──► 检测到 changeset → 自动生成/更新「Version PR」：
                            bump 版本号 + 汇总 CHANGELOG.md
     │
     ▼
维护者合并 Version PR ──► CI 自动执行 changeset publish → 发布到 npm 私服
     │
     ▼
应用仓库 pnpm up @qing/ui ──► 消费方看到 CHANGELOG 才决定升不升级

// .changeset/config.json —— qing-ui 仓库（Monorepo 根）的 changesets 配置
{
  "$schema": "https://unpkg.com/@changesets/config/schema.json",
  "changelog": ["@changesets/cli/changelog", { "repo": "qingorder/qing-ui" }],
  "commit": false,
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

<!-- .changeset/brave-lions-run.md —— PR 里随代码提交的变更声明（changeset add 自动生成文件名） -->
---
'@qing/ui': minor
---

StatusTag 新增 showIcon 属性（默认开启），未传时行为与旧版一致；AmountInput 修复千分位在中文输入法下的光标跳动。

发布目标用 npm 私服（内网verdaccio/Nexus 均可，充当上游 npm 的代理缓存）。凭据只走环境变量，.npmrc 里永远不出现明文 token：

# .npmrc（仓库内，可提交）—— registry 指向内网私服
registry=https://npm-registry.qingorder.example.com/
always-auth=true

# .github/workflows/release.yml（节选）—— token 注入在运行时完成
name: Release
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: pnpm, registry-url: 'https://npm-registry.qingorder.example.com/' }
      - run: pnpm install --frozen-lockfile
      - name: Publish（若有新版本）
        run: pnpm changeset publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_PRIVATE_TOKEN }}   # 私服令牌只存 CI secrets

版本纪律用 semver 表述：修 bug → patch（0.1.x）；加属性且向后兼容 → minor（0.x.0）；改已有 prop 语义/删除 → major，并且必须在 changeset 说明里写迁移示例。0.x 阶段允许 minor 携带小破坏（社区惯例），但 qing-ui 1.0 之后零容忍。

20.8 qing-ui 0→1 路线图：四个里程碑，每步都交付价值

路线图的关键决策是迁移节奏与功能范围解耦：M1–M3 全部完成后库才「可用」，但 admin 的迁移从 M1 就可以开始（直接 workspace 引用），不必等 1.0。避免两种失败模式：闭门造车一年才见第一个调用方；或者反过来，边维护边打补丁导致 API 永不稳定。

🛠 渐进式实战练习

练习 1 · 基础（10–20 min）：把 StatusTag 收编进 qing-ui

任务描述：在 Monorepo 中创建 packages/qing-ui（参照 §19.7 的 source 引用方式），实现令牌三层（primitive.ts + semantic.css）、QingProvider 与 StatusTag（含 7 种订单状态、图标与文字双通道），并在 admin 的订单列表里替换掉本地 StatusTag 实现。

提示：状态语义直接复用附录A §5 的 OrderStatus 类型（从 @qing/shared-types 引入，不要复制类型）；替换后删除 admin 里的旧组件，用 E2E 冒烟集确认列表页无回归。

验收标准：① admin 通过 @qing/ui 引入 StatusTag，本地副本已删除；② 切换暗色主题后标签样式正确（CSS 变量随 data-theme 生效）；③ Storybook 中 AllStatuses story 一屏可见 7 种状态。

练习 2 · 进阶（30–60 min）：AmountInput —— 双模式 + 千分位 + a11y

任务描述：实现 AmountInput：输入/展示千分位格式（如 1,280.50），内部以「分」为单位与调用方交换值（附录A 金额口径）；支持受控（value 单位分 + onChange）与非受控（defaultValue）双模式；单位切换标签（元/千元）；通过 Storybook a11y addon 检查（含 label 关联与键盘操作）。

提示：格式化与解析是纯函数，放 shared/lib/money.ts 并配 Vitest 单测（浮点陷阱见第 15 章：0.1 + 0.2 !== 0.3，用「分」的整数运算）；输入过程中不要边打边格式化，在 onBlur 时才格式化展示，否则光标会乱跳。

验收标准：① 双模式行为正确（受控时外部改 value 立即生效；非受控时内部自转）；② showThousands 千分位展示正确，粘贴/输入法场景不崩；③ a11y addon 零违规：label 关联（htmlFor）、aria-describedby 提示单位、数字键与退格全键盘可用；④ money.ts 单测覆盖「分↔元」「非法输入」「负数拒绝」三类用例，覆盖率 100%。

// packages/qing-ui/src/components/AmountInput/AmountInput.tsx（骨架）
import { useId, useState } from 'react';
import { useControllableState } from '../../hooks/useControllableState';
import { centsToDisplay, displayToCents } from '../../lib/money';
import styles from './AmountInput.module.css';

export interface AmountInputProps {
  /** 受控值，单位：分 */
  value?: number;
  /** 非受控初值，单位：分 */
  defaultValue?: number;
  onChange?: (cents: number) => void;
  disabled?: boolean;
  unitLabel?: string;          // a11y：单位说明走 aria-describedby
}

export function AmountInput(props: AmountInputProps) {
  const { onChange, disabled, unitLabel } = props;
  const [cents, setCents] = useControllableState<number>(props); // 双模式核心
  const [raw, setRaw] = useState<string>(cents != null ? centsToDisplay(cents) : '');
  const id = useId();

  const commit = (text: string) => {
    const next = displayToCents(text);        // 解析失败返回 null
    if (next != null) {
      setCents(next);                         // 受控→回调外部；非受控→内部更新
      setRaw(centsToDisplay(next));           // blur 时才做千分位格式化
    }
  };

  return (
    <span className={styles.wrap}>
      <input
        id={id}
        className={styles.input}
        inputMode="decimal"
        disabled={disabled}
        value={raw}
        onChange={(e) => setRaw(e.target.value)}   // 输入中：存原文，不格式化
        onBlur={(e) => commit(e.target.value)}      // 失焦：解析 + 格式化 + 回调
        aria-describedby={unitLabel ? `${id}-unit` : undefined}
      />
      {unitLabel && <span id={`${id}-unit`} className={styles.unit}>{unitLabel}</span>}
    </span>
  );
}

// packages/qing-ui/src/lib/money.ts —— 金额格式化（分单位，纯函数）
export function centsToDisplay(cents: number): string {
  const negative = cents < 0 ? '-' : '';
  const abs = Math.abs(Math.round(cents));            // 全程整数运算，规避浮点误差
  const yuan = Math.floor(abs / 100);
  const fen = String(abs % 100).padStart(2, '0');
  const [int, dec] = [String(yuan), fen];
  const withComma = int.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
  return `${negative}¥${withComma}.${dec}`;
}

export function displayToCents(text: string): number | null {
  const cleaned = text.replace(/[¥,\s]/g, '');
  if (!/^\d+(\.\d{1,2})?$/.test(cleaned)) return null; // 非法输入一律拒绝
  const [int, dec = ''] = cleaned.split('.');
  return Number(int) * 100 + Number((dec + '00').slice(0, 2));
}

练习 3 · 挑战（选做，60+ min）：发布流水线 0→1 演练

任务描述：为 qing-ui 仓库完整搭起发布链路：配置 .changeset/、verdaccio 本地私服（docker run 一条命令即可）、.npmrc 环境变量注入、changesets/action 的 Version PR 流程；然后真实演练一次「加属性 → 提 changeset → Version PR → 合并 → publish 0.1.0 → admin 升级」的闭环。

提示：本地演练用 pnpm changeset:version + pnpm changeset:publish 手动跑等价流程即可验证配置正确性；verdaccio 的 uplinks 配置上游为 https://registry.npmjs.org/，令牌用 npm adduser --registry <内网地址> 生成，存进本地环境变量 NPM_PRIVATE_TOKEN。

验收标准：① 私服上能看到 @qing/ui@0.1.0 与自动生成的 CHANGELOG；② 故意提交一个 breaking changeset（删 prop），Version PR 正确 bump 到 1.0.0 并在 CHANGELOG 标注迁移说明（随后回滚该 changeset，保留 0.x 线）；③ admin 仓库 pnpm up @qing/ui 后构建通过。

⚠️ 常见易错点

易错点 20-1：API 面面俱到——组件库维护爆炸

❌ 错误做法：业务方提什么就加什么 prop：QTable 半年长出 47 个 props（showBorder、headerBg、emptyImage……），每个 prop 组合都要测试与文档；一个 prop 的 bug 报修牵动 12 个调用方。组件库从「加速器」变成「排队点」。

✅ 正确做法：加 prop 前过三问——「能不能用现有 API 组合出来？」「第二个调用方在哪？」「这个需求是不是属于业务层而不是通用层？」。多数「定制需求」用组合（children/render）与 ...rest 透传解决；确需新增时先写 changeset 说明影响面（§20.7），让改动有 changelog、有迁移示例。API 面每少一个，未来三年少还一笔债。

易错点 20-2：用 !important 深层覆盖第三方样式

❌ 错误做法：global.css 里写 .ant-table-tbody > tr:nth-child(2n) td { background: #f0f7ff !important; }。AntD 5 升级调整了内部类名，斑马纹一夜失效；多套覆盖互相打架，排查样式问题时全靠碰运气。

✅ 正确做法：AntD 5 一切视觉定制走 ConfigProvider.theme.token / components（组件级 token）；令牌层没有的能力（如结构布局差异）用封装组件（QTable 组合出默认行为）而不是 CSS 猜类名。类名是第三方库的私有实现，token 才是它承诺的公共 API——这条同样适用于 Element Plus 等一切组件库。

易错点 20-3：把业务逻辑写进基础组件

❌ 错误做法：为了「方便统计」，在 QButton 内部直接调用 track() 埋点并读取订单上下文；QModal 里 import 了 @/entities/order。基础组件与业务域耦合后，qing-ui 无法被 portal/营销子系统复用，且库内测试需要 mock 业务模块。

✅ 正确做法：分层红线（§20.1）：qing-ui 只依赖令牌层与 AntD，不知道订单是什么。埋点这类横切需求用第 19 章的插件化方案（在应用层给 axios/路由统一挂埋点）或事件回调（QButton 只负责 onClick，埋点由调用方决定）；业务上下文通过 props 注入，组件内不 import 任何 entities/。

易错点 20-4：版本号手改、changelog 凭记忆

❌ 错误做法：发布前手动把 package.json 的 version 从 0.1.0 改成 0.1.1，CHANGELOG.md 手写「更新了一些东西」。三个应用各自 pin 着不同版本，没人说得清生产环境跑的是哪个——出了 bug 连「该看哪个版本的源码」都要考古。

✅ 正确做法：版本号只由 changesets 产生（§20.7）：PR 附 changeset 声明级别（patch/minor/major），Version PR 自动 bump 并汇总 CHANGELOG，合并即发布。配套纪律：admin/portal 的依赖用 ^0.2.0 区间 + lockfile 锁定，升级走独立 PR 让 CI 全量验证；发版后打 git tag 便于回溯生产版本。