⚠️ 敏感信息（HMAC 密钥、服务器凭证等）一律线下同步，不通过任何文档与页面传递。
1. 整体模型：三层角色怎么分工
平台（GR 侧） 搬家服务商（商家） 客户
───────────────────── ───────────────────── ───────────────
定类目 / 子类目 / 标准品 SPU 维护自己可售的 SKU 在平台 C 端浏览选品
C 端频道展示与流量 （选 SPU + 定城市 + 定价） 点"下一步"唤起商家小程序
订单状态聚合、"我的订单" 小程序内预约 / 收款 / 履约 在商家小程序内完成下单支付
平台级认证（白名单 / 资质） 回调同步订单状态给平台 回平台 C 端跟踪进度
一句话分工：平台管标准、商家管售卖与履约、客户信息由商家自己的小程序收集（详见第 4 章）。
2. 商品模型约定（SPU / SKU）
2.1 概念分层（先对齐叫法）
| 概念 | 归属层 | 谁定义 | 含义 |
|---|
| 类目（大类） | 平台 | 平台 | 保洁 / 维修 / 搬家 / 保姆；ID：cleaning / repair / moving / nanny |
| 子类目 | 平台 | 平台 | 搬家下 6 个子类：居民搬家 / 长途搬家 / 钢琴搬运 / 企业搬迁 / 日式搬家 / 搬货上下楼 |
| SPU（标准服务品） | 平台 | 平台统一设计，商家不可改标准 | 规格、标准时长、参考起价、服务流程、服务者最低等级。跨商家口径一致、可比价 |
| SKU（可售单元） | 商家 | 商家实例化 | 选 SPU → 定城市 → 定售价 → 上下架 → 配小程序跳转 path/query →（可选）绑服务者。C 端真正可下单的最小单元 |
命名澄清：平台侧的「标准品（SPU）」与商家侧的「可售商品（SKU）」是两层概念，叫法以本文档为准。
2.2 搬家 SPU 现网清单（直接引用，勿自造）
| SPU slug | 名称 | 规格 | 参考起价 | 计价 | 标准时长 | 服务者等级 |
|---|
| moving-city-standard | 居民搬家·同城 | 金杯车·2 名师傅 | ¥398 起 | /车次 | 180 min | L2 |
| moving-japanese-full | 日式搬家·全包 | 打包收纳 + 还原归位 | ¥1680 起 | /次 | 480 min | L4 |
| moving-longhaul | 长途搬家·跨城 | 厢式货车·300km+ | ¥1200 起 | /车次 | 600 min | L3 |
| moving-piano | 钢琴搬运·专业 | 立式/三角钢琴可接 | ¥800 起 | /次 | 120 min | L4 |
| moving-office | 企业搬迁·整体 | 办公整体搬迁方案 | ¥2800 起 | /项目 | 720 min | L4 |
| moving-updown | 搬货上下楼·计件 | 无电梯搬运·计件 | ¥200 起 | /次 | 120 min | L2 |
- SPU 的
price_from 只是参考起价/展示价，不是商家售价；售价由商家在 SKU 上自定。
- SPU 经接口
POST /api/juzhu/jiazheng/vendor/skus/list 拉取，创建 SKU 时填 channel_sku_id 引用。
- 现场自定义项（楼层费、超距费、大件加价、打包费）在商家自己的小程序内按行规报价收款，平台不干预。
2.3 商家 SKU 约定（决定 C 端能不能看到、怎么跳转）
| 约定项 | 规则 | 违反后果 |
|---|
| 城市维度 | SKU 必须带 city_id，且只能属于被授权城市 | 未覆盖城市 C 端不展示 |
| 关联 SPU | channel_sku_id 必须关联平台 SPU（详情页蓝色 SPU 标签） | 未关联商品不上 C 端 |
| 状态 | on 上架 / off 下架 / sold_out 售罄 | 非 on 不展示 |
| 跳转参数 | path、query 必须非空 | 下单后无法进入商家小程序商品页 |
| 价格 | price/original_price 单位一律分（¥128 = 12800） | 金额错位 |
| 服务者（可选） | worker_ids 绑定本店已认证服务者 | 仅影响详情页展示 |
| 删除 | 无物理删除，接口删除 = 置 off 软删 | — |
3. 商家（vendor）信息约定
平台为每家商家分配唯一商家 ID（vendor_id，随接入单告知）与 HMAC 密钥。商家主数据约定：
| 字段 | 约定 |
|---|
| type | 单值：cleaning / repair / moving / nanny 四选一；搬家填 moving（单值驱动 B 端产品列表） |
| name | C 端展示名（如"某某搬家"） |
| city_ids | 服务城市（逗号分隔 city_id）；现网：1 沈阳 / 2 贵阳 / 3 北京 / 4 上海，新增城市需平台先建 |
| vendor_no | 商家编码（可选，运营标注用） |
| whitelist_id / badges | 平台认证标识：whitelist 白名单、backcheck 实地核查、top10 等；决定 C 端认证徽章 |
| start_price / unit / hours | C 端商家卡片展示：起价（如 398）、计价（车次）、营业时间（如 06:00-22:00） |
| hmac_key | HMAC-SHA256 密钥，64 位 hex（openssl rand -hex 32）；仅平台与商家线下互知 |
| url_link | 商家提供的小程序 URL Link 生成接口完整地址（必配） |
| order_detail_url | 商家提供的订单详情查询接口完整地址（可选，不配则 C 端详情不实时覆盖） |
| status / sort_order | active 启用；排序一般与 vendor_id 同值 |
入驻需提供：公司/品牌名、服务城市、展示素材（logo、起价、营业时间）、小程序 AppID、商品页 path/query 样例、URL Link 与订单详情接口地址、联调联系人。
4. 客户（下单）信息约定
平台不代收、不向商家透传客户联系信息。真实链路：C 端用户看到 SKU → 点"下一步" → 平台调商家 url_link 接口（只传 path、query、order_ref）→ 生成 weixin:// 链接唤起商家小程序 → 客户在商家小程序内自行填写预约信息并支付 → 商家回调平台同步状态。
- 客户信息由商家小程序收集（平台不存储、不参与、不转发）。搬家字段参考：搬出/搬入地址、楼层与电梯、搬家日期与时段、车型（面包车/金杯/厢货/纯人力）、大件物品（冰箱/洗衣机/钢琴…）、打包服务、联系电话、备注。
- 平台侧每单只记订单标识与流转状态，供 C 端"我的订单"展示：
order_ref（GR + 时间戳 + 序号，如 GR202608071429360148）、vendor_oid（商家单号）、user_id（C 端当前为模拟值 demo_user_001）、sku/city 快照、fee（分）、状态时间轴。
- vendor_oid 一致性：首次 paid 回调平台用
order_ref 匹配并写入 vendor_oid；此后所有回调需 order_ref + vendor_oid 联合匹配。
- 服务者电话平台展示统一掩码脱敏（如 139****5678），商家回调
worker.phone 请给完整号，展示层由平台处理。
订单状态机
pending（C 端不可见）→ paid（必带 fee）→ assigned（必带 worker：姓名/电话/预计上门）
→ serving → completed
cancelled：终态，必带 cancel_reason，任意状态可取消，回调须按序推进
5. 接口与安全约定（概览）
| 方向 | 接口 | 说明 |
|---|
| 平台 → 商家（开放） | 城市 / 类目 / SPU / 产品 列表查询 | 商家自维护 SKU 用 |
| 平台 → 商家（开放） | 产品 create / update / status / delete | 商家操作自己的 SKU |
| 商家 → 平台 | POST /api/juzhu/callback | 订单状态回调（paid/assigned/serving/completed/cancelled） |
| 平台 → 商家 | URL Link 生成接口（商家提供） | 平台传 path/query/order_ref，商家回 weixin:// 链接（code=200 成功） |
| 平台 → 商家 | 订单详情查询接口（商家提供，GET） | 客户打开订单详情时平台静默同步最新状态 |
- 认证：所有请求体带 HMAC-SHA256 签名：含 vendor_id → 移除 sign → 加毫秒 timestamp → 嵌套对象递归展平（. 分层）→ 去空值 → 按 key 字典序排序 → k1=v1&k2=v2 拼接 → 以 hmac_key 做 HMAC-SHA256 取 hex 小写 → 随请求发送。验签失败 401。
- 防重放：timestamp 毫秒时间戳，过期或重复被拒。
- IP 白名单：平台调用商家两个接口的出站 IP 需商家加白，实际 IP 以平台日志提示为准。
- 错误码：0 成功 / 400 参数缺失 / 401 签名失败 / 404 订单或产品不存在 / 500 服务端错误。
6. 环境与联调流程
- 联调环境：以接入单下发为准（当前演示站 https://sytest.meizu.life，开放接口同源
/api/juzhu/*；小程序跳转依赖 weixin:// 协议，需系统浏览器打开，勿在微信内直接打开）。
- 测试城市：1 沈阳 / 2 贵阳 / 3 北京 / 4 上海；商品按"城市 + 类目"双维度展示。
- 联调顺序：商家信息收集 → 平台侧配置（vendor 行 + 密钥）→ 商家实现签名与接口 → 签名自测 → 产品 CRUD 联调 → 下单全链路（wechat-link → url_link → paid 回调）→ 订单状态逐级推进核对 → 订单详情同步 → C 端回归验收。参考先例：41 来来（保洁）、42 蓝犀牛（搬家）。
- C 端验收点：B 端商品页能筛到自家商品且 SPU 蓝色已关联、状态上架、价格正确、path/query 非空；C 端列表/详情正常出卡；下单唤起自家小程序；支付后回调 paid，"我的订单"金额正确；逐级推进 assigned / serving / completed；取消单显示原因。
- 金额核对：回调与产品接口金额单位是分（12800 = ¥128），C 端自动转元展示。
7. 约定速查表
| 事项 | 约定值 |
|---|
| 商家类目 type | moving（单值） |
| 平台标准品 | 引用现网 6 个搬家 SPU（见 2.2），不自造 |
| 商家可售单元 | SKU = SPU + city_id + 售价（分）+ 状态 + path/query |
| C 端可见三条件 | 城市覆盖 + 已关联 SPU + status=on |
| 金额单位 | 分（页面展示自动转元） |
| 时间格式 | YYYY-MM-DD HH:mm:ss；timestamp 用毫秒 |
| 订单号 | 平台 order_ref（GR+…）；商家 vendor_oid；首次 paid 绑定后联合匹配 |
| 密钥 | HMAC-SHA256，64 位 hex，线下互传，禁止明文入库/入文档 |
| 客户信息 | 平台不代收不转发；商家小程序内自行收集 |
| 号码展示 | 平台侧统一掩码脱敏 |
| 测试地址 | 以接入单下发为准（演示站 sytest.meizu.life） |