chore(init): 初始化解忧商行项目并完成 Phase 0 基座

This commit is contained in:
yml2213
2026-10-30 11:46:10 +08:00
commit 8d9481c251
689 changed files with 138703 additions and 0 deletions
@@ -0,0 +1,42 @@
package paymentaccount
import (
"time"
)
type PaymentAccountDTO struct {
ID uint64 `json:"id"`
UserID uint64 `json:"user_id"`
AccountType string `json:"account_type"`
AccountName string `json:"account_name"`
AccountNo string `json:"account_no"` // 脱敏显示
BankName string `json:"bank_name"`
BankBranch string `json:"bank_branch"`
CertificateURLs []string `json:"certificate_urls"`
IsDefault bool `json:"is_default"`
Status string `json:"status"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
type CreatePaymentAccountRequest struct {
AccountType string `json:"account_type" binding:"required,oneof=alipay wechat bank"`
AccountName string `json:"account_name" binding:"required"`
AccountNo string `json:"account_no" binding:"required"`
BankName string `json:"bank_name"`
BankBranch string `json:"bank_branch"`
CertificateURLs []string `json:"certificate_urls"`
}
type UpdatePaymentAccountRequest struct {
BankBranch string `json:"bank_branch"`
CertificateURLs []string `json:"certificate_urls"`
IsDefault *bool `json:"is_default"`
}
type PaginatedResult struct {
Items []PaymentAccountDTO `json:"items"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
}
@@ -0,0 +1,185 @@
package paymentaccount
import (
"hfb_sys/backend/pkg/response"
"strconv"
"github.com/gin-gonic/gin"
)
type Handler struct {
service *Service
}
func NewHandler(service *Service) *Handler {
return &Handler{service: service}
}
func (h *Handler) List(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
result, err := h.service.List(c.Request.Context(), userID, page, pageSize)
if err != nil {
writeError(c, err)
return
}
response.OK(c, result)
}
func (h *Handler) FindByID(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
id, ok := parseID(c)
if !ok {
return
}
account, err := h.service.FindByID(c.Request.Context(), userID, id)
if err != nil {
writeError(c, err)
return
}
response.OK(c, account)
}
func (h *Handler) Create(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
var req CreatePaymentAccountRequest
if err := c.ShouldBindJSON(&req); err != nil {
response.BadRequest(c, "请求参数错误")
return
}
account, err := h.service.Create(c.Request.Context(), userID, req)
if err != nil {
writeError(c, err)
return
}
response.OK(c, account)
}
func (h *Handler) Update(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
id, ok := parseID(c)
if !ok {
return
}
var req UpdatePaymentAccountRequest
if err := c.ShouldBindJSON(&req); err != nil {
response.BadRequest(c, "请求参数错误")
return
}
account, err := h.service.Update(c.Request.Context(), userID, id, req)
if err != nil {
writeError(c, err)
return
}
response.OK(c, account)
}
func (h *Handler) Delete(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
id, ok := parseID(c)
if !ok {
return
}
if err := h.service.Delete(c.Request.Context(), userID, id); err != nil {
writeError(c, err)
return
}
response.OK(c, gin.H{"deleted": true})
}
func (h *Handler) SetDefault(c *gin.Context) {
userID, ok := currentUserID(c)
if !ok {
response.Unauthorized(c, "缺少用户上下文")
return
}
id, ok := parseID(c)
if !ok {
return
}
if err := h.service.SetDefault(c.Request.Context(), userID, id); err != nil {
writeError(c, err)
return
}
response.OK(c, gin.H{"updated": true})
}
// 辅助函数
func currentUserID(c *gin.Context) (uint64, bool) {
val, exists := c.Get("user_id")
if !exists {
return 0, false
}
userID, ok := val.(uint64)
return userID, ok
}
func parseID(c *gin.Context) (uint64, bool) {
idStr := c.Param("id")
id, err := strconv.ParseUint(idStr, 10, 64)
if err != nil {
response.BadRequest(c, "无效的ID")
return 0, false
}
return id, true
}
func writeError(c *gin.Context, err error) {
response.RecordError(c, err)
switch err {
case ErrAccountNotFound:
response.NotFound(c, "收款账号不存在")
case ErrAccountNameMismatch:
response.BadRequest(c, "账户名必须与实名认证姓名一致")
case ErrRealnameRequired:
response.BadRequest(c, "请先完成实名认证")
case ErrAccountLimit:
response.BadRequest(c, "收款账号数量已达上限(最多5个)")
case ErrCannotDeleteDefault:
response.BadRequest(c, "无法删除默认账号")
case ErrInvalidCertificateURL:
response.BadRequest(c, "收款凭证必须使用本人上传的图片")
default:
response.InternalServerError(c, "操作失败")
}
}
@@ -0,0 +1,394 @@
package paymentaccount
import (
"context"
"encoding/json"
"errors"
"net/url"
"strings"
"hfb_sys/backend/internal/model"
"hfb_sys/backend/pkg/crypto"
"gorm.io/datatypes"
"gorm.io/gorm"
)
type Repository struct {
db *gorm.DB
encryptor crypto.Encryptor
}
func NewRepository(db *gorm.DB, encryptor crypto.Encryptor) *Repository {
if encryptor == nil {
encryptor = &crypto.MockEncryptor{}
}
return &Repository{db: db, encryptor: encryptor}
}
func (r *Repository) List(ctx context.Context, userID uint64, page, pageSize int) (*PaginatedResult, error) {
db := r.db.WithContext(ctx)
var total int64
if err := db.Model(&model.UserPaymentAccount{}).
Where("user_id = ? AND status = ?", userID, "active").
Count(&total).Error; err != nil {
return nil, err
}
offset := (page - 1) * pageSize
var accounts []model.UserPaymentAccount
if err := db.Where("user_id = ? AND status = ?", userID, "active").
Order("is_default DESC, created_at DESC").
Offset(offset).Limit(pageSize).
Find(&accounts).Error; err != nil {
return nil, err
}
items := make([]PaymentAccountDTO, 0, len(accounts))
for _, acc := range accounts {
dto, err := r.toDTO(acc)
if err != nil {
continue
}
items = append(items, *dto)
}
return &PaginatedResult{
Items: items,
Total: total,
Page: page,
PageSize: pageSize,
}, nil
}
func (r *Repository) FindByID(ctx context.Context, userID, id uint64) (*PaymentAccountDTO, error) {
var account model.UserPaymentAccount
if err := r.db.WithContext(ctx).Where("id = ? AND user_id = ? AND status = ?", id, userID, "active").
First(&account).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrAccountNotFound
}
return nil, err
}
return r.toDTO(account)
}
func (r *Repository) Create(ctx context.Context, userID uint64, req CreatePaymentAccountRequest) (*PaymentAccountDTO, error) {
db := r.db.WithContext(ctx)
if err := r.validateCertificateURLs(ctx, userID, req.CertificateURLs, nil); err != nil {
return nil, err
}
// 加密账号
encryptedNo, err := r.encryptor.Encrypt(req.AccountNo)
if err != nil {
return nil, err
}
// 处理凭证URLs
var certURLs datatypes.JSON
if len(req.CertificateURLs) > 0 {
certURLs, _ = json.Marshal(req.CertificateURLs)
}
// 如果是第一个账号,自动设为默认
isDefault := false
var count int64
db.Model(&model.UserPaymentAccount{}).Where("user_id = ? AND status = ?", userID, "active").Count(&count)
if count == 0 {
isDefault = true
}
account := model.UserPaymentAccount{
UserID: userID,
AccountType: req.AccountType,
AccountName: req.AccountName,
AccountNo: encryptedNo,
BankName: req.BankName,
BankBranch: req.BankBranch,
CertificateURLs: certURLs,
IsDefault: isDefault,
Status: "active",
}
if err := db.Create(&account).Error; err != nil {
return nil, err
}
return r.FindByID(ctx, userID, account.ID)
}
func (r *Repository) Update(ctx context.Context, userID, id uint64, req UpdatePaymentAccountRequest) (*PaymentAccountDTO, error) {
db := r.db.WithContext(ctx)
var account model.UserPaymentAccount
if err := db.Where("id = ? AND user_id = ? AND status = ?", id, userID, "active").
First(&account).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrAccountNotFound
}
return nil, err
}
updates := make(map[string]interface{})
if req.BankBranch != "" {
updates["bank_branch"] = req.BankBranch
}
if len(req.CertificateURLs) > 0 {
var existingURLs []string
_ = json.Unmarshal(account.CertificateURLs, &existingURLs)
if err := r.validateCertificateURLs(ctx, userID, req.CertificateURLs, existingURLs); err != nil {
return nil, err
}
certURLs, _ := json.Marshal(req.CertificateURLs)
updates["certificate_urls"] = certURLs
}
if req.IsDefault != nil && *req.IsDefault {
// 先取消其他默认账号
db.Model(&model.UserPaymentAccount{}).
Where("user_id = ? AND id != ?", userID, id).
Update("is_default", false)
updates["is_default"] = true
}
if len(updates) > 0 {
if err := db.Model(&account).Updates(updates).Error; err != nil {
return nil, err
}
}
return r.FindByID(ctx, userID, id)
}
// validateCertificateURLs 确保新增收款凭证来自当前用户上传的 payment-cert 对象。
// 已绑定在当前收款账号上的历史凭证允许保留,避免旧数据无法编辑。
func (r *Repository) validateCertificateURLs(ctx context.Context, userID uint64, values []string, existing []string) error {
if len(values) == 0 {
return nil
}
existingKeys := make(map[string]struct{}, len(existing))
for _, value := range existing {
if key, ok := paymentCertificateKey(value); ok {
existingKeys[key] = struct{}{}
}
}
for _, value := range values {
key, ok := paymentCertificateKey(value)
if !ok {
return ErrInvalidCertificateURL
}
if _, exists := existingKeys[key]; exists {
continue
}
var count int64
if err := r.db.WithContext(ctx).Table("file_upload_owners").
Where("user_id = ? AND object_key = ?", userID, key).
Count(&count).Error; err != nil {
return err
}
if count == 0 {
return ErrInvalidCertificateURL
}
}
return nil
}
func paymentCertificateKey(value string) (string, bool) {
parsed, err := url.Parse(value)
if err != nil {
return "", false
}
if parsed.Path != "/api/files/object" && parsed.Path != "/api/public/files/object" {
return "", false
}
key := parsed.Query().Get("key")
if !strings.HasPrefix(key, "payment-cert/") {
return "", false
}
return key, true
}
func (r *Repository) Delete(ctx context.Context, userID, id uint64) error {
db := r.db.WithContext(ctx)
var account model.UserPaymentAccount
if err := db.Where("id = ? AND user_id = ? AND status = ?", id, userID, "active").
First(&account).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return ErrAccountNotFound
}
return err
}
// 软删除
return db.Model(&account).Update("status", "disabled").Error
}
func (r *Repository) SetDefault(ctx context.Context, userID, id uint64) error {
// 验证账号存在
var account model.UserPaymentAccount
if err := r.db.WithContext(ctx).Where("id = ? AND user_id = ? AND status = ?", id, userID, "active").
First(&account).Error; err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return ErrAccountNotFound
}
return err
}
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// 取消其他默认账号
if err := tx.Model(&model.UserPaymentAccount{}).
Where("user_id = ? AND id != ?", userID, id).
Update("is_default", false).Error; err != nil {
return err
}
// 设置当前为默认
return tx.Model(&account).Update("is_default", true).Error
})
}
func (r *Repository) CountByUser(ctx context.Context, userID uint64) (int64, error) {
var count int64
err := r.db.WithContext(ctx).Model(&model.UserPaymentAccount{}).
Where("user_id = ? AND status = ?", userID, "active").
Count(&count).Error
return count, err
}
func (r *Repository) ValidateRealname(ctx context.Context, userID uint64, accountName string) error {
var user model.User
db := r.db.WithContext(ctx)
if err := db.First(&user, userID).Error; err != nil {
return err
}
if user.RealnameStatus != "verified" {
return ErrRealnameRequired
}
// 获取实名信息
var realname model.UserRealname
if err := db.Where("user_id = ? AND status = ?", userID, "verified").
First(&realname).Error; err != nil {
return ErrRealnameRequired
}
// 验证姓名匹配 - 使用加密字段进行精确匹配
if realname.EncryptedName != "" {
// 有加密字段,解密后精确匹配
decryptedName, err := r.encryptor.Decrypt(realname.EncryptedName)
if err != nil {
// 解密失败,降级到前缀匹配
return r.validateByMaskedName(realname.MaskedName, accountName)
}
// 精确匹配(去除空格)
if strings.ReplaceAll(decryptedName, " ", "") != strings.ReplaceAll(accountName, " ", "") {
return ErrAccountNameMismatch
}
} else {
// 没有加密字段(旧数据),使用前缀匹配
return r.validateByMaskedName(realname.MaskedName, accountName)
}
return nil
}
// 使用脱敏姓名进行前缀匹配(兼容旧数据)
func (r *Repository) validateByMaskedName(maskedName, accountName string) error {
maskedName = strings.ReplaceAll(maskedName, " ", "")
inputName := strings.ReplaceAll(accountName, " ", "")
if strings.Contains(maskedName, "*") {
// 提取非星号部分(通常是姓氏)
prefix := strings.Split(maskedName, "*")[0]
if prefix != "" && !strings.HasPrefix(inputName, prefix) {
return ErrAccountNameMismatch
}
} else {
// 完整匹配
if maskedName != inputName {
return ErrAccountNameMismatch
}
}
return nil
}
func (r *Repository) toDTO(account model.UserPaymentAccount) (*PaymentAccountDTO, error) {
// 解密账号并脱敏
decrypted, err := r.encryptor.Decrypt(account.AccountNo)
if err != nil {
decrypted = account.AccountNo // 降级处理
}
maskedNo := maskAccountNo(decrypted, account.AccountType)
// 解析凭证URLs
var certURLs []string
if account.CertificateURLs != nil {
json.Unmarshal(account.CertificateURLs, &certURLs)
}
certURLs = privateCertificateURLs(certURLs)
return &PaymentAccountDTO{
ID: account.ID,
UserID: account.UserID,
AccountType: account.AccountType,
AccountName: account.AccountName,
AccountNo: maskedNo,
BankName: account.BankName,
BankBranch: account.BankBranch,
CertificateURLs: certURLs,
IsDefault: account.IsDefault,
Status: account.Status,
CreatedAt: account.CreatedAt,
UpdatedAt: account.UpdatedAt,
}, nil
}
// privateCertificateURLs 兼容历史公开收款凭证 URL,统一经私有对象接口读取。
func privateCertificateURLs(values []string) []string {
for index, value := range values {
parsed, err := url.Parse(value)
if err != nil || parsed.Path != "/api/public/files/object" {
continue
}
if !strings.HasPrefix(parsed.Query().Get("key"), "payment-cert/") {
continue
}
parsed.Path = "/api/files/object"
values[index] = parsed.String()
}
return values
}
// 账号脱敏
func maskAccountNo(accountNo, accountType string) string {
length := len(accountNo)
if length <= 4 {
return accountNo
}
switch accountType {
case "alipay", "wechat":
// 手机号或邮箱
if length == 11 {
return accountNo[:3] + "****" + accountNo[7:]
}
return accountNo[:2] + "****" + accountNo[length-2:]
case "bank":
// 银行卡号
if length > 8 {
return accountNo[:4] + "****" + accountNo[length-4:]
}
return accountNo[:2] + "****" + accountNo[length-2:]
}
return accountNo
}
// 获取解密后的账号(仅供内部使用,如提现申请时)
func (r *Repository) GetDecryptedAccountNo(ctx context.Context, userID, id uint64) (string, error) {
var account model.UserPaymentAccount
if err := r.db.WithContext(ctx).Where("id = ? AND user_id = ?", id, userID).First(&account).Error; err != nil {
return "", err
}
return r.encryptor.Decrypt(account.AccountNo)
}
@@ -0,0 +1,48 @@
package paymentaccount
import (
"context"
"errors"
"testing"
"hfb_sys/backend/internal/database"
"hfb_sys/backend/internal/model"
)
func TestPrivateCertificateURLsConvertsLegacyPublicURL(t *testing.T) {
values := privateCertificateURLs([]string{
"/api/public/files/object?key=payment-cert%2F2026%2Fqr.jpg",
"/api/public/files/object?key=avatar%2Fuser.jpg",
})
if values[0] != "/api/files/object?key=payment-cert%2F2026%2Fqr.jpg" {
t.Fatalf("payment certificate URL = %q", values[0])
}
if values[1] != "/api/public/files/object?key=avatar%2Fuser.jpg" {
t.Fatalf("non-certificate URL changed = %q", values[1])
}
}
func TestValidateCertificateURLsRequiresUploaderOwnership(t *testing.T) {
db := database.NewTestDB()
if err := database.AutoMigrateIfMissing(db, &model.FileUploadOwner{}); err != nil {
t.Fatalf("migrate upload owners error = %v", err)
}
if err := db.Create(&model.FileUploadOwner{UserID: 1, ObjectKey: "payment-cert/owned.jpg"}).Error; err != nil {
t.Fatalf("create upload owner error = %v", err)
}
repo := NewRepository(db, nil)
ownedURL := "/api/files/object?key=payment-cert%2Fowned.jpg"
if err := repo.validateCertificateURLs(context.Background(), 1, []string{ownedURL}, nil); err != nil {
t.Fatalf("owned certificate rejected: %v", err)
}
if err := repo.validateCertificateURLs(context.Background(), 2, []string{ownedURL}, nil); !errors.Is(err, ErrInvalidCertificateURL) {
t.Fatalf("other user's certificate validation error = %v", err)
}
if err := repo.validateCertificateURLs(context.Background(), 1, []string{"/api/files/object?key=listing%2Fowned.jpg"}, nil); !errors.Is(err, ErrInvalidCertificateURL) {
t.Fatalf("non-certificate file validation error = %v", err)
}
legacyURL := "/api/public/files/object?key=payment-cert%2Flegacy.jpg"
if err := repo.validateCertificateURLs(context.Background(), 1, []string{legacyURL}, []string{legacyURL}); err != nil {
t.Fatalf("existing legacy certificate rejected: %v", err)
}
}
@@ -0,0 +1,84 @@
package paymentaccount
import (
"context"
"errors"
)
var (
ErrDependencyUnavailable = errors.New("dependency unavailable")
ErrAccountNotFound = errors.New("payment account not found")
ErrAccountNameMismatch = errors.New("account name must match realname")
ErrRealnameRequired = errors.New("realname verification required")
ErrAccountLimit = errors.New("maximum payment accounts reached")
ErrCannotDeleteDefault = errors.New("cannot delete default account")
ErrInvalidCertificateURL = errors.New("invalid certificate url")
)
type Service struct {
repo *Repository
}
func NewService(repo *Repository) *Service {
return &Service{repo: repo}
}
func (s *Service) List(ctx context.Context, userID uint64, page, pageSize int) (*PaginatedResult, error) {
if s.repo == nil {
return nil, ErrDependencyUnavailable
}
if page < 1 {
page = 1
}
if pageSize < 1 || pageSize > 100 {
pageSize = 20
}
return s.repo.List(ctx, userID, page, pageSize)
}
func (s *Service) FindByID(ctx context.Context, userID, id uint64) (*PaymentAccountDTO, error) {
if s.repo == nil {
return nil, ErrDependencyUnavailable
}
return s.repo.FindByID(ctx, userID, id)
}
func (s *Service) Create(ctx context.Context, userID uint64, req CreatePaymentAccountRequest) (*PaymentAccountDTO, error) {
if s.repo == nil {
return nil, ErrDependencyUnavailable
}
// 验证实名状态
if err := s.repo.ValidateRealname(ctx, userID, req.AccountName); err != nil {
return nil, err
}
// 检查账号数量限制(最多5个)
count, err := s.repo.CountByUser(ctx, userID)
if err != nil {
return nil, err
}
if count >= 5 {
return nil, ErrAccountLimit
}
return s.repo.Create(ctx, userID, req)
}
func (s *Service) Update(ctx context.Context, userID, id uint64, req UpdatePaymentAccountRequest) (*PaymentAccountDTO, error) {
if s.repo == nil {
return nil, ErrDependencyUnavailable
}
return s.repo.Update(ctx, userID, id, req)
}
func (s *Service) Delete(ctx context.Context, userID, id uint64) error {
if s.repo == nil {
return ErrDependencyUnavailable
}
return s.repo.Delete(ctx, userID, id)
}
func (s *Service) SetDefault(ctx context.Context, userID, id uint64) error {
if s.repo == nil {
return ErrDependencyUnavailable
}
return s.repo.SetDefault(ctx, userID, id)
}