地标优选商品

概述

Overview

本 Skill 让社区团购的团长 / 大团长 / 运营直接通过自然语言查询蛋卷 SAAS 系统里的"地标优选"商品库与营销规则。底层调用 1card1 开放平台两个接口，均用 OpenId + Secret 生成签名鉴权：

• Get_GoodsItemsPagedV2（获取商品列表）：实时返回商品名称、分类、价格、特价、单位、在售状态、图片。
• Get_PointAndDiscount（获取积分/折扣系数）：按商品编码（可多码）或整单查最终积分系数、折扣系数、特价信息，支持按会员卡号区分会员级别。

团长常用场景（自然语言即可触发）：

• "帮我看看水果类都有哪些商品"
• "搜一下苹果相关的商品"
• "条码 g001 这件商品详情给我"
• "现在在售的生鲜有哪些"
• "第 2 页商品翻一下"
• "这件商品（条码 0104）给会员打几折、积几分？"
• "整单的积分折扣系数多少？"
• "查下会员 138xxxx 的资料和余额"
• "给会员 136xxxx 下一单：2 份老豆腐、1 份花菜，应付 30 实付 30"

鉴权与配置（首次使用前必做）

接口为签名鉴权（属 API 密钥体系）：signature = MD5(OpenId + Secret + Timestamp + data)（32 位大写），随请求以查询参数 openId / signature / timestamp 传递。

凭据绝不硬编码。按以下任一方式配置（脚本自动读取，环境变量优先于 config.json）：

方式 A — 环境变量（推荐，避免明文落盘）：

DBYX_OPENID=你的OpenId
DBYX_SECRET=你的Secret
DBYX_USERACCOUNT=你的工号(如10003)
DBYX_BASE_URL=https://openapi.1card1.cn   # 可选

方式 B — 同目录 config.json： 复制 config.example.json 为 config.json 并填入真实值。

字段细节、where 写法、返回字段含义见 references/api_spec.md。

调用脚本

脚本：scripts/query_goods.py（纯标准库，无第三方依赖）。

运行方式（在 Skill 目录下）：

python scripts/query_goods.py --category 水果
python scripts/query_goods.py --keyword 苹果
python scripts/query_goods.py --barcode g001
python scripts/query_goods.py --guid a13ea1b4-3fe6-e311-8b81-90b11c47b4da
python scripts/query_goods.py --category 生鲜 --onsale --page 1 --page-size 20
python scripts/query_goods.py --keyword 苹果 --json      # 输出原始 JSON 便于二次处理

# —— 积分 / 折扣系数（Get_PointAndDiscount） ——
python scripts/query_goods.py --point-discount --barcode 0104            # 单品系数
python scripts/query_goods.py --point-discount --barcode "0104,0038"     # 多品明细（编码须真实存在）
python scripts/query_goods.py --point-discount                           # 整单最终系数
python scripts/query_goods.py --point-discount --barcode 0104 --card-id 12345   # 指定会员卡号

# —— 会员查询（Get_MemberInfo） ——
python scripts/query_goods.py --member --card-id 13800138000            # 按手机号查会员
python scripts/query_goods.py --member --card-id q123 --get-ext         # 含扩展字段

# —— 下单 / 消费收银（Consume，⚠️ 真实写操作） ——
# 先预览（不发送）：
python scripts/query_goods.py --consume --total-money 30 --total-paid 30 
    --consume-list '[{"barcode":"0104","name":"老豆腐","number":2,"disCount":1,"paidMoney":20,"meno":""},{"barcode":"0023","name":"花菜","number":1,"disCount":1,"paidMoney":10,"meno":""}]' 
    --card-id 13800138000 --meno "社区团购单"
# 确认无误后再真正提交（加 --confirm）：
python scripts/query_goods.py --consume --total-money 30 --total-paid 30 
    --consume-list '[{"barcode":"0104","name":"老豆腐","number":2,"disCount":1,"paidMoney":20,"meno":""},{"barcode":"0023","name":"花菜","number":1,"disCount":1,"paidMoney":10,"meno":""}]' 
    --card-id 13800138000 --meno "社区团购单" --confirm

参数速查

执行流程（给 WorkBuddy 的指示）

1. 识别用户意图，四类之一：商品查询 / 积分折扣查询 / 会员查询 / 下单(消费收银)。
2. 从用户话语提取参数：
   • 商品查询：分类名、关键词、条码、Guid、页码等。
   • 积分折扣：商品条码（可多个）、会员卡号（若用户提到"会员/老顾客/卡号"则填 --card-id）。
   • 会员查询：会员卡号/手机号/Guid/OpenId → 填 --card-id（会员查询必填）；如需扩展字段加 --get-ext。
   • 下单：会员标识（→ --card-id，可空=散客）、应付 --total-money、实付 --total-paid、明细 --consume-list（barcode/name/number/disCount/paidMoney），以及备注/唯一码。
3. 确认 config.json 或环境变量已就绪；若缺失，提示用户按"鉴权与配置"填写，不要臆造密钥。
4. 调用 scripts/query_goods.py，默认不带 --json（给人看的表格）；若需结构化数据再带 --json：
   • 商品查询：对应筛选参数。
   • 积分折扣：加 --point-discount + --barcode。
   • 会员查询：加 --member + --card-id。
   • 下单：先不带 --confirm 跑一次预览（脚本会打印完整请求，含签名 URL 与 data），把预览内容回显给用户确认；只有用户明确说"确认提交/下单"后，才加 --confirm 真正发送。
5. 把结果用中文转述给团长：
   • 商品查询：商品名、分类、价格（标注特价）、单位、是否在售、图片链接。
   • 积分折扣：折扣系数换算成"X 折"、积分系数换算成"1 元积 X 分"、是否特价及特价金额。
   • 会员查询：姓名、会员级别、可用积分、可用储值、手机号、注册/到期时间。
   • 下单：成功返回单据号 billNumber、本次产生积分、剩余积分/储值；status=1 提示"待支付"。
6. 若商品查询返回"未查询到匹配商品"，视情况建议换关键词或去掉 --onsale 用 --all。
7. 若积分折扣返回 status=-1（如 商品[XXX]不存在），说明该条码在商品库中不存在，请核对从商品查询拿到的真实 Barcode 再查；多码时全部编码都须真实存在。
8. 若接口报错（status=-1 或网络错误），向用户说明错误原文，并提示检查 OpenId/Secret/工号；若报"验证数据签名失败"，确认是否误用了 --json-body（默认表单模式才正确）。

兜底与注意

• 字段名区分大小写且存在拼写/空格差异（如 GooodsItemTypename 三 o、Price 后带空格），脚本已做多候选键兜底。
• IsHide=true 表示下架/隐藏，false 表示在售；默认查询仅返回在售，避免团长推已下架品。
• IsBargain="True" 时优先展示 BargainPrice 并标注原价。
• 商品查询为分页列表接口，无独立"单品详情"端点；详情通过 Guid/Barcode 精确 where 实现，复用同一脚本即可。
• 积分/折扣查询（Get_PointAndDiscount）返回的系数为门店「会员营销/积分折扣设置」决定：若门店未配置，平台返回默认值（折扣系数 1.0=不打折、积分系数 0.0=不计分），属真实数据而非异常；带 --card-id 可查特定会员级别的系数。
• 会员查询（Get_MemberInfo）：cardId 支持卡号/手机号/Guid/OpenId/付款码；查不到返回 卡号不存在！（status=-1），属正常鉴权响应。
• ⚠️ 下单（Consume）是真实写操作：脚本默认仅预览、不发送；任何实际提交都必须用户明确确认且脚本带 --confirm。预览阶段会完整打印请求（含签名 URL 与 data），便于核对金额与明细，避免误下单。建议始终先传 --unique-code 幂等码，防止重复提交。
• 已用真实凭据实跑验证：① 商品查询（分类/关键词/条码/在售，共 162 个在售商品）；② 积分折扣（单品/整单/多码）；③ 会员查询（连通，返回 卡号不存在 验证了签名与端点）；④ 下单已做请求构造与签名验证，并按安全约定默认仅预览、未真实提交。四个接口平台均要求 data 以 data= 表单字段传参，脚本默认即如此。

Resources

scripts/

• query_goods.py — 通用 call_api/_build_request（签名+表单POST）+ 四接口：Get_GoodsItemsPagedV2 商品查询、Get_PointAndDiscount 积分折扣、Get_MemberInfo 会员查询、Consume 下单（默认预览、–confirm 提交）+ 友好表格/JSON 输出。

references/

• api_spec.md — 四个接口的完整契约（URL、鉴权、请求/返回字段、where 写法、积分折扣与会员/消费字段含义）。