diff --git a/.gitignore b/.gitignore index 45a47d2..366116a 100644 --- a/.gitignore +++ b/.gitignore @@ -16,5 +16,4 @@ application/database.php sync_config.jsonc __MACOSX/ *.code-workspace -plan/chat-backup/**/*.jsonl -plan/chat-backup/subagents/ \ No newline at end of file +/plan/ \ No newline at end of file diff --git a/deploy.sh b/deploy.sh index cf91055..ff51cca 100644 --- a/deploy.sh +++ b/deploy.sh @@ -31,6 +31,12 @@ echo "[${DATE}] 执行 git fetch origin ${TARGET_BRANCH}..." >> "${LOG_FILE}" git fetch origin "${TARGET_BRANCH}" >> "${LOG_FILE}" 2>&1 git reset --hard "origin/${TARGET_BRANCH}" >> "${LOG_FILE}" 2>&1 +# plan/ 仅本地文档，不入库；清理服务器上历史残留 +if [ -d "${DEPLOY_DIR}/plan" ]; then + rm -rf "${DEPLOY_DIR}/plan" + echo "[${DATE}] 已删除 plan/ 目录（不入库）" >> "${LOG_FILE}" +fi + # 恢复敏感配置文件（若被覆盖或缺失） if [ -f "application/database.php.deploy_bak" ]; then cp -p application/database.php.deploy_bak application/database.php diff --git a/plan/README.md b/plan/README.md deleted file mode 100644 index 490843a..0000000 --- a/plan/README.md +++ /dev/null @@ -1,105 +0,0 @@ -# 厨房商城（chufang.gynhc.com）项目计划文档 - -本目录存放**本项目（厨房/宥川商城）**相关 Cursor 计划文档、对话备份与实施进度，便于团队查阅与版本管理。 - -> 源文件来自 Cursor Plans / Agent Transcripts -> 最近更新：2026-09-12 -> **注意：「飞天」系列为另一独立酒类项目，相关计划不在本目录。** - ---- - -## 快速入口 - -| 文档 | 说明 | -|------|------| -| [实施进度汇总.md](./实施进度汇总.md) | **当前实施进度与部署清单（推荐阅读）** | -| [chat-backup/对话摘要-2026-09-12打包.md](./chat-backup/对话摘要-2026-09-12打包.md) | **近期全部会话可读摘要（2026-09-04~12）** | -| [chat-backup/对话摘要-区域代理实施.md](./chat-backup/对话摘要-区域代理实施.md) | 区域代理专项对话摘要 | - ---- - -## 对话备份 - -| 文件/目录 | 说明 | -|-----------|------| -| [chat-backup/](./chat-backup/) | **仅保留 Markdown 摘要**（原始 JSONL 不入库，见 `.gitignore`） | - -会话 ID 与主题对照见 [对话摘要-2026-09-12打包.md](./chat-backup/对话摘要-2026-09-12打包.md) 索引表。 - ---- - -## 支付 / 分账 / 进件 - -| 文档 | 说明 | -|------|------| -| [汇付小程序支付对接_c945b5d0.plan.md](./汇付小程序支付对接_c945b5d0.plan.md) | 汇付微信支付 + 延时分账总体方案 | -| [汇付个人进件对接_e1144173.plan.md](./汇付个人进件对接_e1144173.plan.md) | 推广员/区域代理个人进件 | -| [微信发货信息同步_b8fd57f1.plan.md](./微信发货信息同步_b8fd57f1.plan.md) | 微信购物订单发货同步 | -| [阿里云快递查询插件_b22bbd2a.plan.md](./阿里云快递查询插件_b22bbd2a.plan.md) | 阿里云全国快递查询 | - ---- - -## 分销 / 佣金 / 区域代理（核心业务） - -| 文档 | 说明 | -|------|------| -| [区域代理需求对照_060fc1ce.plan.md](./区域代理需求对照_060fc1ce.plan.md) | 区域代理需求图对照、P0/P1/P2 分阶段完善计划 | -| [分销需求差异核对_53c87321.plan.md](./分销需求差异核对_53c87321.plan.md) | 分销功能与需求差异核对 | -| [需求核对报告_a82c765c.plan.md](./需求核对报告_a82c765c.plan.md) | 整体需求核对报告 | -| [shopro分销重构方案_7c67d97d.plan.md](./shopro分销重构方案_7c67d97d.plan.md) | Shopro 分销重构总体方案 | -| [shopro分销重构细化_260cd6c8.plan.md](./shopro分销重构细化_260cd6c8.plan.md) | 分销重构细化任务 | -| [级差奖管理奖改造_7a3ea896.plan.md](./级差奖管理奖改造_7a3ea896.plan.md) | 级差奖、管理奖改造 | -| [商品分销佣金配置_12a20341.plan.md](./商品分销佣金配置_12a20341.plan.md) | 商品级分销佣金配置 | - ---- - -## 小程序 UI / 体验 - -| 文档 | 说明 | -|------|------| -| [首页布局方案_29cd28e2.plan.md](./首页布局方案_29cd28e2.plan.md) | 首页 E-Final 布局方案 | -| [敏感文案替换_1357718d.plan.md](./敏感文案替换_1357718d.plan.md) | 代理→公司、佣金→差价 | -| [首页精简与化妆品扩展_19f078ec.plan.md](./首页精简与化妆品扩展_19f078ec.plan.md) | 首页精简与品类扩展 | -| [首页公告滚动展示_0032cf34.plan.md](./首页公告滚动展示_0032cf34.plan.md) | 公告滚动 | -| [首页视频与商品视频_23635752.plan.md](./首页视频与商品视频_23635752.plan.md) | 视频展示 | -| [商务蓝白_ui_改版_d9d0903f.plan.md](./商务蓝白_ui_改版_d9d0903f.plan.md) | 商务蓝白 UI 改版 | -| [深蓝酒业主题改造_d0048f3e.plan.md](./深蓝酒业主题改造_d0048f3e.plan.md) | 深蓝主题 | -| [白酒文化ui改造_4e54a93b.plan.md](./白酒文化ui改造_4e54a93b.plan.md) | 白酒文化 UI | -| [酒类小程序_ui_设计_4b7fbcd5.plan.md](./酒类小程序_ui_设计_4b7fbcd5.plan.md) | 酒类小程序 UI 设计 | -| [字体背景风格优化_63a32b86.plan.md](./字体背景风格优化_63a32b86.plan.md) | 字体背景优化 | -| [子页面风格统一_7bee3db6.plan.md](./子页面风格统一_7bee3db6.plan.md) | 子页面风格统一 | -| [taro_小程序对齐方案_b61be661.plan.md](./taro_小程序对齐方案_b61be661.plan.md) | Taro 小程序对齐 | - ---- - -## 测试 / 运维 - -| 文档 | 说明 | -|------|------| -| [本地数据库完整还原_5823409e.plan.md](./本地数据库完整还原_5823409e.plan.md) | 本地数据库还原 | - ---- - -## 相关测试脚本 - -```bash -# 分销测试 -php addons/shopro/tests/commission_setup_test_users.php -php addons/shopro/tests/commission_verify.php scenarios - -# 区域代理测试 -php addons/shopro/tests/regional_agent_setup_test_users.php -php addons/shopro/tests/regional_agent_verify.php list-agents - -# 插件验证 -php think shopro_huifu:verify -php think shopro_wechat_trade:verify -``` - -## 相关 SQL 升级脚本 - -- `addons/shopro/upgrade_distribution_features.sql` — 分销+区域代理表结构 -- `addons/shopro/upgrade_regional_agent_menu.sql` — 区域代理完整菜单 -- `addons/shopro/upgrade_regional_agent_commission.sql` — 单个代理自定义佣金字段 -- `addons/shopro_huifu/upgrade_huifu_pay_type.sql` — 汇付支付类型 -- `addons/shopro_huifu/upgrade_huifu_split.sql` — 汇付分账表 diff --git a/plan/chat-backup/对话摘要-2026-09-12打包.md b/plan/chat-backup/对话摘要-2026-09-12打包.md deleted file mode 100644 index de2ac1d..0000000 --- a/plan/chat-backup/对话摘要-2026-09-12打包.md +++ /dev/null @@ -1,156 +0,0 @@ -# 对话摘要汇总（2026-09-04 ~ 2026-09-12） - -- **项目**：chufang.gynhc.com / xgsc.gynhc.com（厨房/宥川商城） -- **备份时间**：2026-09-12 -- **说明**：「飞天」系列为另一独立酒类项目，与本项目无关 - ---- - -## 会话索引 - -| 日期 | 主题 | 会话 ID | 摘要 | -|------|------|---------|------| -| 09-04 | 区域代理功能实施 | `1fc9746b` | [对话摘要-区域代理实施.md](./对话摘要-区域代理实施.md) | -| 09-08~09 | 汇付支付 + 延时分账插件 | `a5138654` | 见下文 §1 | -| 09-10 | 首页布局改版 E-Final | `45ebfacd` | 见下文 §2 | -| 09-10~11 | 微信发货信息同步 | `553f50fe` | 见下文 §3 | -| 09-10~11 | 阿里云快递查询插件 | `909afd5e` | 见下文 §4 | -| 09-11 | 汇付个人进件（推广员/区域代理） | `1cafd55b` | 见下文 §5 | -| 09-11 | 敏感文案 + 提现进件 + 图片压缩 | `c58fb120` | 见下文 §6 | - -详细内容以本目录 Markdown 摘要为准；原始 JSONL 不再纳入 Git 仓库。 - ---- - -## §1 汇付支付 + 延时分账（a5138654） - -**计划**：[汇付小程序支付对接_c945b5d0.plan.md](../汇付小程序支付对接_c945b5d0.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-09 | 判断支付产品线和接入方案 | 分析汇付斗拱聚合支付 + 延时分账 | -| 09-09 | huifu_id 查看、AppID 绑定、sub_openid 链路 | 文档说明 + 后台配置指引 | -| 09-09 | 检查方案遗漏、分账后台可配置 | 补充方案：分账时机可选、插件化 | -| 09-09 | 支付做成可卸载插件 | 设计 `shopro_huifu` 插件架构 | -| 09-09 | 实施汇付对接方案 | 完成插件开发、Hook 接入、后台配置 | -| 09-09 | 插件中心看不到 / 安装验证失败 | 修复 install 流程、verify 脚本、菜单注册 | -| 09-10 | 支付联调、配置参数 | 逐步修复 notify、pay_type、分账配置 | - -**交付物**： -- 插件 `addons/shopro_huifu/`（支付、分账、后台配置、verify/install 命令） -- SQL：`upgrade_huifu_pay_type.sql`、`upgrade_huifu_split.sql` -- 后台：汇付配置、分账接收方、分账记录 - ---- - -## §2 首页布局改版（45ebfacd） - -**计划**：[首页布局方案_29cd28e2.plan.md](../首页布局方案_29cd28e2.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-10 | 参考参考图出首页布局方案 + 预览图 | 生成 A~E 多套预览 | -| 09-10 | 选 E 方案，优化红框区域和底部导航 | 生成 E-Final 预览 | -| 09-10 | 按 E-Final 实现 | 改造 `pages/index/index.vue` 及组件 | -| 09-10 | WXML 编译错误 | 修复 `sh-grid-swiper` style 语法 | -| 09-10 | 图标配色优化、立体化 | 优化分类图标、配色统一 | - -**交付物**： -- 小程序首页 E-Final 布局 -- 预览图：`xgsc.gynhc.com_wx/docs/homepage-previews/` -- 组件：`sh-grid-swiper`、分类网格等 - ---- - -## §3 微信发货信息同步（553f50fe） - -**计划**：[微信发货信息同步_b8fd57f1.plan.md](../微信发货信息同步_b8fd57f1.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-10 | 接入微信购物订单 / 发货信息同步 | 设计并实现 `shopro_wechat_trade` 插件 | -| 09-10 | 经营类目超出开放范围 | 说明需在微信后台申请接入 | -| 09-10 | install 后订单详情路径配置失败 | 需先签署订单中心授权协议 | -| 09-10 | init-path 无效路径 10060035 | 排查 path 格式、小程序版本要求 | -| 09-10 | 订单中心 path 怎么填 | 配置 `pages/order/detail` | -| 09-10 | 支付成功验证 | 确认支付链路正常 | -| 09-11 | 分析个人进件流程是否接好 | 分析结论：分账执行已接，个人进件未接 | - -**交付物**： -- 插件 `addons/shopro_wechat_trade/`（发货同步、配置、verify 命令） -- 后台：微信交易组件配置 - ---- - -## §4 阿里云快递查询（909afd5e） - -**计划**：[阿里云快递查询插件_b22bbd2a.plan.md](../阿里云快递查询插件_b22bbd2a.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-10 | 对接阿里云全国快递查询 API | 设计并实现 `shopro_aliyun_express` 插件 | -| 09-11 | install 命令不存在 | 修复命令注册、InstallFull | -| 09-11 | AppCode vs AppKey 混淆 | 澄清阿里云市场鉴权方式 | -| 09-11 | 选阿里云时隐藏 ExpressBird 配置 | 后台 UI 条件显示 | -| 09-11 | 测试查询 404 / 格式错误 | 修复 API 端点、响应解析 | -| 09-11 | 刷新轨迹非法参数 | 修复单号空格 trim、编码映射 | - -**交付物**： -- 插件 `addons/shopro_aliyun_express/` -- 后台：快递 provider 切换、AppCode 配置 - ---- - -## §5 汇付个人进件（1cafd55b） - -**计划**：[汇付个人进件对接_e1144173.plan.md](../汇付个人进件对接_e1144173.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-11 | 分销/代理必须走汇付进件 | 细化实施计划并开始开发 | -| 09-11 | install-full 命令未定义 | 补充 InstallFull 命令 | -| 09-11 | Agent.php 207 引用传参错误 | 修复 Hook 参数传递 | -| 09-11 | Config::isHuifuMode() 未定义 | 补全 SplitConfig 方法 | -| 09-11 | 找不到小程序进件页面 | 定位 `pages/app/commission/apply` | -| 09-11 | 进件页无法填资料、区域代理秒过 | 修复表单交互、审核流程 | -| 09-11 | 审核中但内容空白 | 修复状态展示与数据回填 | -| 09-11 | 「您暂时不能申请」 | 解释门槛条件（分销等级/状态） | - -**交付物**： -- 进件表、API、Hook 对接 -- 小程序：`pages/app/commission/apply` 进件表单 -- 后台：进件审核管理 -- 命令：`shopro_huifu:install-full`、`shopro_huifu:onboard-poll` - ---- - -## §6 敏感文案 + 提现进件 + 包体积（c58fb120） - -**计划**：[敏感文案替换_1357718d.plan.md](../敏感文案替换_1357718d.plan.md) - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 09-11 | 代理→公司、佣金→差价 | 小程序 + 后台敏感文案批量替换 | -| 09-11 | 补充提现页面 | 完善提现 UI 与逻辑 | -| 09-11 | 进件资料绑定到提现页 | 分销商/区域角色才显示 | -| 09-11 | 绑定页应为提现子页面 | 拆分为 `withdraw/bind` 子页 | -| 09-11 | home 图片太大超包限制 | 压缩 static/images/home | -| 09-11 | 删除未引用图片 | 清理无用资源 | - -**交付物**： -- 文案替换（小程序 + 后台视图/JS） -- 提现页 + 进件绑定子页 -- 首页图片压缩与清理 - ---- - -## 关联计划文档（plan 目录） - -完整列表见 [README.md](../README.md)，新增计划： - -- 汇付小程序支付对接 -- 汇付个人进件对接 -- 微信发货信息同步 -- 阿里云快递查询插件 -- 敏感文案替换 -- 首页布局方案 diff --git a/plan/chat-backup/对话摘要-区域代理实施.md b/plan/chat-backup/对话摘要-区域代理实施.md deleted file mode 100644 index 525a724..0000000 --- a/plan/chat-backup/对话摘要-区域代理实施.md +++ /dev/null @@ -1,86 +0,0 @@ -# 对话摘要：区域代理功能实施 - -- **项目**：chufang.gynhc.com（厨房/宥川商城） -- **会话 ID**：`1fc9746b-419a-426b-98a2-35182ed827b5` -- **备份时间**：2026-09-04 -- **原始记录**：会话 ID `1fc9746b-…`（JSONL 不入 Git，需在 Cursor 本地 transcripts 查看） - -> 说明：「飞天」系列为另一独立酒类项目，与本会话无关。 - ---- - -## 对话时间线 - -| 时间 | 用户诉求 | 处理结果 | -|------|----------|----------| -| 12:08 | 核对区域代理与需求图出入，拆分细化 | 生成对照计划，确认分佣模式可配置、运营优先 | -| 12:26 | 代理佣金需后台可配置 | 计划补充 P0：代理设置页 + 代理等级 CRUD | -| 13:10 | 开始实施 | 完成 P0：佣金配置、等级管理、菜单、编辑/添加、小程序提现等 | -| 13:31 | 继续 P2 | 完成看板、筛选导出、商品开关、审核通知、动态等级匹配 | -| 13:40 | PDO 2031 报错 | 修复 `(clone $query)` 与 `FROM_UNIXTIME` `%` 占位符问题 | -| 13:47 | 继续未完成 | 补全菜单 SQL、通知注册、Order/Reward 格式整理 | -| 14:01 | 单个代理可设专属佣金，优先于等级通用 | 新增字段 + 表单 + `Commission.php` 优先逻辑 | -| 14:06 | 「跟随等级」是什么意思 | 解释：未自定义时用等级通用配置 | -| 14:09 | 开关文案易误导 | 改为单选：「使用等级通用配置 / 单独设置佣金」 | -| 14:37 | 编写区域代理测试脚本 | 新增 setup/cleanup/verify 脚本 + 910001~910009 测试账号 | -| 14:44 | 计划复制到 plan 目录 | 复制 21 份计划 + README + 实施进度汇总 | -| 14:49 | 飞天是另一项目，不要搞混 | 删除 plan 中 3 份飞天相关计划 | -| 15:33 | 对话备份到 plan | 本备份 | - ---- - -## 已确认业务口径 - -- **固定佣金**：按每单计，不按件 × 数量 -- **分佣模式**：后台可配（叠加 / 独占 / 级差） -- **单个代理佣金**：有专属配置时优先，否则跟随代理等级 -- **比例基数**：订单商品实付金额 `pay_price` - ---- - -## 主要交付物 - -### 后台 - -- 区域代理：设置、等级、代理列表、订单、佣金、业绩看板 -- 代理添加/编辑：用户搜索、省市区级联、佣金设置（等级通用 / 单独设置） -- 菜单 SQL：`upgrade_regional_agent_menu.sql` 等 - -### 引擎 - -- `addons/shopro/library/regional_agent/Commission.php` — 三种分佣模式、按单固定、代理优先 -- `upgrade_regional_agent_commission.sql` — 单代理自定义佣金字段 - -### 小程序 - -- `xgsc.gynhc.com_wx/pages/app/regional-agent/` — stats、筛选、待结算、提现入口 - -### 测试 - -```bash -php addons/shopro/tests/regional_agent_setup_test_users.php -php addons/shopro/tests/regional_agent_verify.php list-agents -php addons/shopro/tests/regional_agent_verify.php verify-order {订单ID} -``` - -**测试密码**：`Test@123456` -**主测买家**：19900000014（910004） - ---- - -## 部署 Checklist - -1. 执行 `upgrade_distribution_features.sql` -2. 执行 `upgrade_regional_agent_menu.sql` -3. 执行 `upgrade_regional_agent_commission.sql` -4. 后台分配区域代理权限 -5. 商品开启 `regional_enable` -6. 运行测试脚本验证 - ---- - -## 相关文档 - -- [实施进度汇总.md](../实施进度汇总.md) -- [区域代理需求对照](../区域代理需求对照_060fc1ce.plan.md) -- [README.md](../README.md) diff --git a/plan/chufang-project-plan-backup-20260912.zip b/plan/chufang-project-plan-backup-20260912.zip deleted file mode 100644 index f03cfaf..0000000 Binary files a/plan/chufang-project-plan-backup-20260912.zip and /dev/null differ diff --git a/plan/shopro分销重构方案_7c67d97d.plan.md b/plan/shopro分销重构方案_7c67d97d.plan.md deleted file mode 100644 index 85f0f3a..0000000 --- a/plan/shopro分销重构方案_7c67d97d.plan.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -name: Shopro分销重构方案 -overview: 卸载飞天插件，以 Shopro 分销为核心重建会员/创客/并行角色体系；创客映射分销商等级，合伙人/酒道馆/区县代理作为分销商上的并行标签；马豆/云豆/兑换券/分红池/兑换商城作为 Shopro 扩展模块保留。 -todos: - - id: p0-backup-freeze - content: "Phase 0: 备份 feitian/commission 表，暂停 cron，禁止提前卸载插件" - status: pending - - id: p1-business-skeleton - content: "Phase 1: 新建 shopro_business 扩展，迁移 Reward/Pool/Asset library，注册 order hooks" - status: pending - - id: p2-agent-ext-schema - content: "Phase 1: 设计 shopro_commission_agent_ext 表 + 并行角色字段" - status: pending - - id: p2-enable-commission - content: "Phase 2: 恢复 commission_level，配置 V1-V6 等级，迁移 maker→agent" - status: pending - - id: p3-admin-migrate - content: "Phase 3: 复用 shopro/commission 后台，迁入分红/收入明细/资产/兑换管理" - status: pending - - id: p4-frontend-switch - content: "Phase 4: 小程序切回 commission 中心，改造资产/兑换 API，更新 decorate 入口" - status: pending - - id: p5-parallel-test - content: "Phase 5: 1398 品酒单全链路验收，对比 feitian 历史结算" - status: pending - - id: p6-uninstall-cleanup - content: "Phase 6: 卸载 feitian，删除 admin/feitian 与前端 feitian 页面，清理冗余字段" - status: pending -isProject: false ---- - -# Shopro 分销重构方案（替代飞天插件） - -## 一、需求纠正：正确角色模型 - -```mermaid -flowchart LR - subgraph entry [入口] - Member["会员 = 品酒师"] - end - subgraph upgrade [唯一升级路径] - Maker["创客 = 分销商 V1-V6"] - end - subgraph parallel [并行标签 可同时拥有] - Partner[合伙人] - JDG[酒道馆] - Agent[区县代理] - end - Member -->|"直推3单或团队4单"| Maker - Maker -.-> Partner - Maker -.-> JDG - Maker -.-> Agent - Member -.-> Partner -``` - - - -**关键原则：** - -- 只有一条升级链：**品酒师 → 创客**（达标自动/手动成为分销商） - -- -- 合伙人 / 酒道馆 / 区县代理是**标签**，不是更高级别；同一用户可同时是创客+合伙人+酒道馆+区县代理 -- 推荐链上的每一层代理，可能是不同标签组合（一级区县代理、二级合伙人、三级酒道馆等） - -**代码现状说明：** 当前 `[RewardEngine.php](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\RewardEngine.php) 已对同一订单并行调用 Referral/Maker/Jdg/Agent 四套结算；`[feitian_user_role](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\install.sql) 表结构也支持 `(user_id, role_type)` 多行并存。**问题主要在方案文档/UI 表述为「五级角色」，以及与 Shopro 分销 UI/数据双轨运行**，而非算法完全不可用。 - ---- - -## 二、卸载飞天会不会造成混乱？ - -**会，如果只做「后台卸载插件」而不做配套清理。** - - -| 卸载后状态 | 影响 | -| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| `Feitian.php::uninstall()` 仅删菜单 | 21 张 `feitian_`* 表、历史数据全部残留 | -| 订单 Hook 消失 | 品酒单不再结算任何奖励 | -| 小程序 `/addons/feitian/*` | 会员中心、马豆、兑换商城全部 404 | -| `[application/admin/controller/feitian/](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\feitian) | 控制器仍在，访问报类找不到 | -| `[feitian-disable-commission.sql](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-disable-commission.sql) 已执行 | Shopro 分销仍为关闭状态 → **卸载后短期无任何分销能力** | -| 商品/门店补丁字段 | `is_feitian_order`、`store_type` 等字段仍在 Shopro 表上 | -| 装修数据 | 个人中心仍指向 `/pages/app/feitian/`* 死链 | - - -**结论：** 可以卸载，但必须按 **「先建新、再切流、后清理」** 顺序，不能先卸后用。 - ---- - -## 三、Shopro 改造 vs 保留飞天：是否更快更稳？ - - -| 维度 | 完全 Shopro 改造（你的选择） | 修正飞天 + 复用 Shopro UI | -| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -| 后台分销管理 | 原生 `[shopro/commission/](f:\修改的项目\恒链数通(重庆)*`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\commission) 现成 | 需维护 feitian 后台 + Shopro 双轨 | -| 小程序分销中心 | 已有 `[pages/app/commission/*](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\commission) 8 个页面 | 需维护 feitian 9 页 | -| 创客 V1-V6 | 映射 `shopro_commission_agent_level` | 已有 `feitian_role_config` | -| 三单返佣 398/400/600 | **需自定义**（Shopro 默认按层级百分比） | 已实现 `ReferralReward` | -| 创客极差 120 元/单 | **需自定义**（非标准 MLM） | 已实现 `MakerReward` | -| 酒道馆/区县代理区域逻辑 | **需自定义** | 已实现 `JiudaoguanReward`/`AgentReward` | -| 全国池均分 | **需自定义** | 已实现 `PoolService` | -| 马豆/云豆/兑换券/兑换商城 | **仍需独立表+定时任务** | 已实现 | -| 30 天分红周期 | **仍需独立表+cron** | 已实现 | -| 预估工期 | **4~6 周**（含迁移+联调） | **1~2 周**（模型修正+UI对齐） | -| 长期维护 | **更统一**，一套分销体系 | 双系统并存，认知成本高 | - - -**诚实结论：** - -- **更稳定**：长期看 Shopro 统一体系更好（你已选择此路线） -- **更快**：**不是** — 约 70% 业务规则 Shopro 无法开箱即用，无论选哪条路线都要写自定义结算；完全迁移还要加上卸载清理、数据迁移、前端回切成本 - ---- - -## 四、目标架构（Shopro 核心 + 业务扩展层） - -```mermaid -flowchart TD - OrderPay[Shopro订单支付] --> Hook[order_payed_after] - Hook --> CommHook[Shopro CommissionHook] - Hook --> BizHook[shopro/business OrderHook 新扩展] - CommHook --> AgentLevel[分销商等级 V1-V6] - CommHook --> WalletReward[钱包佣金 commission_reward] - BizHook --> ReferralFix[三单返佣 398/400/600] - BizHook --> MakerDiff[创客极差 120元] - BizHook --> JDGReward[酒道馆团队奖] - BizHook --> AgentArea[区县代理区域奖] - BizHook --> Pools[全国池/绿色池] - BizHook --> Assets[马豆/云豆/兑换券] - AgentExt[shopro_commission_agent_ext] --> BizHook - AgentExt --> CommHook -``` - - - -**建议新建轻量扩展：** `addons/shopro_business/`（或 `addons/shopro/library/business/` 内聚），**不要**再叫 feitian，职责清晰： - -- **Shopro 分销负责：** 分销商身份、V1-V6 等级、团队统计、钱包佣金、后台/小程序分销中心 -- **Business 扩展负责：** 并行角色标签、固定金额奖励、区域代理、资产引擎、分红池、兑换商城 - ---- - -## 五、数据模型改造 - -### 5.1 分销商并行标签（替代 `feitian_user_role`） - -在 `[fa_shopro_commission_agent](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\install.sql) 上扩展，或新建 `fa_shopro_commission_agent_ext`： - - -| 字段 | 说明 | -| ----------------------- | -------------- | -| `user_id` | PK，关联 agent | -| `is_partner` | 合伙人（后台手动） | -| `is_jiudaoguan` | 酒道馆 | -| `jiudaoguan_store_id` | 绑定门店 | -| `is_district_agent` | 区县代理 | -| `agent_area_id` | 辖区 area_id | -| `sommelier_order_count` | 品酒师自购单数（升级创客用） | -| `direct_order_count` | 直推品酒单数 | - - -**创客 = 已是分销商**：`shopro_commission_agent.status=normal` + `level` 1~6 - -**品酒师 = 普通会员**：无 agent 记录，或 agent 未激活 - -### 5.2 资产/分红/兑换表（保留，改名可选） - -以下表**无法**并入 Shopro 分销表，建议保留并改名前缀为 `shopro_business_`* 或保持 `feitian_*` 仅作历史： - -- 马豆/云豆/兑换券账户与流水 -- `green_pool` / `dividend_cycle` / `pool_distribute` -- `exchange_goods` / `exchange_order` - -### 5.3 迁移脚本 - -从 `[feitian-migrate-user.sql](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-migrate-user.sql) 逻辑反向编写： - -- `feitian_user_role.role_type=maker` → `shopro_commission_agent` + level -- `partner_flag` → `is_partner` -- `jiudaoguan` / `agent` → ext 表字段 -- 资产账户按 `user_id` 原样迁移（表 rename 或视图） - ---- - -## 六、业务规则映射到 Shopro - - -| 脑图规则 | Shopro 实现方式 | -| -------------------- | ------------------------------------------------------------- | -| 品酒师三单返佣 398/400/600 | Business Hook：`ReferralReward` 逻辑迁入，按 buyer 序号发 `User::money` | -| 创客升级（直推3/团队4单） | 扩展 `CommissionJob` 或 Business：`Agent::becomeAgent` + level=1 | -| 创客 V1-V6 极差 120 元 | Business Hook 在 CommissionHook 之后，遍历 maker 链（读 agent.level） | -| 酒道馆团队 50 元 + 全国池 100 | Business：`is_jiudaoguan=1` 的用户链 + `pool` 表 | -| 区县代理三种场景 | Business：`agent_area_id` + `AreaResolver`（从 feitian 迁入） | -| 全国池 150 均分 | Business cron `pool-distribute` | -| 马豆/云豆/兑换券 | Business 资产服务（从 feitian library 迁入） | -| 30 天分红 | Business cron `dividend-cycle` | -| 兑换商城 | Business API + 保留/改造 exchange 页面 | - - -**Shopro 原生可承接部分：** - -- 分销商申请/审核 UI -- 团队列表、佣金明细、排行榜（`[pages/app/commission](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\commission)） -- 后台等级配置、佣金订单、奖励流水 - ---- - -## 七、实施阶段（推荐顺序） - -### Phase 0：冻结与备份（1 天） - -- 备份全部 `feitian_`* 表 + `shopro_commission_*` 表 -- 暂停 feitian crontab（`[README.md` L49-52](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\README.md)） -- **不要**此时卸载插件 - -### Phase 1：Shopro 扩展骨架（3 天） - -- 新建 `addons/shopro_business/`（Feitian.php 同级模式）或 shopro 子目录 -- 注册 `order_payed_after` / `order_refund_after`（在 CommissionHook **之后**执行） -- 迁移核心 library：`ReferralReward`、`MakerReward`、`JiudaoguanReward`、`AgentReward`、`PoolService`、`MadaoService`、`YundouService`、`VoucherService`、`AreaResolver` -- 新建 agent_ext 表 + install.sql - -### Phase 2：启用 Shopro 分销（2 天） - -- 执行反向脚本：恢复 `commission_level`（建议 3 层或按脑图配置） -- 配置 V1-V6 等级（`[shopro/commission/level](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\commission\Level.php)） -- 品酒单商品开启分销参与（`shopro_commission_goods`） -- 数据迁移：maker → agent - -### Phase 3：后台改造（4 天） - -- **复用** Shopro 分销后台（代理商/等级/佣金/订单） -- 新增 Business 后台页： - - 并行角色管理（合伙人/酒道馆/区县代理标签） - - 分红管理、收入明细（从 feitian admin 迁入逻辑） - - 马豆充值、兑换商品/订单 -- 删除或废弃 `[application/admin/controller/feitian/](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\feitian) - -### Phase 4：小程序改造（4 天） - -- 个人中心入口改回 **分销中心** `[pages/app/commission/index](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\commission\index.vue) -- 并行角色标签显示在 commission 首页（读 agent_ext） -- 马豆/云豆/兑换券/兑换商城：保留 UI，API 改指向 `shopro_business` 或 shopro 扩展 controller -- 删除 `pages/app/feitian/`*、`FEITIAN_API_URL`、`apis.js` feitian 分组 -- 恢复 `[feitian-demo-patch-user.sql](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-demo-patch-user.sql) 中链接为 commission 路径 - -### Phase 5：切流验证（3 天） - -- 测试单：1398 品酒单 → 三单返佣 + 创客极差 + 角色标签奖励 + 资产 -- 退款回滚 -- 与生产 feitian 结算结果对比抽样 - -### Phase 6：卸载飞天 + 清理冗余（2 天） - -- 后台禁用/卸载 feitian 插件 -- 删除 `[addons/feitian/](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian) -- 删除 `application/admin/feitian/`、`public/assets/js/backend/feitian/` -- 移除 `application/command.php` 中 feitian 命令 -- 可选：DROP `feitian_*` 表（确认迁移完成后） -- 清理 Shopro 商品模板中「飞天分销设置」块（`[goods/add.html](f:\修改的项目\恒链数通(重庆)`科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\goods\goods\add.html)） - ---- - -## 八、风险与规避 - - -| 风险 | 规避 | -| --------------- | ----------------------------------------------------------- | -| 卸载后无结算 | Phase 5 验证通过前禁止卸载 | -| 双 Hook 重复发佣 | 切流时关闭 feitian hook，只留 business hook；Shopro 百分比佣金与固定金额奖励分工明确 | -| 历史 feitian 流水断层 | 资产/奖励表 rename 而非 drop；wallet 日志保留 | -| 小程序用户找不到入口 | 切流前更新 decorate + tabbar 一次到位 | -| 工期低估 | 固定金额+极差+区域逻辑仍需从 feitian **搬迁**而非重写，复用现有 library 代码 | - - ---- - -## 九、最终建议 - -你已选择 **完全 Shopro 改造**，方案可行且长期更统一，但请注意： - -1. **不是简单「打开 Shopro 分销开关」** — 脑图里大部分规则仍要自定义 Business 层 -2. **卸载飞天本身不带来能力** — 价值在于消除双轨、复用 Shopro 后台/小程序分销 UI -3. **最高性价比做法**：Business 扩展层 **直接迁移** 现有 feitian/library 代码（约 3000 行已验证逻辑），而非从零写 Shopro 插件 -4. **若 Phase 1-2 超过 1 周未稳定**，可回退：feitian 插件仍保留至 Phase 5 完成 - -**预估总工期：4~6 周**（1 人全职）；其中 Shopro UI 复用节省约 1 周，但被迁移+清理+联调抵消。 \ No newline at end of file diff --git a/plan/shopro分销重构细化_260cd6c8.plan.md b/plan/shopro分销重构细化_260cd6c8.plan.md deleted file mode 100644 index 295c605..0000000 --- a/plan/shopro分销重构细化_260cd6c8.plan.md +++ /dev/null @@ -1,624 +0,0 @@ ---- -name: Shopro分销重构细化 -overview: 在原有 Shopro 分销重构方案基础上，补充商品级佣金能力审计（原生 vs 飞天补丁）、双轨合并设计，以及 Phase 6 飞天插件零残留卸载清单与切流验收步骤，确保卸载后 Shopro 分销正常、无重复/漏发佣。 -todos: - - id: p0-audit-goods - content: "Phase 0: 审计现有商品 enable_commission/team/rate 配置 + shopro_commission_goods 现状，输出品酒单/普通商品清单" - status: pending - - id: p0-backup-freeze - content: "Phase 0: 备份 feitian/commission 表，暂停 feitian cron，禁止提前卸载" - status: pending - - id: p1-maker-reward-fix - content: "Phase 1: 修正 MakerReward 平级/超越为 prevAmount×10%/5%；扩展升级统计 team_order_count（伞下品酒单）" - status: pending - - id: p1-business-skeleton - content: "Phase 1: 新建 shopro_business，迁移 GoodsRewardResolver + Reward/Pool/Asset library，注册 order hooks" - status: pending - - id: p2-agent-ext-schema - content: "Phase 1: shopro_commission_agent_ext 表 + 并行角色字段" - status: pending - - id: p2-enable-commission - content: "Phase 2: 恢复 commission_level，V1-V6 配置，品酒单 commission_goods.status=0，maker→agent 迁移" - status: pending - - id: p2-goods-ui-merge - content: "Phase 3: 商品页「业务分销设置」四字段 + 分销商品页 MLM 分工说明，防双发" - status: pending - - id: p3-admin-migrate - content: "Phase 3: shopro/commission 后台 + business 分红/资产/兑换/角色管理" - status: pending - - id: p4-frontend-switch - content: "Phase 4: 小程序切 commission 中心，迁移资产/兑换 API，清除 feitian 引用" - status: pending - - id: p5-parallel-test - content: "Phase 5: 1398 品酒单 + 普通商品 MLM + 退款全链路验收，对比 feitian 历史" - status: pending - - id: p6-uninstall-checklist - content: "Phase 6: 按零残留清单卸载 feitian（代码/cron/command/前端/grep 验收），表 rename 归档，保留 shopro_goods 业务列" - status: pending -isProject: false ---- - -# Shopro 分销重构方案（细化版） - -## 一、商品级分销能力审计（回答你的 3 个问题） - -当前系统存在 **两套商品分销配置**，且 **Shopro 原生分销已被关闭**（[`feitian-disable-commission.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-disable-commission.sql) 将 `commission_level=0`），实际结算走飞天 Hook。 - -```mermaid -flowchart LR - subgraph native [Shopro原生 当前关闭] - CG["shopro_commission_goods"] - LevelRules["V1-V6 × 一级/二级/三级 %或固定元"] - end - subgraph feitianPatch [飞天补丁 当前生效] - SG["shopro_goods 四字段"] - Resolver["GoodsRewardResolver"] - end - OrderPay --> FeitianHook - FeitianHook --> Resolver - Resolver --> SG - CommHook["Shopro CommissionHook"] -.->|"commission_level=0 不执行"| CG -``` - -### 1. Shopro 原生「分销商品」能否单独设比例？ - -**能。** 入口：后台 → Shopro → 分销 → **分销商品**（[`application/admin/view/shopro/commission/goods/edit.html`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\commission\goods\edit.html)） - -| 能力 | 字段/表 | 说明 | -|------|---------|------| -| 是否参与分销 | `shopro_commission_goods.status` | 0=不参与，1=参与 | -| 规则模式 | `self_rules` | 0=跟等级默认，1=独立（按规格），2=批量 | -| 各级佣金 | `commission_rules` JSON | 每个分销商等级 V1-V6 下：`commission_1` / `commission_2` / `commission_3`，支持 **% 或固定元** | -| 商品独立层级 | `commission_config.commission_level` | 可覆盖全局，设 1/2/3 级 | -| 是否计入业绩 | `commission_order_status` | 只分佣不计业绩 vs 计入 | - -逻辑类：[`addons/shopro/library/commission/Goods.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Goods.php) - -### 2. 原生有没有「团队佣金比例」？ - -**没有单独的 `team_commission_rate` 字段。** - -Shopro 用 **多级分销** 表达「团队」： -- **一级(自购)** = `commission_1` -- **二级** = `commission_2`（上级团队） -- **三级** = `commission_3`（上上级） - -这与飞天脑图的 **创客极差 120 元/单、酒道馆团队 50 元** 不是同一模型——后者是固定金额 + 极差，Shopro 默认是按订单金额 × 层级百分比。 - -### 3. 每个商品能否单独开关「分佣 / 团队分销」？ - -#### 3.1 飞天补丁（当前生效，写在 `fa_shopro_goods`） - -入口：商品编辑 → **「飞天分销设置」**（[`goods/add.html`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\goods\goods\add.html) / [`edit.html`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\goods\goods\edit.html) L594-635） - -| 字段 | UI 标签 | 用途（GoodsRewardResolver） | -|------|---------|----------------------------| -| `enable_commission` | 是否启用分佣 | 关闭则不算推荐奖/百分比佣金 | -| `commission_rate` | 分销佣金比例 % | >0 按实付×比例；=0 且开启则走全局固定 398/400/600 | -| `enable_team` | 是否启用团队分销 | 关闭则不算创客/酒道馆团队基数 | -| `team_commission_rate` | 团队佣金比例 % | >0 按实付×比例；=0 则用全局固定基数（120/50） | - -来源 SQL：[`feitian-patch-goods-reward.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-patch-goods-reward.sql) - -#### 3.2 Shopro 原生实现（写入计划，迁移后需启用） - -Shopro **没有** `enable_team` / `team_commission_rate` 字段；用 **「是否参与」+ 分销层级 + 各级比例** 组合实现类似效果。 - ---- - -##### A. 数据表：`fa_shopro_commission_goods` - -```sql --- addons/shopro/install.sql -goods_id PK 关联 shopro_goods.id -status 0=不参与分销 1=参与分销 ← 【分佣总开关】 -self_rules 0=默认等级规则 1=独立(按规格) 2=批量 -commission_rules JSON 各等级×各层级的 rate/money -commission_config JSON 商品级覆盖全局分销设置 -commission_order_status 0=只分佣不计业绩 1=计入业绩 -``` - -**默认行为：** 商品若未写入该表，或 `status=0`，则 **不参与任何 Shopro 分佣**。 - -##### B. 后台操作路径 - -| 操作 | 入口 | 控制器/API | -|------|------|-----------| -| 分销商品列表 | Shopro → 分销 → **分销商品** | [`shopro/commission/goods/index`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\commission\goods\index.html) | -| 单商品佣金编辑 | 列表 → 编辑 | [`shopro/commission/goods/edit?id={goods_id}`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\commission\goods\edit.html) | -| 批量参与/不参与 | 列表勾选 → 批量设置 | `POST shopro/commission/goods/commission_status`（[`Goods.php::commission_status()`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\commission\Goods.php) L170） | -| 全局分销层级 | Shopro → 分销 → **分销设置** | `fa_shopro_commission_config.name=commission_level`（0=关闭，1/2/3=层级） | - -**编辑页 UI 对应关系（edit.html L191-276）：** - -``` -是否参与： status 0 不参与 / 1 参与 ← 等同 enable_commission（仅 Shopro MLM） -佣金规则： self_rules 默认 / 独立 / 批量 -分销商业绩： commission_order_status -分销层级： commission_config.commission_level 1级/2级/3级 ← 等同「团队分销深度」 -一级佣金： commission_rules[level][1].rate|money commission_1 -二级佣金： commission_rules[level][2].rate|money commission_2 ← 上级团队 -三级佣金： commission_rules[level][3].rate|money commission_3 ← 上上级团队 -``` - -##### C. 运行时结算链路 - -```mermaid -sequenceDiagram - participant Pay as order_payed_after - participant Hook as CommissionHook - participant Comm as Commission - participant G as Goods_library - participant DB as shopro_commission_goods - - Pay->>Hook: orderPayedAfter - Hook->>Comm: foreach order_item - Comm->>G: new Goods(goods_id, sku_price_id) - G->>DB: WHERE goods_id AND status=1 - alt status=0 或无记录 - G-->>Comm: getCommissionRules=false - Comm-->>Hook: checkAndSetCommission=false 跳过 - else status=1 - G-->>Comm: 加载 commission_rules - Comm->>Comm: commissionLevel=config或商品覆盖 - alt commission_level=0 全局关闭 - Comm-->>Hook: return false - else - Comm->>Comm: runCommissionPlan 递归上级 - Note over Comm: level1→自购/直推
level2→二级上级
level3→三级上级 - end - end -``` - -**关键代码：** - -1. [`CommissionHook.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\commission\CommissionHook.php) L43-54：逐 `order_item` 调用 `Commission::checkAndSetCommission()` -2. [`Commission.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Commission.php) L47-73： - - L55 加载 `Goods` 规则 - - L58-60 商品 `commission_config` 覆盖全局（含 `commission_level`） - - L66-68 `commission_level=0` → 整站分销关闭，所有商品不分 - - L71-73 `getCommissionRules()` 为空 → **该商品不分佣** -3. [`Goods.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Goods.php) L37：`where(['goods_id'=>$goodsId, 'status'=>GOODS_COMMISSION_STATUS_ON])` -4. [`Commission.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Commission.php) L158-217：`runCommissionPlan` 按 `commission_level` 递归 `parent_agent_id`，每层读 `getCommissionLevelRule(agentLevel, currentLevel)` - -##### D. 原生如何实现「分佣开关」 - -| 目标 | 原生做法 | 字段/配置 | -|------|----------|-----------| -| 该商品完全不参与 Shopro 分佣 | 分销商品编辑 → **不参与** | `shopro_commission_goods.status=0` | -| 整站关闭分销 | 分销设置 → 分销层级=0 | `shopro_commission_config.commission_level=0`（当前已被 feitian-disable-commission.sql 设为 0） | -| 批量关闭多商品 | 分销商品列表批量操作 | `commission_status` API 批量 `status=0` | -| 无记录的商品 | 默认不参与 | 需手动加入分销商品并设 status=1 | - -**≠ 飞天 `enable_commission`：** 后者控制的是 Business 层（三单返佣/固定奖），与 Shopro `status` 是 **两个独立开关**（见第二节防双发表）。 - -##### E. 原生如何实现「团队分销开关/比例」 - -Shopro **没有** `enable_team` 布尔开关，用以下组合等效： - -| 目标 | 原生做法 | 说明 | -|------|----------|------| -| 只做直推，不做团队（二级以上） | 商品独立设置 → **分销层级=一级** | `commission_config.commission_level=1`，只跑 level 1 | -| 关闭某商品全部团队奖 | 同上，或 commission_2/3 全填 0 | 二级/三级比例为 0 则不产生上级佣金 | -| 单独设团队比例 | 编辑 **二级/三级佣金比例** | `commission_rules[Vx][2].rate` / `[3].rate`，支持 % 或固定元 | -| 跟全局团队策略 | self_rules=0 + status=1 | 读 `shopro_commission_level.commission_rules` 里的 commission_2/3 | - -**commission_rules JSON 结构示例（批量规则 self_rules=2）：** - -```json -{ - "1": { - "1": { "rate": "10" }, - "2": { "rate": "5" }, - "3": { "rate": "2" } - }, - "2": { - "1": { "rate": "12" }, - "2": { "money": "30" }, - "3": { "rate": "0" } - } -} -``` - -- 键 `"1"`~`"6"` = 分销商等级 V1-V6 -- 子键 `"1"`/`"2"`/`"3"` = 一级/二级/三级（团队）分佣层级 -- `rate` = 百分比；`money` = 每件固定元（[`Goods::caculateGoodsCommission`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Goods.php) L94-104） - -**与飞天 `team_commission_rate` 的本质差异：** - -| 维度 | Shopro 原生（commission_2/3） | 飞天补丁（team_commission_rate） | -|------|------------------------------|----------------------------------| -| 模型 | 标准 MLM：按上级层级 × 等级规则 | 固定基数/比例：创客 120、酒道馆 50 | -| 开关 | 无独立字段，靠层级深度 + 比例为 0 | `enable_team` 布尔开关 | -| 结算类 | `Commission::runCommissionPlan` | `GoodsRewardResolver::sumMakerTeamBase` | -| 适用 | 普通商品层级分销 | 1398 品酒单极差/团队奖 | - -##### F. 两套开关对照表（迁移后并存） - -| 业务含义 | Shopro 原生配置 | Business 层配置（原飞天字段） | -|----------|-----------------|------------------------------| -| 是否参与 Shopro MLM | `commission_goods.status` | — | -| 是否参与三单返佣/固定奖 | — | `enable_commission` | -| 商品级 MLM 比例 | `commission_rules[level][n].rate` | — | -| 商品级推荐奖比例 | — | `commission_rate` | -| 是否参与创客/酒道馆团队奖 | — | `enable_team` | -| 商品级团队基数比例 | — | `team_commission_rate` | -| MLM 团队（二级/三级） | `commission_level` + `commission_2/3` | — | - -**结论：** -- 你问的 3 点中，**飞天补丁四字段已全部实现** Business 侧能力 -- **Shopro 原生可实现「分佣开关」**（`status`）和 **「团队分销深度/比例」**（`commission_level` + `commission_2/3`），但 **不能** 直接表达飞天脑图的固定极差团队奖 — 后者必须保留 Business 层 `enable_team` / `team_commission_rate` - ---- - -## 二、创客（团长）逻辑核对（脑图 vs 现有代码） - -对照脑图与 [`MakerReward.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\MakerReward.php)、[`RoleService.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\RoleService.php) 逐项核对。**创客奖励不能交给 Shopro 原生 MLM**，必须在 `shopro_business` 层完整迁移。 - -### 2.1 升级条件（品酒师 → 创客 V1） - -**脑图要求：** -- 直推 **3 单**，或 -- 伞下 **1 单** / 推荐人有下单行为 -- **总计考核 4 单** - -**现有代码（`RoleService::tryUpgradeMaker` L89-93）：** - -```php -$canUpgrade = ($direct >= 3) || ($self >= 1 && ($direct + $self) >= 4); -// direct = 直推品酒单数，self = 自购品酒单数 -``` - -| 核对项 | 脑图 | 代码 | 结论 | -|--------|------|------|------| -| 直推 3 单升级 | ✓ | `direct_order_count >= 3` | **一致** | -| 合计 4 单考核 | ✓ | `direct + self >= 4` 且需 `self >= 1` | **部分一致** | -| 伞下 1 单（非直推团队单） | ✓ | **未实现**，只计直推+自购 | **缺口** | -| 推荐人有下单行为 | ✓ | 等价为「自购≥1」或直推累计 | **近似** | -| 自动升到 V2–V6 | 后台灵活配置 | **仅自动 V1**；V2–V6 靠后台手动/测试预置 | **缺口**（见 ACCEPTANCE-SIGNOFF.md L85） | - -**Shopro 迁移方案：** -- 创客 = `shopro_commission_agent` + `level=1`（首次达标） -- 升级计数写入 `shopro_commission_agent_ext`（`direct_order_count` / `self_order_count` / **`team_order_count`**） -- **已确认：** 伞下任意层级品酒单计入 4 单考核（见 §2.4） - -### 2.2 等级体系 V1–V6 - -**脑图：** 6 级，不同权益，**后台灵活设置**。 - -**现有代码：** - -| 配置源 | 内容 | -|--------|------| -| [`default.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\config\default.php) L26-33 | V1=10% … V6=60%（占基数比例） | -| `fa_feitian_role_config` | 后台「创客等级」可改每级 `rate` | -| `feitian_user_role.maker_level` | 用户当前 V1–V6 | - -**Shopro 映射：** `shopro_commission_agent.level` 1–6 对应 V1–V6；等级比例仍在 Business 配置（Shopro 的 `commission_level.commission_rules` 是 MLM 一二三级，**不是**创客极差比例）。 - -### 2.3 团队新增业绩 — 级差奖（基数 120 元/单） - -**脑图：** 每单团队基数 **120 元**，按等级拿 **级差**。 - -**现有代码流程：** - -```mermaid -flowchart TD - Order[品酒单支付] --> Lines[GoodsRewardResolver 解析商品行] - Lines --> Base["基数 base = sumMakerTeamBase()
默认120/行 或 team_commission_rate×实付"] - Base --> Chain["ChainResolver.getMakerChain()
推荐链上仅保留创客"] - Chain --> Loop["逐层遍历 近→远"] - Loop --> First{"链上第一个创客?"} - First -->|是| Full["amount = base × makerRate(level)"] - First -->|否| Cmp{"与上一层级比较"} - Cmp -->|level更高| Diff["amount = base × (rate- prevRate) 级差"] - Cmp -->|level相同| Equal["amount = base × 10% 平级"] - Cmp -->|level更低| Over["amount = base × 5% 超越"] -``` - -**级差计算（与脑图一致，S07/S09 验收通过）：** - -- 近端第一个创客：拿 **本级全额比例 × base**（如 V1=12 元） -- 远端更高级创客：拿 **(高级比例 − 已发比例) × base**（极差） -- 默认基数 120，可被商品 `team_commission_rate` 或 `enable_team=0` 覆盖 - -**示例（base=120，链 V1→V3→V5→V6）：** - -| 创客 | 计算 | 金额 | -|------|------|------| -| V1（近端） | 120×10% | 12 | -| V3 | 120×(30%−10%) | 24 | -| V5 | 120×(50%−30%) | 24 | -| V6 | 120×(60%−50%) | 12 | - -### 2.4 平级奖 / 超越奖 — 与脑图存在差异（重要） - -**脑图原文：** -- **平级奖：** 下级与上级**同级**时，上级拿下级**佣金的 10%**（例：下级 V5 拿 100 → 上级 10；V6 拿 120 → 上级 12） -- **超越奖：** 下级**超越**上级等级时，上级拿 **5%**（应为下级佣金的比例） - -**现有代码（`MakerReward.php` L79-87）：** - -```php -// 平级：base × 10%，不是 下级本单佣金 × 10% -} elseif ($level === $prevLevel) { - $amount = round($base * $equalRate, 2); // 固定 120×10%=12 元 - -// 被超越：base × 5% -} else { - $amount = round($base * $overRate, 2); // 固定 120×5%=6 元 -} -``` - -| 场景 | 脑图算法 | 现有代码 | 差异 | -|------|----------|----------|------| -| 平级两 V3（下级本单 36 元） | 上级 = 36×10% = **3.6** | 上级 = 120×10% = **12** | **不一致** | -| 平级 V5（下级本单 60 元） | 上级 = 60×10% = **6** | 上级 = **12** | **不一致** | -| 被超越（下级等级更高已在级差分支处理；更低等级上级） | 下级佣金×5% | base×5% = **6** | **可能不一致** | - -**结论：** **级差奖已对齐脑图**；**平级奖/超越奖当前按「基数×固定比例」实现，与脑图「下级佣金×比例」不符**。 - -**已确认（迁移采用）：** -- **平级奖** = 上一层创客**本单已发金额** × `maker_equal_rate`（10%） -- **超越奖** = 上一层创客**本单已发金额** × `maker_over_rate`（5%） -- 修正后 S08 预期：近端 V3 得 36，远端同级 V3 得 **3.6**（非现码 12） - -**升级条件扩展（已确认）：** -- 除「直推 3 单」外，**伞下任意层级品酒单**也计入 4 单考核 -- 新增 `team_order_count`（或递归统计下级有效品酒单），满足：直推≥3 **或** (自购≥1 且 直推+自购+伞下≥4) - -### 2.5 推荐链与并行角色 - -- 创客链：[`ChainResolver::getMakerChain`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\ChainResolver.php) 沿 `user.parent_user_id` 向上，**只保留有 maker 角色的节点**（中间纯品酒师/合伙人跳过） -- 与酒道馆/区县代理 **并行结算**（`RewardEngine` 同单多次调用），互不替代 -- 商品需 `enable_team=1` 才计入创客基数（[`GoodsRewardResolver::hasTeamLines`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\GoodsRewardResolver.php)） - -### 2.6 Shopro 重构必须保留的创客模块 - -| 模块 | 文件/表 | 迁移到 shopro_business | -|------|---------|------------------------| -| 升级判定 | `RoleService::tryUpgradeMaker` | `AgentUpgradeService` | -| 级差/平级/超越 | `MakerReward::settle` | 同逻辑，**建议修正平级/超越** | -| 基数解析 | `GoodsRewardResolver::sumMakerTeamBase` | 保留，读 `enable_team` / `team_commission_rate` | -| 等级比例 | `Config::makerRate` + `feitian_role_config` | → `shopro_business_role_config` 或 agent_level 扩展字段 | -| 创客链 | `ChainResolver::getMakerChain` | 改读 `shopro_commission_agent` + level | -| 后台配置 | feitian/role_config | → business 后台或 shopro 等级页扩展 | - -**不可交给 Shopro CommissionHook 的部分：** 级差、平级 10%、超越 5%、120 元固定基数 — Shopro 只有 commission_1/2/3 百分比 MLM，**语义不同**。 - ---- - -## 三、迁移后商品配置统一设计 - -目标：**一套后台 UI，两套引擎分工，不重复发佣**。 - -| 奖励类型 | 负责引擎 | 商品配置来源 | -|----------|----------|--------------| -| 标准 MLM 层级佣金（V1-V6 × 1/2/3 级） | Shopro `CommissionHook` | `shopro_commission_goods` | -| 三单固定返佣 398/400/600 | `shopro_business` ReferralReward | `enable_commission` + `commission_rate=0` | -| 商品级百分比推荐奖 | `shopro_business` 或 Shopro（二选一，见下） | `commission_rate>0` | -| 创客/酒道馆团队基数 | `shopro_business` Maker/JdgReward | `enable_team` + `team_commission_rate` | -| 品酒单识别 | `shopro_business` OrderQualify | `is_feitian_order`（迁移后 rename → `is_business_order`） | - -**防双发策略（关键）：** -- 1398 品酒单 + 固定返佣/极差/区域奖 → **Shopro 对该类商品 `commission_goods.status=0` 或 commission_1/2/3 全为 0** -- 仅对需要标准 MLM 的普通商品开启 `shopro_commission_goods` -- `shopro_business` Hook 在 `CommissionHook` **之后**执行，且读取 `SettleContext` 幂等锁 - -**商品 UI 改造（Phase 3）：** -- **Shopro 原生入口**（MLM）：分销 → 分销商品 → 编辑（`status` / `commission_level` / `commission_1~3`），见 **§1.3.2 B** -- **Business 入口**（固定奖/极差）：商品编辑 →「业务分销设置」（`enable_commission` / `enable_team` / 两个 rate），由原「飞天分销设置」改名 -- 后台增加联动说明：品酒单 → Business 四字段 + `commission_goods.status=0`；普通 MLM 商品 → 分销商品页配置 - -**数据迁移脚本（新增）：** -- 现有 `enable_commission/enable_team/commission_rate/team_commission_rate` **保留列，仅 rename 注释** -- 为已标记 `is_feitian_order=1` 的商品批量写入 `shopro_commission_goods.status=0`（避免恢复 commission 后双发） - ---- - -## 四、切流顺序（确保 Shopro 分销不受影响） - -```mermaid -sequenceDiagram - participant Admin - participant ShoproComm as Shopro_CommissionHook - participant Business as shopro_business_Hook - participant Feitian as feitian_Hook - - Note over Admin: Phase5前：仅 Feitian 生效 - Admin->>Feitian: order_payed_after - - Note over Admin: Phase5并行：Business+Feitian 二选一 - Admin->>Business: 启用 business hook - Admin->>Feitian: disable 插件（不删文件） - - Note over Admin: Phase5通过后 - Admin->>Admin: 执行 enable-commission.sql - Admin->>ShoproComm: commission_level=3 - Admin->>Business: 仅处理固定/极差/资产 - - Note over Admin: Phase6：卸载飞天 - Admin->>Feitian: 删除代码+清理残留 -``` - -### 切流检查清单 - -1. **恢复 Shopro 分销前**：确认 `shopro_business` Hook 已接好且 feitian Hook 已 disable -2. 执行 `enable-commission.sql`（反向脚本）：`commission_level` 恢复为 3（或业务要求值） -3. 配置 V1-V6 等级默认规则（[`shopro/commission/level`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\commission\Level.php)） -4. 品酒单商品：`shopro_commission_goods.status=0` -5. 下测试单验证：**commission_order + business_settle_log 各一条，金额不重复** -6. 退款：`order_refund_after` 两边均 rollback - ---- - -## 五、Phase 6 飞天卸载 — 零残留清单 - -**原则：** 先验证 `shopro_business` 全功能 → 再卸载 → 逐项 grep 验收。**禁止** Phase 0-5 完成前卸载。 - -### 4.1 插件与 Hook - -| 步骤 | 路径/操作 | 验证 | -|------|-----------|------| -| 后台禁用插件 | 插件管理 → feitian → 禁用 | `hooks.php` 不再注册 | -| 卸载插件 | 卸载（仅删菜单） | `fa_auth_rule` 无 `feitian%` | -| 删除插件目录 | [`addons/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian) 整目录 | — | -| 确认无 Hook 残留 | grep `feitian` in `addons/shopro/hooks.php`、根目录 hooks | 0 匹配 | - -[`Feitian.php::uninstall()`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\Feitian.php) **仅删菜单**，不删表/不删代码 — 必须手动清理下列全部项。 - -### 4.2 后台 PHP / 视图 / JS（整目录删除） - -- [`application/admin/controller/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\feitian)（9 控制器） -- [`application/admin/model/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\model\feitian) -- [`application/admin/view/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\feitian) -- [`public/assets/js/backend/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\public\assets\js\backend\feitian) - -### 4.3 CLI / Cron - -[`application/command.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\command.php) 删除 5 行： - -- `AcceptanceTest`, `YundouSettle`, `VoucherRelease`, `DividendCycle`, `PoolDistribute` - -Crontab 删除（[`addons/feitian/scripts/cron-daily.sh`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\scripts\cron-daily.sh)）： - -- `feitian:yundou_settle` -- `feitian:voucher_release` -- `feitian:dividend_cycle` -- `feitian:pool_distribute` - -**迁移到** `shopro_business:*` 命令后再删旧 cron。 - -### 4.4 数据库（21 张 feitian 表） - -来自 [`addons/feitian/install.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\install.sql)： - -`feitian_user_role`, `maker_upgrade_log`, `role_config`, `referral_order`, `madao_account/log`, `yundou_account/log`, `voucher_account/release_plan/log`, `reward_log`, `pool`, `pool_distribute`, `green_pool`, `dividend_cycle`, `settle_log`, `exchange_goods/order`, `cron_log`, `config` - -**处理策略：** -- **Phase 1-5：** 表保留，business 层可读旧数据 -- **Phase 6 确认迁移后：** `RENAME TABLE fa_feitian_* TO fa_shopro_business_*`（保留历史）或归档后 DROP -- **禁止**在 business 未接管前 DROP - -### 4.5 Shopro 表补丁字段（谨慎处理） - -| 字段 | 来源 SQL | Phase 6 处理 | -|------|----------|--------------| -| `shopro_goods.is_feitian_order` | feitian-patch-goods.sql | rename → `is_business_order`（business 继续用） | -| `enable_commission/enable_team/commission_rate/team_commission_rate` | feitian-patch-goods-reward.sql | **保留**，business 继续读；仅 UI 改名 | -| `shopro_store.store_type` 等 | feitian-patch-store.sql | 若 business 用则保留 | - -**不要 DROP 上述列** — 它们是业务规则所需，只是来源是飞天补丁。 - -### 4.6 Wallet 日志类型 - -[`Feitian.php::registerWalletLogTypes()`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\Feitian.php) 注册了 `ft_agent_nat_div` 等 4 种类型 → **迁移到 `shopro_business` 的 appInit**，否则历史流水显示异常。 - -### 4.7 小程序前端（hlst_wx） - -**删除：** -- [`pages/app/feitian/`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\feitian) 整目录（9 页 + 7 组件） -- [`common/feitian-constants.js`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\common\feitian-constants.js)、[`feitian-assets.js`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\common\feitian-assets.js) -- `pages.json` 中 feitian 分包路由 -- `env.js` 中 `FEITIAN_API_URL` -- API 定义中 `feitian.*` 分组 - -**改引用（至少 6 处）：** -- [`pages/index/user.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\index\user.vue) L102-103 → commission 路径 -- [`pages/index/user/userinfo-card.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\index\user\userinfo-card.vue) → commission 角色 badge -- [`pages/index/components/sh-wallet.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\index\components\sh-wallet.vue) -- [`pages/index/components/sh-grid-swiper.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\index\components\sh-grid-swiper.vue) -- [`pages/index/index/home-head.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\index\index\home-head.vue) -- 装修 JSON / demo SQL 中 `/pages/app/feitian/*` 链接 - -**保留并迁移 UI：** 马豆/云豆/兑换券/兑换商城 → 挂到 `pages/app/commission/` 子页或 business 分包，API 改 `shopro_business.*` - -### 4.8 Seed / 文档 / 杂项 - -- [`database/seed/feitian-*.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed) — 归档到 `database/seed/archive/`，避免误执行 disable-commission -- [`database/seed/install-feitian-menu.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\install-feitian-menu.php) — 删除 -- 商品模板移除「飞天」字样，改为「业务分销设置」 - -### 4.9 卸载后验收 grep（必须 0 结果） - -```bash -# 后端 -rg -i feitian application/ addons/ public/assets/js/backend/ application/command.php - -# 前端 -rg -i feitian pages/ common/ pages.json env.js - -# 运行时 -curl /addons/feitian/index → 404 -php think feitian:dividend_cycle → 命令不存在 -下测试单 → shopro_commission_order 有记录（若商品参与） -下 1398 单 → business settle 有记录，无 feitian settle -``` - -### 4.10 卸载后 Shopro 分销保障 - -| 检查项 | 期望 | -|--------|------| -| `shopro_commission_config.commission_level` | > 0 | -| `CommissionHook` 注册 | shopro hooks 正常 | -| 分销商品 status | 普通商品=1，品酒单=0 | -| 无 feitian Hook | 不重复结算 | -| 钱包流水 | commission_reward + business 类型均正常 | - ---- - -## 六、实施阶段（更新） - -### Phase 0：冻结与备份（1 天） -- 备份全部 `feitian_*` + `shopro_commission_*` + `shopro_goods` 相关列 -- 暂停 feitian crontab -- **禁止卸载** - -### Phase 1：shopro_business 骨架（3 天） -- 新建 `addons/shopro_business/`，迁移 library（含 `GoodsRewardResolver`） -- `shopro_commission_agent_ext` 表 -- order hooks（CommissionHook 之后） -- CLI 命令 `shopro_business:*` - -### Phase 2：启用 Shopro 分销 + 商品策略（2 天） -- `enable-commission.sql` -- V1-V6 等级配置 -- **品酒单** `commission_goods.status=0`；**普通商品**按需开启 -- maker → agent 数据迁移 - -### Phase 3：后台（4 天） -- 复用 shopro/commission 后台 -- 商品页：「业务分销设置」四字段 + 分销商品页 MLM 配置 -- business 管理页（角色标签/分红/资产/兑换） - -### Phase 4：小程序（4 天） -- 切回 [`pages/app/commission/*`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\commission) -- 资产/兑换 API → shopro_business -- 清除 feitian 引用 - -### Phase 5：切流验证（3 天） -- 1398 品酒单：三单返佣 + 极差 + 标签奖 + 资产 -- 普通商品：Shopro MLM 佣金 -- 退款双 rollback -- 与 feitian 历史抽样对比 - -### Phase 6：卸载 + 零残留（2 天） -- 按 **第四节清单** 逐项执行 -- grep 验收 + 测试单复验 -- 表 rename 归档（非直接 DROP） - ---- - -## 七、风险补充 - -| 风险 | 规避 | -|------|------| -| 卸载后 Shopro 分销仍关闭 | Phase 2 必须执行 enable-commission，Phase 6 前复验 | -| 品酒单双发（Shopro%+固定奖） | 品酒单 `commission_goods.status=0` | -| 商品四字段被误删 | Phase 6 只删 feitian 代码，**保留 shopro_goods 列** | -| 团队奖丢失 | `enable_team`/`team_commission_rate` 由 business 继承，不走 Shopro commission_2 | -| 创客平级/超越算法与脑图不符 | **已确认按脑图修正**：平级/超越 = 上一层本单佣金 × 10%/5% | -| 创客升级缺伞下统计 | **已确认扩展** `team_order_count`，伞下品酒单计入 4 单考核 | -| cron 断档 | business cron 上线后再删 feitian cron | - -**预估工期不变：4~6 周**（1 人全职） diff --git a/plan/taro_小程序对齐方案_b61be661.plan.md b/plan/taro_小程序对齐方案_b61be661.plan.md deleted file mode 100644 index 113dec4..0000000 --- a/plan/taro_小程序对齐方案_b61be661.plan.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -name: Taro 小程序对齐方案 -overview: 推荐使用 **Taro 4 + React + TypeScript** 重构微信小程序，通过 monorepo 与现有 React H5 共享页面逻辑、API、类型和设计令牌，实现「改一处、两边同步」，界面可达 ~90% 一致。不推荐继续维护当前原生 WXML 小程序或改用 uni-app（需从 React 重写为 Vue）。 -todos: - - id: setup-monorepo - content: 搭建 pnpm/npm workspace monorepo，初始化 Taro 4 + React + TS 项目于 apps/weapp/ - status: completed - - id: extract-shared - content: 抽取 packages/shared（types、api-client、vip 逻辑、storage 抽象、设计令牌） - status: completed - - id: build-ui-icons - content: 建立 packages/icons（Lucide 统一）和 packages/ui（Button/Card/TabBar/TopNavBar 跨端组件） - status: completed - - id: pilot-idiom - content: 迁移成语模块 5 页 + 自定义 BottomTabBar 作为 POC 验收 - status: completed - - id: migrate-plaza-profile - content: 迁移 PlazaPage 与个人中心相关页面 - status: completed - - id: migrate-modules - content: 迁移行测/打印/资料/大神练/分销等剩余业务模块 - status: completed - - id: wechat-native - content: 接入 wx.login、微信支付、分享，API 对接 Express 后端 - status: completed - - id: deprecate-native - content: 废弃 miniprogram/ 原生代码，更新启动教程与部署流程 - status: completed -isProject: false ---- - -# React H5 与微信小程序统一方案（Taro 4） - -## 现状诊断：为什么差别这么大 - -当前仓库是 **两套完全独立的实现**，不存在编译关系： - -| 维度 | React H5 ([`src/`](f:\source_code\new_renmrb\src)) | 原生小程序 ([`miniprogram/`](f:\source_code\new_renmrb\miniprogram)) | -|------|------|------| -| 语言 | TypeScript + React 19 | JavaScript + WXML/WXSS | -| 图标 | `lucide-react` SVG（Home, BookOpen, PenTool…） | Emoji（📖 ✍️ 📝）+ PNG Tab 图标 | -| 样式 | Tailwind v4 + shadcn/ui + CSS 变量 | 手写 WXSS | -| 导航 | 自定义 [`BottomTabBar.tsx`](f:\source_code\new_renmrb\src\components\BottomTabBar.tsx)（成语模块 5 Tab） | 原生 `tabBar`（广场 5 Tab：首页/行测/打印/资料/我的） | -| 数据 | [`src/lib/api.ts`](f:\source_code\new_renmrb\src\lib\api.ts) + Express API | [`mockData.js`](f:\source_code\new_renmrb\miniprogram\utils\mockData.js) 本地 mock | - -**结论**：没有任何语言/工具能「一键编译」现有 React + Tailwind + shadcn + lucide 为 100% 一致的小程序。要实现代码共用，必须引入 **跨端 React 框架**，并做一层 UI 适配。 - ---- - -## 技术选型对比 - -```mermaid -flowchart TD - subgraph options [可选方案] - Taro["Taro 4 + React\n推荐"] - UniApp["uni-app + Vue\n需重写"] - WebView["web-view 嵌 H5\n100% UI 但不共用代码"] - Native["继续原生 WXML\n手工同步"] - Remax["Remax\n维护弱"] - end - - ReactH5["现有 React H5"] --> Taro - ReactH5 -.->|"无法直接编译"| Native - ReactH5 -->|"仅视觉一致"| WebView - ReactH5 -->|"语法不兼容"| UniApp - - Taro --> WeApp["微信小程序"] - Taro --> H5Out["同构 H5 可选"] -``` - -| 方案 | 能否共用 React 代码 | 界面一致度 | 适合你的需求 | -|------|-------------------|-----------|-------------| -| **Taro 4 + React** | 高（页面/逻辑/类型/API 可共享） | ~85–90% | **最佳** | -| uni-app | 低（Vue 语法，需全量重写） | 可达 90% | 不推荐 | -| web-view 嵌 H5 | 无（只是壳） | 100% | 不符合「共用代码」 | -| 继续原生 WXML | 无 | 需手工对齐 | 长期双份维护 | -| Remax | 中 | ~80% | 社区活跃度低于 Taro | - -**推荐：Taro 4 + React + TypeScript + Tailwind（weapp 插件）** - ---- - -## 目标架构 - -```mermaid -flowchart TB - subgraph monorepo [Monorepo 结构] - Shared["packages/shared\n类型 / API / 业务逻辑 / 设计令牌"] - Icons["packages/icons\nLucide SVG 统一图标"] - UI["packages/ui\n跨端基础组件 Button Card TabBar"] - H5App["apps/h5\n现有 Vite React 应用"] - WeApp["apps/weapp\nTaro 微信小程序"] - end - - Shared --> H5App - Shared --> WeApp - Icons --> H5App - Icons --> WeApp - UI --> H5App - UI --> WeApp - - WeApp --> WX["微信开发者工具"] - H5App --> Browser["浏览器 H5"] - Shared --> Server["Express API\nserver/index.ts"] - WeApp --> Server -``` - -### 共享层（改一处两边生效） - -从现有代码抽取到 `packages/shared/`： - -- **类型定义**：`IUserData`、`IFavoriteItem` 等（已在 AGENTS.md 定义） -- **API 客户端**：基于 `Taro.request` / `fetch` 的统一 HTTP 层，对接 [`server/index.ts`](f:\source_code\new_renmrb\server\index.ts) 真实接口（替换 H5 的 `adminDb` mock 和小程序的 `mockData.js`） -- **业务逻辑**：[`src/lib/vip.ts`](f:\source_code\new_renmrb\src\lib\vip.ts) 会员/试看/学习统计 -- **设计令牌**：从 [`src/tailwind-theme.css`](f:\source_code\new_renmrb\src\tailwind-theme.css) 导出 CSS 变量（人民日报红 `#C8102E`、米白 `#F7F3ED`） -- **路由常量**：H5 路径与 Taro 页面路径映射表 - -### 平台适配层（各端少量差异） - -| H5 专用（不迁入小程序） | 小程序专用 | -|------------------------|-----------| -| `PhoneFrame.tsx` 手机外框 | `wx.login` / 微信支付 | -| Admin 后台 40+ 页 | `onShareAppMessage` 分享 | -| `@lark-apaas/client-toolkit-lite` | `Taro.getStorageSync` | -| `framer-motion` 复杂动效 | CSS transition 简化版 | - ---- - -## 关键兼容性与解决策略 - -### 1. 图标统一（解决「图标不匹配」） - -- 建立 [`packages/icons`](f:\source_code\new_renmrb)：`lucide-react` 图标导出为 SVG 字符串 -- H5：继续用 `lucide-react` -- 小程序：Taro 内渲染 `` 或 inline SVG 组件 -- TabBar：用 **自定义 TabBar 组件**（与 H5 [`BottomTabBar.tsx`](f:\source_code\new_renmrb\src\components\BottomTabBar.tsx) 同结构），替代原生 PNG `tabBar`，保证 lucide 图标一致 - -### 2. Tailwind 样式 - -- H5：保持 Tailwind v4 -- 小程序：Taro + `weapp-tailwindcss` 或 `@tarojs/plugin-html` + postcss，复用同一套 utility class -- 设计变量从 `tailwind-theme.css` 双端引用 - -### 3. shadcn / Radix 组件 - -- **不能直接使用**（依赖 DOM/Radix Portal） -- 方案：在 `packages/ui/` 重建轻量版 Button、Card、Dialog、Tabs，API 尽量与 shadcn 一致 -- 复杂组件（Dialog/Sheet）可用 **Taroify** 或 **NutUI-Taro** 做底座，外层套项目 design token - -### 4. 路由映射（全平台 26+ 页） - -H5 `react-router` 路由 → Taro `app.config.ts` pages： - -| H5 路由 | Taro 页面 | 说明 | -|---------|----------|------| -| `/` | `pages/plaza/index` | 广场首页 | -| `/idiom` | `pages/idiom/home/index` | 成语首页 | -| `/idiom/sentences` | `pages/idiom/sentences/index` | 每日金句 | -| `/idiom/practice` | `pages/idiom/practice/index` | 精炼练习 | -| `/idiom/dictation` | `pages/idiom/dictation/index` | 成语默写 | -| `/xingce/*` | `pages/xingce/*` | 行测模块 | -| `/print/*` | `pages/print/*` | 打印模块 | -| `/ziliao/*` | `pages/ziliao/*` | 资料模块 | -| `/mingshi/*` | `pages/mingshi/*` | 大神练模块 | -| `/profile/*` | `pages/profile/*` | 个人中心 | -| `/admin/*` | **仅 H5** | 后台不进小程序 | - -成语模块 TabBar 逻辑复刻 H5：首页 / 金句 / 精炼 / 默写 / 我的（非原生 tabBar 的 5 模块 Tab）。 - ---- - -## 分阶段实施计划 - -### 阶段 0：脚手架（1–2 天） - -- 根目录改为 npm/pnpm workspace monorepo -- `npx @tarojs/cli init apps/weapp` 创建 Taro 4 + React + TS 项目 -- 配置 Tailwind、路径别名 `@/`、共享包引用 -- 保留现有 H5 在 `apps/h5/`（或暂留根目录 `src/`，逐步迁移） - -### 阶段 1：共享基础设施（2–3 天） - -- 抽取 `packages/shared`：types、api-client、vip、constants -- 实现 `storage` 抽象：`createStorage({ platform: 'h5' | 'weapp' })` -- 图标包 `packages/icons`：从 lucide 导出 TabBar 所需的 Home/BookOpen/PenTool/Pencil/User 等 -- UI 基座 `packages/ui`：Button、Card、TabBar、TopNavBar（对齐 H5 视觉） - -### 阶段 2：成语模块试点（3–5 天） - -优先迁移与 AGENTS.md 对齐的核心页，验证共用代码可行性： - -- `HomePage` → 成语首页 -- `GoldenSentencesPage` → 金句列表 -- `PracticePage` → 练习 -- `DictationPage` → 默写 -- `MembershipPage` → 会员 -- 自定义 BottomTabBar + IdiomLayout - -**验收标准**：成语模块 H5 与小程序截图对比 ≥90% 一致，图标全部为 lucide 风格。 - -### 阶段 3：广场 + 个人中心（2–3 天） - -- `PlazaPage` → 广场首页（模块网格、学习数据条） -- `ProfilePage` + 子页（收藏、错题、设置等） -- 广场级 TabBar（若 H5 有模块切换逻辑） - -### 阶段 4：其余业务模块（5–7 天） - -- 行测 `/xingce` -- 打印 `/print` -- 资料 `/ziliao` -- 跟着大神练 `/mingshi` -- 分销 `/distribution`、分享页 - -### 阶段 5：微信能力 + 下线旧小程序（2–3 天） - -- 对接 `wx.login`、微信支付、分享卡片 -- API 全部指向 Express 后端（[`启动教程.md`](f:\source_code\new_renmrb\启动教程.md) 第四节） -- 废弃 [`miniprogram/`](f:\source_code\new_renmrb\miniprogram) 原生代码，改为 `apps/weapp/dist` 上传 - ---- - -## 预期效果与局限 - -**能做到：** -- 页面结构、文案、配色、图标风格与 H5 高度一致 -- 业务逻辑、API、类型单份维护 -- 新功能开发一次，编译到 H5 + 微信小程序 - -**~10% 差异（可接受）：** -- `framer-motion` 弹簧动效 → CSS 简化过渡 -- Radix Dialog 焦点陷阱 → Taroify 弹层行为略有不同 -- H5 的 `PhoneFrame` 外框在真机小程序中不存在 -- 部分 Web 专属 API（如 `@lark-apaas`）仅 H5 可用 - -**Admin 后台**：保持纯 H5，不纳入 Taro 小程序。 - ---- - -## 不推荐的路径（供参考） - -- **uni-app**：语法是 Vue，无法复用现有 React 组件，等于重写整个前端 -- **web-view 壳**：界面 100% 一致，但不共享 React 代码，且支付/登录/审核受限 -- **继续维护原生 WXML**：每改一个图标/布局要改两遍，正是当前「差别很大」的根因 - ---- - -## 工作量估算 - -| 阶段 | 工期 | 产出 | -|------|------|------| -| 0–1 基础设施 | ~1 周 | monorepo + 共享层 + UI/图标基座 | -| 2 成语试点 | ~1 周 | 可演示的对齐版成语模块 | -| 3–4 全平台页面 | ~2 周 | 完整业务覆盖 | -| 5 微信能力 | ~3 天 | 可上线版本 | -| **合计** | **约 4–5 周** | 替换现有原生小程序 | - -建议从 **阶段 2 成语模块** 做 POC：1 周内可验证 Taro 方案是否满足你的「共用代码 + 界面接近」目标，再决定是否全量迁移。 diff --git a/plan/分销需求差异核对_53c87321.plan.md b/plan/分销需求差异核对_53c87321.plan.md deleted file mode 100644 index 00120d4..0000000 --- a/plan/分销需求差异核对_53c87321.plan.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -name: 分销需求差异核对 -overview: 当前系统基于 Shopro v1.3.8 标准多级分销模块，推广分销核心能力基本具备；但「省市区县区域代理」整块缺失，「复购返现」「邀请码」「级差/管理奖」等与需求文档存在明显差异。 -todos: - - id: gap-regional-agent - content: 区域代理模块整块缺失 — 需新建代理等级、区域绑定、地址匹配、区域分佣、后台与小程序 - status: completed - - id: gap-repurchase - content: 复购返现未实现 — 需新增首购/复购识别、复购佣金规则、买家自返配置 - status: completed - - id: gap-differential - content: 团队收益机制不同 — 当前为关系链分佣，需求为级差/管理奖，需改造分润算法 - status: completed - - id: gap-invite-code - content: 邀请码体系缺失 — 当前仅用 spm 用户 ID，需独立邀请码生成与绑定 - status: completed - - id: partial-dashboard - content: 推广看板功能分散 — 可整合 index.vue 为统一数据看板 - status: completed -isProject: false ---- - -# 当前系统分销 vs 需求文档差异核对 - -## 总体结论 - -| 模块 | 匹配度 | 说明 | -|------|--------|------| -| 推广分销（关系绑定、直推、等级、看板、提现） | **约 75%** | 核心链路已有，部分机制与需求描述不一致 | -| 省市区县区域代理 | **0%** | 整块未实现，需全新开发 | - -当前技术栈：后端 [`addons/shopro/library/commission/`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\)，小程序 [`pages/app/commission/`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\)。 - ---- - -## 一、推广分销模块对比 - -### 1. 推广关系绑定 — 部分匹配 - -**需求：** 通过邀请码、分享海报、分享链接建立上下级关系。 - -**现状：** -- 分享海报、分享链接：**已实现**（`spm` 参数追踪，[`shopro/share/index.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro\share\index.js) + [`shopro-share.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-share\shopro-share.vue)） -- 独立邀请码：**未实现**，绑定依赖分享者 **用户 ID** 嵌入 `spm`，无单独邀请码生成/输入/展示 UI -- 绑定时机可配置：`share`（点击链接）/ `pay`（首次支付）/ `agent`（成为下级分销商） - -```mermaid -flowchart LR - subgraph req [需求] - A1[邀请码] - A2[分享海报] - A3[分享链接] - end - subgraph cur [当前系统] - B1["spm用户ID追踪"] - B2[分享海报] - B3[分享链接] - end - A1 -.->|缺失| B1 - A2 --> B2 - A3 --> B3 -``` - ---- - -### 2. 直推奖励 — 已匹配 - -**需求：** 直推用户下单，推荐人获得佣金，后台可配置比例。 - -**现状：** -- 一级佣金（`commission_1`）即直推奖励 -- 比例/固定金额可在 **分销商等级** 和 **商品独立规则** 中配置 -- 结算基数可选实付价或商品价；结算节点可选支付/确认收货/完成 - -核心逻辑：[`Commission.php` → `runCommissionPlan()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Commission.php) 递归向上分佣。 - ---- - -### 3. 团队等级体系 — 基本匹配 - -**需求：** 多等级（普通/白银/黄金/钻石），按直推人数 + 团队业绩自动升级。 - -**现状：** -- 分销商等级表 `shopro_commission_agent_level`，支持自定义名称、徽章、佣金规则 -- 自动升级条件丰富：个人消费、团队人数、团队订单金额/数量、下级分销商数量/等级等 -- 支持「满足任一条件」或「满足全部条件」升级 -- 支持跳级升级、升级审核 - -**差异：** -- 前端无独立「等级进度/升级说明」页（`commission.lv` API 已定义但未使用） -- 等级体系是 **分销商个人等级**，不是独立的「团队组织等级」概念 - ---- - -### 4. 团队收益 — 机制不同（重要差异） - -**需求：** 按团队业绩计算 **管理奖/级差奖**，不同等级享受不同佣金比例。 - -**现状：** -- 佣金模型是 **关系链多级分佣**（默认 2 级：直推 + 间推），每级按该分销商 **自身等级** 的 `commission_N` 规则独立计算 -- 有团队统计（一级/二级/团队人数、订单量、金额），但 **不用于额外分润池** -- **没有级差算法**（上级拿「自己与下级比例之差」） -- **没有管理奖/团队业绩分红**（不按团队总业绩额外奖励） - -```mermaid -flowchart TD - Buyer[买家下单] --> L1[一级上级 commission_1] - L1 --> L2[二级上级 commission_2] - L2 --> Stop[停止默认2级] - - subgraph missing [需求有但当前无] - M1[级差奖] - M2[管理奖] - M3[团队业绩池分红] - end -``` - ---- - -### 5. 复购返现 — 未实现（重要差异） - -**需求：** -- 成员复购时，推荐人继续获得佣金 -- 可配置 **用户自身复购** 也获得返现 - -**现状：** -- 代码中 **无「复购」相关逻辑**（全库搜索无匹配） -- 普通订单每次支付都会走标准分佣，推荐人在关系存续期间 **自然能拿到后续订单佣金**，但这与需求中的「复购返现」产品形态不同： - - 无复购专属比例/规则 - - 无「买家自己复购返现」配置（仅有分销商 **自购分佣** `self_buy`，且仅限已是分销商的用户） - - 无复购次数/周期/上限等控制 - ---- - -### 6. 推广数据看板 — 基本匹配 - -**需求：** 展示团队成员数、直推订单、团队总订单、收益明细、佣金统计。 - -**现状（分散在多页，无独立「看板」页名）：** - -| 需求项 | 对应页面/功能 | 状态 | -|--------|--------------|------| -| 团队成员数 | [`team.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\team.vue) | 有 | -| 直推订单 | [`order.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\order.vue) | 有 | -| 团队总订单 | `order.vue` 团队统计 | 有 | -| 收益明细 | [`commission-log.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\commission-log.vue) | 有 | -| 佣金统计 | [`index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\index.vue) 总收益/待入账 | 有 | - -**差异：** 数据分散在「分销中心 + 团队 + 订单 + 明细」多个入口，未整合为单一「推广数据看板」页面；缺少更细粒度的图表/趋势分析。 - ---- - -### 7. 提现管理 — 已匹配 - -**需求：** 用户申请提现、后台审核、打款记录、对接第三方支付自动打款。 - -**现状：** -- 小程序：[`withdraw.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\user\wallet\withdraw.vue) / [`withdraw-log.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\user\wallet\withdraw-log.vue) -- 支持微信/支付宝/银行卡；微信/支付宝可开启 **自动打款**（`wechat_alipay_auto`） -- 后台审核、手续费、每日限额等均可配置 -- 佣金结算后进入用户钱包 `user.money`，与推广提现共用同一钱包体系 - ---- - -## 二、省市区县区域代理模块对比 - -### 整块缺失 — 0% 实现 - -需求文档中的 **区域代理** 与现有 **分销商（commission agent）** 是两套完全不同的业务模型。当前系统中： - -- `shopro_area` 仅用于 **收货地址** 省市区选择，不参与分佣 -- `shopro_store` 是 **线下门店/O2O** 模块，不是区域销售代理 -- 无任何「按收货地址匹配区域代理并分佣」的逻辑 - -| 需求功能 | 当前状态 | -|----------|----------| -| 代理等级（省/市/区县，可扩展） | 无 | -| 后台手动添加代理 | 无 | -| 用户在线申请 + 审核 | 无（仅有「申请分销商」，非区域代理） | -| 按订单收货地址自动匹配区域代理 | 无 | -| 区域内订单按比例/固定金额分佣 | 无 | -| 区域业绩统计（订单量、销售额、佣金明细） | 无 | -| 代理管理后台（列表、区域分配、等级调整、结算） | 无 | -| 代理独立提现流程 | 无（共用钱包提现，无代理身份区分） | - -```mermaid -flowchart LR - Order[订单收货地址] -->|需求| AgentMatch[匹配省市区代理] - AgentMatch --> AgentFee[区域代理分佣] - - Order -->|当前| Commission[关系链分销分佣] - Commission --> Parent[上级分销商] -``` - ---- - -## 三、差异汇总表 - -### 已实现 / 基本满足 - -- 分享海报、分享链接推广绑定 -- 直推佣金（可配置比例） -- 分销商多等级 + 自动升级 -- 二级（可配置 N 级）关系链分佣 -- 推广数据统计（团队/订单/佣金） -- 提现申请、审核、自动打款 -- 分销商申请与后台审核 -- 退款扣回佣金/业绩 - -### 部分实现 / 机制不同 - -- **邀请码** → 仅有 spm 用户 ID，无独立邀请码 -- **团队收益** → 有多级分佣 + 等级差异比例，但无级差奖/管理奖/团队业绩分红 -- **推广看板** → 功能分散，非统一看板页 -- **复购** → 关系存续期间普通订单仍分佣，但无专属复购返现规则 -- **自购返现** → 仅有分销商自购分佣（`self_buy`），非普通用户复购返现 - -### 完全缺失（需新开发） - -- **省市区县区域代理** 整套模块（7 项功能全部缺失） -- **复购返现** 独立业务规则（复购比例、买家自返、次数限制等） -- **邀请码** 生成/展示/输入体系 -- **级差/管理奖** 分润算法 - ---- - -## 四、若需补齐需求的开发方向（参考） - -按工作量与业务独立性，建议优先级： - -1. **P0 — 区域代理模块**（全新）：代理表、区域绑定、订单地址匹配、区域分佣、代理后台、代理端小程序页 -2. **P1 — 复购返现**：订单标记首购/复购、独立佣金规则、买家自返配置 -3. **P2 — 级差/管理奖**：改造 [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\commission\Commission.php) 分润算法，或新增团队业绩结算任务 -4. **P3 — 邀请码体系**：用户邀请码字段、海报/链接携带码、注册/绑定入口 -5. **P4 — 推广看板整合**：新建或改造 `index.vue`，汇总团队/订单/佣金图表 - -区域代理可在现有 `commission` 钱包/提现基础设施上扩展，但 **业务模型、数据表、结算逻辑均需独立设计**，不宜简单复用现有分销商等级体系。 diff --git a/plan/区域代理需求对照_060fc1ce.plan.md b/plan/区域代理需求对照_060fc1ce.plan.md deleted file mode 100644 index 0a2863d..0000000 --- a/plan/区域代理需求对照_060fc1ce.plan.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -name: 区域代理需求对照 -overview: 对照需求图核对当前 Shopro 区域代理实现，列出已满足项与出入点，并按「运营可用性优先 + 分佣模式可配置」给出分阶段完善方案。 -todos: - - id: p0-commission-config - content: "P0: 后台佣金配置 — 代理设置页增加分佣模式；代理等级页配置比例/固定金额（按单）" - status: completed - - id: p0-level-crud - content: "P0: 新增代理等级管理 CRUD（参考分销等级页，含佣金类型切换 UI）" - status: completed - - id: p0-menu - content: "P0: 补全 menu.php 菜单（代理订单、佣金明细、代理等级管理）" - status: completed - - id: p0-agent-edit - content: "P0: 代理编辑页 — 区域变更 + 等级调整 + 状态管理 UI" - status: completed - - id: p0-agent-add-ux - content: "P0: 后台添加页 — 用户搜索 + 省市区级联选择器" - status: completed - - id: p0-mp-withdraw - content: "P0: 小程序代理中心 — 展示 delay_money + 提现入口" - status: completed - - id: p0-wallet-log - content: "P0: UserWalletLog 注册 regional_agent_income/back 中文类型" - status: completed - - id: p0-agent-custom-commission - content: "P0: 单个代理自定义佣金（优先于等级通用配置）" - status: completed - - id: p1-commission-mode - content: "P1: 新增 commission_mode 配置（stack/exclusive/differential）并改造 Commission.php" - status: completed - - id: p1-fixed-amount - content: "P1: 改造 Commission.php 固定佣金为按单计（当前是按件×数量，与需求不符）" - status: completed - - id: p2-stats - content: "P2: 时间筛选、导出、后台业绩看板" - status: completed - - id: p2-notify - content: "P2: 审核结果通知（RegionalAgent + 后台消息配置注册）" - status: completed - - id: p2-goods-toggle - content: "P2: 商品级 regional_enable 开关" - status: completed - - id: p2-dynamic-level - content: "P2: 动态等级匹配（读取等级表）" - status: completed - - id: p2-test-scripts - content: "P2: 区域代理测试脚本（setup/cleanup/verify）" - status: completed -isProject: false ---- - -# 区域代理需求对照与完善计划 - -## 需求图 vs 现状总览 - -```mermaid -flowchart LR - subgraph req [需求图] - A1[代理等级] - A2[申请开通] - A3[地址匹配] - A4[代理收益] - A5[业绩统计] - A6[管理后台] - A7[代理提现] - end - subgraph cur [当前实现] - B1[3级+等级表] - B2[后台添加+用户申请审核] - B3[收货地址省市区匹配] - B4[比例/固定两种类型] - B5[基础计数+明细列表] - B6[列表/审核/订单/佣金] - B7[通用钱包提现] - end - A1 --> B1 - A2 --> B2 - A3 --> B3 - A4 --> B4 - A5 --> B5 - A6 --> B6 - A7 --> B7 -``` - ---- - -## 一、已满足的需求（无出入） - -| 需求项 | 需求描述 | 当前实现 | 关键文件 | -|--------|----------|----------|----------| -| 代理等级 | 省/市/区县三级 | 已实现，`area_level` 1/2/3 对应省/市/区 | [`upgrade_distribution_features.sql`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_distribution_features.sql) | -| 申请/开通 | 后台手动添加 + 用户在线申请 + 平台审核 | 后台 `add/audit` + 小程序 `apply.vue` + 配置 `agent_check` | [`Agent.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\regional_agent\Agent.php)、[`apply.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\apply.vue) | -| 区域归属匹配 | 按订单收货地址自动匹配 | 支付后 hook，用 `province_id/city_id/area_id` 匹配 | [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) | -| 代理收益（逻辑） | 实付比例 或 固定金额 | `commission_type`: `rate` / `money`，基数为 `pay_price` | [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) | -| 代理收益（后台配置） | 后台可配比例/固定金额 | **不可配**：等级表有字段但无管理页；设置页无佣金项 | 见下方「后台佣金配置」专节 | -| 业绩统计（基础） | 区域订单量、销售额、佣金明细 | 代理表 `order_count/order_money/total_income` + 订单/佣金列表 | [`index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\index.vue) | -| 代理列表 | 后台代理目录 | 列表 + 状态 Tab + 审核 | [`agent/index.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\regional_agent\agent\index.html) | -| 提现流程 | 申请 → 审核 → 打款 | 佣金入账用户余额 → 通用 [`UserWalletApply`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\UserWalletApply.php) 提现 | 链路完整，但非独立模块 | - ---- - -## 二、出入与缺口（按需求模块拆分） - -### 1. 代理等级（可扩展） - -**出入：** -- 需求写「可扩展」，当前**数据库可扩展**（`shopro_regional_agent_level` 表），但**业务逻辑写死 3 级**： - - 匹配逻辑硬编码 `areaMap = [1=>省, 2=>市, 3=>区]`（[`Commission.php:62-66`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php)） - - 前后台 UI 下拉框写死 3 个选项 -- **无后台等级管理页**：比例/固定金额/等级名称只能改 SQL，[`Level.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\model\shopro\regional_agent\Level.php) 模型存在但无 Controller/View - -**需完善：** -- 新增「代理等级管理」后台 CRUD（名称、区域层级、佣金类型、比例/固定金额） -- 匹配逻辑改为读取等级表动态生成，而非硬编码 - ---- - -### 2. 代理申请/开通 - -**出入：** -- 核心流程已对齐 -- 后台手动添加体验差：需手填**用户ID + 区域ID**（[`add.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\regional_agent\agent\add.html)），无用户搜索、无省市区选择器 -- 缺少审核结果通知（小程序订阅消息/站内通知均未接） - -**需完善（运营优先）：** -- 后台添加页：用户搜索选择 + 省市区级联选择（对齐小程序 `apply.vue` 体验） -- 审核通过/驳回通知（可选二期） - ---- - -### 3. 区域归属匹配 - -**出入：** -- 匹配依据正确（收货地址） -- **分佣模式未在需求中明确，当前为「三级叠加」**：同一订单可同时给省、市、区代理分佣 -- 您已确认要**做成可配置**（叠加 / 独占最细级 / 级差） -- 边界情况：无 `province_id` 的订单直接跳过；地址不完整时只匹配有 ID 的层级；无模糊匹配/文本解析兜底 - -**需完善：** -- 在 [`shopro_regional_agent_config`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_distribution_features.sql) 增加 `commission_mode` 配置项： - - `stack` = 叠加（现状） - - `exclusive` = 仅最细一级（有区县只给区县，否则市，否则省） - - `differential` = 级差（高级别拿差额，类似分销级差奖） -- 修改 [`Commission::matchRegionalAgents()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) 按模式过滤/计算 -- 后台「代理设置」页增加该选项说明 - ---- - -### 4. 代理收益（重点：后台需可配置） - -**需求图原文：** 区域内订单按**实付金额比例**或**固定金额**给代理分成。 - -**当前实现 vs 需求：** - -| 配置项 | 需求 | 现状 | 差距 | -|--------|------|------|------| -| 佣金类型 | 比例 / 固定金额 | 等级表有 `commission_type` 字段 | **后台无 UI，只能改 SQL** | -| 比例值 | 后台可配 | 默认省3%/市2%/区1% 写死在 seed | **无等级管理页** | -| 固定金额 | 按单固定 | 代码为 `commission_money × goods_num`（按件） | **口径错误 + 不可配** | -| 结算基数 | 实付金额 | 用 `order_item.pay_price` | 符合 | -| 分佣模式 | 可配置 | 固定三级叠加 | 需加 `commission_mode` 配置 | -| 结算时机 | 可配置 | 设置页已有 `commission_event` | 已满足 | - -**后台佣金配置方案（P0 必做）：** - -拆成两个后台入口，对齐分销等级页的交互风格（参考 [`commission/level/edit.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\commission\level\edit.html)）： - -**A. 代理设置页** — [`regional_agent/config/index.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\regional_agent\config\index.html) 扩展「佣金规则」区块： - -- `commission_mode`（新增）：叠加 / 独占最细级 / 级差 -- `commission_event`（已有）：支付后 / 确认收货 / 订单完成 -- 说明文案：比例按实付金额；固定金额按**每单**计（已确认） - -**B. 代理等级管理页** — 新建 `regional_agent/level` CRUD： - -每个等级（省/市/区县）可独立配置： - -- 等级名称 -- 区域层级（1=省 / 2=市 / 3=区） -- 佣金类型：`rate`（比例）/ `money`（固定金额） -- 比例值 `commission_rate`（%），类型为 rate 时生效 -- 固定金额 `commission_money`（元/单），类型为 money 时生效 - -UI 交互：切换佣金类型时显示/隐藏对应输入框（与分销等级页类似的表单切换）。 - -**C. 代码联动改造：** - -- [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) 固定佣金改为**每单一次**（同一 order_item 只计一次；若多 agent 匹配，各自按等级固定值计） -- [`Config.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Config.php) 增加 `getCommissionMode()` 读取新配置 -- SQL 迁移：向 `shopro_regional_agent_config` 插入 `commission_mode` 默认值 `stack` - -**可选（P2）：** 商品级 `regional_enable` 开关 - ---- - -### 5. 代理业绩统计 - -**出入：** -- 基础三项（订单数、销售额、总收益）**已有** -- 佣金明细列表**已有**（小程序 `rewards.vue`、后台 `reward/index.html`） -- **缺口：** - - API 已返回 `delay_money`（待结算），小程序首页**未展示**（[`info()` 有返回，`index.vue` 未用](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\index.vue)） - - `stats` 接口已写好但前端**未调用** - - 无时间范围筛选、无导出、无后台汇总看板 - - 后台代理列表有统计列，但无独立「区域业绩报表」 - -**需完善（运营优先，轻量）：** -- 小程序首页增加：待结算佣金、提现入口 -- 订单/佣金列表增加日期筛选（二期） -- 后台增加简单汇总（按区域/按时间段）（您选运营优先，统计看板放二期） - ---- - -### 6. 代理管理后台 - -**出入对照：** - -| 需求子项 | 现状 | 缺口 | -|----------|------|------| -| 代理列表 | 有 | — | -| 区域分配 | 申请/添加时指定 | **无编辑**：不能修改已有代理的管辖区域；`update()` 只改 `status/level`，不改 `area_id` | -| 等级调整 | 后端 `update()` 支持改 `level` | **无后台 UI**：列表只有审核/禁用，无编辑弹窗 | -| 结算记录 | 有 `reward` 表 + 后台页 | **菜单未入库**：[`menu.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\config\menu.php) 仅有「代理设置」「区域代理」，缺「代理订单」「佣金明细」；需额外执行 [`upgrade_regional_agent_order_menu.sql`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_regional_agent_order_menu.sql) | - -**需完善（运营优先，P0）：** -1. 合并菜单：将 Order/Reward 菜单写入 [`menu.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\config\menu.php)，避免部署遗漏 -2. 代理编辑页/弹窗：支持修改**区域**、**等级**、**状态** -3. 后台添加页 UX 优化（用户选择 + 区域选择器） -4. 新增代理等级管理页 - ---- - -### 7. 代理提现 - -**出入：** -- 流程上**功能闭环**：佣金 → 用户余额 → 提现申请 → 后台审核 → 打款 -- 但**不是独立的「代理提现」模块**： - - 区域代理中心**无提现入口**（需去「我的钱包」或分销中心） - - 钱包流水类型 `regional_agent_income` / `regional_agent_back` **未注册**到 [`UserWalletLog::$typeAll`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\model\UserWalletLog.php)，流水显示可能为原始 code 而非中文 - - 无法区分「区域代理收入」与「分销佣金」的提现来源（共用余额池） - -**需完善（运营优先，P0）：** -- 小程序区域代理中心增加「去提现」按钮 → `/pages/user/wallet/withdraw` -- 注册钱包流水类型中文名 -- 可选：提现页展示「区域代理可提余额」提示（仍走统一提现，不改底层） - ---- - -## 三、部署/运维层面的出入 - -- 区域代理表结构在 [`upgrade_distribution_features.sql`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_distribution_features.sql)，**不在** `install.sql`，新环境易漏执行 -- 有 [`upgrade_distribution.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_distribution.php) 校验脚本，建议纳入部署 checklist - ---- - -## 四、分阶段实施建议（按您选择的优先级） - -### 阶段 P0 — 运营可用性 + 佣金后台可配置（优先实施） - -| 序号 | 任务 | 涉及文件 | -|------|------|----------| -| P0-1 | **代理等级管理 CRUD**（比例/固定金额/类型切换） | 新建 `regional_agent/level` controller/view/js；参考分销等级页 | -| P0-2 | **代理设置页扩展佣金规则**（分佣模式 + 说明文案） | [`config/index.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\regional_agent\config\index.html)、[`config.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\public\assets\js\backend\shopro\regional_agent\config.js)、SQL 新增 `commission_mode` | -| P0-3 | **固定佣金改按单计** | [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) | -| P0-4 | 补全后台菜单（代理订单、佣金明细、代理等级） | [`menu.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\config\menu.php) | -| P0-5 | 代理编辑：区域变更 + 等级调整 UI | [`Agent.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\regional_agent\Agent.php)、[`agent.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\public\assets\js\backend\shopro\regional_agent\agent.js) | -| P0-6 | 后台添加页：用户搜索 + 省市区选择 | [`add.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\regional_agent\agent\add.html) | -| P0-7 | 小程序代理中心：待结算金额 + 提现入口 | [`index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\index.vue) | -| P0-8 | 钱包流水类型注册 | [`UserWalletLog.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\model\UserWalletLog.php) | - -### 阶段 P1 — 分佣模式引擎改造 - -| 序号 | 任务 | 涉及文件 | -|------|------|----------| -| P1-1 | 实现 `commission_mode` 三种模式的匹配/计算逻辑 | [`Commission.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Commission.php) | -| P1-2 | 级差算法：高级别拿（本档比例/金额 - 下级已拿部分） | 同上 | -| P1-3 | 补充集成测试脚本 | 参考 [`commission_setup_test_users.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\tests\commission_setup_test_users.php) | - -### 阶段 P2 — 增强统计与扩展（后续） - -- 时间范围筛选、数据导出 -- 后台区域业绩看板 -- 审核通知（订阅消息） -- 商品级区域分佣开关 -- 等级体系动态扩展（超过 3 级时的 UI/匹配联动） - ---- - -## 五、已确认 / 待确认的业务口径 - -**已确认：** -- 固定佣金按**每单**计（非按件） -- 分佣模式需后台可配（叠加 / 独占 / 级差） -- 比例基数为实付金额 - -**待确认：** -1. **级差模式**：省 3% / 市 2% / 区 1% 时，区县拿 1%，市级拿 1%（2-1），省级拿 1%（3-2）—— 是否采用此标准级差算法？ -2. **区域变更**：已有历史订单是否仍归属旧区域代理，还是仅对新订单生效？（建议仅对新订单） - ---- - -## 六、结论 - -**核心链路已打通**（申请 → 审核 → 地址匹配 → 分佣 → 入账 → 提现），与需求图大方向一致。 - -**主要出入集中在「佣金后台不可配」和「运营后台不完整」**： -- **佣金配置**：等级表有字段但无管理页；设置页缺分佣模式；固定金额口径错误（按件→需改按单） -- 后台缺区域编辑、完整菜单 -- 分佣固定为三级叠加，引擎待按 `commission_mode` 改造 -- 小程序缺待结算与提现入口 -- 商品级开关、统计深度为次要差距 - -按 P0 → P1 → P2 顺序实施，可在不推翻现有架构的前提下补齐需求图差距。 diff --git a/plan/商务蓝白_ui_改版_d9d0903f.plan.md b/plan/商务蓝白_ui_改版_d9d0903f.plan.md deleted file mode 100644 index 4e10f51..0000000 --- a/plan/商务蓝白_ui_改版_d9d0903f.plan.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -name: 商务蓝白 UI 改版 -overview: 将雄戈小酒小程序切换为商务蓝白风格。Logo 用用户提供的「雄戈」徽章（深蓝+金色）；首页风格已确认；我的页仅改 4 列宫格布局，功能项沿用项目现有 DEFAULT_TOOLS + 后台 grid-list，不照搬预览图占位项。 -todos: - - id: preview-mockups - content: 生成我的页 + 首页 2 张商务蓝白 Mockup 预览图，用户确认后再编码 - status: completed - - id: logo-asset - content: 压缩并上传新 Logo 至 CDN，home-head 改为远程加载 - status: pending - - id: token-migration - content: 更新 theme.scss / theme.js / pages.json / MASTER.md，全局蓝系 token 替换金色 - status: pending - - id: user-page-redesign - content: 重构 userinfo-card（蓝顶+资产栏）、sh-order-card（5项）、sh-grid 仅改 4 列宫格布局，数据沿用 mergedTools - status: pending - - id: home-page-polish - content: 首页风格已确认 — 优化 home-head（新 Logo）、sh-grid-swiper、shopro-goods-card 等 - status: pending - - id: global-sweep - content: 扫尾 wallet/search/tabbar/navbar 及硬编码金色组件，联调验收 - status: pending -isProject: false ---- - -# 雄戈小酒 · 商务蓝白风格整体改版方案 - -## 现状 vs 目标 - -```mermaid -flowchart LR - subgraph current [当前] - A1["暖白 #FAFAF8"] - A2["香槟金 Tab/CTA #C4A574"] - A3["我的页工具区: 分组列表"] - A4["首页: 轻奢搜索头图"] - end - subgraph target [目标参考图] - B1["浅灰页面底 #F5F7FA"] - B2["商务蓝主色 #1677FF / #0369A1"] - B3["我的页: 蓝顶区 + 白卡片 + 4列宫格"] - B4["首页: 清爽商务头 + 卡片化模块"] - end - current --> target -``` - -| 维度 | 当前 | 参考图目标 | -|------|------|------------| -| 主色 | 香槟金 `#C4A574` | 商务蓝 `#1677FF`（主）/ `#0369A1`（深） | -| 页面底 | `#FAFAF8` 暖白 | `#F5F7FA` 冷灰白 | -| 顶区 | 暖色渐变头 | **蓝底白字** 个人中心头 | -| 我的页服务 | [`sh-grid.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-grid.vue) 分组**列表** | **4列图标宫格**（参考图「我的服务」） | -| 订单区 | 4项 + 退换货 | 5项横排（待付款/待发货/待收货/待评价/售后） | -| 资产 | 独立 `sh-wallet` 卡片 | 并入顶区三栏（余额/积分/优惠券） | - ---- - -## UI/UX Pro Max 设计系统（已检索 + 人工校准） - -自动检索「ecommerce business blue」后，**B2B Service** 配色最接近参考图；结合参考图视觉，建议最终 token 如下（覆盖现有 [`static/style/theme.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static/style/theme.scss) 与 [`shopro/config/theme.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro/config/theme.js)）： - -| Token | 新值 | 用途 | -|-------|------|------| -| `$brand-primary` | `#1677FF` | Tab 选中、主按钮、图标强调 | -| `$brand-primary-dark` | `#0958D9` | 顶区渐变深色、按下态 | -| `$brand-primary-light` | `#E6F4FF` | 图标底圆、浅蓝块 | -| `$brand-header-gradient` | `linear-gradient(180deg, #1677FF 0%, #4096FF 45%, #F5F7FA 100%)` | 我的页/首页顶区 | -| `$brand-page-bg` | `#F5F7FA` | 全局页面底 | -| `$brand-card-bg` | `#FFFFFF` | 卡片 | -| `$brand-text` | `#1F2937` | 主文字 | -| `$brand-text-muted` | `#6B7280` | 副文字 | -| `$brand-text-on-primary` | `#FFFFFF` | 蓝底白字 | -| `$brand-price` | `#FF4D4F` | 价格/收入（保留红，不用金） | -| `$brand-border` | `#E5E7EB` | 分割线 | - -**风格关键词（UI/UX Pro Max）：** Minimalism & Swiss Style + Feature-Rich Showcase -**密度：** Standard（4/10） -**动效：** 200ms 按压反馈，无复杂动画 -**避免：** 大面积金色、emoji 图标、暖色渐变促销块 - -**字体：** 小程序继续用 OPPOSANS；不引入 Web 字体。 - ---- - -## 用户确认项（2026-08-31 更新） - -| 项目 | 状态 | 说明 | -|------|------|------| -| **Logo** | 已指定 | 使用用户提供的「雄戈」徽章（深皇家蓝底 + 金色字/麦穗/五星） | -| **首页风格** | **已确认** | 按预览图：Logo+搜索、轮播、分类宫格、双列商品、蓝色 Tab | -| **我的页布局** | **已确认** | 4 列宫格「我的服务」卡片，蓝顶白字 + 订单 5 项 | -| **我的页功能** | **按项目实际** | **只改布局，不改功能清单**；不显示预览图里的「水袋/银行卡」等占位项 | - -### Logo 实施方案 - -1. 源文件：用户提供的徽章 PNG（深蓝 `#0A2463` 量级 + 金色 `#C4A574`/`#D4AF37`） -2. 压缩后上传：`public/uploads/demo/xiongge/xiongge-brand-emblem.png` -3. 首页 [`home-head.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index\home-head.vue) 改为 `$IMG_URL + '/uploads/demo/xiongge/xiongge-brand-emblem.png'` -4. 顶区背景色与 Logo 深蓝对齐：`$brand-header-navy: #0A2463`（或从 Logo 取色） -5. UI 交互色仍用商务蓝 `#1677FF`；金色**仅用于 Logo/品牌标识**，不作为全局 CTA 色 - -### 我的页宫格 — 实际功能清单（不改数据，只改展示） - -[`sh-grid.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-grid.vue) 继续用 `mergedTools` 逻辑： - -**内置默认项（DEFAULT_TOOLS）：** -- 分销中心 → `/pages/app/commission/index` -- 区域代理 → `/pages/app/regional-agent/index` -- 积分商城 → `/pages/app/score/list` -- 浏览足迹 → `/pages/user/view-log` -- 我的收藏 → `/pages/user/favorite` -- 地址管理 → `/pages/user/address/list` -- 常见问题 → `/pages/public/faq` -- 问题反馈 → `/pages/public/feedback` -- 系统设置 → `/pages/user/set` - -**后台 API `grid-list` 追加项**（若装修配置了且未隐藏）： -- 在线客服、我的预约 等（按 `EXTRA_ICON_MAP` 映射图标） -- 开启直播（仅 `userInfo.is_live == 1` 时显示） - -**自动隐藏**（[`hidden-tools.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro\utils\hidden-tools.js)）： -- 我的报修、门店管理、我的拼团、今日必拼 -- 路径含 groupon / merchant / after-sale 的项 - -**布局改造要点：** -- 取消「会员权益 / 我的记录 / …」分组标题 -- `mergedTools` 扁平化为 **4 列 × N 行** 宫格，标题统一「我的服务」 -- 每项仍走 `handleTap(menu)` 原有跳转逻辑 -- 若后台配置了自定义图标 URL，优先显示远程图标；否则用 uView iconfont - ---- - -## 阶段 0：预览图确认 - -| 页面 | 状态 | -|------|------| -| 首页预览 | **已确认** | -| 我的页预览 | 布局确认；宫格内容以实际上方功能清单为准 | - -预览 PNG 路径见 [`PREVIEW-blue-business.md`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\design-system\default\PREVIEW-blue-business.md) - ---- - -## 阶段 1：设计 Token 全局替换（一次改、全站生效） - -**改动文件（核心）：** -- [`static/style/theme.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static/style/theme.scss) -- [`shopro/config/theme.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro/config/theme.js) -- [`shopro/utils/theme.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro/utils/theme.js) — `applyThemeToTabbar` / `applyThemeToUserTemplate` 改为蓝系 -- [`uview-ui/theme.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\uview-ui/theme.scss) — primary 对齐 -- [`pages.json`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages.json) — `selectedColor`、`navigationBarBackgroundColor` -- [`design-system/default/MASTER.md`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\design-system/default/MASTER.md) — 文档同步 - -**TabBar 图标：** 替换 [`static/images/tabbar/*1.png`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static/images/tabbar) 选中态为蓝色（可用 SVG 转 PNG 或重新导出）。 - -**批量替换：** 全局检索硬编码 `#C4A574`、`#E8D4A8`、`$brand-gold-gradient` 的组件（约 20+ 处），改为 `$brand-primary` / `$brand-primary-light`。 - ---- - -## 阶段 2：我的页重构（重点） - -**页面入口：** [`pages/index/user.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/user.vue) - -### 2.1 顶区 — 蓝底白字 - -改 [`userinfo-card.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/user/userinfo-card.vue)： -- 背景改为蓝色渐变，文字/图标改白 -- 昵称下方增加会员标签行（沿用 `userInfo.group`） -- 右侧保留分享按钮（白描边圆钮） - -**新增资产三栏**（参考图顶部「余额/经营额度/积分」）： -- 嵌入 `userinfo-card` 底部或紧接其下的新组件 `user-asset-bar.vue` -- 数据映射：余额 `userInfo.money` / 积分 `userInfo.score` / 优惠券 `userOtherData.coupons_num` -- 点击分别跳转钱包、积分、优惠券页 - -### 2.2 订单卡片 - -改 [`sh-order-card.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/components/sh-order-card.vue)： -- 补「待发货」项（`type: 'nosend'`） -- 5 列等分布局，图标统一蓝色线性风格（uView iconfont + 浅蓝圆底） -- 卡片白底圆角，与参考图「商城订单」一致 - -### 2.3 服务宫格（九宫格 → 4列宫格） - -**重写 [`sh-grid.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/components/sh-grid.vue) 布局：** - -``` -┌─────────────────────────────┐ -│ 我的服务 │ -├──────┬──────┬──────┬──────┤ -│ 图标 │ 图标 │ 图标 │ 图标 │ -│ 文字 │ 文字 │ 文字 │ 文字 │ -├──────┼──────┼──────┼──────┤ -│ ... │ ... │ ... │ ... │ -└──────┴──────┴──────┴──────┘ -``` - -- **4 列 × N 行**（参考图标准，比 3×3 更接近参考） -- 取消分组标题（会员权益/我的记录…），合并为单一「我的服务」卡片 -- 保留 `DEFAULT_TOOLS` + API `grid-list` 合并逻辑与 `hidden-tools` 过滤 -- 每项：48rpx 蓝图标 + 24rpx 标签，触控区 ≥88rpx - -### 2.4 模块顺序建议 - -在 decorate 模板不变的前提下，视觉顺序对齐参考图： - -``` -userinfo-card（蓝顶 + 资产栏） -→ sh-order-card（商城订单） -→ sh-banner（营销轮播，可选） -→ sh-grid（我的服务 4列宫格） -→ 其他 decorate 模块（商品推荐等，可后置） -``` - -`sh-wallet` 可隐藏或合并进顶区资产栏，避免重复。 - -### 2.5 页面背景 - -[`user.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/user.vue) 的 `.user-header-bg` 改为蓝色渐变；内容区卡片间距 `$brand-section-gap`。 - ---- - -## 阶段 3：首页优化 - -**入口：** [`pages/index/index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/index.vue) - -| 模块 | 文件 | 改动 | -|------|------|------| -| 顶区 | [`home-head.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/index/home-head.vue) | 搜索框蓝描边/浅蓝底；轮播指示点改蓝；tagline 改商务文案 | -| 分类宫格 | [`sh-grid-swiper.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/components/sh-grid-swiper.vue) | 图标圆底 `#E6F4FF`，文字 `#1F2937` | -| 商品卡 | [`shopro-goods-card.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components/shopro-goods-card/shopro-goods-card.vue) | 加购按钮改蓝渐变 | -| 营销块 | `sh-seckill` / `sh-coupon` / `sh-title-card` | 金色渐变 → 蓝色系 | -| 分类 Tab | [`sh-category-tabs.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/index/components/sh-category-tabs.vue) | 选中态改蓝 | -| 页面底 | `index.vue` `.home-header-bg` | 与我的页统一蓝灰渐变 | - -首页内容顺序仍由后台 `index/template` 驱动，**只改视觉层，不动 API 结构**。 - ---- - -## 阶段 4：子页面与全局组件扫尾 - -优先扫用户高频页（与参考图体验一致）： -- [`pages/user/wallet/index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/user/wallet/index.vue) — 余额卡改蓝渐变（刚改的金色需回改） -- [`pages/public/search.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages/public/search.vue) -- [`components/shopro-tabbar/shopro-tabbar.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components/shopro-tabbar/shopro-tabbar.vue) -- [`components/shopro-navbar/shopro-navbar.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components/shopro-navbar/shopro-navbar.vue) - ---- - -## 后台配合（可选） - -- Shopro 装修后台：我的页 decorate 模块顺序调整（订单在上、轮播在中、去掉重复 wallet-card） -- 轮播/菜单图标：建议换蓝色系 PNG（CDN `uploads/demo/xiongge/`） -- 执行后清除 Shopro 缓存 - ---- - -## 实施顺序与工作量 - -| 阶段 | 内容 | 预估 | -|------|------|------| -| 0 | 2 张预览 Mockup | 0.5h | -| 1 | Token + TabBar + 全局色替换 | 2h | -| 2 | 我的页（顶区+订单+4列宫格） | 3h | -| 3 | 首页 + 核心 sh-* 组件 | 2h | -| 4 | 子页面扫尾 + 联调 | 2h | - -**总计约 1 个工作日**（含预览确认一轮）。 - ---- - -## 验收标准 - -- 我的页顶区为蓝底白字，资产三栏、订单 5 项、服务 4 列宫格与参考图结构一致 -- TabBar / 主按钮 / 选中态全部为商务蓝，无残留金色 CTA -- 首页搜索头、分类宫格、商品卡风格统一 -- 375px 宽度无布局溢出；图标触控区 ≥44pt -- 后台 decorate 数据无需改 API 即可正常渲染 - ---- - -## 下一步 - -方案已按你的反馈更新。**回复「开始改代码」并切换到 Agent 模式** 后执行： - -1. 上传/压缩新 Logo → CDN，更新 `home-head.vue` -2. 阶段 1→4 代码改造（我的页宫格只改布局，功能沿用 `mergedTools`） -3. HBuilderX 编译 + 清缓存验证 diff --git a/plan/商品分销佣金配置_12a20341.plan.md b/plan/商品分销佣金配置_12a20341.plan.md deleted file mode 100644 index f60fe57..0000000 --- a/plan/商品分销佣金配置_12a20341.plan.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -name: 商品分销佣金配置 -overview: 在 Feitian 飞天结算体系下，为每个商品增加「是否启用分佣 / 团队分销」开关，以及「分销佣金比例 / 团队佣金比例」（按商品实付金额百分比）；后台商品编辑页可配置，结算引擎按订单明细逐商品计算，比例为空时回退现有全局固定金额规则。 -todos: - - id: db-patch - content: 新增 feitian-patch-goods-reward.sql：enable_commission、enable_team、commission_rate、team_commission_rate 四字段 - status: completed - - id: reward-resolver - content: 新增 GoodsRewardResolver.php，统一解析订单明细与商品奖励配置 - status: completed - - id: settle-refactor - content: 改造 ReferralReward / MakerReward / JiudaoguanReward，按商品行与开关/比例结算 - status: completed - - id: admin-ui - content: 商品 edit.html + goods.js 增加飞天分销设置表单（含 is_feitian_order） - status: completed - - id: test-seed - content: 更新测试 seed 与 AcceptanceTest 覆盖比例/开关场景 - status: completed -isProject: false ---- - -# 商品级分销/团队佣金配置（Feitian） - -## 背景与目标 - -当前项目 **线上结算走 Feitian**（[`RewardEngine.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\RewardEngine.php)），商品仅有 [`is_feitian_order`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-patch-goods.sql) 标识，奖励金额全部来自全局配置（推荐 398/400/600、创客基数 120 等）。Shopro 分销已关闭，**不在本次范围**。 - -你已确认： -- 体系：**Feitian** -- 比例含义：**按商品实付金额百分比** - -目标字段（每个商品）： - -| 字段 | 含义 | -|------|------| -| 是否启用分佣 | 控制直推/分销佣金是否发放 | -| 是否启用团队分销 | 控制创客链、酒道馆链团队奖励是否发放 | -| 分销佣金比例 | 实付 × 比例 → 给直推推荐人 | -| 团队佣金比例 | 实付 × 比例 → 作为团队奖励基数，沿用现有链式分配算法 | - -## 数据模型 - -新增 SQL 补丁 [`database/seed/feitian-patch-goods-reward.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-patch-goods-reward.sql)（风格对齐现有 [`feitian-patch-goods.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-patch-goods.sql)）： - -在 `fa_shopro_goods` 增加： - -```sql -enable_commission tinyint(1) NOT NULL DEFAULT 1 COMMENT '是否启用分佣' -enable_team tinyint(1) NOT NULL DEFAULT 1 COMMENT '是否启用团队分销' -commission_rate decimal(5,2) NOT NULL DEFAULT 0 COMMENT '分销佣金比例(%)，0=走全局固定推荐奖' -team_commission_rate decimal(5,2) NOT NULL DEFAULT 0 COMMENT '团队佣金比例(%)，0=走全局固定团队基数' -``` - -**兼容策略（重要）**： -- 老数据默认 `enable_* = 1`、比例为 `0` → **行为与现在完全一致**（仍用 398/400/600 + 120/50 固定金额） -- 仅当 `commission_rate > 0` 时，该商品行改用「实付 × 比例」替代固定推荐奖 -- 仅当 `team_commission_rate > 0` 时，该商品行改用「实付 × 比例」作为 Maker/JDG 的 `base` -- `enable_commission = 0` → 该商品行跳过 [`ReferralReward`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\ReferralReward.php) -- `enable_team = 0` → 该商品行跳过 [`MakerReward`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\MakerReward.php) / [`JiudaoguanReward`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\JiudaoguanReward.php) -- [`AgentReward`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\AgentReward.php)、马豆/云豆/兑换券/分红池：**保持全局逻辑不变**（你未要求按商品控制） - -## 结算逻辑 - -新增 [`addons/feitian/library/GoodsRewardResolver.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\GoodsRewardResolver.php)： - -```mermaid -flowchart LR - orderItems[订单明细] --> loadGoods[读取商品配置] - loadGoods --> lines[逐行 RewardLine] - lines --> referral[ReferralReward] - lines --> maker[MakerReward] - lines --> jdg[JiudaoguanReward] -``` - -核心方法： - -- `getOrderItems($order)`：复用 [`OrderQualify`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\OrderQualify.php) 的明细加载方式 -- `resolveLines($order)`：返回每行 `{ goods_id, pay_amount, enable_commission, enable_team, commission_rate, team_commission_rate, is_feitian_order }` - - `pay_amount` = 行实付（优先 `pay_price`，否则 `goods_price × goods_num`） -- `isRewardableLine($line)`：`is_feitian_order=1` 或整单金额命中 `standard_order_amount`（与现有 qualify 一致） - -**ReferralReward 改造**： -- 遍历可奖励明细行 -- `enable_commission=0` → 跳过 -- `commission_rate > 0` → 发放 `pay_amount × rate / 100` 给直推人（仍写 `feitian_referral_order`，`reward_type` 可沿用 `referral_*` 或新增 `referral_percent`） -- `commission_rate = 0` → 对该行仍走现有「前三单 398/400/600」逻辑（仅第一行触发一次，避免多单重复） - -**MakerReward / JiudaoguanReward 改造**： -- 先按明细行汇总各行的 `teamBase = pay_amount × team_commission_rate / 100`（rate=0 时用全局 base 120/50 作为该行贡献） -- 对 `enable_team=0` 的行贡献为 0 -- 将汇总后的 `base` 传入现有链式分配（创客等级差/平级/越级、酒道馆首/中/末级），**不重写链算法，只替换基数来源** -- 一单多商品、比例不同：按行分别算 base 再求和（避免错误合并） - -**混合购物车**：只有 `is_feitian_order=1` 的行（或标准品酒单金额整单）参与奖励；普通商品行贡献 0。 - -## 后台管理 UI - -在商品编辑页增加「飞天分销设置」分组（同时补上缺失的 `is_feitian_order` 开关）： - -- 视图：[`application/admin/view/shopro/goods/goods/edit.html`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\goods\goods\edit.html)（放在「商品状态」附近） -- 脚本：[`public/assets/js/backend/shopro/goods/goods.js`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\public\assets\js\backend\shopro\goods\goods.js) - - `goodsDetailInit` 增加默认值 - - 校验：比例 0~100，启用开关与 `is_feitian_order` 联动提示 -- 控制器 [`Goods.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\goods\Goods.php) 已 `allowField(true)`，新字段随表单自动保存，无需大改 - -表单示意： - -- 团队分销商品（`is_feitian_order`）开关 -- 启用分佣 / 启用团队分销（switch） -- 分销佣金比例 % / 团队佣金比例 %（`el-input-number`，留空或 0 表示走全局固定规则） - -可选增强（非必须）：商品列表页增加「分佣/团队」状态列，便于批量查看。 - -## 测试与数据 - -- 更新 [`database/seed/feitian-test-data.sql`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\database\seed\feitian-test-data.sql) 演示商品：例如 10% 分销 + 5% 团队 -- 扩展 [`addons/feitian/command/AcceptanceTest.php`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\command\AcceptanceTest.php) 覆盖： - - 比例为 0 → 与旧逻辑金额一致 - - 比例 > 0 → 1398 × 10% = 139.8 等 - - `enable_commission=0` / `enable_team=0` → 对应奖励为 0 - - 退款 [`RefundService`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\library\RefundService.php) 仍按 `order_id` 回滚（现有机制可复用） - -## 小程序端 - -**无需改动**：配置仅在后台维护，结算在后端 [`OrderHook`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\feitian\listener\OrderHook.php) 触发；用户端 [`hlst_wx/pages/app/feitian/reward-log.vue`](f:\修改的项目\恒链数通(重庆)科技有限公司\chufang.gynhc.com\hlst_wx\pages\app\feitian\reward-log.vue) 仍读 `feitian_reward_log`。 - -## 部署步骤 - -1. 执行 `database/seed/feitian-patch-goods-reward.sql` -2. 部署 PHP 代码变更 -3. 后台编辑商品验证保存与结算 -4. 跑 `php think feitian:acceptance_test`（或项目现有验收命令）回归 - -## 风险说明 - -- **一单多飞天商品且比例不同**：采用「逐行计算再汇总」，避免简单平均导致金额错误 -- **推荐奖前三单 vs 百分比**：比例为 0 时保留前三单固定金额；比例 > 0 时按百分比计，不再叠加 398/400/600（需在后台文案中说明） -- **团队比例与代理/分红**：本次仅影响 Maker/JDG 团队链，不影响区县代理等固定奖励 diff --git a/plan/子页面风格统一_7bee3db6.plan.md b/plan/子页面风格统一_7bee3db6.plan.md deleted file mode 100644 index a5edb3d..0000000 --- a/plan/子页面风格统一_7bee3db6.plan.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -name: 子页面风格统一 -overview: 对 xgsc.gynhc.com_wx 小程序全部 76 个注册页面进行 UI 审计与分阶段改造：以首页「轻简奢品」设计体系为基准，通过全局 Token、共享布局组件和分包批量替换，消除红/紫/旧金等遗留配色，并统一子页面布局节奏。 -todos: - - id: phase0-tokens - content: "Phase 0: 扩展 theme.scss + index.scss 全局覆盖 + shopro-page-layout 组件 + shopro-navbar variant" - status: completed - - id: phase1-tabs - content: "Phase 1: 统一 category/cart/user Tab 页配色与布局，修复 CSS typo" - status: completed - - id: phase2-activity - content: "Phase 2A: 改造 pages/activity/* 9 页 — 去除红色促销主题，统一卡片/CTA/价格" - status: completed - - id: phase2-commission - content: "Phase 2B: 改造 pages/app/commission/* 8 页 — 紫色 hero 改品牌渐变" - status: completed - - id: phase2-order - content: "Phase 2C: 改造 pages/order/* 12 页 — 旧金按钮/状态色/三段式布局" - status: completed - - id: phase3-goods-user - content: "Phase 3: 改造 goods/* + user/* + app/* 剩余页面" - status: completed - - id: phase4-public - content: "Phase 4: 改造 public/* 及其他零散页面" - status: completed - - id: verify-qa - content: "全量验证: 微信开发者工具预览 + 遗留色 grep 清零 + 各分包抽查" - status: completed -isProject: false ---- - -# 雄哥小酒小程序 — 全子页面风格统一与布局优化计划 - -## 项目现状 - -- **技术栈：** uni-app + uView UI + Shopro 电商框架（源码为 `.vue`，非直接编辑 `.wxml/.wxss`） -- **页面规模：** [`pages.json`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages.json) 注册 **76 个路由**（6 个子包 + 4 Tab 页） -- **首页基准：** [`pages/index/index.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index.vue) — 暖白渐变头图 + 24rpx 边距 + 12rpx 卡片圆角 + 香槟金 accent -- **设计规范已存在：** [`static/style/theme.scss`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\theme.scss) + [`design-system/default/MASTER.md`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\design-system\default\MASTER.md) -- **UI/UX ProMax 结论：** 奢侈品电商方向（暖白底 + 金色 accent + Cormorant/Montserrat），与现有 MASTER 一致；**反模式：** 高饱和红橙促销块、紫色调分销页 - -```mermaid -flowchart TD - subgraph baseline [首页设计基准] - Home[index.vue] - Tokens[theme.scss] - NavBar[shopro-navbar] - TabBar[shopro-tabbar] - end - subgraph broken [主要不一致区域] - Activity[activity 9页 红色促销] - Commission[commission 8页 紫色分销] - Order[order 12页 旧金按钮] - Default[54页 默认白导航] - end - subgraph fix [统一策略] - Global[全局 Token 层] - Layout[标准子页布局] - Batch[分包批量替换] - end - baseline --> fix - broken --> fix - fix --> AllPages[76页统一视觉] -``` - ---- - -## 首页风格基准（改造目标） - -| 维度 | 规范 | SCSS Token | -|------|------|------------| -| 页面底色 | `#FAFAF8` 暖白 | `$brand-page-bg` | -| 头图渐变 | `#FAFAF8 → #F5EFE4` | `$brand-header-gradient` | -| 主 accent | 香槟金 `#C4A574` | `$brand-gold` / `$brand-gold-gradient` | -| 辅助色 | 清透天蓝 `#5C9FD4`（小面积） | `$brand-primary` | -| 价格 | 柔和酒红 `#C45C5C` | `$brand-price` | -| 正文 | `#2C2C2C` / 副文 `#999` | `$brand-text` / `$brand-text-muted` | -| 卡片 | 白底、12rpx 圆角、轻阴影 | `$brand-card-radius` / `$brand-shadow` | -| 水平边距 | 24rpx | 统一 gutter | -| 区块间距 | 16/24/32rpx 三级 | 8dp 节奏 | - -**字体策略（UI/UX ProMax + 小程序约束）：** MASTER 指定 Cormorant/Montserrat，但小程序不宜依赖 Google Fonts CDN。建议 **保留 OPPOSANS 作为正文字体**（已在 [`static/style/index.scss`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\index.scss) 全局加载），标题/价格可选用已有 `wenyue` 装饰字体；更新 MASTER 注明「小程序实现 = OPPOSANS」。 - ---- - -## 核心问题清单 - -### 1. 全局层不一致（影响所有子页） - -- uView 工具类 `.page_box` 背景为 `#f3f4f6`，与 `$brand-page-bg #FAFAF8` 冲突 -- 仅约 **30/115** 个 page 级 `.vue` 使用了 `$brand-*` Token -- 约 **20+** 文件仍含 `#ff0000`、`#d01325`、`#a36fff` 等遗留色 - -### 2. 分包视觉断裂（优先级最高） - -| 分包 | 页面数 | 主要问题 | -|------|--------|----------| -| `pages/activity/*` | 9 | 红色促销头图、橙红 CTA、`#FF0000` Tab | -| `pages/app/commission/*` | 8 | 紫色渐变 hero `#a36fff→#5336ff`，与品牌完全脱节 | -| `pages/order/*` | 12 | 旧金按钮 `#e9b461→#eecc89`、红色状态 `#e50808` | -| `pages/index/category*` | 4 布局 | 侧栏 `#F6F6F6`、选中态用蓝色 primary 而非金色 | -| `pages/index/cart` | 1 | 头部 `#f7f5f6`、删除按钮橙红渐变 | - -### 3. 导航栏不统一 - -- **22 页** custom nav（`shopro-navbar` 或自写） -- **54 页** 系统默认白导航 -- 子页缺少首页的渐变头图感，层级感弱 - -### 4. 布局格式问题 - -- 混用 `page_box/content_box/head_box/foot_box` 与自由布局，边距 20/24/30rpx 不统一 -- 固定底栏页（购物车、确认订单、商品详情）底部安全区 padding 不一致 -- 个别 CSS 错误：`userinfo-card.vue` 的 `powidth: 100%`；`two-catgory.vue` 的 `#ffff` 无效色值 - -### 5. 特殊页面 - -- `pages/live/list2.nvue`、`pages/user/live.nvue` — nvue 样式体系独立，需单独处理或保持功能优先 -- `pages/index/user-copy.vue`、`pages/user/live-copy.nvue` — 未注册孤儿文件，建议删除或忽略 - ---- - -## 实施方案 - -### Phase 0 — 基础设施（一次改动，全局生效） - -**目标：** 让所有子页自动继承首页 Token，减少逐页硬编码。 - -1. **扩展 [`static/style/theme.scss`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\theme.scss)** - - 新增语义化 mixin/类：`.brand-page`、`.brand-card`、`.brand-btn-primary`、`.brand-btn-gold`、`.brand-price-text`、`.brand-section-gap` - - 新增布局 Token：`$brand-page-gutter: 24rpx`、`$brand-section-gap: 24rpx` - -2. **修正全局样式 [`static/style/index.scss`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\index.scss)** - - 覆盖 uView `.page_box { background: $brand-page-bg !important; }` - - 统一 `.head_box` / `.foot_box` 间距与安全区 `padding-bottom: env(safe-area-inset-bottom)` - -3. **增强 [`components/shopro-navbar/shopro-navbar.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-navbar\shopro-navbar.vue)** - - 新增 `variant` prop：`white`（默认）| `gradient`（子页用首页渐变） - - 统一返回图标色 `$brand-text`、标题字重 - -4. **新建子页布局组件 `components/shopro-page-layout/shopro-page-layout.vue`** - - 标准结构：`navbar(optional)` → `scroll-content(24rpx gutter)` → `fixed-footer(optional)` - - 供 order/user/public 等列表/表单页复用，消除各页自写 flex 结构差异 - -5. **同步 JS Token [`shopro/config/theme.js`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro\config\theme.js)** — inline style 场景统一引用 - -6. **更新 MASTER.md** — 补充「小程序字体 = OPPOSANS」及子页布局规范 - ---- - -### Phase 1 — Tab 页对齐首页（4 页 + 组件） - -| 文件 | 改造要点 | -|------|----------| -| [`pages/index/category/*.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\category) | 侧栏改 `$brand-gold-light`；选中态改 `$brand-gold`；修复 `#ffff` typo | -| [`pages/index/cart.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\cart.vue) | 头部/列表区 Token 化；删除按钮改 `$brand-price` 或 `$brand-gold-gradient`；底部结算栏对齐首页 CTA | -| [`pages/index/user.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\user.vue) + [`userinfo-card.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\user\userinfo-card.vue) | 去除 `#c9912c` 旧金；修复 `powidth` typo；版权色改 `$brand-text-muted` | - ---- - -### Phase 2 — 高视觉断裂分包（29 页） - -#### 2A. 活动页 `pages/activity/*`（9 页） - -- 替换 CDN 红色头图为 **渐变 + 品牌标题** 或保留图片但叠加 `$brand-header-gradient` 遮罩 -- CTA：`linear-gradient(90deg, #d01325, #ed3c30)` → `$brand-gold-gradient` -- 价格：`#ff0000` → `$brand-price` -- 进度条：`#ffbbbb` → `$brand-gold-light` + `$brand-gold` 填充 -- [`discounts/list.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\activity\discounts\list.vue) Tab 背景 `#FF0000` → `$brand-gold` -- 统一卡片：白底 + `$brand-card-radius` + `$brand-shadow` - -#### 2B. 分销页 `pages/app/commission/*`（8 页） - -- Hero 紫色渐变 → `$brand-header-gradient` + 金色数据高亮 -- Tab/按钮 inactive `#7430EE` → `$brand-text-muted`；active → `$brand-gold` -- 保留数据可视化结构，只换色板和间距 - -#### 2C. 订单流 `pages/order/*`（12 页） - -- 列表 Tab 指示器、操作按钮统一 `$brand-gold-gradient` -- 状态色：取消/失败用 `$brand-price`；进行中用 `$brand-primary` -- 确认订单 [`confirm.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\order\confirm.vue) 复选框 `#f0c785` → `$brand-gold` -- 引入 `shopro-page-layout` 统一 head/content/foot 三段式 - ---- - -### Phase 3 — 商品与用户分包（18 页） - -| 分组 | 文件 | 要点 | -|------|------|------| -| 商品 | `goods/list.vue`, `goods/detail.vue`, `comment/*` | detail 浮层导航保持；清理 `#fa3534`/`#f00`；list 加 24rpx gutter | -| 用户 | `user/wallet/*`, `user/address/*`, `user/info.vue` 等 | custom nav 页改 `variant="gradient"`；列表 cell 统一白卡片间距 | -| App | `app/coupon/*`, `app/store/*`, `app/score/*`, `app/merchant/*`, `app/video/*` | 已有 partial Token 的保留；其余按标准布局组件包裹 | - ---- - -### Phase 4 — 公共与其他页（15 页） - -- [`pages/public/search.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\public\search.vue) — 搜索框背景改 `$brand-gold-light` -- [`pages/public/chat/index.vue`](F:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\public\chat\index.vue) — navbar gradient -- `faq/feedback/richtext/404` — 最小改动：page bg + 内容区 24rpx padding -- `pages/index/view.vue`, `protocol.vue`, `live/list.vue` — 跟随全局 Token - ---- - -## 子页布局优化标准（UI/UX ProMax 约束） - -所有子页统一遵循： - -``` -┌─────────────────────────┐ -│ shopro-navbar (gradient/white) │ ← 可选，非 Tab 页 -├─────────────────────────┤ -│ scroll-content │ -│ padding: 0 24rpx │ ← $brand-page-gutter -│ ┌─────────────────┐ │ -│ │ brand-card │ │ ← 12rpx radius, shadow -│ │ section gap 24rpx│ │ -│ └─────────────────┘ │ -├─────────────────────────┤ -│ fixed-footer (if any) │ ← safe-area-inset-bottom -└─────────────────────────┘ -``` - -- **触控间距：** 相邻可点击元素 ≥ 16rpx（8dp） -- **列表页：** 卡片间距 24rpx，避免 `#f5f5f5`/`#f6f6f6`/`#f7f5f6` 混用 -- **空状态：** 统一 `shopro-empty` 组件 -- **加载态：** 统一 `shopro-loading` / `page-loading` - ---- - -## 改造范围与工作量估算 - -| 阶段 | 页面/文件数 | 预估改动 | -|------|-------------|----------| -| Phase 0 基础设施 | ~8 文件 | 全局 Token + 2 组件 | -| Phase 1 Tab 页 | 7 文件 | 配色 + 布局 | -| Phase 2 活动/分销/订单 | 29 页 | 配色大改 + 布局 | -| Phase 3 商品/用户/App | 18 页 | 中等 | -| Phase 4 公共/其他 | 15 页 | 轻量 | -| nvue 特殊页 | 2 页 | 单独评估 | - -**建议执行顺序：** Phase 0 → 1 → 2A → 2B → 2C → 3 → 4 - ---- - -## 验证清单 - -- 在微信开发者工具预览 **375px 宽度**（iPhone SE 基准） -- 抽查每分包至少 1 页：活动、订单、分销、商品详情、钱包 -- 对比首页截图：底色、金色 accent、卡片圆角、价格色一致 -- Tab 页切换无闪烁；固定底栏不遮挡内容 -- 搜索遗留色：`rg "#(ff0000|d01325|a36fff|e9b461|f0c785)" pages/` 应为 0 - ---- - -## 风险与说明 - -- **不改业务逻辑：** 仅改样式/布局结构，不动 API 与交互流程 -- **nvue 页面限制：** `list2.nvue`、`live.nvue` 不支持 SCSS mixin，需用内联或独立 wxss 变量 -- **编译产物：** 修改源码 `.vue` 后需 `npm run dev:mp-weixin` 或 `build:mp-weixin` 重新编译 -- **Typography 大改风险高：** 不建议本次全量换 Cormorant/Montserrat，避免包体积和加载问题 diff --git a/plan/字体背景风格优化_63a32b86.plan.md b/plan/字体背景风格优化_63a32b86.plan.md deleted file mode 100644 index 8bad44e..0000000 --- a/plan/字体背景风格优化_63a32b86.plan.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -name: 字体背景风格优化 -overview: 在 gsyuniapp 前端建立统一的字体层级与色彩规范（参考淘宝清爽风格），放大图1-3圈出区域字号，背景统一为白/浅灰，并用红色突出价格、优惠、加入购物车等关键操作，提升中老年用户可读性与操作引导。 -todos: - - id: theme-vars - content: 在 uni.scss / index.scss 新增字号阶梯、促销红色、统一背景变量及工具类 - status: pending - - id: home-page - content: 优化首页：sh-grid-swiper 分类字、shopro-tabbar 字号、商品卡价格红色、背景去绿调 - status: pending - - id: cart-page - content: 购物车页：checkbox/价格/结算按钮改红，字号放大，背景统一 - status: pending - - id: detail-page - content: 商品详情：原价/副标题标签放大改红，底部按钮改红，背景统一 - status: pending - - id: color-cleanup - content: 批量替换硬编码色值为 SCSS 变量，统一 sh-activity 等优惠标签红色 - status: pending - - id: verify - content: 微信/H5 预览验证图1-3圈出区域效果 - status: pending -isProject: false ---- - -# 字体与背景统一优化方案（淘宝风格） - -## 现状分析 - -项目为 `gsyuniapp/`（uni-app + uView + shopro），已有全局字体 **OPPOSANS**，但存在三类问题： - -| 问题 | 表现 | -|------|------| -| 字号偏小 | 底部导航 `20rpx`、金刚区分类 `24rpx`、详情副标题 `25rpx`、原价 `24rpx` | -| 色彩单一 | 购物车 checkbox/价格/结算、详情标签/按钮大量用绿色 `#5EAD82`，与价格红 `#E53935` 混用，缺乏层次 | -| 背景不统一 | 首页带绿调渐变、详情 `#F7F8FA`、购物车 `#f5f7f6`、卡片 `#f7f8fa` 等多套灰绿背景 | - -```mermaid -flowchart LR - subgraph before [当前问题] - A[全局绿主题] --> B[价格/按钮/勾选全绿] - C[字号不统一] --> D[小字难辨认] - end - subgraph after [优化后] - E[品牌绿: 导航/Tab] --> F[红色: 价格/优惠/CTA] - G[统一字号阶梯] --> H[清爽白底卡片] - end -``` - -## 设计原则（对齐图4淘宝风格） - -- **字体**：全站统一 OPPOSANS + 系统回退（PingFang SC），建立字号阶梯，数字加 `font-variant-numeric: tabular-nums` 保证对齐 -- **背景**：页面底 `#F5F5F5`，卡片 `#FFFFFF`，去掉绿调渐变 -- **色彩分工**： - - **品牌绿 `#5EAD82`**：保留在 Tab 选中态、顶部导航、品牌装饰 - - **促销红 `#FF4D4F`**（接近淘宝 `#FF5000`）：价格、优惠价标签、checkbox 选中、加入购物车、结算、优惠/服务标签 - -## 第一步：全局主题变量（改一处影响全站） - -**文件：[`gsyuniapp/uni.scss`](gsyuniapp/uni.scss)** - -新增变量： - -```scss -// 促销/行动色（淘宝风格红） -$gsy-price: #FF4D4F; -$gsy-price-light: #FFF1F0; -$gsy-cta: #FF4D4F; -$gsy-cta-dark: #E63E40; - -// 统一背景 -$gsy-bg: #F5F5F5; // 去掉绿调 -$gsy-card: #FFFFFF; - -// 字号阶梯 -$font-size-xs: 22rpx; -$font-size-sm: 26rpx; -$font-size-base: 30rpx; -$font-size-md: 32rpx; -$font-size-lg: 36rpx; -$font-size-xl: 40rpx; -``` - -同步更新 `$u-type-error` 为 `$gsy-price`，便于 uView checkbox 等组件复用。 - -**文件：[`gsyuniapp/static/style/index.scss`](gsyuniapp/static/style/index.scss)** - -- `page` 基础字号 `30rpx` → `32rpx` -- 增加工具类：`.gsy-price`、`.gsy-text-promo`、`.gsy-font-tabular` -- 全局数字/价格使用 tabular-nums - -## 第二步：图1 首页圈出区域 - -### 金刚区分类文字（名酒鉴赏等） - -**文件：[`gsyuniapp/pages/index/components/sh-grid-swiper.vue`](gsyuniapp/pages/index/components/sh-grid-swiper.vue)** - -| 属性 | 当前 | 调整后 | -|------|------|--------| -| `.tab-title` 字号 | `24rpx` | `28rpx` | -| 字重 | `400` | `500` | -| 颜色 | `#6B7B6C` | `#333333` | - -### 底部导航文字 - -**文件：[`gsyuniapp/components/shopro-tabbar/shopro-tabbar.vue`](gsyuniapp/components/shopro-tabbar/shopro-tabbar.vue)** - -| 属性 | 当前 | 调整后 | -|------|------|--------| -| `.tabbar-text` 字号 | `20rpx` | `24rpx` | -| 字重 | `500` | `500`（保持） | -| 选中色 | 绿 `#5EAD82` | 保持绿色（品牌识别） | - -同步更新 [`gsyuniapp/pages.json`](gsyuniapp/pages.json) 中 tabBar `fontSize`（如有配置）。 - -### 首页商品卡价格 - -**文件：** -- [`gsyuniapp/components/shopro-goods-card/shopro-goods-card.vue`](gsyuniapp/components/shopro-goods-card/shopro-goods-card.vue) -- [`gsyuniapp/pages/index/components/sh-goods-card.vue`](gsyuniapp/pages/index/components/sh-goods-card.vue) - -- 现价颜色 `#1A1A1A` / 绿 → `$gsy-price` 红色 -- 现价字号 `36rpx` → `38rpx` -- 副标题/标签字号 `20-22rpx` → `24rpx` -- 购物车图标按钮可加红色描边或红色图标，增强行动引导 - -### 首页背景 - -**文件：[`gsyuniapp/pages/index/index.vue`](gsyuniapp/pages/index/index.vue)** - -- 顶部渐变 `#F0F4F2 → #F5F7F5` 改为中性 `#F5F5F5 → #FFFFFF` - -## 第三步：图2 购物车圈出区域 - -**文件：[`gsyuniapp/pages/index/cart.vue`](gsyuniapp/pages/index/cart.vue)** - -| 元素 | 当前 | 调整后 | -|------|------|--------| -| checkbox `activeColor` | `#5EAD82` | `$gsy-price` 红 | -| 商品单价/合计 | 绿色 | 红色，字号 `36rpx` → `40rpx` | -| 结算按钮 | 绿渐变 | 红渐变 `#FF4D4F → #E63E40` | -| 页面背景 | `#f5f7f6` | `$gsy-bg #F5F5F5` | -| 列表标题区字号 | `24rpx` | `28rpx` | - -## 第四步：图3 商品详情圈出区域 - -### 原价行 - -**文件：[`gsyuniapp/pages/goods/components/sh-price-card.vue`](gsyuniapp/pages/goods/components/sh-price-card.vue)** - -| 属性 | 当前 | 调整后 | -|------|------|--------| -| `.original-price` 字号 | `24rpx` | `28rpx` | -| 颜色 | `#999999` | `#999999`（保持灰色删除线，仅放大） | -| 主价格色 | `#E53935` | 统一为 `$gsy-price #FF4D4F` | -| `.notice-tag`「优惠价」 | 红底浅粉 | 保持红色强调，字号 `22rpx` → `24rpx` | - -### 副标题标签（观物 纯粮固态发酵） - -**文件：[`gsyuniapp/pages/goods/detail.vue`](gsyuniapp/pages/goods/detail.vue)** `.goods-sub-title` - -| 属性 | 当前 | 调整后 | -|------|------|--------| -| 字号 | `25rpx` | `28rpx` | -| 颜色/背景 | 绿字 `#387656` / 绿底 `#F0F7F3` | 红字 `$gsy-price` / 红浅底 `$gsy-price-light` | - -### 底部操作按钮 - -**文件：[`gsyuniapp/pages/goods/detail.vue`](gsyuniapp/pages/goods/detail.vue)** `.secondary-action-btn` / `.primary-action-btn` - -| 按钮 | 当前 | 调整后 | -|------|------|--------| -| 加入购物车 | 浅绿底 + 绿字 | 白底 + 红边红字，或浅红底红字 | -| 立即购买 | 绿渐变 | 红渐变 `#FF4D4F → #E63E40` | -| 字号 | `28rpx` | `30rpx` | - -### 优惠/服务标签 - -**文件：[`gsyuniapp/pages/goods/components/sh-activity.vue`](gsyuniapp/pages/goods/components/sh-activity.vue)** - -- 已用 ColorUI `.bg-red` / `.line-red`，将 [`colorui-mini.css`](gsyuniapp/static/style/colorui-mini.css) 中红色统一为 `$gsy-price`，标签字号加大至 `26rpx` - -### 详情页背景 - -- `detail.vue` 中 `#F7F8FA` → `$gsy-bg #F5F5F5`，卡片保持白底 - -## 第五步：硬编码色值批量替换 - -用 `$gsy-price` / `$gsy-primary` 变量替换以下文件中散落的 `#5EAD82`（仅限价格/CTA 场景）、`#E53935`、`#e04a4a` 等： - -- `cart.vue` -- `detail.vue` -- `sh-price-card.vue` -- `shopro-goods-card.vue` -- `sh-goods-card.vue` -- `shopro-tabbar.vue`（仅保留导航绿，不动角标红） - -可用命令辅助排查：`rg "#5[Ee][Aa][Dd]82|#E53935" gsyuniapp/` - -## 不涉及的范围 - -- 后台装修数据（`fa_shopro_decorate_content` 中标题色 `#2C3E2D`）——前端组件已有 fallback，无需改库 -- 不新增「7天无理由」文案（用户已说明不支持） -- 不更换字体文件（OPPOSANS 已满足「一种字体、大小不同」的需求） - -## 验证清单 - -1. 首页：金刚区 5 个分类名、底部 Tab 文字明显变大变清晰 -2. 首页商品列表：价格显示红色，背景统一白/浅灰 -3. 购物车：勾选框选中红色，价格/合计红色，结算按钮红色 -4. 商品详情：原价行更大，副标题标签红色醒目，「加入购物车」「立即购买」红色系 -5. 全站数字（价格、数量）视觉风格一致，无绿/红/黑混用突兀感 -6. 微信小程序 + H5 编译预览，确认字号在各端正常渲染 diff --git a/plan/实施进度汇总.md b/plan/实施进度汇总.md deleted file mode 100644 index a746053..0000000 --- a/plan/实施进度汇总.md +++ /dev/null @@ -1,158 +0,0 @@ -# 厨房商城项目实施进度汇总 - -更新时间：2026-09-12 - ---- - -## 一、区域代理（已完成 ✅） - -详见 [对话摘要-区域代理实施.md](./chat-backup/对话摘要-区域代理实施.md) - -P0/P1/P2 全部完成：等级 CRUD、分佣模式、看板、筛选导出、单代理自定义佣金、测试脚本等。 - ---- - -## 二、汇付支付 + 延时分账（已完成 ✅） - -| 任务 | 状态 | 关键文件 | -|------|------|----------| -| shopro_huifu 插件化 | ✅ | `addons/shopro_huifu/` | -| 微信小程序支付 | ✅ | `library/HuifuPay.php`、PayCreateHook | -| 延时分账（支付后/确认收货可选） | ✅ | `ProfitSharingService.php`、后台配置 | -| 分账接收方管理 | ✅ | 后台 split/receiver | -| 安装/验证命令 | ✅ | `shopro_huifu:install`、`verify`、`split-retry` | -| 后台配置页 | ✅ | `/admin/shopro_huifu/config` | - -**部署**： -```bash -php think shopro_huifu:install -php think shopro_huifu:verify -``` - ---- - -## 三、汇付个人进件（基本完成 ✅，待运营验证） - -| 任务 | 状态 | 关键文件 | -|------|------|----------| -| 进件数据表 + API | ✅ | `upgrade_huifu_onboard.sql` | -| 分销申请强制进件 | ✅ | `commission/Agent.php` + Hook | -| 区域代理申请强制进件 | ✅ | `regional_agent/RegionalAgent.php` | -| 小程序进件表单 | ✅ | `pages/app/commission/apply` | -| 提现页进件绑定（子页） | ✅ | `pages/user/wallet/withdraw/bind` | -| 后台进件审核 | ✅ | `/admin/shopro_huifu/onboard` | -| 轮询进件状态 | ✅ | `shopro_huifu:onboard-poll` | - -**部署**： -```bash -php think shopro_huifu:install-full -php think shopro_huifu:onboard-poll -``` - -**待验证**： -- [ ] 汇付沙箱/生产进件全流程 -- [ ] 进件通过后分账 receiver 自动同步 - ---- - -## 四、微信发货信息同步（已开发 ✅，待微信侧授权） - -| 任务 | 状态 | 关键文件 | -|------|------|----------| -| shopro_wechat_trade 插件 | ✅ | `addons/shopro_wechat_trade/` | -| 发货信息上报 | ✅ | `WxShippingService.php` | -| 后台配置 | ✅ | `/admin/shopro_wechat_trade/config` | -| 安装/验证命令 | ✅ | `shopro_wechat_trade:install`、`verify` | - -**前置条件**： -- [ ] 小程序后台签署「订单中心」授权协议 -- [ ] 经营类目在开放范围内（或已申请接入） -- [ ] 配置订单详情 path：`pages/order/detail` - ---- - -## 五、阿里云快递查询（已完成 ✅） - -| 任务 | 状态 | 关键文件 | -|------|------|----------| -| shopro_aliyun_express 插件 | ✅ | `addons/shopro_aliyun_express/` | -| Provider 切换 | ✅ | 后台物流配置 | -| 轨迹查询/刷新 | ✅ | `AliyunExpressProvider.php` | - -**部署**： -```bash -php think shopro_aliyun_express:install-full -``` - ---- - -## 六、小程序 UI / 体验 - -| 任务 | 状态 | 说明 | -|------|------|------| -| 首页 E-Final 布局 | ✅ | 分类网格、配色统一 | -| 敏感文案替换（代理→公司、佣金→差价） | ✅ | 小程序 + 后台 | -| 首页图片压缩/清理 | ✅ | 减小包体积 | -| 提现页 + 进件绑定子页 | ✅ | 角色可见控制 | - -**待办**： -- [ ] 小程序重新编译发布（`xgsc.gynhc.com_wx`） -- [ ] 真机全链路验收 - ---- - -## 七、分销功能（参考计划，部分待续） - -详见： -- [shopro分销重构方案](./shopro分销重构方案_7c67d97d.plan.md) -- [级差奖管理奖改造](./级差奖管理奖改造_7a3ea896.plan.md) -- [分销需求差异核对](./分销需求差异核对_53c87321.plan.md) - -```bash -php addons/shopro/tests/commission_setup_test_users.php -php addons/shopro/tests/commission_verify.php scenarios -``` - ---- - -## 八、部署 Checklist（汇总） - -### 数据库（按顺序） - -1. `upgrade_distribution_features.sql` -2. `upgrade_regional_agent_menu.sql` -3. `upgrade_regional_agent_commission.sql` -4. `upgrade_huifu_pay_type.sql` + `upgrade_huifu_split.sql` -5. 汇付进件表（`shopro_huifu:install-full` 自动执行） - -### 插件安装 - -```bash -php think shopro_huifu:install -php think shopro_huifu:install-full -php think shopro_wechat_trade:install -php think shopro_aliyun_express:install-full -``` - -### 验证 - -```bash -php think shopro_huifu:verify -php think shopro_wechat_trade:verify -php addons/shopro/tests/regional_agent_verify.php list-agents -``` - -### 后台 - -- 汇付：配置 huifu_id、密钥、分账时机 -- 微信交易：配置 AppID、订单 path -- 物流：选择阿里云全国快递 + AppCode -- 区域代理：分配权限、确认等级比例 - ---- - -## 九、文档索引 - -- [README.md](./README.md) — 全部计划文档索引 -- [对话摘要-2026-09-12打包.md](./chat-backup/对话摘要-2026-09-12打包.md) — 近期会话汇总 -- [对话摘要-区域代理实施.md](./chat-backup/对话摘要-区域代理实施.md) — 区域代理专项 diff --git a/plan/微信发货信息同步_b8fd57f1.plan.md b/plan/微信发货信息同步_b8fd57f1.plan.md deleted file mode 100644 index f54db47..0000000 --- a/plan/微信发货信息同步_b8fd57f1.plan.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -name: 微信发货信息同步 -overview: 新建独立插件 `addons/shopro_wechat_trade`，在 Shopro 的 `order_send_after` / `order_confirm_after` 钩子上对接微信小程序订单发货管理与购物订单能力；同时修正汇付支付通知中微信 `transaction_id` 的落库，以支持聚合支付场景下的发货同步与历史补传。 -todos: - - id: ops-prereq - content: 小程序后台签署订单中心协议并开通发货信息管理服务 - status: completed - - id: huifu-wx-txn - content: shopro_huifu：HuifuNotifyHandler 解析并落库 wx_transaction_id / sub_mch_id / sub_openid - status: completed - - id: plugin-scaffold - content: 创建 addons/shopro_wechat_trade 插件骨架（install/hooks/appInit/SQL） - status: completed - - id: wx-api-client - content: 实现 WxTradeClient + WxOrderPathService + WxShippingService - status: completed - - id: mp-detail-route - content: 小程序 detail 页与 API 支持 order_sn 参数；配置 update_order_detail_path - status: completed - - id: shipping-hook - content: ShippingHook 挂 order_send_after + Queue 异步 upload_shipping_info - status: completed - - id: confirm-hook - content: ConfirmHook 挂 order_confirm_after 调用 notify_confirm_receive - status: completed - - id: backfill-retry - content: CLI 历史补传与失败重试 + 后台同步日志页 - status: completed - - id: e2e-test - content: 直连/汇付/分拆发货/确认收货全链路联调 - status: completed -isProject: false ---- - -# Shopro 微信发货信息同步接入方案 - -## 背景与目标 - -微信对实物交易类小程序要求接入 [小程序购物订单](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/business-capabilities/order_center/order_center.html) 与 [发货信息管理服务](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/business-capabilities/order_center/order_center.html)（含 `upload_shipping_info`、订单详情路径配置等）。当前项目： - -- [`order_send_after`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\hooks.php) 已有，由 [`Send::orderSendAfter`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\order\Send.php) 处理站内通知/自动确认队列 -- 商城内部发货逻辑在 [`OrderOperSendGet::sendItem`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\traits\model\order\OrderOperSendGet.php) 触发钩子 -- **无任何** `upload_shipping_info` / `update_order_detail_path` 实现 -- 汇付通道下 [`HuifuNotifyHandler`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\HuifuNotifyHandler.php) 将 `hf_seq_id` 写入 `order.transaction_id`，**不是**微信侧 `420000...` 流水，后续无法正确调用微信发货 API - -```mermaid -sequenceDiagram - participant Admin as 后台发货 - participant Shopro as Shopro_sendItem - participant Hook as order_send_after - participant Plugin as shopro_wechat_trade - participant WX as 微信API - - Admin->>Shopro: expressSendItem / autoSendItem - Shopro->>Hook: order + item - Hook->>Plugin: WxShippingHook - Plugin->>Plugin: 校验平台/支付方式/幂等 - Plugin->>WX: upload_shipping_info - WX-->>Plugin: errcode=0 - Plugin->>Plugin: 记录同步状态 -``` - ---- - -## 模块归属（已确认） - -新建 **`addons/shopro_wechat_trade`** 独立插件，在 `appInit` 动态注册 Hook（与 [`shopro_huifu`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\Shopro_huifu.php) 同模式）。Shopro 核心 **仅增加 0 行**（钩子点已存在）。 - -汇付侧 **小改** [`shopro_huifu`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu)：支付通知时额外提取并保存微信 `transaction_id` / `sub_mch_id`（供发货插件读取）。 - ---- - -## 一、微信侧前置（运营手动，开发前先完成） - -在小程序后台（`wx5c95f038d5974a40`）完成： - -1. **签署订单中心授权协议**（否则 `update_order_detail_path` 返回 `10060034`） -2. **开通发货信息管理服务**（支付与交易 → 订单管理 / 购物订单） -3. 确认实物交易类运营规范已满足（对应你通知中心 8/20 的两条接入通知） - -插件安装时自动调用一次 `update_order_detail_path`；失败则后台给出明确提示，不阻塞商城发货本身。 - ---- - -## 二、插件目录结构 - -``` -addons/shopro_wechat_trade/ -├── Shopro_wechat_trade.php # install/enable/disable/appInit -├── info.ini -├── hooks.php # order_send_after, order_confirm_after -├── install.sql -├── config/menu.php # 同步日志 + 配置页（可选） -├── library/ -│ ├── Bridge.php # isEnabled / shouldHandleOrder -│ ├── WxTradeClient.php # access_token + HTTP 封装 -│ ├── WxOrderPathService.php # update/get_order_detail_path -│ ├── WxShippingService.php # upload_shipping_info / notify_confirm_receive -│ ├── WxExpressMapper.php # shopro express_code → 微信运力编码 -│ └── WxShippingPayload.php # 订单→微信 DTO 转换 -├── listener/ -│ ├── ShippingHook.php # order_send_after -│ └── ConfirmHook.php # order_confirm_after -└── command/ - ├── InitOrderPath.php # 初始化订单详情路径 - └── BackfillShipping.php # 历史已发货订单补传 -``` - ---- - -## 三、数据库设计 - -新建表 `shopro_wechat_trade_sync`（插件私有）： - -| 字段 | 说明 | -|------|------| -| `order_id` / `order_sn` | 订单标识 | -| `order_item_id` | 子单发货时为 item id；整单发货为 0 | -| `sync_type` | `shipping` / `confirm` | -| `status` | `pending` / `success` / `failed` | -| `delivery_mode` | 1=统一发货 2=分拆发货 | -| `request_payload` / `response_payload` | 脱敏日志 | -| `errcode` / `errmsg` | 微信返回 | -| `retry_count` / `next_retry_time` | 重试调度 | - -**汇付扩展表补字段**（[`shopro_huifu_pay_ext.extra`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\install.sql) JSON 或独立列）： - -- `wx_transaction_id`：微信 `420000...`（优先 `wx_response.transaction_id`，备选 `out_trans_id`） -- `wx_sub_mch_id`：微信子商户号（`wx_response.sub_mch_id`） -- `wx_sub_openid`：支付用户 openid - -> 直连微信订单：`shopro_order.transaction_id` 已是微信流水，可直接使用。 - ---- - -## 四、关键改造点 - -### 4.1 汇付支付通知：保存微信流水（shopro_huifu 小改） - -文件：[`HuifuNotifyHandler.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\HuifuNotifyHandler.php) - -支付成功时从 `resp_data` 解析： - -```php -// 伪代码 -$wxResp = json_decode($data['wx_response'] ?? '{}', true); -$wxTransactionId = $wxResp['transaction_id'] ?? ($data['out_trans_id'] ?? ''); -$wxSubMchId = $wxResp['sub_mch_id'] ?? ''; -``` - -- `order.transaction_id` **改为存** `$wxTransactionId`（微信发货/购物订单依赖此值） -- `hf_seq_id` 仍存 `shopro_huifu_pay_ext.hf_seq_id`（汇付查单/退款不变） -- `extra` 字段保存完整 wx 标识供插件读取 - -> 若生产 notify 中字段名与文档不一致，先用一条真实成功 notify 样本对齐字段路径后再固化解析器（避免猜字段）。 - -### 4.2 订单详情路径（小程序端 + 服务端） - -微信要求 path 含 `${商品订单号}`，且该值为支付时的 `out_trade_no`（Shopro = [`order_sn`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\install.sql)）。 - -当前小程序 [`pages/order/detail.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\order\detail.vue) 仅支持 `?id=`（订单主键），**需扩展**： - -- 服务端配置 path：`pages/order/detail?order_sn=${商品订单号}` -- 小程序 `onLoad` / `$Route.query` 增加 `order_sn` 分支：有 `order_sn` 时按订单号拉详情（需 Shopro API 支持 `order_sn` 查询，或在现有 detail 接口增加参数） - -### 4.3 `order_send_after` 监听逻辑 - -文件：新建 [`ShippingHook.php`](addons/shopro_wechat_trade/listener/ShippingHook.php) - -**触发条件（全部满足才同步）**： - -| 条件 | 来源 | -|------|------| -| `order.platform === 'wxMiniProgram'` | [`shopro_order.platform`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\install.sql) | -| `pay_type in ('wechat','huifu_wechat')` | 排除 wallet/score/未支付 | -| 存在有效微信流水 | `transaction_id` 或 pay_ext.wx_transaction_id | -| 插件已启用 | `Bridge::isEnabled()` | - -**配送方式映射**（`item.dispatch_type` → 微信 `logistics_type`）： - -| Shopro | 微信 logistics_type | -|--------|---------------------| -| `express` | 1 快递 | -| `store` | 2 同城 | -| `autosend` | 3 虚拟/自动发货 | -| `selfetch` | 4 用户自提 | - -**发货模式**： - -- 订单仅 1 个待发货 item 或一次性全部发完 → `delivery_mode=1` -- 多 item 分批发货 → `delivery_mode=2`，`shipping_list` 按已发货 item 聚合；每次 `order_send_after` 重算已发列表并调用 `upload_shipping_info`（微信允许更新） - -**快递字段映射**： - -- `tracking_no` ← `item.express_no` -- `express_company` ← [`WxExpressMapper`](addons/shopro_wechat_trade/library/WxExpressMapper.php) 将 [`shopro_express.code`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\install.sql)（如 SF/YTO）转为微信运力编码；未映射时记 failed 并提示后台维护映射 - -**order_key 构造**（优先 transaction_id 模式，聚合支付更稳）： - -```json -{ - "order_key": { - "order_number_type": 2, - "transaction_id": "420000..." - }, - "logistics_type": 1, - "delivery_mode": 1, - "shipping_list": [{ - "tracking_no": "...", - "express_company": "SF", - "item_desc": "商品标题摘要" - }], - "upload_time": "2026-09-10T12:00:00+08:00", - "payer": { "openid": "用户sub_openid" } -} -``` - -**openid 来源**：支付 notify 的 `sub_openid` / `buyer_email` 字段，或 `UserOauth` 表（platform=wxMiniProgram）。 - -**异步执行**：Hook 内不写同步 HTTP；投递 Queue `WxShippingJob`，避免发货接口阻塞后台操作。 - -### 4.4 `order_confirm_after` 确认收货同步 - -文件：新建 [`ConfirmHook.php`](addons/shopro_wechat_trade/listener/ConfirmHook.php) - -当订单全部 item `dispatch_status=已收货`（复用 [`Confirm::orderConfirmAfter`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\order\Confirm.php) 中 `noConfirm <= 0` 判定）： - -- 调用 `POST /wxa/sec/order/notify_confirm_receive` -- 传 `transaction_id` + 收货时间 -- 幂等写入 `shopro_wechat_trade_sync(sync_type=confirm)` - -### 4.5 微信 API 封装 - -复用现有 [`addons/shopro/library/Wechat.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\Wechat.php) 获取小程序 `access_token`（`wxMiniProgram` 配置），在 `WxTradeClient` 中封装： - -| API | 用途 | -|-----|------| -| `POST /wxa/sec/order/update_order_detail_path` | 安装/配置时写入跳转路径 | -| `POST /wxa/sec/order/get_order_detail_path` | 配置页展示 | -| `POST /wxa/sec/order/upload_shipping_info` | 发货同步 | -| `POST /wxa/sec/order/notify_confirm_receive` | 确认收货 | -| `GET /wxa/sec/order/is_trade_managed` | 后台自检是否已纳入管控 | - -参考文档：[小程序购物订单](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/business-capabilities/order_center/order_center.html) - ---- - -## 五、与汇付方案的关系 - -| 项 | shopro_huifu（已有） | shopro_wechat_trade（新建） | -|----|----------------------|----------------------------| -| 职责 | 聚合支付下单/通知/分账 | 微信交易合规（订单展示+发货同步） | -| Hook | `shopro_pay_create` 等 | `order_send_after` / `order_confirm_after` | -| 适用范围 | 仅 huifu 通道 | 全部小程序微信支付（含 yansongda 直连） | -| 耦合点 | notify 落库 wx_transaction_id | 读取 order / pay_ext 发起微信 API | - -支付被微信拦截（「小程序违规」）的**解除**依赖：完成接入 + 历史订单补传 + 微信侧审核/解控（需运营确认，非纯代码可保证）。 - ---- - -## 六、后台与运维 - -**配置页**（插件内，精简）： - -- 开关：`wechat_trade_enable` -- 订单详情 path（默认 `pages/order/detail?order_sn=${商品订单号}`） -- 一键「检测接入状态」（`is_trade_managed` + `get_order_detail_path`） -- 同步日志列表（失败可手动重试） - -**CLI**： - -```bash -php think shopro_wechat_trade:init-path # 配置订单详情路径 -php think shopro_wechat_trade:backfill # 补传已发货未同步订单 -php think shopro_wechat_trade:retry-failed # 重试失败记录 -``` - ---- - -## 七、实施顺序 - -```mermaid -flowchart TD - P0[运营签署协议+开通服务] --> P1[shopro_huifu保存wx_transaction_id] - P1 --> P2[创建shopro_wechat_trade插件骨架] - P2 --> P3[WxTradeClient+路径配置] - P3 --> P4[小程序detail支持order_sn] - P4 --> P5[ShippingHook+Queue] - P5 --> P6[ConfirmHook] - P6 --> P7[backfill历史订单] - P7 --> P8[联调验证+解控申请] -``` - ---- - -## 八、测试清单 - -1. **直连微信**：小程序下单 → 后台快递发货 → 微信「小程序购物订单」可见物流 -2. **汇付微信**：同上，确认使用的是 `wx_transaction_id` 而非 `hf_seq_id` -3. **分拆发货**：多商品订单分两次发货，两次 upload 均成功 -4. **自动发货/自提**：`autosend`/`selfetch` 映射 logistics_type 3/4 -5. **确认收货**：用户确认后 `notify_confirm_receive` 成功 -6. **幂等**：重复发货/重复通知不重复报错 -7. **失败重试**：故意填错 express_company，队列重试可恢复 -8. **历史补传**：对已发货未同步订单跑 backfill -9. **跳转**：从「我-小店与卡包-小程序购物订单」点击跳转详情页正常 - ---- - -## 九、风险与人工确认项 - -- 汇付 notify 中 `wx_response.transaction_id` 字段需用**生产/沙箱真实样本**确认（不同通道返回结构可能差异） -- 微信解控时间由平台审核决定，代码只能满足合规接入条件 -- 部分快递公司编码可能与微信运力表不一致，需维护 [`WxExpressMapper`](addons/shopro_wechat_trade/library/WxExpressMapper.php) 映射表 -- 拼团/未支付/已退款 item 需跳过同步，避免无效 API 调用 diff --git a/plan/敏感文案替换_1357718d.plan.md b/plan/敏感文案替换_1357718d.plan.md deleted file mode 100644 index 50e9061..0000000 --- a/plan/敏感文案替换_1357718d.plan.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: 敏感文案替换 -overview: 将小程序页面与后台管理界面中用户可见的「代理」改为「公司」、「佣金」改为「差价」，不改代码标识/路由/数据库字段；并执行 SQL 更新已有等级名称数据。「区域服务商」宫格名称保持不变。 -todos: - - id: mp-pages - content: 修改小程序 pages.json、regional-agent/*、commission/*、sh-grid.vue 中的用户可见文案 - status: completed - - id: api-models - content: 修改 API 提示、Reward/UserWalletLog/RegionalAgent Reward 等模型中的展示文案 - status: completed - - id: admin-ui - content: 修改 menu.php、regional_agent 与 commission 后台视图/JS/Controller 导出表头 - status: completed - - id: sql-upgrade - content: 新增 upgrade_text_alias.sql 并更新等级名称与钱包 memo 历史数据 - status: completed - - id: verify - content: 清除菜单缓存，编译小程序，按验证清单抽查关键页面 - status: completed -isProject: false ---- - -# 敏感文案替换：代理→公司、佣金→差价 - -## 替换规则 - -| 原文 | 新文 | 范围 | -|------|------|------| -| 代理 | 公司 | 仅用户可见文案 | -| 佣金 | 差价 | 仅用户可见文案 | - -**明确不改：** -- 代码标识、路由、API 路径（如 `regional-agent`、`commission_*`） -- 数据库表名/字段名 -- [`unpackage/`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\unpackage) 编译产物（重新打包后自动生成） -- 测试脚本、plan 文档、SQL 迁移历史文件 -- [`sh-grid.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-grid.vue) 中已有的 **「区域服务商」** 名称（按您确认保持不变） - -**复合词示例：** -- 区域代理 → 区域公司 -- 省级代理 → 省级公司 -- 佣金明细 → 差价明细 -- 待入账佣金 → 待入账差价 -- 推广佣金 → 推广差价 -- 区域代理佣金 → 区域公司差价 - -「分佣」单独出现时不改（如「分佣金额」），但若含「佣金」则一并替换。 - ---- - -## 一、小程序端（xgsc.gynhc.com_wx） - -### 1. 页面路由标题 — [`pages.json`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages.json) - -- `佣金明细` → `差价明细` -- `区域代理` → `区域公司` -- `申请区域代理` → `申请区域公司` -- `区域佣金` → `区域差价` - -### 2. 区域公司模块 — `pages/app/regional-agent/` - -| 文件 | 主要改动 | -|------|----------| -| [`index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\index.vue) | 导航栏、空态、菜单、toast；`levelName` 默认 `'代理'` → `'公司'`；待结算佣金→差价 | -| [`apply.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\apply.vue) | 表单标签、等级选项（省级/市级/区县代理→公司）、校验提示 | -| [`rewards.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\rewards.vue) | 导航栏「区域佣金」→「区域差价」、空态文案 | -| [`orders.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\orders.vue) | 注释（可选） | - -### 3. 分销/差价模块 — `pages/app/commission/` - -| 文件 | 主要改动 | -|------|----------| -| [`index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\index.vue) | 待入账佣金、佣金明细菜单、区域代理入口文案 | -| [`commission-log.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\commission-log.vue) | 待入账/可提现佣金、列表默认「推广佣金」 | -| [`goods.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\goods.vue) | 「预计佣金」→「预计差价」 | -| [`order.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\order.vue) | 列头「佣金」→「差价」 | - -### 4. 首页宫格 — [`sh-grid.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-grid.vue) - -- 仅改：`desc: '推广赚佣金'` → `'推广赚差价'` -- **不改**「区域服务商」及其 alias 映射 - -### 5. 后端 API 返回文案（小程序 toast/提示） - -[`addons/shopro/controller/regional_agent/Agent.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\regional_agent\Agent.php) 中用户可见 error/success 消息，例如： -- `请选择代理区域` → `请选择公司区域` -- `您已申请或已是该区域代理` → `...区域公司` -- `申请已通过，您已成为该区域代理` → `...区域公司` - -[`RegionalAgent.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\regional_agent\RegionalAgent.php)：`区域代理已关闭` → `区域公司已关闭` - -### 6. 小程序数据层文案（接口字段展示名） - -| 文件 | 改动 | -|------|------| -| [`addons/shopro/model/commission/Reward.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\model\commission\Reward.php) | `award_type_name` 映射：`推广佣金` → `推广差价` | -| [`addons/shopro/model/UserWalletLog.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\model\UserWalletLog.php) | `佣金收益/扣除`、`区域代理佣金` 等 type 显示名 | -| [`addons/shopro/library/regional_agent/Reward.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\regional_agent\Reward.php) | 钱包流水 memo：`区域代理佣金` → `区域公司差价` | - ---- - -## 二、后台管理端（chufang.gynhc.com） - -### 1. 侧边栏菜单 — [`addons/shopro/config/menu.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\config\menu.php) - -批量替换 title 字段，例如： -- `区域代理` → `区域公司` -- `代理设置/等级/订单` → `公司设置/等级/订单` -- `佣金明细` → `差价明细` - -改完后需 **清除 FastAdmin 菜单缓存**（后台「常规管理 → 系统配置」或删除 `runtime/cache` 中菜单缓存），否则侧边栏可能仍显示旧文案。 - -### 2. 区域公司后台视图 — `application/admin/view/shopro/regional_agent/` - -涉及 agent、level、config、dashboard、order、reward 共约 10 个 HTML 模板：页面标题、表格列头、表单 label、提示说明、空态文案等。 - -### 3. 分销差价后台视图 — `application/admin/view/shopro/commission/` - -涉及 goods、order、reward、config、level、agent 等模板：「设置佣金」→「设置差价」、「佣金规则/比例/明细」等。 - -### 4. 后台 JS 交互文案 — `public/assets/js/backend/shopro/` - -| 文件 | 典型改动 | -|------|----------| -| `regional_agent/agent.js` | 弹窗标题、确认提示、校验 toast | -| `regional_agent/order.js` / `reward.js` | `确认退回佣金？` → `确认退回差价？` | -| `commission/goods.js` | `设置佣金` → `设置差价` | -| `commission/order.js` | 状态标签（已结算佣金→差价）、`推广佣金` 映射 | -| `commission/agent.js` | 累计/待入账佣金列标题 | -| `split/receiver.js`、`split/rule.js` | `区域代理` → `区域公司` | -| `shopro_huifu/onboard.js` | 角色显示 `区域代理` → `区域公司` | - -### 5. 后台 Model / Controller 展示字段 - -| 文件 | 改动 | -|------|------| -| [`application/admin/model/shopro/commission/Reward.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\model\shopro\commission\Reward.php) | `推广佣金` 默认名 | -| [`application/admin/model/shopro/commission/Log.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\model\shopro\commission\Log.php) | event `'reward' => '佣金'` → `'差价'` | -| [`application/admin/controller/shopro/regional_agent/Reward.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\regional_agent\Reward.php) | 导出 Excel 表头 | -| [`application/admin/controller/shopro/regional_agent/Order.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\regional_agent\Order.php) | 导出表头、success/error 消息 | -| [`addons/shopro/notifications/RegionalAgent.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\notifications\RegionalAgent.php) | 通知模板字段名 | -| [`addons/shopro_huifu/library/onboard/HuifuOnboardAdminView.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\onboard\HuifuOnboardAdminView.php) | `type_text` 显示 | - ---- - -## 三、数据库已有数据更新 - -新增一次性 SQL 脚本（建议放在 [`addons/shopro/upgrade_text_alias.sql`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_text_alias.sql)）： - -```sql --- 区域等级名称：代理 → 公司 -UPDATE `fa_shopro_regional_agent_level` -SET `name` = REPLACE(`name`, '代理', '公司') -WHERE `name` LIKE '%代理%'; - --- 钱包流水 memo（历史记录展示） -UPDATE `fa_shopro_user_wallet_log` -SET `memo` = REPLACE(REPLACE(`memo`, '区域代理佣金', '区域公司差价'), '佣金', '差价') -WHERE `memo` LIKE '%佣金%' OR `memo` LIKE '%代理%'; -``` - -> 表前缀若非 `fa_`，执行前按实际前缀调整。 - ---- - -## 四、验证清单 - -```mermaid -flowchart LR - subgraph mp [小程序] - A[我的服务宫格] --> B[分销中心/差价明细] - A --> C[区域服务商页] - C --> D[申请/订单/区域差价] - end - subgraph admin [后台] - E[侧边栏菜单] --> F[区域公司模块] - E --> G[分销差价模块] - F --> H[导出Excel表头] - end - subgraph data [数据] - I[等级名称SQL] - J[钱包流水memo] - end -``` - -1. 小程序「我的服务」：区域服务商名称不变；分销中心内「待入账差价」「差价明细」显示正确 -2. 区域公司申请页：等级选项为「省级公司」等；提交失败/成功 toast 文案正确 -3. 钱包流水：type_name 与 memo 不含「代理/佣金」 -4. 后台侧边栏：「区域公司」「差价明细」等新菜单名生效 -5. 后台列表/导出：列头与 Excel 文件名/表头一致 -6. 重新编译小程序并上传体验版 - ---- - -## 工作量估计 - -- 小程序源码：约 8 个文件 -- 后台视图 + JS + PHP：约 25–30 个文件 -- SQL 脚本：1 个新文件 -- 预计改动均为字符串替换，不涉及业务逻辑 diff --git a/plan/本地数据库完整还原_5823409e.plan.md b/plan/本地数据库完整还原_5823409e.plan.md deleted file mode 100644 index 5750645..0000000 --- a/plan/本地数据库完整还原_5823409e.plan.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -name: 本地数据库完整还原 -overview: 在本地 MySQL 完全重建 `gushiyu` 库：先导入 FastAdmin 基础表 + Shopro 插件表，再按顺序执行二开迁移 SQL，补齐代码中引用但仓库缺失的自定义表，最后导入白酒测试数据并做全量校验。 -todos: - - id: prep-db - content: DROP/CREATE gushiyu 并确认 .env 与 database.php 连接一致 - status: completed - - id: import-base - content: 导入 fastadmin.sql + 预处理后的 shopro/install.sql - status: completed - - id: custom-ddl - content: 编写并执行 20260810_custom_business_tables.sql（8张缺失表） - status: completed - - id: run-migrations - content: 按依赖顺序执行 sql/migrations 全部 9 个二开迁移 - status: completed - - id: addon-menus - content: 注册 fa_addon 并 php think addon enable/upgrade shopro，重置 admin 密码 - status: completed - - id: seed-data - content: 执行 decorate_bootstrap + baijiu_data + repair_goods_sku_prices + 业务测试种子 - status: completed - - id: verify - content: 编写 verify_schema 脚本并运行 verification/*.sql + 后台/接口冒烟 - status: completed -isProject: false ---- - -# 本地 gushiyu 数据库完整还原计划 - -## 目标与环境 - -| 项 | 值 | -|---|---| -| 数据库 | `gushiyu` | -| 连接 | [application/database.php](application/database.php) — `127.0.0.1:3306` / `root` / `root` | -| 表前缀 | `fa_` | -| 策略 | **DROP DATABASE 后从零重建**（你已确认） | - -## 现状分析（全局检查结果） - -### SQL 资产分层 - -```mermaid -flowchart TD - base[fastadmin.sql 19张核心表] - shopro[shopro/install.sql 76张Shopro表+配置种子] - mig[sql/migrations 9个二开迁移] - data[baijiu_data.sql 白酒商品测试数据] - gap[缺失: 8张二开业务表DDL] - base --> shopro --> mig --> gap --> data -``` - -1. **[yuanshi.sql](yuanshi.sql)** — 仅含 FastAdmin 原始 18 张表 + 少量 admin 数据，**不含 Shopro**，不适合作为本项目主结构源。 -2. **[application/admin/command/Install/fastadmin.sql](application/admin/command/Install/fastadmin.sql)** — 完整 FastAdmin 安装脚本（19 表 + 默认 `fa_auth_rule`），**作为第一层基础**。 -3. **[addons/shopro/install.sql](addons/shopro/install.sql)** — Shopro 全部 **76 张表**、`fa_shopro_config` 默认配置、`fa_shopro_area` 地区数据、以及对 `fa_user` / `fa_user_group` 的扩展字段（分销相关）。需将 `__PREFIX__` 替换为 `fa_` 后导入。 -4. **[sql/migrations/](sql/migrations/)** — 项目二开增量（门店三级/锁客/区域代理/后台菜单），**必须在 shopro 基础表之后执行**。 -5. **[baijiu_data.sql](baijiu_data.sql)** — 仅 **DML**（42 个白酒商品、22 分类、运费模板、首页装修 UPDATE），**不含 CREATE TABLE**。其中装修 UPDATE 依赖生产环境固定 ID（`decorate_id=50`，`decorate_content.id=9212~9217`），新库需先 seed 对应记录。 - -### 二开迁移依赖顺序（不可乱序） - -| 顺序 | 文件 | 作用 | -|------|------|------| -| 1 | `20260725_store_income_foundation.sql` | `fa_shopro_store` 增 level/parent_id/收益字段；新建 `fa_shopro_store_income`；`fa_shopro_order_item.store_income_snapshot` | -| 2 | `20260725_store_customer_lock_code.sql` | 门店锁客码字段 + 唯一索引 | -| 3 | `20260725_store_customer_lock_income.sql` | 锁客收益比例；`fa_user.customer_lock_*`；`fa_shopro_store_income.income_source` + 唯一键调整 | -| 4 | `20260725_store_income_wallet_compat.sql` | 钱包流水索引兼容 | -| 5 | `20260725_region_agent_settlement.sql` | 7 张区域代理表 + 菜单权限节点 | -| 6 | `20260725_normalize_admin_menu.sql` | Shopro 后台菜单归位（硬编码 `fa_auth_rule`） | -| 7 | `20260725_promote_shop_menu_to_top_level.sql` | 商城菜单提升为顶级 | -| 8 | `20260726_region_agent_admin_simplify.sql` | 区域代理菜单收敛 + 索引 | -| 9 | `20260726_repair_goods_sku_prices.sql` | 为非 SKU 商品补 `fa_shopro_goods_sku_price`（**在 baijiu_data 之后**） | - -### 代码引用但仓库无 DDL 的表（需新建） - -通过全局扫描 `application/` 与 `addons/shopro/model/` 的 `$name` 属性，以下表 **不在任何 .sql 中**，需根据模型/控制器/视图反推并新建 [sql/migrations/20260810_custom_business_tables.sql](sql/migrations/20260810_custom_business_tables.sql)： - -| 表名 | 来源 | 关键字段（从代码推断） | -|------|------|------------------------| -| `fa_rob_order` | [RobOrderModel.php](addons/shopro/model/RobOrderModel.php) | user_id, activity_id, goods_id, title, activity_price, is_rob, is_use, create_time | -| `fa_video` | [VideoModel.php](application/common/model/VideoModel.php) + [video/add.html](application/admin/view/video/add.html) | title, image, video, desc, content, views, play_num, sort, status, create_time | -| `fa_notice` | [NoticeModel.php](application/common/model/NoticeModel.php) | title, cover, desc, content, views, type, status, create_time | -| `fa_message` | [MessageModel.php](application/common/model/MessageModel.php) | content, status, create_time（+ user_id 如有 API 使用） | -| `fa_report` | [ReportModel.php](application/common/model/ReportModel.php) | user_id, order_id, name, phone, address, content, images, status, create_time | -| `fa_upgrade` | [UpgradeModel.php](application/common/model/UpgradeModel.php) | name, code, content(JSON), status, create_time, update_time | -| `fa_attachment_nav` | [AttachmentNavModel.php](application/common/model/AttachmentNavModel.php) | pid, name, sort, status, createtime | -| `fa_shopro_goods_params` | [ParamsModel.php](application/common/model/ParamsModel.php) | title, params, status, create_time | - -> `fa_shopro_decorate_page` 仅有 Model 定义、无控制器/SQL 引用，优先级最低，可暂不建。 - -### 二开字段汇总（迁移后 `fa_shopro_store` / `fa_user` 最终态） - -**fa_shopro_store 新增字段：** -`level`, `parent_id`, `settlement_user_id`, `pickup_income_rate`, `customer_lock_income_rate`, `province_unique_key`, `city_unique_key`, `customer_lock_code`, `customer_lock_code_version`, `customer_lock_code_updated_at` - -**fa_user 新增字段：** -Shopro 分销：`parent_user_id`, `child_user_count`, `child_user_count_1/2`, `total_consume` -锁客：`customer_lock_store_id`, `customer_lock_time` - -**fa_shopro_order_item 新增字段：** -`store_income_snapshot`, `customer_lock_income_snapshot` - -## 执行步骤 - -### 阶段 1：准备与建库 - -1. 确认本地 MySQL 可连接（`mysql -uroot -proot -h127.0.0.1`）。 -2. 确认项目 `.env` 与 [application/database.php](application/database.php) 一致（database=`gushiyu`）。 -3. 执行： - ```sql - DROP DATABASE IF EXISTS `gushiyu`; - CREATE DATABASE `gushiyu` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; - USE `gushiyu`; - ``` - -### 阶段 2：导入结构与二开迁移 - -4. 导入 FastAdmin 基础：`application/admin/command/Install/fastadmin.sql` -5. 预处理并导入 Shopro： - - 将 [addons/shopro/install.sql](addons/shopro/install.sql) 中 `__PREFIX__` → `fa_` - - 通过 `mysql gushiyu < shopro_fa.sql` 导入（约 5500 行，含 `fa_shopro_area` 与 `fa_shopro_config`） -6. 新建并执行 `sql/migrations/20260810_custom_business_tables.sql`（补齐 8 张缺失表） -7. 按上表顺序依次执行 `sql/migrations/20260725_*.sql` 和 `20260726_*.sql`（每个文件内 `__PREFIX__` → `fa_`） - -### 阶段 3：Shopro 插件菜单与后台权限 - -8. 在 `fa_addon` 注册 shopro/epay/alisms 插件记录（若表不存在则 FastAdmin 首次访问插件页会自动创建，或手动 CREATE） -9. 执行 ThinkPHP 命令同步菜单： - ```bash - php think addon --name=shopro --action=enable - php think addon --name=shopro --action=upgrade - ``` -10. 重置管理员密码（fastadmin.sql 默认密码为空；使用 yuanshi.sql 中可用 hash：`admin` / `123456`）： - ```sql - UPDATE fa_admin SET password='cba719238115b3611accf3072a29b942', salt='0f77e1' WHERE username='admin'; - ``` - -### 阶段 4：测试数据导入 - -11. **新建** [sql/seed/20260810_decorate_bootstrap.sql](sql/seed/20260810_decorate_bootstrap.sql)： - - `INSERT fa_shopro_decorate` id=50（platform 含 H5/wxMiniProgram，status=normal） - - `INSERT fa_shopro_decorate_content` id=9212~9217（category=home，type 对应 banner/title/menu/goods 组件，content 可为 `{}` 占位） - - 设置 AUTO_INCREMENT 避免后续冲突 -12. 执行 `decorate_bootstrap.sql` -13. 执行 [baijiu_data.sql](baijiu_data.sql)（42 商品 + 分类 + 运费 + 装修 UPDATE） -14. 执行 [20260726_repair_goods_sku_prices.sql](sql/migrations/20260726_repair_goods_sku_prices.sql) 为 42 个商品生成默认 SKU 价格行 - -### 阶段 5：可选业务测试种子 - -15. **新建** [sql/seed/20260810_business_test_data.sql](sql/seed/20260810_business_test_data.sql)，插入最小可测数据： - - 1 个测试会员（`fa_user`） - - 3 级门店样例（省/市/区，`fa_shopro_store`，含锁客码） - - 1 条区域代理规则 + 1 个省代授权（`fa_shopro_region_config` / `fa_shopro_region_agent`） - - 1 条公告、1 条视频（可选） - -### 阶段 6：全量校验（防遗漏） - -16. 编写并执行 [sql/restore/verify_schema.ps1](sql/restore/verify_schema.ps1)（或 PHP 脚本），对比： - - 期望表总数 ≈ **19 + 76 + 1 + 7 + 8 = 111** 张（含 `fa_jobs`） - - 二开关键列存在性：`information_schema.columns` 检查 store/user/order_item 扩展字段 - - 模型 `$name` 与数据库表一一对应（扫描结果作为 checklist） -17. 运行已有校验脚本（只读 SELECT）： - - [sql/verification/20260725_store_customer_lock_code_check.sql](sql/verification/20260725_store_customer_lock_code_check.sql) - - [sql/verification/20260725_store_customer_lock_income_check.sql](sql/verification/20260725_store_customer_lock_income_check.sql) - - [sql/verification/20260726_store_hierarchy_manager_scope_check.sql](sql/verification/20260726_store_hierarchy_manager_scope_check.sql) -18. 功能冒烟： - - 后台登录 https://本地/s.php/index/login（admin/123456） - - 商品列表有 42 个白酒 SKU - - 小程序/H5 首页装修接口返回非空（`fa_shopro_decorate` id=50） - - 区域代理/门店锁客菜单可见且无 SQL 字段报错 - -## 将新增的文件（按规范归入 sql/） - -| 文件 | 用途 | -|------|------| -| `sql/migrations/20260810_custom_business_tables.sql` | 8 张缺失业务表 DDL | -| `sql/seed/20260810_decorate_bootstrap.sql` | 装修模板 bootstrap（匹配 baijiu_data 固定 ID） | -| `sql/seed/20260810_business_test_data.sql` | 门店/代理/用户测试数据 | -| `sql/restore/restore_local.ps1` | 一键还原编排脚本（DROP → 导入 → 迁移 → seed → 校验） | -| `sql/restore/verify_schema.ps1` | 表/字段完整性校验 | - -## 风险与注意事项 - -- **baijiu_data.sql 图片路径** 引用 `/uploads/20260724/...`，需确保 [public/uploads/](public/uploads/) 目录存在对应图片，否则前端显示空白图。 -- **region_agent_settlement.sql** 中 `uniq_region_settle_period` 索引重建语句在非幂等场景可能报错；脚本中需加 `information_schema` 判断（迁移文件已有部分处理，执行时注意日志）。 -- **normalize/promote 菜单迁移** 依赖 shopro 菜单已存在（必须先 `addon enable/upgrade`）。 -- **yuanshi.sql 不导入** — 仅作 FastAdmin 原始参考，避免与 fastadmin.sql 冲突。 -- 生产库（118.184.172.94）本次**不在范围内**；本地验证通过后可复用同一脚本链路上线。 - -## 预期结果 - -还原完成后本地库应包含： -- FastAdmin 完整后台框架 + Shopro 商城 76 表 -- 全部二开字段（门店三级、锁客、区域代理结算） -- 42 个谷时雨白酒商品 + 分类 + 运费模板 + 首页装修 -- 8 张自定义业务表结构就绪 -- 后台可登录，商城核心 API 无 "fields not exists" / "Table doesn't exist" 错误 diff --git a/plan/汇付个人进件对接_e1144173.plan.md b/plan/汇付个人进件对接_e1144173.plan.md deleted file mode 100644 index 7fc0fb7..0000000 --- a/plan/汇付个人进件对接_e1144173.plan.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -name: 汇付个人进件对接 -overview: 在 addons/shopro_huifu 插件内新增个人进件模块，统一服务推广员（分销）与区域代理两条申请链路；用户提交申请时按汇付标准字段收集资料并发起进件，汇付审核成功后后台才允许业务审核通过，成功后自动写入 shopro_split_receiver 供 SplitCalculator/HuifuSplitService 分账。 -todos: - - id: p0-schema - content: 新增 upgrade_huifu_onboard.sql：shopro_huifu_onboard 表 + commission/regional_agent 关联字段 + install 集成 - status: completed - - id: p0-service - content: 插件 library/onboard/ 实现 Picture/BasicIndv/BusiOpen/Query/Validator/ReceiverSync 与 HuifuOnboardService 主编排 - status: completed - - id: p1-api - content: 新增 controller/Onboard.php（config/status/upload/submit/resubmit/notify）+ CLI shopro_huifu:onboard-poll - status: completed - - id: p2-commission - content: 分销：Hook shopro_commission_apply_after + 后台审核拦截 + info 返回进件状态 + 小程序 apply.vue 汇付表单组件 - status: completed - - id: p3-regional - content: 区域代理：Hook shopro_regional_agent_apply_after + audit 拦截 + apply.vue 复用汇付表单组件 - status: completed - - id: p4-split - content: 进件 approved 自动写 shopro_split_receiver；HuifuSplitService 缺 receiver 日志；后台 receiver/进件列表展示 - status: completed - - id: p5-test - content: 沙箱联调：进件→业务审核→延时分账全链路 + 非汇付模式回归 - status: completed -isProject: false ---- - -# 汇付个人进件（推广员/区域代理）细化实施计划 - -## 一、Skill 口径与现状 - -| 维度 | 判定 | -|------|------| -| **能力域** | 商户/个人进件（非支付交易）；支付分账已在 [`addons/shopro_huifu`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu) 完成 | -| **进件类型** | **个人用户**（`V2UserBasicdataIndv` + `V2UserBusiOpen`） | -| **技术栈** | PHP / FastAdmin + Shopro，复用插件内 `dg-php-sdk 2.0.30` | -| **触发条件** | `split_mode=huifu` 或 `split_provider=huifu` 且插件启用时，分销/代理申请**强制走汇付进件** | -| **审核顺序** | **汇付优先**：汇付进件成功 → 后台才允许业务审核通过 | - -**当前缺口（代码已核实）：** - -- 分销申请：[`commission/Agent::applyForm()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\commission\Agent.php) 仅保存 JSON `apply_info`，无汇付 API -- 区域代理申请：[`regional_agent/Agent::apply()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\regional_agent\Agent.php) 同上 -- 分账计算：[`SplitCalculator::getReceiver()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitCalculator.php) 汇付模式下**必须有** `shopro_split_receiver.channel=huifu` 且 `receiver_account=huifu_id`，否则跳过该角色分账 -- 插件 SDK 已含进件 Request：`V2SupplementaryPictureRequest`、`V2UserBasicdataIndvRequest`、`V2UserBusiOpenRequest`、`V2UserApplyQueryRequest`、`V2UserBasicdataQueryRequest` - -```mermaid -sequenceDiagram - participant MP as 小程序申请页 - participant API as Shopro/插件API - participant OB as HuifuOnboardService - participant HF as 汇付斗拱 - participant Admin as 后台审核 - participant Split as SplitCalculator - - MP->>API: 提交业务资料+进件资料 - API->>OB: createOnboard(promoter/regional_agent) - OB->>HF: 图片上传 SupplementaryPicture - OB->>HF: UserBasicdataIndv 开户 - HF-->>OB: huifu_id - OB->>HF: UserBusiOpen 业务入驻 - HF-->>OB: apply_no - loop 轮询 - OB->>HF: UserApplyQuery - end - OB->>API: onboard_status=approved - OB->>API: 写入 split_receiver - Admin->>API: 审核通过(仅当汇付已通过) - Note over Split: 分账时读取 huifu_id -``` - ---- - -## 二、数据表设计 - -新增插件表 [`upgrade_huifu_onboard.sql`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\upgrade_huifu_onboard.sql)： - -### 2.1 `shopro_huifu_onboard`（进件主表） - -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | int PK | 自增 | -| `user_id` | int | 商城用户 ID | -| `role_type` | enum | `promoter` / `regional_agent` | -| `role_ref_id` | int | 推广员=`user_id`；区域代理=`shopro_regional_agent.id` | -| `onboard_status` | varchar(20) | `draft/submitting/basic_ok/busi_pending/approved/rejected/failed` | -| `huifu_id` | varchar(32) | 汇付客户号（开户返回） | -| `apply_no` | varchar(64) | 业务入驻申请单号 | -| `req_seq_id` | varchar(64) | 最近一次汇付请求流水（保留不重写） | -| `req_date` | char(8) | 请求日期 Ymd | -| `basic_req_seq_id` | varchar(64) | 开户流水 | -| `busi_req_seq_id` | varchar(64) | 入驻流水 | -| `reject_reason` | varchar(500) | 汇付/本地驳回原因 | -| `payload` | text | 脱敏后的提交快照 JSON | -| `file_map` | text | 本地图片 URL → 汇付 file_id 映射 | -| `resp_snapshot` | text | 最后一次汇付响应摘要 | -| `createtime/updatetime` | int | 时间戳 | - -**唯一约束：** `UNIQUE(user_id, role_type, role_ref_id)` — 同一角色仅一条有效进件记录。 - -### 2.2 业务表扩展（轻量） - -| 表 | 新增字段 | 用途 | -|----|----------|------| -| `shopro_commission_agent` | `huifu_onboard_id` int NULL | 关联进件记录 | -| `shopro_regional_agent` | `huifu_onboard_id` int NULL | 关联进件记录 | - -### 2.3 与分账接收方关系 - -进件 `approved` 后自动 upsert [`shopro_split_receiver`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_payment_split.sql)： - -```sql -role_type = promoter|regional_agent -role_id = user_id -channel = huifu -receiver_type = HUIFU_ID -receiver_account = huifu_id -status = normal -``` - ---- - -## 三、汇付接口清单与调用顺序 - -| 步骤 | SDK Request | 路径/用途 | 触发时机 | -|------|-------------|-----------|----------| -| 1 | `V2SupplementaryPictureRequest` | 图片上传 | 用户提交前/提交时，身份证正反面、银行卡等 | -| 2 | `V2UserBasicdataIndvRequest` | 个人基本信息开户 | 提交进件 | -| 3 | `V2UserBusiOpenRequest` | 用户业务入驻（结算卡/结算周期） | 步骤 2 返回 `huifu_id` 后 | -| 4 | `V2UserApplyQueryRequest` | 申请单状态查询 | 异步轮询 / CLI 补偿 | -| 5 | `V2UserBasicdataQueryRequest` | 用户详情复核 | 终态确认、后台展示 | - -**异步通知（可选 P1）：** 插件新增 `controller/Onboard.php` 接收 `async_return_url`，验签后更新 `onboard_status`（与支付 notify 同样 RSA 验签 + 幂等）。 - -**SDK 约束（与支付一致）：** -- 加载 SDK 前 `DEBUG=false` -- `skill_source=hfps/1.3.5;hfms/1.0.2`（支付+进件联合请求） -- 复用 [`HuifuClient`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\HuifuClient.php) 初始化 `BsPayClient` - ---- - -## 四、汇付字段对照表（个人进件 MVP） - -### 4.1 小程序采集字段 → `V2UserBasicdataIndv` - -| 业务字段（小程序/后台） | 汇付 wire 字段 | 必填 | 说明 | -|------------------------|----------------|------|------| -| 真实姓名 | `name` | Y | 与身份证一致 | -| 证件类型 | `cert_type` | Y | 固定 `00` 身份证 | -| 身份证号 | `cert_no` | Y | 18 位 | -| 证件有效期类型 | `cert_validity_type` | Y | `1`长期 / `0`非长期 | -| 证件开始日期 | `cert_begin_date` | Y | `yyyyMMdd` | -| 证件截止日期 | `extendInfo.cert_end_date` | 条件 | 非长期必填 | -| 手机号 | `mobile_no` | Y | 与银行卡预留手机号一致 | -| 身份证人像面 | `extendInfo.file_list[F02]` | Y | 先 `SupplementaryPicture` 得 `file_id` | -| 身份证国徽面 | `extendInfo.file_list[F03]` | Y | 同上 | - -### 4.2 小程序采集字段 → `V2UserBusiOpen` - -| 业务字段 | 汇付 extendInfo 路径 | 必填 | 说明 | -|----------|---------------------|------|------| -| — | `huifu_id` | Y | 步骤 2 返回 | -| — | `upper_huifu_id` | Y | 读插件配置 `upper_huifu_id` 或 `sys_id` | -| 开户名 | `card_info.card_name` | Y | 与 `name` 一致 | -| 银行卡号 | `card_info.card_no` | Y | 对私借记卡 | -| 银行省市 | `card_info.prov_id/area_id` | Y | 用现有 [`Area`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\model\Area.php) 映射汇付编码 | -| 支行联行号 | `card_info.branch_code` | Y | 小程序选银行+支行或后台维护字典 | -| 持卡人证件 | `card_info.cert_*` | Y | 复用基本信息 | -| 银行预留手机 | `card_info.mp` | Y | | -| 结算周期 | `settle_config_list[0].settle_cycle` | Y | 默认 `D1`（后台可配） | -| 取现配置 | `cash_config` | Y | 默认模板（后台可配 `fix_amt/fee_rate/cash_type`） | -| 银行卡照片 | `file_list[F12]` | 视通道 | 按汇付要求 | -| 异步通知 | `async_return_url` | N | `/addons/shopro_huifu/onboard/notify` | - -### 4.3 状态映射 - -| 汇付 `apply_status` / 查询结果 | 本地 `onboard_status` | -|-------------------------------|----------------------| -| 受理中 / 审核中 | `busi_pending` | -| 成功 / 开通完成 | `approved` | -| 驳回 / 失败 | `rejected` / `failed` | - ---- - -## 五、内部 API 清单 - -全部放在插件 `addons/shopro_huifu/controller/Onboard.php`（需登录）： - -| 接口 | 方法 | 说明 | -|------|------|------| -| `/addons/shopro_huifu/onboard/config` | GET | 返回是否强制进件、字段模板、银行字典入口 | -| `/addons/shopro_huifu/onboard/status` | GET | 参数 `role_type` + `role_ref_id`；返回进件进度 | -| `/addons/shopro_huifu/onboard/uploadPicture` | POST | 代理上传图片到汇付，返回 `file_id` | -| `/addons/shopro_huifu/onboard/submit` | POST | 提交完整进件（含 role 信息） | -| `/addons/shopro_huifu/onboard/resubmit` | POST | 驳回后重提 | -| `/addons/shopro_huifu/onboard/notify` | POST | 汇付异步回调（无需登录，验签） | - -**Shopro 核心改造（Hook，约 2 处）：** - -| Hook | 注入点 | 行为 | -|------|--------|------| -| `shopro_commission_apply_after` | [`commission/Agent::applyForm()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\commission\Agent.php) 事务末尾 | 插件 listener 读取 POST 中 `huifu_onboard` 块并调用 `HuifuOnboardService::submit()` | -| `shopro_regional_agent_apply_after` | [`regional_agent/Agent::apply()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\regional_agent\Agent.php) create 后 | 同上，`role_ref_id=新代理ID` | - -> 若暂不增 Hook，可在两个 Controller 各加 3 行 `Hook::listen(...)` 桥接（与支付 Hook 同模式）。 - ---- - -## 六、分销 / 区域代理两条链路改造 - -### 6.1 推广员（分销） - -**现有流程：** [`pages/app/commission/apply.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\commission\apply.vue) → `commission.form` / `commission.apply` - -**改造：** - -1. 当 `onboard/config.required=true` 时，在动态表单下方追加**固定汇付进件区块**（姓名/身份证/有效期/银行卡/支行/证件照），不再仅依赖自由 `agent_form` JSON -2. 提交 payload 增加 `huifu_onboard: { ... }` 与原有 `data` 并列 -3. 后端 `applyForm` 成功后触发进件；返回文案改为「申请已提交，汇付进件审核中」 -4. [`commission/Agent::info()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\commission\Agent.php) 增加 `huifu_onboard_status` 字段供前端展示 - -**后台审核拦截（汇付优先）：** - -- [`admin/commission/Agent::update()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\commission\Agent.php) 当 `key=status` 且 `value=normal` 时： - - 若汇付模式开启且 `onboard_status != approved` → **拒绝审核**，提示「汇付进件未通过」 - - 通过后确认 `shopro_split_receiver` 已存在 - -### 6.2 区域代理 - -**现有流程：** [`pages/app/regional-agent/apply.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\app\regional-agent\apply.vue) → `regionalAgent.apply` - -**改造：** - -1. 保留区域层级 + 省市区选择 -2. 同样追加汇付进件固定字段区块（与推广员共用组件 `components/huifu-onboard-form.vue`） -3. `apply()` create 后立即绑定 `huifu_onboard_id` -4. [`admin/regional_agent/Agent::audit()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\controller\shopro\regional_agent\Agent.php) `approve` 前校验 `onboard_status=approved` - ---- - -## 七、插件内服务层结构 - -``` -addons/shopro_huifu/library/onboard/ -├── HuifuOnboardService.php # 编排：upload → basic → busi → poll -├── HuifuOnboardPicture.php # V2SupplementaryPicture 封装 -├── HuifuOnboardBasicIndv.php # V2UserBasicdataIndv -├── HuifuOnboardBusiOpen.php # V2UserBusiOpen（读后台默认 settle/cash 模板） -├── HuifuOnboardQuery.php # ApplyQuery + BasicdataQuery -├── HuifuOnboardReceiverSync.php # approved 后写 shopro_split_receiver -└── HuifuOnboardValidator.php # 字段校验、身份证/手机号格式 -``` - -**核心方法 `HuifuOnboardService::submit($userId, $roleType, $roleRefId, $formData)`：** - -1. 校验 + 落库 `draft` → `submitting` -2. 批量上传图片得 `file_map` -3. 调 `UserBasicdataIndv`，保存 `huifu_id`、`basic_req_seq_id` → `basic_ok` -4. 调 `UserBusiOpen`，保存 `apply_no` → `busi_pending` -5. 同步查询一次；若未终态则交给队列/CLI - -**`HuifuOnboardReceiverSync::sync($onboard)`：** - -- `approved` 时 upsert 分账接收方 -- 更新 `receiver_name` 为真实姓名 - ---- - -## 八、与 SplitCalculator 对接点 - -现有逻辑（无需改计算规则，仅补强前置条件）： - -```138:166:f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitCalculator.php - protected function getReceiver($roleType, $roleId, $ruleMode = false) - { - $channel = $this->config->isHuifuMode() ? 'huifu' : 'wechat'; - // ... - if ($this->config->isHuifuMode()) { - // promoter/regional_agent 无 huifu_id 则 return null → 该角色不分账 - return null; - } -``` - -| 对接点 | 动作 | -|--------|------| -| 进件成功 | `HuifuOnboardReceiverSync` 写入 `shopro_split_receiver` | -| 分账执行前 | [`HuifuSplitService::executeByOrderId()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\HuifuSplitService.php) 已有 `buildAcctInfos`；缺 receiver 的 item 会被跳过 — **需增加日志/告警** | -| 业务准入 | 推广员/代理未 `approved` 不应进入 `normal` 状态，避免产生佣金但无法分账 | -| 后台分账接收方页 | [`receiver.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\public\assets\js\backend\shopro\split\receiver.js) 增加「汇付进件状态」列，替代仅 `syncWx` | - -**可选增强（P1）：** `SplitCalculator::calculate()` 汇付模式下汇总前检查：若存在佣金角色但无 `huifu_id`，写 `split_order` 失败原因「接收方未进件」。 - ---- - -## 九、后台管理扩展 - -| 模块 | 路径 | 新增能力 | -|------|------|----------| -| 进件记录 | `shopro_huifu/onboard` | 列表、详情、手动重试、状态查询 | -| 进件配置 | `shopro_huifu/config` 扩展 | 默认 `settle_cycle`、`cash_config` 模板、`onboard_required` 开关 | -| 分销商管理 | `shopro/commission/agent` | 列：汇付状态 / huifu_id；审核按钮 disabled 直到 approved | -| 区域代理管理 | `shopro/regional_agent/agent` | 同上 | -| 分账接收方 | `shopro/split/receiver` | 展示 `channel=huifu` + 进件来源 | - -**CLI 补偿：** `php think shopro_huifu:onboard-poll` — 扫描 `busi_pending` 记录调 `UserApplyQuery`，成功后触发 `ReceiverSync`。 - ---- - -## 十、实施阶段与工时 - -| 阶段 | 内容 | 预估 | -|------|------|------| -| **P0 数据与服务** | SQL + Model + `HuifuOnboardService` 五步 API 封装 + 单元日志 | 2 天 | -| **P1 插件 API** | Onboard Controller + notify + CLI 轮询 | 1 天 | -| **P2 分销链路** | Hook + commission apply 改造 + 后台审核拦截 + 小程序表单组件 | 1.5 天 | -| **P3 区域代理链路** | regional apply 改造 + audit 拦截 + 复用表单组件 | 1 天 | -| **P4 分账联动** | ReceiverSync + Split 缺 receiver 告警 + 后台展示 | 0.5 天 | -| **P5 联调上线** | 沙箱进件 → 业务审核 → 实单分账全链路 | 2 天 | - -**合计约 8 人天**（不含汇付商务开通个人用户入驻权限）。 - ---- - -## 十一、测试验收清单 - -1. 汇付模式开启时，推广员/区域代理申请页均展示统一进件表单，缺字段不可提交 -2. 提交后本地产生 `shopro_huifu_onboard` 记录，状态流转 `submitting → basic_ok → busi_pending → approved` -3. 汇付未 `approved` 时，后台审核「通过」按钮报错拦截 -4. `approved` 后自动创建 `shopro_split_receiver(channel=huifu, HUIFU_ID)` -5. 支付 + 延时分账：[`HuifuSplitService`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro_huifu\library\HuifuSplitService.php) 分账串包含推广员/代理 `huifu_id` -6. 进件驳回后可修改重提；`req_seq_id` 每次新生成，历史流水保留 -7. 非汇付模式（`split_mode=wallet/wechat`）下，原有申请流程不受影响 -8. CLI 轮询可补偿异步通知缺失场景 - ---- - -## 十二、风险与人工确认项 - -| 项 | 说明 | -|----|------| -| 汇付控台权限 | 需确认渠道商已开通「个人用户开户 + 用户业务入驻 + 分账接收方」能力 | -| 支行联行号 | 需引入银行/支行数据（汇付编码表或第三方），MVP 可先后台维护常用银行 JSON | -| 敏感信息 | 身份证号/银行卡仅服务端存储，payload 脱敏展示；禁止写日志明文 | -| 企业代理 | 本期仅个人；企业代理需 `V2UserBasicdataEnt`，放二期 | -| 存量代理 | 已存在的 normal 代理需补进件：提供后台「补录进件」入口或批量导入 huifu_id | diff --git a/plan/汇付小程序支付对接_c945b5d0.plan.md b/plan/汇付小程序支付对接_c945b5d0.plan.md deleted file mode 100644 index 291a605..0000000 --- a/plan/汇付小程序支付对接_c945b5d0.plan.md +++ /dev/null @@ -1,1000 +0,0 @@ ---- -name: 汇付小程序支付对接 -overview: 以独立 FastAdmin 插件 addons/shopro_huifu 接入汇付斗拱（聚合支付 V4 + 延时分账），Shopro 核心仅增加可选 Hook 桥接；插件可安装/启用/禁用/卸载，卸载后系统自动回退直连微信支付。 -todos: - - id: p0-bridge - content: Shopro 核心增加 3 个可选 Hook 桥接点（prepay/refund/split），无插件时不影响现有逻辑 - status: completed - - id: p0-plugin-scaffold - content: 创建 addons/shopro_huifu 插件骨架（install/uninstall/enable/disable/menu/SQL） - status: completed - - id: p1-sdk - content: 插件内引入 dg-php-sdk 2.0.30，实现 HuifuClient / HuifuPayService（V4 create + notify + 查单补偿） - status: completed - - id: p1-admin - content: 插件后台配置页（5.3 完整参数）+ 分账设置扩展联动 - status: completed - - id: p2-split - content: 插件内延时分账 + SplitCalculator 规则表驱动(rate/money) + 后台 split_timing 三选一（支付成功/确认收货/订单完成） - status: completed - - id: p3-refund - content: 插件内退款/关单/确认退款，卸载保护策略，commission 防重复入账 - status: completed - - id: p4-test - content: 安装/禁用/卸载回归 + 沙箱全链路 + go-live-checklist - status: completed -isProject: false ---- - -# 汇付小程序微信支付 + 延时分账对接方案 - -> 本方案已按 `$huifu-pay-integration`（hfps/1.3.5）复核产品线、接口合同与存量接入口径。 - -## 零、Skill 产品线判断与方案卡 - -### 0.1 维度判定 - -| 维度 | 判定 | -|------|------| -| **产品线** | **聚合支付**（非托管支付、非 checkout-js） | -| **接入阶段** | 存量系统首次接入汇付（Shopro 已有 Yansongda 直连微信 + 分账模块） | -| **技术栈** | PHP / FastAdmin + Shopro，`huifurepo/dg-php-sdk ^2.0.30` | -| **端形态** | 微信小程序 `T_MINIAPP`，服务端下单 + 前端 `uni.requestPayment` | -| **分账模式** | **延时分账**：下单 `delay_acct_flag=Y`，确认时调「交易确认」传 `acct_split_bunch` | -| **通道策略** | 并行：小程序后台可切换 yansongda / huifu，其余端保留直连 | - -### 0.2 推荐方案与排除项 - -**推荐：聚合支付 + 存量增量适配层** - -- 小程序标准服务端收款，接入轻量，与现有 `Pay.php → PayService → paymentProcess` 链路兼容。 -- 延时分账与现有 `split_timing`（confirm/finish）天然匹配，不必在 prepay 前预估佣金。 - -**暂不推荐：** - -| 方案 | 原因 | -|------|------| -| 托管支付 | 需 `project_id` 和托管收银台闭环，你的场景是自有小程序 + 自有 prepay API | -| checkout-js | 依赖托管预下单 + 前端组件，与 uni-app 现有 `uni.requestPayment` 重复 | -| V2 `/v2/trade/payment/jspay` | 你提供的文档链接属旧版；Skill 基线优先 **V4 `v4/trade/payment/create`** + `TradePaymentCreateRequest`，能力等价且 SDK 主链路已对齐 | - -### 0.3 本轮 Skill References - -1. `copilot-solution-selection.md` — 产品线选择 -2. `copilot-existing-system.md` — 存量改造口径 -3. `aggregation-order.md` + `aggregation-php-adapter.md` — V4 下单与 PHP SDK -4. `aggregation-payload-construction.md` — `method_expand` / `acct_split_bunch` 建模 -5. `shared-async-notify.md` — 异步通知验签、幂等、ACK 格式 - -### 0.4 组件职责（新增 / 保留 / 人工确认） - -| 类别 | 内容 | -|------|------| -| **建议新增** | `HuifuConfig`、`HuifuPaymentAdapter`（V4 create）、`HuifuNotifyHandler`、`HuifuQueryService`（查单补偿）、`HuifuSplitService`（交易确认）、`HuifuRefundService` | -| **建议保留** | `Pay.php::prepay` 入口、订单号生成、`OrderOper::paymentProcess`、佣金/区域代理钩子、小程序 `uni.requestPayment` | -| **人工确认后再改** | 订单 `pay_type` 映射、支付成功后的发货/权益动作、灰度路由、退款后库存/账务 | -| **建议落库字段** | `req_seq_id`、`req_date`、`hf_seq_id`、`trans_stat`、`delay_acct_flag`、`confirm_hf_seq_id`、退款请求流水 | -| **进件（独立 Skill）** | 主商户/子商户开户、分账权限、延时权限、AppID 绑定 → 使用 `$huifu-merchant-onboarding`，不在支付 Skill 内实现 | - -### 0.6 凭证查看与绑定位置（操作指引） - -#### 主 `huifu_id` / `sys_id` / `product_id` 在哪里看 - -| 标识 | 含义 | 查看位置 | -|------|------|----------| -| **主 `huifu_id`** | 交易商户号，写入 `data.huifu_id` | **商户控台** 或 **合作伙伴控台** → 商户管理 / 商户详情（进件完成后可见，通常 16 位数字如 `6666000...`） | -| **`sys_id`** | API 调用方系统号 | 直连商户：`sys_id` = 自己的 `huifu_id`；渠道商：`sys_id` = 渠道商 `huifu_id`。在控台「开发参数 / 接入信息 / API 密钥」区域查看 | -| **`product_id`** | 汇付分配的产品号 | 控台「开发参数 / 接入信息」或商务开通材料中（如 `MCS`） | -| **RSA 密钥对** | 请求签名 + 响应验签 | 控台「开发参数 / API 密钥管理」下载或配置；**不能**从前端或日志暴露 | - -入口：[斗拱开放平台](https://paas.huifu.com/open/home/index.html) → 登录对应控台（商户控台 / 合作伙伴控台）。 - -> 商户进件、详情查询、申请状态 → 使用 `$huifu-merchant-onboarding` Skill 或联系汇付商务，不在支付 Skill 范围内。 - -#### 微信小程序 AppID（`sub_appid`）在哪里绑定 - -`sub_appid` **不是在微信公众平台上绑到汇付**，而是在 **汇付控台 / 接口** 完成「微信业务开通 + 应用配置」： - -1. 登录 **合作伙伴控台**（渠道商代操作）或 **商户控台**（直连商户自助） -2. 进入目标商户 → **业务开通 / 业务变更** → 开通 **微信支付** -3. 在 **微信配置 / 微信商户配置** 中填写小程序 AppID（即 `sub_appid`） -4. 也可通过 API：**【微信商户配置】** 或 **【微信支付宝入驻信息修改】** 接口修改（见 `aggregation-faq.md`） - -绑定完成后，该 AppID 与商户 `huifu_id` 建立关联。常见报错 `sub_mch_id与sub_appid不匹配` 即此步未完成或 AppID 填错（注意首尾空格）。 - -你的项目对应值：Shopro 后台 [`shopro_config.wxMiniProgram`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\config\platform.html) 中的 `app_id`，需与汇付控台绑定的 `sub_appid` **完全一致**。 - -#### `sub_openid` 授权链路（不在汇付控台绑定） - -`sub_openid` 是**运行时参数**，来自微信侧用户授权，**汇付控台没有「绑定 openid」的操作**。 - -```mermaid -sequenceDiagram - participant MP as 小程序 - participant WX as 微信服务器 - participant Shopro as Shopro后端 - participant HF as 汇付下单 - - MP->>WX: wx.login() 获取 code - MP->>Shopro: getWxMiniProgramSessionKey(code) - Shopro->>WX: code2session - WX-->>Shopro: openid + session_key - Shopro-->>MP: 存 openid 到 UserOauth - MP->>Shopro: pay/prepay(openid) - Shopro->>HF: method_expand.sub_appid + sub_openid -``` - -**Skill 硬约束：** -- `sub_openid` 必须来自**同一个** `sub_appid` 下的微信登录，不能跨小程序/公众号复用 -- 你的项目已有链路：`getWxMiniProgramSessionKey` → `UserOauth.openid` → `Pay.php::prepay` 读取 -- 汇付下单时：`sub_appid` = 小程序 AppID，`sub_openid` = 该 AppID 下用户的 openid - -**自检清单：** -1. 汇付控台 `sub_appid` = Shopro 小程序 AppID -2. 用户已微信登录，`UserOauth` 表有对应 openid -3. prepay 传的 openid 与 `sub_appid` 匹配（同一小程序） - -### 0.5 请求 / 通知 / 终态 / 安全边界 - -- **请求**：保留 Controller 传入的 `req_date`、`req_seq_id`、金额、商户号；PHP 加载 SDK 前固定 `DEBUG=false`，禁用官方 Demo loader。 -- **前端交接**：同步返回 `pay_info` 仅用于唤起支付，**不是支付终态**；结果页轮询可保留，但终态以服务端为准。 -- **通知**：`notify_url` 验签 → 校验金额/商户号/流水 → 幂等更新 → 回包 `RECV_ORD_ID_{req_seq_id}` + HTTP 200。 -- **终态补偿**：通知缺失时调聚合查单（`TradePaymentScanpayQueryRequest`），`trans_stat=S` 才可标记已支付。 -- **延时分账终态**：交易确认成功后，`acct_stat=S` 才标记分账完成；可用 `v2/trade/trans/split/query` 复核。 -- **退款**：未确认部分走交易退款；已确认部分走交易确认退款（`loan_flag` 规则见 Skill FAQ）。 - ---- - -## 一、现状与目标 - -**当前架构** - -```mermaid -flowchart LR - MP[小程序] -->|POST pay/prepay| PayCtrl[Pay.php] - PayCtrl --> PaySvc[PayService] - PaySvc --> YSD[Yansongda 直连微信] - YSD -->|pay_data| MP - YSD -->|notify| PayCtrl - PayCtrl --> OrderProc[paymentProcess] - OrderProc --> SplitHook[SplitHook] - SplitHook --> WXSplit[ProfitSharingService 微信分账] -``` - -- 后端入口：[`addons/shopro/controller/Pay.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\Pay.php) 的 `prepay` / `notifyx` -- 支付封装：[`addons/shopro/library/PayService.php`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\PayService.php) -- 小程序端：[`xgsc.gynhc.com_wx/shopro/pay/index.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro\pay\index.js) 将 `pay_data` 传给 `uni.requestPayment`，**无需改接口形态** -- 已有分账模块（默认关闭）：[`SplitCalculator`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitCalculator.php) + [`SplitExecutor`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitExecutor.php)（微信 openid/商户号分账） - -**目标架构（并行通道 + 延时分账）** - -```mermaid -sequenceDiagram - participant MP as 小程序 - participant Pay as Pay.php - participant Router as PaymentRouter - participant HF as HuifuPayService - participant HFAPI as 汇付斗拱API - participant Order as paymentProcess - participant Split as HuifuSplitExecutor - - MP->>Pay: prepay(payment=wechat) - Pay->>Router: 读配置 miniprogram_channel - alt channel=huifu - Router->>HF: V4 create T_MINIAPP - Note over HF,HFAPI: delay_acct_flag=Y - HF->>HFAPI: POST v4/trade/payment/create - HFAPI-->>MP: pay_info → pay_data - else channel=yansongda - Router->>Pay: 现有 PayService - end - MP->>MP: uni.requestPayment - HFAPI->>Pay: 异步通知 notifyHuifu - Pay->>Order: paymentProcess - Note over Order: 佣金/区域代理计算(现有钩子) - Order->>Split: 读 split_timing 配置 - alt split_timing=payed - Split->>HFAPI: 支付成功即交易确认 + acct_split_bunch - else split_timing=confirm - Split->>HFAPI: 确认收货后交易确认 + acct_split_bunch - else split_timing=finish - Split->>HFAPI: 订单完成后交易确认 + acct_split_bunch - end -``` - -参考文档：[聚合支付 V4 下单](https://paas.huifu.com/open/doc/api/#/smzf/api_jhzs?id=miniwx)（旧版 jspay 等价迁移至 V4 create）、[分账串说明](https://spin.cloudpnr.com/topds/appendix/acctSplitBunch.html)、[延时分账说明](https://www.explinks.com/api/scd2024012252731a672326) - ---- - -## 二、汇付与现有微信分账的核心差异 - -| 维度 | 现有（Yansongda 直连） | 汇付斗拱 | -|------|------------------------|----------| -| 分账标识 | 微信 `openid` / `mch_id` | 汇付 `huifu_id`（子商户号） | -| 分账时机 | 支付后调微信 profitsharing API | **延时分账**：支付时 `delay_acct_flag=Y`，确认时调「交易确认」传 `acct_split_bunch` | -| 分账金额规则 | 各接收方之和 ≤ 订单 30% | **各分账方 `div_amt` 之和 = 交易金额 `trans_amt`**（主商户也要在分账串里拿留存部分） | -| 接收方前置 | 微信添加分账接收方 | 汇付侧需「用户开户 + 业务入驻」拿到 `huifu_id` | -| 小程序参数 | Yansongda 封装 | `trade_type=T_MINIAPP`，`method_expand` 内直接传 `sub_appid` + `sub_openid`（不用 `wx_data`，不用 `T_MINIAPP` 包装 key） | - -**延时分账优势（符合你的选择）**：与现有 `split_timing`（payed/confirm/finish）一致，可在佣金、区域代理奖励计算完成后再发起分账，不必在 `prepay` 前预估金额。 - ---- - -## 三、商务/资质前置条件（必须先确认） - -对接开发前，需向汇付商务/运营确认并开通： - -1. **主商户进件**（`$huifu-merchant-onboarding`）：取得主 `huifu_id`、`sys_id`、`product_id`、RSA 密钥对 -2. **微信小程序绑定**：在汇付控台绑定小程序 AppID（对应 [`shopro_config.wxMiniProgram`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\config\platform.html) 中的 app_id）；`sub_openid` 必须来自该 `sub_appid` 的授权链路 -3. **分账权限**（进件 Skill）：`rule_origin=01`（接口发起），`div_flag=Y`，配置 `apply_ratio` -4. **延时分账权限**（进件 Skill）：开通延迟交易；未开通前**不要默认传** `delay_acct_flag=Y` -5. **分账接收方开户**（进件 Skill）：推广员/区域代理需获得各自 `huifu_id`，后台绑定到 `shopro_split_receiver` -6. **测试环境**：沙箱与生产密钥/商户号分离；本地沙箱仅验证协议闭环，不证明真实通道/资金结果 - ---- - -## 四、后端实现方案 - -### 4.1 引入 SDK 与基础封装（位于插件 `addons/shopro_huifu/`） - -> 以下代码**全部在插件内**，不在 Shopro 核心目录。 - -- 通过 Composer 引入官方 SDK：`huifurepo/dg-php-sdk ^2.0.30` -- SDK 主链路：`BsPaySdk\core\Payment::create()` + `TradePaymentCreateRequest`（V4） -- **禁止**使用官方 `BsPayDemo/loader.php` 或会定义 `DEBUG=true` 的 Composer 入口；加载任何 SDK 文件前固定 `DEBUG=false` -- 新建目录 `addons/shopro/library/huifu/`： - -| 文件 | 职责 | -|------|------| -| `HuifuClient.php` | 读取配置、初始化 Payment/BsPayClient、统一验签 | -| `HuifuPayService.php` | V4 下单 create、查单、关单 | -| `HuifuSplitService.php` | 延迟交易确认（分账）、`v2/trade/trans/split/query` | -| `HuifuRefundService.php` | 交易退款、交易确认退款 | -| `HuifuNotifyHandler.php` | 解析 `resp_data`、验签、幂等、ACK 回包 | - -**V4 create 关键参数（小程序 T_MINIAPP）**： - -```php -// TradePaymentCreateRequest 核心字段 -$request->setReqDate(date('Ymd')); -$request->setReqSeqId($order_sn); // 当天唯一，保留 prepay 传入值不重写 -$request->setHuifuId($config['huifu_id']); -$request->setTransAmt(number_format($total_fee, 2, '.', '')); // 元，两位小数 -$request->setGoodsDesc('商城订单支付'); -$request->setTradeType('T_MINIAPP'); -$request->setNotifyUrl($notify_url); -// 仅 split_enable=1 且 delay_acct_enable=1 且商户已开通延时权限时： -$request->setDelayAcctFlag('Y'); -// 可选扩展（后台可配，空则不传）：time_expire、pay_scene、channel_no、fee_sign -// method_expand 是 JSON 对象，直接放 sub_appid/sub_openid，不要包 T_MINIAPP 层 -$request->setMethodExpand(json_encode([ - 'sub_appid' => $miniProgramAppId, - 'sub_openid' => $openid, -], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)); -// 延时分账：支付阶段不传 acct_split_bunch -// Payment::create($request) -``` - -**返回处理**：解析响应 `pay_info`（JSON 字符串）→ 转为小程序 `pay_data`（`timeStamp/nonceStr/package/signType/paySign`），保持与现有 [`Pay.php` prepay 返回格式](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\Pay.php) 一致。 - -### 4.2 支付通道路由（插件 Hook + 后台可切换） - -配置存储在插件表 `shopro_huifu_config`（或 `shopro_config` 插件写入隔离 key）： - -```json -{ - "miniprogram": "huifu", // yansongda | huifu - "split_provider": "huifu" // wechat | huifu（与 split_enable 联动） -} -``` - -修改 [`Pay.php::prepay`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\Pay.php) 增加 Hook 桥接（见 13.4）；插件 `PayCreateHook` 内判断： - -```php -if ($platform === 'wxMiniProgram' && Bridge::getChannel() === 'huifu') { - return (new HuifuPayService())->miniAppPay($order_data); -} -// 返回 null 则核心继续走 PayService -``` - -- 小程序端仍传 `payment=wechat`，**前端零改动** -- 订单 `pay_type` 记为 `huifu_wechat`（便于分账/退款路由） -- 移除汇付路径下对 `settle_info.profit_sharing` 的设置（那是微信直连专用） - -### 4.3 异步通知（插件独立 Controller） - -插件 [`addons/shopro_huifu/controller/Pay.php`](addons/shopro_huifu/controller/Pay.php)： - -``` -/addons/shopro_huifu/pay/notify/platform/wxMiniProgram -/addons/shopro_huifu/pay/notifyRefund/platform/wxMiniProgram -``` - -处理逻辑（按 `shared-async-notify.md`）： -1. 从回调体取 `resp_data`，RSA 验签 -2. 校验 `huifu_id`、金额、`req_seq_id` 与本地订单一致 -3. `trans_stat=S` 才进入支付成功候选；`P` 保持支付中并触发查单补偿 -4. 幂等：已支付订单直接回包，不重复 `paymentProcess` -5. 组装 notify → 调用 `$order->paymentProcess($order, $notify)` -6. 保存 `hf_seq_id`、`req_date`、`req_seq_id` -7. **ACK 回包**：HTTP 200 + 响应体 `RECV_ORD_ID_{req_seq_id}`（不是普通 JSON success） - -### 4.4 延时分账执行（插件 listener + 核心 SplitCalculator） - -#### 4.4.1 分账时机：后台三选一（客户可配置） - -现有 Shopro 分账设置页 [`shopro/split/config`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\split\config\index.html) 已有 `split_timing` 下拉，**汇付插件完全复用**，无需新建配置项。运营可在后台自由选择： - -| 后台选项 | 值 | 触发 Hook | 业务含义 | 适用场景 | -|----------|-----|-----------|----------|----------| -| **支付成功** | `payed` | `order_payed_after` | 用户支付成功后**立即**发起汇付「交易确认」分账 | 需求图「支付成功后自动分账」；资金快速到账 | -| **确认收货** | `confirm` | `order_confirm_after` | 用户确认收货后才发起交易确认 | 降低退货/纠纷风险；佣金已结算 | -| **订单完成** | `finish` | `order_finish` | 订单完结（含售后窗口）后再分账 | 更长风控周期 | - -**执行链路（与现有微信分账一致）**： - -```mermaid -flowchart TD - Config[后台 split_timing] --> Hook{匹配事件?} - Payed[order_payed_after] --> Hook - Confirm[order_confirm_after] --> Hook - Finish[order_finish] --> Hook - Hook -->|是| Executor[SplitExecutor.executeByOrderId] - Executor --> Bridge{shopro_split_execute Hook} - Bridge -->|pay_type=huifu_wechat| HuifuSplit[插件 HuifuSplitService.confirm] - Bridge -->|否则| WxSplit[现有微信分账] -``` - -核心 [`SplitHook`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\split\SplitHook.php) 已按 `split_timing` 过滤事件；插件 `SplitHook` 同样注册三个 Hook，**仅当 `split_provider=huifu` 且订单 `pay_type=huifu_wechat` 时**接管汇付「交易确认」。 - -**汇付延时分账说明**：无论选哪种时机，支付阶段均只传 `delay_acct_flag=Y`（资金冻结）；真正分配在对应 Hook 触发时调「交易确认」。对终端用户而言，`payed` 模式仍是「付完即分」，`confirm`/`finish` 则是「确认后再分」。 - -**后台 UI 增强（实施时）**： -- 保留三选项，增加每项下方说明文案（见上表） -- 切换 `split_timing` 时提示：在途订单仍按**下单/支付时**的配置快照执行（见 4.4.2） -- 汇付模式下隐藏/禁用与微信 openid 相关的平台接收方字段，改为 `platform_huifu_id` - -#### 4.4.2 配置快照（防切换影响在途订单） - -`shopro_split_order` 或订单扩展字段保存 **`split_timing_at_pay`**（支付成功时读取的配置值）。Hook 触发分账时优先读快照，避免运营中途改配置导致同一批次订单行为不一致。 - -插件 `SplitHook` 注册到 `order_payed_after` / `order_confirm_after` / `order_finish` / `order_refund_after`；或通过核心 `shopro_split_execute` Hook 被 `SplitExecutor` 调用。 - -**Huifu 分支（替换 ProfitSharingService 调用）**： - -1. [`SplitCalculator`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitCalculator.php) 计算出各角色金额（推广员、区域代理） -2. **构建汇付分账串**（关键差异）： - -```json -{ - "acct_infos": [ - {"huifu_id": "6666000104218017", "div_amt": "5.00"}, - {"huifu_id": "6666000104218018", "div_amt": "3.00"}, - {"huifu_id": "6666000104218019", "div_amt": "92.00"} - ] -} -``` - -- 每个 `div_amt` 保留两位小数 -- **总和必须等于 `trans_amt`** -- 最后一项 = 主商户留存（订单实付 - 各分账方之和） -- 手续费承担方由汇付返回的 `fee_huifu_id` 决定 - -3. 调用「交易确认接口」传入 `acct_split_bunch` -4. 写入现有 `shopro_split_order` / `shopro_split_order_receiver` 表，增加 `channel=huifu` 字段 -5. 失败重试：复用现有 [`SplitRetryJob`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitRetryJob.php) / `shopro:split-retry` - -**SplitCalculator 适配**： -- `getReceiver()` 优先读 `receiver_account` 作为 `huifu_id`（新增 `receiver_type=HUIFU_ID`） -- 不再自动从 OAuth 创建 openid 接收方（汇付必须事先开户） -- 保留 `split_max_rate` 校验 - -### 4.5 退款 - -[`OrderOper::refund()`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\traits\model\order\OrderOper.php) 分支： - -| 场景 | 接口 | -|------|------| -| 未做交易确认（延时分账未确认） | 汇付「交易退款接口」 | -| 已确认分账 | 「交易确认退款接口」+ 可能需分账回退 | - -[`SplitHook::orderRefundAfter`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\split\SplitHook.php) 增加 Huifu 退款联动。 - -### 4.6 与内部佣金系统的关系 - -[`shopro_split_config.split_mode`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_payment_split.sql) 扩展： - -| split_mode | 行为 | -|------------|------| -| `wallet` | 仅内部钱包佣金（现状） | -| `wechat` | 仅微信直连分账 | -| `huifu` | 仅汇付延时分账 | -| `both` | 不建议，易重复发放 | - -当 `split_mode=huifu` 且汇付分账成功时，[`CommissionHook`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\listener\commission\CommissionHook.php) 应标记奖励为「已网关分账」，**跳过钱包入账**（与现有 `shouldSkipWallet()` 逻辑一致）。 - ---- - -## 五、数据库与后台配置 - -### 5.1 SQL 变更（`upgrade_huifu_payment.sql`） - -- `shopro_config` 插入 `huifu`、`payment_channel` 配置行 -- `shopro_split_receiver` 增加 `huifu_id` 字段（或复用 `receiver_account` 存 huifu_id，增加 `channel` 字段区分 wechat/huifu） -- `shopro_split_order` 增加 `channel`、`hf_req_seq_id`、`confirm_status` -- `shopro_order` 的 `pay_type` 枚举支持 `huifu_wechat` - -### 5.2 后台管理界面（概览） - -新增两个后台模块（含菜单 SQL）： - -| 模块 | 路径 | 职责 | -|------|------|------| -| **汇付支付配置** | `shopro/huifu/config` | 密钥、通道、下单/通知/退款参数 | -| **分账设置（扩展）** | 现有 `shopro/split/config` | 增加汇付分账模式与延时分账开关 | -| **分账接收方（扩展）** | 现有 `shopro/split/receiver` | 增加 `channel=huifu`、`huifu_id`、`acct_id` | -| **分账记录（扩展）** | 现有 `shopro/split/order` | 增加手动重试确认、分账明细查询 | - -### 5.3 后台可配置参数清单（Skill 复核后完整版） - -#### A. 汇付支付配置页 `shopro_config.name = huifu` - -| 配置键 | 类型 | 必填 | 用途 | Skill 来源 | -|--------|------|------|------|-----------| -| `env` | test/prod | Y | 切换网关域名 | shared-local-sandbox / 上线检查 | -| `gateway_url` | string | Y | 测试/生产 API 地址 | 随 env 自动填充，可手动覆盖 | -| `sys_id` | string | Y | 公共请求参数 | aggregation-common-params | -| `product_id` | string | Y | 产品号 | aggregation-common-params | -| `huifu_id` | string | Y | 交易商户号 `data.huifu_id` | aggregation-common-params | -| `upper_huifu_id` | string | N | 渠道商场景上级商户号 | payment-operations-faq | -| `merchant_private_key` | text/file | Y | 请求 RSA 私钥（服务端存储，脱敏展示） | shared-credential-boundary | -| `huifu_public_key` | text/file | Y | 响应/通知验签公钥 | shared-signing-v2 | -| `skill_source` | string | N | SDK 请求头，默认 `hfps/1.3.5` | shared-request-header-policy | -| `miniprogram_channel` | yansongda/huifu | Y | 小程序支付通道路由 | 方案决策 | -| `notify_url` | string | 只读 | 支付异步通知（自动生成展示） | shared-async-notify | -| `refund_notify_url` | string | N | 退款异步通知 | aggregation-customer-preparation | -| `time_expire` | int(分钟) | N | 交易超时，不传则微信默认 | aggregation-order-request | -| `pay_scene` | string | N | 微信业务场景类型（如 `02`） | payment-complete-field-catalog | -| `channel_no` | string | N | 指定渠道号；**空则不传**（禁止传空字符串） | payment-operations-faq | -| `fee_sign` | string | N | 手续费场景标识 | payment-complete-field-catalog | -| `goods_desc_tpl` | string | N | 商品描述模板，如 `商城订单{order_sn}` | aggregation-faq | -| `limit_pay_type` | string | N | 禁用支付方式（如 `NO_CREDIT`） | aggregation-faq | -| `status` | 0/1 | Y | 汇付通道总开关 | 存量灰度 | - -**安全约束（后台保存时校验）：** -- 生产环境禁止开启 SDK DEBUG -- 私钥/公钥仅管理员可见，列表页脱敏 -- `notify_url` 必须 HTTPS、无 query 参数（Skill：`shared-async-notify.md`） - -#### B. 分账设置页扩展 `shopro_split_config`（现有页补字段） - -现有 [`shopro/split/config/index.html`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\split\config\index.html) 需扩展： - -| 配置键 | 类型 | 默认 | 说明 | -|--------|------|------|------| -| `split_mode` | select | wallet | 增加 **`仅汇付分账(huifu)`** 选项；`both` 仍不建议 | -| `split_provider` | wechat/huifu/auto | auto | auto=跟随 `miniprogram_channel` | -| `delay_acct_enable` | 0/1 | 0 | 延时分账开关；仅 `split_provider=huifu` 且商户已开通时可开 | -| `platform_huifu_id` | string | — | 平台留存方汇付商户号（主商户 huifu_id） | -| `platform_acct_id` | string | N | 平台分账子账户（基本户/现金户，可选） | -| `term_div_coupon_type` | 1/2/3 | 3 | 遇优惠时分账规则：1按比例 2按顺序 3只给交易商户 | -| `split_retry_max` | int | 5 | 已有，保留 | -| `split_retry_interval` | int | 300 | 已有，保留 | -| `split_max_rate` | decimal | 30 | 已有；汇付侧还需 ≤ 控台 `apply_ratio` | -| `split_timing` | payed/confirm/finish | payed | **已有，运营三选一**：支付成功 / 确认收货 / 订单完成；汇付与微信分账共用；见 4.4.1 | - -**联动规则（后台保存校验）：** -- `split_mode=huifu` 时 `split_enable` 必须=1 -- `delay_acct_enable=1` 要求 `split_provider=huifu` 且汇付商户已开通延时权限 -- `split_mode=huifu` 时禁用微信 openid 自动创建接收方 - -#### C. 分账接收方页扩展 `shopro_split_receiver` - -| 字段 | 说明 | -|------|------| -| `channel` | wechat / huifu | -| `receiver_type` | 微信：`PERSONAL_OPENID`/`MERCHANT_ID`；汇付：`HUIFU_ID` | -| `receiver_account` | 微信 openid/商户号 或 汇付 huifu_id | -| `acct_id` | 汇付分账子账户（可选，基本户/现金户） | -| `role_type` | promoter / regional_agent / platform / supplier | -| `status` | normal / hidden | - -#### D. 只读展示项（帮助运营填汇付控台） - -后台「汇付支付配置」页底部只读展示： -- 支付通知 URL：`/addons/shopro/pay/notifyHuifu/platform/wxMiniProgram` -- 退款通知 URL：`/addons/shopro/pay/notifyHuifuRefund/platform/wxMiniProgram`（若独立） -- 当前小程序 AppID（读取 `shopro_config.wxMiniProgram.app_id`，提示需与汇付控台 sub_appid 一致） - ---- - -## 十一、Skill 复核遗漏项（本次补充） - -> 对照 `$huifu-pay-integration` 的 `copilot-go-live-checklist.md`、`aggregation-payload-construction.md`、`payment-operations-faq.md`、`trade-split-detail-query.md` 复核。 - -### 11.1 支付链路遗漏（需补进方案） - -| 遗漏项 | 严重度 | 补充方案 | -|--------|--------|----------| -| **查单补偿任务** | 高 | 新增 `HuifuQueryService` + 定时任务：对 `trans_stat=P` 或 notify 缺失的订单主动查单（`TradePaymentScanpayQueryRequest`） | -| **notify 幂等事件表** | 高 | 新增 `shopro_huifu_notify_log`（`huifu_id+req_seq_id+event_type` 唯一键），防重复发货 | -| **`req_date` 落库** | 高 | prepay 时保存 `req_date`，查单/退款/关单/确认分账必须复用，不能事后重写 | -| **关单接口** | 中 | 超时未支付订单调聚合关单（`TradePaymentScanpayCloseRequest`），与现有订单超时逻辑联动 | -| **`refund_notify_url`** | 中 | 退款异步通知独立 endpoint + 验签 + 幂等 | -| **`time_expire`** | 低 | 后台可配，避免订单长期挂起 | -| **`pay_scene` / `channel_no`** | 低 | 多渠道/多微信商户号场景后台可配；`channel_no` 空则不传 | -| **`fee_sign`** | 低 | 多费率场景后台可配 | -| **PHP SDK 初始化** | 高 | `MerConfig.skill_source`、显式 require `init.php`（包无 autoload）、`DEBUG=false` 硬约束 | -| **订单扩展表** | 高 | `shopro_order_pay_ext` 或在 order 增 JSON：`hf_seq_id`、`req_date`、`req_seq_id`、`trans_stat`、`confirm_hf_seq_id` | -| **组合支付 group** | 中 | MVP 暂不支持汇付+余额组合，后台开关拦截并提示 | -| **充值订单 TO*** | 中 | MVP 仅商品订单；充值二期适配 | -| **对账** | 低 | 二期：`V2TradeCheckFilequeryRequest` 对账文件下载 | - -### 11.2 分账链路遗漏（需补进方案） - -| 遗漏项 | 严重度 | 补充方案 | -|--------|--------|----------| -| **`delay_acct_flag` 条件化** | 高 | 不应无条件 `Y`：仅当 `split_enable=1` 且 `delay_acct_enable=1` 且商户已开通延时权限时才传 | -| **交易确认 API 封装** | 高 | `HuifuSplitService::confirm()` 需保存返回 `confirm_hf_seq_id`，供退款/查询用 | -| **分账明细查询** | 中 | 确认后调 `v2/trade/trans/split/query` 复核 `acct_stat=S` | -| **分账串 `acct_id`** | 低 | 接收方可选指定基本户/现金户，后台可配 | -| **`term_div_coupon_type`** | 中 | 有优惠券/满减时影响分账，后台可配（默认 3=只给交易商户） | -| **主商户留存计算** | 高 | `div_amt` 总和必须=订单实付；平台留存 = 实付 - 各分账方之和，用 `bcmul/bcadd` | -| **分账仅汇付订单** | 高 | `SplitExecutor` 仅处理 `pay_type=huifu_wechat` 且 `split_provider=huifu` | -| **后台手动重试** | 中 | `shopro/split/order` 增加「重试交易确认」按钮（已有微信重试，需加 huifu 分支） | -| **分账失败告警** | 低 | 复用 `shopro:split-retry`，超次数写日志/通知运营 | -| **延时分账退款分支** | 高 | 未确认→交易退款；已确认→交易确认退款（`loan_flag` 规则，`payment-operations-faq`） | - -### 11.3 后台配置遗漏（用户明确要求） - -原方案 5.2 仅列 5 项，**不足以支撑运营自助配置**。已扩展为 **5.3 完整参数清单**（支付 17 项 + 分账 9 项 + 接收方 6 字段）。 - -还需补充： -- 新建 **`shopro/huifu/config`** 独立菜单（不与 platform.html 混放，避免配置项过多） -- 扩展现有 **分账设置** 下拉增加 `huifu` 模式 -- 扩展 **分账接收方** 支持 `channel` + `huifu_id` -- 配置保存时做 **联动校验**（见 5.3 B 节） - -### 11.4 测试清单补充（对照 go-live-checklist） - -在原第八章基础上增加： - -9. **查单补偿**：notify 不到达时，定时任务能补单成功 -10. **重复 notify**：不重复 `paymentProcess`、不重复发货 -11. **关单**：超时订单正确关单 -12. **退款 notify**：退款终态闭环 -13. **参数缺失拦截**：无 openid / 无 huifu_id / 未开通延时不传 delay_acct_flag -14. **后台配置生效**：改 channel_no/pay_scene/time_expire 后请求参数正确 -15. **灰度切换**：汇付↔直连切换不影响在途订单 - -### 11.5 MVP 边界调整建议 - -| 范围 | MVP（一期） | 二期 | -|------|------------|------| -| 支付 | 小程序商品单 + V4 create + notify + 查单补偿 | 充值单、组合支付 | -| 分账 | 延时分账 + 交易确认 + 明细查询 + 后台配置 | 百分比分账、净值分账 | -| 退款 | 未确认/已确认两种路径 | 垫资退款 | -| 运营 | 完整后台配置页 + 分账记录重试 | 对账报表、批量开户 | - ---- - -## 六、小程序端 - -**基本无需改动**。现有流程： - -```javascript -// shopro/pay/index.js - wxMiniProgramPay -uni.requestPayment({ provider: 'wxpay', ...result.data.pay_data }) -``` - -仅需确认汇付返回的 `pay_info` 字段名与微信一致（`timeStamp` 大小写兼容处理）。 - -可选：支付结果页 [`result.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\order\payment\result.vue) 展示 `pay_type=huifu_wechat` 时文案为「微信支付（汇付）」。 - ---- - -## 七、实施阶段与工时估算 - -| 阶段 | 内容 | 预估 | -|------|------|------| -| P0 资质 | 汇付开户、分账/延时权限、子商户 huifu_id | 商务周期（1~2 周） | -| P1 基础支付 | SDK 接入、HuifuPayService、V4 create、notify+查单补偿、后台配置 | 2~3 天 | -| P2 延时分账 | HuifuSplitService、SplitExecutor 分支、分账串构建、确认接口 | 2~3 天 | -| P3 退款/查询 | 退款、交易查询、关单、分账明细查询 | 1~2 天 | -| P4 联调 | 沙箱支付 → 确认收货分账 → 退款全链路 | 2~3 天 | -| P5 上线 | 生产密钥、控台配置、灰度切换 miniprogram_channel | 1 天 | - -**合计开发约 8~12 人天**（不含商务进件与子商户开户）。 - ---- - -## 八、测试清单 - -1. **支付**：0.01 元小程序下单 → 唤起支付 → 异步通知 → 订单状态变已支付 -2. **通道切换**：后台切回 yansongda，确认直连微信仍正常 -3. **延时分账（两种时机）**： - - `split_timing=payed`：支付成功 → 立即交易确认 → split_order 成功 - - `split_timing=confirm`：支付成功仅冻结；确认收货 → 交易确认 → split_order 成功 - - 切换配置后，在途订单按支付时快照执行 -4. **分账金额**：多分账方 + 主商户留存，总和 = 订单实付 -5. **佣金不重复**：split_mode=huifu 时钱包不入账 -6. **退款**：未确认前退款 / 确认后退款 -7. **幂等**：重复通知、重复分账确认不重复处理 -8. **异常**：分账失败重试、超 max_rate 拦截 - ---- - -## 九、风险与注意事项 - -1. **分账接收方必须是 huifu_id**：推广员/区域代理需提前在汇付开户，不能沿用微信 openid 自动创建逻辑 -2. **金额精度**：汇付用「元」两位小数，现有系统用「元」float，注意 `bcmul/bcadd` 避免精度丢失 -3. **订单号**：`req_seq_id` 需全局唯一；现有 prepay 会 regenerate `order_sn`，需确保与汇付流水一致 -4. **手续费**：分账串返回的 `fee_amt` 可能从某一方扣除，需在构建分账串时预留或按汇付规则处理 -5. **组合支付 group**：余额+微信组合时，仅微信部分走汇付，需单独评估是否支持 -6. **充值订单 TO***：若充值也需走汇付，需同样适配 TradeOrder 流程 - ---- - -## 十、推荐的首批交付范围（MVP） - -1. 小程序商品订单 + 汇付 V4 create + 异步通知 + 查单补偿（不含分账） -2. 后台通道切换（yansongda ↔ huifu） -3. 延时分账 + 交易确认（对接现有 SplitCalculator） -4. 基础退款 - -**二期**：子商户批量开户工具、对账文件、组合支付、充值订单、垫资退款。 - ---- - -## 十二、Skill 复核结论 - -**方案主链路正确**：聚合支付 V4 + 存量适配 + 延时分账 + 并行通道，与 Skill 推荐一致。 - -**主要遗漏已在本节补充**，集中在四类： -1. **支付终态闭环**：查单补偿、notify 幂等表、`req_date` 落库、关单 -2. **分账条件化**：`delay_acct_flag` 不应无条件开启；交易确认/查询/退款三分支 -3. **后台可配置性**：原方案配置项过少，已扩展为 5.3 完整清单（支付+分账+接收方） -4. **MVP 边界**：组合支付、充值单、对账应明确排除在一期外 - -**References 追加**：`copilot-go-live-checklist.md`、`trade-split-detail-query.md`、`aggregation-refund.md`、`payment-operations-faq.md` - ---- - -## 十三、插件化改造方案（$huifu-pay-integration 存量接入口径） - -> Skill 依据：`copilot-existing-system.md`（优先新增适配层、保留原订单/支付/回调链路）、`copilot-solution-selection.md`（存量增量接入）、`copilot-go-live-checklist.md`（卸载/灰度/回滚）。 - -### 13.1 结论：可以做成独立插件 - -**可行**，推荐新建 FastAdmin 插件 **`addons/shopro_huifu`**（依赖 `shopro`，参考现有 [`addons/epay`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\epay\Epay.php) 的独立封装方式）。 - -| 状态 | 系统行为 | -|------|----------| -| **未安装** | 与现在完全一致，仅 Yansongda 直连微信/支付宝 | -| **已安装+启用** | 小程序可按配置走汇付；分账可走汇付延时分账 | -| **已禁用** | 不路由到汇付，历史数据保留，Yansongda 正常 | -| **已卸载** | 移除插件表/菜单/定时任务；Shopro 核心不受影响 | - -**Skill 对齐原则**： -- 汇付逻辑全部在插件内（Adapter / Notify / Query / Refund / Split） -- Shopro 核心只保留 **3 个可选 Hook 桥接点** + `paymentProcess` 不变 -- 不修改订单状态机、发货、佣金计算主流程 - -### 13.2 总体架构 - -```mermaid -flowchart TB - subgraph core [Shopro 核心 最小改动] - PayCtrl[Pay.php prepay] - OrderProc[paymentProcess] - SplitCalc[SplitCalculator 共用] - HookBridge[3 个 Hook 桥接点] - end - - subgraph plugin [addons/shopro_huifu 可卸载] - Bridge[Bridge 入口] - HuifuPay[HuifuPayService] - HuifuNotify[NotifyHandler] - HuifuSplit[HuifuSplitService] - HuifuAdmin[后台配置/菜单] - HuifuDB[(插件私有表)] - SDK[dg-php-sdk] - end - - PayCtrl --> HookBridge - HookBridge -->|插件启用且 channel=huifu| Bridge - HookBridge -->|否则| YSD[现有 PayService Yansongda] - Bridge --> HuifuPay - HuifuPay --> SDK - HuifuNotify --> OrderProc - HuifuSplit --> SplitCalc - HuifuSplit --> HuifuDB -``` - -### 13.3 插件目录结构 - -``` -addons/shopro_huifu/ -├── ShoproHuifu.php # install / uninstall / enable / disable / appInit -├── info.ini -├── config.php # 插件元配置 -├── config/menu.php # 后台菜单 -├── install.sql # 插件表 + 默认配置 -├── uninstall.sql # 可选：DROP 插件表（见 13.6） -├── hooks.php # 注册 Shopro 行为（由 appInit 加载） -├── library/ -│ ├── Bridge.php # class_exists 安全入口、isEnabled() -│ ├── HuifuClient.php -│ ├── HuifuPayService.php -│ ├── HuifuNotifyHandler.php -│ ├── HuifuQueryService.php -│ ├── HuifuRefundService.php -│ ├── HuifuSplitService.php -│ └── sdk/ # 或 composer 依赖隔离在插件 vendor -├── controller/ -│ ├── Pay.php # notifyHuifu / notifyRefund（独立 URL） -│ └── Config.php # 小程序 init 可读通道状态（可选） -├── listener/ -│ ├── PayCreateHook.php # shopro_pay_create -│ ├── RefundHook.php # shopro_pay_refund -│ └── SplitHook.php # order_confirm/finish/refund 汇付分账 -├── model/ # 插件私有 Model -├── command/ -│ ├── CompensateQuery.php # 查单补偿 -│ └── SplitRetry.php # 分账重试 -└── application/admin/ # FastAdmin 后台（随插件安装） - ├── controller/shopro_huifu/ - └── view/shopro_huifu/ -``` - -### 13.4 Shopro 核心「桥接层」改动（极小、可回滚） - -仅在 Shopro 核心增加 **3 处 Hook**，无插件时不执行任何汇付代码： - -| Hook 名 | 注入位置 | 作用 | -|---------|----------|------| -| `shopro_pay_create` | [`Pay.php::prepay`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\controller\Pay.php) 调 PayService 前 | 插件返回 pay_data 则短路；否则走 Yansongda | -| `shopro_pay_refund` | [`OrderOper::refund`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\traits\model\order\OrderOper.php) | 插件处理 `pay_type=huifu_wechat` 退款 | -| `shopro_split_execute` | [`SplitExecutor::executeByOrderId`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitExecutor.php) 开头 | 插件处理汇付分账；返回 true 则跳过微信分账 | - -**桥接代码模式（Skill：不猜、class_exists 防护）**： - -```php -// Pay.php 示例 -if (class_exists('\\addons\\shopro_huifu\\library\\Bridge')) { - $pluginResult = \think\Hook::listen('shopro_pay_create', [ - 'order' => $order, 'order_data' => $order_data, - 'payment' => $payment, 'platform' => $platform, - ], null, true); - if ($pluginResult) { - return $pluginResult; - } -} -// 原有 PayService 逻辑不变 -``` - -**禁止做法**（违反 Skill 存量接入原则）： -- 在 `PayService.php` 内硬编码汇付 SDK 或 `use addons\shopro_huifu\...` -- 在 `shopro/hooks.php` 永久写入汇付 listener（应只在插件 `appInit` 动态注册） -- 卸载插件后仍要求 `composer require huifurepo/dg-php-sdk` 在项目根目录 - -### 13.5 插件生命周期 - -#### install（安装） - -1. 执行 `install.sql`：插件配置表、notify 幂等表、订单支付扩展表（或 ext 表） -2. 注册后台菜单：`shopro_huifu/config`、`shopro_huifu/log` -3. 写入默认配置：`miniprogram_channel=yansongda`（默认不影响现网） -4. 注册 CLI 命令：查单补偿、分账重试 -5. **不修改** Shopro 原有表结构（除可选 ext 外联表） - -#### enable（启用） - -1. `appInit` 注册 `think\Hook` 行为 -2. 加载 SDK（`DEBUG=false` 硬约束） -3. 小程序 init 接口返回当前通道（可选） - -#### disable（禁用） - -1. 停止 Hook 注册（`Bridge::isEnabled()` 返回 false） -2. 自动将 `miniprogram_channel` 置为 `yansongda`（防止禁用后仍路由汇付） -3. **保留**配置、历史订单、分账记录 -4. 定时任务跳过执行 - -#### uninstall（卸载） - -1. **前置检查**（人工确认）：是否存在 `pay_type=huifu_wechat` 且未完结订单/未确认分账/退款中 -2. 删除后台菜单 -3. 执行 `uninstall.sql` 或保留数据策略（见 13.6） -4. 移除 CLI 命令注册 -5. Shopro 核心 3 个 Hook 桥接仍保留但无 listener → **零影响** - -### 13.6 数据隔离与卸载策略 - -| 数据 | 归属 | 卸载策略 | -|------|------|----------| -| 汇付配置/密钥 | 插件表 `shopro_huifu_config` | 卸载时删除（或导出后删除） | -| notify 幂等日志 | 插件表 `shopro_huifu_notify_log` | 可保留 N 天后删 | -| 支付扩展流水 | 插件表 `shopro_huifu_pay_ext` | **建议保留**供财务追溯，卸载不删 | -| 分账记录 | 现有 `shopro_split_order` + `channel=huifu` | **不删**；卸载后仅不可新分账 | -| 订单 `pay_type` | Shopro 订单表 | **不删**；历史 `huifu_wechat` 订单只读 | - -**卸载后历史订单**：不能再发起汇付退款/分账确认（插件已不存在），需人工通过汇付控台处理；安装期间应禁止在有在途汇付订单时卸载。 - -### 13.7 与现有分账模块的关系 - -| 模块 | 归属 | 说明 | -|------|------|------| -| `SplitCalculator` / 佣金规则 | **Shopro 核心** | 继续计算推广员/区域代理金额，插件复用 | -| `shopro_split_config` | **Shopro 核心** | 扩展 `split_mode=huifu`、`delay_acct_enable` 等字段 | -| `SplitExecutor` 微信分支 | **Shopro 核心** | 保持不动 | -| 汇付交易确认 / 分账查询 | **插件** | `HuifuSplitService` + `SplitHook` listener | -| 分账接收方 `huifu_id` | **Shopro 核心表** + 插件校验 | `receiver.channel=huifu` | - -插件 `SplitHook` 仅在 `Bridge::shouldHandleSplit($order)` 时执行，避免与微信分账重复。 - -### 13.8 后台配置归属（插件化后） - -| 配置页 | 位置 | -|--------|------| -| 汇付支付参数（5.3 A 节） | 插件 `shopro_huifu/config` | -| 分账模式/时机/比例（5.3 B 节） | 仍用 Shopro `shopro/split/config`（核心），插件读取 | -| 分账接收方 huifu_id（5.3 C 节） | 仍用 Shopro `shopro/split/receiver` | -| 分账记录/重试 | Shopro `shopro/split/order` + 插件提供 huifu 重试实现 | - -### 13.9 SDK 与 Composer 隔离 - -参考 [`epay`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\epay\Epay.php) 做法，二选一： - -| 方案 | 优点 | 缺点 | -|------|------|------| -| **A. 插件内 vendor** | 卸载即移除依赖 | 需在插件目录 `composer install` | -| **B. 插件内 bundled SDK** | 与 epay 一致，零根目录污染 | 体积较大 | - -Skill 要求：PHP 加载 SDK 前 `DEBUG=false`；`MerConfig.skill_source=hfps/1.3.5`；禁止 Demo loader。 - -### 13.10 卸载/禁用回归清单（必测） - -对照 `copilot-go-live-checklist.md` 存量检查： - -1. 禁用插件后，小程序 prepay 仍走 Yansongda，支付成功 -2. 卸载插件后，Shopro 安装/启用/订单/退款/微信分账均正常 -3. 卸载插件后，访问 `/addons/shopro_huifu/*` 返回 404，不影响 Shopro API -4. 禁用插件后，无汇付定时任务执行 -5. 启用插件后，通道切换 yansongda ↔ huifu 可灰度 -6. 插件启用时，重复 notify 不重复发货（幂等表在插件内） - -### 13.11 实施顺序调整（插件优先） - -| 阶段 | 内容 | 预估 | -|------|------|------| -| P0 | Shopro 3 个 Hook 桥接 + 插件骨架 + install/disable/uninstall | 1~2 天 | -| P1 | 插件内支付（V4 create + notify + 查单补偿 + 后台配置） | 2~3 天 | -| P2 | 插件内延时分账 + 对接 SplitCalculator | 2~3 天 | -| P3 | 插件内退款/关单 + 卸载保护 | 1~2 天 | -| P4 | 安装/禁用/卸载回归 + 沙箱联调 | 2~3 天 | - -**合计约 8~13 人天**（比原方案多 0~1 天插件骨架，但长期维护成本更低）。 - -### 13.12 与原方案章节的关系 - -- **第四节「后端实现」**：代码目标目录从 `addons/shopro/library/huifu/` 改为 **`addons/shopro_huifu/`** -- **第五节「后台配置」**：汇付专属页迁入插件；分账共用页仍在 Shopro -- **第十一节「遗漏项」**：查单补偿、幂等表、关单等均在**插件内**实现 -- **Shopro 核心改动**：仅 3 个 Hook 桥接（约 30 行），可单独 PR 审查 - ---- - -## 十四、需求符合性分析（对照需求图 × $huifu-pay-integration） - -> 需求图五项：**分账接入 / 分账角色管理 / 分账规则配置 / 自动分账 / 分账记录** -> 分析依据：现有 Shopro 分账模块 + 本方案插件化汇付方案 + Skill 延时分账/实时分账能力边界。 - -### 14.1 总览对照表 - -| 需求项 | 符合度 | 现有基础 | 方案覆盖 | 缺口/备注 | -|--------|--------|----------|----------|-----------| -| **1. 分账接入** | ✅ 符合 | 无汇付 | 插件 `shopro_huifu` 对接聚合支付 V4 + 延时分账「交易确认」 | 需汇付控台开通分账+延时权限（进件 Skill） | -| **2. 分账角色管理** | ⚠️ 基本符合 | [`shopro/split/receiver`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\split\receiver\index.html) 已有平台/推广员/区域代理 | 扩展 `channel=huifu`、`huifu_id`、`acct_id` | 需去掉汇付模式下 openid 自动创建；推广员/代理需事先汇付开户拿 `huifu_id` | -| **3. 分账规则配置** | ⚠️ 部分符合 | [`shopro/split/rule`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_payment_split.sql) 支持 `rate`/`money` | 复用规则表 + `SplitCalculator` | 当前计算器**优先读佣金/区域奖励**，规则表对推广员/代理未完全驱动；需增强「按规则表计算」分支 | -| **4. 自动分账** | ✅ 后台可选 | `split_timing` 三选一（已有 UI） | `payed`→支付成功即确认；`confirm`→确认收货后分账 | 两种主场景均支持；选 `payed` 满足需求图「支付成功后自动」；选 `confirm`/`finish` 满足风控需求 | -| **5. 分账记录** | ✅ 基本符合 | [`shopro/split/order`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\split\order\index.html) + 重试命令 | 增加 `channel=huifu`、`confirm_hf_seq_id`、插件内 `v2/trade/trans/split/query` 复核 | 需补汇付失败原因展示、手动重试「交易确认」 | - -**综合结论**：在插件方案落地 + 下列 14.3 补强项完成后，**可满足需求图五项**；第 4 项「自动分账」通过后台 `split_timing` 在「支付成功」与「确认收货」两种模式间切换，客户自行选择。 - -### 14.2 分项说明（Skill 口径） - -#### 1）分账接入 — ✅ 符合 - -- Skill 产品线：**聚合支付** + 分账能力（`acct_split_bunch` / 延时分账「交易确认」） -- 本方案：独立插件对接汇付斗拱，不替换 Shopro 订单与 `paymentProcess` -- 与图意「对接第三方支付公司分账服务商」一致 - -#### 2）分账角色管理 — ⚠️ 基本符合（需扩展） - -| 图中角色 | 系统对应 | 汇付侧要求 | -|----------|----------|------------| -| 平台 | `role_type=platform` + `platform_huifu_id` | 主商户 `huifu_id` 拿留存 | -| 推广员 | `role_type=promoter` + 用户绑定 | 需个人/企业 **汇付开户** 得 `huifu_id` | -| 区域代理 | `role_type=regional_agent` | 同上 | - -现有后台已有接收方 CRUD；插件化后需： -- 接收方类型增加 `HUIFU_ID` -- 列表展示汇付同步状态（替代仅「同步微信」） -- 缺 `huifu_id` 的接收方拦截分账 - -#### 3）分账规则配置 — ⚠️ 部分符合（需增强计算器） - -需求：「按订单金额**比例或固定金额**，设置各角色分账比例」。 - -数据库已支持： - -```sql --- shopro_split_rule -rule_type enum('rate','money') -- 比例 / 固定金额 -role_type enum('platform','promoter','regional_agent') -``` - -**缺口**：[`SplitCalculator`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\library\split\SplitCalculator.php) 当前主要从 `commission_reward` / `regional_agent_reward` 取数，**不是**完全按 `shopro_split_rule` 表驱动。 - -**补强（写入实施）**： -- 增加 `split_amount_source` 配置：`commission`（跟佣金）/ `rule`（纯规则表）/ `mixed`（优先佣金，无则规则） -- 纯规则模式下：`rate` → `pay_fee * rule_value / 100`；`money` → 固定 `rule_value` -- 汇付分账串构建仍遵守 Skill：**各 `div_amt` 之和 = 订单实付** - -#### 4）自动分账 — ✅ 后台可选两种主模式 - -需求原文：**「用户支付成功后自动触发分账，资金直接分配至各方账户」**；同时业务也可能需要 **确认收货后再分账**。 - -**方案：后台 `split_timing` 三选一，客户自行配置**（现有 [`shopro/split/config`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\application\admin\view\shopro\split\config\index.html) 已具备）： - -| 后台选择 | 是否符合「支付成功后自动」 | 是否符合「确认收货后再分账」 | -|----------|--------------------------|------------------------------| -| `split_timing=payed` | ✅ 支付成功 Hook 内立即「交易确认」 | — | -| `split_timing=confirm` | — | ✅ 确认收货 Hook 内「交易确认」 | -| `split_timing=finish` | — | ✅（更保守）订单完结后再分 | - -汇付技术路径统一为 **延时分账**（支付时 `delay_acct_flag=Y`，触发时机由 `split_timing` 决定）。无需两套接口，仅 Hook 触发点不同。 - -**默认建议**：新装默认 `payed`（贴合需求图）；有退货风险的商户可在后台改为 `confirm`，**无需改代码**。 - -#### 5）分账记录 — ✅ 基本符合（需汇付字段） - -现有能力： -- [`shopro_split_order`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\upgrade_payment_split.sql) / `shopro_split_order_receiver` 流水与明细 -- 状态：待分账/分账中/成功/部分成功/失败 -- [`shopro:split-retry`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\chufang.gynhc.com\addons\shopro\command\SplitRetry.php) 失败重试 - -插件补强： -- `channel=huifu`、`hf_seq_id`、`confirm_hf_seq_id`、`acct_stat` -- 调用 Skill 规定的 [`v2/trade/trans/split/query`](https://paas.huifu.com/partners/api/doc/smzf/api_fzmxcx.md) 复核终态（`acct_stat=S` 才标记成功） -- 后台「手动重试交易确认」 - -### 14.3 为完全贴合需求图必须补强的项 - -| 优先级 | 补强项 | 对应需求 | -|--------|--------|----------| -| P0 | 后台 `split_timing` 三选一 UI 说明文案 + 支付时配置快照 `split_timing_at_pay` | 自动分账（两种模式可选） | -| P0 | 接收方管理扩展 `huifu_id` + 开户校验 | 角色管理 | -| P1 | `SplitCalculator` 增加按 `shopro_split_rule`（rate/money）计算分支 | 规则配置 | -| P1 | 分账记录页展示汇付流水、失败原因、手动重试 | 分账记录 | -| P2 | 接收方「汇付开户状态」展示（进件 Skill 对接） | 角色管理 | - -### 14.4 不符合或超出需求图的范围（需知悉） - -| 项 | 说明 | -|----|------| -| 组合支付 `group` | 一期 MVP 不支持，图中未要求但商城可能存在 | -| 充值单 `TO*` | 二期 | -| 对账文件 | 二期 | -| 微信直连分账 | 已有模块，与汇付插件并行；`split_mode` 切换 | -| 钱包佣金 | `split_mode=wallet` 时仍走内部钱包，不走汇付网关 | - -### 14.5 需求验收清单（对照需求图） - -1. 安装并启用 `shopro_huifu`，后台可配置汇付商户号与密钥 -2. 分账接收方可维护平台/推广员/区域代理及 `huifu_id` -3. 分账规则可按比例或固定金额配置各角色 -4. 后台选择 `split_timing=payed` 时支付成功即分账；选择 `confirm` 时确认收货后分账；各方账户收到对应金额 -5. 后台可查看分账流水、状态，失败可重试并最终成功或标记失败 -6. 禁用/卸载插件后，商城直连微信支付与订单流程不受影响 diff --git a/plan/深蓝酒业主题改造_d0048f3e.plan.md b/plan/深蓝酒业主题改造_d0048f3e.plan.md deleted file mode 100644 index f41161e..0000000 --- a/plan/深蓝酒业主题改造_d0048f3e.plan.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -name: 深蓝酒业主题改造 -overview: 将微信小程序从当前红色商城风格，改造为参考「雄戈小酒」包装的深海军蓝 + 金色高端酒业主题；按钮/选中态用金色，价格保留红色；同时更新后台装修默认 tabBar 配置。 -todos: - - id: create-theme-vars - content: 新建 theme.scss + theme.js，并在 uni.scss 中引入 - status: completed - - id: update-global-styles - content: 更新 pages.json、uview theme.scss、index.scss 全局样式 - status: completed - - id: update-headers - content: 改造首页头部渐变、navbar、个人中心头部 fallback - status: completed - - id: replace-colors-by-context - content: 按按钮(金)/价格(红)/选中态(金或蓝) 区分替换 35+ vue 文件中的硬编码色值 - status: completed - - id: tabbar-fallback - content: shopro-tabbar + Vuex 增加新主题 fallback 及旧色自动映射 - status: completed - - id: backend-decorate - content: 更新 decorate.js 默认 tabBar 配置 + SQL 更新已有数据库模板 - status: completed - - id: verify-build - content: 编译微信小程序并逐项验证主要页面视觉效果 - status: completed -isProject: false ---- - -# 微信小程序深蓝酒业主题改造方案 - -## 设计目标 - -参考包装图「雄戈小酒」的视觉语言，建立 **深海军蓝 + 金色 + 价格红** 的三色体系： - -| 用途 | 色值 | 说明 | -|------|------|------| -| 主色（导航/头部/TabBar 背景） | `#001F54` | 深皇家蓝 | -| 主色渐变 | `#001F54 → #003399` | 首页/个人中心头部 | -| 按钮/选中态/强调 | `#C5A059 → #E9C875` | 金色渐变（已有登录弹窗 `#e9b461 → #eecc89` 可统一） | -| 价格/金额 | `#FF0e25` | **保留红色**（按你的选择） | -| 页面底色 | `#F0F3F8` | 微蓝灰，比纯白 `#f6f6f6` 更贴合主题 | -| TabBar 未选中文字 | `#8FA8C8` | 浅蓝灰 | - -```mermaid -flowchart LR - subgraph palette [ColorPalette] - Navy["#001F54 深海军蓝"] - Gold["#C5A059 金色"] - Red["#FF0e25 价格红"] - end - subgraph usage [Usage] - Navy --> NavBar[导航栏/头部/TabBar背景] - Navy --> CategorySel[分类选中背景] - Gold --> Buttons[购买/结算/确认按钮] - Gold --> Checkbox[复选框/Tab选中] - Red --> Price[商品价格/合计金额] - end -``` - ---- - -## 现状分析 - -- 框架：**uni-app (Vue2) + Shopro-plus + uView UI** -- 当前品牌色 `#FF0e25` 分散在 **约 35 个** `.vue` 文件及 [`pages.json`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages.json) 中，无统一主题文件 -- 首页头部为橙红渐变（[`pages/index/index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index.vue) 第 5 行）： - -```5:5:f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index.vue -style="...background: linear-gradient(to right, #FFA33E, #ff1926);" -``` - -- 主 Tab 页使用 **自定义 TabBar**（[`components/shopro-tabbar/shopro-tabbar.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-tabbar\shopro-tabbar.vue)），颜色由后台装修 API 下发（Vuex `tabbarData`） -- 个人中心头部背景色同样来自后台 `userTemplate[0].content.color` - ---- - -## 实施步骤 - -### 1. 建立统一主题变量（前端核心） - -新建 [`static/style/theme.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\theme.scss)： - -```scss -$brand-primary: #001F54; -$brand-primary-light: #003399; -$brand-gold: #C5A059; -$brand-gold-light: #E9C875; -$brand-gold-gradient: linear-gradient(90deg, #C5A059, #E9C875); -$brand-header-gradient: linear-gradient(135deg, #001F54, #003399); -$brand-price: #FF0e25; // 价格保留红 -$brand-page-bg: #F0F3F8; -$brand-tabbar-bg: #001F54; -$brand-tabbar-active: #C5A059; -$brand-tabbar-inactive: #8FA8C8; -``` - -新建 [`shopro/config/theme.js`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\shopro\config\theme.js) 导出同名常量，供 template 内联 `style` 和 uView 组件 `activeColor` / `confirm-color` 属性使用。 - -在 [`uni.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\uni.scss) 中 `@import 'static/style/theme.scss'`。 - -### 2. 全局基础样式 - -| 文件 | 改动 | -|------|------| -| [`uview-ui/theme.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\uview-ui\theme.scss) | `$u-type-primary` 改为 `#001F54`，light/disabled 衍生色同步调整 | -| [`static/style/index.scss`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\static\style\index.scss) | `page` 背景改为 `$brand-page-bg` | -| [`pages.json`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages.json) | `globalStyle`: 导航栏背景 `#001F54`、文字 `white`；`tabBar`: 背景 `#001F54`、选中 `#C5A059`、未选中 `#8FA8C8` | - -### 3. 首页与个人中心头部 - -| 文件 | 改动 | -|------|------| -| [`pages/index/index.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index.vue) | 头部渐变 `#FFA33E→#ff1926` 改为 `$brand-header-gradient`；内联 style 提取为 class | -| [`pages/index/index/home-head.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\index\home-head.vue) | 搜索框在深色背景下微调边框/背景透明度 | -| [`components/shopro-navbar/shopro-navbar.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-navbar\shopro-navbar.vue) | 默认背景改为透明/深蓝，返回图标改白色 | - -个人中心头部 `userinfo-card` 的背景色来自后台配置；前端在 [`userinfo-card.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\user\userinfo-card.vue) 增加 fallback：当 `detail.color` 为空或为旧色值时，使用 `$brand-header-gradient`。 - -### 4. 按场景区分替换 `#FF0e25`（约 35 个文件） - -**改为金色渐变（按钮/CTA）：** -- [`pages/goods/detail.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\goods\detail.vue) — 购买/加购按钮背景 -- [`pages/index/cart.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\cart.vue) — 结算按钮 -- [`components/shopro-sku/shopro-sku.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-sku\shopro-sku.vue) — 确认按钮 -- [`components/shopro-share/shopro-share.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\components\shopro-share\shopro-share.vue) — 分享按钮 -- [`pages/index/components/sh-goods-card.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-goods-card.vue) — `btnBg` 秒杀/拼团按钮 -- [`pages/index/category/takeout-catgory.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\category\takeout-catgory.vue) — 加购按钮 - -**保留红色（价格/金额）：** -- 上述文件中的 `.price`、`.total-price`、`shopro-mini-card` 价格、`order/confirm.vue` 金额、`cart.vue` 合计金额等 **不改动** - -**改为深蓝/金色（交互选中态）：** -- 分类页选中指示条（`one-catgory.vue`、`two-catgory.vue`、`three-catgory.vue`）→ 背景 `#001F54` 或金色左边框 -- Checkbox `activeColor`（cart、favorite、view-log 等）→ `#C5A059` -- [`pages/index/components/sh-grid-swiper.vue`](f:\修改的项目\贵州宥川商贸有限公司\chufang.gynhc.com\xgsc.gynhc.com_wx\pages\index\components\sh-grid-swiper.vue) 指示点 → 金色 - -**统一引入 theme：** -各 `.vue` 的 `