# M16 Follow-up：性能优化专题 Issue 草案

> 用途：可直接复制到 GitHub 新 Issue。  
> 建议标题：`[Feature] M16 follow-up / issue-XXX 线上性能基线与优化闭环（首轮）`

## 背景

- 项目已上线运行，需要在“可观测、可回归、可教学”的前提下推进性能优化。
- 当前仓库已有基础脚本（如 `perf-dev-route`、`perf-build-analyze`），可用于建立首轮基线。
- 需要把优化过程沉淀为教程素材，覆盖方法、步骤、坑点与结果。

## 目标

- 建立线上与本地统一的性能基线记录。
- 明确本轮性能指标与预算（至少覆盖首屏、接口、包体）。
- 完成一轮可归因的性能优化实验（单变量修改）。
- 产出可复用的日志与教程大纲材料。

## 非目标

- 不在本 Issue 内完成所有性能问题一次性修复。
- 不扩展到与本轮性能无关的功能开发（RAG/Chat 新需求等）。
- 不在本轮引入过重的平台化体系（先走最小可行方案）。

## 改动范围

- 脚本与报告：
  - `scripts/perf-*.mjs`
  - `.tmp/perf/*.json`（本地报告）
- 文档与日志：
  - `docs/30-开发日志/`（Issue 级日志）
  - `docs/40-教程与博客/`（专题教程大纲与正文）
- 必要时的性能优化代码（严格按本 Issue 边界小步提交）。

## 验收标准

- 有一份可复现的基线报告（含采样时间、路由、环境、指标）。
- 有至少一项优化前后对比结果，且可说明归因链路。
- 有开发日志记录“目标、改动、坑点、验证、结果”。
- 有教程大纲（可继续扩写为正文）。

## 测试计划

- Web 性能采样：
  - 线上域名关键路由首次访问与热访问
  - 至少 3 次采样并保留结果
- 工程验证：
  - `pnpm typecheck:all`
  - `pnpm test:unit`（按改动影响范围执行）
  - `pnpm build:all`（或受影响 app 的 build）
- 对比结果：
  - 优化前后同路由、同条件采样对照

## 日志 / 教程输出要求

- 开发日志必须包含：
  - 背景
  - 本次目标
  - 实际改动
  - Review 记录
  - 遇到的问题（坑）
  - 测试与验证
  - 可写成教程/博客的切入点
- 教程需覆盖：
  - 性能测试方法
  - 优化步骤
  - 常见误区与踩坑
  - 最终结果与复盘
