模块需求 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. 订单模块
订单状态流转
自动化规则
- 待支付订单: 30分钟未支付自动取消
- 已入住订单: 离店后24小时自动完成
- 商家自动接单: 可配置金额阈值、房型限制、时间范围
价格计算
佣金计算
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元
- 提现手续费: 默认0.6%
- 到账时间: 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加密传输
