京东店铺 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。即使这是为了模块自包含，构建产物也可能被读取或反编译，生产环境应改为：

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

3. 官方调用与签名规则

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

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

官方文档：

当前已验证的 MD5 规则：

收集 X-JOS-Access-Token、X-JOS-App-Key、X-JOS-Timestamp、路径参数、查询参数和请求体参数；
按参数名 ASCII 升序排列；
拼接为 key + value，不插入 &；
计算 MD5(AppSecret + 拼接结果 + AppSecret)；
将摘要转成大写；
时间戳使用毫秒；
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 是物理上不可分割的最小库存单元。当前商品详情接口把两者合并到一次调用中：

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

官方文档：

已确认的请求约束：

项目	规则
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，因此没有把商品详情接口标记为“真实成功”。

这两个问题应分开：

先恢复服务端对 EcomAuth 的读取凭证，确认不是 Parse MasterKey/部署配置变化；
再用已验证商品 ID 调用 scene=pop 的详情接口；
记录真实返回字段覆盖率，尤其是 productInfo、skuList、图片、价格、详情描述、类目和物流字段；
对同一商品分别验证 scene=pop 和错误场景，确认错误码归因；
将准确库存继续以 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 全部字段压缩成字符串：

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 服务端数据链路

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：商品域工程化验收

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

P1：订单与售后开通

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

P1：评价接口

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

P2：报表与经营指标

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

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 闭环。

推荐的上线顺序是：

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

JD-API-CONNECTION-ASSESSMENT-2026-08-15.md 34 KB Постоянная ссылка История Исходник