# 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 节四项验证，不创建完整粒子产品实现，也不重新讨论总体架构。