@clawhub-jishuweihu-476813fded
人人商城龙虾助手 - 人人商城数据查询与订单管理工具。 当用户提到以下意图时使用此技能： 「查待办事项」「查运营数据」「查商品信息」「查会员信息」 「查订单」「管理订单」「查优惠券」「设置满额包邮」 「配置商城API」「验证API连通性」 支持：待办事项查询、运营数据统计、商品/会员/订单全维度查询、优惠券管理、...
---
name: 人人商城龙虾助手
description: |
人人商城龙虾助手 - 人人商城数据查询与订单管理工具。
当用户提到以下意图时使用此技能：
「查待办事项」「查运营数据」「查商品信息」「查会员信息」
「查订单」「管理订单」「查优惠券」「设置满额包邮」
「配置商城API」「验证API连通性」
支持：待办事项查询、运营数据统计、商品/会员/订单全维度查询、优惠券管理、满额包邮规则配置，所有操作需基于用户提供的人人商城合法API凭证执行。
version: 2.0.0
author: likexin
metadata: { "openclaw": { "requires": { "python": [ "requests>=2.31.0" ] }, "primaryEnv": "RR_CLAW_API_KEY", "requiredEnv": [ "RR_CLAW_BASE_URL" ], "optionalEnv": [ ], "baseUrl": "RR_CLAW_BASE_URL", "homepage": "https://www.rrsc.cn", "securityNotes": "所有凭证由平台从 ~/.openclaw/openclaw.json 注入，技能代码仅通过参数接收，不直接读取配置文件；运行时仅向用户配置的 RR_CLAW_BASE_URL 发送请求，不会将凭证传输至任何第三方端点" } }
---
# 人人商城龙虾助手
## 一、必读约束
### 首次安装配置
在 `~/.openclaw/openclaw.json` 中添加凭证，平台启动时会自动读取该文件并将凭证注入技能运行上下文（技能代码本身不直接读取此文件）：
```json
{
"skills": {
"entries": {
"renren-claw": {
"apiKey": "你的RR_CLAW_API_KEY",
"env": {
"RR_CLAW_BASE_URL": "你的人人商城API基础地址"
}
}
}
}
}
```
**获取凭证**：前往 [人人商城后台 > 插件 > 龙虾助手 > API Key管理] 获取 `API_KEY` 和 `服务器地址`。
### 安全约定
* 你操作的是用户线上的电商系统，任何失误都可能造成用户的经济损失
* 操作类接口提交时一定与用户确认好之后再进行操作
* 技能运行时仅向用户配置的 `RR_CLAW_BASE_URL` 发送请求，不会将 API Key 传输至任何第三方端点
* 严禁在聊天消息中明文输出 API Key
## 二、认证与请求方式
### 请求头
- `Authorization: Bearer $RR_CLAW_API_KEY`（格式：`lh-xxxxxxx-oc`）
### 请求方式
- **GET**：查询类接口
- **POST**：提交数据 / 操作类接口，请求体以 `application/x-www-form-urlencoded` 格式提交
#### 请求接口格式
RR_CLAW_BASE_URL + 接口地址
举例：https://example.com/wap/25/api/apps/openClaw/statistics/overview/to-do
#### 响应数据格式
- 所有接口统一返回 HTTP 200，**禁止以 HTTP 状态码判断成功或失败**
- 响应格式为 JSON：`{"error": 0, "message": "success", ...}`
- **必须检查 `error` 字段**：`0` = 成功，非 `0` = 业务失败（`message` 中包含错误描述）
#### 脚本请求示例
凭证由平台从 `~/.openclaw/openclaw.json` 注入，通过参数传递给客户端：
可自行拼接 cURL 请求，或调用 `scripts/request_client.py` 封装的客户端：
```python
from request_client import get_client
# 首次初始化：传入平台注入的凭证
client = get_client(base_url=RR_CLAW_BASE_URL, api_key=RR_CLAW_API_KEY)
# 后续调用直接复用已初始化的单例
client = get_client()
client.get("/some/path")
```
## 三、快速决策
| 用户意图 | 用户示例问法 | 调用接口 | 请求参数 |
|------------|-----------------------|--------------------------------------|-------------------------|
| **数据统计模块** | | | |
| 查询待办事项 | "待办事项"、"今天待办"、"待发货多少" | GET /statistics/overview/to-do | 无 |
| 查询今日运营数据 | "今日销售额"、"今天运营数据" | GET /statistics/overview/operational | period=today |
| 查询昨日运营数据 | "昨天销售额"、"昨日数据" | GET /statistics/overview/operational | period=yesterday |
| 查询近7天运营数据 | "近7天运营数据" | GET /statistics/overview/operational | period=week |
| 查询近30天运营数据 | "近30天数据" | GET /statistics/overview/operational | period=month |
| 新增会员统计 | "今日新增会员"、"近7天新会员" | GET /statistics/overview/new-member | period=today |
| 新增订单统计 | "今日订单数"、"近7天订单趋势" | GET /statistics/overview/new-order | period=today |
| 浏览量分析 | "今日浏览量"、"近7天PV/UV" | GET /statistics/overview/view-data | period=today |
| 商品销量排行 | "销量排行榜"、"什么卖得好" | GET /statistics/overview/goods-rank | period=today |
| 会员消费排行 | "会员消费榜"、"谁消费最多" | GET /statistics/overview/member-rank | period=today |
| 商品基础数据统计 | "近30天商品浏览加购数据" | GET /statistics/goods/basic | start_time、end_time(可选) |
| **商品模块** | | | |
| 查询商品列表 | "搜索iPhone"、"找商品" | GET /goods/list/get | keywords(可选) |
| 获取商品详情 | "商品ID 184的详情" | GET /goods/detail/get | id=184 |
| 下架商品 | "下架商品ID 184" | POST /goods/operation/put-store | id=184 |
| **会员模块** | | | |
| 查询会员列表 | "搜索会员An"、"找会员" | GET /member/list/get | keywords(可选) |
| 获取会员详情 | "会员ID 317的详情" | GET /member/list/get | id=317 |
| 通过手机号查会员ID | "手机号15888888888的会员ID" | GET /member/index/get-id-by-mobile | mobile=15888888888 |
| **订单模块** | | | |
| 查询订单列表 | "查订单"、"待发货订单" | GET /order/list/get | status(可选) |
| 通过订单号查订单ID | "订单号xxx的ID" | GET /order/index/get-id-by-no | order_no=xxx |
| 查询订单状态 | "订单xxx现在什么状态" | GET /order/index/get-status | order_no |
| 查询订单物流 | "订单xxx的物流信息" | GET /order/index/get-express | order_no |
| 关闭待支付订单 | "关闭订单ID 184" | POST /order/operation/close | id=184 |
| **营销活动模块** | | | |
| 优惠券概览 | "优惠券数据概览" | GET /sales/coupon/overview | 无 |
| 查询优惠券列表 | "搜索优惠券"、"发放中的优惠券" | GET /sales/coupon/list | keywords(可选) |
| 停止发放优惠券 | "停止发放优惠券ID 184" | POST /sales/coupon/manual-stop | id=184 |
| 获取满额包邮设置 | "满额包邮设置" | GET /sales/full-free/get | 无 |
| 关闭满额包邮 | "关闭满额包邮" | POST /sales/full-free/close | 无 |
## 四、功能列表
### 数据统计模块
读取 [数据统计模块](references/statistics.md) 的接口文档。
### 商品查询管理模块
读取 [商品查询管理模块](references/goods.md) 的接口文档。
### 订单查询管理模块
读取 [订单查询管理模块](references/order.md) 的接口文档。
### 会员查询管理模块
读取 [会员查询管理模块](references/member.md) 的接口文档。
### 营销活动查询管理模块
读取 [营销活动查询管理模块](references/sales.md) 的接口文档。
## 五、意图判断指南
### 商城字段名词解释
| 字段名 | 说明 |
|--------------|------|
| goods | 商品 |
| member | 会员 |
| order | 订单 |
| shop | 店铺 |
| mall | 综合商城 |
| communityBuy | 社区团购 |
| siteApp | 智慧轻站 |
| promoter | 推客带货 |
### 时间段判断
| 用户提到 | period参数值 |
|---------------|-----------|
| 今天、今日 | today |
| 昨天、昨日 | yesterday |
| 近7天、一周、最近7天 | week |
| 近30天、一月、最近30天 | month |
### 功能关键词判断
| 关键词 | 对应功能 |
|-------------------|----------|
| 待办、待发货、待付款、待审核 | 待办事项接口 |
| 销售额、成交金额、运营数据、客单价 | 运营数据接口 |
| 新增会员、新会员 | 新增会员统计接口 |
| 新增订单、订单数 | 新增订单统计接口 |
| 浏览量、PV、UV、访问量 | 浏览量分析接口 |
| 销量、排行、卖得好、商品排行 | 商品销量排行接口 |
| 会员消费、消费榜、谁消费最多 | 会员消费排行接口 |
| 商品、搜索商品、找商品 | 商品列表接口 |
| 会员、搜索会员、找会员 | 会员列表接口 |
| 订单、查订单、订单状态 | 订单列表接口 |
| 物流、快递、物流信息 | 订单物流接口 |
| 优惠券 | 优惠券相关接口 |
| 满额包邮 | 满额包邮相关接口 |
### ⚠️ 危险操作（必须二次确认）
以下接口会直接影响线上业务，**执行前必须向用户明确确认，禁止自动执行**：
- `POST /goods/operation/put-store` — 下架商品（影响前台展示）
- `POST /order/operation/close` — 关闭订单（不可逆）
- `POST /sales/coupon/manual-stop` — 停止发放优惠券（立即生效）
- `POST /sales/full-free/close` — 关闭满额包邮（立即生效）
FILE:_meta.json
{
"ownerId": "kn70727ys04w1jj3kzgnb7kmm98306rg",
"slug": "renren-claw",
"version": "1.0.8",
"publishedAt": 1773839643854
}
FILE:scripts/request_client.py
from typing import Any, Optional
import requests
class APIError(Exception):
"""接口业务错误：HTTP 200 但响应体中 error 非 0。"""
def __init__(self, code: int, message: str) -> None:
self.code = code
self.message = message
super().__init__(f"[{code}] {message}")
class RequestClient:
"""人人商城龙虾助手 API 请求客户端，基于 requests.Session 复用连接，支持 GET/POST/PUT/PATCH/DELETE。"""
def __init__(
self,
base_url: str,
api_key: str,
timeout: int = 30,
) -> None:
if not base_url:
raise ValueError("base_url 不能为空")
if not api_key:
raise ValueError("api_key 不能为空")
self.base_url = base_url
self.api_key = api_key
self.timeout = timeout
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.api_key}",
})
def _build_url(self, path: str) -> str:
base_url = self.base_url.rstrip("/")
path = path.lstrip("/")
return f"{base_url}/{path}"
def _request(
self,
method: str,
path: str,
*,
params: Optional[dict[str, Any]] = None,
data: Optional[dict[str, Any]] = None,
json: Optional[dict[str, Any] | list[Any]] = None,
**kwargs: Any,
) -> dict[str, Any] | list[Any] | None:
"""
统一请求封装：拼接 URL、超时、状态码校验、安全 JSON 解析，并校验业务错误码 error。
后端以 error 字段表示业务状态：0 为成功，非 0 时抛出 APIError，错误信息在 message 字段。
"""
url = self._build_url(path)
response = self.session.request(
method,
url,
params=params,
data=data,
json=json,
timeout=self.timeout,
**kwargs,
)
response.raise_for_status()
if not response.content:
return None
content_type = response.headers.get("Content-Type", "")
if "application/json" not in content_type:
return None
try:
data = response.json()
except ValueError:
return None
if isinstance(data, dict) and data.get("error", 0) != 0:
raise APIError(
code=int(data.get("error", -1)),
message=str(data.get("message", "未知错误")),
)
return data
def get(
self,
path: str,
params: Optional[dict[str, Any]] = None,
) -> dict[str, Any] | list[Any] | None:
"""发送 GET 请求，返回 JSON 或 None。"""
return self._request("GET", path, params=params)
def post(
self,
path: str,
data: Optional[dict[str, Any]] = None,
) -> dict[str, Any] | list[Any] | None:
"""发送 POST 请求，参数以 form data 提交，返回 JSON 或 None。"""
return self._request("POST", path, data=data)
_client: Optional[RequestClient] = None
def get_client(
base_url: Optional[str] = None,
api_key: Optional[str] = None,
timeout: int = 30,
) -> RequestClient:
"""
获取全局 RequestClient 单例。
首次调用时必须传入 base_url 和 api_key 以完成初始化；后续调用可省略参数直接复用。
"""
global _client
if _client is None:
if not base_url or not api_key:
raise ValueError("首次调用 get_client() 必须提供 base_url 和 api_key")
_client = RequestClient(base_url, api_key, timeout)
return _client
FILE:references/goods.md
# 商品查询管理模块
> 通用说明：所有接口响应均包含 `error` 字段（int），`0` = 成功，非 `0` = 失败（此时 `message` 包含错误描述）。下表不再重复列出
`error`。
| 接口 | 方法 | 路由 | 用途 |
|------|------|----------------------------|---------------|
| 商品列表 | GET | /goods/list/get | 按标题/编码/条码搜索商品 |
| 商品详情 | GET | /goods/detail/get | 按商品ID获取详情 |
| 下架商品 | POST | /goods/operation/put-store | ⚠️ 危险操作，需用户确认 |
---
## 获取商品列表
`GET /goods/list/get`
根据商品标题、商品编码、商品条码搜索商品信息。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|-----------|--------|----|-----------------------------------------------------------------------------------------------------------------------------------|
| keywords | string | 否 | 搜索关键字（可匹配商品标题、编码、条码） |
| type | int | 否 | 商品类型：`0` 实体商品 / `1` 虚拟商品 / `2` 虚拟卡密 / `3` 预约到店 / `5` 计次时商品 / `8` 批发商品 / `9` 智慧药房 / `13` 海淘商品 / `20` 社区团购 / `21` 期刊商品 / `22` 供应链商品 |
| status | int | 否 | 商品状态：不传=全部 / `1` 上架 / `2` 售罄 / `3` 下架 / `4` 已删除 |
| sort | string | 否 | 排序字段：`real_sales` 真实销量 / `create_time` 创建时间 |
| by | string | 否 | 排序方式：`asc` 升序 / `desc` 降序 |
| page | int | 否 | 页码（默认 1） |
| page_size | int | 否 | 每页数量（默认 6） |
**响应字段：**
| 字段 | 类型 | 说明 |
|-----------------------|--------|---------------------|
| total | int | 当前条件下的总数量 |
| page | int | 当前页 |
| page_size | int | 每页数量 |
| list[].id | int | 商品ID |
| list[].title | string | 商品标题 |
| list[].sub_title | string | 商品副标题 |
| list[].type | int | 商品类型 |
| list[].thumb | string | 商品主图 |
| list[].unit | string | 单位 |
| list[].goods_code | string | 编码 |
| list[].bar_code | string | 条码 |
| list[].stock | int | 库存 |
| list[].stock_warning | int | 库存告警值 |
| list[].real_sales | int | 真实销量 |
| list[].price | float | 商品价格 |
| list[].min_price | float | 多规格区间最低价 |
| list[].max_price | float | 多规格区间最高价 |
| list[].cost_price | float | 成本价 |
| list[].original_price | float | 划线价 |
| list[].has_option | int | 是否多规格：`0` 否 / `1` 是 |
| list[].sales | int | 销量 |
| list[].type_text | string | 商品类型文字 |
| list[].status_text | string | 商品状态文字 |
```json
{
"error": 0,
"total": 1307,
"list": [
{
"id": "9842",
"title": "按订单-一次性核销完成",
"sub_title": "",
"type": "5",
"thumb": "image/25/2025/11/xxxx.jpg",
"unit": "件",
"goods_code": "",
"bar_code": "",
"stock": "3316",
"stock_warning": "20",
"real_sales": "16",
"price": "10.00",
"min_price": "10.00",
"max_price": "12.00",
"cost_price": "0.00",
"original_price": "0.00",
"has_option": "1",
"status": "1",
"sales": "16",
"type_text": "计次时商品",
"status_text": "上架"
}
],
"page": 1,
"page_size": 6
}
```
---
## 获取商品详情
`GET /goods/detail/get`
根据商品ID获取商品详情。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----|-----|----|------|
| id | int | 是 | 商品ID |
**响应字段：**
| 字段 | 类型 | 说明 |
|----------------------|--------|---------------------|
| goods.id | int | 商品ID |
| goods.type | int | 商品类型 |
| goods.status | int | 商品状态 |
| goods.is_deleted | int | 是否删除：`0` 否 / `1` 是 |
| goods.title | string | 商品标题 |
| goods.sub_title | string | 商品副标题 |
| goods.unit | string | 单位 |
| goods.goods_code | string | 编码 |
| goods.bar_code | string | 条码 |
| goods.stock | int | 库存 |
| goods.price | float | 商品价格 |
| goods.min_price | float | 多规格区间最低价 |
| goods.max_price | float | 多规格区间最高价 |
| goods.cost_price | float | 成本价 |
| goods.original_price | float | 划线价 |
| goods.has_option | int | 是否多规格：`0` 否 / `1` 是 |
| goods.view_count | int | 浏览量 |
| goods.sales | int | 销量 |
| goods.thumb | string | 主图 |
| goods.type_text | string | 商品类型文字 |
| goods.status_text | string | 商品状态文字 |
```json
{
"error": 0,
"goods": {
"id": "9842",
"type": "5",
"status": "1",
"is_deleted": "0",
"title": "按订单-一次性核销完成",
"sub_title": "",
"price": "10.00",
"max_price": "12.00",
"min_price": "10.00",
"original_price": "0.00",
"stock": "3316",
"has_option": "1",
"view_count": "27",
"sales": "0",
"thumb": "https://xxx.jpg",
"goods_unit": "袋",
"status_text": "上架",
"type_text": "计次时商品"
}
}
```
---
## ⚠️ 下架商品
`POST /goods/operation/put-store`
通过商品ID下架商品。**此操作影响前台展示，执行前必须向用户确认。**
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----|-----|----|------|
| id | int | 是 | 商品ID |
**响应字段：**
| 字段 | 类型 | 说明 |
|---------|--------|--------------------|
| message | string | 失败时返回错误信息，如"商品不存在" |
```json
{
"error": 0
}
```
FILE:references/member.md
# 会员查询管理模块
> 通用说明：所有接口响应均包含 `error` 字段（int），`0` = 成功，非 `0` = 失败（此时 `message` 包含错误描述）。下表不再重复列出
`error`。
| 接口 | 方法 | 路由 | 用途 |
|--------|-----|--------------------------------|----------------------|
| 会员列表 | GET | /member/list/get | 按昵称/姓名/手机号/ID搜索会员 |
| 会员详情 | GET | /member/list/get | 按会员ID获取详情（传 `id` 参数） |
| 手机号查ID | GET | /member/index/get-id-by-mobile | 通过手机号获取会员ID |
---
## 获取会员列表
`GET /member/list/get`
根据会员昵称、真实姓名、手机号、会员ID搜索会员信息。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|-----------|--------|----|----------------------------|
| keywords | string | 否 | 搜索关键字（可匹配昵称、真实姓名、手机号、会员ID） |
| page | int | 否 | 页码（默认 1） |
| page_size | int | 否 | 每页数量（默认 6） |
**响应字段：**
| 字段 | 类型 | 说明 |
|----------------------|--------|----------------------|
| total | int | 当前条件下的总数量 |
| page | int | 当前页 |
| page_size | int | 每页数量 |
| list[].id | int | 会员ID |
| list[].avatar | string | 头像地址 |
| list[].nickname | string | 昵称 |
| list[].realname | string | 真实姓名 |
| list[].mobile | string | 手机号 |
| list[].credit | int | 积分 |
| list[].balance | float | 余额 |
| list[].is_black | int | 是否是黑名单：`0` 否 / `1` 是 |
| list[].level_id | int | 等级ID |
| list[].source | int | 来源 |
| list[].create_time | string | 创建时间 |
| list[].remark | string | 备注 |
| list[].order_count | int | 订单数量 |
| list[].money_count | float | 订单金额 |
| list[].last_pay_time | string | 最后支付时间 |
| list[].is_black_name | string | 是否黑名单 |
| list[].level_name | string | 等级名称 |
| list[].group_name | string | 标签名 |
| list[].source_name | string | 来源渠道 |
```json
{
"error": 0,
"total": 1,
"list": [
{
"id": "317",
"avatar": "https://xxx.jpg",
"nickname": "An",
"realname": "李可鑫",
"mobile": "15888888888",
"credit": "9981290",
"balance": "935276.97",
"is_black": 0,
"level_id": "447",
"source": "40",
"create_time": "2021-12-13 10:10:35",
"remark": "",
"order_count": "104",
"money_count": "65030.82",
"last_pay_time": "2026-03-04 21:01:02",
"is_black_name": "否",
"level_name": "市长",
"group_name": "简单明了,复杂繁琐",
"source_name": "APP"
}
],
"page": 1,
"page_size": 20
}
```
---
## 获取会员详情
`GET /member/detail/get`
根据会员ID获取会员详情（传 `id` 参数时返回单个会员详细信息）。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----|-----|----|------|
| id | int | 是 | 会员ID |
**响应字段：**
| 字段 | 类型 | 说明 |
|-----------------------|--------|-----------------------|
| member.id | int | 会员ID |
| member.avatar | string | 头像地址 |
| member.nickname | string | 昵称 |
| member.realname | string | 真实姓名 |
| member.mobile | string | 手机号 |
| member.credit | int | 积分 |
| member.balance | float | 余额 |
| member.level_id | int | 等级ID |
| member.source | int | 来源 |
| member.last_time | string | 最后登录时间 |
| member.is_deleted | int | 是否删除：`0` 否 / `1` 是 |
| member.create_time | string | 注册时间 |
| member.is_black | int | 是否黑名单：`0` 否 / `1` 是 |
| member.remark | string | 备注 |
| member.is_bind_mobile | int | 是否绑定手机号：`0` 否 / `1` 是 |
| member.birthday | string | 生日 |
| member.level_name | string | 等级名称 |
| member.password_set | int | 是否设置密码：`0` 否 / `1` 是 |
| member.group_name | string | 标签名 |
| member.is_black_name | string | 是否黑名单（文字） |
| member.member_code | string | 会员码 |
| member.source_name | string | 来源渠道 |
```json
{
"error": 0,
"member": {
"id": "317",
"avatar": "https://xxx.jpg",
"nickname": "An",
"realname": "李可鑫",
"level_id": "447",
"mobile": "15888888888",
"credit": "9981290",
"balance": "935276.97",
"source": "40",
"last_time": "2026-03-05 17:28:12",
"is_deleted": "0",
"create_time": "2021-12-13 10:10:35",
"is_black": 0,
"remark": "-",
"is_bind_mobile": "0",
"birthday": "0000-00-00 00:00:00",
"level_name": "市长",
"password_set": 1,
"group_name": "简单明了,复杂繁琐",
"is_black_name": "否",
"member_code": "000000000000000317",
"source_name": "APP"
}
}
```
---
## 通过手机号获取会员ID
`GET /member/index/get-id-by-mobile`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|-----|
| mobile | string | 是 | 手机号 |
**响应字段：**
| 字段 | 类型 | 说明 |
|-----------|-----|------|
| member_id | int | 会员ID |
```json
{
"error": 0,
"member_id": "317"
}
```
FILE:references/order.md
# 订单查询管理模块
> 通用说明：所有接口响应均包含 `error` 字段（int），`0` = 成功，非 `0` = 失败（此时 `message` 包含错误描述）。下表不再重复列出
`error`。
| 接口 | 方法 | 路由 | 用途 |
|--------|------|---------------------------|------------------|
| 订单列表 | GET | /order/list/get | 按编号/会员/状态/时间搜索订单 |
| 订单号查ID | GET | /order/index/get-id-by-no | 通过订单编号获取订单ID |
| 订单状态 | GET | /order/index/get-status | 查询订单当前状态 |
| 订单物流 | GET | /order/index/get-express | 查询订单物流轨迹 |
| 关闭订单 | POST | /order/operation/close | ⚠️ 危险操作，需用户确认 |
> **订单状态码对照：** `-1` 已关闭 / `0` 待支付 / `10` 待发货 / `11` 部分发货 / `20` 待收货 / `21` 待自提 / `30` 已完成
---
## 获取订单列表
`GET /order/list/get`
根据会员ID、订单状态、下单时间、订单编号搜索订单信息。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|-------------------|--------|----|----------------------------------|
| order_no | string | 否 | 订单编号 |
| create_time_start | string | 否 | 下单时间-开始，格式 `2026-02-02 00:00:00` |
| create_time_end | string | 否 | 下单时间-结束，格式 `2026-02-04 23:59:59` |
| member_id | int | 否 | 指定会员ID |
| status | int | 否 | 订单状态（见上方状态码对照） |
| page | int | 否 | 页码（默认 1） |
| page_size | int | 否 | 每页数量（默认 6） |
**响应字段：**
| 字段 | 类型 | 说明 |
|--------------------------------|--------|-----------|
| total | int | 当前条件下的总数量 |
| page | int | 当前页 |
| page_size | int | 每页数量 |
| list[].id | int | 订单ID |
| list[].order_no | string | 订单编号 |
| list[].pay_price | float | 实付金额 |
| list[].order_type | int | 订单类型码 |
| list[].activity_type | int | 活动类型码 |
| list[].status | int | 订单状态码 |
| list[].create_time | string | 下单时间 |
| list[].dispatch_type | int | 配送方式 |
| list[].buyer_name | string | 收件人姓名 |
| list[].buyer_mobile | string | 收件人手机号 |
| list[].buyer_remark | string | 买家备注 |
| list[].member_id | int | 会员ID |
| list[].member_nickname | string | 会员昵称 |
| list[].member_realname | string | 会员真实姓名 |
| list[].member_mobile | string | 会员手机号 |
| list[].address | string | 收货地址 |
| list[].status_text | string | 订单状态文字 |
| list[].order_type_text | string | 订单类型文字 |
| list[].activity_type_text | string | 订单活动类型文字 |
| list[].goods_info[] | array | 订单商品列表 |
| list[].goods_info[].title | string | 商品标题 |
| list[].goods_info[].goods_id | string | 商品ID |
| list[].goods_info[].total | string | 购买数量 |
| list[].goods_info[].price | float | 实付价 |
| list[].goods_info[].price_unit | string | 单价 |
```json
{
"error": 0,
"total": 1,
"list": [
{
"id": "29057",
"order_no": "1010260204182752364533",
"pay_price": "1898.80",
"order_type": "10",
"activity_type": "22",
"status": "11",
"create_time": "2026-02-04 18:27:52",
"goods_info": [
{
"title": "大疆 DJI Pocket 2 全能套装",
"goods_id": "8588",
"total": "1",
"price": 1726.95,
"price_unit": "1788.00"
}
],
"dispatch_type": "10",
"buyer_name": "收件人姓名",
"buyer_mobile": "15888888888",
"buyer_remark": "",
"member_id": "317",
"member_nickname": "An",
"member_realname": "李可鑫",
"member_mobile": "15888888888",
"address": "浙江省 杭州市 淳安县 啦啦啦",
"status_text": "部分发货",
"order_type_text": "普通订单",
"activity_type_text": null
}
],
"page": 1,
"page_size": 20
}
```
---
## 通过订单编号获取订单ID
`GET /order/index/get-id-by-no`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----------|--------|----|------|
| order_no | string | 是 | 订单编号 |
**响应字段：**
| 字段 | 类型 | 说明 |
|----------|-----|------|
| order_id | int | 订单ID |
```json
{
"error": 0,
"order_id": "31711"
}
```
---
## 获取订单状态
`GET /order/index/get-status`
根据订单编号或订单ID查询订单当前状态（后端自动识别传入的是编号还是ID）。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----------|--------|----|-------------------|
| order_no | string | 是 | 订单编号或订单ID（后端自动识别） |
**响应字段：**
| 字段 | 类型 | 说明 |
|-------------|--------|--------|
| status | int | 订单状态码 |
| status_text | string | 订单状态文字 |
```json
{
"error": 0,
"status": "30",
"status_text": "已完成"
}
```
---
## 获取订单物流信息
`GET /order/index/get-express`
根据订单编号或订单ID查询订单物流信息（后端自动识别传入的是编号还是ID）。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----------|--------|----|-------------------|
| order_no | string | 是 | 订单编号或订单ID（后端自动识别） |
**响应字段：**
| 字段 | 类型 | 说明 |
|-------------------------------|--------|--------|
| data.express.state | int | 物流状态码 |
| data.express.state_text | string | 物流状态文字 |
| data.express.data[] | array | 物流轨迹列表 |
| data.express.data[].date_time | string | 时间 |
| data.express.data[].step | string | 物流详情 |
| data.express_com | string | 物流公司名称 |
| data.express_sn | string | 物流单号 |
| data.address_detail | string | 收货地址 |
```json
{
"error": 0,
"data": {
"express": {
"state": "2",
"data": [
{
"date_time": "2026-03-12 11:52:29",
"step": "【济南市】已离开 山东济南分拨交付中心；发往 山东潍坊分拨交付中心"
},
{
"date_time": "2026-03-11 16:18:16",
"step": "【南京市】江苏南京浦口区新城公司 已揽收"
}
],
"state_text": "疑难"
},
"express_com": "韵达快运",
"express_sn": "315070238346274",
"address_detail": "啦啦啦"
}
}
```
---
## ⚠️ 关闭待支付订单
`POST /order/operation/close`
通过订单ID关闭待支付的订单。**此操作不可逆，执行前必须向用户确认。**
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----|-----|----|------|
| id | int | 是 | 订单ID |
**响应字段：**
| 字段 | 类型 | 说明 |
|---------|--------|--------------------|
| message | string | 失败时返回错误信息，如"订单不存在" |
```json
{
"error": 0
}
```
FILE:references/sales.md
# 营销活动查询管理模块
> 通用说明：所有接口响应均包含 `error` 字段（int），`0` = 成功，非 `0` = 失败（此时 `message` 包含错误描述）。下表不再重复列出
`error`。
| 接口 | 方法 | 路由 | 用途 |
|---------|------|---------------------------|------------------|
| 优惠券概览 | GET | /sales/coupon/overview | 各状态优惠券数量汇总 |
| 优惠券列表 | GET | /sales/coupon/list | 按名称/状态/领取方式搜索优惠券 |
| 停止发放优惠券 | POST | /sales/coupon/manual-stop | ⚠️ 危险操作，需用户确认 |
| 满额包邮设置 | GET | /sales/full-free/get | 获取当前满额包邮规则 |
| 关闭满额包邮 | POST | /sales/full-free/close | ⚠️ 危险操作，需用户确认 |
---
## 获取优惠券概览
`GET /sales/coupon/overview`
获取优惠券各状态数量汇总。无请求参数。
**响应字段：**
| 字段 | 类型 | 说明 |
|-------------------|-----|----------|
| data.sending | int | 发放中优惠券数量 |
| data.expired | int | 已过期优惠券数量 |
| data.out_of_stock | int | 已领完优惠券数量 |
| data.used | int | 已使用优惠券数量 |
| data.received | int | 已领取优惠券数量 |
```json
{
"error": 0,
"data": {
"sending": 29,
"expired": 66,
"out_of_stock": 6,
"used": 523,
"received": 18417
}
}
```
---
## 获取优惠券列表
`GET /sales/coupon/list`
根据优惠券名称、状态、领取方式搜索优惠券信息。
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|------------------|--------|----|----------------------------------------------------------------------|
| keywords | string | 否 | 搜索优惠券名称 |
| coupon_sale_type | int | 否 | 优惠类型：`1` 立减 / `2` 折扣（不传=全部） |
| status | int | 否 | 状态：`1` 发放中 / `2` 未发放 / `3` 已领完 / `4` 已过期（不传=全部） |
| pick_way | int | 否 | 领取方式：`1` 免费领取 / `2` 付费领取 / `3` 链接领取 / `4` 活动领取 / `5` 领券中心 / `6` 直播领取 |
| page | int | 否 | 页码（默认 1） |
| page_size | int | 否 | 每页数量（默认 6） |
**响应字段：**
| 字段 | 类型 | 说明 |
|----------------------|--------|-----------------|
| total | int | 当前条件下的总数量 |
| page | int | 当前页 |
| page_size | int | 每页数量 |
| list[].id | int | 优惠券ID |
| list[].coupon_name | string | 优惠券名称 |
| list[].stock | int | 优惠券库存 |
| list[].create_time | string | 添加时间 |
| list[].content | string | 优惠内容（如"满1减0.1"） |
| list[].pick_way_text | string | 领取类型文字 |
| list[].status_text | string | 状态文字 |
```json
{
"error": 0,
"total": 1,
"list": [
{
"id": "218",
"coupon_name": "计次时",
"coupon_sale_type": "1",
"stock": "0",
"create_time": "2025-11-25 15:24:33",
"content": "满1减0.1",
"pick_way": 2,
"pick_way_text": "付费领取",
"status": "4",
"status_text": "已过期"
}
],
"page": 1,
"page_size": 20
}
```
---
## ⚠️ 手动停止发放优惠券
`POST /sales/coupon/manual-stop`
根据优惠券ID停止发放指定的优惠券。**此操作立即生效，执行前必须向用户确认。**
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|----|-----|----|-------|
| id | int | 是 | 优惠券ID |
**响应字段：**
| 字段 | 类型 | 说明 |
|---------|--------|---------------------|
| message | string | 失败时返回错误信息，如"优惠券不存在" |
```json
{
"error": 0
}
```
---
## 获取满额包邮设置
`GET /sales/full-free/get`
获取当前满额包邮规则。无请求参数。
**响应字段：**
| 字段 | 类型 | 说明 |
|-------------------------|--------|-----------------------------------------|
| settings.state | int | 开启状态：`0` 关闭 / `1` 开启 |
| settings.is_participate | string | 指定商品：`0` 以下商品不参与 / `1` 以下商品参与 / `2` 不限制 |
| settings.goods_ids | array | 指定商品的ID合集 |
| settings.order_enough | string | 单笔订单包邮金额 |
| goods_list[] | array | 指定商品的列表 |
| goods_list[].id | int | 商品ID |
| goods_list[].title | string | 商品标题 |
| goods_list[].price | float | 商品价格 |
| no_support_areas | string | 不参加包邮地区（为空则不限制） |
```json
{
"error": 0,
"settings": {
"state": 0,
"is_participate": "0",
"goods_ids": [
"9801"
],
"order_enough": "3000.00"
},
"goods_list": [
{
"id": "9801",
"title": "xzj多规格",
"price": "120.00",
"has_option": "1"
}
],
"no_support_areas": "北京市，山东省【青岛市(黄岛区)】"
}
```
---
## ⚠️ 关闭满额包邮设置
`POST /sales/full-free/close`
关闭满额包邮设置。无请求参数。**此操作立即生效，执行前必须向用户确认。**
**响应字段：**
| 字段 | 类型 | 说明 |
|---------|--------|------------------------|
| message | string | 失败时返回错误信息，如"当前已经是关闭状态" |
```json
{
"error": 0
}
```
FILE:references/statistics.md
# 数据统计模块
> 通用说明：所有接口响应均包含 `error` 字段（int），`0` = 成功，非 `0` = 失败（此时 `message` 包含错误描述）。下表不再重复列出
`error`。
| 接口 | 方法 | 路由 | 用途 |
|--------|-----|----------------------------------|---------------|
| 待办事项 | GET | /statistics/overview/to-do | 待发货、待付款等待办数量 |
| 运营数据 | GET | /statistics/overview/operational | 成交额、退款、订单数等 |
| 新增会员统计 | GET | /statistics/overview/new-member | 各渠道新增会员折线 |
| 新增订单统计 | GET | /statistics/overview/new-order | 各渠道新增订单折线 |
| 浏览量分析 | GET | /statistics/overview/view-data | 各渠道 PV/UV |
| 商品销量排行 | GET | /statistics/overview/goods-rank | 各渠道商品销量、销售额排行 |
| 会员消费排行 | GET | /statistics/overview/member-rank | 各渠道会员消费排行 |
| 商品基础数据 | GET | /statistics/goods/basic | 被浏览/加购/购买商品数 |
> **渠道字段说明**（多个接口共用）：`mall` = 综合商城（必返），`communityBuy` = 社区团购，`siteApp` = 智慧轻站，`promoter` =
> 推客带货。后三者仅在商城开启对应业务时返回。
---
## 待办事项数据
`GET /statistics/overview/to-do`
无请求参数。
**响应字段：**
| 字段 | 类型 | 说明 |
|----------------------------|-----|-----------|
| data.wait_delivery_order | int | 待发货订单数量 |
| data.wait_pay_order | int | 待支付订单数量 |
| data.wait_after_sale_order | int | 待处理售后订单数量 |
| data.wait_replenish_goods | int | 待补货商品数量 |
| data.wait_audit_member | int | 待审核会员数量 |
```json
{
"error": 0,
"data": {
"wait_delivery_order": 1737,
"wait_pay_order": 943,
"wait_after_sale_order": 83,
"wait_replenish_goods": 35,
"wait_audit_member": 0
}
}
```
---
## 运营数据
`GET /statistics/overview/operational`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|-----------------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week`(近7日) / `month`(近30日) |
**响应字段：**
| 字段 | 类型 | 说明 |
|-----------------------------------------|--------|-----------------------------|
| data.order_pay_price | float | 成交金额（元） |
| data.order_refund_price | float | 退款金额（元） |
| data.order_pay | int | 支付订单数（笔） |
| data.unit_price | float | 笔单价（元） |
| data.guest_unit_price | int | 客单价（元） |
| data.order_pay_member | int | 支付人数 |
| data.new_member_count | int | 新会员数量 |
| data.compare | object | 与昨日对比（仅 `period=today` 时返回） |
| data.compare.compare_order_pay_price | int | 较昨日成交金额比例(%) |
| data.compare.compare_order_refund_price | int | 较昨日退款金额比例(%) |
| data.compare.compare_order_pay | int | 较昨日支付订单数比例(%) |
| data.compare.compare_unit_price | int | 较昨日笔单价比例(%) |
| data.compare.compare_guest_unit_price | int | 较昨日客单价比例(%) |
| data.compare.compare_change | int | 较昨日支付人数比例(%) |
| data.compare.compare_new_member_count | int | 较昨日新会员数量比例(%) |
```json
{
"error": 0,
"data": {
"order_pay_price": 139,
"order_refund_price": 120.25,
"order_pay": 2,
"unit_price": 69.5,
"guest_unit_price": 139,
"order_pay_member": 1,
"new_member_count": 0,
"compare": {
"compare_order_pay_price": 100,
"compare_order_refund_price": 100,
"compare_order_pay": 100,
"compare_unit_price": 100,
"compare_guest_unit_price": 100,
"compare_change": 0,
"compare_new_member_count": 100
}
}
}
```
---
## 新增会员统计
`GET /statistics/overview/new-member`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week` / `month` |
**响应字段：** 按渠道返回时间序列数组，每个元素包含 `period`（时间点）和 `count`（数量）。
| 字段 | 类型 | 说明 |
|---------------------|-------|------------|
| data.mall[] | array | 综合商城（必返） |
| data.communityBuy[] | array | 社区团购（有则返回） |
| data.siteApp[] | array | 智慧轻站（有则返回） |
| data.promoter[] | array | 推客带货（有则返回） |
```json
{
"error": 0,
"data": {
"mall": [
{
"period": "00:00",
"count": 0
},
{
"period": "01:00",
"count": 2
},
"... 每小时一个数据点，至 23:00"
],
"communityBuy": [
"... 同上结构"
],
"siteApp": [
"... 同上结构"
],
"promoter": [
"... 同上结构"
]
}
}
```
---
## 新增订单统计
`GET /statistics/overview/new-order`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week` / `month` |
**响应字段：** 结构与「新增会员统计」完全一致，按渠道返回 `{ period, count }` 时间序列。
```json
{
"error": 0,
"data": {
"mall": [
{
"period": "00:00",
"count": 0
},
"..."
],
"communityBuy": [
"..."
],
"siteApp": [
"..."
],
"promoter": [
"..."
]
}
}
```
---
## 浏览量分析
`GET /statistics/overview/view-data`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week` / `month` |
**响应字段：** 每个渠道包含 `viewData`（汇总 PV/UV）和 `detailData`（按时间点的明细）。
| 字段 | 类型 | 说明 |
|----------------------------|--------|-----------------------------|
| data.{channel}.viewData.pv | int | 页面浏览量 |
| data.{channel}.viewData.uv | int | 独立访客数 |
| data.{channel}.detailData | object | 按时间点的 PV 明细，键为时间如 `"00:00"` |
> `{channel}` 可选值：`mall`（必返）、`communityBuy`、`siteApp`、`promoter`
```json
{
"error": 0,
"data": {
"mall": {
"viewData": {
"pv": 126,
"uv": 45
},
"detailData": {
"00:00": {
"pv": 0
},
"01:00": {
"pv": 3
},
"...": "..."
}
},
"communityBuy": {
"viewData": {
"pv": 0,
"uv": 0
},
"detailData": {
"...": "..."
}
},
"siteApp": {
"viewData": {
"pv": 0,
"uv": 0
},
"detailData": {
"...": "..."
}
},
"promoter": {
"viewData": {
"pv": 0,
"uv": 0
},
"detailData": {
"...": "..."
}
}
}
}
```
---
## 商品销量排行榜
`GET /statistics/overview/goods-rank`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week` / `month` |
**响应字段：** 按渠道返回商品排行数组。
| 字段 | 类型 | 说明 |
|------------------------|--------|------------------------|
| data.{channel}[].title | string | 商品标题 |
| data.{channel}[].total | int | 销售数量（promoter 渠道为带货数量） |
| data.{channel}[].price | float | 销售额 |
```json
{
"error": 0,
"data": {
"mall": [
{
"id": "3326",
"title": "示例商品名2",
"total": "8",
"price": "75.00"
}
],
"communityBuy": [],
"promoter": [
{
"title": "示例商品名",
"total": "5",
"price": "199.00"
}
]
}
}
```
---
## 会员消费排行榜
`GET /statistics/overview/member-rank`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|--------|--------|----|------------------------------------------|
| period | string | 是 | `today` / `yesterday` / `week` / `month` |
**响应字段：** 按渠道返回会员消费排行数组。
| 字段 | 类型 | 说明 |
|-----------------------------|--------|----------|
| data.mall[].id | int | 会员ID |
| data.mall[].nickname | string | 会员昵称 |
| data.mall[].order_money | float | 消费金额 |
| data.communityBuy[] | array | 结构同 mall |
| data.promoter[].id | int | 会员ID |
| data.promoter[].nickname | string | 会员昵称 |
| data.promoter[].total | int | 带货订单数量 |
| data.promoter[].order_money | float | 带货订单金额 |
```json
{
"error": 0,
"data": {
"mall": [
{
"id": "317",
"nickname": "An",
"mobile": "15888888888",
"order_money": 11
}
],
"communityBuy": [
{
"id": "317",
"nickname": "An",
"order_money": 11
}
],
"promoter": [
{
"id": "9",
"nickname": "som",
"total": "0",
"order_money": 0
}
]
}
}
```
---
## 获取商品基础数据统计
`GET /statistics/goods/basic`
**请求参数：**
| 字段 | 类型 | 必传 | 说明 |
|------------|--------|----|-------------------------------------------|
| start_time | string | 否 | 统计开始时间，不传默认为30天前，格式 `2026-01-01 00:00:00` |
| end_time | string | 否 | 统计结束时间，不传默认为前一天，格式 `2026-02-01 00:00:00` |
**响应字段：**
| 字段 | 类型 | 说明 |
|-----------------------|-----|------------|
| data.goods_view_count | int | 被浏览商品数量（件） |
| data.cart_goods_count | int | 加购商品数量（件） |
| data.pay_goods_count | int | 购买商品数量（件） |
```json
{
"error": 0,
"data": {
"goods_view_count": 1,
"cart_goods_count": 2,
"pay_goods_count": 3
}
}
```