# 粒子系统项目规则与设计决策 v1

## DEC-001 Linux 与 Win11 职责分离
Linux 是 MapLibre Native / Particle Renderer 的主要开发和构建环境，正式源码 `/mnt/sda1/MapLibreParticleLab`。Linux 负责 Native、Particle、Test App、Fixture、AAR/APK、OpenGL/Vulkan、Native 调试、性能与 Git。Win11 负责 NavSea、NavSea Android 编译、Android 模拟器、Particle Test APK 运行和产品 Gate。

## DEC-002 独立 Particle Test App
必须建立长期维护的独立测试 App。它不是 Demo，而是粒子 Renderer 的开发、调试、回归和性能平台。日常粒子开发不直接使用 NavSea。Android 第一阶段优先原生 Test App。

## DEC-003 NavSea 只用于关键产品 Gate
NavSea 是最终产品，不作为日常粒子调试宿主。只在自编译等价验证、关键 Particle Gate、真实 Layer Stack、Weather/Mask、产品级回归和最终集成时使用。

## DEC-004 OpenGL 为 Android 主开发 Backend
初期主开发 OpenGL；架构必须服从 MapLibre `gfx` 抽象，不能锁死 OpenGL。

## DEC-005 Vulkan / Metal 不是后补重写
Particle State、Velocity、Tile、生命周期、Style/RenderLayer、Coverage、Color Ramp、Mask 尽量共享；后端差异主要放在 Shader、Texture、RenderTarget、RenderPass、gfx backend。iOS/Metal 以后单独设计测试流程。

## DEC-006 WeatherColorLayer 与 RasterParticleLayer 分离
定量天气色场和粒子流动分为 `WeatherColorLayer` 与 `RasterParticleLayer`。

## DEC-007 天气色场不靠低透明度看底图
天气定量颜色保持准确；岸线、等深线、航标、航道、文字和导航对象绘制在天气层上方。

## DEC-008 Coverage
Wind=`GLOBAL`；Wave/Tide/Current/Sea Temperature 等=`OCEAN_ONLY`。

## DEC-009 统一 Land/Ocean Mask
所有 OCEAN_ONLY 字段共用统一 Mask；海岸线语义尽量与 NavSea/MapLibre 海图一致，不依赖天气模型 nodata。

## DEC-010 正式目标是 GPU Particle Engine
核心至少包括 Velocity Texture、Particle State Texture A/B、Ping-Pong、Update Pass、Draw Pass、Trail Render Target、Color Ramp。CPU 每粒子循环不能作为正式主实现。

## DEC-011 Camera 正确后再冻结 Particle State Model
先验证 Pan/Zoom/Rotate/Pitch/Resize/Camera Animation，再冻结状态格式。

## DEC-012 Fixture 优先
至少：uniform-east/north/west/south、vortex-clockwise/counterclockwise、shear、divergence、convergence、coastal-mask。真实天气服务器不是早期 Renderer 调试前置条件。

## DEC-013 thin-hook 原则
目标约 95% 粒子代码放新增文件/独立模块；MapLibre 官方现有文件只做必要 Layer/Source/RenderLayer/Shader/Build/Backend 薄接入，降低 upstream merge 冲突。

## DEC-014 普通 Step 禁止修改项目总则
需要改变长期规则时，只在执行报告提出建议。

## DEC-015 GPT“粒子系统”项目是设计背景来源
GPT 写设计和指令书时要参考该项目既有讨论；正式权威规则以 Git 仓库本目录为准。

## DEC-016 大阶段目录按目的建立
使用两位数字前缀；进入新阶段前 GPT 先告知用户目录目的和预计 Step 范围。

## DEC-017 Step 指令书与执行报告同目录
`step-xxxx-目的内容.md` 与 `step-xxxx-目的内容-执行报告.md` 放同一大阶段目的目录。

## DEC-018 报告由指令书预先定义
指令书必须事先写清报告完整路径、文件名、章节、Git 信息、构建信息、APK/AAR、大小、SHA256、PASS/PARTIAL/BLOCKED/FAIL。不得执行完后临时追加未定义报告。