755 lines
16 KiB
Markdown
755 lines
16 KiB
Markdown
# MapLibreParticleLab 10_架构调查指令书 v1
|
||
|
||
## 1. 任务基本信息
|
||
|
||
- 项目：MapLibreParticleLab
|
||
- 大阶段：`10_架构调查`
|
||
- 当前基线分支：`particle/main`
|
||
- 当前前置状态：总则 v1 已提交并推送
|
||
- 任务性质：只读架构调查
|
||
- 是否允许修改业务代码：否
|
||
- 是否允许升级或安装依赖：否
|
||
- 是否允许顺手修复发现的问题：否
|
||
|
||
---
|
||
|
||
## 2. 任务目标
|
||
|
||
对 MapLibreParticleLab 当前真实代码、依赖、原生工程、MapLibre 接入方式和渲染架构进行一次完整调查。
|
||
|
||
本阶段的目的不是设计最终粒子系统，而是回答：
|
||
|
||
> 当前项目实际上是怎样运行的，MapLibre 实际经过哪些层完成地图渲染，未来粒子系统有哪些真实可用的接入位置，以及当前仍有哪些关键问题无法仅通过现有代码确认。
|
||
|
||
最终必须形成一份基于实际仓库源码和配置的中文架构调查报告，为下一阶段 `20_架构设计` 提供事实基础。
|
||
|
||
---
|
||
|
||
## 3. 核心原则
|
||
|
||
### 3.1 以实际代码为唯一事实来源
|
||
|
||
不得根据：
|
||
|
||
- 记忆
|
||
- MapLibre 一般架构
|
||
- React Native 常见做法
|
||
- 网上其他项目的实现
|
||
- 对新版 MapLibre 的印象
|
||
|
||
推断当前项目架构。
|
||
|
||
所有结论必须优先来自当前 `particle/main` 实际源码、配置、依赖锁定文件和原生工程。
|
||
|
||
如果某项无法通过仓库确认，必须明确标记为：
|
||
|
||
`未确认`
|
||
|
||
不得自行补全。
|
||
|
||
### 3.2 本任务只调查，不设计
|
||
|
||
本任务不得直接决定：
|
||
|
||
- 最终粒子渲染技术路线
|
||
- CPU 粒子还是 GPU 粒子
|
||
- CustomLayer 是否作为最终方案
|
||
- 是否修改 MapLibre Native
|
||
- 是否自行创建原生 Renderer
|
||
- 是否使用 Metal / OpenGL / Vulkan
|
||
- 最终数据纹理格式
|
||
- 最终 Shader 架构
|
||
- 最终线程模型
|
||
|
||
可以列出候选扩展位置和现有限制，但不得提前作最终技术选型。
|
||
|
||
### 3.3 不预设多个调查任务
|
||
|
||
本次应尽可能一次完成整个 `10_架构调查`。
|
||
|
||
只有在调查后发现某个关键问题同时满足以下条件时，才建议追加新的调查任务：
|
||
|
||
1. 无法依靠当前项目源码确认；
|
||
2. 该问题会直接影响下一阶段技术路线；
|
||
3. 需要额外读取第三方源码、编译验证、最小实验或平台专项验证。
|
||
|
||
不得为了形式完整主动拆出大量 `10-01 / 10-02 / 10-03` 子任务。
|
||
|
||
---
|
||
|
||
## 4. 开始前检查
|
||
|
||
开始调查后先确认以下信息：
|
||
|
||
- [ ] 当前仓库确实为 MapLibreParticleLab
|
||
- [ ] 当前分支为 `particle/main`
|
||
- [ ] 读取当前 Git 状态
|
||
- [ ] 确认工作区是否干净
|
||
- [ ] 找到并完整阅读当前“总则 v1”
|
||
- [ ] 确认项目根目录结构
|
||
- [ ] 确认主要源码目录
|
||
- [ ] 确认 Android / iOS 原生目录是否存在
|
||
- [ ] 确认依赖清单及 lock 文件
|
||
|
||
如果当前分支或代码状态与上述基线明显不符：
|
||
|
||
不要修改仓库状态。
|
||
|
||
继续进行能够完成的只读调查，并在报告中明确记录实际状态。
|
||
|
||
---
|
||
|
||
## 5. 必做调查内容
|
||
|
||
### 5.1 项目整体架构
|
||
|
||
调查当前项目的真实目录与模块组织。
|
||
|
||
至少确认：
|
||
|
||
- 项目入口
|
||
- React Native / Expo / Bare RN 等实际工程形态
|
||
- TypeScript / JavaScript 使用情况
|
||
- Android 工程
|
||
- iOS 工程
|
||
- 公共源码目录
|
||
- 地图相关源码目录
|
||
- 实验代码目录
|
||
- 数据处理目录
|
||
- Shader 或图形相关资源目录
|
||
- assets
|
||
- scripts
|
||
- docs
|
||
- 测试目录
|
||
- 构建配置
|
||
- Metro 配置
|
||
- Babel 配置
|
||
- TypeScript 配置
|
||
|
||
报告中需要给出简化的当前项目结构图。
|
||
|
||
只列架构相关目录，不需要机械复制整个文件树。
|
||
|
||
### 5.2 当前依赖与版本
|
||
|
||
读取实际：
|
||
|
||
- `package.json`
|
||
- lock 文件
|
||
- Android Gradle 相关配置
|
||
- iOS Pod 相关配置
|
||
- 与地图和图形渲染相关的依赖配置
|
||
|
||
重点确认：
|
||
|
||
- React Native 版本
|
||
- React 版本
|
||
- MapLibre React Native 包及实际版本
|
||
- MapLibre Android / iOS Native 版本，如能够从当前工程确认
|
||
- Skia 或其他图形库是否存在
|
||
- Reanimated 等与渲染相关的辅助依赖
|
||
- OpenGL / Metal / WebGL / GPU 相关第三方库
|
||
- Native Module / TurboModule / Fabric 相关配置
|
||
|
||
必须区分：
|
||
|
||
1. 直接依赖
|
||
2. 间接依赖
|
||
3. 原生 MapLibre 底层实际版本
|
||
|
||
如果底层版本无法确认，明确写“未确认”。
|
||
|
||
---
|
||
|
||
## 6. MapLibre 当前接入链调查
|
||
|
||
这是本任务重点。
|
||
|
||
必须从项目实际地图页面或地图 Host 开始向下追踪。
|
||
|
||
调查：
|
||
|
||
`业务/页面`
|
||
↓
|
||
`React Native Map 组件`
|
||
↓
|
||
`MapLibre React Native 封装`
|
||
↓
|
||
`Android / iOS Native View`
|
||
↓
|
||
`MapLibre Native`
|
||
|
||
需要确认当前代码实际使用的：
|
||
|
||
- MapView
|
||
- Camera
|
||
- Style
|
||
- Source
|
||
- Layer
|
||
- ShapeSource
|
||
- RasterSource
|
||
- ImageSource
|
||
- CustomLayer，如存在
|
||
- 地图事件
|
||
- 地图生命周期事件
|
||
- onPress
|
||
- camera change
|
||
- style load
|
||
- render/frame 相关事件
|
||
|
||
报告中必须给出一张文字形式的实际调用关系图。
|
||
|
||
例如：
|
||
|
||
`Screen → MapHost → MapView → RN MapLibre Binding → Native Map View`
|
||
|
||
但最终结构必须根据当前代码得出，不得照抄该例子。
|
||
|
||
---
|
||
|
||
## 7. 地图生命周期调查
|
||
|
||
调查当前代码能够观察或控制哪些生命周期阶段。
|
||
|
||
至少关注：
|
||
|
||
- 地图组件创建
|
||
- Native Map 创建
|
||
- Style 加载开始
|
||
- Style Ready
|
||
- 地图 Ready
|
||
- Camera 变化
|
||
- 地图移动
|
||
- 地图缩放
|
||
- 地图旋转
|
||
- 每帧刷新能力
|
||
- App 前后台
|
||
- MapView unmount
|
||
- Native 资源释放
|
||
|
||
明确：
|
||
|
||
### 当前 TS/RN 层已经直接获得哪些生命周期事件
|
||
|
||
以及：
|
||
|
||
### 哪些生命周期只存在 Native 或 MapLibre 内部，目前 JS 层拿不到
|
||
|
||
---
|
||
|
||
## 8. 自定义渲染扩展点调查
|
||
|
||
调查当前工程和当前依赖版本实际存在的自定义渲染能力。
|
||
|
||
重点寻找：
|
||
|
||
- CustomLayer
|
||
- CustomLayerHost
|
||
- Native Layer
|
||
- Render Layer
|
||
- MapLibre 自定义 layer 接口
|
||
- 自定义 View Overlay
|
||
- Surface
|
||
- Texture
|
||
- GL Context
|
||
- Metal Context
|
||
- Renderer hook
|
||
- Render pass
|
||
- Native callback
|
||
- Frame callback
|
||
|
||
每个发现必须分类。
|
||
|
||
### A. 当前项目已经直接使用
|
||
|
||
### B. 当前依赖已经暴露，但项目尚未使用
|
||
|
||
### C. MapLibre Native 可能支持，但 RN 封装当前未暴露
|
||
|
||
### D. 当前代码无法确认
|
||
|
||
不要把 B/C/D 写成“当前已经支持”。
|
||
|
||
---
|
||
|
||
## 9. Android 渲染架构调查
|
||
|
||
单独调查 Android。
|
||
|
||
至少确认：
|
||
|
||
- MapLibre Android Native 如何被当前 RN 包引入
|
||
- MapView 对应原生 View
|
||
- renderer 所处代码边界
|
||
- 当前工程是否显式涉及 OpenGL
|
||
- 是否能够找到 render thread 相关实现或接口
|
||
- 地图帧刷新由谁驱动
|
||
- Camera / transform 数据当前在哪一层
|
||
- Native Module 是否能够接触 MapView 实例
|
||
- 是否存在可插入自定义渲染的明确入口
|
||
- JS 与 Native 的当前桥接方式
|
||
|
||
如果当前项目使用 New Architecture，也需要说明其实际启用状态。
|
||
|
||
---
|
||
|
||
## 10. iOS 渲染架构调查
|
||
|
||
Android 与 iOS 不得合并推断。
|
||
|
||
单独确认：
|
||
|
||
- iOS MapLibre Native 依赖
|
||
- MapView 原生类型
|
||
- Metal / OpenGL 实际情况
|
||
- renderer 生命周期
|
||
- Camera / transform 数据
|
||
- RN 到 Native 的连接方式
|
||
- 是否能够确认自定义渲染接口
|
||
- 当前 Native 层能够访问的 MapLibre 对象范围
|
||
|
||
如果 Android 与 iOS 能力不一致，必须明确列出。
|
||
|
||
---
|
||
|
||
## 11. JS / UI / Native / Render / GPU 边界
|
||
|
||
基于当前工程实际情况，整理线程和执行层级。
|
||
|
||
至少区分：
|
||
|
||
- JavaScript Thread
|
||
- React Native UI/Main Thread
|
||
- Android/iOS Native 层
|
||
- MapLibre 内部 Worker
|
||
- MapLibre Render Thread
|
||
- GPU
|
||
|
||
如果某个平台实际名称有所不同，使用项目和 MapLibre 当前版本对应的真实名称。
|
||
|
||
重点调查：
|
||
|
||
- 当前高频数据从 JS 传 Native 会经过什么链路
|
||
- 地图 Camera 高频变化如何传播
|
||
- 是否存在 JS 每帧回调
|
||
- 是否存在 Native 每帧回调
|
||
- 是否存在直接 GPU 资源更新的位置
|
||
- 哪些数据如果每帧跨 JS Bridge 会形成明显风险
|
||
|
||
这里只描述架构事实和风险，不提前设计最终优化方案。
|
||
|
||
---
|
||
|
||
## 12. Camera 与坐标变换能力
|
||
|
||
粒子系统未来必须与地图同步，因此重点调查当前代码能够获得哪些：
|
||
|
||
- center
|
||
- zoom
|
||
- bearing
|
||
- pitch
|
||
- bounds
|
||
- viewport size
|
||
- screen coordinate
|
||
- geographic coordinate
|
||
- projection / unprojection
|
||
- camera matrix
|
||
- projection matrix
|
||
- view matrix
|
||
- transform matrix
|
||
|
||
区分：
|
||
|
||
1. JS API 可以直接获取
|
||
2. Native API 可以获取
|
||
3. MapLibre 内部存在但当前封装未暴露
|
||
4. 无法确认
|
||
|
||
尤其要明确：
|
||
|
||
> 当前是否可以获得足够信息，使自定义粒子渲染与 MapLibre 地图的平移、缩放、旋转、pitch 保持严格同步。
|
||
|
||
如果不能确认，不得猜测。
|
||
|
||
---
|
||
|
||
## 13. 帧驱动能力
|
||
|
||
调查未来粒子动画最关键的问题：
|
||
|
||
> 谁负责下一帧？
|
||
|
||
确认当前可利用的：
|
||
|
||
- requestAnimationFrame
|
||
- RN animation frame
|
||
- Reanimated frame callback
|
||
- Native Choreographer / DisplayLink
|
||
- MapLibre render loop
|
||
- CustomLayer render callback
|
||
- GPU render callback
|
||
|
||
需要说明：
|
||
|
||
- 哪些帧驱动来自地图 Renderer 本身
|
||
- 哪些与地图 Renderer 独立
|
||
- 如果使用独立动画循环，理论上可能出现什么同步问题
|
||
|
||
这里只进行架构分析。
|
||
|
||
---
|
||
|
||
## 14. 当前数据与实验代码调查
|
||
|
||
搜索当前仓库内已经存在的：
|
||
|
||
- particle
|
||
- wind
|
||
- current
|
||
- wave
|
||
- grid
|
||
- vector field
|
||
- raster
|
||
- interpolation
|
||
- texture
|
||
- shader
|
||
- velocity
|
||
- animation
|
||
- GPU
|
||
- GL
|
||
- Metal
|
||
- MapLibre custom rendering
|
||
|
||
以及相关实验代码。
|
||
|
||
对发现的代码进行分类：
|
||
|
||
- 可复用基础代码
|
||
- 仅实验用途
|
||
- 与最终架构可能无关
|
||
- 已弃用
|
||
- 状态不明确
|
||
|
||
不得因为文件名相似就判定“可复用”。
|
||
|
||
需要查看真实实现。
|
||
|
||
---
|
||
|
||
## 15. 海洋/气象格点数据未来可能经过的现有层
|
||
|
||
本任务不设计数据系统，只调查当前项目有哪些已经存在的基础设施。
|
||
|
||
关注未来可能涉及：
|
||
|
||
`原始格点数据`
|
||
→ `解析`
|
||
→ `内存结构`
|
||
→ `插值`
|
||
→ `渲染资源`
|
||
→ `地图显示`
|
||
|
||
调查当前是否已经存在：
|
||
|
||
- 数据 Fetch 层
|
||
- ArrayBuffer
|
||
- TypedArray
|
||
- 二进制解码
|
||
- Grid 数据模型
|
||
- 经纬度格点模型
|
||
- 缓存
|
||
- Worker
|
||
- Native Buffer
|
||
- Texture Upload
|
||
- Shader Uniform
|
||
- 数据生命周期管理
|
||
|
||
报告只描述现状。
|
||
|
||
---
|
||
|
||
## 16. 性能风险调查
|
||
|
||
不得运行大型性能优化工作。
|
||
|
||
仅根据真实架构识别潜在风险。
|
||
|
||
至少关注：
|
||
|
||
- JS 高频循环
|
||
- 每帧 JS → Native 调用
|
||
- 大数组 Bridge 传输
|
||
- JSON 序列化
|
||
- ArrayBuffer 复制
|
||
- Native → GPU 重复复制
|
||
- Texture 高频重建
|
||
- 地图 Camera 变化导致的大规模重新计算
|
||
- React re-render
|
||
- MapView Overlay 与地图不同步
|
||
- Android/iOS 实现分叉
|
||
- GPU context 共享风险
|
||
- 地图销毁后的资源泄漏
|
||
|
||
风险需要标记等级：
|
||
|
||
- 高
|
||
- 中
|
||
- 低
|
||
- 尚无法判断
|
||
|
||
---
|
||
|
||
## 17. 当前架构图
|
||
|
||
最终调查报告必须至少包含以下几个简化架构图。
|
||
|
||
全部使用 Markdown 文本图即可。
|
||
|
||
### 17.1 当前 App / MapLibre 总体调用图
|
||
|
||
### 17.2 JS → Native → MapLibre 调用链
|
||
|
||
### 17.3 Android 地图渲染相关层级
|
||
|
||
### 17.4 iOS 地图渲染相关层级
|
||
|
||
### 17.5 当前能够确认的数据与渲染边界
|
||
|
||
不得为了图看起来完整而补画未经确认的组件。
|
||
|
||
未知位置使用：
|
||
|
||
`[未确认]`
|
||
|
||
---
|
||
|
||
## 18. 关键结论分类
|
||
|
||
调查报告结尾必须将全部关键结论整理成四类。
|
||
|
||
### 18.1 已确认事实
|
||
|
||
只能放已有源码或配置证据的事实。
|
||
|
||
### 18.2 当前限制
|
||
|
||
当前架构真实存在的限制。
|
||
|
||
### 18.3 候选扩展点
|
||
|
||
当前看来可能承载未来粒子系统的位置。
|
||
|
||
这里只列候选，不做最终选择。
|
||
|
||
### 18.4 未确认问题
|
||
|
||
列出不能通过本次仓库静态调查确认，但会影响后续架构设计的问题。
|
||
|
||
每个“未确认问题”注明：
|
||
|
||
- 为什么当前无法确认
|
||
- 是否会阻塞 `20_架构设计`
|
||
- 如果需要继续调查，建议采用什么最小方式确认
|
||
|
||
---
|
||
|
||
## 19. 是否需要追加调查任务的判断
|
||
|
||
本次调查结束时必须明确给出：
|
||
|
||
### A. 可以直接进入 `20_架构设计`
|
||
|
||
或：
|
||
|
||
### B. 必须追加一个新的 `10_架构调查` 子任务
|
||
|
||
只有关键技术事实无法确认并且会直接影响架构选择时才能选择 B。
|
||
|
||
如果选择 B，只提出真正需要的最少调查任务。
|
||
|
||
不得为了保险而把所有未知问题拆成新任务。
|
||
|
||
---
|
||
|
||
## 20. 禁止事项
|
||
|
||
本任务禁止：
|
||
|
||
- 修改生产源码
|
||
- 修改实验源码
|
||
- 新建粒子实现
|
||
- 修改 MapLibre 接入
|
||
- 升级 MapLibre
|
||
- 升级 React Native
|
||
- 安装任何新 npm 包
|
||
- 安装任何新 Pod
|
||
- 修改 Gradle 依赖
|
||
- 修改 Podfile
|
||
- 修改 Metro
|
||
- 修改 Babel
|
||
- 修改 TypeScript 配置
|
||
- 修改 Android 原生代码
|
||
- 修改 iOS 原生代码
|
||
- 创建 Shader 实现
|
||
- 创建 CustomLayer 实现
|
||
- 创建 Native Module
|
||
- 进行架构重构
|
||
- 顺手修复发现的问题
|
||
|
||
发现问题只记录。
|
||
|
||
---
|
||
|
||
## 21. 允许执行的验证
|
||
|
||
允许执行不会改变项目状态的只读命令，例如：
|
||
|
||
- Git 状态查询
|
||
- Git 分支查询
|
||
- 文件搜索
|
||
- 文本搜索
|
||
- 查看 package 配置
|
||
- 查看 Gradle 配置
|
||
- 查看 Pod 配置
|
||
- 查看源码
|
||
- 查看当前项目已有脚本定义
|
||
|
||
如果某个命令可能：
|
||
|
||
- 自动安装依赖
|
||
- 修改 lock 文件
|
||
- 修改构建产物
|
||
- 修改 Native 工程
|
||
- 写入项目配置
|
||
|
||
则不要执行。
|
||
|
||
本任务主要依赖静态调查。
|
||
|
||
---
|
||
|
||
## 22. 必做输出
|
||
|
||
### 22.1 架构调查成果
|
||
|
||
必须生成中文调查报告：
|
||
|
||
`docs/20_调查/10_架构调查报告_v1.md`
|
||
|
||
如果同名文件已经存在，不得覆盖，应递增版本号。
|
||
|
||
该报告是后续 `20_架构设计` 的主要输入。
|
||
|
||
### 22.2 Codex 完成报告
|
||
|
||
必须生成中文执行完成报告：
|
||
|
||
`docs/报告/10_架构调查_Codex完成报告_v1.md`
|
||
|
||
如果 `docs/报告/` 不存在，则创建该目录。
|
||
|
||
如果同名报告已经存在，不得覆盖旧报告，应递增版本号。
|
||
|
||
---
|
||
|
||
## 23. 架构调查报告必须包含
|
||
|
||
`docs/20_调查/10_架构调查报告_v1.md` 至少包含：
|
||
|
||
1. 调查环境
|
||
2. Git / 分支 / 工作区状态
|
||
3. 总则 v1 读取情况
|
||
4. 当前项目整体架构
|
||
5. 核心依赖与版本
|
||
6. MapLibre 接入链
|
||
7. MapLibre 生命周期
|
||
8. 自定义渲染能力
|
||
9. Android 渲染架构
|
||
10. iOS 渲染架构
|
||
11. JS / Native / Render / GPU 边界
|
||
12. Camera / Matrix / 坐标转换能力
|
||
13. 帧驱动能力
|
||
14. 当前数据与粒子相关实验代码
|
||
15. 当前可复用基础设施
|
||
16. 性能与线程风险
|
||
17. 当前架构图
|
||
18. 已确认事实
|
||
19. 当前限制
|
||
20. 候选扩展点
|
||
21. 未确认问题
|
||
22. 是否需要追加调查任务
|
||
23. 是否已经具备进入 `20_架构设计` 的条件
|
||
|
||
---
|
||
|
||
## 24. Codex 完成报告必须包含
|
||
|
||
`docs/报告/10_架构调查_Codex完成报告_v1.md` 至少包含：
|
||
|
||
1. 本次实际调查范围
|
||
2. 必做项逐项状态：`已完成 / 未完成 / 无法验证`
|
||
3. 未完成或无法验证的原因
|
||
4. 实际生成或修改的文档清单
|
||
5. 是否修改生产代码
|
||
6. 是否安装或升级依赖
|
||
7. 是否存在需要用户关注的阻塞项
|
||
8. 下一步建议
|
||
|
||
---
|
||
|
||
## 25. 必做项完成检查
|
||
|
||
完成前逐项检查：
|
||
|
||
- [ ] 已读取总则 v1
|
||
- [ ] 已确认当前实际 Git 基线
|
||
- [ ] 已调查整体目录和工程形态
|
||
- [ ] 已确认核心依赖版本
|
||
- [ ] 已追踪 MapLibre 实际调用链
|
||
- [ ] 已调查地图生命周期
|
||
- [ ] 已调查自定义渲染扩展点
|
||
- [ ] 已分别调查 Android
|
||
- [ ] 已分别调查 iOS
|
||
- [ ] 已调查线程与执行边界
|
||
- [ ] 已调查 Camera / 坐标 / Matrix 能力
|
||
- [ ] 已调查帧驱动能力
|
||
- [ ] 已搜索现有粒子/场数据/Shader 实验代码
|
||
- [ ] 已调查当前可复用的数据基础设施
|
||
- [ ] 已整理性能风险
|
||
- [ ] 已绘制必要架构图
|
||
- [ ] 已区分事实、限制、候选和未知项
|
||
- [ ] 已判断是否需要追加调查
|
||
- [ ] 已判断能否进入 `20_架构设计`
|
||
- [ ] 未修改生产代码
|
||
- [ ] 未升级或安装依赖
|
||
- [ ] 已生成 `docs/20_调查/` 下的正式调查报告
|
||
- [ ] 已生成 `docs/报告/` 下的 Codex 完成报告
|
||
|
||
不得静默跳过任何必做项。
|
||
|
||
无法完成的项目必须明确写：
|
||
|
||
`未完成`
|
||
|
||
或：
|
||
|
||
`无法验证`
|
||
|
||
并说明原因。
|
||
|
||
---
|
||
|
||
## 26. 完成标准
|
||
|
||
本任务完成的标准不是“找到一个粒子方案”。
|
||
|
||
真正完成标准是：
|
||
|
||
> 已经能够基于 MapLibreParticleLab 当前真实代码，准确描述项目、React Native、Native、MapLibre 和 GPU 之间的现有边界，并明确下一阶段进行粒子系统架构设计时，哪些能力已经确认、哪些扩展位置值得考虑、哪些关键事实仍需要额外验证。
|
||
|
||
达到这个状态后，`10_架构调查` 才算完成。
|
||
|
||
除非存在真正阻塞架构选择的未知项，否则下一步直接进入：
|
||
|
||
`20_架构设计`
|