# Huawei Merccoupon Integration

> 商家券是华为支付为商户提供的电子优惠券解决方案，通过该产品实现商家优惠券创建、投放、领取、核销及券查询等管理操作，商家券优惠规则和玩法由商家自定义，商家可将自有营销体系的优惠券同步到华为服务分发平台流量（日日有礼、搜索、品专、支付成功页等）和商家自有流量进行发放和运营;商家券功能暂仅提供API接口功能，有开发意愿的商户或者服务商可使用API接口完成商家券创建、发放、领取、核销、券查询等全链路操作。

- Skill: `makerjackie/huawei-merccoupon-integration` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add makerjackie/huawei-merccoupon-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/makerjackie/huawei-merccoupon-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: makerjackie (https://skillmd.com/u/makerjackie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/makerjackie/huawei-merccoupon-integration

---


# 商家券服务接入指引

## 何时使用

当用户说"要接商家券"、"要接华为支付商家券"或"要接鸿蒙支付商家券服务"时，使用本技能帮助用户完成商家券接入。

本技能中，"华为支付""鸿蒙支付服务""HarmonyOS Payment Kit"默认视为同一类能力入口。

## 使用顺序

1. **确认场景**: 先确认业务路径（随机Code+华为平台发放、导入Code+华为平台发放、发放时指定Code+商户平台发放）
2. **查阅指南**: 阅读对应场景的接入指南了解完整流程
3. **获取代码**: 通过示例索引获取具体接口调用代码

常用入口：

- 场景与主题导航：[reference.md](reference.md)
- 示例入口：[examples.md](examples.md)

## 全局高优先级规则

> 以下规则适用于本技能全部能力和全部对话轮次，优先级高于局部规则。

1. **关键问题必须得到用户明确回答后才能继续。** 对业务场景、券码Code的使用方式等关键信息，严禁擅自猜测或补默认值。
2. **场景前置确认**：除简单知识问答外，优先确认当前属于哪种券码模式，再进入后续能力。
3. **分步确认协议**：需要帮用户分析、排障、改代码或执行操作时，必须遵循"先理解需求 -> 提议下一步 -> 征得同意 -> 收集信息 -> 执行前确认"。
4. **线上风险提示**：涉及生产环境、真实商户号、证书、公钥私钥、回调地址等内容时，必须先提示风险，再继续。
5. **资源优先原则**：优先从 `references/` 检索现有指南和示例代码；资源缺失时，才可结合官方文档和本技能规则补充最小示例。
6. **服务端商户模型先行**：只要涉及 Java/Spring Boot 等服务端预下单、回调或签名验签实现，必须先确认商户模型（直连商户 / 服务商 / 平台类商户）与业务场景；未确认前，不得擅自决定接口路径、请求字段或 `appId/mercNo/spAppId/spMercNo/subMercNo` 映射关系。
7. **SDK 可用性闸门**：当用户要求"优先官方 SDK / 必须使用官方 SDK"时，必须先验证依赖是否可下载、关键类是否可见、关键 API 是否可确认；若三者任一无法验证，不得伪造 SDK 直连实现，应退回"SDK 适配层 + HTTP 网关兜底"的结构并明确告知用户。
    - **用户已提供官方接入文档或官方样例工程时**：优先以文档/样例中的 Maven 坐标、`pom.xml`、`MercApiController` 等真实源码为准完成验证；只有在"已按官方路径仍无法完成三者验证"时，才允许降级到 HTTP 网关兜底，并在回复中明确写出降级原因与恢复条件。
    - **官方文档页为 SPA（抓取正文为空）时**：不要仅凭 HTML 外壳判断"无 SDK"；应改用官方样例仓库、`mvn dependency:get`、本地 `~/.m2` 产物、`javap` 反查类签名等方式完成验证。
8. **源码事实优先于文档**：服务端工程改造时，优先以 `src/main/java`、`src/main/resources` 等真实源码为准；`README.md`、`target/`、`build/`、metadata、历史产物只能作为线索，不能当作源码事实。

## 能力与路由

### 1. 接入路线判断
当用户只说“要接华为支付商家券”或“商家”时，先帮助其确认：

- 随机Code、导入Code，还是指定Code。
- Java SDK、自研 REST，还是其他服务端语言。

### 2. 示例代码检索

用户要代码时，不直接从零生成，先确认场景和端类型，再读取索引：
| 场景 | 券码模式 | 示例入口 |
|------|----------|----------|
| 随机Code+华为平台发放 | HWPAY_MODE | [接口索引](references/1-随机Code+华为平台发放/示例代码/接口索引.md) |
| 导入Code+华为平台发放 | MERCHANT_UPLOAD | [接口索引](references/2-导入Code+华为平台发放/示例代码/接口索引.md) |
| 发放时指定Code+商户平台发放 | MERCHANT_API | [接口索引](references/3-发放时指定Code+商户平台发放/示例代码/接口索引.md) |

输出代码时继续遵守：

- `orderStr` / `contractStr` 必须由服务端生成。

### 3. 服务端改代码前的最小确认

在 Java / Spring Boot 等服务端接入前，至少确认：

1. 商户模型是直连商户、服务商，还是平台类商户
2. 当前业务场景是哪种券码模式
3. 服务端语言与框架。
4. 是否要求优先官方 SDK

处理要求：

- 未确认商户模型前，不决定 `appId/mercNo` 或 `spAppId/spMercNo/subMercNo` 映射。
- 要求官方 SDK 时，先走 SDK 可用性闸门，再写实现。
- starter / 样例工程优先保证可编译、可替换、可配置。
- 新增依赖前先验证可解析，避免先写未解析 `import`。


### 4. 质量评估与排障

用户准备联调、测试、上线，或已经出现报错时：

- 只检查当前实际使用的模块。
- 验签失败、幂等缺失属于高优先级问题。
- 若服务端返回 `resultDesc` 这类字段校验报错，优先核对字段契约。

## 硬性红线

- 私钥不得出现在日志、公共仓库或对话明文示例中。
- 不得跳过回调验签。
- 不得在官方 SDK 不可验证时，伪造 SDK 直连实现、虚构类名、配置对象或方法签名。
- 不得在新增 Maven 依赖尚未验证可解析前，就先写入依赖耦合实现或提交带有未解析 `import` 的源码。
- 不得把 `README`、`target/`、`build/`、metadata 中出现的类或配置直接当作当前源码事实。
- 不得把 `MOCK` 验签、内存幂等、样例签名工具包装成“可直接上线的生产实现”。


## 输出建议模板

```markdown
## 结论
[一句话说明当前是否可接入、可联调、已定位问题或存在阻塞]

## 执行清单
- 已完成：
  - [item]
- 待完成：
  - [item]

## 风险与阻塞
- [风险项]

## 下一步
1. [最小可执行动作]
2. [下一步验证动作]
```

## 顶层入口

- [参考索引](reference.md) - 场景选择、规则说明
- [示例入口](examples.md) - 完整示例代码