docs: document pnpm EACCES issue on WSL2 Windows filesystem

pnpm fails with permission denied during atomic rename on /mnt/d/ (NTFS).
Solution: keep app/ on WSL2 native fs (~/fire_goal/app/).

- 04-风险与避坑.md: add as 三级坑 with cause, fix, and principle
- 03-架构设计.md: add WSL2 native path requirement with HBuilderX access path

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/03-架构设计.md

@@ -114,6 +114,27 @@ interface Store {
 
 WSL2 会自动将内部端口转发到 Windows 的 `localhost`，所以 WSL2 里启动的 dev server，Windows 浏览器直接用 `http://localhost:端口` 访问，热更新也正常生效。
 
+### ⚠️ app/ 必须放在 WSL2 原生文件系统
+
+pnpm 在 `/mnt/d/`（Windows NTFS 挂载）上做原子重命名时会报 `EACCES` 权限错误，导致 `pnpm install` 失败。
+
+**正确路径**：`~/fire_goal/app/`（WSL2 原生 ext4）
+
+```bash
+# 开发时进入 WSL2 原生目录
+cd ~/fire_goal/app
+pnpm install   # ✅ 无权限问题
+pnpm dev:h5
+```
+
+Windows 侧（HBuilderX 云打包）通过以下路径访问：
+
+```
+\\wsl$\Ubuntu\home\<用户名>\fire_goal\app
+```
+
+> docs/ 和 research/ 仍在 `/mnt/d/opc_project/fire_goal/`，用 git 管理；app/ 在 WSL2 原生 fs 单独开发。
+
 ### 必须的 Vite 配置
 
 Vite 默认只监听 `127.0.0.1`（WSL2 内部），需改为监听所有网卡，否则 Windows 浏览器无法访问。

docs/04-风险与避坑.md

@@ -35,6 +35,10 @@ rpx 换算、iOS 安全区、状态栏、**键盘顶起输入框**、滚动穿
 
 ## 🟢 三级坑：知道即可
 
+- **pnpm 在 /mnt/d/ 上权限报错（已踩）**：WSL2 挂载的 Windows NTFS 磁盘（`/mnt/d/`）不支持原子重命名操作，pnpm install 时报 `EACCES: permission denied, rename ...`。
+  - **解决**：把 `app/` 移到 WSL2 原生文件系统（`~/fire_goal/app/`），pnpm 在原生 fs 上无此问题；Windows 侧通过 `\\wsl$\Ubuntu\home\用户名\fire_goal\app` 访问（HBuilderX 云打包用此路径）。
+  - **原则**：开发目录放 WSL2 原生 fs（`~`），文档/配置等只读文件可留 `/mnt/d/`。
+
 - **nvue 陷阱**：只支持 flex、CSS 受限、与 vue 混用割裂 → **全程用普通 vue 页面，不碰 nvue**。
 - **插件市场质量参差**：收费/失修/文档差，跨端 bug 难定位 → 少依赖第三方原生插件。
 - **HBuilderX 耦合**：云打包/原生插件偏 GUI；CLI 项目导入偶有适配问题 → 用 HBuilderX 友好的结构搭项目。