@jctrans/dw-sdk 1.0.0

package/README.md

@@ -0,0 +1,587 @@
+# @jctrans/dw-sdk
+
+JCTRans 数据仓库前端 TypeScript GraphQL SDK — **Query Builder 风格**，**SSR 安全**，**零重型依赖**。
+
+## 特性
+
+- 🔗 **ORM 风格链式调用** — `select().arg().eq().ge().page().query()` 一气呵成
+- 🛡️ **SSR 安全设计** — 工厂函数 + 外部注入 headers，彻底杜绝 Cross-Request State Pollution
+- 📦 **零重型依赖** — 仅依赖原生 `fetch`，不引入 `@apollo/client`、`graphql` 等 AST 库
+- 🔒 **类型安全** — 全链路 TypeScript 泛型推断，字段名 IDE 自动补全 + 编译期校验
+- 🤝 **对齐 Java 后端** — 操作符、端点、query 结构、类型映射与 `data-common` / `data-sdk17` 完全一致
+- 🧩 **可扩展** — 核心与生成层分离，`api-builder` 可增量生成新的主题域 Manager
+
+## 安装
+
+```bash
+pnpm add @jctrans/dw-sdk
+```
+
+> **前置条件**：项目需已安装 `typescript >= 5.0`。
+
+## 快速开始
+
+```ts
+import { createDwSdk } from '@jctrans/dw-sdk'
+
+// 创建 SDK 实例（每次请求上下文调用一次）
+const sdk = createDwSdk({
+  baseUrl: 'https://api.jctrans.net.cn',
+  headers: { Authorization: 'Bearer xxx' },
+})
+
+// 链式查询
+const { records, total } = await sdk.opportunity
+  .opportunityEffectiveBoardPage()              // 进入商机有效看板
+  .select('companyId', 'periodType', 'statYear', 'inquiryCount', 'responseCount')
+  .arg('companyId', 12345)                       // 必填参数
+  .eq('statYear', 2026)                          // 筛选：年份 = 2026
+  .ge('inquiryCount', 10)                        // 筛选：发盘数 >= 10
+  .page(1, 20)                                   // 第 1 页，每页 20 条
+  .query()
+
+// records 类型自动推断为 OpportunityEffectiveBoard[]
+console.log(`共 ${total} 条，当前 ${records.length} 条`)
+```
+
+### 封装 API（推荐前端使用）
+
+封装层将底层字段（statYear/statMonth/statQuarter/periodType）映射为语义化入参，自动校验并返回统一结果结构：
+
+```ts
+import { createDwSdk } from '@jctrans/dw-sdk'
+
+const sdk = createDwSdk({ baseUrl: 'https://api.jctrans.net.cn' })
+
+// 季度查询
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'QUARTER',
+  dateValue: '2026-Q2',
+})
+
+// 年度查询
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'YEAR',
+  dateValue: '2026',
+})
+
+// 月度查询
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'MONTH',
+  dateValue: '2026-06',
+})
+
+if (res.success) {
+  // res.data.records, res.data.total, res.data.current, res.data.pages
+  console.log(`共 ${res.data.total} 条`)
+} else {
+  // res.error → 参数校验失败或查询错误
+  console.error(res.error)
+}
+```
+
+## 基础用例
+
+### 1. 全字段分页查询
+
+```ts
+const result = await sdk.opportunity.opportunityEffectiveBoardPage()
+  .select(
+    'companyId', 'periodType', 'statYear', 'statMonth', 'statQuarter',
+    'inquiryCount', 'responseCount', 'receivedResponseCount',
+    'potentialCustomerCount', 'oneOnOneMeetCount', 'sessionCount',
+    'viewedResponseCount', 'imCommunicateCount', 'imEffectiveCommunicateCount',
+    'viewRecommendAgentCount', 'findAgentDemandCount', 'findAgentContactCount',
+    'browseStoreCount', 'storeContactCount', 'visitorManageContactCount',
+    'publishFindAgentDemandCount', 'createTime'
+  )
+  .arg('companyId', 12345)
+  .page(1, 50)
+  .query()
+
+// result: OpportunityEffectiveBoardPageResponse
+```
+
+### 2. 按公司 + 时间维度查询
+
+```ts
+const result = await sdk.opportunity.opportunityEffectiveBoardPage()
+  .select('periodType', 'statYear', 'statMonth', 'inquiryCount', 'responseCount')
+  .arg('companyId', 12345)
+  .eq('periodType', 'month')        // 月维度
+  .eq('statYear', 2026)
+  .ge('statMonth', 1)
+  .le('statMonth', 6)               // 上半年
+  .page(1, 12)
+  .query()
+```
+
+### 3. 多条件筛选
+
+```ts
+const result = await sdk.opportunity.opportunityEffectiveBoardPage()
+  .select('companyId', 'periodType', 'statYear', 'inquiryCount')
+  .arg('companyId', 12345)
+  .eq('periodType', 'year')         // 等于
+  .ne('statYear', 2020)              // 不等于
+  .gt('inquiryCount', 100)           // 大于
+  .lt('inquiryCount', 10000)         // 小于
+  .in('statYear', [2024, 2025, 2026]) // IN
+  .like('periodType', '%month%')    // 模糊匹配（此处仅作示例）
+  .page(1, 20)
+  .query()
+```
+
+### 4. 空值筛选
+
+```ts
+// 查询 createTime 不为空的记录
+const result = await sdk.opportunity.opportunityEffectiveBoardPage()
+  .select('companyId', 'periodType', 'statYear', 'createTime')
+  .arg('companyId', 12345)
+  .isNotNull('createTime')          // 对齐 Java Conditions.isNotNull
+  .page(1, 20)
+  .query()
+```
+
+### 5. 不指定字段（使用默认）
+
+```ts
+// select 可省略，默认返回 companyId 字段
+const result = await sdk.opportunity.opportunityEffectiveBoardPage()
+  .arg('companyId', 12345)
+  .eq('statYear', 2026)
+  .page(1, 20)
+  .query()
+```
+
+### 6. 调试：查看 GraphQL payload
+
+```ts
+const graphQL = sdk.opportunity.opportunityEffectiveBoardPage()
+  .select('companyId', 'periodType', 'inquiryCount')
+  .arg('companyId', 12345)
+  .eq('statYear', 2026)
+  .page(1, 20)
+  .toGraphQL()
+
+// 输出:
+// query { opportunityEffectiveBoardPage(
+//   dto: { current: 1, size: 20, companyId: 12345, statYear: 2026 }
+// ) { total current size pages records { companyId periodType inquiryCount } } }
+```
+
+## 封装 API 用例（sdk.opportunity.board）
+
+封装 API 提供 `{ success, data, error }` 统一返回结构，参数校验失败不抛异常，前端可直接展示 `error` 字段。
+
+### 1. 季度查询
+
+```ts
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'QUARTER',
+  dateValue: '2026-Q2',   // Q 取值 1-4
+})
+```
+
+### 2. 年度查询
+
+```ts
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'YEAR',
+  dateValue: '2026',
+})
+```
+
+### 3. 月度查询
+
+```ts
+const res = await sdk.opportunity.board.query({
+  compId: 12345,
+  dateType: 'MONTH',
+  dateValue: '2026-06',   // MM 取值 01-12
+})
+```
+
+### 4. 参数校验错误处理
+
+```ts
+const res = await sdk.opportunity.board.query({
+  compId: 0,              // ❌ 必须 > 0
+  dateType: 'QUARTER',
+  dateValue: '2026-Q5',   // ❌ Q 取值 1-4
+})
+
+// res.success → false
+// res.error → "参数错误：compId 必须为大于 0 的数字"
+```
+
+### 5. 入参校验规则
+
+| 字段 | 必填 | 规则 |
+|------|------|------|
+| `compId` | ✅ | `number`，> 0 |
+| `dateType` | ✅ | `'QUARTER' \| 'YEAR' \| 'MONTH'` |
+| `dateValue` | ✅ | 格式依 dateType 而定 |
+
+**dateValue 格式：**
+
+| dateType | 格式 | 示例 |
+|----------|------|------|
+| `QUARTER` | `YYYY-QN`（Q=1-4） | `2026-Q2` |
+| `YEAR` | `YYYY` | `2026` |
+| `MONTH` | `YYYY-MM`（MM=01-12） | `2026-06` |
+
+### 6. 封装层返回值类型
+
+```ts
+interface BoardQueryResult {
+  success: boolean
+  data: BoardPageData | null   // 成功时包含 records, total, current, size, pages
+  error: string | null         // 失败时为错误描述
+}
+```
+
+## API 参考
+
+### createDwSdk(config)
+
+创建 SDK 实例的工厂函数。**每次请求上下文调用一次**，绝不在模块顶层或全局作用域调用。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `config.baseUrl` | `string` | ✅ | GraphQL 端点基础路径（如 `https://api.jctrans.net.cn`） |
+| `config.headers` | `Record<string, string>` | ❌ | 外部注入的请求头（SSR 下从 H3Event 提取 Cookie） |
+| `config.timeout` | `number` | ❌ | 超时毫秒，默认 `15000` |
+| `config.fetch` | `typeof fetch` | ❌ | 自定义 fetch 实现，默认 `globalThis.fetch` |
+
+### Query Builder 方法
+
+所有方法均返回 `this`（多态类型），支持无限链式调用。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `select(...fields)` | `...string[]` | 指定查询字段，缺省返回 `companyId` |
+| `arg(name, value)` | `string, unknown` | 设置额外参数（对齐 Java QueryBuilder.arg()） |
+| `eq(field, value)` | `string, unknown` | 等于条件 |
+| `ne(field, value)` | `string, unknown` | 不等于条件 |
+| `gt(field, value)` | `string, unknown` | 大于条件 |
+| `ge(field, value)` | `string, unknown` | 大于等于条件 |
+| `lt(field, value)` | `string, unknown` | 小于条件 |
+| `le(field, value)` | `string, unknown` | 小于等于条件 |
+| `like(field, value)` | `string, string` | 模糊匹配（后端 SQL LIKE） |
+| `in(field, values)` | `string, unknown[]` | IN 条件 |
+| `isNull(field)` | `string` | 判断为空（对齐 Java Conditions.isNull） |
+| `isNotNull(field)` | `string` | 判断不为空（对齐 Java Conditions.isNotNull） |
+| `page(current, size)` | `number, number` | 分页，默认第 1 页 20 条（current: 当前页码, size: 每页条数） |
+| `query()` | — | **终止方法**，执行分页查询 |
+| `toGraphQL()` | — | 调试用，返回当前构造的 GraphQL payload |
+
+### GraphQLClientError
+
+```ts
+import { GraphQLClientError } from '@jctrans/dw-sdk'
+
+try {
+  await sdk.opportunity.opportunityEffectiveBoardPage()
+    .arg('companyId', 12345)
+    .query()
+} catch (err) {
+  if (err instanceof GraphQLClientError) {
+    console.error(`[${err.status}] ${err.message}`)
+    // err.body — 服务端返回的原始响应体
+  }
+}
+```
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `message` | `string` | 错误描述 |
+| `status` | `number` | HTTP 状态码（0 = 网络错误，200 = GraphQL 业务错误，408 = 超时） |
+| `body` | `string` | 原始响应体 |
+| `url` | `string` | 请求的完整 URL（便于 Network 面板定位） |
+| `name` | `string` | 固定为 `'GraphQLClientError'` |
+
+### BoardService（封装层）
+
+通过 `sdk.opportunity.board` 访问。
+
+#### board.query(params)
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `params.compId` | `number` | ✅ | 公司 ID，必须 > 0 |
+| `params.dateType` | `'QUARTER' \| 'YEAR' \| 'MONTH'` | ✅ | 日期聚合类型 |
+| `params.dateValue` | `string` | ✅ | 日期值，格式依 dateType 而定 |
+
+**返回值: `Promise<BoardQueryResult>`**
+
+```ts
+interface BoardQueryResult {
+  success: boolean
+  data: {
+    total: number
+    current: number
+    size: number
+    pages: number
+    records: OpportunityEffectiveBoard[]
+  } | null
+  error: string | null
+}
+```
+
+**dateType → 底层字段映射：**
+
+| dateType | 映射到底层调用 |
+|----------|----------------|
+| `QUARTER` | `.eq('periodType', 'quarter')` + `.eq('statQuarter', N)` + `.arg('statYear', YYYY)` |
+| `YEAR` | `.eq('periodType', 'year')` + `.arg('statYear', YYYY)` |
+| `MONTH` | `.eq('periodType', 'month')` + `.eq('statMonth', N)` + `.arg('statYear', YYYY)` |
+
+## 与 Java 后端对齐
+
+SDK 与 `jctrans-data-service` 的 Java 代码完全对齐。
+
+### 端点
+
+```
+POST {baseUrl}/api/{domain}/{topic}/graphql
+```
+
+每个查询使用独立的端点 URL，domain 和 topic 在路径中可见：
+
+| domain | topic | 完整 URL |
+|--------|-------|---------|
+| `opportunity` | `opportunityEffectiveBoardPage` | `/api/opportunity/opportunityEffectiveBoardPage/graphql` |
+
+这种设计使得浏览器 DevTools → Network 面板可按路径分类筛选，便于调试。
+
+发送的请求 body 为 `GraphQLRequest`，包含 `query` 字段（及可选的 `operationName`、`variables`）。
+
+### Network 面板可见性
+
+每个查询在 Network 面板中展示为独立的 POST 请求，URL 中包含 domain/topic 路径：
+
+```
+POST /api/opportunity/opportunityEffectiveBoardPage/graphql
+Body: {"query": "query { opportunityEffectiveBoardPage(dto: ...) { ... } }"}
+Response: {"data": {"opportunityEffectiveBoardPage": {"total": ..., "records": [...]}}}
+```
+
+### 操作符
+
+| TS SDK | Java Conditions.java |
+|--------|---------------------|
+| `eq` | `eq` |
+| `ne` | `ne` |
+| `gt` | `gt` |
+| `ge` | `ge` |
+| `lt` | `lt` |
+| `le` | `le` |
+| `like` | `like` |
+| `in` | `in` |
+| `isNull` | `isNull` |
+| `isNotNull` | `isNotNull` |
+
+### query 结构
+
+产出的 GraphQL query 与后端 `opportunity.graphqls` schema 对齐：
+
+```
+query { topic(dto: { current: N, size: N, companyId: N, statYear: N, ... })
+        { total current size pages records { fields } } }
+```
+
+> **注意**：`eq` 条件中匹配 DTO 字段（`companyId`/`statYear`/`statMonth`/`statQuarter`）的会提取到 `dto` 入参中，
+> 非 DTO 字段或非 `eq` 操作符的条件仍以 `conditions` 数组方式传递。
+
+## SSR 使用指南
+
+### Nuxt 3 Server API
+
+```ts
+// server/api/opportunity/board.ts（底层 API）
+import { createDwSdk } from '@jctrans/dw-sdk'
+
+export default defineEventHandler(async (event) => {
+  const sdk = createDwSdk({
+    baseUrl: useRuntimeConfig().apiBaseUrl,
+    // ✅ 从 H3Event 提取 Cookie 透传给后端
+    headers: {
+      Cookie: getHeader(event, 'cookie') ?? '',
+      Authorization: getHeader(event, 'authorization') ?? '',
+    },
+    timeout: 10_000, // SSR 下使用较短超时
+  })
+
+  const query = getQuery(event)
+  return sdk.opportunity.opportunityEffectiveBoardPage()
+    .select('companyId', 'periodType', 'statYear', 'inquiryCount', 'responseCount')
+    .arg('companyId', Number(query.companyId))
+    .eq('statYear', Number(query.year) || 2026)
+    .page(Number(query.page) || 1, Number(query.size) || 20)
+    .query()
+})
+```
+
+```ts
+// server/api/opportunity/board-wrapped.ts（封装 API）
+import { createDwSdk } from '@jctrans/dw-sdk'
+
+export default defineEventHandler(async (event) => {
+  const sdk = createDwSdk({
+    baseUrl: useRuntimeConfig().apiBaseUrl,
+    headers: {
+      Cookie: getHeader(event, 'cookie') ?? '',
+      Authorization: getHeader(event, 'authorization') ?? '',
+    },
+  })
+
+  const body = await readBody(event)
+  // body: { compId: 12345, dateType: 'QUARTER', dateValue: '2026-Q2' }
+  return sdk.opportunity.board.query(body)
+})
+```
+
+### Nuxt 3 Composables（客户端）
+
+```ts
+// composables/useOpportunity.ts
+import { createDwSdk, type BoardQueryResult } from '@jctrans/dw-sdk'
+
+export function useOpportunity() {
+  const sdk = createDwSdk({ baseUrl: '/api' })
+
+  /** 底层 API（Query Builder） */
+  async function fetchBoard(
+    companyId: number,
+    page = 1,
+    size = 20
+  ): Promise<OpportunityEffectiveBoardPageResponse> {
+    return sdk.opportunity.opportunityEffectiveBoardPage()
+      .select('companyId', 'periodType', 'statYear', 'statMonth',
+        'inquiryCount', 'responseCount', 'receivedResponseCount')
+      .arg('companyId', companyId)
+      .page(page, size)
+      .query()
+  }
+
+  /** 封装 API（推荐—语义化入参，自动校验） */
+  async function queryBoard(
+    compId: number,
+    dateType: 'QUARTER' | 'YEAR' | 'MONTH',
+    dateValue: string
+  ): Promise<BoardQueryResult> {
+    return sdk.opportunity.board.query({ compId, dateType, dateValue })
+  }
+
+  return { fetchBoard, queryBoard }
+}
+```
+
+### SSR 避坑清单
+
+| ❌ 错误做法 | ✅ 正确做法 |
+|------------|------------|
+| 模块顶层 `export const sdk = createDwSdk(...)` | 每次请求/组件内调用 `createDwSdk()` |
+| 在 SDK 内部读取 `document.cookie` | headers 由外部注入 |
+| 跨请求复用同一个 Query 实例 | 每次 `opportunityEffectiveBoardPage()` 返回全新实例 |
+| 在实例上缓存上次请求的 Promise | 每次 `execute()` 返回独立 Promise |
+| 全局单例 Client | 工厂函数创建，用完即 GC |
+
+## 架构
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  createDwSdk(config)                                              │
+│  ├── GraphQLClient (fetch 封装)                                    │
+│  │   POST {baseUrl}/api/{domain}/{topic}/graphql                  │
+│  │   ├── /api/opportunity/opportunityEffectiveBoardPage/graphql   │
+│  │   ├── /api/order/adsOrderPage/graphql (待生成)                  │
+│  │   └── /api/logistics/... (待生成)                               │
+│  ├── OpportunityManager (商机域)                                    │
+│  │   ├── opportunityEffectiveBoardPage() → Query Builder          │
+│  │   └── board (getter) → BoardService (封装层)                    │
+│  ├── OrderManager (订单域, 待生成)                                  │
+│  └── LogisticsManager (物流域, 待生成)                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| 层 | 目录 | 说明 |
+|----|------|------|
+| **基建层** | `src/core/` | `GraphQLClient` + `BaseQuery`，手写维护 |
+| **生成层** | `src/generated/` | 各主题域 Manager + Query + types，由 `api-builder` 自动生成 |
+| **封装层** | `src/services/` | 语义化入参封装，参数校验，统一返回结构 |
+| **入口** | `src/index.ts` | `createDwSdk()` 工厂函数 + 类型导出 |
+
+## 类型系统
+
+SDK 提供全链路类型推断，调用方无需手动标注泛型：
+
+```
+createDwSdk()
+  → DwSdk
+    → sdk.opportunity                                    // OpportunityManager
+      → sdk.opportunity.opportunityEffectiveBoardPage()  // OpportunityEffectiveBoardQuery
+        → .query()                                       // Promise<OpportunityEffectiveBoardPageResponse>
+          → result.records                               // OpportunityEffectiveBoard[]
+```
+
+字段名通过 `keyof` 联合类型约束，IDE 自动补全：
+
+```ts
+.('')
+// IDE 弹出: 'companyId' | 'periodType' | 'statYear' | 'statMonth' | 'statQuarter'
+//           | 'inquiryCount' | 'responseCount' | ...
+```
+
+### 当前前端可补全能力
+
+```ts
+.                   // 可补全: opportunity
+sdk.opportunity
+  .opportunityEffectiveBoardPage()
+  // 可链式补全: select / arg / eq / ne / gt / ge / lt / le
+  //            / like / in / isNull / isNotNull / page / query / toGraphQL
+  .board
+  // BoardService: .query({ compId, dateType, dateValue })
+  // 返回 BoardQueryResult: { success, data, error }
+```
+
+### 封装层导出类型
+
+```ts
+import type {
+  DateType,              // 'QUARTER' | 'YEAR' | 'MONTH'
+  OpportunityBoardParams,// { compId: number; dateType: DateType; dateValue: string }
+  BoardQueryResult,      // { success: boolean; data: BoardPageData | null; error: string | null }
+  BoardPageData,         // { total; current; size; pages; records }
+} from '@jctrans/dw-sdk'
+```
+
+### 如何让前端都"点得出来"新能力
+
+1. 先由 `api-builder` 生成 `src/generated/{domain}/` 下的 Manager + Query + types。
+2. 在 `src/index.ts` 的 `DwSdk` 接口增加新字段。
+3. 在 `createDwSdk()` 返回对象中实例化该 Manager。
+4. 发布新版本后，前端更新依赖并重启 TS Server（或重启 IDE）。
+
+## 扩展新主题域
+
+`api-builder` 增量生成新主题域后，按以下步骤接入：
+
+1. 将生成的 `src/generated/{domain}/` 目录放入项目中
+2. 在 `src/index.ts` 中 import 新 Manager
+3. 在 `DwSdk` 接口中添加字段
+4. 在 `createDwSdk()` 函数体中实例化
+
+调用方无需任何改动，TypeScript 自动推断新字段类型。
+
+## 许可
+
+UNLICENSED — JCTRans 内部使用