@uavs/3d-model-map 0.1.0

package/README.md

@@ -0,0 +1,392 @@
+# @uavs/3d-model-map
+
+`@uavs/3d-model-map` 是 UAVS 的 Vue 3 三维模型地图能力包，专门用于展示 3D Tiles 模型。组件内部负责 Mars3D/Cesium 地图初始化、三维模型加载、模型定位、模型总览、hover 边框高亮和清晰度调整；业务项目负责提供模型数据、模型文件地址和应用级 API 适配。
+
+源码仓库：[https://gitee.com/jxzhsz/packages](https://gitee.com/jxzhsz/packages)，包目录为 `packages/3d-model-map`。
+
+## 功能
+
+- 基于 Vue 3、Mars3D、Cesium 展示城市、园区、小区、工厂等区域的三维模型。
+- 支持从外部传入模型分组数据或模型列表数据。
+- 支持从外部传入 3D Tiles `tileset.json` 地址解析函数。
+- 支持模型定位、当前模型状态面板、模型总览切换。
+- 支持模型 hover 边框强化，不用透明色块覆盖模型。
+- 支持配置返回按钮是否显示、按钮文字和返回行为。
+- 不依赖业务项目里的 `@uavs/ui`、`BaseDialog` 或 Element Plus。
+
+## 安装
+
+```bash
+pnpm add @uavs/3d-model-map
+```
+
+如果 `@uavs` scope 发布在私有 npm 源，先配置 scope registry：
+
+```bash
+pnpm config set @uavs:registry <registry-url>
+```
+
+然后再安装：
+
+```bash
+pnpm add @uavs/3d-model-map
+```
+
+`@uavs/3d-model-map` 会把 `vue`、`mars3d`、`mars3d-cesium`、`@turf/turf` 作为 peer dependencies 使用。业务项目里已经有这些依赖时，不需要重复安装，只要版本兼容即可。
+
+如果某个接入项目缺少这些依赖，再按需补装：
+
+```bash
+pnpm add <缺失的包名>
+```
+
+### 推荐补装依赖
+
+如果接入项目缺少运行时 peer dependencies，推荐按下面的版本补装：
+
+```bash
+pnpm add mars3d@3.11.2 mars3d-cesium@1.140.0 @turf/turf@^7.3.5
+```
+
+Vue 项目通常已经安装了 `vue`；如果没有，再补装：
+
+```bash
+pnpm add vue@^3.5.16
+```
+
+Vite 项目使用包内 `createCesiumStaticPlugins` 时，不需要单独安装 `vite-plugin-static-copy`，它会随 `@uavs/3d-model-map` 一起安装；宿主项目本身仍需要有 `vite`。
+
+## Cesium 依赖
+
+组件会按下面的顺序使用 Cesium：
+
+1. 如果业务项目已经初始化了 `window.Cesium`，直接复用。
+2. 如果没有 `window.Cesium`，从 peer dependency `mars3d-cesium` 动态加载 Cesium 和 `Widgets/widgets.css`。
+
+接入项目只要本身已经依赖 `mars3d-cesium`，并且构建工具可以正常处理 `mars3d-cesium/Build/Cesium/Widgets/widgets.css` 即可。
+
+如果地图配置里用到了底图预览图片，也需要在业务项目里准备：
+
+```text
+public/img/basemaps
+```
+
+这些底图预览图片会随 npm 包发布，并由 `createCesiumStaticPlugins` 在构建时复制到应用产物。业务项目需要替换底图预览图片时，可以在自己的 `public/img/basemaps` 中放置同名文件覆盖。
+
+## Vite 接入配置
+
+使用 Vite 的项目建议在 `vite.config.ts` 中加入 Cesium 静态资源插件、Mars3D Cesium shim 和依赖预构建排除：
+
+```ts
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig, loadEnv } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { createCesiumStaticPlugins, createMapdataProxy } from '@uavs/3d-model-map/vite/cesium'
+
+const cesiumSource = fileURLToPath(new URL('./node_modules/mars3d-cesium/Build/Cesium', import.meta.url))
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, import.meta.dirname)
+
+  return {
+    plugins: [
+      vue(),
+      ...createCesiumStaticPlugins(cesiumSource)
+    ],
+    resolve: {
+      alias: [
+        {
+          find: /^mars3d-cesium$/,
+          replacement: '@uavs/3d-model-map/runtime/mars3d-cesium-shim'
+        }
+      ]
+    },
+    server: {
+      proxy: createMapdataProxy(env)
+    },
+    optimizeDeps: {
+      exclude: ['mars3d', 'mars3d-cesium']
+    },
+    build: {
+      assetsInlineLimit: 0,
+      target: 'es2020'
+    }
+  }
+})
+```
+
+如果项目的 `mars3d-cesium` 不在当前项目根目录的 `node_modules` 下，可以把 `cesiumSource` 改成实际路径，但必须指向 `mars3d-cesium/Build/Cesium`。
+
+## 基础用法
+
+在页面或应用入口里导入组件和样式：
+
+```vue
+<script setup lang="ts">
+import { ThreeDimensionalMap } from '@uavs/3d-model-map'
+import '@uavs/3d-model-map/style.css'
+import type { MaterialModelItem, ThreeDimensionalMapDataSource } from '@uavs/3d-model-map'
+
+const dataSource: ThreeDimensionalMapDataSource = {
+  async getModelGroups() {
+    // 在业务项目里调用自己的接口，例如 /admin-api/material/threedList
+    return []
+  }
+}
+
+function resolveTilesetUrl(item: MaterialModelItem) {
+  if (!item.file) return ''
+  return `/mapdata/${String(item.file).replace(/^\/+|\/+$/g, '')}/tileset.json`
+}
+</script>
+
+<template>
+  <div class="map-page">
+    <ThreeDimensionalMap
+      map-key="project-3d-map"
+      :data-source="dataSource"
+      :resolve-tileset-url="resolveTilesetUrl"
+      :show-back-button="false"
+    />
+  </div>
+</template>
+
+<style scoped>
+.map-page {
+  width: 100%;
+  height: 100vh;
+}
+</style>
+```
+
+注意：地图容器必须有明确高度，否则 Cesium 容器可能无法正常显示。
+
+## 数据接入
+
+推荐在业务项目里通过 `dataSource` 注入数据，组件本身不绑定具体请求库，也不固定接口地址。
+
+```ts
+interface ThreeDimensionalMapDataSource {
+  getModelGroups?: () => Promise<MaterialModelGroup[]>
+  getModelItems?: () => Promise<MaterialModelItem[] | PageResult<MaterialModelItem>>
+}
+```
+
+### 分组数据
+
+`getModelGroups` 适合接入类似 `/admin-api/material/threedList` 的树形数据：
+
+```ts
+const dataSource: ThreeDimensionalMapDataSource = {
+  async getModelGroups() {
+    const res = await geyThreedList()
+    return res.data ?? []
+  }
+}
+```
+
+顶层 `modelType` 为 `2` 的分组会被当作三维模型分组。因为部分接口返回的子项 `modelType` 不可靠，组件会按顶层分组归一化子项类型，不再依赖子项自己的 `modelType` 判断是否为 3D 模型。
+
+### 平铺数据
+
+`getModelItems` 适合接入普通模型列表接口。返回值可以是数组，也可以是带 `list` 字段的分页对象：
+
+```ts
+const dataSource: ThreeDimensionalMapDataSource = {
+  async getModelItems() {
+    const res = await getMaterialApi({ pageSize: 999, pageNo: 1, type: 2 })
+    return res.data
+  }
+}
+```
+
+## 模型数据格式
+
+模型项至少需要包含可唯一识别的 `id`。如果要让定位更准确，建议同时提供经纬度。
+
+```ts
+interface MaterialModelItem {
+  id: number | string
+  file?: string
+  fileName?: string
+  name?: string
+  longitude?: number
+  latitude?: number
+  height?: number
+}
+```
+
+字段说明：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 模型唯一标识，用于图层创建、定位和当前模型判断。 |
+| `file` | 模型文件目录或 URL，默认会用于拼接 `tileset.json`。 |
+| `fileName` / `name` | 模型展示名称。 |
+| `longitude` / `latitude` | 模型中心点经纬度，用于定位和飞行。 |
+| `height` | 模型高度或定位高度，按业务接口实际含义传入。 |
+
+## 模型地址解析
+
+不同项目的模型文件可能放在不同域名、不同前缀下，所以建议传入 `resolveTilesetUrl`：
+
+```ts
+function resolveTilesetUrl(item: MaterialModelItem) {
+  if (!item.file) return ''
+
+  if (/^https?:\/\//i.test(item.file)) {
+    return item.file.endsWith('tileset.json') ? item.file : `${item.file}/tileset.json`
+  }
+
+  return `/mapdata/${String(item.file).replace(/^\/+|\/+$/g, '')}/tileset.json`
+}
+```
+
+如果不传 `resolveTilesetUrl`，包内默认逻辑会把 `file` 解析成：
+
+```text
+/mapdata/<file>/tileset.json
+```
+
+## Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `configUrl` | `string` | `${import.meta.env.BASE_URL}config/config.json` | Mars3D 地图配置地址，默认跟随宿主 Vite `base`。 |
+| `mapKey` | `string` | `common-3d` | 地图实例 key，会用于生成容器 id；同页多个地图时必须不同。 |
+| `options` | `Record<string, unknown>` | `{}` | 额外 Mars3D 地图配置，会合并到地图初始化配置里。 |
+| `initialView` | `Map3dInitialView \| false` | 内置默认视角 | 初始总览视角；传 `false` 可禁用回到总览能力。 |
+| `flyToInitialView` | `boolean` | `true` | 地图创建后是否飞到初始视角。 |
+| `showRealModelLabels` | `boolean` | `true` | 是否展示模型标签。 |
+| `preloadModels` | `boolean` | `true` | 是否预加载模型元数据。 |
+| `modelGroups` | `MaterialModelGroup[]` | - | 直接传入的分组模型数据。 |
+| `modelItems` | `MaterialModelItem[]` | - | 直接传入的平铺模型数据。 |
+| `dataSource` | `ThreeDimensionalMapDataSource` | - | 外部异步数据源。 |
+| `resolveTilesetUrl` | `MaterialTilesetUrlResolver` | 内置 `/mapdata` 解析 | 把模型项转换成 3D Tiles 地址。 |
+| `showBackButton` | `boolean` | `true` | 是否显示左上角返回按钮。 |
+| `backButtonText` | `string` | `返回` | 返回按钮文字。 |
+| `backFallbackUrl` | `string` | `/` | 没有浏览器历史可退时跳转的兜底地址。 |
+| `onBack` | `() => void` | - | 自定义返回行为。 |
+
+## 常用导出
+
+```ts
+export {
+  ThreeDimensionalMap,
+  ThreeDimensionalMapPage,
+  createMapApi,
+  provideMapApi,
+  formatMaterialModelTree,
+  isThreeDimensionalModel,
+  resolveTilesetUrl,
+  resolveMap3dPublicUrl
+}
+```
+
+常用类型：
+
+```ts
+export type {
+  MaterialModelGroup,
+  MaterialModelItem,
+  MaterialTilesetUrlResolver,
+  ThreeDimensionalMapDataSource,
+  Map3dInitialView
+}
+```
+
+## 发布前检查
+
+发布前先执行：
+
+```bash
+pnpm --filter @uavs/3d-model-map build
+pnpm --filter @uavs/3d-model-map pack:check
+```
+
+`pack:check` 会执行构建并运行 `npm pack --dry-run`，用于确认最终 npm 包里只包含需要发布的文件。
+
+## 发布
+
+### 切换 npm 账号
+
+发布前先确认当前登录账号：
+
+```bash
+npm whoami
+```
+
+如果当前不是要发布 `@uavs/3d-model-map` 的账号，先退出旧账号：
+
+```bash
+npm logout --registry=https://registry.npmjs.org/
+```
+
+然后登录新账号：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+```
+
+登录完成后再次确认账号：
+
+```bash
+npm whoami
+```
+
+确认新账号有 `@uavs` scope 或当前包的发布权限：
+
+```bash
+npm access list packages @uavs
+npm owner ls @uavs/3d-model-map
+```
+
+如果 `@uavs` 还没有在 npm 上创建，需要先到 npm 官网创建 `uavs` organization；`@uavs/3d-model-map` 包不需要提前创建，第一次发布成功时会自动创建。
+
+如果发布时报 `Two-factor authentication or granular access token with bypass 2FA enabled is required to publish packages`，说明 npm 要求当前账号启用 2FA，或者使用允许发布的 granular access token。
+
+本地手动发布推荐在 npm 官网账号设置里启用 2FA，然后用一次性验证码发布：
+
+```bash
+pnpm --filter @uavs/3d-model-map publish --access public --otp <6位验证码>
+```
+
+CI 或自动化发布推荐在 npm 官网创建 granular access token，给 `@uavs` 或 `@uavs/3d-model-map` 配置 `Read and write` 权限，并启用 `Bypass two-factor authentication`，再把 token 配到发布环境的 npm auth token 中。
+
+本机临时使用 access token 发布时，需要把新 token 写入当前 npm 配置：
+
+```bash
+npm config set //registry.npmjs.org/:_authToken=<npm_access_token>
+npm whoami
+pnpm --filter @uavs/3d-model-map publish --access public
+```
+
+如果仍然报 2FA/token 错误，通常是 token 没有勾选 `Bypass two-factor authentication`，或者 package/scope 权限不是 `Read and write`。
+
+公开发布：
+
+```bash
+pnpm --filter @uavs/3d-model-map publish --access public
+```
+
+如果发布到私有源，需要先在发布环境里配置 registry 和登录信息：
+
+```bash
+pnpm config set @uavs:registry <registry-url>
+npm login --registry <registry-url>
+pnpm --filter @uavs/3d-model-map publish
+```
+
+## 接入项目检查清单
+
+- 已安装 `@uavs/3d-model-map`。
+- 业务项目已有并满足版本要求的 peer dependencies：`vue`、`mars3d@3.11.2`、`mars3d-cesium@1.140.0`、`@turf/turf@^7.3.5`。
+- 已导入 `@uavs/3d-model-map/style.css`。
+- Vite 项目已从 `@uavs/3d-model-map/vite/cesium` 接入 `createCesiumStaticPlugins`。
+- Vite 项目已把 `mars3d-cesium` alias 到 `@uavs/3d-model-map/runtime/mars3d-cesium-shim`。
+- Vite 项目已在 `optimizeDeps.exclude` 中排除 `mars3d` 和 `mars3d-cesium`。
+- 已准备 Mars3D 配置文件，默认会从宿主应用的 `BASE_URL + config/config.json` 读取，例如 `base: '/uavs_frontend/'` 时请求 `/uavs_frontend/config/config.json`；非 Vite 项目或自定义路径可通过 `configUrl` 指定。
+- 已在业务项目里实现模型接口请求，并通过 `dataSource` 传入。
+- 已根据项目模型文件路径实现 `resolveTilesetUrl`。
+- 地图容器有明确宽高。
+- 如果不需要组件内返回按钮，传入 `:show-back-button="false"`。