# 《我要当市长》3D 技术预研 · 浮空岛最小旋转原型

> 独立原型（`3d-spike/`），与正式 2D 工程（`../app/`）完全隔离。
> **不接入**金币 / 声望 / 升级 / 存档 / 广告 / 后端 / 微信 AppID。
> **不进入** 0.1 第三步。技术结论见 `docs/`。

## 一、这是什么

一个「简约低多边形浮空岛城市」最小 3D 原型，用于验证 NAS Docker + Node.js + TypeScript 环境下的 3D 可行性：

- 悬浮岛（9 边台地 + 岛底悬浮截面 + 悬浮碎石）
- 一条 L 形道路
- 市政厅占位模型（含塔楼）、两个建筑占位模型、一个居民占位模型
- 方向光 + 半球环境光 + 真实阴影贴图
- **正交相机**、鼠标拖动旋转、触摸拖动旋转、滚轮/双指缩放（实验）
- 点击对象 → **射线检测**（Raycaster）→ 显示对象名称（点击空白处不误报）

## 二、启动与构建命令

所有命令均在 NAS 上执行（Docker 镜像 `node:22-bookworm-slim`）。

```bash
# 0) 首次：给容器 node 用户（uid 1000）写权限（改 ACL 不改属主）
setfacl -R -m u:1000:rwx /vol1/ai/projects/wyszz-new/3d-spike
setfacl -R -m d:u:1000:rwx /vol1/ai/projects/wyszz-new/3d-spike

cd /vol1/ai/projects/wyszz-new/3d-spike

# 1) 安装依赖（Docker 内，不污染宿主）
docker run --rm -u 1000:1000 --memory 1g --cpus 2 \
  -v /vol1/ai/projects/wyszz-new/3d-spike:/app -w /app \
  node:22-bookworm-slim npm install

# 2) 类型检查 + 生产构建
docker run --rm -u 1000:1000 --memory 1g --cpus 2 \
  -v /vol1/ai/projects/wyszz-new/3d-spike:/app -w /app \
  node:22-bookworm-slim npm run build        # = tsc --noEmit && vite build

# 3) 启动开发预览（局域网 192.168.1.38:4180）
docker compose up spike        # npm install && npm run dev

# 4) 启动生产构建 + 预览（验证用）
docker compose up spike-build  # npm install && npm run build && vite preview

# 5) 浏览器自动化验证（竖屏 / 拖动 / 触摸 / 点击 / 截图 / 报告）
node tools/cdp-verify.mjs http://192.168.1.38:4180/ screenshots docs/verify-report.json
```

## 三、实际依赖与版本（2026-10-08 实测）

| 包 | 版本 | 类型 |
| --- | --- | --- |
| three | 0.186.1 | 运行时 |
| @types/three | 0.186.0 | 开发（three 本体不带 .d.ts） |
| typescript | 5.9.3 | 开发 |
| vite | 6.4.4 | 开发 |

- 容器内：Node v22.23.3 / npm 10.9.9；`npm install` 共装 23 个包（含传递依赖）。
- 构建产物：JS 合计 537.48 kB（gzip 136.54 kB），three 单独 chunk 525.82 kB（gzip 131.74 kB）。

## 四、目录结构（新增文件全在本目录内）

```
3d-spike/
├── index.html                    页面骨架 + CSS（DOM 仅此一处 + platform/browser.ts）
├── package.json / tsconfig.json / vite.config.ts
├── docker-compose.yml            Docker 开发/构建预览服务（node:22，限 1G 内存）
├── src/
│   ├── main.ts                   入口：渲染器/相机/光照/接线/调试统计
│   ├── config.ts                 颜色、相机、名称常量
│   ├── platform/
│   │   ├── types.ts              PlatformAdapter 接口（微信端换实现的切面）
│   │   └── browser.ts            浏览器实现（唯一碰 DOM 的文件）
│   ├── world/
│   │   ├── island.ts             悬浮岛地形 + 道路（程序化几何）
│   │   └── props.ts              市政厅 / 两建筑 / 居民占位模型
│   ├── controls/orbit.ts         拖动旋转 + 捏合/滚轮缩放（实验）
│   └── interaction/pick.ts       Raycaster 点击检测 + 高亮
├── tools/cdp-verify.mjs          CDP 浏览器验证脚本（可复跑）
├── screenshots/                  01-default / 02-rotated / 03-clicked
├── docs/
│   ├── 01-技术方案比较报告.md
│   ├── 02-微信小游戏适配评估.md
│   ├── 03-验证结果与性能记录.md
│   ├── 04-微信适配风险清单与后续建议.md
│   └── verify-report.json        验证原始数据（自动生成）
└── dist/                         生产构建产物
```

## 五、验证结论速览

- tsc 0 错误；vite 生产构建通过；竖屏 390×844 显示正常。
- 鼠标拖动 10/10、触摸拖动 10/10（CDP 原生触摸事件）、点击 4 对象名称全部一致、空白处不误报。
- 运行时 0 报错；场景 22 网格 / 580 三角形 / 0 图片纹理。
- **真机未验证；微信端未验证。** 浏览器通过 ≠ 微信小游戏通过。
