@bi-nova/services 1.3.2-beta.202605161224

package/README.md

@@ -0,0 +1,336 @@
+# @bi-nova/services
+
+跨平台广告服务 SDK，以 NovaSDK 插件形式提供京东保险口令、京东金融现金贷等业务服务。
+
+支持环境：微信小程序、支付宝小程序、Taro、H5（浏览器）。
+
+## 安装
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @bi-nova/core @bi-nova/services
+```
+
+```bash [npm]
+npm install @bi-nova/core @bi-nova/services
+```
+
+:::
+
+## 快速开始
+
+```ts
+import { createNova } from '@bi-nova/core'
+import { createServices } from '@bi-nova/services'
+
+const nova = createNova({ appId: 'your-app-id', autoEnv: true })
+
+nova.use(createServices({
+  env: 'prod',
+  debug: false,
+  getAuthToken: () => getToken(),
+}))
+
+// 调用服务
+const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })
+```
+
+
+## 登录态 token 管理
+
+`createServices` 安装后会在 `nova` 实例上挂载登录态管理方法：
+
+```ts
+nova.setToken(token)
+nova.clearToken()
+```
+
+推荐在宿主登录成功后写入 token：
+
+```ts
+const nova = createNova({ appId: 'your-app-id', autoEnv: true })
+
+nova.use(createServices({
+  env: 'prod',
+  debug: false,
+}))
+
+// 用户登录成功后写入 token，后续需要登录态的内部服务会自动携带。
+nova.setToken(loginResult.token)
+
+// 用户退出登录或 token 失效时清理。
+nova.clearToken()
+```
+
+如果宿主已经有统一登录态管理，也可以继续使用初始化配置中的 `getAuthToken`：
+
+```ts
+nova.use(createServices({
+  env: 'prod',
+  getAuthToken: () => appStore.token,
+}))
+```
+
+内部请求的 token 获取优先级为：
+
+```txt
+nova.setToken(token) 写入的运行时 token
+> createServices({ getAuthToken }) 返回值
+> SDK storage 中的 auth_token
+```
+
+默认情况下，内部 API 请求需要 token；明确无需 token 的接口会在 SDK 内部单独标记，例如展示广告配置接口。
+
+## UMD 使用
+
+```html
+<script src="bi-nova.umd.js"></script>
+<script>
+  const { createNova, createServices } = window.BiNova
+
+  const nova = createNova({ appId: 'xxx', autoEnv: true })
+  nova.use(createServices({
+    env: 'sit',
+    debug: true,
+    getAuthToken: () => getToken(),
+  }))
+
+  // 调用方式完全一致
+  const result = await nova.jd.handleJdInsurance({ equipmentValue: '...' })
+</script>
+```
+
+---
+
+## 初始化配置
+
+### 配置选项（ServicesOptions）
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 | 适用 |
+|------|------|:----:|--------|------|------|
+| `debug` | `boolean` | 否 | `false` | 开启调试日志 | 所有 |
+| `env` | `string` | 否 | `'prod'` | 内部 API 环境：`'dev'` / `'sit'` / `'uat'` / `'prod'` | 内部服务 |
+| `apiDomain` | `string` | 否 | `''` | 自定义 API 域名（覆盖 env 映射） | 内部服务 |
+| `getAuthToken` | `() => Promise<string> \| string` | 否 | - | 获取鉴权 token | 内部服务 |
+| `externalEnv` | `string` | 否 | `'prod'` | 外部对接环境：`'sit'` / `'release'` / `'prod'` | 外部服务 |
+| `externalAppId` | `string` | 外部必填 | - | 乐遥摇平台分配的应用标识（⚠️ 非微信/支付宝小程序 appId） | 外部服务 |
+| `externalAppSecret` | `string` | 外部必填 | - | 乐遥摇平台分配的应用密钥 | 外部服务 |
+
+> ⚠️ **注意**：`externalAppId` 和 `externalAppSecret` 是由乐遥摇平台分配的应用凭证，与微信/支付宝小程序的 `appId`/`appSecret` 无关。
+
+### 配置示例
+
+**仅内部服务：**
+
+```ts
+nova.use(createServices({
+  env: 'sit',
+  debug: true,
+  getAuthToken: () => getToken(),
+}))
+```
+
+**仅外部对接服务：**
+
+```ts
+nova.use(createServices({
+  externalEnv: 'sit',
+  externalAppId: 'leyaoyao-assigned-app-id',
+  externalAppSecret: 'leyaoyao-assigned-secret',
+}))
+```
+
+**同时使用内部和外部服务：**
+
+```ts
+nova.use(createServices({
+  // 内部服务配置
+  env: 'sit',
+  getAuthToken: () => getToken(),
+  // 外部服务配置
+  externalEnv: 'sit',
+  externalAppId: 'leyaoyao-assigned-app-id',
+  externalAppSecret: 'leyaoyao-assigned-secret',
+  debug: true,
+}))
+```
+
+### 环境域名映射
+
+**内部 API（`env`）** — 适用于京东保险服务、京东金融现金贷服务
+
+| env | 域名 |
+|-----|------|
+| `dev` | `https://dm.leyaoyao.com` |
+| `sit` | `https://sm.leyaoyao.com` |
+| `uat` | `https://um.leyaoyao.com` |
+| `prod` | `https://m.leyaoyao.com` |
+
+**外部对接 API（`externalEnv`）** — 适用于外部对接京东保险服务
+
+| externalEnv | 域名 |
+|-------------|------|
+| `sit` | `https://sopenapi.leyaoyao.com` |
+| `release` | `https://uopenapi.leyaoyao.com` |
+| `prod` | `https://openapi.leyaoyao.com` |
+
+---
+
+## API 详解
+
+所有方法返回统一格式：
+
+```ts
+interface BuildResultReturn<T = any> {
+  code: number     // 0 = 成功，非 0 = 失败
+  message: string  // 提示信息
+  data: T | null   // 业务数据
+}
+```
+
+---
+
+## TypeScript 类型
+
+### 类型导入
+
+**方式一：导入特定类型（推荐）**
+
+```ts
+// 配置类型
+import type { ServicesOptions } from '@bi-nova/services'
+
+// 京东保险服务类型
+import type {
+  JdInsuranceOptions,
+  JdInsuranceExternalOptions,
+  JdInsuranceResult,
+} from '@bi-nova/services'
+
+// 京东金融现金贷服务类型
+import type {
+  JdjrCashLoanOptions,
+  JdjrCashLoanExternalOptions,
+} from '@bi-nova/services'
+
+// 通用类型
+import type {
+  PluginConfig,
+  BuildResultReturn,
+  JumpConfig,
+} from '@bi-nova/services'
+
+// 环境枚举
+import { ENV_TYPE, EXTERNAL_ENV_TYPE } from '@bi-nova/services'
+
+// 错误码
+import { JdErrorCode } from '@bi-nova/services'
+```
+
+**方式二：导入所有类型**
+
+```ts
+import type * as ServiceTypes from '@bi-nova/services'
+
+// 使用时：ServiceTypes.JdInsuranceOptions
+```
+
+### 类型使用示例
+
+**使用 ENV_TYPE 枚举配置**
+
+```ts
+import { createNova } from '@bi-nova/core'
+import { createServices, ENV_TYPE } from '@bi-nova/services'
+import type { ServicesOptions } from '@bi-nova/services'
+
+const config: ServicesOptions = {
+  env: ENV_TYPE.SIT,        // IDE 会提示可用的环境选项
+  debug: true,
+  getAuthToken: async () => {
+    return await getToken()
+  },
+}
+
+const nova = createNova({ appId: 'your-app-id', autoEnv: true })
+nova.use(createServices(config))
+```
+
+**泛型错误处理函数**
+
+```ts
+import type { BuildResultReturn } from '@bi-nova/services'
+
+async function handleServiceResult<T>(
+  promise: Promise<BuildResultReturn<T>>
+): Promise<T | null> {
+  const result = await promise
+
+  if (result.code === 0 && result.data !== null) {
+    return result.data
+  }
+
+  showToast(result.message || '操作失败，请重试')
+  return null
+}
+
+// 使用
+const data = await handleServiceResult(
+  nova.jd.handleJdInsurance({ equipmentValue: 'xxx' })
+)
+```
+
+**外部对接服务类型**
+
+```ts
+import type { JdInsuranceExternalOptions } from '@bi-nova/services'
+
+const params: JdInsuranceExternalOptions = {
+  thirdPlatform: 'yipule',
+  thirdPlatformUserId: '23413494',
+  thirdPlatformEquipmentValue: '999999',
+  phone: '13800138000',
+  extendData: {
+    customField1: 'value1',
+    customField2: 123,
+  },
+}
+
+const result = await nova.jd.handleJdInsuranceExt(params)
+```
+
+**外部对接现金贷服务类型**
+
+```ts
+import type { JdjrCashLoanExternalOptions } from '@bi-nova/services'
+
+const params: JdjrCashLoanExternalOptions = {
+  phone: '13800138000',
+  rtaId: 'rta_strategy_001',
+  thirdPlatform: 'yipule',
+  thirdPlatformUserId: '23413494',
+  thirdPlatformEquipmentValue: '999999',
+  os: 'ios',
+  client: 'miniapp',
+  extendData: {
+    customField1: 'value1',
+    customField2: 123,
+  },
+}
+
+const result = await nova.jd.handleJdjrCashLoanExt(params)
+```
+
+---
+
+## 注意事项
+
+### 通用
+
+1. **SDK 引入**：确保已正确引入京东 SDK 文件（`LyyGetCommandSDK.min.js`）
+2. **网络请求**：插件会发起网络请求，确保小程序已配置合法域名
+3. **小程序跳转权限**：使用小程序跳转功能时，需要在小程序配置中添加跳转白名单
+4. **剪贴板权限**：复制口令功能需要用户授权剪贴板权限
+5. **异步处理**：所有方法返回 Promise，使用 `async/await` 或 `.then()` 处理
+