添加 README 文档

README.md

@@ -0,0 +1,555 @@
+## 文档概述
+- 接口总数：25个
+- API版本：linkedmall/2023-09-30
+- RegionId：cn-zhangjiakou（华北3 张家口）
+- Endpoint：`linkedmall.cn-zhangjiakou.aliyuncs.com`
+- HTTP基础Path前缀：`/opensaas-s2b/opensaas-s2b-biz-trade/v2`
+- 签名类型：ROA签名，SDK内部自动处理
+- 金额单位：分（整数，long/int64）
+- 区域编码divisionCode：必须使用五级（乡镇街道级别）编码
+
+## 认证与安全
+- 使用RAM子账号AccessKey（AccessKeyId / AccessKeySecret），禁止主账号AK
+- 授予LinkedMall对应OpenAPI最小权限
+- 业务前置资源：purchaserId（采购方ID）、shopId（店铺ID），由LinkedMall控制台分配
+- 签名类型为ROA签名，SDK内部自动处理，业务无需实现签名算法
+- 使用通用OpenApiClient（darabonba-openapi/v2）发起ROA调用
+
+## 公共返回结构体
+所有接口返回外层统一格式：
+```go
+type CommonResponse struct {
+    RequestId  string      `json:"RequestId"`
+    Success    bool        `json:"Success"`
+    Code       string      `json:"Code"`
+    Message    string      `json:"Message"`
+    SubCode    string      `json:"SubCode"`
+    SubMessage string      `json:"SubMessage"`
+    Data       interface{} `json:"Data"` // 业务数据，不同接口Data内部结构不同
+}
+```
+公共Code枚举：
+- `SUCCESS`：业务调用成功
+- 其他：业务失败，看SubCode、SubMessage定位原因
+> 注意：HTTP 200 不代表业务成功，必须判断 `Success==true`
+
+## SDK客户端初始化
+```go
+package main
+
+import (
+    "github.com/alibabacloud-go/darabonba-openapi/v2/client"
+    "github.com/alibabacloud-go/tea/v2"
+)
+
+func NewLinkedMallClient(accessKeyId, accessKeySecret string) (*client.Client, error) {
+    config := &client.Config{
+        AccessKeyId:     tea.String(accessKeyId),
+        AccessKeySecret: tea.String(accessKeySecret),
+        RegionId:        tea.String("cn-zhangjiakou"),
+        Endpoint:        tea.String("linkedmall.cn-zhangjiakou.aliyuncs.com"),
+        ReadTimeout:     tea.Int(30000),
+        ConnectTimeout:  tea.Int(10000),
+    }
+    return client.NewClient(config)
+}
+```
+调用示例：
+```go
+cli, err := NewLinkedMallClient("AKxxx", "SKxxx")
+resp, err := cli.RoaRequest(
+    tea.String("POST"),
+    tea.String("/opensaas-s2b/opensaas-s2b-biz-trade/v2/xxx"),
+    nil, // query map[string]*string
+    bodyObj, // post json body
+    nil, // header
+)
+```
+
+## 接口列表
+
+### 接口 1：ListPurchaserShops 获取采购方店铺列表
+- 路径：`/purchaser-shops`
+- 方法：GET
+- 描述：分页获取采购方店铺列表
+
+#### 请求参数（Query）
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PageNum | int | 否 | 页码，默认1 |
+| PageSize | int | 否 | 每页条数，最大100 |
+
+#### 响应Data结构体
+```go
+type ListPurchaserShopsRespData struct {
+    Total      int64              `json:"Total"`
+    PageNum    int                `json:"PageNum"`
+    PageSize   int                `json:"PageSize"`
+    ShopList   []PurchaserShopItem `json:"ShopList"`
+}
+type PurchaserShopItem struct {
+    ShopId      string `json:"ShopId"`
+    PurchaserId string `json:"PurchaserId"`
+    ShopName    string `json:"ShopName"`
+    ShopStatus  string `json:"ShopStatus"`
+}
+```
+
+### 接口 2：GetPurchaserShop 获取采购方店铺详情
+- 路径：`/purchaser-shops/{ShopId}`
+- 方法：GET
+- 描述：获取单个采购店铺详情
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ShopId | string | Path | 是 | 店铺ID |
+
+#### 响应Data结构体
+```go
+type GetPurchaserShopRespData struct {
+    ShopId      string `json:"ShopId"`
+    PurchaserId string `json:"PurchaserId"`
+    ShopName    string `json:"ShopName"`
+    ShopStatus  string `json:"ShopStatus"`
+    ContactInfo string `json:"ContactInfo"`
+}
+```
+
+### 接口 3：ListSelectionProducts 查询选品池商品列表
+- 路径：`/selection-products`
+- 方法：GET
+- 描述：分页查询选品池商品列表
+
+#### 请求参数（Query）
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PageNum | int | 否 | 页码 |
+| PageSize | int | 否 | 最大100 |
+| PurchaserId | string | 是 | 采购方ID |
+
+#### 响应Data结构体
+```go
+type ListSelectionProductsRespData struct {
+    Total       int64                  `json:"Total"`
+    PageNum     int                    `json:"PageNum"`
+    PageSize    int                    `json:"PageSize"`
+    ProductList []SelectionProductItem `json:"ProductList"`
+}
+type SelectionProductItem struct {
+    ProductId  string `json:"ProductId"`
+    Title      string `json:"Title"`
+    MainImage  string `json:"MainImage"`
+    BrandName  string `json:"BrandName"`
+    CategoryId string `json:"CategoryId"`
+}
+```
+
+### 接口 4：GetSelectionProduct 查询选品池商品详情
+- 路径：`/selection-products/{ProductId}`
+- 方法：GET
+- 描述：查询单个商品详情，支持传入divisionCode校验区域可售库存
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ProductId | string | Path | 是 | 商品ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+| DivisionCode | string | Query | 否 | 五级乡镇区域编码，传后返回该区域可售状态 |
+
+#### 响应Data结构体
+```go
+type GetSelectionProductRespData struct {
+    ProductId     string            `json:"ProductId"`
+    Title         string            `json:"Title"`
+    MainImage     string            `json:"MainImage"`
+    Images        []string          `json:"Images"`
+    BrandName     string            `json:"BrandName"`
+    CategoryId    string            `json:"CategoryId"`
+    Desc          string            `json:"Desc"`
+    SkuList       []SelectionSkuItem `json:"SkuList"`
+    CanSale       bool              `json:"CanSale"`       // 传入divisionCode才有效，该区域是否可售
+    StockQuantity int64             `json:"StockQuantity"`
+}
+type SelectionSkuItem struct {
+    SkuId         string `json:"SkuId"`
+    SkuSpec       string `json:"SkuSpec"`
+    SalePrice     int64  `json:"SalePrice"`     // 单位分
+    MarketPrice   int64  `json:"MarketPrice"`
+    StockQuantity int64  `json:"StockQuantity"`
+}
+```
+
+### 接口 5：GetSelectionProductSaleInfo 查询选品池商品销售信息
+- 路径：`/selection-products/{ProductId}/sale-info`
+- 方法：GET
+- 描述：查询商品可售、价格库存快照
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| ProductId | string | Path | 是 | 商品ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+| DivisionCode | string | Query | 否 | 五级乡镇区域编码 |
+
+### 接口 6：ListSelectionProductSaleInfos 批量查询商品销售信息
+- 路径：`/selection-products:batch-sale-info`
+- 方法：POST
+- 描述：批量查询商品销售信息
+
+#### 请求Body
+```json
+{
+  "PurchaserId": "xxx",
+  "ProductIdList": ["p1","p2"],
+  "DivisionCode": "五级编码"
+}
+```
+
+### 接口 7：ListSelectionSkuSaleInfos 批量SKU销售信息
+- 路径：`/selection-skus:batch-sale-info`
+- 方法：POST
+- 描述：批量查询SKU销售信息
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| SkuIdList | []string | 是 | SKU ID列表 |
+| DivisionCode | string | 否 | 五级乡镇区域编码 |
+
+### 接口 8：ListCategories 查询类目列表
+- 路径：`/categories`
+- 方法：GET
+- 描述：查询类目列表
+
+#### 请求参数（Query）
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| ParentCategoryId | string | 否 | 父类目ID（不传查一级类目） |
+
+### 接口 9：SearchProducts 搜索选品池商品
+- 路径：`/selection-products:search`
+- 方法：POST
+- 描述：搜索选品池商品
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| Keyword | string | 否 | 关键词 |
+| CategoryId | string | 否 | 类目ID |
+| PageNum | int | 否 | 页码 |
+| PageSize | int | 否 | 每页条数 |
+| PurchaserId | string | 是 | 采购方ID |
+
+### 接口 10：SelectionGroupAddProduct 选品池商品入库
+- 路径：`/selection-group/products:add`
+- 方法：POST
+- 描述：选品池商品入库
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| ShopId | string | 是 | 店铺ID |
+| ProductIdList | []string | 是 | 商品ID列表 |
+
+### 接口 11：SelectionGroupRemoveProduct 选品池商品出库
+- 路径：`/selection-group/products:remove`
+- 方法：POST
+- 描述：选品池商品出库
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| ShopId | string | 是 | 店铺ID |
+| ProductIdList | []string | 是 | 商品ID列表 |
+
+### 接口 12：RenderPurchaseOrder 采购单渲染（下单预校验）
+- 路径：`/purchase-orders:render`
+- 方法：POST
+- 描述：下单前必须调用，获取实时价格、校验商品是否可售
+
+#### 请求Body
+```go
+type RenderPurchaseOrderReq struct {
+    PurchaserId  string          `json:"PurchaserId"`
+    ShopId       string          `json:"ShopId"`
+    DivisionCode string          `json:"DivisionCode"` // 五级乡镇编码
+    ItemList     []RenderOrderItem `json:"ItemList"`
+    ReceiverInfo ReceiverInfo    `json:"ReceiverInfo"`
+}
+type RenderOrderItem struct {
+    SkuId    string `json:"SkuId"`
+    Quantity int64  `json:"Quantity"`
+}
+type ReceiverInfo struct {
+    ReceiverName  string `json:"ReceiverName"`
+    ReceiverPhone string `json:"ReceiverPhone"`
+    ProvinceCode  string `json:"ProvinceCode"`
+    CityCode      string `json:"CityCode"`
+    DistrictCode  string `json:"DistrictCode"`
+    TownCode      string `json:"TownCode"`
+    DetailAddress string `json:"DetailAddress"`
+}
+```
+#### 响应Data
+渲染后的价格、商品校验结果、不可售原因、预估运费。
+
+### 接口 13：SplitPurchaseOrder 采购单渲染并拆单
+- 路径：`/purchase-orders:split-render`
+- 方法：POST
+- 描述：采购单渲染并拆单，返回拆成多份子单结构
+
+#### 请求Body
+结构和RenderPurchaseOrderReq完全一致
+
+#### 响应Data
+返回拆成多份子单结构，用于前端展示，拆单结果用于创建采购单入参。
+
+### 接口 14：CreatePurchaseOrder 创建采购单【异步】
+- 路径：`/purchase-orders`
+- 方法：POST
+- 描述：⚠️重要：接口只返回采购单号，不代表下单成功，必须等待回调通知，再查询订单接口
+
+#### 请求Body
+```go
+type CreatePurchaseOrderReq struct {
+    PurchaserId          string              `json:"PurchaserId"`
+    ShopId               string              `json:"ShopId"`
+    OuterPurchaseOrderId string              `json:"OuterPurchaseOrderId"` // 外部业务唯一单号，幂等
+    DivisionCode         string              `json:"DivisionCode"`
+    ReceiverInfo         ReceiverInfo        `json:"ReceiverInfo"`
+    SubOrderList         []CreateSubOrderItem `json:"SubOrderList"` // SplitPurchaseOrder返回的子单
+}
+type CreateSubOrderItem struct {
+    SkuId    string `json:"SkuId"`
+    Quantity int64  `json:"Quantity"`
+}
+```
+#### 响应Data结构体
+```go
+type CreatePurchaseOrderRespData struct {
+    PurchaseOrderId string `json:"PurchaseOrderId"` // 阿里云采购单号
+}
+```
+
+### 接口 15：GetPurchaseOrderStatus 获取采购单状态
+- 路径：`/purchase-orders/{PurchaseOrderId}/status`
+- 方法：GET
+- 描述：获取采购单状态
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| PurchaseOrderId | string | Path | 是 | 采购单ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+
+#### 响应Data
+采购单状态枚举：INIT、PROCESS、SUCCESS、FAIL、CLOSED
+
+### 接口 16：GetOrder 获取订单详情
+- 路径：`/orders/{OrderId}`
+- 方法：GET
+- 描述：获取订单详情
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| OrderId | string | Path | 是 | 订单ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+
+#### 响应Data
+订单主信息、商品明细、实付金额、状态、收货信息
+
+### 接口 17：QueryOrders 查询订单列表
+- 路径：`/orders`
+- 方法：GET
+- 描述：查询订单列表
+
+#### 请求参数（Query）
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| PurchaseOrderId | string | 否 | 采购单ID |
+| PageNum | int | 否 | 页码 |
+| PageSize | int | 否 | 每页条数 |
+| StartTime | string | 否 | 开始时间 |
+| EndTime | string | 否 | 结束时间 |
+
+### 接口 18：ListLogisticsOrders 查询订单物流信息
+- 路径：`/orders/{OrderId}/logistics`
+- 方法：GET
+- 描述：查询订单物流信息
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| OrderId | string | Path | 是 | 订单ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+
+#### 响应Data
+运单号、物流公司、物流轨迹数组
+
+### 接口 19：ConfirmDisburse 确认收货
+- 路径：`/orders/{OrderId}:confirm-disburse`
+- 方法：POST
+- 描述：确认收货
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| OrderId | string | Path | 是 | 订单ID |
+
+#### 请求Body
+```json
+{"PurchaserId":"xxx"}
+```
+
+### 接口 20：RenderRefundOrder 售后渲染预校验
+- 路径：`/refund-orders:render`
+- 方法：POST
+- 描述：售后渲染预校验
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| OrderId | string | 是 | 订单ID |
+| OrderItemId | string | 是 | 订单商品明细ID |
+| RefundQuantity | int64 | 是 | 退款数量 |
+| RefundType | string | 是 | 退款类型（仅退款/退货退款） |
+
+### 接口 21：CreateRefundOrder 创建售后单
+- 路径：`/refund-orders`
+- 方法：POST
+- 描述：创建售后单
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| OrderId | string | 是 | 订单ID |
+| OrderItemId | string | 是 | 订单商品明细ID |
+| RefundQuantity | int64 | 是 | 退款数量 |
+| RefundAmount | int64 | 是 | 退款金额（单位分） |
+| RefundType | string | 是 | 退款类型 |
+| RefundReason | string | 是 | 退款原因 |
+| OuterRefundNo | string | 是 | 外部售后单号 |
+
+### 接口 22：CancelRefundOrder 取消售后单
+- 路径：`/refund-orders/{RefundOrderId}:cancel`
+- 方法：POST
+- 描述：取消售后单
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| RefundOrderId | string | Path | 是 | 售后单ID |
+
+#### 请求Body
+```json
+{"PurchaserId":"xxx"}
+```
+
+### 接口 23：GetRefundOrder 获取售后单详情
+- 路径：`/refund-orders/{RefundOrderId}`
+- 方法：GET
+- 描述：获取售后单详情
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| RefundOrderId | string | Path | 是 | 售后单ID |
+| PurchaserId | string | Query | 是 | 采购方ID |
+
+### 接口 24：CreateGoodsShippingNotice 回填退货物流运单
+- 路径：`/refund-orders/{RefundOrderId}:fill-logistics`
+- 方法：POST
+- 描述：回填退货物流运单
+
+#### 请求参数
+| 参数名 | 类型 | 位置 | 必填 | 说明 |
+|--------|------|------|------|------|
+| RefundOrderId | string | Path | 是 | 售后单ID |
+
+#### 请求Body参数
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| PurchaserId | string | 是 | 采购方ID |
+| LogisticsCompany | string | 是 | 物流公司 |
+| TrackingNumber | string | 是 | 运单号 |
+
+### 接口 25：QueryChildDivisionCode 查询子区域编码
+- 路径：`/divisions:children`
+- 方法：GET
+- 描述：查询子区域编码，不传返回省级；传入省返回市，传入市返回区，传入区返回乡镇（五级）
+
+#### 请求参数（Query）
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| ParentDivisionCode | string | 否 | 父区域编码 |
+
+#### 响应Data
+DivisionCode列表、名称、层级；下单、商品可售校验必须拿到乡镇级DivisionCode
+
+## 错误码
+| 错误码 | 说明 | 处理建议 |
+|--------|------|----------|
+| ShopTypeInvalid | SKU属于经销集采店铺，不可下单 | 过滤SKU |
+| SkuPriceUnique | SKU价格非最新 | 重新调用RenderPurchaseOrder获取最新价格再下单 |
+| PurchaseOrderNotFound | 采购单号不存在 | 核对入参PurchaseOrderId |
+| RefundNumberMustLessThanOrder | 退款数量大于订单商品数量 | 修正退款数量 |
+| RefundAmountMustLessThanOrder | 退款金额大于实付金额 | 修正退款金额 |
+| HasNoPrivilege | RAM无接口权限 | 检查RAM授权策略 |
+| OrderNotFound | 订单ID不存在 | 核对OrderId |
+| ShopNotFind | 店铺不存在 | 核对ShopId/PurchaserId |
+| SavePurchaseOrderError | 保存采购单服务端异常 | 短间隔重试 |
+| OuterPurchaseOrderIdExist | 外部业务单号重复 | 更换OuterPurchaseOrderId，做好幂等 |
+
+## 回调通知
+### 消息回调（异步通知）规范
+CreatePurchaseOrder创建采购单后，阿里云主动POST回调业务配置的回调地址。
+
+1. 请求方式：POST，Content-Type: application/json
+2. 业务侧需要返回 `{"success":true}` 告知阿里云消费成功；否则阿里云会重试推送。
+3. 回调Body公共字段：
+```json
+{
+  "EventCode": "PURCHASE_ORDER_CHANGE",
+  "PurchaseOrderId": "xxx",
+  "OrderIdList": ["附属真实订单ID数组"],
+  "Status": "SUCCESS/FAIL",
+  "RequestId": "xxx"
+}
+```
+EventCode枚举：
+- PURCHASE_ORDER_CHANGE：采购单状态变更
+- ORDER_STATUS_CHANGE：订单状态变更
+- REFUND_ORDER_CHANGE：售后单变更
+
+业务处理逻辑：收到回调后，调用对应查询接口拉取最新业务数据做本地状态同步。
+
+## 完整业务调用流程
+1. 调用 `QueryChildDivisionCode` 获取五级乡镇divisionCode（收货地址对应的区域编码）
+2. 调用 `ListSelectionProducts` / `SearchProducts` 获取选品池商品SkuId
+3. 调用 `RenderPurchaseOrder` 预渲染校验商品可售、价格
+4. 调用 `SplitPurchaseOrder` 获取拆单结果
+5. 调用 `CreatePurchaseOrder`，传入外部唯一业务单号OuterPurchaseOrderId，拿到PurchaseOrderId
+6. **等待阿里云消息回调通知**
+7. 回调收到事件，调用`GetPurchaseOrderStatus`看采购单状态；拿到附属OrderId调用`GetOrder`同步订单入库本地库
+8. 后续：查物流、确认收货；产生售后调用售后接口
+
+> ❗禁止：CreatePurchaseOrder同步返回成功直接标记本地订单成功。
+
+## 开发注意事项
+1. 金额全部为**分（int64）**，Go使用int64，不要float64；JSON序列化不要丢失long精度
+2. DivisionCode必须五级乡镇，否则商品可售校验错误
+3. OuterPurchaseOrderId外部采购单号全局唯一，用于幂等防重复下单
+4. CreatePurchaseOrder异步，依赖回调；不能轮询频率过高
+5. RAM子账号最小权限，AK禁止硬编码代码，环境变量配置
+6. 所有接口必须判断外层返回`Success==true`，HTTP 200不等于业务成功
+7. 分页接口PageSize上限100，不要传超大值
+8. 回调接口做好幂等，同一个事件可能多次推送