MapLibreParticleLab/docs/报告/20_架构设计_Codex完成报告_v1.md

20_架构设计 Codex 完成报告 v1

日期：2026-08-29

任务：docs/40_任务/20_架构设计指令书_v1.md

分支：particle/main

起始提交：127de2271480000fcc8f390d81cf446e98757800

结束提交：127de2271480000fcc8f390d81cf446e98757800（本任务未提交）

执行结论：PASS（文档设计任务）

下一阶段：B，进入 30_最小技术验证

1. 前置文档与 Git 基线

项目	状态	结果
根 AGENTS/基线	已完成	已读取 AGENTS.md、PARTICLE_BASELINE.md
项目总则	已完成	已完整读取 docs/00_项目总则/ 全部当前有效文件
项目规范	已完成	已完整读取 docs/00_项目规范/ 全部当前有效文件
前置调查/报告	已完成	已读取调查报告和 Codex 完成报告
当前架构/记录/Step	已完成	已读取现有架构文档、开发记录和 STEP-000
当前设计任务书	已完成	1092 行已完整读取
Git baseline	已完成	particle/main，HEAD 为上述起始提交；submodule 已查询
工作区干净	未完成	开始时已有上一阶段文档变更及用户提供的两份未跟踪任务书；均予以保留

2. 设计必做项状态

必做项	状态	结果
候选渲染路线比较	已完成	比较 CustomLayer、CustomDrawable、独立 Core layer、Overlay
唯一主路线选择	已完成	独立 Core RasterParticleLayer/RenderRasterParticleLayer + gfx
Core 模块设计	已完成	Field、Adapter、Simulation、Render、GPU、Mask、Controller
与 Style/RenderTree/gfx 关系	已完成	正式进入 Style/RenderTree，offscreen pass + translucent composite
WeatherColor/Particle 边界	已完成	分离 Layer/RenderLayer/GPU 状态/动画生命周期
Data/Field contract	已完成	RasterArraySource、immutable snapshot、revision、canonical U/V
Fixture contract	已完成	metadata.json、field.f32、mask.u8、字节序、校验和、五个预留场景
GPU resource 设计	已完成	velocity、State A/B、Trail A/B、Mask、uniform、shader set
GPU state/simulation	已完成	逻辑状态、render-pass ping-pong、NoData/mask/respawn；compute 延后
Trail 架构	已完成	第一阶段包含 screen-space ping-pong trail，Camera 变化清空
Land/Ocean Mask	已完成	独立 snapshot/cache/texture，OCEAN_ONLY 共享，缺失 fail closed
数据流与频率分类	已完成	低频、每帧、Camera 变化三类已定义
线程模型	已完成	Map/UI、Worker、Render、GPU 的所有权和交接已定义
Camera/Matrix 同步	已完成	只读取当前 render frame Paint/Transform parameters
帧驱动	已完成	MapLibre render loop + needsRepaint，禁用独立粒子时钟
Android 薄接入	已完成	typed JNI；禁止 raw long；OpenGL 主线、Vulkan gate
iOS 薄接入	已完成	Core Source/Layer peer；CustomStyleLayer 只作参考；后续 Metal/OpenGL gate
生命周期状态机	已完成	DISABLED 至 ERROR/CONTEXT_LOST 的状态、恢复和释放责任已定义
公共 API/配置分层	已完成	backend-independent source/layer/options/status；内部参数不外露
错误/降级	已完成	Field、Mask、GPU、backend、context、shader、memory pressure 均定义
性能预算	已完成	给出待验证目标和测量档位，未声称性能已达到
最小技术验证清单	已完成	压缩为四项，并标记阻塞性和最小方法
不采用方案	已完成	逐项拒绝任务书要求的八类方案及 CPU/compute-only 等
九类架构图	已完成	总体、Core、fixture 数据流、每帧、Camera、Android、iOS、Mask、状态机
架构冻结项	已完成	14 项正式冻结；同时列出不得冻结项
下一阶段判断	已完成	B：进入 30_最小技术验证

3. 核心架构选择

正式主路线是新增独立 Core RasterParticleLayer、RenderRasterParticleLayer 和 mbgl::particle 模块，通过 RasterArraySource 接受 immutable Field snapshot，进入 MapLibre Style/RenderTree，并使用 gfx Texture/RenderTarget/Drawable/Shader/UploadPass 完成 GPU simulation、trail 与 translucent composite。

CustomLayer/CustomDrawable 不构成产品双轨；Android raw CustomLayerHost 不进入正式 API。平台只提供类型安全 Source/Layer peer、backend lifecycle 与 capability 薄接入。

4. 实际生成或修改文件

• 新增 docs/10_架构/20_粒子系统总体架构设计_v1.md。
• 新增 docs/报告/20_架构设计_Codex完成报告_v1.md。
• 追加 粒子开发记录.md。
• 未修改现有 docs/10_架构/MapLibre粒子总体架构_v1.md；其简略 Layer 顺序与本设计一致。
• 未新增或修改 docs/50_Step记录/；符合任务书第 31 节。

5. 无法验证与未完成

无法验证

• 独立 particle RenderLayer 在 Android OpenGL/Vulkan 的运行时 pass/barrier/context 行为。
• State/Trail RenderTarget 的实际格式、性能和 context recreation 时间。
• Camera/wrap/Mask 在真机/模拟器上的视觉正确性。
• iOS Metal/OpenGL 的粒子 Core layer 薄接入。
• 最终 FPS、最大粒子数、最佳 texture format、设备能力和生产 Mask 来源。

这些均已列入 30_最小技术验证 或明确标记为后续 Gate，不影响本次总体设计文档 PASS。

未完成

• 无。本任务要求的设计输出均已完成；生产实现、构建和运行时验证本来就是本任务禁止项。

6. 代码、依赖、构建与测试

• 生产/实验源码：未修改。
• Android/iOS/Gradle/Pod/CMake/package/lock：未修改。
• 依赖：未安装、未升级。
• 构建：未执行；任务明确禁止会修改工程状态的构建。
• 测试：未执行；本阶段仅做静态架构设计。
• APK/AAR/其他产物：无。
• 项目总则/项目规范：未修改。

7. 与指令书差异、阻塞和建议

• 与指令书差异：无。
• 与长期总则冲突：无。
• 阻塞：没有阻塞本次设计完成的事项；存在四项会阻塞后续正式实现或平台扩展的运行时验证。
• 建议：下一份正式指令书进入 30_最小技术验证，只覆盖设计文档第 26 节四项验证，不创建完整粒子产品实现，也不重新讨论总体架构。