# @dgtwin/map3d

SDK bản đồ 3D và quản trị nội dung 3D của MDS. Một package, không cần cài engine
3D riêng, không cần import file CSS.

> Khung tối thiểu để dùng được ngay. Tài liệu bàn giao đầy đủ nằm ở thư mục
> `docs/` của bộ mã nguồn — gói npm chỉ chứa `dist/`, nên các đường dẫn
> `docs/...` bên dưới là để tra trong bộ mã nguồn, không mở được từ trang npm.

## Cài đặt

```bash
npm install @dgtwin/map3d
```

> Gói đã có trên registry công khai, không cần cấu hình registry hay token.
> Bản thử nghiệm phát hành ở dist-tag `dev`:
>
> ```bash
> npm install @dgtwin/map3d@dev
> ```
>
> Cách chạy test và xem demo chạy thật nằm trong `docs/local-development.md`
> của bộ mã nguồn bàn giao (không kèm trong gói npm).

`react` là peer dependency **tuỳ chọn** — chỉ cần khi dùng `@dgtwin/map3d/react`.

## Dùng nhanh

```ts
import { createMap } from '@dgtwin/map3d';

const map = await createMap(document.getElementById('map')!, {
  basemap: 'satellite',
  center: [105.8542, 21.0285],
  zoom: 14,
});

map.on('featureClick', (event) => {
  console.log(event.feature.buildingId, event.feature.attributes);
});
```

React:

```tsx
import { MDSMapView, useMDSMap } from '@dgtwin/map3d/react';

<MDSMapView options={{ basemap: 'satellite' }} onReady={(map) => console.log(map)}>
  <MyOverlay /> {/* dùng useMDSMap() bên trong */}
</MDSMapView>;
```

Thẻ `<script>` (không bundler) — bản UMD, global `MDSMap3D`:

```html
<script src="/path/to/@dgtwin/map3d/dist/mds-map3d.umd.js"></script>
<script>
  MDSMap3D.createMap(document.getElementById('map'), { basemap: 'satellite' });
</script>
```

## ⚠️ Assets của engine 3D — ĐỌC TRƯỚC KHI DEPLOY

Engine 3D cần một tập **file tĩnh** (web worker, bảng dữ liệu địa hình, decoder
`.wasm`, texture bầu trời) mà **không bundler nào nhét vào JS được**. SDK đã đóng
gói sẵn chúng trong `dist/engine-assets/`, nhưng app của bạn phải **phục vụ được
thư mục đó qua HTTP**. Thiếu bước này: quả địa cầu vẫn hiện nhưng địa hình,
tileset nén Draco và skybox hỏng im lặng, console đầy 404 `Workers/*`,
`Assets/*`.

SDK tự dò `dist/engine-assets/` từ URL của chính bundle. Tự dò ĐÚNG khi trình
duyệt nạp thẳng file trong `dist/`; **SAI khi bundler của app đóng gói lại SDK**
(file JS bị di chuyển, `engine-assets/` thì không đi theo).

### Vite

Thêm một dòng để Vite không pre-bundle SDK (giữ nguyên đường dẫn thật của gói):

```ts
export default defineConfig({
  optimizeDeps: { exclude: ['@dgtwin/map3d'] },
});
```

Cho bản production build, copy assets vào thư mục tĩnh rồi trỏ `assetsBaseUrl`
(xem mục dưới) — hoặc dùng `vite-plugin-static-copy`:

```ts
import { viteStaticCopy } from 'vite-plugin-static-copy';
import { createRequire } from 'node:module';
import path from 'node:path';

const pkgDir = path.dirname(createRequire(import.meta.url).resolve('@dgtwin/map3d/package.json'));

viteStaticCopy({
  targets: [{ src: path.join(pkgDir, 'dist/engine-assets'), dest: '' }],
});
```

### Angular

`angular.json` → `architect.build.options.assets`:

```json
{
  "glob": "**/*",
  "input": "node_modules/@dgtwin/map3d/dist/engine-assets",
  "output": "engine-assets"
}
```

### Trỏ tay khi cần

Ba cách, ưu tiên từ trên xuống:

```ts
// 1. Tường minh cho từng map (thắng tất cả)
await createMap(el, { assetsBaseUrl: '/engine-assets/' });
```

```html
<!-- 2. Toàn trang, không phải sửa code gọi createMap -->
<script>
  window.MDS_MAP3D_ASSETS_BASE_URL = '/engine-assets/';
</script>
```

3. Không khai gì → SDK tự dò; dò không ra thì in cảnh báo kèm hướng dẫn.

> `assetsBaseUrl` là cấu hình **theo trang**, không theo map: map đầu tiên khoá
> giá trị, map sau khai khác sẽ nhận `MDS_INVALID_OPTIONS`.

## Nội dung gói

| Đường dẫn                  | Vai trò                                                   |
| -------------------------- | --------------------------------------------------------- |
| `dist/index.js` / `.cjs`   | Entry chính (ESM/CJS). Engine nằm ở chunk tải lười.        |
| `dist/react/index.js`      | Bindings React (`@dgtwin/map3d/react`).                       |
| `dist/internal/index.js`   | Entry nội bộ MDS — **không cam kết ổn định**.              |
| `dist/mds-map3d.umd.js`    | Bản UMD một file cho thẻ `<script>` (global `MDSMap3D`).   |
| `dist/engine-assets/`      | File tĩnh của engine — phải phục vụ được qua HTTP.         |
| `THIRD_PARTY_LICENSES.txt` | Giấy phép các thư viện được bundle (bắt buộc khi phân phối). |

## Yêu cầu môi trường

- Node ≥ 18 để build/SSR; trình duyệt cần WebGL 2.
- TypeScript: dùng `moduleResolution` là `bundler` / `node16` / `nodenext`.
  Chế độ `node` (node10) cũ chỉ resolve được entry chính `@dgtwin/map3d`, **không**
  resolve được subpath `@dgtwin/map3d/react` và `@dgtwin/map3d/internal`.
- SSR an toàn: import package ở Node không đụng `window`/`document`; `createMap`
  chỉ gọi được phía client.

## Kiểm tra chất lượng gói

```bash
npm run build   # tsup → copy engine-assets → sinh licenses → gate .d.ts
npm run qa      # publint + are-the-types-wrong + ngân sách kích thước
npm test        # gate ranh giới + typecheck đầy đủ + Vitest
```

## Tài liệu

Tài liệu bàn giao cho bên tích hợp — cùng bố cục [VNPT Maps Web SDK](https://gomaps.vnpt.vn/docs/docs/category/web-sdk):
mục lục chuyên mục, tổng quan từng bước, rồi từng nhóm tính năng.

**Bắt đầu từ [`docs/README.md`](./docs/README.md).**

| Tài liệu | Nội dung |
| --- | --- |
| [`docs/README.md`](./docs/README.md) | Mục lục Web SDK |
| [`docs/tong-quan.md`](./docs/tong-quan.md) | Cài đặt môi trường, nhúng CDN / bundler, map lần đầu |
| [`docs/ban-do.md`](./docs/ban-do.md) | `createMap`, options, camera, sự kiện, bản đồ nền |
| [`docs/layers.md`](./docs/layers.md) | 5 loại layer |
| [`docs/auth.md`](./docs/auth.md) | Xác thực `token` / `apiKey` |
| [`docs/citydb-catalog.md`](./docs/citydb-catalog.md) | Digital Twin 3DCityDB |
| [`docs/upload-3d-model.md`](./docs/upload-3d-model.md) | Upload GLB pipeline MDS |
| [`docs/widget-ui.md`](./docs/widget-ui.md) | Panel UI dựng sẵn |
| [`docs/getting-started-react.md`](./docs/getting-started-react.md) | `MDSMapView` / `useMDSMap` |
| [`docs/getting-started-angular.md`](./docs/getting-started-angular.md) | Tích hợp Angular |
| [`docs/trien-khai.md`](./docs/trien-khai.md) | Engine assets, Vite, Angular |
| [`docs/xu-ly-loi.md`](./docs/xu-ly-loi.md) | `MDSMapError` |
| [`docs/api-reference.md`](./docs/api-reference.md) | Tham chiếu type/API công khai |
| [`docs/local-development.md`](./docs/local-development.md) | Chạy test, demo, `npm pack` |