@jctrans-materials/shared 1.0.41-beta.0 → 1.0.41-beta.10

package/README.md

@@ -1,236 +1,631 @@
-# 地理位置搜索 SDK
-
-该 SDK 提供了一套统一的地理位置（国家、地区、城市、港口、机场、码头等）搜索与查询能力，支持 axios/fetch 双请求适配器、多语言适配、动态配置管理，可快速集成到各类前端项目中。
-
-## 特性
-
-- 🗺️ 覆盖多类型地理实体：国家/地区、省份、城市、港口、机场、码头等
-- 🔌 双请求适配器：支持 Axios / Fetch 两种请求方式
-- 🌐 多语言适配：自动识别中英文环境，生成对应展示文本
-- ⚙️ 动态配置：支持运行时修改请求地址，适配多环境（开发/测试/生产）
-- 📦 类型完备：基于 TypeScript 开发，提供完整的类型定义
-- 🚀 事件总线：内置全局模态框事件通信能力
+# @jctrans-materials/shared
+
+JCTrans 前端共享工具库，为 JCTrans 系列项目提供认证、请求、加密、地理位置搜索、GrowingIO 埋点等基础能力。
+
+## 功能模块
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| 配置管理 | `config/` | 运行时动态配置（API 地址、AppId 等） |
+| 地理搜索 V1 | `api/baseSearch` | 旧接口搜索（findPageList），使用 appointSearch 结构 |
+| 地理搜索 V2 | `api/searchV2` | 新接口搜索（getLocationOptions），支持 Carrier/Line |
+| 统一类型 | `api/searchTypes` | 搜索模块共享类型定义 |
+| 认证 API | `api/auth` | 登录、注册、第三方登录、密码找回、Session 管理 |
+| 业务 API | `api/common` + `api/applyData` | 验证码、字典、IP 查询、数据上报 |
+| 反查回显 | `api/reverseLookup` | 按英文展示名反查实体详情 |
+| DW-SDK | `dw-sdk/` | 数据仓库 GraphQL SDK 统一入口 |
+| 请求封装 | `utils/request` | Axios/Fetch 双适配器 + 拦截器 |
+| Token 管理 | `utils/storage` | Cookie 凭证存取（Access Token / Refresh Token） |
+| 加密 | `utils/crypto` | AES 加解密（ECB，与后端对齐） |
+| GrowingIO | `utils/gio` | GIO SDK 封装 + v-gio-track 指令支持 |
+| 域名工具 | `utils/domain` | IP 判断、一级域名提取 |
+| AppId/ProjectId | `utils/app` | 跨环境 AppId 和 ProjectId 获取 |
+| 语言 | `utils/lang` | 当前语言获取 |
+| Header 工具 | `utils/header` | HTTP Header 安全处理 |
+| Modal 事件 | `utils/modal` | 全局模态框事件总线 |
+| ClientId | `utils/clientId` | 客户端唯一标识生成与持久化 |
 
 ## 安装
 
-### npm
-
 ```bash
-npm install @jctrans-materials/shared --save
+pnpm add @jctrans-materials/shared
 ```
 
-### yarn
+**Peer Dependencies：**
 
-```bash
-yarn add @jctrans-materials/shared
+```json
+{
+  "axios": "1.13.2",
+  "gio-webjs-sdk": "^4.0.0"
+}
 ```
 
-### pnpm
-
-```bash
-pnpm add @jctrans-materials/shared
-```
+`axios` 为必须依赖，`gio-webjs-sdk` 为可选依赖（仅使用 GIO 埋点时需要）。
 
 ## 快速开始
 
-### 1. 初始化配置（可选）
+### 1. 初始化配置
 
-默认使用测试环境地址，可在项目入口处初始化自定义配置：
+在项目入口调用 `initSharedConfig`，配置 API 域名和路径：
 
 ```typescript
-import { initSharedConfig } from "@jctrans-materials/shared";
+import { initSharedConfig, initCommonKeys } from "@jctrans-materials/shared";
 
-// 初始化自定义配置
 initSharedConfig({
-  prefixPath: "https://api-production.jctrans.com", // 生产环境域名
-  searchPath: "/system/dms/fr/aggr/getLocationOptions", // 接口路径
+  prefixPath: "https://api-production.jctrans.com",
+  searchPath: "/system/dms/fr/aggr/getLocationOptions",
+  oldSearchPath: "/system/dms/fr/aggr/findPageList",
+  carrierPath: "/system/dms/carrier/findAllList",
+  linePath: "/system/dms/fr/line/findAllList",
+  allLinePath: "/system/dms/fr/line/findAllListByCountry",
+  appId: "YOUR_APP_ID",
+  commonKeys: {
+    TokenKey: "CUSTOM-TOKEN-KEY", // 可选：自定义 Cookie key
+  },
 });
 ```
 
-### 2. 切换请求适配器（可选）
+### 2. 切换请求适配器
 
-默认使用 Axios 适配器，可切换为 Fetch：
+默认使用 Fetch 适配器（浏览器环境自动检测），可手动切换：
 
 ```typescript
 import { createRequest } from "@jctrans-materials/shared";
 
-// 切换为 Fetch 适配器
-createRequest("fetch", {
-  fetch: window.fetch, // 可传入自定义 fetch 实现（如 node-fetch）
+// 切换为 Axios
+createRequest("axios");
+
+// 切换为 Fetch（可传入自定义实现，如 Nuxt 的 $fetch）
+createRequest("fetch", { fetch: $fetch });
+
+// 切换为 Custom（小程序等非浏览器环境，完全透传）
+createRequest("custom", {
+  baseURL: "https://cloudapi-sit2.jctrans.net.cn",
+  fetch: async ({ url, method, data, params, headers }) => {
+    // 用户自己的请求实现，header/token/返回值完全由你控制
+    return new Promise((resolve, reject) => {
+      wx.request({
+        url,
+        method: method as any,
+        data,
+        header: headers,
+        success: (res: any) => resolve(res.data),
+        fail: reject,
+      });
+    });
+  },
 });
 ```
 
-### 3. 基础使用示例
+#### ClientId 插件
 
-#### 搜索国家
+自动在所有请求 header 中注入客户端唯一标识（`client-uid`），用于无埋点追踪和用户行为分析。
 
 ```typescript
-import { searchCountryByName } from "@jctrans-materials/shared";
+import {
+  installClientIdPlugin,
+  installFetchClientIdPlugin,
+  getOrCreateClientId,
+  createRequest,
+} from "@jctrans-materials/shared";
+
+// Axios 环境：直接安装插件
+installClientIdPlugin(axiosInstance, {
+  headerName: "client-uid", // 可选，默认 'client-uid'
+});
 
-// 搜索名称包含"中国"的国家
-const result = await searchCountryByName("中国", {
-  page: 1,
-  size: 10,
+// Fetch 环境：先创建请求实例再安装
+const request = createRequest("fetch", { fetch: customFetch });
+installFetchClientIdPlugin({
+  headerName: "client-uid", // 可选，默认 'client-uid'
 });
-console.log(result.records); // 归一化后的国家列表
+
+// 手动获取 clientId
+const cid = getOrCreateClientId(); // 首次调用自动生成并持久化
 ```
 
-#### 按ID查询城市
+> **原理**：使用 `nanoid` 生成，完全 SSR 兼容（无 `window`/`document` 依赖）。ClientId 存储在 `localStorage` 中，跨页面共享。
+
+### 3. 地理位置搜索
+
+#### V2 接口（推荐）
 
 ```typescript
-import { getById } from "@jctrans-materials/shared";
+import { locationSearchV2 } from "@jctrans-materials/shared";
 
-// 查询 ID 为 1001 的城市
-const city = await getById("City", 1001);
-console.log(city); // 城市详情
-```
+// 按名称搜索港口
+const ports = await locationSearchV2.seaport.searchByName({
+  keyword: "上海",
+  countryId: 1,
+  current: 1,
+  size: 10,
+});
 
-#### 获取指定国家下的所有城市
+// 按 ID 查询国家
+const countries = await locationSearchV2.country.getByIds([1, 2, 3]);
 
-```typescript
-import { getCitiesByCountry } from "@jctrans-materials/shared";
+// 获取国家下所有城市
+const cities = await locationSearchV2.city.getCitiesByCountry(1);
+
+// 获取城市下的港口/机场
+const children = await locationSearchV2.getChildrenByCity(100, ["Seaport", "Airport"]);
+
+// 搜索船公司
+const carriers = await locationSearchV2.carrier.searchShipping({
+  keyword: "MAERSK",
+  current: 1,
+  size: 10,
+});
 
-// 获取国家 ID 为 1 的所有城市
-const cities = await getCitiesByCountry(1, {
-  page: 1,
-  size: 100,
+// 搜索航线
+const lines = await locationSearchV2.line.searchShipping({
+  keyword: "AE1",
+  current: 1,
+  size: 10,
 });
-console.log(cities.records);
+
+// 通用按类型+ID查询
+const result = await locationSearchV2.searchByIdWithType(100, "City");
 ```
 
-#### 使用 V2 版本接口（推荐）
+#### V1 接口（兼容旧项目）
 
 ```typescript
-import { locationSearchV2 } from "@jctrans-materials/shared";
+import {
+  searchCountryByName,
+  searchCityByName,
+  searchSeaportByName,
+  getById,
+  getByIds,
+  getCitiesByCountry,
+} from "@jctrans-materials/shared";
+
+// 按名称搜索
+const countries = await searchCountryByName("中国");
+
+// 按 ID 查询
+const city = await getById("City", 1001);
+const ports = await getByIds("Seaport", [100, 200]);
 
-// 搜索港口
-const seaports = await locationSearchV2.seaport.searchByName({
-  keyword: "上海",
-  countryId: 1,
-  current: 1,
-  size: 10,
+// 按国家获取城市
+const cities = await getCitiesByCountry(1);
+```
+
+### 4. 认证 API
+
+```typescript
+import {
+  loginApi,
+  sendEmailCodeApi,
+  loginByFacebookApi,
+  autoLoginByTGC,
+  resetPasswordApi,
+  setAuthSessionItems,
+  getAuthSessionItems,
+} from "@jctrans-materials/shared";
+
+// 登录
+const res = await loginApi({
+  username: "user@example.com",
+  password: "encrypted_password",
+  appId: "ERA",
+  code: "",
+  uuid: "",
+  kick: false,
+  redirectPath: "/dashboard",
+  activityCode: "",
+  referenceUserId: "",
 });
-console.log(seaports.records);
+
+// 发送邮箱验证码
+await sendEmailCodeApi({ target: "user@example.com" });
+
+// 第三方登录
+const fbResult = await loginByFacebookApi({ /* oauth data */ });
+
+// TGC 自动登录
+await autoLoginByTGC({ toSys: "ERA", path: "/", tgc: "tgc_token" });
+
+// 密码找回
+await resetPasswordApi({ account: "user@example.com", password: "new_pwd", code: "123456" });
+
+// Session 管理
+setAuthSessionItems({ activityCode: "SUMMER2026", path: "/register" });
+const items = getAuthSessionItems();
 ```
 
-## 核心 API 文档
+### 5. Token 管理
 
-### 配置管理
+```typescript
+import {
+  setTokenAll,
+  getToken,
+  getRefreshToken,
+  getExpiresTimeIn,
+  clearAllAuth,
+  setRememberMe,
+} from "@jctrans-materials/shared";
+
+// 登录成功后保存 Token
+setTokenAll({
+  accessToken: "eyJhbGci...",
+  expireIn: 86400,
+  refreshToken: "refresh_token...",
+  refreshTokenExpireIn: 2592000,
+});
 
-| 方法               | 说明                   | 类型                                         |
-| ------------------ | ---------------------- | -------------------------------------------- |
-| `initSharedConfig` | 初始化全局配置         | `(newConfig: Partial<SharedConfig>) => void` |
-| `getSharedConfig`  | 获取当前配置           | `() => { basePath: string }`                 |
-| `getIsEn`          | 判断当前是否为英文环境 | `() => boolean`                              |
+// 读取 Token
+const token = getToken();
 
-### 基础搜索（baseSearch）
+// 清除所有凭证
+clearAllAuth();
 
-| 方法                  | 说明                               |
-| --------------------- | ---------------------------------- |
-| `search`              | 通用搜索接口（支持多条件、多类型） |
-| `searchByName`        | 按名称搜索指定类型地理实体         |
-| `getByIds`            | 按类型+ID批量查询                  |
-| `getById`             | 按类型+单个ID查询                  |
-| `getCitiesByCountry`  | 获取指定国家下的所有城市           |
-| `getChildrenByCity`   | 获取指定城市下的港口/机场          |
-| `searchCountryByName` | 按名称搜索国家                     |
-| `searchCityByName`    | 按名称搜索城市（支持国家筛选）     |
-| `searchSeaportByName` | 按名称搜索港口（支持城市筛选）     |
-| `searchAirportByName` | 按名称搜索机场（支持城市筛选）     |
+// 记住账号（⚠️ 密码会明文存储在 Cookie 中）
+setRememberMe("user@example.com", "password", true);
+```
 
-### V2 版本搜索（searchV2）
+### 6. 加密
 
-`locationSearchV2` 提供更语义化的接口封装：
+```typescript
+import { encrypt, decrypt, Encrypt, Decrypt } from "@jctrans-materials/shared";
 
-| 子模块    | 方法                                           | 说明                       |
-| --------- | ---------------------------------------------- | -------------------------- |
-| `country` | `searchByName`/`getByIds`                      | 国家搜索/批量查询          |
-| `region`  | `searchByName`/`getByIds`                      | 地区搜索/批量查询          |
-| `city`    | `searchByName`/`getByIds`/`getCitiesByCountry` | 城市搜索/查询/按国家筛选   |
-| `seaport` | `searchByName`/`getByIds`                      | 港口搜索/批量查询          |
-| `airport` | `searchByName`/`getByIds`                      | 机场搜索/批量查询          |
-| `wharf`   | `getByIds`                                     | 码头批量查询               |
-| -         | `searchByIdWithType`                           | 按类型+ID查询任意地理实体  |
-| -         | `getChildrenByCity`                            | 获取城市下的港口/机场/码头 |
+// camelCase（推荐）
+const encrypted = encrypt("plain_text");
+const decrypted = decrypt(encrypted);
 
-### 请求适配器
+// PascalCase（兼容旧代码）
+const enc = Encrypt("plain_text");
+const dec = Decrypt(enc);
+```
 
-| 方法            | 说明                               |
-| --------------- | ---------------------------------- |
-| `createRequest` | 创建/切换请求适配器（axios/fetch） |
-| `request`       | 全局请求实例（get/post方法）       |
+> ⚠️ 加密使用 AES-ECB 模式，密钥与后端对齐。ECB 模式安全性较低（相同明文产生相同密文），仅用于传输层保护，不可用于高安全场景。
 
-### 事件总线
+### 7. GrowingIO 埋点
 
-用于全局模态框交互：
+```typescript
+import { tracker, normalizeClickPageAttrs, GIO_EVENT_CLICK_PAGE } from "@jctrans-materials/shared";
+
+// 初始化
+tracker.init("account-id", "datasource-id", {
+  debug: true,
+  trackPage: true,
+  // 性能采集（默认开启首屏加载监控和错误监控，默认关闭网络监控）
+  performance: {
+    monitor: true,     // 首屏加载监控，默认 true
+    exception: true,   // 错误监控，默认 true
+    network: {         // 网络监控，不配置则默认关闭
+      exclude: /api\.example\.com/,  // 排除指定域名的请求
+    },
+  },
+});
+
+// 设置用户 ID
+tracker.setUserId("user-123");
+
+// 埋点事件
+tracker.track("order_submit", {
+  order_type: "freight",
+  price: 5000,
+});
+
+// clickPage 事件（自动补齐必填字段）
+const attrs = normalizeClickPageAttrs(GIO_EVENT_CLICK_PAGE, {
+  pageCode_var: "HOME",
+  pageClickName_var: "search_btn",
+});
+tracker.track(GIO_EVENT_CLICK_PAGE, attrs);
+```
+
+### 8. Modal 事件总线
 
 ```typescript
 import { emitter, MODAL_ACTION } from "@jctrans-materials/shared";
 
-// 监听模态框打开事件
+// 监听
 emitter.on(MODAL_ACTION.Open, () => {
   console.log("模态框已打开");
 });
 
-// 触发模态框关闭事件
-emitter.emit(MODAL_ACTION.Close);
+// 触发
+emitter.emit(MODAL_ACTION.Close, undefined);
+emitter.emit(MODAL_ACTION.Submit, { key: "value" });
 ```
 
-## 关键类型定义
+### 9. 业务 API
 
-### 地理实体类型
+```typescript
+import {
+  slideGetApi,
+  slideCheckApi,
+  findDictApi,
+  findPAreaCodeApi,
+  getLocalIpDataApi,
+  getRedirectPathApi,
+  reportNewTypeDataApi,
+} from "@jctrans-materials/shared";
+
+// 滑动验证码
+const captcha = await slideGetApi({ clientUid: "xxx", ts: Date.now() });
+const verified = await slideCheckApi({ pointJson: "...", uuid: "..." });
+
+// 字典查询
+const dict = await findDictApi({ size: -1 });
+
+// 区号列表
+const areaCodes = await findPAreaCodeApi({ size: -1 });
+
+// 数据上报
+await reportNewTypeDataApi({
+  reportData: "report_content",
+  reportType: "City",
+});
+```
+
+### 10. 反查回显
+
+通过英文展示名（nameEnShow）反查实体详情，用于从外部链接或 URL 参数回显数据。
 
 ```typescript
-// baseSearch 支持的类型
-type DisplayInfo =
-  | "Continent"
-  | "Country"
-  | "Province"
-  | "City"
-  | "Seaport"
-  | "Airport";
+import {
+  getAirportByNameEnShow,
+  getCountryByNameEnShow,
+  getCityByNameEnShow,
+  getSeaportByNameEnShow,
+} from "@jctrans-materials/shared";
+
+// 按英文展示名查询机场详情
+const airport = await getAirportByNameEnShow("Shanghai Pudong International Airport");
 
-// searchV2 支持的类型（扩展）
-type LocationType = DisplayInfo | "Region" | "Street" | "Town" | "Wharf";
+// 按英文展示名查询国家详情
+const country = await getCountryByNameEnShow("China");
+
+// 按英文展示名查询城市详情
+const city = await getCityByNameEnShow("Shanghai");
+
+// 按英文展示名查询港口详情
+const seaport = await getSeaportByNameEnShow("Shanghai Port");
 ```
 
-### 归一化实体结构
+### 11. DW-SDK（数据仓库 GraphQL SDK）
+
+对 `@jctrans/dw-sdk` 的零配置封装，自动注入 baseUrl 和 Authorization Token。
 
 ```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; // 原始后端数据
+import {
+  queryOpportunityBoard,
+  GraphQLClientError,
+} from "@jctrans-materials/shared";
+import type {
+  OpportunityBoardParams,
+  BoardQueryResult,
+  DateType,
+} from "@jctrans-materials/shared";
+
+// 查询商机有效看板数据
+const result = await queryOpportunityBoard({
+  compId: 12345,
+  dateType: "QUARTER",
+  dateValue: "2026-Q2",
+});
+
+if (result.success) {
+  console.log(result.data.records);
+} else {
+  console.error(result.error);
 }
 ```
 
-### 请求配置
+> **原理**：每次调用内部新建 `createDwSdk()` 实例，调用后即销毁，无状态污染。`baseUrl` 自动从 `initSharedConfig` 的 `prefixPath + '/data'` 拼接。
+
+## 核心 API 参考
+
+### 配置
+
+| 方法 | 说明 | 签名 |
+|------|------|------|
+| `initSharedConfig` | 初始化全局配置 | `(config: Partial<SharedConfig>) => void` |
+| `getSharedConfig` | 获取当前配置 | `() => SharedConfig` |
+| `getIsEn` | 判断当前是否英文环境 | `() => boolean` |
+| `initCommonKeys` | 初始化 Cookie Key 配置 | `(keys: Partial<CommonKeysConfig>) => void` |
+
+### 搜索 V2（locationSearchV2）
+
+| 子模块 | 方法 | 说明 |
+|--------|------|------|
+| `country` | `searchByName` / `getByIds` | 国家 |
+| `region` | `searchByName` / `getByIds` | 地区（复用 Country 接口） |
+| `city` | `searchByName` / `getByIds` / `getCitiesByCountry` | 城市 |
+| `province` | `searchByName` / `getByIds` | 省份 |
+| `continent` | `searchByName` / `getByIds` | 大洲 |
+| `seaport` | `searchByName` / `getByIds` | 港口 |
+| `airport` | `searchByName` / `getByIds` | 机场 |
+| `wharf` | `getByIds` | 码头 |
+| `carrier` | `searchShipping` / `searchAir` / `search` / `getByIds` | 船公司/航空公司 |
+| `line` | `searchShipping` / `searchAir` / `search` / `getByIds` / `searchAllByCountry` | 航线 |
+| — | `searchByName` | 通用按名称搜索 |
+| — | `searchByIdWithType` | 按类型+ID查询任意实体 |
+| — | `getCitiesByCountry` | 国家→城市 |
+| — | `getChildrenByCity` | 城市→港口/机场/码头 |
+
+### 搜索 V1（baseSearch）
+
+| 方法 | 说明 |
+|------|------|
+| `search` | 通用搜索（支持 keyword + ids + scope） |
+| `searchByName` | 按名称搜索 |
+| `getByIds` / `getById` | 按 ID 查询 |
+| `getCitiesByCountry` | 国家→城市 |
+| `getChildrenByCity` | 城市→港口/机场 |
+| `searchCountryByName` / `searchCityByName` / `searchSeaportByName` / `searchAirportByName` | 按名称快捷搜索 |
+| `getContinent` / `getCountry` / `getCity` / `getProvince` / `getSeaport` / `getAirport` | 按类型获取列表 |
+
+### 认证
+
+| 方法 | 说明 |
+|------|------|
+| `loginApi` | 账号密码登录 |
+| `loginByEmailOrMobileCodeApi` | 验证码登录 |
+| `loginByQrCode` / `getLoginQrCode` | 扫码登录 |
+| `autoLoginByTGC` | TGC 单点登录 |
+| `loginByFacebookApi` / `loginByLinkedinApi` | 第三方登录 |
+| `sendEmailCodeApi` / `sendMobileCodeApi` | 发送验证码 |
+| `checkEmailCodeApi` / `checkMobileCodeApi` | 校验验证码 |
+| `validateAccountExistApi` | 校验账号是否存在 |
+| `registerApi` / `validateCompanyApi` | 注册 |
+| `resetPasswordApi` / `checkAccountExistsFPApi` / `getMEVCodeApi` | 密码找回 |
+| `setAuthSessionItems` / `getAuthSessionItems` / `resetAuthSessionItems` | Auth Session 管理 |
+| `setGioSessionItems` / `getGioSessionItems` / `resetGioSessionItems` | GIO Session 管理 |
+
+### 反查回显
+
+| 方法 | 说明 |
+|------|------|
+| `getAirportByNameEnShow` | 按英文展示名查询机场 |
+| `getCountryByNameEnShow` | 按英文展示名查询国家 |
+| `getCityByNameEnShow` | 按英文展示名查询城市 |
+| `getSeaportByNameEnShow` | 按英文展示名查询港口 |
+
+### DW-SDK
+
+| 方法 | 说明 |
+|------|------|
+| `queryOpportunityBoard` | 查询商机有效看板（分页） |
+
+导出类型：`OpportunityBoardParams`, `BoardQueryResult`, `DateType`, `GraphQLClientError`。
+
+### Token & Cookie
+
+| 方法 | 说明 |
+|------|------|
+| `setTokenAll` | 批量写入所有凭证 |
+| `getToken` / `getRefreshToken` | 读取 Token |
+| `getExpiresTimeIn` | 获取 Token 过期时间戳 |
+| `clearAllAuth` | 清除所有认证 Cookie |
+| `setRememberMe` / `getRememberAccount` | 记住账号 |
+
+### 工具
+
+| 方法 | 说明 |
+|------|------|
+| `isEmpty` | 判断值是否为空（null/undefined/空字符串/空数组/空对象/空 Map/空 Set）。数字、布尔值等原始类型返回 `false` |
+| `isIpAddress` / `getFirstDomain` | 域名工具 |
+| `getAppId` / `getProjectId` | 跨环境 ID 获取 |
+| `getLanguage` | 获取当前语言 |
+| `getSessionHeaderValue` / `toSafeHeaderValue` | HTTP Header 安全工具 |
+| `encrypt` / `decrypt` | AES 加解密 |
+| `generateClientId` / `getOrCreateClientId` | 客户端唯一标识 |
+| `installClientIdPlugin` | 为 Axios 实例注入 client-uid header |
+| `installFetchClientIdPlugin` | 为 Fetch 请求注入 client-uid header |
+
+## 类型定义
+
+### LocationType / DisplayInfo
 
 ```typescript
-interface RequestConfig {
-  params?: Record<string, any>; // URL参数
-  headers?: Record<string, string>; // 请求头
+type LocationType =
+  | "Continent" | "Country" | "Region" | "Province"
+  | "City" | "Seaport" | "Airport"
+  | "Street" | "Town" | "Wharf"
+  | "Carrier" | "Line";
+
+type DisplayInfo = LocationType; // 兼容别名
+```
+
+### LocationUnifiedItem / UnifiedItem
+
+```typescript
+interface LocationUnifiedItem {
+  id: number | string;
+  type: LocationType;
+  nameCn?: string;
+  nameEn?: string;
+  display?: string;       // 适配当前语言的展示文本
+  displayEn?: string;     // 英文展示
+  displayCn?: string;     // 中文展示
+  code?: string;          // 通用代码（Carrier: scacCode, 机场: iataCode）
+  scacCode?: string;      // Carrier: SCAC 代码
+  iataCode?: string;      // Airport: IATA 代码
+  carrierCode?: string;   // Carrier: 船公司代码
+  lineType?: string;      // Carrier/Line: air | shipping
+  country?: Record<string, any>;
+  city?: Record<string, any>;
+  province?: Record<string, any>;
+  continent?: Record<string, any>;
+  raw?: any;              // 原始后端数据
 }
+
+type UnifiedItem = LocationUnifiedItem; // 兼容别名
 ```
 
-## 注意事项
+### BaseResponse
 
-1. 接口默认分页：`current=1`（页码）、`size=10`（每页条数）
-2. 多语言判断优先级：Nuxt Cookie > 浏览器 Cookie > Nuxt SSR 上下文
-3. 实体展示文本规则：
-   - 港口/机场：`名称 (城市, 国家)`
-   - 城市/省份：`名称 (国家)`
-   - 国家：`名称 (大洲)`
-4. 请求超时时间（Axios）：默认 15000ms
-5. 重复数据：SDK 内部会自动根据 `type + id` 去重
+```typescript
+interface BaseResponse<T = any> {
+  records: T[];
+  total: number;
+  size: number;
+  current: number;
+  pages?: number;
+}
+```
+
+## 架构说明
+
+### 请求拦截器
+
+请求适配器（Axios / Fetch）共享以下拦截器逻辑：
+
+- **buildHeaders** — 统一注入 APP-ID、Accept-Language、pageCode、Authorization、popular-channel
+- **handleTokenRefresh** — Access Token 即将过期时（5 分钟内），自动使用 Refresh Token 刷新
+- **handleResponse** — 登录接口自动同步 Token、验证码接口触发 GIO 埋点、401 触发回调
+
+### 多语言判断优先级
+
+1. Nuxt `useCookie("jc-language")`
+2. 浏览器 Cookie `jc-language`
+3. Nuxt SSR 请求头中的 Cookie
+
+### 实体展示文本规则
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 港口/机场/码头 | `名称 (城市, 国家)` | Shanghai (Shanghai, China) |
+| 城市/省份 | `名称 (国家)` | Shanghai (China) |
+| 国家 | `名称 (大洲)` | China (Asia) |
+| 船公司 | `名称 (代码)` | MAERSK (MAEU) |
+| 航线 | `名称 (国家)` | AE1 (China) |
+
+## 迁移指南
+
+### 从 V1 (baseSearch) 迁移到 V2 (searchV2)
+
+V2 是 V1 的超集，所有 V1 函数仍然可用。推荐逐步迁移：
+
+```typescript
+// V1 写法
+import { searchCityByName } from "@jctrans-materials/shared";
+const result = await searchCityByName("上海", { countryId: 1 });
+
+// V2 等价写法
+import { locationSearchV2 } from "@jctrans-materials/shared";
+const result = await locationSearchV2.city.searchByName({
+  keyword: "上海",
+  countryId: 1,
+});
+```
+
+V2 新增能力：Carrier（船公司/航空公司）、Line（航线）、Province、Continent 命名空间。
+
+### crypto 函数名变更
+
+```typescript
+// 旧写法（仍然可用）
+import { Encrypt, Decrypt } from "@jctrans-materials/shared";
+
+// 新写法（推荐）
+import { encrypt, decrypt } from "@jctrans-materials/shared";
+```
 
 ## 许可证
 
-[MIT]（根据实际情况修改）
+MIT