上传文件至「/」

05-订单与分销全链路升级项汇总.md

@@ -0,0 +1,466 @@
+# 订单与分销全链路升级项汇总
+
+> 用途：详细说明本轮订单与分销全链路升级了什么、解决了什么、形成了哪些统一规则，以及当前交付状态。
+>
+> 本文按业务能力汇总，不使用研发阶段编号、确认项编号或内部节点名称。
+>
+> 汇总日期：2026-08-12。
+
+## 一、升级目标与总体结果
+
+本轮升级不是单独修改某几个页面或接口，而是按照订单生命周期把来源、下单、工单、费用、支付、退款、结算、分销、钱包、通知和发票重新连成一条可追踪业务链。
+
+升级后的核心结果如下：
+
+1. 一笔订单从创建到资金结束，关键状态、金额、参与人和处理结果都有唯一事实来源。
+2. 业务按订单生命周期顺序推进，不由前端页面、统计结果或人工命令反推状态。
+3. 抢单、派单、接单、改天上门和多工单占用具备清晰并发边界。
+4. 报价、施工记录和费用允许在规定阶段修订，但历史版本不被覆盖。
+5. 支付、退款、取消、结算、分账、钱包和统计不再是互相断开的处理片段。
+6. 用户、师傅、派单员、分销参与人和管理后台读取同一套业务及资金口径。
+7. 通知改为统一内容、统一入口、按配置投递，不再由各业务入口各写一套消息。
+8. 发票按订单申请并自动冻结收费项明细，退款后能够形成红字处理闭环。
+9. 正式业务不要求业务负责人手工运行自定义命令；当前任务可同步执行，并保留后期安全切换队列执行的能力。
+
+## 二、交付范围总览
+
+| 业务范围 | 升级前主要问题 | 本轮升级结果 | 当前状态 |
+|---|---|---|---|
+| 来源与分销关系 | 来源生命周期、覆盖规则和订单分配快照不完整 | 来源按运行周期管理，订单创建时冻结全部有效参与关系 | 代码已落实，待集中人工验收 |
+| 预约与订单初始化 | 上门费、初始状态、工单创建存在分散判断 | 统一为“先付上门费”或“直接创建待接工单”两条确定分支 | 代码已落实，待集中人工验收 |
+| 抢单与派单 | 抢单、超时派单、接管并发和师傅匹配边界不清 | 建立超时双池、限时接管、唯一结果和服务项目匹配 | 代码已落实，自动检查已完成 |
+| 师傅占用 | 多工单、改天上门和公共抢单限制缺少统一口径 | 统一占用判断，改天上门立即释放，配置控制公共抢单 | 代码已落实，待人工复验 |
+| 到场、报价与施工 | 报价确认、预付款、改天上门、记录修改互相影响 | 建立连续履约状态和统一恢复规则 | 代码已落实，自动检查已完成 |
+| 费用确认与修订 | 单条、批量确认及后付增费门禁容易混淆 | 按服务记录确认，统一重算确认、支付和完工门禁 | 代码已落实，待人工验收 |
+| 支付与退款 | 客户端结果、微信通知和项目业务推进存在断点 | 以合法通知形成权威事实，并完成支付和退款全闭环 | 代码及数据库已落实，待真实支付退款验收 |
+| 结算、分账与钱包 | 收益口径、压款、兜底和退款冲正分散 | 建立唯一结算、分账、钱包、压款与冲正链路 | 代码及数据库已落实，待真实资金验收 |
+| 分销及师傅统计 | 页面可能继续读取旧表、旧字段或旧累计口径 | 全部对齐新结算、分配关系、钱包及退款净额 | 代码已落实，待页面人工验收 |
+| 通知 | 业务通知入口和渠道模板分散，端别跳转混乱 | 统一通知事实、模板、收件箱、渠道和目标小程序 | 通知基座已落实，旧入口按业务范围迁移 |
+| 发票与红字 | 缺少整单额度冻结及退款后的红字事实 | 整单申请、蓝字交付、退款红字和额度守恒已闭环 | 代码及数据库已落实，待人工验收 |
+
+## 三、来源、身份与分销关系升级
+
+### 1. 来源生命周期
+
+- 普通进入使用平台自然来源。
+- 好友分享或合作方二维码来源必须先通过有效性校验。
+- 有效来源保存在当前小程序运行内存中，不依赖永久本地缓存。
+- 同一运行周期再次下单继续使用当前来源；新有效来源覆盖旧来源；完全退出后重新进入恢复平台自然来源。
+- 下单成功后不主动清除来源，避免连续下单时来源意外丢失。
+
+### 2. 订单来源快照
+
+订单创建时一次性保存来源类型、来源参与人和对应业务信息。后续来源失效、身份变化或后台配置变化，不回写历史订单。
+
+### 3. 分销身份与订单关系
+
+- 邀请人、业务员、合伙人等小程序业务身份使用同一用户体系，但身份资格和业务权限各自校验。
+- 小程序身份与管理后台账号、角色完全隔离，不能互相代替。
+- 订单创建时冻结全部有效营销参与关系及平台剩余关系。
+- 后续收益按订单快照计算，不按结算时的最新身份或最新比例重新寻找参与人。
+- 只有平台关系时不记录无业务价值的分销关系日志，但订单和平台收益仍正常处理。
+
+## 四、预约下单与订单初始化升级
+
+### 1. 服务项目约束
+
+- 预约页只展示包含真实有效服务项目的服务分类。
+- 下单必须提交合法服务项目、地址和必要预约资料。
+- 服务项目、分类、地址、问题描述及图片在后端再次校验，不能只依赖前端显示限制。
+
+### 2. 初始上门费
+
+- 上门费按下单时服务项目配置创建为确定收费项。
+- 下单时的初始上门费与师傅履约过程中新增的上门费属于不同收费事实，名称相同但业务来源互不替代。
+- 需要前置支付且金额大于零时，订单进入“待支付上门费”，暂不创建工单。
+- 不需要前置支付时，订单进入“待派单”并创建唯一“待接单”工单。
+- 上门费支付成功后由统一支付结果处理创建首张工单，避免前端重复触发。
+
+### 3. 初始化事务
+
+订单主体、来源快照、分配关系、初始收费项、支付阻塞、进度日志和首张工单按确定分支集中写入。任何一步失败时不留下半张订单或缺失关系。
+
+## 五、抢单、派单、接单与师傅占用升级
+
+### 1. 抢单资格
+
+- 师傅只能看到与本人已选服务项目匹配且本人具备接单资格的公共工单。
+- 抢单时再次校验资格和服务项目，防止列表打开后资格变化导致越权接单。
+- 已经被其他师傅抢走或被派单员接管的工单不能被后到请求覆盖。
+
+### 2. 超时派单
+
+- 未达到后台配置的等待时长前，工单只进入公共抢单，不对派单员开放。
+- 超时后同时进入公共抢单和派单范围，不因开放人工派单而强制停止师傅抢单。
+- 师傅抢单和派单员接管并发竞争，先成功提交者取得处理权。
+
+### 3. 派单员接管
+
+- 派单员先选择“接管派单”，工单随即退出两个公共范围，避免沟通师傅期间被并发抢走。
+- 接管具有有效期，可续期、主动放回或正式选择师傅。
+- 到期自动放回，不依赖人工运行命令。
+- 正式派单时再次校验目标师傅的接单资格和服务项目。
+- 被派师傅确认接单或拒绝后，按唯一状态继续推进或回流。
+- 派单员在师傅端小程序操作，并可持续跟踪本人经手订单。
+
+### 4. 统一师傅占用
+
+- 待确认派单不占用。
+- 已接单到提交完工之间，除改天上门和异常状态外均属于有效占用。
+- 改天上门立即释放，师傅可承接其他工作。
+- 默认限制开启时，有有效占用的师傅不显示其他公共抢单，只显示本人已有工单及待确认派单。
+- 限制关闭时，展示全部符合服务项目和资格的公共工单。
+- 派单员向师傅派单不受该开关限制。
+- 多个工单同时停在“待上门”时不再形成全部无法推进的死锁，只在真正开始履约时处理冲突。
+
+## 六、到场、报价、施工和完工升级
+
+### 1. 到场事实
+
+- 到场时间由后端记录，师傅不可编辑。
+- 现场说明可选，现场照片必填。
+- 工单从“待上门”进入“已到场”，为首次报价建立明确起点。
+
+### 2. 首次报价
+
+首次方案包含问题说明、现场照片、费用明细和施工安排：
+
+- “待用户确认”：用户确认后方可施工；有预付款时还必须完成支付。
+- “改天上门”：保存报价和费用事实，暂停履约并立即释放师傅。
+
+### 3. 改天上门恢复
+
+- 用户确认和支付不因改天上门而停止，也不因再次到场而丢失。
+- 未确认报价时再次到场：恢复“已到场”，继续等待确认，禁止施工。
+- 已确认且没有待支付预付款：再次到场后恢复“施工中”。
+- 已确认但预付款未支付：仍暂停施工，等待支付。
+- 用户端和师傅端相关列表统一显示中文“上门时间”。
+- 恢复逻辑收敛为统一能力，避免每个入口各判断一遍。
+
+### 4. 施工记录
+
+- 施工中可以多次提交说明、图片、费用和继续安排。
+- 后付新增费用只要求用户确认，不暂停施工。
+- 预付新增费用必须等待确认和支付，未完成前暂停施工。
+- 施工中允许调整为继续施工或改天上门，避免现场变化时流程被锁死。
+
+### 5. 提交完工
+
+- 施工后提交不再显示施工安排；需要下次上门时继续使用施工中记录。
+- 提交完工立即释放师傅占用。
+- 有待确认或待支付费用时显示“已提交完工”。
+- 全部费用处理完毕后进入“已完成”，再触发订单资金结算。
+- 接单后到提交完工前保留重新派单异常入口。
+
+## 七、费用、材料与记录版本升级
+
+### 1. 收费项统一
+
+当前履约费用包括服务费、履约中新上门费、师傅代购材料费和后台材料库费用。每一项都记录业务来源、金额、支付方式、所属服务记录和当前确认支付状态。
+
+### 2. 材料费用
+
+- 师傅代购材料费可上传购买清单图片，并选择预付或后付。
+- 后台开关只控制是否展示材料库入口。
+- 材料库费用提交材料和规格标识，由后端按权威材料、规格、单位和价格复原，避免信任前端衍生名称和金额。
+
+### 3. 记录修订
+
+- 用户确认前允许师傅从工单记录再次进入修改。
+- 每次修改创建新版本，不覆盖历史。
+- 列表只展示当前有效版本，避免同一业务记录重复出现。
+- 用户确认、进入支付或提交完工后转为只读。
+- 当前用户没有费用驳回入口；异议通过暂不确认、沟通及师傅修订处理。
+
+## 八、费用确认与统一支付入口升级
+
+### 1. 确认单位
+
+- 用户按服务记录查看问题说明、图片和关联费用。
+- 单条确认时，服务记录及其收费项在同一事务内变为“已确认”。
+- 支持前端明确提供一键确认所有待确认项，后端仍按实际记录逐项校验，防止范围不清。
+
+### 2. 确认后的门禁
+
+- 首次报价无预付款：确认后进入施工。
+- 存在预付款：确认后进入待支付，支付成功后施工。
+- 改天上门：确认和支付继续处理，但工单仍等待再次到场。
+- 施工中后付增费：确认不暂停施工。
+- 已提交完工：确认后进入尾款处理；无待付款时完成订单。
+
+### 3. 订单详情入口
+
+- 按钮统一显示“去支付”，减少用户对“确认费用”和“支付费用”的理解分歧。
+- 有待确认项时先进入确认页。
+- 无待确认项且存在有效、金额大于零、尚未支付费用时进入支付。
+- 没有可处理费用时不显示。
+
+## 九、支付发起与支付结果升级
+
+### 1. 发起支付
+
+- 系统只选择当前允许支付、已确认、金额大于零且尚未支付的收费项。
+- 每次收款永久冻结对应收费项关系，后续修改不能改变历史支付范围。
+- 重复点击时复用或正确处理已有待支付收款，防止形成冲突收款事实。
+- 校验订单所有者、当前小程序、用户微信身份、支付阶段和币种金额。
+
+### 2. 支付结果
+
+- 前端完成微信支付后正常提示“支付成功”并静默刷新，不增加“结果确认中”等用户负担。
+- 最终业务以微信有效支付通知为准。
+- 回调再次校验支付类型、成功状态、应用、商户单号、微信交易号、金额、币种及收费项。
+- 支付成功时间采用微信实际成功时间。
+- 同一微信交易结果不能重复推进业务。
+
+### 3. 支付后的业务推进
+
+- 初始上门费：解除上门费门禁，进入待派单并幂等创建首工单。
+- 施工预付款：解除支付门禁，再结合是否改天上门决定恢复施工或继续挂起。
+- 完工尾款：全部有效费用结清后推进工单和订单完成。
+
+## 十、取消与退款闭环升级
+
+### 1. 退款范围
+
+- 接单前取消且存在已付费用时，退款按原成功收款、原收费项和金额精确冻结。
+- 一次取消可按多张原收款单拆成多张退款单。
+- 支持部分退款和同一原收款下的多次合法退款事实，不覆盖历史。
+
+### 2. 提交与结果
+
+- 本地退款先进入“处理中”，再提交微信退款。
+- 提交失败保留退款单和失败原因，不删除事实。
+- 微信退款通知到达后，再次校验状态、金额、币种、原商户单号、退款单号和渠道退款号。
+- 成功退款不被晚到的失败或关闭消息覆盖。
+
+### 3. 取消推进
+
+- 全部应退款成功：统一取消订单和工单并解除退款阻塞。
+- 仍有退款处理中：继续冻结，等待最终结果。
+- 退款失败或结果未知：进入可追踪重试或授权人工处理，不提前显示取消完成。
+
+### 4. 资金冲正
+
+- 订单收益仍在师傅压款时，减少压款金额并写入唯一反向流水。
+- 收益已释放到钱包时，减少可用余额并写入唯一反向流水。
+- 每笔冲正按退款和结算明细保持唯一，重复回调不会重复扣减。
+- 余额不足时标记为“人工复核”，但不改变微信退款已经成功的事实。
+
+## 十一、统一结算、分账、钱包与统计升级
+
+### 1. 唯一订单结算
+
+只有订单、工单均已完成，没有有效阻塞和待支付费用，并存在成功收款时才构建结算。结算依据包括：
+
+- 已确认收费项；
+- 成功收款减成功退款的净额；
+- 订单创建时冻结的全部分配关系；
+- 收款时冻结的支付手续费信息。
+
+结算生成一次后按不可变签名校验，不因当前配置变化重新计算覆盖历史。
+
+### 2. 各方收益
+
+- 平台收益直接形成成功结算项。
+- 师傅收益进入订单压款。
+- 邀请人、业务员和合伙人收益进入微信分账。
+- 支付手续费形成平台减少项。
+
+### 3. 微信分账
+
+- 按成功收款单创建分账记录及明细。
+- 明确成功后等待分账完结。
+- 明确失败时按规则进入钱包兜底。
+- 状态未知时自动到期查询；超过次数后进入“人工复核”。
+- 钱包收益再次分账时先冻结余额，成功后扣除，失败后退回。
+- 全部结算项进入最终状态后完成微信分账完结。
+
+### 4. 师傅压款与钱包
+
+- 结算产生师傅收益后增加压款余额和压款明细。
+- 到释放时间后从压款余额转为可提现余额并生成钱包流水。
+- 自动处理与访问钱包时的幂等兜底并存，不依赖手工命令。
+- 本轮只覆盖订单导致的入账、压款、释放、兜底和退款冲正，不包含独立提现及保证金流程。
+
+### 5. 页面和统计对齐
+
+- 用户端分销中心的角色、累计金额和明细对齐新分销关系及结算表。
+- 师傅端个人中心统计对齐新结算、压款、钱包和退款净额。
+- 师傅收益明细读取统一订单结算收益及冲正事实。
+- 管理后台和接口统计使用相同查询与金额口径。
+- 资金事实保存后自动更新日统计；当前同步执行，不需要人工命令，后期可直接切换队列。
+
+## 十二、统一通知基座升级
+
+### 1. 单一业务入口
+
+业务只提交通知场景、接收人和受控变量，不直接拼接站内信、小程序订阅消息或服务号消息。
+
+### 2. 统一通知成品
+
+通知模板统一配置以下内容：
+
+- 标题和摘要；
+- 正文；
+- 结构化详情；
+- 业务时间；
+- 操作按钮；
+- 目标小程序和目标页面；
+- 可用渠道及渠道模板信息。
+
+标题和正文可在站内信及外部微信消息中复用；跳转目标独立于正文，不混入文本内容。
+
+### 3. 端别和跳转
+
+- 不再因为用户端、师傅端而复制两套业务通知正文。
+- 接收身份、目标小程序和页面路径由场景投递配置决定。
+- 同一场景确需两端展示时，共用一条业务通知事实，分别生成两端收件箱和渠道投递。
+- 站内信按当前端识别目标；跨小程序时先打开目标小程序，再进入指定页面。
+- 小程序订阅消息必须在发送时选择对应目标小程序的模板和页面。
+
+### 4. 快照与执行
+
+- 发布后的模板版本用于渲染通知。
+- 业务事务内保存通知事实、成品快照和投递任务。
+- 事务提交后执行通知任务；当前同步，后期可切换队列。
+- 模板后续变化不修改历史消息。
+- 关闭的渠道不生成虚假投递记录。
+
+### 5. 后台配置
+
+通知配置在管理后台使用独立页签集中维护，包括全局渠道开关、场景模板、目标小程序、页面路径、变量和发布版本。通知内容不再散落在各业务代码中。
+
+## 十三、订单开票与红字升级
+
+### 1. 开票资格
+
+- 订单已完成且存在成功支付净额时，用户可以按订单申请。
+- 申请不允许用户勾选收费项或自行填写金额。
+- 后端按成功收款减成功退款，自动收集本次全部可开票收费项和金额。
+- 全额退款时可开票金额为零，不显示申请入口。
+
+### 2. 唯一有效申请
+
+- “待处理”“处理中”“已开票”均占用本次可开票额度并阻止重复申请。
+- “已驳回”“已取消”保留历史，但释放额度并允许重新申请。
+- 申请主单金额必须等于收费项明细合计。
+
+### 3. 蓝字发票
+
+- 用户提交个人普票、企业普票或企业专票资料。
+- 管理人员开始办理后进入“处理中”。
+- 保存发票号码、开票时间和电子文件后进入“已开票”。
+- 用户收到统一通知并可查看、下载。
+
+### 4. 退款红字
+
+- 已开票收费项退款成功后，按退款单、原蓝字发票、收费项和金额生成独立红字任务。
+- 退款成功不因红字尚未办理而回退或显示失败。
+- 红字完成后保存红字号码、文件、金额、处理人和时间。
+- 因退款红冲的金额不恢复开票额度。
+
+### 5. 开票错误修正
+
+原发票抬头、税号等错误时，由管理人员发起红字修正；只有红字完成后，未退款的有效交易额度才恢复，用户可按正确资料重新申请。不能直接修改或覆盖原蓝字发票。
+
+## 十四、管理后台升级
+
+1. 订单、工单、费用、收款、退款、结算、分账、钱包、发票及通知均保留可追踪事实。
+2. 管理后台与小程序接口复用相同的状态、金额和统计口径，不在后台另算一套。
+3. 派单员属于师傅端小程序业务角色，管理后台角色不获得派单员小程序权限。
+4. 分账长期未知、钱包冲正余额不足等资金异常进入授权管理人员复核。
+5. 发票处理在管理后台完成蓝字办理、取消、驳回和红字任务处理。
+6. 通知配置使用独立页签统一管理场景、模板版本、渠道和跳转目标。
+
+## 十五、数据与代码治理升级
+
+### 1. 权威事实
+
+- 订单来源以订单创建快照为准。
+- 收费项以服务记录及其有效版本为准。
+- 支付和退款以微信合法结果及项目二次校验事实为准。
+- 结算以唯一不可变订单结算为准。
+- 分销、师傅和平台收益以结算明细及退款冲正为准。
+- 钱包余额以钱包账户、压款和不可重复流水为准。
+- 发票额度以成功收款、成功退款和有效开票占用为准。
+- 统计只读取权威事实，不参与状态推进。
+
+### 2. 代码收敛
+
+- 相同业务规则优先复用统一方法，不允许控制器、任务和后台各写一套。
+- 师傅占用、费用确认门禁、支付状态、退款推进、结算、统计和通知均使用统一权威能力。
+- 代码调整遵循已定业务方案的最小范围，不在错误方案上保守修补，也不无故推翻已确认方案重写。
+- 不保留无实际需要的旧兼容路径，保持代码干净。
+- 注释随代码同步维护，只描述关键业务条件、状态推进、金额和并发依据。
+- 可以复用的逻辑必须复用，可以形成统一能力的规则集中维护。
+
+### 3. 数据库和人工操作
+
+- 需要业务负责人执行的数据库操作继续单独维护文档，不混入业务流程。
+- 正式业务执行不依赖自定义命令。
+- 测试数据清理只处理运行中业务数据，不清理后台维护的服务、材料、展示和费用配置。
+- Kit通用表除明确允许的应用配置外，业务代码和清理脚本均不操作。
+- Laravel及管理后台框架表不纳入业务清理。
+- 后续新增或调整业务表时，必须同步维护测试环境清理文档。
+
+### 4. 测试边界
+
+- 测试代码用于验证已确认业务，不作为反推业务规则的审查依据。
+- 业务代码审查排除测试目录；业务规则改变后，测试应同步调整以验证新契约。
+- 自动检查、数据库核验和真实小程序人工验收分别记录，不用其中一项替代另一项。
+
+## 十六、中文业务状态口径
+
+对客户、运营和文档展示时统一使用中文含义：
+
+| 范围 | 中文状态序列 |
+|---|---|
+| 订单履约 | 待支付上门费 → 待派单 → 待上门／已到场／施工中 → 已提交完工 → 已完成 |
+| 接单处理 | 公共抢单 → 超时可派单 → 派单处理中 → 待师傅确认 → 已接单或已拒绝回流 |
+| 改天上门 | 履约挂起 → 等待再次到场 → 按确认和预付款结果恢复已到场或施工中 |
+| 费用 | 待确认 → 已确认 → 待支付 → 已支付；无效费用进入已取消 |
+| 收款 | 待支付 → 支付中 → 支付成功；异常进入关闭或人工复核 |
+| 退款 | 待提交 → 处理中 → 已退款；失败或未知进入可重试／人工复核 |
+| 订单结算 | 待结算 → 结算处理中 → 已结算；异常进入人工复核 |
+| 微信分账 | 待提交 → 处理中 → 已成功／钱包兜底／人工复核 → 已完结 |
+| 师傅收益 | 压款中 → 已释放为可提现余额；退款时进入已冲正或人工复核 |
+| 发票 | 待处理 → 处理中 → 已开票；开票前可进入已驳回或已取消 |
+| 红字任务 | 待处理 → 处理中 → 已完成；原退款事实不受其处理进度影响 |
+
+页面内部实际展示可根据端别压缩文字，但业务含义不得变化。
+
+## 十七、当前交付与验收状态
+
+| 项目 | 当前结果 |
+|---|---|
+| 业务规则 | 已按当前覆盖范围定稿并形成连续流程 |
+| 后端代码 | 当前覆盖范围已落实 |
+| 小程序必要调整 | 当前涉及的入口、列表提示、确认支付及统计读取已同步 |
+| 管理后台必要调整 | 通知配置、资金查看和发票处理已同步 |
+| 数据库变更 | 当前各范围手动数据库脚本已执行或完成预期核验 |
+| 自动检查 | 已按各业务范围完成定向检查；不替代真实环境验收 |
+| 人工验收 | 尚未集中完成，应按《客户验收－订单与分销完整业务流程》逐项验证 |
+| 真实资金验收 | 支付、退款、微信分账、钱包释放及红字发票仍需使用部署环境真实结果确认 |
+
+## 十八、明确后置能力
+
+以下能力已记录但不属于本轮当前交付，后续启动时需重新确认业务规则和实现范围：
+
+- 来源二维码签发及防篡改；
+- 正式身份注销；
+- 小程序订阅消息和服务号真实发送；
+- 钱包异常余额和已提现后退款的扩展处置；
+- 用户直接驳回费用；
+- 营销收益独立钱包及提现页面；
+- 微信支付手续费正式账单对账；
+- 订单财务摘要缓存和财务专用详情；
+- 下单请求防重复能力；
+- 收费项单独支付；
+- 用户取消尚未处理的开票申请；
+- 后台配置部分收费项不参与开票；
+- 独立提现、提现审核打款及保证金流程。
+
+## 十九、客户验收入口
+
+客户不需要阅读内部审计文档，按 [客户验收－订单与分销完整业务流程](./04-客户验收订单与分销全链路流程.md) 的业务顺序和验收清单执行即可。
+