huangyujie
/
qihang-ecom-erp-open
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(erp-open): 拼多多外部接口支持 pdd.goods.quantity.update 库存更新 

新增 POST /external/pdd/goods/quantity/update，封装 POP 调用与请求/响应模型；Controller 与日志脱敏沿用 goods 外部接口约定；补充 PddOpenApiSupport 对 quantity.update 响应解析。

Made-with: Cursor
This commit is contained in:
huangyujie 2026-03-30 14:46:14 +08:00
parent fd6b6e5cc1
commit bda4302e59
8 changed files with 328 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
api/erp-api/src/main/java/cn/qihangerp/erp/controller/ExternalPddGoodsController.java
View File

@ -2,11 +2,14 @@ package cn.qihangerp.erp.controller;
import cn.qihangerp.common.AjaxResult;
import cn.qihangerp.model.request.ExternalPddGoodsDetailRequest;
import cn.qihangerp.model.request.ExternalPddGoodsQuantityUpdateRequest;
import cn.qihangerp.model.vo.ExternalPddGoodsDetailResultVo;
import cn.qihangerp.model.vo.ExternalPddGoodsQuantityUpdateResultVo;
import cn.qihangerp.security.common.BaseController;
import cn.qihangerp.erp.config.ExternalGoodsApiLogProperties;
import cn.qihangerp.erp.support.ExternalGoodsRequestLogSupport;
import cn.qihangerp.service.external.ExternalPddGoodsDetailAppService;
import cn.qihangerp.service.external.ExternalPddGoodsQuantityUpdateAppService;
import lombok.AllArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.StringUtils;
@ -19,6 +22,7 @@ import org.springframework.web.bind.annotation.RestController;
* 拼多多专用外部接口（与 {@code /external/goods/upsert} 编排解耦）。
* <ul>
* <li>{@code POST /external/pdd/goods/detail} — {@code pdd.goods.detail.get}</li>
* <li>{@code POST /external/pdd/goods/quantity/update} — {@code pdd.goods.quantity.update}</li>
* </ul>
*/
@Slf4j
@ -28,6 +32,7 @@ import org.springframework.web.bind.annotation.RestController;
public class ExternalPddGoodsController extends BaseController {
private final ExternalPddGoodsDetailAppService externalPddGoodsDetailAppService;
private final ExternalPddGoodsQuantityUpdateAppService externalPddGoodsQuantityUpdateAppService;
private final ExternalGoodsApiLogProperties goodsApiLogProperties;
@PostMapping("/detail")
@ -52,4 +57,34 @@ public class ExternalPddGoodsController extends BaseController {
}
return AjaxResult.success(vo);
}
@PostMapping("/quantity/update")
public AjaxResult quantityUpdate(@RequestBody ExternalPddGoodsQuantityUpdateRequest req) {
if (goodsApiLogProperties.isLogFullRequest()) {
log.info("[external/pdd/goods/quantity/update] request={}",
ExternalGoodsRequestLogSupport.pddQuantityUpdateRequestJsonForLog(req));
}
if (req == null || req.getGoodsId() == null || req.getGoodsId() <= 0) {
return AjaxResult.error("参数错误：goodsId 不能为空且须为正数");
}
if (req.getSkuId() == null || req.getSkuId() <= 0) {
return AjaxResult.error("参数错误：skuId 不能为空且须为正数（拼多多 sku_id）");
}
if (req.getQuantity() == null || req.getQuantity() < 0) {
return AjaxResult.error("参数错误：quantity 不能为空且不能为负");
}
if (req.getPddPopAuth() == null) {
return AjaxResult.error("参数错误：pddPopAuth 不能为空");
}
var auth = req.getPddPopAuth();
if (!StringUtils.hasText(auth.getAppKey()) || !StringUtils.hasText(auth.getAppSecret())
|| !StringUtils.hasText(auth.getAccessToken())) {
return AjaxResult.error("参数错误：pddPopAuth 需提供 appKey、appSecret、accessToken");
}
ExternalPddGoodsQuantityUpdateResultVo vo = externalPddGoodsQuantityUpdateAppService.updateQuantity(req);
if (!Boolean.TRUE.equals(vo.getPopBizSuccess())) {
return AjaxResult.error(StringUtils.hasText(vo.getMessage()) ? vo.getMessage() : "pdd.goods.quantity.update 失败");
}
return AjaxResult.success(vo);
}
}

25
api/erp-api/src/main/java/cn/qihangerp/erp/support/ExternalGoodsRequestLogSupport.java
View File

@ -2,6 +2,7 @@ package cn.qihangerp.erp.support;
import cn.qihangerp.model.request.ExternalGoodsUpsertRequest;
import cn.qihangerp.model.request.ExternalPddGoodsDetailRequest;
import cn.qihangerp.model.request.ExternalPddGoodsQuantityUpdateRequest;
import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import org.springframework.util.StringUtils;
@ -17,8 +18,27 @@ public final class ExternalGoodsRequestLogSupport {
}
/**
* 序列化为 JSON 并对 {@link ExternalGoodsUpsertRequest#getPddPopAuth()} 脱敏（不修改入参对象）。
* {@link ExternalPddGoodsQuantityUpdateRequest} 脱敏日志（不修改入参）。
*/
public static String pddQuantityUpdateRequestJsonForLog(ExternalPddGoodsQuantityUpdateRequest req) {
if (req == null) {
return "null";
}
try {
JSONObject root = JSON.parseObject(JSON.toJSONString(req));
if (root == null) {
return "{}";
}
JSONObject auth = root.getJSONObject("pddPopAuth");
if (auth != null && !auth.isEmpty()) {
maskPddPopAuth(auth);
}
return root.toJSONString();
} catch (Exception e) {
return "{\"_logSanitizeError\":true}";
}
}
/**
* {@link ExternalPddGoodsDetailRequest} 脱敏日志（不修改入参）。
*/
@ -41,6 +61,9 @@ public final class ExternalGoodsRequestLogSupport {
}
}
/**
* 序列化为 JSON 并对 {@link ExternalGoodsUpsertRequest#getPddPopAuth()} 脱敏（不修改入参对象）。
*/
public static String upsertRequestJsonForLog(ExternalGoodsUpsertRequest req) {
if (req == null) {
return "null";

35
model/src/main/java/cn/qihangerp/model/request/ExternalPddGoodsQuantityUpdateRequest.java Normal file
View File

@ -0,0 +1,35 @@
package cn.qihangerp.model.request;
import lombok.Data;
/**
* {@code POST /external/pdd/goods/quantity/update}：调用拼多多 {@code pdd.goods.quantity.update} 更新 SKU 库存。
* <p>凭证形态与 {@link ExternalGoodsUpsertRequest#getPddPopAuth()} 一致。</p>
*/
@Data
public class ExternalPddGoodsQuantityUpdateRequest {
/** 拼多多商品 {@code goods_id} */
private Long goodsId;
/** 拼多多 {@code sku_id}（与 POP 文档一致） */
private Long skuId;
/** 可选，商家外部编码 {@code outer_id} */
private String outerId;
/** 库存数量 */
private Long quantity;
/**
* 更新类型，参见拼多多开放平台；常见 {@code 1}（与官方示例一致）。
*/
private Integer updateType;
/**
* 是否使用 {@code force_update}（默认 {@code true}，与官方示例一致）。
*/
private Boolean forceUpdate;
private ExternalGoodsUpsertRequest.PddPopAuth pddPopAuth;
}

31
model/src/main/java/cn/qihangerp/model/vo/ExternalPddGoodsQuantityUpdateResultVo.java Normal file
View File

@ -0,0 +1,31 @@
package cn.qihangerp.model.vo;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.io.Serializable;
/**
* {@code /external/pdd/goods/quantity/update} 返回：含 POP 网关原始 JSON 与业务 {@code is_success} 解析结果。
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ExternalPddGoodsQuantityUpdateResultVo implements Serializable {
/**
* 整体是否成功：无 {@code error_response} 且 {@code goods_quantity_update_response.is_success=true}。
*/
private Boolean popBizSuccess;
/** 与响应体 {@code goods_quantity_update_response.is_success} 一致（解析失败时为 false） */
private Boolean quantityUpdateSuccess;
private String message;
/** 拼多多网关响应全文 */
private String popResponseBody;
}

12
service/src/main/java/cn/qihangerp/service/external/ExternalPddGoodsQuantityUpdateAppService.java vendored Normal file
View File

@ -0,0 +1,12 @@
package cn.qihangerp.service.external;
import cn.qihangerp.model.request.ExternalPddGoodsQuantityUpdateRequest;
import cn.qihangerp.model.vo.ExternalPddGoodsQuantityUpdateResultVo;
/**
* 拼多多库存更新（{@code pdd.goods.quantity.update}）。
*/
public interface ExternalPddGoodsQuantityUpdateAppService {
ExternalPddGoodsQuantityUpdateResultVo updateQuantity(ExternalPddGoodsQuantityUpdateRequest req);
}

121
service/src/main/java/cn/qihangerp/service/external/impl/ExternalPddGoodsQuantityUpdateAppServiceImpl.java vendored Normal file
View File

@ -0,0 +1,121 @@
package cn.qihangerp.service.external.impl;
import cn.qihangerp.model.request.ExternalGoodsUpsertRequest;
import cn.qihangerp.model.request.ExternalPddGoodsQuantityUpdateRequest;
import cn.qihangerp.model.vo.ExternalPddGoodsQuantityUpdateResultVo;
import cn.qihangerp.service.external.ExternalPddGoodsQuantityUpdateAppService;
import cn.qihangerp.service.external.pdd.ExternalPddProperties;
import cn.qihangerp.service.external.pdd.PddOpenApiSupport;
import cn.qihangerp.service.external.pdd.PddPopClient;
import cn.qihangerp.service.external.shop.PddShopCredential;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;
/**
* @author guochengyu
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class ExternalPddGoodsQuantityUpdateAppServiceImpl implements ExternalPddGoodsQuantityUpdateAppService {
private final ExternalPddProperties props;
private final PddPopClient pddPopClient;
@Override
public ExternalPddGoodsQuantityUpdateResultVo updateQuantity(ExternalPddGoodsQuantityUpdateRequest req) {
if (req == null || req.getGoodsId() == null || req.getGoodsId() <= 0) {
return fail("goodsId 无效", null, false);
}
if (req.getSkuId() == null || req.getSkuId() <= 0) {
return fail("skuId 无效：须传拼多多 sku_id", null, false);
}
if (req.getQuantity() == null || req.getQuantity() < 0) {
return fail("quantity 无效：不能为空且不能为负", null, false);
}
int updateType = req.getUpdateType() != null ? req.getUpdateType() : 1;
boolean forceUpdate = req.getForceUpdate() == null || Boolean.TRUE.equals(req.getForceUpdate());
PddShopCredential cred = resolveCredential(req);
if (cred == null || !StringUtils.hasText(cred.getAppKey()) || !StringUtils.hasText(cred.getAppSecret())
|| !StringUtils.hasText(cred.getAccessToken())) {
return fail("pddPopAuth 不完整：需 appKey、appSecret、accessToken", null, false);
}
String gateway = StringUtils.hasText(cred.getGatewayUrl()) ? cred.getGatewayUrl() : props.getGatewayUrl();
if (!StringUtils.hasText(gateway)) {
return fail("未配置 POP gatewayUrl（请求体或 external.pdd.gateway-url）", null, false);
}
try {
var biz = PddOpenApiSupport.goodsQuantityUpdateTopLevelParams(
req.getGoodsId(),
req.getSkuId(),
req.getOuterId(),
req.getQuantity(),
updateType,
forceUpdate);
String raw = pddPopClient.invokeTopLevelBiz(
gateway,
cred.getAppKey(),
cred.getAppSecret(),
cred.getAccessToken(),
"pdd.goods.quantity.update",
biz);
boolean noPopError = !PddOpenApiSupport.isError(raw);
boolean innerOk = PddOpenApiSupport.parseGoodsQuantityUpdateIsSuccess(raw);
boolean ok = noPopError && innerOk;
String msg;
if (!noPopError) {
msg = "pdd.goods.quantity.update POP错误: " + PddOpenApiSupport.formatError(raw);
} else if (!innerOk) {
msg = "pdd.goods.quantity.update 业务失败: goods_quantity_update_response.is_success=false 或响应缺字段";
} else {
msg = "pdd.goods.quantity.update 成功";
}
return ExternalPddGoodsQuantityUpdateResultVo.builder()
.popBizSuccess(ok)
.quantityUpdateSuccess(innerOk)
.message(msg)
.popResponseBody(raw)
.build();
} catch (Exception e) {
log.warn("[PDD] pdd.goods.quantity.update exception goodsId={} skuId={} err={}",
req.getGoodsId(), req.getSkuId(), e.getMessage(), e);
return fail(e.getMessage(), null, false);
}
}
private static ExternalPddGoodsQuantityUpdateResultVo fail(String message, String raw, boolean innerOk) {
return ExternalPddGoodsQuantityUpdateResultVo.builder()
.popBizSuccess(false)
.quantityUpdateSuccess(innerOk)
.message(message)
.popResponseBody(raw)
.build();
}
private static PddShopCredential resolveCredential(ExternalPddGoodsQuantityUpdateRequest req) {
if (req == null || req.getPddPopAuth() == null) {
return null;
}
ExternalGoodsUpsertRequest.PddPopAuth a = req.getPddPopAuth();
PddShopCredential c = new PddShopCredential();
c.setAppKey(trimToNull(a.getAppKey()));
c.setAppSecret(trimToNull(a.getAppSecret()));
c.setAccessToken(trimToNull(a.getAccessToken()));
if (StringUtils.hasText(a.getGatewayUrl())) {
c.setGatewayUrl(a.getGatewayUrl().trim());
}
c.setSource("REQUEST");
return c;
}
private static String trimToNull(String s) {
if (!StringUtils.hasText(s)) {
return null;
}
return s.trim();
}
}

55
service/src/main/java/cn/qihangerp/service/external/pdd/PddOpenApiSupport.java vendored
View File

@ -51,6 +51,61 @@ public final class PddOpenApiSupport {
return m;
}
/**
* {@code pdd.goods.quantity.update} 表单顶层参数（与 POP 官方 curl / Java SDK 一致：{@code goods_id}、{@code sku_id}、{@code quantity}、
* {@code update_type}、{@code force_update}、可选 {@code outer_id}）。
*/
public static Map<String, String> goodsQuantityUpdateTopLevelParams(long goodsId, Long skuId, String outerId,
long quantity, int updateType, boolean forceUpdate) {
if (goodsId <= 0) {
throw new IllegalArgumentException("goods_id 必须为正数: " + goodsId);
}
if (quantity < 0) {
throw new IllegalArgumentException("quantity 不能为负: " + quantity);
}
Map<String, String> m = new LinkedHashMap<>();
m.put("goods_id", String.valueOf(goodsId));
if (skuId != null && skuId > 0) {
m.put("sku_id", String.valueOf(skuId));
}
if (StringUtils.hasText(outerId)) {
m.put("outer_id", outerId.trim());
}
m.put("quantity", String.valueOf(quantity));
m.put("update_type", String.valueOf(updateType));
m.put("force_update", forceUpdate ? "true" : "false");
return m;
}
/**
* 解析 {@code pdd.goods.quantity.update} 响应中的 {@code goods_quantity_update_response.is_success}。
*/
public static boolean parseGoodsQuantityUpdateIsSuccess(String raw) {
if (!StringUtils.hasText(raw)) {
return false;
}
try {
JSONObject root = JSON.parseObject(raw);
if (root == null) {
return false;
}
JSONObject resp = root.getJSONObject("goods_quantity_update_response");
if (resp == null) {
return false;
}
Object v = resp.get("is_success");
if (v instanceof Boolean b) {
return b;
}
if (v != null) {
return "true".equalsIgnoreCase(String.valueOf(v).trim());
}
return false;
} catch (Exception e) {
return false;
}
}
/**
* 从 {@code pdd.goods.add} 原始响应 JSON 中解析 {@code goods_add_response.goods_id}（拼多多侧商品 ID）。
*/

16
service/src/main/java/cn/qihangerp/service/external/pdd/PddPopClient.java vendored
View File

@ -22,7 +22,7 @@ import java.util.Map;
* <ul>
* <li>{@link #invokeGoodsAdd} / {@link #invokeGoodsInformationUpdate} — {@code pdd.goods.add}、{@code pdd.goods.information.update}：
* 根 JSON 展开为表单顶层（与官方 curl / Java SDK 一致），<b>无</b> {@code param_json}、<b>无</b> {@code version}</li>
* <li>{@link #invokeTopLevelBiz} — 如 {@code pdd.goods.cat.rule.get} 的 {@code cat_id}/{@code goods_id} 等顶层字段</li>
* <li>{@link #invokeTopLevelBiz} — 如 {@code pdd.goods.cat.rule.get}、{@code pdd.goods.quantity.update} 的顶层字段</li>
* <li>{@link #invokeGoodsImageUpload} — {@code pdd.goods.image.upload}：urlencoded，{@code image} 为 {@code data:image/*;base64,} + Base64</li>
* <li>{@link #invoke} — 仅当接口要求整包 {@code param_json} 时使用（少数场景）</li>
* </ul>
@ -240,6 +240,20 @@ public class PddPopClient {
}
return raw;
}
if ("pdd.goods.quantity.update".equals(type)) {
String snippet = PddOpenApiSupport.snippet(raw, 800);
if (!httpOk || popBizError) {
String errSummary = popBizError ? PddOpenApiSupport.formatError(raw) : "";
log.warn("PDD_POP api={} host={} clientId={} httpStatus={} durationMs={} popBizError={} errSummary={} paramPayloadSnippet={} bodySnippet={}",
type, host, clientMasked, httpStatus, durationMs, popBizError, errSummary,
paramLogSnippet != null ? paramLogSnippet : "", snippet);
} else {
log.info("PDD_POP api={} host={} clientId={} httpStatus={} durationMs={} quantityOk={} bodySnippet={}",
type, host, clientMasked, httpStatus, durationMs,
PddOpenApiSupport.parseGoodsQuantityUpdateIsSuccess(raw), snippet);
}
return raw;
}
String snippet = PddOpenApiSupport.snippet(raw, 600);
if (!httpOk || popBizError) {
String errSummary = popBizError ? PddOpenApiSupport.formatError(raw) : "";