@jctrans-materials/shared 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,236 @@
+# 地理位置搜索 SDK
+
+该 SDK 提供了一套统一的地理位置（国家、地区、城市、港口、机场、码头等）搜索与查询能力，支持 axios/fetch 双请求适配器、多语言适配、动态配置管理，可快速集成到各类前端项目中。
+
+## 特性
+
+- 🗺️ 覆盖多类型地理实体：国家/地区、省份、城市、港口、机场、码头等
+- 🔌 双请求适配器：支持 Axios / Fetch 两种请求方式
+- 🌐 多语言适配：自动识别中英文环境，生成对应展示文本
+- ⚙️ 动态配置：支持运行时修改请求地址，适配多环境（开发/测试/生产）
+- 📦 类型完备：基于 TypeScript 开发，提供完整的类型定义
+- 🚀 事件总线：内置全局模态框事件通信能力
+
+## 安装
+
+### npm
+
+```bash
+npm install @jctrans-materials/shared --save
+```
+
+### yarn
+
+```bash
+yarn add @jctrans-materials/shared
+```
+
+### pnpm
+
+```bash
+pnpm add @jctrans-materials/shared
+```
+
+## 快速开始
+
+### 1. 初始化配置（可选）
+
+默认使用测试环境地址，可在项目入口处初始化自定义配置：
+
+```typescript
+import { initSharedConfig } from "@jctrans-materials/shared";
+
+// 初始化自定义配置
+initSharedConfig({
+  prefixPath: "https://api-production.jctrans.com", // 生产环境域名
+  searchPath: "/system/dms/fr/aggr/getLocationOptions", // 接口路径
+});
+```
+
+### 2. 切换请求适配器（可选）
+
+默认使用 Axios 适配器，可切换为 Fetch：
+
+```typescript
+import { createRequest } from "@jctrans-materials/shared";
+
+// 切换为 Fetch 适配器
+createRequest("fetch", {
+  fetch: window.fetch, // 可传入自定义 fetch 实现（如 node-fetch）
+});
+```
+
+### 3. 基础使用示例
+
+#### 搜索国家
+
+```typescript
+import { searchCountryByName } from "@jctrans-materials/shared";
+
+// 搜索名称包含"中国"的国家
+const result = await searchCountryByName("中国", {
+  page: 1,
+  size: 10,
+});
+console.log(result.records); // 归一化后的国家列表
+```
+
+#### 按ID查询城市
+
+```typescript
+import { getById } from "@jctrans-materials/shared";
+
+// 查询 ID 为 1001 的城市
+const city = await getById("City", 1001);
+console.log(city); // 城市详情
+```
+
+#### 获取指定国家下的所有城市
+
+```typescript
+import { getCitiesByCountry } from "@jctrans-materials/shared";
+
+// 获取国家 ID 为 1 的所有城市
+const cities = await getCitiesByCountry(1, {
+  page: 1,
+  size: 100,
+});
+console.log(cities.records);
+```
+
+#### 使用 V2 版本接口（推荐）
+
+```typescript
+import { locationSearchV2 } from "@jctrans-materials/shared";
+
+// 搜索港口
+const seaports = await locationSearchV2.seaport.searchByName({
+  keyword: "上海",
+  countryId: 1,
+  current: 1,
+  size: 10,
+});
+console.log(seaports.records);
+```
+
+## 核心 API 文档
+
+### 配置管理
+
+| 方法               | 说明                   | 类型                                         |
+| ------------------ | ---------------------- | -------------------------------------------- |
+| `initSharedConfig` | 初始化全局配置         | `(newConfig: Partial<SharedConfig>) => void` |
+| `getSharedConfig`  | 获取当前配置           | `() => { basePath: string }`                 |
+| `getIsEn`          | 判断当前是否为英文环境 | `() => boolean`                              |
+
+### 基础搜索（baseSearch）
+
+| 方法                  | 说明                               |
+| --------------------- | ---------------------------------- |
+| `search`              | 通用搜索接口（支持多条件、多类型） |
+| `searchByName`        | 按名称搜索指定类型地理实体         |
+| `getByIds`            | 按类型+ID批量查询                  |
+| `getById`             | 按类型+单个ID查询                  |
+| `getCitiesByCountry`  | 获取指定国家下的所有城市           |
+| `getChildrenByCity`   | 获取指定城市下的港口/机场          |
+| `searchCountryByName` | 按名称搜索国家                     |
+| `searchCityByName`    | 按名称搜索城市（支持国家筛选）     |
+| `searchSeaportByName` | 按名称搜索港口（支持城市筛选）     |
+| `searchAirportByName` | 按名称搜索机场（支持城市筛选）     |
+
+### V2 版本搜索（searchV2）
+
+`locationSearchV2` 提供更语义化的接口封装：
+
+| 子模块    | 方法                                           | 说明                       |
+| --------- | ---------------------------------------------- | -------------------------- |
+| `country` | `searchByName`/`getByIds`                      | 国家搜索/批量查询          |
+| `region`  | `searchByName`/`getByIds`                      | 地区搜索/批量查询          |
+| `city`    | `searchByName`/`getByIds`/`getCitiesByCountry` | 城市搜索/查询/按国家筛选   |
+| `seaport` | `searchByName`/`getByIds`                      | 港口搜索/批量查询          |
+| `airport` | `searchByName`/`getByIds`                      | 机场搜索/批量查询          |
+| `wharf`   | `getByIds`                                     | 码头批量查询               |
+| -         | `searchByIdWithType`                           | 按类型+ID查询任意地理实体  |
+| -         | `getChildrenByCity`                            | 获取城市下的港口/机场/码头 |
+
+### 请求适配器
+
+| 方法            | 说明                               |
+| --------------- | ---------------------------------- |
+| `createRequest` | 创建/切换请求适配器（axios/fetch） |
+| `request`       | 全局请求实例（get/post方法）       |
+
+### 事件总线
+
+用于全局模态框交互：
+
+```typescript
+import { emitter, MODAL_ACTION } from "@jctrans-materials/shared";
+
+// 监听模态框打开事件
+emitter.on(MODAL_ACTION.Open, () => {
+  console.log("模态框已打开");
+});
+
+// 触发模态框关闭事件
+emitter.emit(MODAL_ACTION.Close);
+```
+
+## 关键类型定义
+
+### 地理实体类型
+
+```typescript
+// baseSearch 支持的类型
+type DisplayInfo =
+  | "Continent"
+  | "Country"
+  | "Province"
+  | "City"
+  | "Seaport"
+  | "Airport";
+
+// searchV2 支持的类型（扩展）
+type LocationType = DisplayInfo | "Region" | "Street" | "Town" | "Wharf";
+```
+
+### 归一化实体结构
+
+```typescript
+interface UnifiedItem {
+  id: number | string; // 实体ID
+  type: DisplayInfo; // 实体类型
+  nameCn?: string; // 中文名称
+  nameEn?: string; // 英文名称
+  display?: string; // 适配当前语言的展示文本
+  continent?: Record<string, any>; // 所属大洲
+  country?: Record<string, any>; // 所属国家
+  city?: Record<string, any>; // 所属城市
+  province?: Record<string, any>; // 所属省份
+  raw?: any; // 原始后端数据
+}
+```
+
+### 请求配置
+
+```typescript
+interface RequestConfig {
+  params?: Record<string, any>; // URL参数
+  headers?: Record<string, string>; // 请求头
+}
+```
+
+## 注意事项
+
+1. 接口默认分页：`current=1`（页码）、`size=10`（每页条数）
+2. 多语言判断优先级：Nuxt Cookie > 浏览器 Cookie > Nuxt SSR 上下文
+3. 实体展示文本规则：
+   - 港口/机场：`名称 (城市, 国家)`
+   - 城市/省份：`名称 (国家)`
+   - 国家：`名称 (大洲)`
+4. 请求超时时间（Axios）：默认 15000ms
+5. 重复数据：SDK 内部会自动根据 `type + id` 去重
+
+## 许可证
+
+[MIT]（根据实际情况修改）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jctrans-materials/shared",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "private": false,
   "description": "Shared logic for global modal components.",
   "main": "dist/index.cjs.js",