携岛系统功能设计说明书

本文档是携岛（XieDao）系统的功能事实基准文档。内容基于对代码库、数据库迁移与四端前端的全面核对整理，覆盖「平台 + 商户 + 用户」三端 O2O 旅游生活平台的全部已实现功能。
文档版本：v2.0（全面整理版）
整理日期：2026-10-21
上一版本：v1.0（2026-07，仅覆盖主体流程）
配套文档：《功能模块划分》（F 编号定义与追踪规则）、《系统使用手册》（操作步骤）、《项目架构全景》（技术架构）

1. 文档说明
2. 系统总体架构
3. 总体业务流程
4. F01 账户与用户
5. F02 商户入驻与管理
6. F03 商品与供应
7. F04 营销活动
8. F05 订单交易
9. F06 支付与退款
10. F07 履约管理
11. F08 售后服务
12. F09 商户财务
13. F10 内容与社区
14. F11 消息与通知
15. F12 平台运营与系统
16. 四端功能矩阵
17. 当前限制与未实现能力
18. 附录 A：实现参考索引

1. 文档说明

1.1 编写目的

本文档描述携岛系统已经形成的业务功能、参与角色、页面与接口入口、流程、状态、规则和限制，用于：

产品与运营：理解功能边界与生效时点，避免把配置项或后台任务误当作用户功能。
商户与客服：理解订单、履约、结算链路，回答用户与商户的实际问题。
研发与测试：以业务事实为基准核对实现差异，定位功能归属模块。
新成员：作为系统的功能地图，避免在陌生模块间反复搜索。

1.2 系统范围

携岛是基于 RuoYi-Vue 3.9.1 二次开发的海南旅游生活服务平台，覆盖：

业务域	覆盖内容
交易	团购、拼团、套餐、酒店房型、租车、接送包车、旅拍、物品租赁、商城电商、定制游
履约	预约申请、派单调度、接单拒单、核销扫码、交接单、发货收货、补差价
资金	微信支付 V3、钱包余额、优惠券结算、商户内部账本结算、保证金、提现、罚款申诉
内容	种草笔记社区、话题、关注收藏、旅游攻略、评论
运营	审核体系、价格日历与月度申报、推荐位置、首页运营、推广分销、数据看板、待办中心
通信	自托管 OpenIM 即时消息、平台广播通知、阿里云短信、微信订阅（未启用）

不在范围内：微信服务商利润分账（已下线，改为平台内部账本结算）、跨平台多租户 SaaS、国际化多语言。

1.3 终端与角色

端	路径	技术栈	使用者	认证方式
后端 API	`Api/`	Java 21 + Spring Boot 3.5.8 + MyBatis + 微信支付 V3	全部端	见 2.2
平台管理端	`AdminWeb/`	Vue 3 + Element Plus + Pinia + Vite 6	平台运营、审核、财务	账号密码 + 验证码 → JWT
商户 Web 端	`MerchantWeb/`	同上	商户负责人、店长	手机号 + 密码 → 商户 JWT
用户小程序	`App/`	原生小程序 + glass-easel	消费者	微信授权登录 → 自建 JWT
商户小程序	`MerchantApp/`	原生小程序 + OpenIM	商户员工、司机、摄影师	手机号 + 密码 → 商户 JWT

角色清单

角色	载体	说明
消费者	App	注册即用，openid 绑定
商户负责人	MerchantWeb / MerchantApp	完整经营权限，菜单由能力矩阵决定
商户员工	MerchantApp	同一商户身份，按能力显示功能
司机	MerchantApp	`driver` 外包角色，仅接单与行程
摄影师	MerchantApp	`photographer` 外包角色，仅旅拍履约
平台管理员	AdminWeb	全部权限（`::*`）
平台运营/审核/财务	AdminWeb	按角色分配菜单与按钮权限

1.4 通用设计原则

金额统一以「分」存储。所有后端字段为 *Fen（整数分），前端通过 AmountInput / fenToYuan 做元↔分转换。任何文档中出现的"元"均指展示口径。
订单金额由服务端计算，不信任前端传入。OrderOrchestrator 汇总明细得出总额。
状态迁移集中管理。订单、结算、履约派单、定制游阶段均有唯一状态机入口，迁移时写审计日志。
价格三级模型。结算底价（商户底价）→ 平台售价 → 活动售价，详见 2.4。
能力矩阵而非角色权限控制商户端。商户菜单由「经营类型 + 已开通能力」双轨决定，与平台端的 RuoYi 角色权限体系是两套独立机制。
驳回必须留原因。所有审核类动作，驳回时必填原因，供提交方修改后重提。
对外文档不写死"已实现"。依赖外部服务的能力按第 6 节的状态规范标注。

1.5 功能状态表达规范

本文档与《使用手册》统一使用以下状态，禁止把占位、配置或后台任务写成用户功能：

状态	含义	使用要求
已实现	已有页面或接口，且存在完整业务处理	可写入功能设计与使用手册
系统自动	由回调、事件或定时任务执行，无人工页面	功能设计说明触发条件；使用手册不虚构入口
配置后可用	代码已实现，依赖微信、阿里云、OpenIM 等外部配置	必须写明环境与配置前提
默认模拟	默认返回模拟结果，未默认连接正式能力	明确标注 Mock，不描述为正式生产能力
暂未实现	仅有配置、接口、注释或规划	只能放入限制或后续规划

1.6 与其他文档的关系

文档	关系
《功能模块划分》	定义 F01–F12 编号、角色边界与追踪规则；本文档按该编号展开
《系统使用手册》	按终端和用户任务组织的操作步骤，引用本文档的 F 编号
《项目架构全景》	技术实现视角（类、表、模块依赖），本文档是业务视角
《商家中心产品设计与使用说明》	F02 商户生命周期的深度专题文档
《平台运营商品价格逻辑》	F03 三级价格模型与改价影响面的深度专题文档
《推荐位置功能设计与运营使用说明》	F12 推荐位置的深度专题文档
《酒店房态与团购价格日历整体功能说明》	F03-01 / F03-07 日历体系的深度专题文档

2. 系统总体架构

2.1 四端构成与数据流

                    ┌──────────────┐
   消费者 (App) ────▶│              │
                    │   后端 API   │◀──── 商户 (MerchantApp / MerchantWeb)
   平台 (AdminWeb) ▶│  Spring Boot │◀────
                    │   + MyBatis  │
                    └──────┬───────┘
                           │
        ┌──────────┬───────┼────────┬──────────┐
        ▼          ▼       ▼        ▼          ▼
     MySQL      Redis    阿里云    微信支付    OpenIM
    业务主库   令牌/锁/限流  OSS/短信/审核  V3/支付分  自建IM

2.2 后端 API 命名空间

命名空间	消费端	认证	端点量级
`/api/app/**`	用户小程序	`@CurrentUser` 注入 app JWT	约 226
`/api/merchant/**`	商户 Web / 小程序	商户拦截器 + `@CurrentMerchant`；公开接口须标 `@Anonymous`	约 218
`/api/admin/**`	平台管理端	平台 JWT + `@PreAuthorize` 权限标识	约 395
`/api/platform/**`	平台管理端（商城商品/订单）	同上	少量
`/system/` `/monitor/` `/tool/**`	平台管理端（RuoYi 原生）	平台 JWT	约 95
`/common/**`	全端	部分公开	约 6

三套认证体系的差异

体系	令牌存储	前端 Header	后端解析	失效条件
平台	Cookie `Admin-Token`	`Authorization: Bearer <token>`	Spring Security JWT Filter	过期、账号停用、密码变更
用户	小程序 Storage `token`	同上	`CurrentUserResolver` 解析 app JWT	401 → 清除登录态回登录页
商户	Cookie `Merchant-Token`	同上	`MerchantAuthenticationInterceptor`	商户状态非「正常营业」时实时回查 DB 并拦截

2.3 核心业务对象

对象	承载表	关键属性
商户 `XdMerchant`	`xl_merchant`	经营类型、末级分类、状态机、3 套佣金、保证金、结算账户
商品 `XdProduct`	`xl_product`	活动类型、运营模式、定价模式、价格、库存、状态
活动 `XdProductActivity`	`xl_product_activity`	团购/拼团/套餐/租赁、售价、审核状态、有效期
价格日历 `XdProductPriceCalendar`	`xl_product_price_calendar`	商品+活动+日期 → 底价加价、活动加价、库存、已售
订单 `XdOrder`	`xl_order`	瘦交易头：金额分摊、状态、结算状态、父单号
订单明细 `XdOrderItem`	`xl_order_item`	单价、支付手续费、商户应收、佣金率、商品快照
订单事件 `XdOrderEvent`	`xl_order_event`	状态迁移审计：from/to、操作人、业务 ID
核销券 `XdOrderVoucher`	`xl_order_voucher`	12 位券码、状态、预约区间、核销时间
支付主单 `XdPaymentRecord`	`xl_payment_record`	微信/钱包分摊金额、状态、过期时间、版本号
退款单 `XdRefundRecord`	`xl_refund_record`	双渠道退款状态、触发类型、微信退款号、失败原因
房型 `XdRoomType`	`xl_room_type`	面积、床型、间数、结算底价、审核状态
房态日历 `XdRoomCalendar`	`xl_room_calendar`	房型+日期 → 底价、库存、可售状态、审核状态
派单 `Xd*Dispatch`	`xl_car_rental_dispatch` 等 4 张	履约主体、状态机、交接快照
商户钱包 `MerchantWallet`	`xl_merchant_wallet`	可用、冻结、待结算、累计
提现 `MerchantWithdrawal`	`xl_merchant_withdrawal`	状态机、金额、凭证、驳回原因
笔记 `XdNote`	`xd_note`	图文、话题、状态、置顶、推荐
推荐位置 `XdLocationZone`	`xl_location_zone`	中心点+半径、类型、归属匹配来源

2.4 三级价格模型

这是全系统最核心的业务约定，所有价格类功能（F03、F04、F05、F09）都基于它。

  结算底价                 平台售价                   活动售价
（商户报价，             （平台零售价，             （本次交易的
  商户收入来源）           可按日期覆盖）              用户实付价）
     │                        │                         │
     └──── 平台毛利 = 售价 − 底价 ────┘                    │
                                                          │
                              用户实付 = 活动售价 − 优惠券 − 钱包抵扣

层级	谁设置	影响面	关键约束
结算底价	商户提交，平台可审核/调整	该商户所有商品/房型的收入	变更留痕，触发商户通知；有快照乐观锁
平台售价	平台设置	用户看到的零售价	可按日期覆盖（日期售价）
活动售价	平台设置（底价模式下平台统一定价）	用户下单实付	团购/拼团/套餐固定使用「底价模式」，商户只填底价

关键规则

定价模式 self（自主定价）商户可自行定价；floor（底价模式）商户只能填结算底价。团购、拼团、套餐固定使用底价模式。
平台运营（代运营）商品由平台按底价统一定价，商户不参与定价。
酒店场景下，商品价格日历与房型房态日历是两套独立数据：前者管「团购套餐」，后者管「客人直接订房」，套餐含房型时按房型库存取交集。
日期售价允许低于默认售价，但不得低于结算底价。
已成交订单按下单时的价格快照结算，事后改价不影响已成交订单；改价只影响生效日之后的订单。

2.5 关键状态机总览

状态机	状态链	入口
订单主状态	PENDING_PAY → PAID → COMPLETED；PAID/COMPLETED → REFUNDING → REFUNDED；PENDING_PAY → CANCELLED	`OrderStateMachine`
订单结算状态	NONE → PENDING_SETTLE → AVAILABLE → DEDUCTED	`OrderSettlementStateMachine`
商户入驻状态	待审核(1) → 驳回(2) / 待支付(3) → 正常营业(4) → 关店审核中(5) → 已关店(6)；另有禁用(7)	`MerchantStatus`
活动状态	待审核(0) → 已上架(1) → 已下架(2) / 已驳回(3) / 平台下架(4)	`ProductActivityStatusEnum`
派单状态（4 条履约线各一套）	待派单 → 待接单 → 已接单 → 执行中 → 已完成；另有取消/拒绝/异常	各自 `*DispatchStatusEnum`
券码状态	未使用(0) → 已核销(1) / 已退款(2) / 已过期(3)；已预约(4)	`OrderVoucherStatusEnum`
提现状态	待处理 → 审批通过 → 已打款；或审批通过 → 打款失败 / 已驳回；另有风险审核	`WithdrawalStatusEnum`
退款申请状态	PENDING → APPROVED → REFUNDING → SUCCESS / FAILED / REJECTED	`RefundApplicationStatus`
定制游阶段	13 阶段带迁移白名单（见 6.9.3）	`CustomTourStage`
酒店预约状态	待确认(0) → 已成立(1) / 协商中(2) / 已撤销(3) / 待补差(4)	`HotelAppointmentStatusEnum`

2.6 订单展示状态（用户可见口径）

订单主状态只有 6 个，但用户端展示 17 种状态，由 XdOrderDisplayStatusResolver 按业务类型、履约进度和查看者角色聚合计算：

待支付 / 处理中 / 拼团中 / 待预约 / 待确认 / 协商中 / 待补差 / 已预订 / 待使用 / 派单中 / 待发货 / 已发货 / 服务中 / 已完成 / 结算中 / 退款中 / 已退款 / 已取消

同一条订单在不同角色视角下文案不同：商户看"待接单"，用户看"处理中"，平台看"派单中"。这是排查"状态不一致"类问题时的首要检查点。

3. 总体业务流程

3.1 消费者交易主流程

3.2 商户入驻经营主流程

3.3 售后退款主流程

3.4 履约主线（4 条业务线并行）

业务线	入口	状态链
专车接送（司机）	平台指派 / 司机接单	待接单 → 已接单 → 行程中 → 已完成（开始/完成上报 GPS）
旅拍（摄影师）	平台指派 / 摄影师接单	待接单 → 已接单 → 拍摄中 → 已交付 → 已完成
租车（车行）	平台指派 / 车行接单	待接单 → 已接车 → 已取车 → 还车中 → 已还车 → 已完成（含交接单、附加费、变更）
物品租赁	平台指派 / 商户接单	待接单 → 已接单 → 已交付 → 使用中 → 待验收 → 已完成（含损坏登记与押金扣除）

3.5 内容互动主流程

4. F01 账户与用户

4.1 功能概述

四套独立身份体系与各自的资料管理：消费者（微信授权登录）、商户（手机号 + 密码）、平台管理员（账号密码 + 验证码），加上三套身份各自的资料维护入口。

4.2 使用角色与权限

身份	载体	凭证	令牌存储
消费者	App	微信 `wx.login` code + 手机号授权 code	小程序 Storage `token`
商户	MerchantWeb / MerchantApp	手机号 + 密码	Cookie `Merchant-Token`
平台管理员	AdminWeb	账号 + 密码 + 图形验证码	Cookie `Admin-Token`

4.3 前置条件

消费者：已安装携岛小程序；首次登录需同意《用户协议》《隐私政策》。
商户：入驻申请已通过审核，状态为「正常营业」。
平台管理员：已由系统管理员在「系统管理 → 用户管理」中创建并分配角色。

4.4 页面与接口入口

端	页面	关键接口
App	登录页、个人资料、编辑资料、入住人管理、收货地址	`POST /api/app/login`、`PUT /api/app/user/update`、`/api/app/user/guest/`、`/api/app/mall/address/`
MerchantApp	登录、忘记密码、修改密码、商户资料	`POST /api/merchant/login`、`/api/merchant/password/reset/code`、`/api/merchant/password/reset`
MerchantWeb	登录、忘记密码、商户信息、修改密码	同上 + `GET/PUT /api/merchant/info`
AdminWeb	登录、用户管理、角色管理、个人中心	`POST /login`、`/system/user/`、`/system/role/`

4.5 主业务流程

消费者登录

用户在需要登录的功能页触发登录，先弹出协议确认弹窗。
用户勾选协议后点击「微信登录并授权手机号」。
小程序同时取得 wx.login 的 code 与手机号授权 code，一并提交。
后端用 code 换 openid，用手机号 code 换真实手机号，按 openid 查找或注册用户。
返回令牌、用户信息、是否新用户、新人礼包券。
小程序写入令牌、拉取推广码、初始化 OpenIM 会话、尝试绑定推广人。
登录后按原页面参数返回。

商户登录

输入手机号与密码（密码 ≥ 6 位）。
后端校验商户存在、密码正确、账号未禁用。
返回令牌与商户对象；前端据此加载能力矩阵与动态菜单。
商户状态不是「正常营业」时，强制跳转到入驻状态页。

商户忘记密码

输入手机号，获取短信验证码（60 秒冷却）。
填写新密码（6–20 位），两次输入一致。
校验通过后重置成功，返回登录页。

平台管理员登录

输入账号、密码、图形验证码。
后端校验后签发平台令牌。
前端拉取用户信息、角色与权限标识，再拉取动态菜单。
菜单与按钮按权限标识控制可见性。

4.6 状态及状态流转

消费者账号

状态	含义
正常	可正常浏览与下单
禁用	平台侧封禁，无法登录

平台账号：正常(0) / 停用(1) / 删除(2)。

商户账号：见 F02 的商户状态机。

令牌失效：平台令牌到期或改密后失效；消费者令牌由后端判定；商户令牌在商户状态变更后立即失效（每次请求回查数据库）。

4.7 业务规则和计算规则

手机号是商户的唯一身份标识。商户登录用手机号，不用商户 ID，也不用 RuoYi 账号体系。
openid 只在服务端持有，小程序前端从不接触 openid。
推广码 6 位，注册时生成，用于推广归因；推广人绑定发生在注册后首次拉取信息时。
平台端菜单 = 角色 ∩ 菜单权限；按钮再叠加按钮权限；数据范围由角色的数据权限决定。
商户端菜单 = 经营类型 ∩ 已开通能力，与平台端角色权限是两套独立机制。
消费者注册即发新人礼包，礼包内容由平台配置，登录时随响应下发。

4.8 数据输入与输出

对象	关键字段	说明
消费者	id、openid、unionid、昵称、头像、性别、简介、手机号、推广码、注册时间	手机号来自微信授权，可为空
常用入住人	姓名、电话、是否默认	酒店订单预约时使用
收货地址	省市区、详细地址、姓名、电话、是否默认	商城订单使用
商户	手机号、密码（BCrypt）、昵称、头像	密码存储为 BCrypt 摘要

4.9 异常、边界和幂等处理

场景	处理
未登录访问需登录页面	跳登录页并携带来源地址，登录后返回原页面
令牌过期	清除本地登录态、断开 IM 会话、跳登录页
商户状态非正常营业	拦截业务接口，仅放行入驻相关路径（状态查询、缴费、补料重提、取消）
账号被禁用	提示「账号已禁用，请联系管理员」
重复点击提交	前端 1 秒内相同请求直接拒绝；后端按业务键做幂等
验证码错误或过期	明确提示，允许重新获取（受冷却时间限制）
头像/图片上传失败	保留原值，允许重新上传

4.10 消息、短信和自动任务

短信：商户注册验证码、忘记密码验证码、酒店预约提醒三个场景，发送记录写入短信日志，可在平台「内容中心 → 短信日志」查询投递状态。
自动任务：无。

4.11 与其他模块的关系

F01 决定谁能看到 F02–F12 的功能：身份与权限是所有业务模块的前置。
消费者钱包与优惠券余额属于 F06 与 F04，但账户归属 F01。
商户能力矩阵定义在 F02，菜单过滤依赖 F01 的商户身份。

4.12 当前限制

消费者注销：暂无自助注销入口，需平台侧处理。
平台端数据权限（@DataScope）：框架已具备，但业务接口目前未启用，行级数据隔离实际不生效。
重复提交拦截（@RepeatSubmit）：注解已定义但未使用，幂等目前靠各业务自行实现（如退款接口的 Idempotency-Key 请求头）。

5. F02 商户入驻与管理

5.1 功能概述

商户从提交入驻申请到正常营业的完整生命周期：多步入驻、资质 OCR 识别、平台审核与驳回补料、保证金缴纳、经营类型与能力开通、菜单配置、经营位置、资料变更、保证金与关店。

5.2 使用角色与权限

角色	可执行动作
申请人（商户）	填写入驻、提交、查看状态、补料重提、缴保证金、查看须知
平台审核员	审核入驻、驳回、审核结算账户、关店审核、经营位置变更审核
平台运营	配置商户菜单、广播通知、入驻须知、保证金扣款与申诉处理

5.3 前置条件

申请人已具备可接收短信的手机号。
需准备营业执照、身份证正反面、行业资质、结算账户信息。
平台侧需已配置：经营分类树、入驻方案与费用、结算规则、入驻须知、保证金金额。

5.4 页面与接口入口

端	页面	关键接口
MerchantWeb / MerchantApp	入驻申请向导、入驻状态页、我的商户信息、保证金申诉	`POST /api/merchant/apply`、`/api/merchant/resubmit/{id}`、`/api/merchant/upload-and-ocr`、`/api/merchant/upload-and-ocr-idcard`、`/api/merchant/pay/`、`/api/merchant/deposit/penalties/`
AdminWeb	商户管理（8 页签）、入驻须知、商户通知、保证金申诉审核、商户菜单、经营位置变更审核	`/api/admin/merchants/`、`/api/admin/merchant-entry-notices/`、`/api/admin/merchant-notices/`、`/api/admin/merchant-entry-finance/`、`/api/admin/merchantMenu/`、`/api/admin/merchant-location-changes/`

5.5 主业务流程

平台审核动作

在「商户中心 → 商户管理」按状态筛选出待审核商户。
打开商户详情，核对主体信息、证照、经营信息、结算账户、分类与费用。
选择通过或驳回。驳回必须填写原因，原因会推送给申请人。
通过后：金额大于 0 时商户状态变为「待支付」，否则直接置为「正常营业」。

5.6 状态及状态流转

状态码	状态	含义	可执行动作
1	待平台审核	已提交，等待审核	补料重提、取消
2	平台审核驳回	审核未通过	查看原因、补料重提
3	待支付	审核通过，待缴保证金	缴费、取消
4	正常营业	正式经营	全部业务功能
5	关店审核中	已申请关店	查看进度、重新开业
6	已关店	关店完成	重新开业（需补缴费用）
7	已禁用	平台强制禁用	申诉联系平台

保证金状态：已缴、已扣（违约扣款）、可退、冻结中（重开/续费待付）。 结算账户状态：生效中、待审核、已驳回。

5.7 业务规则和计算规则

经营类型决定菜单：本地生活、酒店、商城、租赁属自营型；配送、司机、摄影师、租车属外包型。类型 + 能力矩阵共同决定商户端可见菜单。
分类决定费用与门槛：末级分类决定入驻费、保证金金额、佣金率、所需资质严格程度。
入驻方案分正式与体验：体验期免保证金但有有效期倒计时，可转正式。
三套佣金并存：团购、拼团、活动各一套佣金比例，可在平台侧按商户配置。
结算账户变更需重新审核，通过后替换生效账户；原账户保留历史关联。
保证金可被扣罚：平台可创建违约扣款，商户可申诉，平台裁决后可退回或维持扣款。
敏感信息加密存储：法人身份证号、手机号、银行账号均为密文；平台侧查看明文需单独权限并记录操作日志。

5.8 数据输入与输出

对象	关键字段
商户	经营类型、末级分类、状态、驳回原因、入驻费、保证金、3 套佣金、推广佣金率、新客奖励、主体类型、全部入驻资料、结算账户
入驻须知	作用域（默认/分类）、版本、正文、发布时间
广播通知	标题、正文、目标范围（分类/指定商户）、状态（草稿/已发布/已取消）、确认截止
保证金扣款	扣款原因、证据、金额、申诉记录、审核意见
商户菜单	菜单名、图标、排序、组件路径、适用商户类型、显示状态

5.9 异常、边界和幂等处理

场景	处理
审核通过但商户未付款	状态停留在「待支付」，无法进入经营功能
驳回后重复提交	补料重提恢复为「待平台审核」，历史驳回记录保留
保证金支付回调延迟	提供支付状态轮询接口；小程序轮询直到状态变更
证件 OCR 识别失败	允许手动填写识别结果后继续提交
同一手机号重复入驻	手机号唯一，重复申请会被拒绝
商户状态在操作中途变更	商户接口每次请求回查状态，状态不符立即拦截并跳转状态页
结算账户审核中被反复修改	每次修改生成新的待审核记录，历史可追溯

5.10 消息、短信和自动任务

短信：商户注册验证码、密码重置验证码。
通知：入驻须知发布、广播通知下发、保证金扣款与申诉结果、活动被平台下架、结算底价变更，均通过 IM 卡片消息与平台通知双通道送达。
自动任务：MerchantBroadcastNoticeTask 定期提醒未确认的通知；MerchantOrderNotificationTask 推送新订单与待办。

5.11 与其他模块的关系

F02 决定商户能使用 F03–F11 的哪些能力。
入驻费、保证金与罚款属于 F09 商户财务的口径来源。
商户分类与商品分类共用分类树（F03）。

5.12 当前限制

入驻费与保证金的收款依赖微信支付的 Native 扫码，正式环境需配置商户号与证书。
关店流程为单向状态推进（关店审核中 → 已关店），重新开业需重新缴费。
经营位置变更的审核入口在平台端「商户中心」，无独立菜单项。

6. F03 商品与供应

6.1 功能概述

平台供给侧的核心模块，覆盖 8 个业务类型（酒店、租车、接送、旅拍、物品租赁、商城、套餐、定制游）的商品资料、价格、库存、房态、审核与上下架，以及三者共用的分类、经营模式、定价模式与价格日历体系。

6.2 公共设计

6.2.1 商品信息与三种经营模式

经营模式	谁维护内容	谁定价	商户端能否编辑
自主运营 `MERCHANT_SELF`	商户	商户（受定价模式约束）	可
平台运营 `PLATFORM_MANAGED`	商户提交，平台代运营	平台按底价统一定价	仅可编辑部分字段
平台自营 `PLATFORM`	平台	平台	商户端不展示

状态：待审核(0) / 已通过(1) / 已驳回(2) / 已下架待编辑(3)；活动层另有 待审核(0) / 已上架(1) / 已下架(2) / 已驳回(3) / 平台下架(4)。

6.2.2 定价模式

模式	商户可填	适用
自主定价 `self`	售价、原价	商城商品等
底价模式 `floor`	仅结算底价	团购、拼团、套餐固定使用

底价模式下，平台在审核时设定活动售价，商户无法自行改价。

6.2.3 三套价格日历体系

系统里有三套互不相同但作用相似的日历，极易混淆，必须分清：

日历	管什么	数据粒度	维护方
商品价格日历	团购/拼团/套餐商品的按日价格与库存	商品 + 活动 + 日期	商户填底价加价与库存，平台设活动加价并审核发布
房态日历	酒店房型的按日房价与房量	房型 + 日期	商户填结算底价、库存、可售状态，平台审核发布
库存日历	商户日期库存的调整与留痕	商户 + 对象类型 + 对象 + 日期	平台在商户详情页调整

公共规则

底价加价与活动加价分开存：商户只影响底价，平台只影响售价，互不覆盖。
支持「批量设置」与「应用到全部」；区间上限 366 天。
月度申报：商户按月提交下月的底价加价、库存与可售状态，平台审核后发布到正式日历。
平台侧可「重算」「一键同步商户底价加价」。
已成交订单按下单时的快照结算，改价不影响已成交订单。

6.2.4 通用功能清单

分类树维护、商品资料与图集、购买须知（可关联退款政策）、限购、服务位置（继承门店或移动服务范围多选推荐位置）、销量展示（真实销量与展示销量分离）、提交审核、驳回重提、上下架、删除、价格日历、库存日历、搜索与筛选、热销榜。

6.2.5 用户端浏览入口

入口	接口
商品列表（团购/拼团/套餐/热销榜）	`/api/app/products/**/list`
商品详情	`/api/app/products/{type}/{id}`
分类树	`/api/app/products/category/list`
价格日历	`/api/app/products/price/calendar/{id}`
本店推荐 / 猜你喜欢	`/api/app/products/{type}/{id}/merchant-recommend`、`guess-you-like`
全站聚合搜索	`/api/app/search`

搜索结果按类型分区，列表接口支持 seed 随机打散，保证多次刷新顺序不同。

6.3 F03-01 酒店住宿

子功能	说明
酒店资料	名称、星级、设施、简介、图文视频、营业信息
房型	名称、分类、床型、面积、可住人数、总房间数、设施、结算底价；新增后自动提审
房态日历	逐日底价、库存、可售开关；支持按日期范围或按星期批量设置
房型审核	平台审核结算底价与平台售价，通过或驳回
房态审核	逐条或批量通过/驳回；驳回需填原因
月度房态审核	逐行通过/驳回，或「审核并发布」一次性发布
预约申请	团购/套餐场景下用户提交预约申请，商户确认/协商/拒绝
酒店套餐	平台组装的房型 + 商品组合，含折扣规则与价格日历

预约三态：待确认 → 已成立 / 协商中 / 已撤销；协商中可能转入「待补差」。

房型与商品的关系：客人「直接订房」走房型房态日历；客人「买套餐」走商品价格日历，且套餐含房型时可用房量受房型库存约束（取交集）。

6.4 F03-02 租车

子功能	说明
车型分类	分类名称、图标、排序、状态
车型	品牌、型号、参数、座位数、图片、日租价；平台维护
车辆	平台车型 + 车牌 + 基础出车价 + 照片 + 可出车状态；由车行维护
车辆报价日历	按日可出车/不可出车 + 每日出车价，支持表格批量保存
增值服务	计价方式（按次/按天/按数量/按天数量）、用户售价、平台分成、商户分成、是否必选
可用性查询	按取还车日期、地点、时段校验车辆可用性
派单与交接	见 F07
变更与附加费	见 F07、F08

6.5 F03-03 接送服务

子功能	说明
固定路线	出发地、目的地、距离、经济型/豪华型价格；上下架
出租车价目	分段：起步价、起步公里、每公里价、平台抽成
包车价目	车辆类型、包车类型（按小时/按天）、单价、平台抽成、最低预订量
自定义行程	起终点选点 + 距离与价格预估（腾讯地图真实驾车距离）
司机与车辆	司机登记车辆、上下线状态

6.6 F03-04 旅拍

旅拍套餐（拍摄时长、地点、摄影师结算价、上下架）+ 派单（摄影师指派、接单、拍摄、交付）。详见 F07。

6.7 F03-05 物品租赁

子功能	说明
租赁商品	规格、起租日、库存日历、押金模式、评价
库存日历	逐日可租数量与价格
押金	两种模式：微信支付分与预付押金
派单与履约	接单、交付、验收、损坏上报与押金扣除，见 F07
评价	评分、图片、匿名、商户回复、平台隐藏与恢复

租赁商品由平台统一上架，商户端不提供租赁商品管理入口。

6.8 F03-06 商城

子功能	说明
商品与 SKU	标题、分类、品牌、单位、重量、主图、详情图、多规格 SKU（SKU 编码、规格、规格图、供货结算价、原价、库存）
专区	每日秒杀、补贴专区、海南特产专区；平台可设置专区定价与专区标签
审核	平台审核商品与价格，驳回需填原因
上下架与补货	商户自助上下架、按 SKU 补货
订单与发货	见 F05、F07
供货结算价与平台售价	页面同时展示「供货结算价」「平台售价」「单件差额」

6.9 F03-07 套餐

子功能	说明
套餐结构	基本信息 + 分组 + 区域段 + 行程段
商品池	从在售商品中选择，平台维护各商品底价与平台售价
组合与分摊	下单后按分组拆分为多笔子订单，价格按规则分摊到各商品
折扣规则	套餐级折扣，生效时按规则计算最终售价
价格日历	套餐按日价格，平台可批量设置
成本分析	展示套餐成本构成与毛利
固定套餐与自选套餐	固定套餐按预设组合成交；自选套餐由用户在必选/可选项目间勾选并动态计价

6.10 F03-08 定制游

子功能	说明
套餐型定制游	平台维护的定制套餐，按天/段/组解析行程，用户勾选必选与可选项目
1 对 1 定制	用户提交需求（城市、出发地、日期、人数、预算、酒店等级、节奏、偏好），平台分配旅行顾问
需求阶段	13 阶段带迁移白名单，见下表
行程方案与报价	顾问制作方案与报价，发布给用户；用户可接受或要求修改
转订单	报价确认后生成待支付订单

定制游阶段流转

阶段	含义	可转向
SUBMITTED	已提交需求	ASSIGNED / CANCELLED / CLOSED
ASSIGNED	已分配顾问	REQUIREMENT_CONFIRMED / CANCELLED / CLOSED
REQUIREMENT_CONFIRMED	需求已确认	PLAN_DRAFTING / CANCELLED / CLOSED
PLAN_DRAFTING	方案制作中	PLAN_SENT / CANCELLED / CLOSED
PLAN_SENT	方案已发送	PLAN_DRAFTING / PLAN_CONFIRMED / CANCELLED / CLOSED
PLAN_CONFIRMED	方案已确认	PLAN_DRAFTING / QUOTE_SENT / CANCELLED / CLOSED
QUOTE_SENT	报价已发送	PLAN_CONFIRMED / WAIT_PAYMENT / CANCELLED / CLOSED
WAIT_PAYMENT	待支付	PAID / CANCELLED / CLOSED
PAID	已支付	IN_SERVICE / CLOSED
IN_SERVICE	服务中	COMPLETED / CLOSED
COMPLETED	已完成	—
CANCELLED	已取消	—
CLOSED	已关闭	—

阶段迁移由状态机强制校验，非法迁移直接拒绝并提示当前阶段与目标阶段。

6.11 F03 通用规则与限制

审核驳回必须填原因，商户端展示驳回原因并允许修改后重新提交。
已成交订单不受后续改价影响，价格以下单时的快照为准。
展示销量与真实销量分离：真实销量由支付链路维护，平台与商户可单独调整展示销量；热销榜的人工排序可一键「恢复自动计算」。
位置筛选只对参与位置运营的业务生效（酒店、团购、租赁、本地生活），电商商城商品不参与位置筛选。
微信支付分默认 mock 模式，需显式配置后才走真实支付分。
优惠券适用分类与商品分类树绑定，新增分类时需确认是否纳入券范围。

6.12 与其他模块的关系

F03 的商品与活动是 F05 订单的输入。
F03 的底价直接决定 F09 商户收入。
F03 的可售状态与价格日历决定 F04 优惠能否用（券门槛、拼团价）。
F03 的审核结果通过 F11 通知商户。

6.13 当前限制

平台代运营商品的交付与投放为半自动流程，平台需人工确认。
租赁商品管理仅平台侧可用，商户端只做履约与评价。
套餐报名入口在商户端已废弃，统一改为「商品管理」中按类型筛选。
销量数据依赖支付链路实时回写，测试或手工造数环境下展示销量与真实销量可能不一致。

7. F04 营销活动

7.1 功能概述

平台与商户侧的促销与优惠体系：优惠券模板与发放、新人礼包与券包、团购/拼团等促销活动、热销推荐，以及下单时的优惠试算、分摊、占用、核销与退还。

7.2 使用角色与权限

角色	可执行动作
消费者	领券、领券包、使用券、管理我的券包与核销券
商户	报名活动、查看活动价与审核状态、驳回后重新报名、配置券的承担方
平台运营	维护券模板、发券、配置券包与新人礼包、维护活动与售价、配置热销榜、配置推广规则

7.3 前置条件

券模板已创建并发布（存在已发布版本），否则用户端无券可领。
活动需先有在售商品，商户方能报名。
推广提现需商户已开通推广能力并绑定结算账户。

7.4 页面与接口入口

端	页面	关键接口
App	首页、领券中心、优惠礼包、我的优惠券、拼好团、正在拼团、我的推广	`/api/app/coupons/`、`/api/app/groups/`、`/api/app/promotion/**`
MerchantWeb / MerchantApp	可报名活动、活动记录、活动详情、券的承担配置	`/api/merchant/product-activities/**`、`/api/merchant/activity-refund-config`
AdminWeb	优惠券模板、优惠券发放、新人礼包/券包、活动管理、拼团管理、推广管理、热销推荐	`/api/admin/coupon-templates/`、`/api/admin/coupon-grants/`、`/api/admin/coupon-bundles/`、`/api/admin/product-activities/`、`/api/admin/groups/`、`/api/admin/promotion/`、`/api/admin/hot-sale/**`

7.5 主业务流程

优惠券生命周期

拼团流程

商户报名活动 → 平台审核 → 平台设定活动售价 → 上架。
用户选择「发起拼团」或「加入拼团」，支付后进入待成团。
成团成功 → 订单转为已支付、生成券码。
超时未成团 → 系统自动全额退款（按配置的自动退款时限）。
超窗成团 → 按惩罚费率扣手续费（XdPintuanCategoryConfig.penaltyRate），含商户钱包扣减。

多选拼团：按拼团规则需选 N 件，实时合计后批量下单。

7.6 状态及状态流转

券模板：草稿 / 已发布版本 / 停用。已发布版本可被用户领取，编辑不影响已领取的券。

用户券状态：未使用 / 已使用 / 已过期 / 已锁定（下单占用）/ 已释放 / 已返还 / 已退款。

活动状态：待审核(0) / 已上架(1) / 已下架(2) / 已驳回(3) / 平台下架(4)。

推广主体状态：待审核 / 生效 / 停用；提现状态待处理 / 审批通过 / 已打款 / 已驳回 / 打款失败 / 风险审核。

7.7 业务规则和计算规则

券类型：满减（FULL_REDUCTION）与直减（DIRECT_REDUCTION）两种。
资金承担方：默认商户承担，可配置为本商户承担或平台承担；承担比例影响下单分摊与退款时的责任划分。
优惠分摊：多商品订单中，优惠按基数分摊到各商品，尾差用最大余数法处理，保证分摊金额之和等于优惠总额。
最优券推荐：下单页展示可用券并标注推荐使用的那张。
拼团超时时限由平台配置，可手动触发处理超时拼团。
多选拼团规则由平台配置（下限件数等），商户不参与。
推广佣金：按层级规则计算，主体与等级规则由平台配置；提现需审核。
热销榜：真实销量决定自动排名，平台可人工覆盖排序，也可一键恢复自动计算。
团购/拼团/套餐固定使用底价模式，活动售价由平台定价，商户不自行定价。

7.8 数据输入与输出

对象	关键字段
券模板	面额、门槛、类型、适用分类、有效期、资金承担、领券中心开关、启停
券包	包含的券集合、领取规则（N 选 K）、领取时间窗
新人礼包	礼包内容、领取时间、券有效期
发券批次	批次号、目标用户、发放结果、失败原因
推广主体	主体类型、等级、合作期限、绑定关系、佣金
拼团	拼团规则、成团人数、超时时限、惩罚费率

7.9 异常、边界和幂等处理

场景	处理
重复领取同一券	幂等，已领则返回已有券
券过期	结算时校验有效期，过期券不可用并在下单页隐藏
券被他人先占用	结算时二次校验，占用失败时提示重新选择
拼团超时	后台任务自动处理；平台也可手动触发
优惠金额超过订单金额	截断为订单金额，不产生负数订单
退款式时券已核销	按券的实际消耗状态判定，退还或折算为金额
发券失败	批次内逐条记录失败原因，可重试

7.10 消息、短信和自动任务

消息：用户领券成功、券即将过期（由小程序侧展示）、推广佣金到账、提现审核结果。
自动任务：拼团超时处理（XdGroupTimeoutTask）、券码过期（XdVoucherExpireTask）、推广结算。

7.11 与其他模块的关系

F04 的优惠在 F05 下单时被试算，在 F06 支付时实际扣减，在 F08 退款时按分摊结果退还。
F04 的活动售价建立在 F03 的底价之上。
推广主体与佣金最终进入 F09 财务结算。

7.12 当前限制

推广管理的提现审核在平台端「平台配置 → 推广管理」内，非独立菜单。
券模板的编辑只改草稿，已发布版本需重新发布才生效。
拼团超时处理依赖定时任务，任务异常时需要平台手动触发。
推广二维码依赖 Canvas 绘制，个别低端机型可能失败。

8. F05 订单交易

8.1 功能概述

统一下单、金额计算、合单合并支付、订单状态机与展示状态，是全系统最核心的交易枢纽。

8.2 使用角色与权限

角色	可执行动作
消费者	下单、支付、取消、删除、申请退款、确认收货、查物流、核销码查看
商户	查看本商户订单、核销、审批退款、发货、处理预约
平台	查看全部订单、合单详情、退款审核、核销券码、订单事件审计

8.3 前置条件

商品在售、价格日历覆盖目标日期、库存充足。
消费者已登录（游客仅可浏览）。
涉及支付的订单需完成微信支付或钱包余额支付。

8.4 页面与接口入口

端	页面	关键接口
App	各业务确认订单页、我的订单、订单详情、支付结果	`/api/app/orders/`（groupbuy / pintuan / package / room / transfer / mall）、`/api/app/pay/`
MerchantWeb / MerchantApp	订单列表、订单详情、核销弹窗、预约处理	`/api/merchant/orders/`、`/api/merchant/hotel/appointments/`
AdminWeb	订单管理（订单概览 + 合单流水）、退款审核	`/api/admin/orders/`、`/api/admin/fixed-package-refunds/`

8.5 主业务流程

下单编排

前端提交业务参数（商品 ID、数量、日期、房型、规格等）。
后端按活动类型取对应处理器，产出订单草稿（订单头 + 明细）。
Orchestrator 自行汇总金额，不采信请求传入的金额。
写订单主表与明细，状态置为「待支付」。
前端跳支付。

合单（伪合单）

重要口径：微信服务商合单支付与特约商户号分账已下线，当前为伪合单模型。

子单 = 一笔订单；合单 = 共享同一父单号的多笔订单。
多笔子单的支付金额汇总后发起一笔 JSAPI 预支付。
支付回调按父单号批量把子单标记为已支付。
券核销、钱包扣减在子单粒度逐笔处理。

订单号前缀

前缀	业务	前缀	业务
PH	房	TF	接送
CR	车	RM	房型
IR	物品	PK	套餐
ML	商城	OD	团购

预支付使用 PAY_ 前缀作为微信商户单号。

8.6 状态及状态流转

主状态（6 个，持久化）

状态	码	含义
PENDING_PAY	0	待支付
PAID	1	已支付
REFUNDING	2	退款中
REFUNDED	3	已退款
CANCELLED	4	已取消
COMPLETED	5	已完成

迁移规则

动作	从	到
markPaid	PENDING_PAY	PAID
cancelPendingOrder	PENDING_PAY	CANCELLED
complete	PAID	COMPLETED
startRefund	PAID / COMPLETED	REFUNDING
markRefunded	REFUNDING	REFUNDED
restoreAfterRefundFailed	REFUNDING	退款前的原状态

结算状态：NONE → PENDING_SETTLE → AVAILABLE → DEDUCTED。

展示状态（17 个，计算得出，不持久化）

每次状态迁移都写入一条订单事件审计日志（原状态、新状态、操作人、业务 ID）。

8.7 业务规则和计算规则

服务端算钱：订单总额由明细汇总，前端传入金额仅作参考。
多晚住宿拆单：跨夜的酒店订单按每晚拆价，价格取对应日期的价格日历。
拼团与套餐为「下单即预约」，团购为「囤券预约制」：团购先买券，再单独提交预约申请。
补差价：预约日期与核销日期发生变化时，产生差价订单，走「补差价」活动类型。
优惠分摊：券与钱包优惠按基数分摊到各明细，尾差用最大余数法归并。
佣金：平台佣金在支付回调时写入明细的商户应收字段，不调用微信分账接口。
快照：下单时保存商品、价格、优惠、佣金的比例与数值快照，后续变更不影响该单。
订单可见性：消费者只见自己的；商户只见自己的；平台可见全部。商户端按商户 ID 强制隔离。

8.8 数据输入与输出

对象	关键字段
订单	订单号、父单号、用户、商户、活动类型、支付金额、优惠金额、钱包金额、佣金、状态、结算状态、父单关联
明细	单价、支付手续费、商户应收、佣金率、商品快照、优惠分摊
订单事件	原状态、新状态、操作人、业务 ID、时间
核销券	券码、状态、预约起止、核销时间

8.9 异常、边界和幂等处理

场景	处理
重复提交下单	服务端按业务键幂等；前端 1 秒内同参请求直接拒绝
支付回调与主动查单同时到达	状态机用「乐观并发 + 0 行判定」保证只生效一次
订单超时未支付	定时任务关单，支付主单一并关闭
取消与支付并发	由状态机裁决：已支付则取消失败，提示走退款
库存被抢完	下单时校验失败，明确提示剩余量
价格日历无当日数据	按商品默认价计算，提示运营补齐日历
删除订单	仅允许删除不影响资金与履约的订单；已支付订单不可删
合单部分子单支付失败	父单级回调按子单粒度回填，部分成功时逐单处理

8.10 消息、短信和自动任务

消息：新订单通知商户、订单状态变化通知用户、平台待办提醒。
自动任务：支付超时关单、已支付订单的补偿处理、拼团超时、券码过期、商城超期自动确认收货。

8.11 与其他模块的关系

F05 是 F03（商品）、F04（优惠）、F06（支付）、F07（履约）、F08（售后）、F09（结算）的交汇点。
F05 的金额构成直接决定 F09 的商户收入与 F08 的退款分摊。

8.12 当前限制

合单为伪合单：不涉及微信服务商侧的真实合单支付与分账。
订单事件审计无独立查询页面，需通过数据库或日志查看。
补差价依赖履约环节触发，用户无法自助发起。
删除订单为物理删除，删除前需确认无资金与履约关联。

9. F06 支付与退款

9.1 功能概述

微信支付 V3 的接入与编排、钱包余额支付、退款的申请—审核—执行—回调全链路，以及商户个体结算与账单对账。

9.2 使用角色与权限

角色	可执行动作
消费者	发起支付、确认支付结果、查询支付状态
商户	审批退款、查看退款状态
平台	退款审核、触发结算任务、查看对账结果与微信交易履约

9.3 前置条件

微信支付商户号、证书、私钥与平台公钥已配置（PlatformWechatPayConfig 启动时强校验，缺失直接启动失败）。
退款需对应的支付主单存在。

9.4 页面与接口入口

端	页面	关键接口
App	收银台、支付结果页	`POST /api/app/pay/prepay`、`/api/app/pay/confirm`、`GET /api/app/pay/status`、`/api/app/pay/notify`、`/api/app/pay/refund-notify`
MerchantWeb / MerchantApp	订单详情退款审批	`PUT /api/merchant/orders/{id}/refund`
AdminWeb	退款审核、微信交易履约、钱包流水	`PUT /api/admin/orders/refund/audit`、`/api/admin/wx-trade/fulfillment/**`

9.5 主业务流程

支付

退款

用户提交申请（支持 Idempotency-Key 幂等键）。
退款引擎按业务分类与规则版本计算可退金额、手续费与渠道分摊。
商户或平台审批；通过后按渠道（微信/钱包）分别执行退款。
微信退款异步回调：SUCCESS 回填并推进订单为已退款；CLOSED 回滚订单状态；ABNORMAL 转人工。
钱包退款即时到账。

9.6 状态及状态流转

支付主单：PENDING / SUCCESS / CLOSED / REFUNDING / REFUNDED。

退款单：PENDING / PROCESSING / SUCCESS / FAILED / PARTIAL_REFUNDED。

退款申请（新版引擎）：PENDING → APPROVED → REFUNDING → SUCCESS / FAILED / REJECTED。

微信交易履约：支付单级状态机，单调前进，乐观锁防回退。

微信退款单状态：PROCESSING / SUCCESS / CLOSED / ABNORMAL。

9.7 业务规则和计算规则

两套支付配置：当前唯一启用的是 PlatformWechatPayConfig（平台直连）。服务商模式 WechatPayConfig 已删除，无代码残留。
支付分独立配置，含 mockMode 开关，默认 mock。
渠道分摊：一笔订单可同时用微信与钱包支付，两者金额分开记录与退款。
手续费：微信支付手续费（0.6%）在商户与平台之间按规则分摊，写入明细。
退款计算：按业务分类（团购、拼团、套餐、固定套餐、自选套餐、酒店、租车、商城、接送）选择对应的计算器；规则支持阶梯（距锚点时间 → 退款比例）与时间窗口两种形态。
不依赖 Java 短路幂等：退款状态更新用 SQL 条件（WHERE wx_status != 'SUCCESS'）兜底，支持自愈。
个体结算：司机与摄影师的收入通过微信「商家转账到零钱」批次发放，按 openidAppid 分组，每日 02:00 生成批次、03:00 查询结果；失败最多重试 3 次。
对账：每日 10:30 下载前一日微信账单，逐笔与本地支付记录比对，记录金额差异与单边缺失。

9.8 数据输入与输出

对象	关键字段
支付主单	支付单号、总额、微信金额、钱包金额、状态、过期时间、版本号
支付-订单关联	支付单 ↔ 订单，微信/钱包分摊金额
退款记录	退款单号、支付单、退款前订单状态、微信退款状态、钱包退款状态、退款类型、微信退款号、失败码
退款规则	分类、已发布版本、草稿、状态、生效时间
账单对账	账单日期、订单号、微信交易号、微信金额、本地金额、差异金额、状态
个体结算	结算日期、订单、工人、openid、金额、批次号、明细号、状态、重试次数

9.9 异常、边界和幂等处理

场景	处理
支付回调丢失	定时任务查单兜底（每 2 分钟），命中 SUCCESS 即补偿推进
用户取消支付	支付结果页显示取消态，订单仍为待支付，可继续支付
支付成功但订单未更新	支付结果页主动查单 + 定时任务双保险
预支付过期	支付主单过期自动关单；用户需重新发起
微信退款 CLOSED	恢复订单到退款前状态，通知用户
微信退款 ABNORMAL	标记人工介入，平台侧处理
混合支付退款的渠道到账时间差	微信与钱包分别到账，可能不同步，文档与客服话术需明确
回调验签失败	返回 500，触发微信重试；业务异常返回 200 避免无效重试
结算批次部分失败	记录失败明细与重试次数，3 次后停止

9.10 消息、短信和自动任务

任务	频率	职责
支付单过期关单	30 秒	关闭超时未支付订单
支付查单兜底	2 分钟	查微信订单状态，补偿推进
退款状态同步	5 分钟	同步退款进度
微信账单对账	每天 10:30	下载并比对前一日账单
个体结算批次	每天 02:00 / 03:00	生成批次并查询结果
商户钱包结算	每天 01:00	结算与分成入账
微信发货同步	每 5 分钟	同步商城发货信息
商城自动确认收货	每天 02:00	超 15 天未确认自动确认

9.11 与其他模块的关系

支付金额来自 F05 订单，退款金额受 F08 规则约束。
支付成功是 F07 履约开始的触发点。
结算入账进入 F09 商户钱包。

9.12 当前限制

微信服务商利润分账：暂未实现。系统以「平台内部账本结算」替代，文档与客服话术不得表述为微信分账。
微信支付分：默认模拟，mock-mode=true 时不产生真实服务订单。
对账无独立页面：结果在日志与数据库中，平台端没有对账菜单。
支付分回调处理不完整：PayScoreNotifyController 未做验签与 AES 解密，属于待完善项。
退款状态同步存在两份近似实现（RefundSyncTask 与 RefundStateSyncTask），行为可能有细微差异。

10. F07 履约管理

10.1 功能概述

下单之后的实际交付：预约申请处理、派单调度、核销、交接单、发货收货、变更与附加费、补差价。

10.2 使用角色与权限

角色	可执行动作
消费者	提交预约、确认交接、确认收货、发起变更、支付额外费用、评价
商户	接单/拒单、履约操作、核销、发货、发起附加费、响应变更
司机	上线/下线、接单、开始行程、完成行程（上报 GPS）
摄影师	接单、开始拍摄、交付作品
平台	指派与调度、审核交接与费用、处理异常、结算

10.3 前置条件

订单已支付（履约类订单）。
履约主体已具备对应能力（外包型商户）。

10.4 页面与接口入口

端	页面	关键接口
App	订单详情、交接单、变更、变更差价支付、额外费用、账单、评价、商城订单详情	`/api/app/car-rental/`、`/api/app/rental/`、`/api/app/photography/`、`/api/app/hotel/appointments/`、`/api/app/wx-trade/**`
MerchantApp	扫码核销、核销确认、派单处理、派单详情、额外费用、变更申请、变更报价核对、累计账单、车队与报价日历、预约处理、商城订单与发货	`/api/merchant/orders/`、`/api/merchant/car-rental/dispatch/`、`/api/merchant/rental/dispatch/`、`/api/merchant/photography/dispatch/`、`/api/merchant/transfer/orders/`、`/api/merchant/mall/orders/`
MerchantWeb	同上，另加调度台（租车/接送/旅拍）	`/api/merchant/**`
AdminWeb	租车调度台、接送调度、旅拍派单、拼团管理、微信交易履约	`/api/admin/car-rental/dispatches/`、`/api/admin/transfer/dispatch/`、`/api/admin/photography/dispatches/`、`/api/admin/groups/`

10.5 主业务流程

四条履约线

业务线	状态链	关键动作
专车接送	待接单 → 已接单 → 行程中 → 已完成	平台指派或司机接单；开始与完成上报经纬度
旅拍	待接单 → 已接单 → 拍摄中 → 已交付 → 已完成	交付作品链接与交付说明
租车	待接单 → 已接车 → 已取车 → 还车中 → 已还车 → 已完成	取还车交接单（照片/里程/油量）、确认交车、拒收、验收备注
物品租赁	待接单 → 已接单 → 已交付 → 使用中 → 待验收 → 已完成	交付照片、归还照片、损坏登记与押金扣除

扫码核销（两步式）

商户扫码或手动输入券码 → 系统查出该订单下的券码列表。
勾选本次要核销的券（仅未使用与已预约可选）→ 批量核销。
核销后券状态置为已核销，订单展示状态同步更新。

租车变更

用户发起变更申请（续租 / 改期 / 换车 / 提前还车）。
平台或商户制定变更方案（新报价、还车依据）。
商户核对报价，确认或声明无法履约。
用户接受方案并支付差价（钱包与微信可分摊）。
差额与库存同步，方案过期需重新制定。

租车额外费用

商户发起额外费用（逾期、油电差额、超里程、损坏、违章、其他），需附照片凭证；用户可接受或提出异议；异议转售后由平台审核并可重试；用户支付后计入累计账单。

10.6 状态及状态流转

履约对象	状态链
租车派单	待派单(0) → 待接单(1) → 已接单(2) → 已取车(3) → 还车中(4) → 已还车(5) → 已完成(6)；取消(7)、拒绝(8)
旅拍派单	待派单(0) → 待接单(1) → 已接单(2) → 准备中(3) → 拍摄中(4) → 已交付(5) → 已完成(6)；取消(7)、拒绝(8)
租赁派单	待接单(0) → 已派单(1) → 已接单(2) → 已交付(3) → 使用中(4) → 待验收(5) → 已完成(6)；取消(7)、异常(8)
接送订单	待支付 → 待派单 → 派单中 → 已接单 → 行程中 → 已完成；取消、退款
酒店预约	待确认(0) → 已成立(1) / 协商中(2) / 已撤销(3) / 待补差(4)
商城订单	待发货 → 已发货 → 已签收；另有退款与售后
交接单	待确认 → 已确认 / 有异议；带历史版本对比与自动完成倒计时
变更申请	待处理 → 方案制定中 → 待商户核对 → 用户确认 → 差价处理中 → 完成；或无法履约、已撤回、已过期
额外费用	待确认 → 平台处理中 → 待支付 → 已支付 / 已免收 / 已撤回 / 已退款

10.7 业务规则和计算规则

派单可自动或手动：平台按规则指派，也可手动指派或撤回重派。
拒单必须填原因，原因对用户可见。
交接单是快照：签署时保存条款、照片与损坏照片，后续变更保留历史版本供对比。
费用必须有凭证：额外费用与损坏登记需上传照片，商户侧不可无凭证发起。
变更差价双校验：按方案快照 hash 与须知版本双重校验，防止方案被篡改或过期。
佣金与分成在结算时写账：司机应得、摄影师结算、平台分成在完成环节计算，不实时打款。
租借押金两种模式：微信支付分与预付押金。损坏时按登记金额从押金扣除，剩余部分退还。
发货信息同步微信：商城发货后调用微信「发货信息管理」上传物流信息，失败重试 5 次后转人工。

10.8 数据输入与输出

对象	关键字段
派单	订单、履约主体、状态、预约时间、接单时间、交接单 id
交接单	类型（取车/还车）、里程、油量、照片、损坏照片、条款快照、版本
变更申请	变更类型、期望取还车时间、申请原因、商户意见、状态、事件流
变更方案	调整项、差额、状态、候选车型、还车依据
额外费用	费用类型、单价、数量、计费依据、凭证、状态、售后记录
累计账单	按费用类型分组的应付/已付/已退/待付明细

10.9 异常、边界和幂等处理

场景	处理
派单超时未接单	定时任务超时处理，可重新指派
用户对交接单有异议	进入争议流程，双方补充证据，平台裁定
变更方案过期	需重新制定，旧的差价支付入口失效
差价支付重复提交	幂等键 + 快照校验，重复提交返回同一结果
额外费用被用户争议	转平台审核，支持重试与关联原退款单
微信发货同步失败	记录失败原因与重试次数，5 次后转人工（`GIVEUP`）
商城超 15 天未确认	定时任务自动确认收货
押金退还失败	记录失败并支持重试，不影响订单完成

10.10 消息、短信和自动任务

短信：酒店预约申请与协商的短信提醒。
消息：派单指派、接单、开始服务、交付、变更、费用通知；结算底价变更也会以卡片消息推送商户。
自动任务：派单超时、变更完成、变更退款、附加费退款、租赁超期、订单履约通知。

10.11 与其他模块的关系

F07 是 F05 订单支付后的执行阶段，涉及 F03 的库存与 F08 的退款。
履约完成触发 F09 的结算入账。

10.12 当前限制

司机 GPS 仅在开始与完成行程时上报，不是持续轨迹。
交接单无电子签名，以确认动作与照片为凭据。
租借损坏赔付依赖押金扣除，超出押金部分需线下协商。
租车变更链路复杂，用户侧与商户侧对「方案确认」的含义需分别阅读对应章节。

11. F08 售后服务

11.1 功能概述

退款申请、审核、按规则计算、分渠道执行、进度跟踪与自动超时退款。退款规则按业务分类独立维护，支持草稿与已发布版本双轨。

11.2 使用角色与权限

角色	可执行动作
消费者	申请退款、查看进度、取消申请（未审核时）、发起售后
商户	同意或拒绝退款申请、查看待处理列表
平台	退款审核、规则配置与发布、附加费售后审核

11.3 前置条件

订单已支付，且在规则允许的退款窗口内。
对应业务分类的退款规则已有已发布版本。

11.4 页面与接口入口

端	页面	关键接口
App	申请售后、订单详情的退款入口、额外费用售后	`POST /api/app/refund-applications`、`POST /api/app/orders/{id}/refund`、`/api/app/car-rental/charges/{id}/aftersales`
MerchantWeb / MerchantApp	售后处理、订单详情退款审批、商城退款审核、额外费用售后	`/api/merchant/refund-applications/`、`PUT /api/merchant/orders/{id}/refund`、`/api/merchant/mall/refunds/`
AdminWeb	退款审核、退款规则配置、附加费售后审核	`PUT /api/admin/orders/refund/audit`、`/api/admin/refund-policies/`、`/api/admin/car-rental/charges/aftersales/`

11.5 主业务流程

11.6 状态及状态流转

退款申请：PENDING → APPROVED → REFUNDING → SUCCESS / FAILED / REJECTED；另有自动超时直接通过。

退款触发类型：用户申请 / 自动超时 / 拼团未成团 / 平台取消 / 租车联动退款。

退款业务分类：团购、拼团、套餐、固定套餐、自选套餐、酒店、租车、商城、接送。

规则版本状态：草稿 / 已发布 / 停用。

11.7 业务规则和计算规则

规则按分类独立，每类可配置不同形态：固定规则、阶梯规则（距锚点时间 → 退款比例档位）、时间窗口规则。
双轨版本：编辑只改草稿，发布需二次确认，发布后才影响新申请。已提交申请按申请时的规则版本计算。
拼团三分支：
- 未成团 → 全额退（user_cancel）；
- 免费窗口内成团 → 全额退；
- 超窗成团 → 扣手续费（pintuan_penalty，按分类惩罚费率，含商户钱包扣减）。
预约撤销 → 撤销预约并退款。
部分退款：需校验可退余额，手续费按比例分摊。
混合支付退款：微信与钱包分别退回，到账时间可能不同。
规则计算基于快照：退款时重新读取订单快照，不使用当前商品配置。

11.8 数据输入与输出

对象	关键字段
退款申请	退款单号、订单、类型、状态、金额、渠道、审核人、审核意见、快照
退款规则	分类、规则名、已发布版本、草稿、生效时间、状态
退款快照	下单时的价格、优惠分摊、佣金、已用资源摘要
附加费售后	费用、原因、凭证、状态、审核意见、重试次数

11.9 异常、边界和幂等处理

场景	处理
重复申请退款	使用 `Idempotency-Key`，同一订单重复提交返回同一结果
审核与自动超时并发	状态机裁决，已处理的不再变动
规则未发布	无法计算时拒绝申请并提示配置缺失
退款金额超过实付	校验拦截，按可退余额上限处理
券已核销	按实际消耗判定，核销后退还为金额或按比例折算
微信退款异步未回	定时任务同步状态
附加费售后失败	支持重试，关联原退款单
部分退款后再次退款	按剩余可退余额校验

11.10 消息、短信和自动任务

消息：退款提交、审核结果、到账通知。
自动任务：退款状态同步、退款执行（RefundPayoutTask）、商城退款审核超时、附加费退款。

11.11 与其他模块的关系

F08 消费 F05 的订单快照与 F04 的优惠分摊结果。
退款完成后影响 F09 的结算与钱包余额。
退款规则对用户端可见，App 会展示「退款政策提示」。

11.12 当前限制

阶梯规则与时间窗口规则为较新能力，历史订单不追溯。
退款审核无批量操作，需逐条处理。
微信退款到账由微信侧决定，平台无法保证具体时间。
拼团惩罚费率由分类配置，配置缺失时按默认规则处理。

12. F09 商户财务

12.1 功能概述

商户的资金全链路：订单收入入账、钱包余额构成、结算解冻、提现审批、保证金与违约扣款、申诉处理、入驻费用与体验期续费。

口径提醒：当前商户结算是平台内部账本结算，不调用微信服务商利润分账接口。所有面向商户与客服的表述都必须用「平台内部结算」，不要用「微信分账」。

12.2 使用角色与权限

角色	可执行动作
商户	查看余额与流水、申请提现、维护结算账户、缴纳保证金、提交扣款申诉、续费
平台财务	审批提现、标记打款、查看打款账户明文、创建违约扣款、裁决申诉、触发结算任务
消费者	查看个人钱包余额与流水（属 F06 口径）

12.3 前置条件

商户状态为「正常营业」。
提现需已绑定并通过审核的结算账户。
保证金相关操作需平台已配置扣款规则。

12.4 页面与接口入口

端	页面	关键接口
MerchantWeb	财务中心（经营概览/资金账单/提现管理）、收入明细、结算信息、统计	`/api/merchant/wallet/`、`/api/merchant/income/`、`/api/merchant/stats/**`
MerchantApp	财务中心、结算流水、申请提现、结算信息、保证金扣款	同上 + `/api/merchant/deposit/**`
AdminWeb	提现管理、钱包与流水、入驻财务与保证金、微信结算规则、微信交易履约	`/api/admin/wallet/`、`/api/admin/wallets/`、`/api/admin/merchant-entry-finance/`、`/api/admin/wechat-settlement-rules/`

12.5 主业务流程

收入到账

提现

商户在财务中心查看可提现余额、户名与掩码账号。
填写提现金额（不超过可提现余额），提交申请。
平台在「财务中心 → 提现管理」核对商户、金额、可用余额与结算账户。
审批通过 → 线下打款 → 在平台标记「已打款」并上传汇款凭证。
打款失败 → 标记「打款失败」，余额退回商户可提现。
审批驳回 → 填写驳回原因，商户可见。

保证金扣款与申诉

平台在商户详情创建违约扣款，记录原因与证据，冻结或扣减保证金。
商户在「我的商户信息」看到扣款记录，可提交申诉（附证据与说明）。
平台在「保证金申诉」页面裁决：驳回并维持扣款 / 通过并退回保证金。
裁决结果与证据回传商户。

12.6 状态及状态流转

钱包余额构成（6 项）

科目	含义
可提现	可发起提现的余额
交易冻结	支付中冻结的金额
待结算	已完成但未到结算周期的金额
提现中	已申请提现的金额
累计入账	历史累计收入
累计已提现	历史累计提现

资金流水类型（8 类）：支付成功（交易冻结）、订单入账（待结算）、结算可用、退款扣减、提现冻结、提现驳回退回、提现打款、打款失败退回。

提现状态：待处理 / 审批通过 / 已打款 / 已驳回 / 打款失败 / 风险审核。

保证金状态：已缴 / 已扣 / 可退 / 冻结中；申诉状态：未申诉 / 待审核 / 已通过 / 已驳回。

结算账户状态：生效中 / 待审核 / 已驳回。

12.7 业务规则和计算规则

佣金在支付回调时确定：写入订单明细的商户应收字段，不在结算时重新计算。
结算周期由平台配置（当前为次日 01:00 批量结算），商户可在财务页看到预计结算收入趋势。
可提现金额 = 已结算金额 − 提现中金额 − 冻结金额。
提现金额不得超过可提现余额，超出直接拒绝。
提现审批通过不等于已打款：需要线下打款后手工标记，两步分离。
打款失败自动退回余额，商户可重新申请。
保证金扣款不影响商户正常经营（除平台主动禁用），但会影响可提现金额与续费。
保证金申诉有次数限制，剩余次数在商户端展示。
入驻费用与保证金分开：入驻费是入场费，保证金是违约担保。体验期商户免保证金，有到期倒计时。
结算账户三级联动：开户行 → 支行 → 账号；户名须含字母或汉字，账号 8–32 位数字。
提现打款账户明文查看属高敏操作，平台侧需单独权限且写入操作日志。

12.8 数据输入与输出

对象	关键字段
商户钱包	商户、可用、冻结、待结算、累计
钱包流水	变动类型、金额、变动后余额、关联单号、时间
提现单	商户、金额、状态、结算账户快照、汇款凭证、驳回原因、审核人
结算账户	账户类型、开户行、支行、户名、账号、审核状态
保证金扣款	商户、金额、原因、证据、状态、申诉、审核意见
微信结算规则	主体类型、行业、费率、资质、启停

12.9 异常、边界和幂等处理

场景	处理
提现金额超余额	拒绝并提示可提现金额
结算账户未配置	提现入口拦截，提示先配置结算信息
账户审核中提交提现	允许提交但打款需等待审核通过，平台侧可拒绝
打款失败	余额退回，状态置为打款失败
重复审批同一提现	状态机约束，重复调用幂等返回当前状态
扣款后申诉通过	退回扣款金额，余额恢复
结算任务重复执行	按日期幂等去重，不会重复入账
提现导出	支持按时间、状态、商户筛选并导出 Excel

12.10 消息、短信和自动任务

消息：提现审批结果、打款结果、保证金扣款、申诉结果、结算底价变更。
自动任务：商户钱包结算与分成入账（每天 01:00）、保证金退款重试、结算底价变更通知。

12.11 与其他模块的关系

F09 的收入来源是 F05 订单，退款扣减来自 F08。
F09 的底价口径来自 F03 的结算底价，改价会触发商户通知与结算价变更记录。
推广佣金提现复用同一套提现流程。

12.12 当前限制

打款为线下操作，平台只记录结果，不做自动打款。
结算周期固定为次日，不支持自定义结算周期。
无提现批量审批，需逐单处理。
保证金退款依赖微信退款，失败需重试，平台侧有手动重试入口。

13. F10 内容与社区

13.1 功能概述

种草笔记社区（发布、审核、互动、话题、推荐）、用户关注关系、旅游攻略，以及内容审核与统计数据。

13.2 使用角色与权限

角色	可执行动作
消费者	发布笔记、编辑、上传图文视频、点赞、收藏、评论、关注、发布文字卡片
商户	发布商户笔记、关联本店商品、回复评论、查看浏览与点赞数据
平台运营	审核笔记、驳回、下架、置顶、推荐、管理话题、管理评论树、统计用户内容

13.3 前置条件

发布内容需登录。
涉及图片与视频的上传需微信内容安全检查通过。
商户笔记关联商品时，只能关联本商户在售商品。

13.4 页面与接口入口

端	页面	关键接口
App	种草首页、笔记详情、发布笔记、文字碎碎念、用户主页、攻略频道	`/api/app/notes/`、`/api/app/note-drafts/`、`/api/app/follow/`、`/api/app/travel-guides/`
MerchantWeb / MerchantApp	笔记管理、创建笔记、评论管理	`/api/merchant/notes/**`
AdminWeb	笔记管理、话题管理、评论树、用户统计、旅游攻略	`/api/admin/notes/`、`/api/admin/note-topics/`、`/api/admin/note-comments/`、`/api/admin/travel-guides/`

13.5 主业务流程

内容生命周期

互动

点赞、收藏、评论、关注均为幂等操作：重复点击不产生重复数据，取消操作同样幂等。

文字碎碎念

纯文字经 Canvas 自动换行排版生成 750×1000 的图片卡片，可存相册或直接进入发布流程。

13.6 状态及状态流转

笔记状态：草稿(0) / 已发布(1) / 已拒绝(2) / 已下架(3) / 待审核(4)。

推荐与置顶：是独立标记，不是状态；可叠加在已发布笔记上；置顶优先于推荐。

13.7 业务规则和计算规则

话题可在发布时搜索选择，也可新建；笔记可关联多个话题。
位置标签通过微信选点获取经纬度，用于社区的同城内容聚合。
浏览时长上报用于热度排序，笔记详情页按停留时长上报一次。
内容安全：图片与文本经阿里云内容审核（ScanText / ScanImage）后才可发布。
评论树：支持二级嵌套，平台可删除任意层级评论。
推荐位效果：推荐笔记在社区首页与话题页加权；置顶笔记固定在列表顶部。
商户笔记关联商品后，用户点击可跳转到对应商品详情。
攻略支持富文本正文，图片 URL 做编码处理以兼容小程序富文本组件。

13.8 数据输入与输出

对象	关键字段
笔记	标题、封面、正文、图片、视频、话题、位置、状态、浏览量、点赞数、收藏数、评论数、置顶、推荐、关联商品
话题	名称、来源、笔记数、排序、状态
评论	笔记、作者、内容、图片、父评论、点赞数
关注	用户、被关注用户、状态
攻略	封面、标题、摘要、正文、浏览量、排序、状态
草稿	用户、标题、正文、图片、更新时间

13.9 异常、边界和幂等处理

场景	处理
重复点赞	幂等，第二次取消点赞
重复关注	幂等，第二次取消关注
内容审核不通过	拒绝发布并提示原因，保留草稿
图片上传失败	保留已填内容，允许重试
笔记被删除	级联处理评论与关联商品的展示
平台删除评论	物理删除，子评论保留
草稿未保存	明确提示，不静默丢弃

13.10 消息、短信和自动任务

消息：评论回复通知、点赞与关注通知（频次受控）。
自动任务：笔记推荐（定时刷新推荐状态）。

13.11 与其他模块的关系

F10 的笔记可关联 F03 的商品，形成内容到交易的引流路径。
笔记审核由 F12 的运营权限控制。

13.12 当前限制

无视频审核的独立状态，视频与图文共用同一审核流程。
评论不支持图片以外的富文本。
话题无合并功能，相似话题需人工维护。
内容审核依赖阿里云，未配置时按放行处理，需注意合规风险。

14. F11 消息与通知

14.1 功能概述

四类消息通道：OpenIM 即时消息、平台广播通知、订单与业务卡片消息、短信。以及各端的待办中心。

14.2 使用角色与权限

角色	可执行动作
消费者	查看会话、与商户和客服聊天、接收系统通知
商户	查看会话、接收订单与业务卡片、接收并确认平台通知
平台	向商户群发通知、查看发送与确认统计、与用户会话

14.3 前置条件

OpenIM 服务已部署并配置凭据接口。
商户通知的发布需在平台端具备对应权限。

14.4 页面与接口入口

端	页面	关键接口
App	消息（会话列表）、聊天页	`/api/app/im/credentials`、`/api/app/im/merchant/{id}`、`/api/app/im/customer-service`、`/api/app/im/canChat/{id}`
MerchantApp / MerchantWeb	消息中心、平台通知列表与详情	`/api/merchant/im/credentials`、`/api/merchant/notifications/**`
AdminWeb	消息中心、商户通知、接收人统计	`/api/admin/im/credentials`、`/api/admin/merchant-notices/**`

14.5 主业务流程

平台广播通知

平台在「商户中心 → 商户通知」新建通知，选择目标范围（分类或指定商户）。
预览收件人，确认范围无误。
发布。系统向目标商户投递，并生成接收人记录。
商户在「平台通知」查看，需点击「确认收到」；系统记录确认时间、IP 与客户端。
平台可查看发送数与确认数；未确认的通知会被定时任务提醒。

业务卡片消息

系统以结构化卡片下发消息，各端解析后跳转到对应业务页：

卡片类型	内容	跳转
商品卡片	商品信息	商城/套餐/定制游/拼团/房型/车型/租赁/接送/路线详情
订单卡片	订单摘要	订单详情
活动卡片	活动被平台下架	活动详情
罚款卡片	保证金扣款与申诉结果	保证金记录
结算价卡片	结算底价变更	商户结算底价页
平台通知	运营通知正文	通知详情

14.6 状态及状态流转

平台通知：草稿 → 已发布 → 已取消；接收人状态：待确认 → 已确认。

会话消息：未读 → 已读；未读数在 tabBar 与工作台显示角标。

14.7 业务规则和计算规则

未读角标：> 99 时显示 99+。
消息去重：滑动窗口 200 条内按消息 ID 去重。
被踢下线：检测到被其他端挤下线时清理会话并提示。
商户类型过滤：司机只接收专车派单消息，摄影师只接收旅拍派单消息。
通知需确认：平台通知要求商户显式确认，平台可查看确认率。
待办中心：侧边栏与工作台显示各类待办数量，15 秒最小刷新间隔；写操作后立即失效重取。
提示音：新消息播放 880Hz 正弦波提示音。

14.8 数据输入与输出

对象	关键字段
平台通知	标题、正文、目标范围、状态、发布时间、确认截止
接收人记录	通知、商户、已读、确认时间、确认 IP、客户端
卡片消息	业务类型、业务 ID、卡片数据、创建时间
待办	事项类型、数量、跳转地址

14.9 异常、边界和幂等处理

场景	处理
推送失败	记录失败，接收人列表标记未送达
通知被取消	已投递的记录保留，商户侧提示已取消
重复确认	幂等，保留首次确认时间
IM 服务不可用	会话页显示不可用，不影响其他功能
角标不同步	重新进入页面时重新拉取
消息去重误判	按消息 ID 去重，不按内容

14.10 消息、短信和自动任务

自动任务：平台通知未确认提醒（MerchantBroadcastNoticeTask）、订单通知分发（MerchantOrderNotificationTask）。

14.11 与其他模块的关系

F11 承载 F03–F10 产生的结果通知，本身不产生业务变更。

14.12 当前限制

OpenIM 为自建服务，可用性依赖运维；不可用时站内信不可达。
不支持已读回执的业务语义，只区分未读与已读。
通知仅支持图文正文，不支持富文本附件。
短信通道目前只用于三个场景（商户注册、密码重置、酒店预约）。

15. F12 平台运营与系统

15.1 功能概述

平台侧的运营配置与系统管理：数据看板与待办、首页运营、分类与区域、推荐位置、推广管理、通知模板、用户管理、系统权限、监控与日志、数据库迁移与发布运维。

15.2 使用角色与权限

角色	可执行动作
平台管理员	全部功能，含系统管理、监控、代码生成
平台运营	审核、首页运营、内容运营、商品供给、履约调度
平台财务	提现审批、钱包、保证金、结算规则、退款审核

15.3 前置条件

平台账号已创建并分配角色。
菜单在「系统管理 → 菜单管理」中配置，角色决定可见范围。

15.4 页面与接口入口

平台端菜单分十组：

分组	覆盖内容
商户中心	商户管理、入驻须知、商户通知、保证金申诉、商户菜单
商品供给	商品、活动、平台代运营、平台自营、房型与房态审核、月度日历、房态规则、热门区域与关键词、车型、租车增值服务与评价、租赁、接送路线与价格、商城商品与订单、套餐、旅拍
交易中心	订单、退款审核、拼团、租车调度、接送调度、旅拍派单
内容中心	笔记、话题、用户统计、旅游攻略、短信日志
财务中心	提现、钱包流水、退款规则、微信结算规则、微信交易履约
平台配置	商品分类、地区、推荐位置、首页轮播、首页 Tab、推广、优惠券模板/发放/礼包、热销推荐、通知模板
用户与增长	定制游工作台、小程序用户管理
系统管理	用户、角色、菜单、部门、岗位、字典、参数、通知公告
系统监控	在线用户、定时任务、数据源、服务、缓存、操作日志、登录日志
系统工具	表单构建、代码生成、接口文档

15.5 主业务流程

数据看板与待办

打开平台首页，看板展示今日订单、今日收入、新注册用户、待审核事项四项 KPI。
近 7 天订单趋势折线可在「订单数 / 收入」间切换，订单类型分布饼图。
待办事项列出 6 类待办并带计数，点击直达对应列表并自动带上筛选条件。
侧边栏菜单显示待办角标，悬停展开清单。

定制游工作台

查看需求列表，按阶段筛选。
打开需求详情，核对客户预算、人数、日期与偏好。
分配旅行顾问。
在跟进时间线记录每次沟通与推进阶段。
创建行程方案并发布给用户；用户可接受或要求修改。
创建报价并发布给用户；用户可接受或拒绝。
报价确认后生成待支付订单。

推荐位置运营

新增片区，设定中心点经纬度与覆盖半径，类型可选乡镇、景区、商圈、度假区、交通枢纽。
系统自动归属商户：有效经纬度 + 城市匹配 + 直线距离不超过半径 + 商户启用。
人工修正：可强制纳入或排除某商户，人工结果优先级高于自动结果。
「重算」重新跑自动归属，不覆盖人工修正结果。
改址审核：商户申请变更经营位置，平台在此通过或驳回。

系统管理与监控

用户、角色、菜单、部门、岗位、字典、参数、通知公告的标准 RuoYi 能力；监控侧提供在线用户、定时任务、缓存、服务、Druid、操作日志与登录日志。

15.6 状态及状态流转

对象	状态
推荐位置	启用(1) / 停用(0)
归属来源	自动归属 / 人工修正 / 未归属
片区类型	乡镇 / 景区 / 商圈 / 度假区 / 交通枢纽
首页轮播	启用 / 停用
Tab 分组	启用 / 停用
优惠券模板	草稿 / 已发布 / 停用
退款规则	草稿 / 已发布 / 停用
待办事项	无状态，按计数聚合

15.7 业务规则和计算规则

菜单由后端下发：前端只注册静态公共路由，登录后由 getRouters 返回按角色过滤后的菜单树。
三层权限：菜单权限（能否看到）→ 按钮权限（能否操作）→ 数据权限（能看到哪些行）。平台端数据权限注解目前未在业务接口启用。
待办角标按菜单路径聚合，点击后通过 URL query 注入筛选条件直达。
首页运营配置：轮播图可指定跳转的小程序页面；Tab 分组绑定场景类型与关联分类。
热销榜：真实销量与展示销量分离，运营可人工排序或一键恢复自动计算。
推广管理：主体、等级规则、参数配置、提现审核四部分；主体支持批量启停与导出 CSV。
通知模板：按唯一键管理，字段类型支持日期范围、时间范围、富文本、文本、数字；支持排序与启停。
定时任务：可视化配置 Cron，可立即执行一次，保留调度日志。
退款规则版本化：每个业务分类维护已发布版本与草稿，发布需二次确认。
首页运营与位置筛选互不冲突：位置筛选只影响参与位置运营的业务，商城商品不参与。

15.8 数据输入与输出

对象	关键字段
数据看板	今日订单、今日收入、新注册用户、待审核数、7 日趋势、订单类型分布
待办	事项类型、计数、目标地址
推荐位置	名称、类型、中心经纬度、半径、状态、归属商户
轮播图	图片、跳转页面、排序、状态
Tab 分组	场景类型、名称、图标、关联分类、排序
推广主体	主体类型、等级、合作期限、状态
通知模板	标签名、唯一键、字段类型、排序、状态

15.9 异常、边界和幂等处理

场景	处理
角色未分配菜单	登录后无菜单，需管理员分配角色菜单权限
有菜单无按钮	检查按钮权限标识；仍不可操作则查数据权限
片区半径过大	会归属大量商户，列表核对后再启用
重算覆盖人工修正	重算不覆盖人工结果，界面明确提示
轮播图跳转页面失效	发布前校验页面选项
定时任务执行失败	调度日志记录异常信息，可重试
字典被业务引用	删除前确认无业务数据引用
退款规则发布	需二次确认，避免误发布影响新申请

15.10 消息、短信和自动任务

自动任务：见 9.10 汇总表（支付、退款、结算、对账、履约、通知等共 17 个任务）。
日志：操作日志记录所有带 @Log 的写操作；登录日志记录登录、登出与失败。

15.11 与其他模块的关系

F12 为所有业务模块提供配置入口、审核权限与数据支撑。

15.12 当前限制

对账无独立页面，需通过日志与数据库查看。
数据权限（行级）未在业务接口启用。
代码生成器与表单构建器为 RuoYi 原生能力，与本项目业务模型不直接对应。
多环境差异：开发、正式环境的支付、短信、OSS、IM 配置不同，功能描述不随环境变化，但实际可用性随配置变化。

16. 四端功能矩阵

「●」已实现且四端均有入口；「◐」部分端有入口；「○」仅平台或商户侧维护。

功能模块	用户小程序	商户小程序	商户 Web	平台管理端
F01 账户与用户	● 微信登录、资料、入住人、地址	● 登录、改密	● 登录、改密、资料	● 账号、角色、权限
F02 商户入驻与管理	○	● 入驻向导、状态页	● 入驻向导、状态页	● 审核、菜单、通知、申诉
F03 商品与供应	● 浏览、搜索、详情、下单	● 维护、提审	● 维护、提审、日历	● 审核、定价、日历发布
F04 营销活动	● 领券、拼团、推广	● 活动报名	● 活动报名、券承担	● 券模板、发券、活动、推广
F05 订单交易	● 下单、支付、查询	● 列表、详情	● 列表、详情	● 全量订单、合单、审计
F06 支付与退款	● 支付、申请退款	● 审批退款	● 审批退款	● 退款审核、履约、对账
F07 履约管理	● 预约、确认、评价	● 核销、派单、发货	● 核销、派单、发货	● 调度、交接、费用审核
F08 售后服务	● 申请、进度	● 处理	● 处理、商城退款	● 审核、规则配置
F09 商户财务	○ 用户钱包	● 余额、提现、申诉	● 余额、提现、统计	● 审批、打款、保证金
F10 内容与社区	● 发布、互动、攻略	● 商户笔记、评论	● 商户笔记、评论	● 审核、置顶、推荐、话题
F11 消息与通知	● 会话、客服	● 会话、平台通知	● 会话、平台通知	● 群发通知、统计
F12 平台运营与系统	○	○	○	● 看板、配置、监控、运维

17. 当前限制与未实现能力

汇总全站需要在文档与沟通中明确的边界：

能力	状态	说明
微信平台直连支付	配置后可用	正式使用依赖商户号、证书与公钥配置
微信支付分（押金）	默认模拟	默认 `mock-mode=true`，不产生真实服务订单
微信服务商利润分账	暂未实现	已下线，改用平台内部账本结算
OpenIM 即时消息	配置后可用	依赖自托管 OpenIM 服务可用性
阿里云短信 / OSS / 内容审核	配置后可用	依赖对应参数与服务状态
商户内部收入结算	系统自动	每日 01:00 批量结算，无人工干预入口
微信账单对账	系统自动	每日 10:30 执行，平台端无独立页面
微信发货信息同步	系统自动	每 5 分钟重试，5 次后转人工
商城超期自动确认收货	系统自动	超 15 天未确认自动确认
行级数据权限（`@DataScope`）	暂未实现	注解与切面已存在，业务接口未启用
重复提交拦截（`@RepeatSubmit`）	暂未实现	幂等由各业务自行实现
消费者自助注销	暂未实现	需平台侧处理
微信支付分回调验签与解密	待完善	回调未做验签与 AES 解密

18. 附录 A：实现参考索引

供维护人员核对业务事实与代码位置，不作为功能口径。

18.1 后端关键实现

业务	实现位置
下单编排	`Api/ruoyi-system/.../service/order/OrderOrchestrator`
业务类型处理器	`Api/ruoyi-system/.../service/order/handler/`（11 个 Handler）
订单状态机	`Api/ruoyi-system/.../service/order/OrderStateMachine`
结算状态机	`Api/ruoyi-system/.../service/order/OrderSettlementStateMachine`
展示状态计算	`Api/ruoyi-system/.../service/impl/XdOrderDisplayStatusResolver`
支付编排	`Api/ruoyi-system/.../service/payment/PaymentOrchestrator`
微信支付	`Api/ruoyi-system/.../config/PlatformWechatPayConfig`
退款引擎	`Api/ruoyi-system/.../system/refundengine/`（application / calculator / policy / payout / snapshot / hint）
退款规则计算器	`.../refundengine/calculator/`（按业务分类各一套）
商户能力矩阵	`Api/ruoyi-common/.../common/merchant/MerchantCapabilityCatalog`
商户身份解析	`Api/ruoyi-framework/.../interceptor/MerchantAuthenticationInterceptor`
用户身份解析	`Api/ruoyi-framework/.../web/resolver/CurrentUserResolver`
优惠券结算	`.../service/coupon/CouponCheckoutService`、`CouponSettlementCalculator`、`LargestRemainderAllocator`
位置归属	`Api/ruoyi-system/.../service/LocationZoneService`
定制游阶段机	`Api/ruoyi-system/.../service/customtour/CustomTourStage`
微信交易履约	`.../service/WxTradeFulfillmentService`、`WxTradeEventProcessor`
定时任务	`Api/ruoyi-admin/.../web/task/`（17 个）、`Api/ruoyi-quartz/`
数据库迁移	`Api/ruoyi-system/src/main/resources/db/migration/`（Flyway）

18.2 前端关键实现

业务	实现位置
平台菜单	`AdminWeb/src/router/index.js` + 后端 `getRouters`
平台待办	`AdminWeb/src/store/modules/pending.js`、`AdminWeb/src/utils/pendingTodos.js`
商户能力过滤	`MerchantWeb/src/utils/merchantCapabilities.js`
商户端路由	`MerchantWeb/src/router/index.js` + `getMerchantRouters`
平台代运营商品	`AdminWeb/src/views/xl/product/managed/`
退款规则编辑	`AdminWeb/src/views/xl/refund-policy/`
定制游工作台	`AdminWeb/src/views/xl/customTour/index.vue`
价格日历	`AdminWeb/src/views/xl/product/activity/`、`MerchantWeb/src/views/products/components/PriceCalendarDialog.vue`
房态日历	`MerchantWeb/src/views/room-calendar/index.vue`
核销弹窗	`MerchantWeb/src/views/orders/list.vue`、`MerchantApp/pages/scan/confirm`
商城批量发货	`MerchantWeb/src/views/mall/orders/list.vue`
用户端下单	`App/pages/*/order-confirm/`
金额换算	`AdminWeb/src/utils/`、`MerchantWeb/src/components/AmountInput/`、`App/utils/money.js`

18.3 订单号前缀与活动类型对照

活动类型	值	订单号前缀	处理器
团购	`groupbuy`	OD	`GroupbuyOrderHandler`
拼团	`pintuan`	OD	`PintuanOrderHandler`
套餐	`package`	PK	`PackageOrderHandler`
酒店房型	`room`	PH / RM	`RoomOrderHandler`
旅拍	`photography`	—	`PhotographyOrderHandler`
租车	`car_rental`	CR	`CarRentalOrderHandler`
物品租赁	`item_rental`	IR	`ItemRentalOrderHandler`
接送	`transfer`	TF	`TransferOrderHandler`
商城	`mall`	ML	`MallOrderHandler`
定制游	`custom_tour`	—	`CustomTourOrderHandler`
补差价	`surcharge`	—	`SurchargeOrderHandler`

18.4 关键枚举速查

枚举	取值
`XdOrderStatus`	PENDING_PAY(0) / PAID(1) / REFUNDING(2) / REFUNDED(3) / CANCELLED(4) / COMPLETED(5)
`MerchantStatus`	待审核(1) / 驳回(2) / 待支付(3) / 正常营业(4) / 关店审核中(5) / 已关店(6) / 禁用(7)
`ProductActivityStatusEnum`	待审核(0) / 已上架(1) / 已下架(2) / 已驳回(3) / 平台下架(4)
`OrderVoucherStatusEnum`	未使用(0) / 已核销(1) / 已退款(2) / 已过期(3) / 已预约(4)
`WithdrawalStatusEnum`	待处理 / 审批通过 / 已打款 / 已驳回 / 打款失败 / 风险审核
`LocationZoneTypeEnum`	乡镇 / 景区 / 商圈 / 度假区 / 交通枢纽
`RefundCategory`	团购 / 拼团 / 套餐 / 固定套餐 / 自选套餐 / 酒店 / 租车 / 商城 / 接送
`CustomTourStage`	13 阶段，见 6.10
`MerchantCapability`	22 个能力键，见附录 18.5

18.5 商户能力键

profile、messages、finance、dashboard、orders、orders.fulfill、orders.verify、orders.refundReview、products、activities、packages、rooms、roomCalendar、hotelAppointments、mallProducts、mallOrders、mallShipment、mallRefundReview、rentalProducts、rentalReviews、driverAvailability、carFleet、carReviews、stats、notes

18.6 主要 API 命名空间

命名空间	端点量级	说明
`/api/app/**`	约 226	用户小程序
`/api/merchant/**`	约 218	商户 Web 与小程序
`/api/admin/` + `/api/platform/`	约 395	平台管理端
`/system/`、`/monitor/`、`/tool/**`	约 95	平台 RuoYi 原生
`/common/**`	约 6	上传、下载、公开配置

接口文档在服务启动后可见于 http://localhost:8082/swagger-ui.html。

携岛系统功能设计说明书 ​

目录 ​

1. 文档说明 ​

1.1 编写目的 ​

1.2 系统范围 ​

1.3 终端与角色 ​

1.4 通用设计原则 ​

1.5 功能状态表达规范 ​

1.6 与其他文档的关系 ​

2. 系统总体架构 ​

2.1 四端构成与数据流 ​

2.2 后端 API 命名空间 ​

2.3 核心业务对象 ​

2.4 三级价格模型 ​

2.5 关键状态机总览 ​

2.6 订单展示状态（用户可见口径） ​

3. 总体业务流程 ​

3.1 消费者交易主流程 ​

3.2 商户入驻经营主流程 ​

3.3 售后退款主流程 ​

3.4 履约主线（4 条业务线并行） ​

3.5 内容互动主流程 ​

4. F01 账户与用户 ​

4.1 功能概述 ​

4.2 使用角色与权限 ​

4.3 前置条件 ​

4.4 页面与接口入口 ​

4.5 主业务流程 ​

4.6 状态及状态流转 ​

4.7 业务规则和计算规则 ​

4.8 数据输入与输出 ​

4.9 异常、边界和幂等处理 ​

4.10 消息、短信和自动任务 ​

4.11 与其他模块的关系 ​

4.12 当前限制 ​

5. F02 商户入驻与管理 ​

5.1 功能概述 ​

5.2 使用角色与权限 ​

5.3 前置条件 ​

5.4 页面与接口入口 ​

5.5 主业务流程 ​

5.6 状态及状态流转 ​

5.7 业务规则和计算规则 ​

5.8 数据输入与输出 ​

5.9 异常、边界和幂等处理 ​

5.10 消息、短信和自动任务 ​

5.11 与其他模块的关系 ​

5.12 当前限制 ​

6. F03 商品与供应 ​

6.1 功能概述 ​

6.2 公共设计 ​

6.2.1 商品信息与三种经营模式 ​

6.2.2 定价模式 ​

6.2.3 三套价格日历体系 ​

6.2.4 通用功能清单 ​

6.2.5 用户端浏览入口 ​

6.3 F03-01 酒店住宿 ​

6.4 F03-02 租车 ​

6.5 F03-03 接送服务 ​

6.6 F03-04 旅拍 ​

6.7 F03-05 物品租赁 ​

6.8 F03-06 商城 ​

6.9 F03-07 套餐 ​

6.10 F03-08 定制游 ​

6.11 F03 通用规则与限制 ​

6.12 与其他模块的关系 ​

6.13 当前限制 ​

7. F04 营销活动 ​

7.1 功能概述 ​

7.2 使用角色与权限 ​

7.3 前置条件 ​

7.4 页面与接口入口 ​

7.5 主业务流程 ​

7.6 状态及状态流转 ​

7.7 业务规则和计算规则 ​

7.8 数据输入与输出 ​

7.9 异常、边界和幂等处理 ​

7.10 消息、短信和自动任务 ​

7.11 与其他模块的关系 ​

7.12 当前限制 ​