# 京东店铺 API 连接与 SaaS-VOC 能力深度评估

> 评估时间：2026-08-15，商品详情补充调研：2026-08-16  
> 评估对象：已完成商家授权的 JD 店铺连接  
> 评估范围：OAuth/token 状态、SP-API 商品/SKU/库存、订单/售后/评价/数据能力、与现有 SaaS-VOC 模型的覆盖关系

## 1. 结论先行

当前连接已经从“只有 OAuth、无法验证业务权限”进入“商品域真实可用”的阶段：

- Parse 中已存在 1 条生产环境 JD 授权记录，包含店铺 UID、access token、refresh token 和过期时间；凭证本身未写入本报告。
- 新版 SP-API 已真实返回本店商品数据：商品总数 **614**，商品列表、SKU 列表、库存查询均返回 `success: true`。
- 当前已经可以支撑“本店商品主数据 + SKU 主数据 + 库存状态”的第一阶段同步。
- 商品详情文档显示，详情页可以继续扩展到状态、价格、属性、媒体、物流和售后承诺，但详情接口本身不提供订单经营趋势或用户 VOC 证据。
- 订单列表和售后服务单仍受京东侧云鼎调用前置条件影响；这不是代码签名错误，也不能直接解释为 token 无效。
- 客服、承运商等接口在前次验证中返回“应用无该 API 调用权限”；报表接口仍需按接口专用签名/请求体规则复测。
- 评价、流量、GMV、退款原因、竞品数据尚未形成真实成功样本，因此当前不能把现有本地快照中的这些字段当作 JD 实时能力。

综合判断：**商品/SKU/库存能力可进入工程化接入；订单/售后是下一阶段的外部开通项；评价和经营报表是 SaaS-VOC 价值闭环的关键风险项。**

## 2. 凭证与连接状态

### 2.1 已验证状态

授权记录通过 Parse `EcomAuth` 查询确认：

| 项目 | 结果 |
|---|---|
| 平台 | `jd` |
| 环境 | `production` |
| 店铺标识 | 已保存 UID，报告不展开具体值 |
| access token | 存在，长度 36；不记录原文 |
| refresh token | 存在，长度 36；不记录原文 |
| access token 有效期 | 约 1 年，当前记录到 2027-08-15 |
| refresh 刷新阈值 | 2026-09-14 前后进入刷新窗口 |
| 存储位置 | Parse `EcomAuth`，服务端读取 |

### 2.2 现有模块边界

当前 JD 模块已具备：

- 生成 OAuth 授权链接和随机 `state`；
- 处理回调 `code`，向京东换取 token；
- 将授权信息保存到 Parse；
- 按店铺 UID 查询最新授权记录；
- access token/refresh token 临近过期时刷新；
- 提供健康检查、token 状态和取 token 路由。

当前 JD 模块尚未具备：

- 通用 SP-API 请求客户端；
- 服务端签名生成和参数规范化；
- 商品、SKU、库存、订单、售后、评价、报表 API 封装；
- 增量游标、分页断点、幂等写入和失败重试；
- 将 JD 原始响应转换为 `DomesticDataset` 的同步任务。

### 2.3 凭证安全结论

`E:\workspace\server\future-server\fmode-server\modules\voc-ecom-jd-api\src\config.ts` 当前存在 AppKey/AppSecret 的硬编码 fallback。即使这是为了模块自包含，构建产物也可能被读取或反编译，生产环境应改为：

1. AppKey 可作为公开配置或服务端配置保存；
2. AppSecret 只通过服务端环境变量、密钥管理服务或部署平台 secret 注入；
3. 前端和浏览器 URL 永远不出现 AppSecret；
4. `get-access-token` 不应向客户浏览器返回完整 access token；
5. 日志只记录 shop UID、接口名、HTTP 状态、京东 request_id 和脱敏错误码。

## 3. 官方调用与签名规则

本次使用新版 SP-API 入口：

`https://api-cn.jd.com/rest`

官方文档：

- [SP-API 调用方法](https://open.jd.com/v2/#/doc/dev-guide?listId=1100587)
- [SP-API 签名算法](https://open.jd.com/v2/#/doc/dev-guide?listId=1100604)
- [商品列表 listProducts](https://open.jd.com/v2/#/doc/api?apiCateId=100081&apiId=100508&apiName=listProducts&gwType=1)
- [SKU 列表 listSkus](https://open.jd.com/v2/#/doc/api?apiCateId=200375&apiId=100509&apiName=listSkus&gwType=1)
- [库存 listSkuStocks](https://open.jd.com/v2/#/doc/api?apiCateId=200375&apiId=100667&apiName=listSkuStocks&gwType=1)
- [商品详情 getProduct](https://open.jd.com/v2/#/doc/api?apiCateId=200375&apiId=100588&apiName=getProduct&gwType=1)
- [订单详情 getOrder](https://open.jd.com/v2/#/doc/api?apiCateId=100066&apiId=100251&apiName=getOrder&gwType=1)

当前已验证的 MD5 规则：

1. 收集 `X-JOS-Access-Token`、`X-JOS-App-Key`、`X-JOS-Timestamp`、路径参数、查询参数和请求体参数；
2. 按参数名 ASCII 升序排列；
3. 拼接为 `key + value`，不插入 `&`；
4. 计算 `MD5(AppSecret + 拼接结果 + AppSecret)`；
5. 将摘要转成大写；
6. 时间戳使用毫秒；
7. `X-JOS-Request-Identity: vender` 是相关接口要求的请求头，但不加入成功请求的签名参数串。

工程上必须把签名放在后端统一客户端中，禁止由 Angular 直接拼签名。

## 4. 真实接口测试结果

### 4.1 已通过的接口

| 数据域 | 接口 | 测试参数摘要 | 结果 | 能力判断 |
|---|---|---|---|---|
| 商品 | `GET /sp-product/v0/products` | `scopeSet=productName`、分页、有效商品状态 | HTTP 200，`success: true`，总数 614 | 当前店铺商品列表可读 |
| SKU | `GET /sp-product/v0/skus` | 以商品 ID 查询，返回 SKU ID、商品 ID、名称、状态 | HTTP 200，`success: true` | 当前商品的 SKU 主数据可读 |
| 库存 | `GET /sp-product/v0/sku-stocks` | 以 SKU ID 查询 | HTTP 200，`success: true` | 当前 SKU 库存可读 |

代表性样本（仅业务 ID 和数量，不包含凭证）：

- 商品 ID：`10026650610613`；
- SKU ID：`10116518781681`；
- 库存样本：`stockNum=1000`、`warehouseId=0`、`orderBookingNum=0`、`unpaidBookingNum=0`。

这三个成功结果说明：AppKey、签名、access token、接口路径和店铺授权关系已经至少在商品域闭环成立。之前出现的 access token 为空错误来自跨进程环境变量未重新读取 Parse，不是当前授权失效；后续探测必须在同一进程内先读取最新授权记录再发请求。

### 4.2 受云鼎或权限前置条件影响的接口

| 数据域 | 接口/范围 | 既有结果 | 解释 |
|---|---|---|---|
| 订单 | `GET /sp-order/v0/orders` | `99904030005` | 需要从云鼎平台发起调用，未进入订单业务数据层 |
| 订单 | `GET /sp-order/v0/orders/{orderId}` | 文档标记需授权；暂无真实成功样本 | 需要订单列表先拿到真实订单号，再验证详情 |
| 售后 | 售后服务单列表 | `99904030005` | 同样受云鼎调用前置条件影响 |
| 客服 | 客服列表相关接口 | `99904030008` | 当前应用没有该 API 调用权限 |
| 物流 | 承运商列表相关接口 | `99904030008` | 当前应用没有该 API 调用权限 |
| 报表 | `sp-data` 报表定义探测 | `99904000013` | 需要按该接口的专用签名/请求体规则复测，不能据此判定无权限 |

这些错误需要分开处理：

- `99904030005` 是调用平台/接入前置条件，不是简单的 token 续期问题；
- `99904030008` 是 API 权限包问题；
- `99904000013` 目前只能归类为请求签名或报表接口格式待复核；
- 只有返回业务响应并携带真实店铺数据，才能认定某数据域已真正可用。

### 4.3 尚未形成成功样本的能力

| 数据域 | 文档或已知入口 | 当前结论 |
|---|---|---|
| 商品详情 | `getProduct` | 文档存在，需用有效商品 ID 做字段级回归 |
| 商品评价 | 旧版 JOS `jingdong.pop.PopCommentJsfService.getVenderCommentsForJos` 等评价方法 | 只有方法线索，没有当前授权下的成功响应 |
| 流量/转化 | 新版数据 API、报表 API | 需要 schema、数据权限和时间粒度验证 |
| 退款原因 | 售后服务单详情/日志 | 受售后接口前置条件影响 |
| 竞品数据 | 商品/市场/搜索类数据 | 本店授权不等于竞品数据授权，不能推导为可用 |

## 5. 商品详情深度研究

### 5.1 官方接口边界

官方商品查询场景把 SPU 和 SKU 分开定义：SPU 是商品信息聚合单位，SKU 是物理上不可分割的最小库存单元。当前商品详情接口把两者合并到一次调用中：

```text
GET /sp-product/v0/products/{productId}
```

官方文档：

- [商品查询场景方案](https://open.jd.com/v2/#/doc/scene?listId=1100463)
- [获取商品详情 getProduct](https://open.jd.com/v2/#/doc/api?apiCateId=100081&apiId=100588&apiName=getProduct&gwType=1)
- [新老商品状态码对应关系](https://joyspace.jd.com/pages/qbougEvCGW7f2Rcia0dL)

已确认的请求约束：

| 项目 | 规则 |
|---|---|
| productId | 路径参数，`int64`，即京东商品 ID/wareId |
| request | 查询对象；至少应明确业务场景 |
| scene | `pop` 表示 POP，`vc` 表示 VC/自营供应商场景 |
| categoryId | 可选末级类目 ID；传入末级类目后才返回搜索推荐图 |
| spuSkuApplyGray | 可选自营 SPU 融合灰度开关 |
| 授权 | 文档标记“需用户授权” |
| 数据维度 | 店铺范围、供应商简码范围；本店应使用 `X-JOS-Request-Identity: vender` |
| 服务端时间 | `X-JOS-Timestamp` 精确到毫秒，服务端允许约 10 分钟误差 |

官方商品查询方案还说明：

- 商品列表支持商品状态、店内分类等筛选，最多支持查询 10 万条，应采用分页同步；
- SKU 列表可按 SKU、上下架状态、库存等维度检索，但部分字段只支持 POP；
- `wareId` 是京东商品 ID，一个 wareId 可以有多个 skuId；一个 skuId 只属于一个 wareId；
- `getProduct` 的详情结果不应替代准确库存查询，详情里的 `stockNum` 与京麦商品列表口径一致，精确库存仍应使用 `listSkuStocks`；
- 非盖亚商品可能出现京麦展示的子 SKU 与接口 `skuList` 结构不同的情况，接入时必须保留平台原始 SKU 关系，不按页面视觉层级猜测 SKU 数量。

### 5.2 getProduct 可提供的数据

下面按“可以展示/可以分析/应限制展示”拆分官方响应字段。

#### A. 商品身份与状态

| 字段组 | 典型字段 | 可形成的页面能力 |
|---|---|---|
| 标识 | `productId`、`itemNum`、`wareId`、`model`、`upcCode` | 商品 ID、商品编号、型号、条码检索和去重 |
| 商品有效性 | `yn` | 有效/已删除状态 |
| 上下架状态 | `productStatus`、`productStatusNew`、`saleState`、`saleStateName` | 在售、下架、审核中、违规下架等状态标签 |
| 状态时间 | `onlineTime`、`offlineTime`、SKU `onShelfTime` | 上架、下架时间线和生命周期节点 |
| SKU 状态 | `skuEnableStatus`、`valid`、`skuStatus.onOffShelfStatus` | SKU 启用、停用、无效、上下架状态 |

注意：自营商品的 product 维度状态和 `createdTime`/`modifiedTime` 有缺失规则；不能用 POP 状态码的含义直接解释自营数据。状态应同时保存原始码和标准化标签。

#### B. 标题、品牌与类目

| 字段组 | 典型字段 | 页面用途 |
|---|---|---|
| 标题 | `productTitle.title`、`productNames` | 商品卡片、详情页标题、搜索 |
| 推荐词 | `recommendWords` | 商品卖点候选词、内容提示，不直接等同于人工卖点 |
| 品牌 | `brandInfo.brandId`、中文/英文品牌名、标题品牌名 | 品牌筛选、品牌归属校验 |
| 类目 | 一级/二级/三级/末级 ID 与名称 | 类目树、类目分析、类目覆盖质量 |
| 结构关系 | `currencySpuId`、`productId`、`skuId` | SPU/SKU 关系和变体组展示 |

当前系统的 `category1/2/3` 可以直接承接类目名称；但商品详情接口对部分类目名称标注了业务模式限制，应以实际返回字段为准，不能在空字段时从 ID 反推名称。

#### C. 规格、属性和变体

| 字段组 | 典型字段 | 页面用途 |
|---|---|---|
| 基础尺寸 | `length`、`width`、`height`、`weight` | 规格档案、物流包装信息 |
| 商品属性 | `goodsAttrInfos`、`attrNames`、`attrValues`、`unit` | 规格表、属性筛选、产品定义 |
| 销售属性 | `saleAttrs`、`attrKey`、`attrValues`、颜色标识 | 颜色/容量/型号等变体选择 |
| 自定义属性 | `customAttrInfos`、`customAttrValues` | 店铺自定义规格和产品定义 |
| SKU 列表 | `skuId`、`skuNames`、`outerId`、UPC、SKU 属性、SKU 状态 | SKU 明细表、变体库存和状态 |
| 套装关系 | `suiteSkus` | 组合商品的子 SKU 和数量 |

当前 `DomesticProductProfile.color` 和 `specification` 是两个字符串，承载不了多属性、多 SKU 和属性值 ID。生产模型应保留结构化属性数组，字符串只作为兼容展示字段。

#### D. 价格与销售条件

| 字段组 | 典型字段 | 可用场景 | 权限/展示注意 |
|---|---|---|---|
| 公开价格 | `marketPrice`、`jdPrice` | 商品档案当前挂牌价 | 不等于历史成交均价 |
| 特殊价格 | `agreementPrice`、优惠券价、限时价、参考价 | 价格构成和活动上下文 | 需按店铺业务身份确认 |
| 划线价 | `lineationPrice`、类型、应用原因 | 价格合规提示 | 不直接当作实际售价 |
| 价格范围 | `minSalePrice`、`maxSalePrice`、错误提示 | 多 SKU 价格区间 | 应以 SKU 维度展示 |
| 成本/协议 | `costPrice`、协议价 | 内部经营或权限用户 | 不应默认展示给所有角色 |

`DomesticProductMarketSnapshot.currentPrice` 当前用于竞品市场快照；本店 `jdPrice` 不应写入竞品 `market` 对象。`DomesticProduct.summary.averageUnitPrice` 也必须继续来自订单成交金额/成交件数，不能拿挂牌价代替。

#### E. 描述、图片、视频与内容资产

| 字段组 | 典型字段 | 页面用途 |
|---|---|---|
| 商品描述 | `productDetailDesc.desc`、移动端描述、小程序描述 | 商品详情内容预览、内容质量检查 |
| 包装说明 | `packListing`、温馨提示、适用车型说明 | 购买前信息完整度、售后风险提示 |
| 主图 | `mainImages.imageInfoList`、主图标识、排序 | 商品详情首图和图片画廊 |
| 衍生图片 | 长图、透明图、白底图、规格图、搜索推荐图 | 视觉素材检查和渠道适配 |
| 视频 | 视频 ID、封面、标题、播放地址、时长、状态 | 商品内容资产完整度 |
| 素材状态 | 图片审核状态、审核描述、规格图标记 | 素材质量和审核问题追踪 |

当前系统多数商品只有 `detail.imageUrl`，详情接口能够把它扩展成图片画廊和内容质量模块。图片与视频应保存 URL、排序、状态和 `collectedAt`，避免每次详情页打开时直接依赖京东实时接口。

#### F. 售后、物流和履约属性

| 字段组 | 典型字段 | 页面用途 |
|---|---|---|
| 售后承诺 | 保修、保质期、服务、服务描述、售后说明 | 商品详情页售后承诺、风险提示 |
| 配送信息 | `transportId`、`promiseId`、配送方式、发货地、仓库 | 配送能力和履约上下文 |
| 包装信息 | 包装清单、包装规格、箱规、单位 | 规格档案和履约准备 |
| 仓库信息 | 仓库 ID、店铺 ID、仓库位置、状态 | 库存按仓库拆分 |
| 合作类型 | `colType`、仓库状态 | SOP/FBP/FCS 等履约口径 |
| 特殊服务 | 特殊服务列表、服务编码 | 服务标签和场景识别 |

`jdExpress` 和 `localDelivery` 不是 getProduct 中可以直接一一对应的统一布尔字段。除非有明确的业务字段映射，否则页面应显示“未标记/未知”，不要用配送方式字符串推断即时零售或京东配送。

#### G. 税务、质检和运营扩展

接口还可能返回税务信息、质检信息、运营人员、活动、质检文件、商品健康或业务扩展字段。它们适合放入权限控制后的“商品合规/商品管理”页，不适合直接进入公开的 VOC 快照：

- 成本价、协议价、税务和结算字段需要角色权限；
- 运营人员 PIN、地址列表、仓库位置等字段属于敏感或内部字段；
- 质检文件、资质文件和活动协议应保留引用与状态，文件内容单独受控；
- 商品详情正文可以进入 AI 分析上下文，但要保留原始来源和采集时间，避免模型把描述文案当成用户评价。

### 5.3 本次真实验证状态

已真实成功的商品域接口仍是：商品列表 614 个、SKU 列表、准确库存查询。`getProduct` 的官方文档字段和请求规则已完成补充调研，但本次补充复测在读取 Parse 授权记录时收到 `unauthorized`，因此没有把商品详情接口标记为“真实成功”。

这两个问题应分开：

1. 先恢复服务端对 `EcomAuth` 的读取凭证，确认不是 Parse MasterKey/部署配置变化；
2. 再用已验证商品 ID 调用 `scene=pop` 的详情接口；
3. 记录真实返回字段覆盖率，尤其是 `productInfo`、`skuList`、图片、价格、详情描述、类目和物流字段；
4. 对同一商品分别验证 `scene=pop` 和错误场景，确认错误码归因；
5. 将准确库存继续以 `listSkuStocks` 作为唯一库存来源。

## 6. 与现有 SaaS-VOC 系统的字段映射

### 5.1 可以直接落地的部分

现有模型位于 `src/app/core/models/domestic.models.ts`：

| 现有字段 | JD 来源 | 接入判断 |
|---|---|---|
| `DomesticProduct.productId` | 商品 ID | 直接映射 |
| `productKey` | 建议生成 `jd:{productId}` | 直接生成，保持现有关系表稳定 |
| `title` | 商品名称/详情名称 | 商品列表或详情映射 |
| `brand`、`category1/2/3` | 商品详情/类目信息 | 需商品详情接口确认字段 |
| `model` | 商品型号或商家型号 | 需从详情/SKU 属性抽取 |
| `detail.skuStatus` | SKU 状态 | SKU 列表映射 |
| `detail.shopId`、`sellerId` | 店铺 UID、商家 UID | 授权记录和接口响应映射 |
| 库存状态 | `stockNum`、预占库存、未付款预占 | 建议新增库存快照，不塞进销售汇总 |
| `detail.collectedAt` | 同步时间 | 由同步任务统一生成 |

### 5.2 不能由商品接口直接填充的部分

现有 `DomesticMetricSummary` 需要：

`gmv`、销量、订单数、成交客户、曝光、点击、访客、加购、退款金额、退款件数、退款订单数、转化率等。

商品/SKU/库存接口不能提供这些经营指标。需要分别依赖：

- 订单列表/详情：订单数、商品件数、订单金额、订单状态、支付/履约时间；
- 售后服务单：退款金额、售后类型、售后原因、售后状态；
- 数据/报表 API：曝光、点击、访客、加购及稳定的日粒度经营指标；
- 评价 API：评分、评价正文、评价时间和 VOC 样本；
- 竞品或市场数据源：竞品价格、销量、评价和市场排名。

在这些接口未通过前，应把缺失指标保持为 `null` 或明确的“未接入”，不要填 0。填 0 会让页面把“没有采集到”误判为“真实为零”。

### 5.3 与现有页面的对应关系

现有 `DomesticDatasetService` 和 `DomesticAnalyticsAdapterService` 已经围绕以下页面场景工作：

- 经营总览：GMV、销量、订单、访客、退款和趋势；
- 商品运营：本品商品、SKU、状态、价格和销量趋势；
- 退款风险：退款金额占比、退款订单数、售后归因；
- VOC 分析：本品/竞品评价拆分、评分、正文和情绪分析；
- 竞品映射：本品与竞品商品关系；
- 数据质量：商品、评论、映射和采集完整度。

当前 JD API 只能立即支撑“商品运营”的基础层，以及库存风险的新增看板。要支撑完整经营总览和退款风险，需要先解决订单/售后；要支撑 VOC 结论，需要先解决评价正文；要支撑竞品页面，需要另行接入市场数据源。

## 7. 页面能力与可展示数据

### 7.1 现有页面的真实消费关系

| 页面 | 当前依赖 | 接入商品详情后可展示 | 仍需其他数据域 |
|---|---|---|---|
| 商品经营详情 | `DomesticProduct.summary`、`trend`、基础档案 | 标题、图片、品牌、型号、类目、状态、价格、SKU 数量、规格、图片/视频、商品描述、库存摘要、详情采集时间 | 订单/报表提供 GMV、销量、访客、转化、退款和日趋势；评价 API 提供评论样本 |
| 商品运营总览 | 商品汇总、日指标、评论范围、类目聚合 | 商品数、有效/下架/审核状态、类目覆盖、库存风险和商品信息完整度 | 订单/报表提供经营排行和趋势；评价提供本品 VOC 覆盖 |
| 品类分析 | 商品类目 + `summary` 聚合 | 类目商品数、状态分布、属性完整度、库存覆盖、类目详情链接 | 订单/报表提供类目 GMV、成交、访客和退款 |
| 竞品详情 | `detail`、`market`、`reviews`、本品关系 | 该页面的商品档案、图片、规格、卖点、售后和履约字段可复用 | JD 本店授权不能提供竞品市场快照；评价需要评价 API；竞品价格/销量来自外部市场采集 |
| VOC 详情/评价工作台 | `reviews` + 商品上下文 | 标题、类目、型号、商品描述、属性可作为 AI 分析上下文 | 评价列表、正文、星级、时间是核心输入，商品详情本身不产生 VOC 结论 |
| 产品开发 | 商品、类目、趋势、竞品关系、评价 | 属性缺口、规格结构、图片/视频资产、售后承诺、商品定义素材 | 趋势需要经营指标；需求挖掘需要本品评价；竞品对标需要市场数据 |
| 数据中心 | 来源、同步任务、质量规则、指标字典 | 商品主数据同步、详情字段覆盖率、SKU/库存同步任务、图片和状态异常 | 订单、售后、评价、报表、结算仍需各自连接器 |

### 7.2 商品经营详情页建议升级

当前 `src/modules/domestic-voc/product-operating-detail.component.ts` 的页面已经有四类经营指标、趋势图、商品档案、流量漏斗和数据口径，但档案只展示商品 ID、型号、品牌、平台、二/三级类目、竞品关系和评论样本。接入 getProduct 后建议增加以下四个层次：

#### 顶部商品身份区

- 主图和图片切换；
- 商品标题、商品 ID、商品编号、型号、品牌；
- 在售/下架/审核中/删除状态；
- 当前 JD 价和 SKU 价格区间；
- SKU 数量、有效 SKU 数量、库存风险标签；
- 最后上架时间和详情采集时间。

#### 商品内容区

- 商品卖点候选词和详情描述摘要；
- 类目 ID/名称；
- 结构化属性表，显示属性名、属性值、单位和是否必填；
- 主图、白底图、规格图、视频的数量、审核状态和排序；
- 包装清单、温馨提示、适用车型/场景说明。

#### SKU 与库存区

- SKU ID、SKU 名称、外部 SKU、销售属性；
- SKU 启用/上下架状态；
- 当前准确库存、订单预占、未付款预占、仓库 ID；
- 库存更新时间和数据源；
- 按 SKU 的价格、库存和状态筛选。

#### 经营与 VOC 区

- 已验证订单/报表数据才显示 GMV、销量、订单、访客和转化；
- 已验证售后数据才显示退款金额、退款件数和退款原因；
- 已验证评价数据才显示本品评价数、评分分布、正文和 AI 主题；
- 商品详情文案和用户评价分开标注来源，避免把商品宣传语当作用户声音。

### 7.3 当前页面能达到的能力级别

在只使用已经验证的商品列表、SKU 和库存接口时，系统可上线：

- 本店商品目录和商品搜索；
- SPU/SKU 关系查看；
- 商品上下架/有效性状态查看；
- SKU 维度库存监控和库存预占展示；
- 商品类目、品牌、型号和规格档案；
- 商品主图、详情图、视频和详情描述的完整度检查；
- 商品信息质量和采集新鲜度检查；
- 商品运营详情页的“商品资产”部分。

在订单、售后、评价和报表都打通后，才能完整上线：

- 商品日 GMV、销量、订单和转化趋势；
- 退款风险和售后原因归因；
- 本品评价健康度、主题、情绪和痛点；
- 商品内容/规格/履约属性与用户评价的关联分析；
- 产品迭代建议和生命周期复盘。

### 7.4 当前模型需要调整的地方

现有 `DomesticProductProfile` 只有图片、颜色、规格、产地、重量、尺寸、上架时间、店铺、商家、SKU 状态、履约布尔值和卖点等扁平字段。建议新增一个独立的结构化详情对象，而不是继续把 JD 全部字段压缩成字符串：

```ts
interface JdProductDetailSnapshot {
  productId: string;
  itemNum?: string;
  model?: string;
  status?: { raw?: number; label?: string; source?: string };
  brand?: { id?: string; name?: string; enName?: string };
  categories?: Array<{ level: number; id?: string; name?: string }>;
  prices?: { jd?: number; market?: number; min?: number; max?: number };
  attributes?: Array<{ id?: string; name: string; values: string[]; unit?: string }>;
  skus?: Array<{ skuId: string; name?: string; attributes?: Record<string, string>; status?: string }>;
  media?: { images: string[]; whiteBackgroundImages: string[]; videos: string[] };
  description?: { pc?: string; mobile?: string; packageList?: string; tips?: string };
  logistics?: { delivery?: string; promiseId?: string; transportId?: string; warehouseIds?: string[] };
  afterSales?: { warranty?: string; shelfLifeDays?: number; service?: string; description?: string };
  collectedAt: string;
}
```

字段是否存在应由 `fieldAvailability` 或来源元数据标记，页面使用 `null`/“未返回”表示缺失，不把缺失字段格式化成 0。当前商品经营详情页中的 `number()`、`currency()` 和 `percent()` 都会把空值转成 0，生产数据接入前需要增加数据状态判断。

### 7.5 数据中心状态需要同步调整

当前 `src/modules/data-center/data-center.component.ts` 的连接器状态是：商品主数据 supported、商品评价 supported、订单/售后/库存/结算 building。结合本次真实结果，建议改成更准确的分层状态：

- 商品主数据：`supported`，包含商品列表、详情待实测、SKU 列表；
- 库存：`supported-read-only`，商品库存查询已经成功，但库存同步任务和仓库维度快照还未工程化；
- 商品评价：`pending-permission`，文档和旧版方法线索存在，当前授权下没有成功样本；
- 订单/售后：`blocked-by-platform`，待云鼎调用前置条件和权限包确认；
- 结算：`building`，本次没有验证财务接口。

同时，`DataCenterSyncScope` 目前只有 `product | reviews`，应增加 `inventory`，并让数据中心的“可售库存”指标从 missing 调整为 partial/read-only，而不是在有真实库存接口结果后继续显示缺失。

## 8. 能力覆盖矩阵

| 场景 | 当前状态 | 覆盖度 | 说明 |
|---|---|---:|---|
| 店铺授权与凭证续期 | 已验证 | 90% | OAuth、Parse 存储和刷新已具备；需补撤销授权、重复授权幂等 |
| 商品目录同步 | 已验证 | 80% | 列表可读；商品详情、类目和媒体字段需继续回归 |
| SKU 主数据同步 | 已验证 | 85% | SKU 列表成功；需补 SKU 属性、价格和变体关系 |
| 库存监控 | 已验证 | 75% | 可读取库存和预占量；需确认分页、批量上限、仓库维度和频率 |
| 订单经营分析 | 外部前置条件阻断 | 20% | 接口文档存在，但暂无订单业务样本 |
| 退款/售后分析 | 外部前置条件阻断 | 10% | 没有售后服务单与原因明细 |
| 评价 VOC | 待接口回归 | 20% | 有旧版方法线索，没有真实成功样本 |
| 流量/转化分析 | 待报表验收 | 10% | 无法仅靠订单和商品接口可靠计算 |
| 客服 VOC | 权限不足 | 0% | 需单独申请接口权限并评估敏感信息处理 |
| 竞品对标 | 不属于本店授权直接能力 | 0% | 需要市场/搜索/外部数据源 |
| 写操作 | 本次未测 | 0% | 库存写入、发货、订单备注、售后操作必须单独审批和验收 |

## 9. 推荐的落地架构

### 7.1 服务端数据链路

```text
Parse EcomAuth
  -> JD token provider（按 shop UID 取最新 token）
  -> JD SP-API signer（统一签名、超时、重试、限流）
  -> domain clients（product / sku / stock / order / after-sales / review / report）
  -> raw response audit（脱敏）
  -> normalized snapshot + incremental tables
  -> /api/domestic-voc/snapshot
  -> Angular DomesticDatasetService
```

### 7.2 建议新增的后端边界

不要继续让前端通过通用 GET 代理直接拼 JD 路径。建议在 JD 模块中增加：

- `JdTokenProvider`：按 shop UID 获取并自动刷新 token；
- `JdSpClient`：统一处理 URL、参数排序、MD5、请求头、超时和错误分类；
- `JdProductClient`：商品、SKU、商品详情、库存；
- `JdOrderClient`：订单列表、详情和物流只读能力；
- `JdAfterSalesClient`：售后服务单、退款和原因；
- `JdReviewClient`：评价分页和字段清洗；
- `JdReportClient`：报表定义、任务查询和数据下载；
- `JdSnapshotSync`：分页、增量窗口、断点、幂等和快照生成。

前端只访问统一后的 SaaS-VOC 数据，不接触 JD 签名参数或完整 token。

### 7.3 数据存储建议

至少拆分以下实体：

| 实体 | 关键字段 | 用途 |
|---|---|---|
| `jd_product` | shop UID、product ID、标题、类目、状态、raw hash、observedAt | 商品主数据 |
| `jd_sku` | shop UID、SKU ID、product ID、名称、状态、属性 | SKU 维度分析 |
| `jd_stock_snapshot` | SKU ID、仓库、可用库存、预占库存、采集时间 | 库存趋势和告警 |
| `jd_order` | 订单 ID、状态、金额、支付/完成时间、raw hash | 经营指标 |
| `jd_order_item` | 订单 ID、商品 ID、SKU、数量、成交金额 | 商品销量归因 |
| `jd_after_sales` | 售后单、订单、商品、类型、金额、原因、状态 | 退款风险 |
| `jd_review` | 评价 ID、商品 ID、星级、正文、时间、脱敏作者 | VOC 分析 |
| `jd_sync_cursor` | shop UID、domain、window、cursor、lastSuccessAt | 增量同步和断点 |

原始响应应保存 hash 或受控的脱敏原文，不应把地址、手机号、用户 PIN、聊天正文直接进入通用 VOC 快照。

## 10. 下一步测试与开通计划

### P0：商品域工程化验收

1. 用商品 ID `10026650610613` 复测 `getProduct`，记录可返回字段、空字段和字段类型；
2. 对 614 个商品做分页测试，确认最大 page size、重复数据和状态筛选；
3. 对 SKU 列表和库存接口做批量上限、空 SKU、无效 SKU、重复 SKU 测试；
4. 将成功响应转成 `DomesticProduct`、SKU 表和库存快照；
5. 加入 request_id、接口耗时、错误码和响应 hash 的脱敏审计。

### P1：订单与售后开通

1. 向京东确认当前应用是否必须从云鼎平台发起订单/售后调用；
2. 确认应用绑定的店铺类型、服务对象和订单/售后 API 权限包；
3. 前置条件满足后，先用最小字段调用订单列表；
4. 拿到真实订单号后再调用订单详情；
5. 用只读方式验证售后列表、售后详情和退款原因；
6. 验证时间窗口、分页、空数据、重复运行和数据脱敏。

### P1：评价接口

1. 确认评价 API 属于新版 SP-API 还是旧版 JOS 权限包；
2. 用当前 access token 复测评价列表，不以旧版方法“存在”推导为有权限；
3. 至少拿到一条本店真实评价，确认评价 ID、商品 ID、星级、正文和时间字段；
4. 做内容脱敏、重复评价去重和增量窗口回归；
5. 接入 `DomesticReview` 前区分本品与竞品，防止把竞品评论写成本品 VOC。

### P2：报表与经营指标

1. 按官方报表接口文档确认签名参数是否包含请求体、schema 和任务字段；
2. 先查询报表定义，再执行最小只读报表任务；
3. 验证日粒度的曝光、点击、访客、加购、订单、成交金额和退款字段；
4. 只有在同一统计口径和时间窗口下同时拿到分子/分母，才计算转化率、点击率和退款率；
5. 将“接口无数据”“店铺真实为零”“权限不足”分别建模。

## 11. 验收标准

### 连接层

- 任何业务接口请求前都从 Parse 读取最新授权记录；
- access token 过期前自动刷新，刷新失败有可定位错误；
- AppSecret、MasterKey、token 和敏感用户字段不进入前端、URL、构建产物日志和报告；
- 每个请求都有接口名、shop UID、request_id、状态码、错误码和耗时。

### 数据层

- 商品、SKU、库存分页可重复运行且不产生重复快照；
- 订单、售后、评价均有真实店铺样本后才标记为“可用”；
- 所有增量同步有时间窗口、游标或更新时间字段；
- 失败任务支持重试、断点续跑和幂等；
- 缺失字段使用 null/未接入状态，不使用 0 伪造经营结果。

### SaaS-VOC 层

- 商品详情页能够展示真实 JD 商品和 SKU；
- 库存告警不会混入 GMV/销量指标；
- 经营总览只使用已验证的订单、售后和报表口径；
- VOC 分析只使用真实评价正文，并正确拆分本品与竞品；
- 没有经过独立数据源验证时，不展示竞品价格、销量或市场排名。

## 12. 最终判断

本次授权已经证明 JD 连接不是“只有 token 但没有业务权限”：商品列表、SKU 和库存均已打通，足以启动第一阶段的本店商品资产同步。

但是，SaaS-VOC 的核心价值不是商品目录，而是“经营结果 + 售后原因 + 评价正文 + 趋势解释”。目前订单和售后受云鼎前置条件影响，评价和报表尚未形成成功样本，因而系统还不能宣称已经覆盖完整的京东经营分析或本店 VOC 闭环。

推荐的上线顺序是：

1. 先把商品/SKU/库存能力做成服务端同步和快照；
2. 同步推进云鼎/订单/售后开通；
3. 单独完成评价 API 的权限和字段验收；
4. 最后接入报表并校准经营口径；
5. 在上述四个数据域都有真实样本后，再把 `DomesticDataset` 从本地案例快照切换为生产数据。