docs: 记录商家客服 API 设计与计划

Author: binarywang

docs/superpowers/plans/2026-08-22-channel-merchant-kf.md

@@ -0,0 +1,45 @@
+# 视频号小店商家客服 API Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为 `weixin-java-channel` 增加商家客服媒体上传和消息发送 API。
+
+**Architecture:** 以独立的客服子服务封装两条官方 API，通过既有 `BaseWxChannelServiceImpl` 完成鉴权、JSON 请求与 multipart 上传。请求模型保持强类型，服务层测试使用可记录调用的测试替身，避免真实网络依赖。
+
+**Tech Stack:** Java 8、Maven、TestNG、Lombok、Jackson 注解。
+
+## Global Constraints
+
+- Java 8 兼容，不新增依赖。
+- API 路径固定为 `/channels/ec/commkf/cosupload` 和 `/channels/ec/commkf/sendmsg`。
+- 使用 TestNG，所有新增测试不使用真实微信凭据。
+
+---
+
+### Task 1: 请求与响应模型
+
+**Files:**
+- Create: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/kf/WxChannelKfCosUploadResponse.java`
+- Create: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/kf/WxChannelKfSendMsgParam.java`
+- Create: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/kf/WxChannelKfSendMsgResponse.java`
+- Test: `weixin-java-channel/src/test/java/me/chanjar/weixin/channel/bean/kf/WxChannelKfBeanTest.java`
+
+- [ ] Write JSON encode/decode tests for `request_id`, `open_id`, `msg_type`, `text.content`, `cos_url` and `msg_id`.
+- [ ] Run the test and verify it fails because the classes do not exist.
+- [ ] Add the minimal annotated model classes and nested message content types.
+- [ ] Run the test and verify it passes.
+
+### Task 2: 服务入口与请求执行
+
+**Files:**
+- Create: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/api/WxChannelKfService.java`
+- Create: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/api/impl/WxChannelKfServiceImpl.java`
+- Modify: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/api/WxChannelService.java`
+- Modify: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/api/impl/BaseWxChannelServiceImpl.java`
+- Modify: `weixin-java-channel/src/main/java/me/chanjar/weixin/channel/constant/WxChannelApiUrlConstants.java`
+- Test: `weixin-java-channel/src/test/java/me/chanjar/weixin/channel/api/impl/WxChannelKfServiceImplTest.java`
+
+- [ ] Write tests proving the service uses the documented URLs, uploads `file`, `open_id`, `msg_type`, decodes both responses, and caches `getKfService()`.
+- [ ] Run the test and verify it fails because the API is absent.
+- [ ] Add the minimal service API, implementation, constants and cached service entry point.
+- [ ] Run the focused tests and module test suite, then inspect `git diff --check`.

docs/superpowers/specs/2026-08-22-channel-merchant-kf-design.md

@@ -0,0 +1,18 @@
+# 视频号小店商家客服 API 设计
+
+## 目标
+
+实现 Issue #3991 所列的商家客服媒体上传与消息发送 API，并使调用入口、请求模型和响应解析与现有 `weixin-java-channel` 服务保持一致。
+
+## 设计
+
+- 在 `WxChannelService` 暴露 `getKfService()`，由 `BaseWxChannelServiceImpl` 缓存并懒加载 `WxChannelKfServiceImpl`。
+- `WxChannelKfService` 提供媒体上传（带文件名和便捷重载）以及接收强类型请求参数的消息发送方法。上传请求通过既有 `CommonUploadParam` 发送 multipart 数据。
+- 消息模型用 `@JsonProperty` 显式映射微信字段，支持 text、image、video、file、product_share 和 order_share 六类内容；响应继承项目既有基础响应。
+- API 常量使用官方文档确认的 `/channels/ec/commkf/cosupload` 和 `/channels/ec/commkf/sendmsg` 路径。
+
+## 质量边界
+
+- 保持 Java 8 兼容，不增加依赖，不变更现有公共 API。
+- 使用 TestNG 覆盖请求/响应 JSON 映射、服务 URL、上传表单字段及服务入口缓存；测试不依赖真实微信凭据。
+- PR 使用 `Closes #3991` 关联并关闭原始 Issue；旧 PR #4037 在新 PR 创建后以替代说明关闭。