# @happyvertical/smrt-places 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-places/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:54:39.780Z
中文译文更新时间：2026-11-17T10:04:23.537Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-places
原文对照：https://npmcn.com/package/%40happyvertical/smrt-places/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：378 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2026-06-23T01:18:46.137Z
- 最新版本发布：2026-11-17T07:54:39.574Z
- 近 30 天下载量：14876（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

具有地理整合和SMRT框架支持的分级地点管理

## 安装

```sh
npm install @happyvertical/smrt-places
```

也可以使用：`pnpm add @happyvertical/smrt-places`、`yarn add @happyvertical/smrt-places`、`bun add @happyvertical/smrt-places`

## README

# @ happyvertical/ smrt- places (笑) (笑) :

具有地道编码整合和空间查询功能的分级地道管理. 既支持现实世界位置(有坐标),也支持抽象地段(虚拟世界,游戏区).

## 安装

```bash
pnpm add @happyvertical/smrt-places
```

## 使用量

### 查找或创建有机数据库增长的地方

```typescript
import { PlaceCollection, PlaceTypeCollection } from '@happyvertical/smrt-places';

const places = await PlaceCollection.create();
const types = await PlaceTypeCollection.create();

// DB-first lookup, geocodes and creates if not found
const place = await places.lookupOrCreate('1600 Amphitheatre Parkway, Mountain View, CA');

if (place) {
  console.log(`${place.name}: ${place.latitude}, ${place.longitude}`);
  console.log(`Source: ${place.source}`); // 'openstreetmap' or 'google'
}

// Build hierarchy: Country > State > City
const country = await places.create({
  typeId: (await types.getOrCreate('country')).id,
  name: 'United States',
  countryCode: 'US',
});

const city = await places.create({
  typeId: (await types.getOrCreate('city')).id,
  parentId: country.id,
  name: 'San Francisco',
  latitude: 37.7749,
  longitude: -122.4194,
});

// Hierarchy traversal
const hierarchy = await city.getHierarchy();
console.log(hierarchy.ancestors.map(p => p.name)); // ['United States']

// Proximity search (Haversine distance, sorted nearest-first)
const nearby = await places.searchByProximity(37.7749, -122.4194, 10); // 10km radius
```

### 在坐标周围发现 PoIs

`discoverNearby` 编曲 `@happyvertical/geo`是因为 `findPoisNear` 与 收藏的一分法 -- -- 持久性逻辑。 提供商退回的每个指令是 或从本地 DB 重用( 由提供者匹配) `externalId`)或(或) 作为新的 Place 行创建。 重复呼叫同一个区域是有效的 免费 —— 提供者自己的身份成为 `Place.externalId`进行第二次扫描 不重复任何东西.

```typescript
const pois = await places.discoverNearby(53.5461, -113.4938, 250, {
  geoProvider: 'openstreetmap', // default
  types: ['cafe'], // optional filter — passed through to the provider
  limit: 10,
});

for (const poi of pois) {
  console.log(poi.name, poi.externalId);
}
```

需要一个执行 `findPoisNear`。丢出一个明显的错误 否则,呼叫者可以回到 `lookupOrCreate` (地址级别)或 切换提供者.

### 沿着 GPS 轨道解析 POIS

对于工作流程,如"这个驱动器/摩托车通过的地方是什么?", `resolveTrackPlaces` 移动命令数组点, 崩溃关闭 样品入网格细胞,在请求之间节流供体,以及 返回已复制的 Place 行.

```typescript
const track = [
  { lat: 53.5461, lng: -113.4938 },
  { lat: 53.5465, lng: -113.4942 },
  { lat: 53.5470, lng: -113.4950 },
  // ...hundreds more along a route
];

const result = await places.resolveTrackPlaces(track, {
  radiusMeters: 50,       // per-point POI search radius
  bucketMeters: 50,       // collapse points within this distance into one request
  throttleMs: 1100,       // ≥1s is safe for public Overpass/Nominatim
  types: ['cafe', 'restaurant'],
});

console.log(`Hit ${result.requestCount} buckets, ${result.cacheHitCount} cached, ${result.places.length} distinct places`);
```

Bucketing是主要的成本保护器:在1 Hz GPS 生产20分钟的驱动器 1200个原始样本,但往往只有100-200个显著的50米细胞,因此 提供商只能拨打100-200次. `throttleMs` 让你进入 超过/诺米纳蒂姆的 1 req/sec 社区限制出框; 将其扔到 薪级为100毫秒等.

### 拥有资产

```typescript
import { AssetCollection } from '@happyvertical/smrt-assets';

const assets = await AssetCollection.create();
const floorplan = await assets.create({
  name: 'main-hall-floorplan.png',
  sourceUri: 'file:///tmp/main-hall-floorplan.png',
  mimeType: 'image/png',
});

await place.addAsset(floorplan, 'floorplan');
await places.addAsset(place.id!, floorplan, 'gallery', 1);

const floorplans = await place.getAssets('floorplan');
const galleryAssets = await places.getAssets(place.id!, 'gallery');
```

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Place` | 具有可选地理字段的等级位置, 启用了 STI |
| `PlaceType` | 基于污名的分类(国家、城市、建筑、区域、房间) |
| `PlaceAsset` | 专用自有资产加入存储于 `place_assets` 与 `relationship` 财务报告和审定财务报表 `sortOrder` |

### 收款

| 导出 | 说明 |
| --- | --- |
| `PlaceCollection` | CRUD + 软件 `lookupOrCreate()`, (中文(简体) ), `searchByProximity()`, (中文(简体) ), `findByCoordinates()`, (中文(简体) ), `getRootPlaces()`, (中文(简体) ), `getByType()`, (中文(简体) ), `findWithGlobals()` |
| `PlaceAssetCollection` | 直接进入 `place_assets` 行外加资产助手包装 |
| `PlaceTypeCollection` | CRUD + 软件 `getOrCreate()` 用于创建偶能类型 |

### 类型

| 导出 | 说明 |
| --- | --- |
| `GeoData` | 地理数据结构 |
| `LookupOrCreateOptions` | 备选方案 `lookupOrCreate()` |
| `PlaceHierarchy` | 等级倒转结果 |
| `PlaceOptions` | 位置创建选项 |
| `PlaceTypeOptions` | PlaceType 创建选项 |

### 公用事业

| 导出 | 说明 |
| --- | --- |
| `calculateDistance` | 两个坐标相距(公里) |
| `areCoordinatesNear` | 检查两个坐标是否在阈值内 |
| `validateCoordinates` | 验证纬度/升值 |
| `parseCoordinates` | 剖析坐标字符串到 lat/ lng |
| `formatCoordinates` | 将lat/ lng 格式化为字符串 |
| `generateDisplayName` | 从地址组件构建显示名称 |
| `locationToGeoData` | 将位置响应转换为 GeoData |
| `mapLocationTypeToPlaceType` | 将地理编码器位置类型映射到 PlaceType sult |
| `normalizeAddressComponents` | 将地理编码器中的地址组件规范化 |

### 实例方法(地点)

`getParent()`, (中文(简体) ), `getChildren()`, (中文(简体) ), `getAncestors()`, (中文(简体) ), `getDescendants()`, (中文(简体) ), `getHierarchy()` - 任何Place实例上的等级.

双方都有自有资产助手 `Place` 财务报告和审定财务报表 `PlaceCollection` 通过 `getAssets()`, (中文(简体) ), `addAsset()`,以及 `removeAsset()`共同关系包括: `hero`, (中文(简体) ), `floorplan`, (中文(简体) ), `gallery`,以及 `attachment`。 。 。 .

## 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `@happyvertical/smrt-core` | 垃圾对象/垃圾分类 |
| `@happyvertical/smrt-tenancy` | 备选租户范围界定 |
| `@happyvertical/geo` | 地理编码提供者( OpenStreetMap, Google Maps) |
| `@happyvertical/sql` | 数据库操作 |
| `@happyvertical/ai` | 大赦国际一体化 |

## 常见问题

### @happyvertical/smrt-places 是什么？

具有地理整合和SMRT框架支持的分级地点管理

### 如何安装 @happyvertical/smrt-places？

在项目目录运行 npm install @happyvertical/smrt-places，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-places 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-places 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-places 可以商用吗？

@happyvertical/smrt-places 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-places 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-places 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,876 次，日均约 496 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-places 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

