docs: add STEP-063 particle release engineering task

2026-09-09 10:31:37 +08:00
parent 17d791b249
commit 3664db0770
1 changed files with 889 additions and 0 deletions
--- a/docs/40_任务/STEP-063_MapLibre粒子Android_v1发布工程化与ReactNative可导入包_Codex任务_v1.md
+++ b/docs/40_任务/STEP-063_MapLibre粒子Android_v1发布工程化与ReactNative可导入包_Codex任务_v1.md
@@ -0,0 +1,889 @@
+# STEP-063 MapLibre 粒子 Android v1 发布工程化与 React Native 可导入包 Codex 任务 v1
+
+## 0. 任务性质
+
+本任务开始把已经通过 Android 实机综合验证的 MapLibre Particle 从“开发工程状态”整理为“可版本化、可发布、可由 React Native 通过包依赖导入的组件”。
+
+本任务属于发布工程化与包结构整理，不是继续开发新的粒子渲染能力。
+
+当前用户已确认：
+
+- Android MapLibre Particle 当前能力达到满意水平。
+- STEP-062 可按 `CLOSED / PASS` 收尾。
+- 当前阶段不接入 NavSea。
+- 发布服务器、npm Registry、Maven Repository 的最终部署位置暂不决定。
+- npm 正式包名采用：
+  - `@navsea/maplibre-particle-rn`
+- 正式版本规则采用：
+  - `<上游 MapLibre Native 版本>-particle.<NavSea 修订号>`
+- 当前计划首个正式版本：
+  - `13.4.1-particle.1`
+- Android Maven artifact 计划采用：
+  - group: `cc.navsea.maplibre`
+  - artifact: `android-sdk-particle-opengl`
+  - version: `13.4.1-particle.1`
+
+如果仓库实际调查证明基础 MapLibre Native 并非 `13.4.1`，必须停止版本改写并先报告，不得自行猜测或强行套用版本号。
+
+---
+
+# 1. 本任务目标
+
+完成以下四个目标：
+
+1. 冻结并记录当前 MapLibre Particle 的真实上游版本基线。
+2. 建立正式版本号、release manifest、CHANGELOG 与发布契约。
+3. 把当前 React Native 接入整理成一个正式 npm package：
+   - `@navsea/maplibre-particle-rn`
+4. 建立一个“只通过发布包消费”的独立 Consumer Test Host，用于后续证明 NavSea 不需要源码路径或 MapLibre Native 源码编译即可使用。
+
+本任务结束时，不要求真正上传到任何服务器。
+
+最终服务器发布位置后续单独决定。
+
+---
+
+# 2. 强制边界
+
+## 2.1 禁止继续扩展粒子功能
+
+本任务不得新增或重写：
+
+- Particle GPU simulation
+- WeatherColor 算法
+- Timeline / Playback 算法
+- HostField 二进制入口
+- RasterArraySource 核心语义
+- U/V canonical contract
+- MapLibre renderer
+- JNI 核心路径
+- WeatherRuntime 业务语义
+
+除非当前发布工程化过程中发现明确的“无法打包/无法消费”的结构性阻塞。
+
+如果出现此类阻塞：
+
+1. 停止扩大修改。
+2. 明确记录阻塞位置。
+3. 说明最小修复建议。
+4. 不得借发布任务顺便重构 Native/Core。
+
+---
+
+## 2.2 不接入 NavSea
+
+本任务不得修改 NavSea 仓库。
+
+不得：
+
+- 在 NavSea 中安装 npm package
+- 修改 NavSea Metro
+- 修改 NavSea Gradle
+- 修改 NavSea Pod
+- 修改 NavSea Store / Adapter / Action
+- 将 Test Host 逻辑搬入 NavSea
+
+本任务只负责把发布组件准备好。
+
+---
+
+## 2.3 不决定最终发布服务器
+
+本任务不得擅自加入：
+
+- 公司 npm Registry URL
+- GitHub Packages
+- GitLab Packages
+- Gitea Packages
+- Nexus
+- Artifactory
+- Verdaccio
+- 私有 Maven Repository URL
+- 生产用户名、密码、Token、证书
+
+可以建立与 Registry 无关的标准发布配置和说明。
+
+可以使用本地 `.tgz`、本地 staging 目录作为“未上传发布物”验证手段。
+
+---
+
+## 2.4 Android 编译边界
+
+严格遵守项目长期规则：
+
+**所有 Android 编译由用户手工执行。**
+
+Codex 不得执行：
+
+- Android Gradle assemble
+- Android Gradle build
+- AAR build
+- AAR publish
+- Maven Local publish
+- APK build
+- APK install
+- ADB
+- Android 实机测试
+
+Codex 可以：
+
+- 修改构建配置
+- 修改版本号
+- 准备 publication 配置
+- 做非 Android 编译的静态检查
+- 执行 TypeScript 编译/类型检查（若不触发 Android build）
+- 执行 `npm pack`
+- 检查 `.tgz` 内容
+- 编写用户手工 Android 构建命令
+
+---
+
+## 2.5 不执行 Jest
+
+本任务不执行 Jest，也不新增 Jest 作为验收要求。
+
+---
+
+# 3. 第一步：真实基线只读调查
+
+开始修改前必须先从当前仓库真实代码调查。
+
+至少确认：
+
+## 3.1 MapLibre Native 基础版本
+
+从实际构建文件、版本定义、Gradle publication、Git metadata 等确认：
+
+- upstream MapLibre Native version
+- 当前 Android renderer variant
+- 当前 STEP-061 AAR 坐标
+- 当前 STEP-061 AAR version
+- 当前 Native/Core source 与该版本之间的关系
+
+预期：
+
+```text
+upstreamMapLibreNative = 13.4.1
+currentDevelopmentArtifact = org.maplibre.gl:android-sdk-opengl:13.4.1-step061
+renderer = opengl
+```
+
+但必须以仓库实际内容为准。
+
+---
+
+## 3.2 React Native 基线
+
+调查当前 RN bridge / package 的真实位置与结构。
+
+至少确认：
+
+- 当前 RN package 名
+- 当前 RN package version
+- 当前 `package.json`
+- 当前 Android module / Gradle 文件
+- 当前 autolinking 方式
+- 当前 MapLibre RN 公共 API 导出方式
+- `WeatherRuntime`
+- `RasterParticleLayer`
+- `WeatherColorLayer`
+- HostField submit API
+- RN Test Host 当前如何引用该 RN 模块
+- 是否存在 `file:`、workspace path、source path 等开发期依赖
+
+必须明确：
+
+**哪些路径只是开发期源码引用，正式 npm package 后必须消失。**
+
+---
+
+## 3.3 当前正式能力链路
+
+只读确认当前已冻结链路：
+
+```text
+React Native Host
+  ↓ metadataJson + local file:// binary payload
+RN bridge
+  ↓
+WeatherRuntime
+  ↓
+RasterArraySource::submitHostField()
+  ↓
+LocalParticleFieldFeed
+  ↓
+ParticleFieldDataAdapter
+  ↓
+ParticleFieldSnapshot
+  ↓
+Core Timeline / Runtime Field Window
+  ↓
+WeatherColorLayer + RasterParticleLayer
+```
+
+不得因为发布工程化另建第二套入口。
+
+---
+
+# 4. 第二步：正式版本契约
+
+调查确认基础版本无误后，建立正式版本契约。
+
+## 4.1 正式版本
+
+首个正式版本：
+
+```text
+13.4.1-particle.1
+```
+
+语义：
+
+```text
+13.4.1
+= 上游 MapLibre Native 基础版本
+
+particle
+= NavSea Particle 扩展发行线
+
+1
+= 基于该 upstream version 的第 1 个 NavSea Particle 正式修订
+```
+
+后续规则：
+
+```text
+13.4.1-particle.2
+13.4.1-particle.3
+
+13.5.0-particle.1
+
+14.0.0-particle.1
+```
+
+禁止以后恢复使用 `step061` 这种开发阶段编号作为正式发行版本。
+
+---
+
+## 4.2 npm package
+
+正式 npm package：
+
+```text
+@navsea/maplibre-particle-rn
+```
+
+正式首发 version：
+
+```text
+13.4.1-particle.1
+```
+
+要求 package 名清楚表达：
+
+- NavSea 维护
+- MapLibre
+- Particle
+- React Native
+
+---
+
+## 4.3 Android Maven artifact
+
+正式 Android artifact：
+
+```text
+cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1
+```
+
+不得继续使用官方坐标作为 NavSea 正式发行坐标：
+
+```text
+org.maplibre.gl:android-sdk-opengl
+```
+
+注意：
+
+Java/Kotlin package namespace 不要求因此重命名。
+
+本任务重点是 Maven publication coordinate 与依赖契约，不允许进行大规模 Java/C++ namespace rename。
+
+---
+
+# 5. 第三步：建立 Release Manifest
+
+在项目中建立稳定、机器可读的 release manifest。
+
+路径由 Codex根据现有仓库结构选择，但建议类似：
+
+```text
+release/maplibre-particle/release-manifest.json
+```
+
+或：
+
+```text
+release/maplibre-particle/13.4.1-particle.1.json
+```
+
+至少包含：
+
+```json
+{
+  "release": "13.4.1-particle.1",
+  "upstreamMapLibreNative": "13.4.1",
+  "extensionLine": "particle",
+  "extensionRevision": 1,
+  "platform": {
+    "android": {
+      "renderer": "opengl"
+    }
+  },
+  "reactNativePackage": {
+    "name": "@navsea/maplibre-particle-rn",
+    "version": "13.4.1-particle.1"
+  },
+  "nativeArtifact": {
+    "group": "cc.navsea.maplibre",
+    "artifact": "android-sdk-particle-opengl",
+    "version": "13.4.1-particle.1"
+  },
+  "publication": {
+    "npmRegistry": null,
+    "mavenRepository": null
+  }
+}
+```
+
+可以增加必要字段，例如：
+
+- source commit
+- compatibility
+- canonical field schema
+- RN compatibility
+- minSdk / compileSdk（如果项目已有真实事实）
+- release state
+
+但不得猜测未确认版本。
+
+---
+
+# 6. 第四步：正式 React Native package
+
+目标：
+
+```text
+@navsea/maplibre-particle-rn@13.4.1-particle.1
+```
+
+必须成为 NavSea 未来唯一面对的 React Native MapLibre Particle 包入口。
+
+---
+
+## 6.1 设计原则
+
+NavSea 未来目标使用方式：
+
+```ts
+import {
+  MapView,
+  Camera,
+  RasterParticleLayer,
+  WeatherColorLayer,
+  WeatherRuntime,
+} from '@navsea/maplibre-particle-rn';
+```
+
+实际导出名称必须依据当前仓库真实 API。
+
+不得为了示例强行重命名现有稳定 API。
+
+---
+
+## 6.2 不允许正式消费源码路径
+
+正式 package 不得要求 Consumer：
+
+```text
+file:../MapLibreParticleLab/...
+../../platform/react-native
+workspace 源码路径
+CMake source path
+MapLibre Native source tree
+本地源码软链接
+```
+
+Consumer 只能依赖正式 npm package。
+
+Android Native 应通过正式 artifact dependency 解决，而不是 Consumer 直接编译 MapLibre Native 源码。
+
+---
+
+## 6.3 包内部结构
+
+根据当前 React Native package 实际结构做最小整理。
+
+要求：
+
+- `package.json` 名称正式改为 `@navsea/maplibre-particle-rn`
+- version = `13.4.1-particle.1`
+- 保留正确的 React Native autolinking
+- 保留当前稳定 JS/TS 公共 API
+- 保留 Native bridge
+- 内部 Android Gradle dependency 改为正式 artifact：
+  - `cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1`
+- 不得同时再自动引入官方 `org.maplibre.gl:android-sdk-opengl` 导致双 Native AAR
+- 不得引入第二份 MapLibre RN native module
+
+---
+
+## 6.4 唯一 MapLibre RN 入口原则
+
+需要重点审计：
+
+Consumer 是否仍然需要同时安装：
+
+```text
+@maplibre/maplibre-react-native
+```
+
+如果当前 NavSea Particle RN package 本质上是对 MapLibre RN 的完整 fork/扩展，则正式目标应是：
+
+```text
+Consumer
+  ↓
+@navsea/maplibre-particle-rn
+  ↓
+唯一 RN native module
+  ↓
+cc.navsea.maplibre:android-sdk-particle-opengl
+```
+
+不应形成：
+
+```text
+@maplibre/maplibre-react-native
+
+@navsea/maplibre-particle-rn
+```
+
+两套 Native MapLibre 同时进入 App。
+
+如果仓库实际结构暂时无法做到唯一入口，必须在报告中明确说明，不得假装已经完成。
+
+---
+
+# 7. 第五步：发布包内容审计
+
+必须能够执行：
+
+```text
+npm pack
+```
+
+生成类似：
+
+```text
+navsea-maplibre-particle-rn-13.4.1-particle.1.tgz
+```
+
+实际文件名以 npm 规则为准。
+
+Codex 必须检查 tarball 内容。
+
+至少确保：
+
+必须包含：
+
+- package.json
+- JS/TS build output 或正式 package 所需源码
+- type declarations
+- React Native native module 必需文件
+- android module 必需文件
+- README
+- LICENSE/NOTICE（依据仓库现有许可要求）
+- 必需 plugin/config 文件
+
+不得包含：
+
+- node_modules
+- `.git`
+- 大量 build cache
+- Android APK
+- 临时 log
+- Test Host
+- WeatherV2 测试数据
+- `.codex-build-logs`
+- unrelated docs
+- 任何 credential
+
+---
+
+# 8. 第六步：Android artifact publication 配置
+
+把 Android Native publication 从开发阶段坐标整理成正式坐标。
+
+目标：
+
+```text
+groupId:
+cc.navsea.maplibre
+
+artifactId:
+android-sdk-particle-opengl
+
+version:
+13.4.1-particle.1
+```
+
+必须保留：
+
+```text
+renderer = opengl
+```
+
+本阶段只准备 publication 配置。
+
+Codex 不执行 AAR build 或 publish。
+
+---
+
+# 9. 第七步：建立独立 Consumer Test Host
+
+新增一个真正用于验证“发布包消费”的最小 React Native Test Host。
+
+名称建议：
+
+```text
+MapLibreParticlePackageConsumerTestHost
+```
+
+实际路径应遵守现有 integration 结构。
+
+---
+
+## 9.1 Consumer Test Host 的核心约束
+
+它不得：
+
+- 引用 MapLibreParticleLab RN 源码目录
+- 使用 workspace source dependency
+- 使用相对路径导入正式 RN package 源码
+- 直接引用 MapLibre Native source tree
+- 自己实现 WeatherRuntime bridge
+- 复制 Native bridge 源码
+
+它只能通过安装后的：
+
+```text
+@navsea/maplibre-particle-rn
+```
+
+使用功能。
+
+---
+
+## 9.2 当前服务器未决定时的测试方式
+
+由于最终 npm/Maven 服务器尚未决定，本阶段允许：
+
+### npm
+
+使用本地：
+
+```text
+npm pack
+```
+
+生成 `.tgz` 后安装：
+
+```text
+npm install <package.tgz>
+```
+
+这属于“发布包消费”，不是源码路径消费。
+
+### Android Native artifact
+
+本任务只准备正式 artifact publication。
+
+后续由用户手工构建并放入 Maven Local 或临时 staging repository，再进行 Consumer APK 编译。
+
+不得因为服务器未决定，就退回 source path。
+
+---
+
+## 9.3 Consumer Test Host 最低功能
+
+先做最小 smoke host，不要求复制 STEP-062 全部复杂测试 UI。
+
+最低要求：
+
+- MapLibre MapView
+- GSI basemap
+- `WeatherColorLayer`
+- `RasterParticleLayer`
+- `WeatherRuntime`
+- 一个最小真实或 canonical fixture 提交入口
+- Runtime state 可见
+- Particle / WeatherColor 显示
+
+如果已有可复用 STEP-062 Test Host 逻辑，可以复用业务层代码，但不得通过源码 dependency 复用 RN package。
+
+---
+
+# 10. 第八步：文档
+
+所有文档中文。
+
+至少新增或更新：
+
+## 10.1 架构/发布设计
+
+建议：
+
+```text
+docs/30_设计/MapLibre粒子Android发布与ReactNative包设计_v1.md
+```
+
+至少说明：
+
+- upstream version
+- NavSea Particle version rule
+- npm package name
+- Maven coordinate
+- RN package 与 Native artifact 关系
+- 为什么 Consumer 不编译 MapLibre Native 源码
+- 为什么不能同时装官方 RN MapLibre 和 NavSea Particle RN
+- server registry 尚未决定
+- 本地 `.tgz` / staging 只是预发布验证手段
+- 后续 upstream upgrade 规则
+
+---
+
+## 10.2 STEP 记录
+
+建议：
+
+```text
+docs/50_Step记录/STEP-063_MapLibre粒子Android_v1发布工程化_v1.md
+```
+
+---
+
+## 10.3 Codex 完成报告
+
+建议：
+
+```text
+docs/报告/STEP-063_MapLibre粒子Android_v1发布工程化_Codex完成报告_v1.md
+```
+
+---
+
+## 10.4 CHANGELOG
+
+为正式 package 建立中文 CHANGELOG 或遵循仓库现有发布记录结构。
+
+至少记录：
+
+```text
+13.4.1-particle.1
+
+- 基于 MapLibre Native 13.4.1
+- Android OpenGL
+- WeatherColor
+- RasterParticle
+- HostField binary ingress
+- Timeline / Playback
+- React Native WeatherRuntime
+- STEP-061 Native/RN ingress 验证
+- STEP-062 GSI + WeatherV2 + Particle Android 综合验证
+```
+
+不得把没有验证的能力写成已通过。
+
+---
+
+# 11. 静态验收
+
+Codex 可执行且应执行：
+
+- package JSON 校验
+- TypeScript typecheck
+- `npm pack`
+- tarball 内容列表审计
+- 检查正式 package 中不存在开发期 `file:` dependency
+- 检查正式 package 中不存在 MapLibre Native source path
+- 检查 Android Gradle dependency 指向正式 coordinate
+- 检查没有同时依赖正式 Particle AAR 与官方 MapLibre AAR
+- `git diff --check`
+- repository search 审计旧 `13.4.1-step061` 使用位置
+
+注意：
+
+历史文档中出现 `13.4.1-step061` 是合法的。
+
+但正式 release/package/build config 不得继续把它作为当前发行依赖。
+
+---
+
+# 12. 用户手工 Android 验证入口
+
+Codex 完成本任务后，必须给出准确的用户手工命令，但不得自行执行。
+
+后续用户将手工完成两个阶段：
+
+## 阶段 A：正式 AAR
+
+构建：
+
+```text
+cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1
+```
+
+并验证 artifact 生成。
+
+最终 publish server 尚未决定，因此可先由用户手工发布到 Maven Local 或指定 staging 目录用于验证。
+
+---
+
+## 阶段 B：Consumer Test Host APK
+
+Consumer 只安装：
+
+```text
+@navsea/maplibre-particle-rn@13.4.1-particle.1
+```
+
+通过正式 artifact dependency 获取 Android Native。
+
+然后用户手工：
+
+- Android assembleDebug
+- 安装 APK
+- 实机 smoke
+- GSI
+- WeatherColor
+- Particle
+- Runtime READY
+
+通过后才能正式创建 release tag。
+
+---
+
+# 13. Git Tag 规则
+
+本任务暂时不得创建正式 release tag。
+
+原因：
+
+`13.4.1-particle.1` 必须先经过：
+
+1. 正式 AAR 手工构建
+2. npm tarball package consumer 验证
+3. Consumer Test Host Android APK 实机验证
+
+全部通过后，再单独执行最终 Release Freeze 任务创建 tag。
+
+建议未来 tag：
+
+```text
+maplibre-particle/android/13.4.1-particle.1
+```
+
+实际 tag 命名在最终发布任务确认。
+
+---
+
+# 14. Git 收尾
+
+本任务会修改项目文件，因此必须提交并 push 到：
+
+```text
+origin/particle/main
+```
+
+严格遵守项目 Git 规则。
+
+不得：
+
+```text
+git add .
+git add -A
+```
+
+必须精确 add 本任务文件。
+
+不得提交历史无关 untracked 文件。
+
+完成后：
+
+```text
+git fetch origin
+git rev-parse HEAD
+git rev-parse origin/particle/main
+git status --short
+```
+
+必须确认：
+
+```text
+HEAD == origin/particle/main
+```
+
+如果 push 失败：
+
+**不得声称任务完成。**
+
+---
+
+# 15. 任务完成状态
+
+如果代码/package/publication 配置均完成，静态检查和 npm pack 均通过，但尚未执行用户手工 Android 构建：
+
+状态写：
+
+```text
+IMPLEMENTED / WAITING_MANUAL_RELEASE_VALIDATION
+```
+
+不得提前写：
+
+```text
+RELEASED
+CLOSED / PASS
+```
+
+正式 `CLOSED / PASS` 等待后续用户手工 AAR + Consumer APK 验证。
+
+---
+
+# 16. Codex 最终报告必须包含
+
+- 实际确认的 upstream MapLibre Native version
+- 当前 RN 基线
+- 正式版本号
+- npm package name
+- Maven coordinate
+- release manifest 路径
+- 正式 RN package 路径
+- Consumer Test Host 路径
+- `npm pack` 结果
+- tarball 文件名
+- tarball 内容审计结果
+- 是否仍存在正式配置中的 `step061`
+- 是否存在 `file:` 或 source-path consumer dependency
+- 是否修改 Native/Core 功能代码
+- 是否执行 Android Gradle
+- 是否构建 AAR
+- 是否执行 ADB
+- 是否执行 Jest
+- 用户下一步手工命令
+- commit hash
+- commit message
+- push result
+- remote branch
+- Final HEAD
+- 历史无关 untracked 项说明
+