# M1 / issue-04 空应用脚手架策略说明

- Issue：`#9`
- 里程碑：`M1 基础工程：workspace 骨架初始化`
- 分支：`feat/m1-issue-04-scaffold-strategy-doc`
- 日期：`2026-03-24`

## 背景

`issue-01` 到 `issue-03` 已完成基础骨架、目标目录与共享配置占位，但仓库仍未创建真实 `Next.js` / `NestJS` 应用。  
为了让读者理解这不是遗漏，而是教程节奏设计，需要把“何时创建空应用、为什么 M1 不直接生成脚手架”沉淀成正式说明文档。

## 本次目标

- 输出正式的空应用脚手架策略说明
- 解释为什么 M1 在此收口
- 明确进入真实脚手架阶段的时机与顺序
- 更新文档导航
- 补充本次任务开发日志

## 非目标

- 不运行 `create-next-app`
- 不运行 `nest new`
- 不创建真实应用代码
- 不修改当前根级 Vue 项目
- 不进入 M2 业务实现

## TDD / 测试设计

- 先扩展 `scripts/check-workspace.mjs`
- 让脚本开始要求以下路径存在：
  - `docs/10-架构设计/04-空应用脚手架策略说明.md`
- 先运行一次 `pnpm run test:workspace`
- 确认在策略文档尚未创建前失败
- 再补齐文档与导航

## 实际改动

- 扩展 `scripts/check-workspace.mjs` 的文档验收范围
- 新增 `docs/10-架构设计/04-空应用脚手架策略说明.md`
- 更新 `docs/00-文档导航.md`

## Review 记录

### 是否符合当前 Issue 与里程碑目标

符合。当前只做：

- 策略说明文档
- 文档导航更新
- 与文档存在性相关的验收脚本

没有提前进入：

- 真实脚手架生成
- 工程链路改造
- 业务能力开发

### 是否可抽离组件、函数、skills 或其他复用能力

- 当前属于文档与流程收尾阶段，没有组件或函数抽离价值
- `scripts/check-workspace.mjs` 继续作为 M1 阶段验收脚本使用
- 暂无必要引入新的 skill 抽象

### Review 结论

- 通过
- 可进入自测

## 自测结果

### 1. TDD 首次失败

- `pnpm run test:workspace`
- 结果：失败
- 原因：缺少 `docs/10-架构设计/04-空应用脚手架策略说明.md`

### 2. 骨架验收

- `pnpm run test:workspace`
- 结果：通过

### 3. 类型检查

- `pnpm run typecheck`
- 结果：通过

### 4. 构建验证

- `pnpm run build`
- 结果：通过
- 备注：仍存在 `tailwind.config.cjs` 的 ESM 警告，但与本次任务无关，且构建成功

## 遇到的问题

### 1. 文档任务也要保持“先失败再补齐”的节奏

- 难点：纯文档任务很容易直接开始写，而跳过可验证的失败起点
- 处理：本次把策略文档路径纳入 `scripts/check-workspace.mjs`，继续保持验收先行

### 2. M1 很容易在收尾阶段继续扩到脚手架实现

- 风险：在写策略说明时顺手进入 `create-next-app` 或 `nest new`
- 处理：明确将“脚手架生成”留给后续里程碑起点，本次只完成解释与收口

## M1 收尾结论

- M1 已把 monorepo 的“结构意图”讲清楚
- 后续可在进入新能力前，再逐步生成真实应用
- 教程节奏上，M1 到此收口比继续堆脚手架更清晰

## 后续待办

- 关闭 `M1` milestone
- 进入 `M2` 的首个 issue 规划
