feat: implement cross-batch Alipay refund reconciliation

When a refund row in an uploaded Alipay bill has no matching expense row in the same batch (because the original purchase was uploaded in a prior batch), the refund is now reconciled against the stored record in bills_cleaned rather than being silently discarded. Changes: - analyzer/cleaners/base.py: add unresolved_refunds list to BaseCleaner - analyzer/cleaners/alipay.py: _aggregate_refunds stores full refund metadata (dict); _process_expenses tracks matched keys and populates self.unresolved_refunds for unmatched refunds - analyzer/server.py: thread unresolved_refunds through do_clean, CleanResponse, and both /clean endpoints - server/adapter/adapter.go: add UnresolvedRefund type and field to CleanResult - server/adapter/http/cleaner.go: deserialize unresolved_refunds from Python response and populate CleanResult - server/repository/repository.go: add ReconcileRefund to BillRepository interface - server/repository/mongo/repository.go: implement ReconcileRefund — full refund soft-deletes the bill, partial refund reduces amount and appends remark with original amount and refund order number - server/handler/upload.go: capture clean result and call ReconcileRefund for each unresolved refund after saving cleaned bills - server/model/response.go: add ReconciledRefundCount to UploadData Also: add CLAUDE.md (@AGENTS.md), update AGENTS.md, fix DailyTrendChart missing-date gap by filling zero-expense dates in daily map. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-16 19:29:47 +08:00
parent bb717faac3
commit e2e1beb6f7
12 changed files with 342 additions and 133 deletions
--- a/server/adapter/adapter.go
+++ b/server/adapter/adapter.go
@@ -13,8 +13,20 @@ type CleanOptions struct {

 // CleanResult 清洗结果
 type CleanResult struct {
-	BillType string // 检测到的账单类型: alipay/wechat/jd
-	Output   string // 脚本输出信息
+	BillType          string             // 检测到的账单类型: alipay/wechat/jd
+	Output            string             // 脚本输出信息
+	UnresolvedRefunds []UnresolvedRefund // 本次清洗未在同批次内匹配到对应支出的退款
+}
+
+// UnresolvedRefund 本次清洗未在同批次内匹配到对应支出的退款
+type UnresolvedRefund struct {
+	OrderNo         string  // 原订单号（去除退款后缀）
+	MerchantOrderNo string  // 商家订单号（备用匹配字段）
+	RefundOrderNo   string  // 退款行自身的完整订单号（用于备注追溯）
+	Amount          float64 // 退款金额
+	Time            string  // 退款时间
+	Merchant        string  // 交易对方
+	Description     string  // 商品说明
 }

 // ConvertResult 格式转换结果
--- a/server/adapter/http/cleaner.go
+++ b/server/adapter/http/cleaner.go
@@ -29,10 +29,22 @@ type CleanRequest struct {

 // CleanResponse HTTP 清洗响应
 type CleanResponse struct {
-	Success    bool   `json:"success"`
-	BillType   string `json:"bill_type"`
-	Message    string `json:"message"`
-	OutputPath string `json:"output_path,omitempty"`
+	Success           bool               `json:"success"`
+	BillType          string             `json:"bill_type"`
+	Message           string             `json:"message"`
+	OutputPath        string             `json:"output_path,omitempty"`
+	UnresolvedRefunds []UnresolvedRefund `json:"unresolved_refunds,omitempty"`
+}
+
+// UnresolvedRefund 本次清洗未在同批次内匹配到对应支出的退款（与 Python 端 dict 字段对应）
+type UnresolvedRefund struct {
+	OrderNo         string  `json:"order_no"`
+	MerchantOrderNo string  `json:"merchant_order_no"`
+	RefundOrderNo   string  `json:"refund_order_no"`
+	Amount          float64 `json:"amount"`
+	Time            string  `json:"time"`
+	Merchant        string  `json:"merchant"`
+	Description     string  `json:"description"`
 }

 // ErrorResponse 错误响应
@@ -149,9 +161,23 @@ func (c *Cleaner) Clean(inputPath, outputPath string, opts *adapter.CleanOptions
 		}
 	}

+	unresolvedRefunds := make([]adapter.UnresolvedRefund, 0, len(cleanResp.UnresolvedRefunds))
+	for _, ur := range cleanResp.UnresolvedRefunds {
+		unresolvedRefunds = append(unresolvedRefunds, adapter.UnresolvedRefund{
+			OrderNo:         ur.OrderNo,
+			MerchantOrderNo: ur.MerchantOrderNo,
+			RefundOrderNo:   ur.RefundOrderNo,
+			Amount:          ur.Amount,
+			Time:            ur.Time,
+			Merchant:        ur.Merchant,
+			Description:     ur.Description,
+		})
+	}
+
 	return &adapter.CleanResult{
-		BillType: cleanResp.BillType,
-		Output:   cleanResp.Message,
+		BillType:          cleanResp.BillType,
+		Output:            cleanResp.Message,
+		UnresolvedRefunds: unresolvedRefunds,
 	}, nil
 }

--- a/server/handler/upload.go
+++ b/server/handler/upload.go
@@ -223,7 +223,7 @@ func Upload(c *gin.Context) {
 		End:    req.End,
 		Format: req.Format,
 	}
-	_, cleanErr := service.RunCleanScript(processFilePath, outputPath, cleanOpts)
+	cleanResult, cleanErr := service.RunCleanScript(processFilePath, outputPath, cleanOpts)
 	if cleanErr != nil {
 		service.CleanupExtractedFiles(extractedFiles)
 		c.JSON(http.StatusInternalServerError, model.UploadResponse{
@@ -255,22 +255,37 @@ func Upload(c *gin.Context) {
 	}
 	service.CleanupExtractedFiles(extractedFiles)

+	repo := repository.GetRepository()
+
 	// 13. 如果是京东账单，软删除其他来源中包含"京东-订单编号"的记录
 	var jdRelatedDeleted int64
-	if billType == "jd" {
-		repo := repository.GetRepository()
-		if repo != nil {
-			deleted, err := repo.SoftDeleteJDRelatedBills()
-			if err != nil {
-				fmt.Printf("⚠️  软删除京东关联记录失败: %v\n", err)
-			} else if deleted > 0 {
-				jdRelatedDeleted = deleted
-				fmt.Printf("🗑️  已软删除 %d 条其他来源中的京东关联记录\n", deleted)
+	if billType == "jd" && repo != nil {
+		deleted, err := repo.SoftDeleteJDRelatedBills()
+		if err != nil {
+			fmt.Printf("⚠️  软删除京东关联记录失败: %v\n", err)
+		} else if deleted > 0 {
+			jdRelatedDeleted = deleted
+			fmt.Printf("🗑️  已软删除 %d 条其他来源中的京东关联记录\n", deleted)
+		}
+	}
+
+	// 14. 核销跨批次退款（本次清洗中未在同批次内匹配到对应支出的退款）
+	var reconciledCount int
+	if repo != nil && cleanResult != nil {
+		for _, ur := range cleanResult.UnresolvedRefunds {
+			matched, rErr := repo.ReconcileRefund(billType, ur.OrderNo, ur.MerchantOrderNo, ur.Amount, ur.Time, ur.Merchant, ur.Description, ur.RefundOrderNo)
+			if rErr != nil {
+				fmt.Printf("⚠️  退款核销失败: %v\n", rErr)
+				continue
+			}
+			if matched {
+				reconciledCount++
+				fmt.Printf("💰 已核销退款: 订单%s, 金额%.2f元\n", ur.OrderNo, ur.Amount)
 			}
 		}
 	}

-	// 14. 返回成功响应
+	// 15. 返回成功响应
 	message := fmt.Sprintf("处理成功，新增 %d 条记录", cleanedCount)
 	if dedupResult.DuplicateCount > 0 {
 		message = fmt.Sprintf("处理成功，新增 %d 条，跳过 %d 条重复记录", cleanedCount, dedupResult.DuplicateCount)
@@ -278,18 +293,22 @@ func Upload(c *gin.Context) {
 	if jdRelatedDeleted > 0 {
 		message = fmt.Sprintf("%s，标记删除 %d 条重复的京东订单", message, jdRelatedDeleted)
 	}
+	if reconciledCount > 0 {
+		message = fmt.Sprintf("%s，核销退款 %d 条", message, reconciledCount)
+	}

 	c.JSON(http.StatusOK, model.UploadResponse{
 		Result:  true,
 		Message: message,
 		Data: &model.UploadData{
-			BillType:         billType,
-			FileURL:          fmt.Sprintf("/download/%s", outputFileName),
-			FileName:         outputFileName,
-			RawCount:         rawCount,
-			CleanedCount:     cleanedCount,
-			DuplicateCount:   dedupResult.DuplicateCount,
-			JDRelatedDeleted: jdRelatedDeleted,
+			BillType:              billType,
+			FileURL:               fmt.Sprintf("/download/%s", outputFileName),
+			FileName:              outputFileName,
+			RawCount:              rawCount,
+			CleanedCount:          cleanedCount,
+			DuplicateCount:        dedupResult.DuplicateCount,
+			JDRelatedDeleted:      jdRelatedDeleted,
+			ReconciledRefundCount: reconciledCount,
 		},
 	})
 }
--- a/server/model/response.go
+++ b/server/model/response.go
@@ -2,13 +2,14 @@ package model

 // UploadData 上传响应数据
 type UploadData struct {
-	BillType         string `json:"bill_type,omitempty"`          // alipay/wechat/jd
-	FileURL          string `json:"file_url,omitempty"`           // 下载链接
-	FileName         string `json:"file_name,omitempty"`          // 文件名
-	RawCount         int    `json:"raw_count,omitempty"`          // 存储到原始数据集合的记录数
-	CleanedCount     int    `json:"cleaned_count,omitempty"`      // 存储到清洗后数据集合的记录数
-	DuplicateCount   int    `json:"duplicate_count,omitempty"`    // 重复跳过的记录数
-	JDRelatedDeleted int64  `json:"jd_related_deleted,omitempty"` // 软删除的京东关联记录数（其他来源中描述包含京东订单号的记录）
+	BillType              string `json:"bill_type,omitempty"`               // alipay/wechat/jd
+	FileURL               string `json:"file_url,omitempty"`                // 下载链接
+	FileName              string `json:"file_name,omitempty"`               // 文件名
+	RawCount              int    `json:"raw_count,omitempty"`               // 存储到原始数据集合的记录数
+	CleanedCount          int    `json:"cleaned_count,omitempty"`           // 存储到清洗后数据集合的记录数
+	DuplicateCount        int    `json:"duplicate_count,omitempty"`         // 重复跳过的记录数
+	JDRelatedDeleted      int64  `json:"jd_related_deleted,omitempty"`      // 软删除的京东关联记录数（其他来源中描述包含京东订单号的记录）
+	ReconciledRefundCount int    `json:"reconciled_refund_count,omitempty"` // 跨批次核销的退款记录数
 }

 // UploadResponse 上传响应
--- a/server/repository/mongo/repository.go
+++ b/server/repository/mongo/repository.go
@@ -4,6 +4,7 @@ package mongo
 import (
 	"context"
 	"fmt"
+	"math"
 	"time"

 	"go.mongodb.org/mongo-driver/bson"
@@ -16,6 +17,9 @@ import (
 	"billai-server/repository"
 )

+// refundEpsilon 退款核销后剩余金额的容差阈值，小于该值视为已全额退款
+const refundEpsilon = 0.005
+
 // Repository MongoDB 账单存储实现
 type Repository struct {
 	client            *mongo.Client
@@ -498,6 +502,74 @@ func (r *Repository) SoftDeleteJDRelatedBills() (int64, error) {
 	return result.ModifiedCount, nil
 }

+// ReconcileRefund 将跨批次退款核销到已存储的清洗后账单
+// 按 bill_type + (transaction_id == orderNo 或 merchant_order_no == merchantOrderNo) 查找未删除记录
+// 全额退款（剩余金额 <= refundEpsilon）则软删除；部分退款则扣减 amount 并追加备注
+func (r *Repository) ReconcileRefund(billType, orderNo, merchantOrderNo string, refundAmount float64, refundTime, merchant, description, refundOrderNo string) (bool, error) {
+	if r.cleanedCollection == nil {
+		return false, fmt.Errorf("cleaned collection not initialized")
+	}
+
+	if orderNo == "" && merchantOrderNo == "" {
+		return false, nil
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	var or []bson.M
+	if orderNo != "" {
+		or = append(or, bson.M{"transaction_id": orderNo})
+	}
+	if merchantOrderNo != "" {
+		or = append(or, bson.M{"merchant_order_no": merchantOrderNo})
+	}
+	filter := bson.M{
+		"bill_type":  billType,
+		"is_deleted": bson.M{"$ne": true},
+		"$or":        or,
+	}
+
+	var bill model.CleanedBill
+	if err := r.cleanedCollection.FindOne(ctx, filter).Decode(&bill); err != nil {
+		if err == mongo.ErrNoDocuments {
+			return false, nil
+		}
+		return false, fmt.Errorf("查询待核销账单失败: %w", err)
+	}
+
+	remaining := bill.Amount - refundAmount
+	now := time.Now()
+
+	if remaining <= refundEpsilon {
+		update := bson.M{"$set": bson.M{
+			"is_deleted": true,
+			"updated_at": now,
+			"remark":     fmt.Sprintf("[退款核销]全额退款%.2f元(退款单号%s);%s", refundAmount, refundOrderNo, bill.Remark),
+		}}
+		_, err := r.cleanedCollection.UpdateOne(ctx, bson.M{"_id": bill.ID}, update)
+		if err != nil {
+			return false, fmt.Errorf("核销退款失败: %w", err)
+		}
+		return true, nil
+	}
+
+	remaining = math.Round(remaining*100) / 100
+	update := bson.M{"$set": bson.M{
+		"amount":     remaining,
+		"updated_at": now,
+		"remark":     fmt.Sprintf("原金额%.2f元,退款%.2f元(退款单号%s);%s", bill.Amount, refundAmount, refundOrderNo, bill.Remark),
+	}}
+	_, err := r.cleanedCollection.UpdateOne(ctx, bson.M{"_id": bill.ID}, update)
+	if err != nil {
+		return false, fmt.Errorf("核销退款失败: %w", err)
+	}
+	return true, nil
+}
+
+// 建议: 为提升 ReconcileRefund 查询性能，可为 bills_cleaned 添加索引
+// {transaction_id:1, bill_type:1} 和 {merchant_order_no:1, bill_type:1}（与现有"无索引"问题一并处理）
+
 // GetClient 获取 MongoDB 客户端（用于兼容旧代码）
 func (r *Repository) GetClient() *mongo.Client {
 	return r.client
--- a/server/repository/repository.go
+++ b/server/repository/repository.go
@@ -56,4 +56,10 @@ type BillRepository interface {
 	// 用于避免京东账单与其他来源（微信、支付宝）账单重复计算
 	// 返回: 删除数量、错误
 	SoftDeleteJDRelatedBills() (int64, error)
+
+	// ReconcileRefund 将跨批次退款核销到已存储的清洗后账单
+	// 按 bill_type + (transaction_id == orderNo 或 merchant_order_no == merchantOrderNo) 查找未删除记录
+	// 全额退款（剩余金额 <= 0.005）则软删除；部分退款则扣减 amount 并追加备注
+	// 返回: 是否找到并核销了匹配记录、错误（未找到匹配记录不算错误，返回 matched=false）
+	ReconcileRefund(billType, orderNo, merchantOrderNo string, refundAmount float64, refundTime, merchant, description, refundOrderNo string) (matched bool, err error)
 }