版本：V1.0
适用环境：CRMEB标准版 v6 PHP / 花娃开放平台 API
文档状态：正式发布
第1章 项目概述 1.1 插件定位与目标 “CRMEB标准版 × 花娃开放平台插件”旨在打通CRMEB标准版商城系统与花娃鲜花B2B 供应链平台的数据链路。本插件的核心目标是实现CRMEB商城订单向花娃平台的自动化同 步、订单全生命周期状态的实时回调同步，以及售后与投诉流程的双向对接。通过本插件，商 户可在自有商城内无缝接入花娃的全国鲜花配送网络，实现“前端独立运营，后端供应链履 约”的商业模式。 1.2 适用环境 •商城系统：CRMEB标准版 v6 PHP •对接平台：花娃开放平台 API •运行环境：PHP >= 7.4，支持 cURL 扩展，服务器需开启 HTTPS 协议 1.3 整体架构 本插件采用三层架构设计，确保系统解耦与高可用性： 1. CRMEB商城层：作为业务入口，负责商品展示、用户下单及支付。通过CRMEB的事件/钩子机制触发订单同步，并接收回调数据更新本地订单状态。 2. 插件中间层（Plugin_Huawa）：作为数据转换与安全网关。负责将CRMEB订单模型转换为花娃API规范参数，执行MD5/SHA256签名，处理回调验签，并利用消息队列进行异步任务调度。 3. 花娃API层：作为履约与供应链核心。提供订单导入、状态查询、售后处理等RESTful接口，并通过Webhook机制向插件推送状态变更。 1.4 数据流向图 •正向订单同步流：用户在CRMEB下单并支付成功 → 触发订单支付成功事件 → 插件监听器捕获事件 → 组装参数并签名 → 调用花娃 /newapi/import 接口 → 获取花娃订单号并绑定本地订单。 •逆向状态回调流：花娃平台订单状态变更（如接单、配送、完成、拒单） → 发送 Webhook至插件 notify_url → 插件验签并解析状态 → 更新CRMEB本地订单状态 → 返回 {“data”:“HW_SUCCESS”}。 •售后处理流：用户在CRMEB申请退款/售后 → 插件映射售后原因枚举 → 调用花娃 / newapi/complain_save_new 接口 → 花娃处理并回调结果 → 插件同步售后状态至CRMEB。 第2章 环境准备 2.1 花娃API密钥申请 开发者需登录花娃开放平台后台，进入“API接入”或“开发者中心”模块，申请并获取以下核心凭证： - api_account：商户API账号，用于接口身份识别及签名生成。 - keycode：安全校验码，用于回调通知的验签及API请求签名。 2.2 CRMEB插件开发环境要求 •PHP版本：PHP 7.4 及以上版本。 •PHP扩展：必须开启 curl、json、mbstring、openssl 扩展。 •目录权限：插件根目录 Plugin_Huawa 及其子目录需具备可写权限（通常为 755 或 775），以 确保安装脚本执行及缓存写入。 2.3 服务器要求 •HTTPS协议：花娃回调通知强制要求目标地址必须为 HTTPS 协议，服务器需配置有效的 SSL证书。 •cURL支持：服务器需支持 cURL 且允许外网POST请求，用于调用花娃API。•时区设置：PHP时区需设置为 Asia/Shanghai，确保订单配送时间（songdate、 delivery_time）参数准确。 2.4 花娃后台配置 在花娃开放平台后台完成以下配置： - 开通“API导入”权限。 - 在“通知设置”中填写插件提供的回调地址（即 notify_url），确保地址可被外网正常访问。 第3章 CRMEB标准版插件开发规范 3.1 插件目录结构 插件根目录命名为 Plugin_Huawa，严格遵循以下目录树结构： Plugin_Huawa/ ├── controller/ # 控制器：后台管理页面及花娃回调接口 ├── core/ # 核心类：API客户端、签名工具、枚举定义 ├── events/ # 事件监听器：订单支付、取消等事件处理 ├── services/ # 服务层：业务逻辑封装、数据转换 ├── views/ # 后台视图模板（Vue+Element UI组件） ├── config/ # 配置文件：路由、菜单、事件注册 ├── install/ # 安装脚本：配置项注册、数据库迁移 ├── uninstall/ # 卸载脚本：清理配置及数据 └── plugin.json # 插件描述文件 3.2 插件描述文件 plugin.json plugin.json 是插件的身份标识，格式如下： { “name”: “Plugin_Huawa”, “title”: “花娃开放平台对接插件”, “description”: “实现CRMEB商城与花娃鲜花供应链的订单同步、状态回调及售后对接”, “version”: “1.0.0”, “author”: “Developer”, “type”: “logistics”, “require”: “>=6.0.0” } 3.3 扩展开发类型说明 CRMEB标准版支持登录、支付、商品采集、小票打印、上传、物流查询、短信等扩展类型。本插件核心功能为订单同步与履约状态追踪，属于“物流查询”类扩展的深度变体。在 plugin.json 中 type 字段声明为 logistics，同时作为独立业务扩展运行，不依赖系统原生物流模块。 3.4 配置的新增和使用方式 •新增配置：在 install/ 目录的安装脚本中，通过CRMEB系统配置服务注册配置项（如 api_account、keycode 等）。 •读取配置：在插件服务层或控制器中，通过CRMEB提供的配置读取方法获取，避免硬编 码。配置支持后台界面动态编辑并实时生效。 3.5 事件/钩子机制说明 CRMEB标准版采用事件监听器机制实现业务解耦。本插件需监听以下核心订单事件： - 订单支付成功后：触发向花娃导入订单的逻辑。 - 订单取消后：触发调用花娃 /newapi/order_cans 取消订单。 - 订单完成后：触发调用花娃 /newapi/order_receive 确认完成。 事件监听器需继承CRMEB基础事件类，并实现 handle 方法，在 config/ 目录的事件配置文件中完成绑定。 3.6 定时任务与消息队列 •消息队列：订单导入及状态同步属于耗时操作，必须通过CRMEB消息队列异步执行，避 免阻塞主交易流程。 •定时任务：用于补偿机制。当消息队列执行失败或回调丢失时，通过命令行定时任务定期 调用花娃 /newapi/orderlist 接口，主动拉取并同步订单最新状态。 第4章 花娃开放平台API规范 4.1 API基础说明 •请求地址：https://open.huawa.com/newapi/{action}（{action} 为具体接口名）•请求方式：POST •Content-Type：application/x-www-form-urlencoded •User-Agent：必须传入，不同接口需使用对应值（如 import_huawa、orderlist 等） 4.2 请求签名详解 所有API请求必须携带签名，步骤如下： 1. 参数排序：将所有业务参数（不含 _is_net）按参数名ASCII码升序排列。 2. 字符串拼接：将排序后的参数拼接为 key1=value1&key2=value2 格式。注意：不能进行urlencode，值前后不能加空格。 3. 计算签名： - MD5方式：以 api_account 为key，对拼接字符串生成MD5签名，再进行Base64编码，最后进行URL编码。 - SHA256方式：以 api_account 为key，对拼接字符串生成HMAC-SHA256签名，再进行Base64编码，最后进行URL编码。 4. 传递签名：将最终签名值赋给参数 sign 随请求发送。 4.3 通知签名与验签详解 花娃回调通知的验签步骤： 1. 参数排序：接收到的回调参数按字典序排序。 2. 拼接字符串：拼接为 key1=value1&key2=value2 格式，并在末尾追加 &key={安全校验码}。 3. MD5加密：对拼接后的完整字符串进行MD5加密。 4. 转大写：将MD5结果转为大写，与回调参数中的 sign 进行比对。 4.4 通知应答规范 插件在处理完回调逻辑后，必须返回以下JSON字符串，否则花娃平台将视为通知失败并持续重发： {“data”:“HW_SUCCESS”} 注意：字母必须全大写。 4.5 全部API接口清单
Action 方法 用途 是否必须实现
import POST 订单导入 是
orderlist POST 查询订单列表 是
order_cans POST 取消订单 是
order_receive POST 确认订单完成 是
assign_store POST 指定花店 否
assign_store_amount POST 指定花店配送(新) 否
get_city POST 获取城市列表 否
add_price POST 追加订单价格 否
select_price POST 选择报价花店 否
get_courier_info POST 获取第三方配送信息 否
get_rider_info POST 获取骑手信息 否
examine_image POST 花图审核 否
get_examine_reason POST 花图审核原因列表 否
publish_three_order POST 发布三方订单到抢单池 否
edit_order POST 修改订单 否
select_store_list POST 报价花店列表 否
storename_to_membername POST 店铺名转会员名 否
get_black_list POST 获取拉黑列表 否
complain_save_new POST 申请售后 是
cancel_refund POST 取消申请 否
get_account_balances POST 获取账号余额 否
4.6 订单状态枚举表
状态码 含义
PAY_ORDER_SUCCESS 支付订单成功
POINT_STORE_ORDER 指定订单给花店
STORE_REFUSE_ORDER 花店拒接指定单
STORE_ACCEPT_ORDER 花店接单
START_DELIVERY_ORDER 花店开始配送
ORDER_ACHIEVE 订单已送达
ORDER_FINISH 订单完成
CANCEL_ORDER 取消订单
APPLY_REFUND 申请退款
STORE_AGREE_REFUND 花店同意退款
STORE_REFUSE_REFUND 花店拒绝退款
APPLY_COMPLAINT 订单发起申诉
FINISH_COMPLAINT 申诉完成
STORE_SEND_IMG 花店上传花图
ORDER_STORE_PRICE 花店报价
STORE_CANCEL_ORDER 花店撤单
4.7 售后原因枚举表
原因码 含义
8013 协商退款
8001 漏单
8002 误单
8003 花材不符
8004 质量问题
8005 配材不符
8006 包装不符
8007 虚假操作
8008 恶意透露价格
8010 恶意骚扰
8011 贺卡问题
8012 第三方差评
4.8 投诉类型枚举表
类型码 含义
5013 退还订单金额30%
5015 退还订单金额50%
5018 退还订单金额80%
5000 全额退款
5005~5010 全额退款+赔付50%~100%
5100 部分退款自定义金额
第5章 后台设置页面设计 5.1 后台路由配置 在CRMEB admin路由文件中注册插件设置页面路由： - 路由路径：/plugin/huawa/config - 控制器：Plugin_Huawa- 方法：index（渲染设置表单）、save （保存配置） 5.2 设置表单字段设计
字段名 标题 类型 说明 默认值 是否必填
api_account 商户API账
号 Input 花娃开放平台分配的
API账号 - 是
keycode 安全校验码 Password 用于签名与回调验签的安全密钥 - 是
sign_type 签名方式 Select 可选：MD5 /
SHA256 MD5 是
notify_url 通知回调地
址 Input 花娃状态推送地址，需为HTTPS - 是
test_mode 测试模式 Switch 开启后不实
际推送订单，仅记录日志 false 否
default_good s_type默认商品类
型 Select 导入订单时的默认商品类型 - 是
default_deliv ery_time默认配送时
段 Select 未指定时段时的默认配送时间 - 是
default_exam ine_status默认花图审
核 Select 花图审核默
认状态 - 否
city_mapping 城市映射配
置 JsonEditor CRMEB省市区与花娃城
市的映射关 系 | {} | 否 | | product_cate | gory_mapping商品分类映 射 | JsonEditor | CRMEB商品分类与花娃 商品类型的 映射 | {} | 否 |
5.3 配置存储方案 •存储方式：所有配置项通过CRMEB系统配置表（eb_system_config）统一存储，键名以 pluginhuawa 为前缀。 •读取方式：在服务层通过CRMEB配置服务按前缀批量读取，避免多次数据库查询。•敏感信息：keycode 字段在后台展示时脱敏处理，仅在保存时更新。 5.4 测试连接功能 在后台设置页面顶部提供“测试连接”按钮，点击后执行以下逻辑： 1. 读取当前表单填写的 api_account、keycode、sign_type。 2. 调用花娃 /newapi/get_account_balances 接口。 3. 若返回成功，提示“连接成功，当前余额：XXX”；若失败，提示具体错误原因（如签名错误、账号不存在等）。 4. 此功能用于在正式启用插件前验证配置的正确性，避免订单同步失败。 CRMEB标准版 × 花娃开放平台插件开发文档（下） 第6章 数据映射规范 6.1 CRMEB订单 → 花娃导入订单参数映射表 为确保CRMEB标准版订单成功导入至花娃开放平台，需严格遵循以下字段映射与转换逻辑：
花娃参数 | CRMEB来源字
段 转换逻辑 必填 示例值
member_name 插件配置 读取插件后台配
置的花店会员名 是 huawa_fower_0
istimer delivery_time 根据配送时间判断，自定义时段为1，否则为0 是 1
delivery_time delivery_time 1:不限, 2:08-10
点… 99:自定义 是 3
songdate pay_time/
delivery_time istimer=1时为
Y-m-d H:i:s，否则为Y-m-d 是 2026-08-29
14:00:00
receive_name real_name 直接映射 是 张三
receive_mobile user_phone 直接映射 是 13800138000
area_info province, city,
area 拼接为”省 市 区”，以空格隔开 是 广东省 深圳市
南山区
address user_address 直接映射 是 科技园南路88
号
material goods_name/
spec_value 从商品花材描述
或规格中获取 是 红玫瑰11枝
quantity quantity 直接映射 是 1
sales_price price 商品销售价 是 199.00
order_amount pay_price 订单实付金额，
必须大于10元 是 199.00
remark remark 直接映射 否 请轻拿轻放
picurl goods_image 取商品主图
URL，需http开头 否 https://img.
com/flower.jpg
card_descriptio 贺卡内容字段 取订单关联的贺
卡内容 否 生日快乐
send_mobile user_phone(下
单人) 取下单人手机号 否 13900139000
seller_order order_sn CRMEB订单编
号 是 CR202608290001
is_payment order_status 已支付为1(等待接单)，未支付
为0(待发布) 是 1
goods_type cat_id 根据商品分类映
射 是 鲜花
examine_status 插件配置 取配置默认值，
如0不审核 是 0
more_goods_dataeb_order_goods urlencode(json_encode($goodsArray)) %7B%22goods_name…
6.2 花娃订单 → CRMEB订单状态映射表
花娃状态码/事件 CRMEB订单状态 说明
PAY_ORDER_SUCCESS 已支付 支付订单成功
STORE_ACCEPT_ORDER 待发货 花店接单
START_DELIVERY_ORDER 配送中 花店开始配送
ORDER_ACHIEVE 已完成 订单已送达
ORDER_FINISH 已完成 订单完成
CANCEL_ORDER 已取消 取消订单
APPLY_REFUND 退款中 申请退款
STORE_AGREE_REFUND 已退款 花店同意退款
STORE_REFUSE_REFUND 待处理 花店拒绝退款
STORE_CANCEL_ORDER 已取消 花店撤单
6.3 商品类型映射规则 花娃商品类型与CRMEB商品分类（eb_goods_category）的映射关系需在插件后台配置。默认规则如下： - 鲜花：映射至CRMEB分类ID 1001 - 蛋糕：映射至CRMEB分类ID 1002 - 礼品：映射至CRMEB分类ID 1003 6.4 配送时段映射规则
花娃delivery_time值 人类可读描述
1 不限
2 08:00-10:00
3 10:00-12:00
4 12:00-14:00
5 14:00-16:00
6 16:00-18:00
7 18:00-20:00
8 20:00-22:00
15 上午
16 下午
17 晚上
99 自定义时段
6.5 多商品处理方案 当CRMEB订单包含多个商品时，需组装 more_goods_data 参数： [ { “goods_name”: “红玫瑰11枝”, “quantity”: 1, “sales_price”: 199.00, “material”: “红玫瑰11枝，尤加利叶搭配” }, { “goods_name”: “巧克力蛋糕8寸”, “quantity”: 1, “sales_price”: 168.00, “material”: “黑巧克力，动物奶油” }] 处理逻辑：遍历 eb_order_goods 中属于当前订单的记录，组装为上述数组，执行 json_encode() 后再执行 urlencode()。 第7章 事件钩子设计 7.1 CRMEB事件监听器注册方式 在插件的 config/event.php 中注册监听器： return [ ‘bind’ => [ ‘OrderCreated’ => ::class, ‘OrderPaid’ => ::class, ‘OrderCompleted’ => ::class, ‘OrderCancelled’ => ::class, ],]; 7.2 订单创建事件处理流程 1.用户在CRMEB提交订单 2.系统触发 OrderCreated 事件 3.插件监听器捕获事件，获取 order_id 4.调用 OrderSyncService::transform() 转换数据 5.判断 is_payment：若为0，调用花娃 /newapi/import 接口，is_payment=0 6.记录同步结果至插件日志表 7.3 订单支付成功事件处理 当 is_payment=0 的订单支付成功后： 1. 触发 OrderPaid 事件 2. 查询花娃待发布订单（通过 seller_order 匹配） 3. 调用花娃接口更新订单状态为已支付（is_payment=1） 4. 更新CRMEB订单状态为”待发货” 7.4 花娃回调通知处理流程 1.接收POST请求，解析JSON格式数据 2.验证签名（使用配置的keycode） 3.幂等检查：通过 seller_order + order_state 查询本地处理记录4.状态映射：将花娃 order_state 转换为CRMEB订单状态5.更新 eb_order 表对应字段 6.返回 {“data”:“HW_SUCCESS”} 7.5 幂等防重设计 •唯一键：使用 seller_order（CRMEB订单号）+ order_state 作为幂等键 •状态机：仅允许合法状态流转（如：待发货→配送中→已完成），非法流转直接返回成功但 不更新 •分布式锁：高并发场景下使用Redis锁防止并发处理同一通知 7.6 定时任务设计
任务名称 执行频率 说明
SyncUnpaidOrders 每5分钟 同步未支付订单至花娃
RefreshStorePrice 每10分钟 刷新花店报价列表
RetryFailedSync 每15分钟 重试同步失败的订单
7.7 消息队列设计 •队列名称：huawa_order_sync •触发条件：订单同步API调用失败 •最大重试次数：3次 •退避策略：指数退避（1min → 5min → 15min） •死信处理：超过重试次数后标记为”同步失败”，触发管理员告警 第8章 核心模块详细设计 8.1 HuawaClient类设计 class HuawaClient { private $baseUrl = ‘https://open.huawa.com/newapi/’; private $keycode; public function __construct(string $keycode) { … } public function generateSign(array $params): string { … } public function request(string action,arrayparams, string $userAgent): array { … } public function importOrder(array $orderData): array { … } public function cancelOrder(string $orderSn): array { … } } 8.2 订单同步服务设计 OrderSyncService 核心方法： - transform(CrmebOrder $order): array - 数据转换 - validate(array data):bool-参数校验-sync(CrmebOrderorder): SyncResult - 执行同步 - handleImportResponse(array response,stringorderSn): void - 结果处理 8.3 回调通知控制器设计 NotifyController 路由：POST /plugin/huawa/notify 核心逻辑： 1. 获取原始POST body 2. 验签 → 失败返回403 3. 幂等检查 → 已处理返回HW_SUCCESS 4. 状态更新 → 事务内完成 5. 返回HW_SUCCESS 8.4 售后处理服务设计 AfterSaleService 处理： - applyRefund(string orderSn,stringreason, float amount)-申请退款-cancelRefund(stringorderSn) - 取消售后 - 映射售后原因枚举（8013-协商退款等） 8.5 辅助功能服务设计 •StoreService::getStores() - 获取花店列表并缓存 •CityService::getCityList() - 获取城市列表 •AccountService::getBalance() - 查询账户余额 第9章 异常处理与日志规范 9.1 异常分类
异常类型 说明 示例
网络异常 API请求超时/连接失败 cURL Error 28
API业务异常 花娃返回业务错误码 订单金额小于10元
数据异常 CRMEB数据缺失/格式错误 收货人手机号为空
签名异常 回调验签失败 Sign mismatch
9.2 异常处理策略 •网络异常：自动重试3次，间隔递增 •API业务异常：记录日志，不重试，标记订单为”同步失败”•数据异常：记录日志，触发管理员通知 •签名异常：直接返回403，记录安全告警日志 9.3 日志规范 •日志目录：runtime/log/huawa/ •日志级别： ‣INFO：正常同步/回调处理 ‣WARNING：重试/数据缺失 ‣ERROR：同步失败/验签失败 ‣CRITICAL：安全异常 •日志格式：[时间] [级别] [订单号] [动作] [详情] •保留策略：INFO保留30天，WARNING/ERROR保留90天，CRITICAL永久保留 9.4 失败重试策略 •队列重试：最多3次 •退避时间：60s → 300s → 900s •超过重试：写入 huawa_sync_fail 表，触发告警 9.5 监控告警 •关键异常：连续3次同步失败 → 发送钉钉/邮件告警 •安全告警：验签失败 → 即时告警 •业务告警：订单状态异常流转 → 每日汇总报告 第10章 测试方案 10.1 开发环境配置 •花娃测试账号：联系花娃商务获取沙箱环境keycode •CRMEB测试环境：本地Docker部署，数据库使用独立测试库•回调测试：使用ngrok暴露本地端口，配置花娃测试回调URL 10.2 单元测试用例设计
测试类 测试方法 预期结果
SignTest testGenerateSign 签名与官方示例一致
TransformTest testOrderTransform 字段映射正确
TransformTest testAreaInfoConcat 省市区空格拼接正确
NotifyTest testVerifySign 正确签名通过，错误签名拒绝
10.3 集成测试用例设计
场景 步骤 预期结果
订单同步正常 创建订单→支付→检查花娃 花娃订单创建成功
订单同步异常 创建金额为5元的订单 同步失败，日志记录
回调正常 模拟花娃推送接单通知 CRMEB订单状态更新
验签失败 篡改签名推送 返回403
重复通知幂等 同一通知推送2次 仅处理1次，第二次返回成功
10.4 联调测试清单 •☐ 订单创建并支付，花娃端可见订单 •☐ 花娃接单，CRMEB订单状态变为”待发货” •☐ 花店开始配送，CRMEB订单状态变为”配送中” •☐ 订单送达，CRMEB订单状态变为”已完成” •☐ 取消订单，双端状态同步 •☐ 申请退款，花娃端可见退款申请 •☐ 回调通知幂等性验证 第11章 部署上线Checklist 11.1 生产环境配置检查项
检查项 说明 验证方式
keycode配置 生产环境keycode正确 后台查看配置
回调URL HTTPS且可公网访问 curl测试
队列Worker 正常运行 ps aux | grep queue
日志目录 可写权限 检查runtime/log/huawa
定时任务 crontab配置正确 检查crontab -l
IP白名单 花娃回调IP已加白 防火墙规则检查
11.2 安全加固 •keycode保密：不硬编码，使用环境变量或加密配置•HTTPS强制：回调接口仅接受HTTPS •IP白名单：仅允许花娃回调服务器IP访问notify接口 •签名验证：所有回调必须验签 11.3 性能优化建议 •队列异步化：订单同步必须走队列，不阻塞下单流程 •缓存城市列表：Redis缓存，TTL 24小时 •连接池：使用Swoole/Guzzle连接池，减少TCP握手•批量查询：定时任务使用分批查询，避免大SQL 11.4 上线步骤 1.备份生产数据库 2.上传插件代码 3.执行数据库迁移（创建huawa相关表） 4.配置生产环境keycode和回调URL 5.启动队列Worker 6.配置crontab定时任务 7.执行联调测试清单 8.开放流量 11.5 回滚方案 1.停止队列Worker 2.禁用插件（后台操作） 3.恢复插件代码至上一版本 4.恢复数据库备份（如有数据污染） 5.重启服务并验证 第12章 商品映射与定价策略设计 12.1 设计背景与业务逻辑 在CRMEB商城与花娃供应链的对接场景中，存在一个核心的业务差异：用户在CRMEB商城下单时支付的商品售价（如199元），与花娃平台上的实际拿货成本（如120元）并不一致。插件在调用花娃API导入订单时，必须传递花娃侧的成本价，而非CRMEB侧的销售价。两者之间的差额即为商户的毛利空间。 本章节的设计目标是：在插件后台提供一套完整的”商品映射与定价策略”管理界面，让商户能够灵活配置CRMEB商品与花娃商品之间的对应关系、定价规则、配送费处理方式，并在花娃价格波动超过阈值时自动触发预警机制，确保商户不会因成本倒挂而亏损。 12.2 金额数据流向 完整的金额数据流向如下： ① 用户在CRMEB下单并支付 → 订单金额 = CRMEB商品售价（如199元），此金额仅存在于CRMEB系统内部，不会传递给花娃。 ② 插件拦截订单 → 根据CRMEB商品ID查找商品映射配置 → 获取花娃拿货价（如120元）。 ③ 插件调用花娃 /newapi/import 接口 → 传递参数 order_amount = 花娃拿货价（120元），而非CRMEB售价。 ④ 花娃平台按拿货价向商户扣款 → 商户的实际利润 = CRMEB售价 - 花娃拿货价 - 配送费。 ⑤ 插件在本地记录利润明细（售价、成本、毛利），供商户在后台查看经营报表。 12.3 下单策略设计 本插件提供两种下单策略，商户可根据业务场景灵活选择： （1）全自动下单模式（默认） 用户在CRMEB下单并支付成功后，插件自动调用花娃API创建订单。鲜花属于时效性极强的商品，自动下单可确保订单尽快进入花娃接单流程，减少花店拒单和配送超时的风险。 （2）价格预警后人工确认模式 当插件检测到花娃实时拿货价超过CRMEB售价的预设阈值（如90%）时，自动暂停该订单的同步，将订单标记为”价格异常-待处理”，并通过后台消息通知管理员。管理员可手动确认下单（接受当前成本价）或取消订单并退款。 策略配置项位于后台设置页的”下单策略”区域，提供”全自动”和”预警后人工确认”两个单选按钮，默认值为”全自动”。 12.4 数据库表设计 本模块涉及两张核心数据表：商品映射配置表（huawa_product_mapping）和利润明细日志表（huawa_price_log）。以下提供建表SQL。 1. 商品映射配置表（huawa_product_mapping） 建表SQL： CREATE TABLE huawa_product_mapping ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, plugin_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘插件ID’, crmeb_goods_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘CRMEB商品ID’, crmeb_goods_name VARCHAR(255) NOT NULL DEFAULT ’’ COMMENT ‘CRMEB商品名称快照’, crmeb_goods_image VARCHAR(500) NOT NULL DEFAULT ’’ COMMENT ‘CRMEB商品主图URL快照’, huawa_goods_id VARCHAR(100) NOT NULL DEFAULT ’’ COMMENT ‘花娃商品ID/编码’, huawa_goods_name VARCHAR(255) NOT NULL DEFAULT ’’ COMMENT ‘花娃商品名称快照’, mapping_type ENUM(‘fixed’,‘rule’) NOT NULL DEFAULT ‘fixed’ COMMENT ‘映射方式：fixed固定拿货价, rule浮动规则’, fixed_cost_price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘固定拿货价(mapping_type=fixed时生效)’, pricing_rule VARCHAR(50) NOT NULL DEFAULT ’’ COMMENT ‘定价规则：huawa_plus/N, huawa_minus/N, custom/N’, pricing_value VARCHAR(50) NOT NULL DEFAULT ’’ COMMENT ‘规则值’, delivery_fee_handling ENUM(‘include’,‘separate’,‘crmeb_free’) NOT NULL DEFAULT ‘include’ COMMENT ‘配送费处理’, delivery_fee DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘单独配送费金额’, auto_sync TINYINT(1) NOT NULL DEFAULT 1 COMMENT ‘是否自动下单：1=是, 0=否’, price_alert_ratio DECIMAL(5,2) NOT NULL DEFAULT 0.90 COMMENT ‘价格预警阈值(百分比)’, is_enabled TINYINT(1) NOT NULL DEFAULT 1 COMMENT ‘是否启用：1=是, 0=否’, sort INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘排序’, remark VARCHAR(500) NOT NULL DEFAULT ’’ COMMENT ‘备注’, create_time INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘创建时间’, update_time INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘更新时间’, UNIQUE KEY idx_crmeb_goods (crmeb_goods_id, plugin_id), KEY idx_is_enabled (is_enabled, plugin_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=‘花娃插件-商品映射配置表’; 2. 利润明细日志表（huawa_price_log） 建表SQL： CREATE TABLE huawa_price_log ( id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, plugin_id INT UNSIGNED NOT NULL DEFAULT 0, order_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘CRMEB订单ID’, order_sn VARCHAR(64) NOT NULL DEFAULT ’’ COMMENT ‘CRMEB订单编号’, goods_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT ‘CRMEB商品ID’, goods_name VARCHAR(255) NOT NULL DEFAULT ’’ COMMENT ‘商品名称快照’, crmeb_price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘CRMEB售价(用户支付)’, crmeb_freight DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘CRMEB运费’, huawa_cost DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘花娃拿货价’, huawa_delivery_fee DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘花娃配送费’, profit DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT ‘毛利=crmeb_price-huawa_cost-huawa_delivery_fee’, profit_rate DECIMAL(5,2) NOT NULL DEFAULT 0.00 COMMENT ‘利润率(百分比)’, sync_status TINYINT(1) NOT NULL DEFAULT 0 COMMENT ‘同步状态：0=待同步,1=已同步,2=预警待确认,3=失败’, sync_message VARCHAR(500) NOT NULL DEFAULT ’’ COMMENT ‘同步结果消息’, create_time INT UNSIGNED NOT NULL DEFAULT 0, UNIQUE KEY idx_order_goods (order_id, goods_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT=‘花娃插件-利润明细日志表’; 12.5 后台设置页面设计 本模块的后台设置页面位于CRMEB管理后台 → 插件 → 花娃开放平台对接 → 商品映射与定价策略。页面包含三个子页面：商品映射列表、新增/编辑表单、批量导入。 1. 商品映射列表页 列表页提供以下功能和字段：
字段名 说明 是否必填
商品名称 CRMEB商品名称，支持搜索 是
CRMEB商品ID 关联的CRMEB商品ID 是
花娃商品编码 花娃侧的商品ID/编码 是
映射方式 固定拿货价 / 浮动规则 是
拿货价/定价 根据映射方式显示对应值 是
配送费处理 含在拿货价 / 单独计算 / 免运费 是
自动下单 开关 是
价格预警阈值 百分比数值 否
状态 启用/禁用 是
操作 编辑 / 删除 -
列表页操作按钮：
按钮 功能说明
新增 跳转至新增表单页面
批量导入 下载Excel模板 → 填写映射关系 → 上传导入
批量导出 导出当前映射配置为Excel文件
测试连接 验证花娃API配置是否正确（复用全局测试连接）
- 新增/编辑表单设计 表单分为三个区域： （1）基本信息区
字段名 类型 说明
CRMEB商品 商品搜索选择器 搜索并选择CRMEB商城中的商品，选择后自动填充商品名称和主图
花娃商品编码 文本输入 花娃平台上的商品ID或编码，需手动输入
花娃商品名称 文本输入（只读） 可选：输入编码后通过花娃API自动获取商品名称
备注 文本域 用于备注特殊说明
（2）定价策略区
字段名 类型 说明
映射方式 单选：固定拿货价 / 浮动规则 选择定价策略类型
固定拿货价 数字输入（两位小数） 当映射方式为”固定拿货价”时生效，如120.00
定价规则 单选：花娃实时价+X / 花娃实时价-X / 自定义金额 当映射方式为”浮动规则”时生效
规则值 数字输入 定价规则中的X值，如+10表示花娃价加10元
配送费处理 单选：含在拿货价 / 单独计算 / 免运费 配送费的计算方式
单独配送费 数字输入（两位小数） 当配送费处理为”单独计算”时生效
（3）同步策略区
字段名 类型 说明
自动下单 开关 开启后支付成功自动同步至花娃，关闭则需手动确认
价格预警阈值 百分比输入（如90） 当花娃拿货价/CRMEB售价超过此值时，订单标记为”预警待确认” - 批量导入功能 提供Excel模板下载，模板包含以下列：
列名 说明 示例
CRMEB商品ID 必填 10086
花娃商品编码 必填 HW_8882
映射方式 必填：fixed或rule fixed
固定拿货价 映射方式为fixed时必填 120.00
定价规则 映射方式为rule时必填 huawa_plus
规则值 映射方式为rule时必填 10
配送费处理 可选：include/separate/crmeb_free include
单独配送费 配送费处理为separate时必填 5.00
自动下单 可选：1或0 1
价格预警阈值 可选，默认0.90 0.90
12.6 插件内部定价逻辑 插件在订单同步流程中，按照以下逻辑计算传递给花娃的金额： 步骤1：根据CRMEB商品ID查找映射配置 通过 crmeb_goods_id 查询 huawa_product_mapping 表，获取该商品的映射配置。若未找到配置，则使用全局默认配置（可在后台设置中配置默认拿货价），并将订单标记为”未配置映射-待处理”。 步骤2：根据映射方式计算花娃下单金额 （1）固定拿货价模式（mapping_type = fixed）： huawa_order_amount = fixed_cost_price（如120.00） （2）浮动规则模式（mapping_type = rule）： 插件需先调用花娃 /newapi/select_store_list 获取该订单的报价列表，取最低报价作为花娃实时价。 若 pricing_rule = huawa_plus：huawa_order_amount = 花娃实时价 + pricing_value 若 pricing_rule = huawa_minus：huawa_order_amount = 花娃实时价 - pricing_value 若 pricing_rule = custom：huawa_order_amount = pricing_value（自定义金额） （3）配送费处理： 若 delivery_fee_handling = include：配送费已含在拿货价中，不再额外收取 若 delivery_fee_handling = separate：huawa_order_amount += delivery_fee（单独加配送费） 若 delivery_fee_handling = crmeb_free：不收取配送费 步骤3：价格预警判断 计算 ratio = huawa_order_amount / crmeb_order_amount 若 ratio > price_alert_ratio（默认0.90）： 订单不自动同步，标记为”预警待确认” 写入 huawa_price_log 表，sync_status = 2 触发管理员后台消息通知 否则：正常同步 步骤4：记录利润明细 无论同步成功与否，均写入 huawa_price_log 表，记录：
字段 计算方式
crmeb_price CRMEB订单中该商品的售价
crmeb_freight CRMEB订单中的运费分摊
huawa_cost 花娃拿货价（步骤2计算结果）
huawa_delivery_fee 花娃配送费（若有）
profit crmeb_price - huawa_cost - huawa_delivery_fee
profit_rate profit / crmeb_price x 100
sync_status 0=待同步, 1=已同步, 2=预警待确认, 3=同步失败
sync_message 同步结果描述
12.7 金额分配全流程示例 完整的金额分配流程示例： ① 用户在CRMEB下单 → 支付199元（商品199 + 运费10） ② 插件拦截订单，根据商品ID查映射表 → 获取固定拿货价120元 ③ 插件判断：120 / 199 = 60.3% < 90%（预警阈值）→ 无需预警 ④ 插件调用花娃 /newapi/import，传递 order_amount = 120 ⑤ 花娃扣款120元 + 配送费5元 = 125元 ⑥ 插件记录利润：售价199 - 成本120 - 配送费5 = 毛利74元（利润率37.2%） ⑦ 商户实际收入 = 199（用户支付）- 125（花娃扣款）= 74元毛利 12.8 特殊场景处理方案 场景1：花娃价格波动导致成本倒挂 当花娃实时价上涨导致拿货价超过CRMEB售价时，插件不会直接取消订单，而是： - 自动暂停该订单的同步（标记为”预警待确认”） - 在CRMEB后台生成一条待办任务通知管理员 - 管理员可选择：A. 手动确认下单（接受当前成本价） B. 联系客户补差价 C. 取消订单退款 场景2：多商品订单中部分商品未配置映射 - 已配置的商品正常同步 - 未配置的商品所在订单整体标记为”部分未配置”，不自动同步 - 管理员可逐个补充映射或手动处理 场景3：CRMEB订单修改价格（管理员后台调价） - 若管理员在CRMEB后台修改了订单价格，插件应重新计算利润明细 - 若调价后触发价格预警（ratio > threshold），重新评估是否需要暂停同步 场景4：退款时的金额分配 - 用户在CRMEB申请退款时，插件调用花娃 /newapi/complain_save_new 申请售后 - 退款金额以花娃实际扣款金额为准，而非CRMEB售价 - 插件在 huawa_price_log 中追加退款记录，重新计算实际利润 12.9 经营报表设计（预留） 建议在插件后台增加一个简单的经营报表页面，展示以下数据：
报表维度 展示指标
今日/本周/本月概览 订单总数、总销售额（CRMEB）、总成本（花娃）、总毛利、平均利润率
商品维度排行 按毛利从高到低排列商品，展示每个商品的销量、销售额、成本、毛利
异常订单列表 展示所有”预警待确认”和”同步失败”的订单，支持批量处理
趋势图 按月/周展示销售额与毛利趋势折线图
第13章 用户自定义字段设计
13.1 设计背景
用户在CRMEB商城下单鲜花商品时，除了基本的收货人信息外，还需要填写多个自定义字段，这些字段需要完整传递到花娃平台，确保花店能按照用户要求制作和配送鲜花。本章详细定义前端字段规范、交互逻辑及后端数据映射方案。
13.2 CRMEB前端字段设计
在CRMEB商品详情页和下单页，需通过“商品属性”或“下单页自定义字段”功能新增以下表单字段：
13.2.1 用户上传参考图
字段名：reference_images 字段类型：多图上传（图片/文件） 是否必填：可选配置（商品级别设置是否必填） 字段说明：用户上传心仪的花束样式参考图，花店根据参考图制作相似花束。 存储位置：CRMEB云存储（OSS），下单时将图片URL传递给花娃。 前端展示：图片上传组件，支持多图上传，最多5张，显示缩略图预览。 限制条件： 格式：jpg / png 单张大小：≤ 4MB 总数量：1-5张 数据流向： 用户在前端选择图片 → CRMEB上传图片到云存储（OSS）。 下单时，CRMEB获取已上传图片的URL列表。 插件将图片URL以逗号分隔的方式传递给花娃的 picurl 参数。 花娃平台展示参考图给花店。
13.2.2 贺卡内容
字段名：card_description 字段类型：文本域（Textarea） 是否必填：可选配置 字段说明：用户在贺卡上想要写的内容（如“生日快乐，天天开心”）。 限制条件： 最大长度：100个字符（中文字符按2个计算）。 支持换行（最多3行）。 数据流向： 用户输入贺卡内容。 下单时，插件将贺卡内容传递给花娃的 card_description 参数。 花店根据贺卡内容制作实体贺卡。
13.2.3 下单人信息
字段名：send_name, send_mobile 字段类型：文本输入 是否必填：是（花娃要求必须传递） 字段说明： send_name：下单人的姓名（可以是昵称）。 send_mobile：下单人的手机号码（花店需要联系下单人时使用）。 数据流向： 用户填写下单人姓名和手机号。 插件将这两个字段传递给花娃的 send_name 和 send_mobile 参数。 如果用户未登录，需要额外展示登录/注册引导。
13.2.4 收货时间（配送时间）
字段名：delivery_date, delivery_time_slot 字段类型：日期选择器 + 时间段选择器 是否必填：是 字段说明： delivery_date：配送日期（YYYY-MM-DD）。 delivery_time_slot：配送时间段。 时间段选项（对应花娃的 delivery_time 枚举值）：
值 含义
1 不限时段
2 08-10点
3 10-12点
4 12-14点
5 14-16点
6 16-18点
7 18-20点
8 20-22点
15 上午
16 下午
17 晚上
99 自定义时间
定时配送开关：istimer（0-否，1-是） 如果用户选择了具体的配送日期和时间段 → istimer=1 如果用户选择“尽快配送”或不指定时间 → istimer=0, delivery_time=1
13.2.5 订单备注
字段名：remark 字段类型：文本域 是否必填：否 字段说明：用户给花店的额外备注（如“请务必保证花材新鲜”、“请准时送达”）。 限制条件：最大200字符。 数据流向：直接传递给花娃的 remark 参数。
13.3 CRMEB前端表单UI设计
13.3.1 字段排列顺序
收货人姓名（CRMEB原有字段） 收货人手机（CRMEB原有字段） 收货地址（CRMEB原有字段） 下单人姓名（新增） 下单人手机（新增） 配送时间（新增，含日期选择器+时间段选择器+定时配送开关） 用户上传参考图（新增，图片上传组件） 贺卡内容（新增，文本域） 订单备注（新增，文本域）
13.3.2 交互设计要点
配送时间： 默认选择“不限时段”，istimer 自动设为0。 用户选择具体日期后，显示时间段选择器。 已过去的日期不可选。 支持“尽快配送”和“定时配送”两种模式切换。 参考图上传： 提供示例图引导用户理解上传什么内容。 上传后显示缩略图，支持删除重选。 图片上传到CRMEB云存储，返回URL后缓存到 localStorage。 贺卡内容： 提供示例模板供用户选择（如“生日快乐”、“节日快乐”、“我爱你”等）。 实时显示已输入字数。
13.4 插件内部数据映射
13.4.1 CRMEB字段 → 花娃API参数完整映射表
CRMEB前端字段 花娃API参数 映射规则 是否必填
收货人姓名 receive_name 直接传递 是
收货人手机 receive_mobile 直接传递 是
收货人座机 receive_tel 用户填写则传，不填传空字符串 否
收货省市区 area_info 省+市+区，以空格隔开 是
收货详细地址 address 直接传递 是
下单人姓名 send_name 直接传递 是
下单人手机 send_mobile 直接传递 是
配送日期 songdate istimer=1时传 YYYY-mm-dd H:i:s 格式；istimer=0时传 YYYY-mm-dd 条件必填
配送时段 delivery_time 按上表枚举值映射 是
是否定时配送 istimer 用户选择定时→1，否则→0 是
自定义开始时间 s_time delivery_time=99时必填 条件必填
自定义结束时间 e_time delivery_time=99时必填 条件必填
参考图URL列表 picurl 多张以英文逗号分隔，http开头 否
贺卡内容 card_description 直接传递 否
订单备注 remark 直接传递 否
商品花材描述 material 从商品属性获取 否
商品数量 quantity 从购物车获取 是
发票信息 invoice_title 从订单发票信息获取 否
商家订单号 seller_order CRMEB订单号 否
是否支付 is_payment 0-不支付(待发布)，1-支付(直接发布) 是
商品类型 goods_type 默认“鲜花”，可配置映射 是
花图审核 examine_status 0-不审核，1-未提交，2-待审核，3-成功，4-失败 是
多商品信息 more_goods_data urlencode(json_encode(商品数组)) 是
是否自提 is_self_delivery 0-配送，1-自提 否
百度经度 x_axis 从地址解析获取 否
百度纬度 y_axis 从地址解析获取 否
13.4.2 多商品处理（more_goods_data）
当订单包含多个商品时，more_goods_data 的结构如下： [ {“goods_image”:“图片URL”,“quantity”:1,“goods_material”:“商品描述1”}, {“goods_image”:“图片URL”,“quantity”:2,“goods_material”:“商品描述2”}] 处理逻辑： 1. 遍历CRMEB订单中的每个商品。 2. 获取商品的图片URL（从商品主图或用户上传的参考图）。 3. 获取商品的花材描述（从商品属性或SKU描述）。 4. 获取商品数量。 5. 将数组 json_encode 后 urlencode。
13.5 配送时间处理逻辑
13.5.1 时间格式转换
用户选择 istimer delivery_time songdate格式
不限时段/尽快配送 0 1 传今天日期 YYYY-mm-dd
选择具体日期+时间段 1 对应时段值 YYYY-mm-dd HH:mm:ss
选择具体日期+自定义时段 1 99 YYYY-mm-dd HH:mm:ss
选择具体日期+上午 1 15 YYYY-mm-dd HH:mm:ss
13.5.2 时间验证规则
配送日期不能是已过去的日期。 如果是定时配送，配送时间必须晚于当前时间（至少提前30分钟）。 自定义时段（delivery_time=99）时，s_time 必须早于 e_time。 配送时间必须包含日期和时间（songdate 格式：YYYY-mm-dd H:i:s）。
13.6 图片处理逻辑
13.6.1 图片URL获取流程
用户在前端选择参考图 → 调用CRMEB上传接口 → 返回云存储URL。 将URL列表缓存到前端（localStorage / sessionStorage）。 下单时，从缓存中获取URL列表。 插件获取URL列表，以逗号分隔传递给花娃。
13.6.2 图片验证规则
格式验证：仅允许 jpg / png。 大小验证：单张 ≤ 4MB。 数量验证：最多5张。 URL验证：必须以 http:// 或 https:// 开头。 容错处理：如果用户未上传参考图，picurl 参数不传（花娃接口中为可选参数）。
13.7 下单人信息处理
13.7.1 数据来源优先级
用户手动填写的下单人信息（优先级最高）。 如果用户已登录，默认使用登录账号的昵称和手机号。 如果用户未登录，要求手动填写（必填）。
13.7.2 数据校验
手机号格式验证（中国大陆手机号）。 姓名不能为空，长度1-20字符。 如果下单人与收货人信息相同，可自动填充。
第14章 完整下单流程设计
14.1 端到端下单流程图
用户在CRMEB前端操作 插件后端处理 花娃平台 | | | | 1. 选择鲜花商品，加入购物车 | | | 2. 填写收货人信息 | | | 3. 填写下单人信息（姓名/手机） | | | 4. 选择配送日期和时间段 | | | 5. 上传参考图（可选） | | | 6. 填写贺卡内容（可选） | | | 7. 填写订单备注（可选） | | | 8. 提交订单并支付 | | | | 9. 支付成功事件触发 | | | 10. 插件获取订单全量数据 | | | 11. 查商品映射表获取成本价 | | | 12. 组装花娃API参数 | | | 13. 生成签名(sign) | | | 14. 调用花娃import接口 | | |————————–>| | | 15. 花娃返回订单ID/编号 | | | 16. 记录映射关系到本地表 | | | 17. 更新CRMEB订单状态 | | 18. 显示下单成功页面 | | | | 19. 花娃推送状态变更通知 | | |————————–>| | | 20. 接收通知并验签 | | | 21. 更新CRMEB订单状态 | | 22. 用户在订单详情页查看状态更新 | |
14.2 各阶段数据流转详情
阶段一：前端下单（用户侧）
用户在商品详情页选择商品规格（SKU）。 加入购物车，进入结算页。 结算页展示完整的表单（含新增字段）。 用户填写所有必填项。 提交订单 → 调用CRMEB下单接口。 选择支付方式（微信/支付宝）完成支付。
阶段二：插件处理（系统侧）
CRMEB支付成功事件触发。 插件监听事件，获取订单全量数据： 订单基本信息（订单号、金额、时间） 商品信息（商品ID、名称、数量、价格、图片） 收货人信息（姓名、手机、地址、省市区） 下单人信息（姓名、手机） 配送时间（日期、时段、是否定时） 参考图URL列表 贺卡内容 订单备注 发票信息 查询商品映射表，获取花娃对应商品和成本价。 组装花娃API请求参数。 生成HMAC-SHA256签名。 调用花娃 import 接口。 处理花娃返回结果： 成功：记录花娃订单ID，更新本地订单状态。 失败：记录错误日志，根据错误类型决定重试或标记异常。
阶段三：花娃处理（花店侧）
花娃接收订单（状态：待发布/待接单）。 花店接单。 花店制作花束。 花店上传花图（如需审核）。 花店配送。 配送完成。
阶段四：状态回调（花娃→CRMEB）
花娃订单状态变更时，向插件配置的通知地址推送JSON数据。 插件接收通知。 验证签名（MD5方式）。 解析订单状态。 更新CRMEB订单状态。 返回 {“data”:“HW_SUCCESS”}。
14.3 异常处理流程
14.3.1 下单失败处理
异常类型 处理策略
花娃API超时 重试3次（间隔5秒），仍失败则标记“待人工处理”
花娃返回错误码 记录错误信息，根据错误码分类处理
余额不足 订单标记为“待发布”，通知管理员充值
商品未映射 订单标记为“待人工处理”，通知管理员配置映射
网络异常 重试3次，仍失败则标记“待人工处理”
14.3.2 回调失败处理
异常类型 处理策略
验签失败 记录日志，返回失败，花娃会重试3次
订单号不存在 记录日志，返回失败，花娃会重试3次
数据库写入失败 记录日志，返回失败，花娃会重试3次
14.4 幂等性设计
每个CRMEB订单号（seller_order）在全球唯一。 花娃返回的 order_sn 与CRMEB订单号建立映射关系。 收到重复通知时，检查是否已处理过该订单号。 已处理的订单直接返回 HW_SUCCESS，不重复执行业务逻辑。
第15章 后台管理功能设计
15.1 新增配置页面
在花娃插件的后台设置页面，新增以下配置区域：
15.1.1 字段配置区域
配置项 类型 说明 默认值
参考图上传是否必填 开关 控制前端是否显示必填标记 关闭
参考图最大数量 数字 1-10 5
贺卡内容是否必填 开关 控制前端是否显示必填标记 关闭
贺卡最大字符数 数字 50-200 100
订单备注是否必填 开关 控制前端是否显示必填标记 关闭
订单备注最大字符数 数字 50-500 200
下单人信息是否必填 开关 控制前端是否显示必填标记 开启
配送时间是否必填 开关 控制前端是否显示必填标记 开启
默认配送时段 下拉选择 未选择时的默认值 1（不限时段）
是否自动下单 开关 支付成功后是否自动调用花娃API 开启
自动下单失败重试次数 数字 0-5 3
重试间隔（秒） 数字 5-60 5
15.2 订单管理页面
在花娃插件的订单管理页面，新增以下展示字段：
字段 说明 数据来源
下单人姓名 下单人姓名 本地记录
下单人手机 下单人手机号 本地记录
配送日期 配送日期 本地记录
配送时段 配送时间段 本地记录
参考图 用户上传的参考图 本地记录的URL列表
贺卡内容 贺卡上的文字 本地记录
订单备注 用户备注 本地记录
花娃订单ID 花娃返回的订单ID 花娃API返回
花娃订单编号 花娃返回的订单编号 花娃API返回
成本价 花娃实际扣款金额 花娃API返回
毛利 CRMEB售价 - 成本价 计算得出
下单状态 同步状态 本地记录
同步时间 调用花娃API的时间 本地记录
花娃状态 花娃侧订单状态 花娃回调/查询
15.3 订单详情页面
在订单详情页面，以卡片形式展示所有新增字段： 下单信息卡片：下单人姓名、下单人手机、下单时间。 配送信息卡片：配送日期、配送时段、是否定时。 用户素材卡片：参考图（可点击放大预览）、贺卡内容、订单备注。 费用信息卡片：CRMEB售价、花娃成本价、毛利、运费。 同步信息卡片：花娃订单ID、花 ## 第16章 字段校验与数据完整性保障
16.1 前端校验规则
所有用户填写的自定义字段必须在CRMEB前端进行实时校验，确保数据格式正确后再提交到后端。
字段 校验规则 错误提示
收货人姓名 非空，1-50字符 请填写收货人姓名
收货人手机 中国大陆手机号格式 请填写正确的手机号码
收货地址 非空 请填写收货地址
省市区 三级联动，均非空 请选择完整的省市区
下单人姓名 非空，1-20字符 请填写下单人姓名
下单人手机 中国大陆手机号格式 请填写正确的手机号码
配送日期 不能是已过去的日期 配送日期不能早于今天
配送时段 定时配送时必须选择 请选择配送时间段
参考图 jpg/png，单张≤4MB，最多5张 请上传有效的图片
贺卡内容 最多100字符 贺卡内容不能超过100字符
订单备注 最多200字符 订单备注不能超过200字符
16.2 后端校验规则
后端在接收订单数据后，需进行二次校验，防止前端校验被绕过。
校验项 规则 失败处理
必填字段完整性 收货人姓名/手机/地址、下单人姓名/手机、配送时间 返回错误，不继续处理
手机号格式 正则匹配中国大陆手机号 返回错误
配送时间合理性 不能是过去的时间，定时配送需提前≥30分钟 返回错误
订单金额 必须大于10元（花娃接口要求） 标记为异常订单
图片URL格式 必须以http://或https://开头 过滤无效URL
商品映射配置 每个商品必须有对应的花娃映射 标记为”未配置映射-待处理”
签名验证 回调通知必须验签通过 返回403，记录安全日志
16.3 数据兜底策略
场景 兜底方案
前端未传picurl 使用商品主图作为默认图片
前端未传贺卡内容 传空字符串，花娃不显示贺卡
前端未传订单备注 传空字符串
省市区缺失 使用收货地址中的省市区信息补全
配送时间未选择 使用后台配置的默认配送时段
商品映射未配置 使用全局默认配置，标记订单为”待处理”
花娃API超时 重试3次后标记为”待人工处理”
回调验签失败 直接拒绝，记录安全告警日志
16.4 数据一致性保障
1.订单号唯一性：CRMEB订单号（seller_order）作为全局唯一标识，确保与花娃订单号的一一对应关系。
2.状态同步幂等性：使用 seller_order + order_state 作为幂等键，防止重复通知导致状态错乱。
3.事务一致性：订单同步成功后，必须在同一事务内更新CRMEB订单状态和写入插件日志表，确保数据一致性。
4.对账机制：每日凌晨通过定时任务调用花娃 /newapi/orderlist 接口，拉取所有订单进行对账，发现状态不一致时自动修复或告警。
附录
附录A：数据库表结构
A.1 huawa_order_extend（订单扩展信息表）
该表用于存储CRMEB订单在插件处理过程中产生的扩展信息。
CREATE TABLE huawa_order_extend (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
order_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'CRMEB订单ID',
order_sn VARCHAR(64) NOT NULL DEFAULT '' COMMENT 'CRMEB订单编号',
huawa_order_id VARCHAR(100) NOT NULL DEFAULT '' COMMENT '花娃订单ID',
huawa_order_sn VARCHAR(100) NOT NULL DEFAULT '' COMMENT '花娃订单编号',
send_name VARCHAR(50) NOT NULL DEFAULT '' COMMENT '下单人姓名',
send_mobile VARCHAR(20) NOT NULL DEFAULT '' COMMENT '下单人手机',
delivery_date VARCHAR(20) NOT NULL DEFAULT '' COMMENT '配送日期',
delivery_time VARCHAR(10) NOT NULL DEFAULT '' COMMENT '配送时段',
istimer TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否定时配送',
reference_images TEXT COMMENT '参考图URL列表（逗号分隔）',
card_description VARCHAR(500) NOT NULL DEFAULT '' COMMENT '贺卡内容',
remark VARCHAR(500) NOT NULL DEFAULT '' COMMENT '订单备注',
sync_status TINYINT(1) NOT NULL DEFAULT 0 COMMENT '同步状态：0=待同步,1=已同步,2=预警待确认,3=失败',
sync_message VARCHAR(500) NOT NULL DEFAULT '' COMMENT '同步结果消息',
sync_time INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '同步时间',
huawa_status VARCHAR(50) NOT NULL DEFAULT '' COMMENT '花娃侧订单状态',
cost_price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '花娃成本价',
profit DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '毛利',
create_time INT UNSIGNED NOT NULL DEFAULT 0,
update_time INT UNSIGNED NOT NULL DEFAULT 0,
UNIQUE KEY idx_order_sn (order_sn),
KEY idx_huawa_order_sn (huawa_order_sn),
KEY idx_sync_status (sync_status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='花娃插件-订单扩展信息表';
A.2 huawa_sync_fail（同步失败记录表）
CREATE TABLE huawa_sync_fail (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
order_id INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'CRMEB订单ID',
order_sn VARCHAR(64) NOT NULL DEFAULT '' COMMENT 'CRMEB订单编号',
fail_count INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '失败次数',
last_fail_time INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '最后失败时间',
error_message TEXT COMMENT '错误信息',
retry_status TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否已重试: 0=未重试, 1=已重试',
create_time INT UNSIGNED NOT NULL DEFAULT 0
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='花娃插件-同步失败记录表';
附录B：前端表单HTML结构示例
以下为CRMEB下单页新增自定义字段的Vue模板结构示例：
附录C：花娃API接口完整清单
Action 方法 路径 用途 是否必须实现
import POST /newapi/import 订单导入 是
orderlist POST /newapi/orderlist 查询订单列表 是
order_cans POST /newapi/order_cans 取消订单 是
order_receive POST /newapi/order_receive 确认订单完成 是
assign_store POST /newapi/assign_store 指定花店 否
assign_store_amount POST /newapi/assign_store_amount 指定花店配送(新) 否
get_city POST /newapi/get_city 获取城市列表 否
add_price POST /newapi/add_price 追加订单价格 否
select_price POST /newapi/select_price 选择报价花店 否
get_courier_info POST /newapi/get_courier_info 获取第三方配送信息 否
get_rider_info POST /newapi/get_rider_info 获取骑手信息 否
examine_image POST /newapi/examine_image 花图审核 否
get_examine_reason POST /newapi/get_examine_reason 花图审核原因列表 否
publish_three_order POST /newapi/publish_three_order 发布三方订单到抢单池 否
edit_order POST /newapi/edit_order 修改订单 否
select_store_list POST /newapi/select_store_list 报价花店列表 否
storename_to_membername POST /newapi/storename_to_membername 店铺名转会员名 否
get_black_list POST /newapi/get_black_list 获取拉黑列表 否
complain_save_new POST /newapi/complain_save_new 申请售后 是
cancel_refund POST /newapi/cancel_refund 取消申请 否
get_account_balances POST /newapi/get_account_balances 获取账号余额 否
附录D：订单状态枚举完整对照表
花娃状态码 含义 CRMEB订单状态 说明
PAY_ORDER_SUCCESS 支付订单成功 已支付 支付成功
POINT_STORE_ORDER 指定订单给花店 待发货 指定花店
STORE_REFUSE_ORDER 花店拒接指定单 待处理 花店拒绝
STORE_ACCEPT_ORDER 花店接单 待发货 花店接单
START_DELIVERY_ORDER 花店开始配送 配送中 花店开始配送
ORDER_ACHIEVE 订单已送达 已完成 配送完成
ORDER_FINISH 订单完成 已完成 订单完成
CANCEL_ORDER 取消订单 已取消 取消订单
APPLY_REFUND 申请退款 退款中 申请退款
STORE_AGREE_REFUND 花店同意退款 已退款 退款成功
STORE_REFUSE_REFUND 花店拒绝退款 待处理 退款被拒
APPLY_COMPLAINT 订单发起申诉 申诉中 发起申诉
FINISH_COMPLAINT 申诉完成 申诉完成 申诉处理完毕
STORE_SEND_IMG 花店上传花图 - 花店上传花图
ORDER_STORE_PRICE 花店报价 - 花店报价
STORE_CANCEL_ORDER 花店撤单 已取消 花店撤单
附录E：售后原因枚举表
原因码 含义
8013 协商退款
8001 漏单
8002 误单
8003 花材不符
8004 质量问题
8005 配材不符
8006 包装不符
8007 虚假操作
8008 恶意透露价格
8010 恶意骚扰
8011 贺卡问题
8012 第三方差评
附录F：投诉类型枚举表
类型码 含义
5013 退还订单金额30%
5015 退还订单金额50%
5018 退还订单金额80%
5000 全额退款
5005~5010 全额退款+赔付50%~100%
5100 部分退款自定义金额
附录G：配送时段枚举表
delivery_time值 含义
1 不限
2 08:00-10:00
3 10:00-12:00
4 12:00-14:00
5 14:00-16:00
6 16:00-18:00
7 18:00-20:00
8 20:00-22:00
15 上午
16 下午
17 晚上
99 自定义时段
附录H：FAQ常见问题
Q1：花娃回调通知为什么会被重复推送？
花娃平台在发送通知后，如果未在3秒内收到HTTP 200 + {“data”:“HW_SUCCESS”}的响应，会认为通知失败并在短时间内重试3次。因此，回调接口必须保证幂等性，同一订单的同一状态只处理一次。
Q2：签名验证失败怎么办？
检查以下几点：1）keycode配置是否正确；2）参数排序是否正确（ASCII升序）；3）拼接字符串时是否有空格或urlencode；4）MD5结果是否转大写。
Q3：订单同步失败后如何手动重试？
在后台订单管理页面，找到同步失败的订单，点击”手动重试”按钮。系统会重新调用花娃API进行同步，最多重试3次。
Q4：如何查看插件运行日志？
日志文件存储在 runtime/log/huawa/ 目录下，按日期分割。可通过后台”日志管理”页面查看，或直接SSH登录服务器查看日志文件。
Q5：花娃价格变动后如何更新成本价？
在后台”商品映射与定价策略”页面，找到对应商品的映射配置，修改”固定拿货价”或”定价规则”，保存后即时生效。
Q6：支持多商品订单吗？
支持。当订单包含多个商品时，插件会自动组装 more_goods_data 参数，将每个商品的图片、数量、描述信息传递给花娃。
Q7：定时配送和尽快配送有什么区别？
定时配送（istimer=1）：用户选择具体的配送日期和时间段，花娃按指定时间配送。尽快配送（istimer=0）：花娃尽快安排配送，配送时段由 delivery_time 参数指定。
Q8：回调地址配置后如何测试？
在后台设置页面点击”测试连接”按钮，系统会向配置的回调地址发送一个测试请求，验证地址是否可访问。
文档结束
