TODO — 能力缺口与改进方向

基于当前 @m-tech/gis-core（约 0.4.x）代码结构与导出表面的审视，按优先级粗分。
非正式排期，供产品/研发与 AI 后续迭代参考。

P0 — 工程质量与可维护性

项	说明	建议
自动化测试几乎为零	无 `.test` / `.spec`，回归全靠 demo 手点	对 `Position`/`Transform`/`Util` 先补单元测试；对 Overlay 挂载用 Cesium 无头或 mock
类型安全偏弱	大量 `any`、options 未建模	逐步为 Layer/Overlay options、`setStyle` 补 interface；减少 public API 的 any
Material 仍为 JS	`material/*/.js` 与 TS 主代码割裂	迁移为 TS + 与 `effects/shader` 统一注册表
导出不一致	`effects/index` 有 Rain/Snow/Bloom/RadarScan 等，根 `index.ts` 仅导出 Fog/Cloud/AtmosphereFog	梳理对外 API 清单，该导出的补齐，内部的明确标记
`WKTLayer2` 未导出	双实现并存易混淆	合并或删除其一，文档写清选用规则
销毁/泄漏	Viewer、分析类、Widget、postProcess、监听器销毁路径不统一	统一 `destroy()` 约定；demo unmount 必须 destroy Viewer
Cesium 打进 bundle	vite 未 external cesium，包体积大、多实例风险	评估 peerDependencies + external，文档说明 CESIUM_BASE_URL

P1 — 核心 GIS 能力补齐

数据与图层

[ ] GeoJSON / TopoJSON Layer：标准矢量入口（现多靠 WKT/Entity 手工转）
[ ] KML / KMZ Layer
[ ] GeoServer / WMS / WFS / WMTS 一等公民封装（不止通用 Imagery）
[ ] 矢量瓦片样式体系：MvtLayer 增强（数据驱动样式、过滤、点击拾取文档化）
[ ] 多地形融合 / 地形夸张 / 地形开挖 API 产品化
[ ] 3D Tiles 批处理：样式、条件显示、裁剪、属性查询、失败重试与进度事件标准化（Tileset 已有能力需文档+统一）
[ ] 点云（Potree / 3D Tiles 点云） 加载与样式
[ ] BIM / IFC 或常见行业模型管线（可放 biz，core 提供底层 primitive 支持）

覆盖物与渲染

[ ] 聚合 Clustering 产品化：EntityLayer declutter 逻辑增强、样式可配置、事件冒泡
[ ] 大规模点/线性能路径：Primitive + GroundPrimitive + ClassificationPrimitive 封装对齐 Entity API
[ ] 动态轨迹 / 路径巡游：时间轴采样、模型朝向、ROAM（现有 KeyboardRoaming 偏输入；缺路径漫游）
[ ] 模型 Model Overlay（glTF）一等类，而不是业务侧直接 Entity
[ ] 挤出建筑 / 立体面 便捷 API
[ ] 视频融合 / 投影纹理 能力文档化与通用化（已有 Video，可扩展）

分析与量测

[ ] 剖面分析（地形/模型剖面）独立模块
[ ] 通视网络 / 多点可视域
[ ] 日照 / 阴影分析（时间驱动）
[ ] 缓冲区 与 Turf 能力对齐（2D/3D、联合/擦除）
[ ] 空间关系查询（包含、相交）基于当前 Entity/GeoJSON
[ ] Measure / Plot 结果序列化（GeoJSON 导出导入）与撤销栈

交互与控件

[ ] 统一 Popup / InfoBox 替代业务各写一套 DivBoard
[ ] 图例 Legend Widget
[ ] 图层树 / 管理器 API（显隐、透明度、排序、分组）— 现靠 cache 不够用
[ ] 绘制工具状态机 文档与禁用冲突（与量测、拾取互斥）
[ ] 触控 / 移动端 手势与 UI 适配
[ ] 多屏 / 分屏联动 Viewer

坐标与服务

[ ] 坐标系：CGCS2000 / 地方坐标 / 七参数更完整链路（Convertor 已有部分）
[ ] 离线包规范：影像、地形、3D Tiles 本地目录约定 + 文档
[ ] 地名搜索 Suggestion 多源插件化（现配置化不足）
[ ] 底图 Key 管理：天地图等 key 注入方式标准化，避免硬编码

P2 — 工程化、生态与体验

项	说明
变更日志 / Changeset	monorepo 有 changesets，core 发版说明需常态化
Tree-shaking	评估副作用（css 全局引入、console 版本日志、globalThis.Cesium）对 tree-shake 影响
按需加载	分析/特效/超图分包 `export` 子路径
Vue / React 绑定	`packages/vue` 仍弱；官方 hooks：`useViewer` / 生命周期
SSR / 微前端	动态 import Cesium，避免 window 假设
i18n	Widget 文案中英
主题	控件 dark/light 与大屏场景
性能面板	实体数量、draw call、内存简易诊断 Widget
CI	构建 + 类型检查 + 单测进 pipeline
示例资产	demo 依赖外网影像/模型时提供 mock 或内置小数据
SuperMap 边界	S3M 能力与 Cesium 路径的职责、版本矩阵写清
安全	任意 URL 图层的 SSRF/CORS 说明；token 刷新

P3 — API 设计债（中长期）

双轨 Overlay：Overlay vs PrimitiveOverlay 概念重复，考虑统一接口或明确选用表。
Event.once 实现可疑（Event.ts 中 once 立刻 removeCallback），需审计行为。
relate 判断 bug 风险：!this._relaters.includes((o) => o === overlay) 用法不正确（includes 不能传谓词），应 some。
默认开启 lighting + HDR + FXAA：大屏性能敏感场景应可一键「性能模式」。
Store 全局 viewer：多实例不友好，改为 WeakMap 或强制入参。
版本日志 console.log：生产可关。
中英 API 混用（部分枚举中文注释、类型英文）：保持现状即可，但新增 API 命名规范写进 AGENTS.md（已写）。

已有能力（避免重复造轮子）

在开工前先搜现有实现：

量测 / 标绘 / 拾取 → geomatics/
通视、可视域、淹没、填挖方、限高、天际线、缓冲 → analysis/
热力图 → overlay/entity/Heatmap.ts
MVT → layer/MvtLayer/
ECharts 叠加 → layer/EchartsLayer/
动态材质 → material/ + effects/shader/
键盘漫游 → roaming/KeyboardRoaming.ts
鹰眼 / 搜索 / 工具箱 → widget/

建议迭代顺序（务实）

修销毁与 Event/relate 明显问题 + 导出清单对齐
GeoJSON Layer + Model Overlay + 轨迹漫游（业务最高频）
图层管理器 API + Popup
单测与 Material TS 化
分析类增强与序列化
包体积 / peer Cesium / 分包

记录方式

完成项请移到下方「已完成」或直接删除并在 changelog 说明。
新增缺口保持表格/checkbox，便于 AI 与人工扫读。

已完成

[x] 核心 Viewer / Layer / Overlay 体系
[x] 常用 Entity 覆盖物与 3D Tiles / Water / Video
[x] 量测、标绘、多种空间分析
[x] 天地图等影像与地形封装
[x] Demo + VitePress 文档骨架
[x] README / AGENTS.md / TODO.md 初版（本文档体系）