# 10_架构调查 Codex 完成报告 v1

日期：2026-08-29

任务：`docs/40_任务/10_架构调查指令书_v1.md`

分支：`particle/main`
结论：调查完成，建议直接进入 `20_架构设计`

## 1. 实际调查范围

本次对当前仓库的目录和工程形态、Git 基线、项目总则与规范、JavaScript/TypeScript 配置、Android Gradle/JNI/renderer、iOS Pod/MapView/backend、MapLibre Core Map/Style/Source/Renderer/Layer/gfx、CustomLayer、Camera/Matrix、帧驱动、线程边界、粒子搜索结果、fixture 和潜在性能风险进行了只读调查。

## 2. 必做项状态

| 必做项 | 状态 | 说明 |
|---|---|---|
| 读取总则 v1 | 已完成 | 根 AGENTS、`docs/00_项目总则/`、`docs/00_项目规范/` 已完整读取 |
| 确认 Git 基线 | 已完成 | 分支、HEAD、远端、submodule 状态已查询 |
| 确认整体目录和工程形态 | 已完成 | 确认是 MapLibre Native monorepo，不是 RN app |
| 确认核心依赖版本 | 已完成 | package/lock、Android VERSION/Gradle、iOS VERSION/Podspec 已读取 |
| 追踪 MapLibre 实际调用链 | 已完成 | Android、iOS、Core 三条链已追踪 |
| 调查地图生命周期 | 已完成 | Core、Android、iOS 分别记录 |
| 调查自定义渲染扩展点 | 已完成 | A/B/C/D 分类已记录 |
| 分别调查 Android | 已完成 | MapView、JNI、renderer thread、OpenGL/Vulkan、CustomLayer |
| 分别调查 iOS | 已完成 | MLNMapView、CADisplayLink、OpenGL/Metal、CustomStyleLayer |
| 调查线程和执行边界 | 已完成 | Native、Worker、FileSource、Render、GPU 已区分 |
| 调查 Camera/坐标/Matrix | 已完成 | Core TransformState、CustomLayer 参数和高层差异已记录 |
| 调查帧驱动 | 已完成 | Android requestRender、iOS DisplayLink、Core render callback 已记录 |
| 搜索粒子/场数据/Shader 实验 | 已完成 | 无运行时粒子实现；fixture 仅占位，内置 shader 无粒子 shader |
| 调查可复用基础设施 | 已完成 | FileSource、immutable、thread pool、gfx resource、upload/shader registry |
| 整理性能风险 | 已完成 | 逐项标记高/中/低/尚无法判断 |
| 绘制必要架构图 | 已完成 | 总体、JS/Native、Android、iOS、数据边界共五图 |
| 区分事实/限制/候选/未知 | 已完成 | 报告第 17 节分类 |
| 判断是否追加调查 | 已完成 | 选择 A，不追加子任务 |
| 判断能否进入 20_架构设计 | 已完成 | 可以进入，未知项作为设计输入 |
| 未修改生产代码 | 已完成 | 无源码改动 |
| 未升级或安装依赖 | 已完成 | 无 lock/Gradle/Pod/npm 改动 |
| 生成正式调查报告 | 已完成 | `docs/20_调查/10_架构调查报告_v1.md` |
| 生成 Codex 完成报告 | 已完成 | 本文件 |

## 3. 未完成或无法验证

- “工作区干净”未完成：调查开始时存在任务书自身的未跟踪文件，非本次产生。
- RN 页面、RN binding、NativeModule/TurboModule/Fabric 和 JS 每帧回调无法验证：当前仓库没有 RN 宿主或对应配置。
- 目标产品最终 iOS backend、目标宿主线程调度、Android 业务侧 raw CustomLayerHost 的稳定用法、设备 GPU 能力和正式粒子数据格式无法仅凭当前静态源码确认。
- 本次未重新构建或测试：任务性质为只读调查，构建可能改变产物；已有历史构建结果仅按基线记录引用。

这些项目已在调查报告中使用“未确认/无法验证”明确标记，没有用外部项目或记忆补全。

## 4. 实际生成/修改文档

- 新增 `docs/20_调查/10_架构调查报告_v1.md`。
- 新增 `docs/报告/10_架构调查_Codex完成报告_v1.md`。
- 追加 `粒子开发记录.md` 的本次调查记录。
- 未新增或修改 Step 文件：遵循用户“当前不要自行创建 Step”的明确限制。
- 未修改 `docs/00_项目总则/` 或 `docs/00_项目规范/`。

## 5. 生产代码与依赖

- 生产代码：未修改。
- 实验源码：未修改。
- Android/iOS/Gradle/Pod/Metro/Babel/TypeScript 配置：未修改。
- 依赖：未安装、未升级、未修改 lock 文件。

## 6. 阻塞项和下一步

没有阻塞 `20_架构设计` 的关键未知项。建议下一步进入 `20_架构设计`，将本报告中的 CustomLayer/Core gfx 候选、Android/iOS 差异、离线 fixture contract、Land/Ocean Mask 边界和 context-loss 生命周期作为设计约束；在需要选择最终 GPU/线程/数据格式前，再安排最小平台运行时验证。