diff --git a/docs/api.md b/docs/api.md index 4733e25..5c7df87 100644 --- a/docs/api.md +++ b/docs/api.md @@ -7,7 +7,7 @@ API 规划以 [项目计划](project-plan.md) 第 10 章为准。 - 认证:短信验证码、手机号登录、Token 刷新、退出登录。 - 实名:发起认证、查询状态、服务回调。 - 发布:创建、修改、提交审核、下架、列表、详情。 -- 订单:创建、取消、确认收号、提交归还、确认归还、发起申诉。 +- 订单:创建、取消、确认收号、发起结账、确认结账、修改结账、确认/拒绝修正、发起申诉。 - 交接:提交交接说明、查看交接记录。 - 钱包:余额、流水、提现预留。 - 通知:站内信列表、标记已读。 @@ -37,8 +37,10 @@ API 规划以 [项目计划](project-plan.md) 第 10 章为准。 - `POST /api/orders/{id}/handoff` - `GET /api/orders/{id}/handoff-records` - `POST /api/orders/{id}/confirm-receive` -- `POST /api/orders/{id}/return` -- `POST /api/orders/{id}/confirm-return` +- `POST /api/orders/{id}/checkout` +- `POST /api/orders/{id}/checkout/confirm` +- `POST /api/orders/{id}/checkout/counter` +- `POST /api/orders/{id}/checkout/accept` - `POST /api/orders/{id}/dispute` - `GET /api/disputes` - `GET /api/disputes/{id}` diff --git a/docs/business-rules.md b/docs/business-rules.md index 4890953..1309d1c 100644 --- a/docs/business-rules.md +++ b/docs/business-rules.md @@ -49,24 +49,27 @@ - 确认收号时会重新计算租赁开始时间和结束时间。 - 交接记录保存在 `handoff_records`,订单双方都可以查看。 -## 开发态归还与完成 +## 开发态结账与完成 -- 租赁中订单可以由租客提交归还。 -- 逾期中订单仍允许租客提交归还,但后台和号主可以根据逾期情况发起申诉或客服处理。 -- 租客提交归还后,订单状态变为 `pending_return_confirm`,交接状态变为 `pending_owner_return_confirm`。 -- 只有号主可以确认归还。 -- 号主确认归还后,订单状态变为 `completed`,交接状态变为 `returned`,结算状态先标记为 `settled`。 +- 租赁中订单可以由租客发起结账,填写使用结束说明、消耗金额、哈夫币消耗量、其他扣款和证据链接。 +- 逾期中订单仍允许租客发起结账,但后台和号主可以根据逾期情况发起申诉或客服处理。 +- 租客发起结账后,订单状态变为 `pending_checkout_confirm`,交接状态变为 `pending_owner_checkout`。 +- 只有号主可以确认结账或修改结账。 +- 号主直接确认结账后,订单状态变为 `completed`,交接状态变为 `returned`,结算状态标记为 `settled`。 +- 号主修改结账后,订单状态变为 `pending_checkout_accept`,交接状态变为 `pending_renter_checkout`,必须等待租客确认修正。 +- 待号主确认结账或待租客确认修正时,任一方都可以发起结账争议。 +- 结账争议后订单状态变为 `checkout_disputing`,交接状态变为 `checkout_disputed`,由客服仲裁。 - 订单完成后,账号和发布状态恢复为 `published`。 - 当前会生成开发态模拟钱包流水,不代表真实支付或提现。 ## 开发态超时任务 - 后端启动后会运行订单超时扫描任务,默认每 1 分钟执行一次。 -- 任务从 `system_configs` 读取超时阈值,包括号主待交接、租客确认收号、租客归还宽限和号主确认归还。 +- 任务从 `system_configs` 读取超时阈值,包括号主待交接、租客确认收号、租客结账宽限和号主确认结账。 - 号主待交接超时:订单保持 `pending_handoff`,交接状态变为 `owner_timeout`,租客仍可取消订单或发起申诉。 - 租客确认收号超时:订单状态变为 `abnormal`,交接状态变为 `renter_confirm_timeout`,进入客服介入。 -- 租客逾期未归还:订单状态变为 `overdue`,交接状态变为 `return_overdue`,租客仍可提交归还,号主可发起申诉。 -- 号主确认归还超时:订单状态变为 `abnormal`,交接状态变为 `owner_return_confirm_timeout`,进入客服复核。 +- 租客逾期未结账:订单状态变为 `overdue`,交接状态变为 `return_overdue`,租客仍可发起结账,号主可发起申诉。 +- 号主确认结账超时:订单状态变为 `abnormal`,交接状态变为 `owner_checkout_confirm_timeout`,进入客服复核。 - 每个超时动作只推进一次状态,避免重复通知。 - 超时动作会给相关用户写入站内信,并以 `system` 身份写入 `audit_logs`。 @@ -97,8 +100,10 @@ - 租客取消订单后通知号主和租客。 - 号主提交交接说明后通知租客。 - 租客确认收号后通知号主。 -- 租客提交归还后通知号主。 -- 号主确认归还后通知号主和租客。 +- 租客发起结账后通知号主。 +- 号主确认结账后通知号主和租客。 +- 号主修改结账后通知租客。 +- 租客拒绝修正结账后通知双方并进入争议。 - 发起申诉后通知对方和发起人。 - 仲裁完成后通知号主和租客。 - 站内信支持列表查询和标记已读。 @@ -107,7 +112,7 @@ - 订单双方都可以在非终态订单发起申诉。 - 同一个订单同一时间只允许存在一个 `open` 或 `processing` 申诉。 -- 发起申诉后订单状态变为 `disputing`,账号和发布保持锁定。 +- 发起普通申诉后订单状态变为 `disputing`,发起结账争议后订单状态变为 `checkout_disputing`,账号和发布保持锁定。 - 开发态后台仲裁接口为 `/api/admin/disputes`,当前只要求登录,后续接后台管理员和 RBAC。 - 仲裁会释放开发态模拟冻结金额,并根据结果生成钱包流水。 - 全额退款:释放冻结金额后,将租金加押金作为可用余额退给租客,订单置为 `closed`。 @@ -139,7 +144,7 @@ - 后台仪表盘接口为 `/api/admin/dashboard`,前端页面为 `/admin/dashboard`。 - 当前统计用户数、实名用户数、商品数、上架数、订单数、租赁中订单、今日订单、今日钱包流水。 -- 待处理事项包括待审核商品、待仲裁申诉、待交接订单和待归还确认订单。 +- 待处理事项包括待审核商品、待仲裁申诉、待交接订单和待结账确认订单。 - 最近订单和最近申诉用于运营快速定位问题,后续接入后台订单管理和商品审核后再跳转到对应详情页。 ## 开发态用户管理 diff --git a/docs/order-payment-implementation-plan.md b/docs/order-payment-implementation-plan.md new file mode 100644 index 0000000..1e3b51d --- /dev/null +++ b/docs/order-payment-implementation-plan.md @@ -0,0 +1,107 @@ +# 订单支付确认改造 —— 实施计划 + +> 状态:核心订单支付链路已按分步兼容策略实施;旧字段暂保留兼容 +> 日期:2026-05-24 + +说明:本文来自改造前计划,用于保留决策背景。当前分支没有直接删除旧价格/租期字段,也没有删除增量迁移文件;为了避免影响已有页面和开发库,采用 `price`、`rented_at` 等新字段优先、旧字段兜底的兼容迁移方式。 + +## 目标 + +将当前"下单即锁定"的流程改造为: + +``` +下单 → 待支付(pending_payment) → 支付确认 → 冻结锁定 → 待交接(pending_handoff) +``` + +同时清理 `price_hourly`、`price_daily`、`price_weekly`、`rent_start_at`、`rent_end_at`、`rent_hours` 等时租残留字段。 + +--- + +## 改造清单(按依赖顺序) + +``` +第1层(无依赖,可并行) +├── A. 合并 3 个 SQL 迁移文件 → 1 个 000001_init.sql +│ 修改 rental_listings:price + in_transaction +│ 修改 rental_orders:rented_at + estimated_duration_hours +│ 修改 notifications:category/link_type/link_id/extra_data +│ 新增 sms_logs 表 +│ 同步改 scripts/dev.sh +│ +├── B. Go 模型改造 +│ model/listing.go → Price + InTransaction +│ model/order.go → RentedAt + EstimatedDurationHours +│ model/notification.go → Category/LinkType/LinkID/ExtraData +│ +第2层(依赖第1层) +├── C. Listing 模块清理 +│ listing/dto.go → ListingDTO + CreateRequest 适配 +│ listing/repository.go → Create/Update/listQuery/toDTO 全部替换 +│ listing/service.go → 校验适配 +│ +├── D. Order DTO 改造 +│ order/dto.go → 删 RentStartAt/RentEndAt/RentHours,加 RentedAt/EstimatedDurationHours +│ +第3层(依赖第2层) +├── E. Order 核心改造 +│ order/service.go → 删 internalOrderHours,加错误,加 Pay() +│ order/repository.go → Create() → pending_payment + in_transaction +│ order/repository.go → 新增 Pay():余额→扣款→冻结→锁定→通知 +│ order/repository.go → Cancel() 适配 pending_payment +│ order/handler.go → 新增 Pay handler +│ 路由注册 → POST /orders/:id/pay +│ +├── F. 钱包充值 +│ wallet/repository.go → Recharge() +│ wallet/service.go → Recharge() +│ wallet/handler.go → Recharge handler +│ 路由注册 → POST /wallet/recharge +│ +第4层(依赖第3层 E) +└── G. 超时扫描 + job.go → 新增 handlePendingPaymentTimeout(15min 超时取消) + system_configs → order.pending_payment_timeout_minutes: 15 +``` + +--- + +## API 变更 + +| API | 类型 | 说明 | +|-----|------|------| +| `POST /api/orders` | 行为变更 | 返回 `pending_payment`,不锁商品,标记 `in_transaction` | +| `POST /api/orders/{id}/pay` | **新增** | 校验余额→扣款→冻结→锁定→通知 | +| `POST /api/orders/{id}/cancel` | 行为变更 | 允许取消 `pending_payment` | +| `POST /api/wallet/recharge` | **新增** | 开发环境充值 | + +--- + +## 涉及文件 + +### 修改(17 个) +``` +backend/migrations/000001_init.sql +scripts/dev.sh +backend/internal/model/listing.go +backend/internal/model/order.go +backend/internal/model/notification.go +backend/internal/modules/listing/dto.go +backend/internal/modules/listing/repository.go +backend/internal/modules/listing/service.go +backend/internal/modules/order/dto.go +backend/internal/modules/order/service.go +backend/internal/modules/order/repository.go +backend/internal/modules/order/handler.go +backend/internal/modules/wallet/repository.go +backend/internal/modules/wallet/service.go +backend/internal/modules/wallet/handler.go +backend/internal/router/router.go(或同等路由文件) +backend/internal/jobs/ordertimeout/job.go +backend/internal/modules/systemconfig/defaults.go(或同等文件) +``` + +### 删除(2 个) +``` +backend/migrations/000002_order_checkouts.sql +backend/migrations/000003_add_indexes.sql +``` diff --git a/docs/order-testing-messaging-analysis.md b/docs/order-testing-messaging-analysis.md new file mode 100644 index 0000000..e442207 --- /dev/null +++ b/docs/order-testing-messaging-analysis.md @@ -0,0 +1,511 @@ +# HFB Sys 订单购买测试 & 消息系统增强 —— 综合分析报告 + +> 生成日期:2026-05-24 +> 状态:订单支付与开发充值主链路已实施;消息系统增强留待后续 + +说明:本文来自改造前分析,用于保留问题背景和测试思路。文中对“当前链路”的描述对应改造前状态;当前分支已接入 `pending_payment`、支付冻结、开发充值、结账确认等订单系统能力,消息系统增强仍未纳入本轮改造。 + +--- + +## 第一部分:如何进行实际的订单购买测试 + +### 1. 当前完整订单购买链路 + +从前端到后端,当前链路如下: + +``` +租客浏览商品列表 → 点击商品详情 → 点击"立即租赁" + ↓ +MobileListingDetailView.vue 调用 createOrder(listingId) + ↓ +POST /api/orders {listing_id} + ↓ +handler.CreateOrder() → 验证 listing 状态(published & approved) + ↓ +service.CreateOrder(ctx, userID, listingID) + ↓ +repository.Create(tx) → 一条大事务: + ├── SELECT listing + account FOR UPDATE (悲观锁防并发) + ├── 校验: listing.status=published, account.status=published + ├── INSERT rental_orders (status=pending_handoff, rent_hours=24 硬编码) + ├── UPDATE listing.status → rented, account.status → rented + ├── INSERT account_snapshot (JSON 字段, 记录下单时资产快照) + ├── INSERT wallet_ledger (order_lock, 模拟冻结 rent_amount + deposit_amount) + ├── UPDATE wallet_accounts (frozen_balance ↑) + ├── notification.Append() → 通知号主+租客 + └── COMMIT +``` + +**关键发现——无支付环节**:`POST /api/orders` 调用后直接进入 `pending_handoff`,完全没有支付确认步骤。这是因为项目计划明确说"一期先做账务模型,不直接接真实支付和提现"。 + +### 2. 当前存在的 9 个关键缺失 + +| # | 缺失项 | 影响 | 涉及文件 | +|---|--------|------|----------| +| 1 | **无支付确认步骤** | 订单创建即生效,无资金冻结验证 | `order/repository.go` Create() | +| 2 | **租期硬编码 24h** | `internalOrderHours = 24`,用户无法选择 | `order/repository.go:21` | +| 3 | **无余额校验** | 下单时未检查租客 `available_balance >= rent_amount + deposit_amount` | `order/repository.go` Create() | +| 4 | **前端余额硬编码** | `MobileProfileView.vue` 写死 `¥0.00`,未调 API | `MobileProfileView.vue` | +| 5 | **钱包首次查询才创建** | `GET /api/wallet/balance` 首次访问才初始化账户 | `wallet/repository.go` | +| 6 | **无充值入口** | 没有任何充值接口或页面 | 全项目 | +| 7 | **站内信前端空壳** | `MobileMessagesView.vue` 只显示 `van-empty` | `MobileMessagesView.vue` | +| 8 | **无租期即将结束提醒** | 项目计划中规划了但未实现 | 超时扫描任务 | +| 9 | **短信完全未接** | 只有登录验证码的 mock,业务通知短信完全缺失 | `integrations/sms/` | + +### 3. 要完成端到端测试必须补充的最小功能集 + +``` +必须在测试前补充的功能(按依赖顺序): + +第1步:余额充值(测试前置条件) + └── POST /api/wallet/recharge {amount} → 给测试用户加余额 + +第2步:租期选择(核心流程) + └── 前端:下单时增加租期选择组件 + └── 后端:CreateOrderDTO 增加 rent_hours 字段 + +第3步:支付确认步骤(状态机改造) + └── 新增订单状态:pending_payment + └── POST /api/orders → pending_payment(而非直接 pending_handoff) + └── POST /api/orders/{id}/pay → 校验余额 → 扣款 → pending_handoff + +第4步:前端站内信接入 + └── MobileMessagesView.vue 接入 fetchNotifications API + └── 底部导航栏增加未读消息角标 +``` + +### 4. 支付确认步骤的推荐设计 + +``` +建议的状态机改造(最小侵入): + +POST /api/orders + ↓ +[新增] pending_payment(待支付,默认 15 分钟超时自动取消) + ↓ +POST /api/orders/{id}/pay + ├── 校验:订单归属租客、status=pending_payment、未超时 + ├── 校验:wallet_accounts.available_balance >= rent_amount + deposit_amount + ├── UPDATE wallet_accounts: available_balance -= total, frozen_balance += total + ├── INSERT wallet_ledger: order_lock (冻结流水) + ├── UPDATE rental_orders: status → pending_handoff + ├── UPDATE listing + account: status → rented + └── notification.Append() → 通知双方 +``` + +对应的新 API: +- `POST /api/orders/{id}/pay` — 确认支付 +- `GET /api/orders/{id}/payment-status` — 查询支付状态 +- 超时扫描任务新增:`pending_payment` 超过 15 分钟 → 自动取消 + +### 5. 完整测试场景清单 + +#### 5.1 正常流程测试 + +| 场景 | 步骤 | 验证点 | +|------|------|--------| +| 完整租赁闭环 | 浏览→下单→支付→号主交接→收号确认→租赁→结账→号主确认→完成 | 所有状态流转正确,资金流水完整 | +| 租期选择 | 选择不同租期(1h/3h/12h/24h) | rent_end_at 正确计算,租金按比例 | +| 多商品下单 | 不同商品分别下单 | 互不影响,各自锁定 | +| 结账修改流程 | 号主修改结账金额→租客同意修正 | 状态流转:pending_checkout_confirm → pending_checkout_accept → completed | + +#### 5.2 边界与异常测试 + +| 场景 | 验证点 | +|------|--------| +| 余额不足下单 | 返回明确错误,不创建订单 | +| 已租出商品下单 | `SELECT FOR UPDATE` 后检测到 status≠published,拒绝 | +| 审核未通过商品下单 | 拒绝(review_status≠approved) | +| 自己租自己 | 拒绝(owner_id = renter_id) | +| 未实名租客下单 | 根据 system_config 的 `realname_required_for_order` 配置 | +| 非法状态转换 | 已取消订单不能再次取消,已完成订单不能结账等 | +| 结账争议流程 | 任一方发起争议→客服仲裁→完成/关闭 | + +#### 5.3 并发测试 + +| 场景 | 验证点 | +|------|--------| +| 2 人同时下单同一商品 | `SELECT FOR UPDATE` 保证只有一人成功 | +| 同时支付+超时取消 | 互斥,不会出现既支付又取消 | +| 并发结算 | wallet_ledger 不出现负数或重复入账 | +| 并发创建订单 | 库存锁定正确 | + +#### 5.4 超时测试(依赖超时扫描任务) + +| 超时类型 | 默认阈值 | 期望行为 | +|----------|----------|----------| +| 待支付超时 | 15 min | 订单自动取消 | +| 号主待交接超时 | 30 min | handoff_status → owner_timeout,通知双方 | +| 租客确认收号超时 | 30 min | status → abnormal,客服介入 | +| 租客逾期未结账 | 10 min 宽限 | status → overdue | +| 号主确认结账超时 | 120 min | status → abnormal | + +#### 5.5 安全测试 + +| 场景 | 验证点 | +|------|--------| +| 未登录访问 | 所有写接口返回 401 | +| 跨用户操作 | A 不能取消 B 的订单,不能确认 B 的收号 | +| 后台接口保护 | 普通用户 token 不能访问 /api/admin/* | +| 重复提交 | 防重机制(前端 loading + 后端幂等) | +| SQL 注入 | 所有查询通过 GORM 参数化 | +| 越权查看 | 用户不能查看他人订单、钱包、交接记录 | + +### 6. 具体测试实施方案 + +#### 6.1 测试环境搭建 + +```bash +# 1. 启动基础设施 +docker compose -f deploy/docker-compose.dev.yml up -d + +# 2. 初始化数据库 +docker exec -i hfb-mysql mysql -uhfb -psecret hfb_sys < backend/migrations/000001_init.sql + +# 3. 启动后端 +cd backend && cp .env.example .env && go run ./cmd/api + +# 4. 启动前端 +cd frontend && npm install && npm run dev +``` + +#### 6.2 手动端到端测试步骤(核心路径) + +``` +前置条件:准备两个测试手机号(号主A + 租客B) + +Step 1: 号主A 注册/登录 + POST /api/auth/sms/send {phone: "138xxxx0001"} + POST /api/auth/sms/login {phone: "138xxxx0001", code: "从日志获取"} + +Step 2: 号主A 实名认证(mock) + POST /api/realname/start {name: "张三", id_no: "110101199001011234"} + +Step 3: 号主A 发布商品 + POST /api/listings { + game_name: "三角洲行动", + server_region: "微信区", + haf_coin_amount: 5000000, + price_hourly: 10, + deposit_amount: 100, + min_rent_hours: 1, + max_rent_hours: 24 + } + POST /api/listings/{id}/submit-review + +Step 4: 后台审核通过 + POST /api/admin/auth/login {username: "admin", password: "admin123456", captcha: "..."} + POST /api/admin/listings/{id}/approve + +Step 5: 租客B 注册/登录 + (同 Step 1,使用 138xxxx0002) + +Step 6: 租客B 充值(当前需手动) + 直接改数据库或通过调试接口给租客B加余额 + +Step 7: 租客B 浏览并下单 + GET /api/listings → 查看商品 + POST /api/orders {listing_id, rent_hours: 3} + +Step 8: 租客B 支付(当前直接跳到 pending_handoff,后续需补充) + 验证订单状态 + +Step 9: 号主A 提交交接说明 + POST /api/orders/{id}/handoff {content: "登录方式:..."} + +Step 10: 租客B 确认收号 + POST /api/orders/{id}/confirm-receive + +Step 11: 租客B 发起结账 + POST /api/orders/{id}/checkout { + content: "使用结束", + consumable_amount: 30, + coin_consumed_m: 0.5 + } + +Step 12: 号主A 确认结账 + POST /api/orders/{id}/checkout/confirm + +Step 13: 验证结果 + GET /api/orders/{id} → status=completed + GET /api/wallet/ledger → 流水完整 +``` + +#### 6.3 自动化测试建议 + +| 层级 | 工具 | 覆盖内容 | +|------|------|----------| +| 单元测试 | Go testing + testify | Repository 的事务方法,Service 参数校验 | +| 集成测试 | Go testing + testcontainers | 真实 MySQL/Redis 下的完整流程 | +| API 测试 | Postman/Newman 或 Go httptest | 所有 API 端点的正常+异常路径 | +| E2E 测试 | Playwright 或 Cypress | 前端页面操作完整流程 | +| 并发测试 | Go benchmark + goroutines | 并发下单、并发结算 | + +--- + +## 第二部分:应增加什么消息系统 + +### 1. 现有消息系统现状评估 + +#### 1.1 站内信体系 + +**好消息**:后端站内信的写入非常完整——所有 18 个关键业务节点都在事务内通过 `notification.Append(tx, ...)` 写入,覆盖了订单全生命周期的每个状态变更。 + +| 文件 | notification.Append 调用次数 | 场景 | +|------|------------------------------|------| +| `order/repository.go` | 9 次 | 创建/取消/交接/收号/结账/修改结账/客服关闭/标记异常/完成结算 | +| `dispute/repository.go` | 4 次 | 发起申诉(2)/仲裁完成(2) | +| `ordertimeout/job.go` | 4 次 | 号主超时/收号超时/逾期/确认结账超时 | + +**坏消息**:前端完全没接——`MobileMessagesView.vue` 只有一个 `van-empty` 组件,`Desktop NotificationsView.vue` 虽然接入了 API 但缺乏未读数角标和分类。 + +#### 1.2 表结构分析 + +```sql +notifications ( + id, user_id, type, title, content, + biz_type, biz_id, read_at, created_at +) +``` + +**当前优点**: +- 简洁高效 +- `(user_id, read_at, created_at)` 联合索引支持快速分页查询 + +**当前不足**: +- 缺少 `category` 字段(订单消息/系统通知/公告无法区分) +- 缺少软删除标记 +- 缺少 `extra_data` (JSON) 用于存储跳转链接等扩展信息 + +#### 1.3 对照项目计划的缺口 + +项目计划第 8 章规划的但**尚未实现**的场景: + +| 规划场景 | 当前状态 | 优先级 | +|----------|----------|--------| +| 商品审核通过/拒绝通知号主 | ✅ 已实现 | — | +| 租期即将结束提醒 | ❌ 未实现 | 🔴 高 | +| 账户冻结/解冻通知用户 | ❌ 未实现 | 🟡 中 | +| 短信登录验证码 | ✅ mock | — | +| 租期即将到期短信 | ❌ 未实现 | 🔴 高 | +| 申诉被受理短信 | ❌ 未实现 | 🟡 中 | +| 仲裁结果短信 | ❌ 未实现 | 🟡 中 | +| WebSocket/SSE 实时推送 | ❌ 未实现 | 🟢 低 | + +### 2. 推荐的消息系统增强架构 + +#### 2.1 站内信增强(Phase 1 — 立即做) + +``` +最小可行方案: +┌─────────────────────────────────────────────────┐ +│ notifications 表扩展 │ +├─────────────────────────────────────────────────┤ +│ + category VARCHAR(32) -- order|system|announce │ +│ + link_type VARCHAR(32) -- order_detail|... │ +│ + link_id BIGINT │ +│ + extra_data JSON -- 扩展数据 │ +├─────────────────────────────────────────────────┤ +│ 新增 API: │ +│ GET /api/notifications/unread-count │ +│ POST /api/notifications/batch-read │ +└─────────────────────────────────────────────────┘ + +前端改动: +├── MobileMessagesView.vue:接入 fetchNotifications,消息列表 +├── 底部导航栏:未读消息红点角标 +├── Desktop NotificationsView.vue:增强消息分类和已读标记 +└── Router:增加消息未读数 store +``` + +#### 2.2 短信系统增强(Phase 2 — 短期) + +``` +设计短信 Provider 抽象层: + +internal/integrations/sms/ +├── provider.go ← Provider 接口 +│ type Provider interface { +│ Send(ctx, phone, templateCode string, params map[string]string) error +│ SendBatch(ctx, phones []string, ...) error +│ } +├── mock.go ← MockProvider(开发环境) +├── aliyun.go ← AliyunProvider(生产环境) +├── limiter.go ← 限流器(基于 Redis) +│ - 手机号维度:60s/次,10次/天 +│ - IP 维度:100次/小时 +│ - 场景维度:可配置 +└── logger.go ← 发送日志(sms_logs 表) + +短信触发场景: +├── 登录验证码(已有 mock) +├── 租期即将到期提醒(新增 🔴) +├── 订单申诉被受理(新增 🟡) +├── 仲裁结果通知(新增 🟡) +└── 高风险安全提醒(预留) +``` + +#### 2.3 SSE 实时推送架构(Phase 3 — 中期) + +``` +推荐 SSE(Server-Sent Events)而非 WebSocket: +理由:本场景是单向推送(服务端→客户端),SSE 更轻量, + 基于 HTTP,不需要额外协议升级,断线自动重连。 + +Go 侧架构: +┌──────────────────────────────────────┐ +│ SSEBroker (单例) │ +├──────────────────────────────────────┤ +│ clients map[userID]*SSEClient │ +│ Notify(userID, event) │ +│ Broadcast(event) │ +└──────────────────────────────────────┘ + ↓ 事件分发 +┌──────────────────────────────────────┐ +│ SSE Events: │ +│ - order.status_changed │ +│ - order.handoff_updated │ +│ - order.checkout_updated │ +│ - notification.new │ +│ - dispute.updated │ +└──────────────────────────────────────┘ + +Vue 侧: +// composables/useSSE.ts +const eventSource = new EventSource('/api/sse/stream?token=xxx') +eventSource.addEventListener('notification.new', (e) => { + const data = JSON.parse(e.data) + notificationStore.incrementUnread() +}) + +重连策略: +- EventSource 原生支持自动重连 +- 可设置 retry interval: 3000ms +- 重连时重新验证 token +``` + +#### 2.4 订单全链路状态变更推送矩阵 + +``` +订单状态变更 → 推送内容设计: + +pending_payment → 租客: {type:"order.created", title:"订单已创建", orderId, amount, expireAt} + 号主: {type:"order.new_rental", title:"有新的租用请求"} + +pending_handoff → 租客: {type:"order.paid", title:"支付成功,等待号主交接"} + 号主: {type:"order.pending_handoff", title:"请尽快完成账号交接"} + +pending_renter_confirm → 租客: {type:"handoff.submitted", title:"号主已完成交接,请确认收号"} + +renting → 号主: {type:"handoff.confirmed", title:"租客已确认收号,租赁开始"} + +[租期结束前5分钟] → 租客: {type:"rental.expiring", title:"租期即将结束"} + +pending_checkout_confirm → 号主: {type:"checkout.submitted", title:"租客已发起结账"} + +completed → 双方: {type:"order.completed", title:"订单已完成"} +``` + +### 3. 数据库设计建议 + +#### 3.1 新增表 + +```sql +-- 短信发送日志 +CREATE TABLE sms_logs ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + phone VARCHAR(20) NOT NULL, + template_code VARCHAR(64) NOT NULL, + template_params JSON, + status VARCHAR(16) NOT NULL DEFAULT 'pending', -- pending|sent|failed + provider VARCHAR(32) NOT NULL, + provider_msg_id VARCHAR(128), + error_msg VARCHAR(512), + biz_type VARCHAR(32), + biz_id BIGINT UNSIGNED, + user_id BIGINT UNSIGNED, + created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + INDEX idx_sms_logs_phone_created (phone, created_at), + INDEX idx_sms_logs_status (status) +); + +-- SSE 推送记录(可选,用于对账) +CREATE TABLE push_records ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + user_id BIGINT UNSIGNED NOT NULL, + event_type VARCHAR(64) NOT NULL, + payload JSON, + delivered TINYINT DEFAULT 0, + delivered_at DATETIME, + created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + INDEX idx_push_records_user (user_id, created_at) +); +``` + +#### 3.2 notifications 表扩展 + +```sql +ALTER TABLE notifications + ADD COLUMN category VARCHAR(32) NOT NULL DEFAULT 'order' + COMMENT 'order|system|announce|security', + ADD COLUMN link_type VARCHAR(32) DEFAULT NULL + COMMENT 'order_detail|listing_detail|dispute_detail|wallet|url', + ADD COLUMN link_id BIGINT UNSIGNED DEFAULT NULL, + ADD COLUMN extra_data JSON DEFAULT NULL; +``` + +### 4. 实施优先级总览 + +``` +Phase 1(立即 — 让消息系统可用) +├── ✅ 让 MobileMessagesView.vue 接入 fetchNotifications +├── ✅ 底部导航栏增加未读消息角标 +├── ✅ 增加 GET /api/notifications/unread-count API +├── ✅ 增加 POST /api/notifications/batch-read API +└── ✅ 消息列表支持点击跳转到对应订单详情 + +Phase 2(短期 — 完善通知体系) +├── notifications 表扩展 category/link_type/extra_data +├── 实现租期即将结束通知(站内信 + 前端定时检查) +├── 实现用户冻结/解冻通知 +├── 短信 Provider 抽象层 + 限流器 +├── sms_logs 表 + 短信日志后台查看 +└── 接入一个真实短信服务商 + +Phase 3(中期 — 实时体验) +├── SSE Broker 实现 +├── 订单状态实时推送接入前端 +├── 租期倒计时实时更新 +├── 客服消息实时通知 +└── push_records 表(可选) +``` + +--- + +## 附录:关键文件索引 + +### 后端核心文件 + +| 文件 | 说明 | +|------|------| +| `backend/internal/modules/order/repository.go` | 订单 Repository,核心业务逻辑(1089行) | +| `backend/internal/modules/order/handler.go` | 订单 HTTP Handler(376行) | +| `backend/internal/modules/order/service.go` | 订单 Service 层(160行) | +| `backend/internal/modules/order/dto.go` | 订单 DTO 定义(126行) | +| `backend/internal/model/order.go` | RentalOrder 模型定义 | +| `backend/internal/modules/wallet/repository.go` | 钱包 Repository + AppendEntries | +| `backend/internal/modules/notification/repository.go` | 通知 Repository + Append | +| `backend/internal/modules/dispute/repository.go` | 争议仲裁 Repository | +| `backend/internal/jobs/ordertimeout/job.go` | 超时扫描定时任务 | + +### 前端核心文件 + +| 文件 | 说明 | +|------|------| +| `frontend/src/views/mobile/MobileListingDetailView.vue` | 商品详情/下单页 | +| `frontend/src/views/mobile/MobileOrdersView.vue` | 订单列表页 | +| `frontend/src/views/mobile/MobileMessagesView.vue` | 消息页(空壳) | +| `frontend/src/views/mobile/MobileProfileView.vue` | 个人中心(余额硬编码) | +| `frontend/src/api/orders.ts` | 订单 API 定义 | +| `frontend/src/api/notifications.ts` | 通知 API 定义 | +| `frontend/src/api/wallet.ts` | 钱包 API 定义 | diff --git a/docs/project-plan.md b/docs/project-plan.md index b5e827d..e1fa927 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -113,7 +113,7 @@ - 租客选择商品和租期后创建订单。 - 系统锁定商品库存,避免同一账号被重复出租。 -- 订单流转覆盖待确认、待交接、租赁中、待归还确认、已完成、已取消、申诉中。 +- 订单流转覆盖待确认、待交接、租赁中、待号主确认结账、待租客确认修正、结账争议中、已完成、已取消、申诉中。 钱包账务: @@ -142,10 +142,10 @@ 2. 订单确认后,商品进入锁定状态,订单进入待交接。 3. 号主在订单内提交交接说明,例如登录方式、注意事项、联系说明或外部交接备注。 4. 租客确认收到账号后,订单进入租赁中,并记录租赁开始时间和预计结束时间。 -5. 租期即将结束时,系统通过站内信和短信提醒租客归还。 -6. 租客提交归还申请,上传必要的租后截图或说明。 -7. 号主确认账号状态无误后,订单进入结算。 -8. 如任一方对交接、使用、归还或资产变化有异议,订单进入申诉仲裁。 +5. 租期即将结束时,系统通过站内信和短信提醒租客完成使用并发起结账。 +6. 租客发起结账,填写使用结束说明、消耗金额、哈夫币消耗量和必要证据。 +7. 号主确认账号状态无误后直接完成结算,或修改结账金额后交由租客确认。 +8. 租客同意修正后订单完成;拒绝修正或任一方对交接、使用、结账、资产变化有异议时,订单进入申诉仲裁。 回收边界: @@ -158,8 +158,8 @@ - 号主待交接超时:订单进入待交接后,默认 30 分钟未提交交接说明,租客可取消订单或发起申诉。 - 租客确认收号超时:号主提交交接说明后,默认 30 分钟未确认收号,订单进入客服介入,不自动开始租期。 -- 租客归还超时:超过租期结束时间仍未提交归还,系统提醒后进入逾期中,号主可发起申诉。 -- 号主确认归还超时:租客提交归还后,默认 2 小时未确认,订单进入自动确认候选或客服复核。 +- 租客结账超时:超过租期结束时间仍未发起结账,系统提醒后进入逾期中,号主可发起申诉。 +- 号主确认结账超时:租客发起结账后,默认 2 小时未确认,订单进入客服复核。 - 所有超时阈值必须进入 `system_configs` 管理,后台可调整。 订单状态机: @@ -173,12 +173,16 @@ | 待交接 | 申诉中 | 租客/号主 | 交接争议或安全验证无法完成 | | 待收号确认 | 租赁中 | 租客 | 租客确认收到账号并可正常登录 | | 待收号确认 | 申诉中 | 租客/系统 | 租客确认超时、无法登录或描述不符 | -| 租赁中 | 逾期中 | 系统 | 超过租期结束时间仍未提交归还 | -| 租赁中 | 待归还确认 | 租客 | 租客提交归还和租后凭证 | -| 逾期中 | 待归还确认 | 租客 | 租客补交归还申请 | +| 租赁中 | 逾期中 | 系统 | 超过租期结束时间仍未发起结账 | +| 租赁中 | 待号主确认结账 | 租客 | 租客发起结账和租后凭证 | +| 逾期中 | 待号主确认结账 | 租客 | 租客补交结账申请 | | 逾期中 | 申诉中 | 号主/系统 | 逾期未归还或疑似资产损失 | -| 待归还确认 | 已完成 | 号主/系统 | 号主确认归还,或超时后客服/系统确认 | -| 待归还确认 | 申诉中 | 号主/租客 | 归还争议、资产损失或封号异常 | +| 待号主确认结账 | 已完成 | 号主 | 号主确认结账 | +| 待号主确认结账 | 待租客确认修正 | 号主 | 号主修改结账金额 | +| 待租客确认修正 | 已完成 | 租客 | 租客同意修正结账 | +| 待号主确认结账 | 结账争议中 | 任一方 | 发起结账争议 | +| 待租客确认修正 | 结账争议中 | 任一方 | 发起结账争议 | +| 结账争议中 | 已完成/已关闭/异常 | 客服 | 后台仲裁 | | 申诉中 | 已完成 | 客服 | 仲裁为正常完成或部分扣款后完成 | | 申诉中 | 已取消 | 客服 | 仲裁为订单取消和退款 | | 申诉中 | 已关闭 | 客服 | 仲裁为异常关闭、冻结用户或冻结商品 | @@ -216,7 +220,7 @@ 结算规则: - 正常完成订单后,租金按平台抽成规则分账给号主。 -- 押金在号主确认归还后释放给租客。 +- 押金在双方结账确认或客服仲裁后释放给租客。 - 如发生资产损失、无法登录、封号或超时归还,可由客服仲裁后扣除部分或全部押金。 - 如号主虚假描述、超时未交接或账号无法使用,可裁定全额或部分退款。 - 仲裁导致的扣款、退款、赔付必须生成资金流水和审计日志。 @@ -281,8 +285,9 @@ - 号主提交交接说明。 - 租客确认收号。 - 租期即将结束。 -- 租客提交归还。 -- 号主确认归还。 +- 租客发起结账。 +- 号主确认或修改结账。 +- 租客确认或拒绝修正结账。 - 订单完成结算。 - 发起申诉。 - 仲裁结果。 @@ -592,8 +597,10 @@ - `GET /api/orders/{id}`:订单详情。 - `POST /api/orders/{id}/cancel`:取消订单。 - `POST /api/orders/{id}/confirm-receive`:租客确认收号。 -- `POST /api/orders/{id}/return`:租客提交归还。 -- `POST /api/orders/{id}/confirm-return`:号主确认归还。 +- `POST /api/orders/{id}/checkout`:租客发起结账。 +- `POST /api/orders/{id}/checkout/confirm`:号主确认结账。 +- `POST /api/orders/{id}/checkout/counter`:号主修改结账。 +- `POST /api/orders/{id}/checkout/accept`:租客同意修正结账。 - `POST /api/orders/{id}/dispute`:发起申诉。 交接: @@ -835,8 +842,8 @@ hfb_sys/ - 实现订单账号资产快照。 - 实现号主提交交接说明。 - 实现租客确认收号。 -- 实现租客提交归还、号主确认归还。 -- 实现交接、确认收号、归还、确认归还的超时处理。 +- 实现租客发起结账、号主确认或修改结账、租客确认或拒绝修正结账。 +- 实现交接、确认收号、结账逾期、确认结账超时处理。 - 实现钱包账户、押金冻结、租金流水、结算流水。 - 预留支付和提现接口。 @@ -887,9 +894,9 @@ hfb_sys/ - 商品草稿、待审核、已上架、已下架、审核拒绝状态流转正确。 - 审核未通过商品不能下单。 - 同一账号并发下单只能成功一单。 -- 订单待交接、租赁中、待归还确认、已完成、申诉中状态流转正确。 +- 订单待交接、租赁中、待号主确认结账、待租客确认修正、结账争议中、已完成、申诉中状态流转正确。 - 非法订单状态转换会被拒绝。 -- 交接、收号、归还、确认归还超时会按配置触发取消、申诉、逾期或客服复核。 +- 交接、收号、结账逾期、确认结账超时会按配置触发取消、申诉、逾期或客服复核。 - 押金冻结、释放、扣款、退款流水一致。 - 每笔 `wallet_ledger` 正确记录 `balance_after`。 - 租金、平台抽成、号主结算流水一致。 diff --git a/frontend/src/views/mobile/MobileListingDetailView.vue b/frontend/src/views/mobile/MobileListingDetailView.vue index cb32da3..1bf5a6c 100644 --- a/frontend/src/views/mobile/MobileListingDetailView.vue +++ b/frontend/src/views/mobile/MobileListingDetailView.vue @@ -318,10 +318,11 @@ function isNavActive(path: string) { round class="order-btn" :loading="ordering" + :disabled="listing.in_transaction" loading-text="下单中..." @click="handleCreateOrder" > - 立即下单 + {{ listing.in_transaction ? "交易中" : "立即下单" }}