# 运行预览前端安装卡顿修复设计

## 背景

运行预览会为生成的前台和后台前端分别执行：

```text
npm install && npm run dev
```

生成项目使用 Vue CLI 4，因此安装时出现 `svgo@1.3.2` 等 deprecated 警告属于旧依赖提示，不是启动失败。

现场检查确认：

- 两个前端没有 `package-lock.json`，每次都需要重新解析完整依赖树。
- 每个前端、每次预览都使用独立的空 npm 缓存。
- 重新启动预览时只终止 Java 持有的外层 shell；安装阶段尚未监听端口，现有按端口清理无法找到仍在运行的 npm/node 子进程。
- 多次启动后遗留的 npm 进程并行下载和解压依赖，持续争抢网络、CPU 和磁盘，日志又长时间停留在 deprecated 警告附近，因此表现为“卡住”。

## 目标

1. 停止或重新启动预览时，终止该预览启动的整棵后端和前端进程树。
2. 前台、后台前端以及后续预览复用同一份 npm 下载缓存。
3. 保留当前 Vue 2 / Vue CLI 4 生成模板，不在本次修复中升级依赖栈。
4. 保留端口清理作为服务已经监听后的兜底措施。

## 方案

### 受管进程

`RunPreviewProcessRunner` 在 Windows 上通过无用户配置的 PowerShell 包装器启动命令。包装器在执行实际命令前记录自身 PID，并等待子命令退出。

Java 侧返回一个委托标准 `Process` 行为的受管进程对象，同时保留 PID 记录位置。这样不依赖 Java 9 的 `ProcessHandle`，可继续运行在当前 Java 8 环境。

在非 Windows 平台上继续使用现有 shell 启动方式；进程终止逻辑保持标准 `Process.destroy()` / `destroyForcibly()` 行为。

### 进程树终止

`RunPreviewProcessKiller` 停止受管 Windows 进程时：

1. 读取包装器记录的根 PID。
2. 执行 `taskkill /PID <pid> /T /F`，终止根进程及全部后代。
3. 等待 Java 持有的进程退出。
4. 如果 PID 不可用或系统命令失败，回退到当前的 `destroy()` / `destroyForcibly()`。
5. 最后继续按端口查找并清理已经进入监听状态的残留进程。

PID 文件位于对应预览工作区内，名称唯一；进程退出或停止后尽力删除。

### 共享 npm 缓存

把当前每个工作区下的：

```text
.easycode-preview/npm-cache/frontend
.easycode-preview/npm-cache/admin-frontend
```

改为预览根目录下的共享缓存：

```text
preview-workspaces/.npm-cache
```

前台、后台前端和后续预览都设置同一个 `NPM_CONFIG_CACHE`。npm 自身的内容寻址缓存支持并发访问；保留 `audit=false`、`fund=false` 和更新检查关闭配置，并启用 `prefer-offline`，优先复用已经下载的包，缺失内容仍可联网获取。

共享缓存只保存 npm 下载内容，不复用生成项目的 `node_modules`，避免不同项目依赖树互相污染。

## 错误处理

- PID 文件尚未生成、内容无效或 `taskkill` 不可用时，不让停止接口失败，回退到标准 Java 进程终止。
- npm 缓存目录无法创建时，启动预览失败并返回明确错误。
- deprecated 警告继续展示，避免隐藏真实安装输出；它们不改变预览状态。

## 测试

### 自动化测试

- 先新增失败测试，证明 Windows 受管进程能够暴露进程树根 PID，且终止器会针对该 PID 请求整树终止。
- 验证 PID 缺失时仍会回退并结束 Java `Process`。
- 更新运行预览服务测试，验证前台与后台前端获得同一个、位于预览根目录的 npm 缓存。
- 验证 npm 环境启用 `prefer-offline`，同时保持允许联网下载。
- 运行 `RunPreviewProcessRunnerTest`、进程终止器测试和 `FrontProjectRunPreviewServiceImplTest`。

### 手工验证

1. 启动同时包含前台和后台前端的运行预览。
2. 在安装期间停止并重新启动预览，确认旧 npm/node 子进程消失。
3. 首次安装完成后再次启动，确认共享缓存被复用，安装阶段明显缩短。
4. 确认两个前端端口均可访问，停止后端口被释放。

## 非目标

- 升级 Vue、Vue CLI、webpack 或 deprecated 间接依赖。
- 生成或维护 `package-lock.json`。
- 跨项目复用 `node_modules`。
- 引入 Docker 或新的依赖安装调度服务。