第 4 阶段：订单、交接与账务--ok

backend/internal/model/wallet.go

@@ -0,0 +1,36 @@
+package model
+
+import "time"
+
+type WalletAccount struct {
+	ID               uint64    `gorm:"primaryKey" json:"id"`
+	UserID           uint64    `gorm:"not null;uniqueIndex" json:"user_id"`
+	AvailableBalance float64   `gorm:"type:decimal(12,2);not null;default:0" json:"available_balance"`
+	FrozenBalance    float64   `gorm:"type:decimal(12,2);not null;default:0" json:"frozen_balance"`
+	Status           string    `gorm:"size:32;not null;default:'active'" json:"status"`
+	CreatedAt        time.Time `json:"created_at"`
+	UpdatedAt        time.Time `json:"updated_at"`
+}
+
+func (WalletAccount) TableName() string {
+	return "wallet_accounts"
+}
+
+type WalletLedger struct {
+	ID           uint64    `gorm:"primaryKey" json:"id"`
+	LedgerNo     string    `gorm:"size:64;not null;uniqueIndex" json:"ledger_no"`
+	UserID       uint64    `gorm:"not null;index" json:"user_id"`
+	OrderID      *uint64   `json:"order_id"`
+	Direction    string    `gorm:"size:16;not null" json:"direction"`
+	Amount       float64   `gorm:"type:decimal(12,2);not null" json:"amount"`
+	BalanceAfter float64   `gorm:"type:decimal(12,2);not null" json:"balance_after"`
+	BalanceType  string    `gorm:"size:32;not null" json:"balance_type"`
+	BizType      string    `gorm:"size:32;not null" json:"biz_type"`
+	BizNo        string    `gorm:"size:64;not null" json:"biz_no"`
+	Remark       string    `gorm:"size:255;not null;default:''" json:"remark"`
+	CreatedAt    time.Time `json:"created_at"`
+}
+
+func (WalletLedger) TableName() string {
+	return "wallet_ledger"
+}

backend/internal/modules/order/dto.go

@@ -39,6 +39,10 @@ type SubmitHandoffRequest struct {
 	Content string `json:"content" binding:"required"`
 }
 
+type SubmitReturnRequest struct {
+	Content string `json:"content" binding:"required"`
+}
+
 type HandoffRecordDTO struct {
 	ID                  uint64     `json:"id"`
 	OrderID             uint64     `json:"order_id"`

backend/internal/modules/order/handler.go

@@ -145,6 +145,46 @@ func (h *Handler) HandoffRecords(c *gin.Context) {
 	response.OK(c, gin.H{"items": items})
 }
 
+func (h *Handler) SubmitReturn(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	id, ok := parseID(c)
+	if !ok {
+		return
+	}
+	var req SubmitReturnRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.BadRequest(c, "归还说明不能为空")
+		return
+	}
+	record, err := h.service.SubmitReturn(userID, id, req)
+	if err != nil {
+		writeOrderError(c, err)
+		return
+	}
+	response.Created(c, record)
+}
+
+func (h *Handler) ConfirmReturn(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	id, ok := parseID(c)
+	if !ok {
+		return
+	}
+	if err := h.service.ConfirmReturn(userID, id); err != nil {
+		writeOrderError(c, err)
+		return
+	}
+	response.OK(c, gin.H{"completed": true})
+}
+
 func currentUserID(c *gin.Context) (uint64, bool) {
 	value, ok := c.Get(middleware.ContextUserID)
 	if !ok {
@@ -179,6 +219,10 @@ func writeOrderError(c *gin.Context, err error) {
 		response.Error(c, http.StatusConflict, "order_cannot_handoff", "当前订单不能交接")
 	case errors.Is(err, ErrOrderCannotReceive):
 		response.Error(c, http.StatusConflict, "order_cannot_receive", "当前订单不能确认收号")
+	case errors.Is(err, ErrOrderCannotReturn):
+		response.Error(c, http.StatusConflict, "order_cannot_return", "当前订单不能归还")
+	case errors.Is(err, ErrOrderCannotComplete):
+		response.Error(c, http.StatusConflict, "order_cannot_complete", "当前订单不能完成")
 	case errors.Is(err, ErrPermissionDenied):
 		response.Error(c, http.StatusForbidden, "permission_denied", "无权操作该订单")
 	case IsNotFound(err):

backend/internal/modules/order/repository.go

@@ -5,10 +5,11 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"errors"
-	"fmt"
+	"strconv"
 	"time"
 
 	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/wallet"
 
 	"gorm.io/datatypes"
 	"gorm.io/gorm"
@@ -74,6 +75,21 @@ func (r *Repository) Create(renterID uint64, req CreateRequest) (*OrderDTO, erro
 		if err := tx.Create(&order).Error; err != nil {
 			return err
 		}
+		orderID := order.ID
+		if err := wallet.AppendEntries(tx,
+			wallet.Entry{
+				UserID:      renterID,
+				OrderID:     &orderID,
+				Direction:   "in",
+				Amount:      order.RentAmount + order.DepositAmount,
+				BalanceType: "frozen",
+				BizType:     "order_lock",
+				BizNo:       order.OrderNo,
+				Remark:      "开发态模拟冻结租金和押金",
+			},
+		); err != nil {
+			return err
+		}
 		listing.Status = "rented"
 		account.Status = "rented"
 		if err := tx.Save(&listing).Error; err != nil {
@@ -113,6 +129,21 @@ func (r *Repository) Cancel(userID uint64, orderID uint64) error {
 
 		order.Status = "cancelled"
 		order.HandoffStatus = "cancelled"
+		orderID := order.ID
+		if err := wallet.AppendEntries(tx,
+			wallet.Entry{
+				UserID:      order.RenterID,
+				OrderID:     &orderID,
+				Direction:   "out",
+				Amount:      order.RentAmount + order.DepositAmount,
+				BalanceType: "frozen",
+				BizType:     "order_cancel",
+				BizNo:       order.OrderNo,
+				Remark:      "取消订单释放模拟冻结金额",
+			},
+		); err != nil {
+			return err
+		}
 		listing.Status = "published"
 		account.Status = "published"
 		if err := tx.Save(&order).Error; err != nil {
@@ -204,6 +235,123 @@ func (r *Repository) HandoffRecords(userID uint64, orderID uint64) ([]HandoffRec
 	return items, nil
 }
 
+func (r *Repository) SubmitReturn(userID uint64, orderID uint64, req SubmitReturnRequest) (*HandoffRecordDTO, error) {
+	var recordID uint64
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		var order model.RentalOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&order, orderID).Error; err != nil {
+			return err
+		}
+		if order.RenterID != userID {
+			return ErrPermissionDenied
+		}
+		if order.Status != "renting" || order.HandoffStatus != "received" {
+			return ErrOrderCannotReturn
+		}
+		now := time.Now()
+		record := model.HandoffRecord{
+			OrderID:    order.ID,
+			FromUserID: order.RenterID,
+			ToUserID:   order.OwnerID,
+			Type:       "renter_return",
+			Content:    req.Content,
+		}
+		if err := tx.Create(&record).Error; err != nil {
+			return err
+		}
+		order.Status = "pending_return_confirm"
+		order.HandoffStatus = "pending_owner_return_confirm"
+		order.RentEndAt = &now
+		if err := tx.Save(&order).Error; err != nil {
+			return err
+		}
+		recordID = record.ID
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return r.findHandoffRecord(recordID)
+}
+
+func (r *Repository) ConfirmReturn(userID uint64, orderID uint64) error {
+	return r.db.Transaction(func(tx *gorm.DB) error {
+		var order model.RentalOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&order, orderID).Error; err != nil {
+			return err
+		}
+		if order.OwnerID != userID {
+			return ErrPermissionDenied
+		}
+		if order.Status != "pending_return_confirm" || order.HandoffStatus != "pending_owner_return_confirm" {
+			return ErrOrderCannotComplete
+		}
+		now := time.Now()
+		if err := tx.Model(&model.HandoffRecord{}).
+			Where("order_id = ? AND type = ?", order.ID, "renter_return").
+			Update("confirmed_by_owner_at", now).Error; err != nil {
+			return err
+		}
+		var listing model.RentalListing
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&listing, order.ListingID).Error; err != nil {
+			return err
+		}
+		var account model.GameAccount
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&account, order.AccountID).Error; err != nil {
+			return err
+		}
+		order.Status = "completed"
+		order.HandoffStatus = "returned"
+		order.SettlementStatus = "settled"
+		order.SettledAt = &now
+		order.OwnerSettledAt = &now
+		orderID := order.ID
+		if err := wallet.AppendEntries(tx,
+			wallet.Entry{
+				UserID:      order.RenterID,
+				OrderID:     &orderID,
+				Direction:   "out",
+				Amount:      order.RentAmount + order.DepositAmount,
+				BalanceType: "frozen",
+				BizType:     "order_settle",
+				BizNo:       order.OrderNo,
+				Remark:      "订单完成释放模拟冻结金额",
+			},
+			wallet.Entry{
+				UserID:      order.OwnerID,
+				OrderID:     &orderID,
+				Direction:   "in",
+				Amount:      order.RentAmount,
+				BalanceType: "available",
+				BizType:     "owner_income",
+				BizNo:       order.OrderNo,
+				Remark:      "订单完成模拟结算租金",
+			},
+			wallet.Entry{
+				UserID:      order.RenterID,
+				OrderID:     &orderID,
+				Direction:   "in",
+				Amount:      order.DepositAmount,
+				BalanceType: "available",
+				BizType:     "deposit_release",
+				BizNo:       order.OrderNo,
+				Remark:      "订单完成模拟退回押金",
+			},
+		); err != nil {
+			return err
+		}
+		listing.Status = "published"
+		account.Status = "published"
+		if err := tx.Save(&order).Error; err != nil {
+			return err
+		}
+		if err := tx.Save(&listing).Error; err != nil {
+			return err
+		}
+		return tx.Save(&account).Error
+	})
+}
+
 func (r *Repository) ListForUser(userID uint64) ([]OrderDTO, error) {
 	var rows []orderRow
 	err := r.baseQuery().
@@ -316,7 +464,7 @@ func newOrderNo() (string, error) {
 	if _, err := rand.Read(buf); err != nil {
 		return "", err
 	}
-	return fmt.Sprintf("RO%d%s", time.Now().UnixNano(), hex.EncodeToString(buf)), nil
+	return "RO" + strconv.FormatInt(time.Now().UnixNano(), 10) + hex.EncodeToString(buf), nil
 }
 
 func IsNotFound(err error) bool {

backend/internal/modules/order/service.go

@@ -10,6 +10,8 @@ var (
 	ErrOrderCannotCancel     = errors.New("order cannot cancel")
 	ErrOrderCannotHandoff    = errors.New("order cannot handoff")
 	ErrOrderCannotReceive    = errors.New("order cannot receive")
+	ErrOrderCannotReturn     = errors.New("order cannot return")
+	ErrOrderCannotComplete   = errors.New("order cannot complete")
 	ErrPermissionDenied      = errors.New("permission denied")
 )
 
@@ -62,6 +64,23 @@ func (s *Service) HandoffRecords(userID uint64, orderID uint64) ([]HandoffRecord
 	return s.repo.HandoffRecords(userID, orderID)
 }
 
+func (s *Service) SubmitReturn(userID uint64, orderID uint64, req SubmitReturnRequest) (*HandoffRecordDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if orderID == 0 || req.Content == "" {
+		return nil, ErrOrderCannotReturn
+	}
+	return s.repo.SubmitReturn(userID, orderID, req)
+}
+
+func (s *Service) ConfirmReturn(userID uint64, orderID uint64) error {
+	if s.repo == nil {
+		return ErrDependencyUnavailable
+	}
+	return s.repo.ConfirmReturn(userID, orderID)
+}
+
 func (s *Service) ListForUser(userID uint64) ([]OrderDTO, error) {
 	if s.repo == nil {
 		return nil, ErrDependencyUnavailable

backend/internal/modules/wallet/dto.go

@@ -0,0 +1,25 @@
+package wallet
+
+import "time"
+
+type AccountDTO struct {
+	UserID           uint64  `json:"user_id"`
+	AvailableBalance float64 `json:"available_balance"`
+	FrozenBalance    float64 `json:"frozen_balance"`
+	Status           string  `json:"status"`
+}
+
+type LedgerDTO struct {
+	ID           uint64    `json:"id"`
+	LedgerNo     string    `json:"ledger_no"`
+	UserID       uint64    `json:"user_id"`
+	OrderID      *uint64   `json:"order_id"`
+	Direction    string    `json:"direction"`
+	Amount       float64   `json:"amount"`
+	BalanceAfter float64   `json:"balance_after"`
+	BalanceType  string    `json:"balance_type"`
+	BizType      string    `json:"biz_type"`
+	BizNo        string    `json:"biz_no"`
+	Remark       string    `json:"remark"`
+	CreatedAt    time.Time `json:"created_at"`
+}

backend/internal/modules/wallet/handler.go

@@ -0,0 +1,64 @@
+package wallet
+
+import (
+	"errors"
+
+	"hfb_sys/backend/internal/middleware"
+	"hfb_sys/backend/pkg/response"
+
+	"github.com/gin-gonic/gin"
+)
+
+type Handler struct {
+	service *Service
+}
+
+func NewHandler(service *Service) *Handler {
+	return &Handler{service: service}
+}
+
+func (h *Handler) Balance(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	account, err := h.service.Account(userID)
+	if err != nil {
+		writeWalletError(c, err)
+		return
+	}
+	response.OK(c, account)
+}
+
+func (h *Handler) Ledger(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	items, err := h.service.Ledger(userID)
+	if err != nil {
+		writeWalletError(c, err)
+		return
+	}
+	response.OK(c, gin.H{"items": items})
+}
+
+func currentUserID(c *gin.Context) (uint64, bool) {
+	value, ok := c.Get(middleware.ContextUserID)
+	if !ok {
+		return 0, false
+	}
+	userID, ok := value.(uint64)
+	return userID, ok
+}
+
+func writeWalletError(c *gin.Context, err error) {
+	switch {
+	case errors.Is(err, ErrDependencyUnavailable):
+		response.ServiceUnavailable(c, "数据库未连接")
+	default:
+		response.ServiceUnavailable(c, "钱包服务暂时不可用")
+	}
+}

backend/internal/modules/wallet/repository.go

@@ -0,0 +1,165 @@
+package wallet
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+type Repository struct {
+	db *gorm.DB
+}
+
+type Entry struct {
+	UserID      uint64
+	OrderID     *uint64
+	Direction   string
+	Amount      float64
+	BalanceType string
+	BizType     string
+	BizNo       string
+	Remark      string
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+	return &Repository{db: db}
+}
+
+func (r *Repository) Account(userID uint64) (*AccountDTO, error) {
+	var account model.WalletAccount
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		if err := ensureAccount(tx, userID); err != nil {
+			return err
+		}
+		return tx.Where("user_id = ?", userID).First(&account).Error
+	})
+	if err != nil {
+		return nil, err
+	}
+	return toAccountDTO(account), nil
+}
+
+func (r *Repository) Ledger(userID uint64) ([]LedgerDTO, error) {
+	var rows []model.WalletLedger
+	if err := r.db.Where("user_id = ?", userID).Order("id DESC").Limit(100).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	items := make([]LedgerDTO, 0, len(rows))
+	for _, row := range rows {
+		items = append(items, toLedgerDTO(row))
+	}
+	return items, nil
+}
+
+func AppendEntries(tx *gorm.DB, entries ...Entry) error {
+	for _, entry := range entries {
+		if entry.Amount <= 0 {
+			continue
+		}
+		if err := ensureAccount(tx, entry.UserID); err != nil {
+			return err
+		}
+		var account model.WalletAccount
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("user_id = ?", entry.UserID).First(&account).Error; err != nil {
+			return err
+		}
+		balanceAfter, err := applyEntry(&account, entry)
+		if err != nil {
+			return err
+		}
+		if err := tx.Save(&account).Error; err != nil {
+			return err
+		}
+		ledgerNo, err := newLedgerNo()
+		if err != nil {
+			return err
+		}
+		ledger := model.WalletLedger{
+			LedgerNo:     ledgerNo,
+			UserID:       entry.UserID,
+			OrderID:      entry.OrderID,
+			Direction:    entry.Direction,
+			Amount:       entry.Amount,
+			BalanceAfter: balanceAfter,
+			BalanceType:  entry.BalanceType,
+			BizType:      entry.BizType,
+			BizNo:        entry.BizNo,
+			Remark:       entry.Remark,
+		}
+		if err := tx.Create(&ledger).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ensureAccount(tx *gorm.DB, userID uint64) error {
+	account := model.WalletAccount{
+		UserID:           userID,
+		AvailableBalance: 0,
+		FrozenBalance:    0,
+		Status:           "active",
+	}
+	return tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&account).Error
+}
+
+func applyEntry(account *model.WalletAccount, entry Entry) (float64, error) {
+	switch entry.BalanceType {
+	case "available":
+		if entry.Direction == "in" {
+			account.AvailableBalance += entry.Amount
+		} else {
+			account.AvailableBalance -= entry.Amount
+		}
+		return account.AvailableBalance, nil
+	case "frozen":
+		if entry.Direction == "in" {
+			account.FrozenBalance += entry.Amount
+		} else {
+			account.FrozenBalance -= entry.Amount
+		}
+		return account.FrozenBalance, nil
+	default:
+		return 0, fmt.Errorf("unsupported balance type: %s", entry.BalanceType)
+	}
+}
+
+func toAccountDTO(account model.WalletAccount) *AccountDTO {
+	return &AccountDTO{
+		UserID:           account.UserID,
+		AvailableBalance: account.AvailableBalance,
+		FrozenBalance:    account.FrozenBalance,
+		Status:           account.Status,
+	}
+}
+
+func toLedgerDTO(row model.WalletLedger) LedgerDTO {
+	return LedgerDTO{
+		ID:           row.ID,
+		LedgerNo:     row.LedgerNo,
+		UserID:       row.UserID,
+		OrderID:      row.OrderID,
+		Direction:    row.Direction,
+		Amount:       row.Amount,
+		BalanceAfter: row.BalanceAfter,
+		BalanceType:  row.BalanceType,
+		BizType:      row.BizType,
+		BizNo:        row.BizNo,
+		Remark:       row.Remark,
+		CreatedAt:    row.CreatedAt,
+	}
+}
+
+func newLedgerNo() (string, error) {
+	buf := make([]byte, 4)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("WL%d%s", time.Now().UnixNano(), hex.EncodeToString(buf)), nil
+}

backend/internal/modules/wallet/service.go

@@ -0,0 +1,27 @@
+package wallet
+
+import "errors"
+
+var ErrDependencyUnavailable = errors.New("dependency unavailable")
+
+type Service struct {
+	repo *Repository
+}
+
+func NewService(repo *Repository) *Service {
+	return &Service{repo: repo}
+}
+
+func (s *Service) Account(userID uint64) (*AccountDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.Account(userID)
+}
+
+func (s *Service) Ledger(userID uint64) ([]LedgerDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.Ledger(userID)
+}

backend/internal/router/router.go

@@ -9,6 +9,7 @@ import (
 	"hfb_sys/backend/internal/modules/order"
 	"hfb_sys/backend/internal/modules/realname"
 	"hfb_sys/backend/internal/modules/user"
+	"hfb_sys/backend/internal/modules/wallet"
 
 	"github.com/gin-gonic/gin"
 	"go.uber.org/zap"
@@ -52,6 +53,12 @@ func New(cfg config.Config, deps Dependencies, logger *zap.Logger) *gin.Engine {
 	}
 	orderService := order.NewService(orderRepo)
 	orderHandler := order.NewHandler(orderService)
+	var walletRepo *wallet.Repository
+	if deps.DB != nil {
+		walletRepo = wallet.NewRepository(deps.DB)
+	}
+	walletService := wallet.NewService(walletRepo)
+	walletHandler := wallet.NewHandler(walletService)
 	requireAuth := middleware.Auth(jwtManager)
 	requireRealname := middleware.RequireRealname(userRepo)
 
@@ -94,6 +101,14 @@ func New(cfg config.Config, deps Dependencies, logger *zap.Logger) *gin.Engine {
 			orderRoutes.POST("/:id/handoff", orderHandler.SubmitHandoff)
 			orderRoutes.GET("/:id/handoff-records", orderHandler.HandoffRecords)
 			orderRoutes.POST("/:id/confirm-receive", orderHandler.ConfirmReceive)
+			orderRoutes.POST("/:id/return", orderHandler.SubmitReturn)
+			orderRoutes.POST("/:id/confirm-return", orderHandler.ConfirmReturn)
+		}
+
+		walletRoutes := api.Group("/wallet", requireAuth)
+		{
+			walletRoutes.GET("/balance", walletHandler.Balance)
+			walletRoutes.GET("/ledger", walletHandler.Ledger)
 		}
 
 		realnameRoutes := api.Group("/realname", requireAuth)