xiaoquan/rent

Fork 0

Files

T

xiaoquan 524ff8cd32 dev

2026-04-24 00:28:52 +08:00

23 KiB

Raw Blame History

模块需求 Skills

本文档定义各业务模块的详细规则和约束。

1. 用户认证模块

登录方式

方式	场景	说明
手机号+验证码	小程序用户	发送6位验证码，5分钟有效
账号密码	商家/管理员	密码6-20位，bcrypt加密
微信授权	小程序用户	获取openid，自动绑定或注册
支付宝授权	小程序用户	获取openid，自动绑定或注册

JWT配置

Token有效期: 2小时
RefreshToken有效期: 7天
刷新机制: 过期前30分钟可无感刷新

角色权限

角色	认证端点	可访问路由	权限范围
user	/auth/*	/rooms, /orders, /user	仅自己的数据
seller	/seller-auth/*	/merchant/*	仅自己店铺的数据
admin	/auth/*	/admin/, /auth/	全平台数据

账户体系

账户类型	表名	说明
C端用户	users	小程序用户，支持第三方登录
商家账户	sellers	B端商家，独立账户体系
平台管理员	admins	平台运营管理人员

商家入驻流程

小程序「个人中心」→ 点击「商家入驻」→ 跳转商家注册/登录页
    → 商家账号注册（手机号+密码+联系人+邮箱）
    → 注册成功后跳转商家中心
    → 创建店铺（店铺名称、地址、营业执照等）
    → 提交审核 → 平台审核 → 通过后可营业

商家注册校验规则

字段	规则	错误提示
phone	必填，正则 `/^1[3-9]\d{9}$/`	手机号格式不正确
code	必填，6位数字	请输入6位验证码
contactName	必填，2-50字	请填写联系人姓名
email	选填，正则邮箱格式	邮箱格式不正确
password	选填，6-20位	密码长度为6-20位

商家注册后端校验

验证码校验（开发环境万能验证码: 123456）
手机号唯一性检查（已注册则返回400: 该手机号已注册）
密码选填，填写时 bcrypt 加密存储（salt rounds: 10）
注册成功自动生成 accessToken + refreshToken
JWT payload 包含: { sub, phone, role: 'seller', merchantId }

商家登录方式

方式	参数	说明
验证码登录	phone + code	6位验证码，5分钟有效
密码登录	phone + password	需先设置密码

验证码缓存

开发环境: 内存Map缓存，5分钟过期
生产环境: TODO 替换为 Redis

商家中心页面状态机

条件	展示内容
未登录商家账号	引导注册/登录
已登录但未创建店铺(merchantId为空)	引导创建店铺
已登录且merchantId有值	店铺管理面板(状态、数据、菜单)

店铺审核状态展示

status	显示	可修改	功能菜单	特殊展示
pending	审核中	否	隐藏	提示"审核中，暂不可修改"
approved	营业中	是	显示	数据概览+功能菜单
rejected	已拒绝	是	隐藏	红色拒绝原因区块
frozen	已冻结	否	隐藏	提示"联系客服"

修改店铺重新审核规则

审核通过(approved)或拒绝(rejected)状态下修改店铺信息
后端自动将 status 重置为 pending，清空 rejectReason
商家中心显示"审核中"状态，等待重新审核

2. 房源模块

房源类型

类型	说明	默认设施
hotel	酒店	WiFi, 独立卫浴, 空调
homestay	民宿	WiFi, 厨房, 洗衣机
apartment	公寓	WiFi, 厨房, 洗衣机, 冰箱
hostel	青旅	WiFi, 公共卫浴

取消政策

政策	说明	退款比例
free	免费取消	入住前任意时间全额退款
flexible	灵活取消	入住前24小时全额，之后50%
strict	严格取消	入住前48小时全额，之后不退款

房量日历规则

默认提前365天可预订
价格继承自基础价格，可单独调整
房态变更需记录日志（操作人、时间、变更内容）
批量修改支持按日期范围、房型批量设置

3. 订单模块

订单状态流转

待支付 ──支付成功──> 待确认 ──商家确认──> 待入住 ──入住──> 已入住 ──离店──> 已完成
   │                  │                    │
   └──超时/取消──> 已取消   └──商家拒绝──> 已取消    └──用户退款──> 退款中
                                              │
                                              ├──商家通过──> 已退款（恢复房量）
                                              └──商家拒绝──> 已取消

待确认 ──用户退款──> 退款中 ──商家通过──> 已退款（恢复房量）

用户订单操作

操作	接口	适用状态	说明
取消订单	PUT /orders/:id/cancel	pending_pay, pending_confirm	取消订单，已支付则退款
申请退款	PUT /orders/:id/refund	pending_confirm, pending_checkin	提交退款申请

商家订单操作

操作	接口	适用状态	说明
确认订单	PUT /seller/orders/:id/confirm	pending_confirm	确认后等待用户入住
拒绝订单	PUT /seller/orders/:id/reject	pending_confirm	拒绝并退款
办理入住	PUT /seller/orders/:id/checkin	pending_checkin	标记已入住
通过退款	PUT /seller/orders/:id/approve-refund	refunding	同意退款，恢复房量日历库存
拒绝退款	PUT /seller/orders/:id/reject-refund	refunding	拒绝退款，订单变为已取消

自动化规则

待支付订单: 30分钟未支付自动取消
已入住订单: 离店后24小时自动完成
商家自动接单: 可配置金额阈值、房型限制、时间范围

价格计算

房费总额 = 房价/晚 × 入住晚数 × 房间数
订单总额 = 房费总额
实付金额 = 订单总额 - 优惠券抵扣
软件服务费 = 实付金额 × 服务费比例(默认5%，平台后台可配置)
商家预计收入 = 实付金额 - 软件服务费

说明：

软件服务费归平台所有，在订单创建时计算
商家预计收入 = 实付金额 - 软件服务费
费用明细仅在商家订单详情中展示，用户端不显示

佣金计算

平台佣金 = 实付金额 × 佣金比例(默认10%)
商家结算 = 实付金额 - 平台佣金

4. 优惠券模块

优惠券类型

类型	value含义	使用规则
fixed	固定金额(元)	满 min_amount 可用
percent	折扣比例(0.9=9折)	最高优惠可配置

适用范围

scope	说明	scope_id
platform	全平台通用	null
merchant	指定商家可用	商家ID
room	指定房源可用	房源ID

使用规则

每单限用1张
不找零、不兑现
过期自动失效
使用后不可退回

5. 促销活动模块

活动类型

类型	rules字段示例	说明
full_reduction	`{"threshold": 500, "reduce": 50}`	满500减50
discount	`{"discount": 0.85}`	全场85折
package	`{"items": [...], "price": 888}`	套餐打包价

活动优先级

房源级活动 > 商家级活动 > 平台级活动
同级别时，创建时间晚的优先
优惠不可叠加，取最优

6. 评价模块

评价规则

订单完成后7天内可评价
评价后不可修改
支持追评（商家回复后）
匿名评价隐藏用户昵称头像

评分维度

综合评分: 1-5分（必填）
评价内容: 最多500字（选填）
图片/视频: 最多9张（选填）

商家回复

每条评价仅可回复一次
回复后用户可追评一次

7. 财务模块

结算周期

预付订单: 用户支付后T+1结算给商家
现付订单: 用户入住后结算

提现规则

最低提现金额: 100元
提现手续费: 无
到账时间: T+1工作日
需绑定银行卡

对账维度

对账类型	说明
预付对账	预付订单结算明细
现付对账	现付订单收款明细
应付对账	平台应付商家明细

8. 消息通知模块

通知类型

type	场景	模板
order	订单状态变更	"您的订单{{orderNo}}已{{status}}"
system	系统公告	直接展示content
promotion	促销活动	"{{activityName}}即将开始"
review	评价提醒	"您有一条新评价待回复"

推送渠道

小程序: 模板消息（需用户授权）
短信: 重要订单状态（需验证手机号）
站内信: 全部通知

9. 搜索与筛选

搜索维度

目的地: 城市/商圈/地标
关键词: 房源名称（支持模糊、拼音首字母）
地图选点: 按半径筛选

筛选条件

条件	类型	说明
价格区间	[min, max]	每晚价格
房型	多选	hotel/homestay/apartment/hostel
设施服务	多选	WiFi/停车/早餐等
入住日期	日期范围	检查房量
评分	最小值	默认不限

排序方式

智能推荐（默认）: 综合评分、销量、距离
价格升序/降序
评分降序
距离升序（需位置权限）

10. 安全与风控

请求限流

接口	限制	时间窗口
发送验证码	1次/分钟	同一手机号
登录	5次/分钟	同一IP
创建订单	10次/分钟	同一用户
API通用	100次/分钟	同一用户

敏感操作

修改密码: 需验证旧密码或手机验证码
绑定银行卡: 需实名认证
提现: 需二次验证
账号注销: 需验证手机号 + 7天冷静期

数据加密

手机号存储: AES-256加密
身份证号: AES-256加密
支付数据: RSA加密传输

11. 邀请返现活动模块

模块概述

邀请返现是平台级营销活动，独立于其他促销活动管理。平台管理后台有专门的「邀请返现」菜单入口，不与其他活动混在一起。

活动概述

平台级营销活动，用户（邀请人）通过分享邀请链接/海报邀请新用户注册并完成订单，邀请人获得返现奖励。被邀请人无额外收益。

返现规则

订单序号	返现比例	最低返现	最高返现
第1单	订单金额 × 5%	0.01元	50元
第2单	订单金额 × 0.5%	0.01元	50元

仅限被邀请人首次下单（第1、2单）触发返现
订单状态为「已完成」时才计算返现
退款订单不计算返现

提现规则

规则	值
最低提现金额	10元
提现方式	微信零钱（自动打款）
到账时间	T+1工作日
提现手续费	0

数据表结构

mkt_activities - 营销活动总表

字段	类型	说明
id	BIGINT PK	主键
name	VARCHAR(100)	活动名称
type	ENUM('invite_cashback')	活动类型
enabled	TINYINT(1)	是否启用
config	JSON	活动配置（见下方）
start_time	DATETIME	活动开始时间
end_time	DATETIME	活动结束时间
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

invite_cashback 类型 config 结构：

{
  "firstOrderRate": 0.05,
  "secondOrderRate": 0.005,
  "minCashback": 0.01,
  "maxCashback": 50,
  "withdrawThreshold": 10
}

mkt_invitations - 邀请关系表

字段	类型	说明
id	BIGINT PK	主键
activity_id	BIGINT	活动ID
inviter_id	BIGINT	邀请人用户ID
invitee_id	BIGINT	被邀请人用户ID
invite_code	VARCHAR(32)	邀请码（邀请人唯一标识）
scene	VARCHAR(100)	小程序scene参数
created_at	DATETIME	邀请时间

约束: 一个被邀请人只能被一个人邀请（UNIQUE invitee_id）

mkt_cashbacks - 返现记录表

字段	类型	说明
id	BIGINT PK	主键
activity_id	BIGINT	活动ID
inviter_id	BIGINT	邀请人用户ID
invitee_id	BIGINT	被邀请人用户ID
order_id	BIGINT	关联订单ID
order_no	VARCHAR(32)	订单号
order_amount	DECIMAL(10,2)	订单金额
order_index	TINYINT	被邀请人第几单（1/2）
rate	DECIMAL(5,4)	返现比例
amount	DECIMAL(10,2)	返现金额
status	ENUM('pending','settled','cancelled')	pending=待结算 settled=已到账 cancelled=已取消
settled_at	DATETIME	到账时间
created_at	DATETIME	创建时间

约束: 同一订单同一邀请人只能有一条返现记录（UNIQUE order_id + inviter_id）

mkt_user_invite_stats - 用户邀请统计表

字段	类型	说明
id	BIGINT PK	主键
activity_id	BIGINT	活动ID
user_id	BIGINT UNIQUE	用户ID
invite_code	VARCHAR(32)	专属邀请码
total_invites	INT	累计邀请人数
total_orders	INT	累计下单人数
total_cashback	DECIMAL(10,2)	累计返现金额
available_balance	DECIMAL(10,2)	可提现余额
withdrawn_amount	DECIMAL(10,2)	已提现金额
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

mkt_invite_withdrawals - 邀请提现申请表

字段	类型	说明
id	BIGINT PK	主键
activity_id	BIGINT	活动ID
user_id	BIGINT	用户ID
amount	DECIMAL(10,2)	提现金额
status	ENUM('pending','approved','rejected','paid')	状态
reject_reason	VARCHAR(500)	拒绝原因
reviewer_id	BIGINT	审核人ID
reviewed_at	DATETIME	审核时间
paid_at	DATETIME	打款时间
created_at	DATETIME	申请时间
updated_at	DATETIME	更新时间

核心业务流程

用户A生成邀请海报/链接 → 用户B扫码进入小程序
  → B注册时记录邀请关系(mkt_invitations)
  → B完成第1单 → 订单完成时触发返现
    → 计算返现金额(payAmount × 5%)
    → 写入mkt_cashbacks，status=settled
    → 更新mkt_user_invite_stats.available_balance
  → B完成第2单 → 同上(0.5%)
  → A的available_balance累计 ≥ 10元 → A申请提现
    → 写入mkt_invite_withdrawals，status=pending
    → 平台审核 → approved
    → 确认打款 → paid

订单完成触发返现逻辑

订单状态变为completed时:
  1. 查询该用户是否被邀请(mkt_invitations.invitee_id = userId)
  2. 若无邀请关系 → 跳过
  3. 查询活动是否启用(mkt_activities.enabled = true)
  4. 查询该被邀请人已完成订单数(不含退款)
  5. 若订单序号 > 2 → 跳过
  6. 检查是否已有返现记录(防重复)
  7. 根据订单序号取返现比例(1→5%, 2→0.5%)
  8. 计算返现金额 = payAmount × rate，限制在[min, max]
  9. 写入mkt_cashbacks，直接设为settled
  10. 更新mkt_user_invite_stats（累计字段 + available_balance）

小程序分享机制

分享方式:

小程序原生分享（onShareAppMessage）→ 携带邀请人ID
生成海报图片 → 含小程序码（wxacode.getUnlimited）
复制链接 → 含邀请码

小程序码参数: scene: i=userId的base62编码

注册时绑定逻辑:

从scene或shareTicket解析出inviter_id
注册成功后自动创建mkt_invitations记录
同时初始化mkt_user_invite_stats（为邀请人生成invite_code）

邀请码规则

格式: 用户ID的base62编码，长度6-8位
唯一: 每个用户一个invite_code
场景值: i={inviteCode}

API 接口设计

用户端（需用户Token）：

方法	路径	说明
GET	/user/activity/invite/stats	获取我的邀请统计
GET	/user/activity/invite/records	邀请记录列表
GET	/user/activity/invite/cashbacks	返现记录列表
POST	/user/activity/invite/withdraw	申请提现
GET	/user/activity/invite/withdrawals	提现记录列表
POST	/user/activity/invite/bind	绑定邀请关系（注册后调用）

平台管理端（需管理员Token）：

方法	路径	说明
GET	/admin/activity/invite/stats	邀请数据总览
GET	/admin/activity/invite/config	获取活动配置
PUT	/admin/activity/invite/config	更新活动配置
GET	/admin/activity/invite/records	邀请记录列表
GET	/admin/activity/invite/cashbacks	返现记录列表
GET	/admin/activity/invite/withdrawals	提现审核列表
PUT	/admin/activity/invite/withdrawals/:id/approve	审核通过
PUT	/admin/activity/invite/withdrawals/:id/reject	审核拒绝
PUT	/admin/activity/invite/withdrawals/:id/pay	确认打款

注意: 平台管理后台不再提供通用的活动列表CRUD，邀请返现活动有独立的配置管理页面。

小程序页面路由

页面	路径	说明
邀请首页	/pages/invite/index	邀请统计、海报生成、分享
邀请记录	/pages/invite/records	邀请人数、被邀请人列表
返现记录	/pages/invite/cashbacks	返现明细列表
提现页面	/pages/invite/withdraw	余额展示、提现操作
提现记录	/pages/invite/withdrawals	提现历史列表
邀请海报	/pages/invite/poster	生成分享海报

平台管理后台页面

页面	路径	说明
邀请返现管理	/invite	数据概览、提现审核、活动配置三个Tab

页面结构:

数据概览Tab: 统计卡片 + 邀请记录列表 + 返现记录列表
提现审核Tab: 提现申请列表，支持审核通过/拒绝/确认打款
活动配置Tab: 启用/停用开关 + 返现比例/金额限制/提现门槛配置表单

23 KiB Raw Blame History Unescape Escape

模块需求 Skills

1. 用户认证模块

登录方式

JWT配置

角色权限

账户体系

商家入驻流程

商家注册校验规则

商家注册后端校验

商家登录方式

验证码缓存

商家中心页面状态机

店铺审核状态展示

修改店铺重新审核规则

2. 房源模块

房源类型

取消政策

房量日历规则

3. 订单模块

订单状态流转

用户订单操作

商家订单操作

自动化规则

价格计算

佣金计算

4. 优惠券模块

优惠券类型

适用范围

使用规则

5. 促销活动模块

活动类型

活动优先级

6. 评价模块

评价规则

评分维度

商家回复

7. 财务模块

结算周期

提现规则

对账维度

8. 消息通知模块

通知类型

推送渠道

9. 搜索与筛选

搜索维度

筛选条件

排序方式

10. 安全与风控

请求限流

敏感操作

数据加密

11. 邀请返现活动模块

模块概述

活动概述

返现规则

提现规则

数据表结构

mkt_activities - 营销活动总表

mkt_invitations - 邀请关系表

mkt_cashbacks - 返现记录表

mkt_user_invite_stats - 用户邀请统计表

mkt_invite_withdrawals - 邀请提现申请表

核心业务流程

订单完成触发返现逻辑

小程序分享机制

邀请码规则

API 接口设计

小程序页面路由

平台管理后台页面

23 KiB

Raw Blame History