补充退款列表应当让本店铺的人看见

.env.prod

@@ -240,6 +240,7 @@ export JUNHONG_MIDDLEWARE_CORS_ALLOW_CREDENTIALS=true
 # ----------------------------------------------------------------------------
 export JUNHONG_WORKER_ROLE='all'
 export JUNHONG_WORKER_INSTANCE_NAME='worker-all-1'
+export JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED='false'
 export JUNHONG_WECOM_BASE_URL='https://qyapi.weixin.qq.com'
 export JUNHONG_WECOM_TIMEOUT='10s'
 export JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED='true'

docs/deployment/production-runbook.md

@@ -45,7 +45,7 @@ GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/api ./cmd/api
 GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/worker ./cmd/worker
 ```
 
-本次迭代更新只上传 API 与 Worker 二进制；配置变化由维护者直接修改各运行目录的 `.env.prod`。生产迁移文件必须随本次发布上传到 API 目录下的 `migrations/`，供 `migrate` 记录和执行。生产服务器当前尚未安装 `migrate`；安装路径和版本待首次迁移前确认。
+本次迭代更新上传 API 与 Worker 二进制；配置变化由维护者直接修改各运行目录的 `.env.prod`。生产迁移文件必须随本次发布上传到 API 目录下的 `migrations/`，并同步上传当前分支的 `scripts/migrate.sh`，供 `migrate` 记录和执行。生产服务器当前尚未安装 `migrate`；安装路径和版本待首次迁移前确认。
 
 ## 配置规则
 
@@ -60,7 +60,7 @@ GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/worker ./cmd/worker
 
 已确认顺序：备份二进制和数据库 → 上传二进制及迁移文件 → 停止 systemd 服务 → 执行迁移 → 启动服务。
 
-生产当前迁移版本已于 2026-08-13 由维护者在 API 目录验证为 `140`（非 dirty）。历史迁移已归档，生产从 `140` 向后执行根目录 `migrations/` 的 `141+` 迁移；七月分支最终目标为 `206`。根目录不存在 `173` 号迁移，这是正常编号空档。执行前先以显式 `DB_*` 参数运行：
+生产当前迁移版本已于 2026-08-13 由维护者在 API 目录验证为 `140`（非 dirty）。历史迁移已归档，生产从 `140` 向后执行根目录 `migrations/` 的 `141+` 迁移；七月分支最终目标为 `209`。根目录不存在 `173` 号迁移，这是正常编号空档。执行前先以显式 `DB_*` 参数运行：
 
 ```bash
 DB_HOST=<生产主机> DB_PORT=<端口> DB_USER=<用户> \

internal/infrastructure/commissiondelivery/event.go

@@ -117,7 +117,7 @@ func Recover(ctx context.Context, db *gorm.DB, repository *outbox.Repository, li
 		logger.Warn("扫描待计算订单失败", zap.Error(err))
 	} else {
 		for _, order := range orders {
-			recoverOne(ctx, db, repository, EventCommissionCalculate, order.ID, order.ID, &orderStats, logger)
+			recoverOne(ctx, db, repository, EventCommissionCalculate, order.ID, order.ID, &orderStats, logger, false)
 		}
 	}
 	var refunds []model.RefundRequest
@@ -126,10 +126,10 @@ func Recover(ctx context.Context, db *gorm.DB, repository *outbox.Repository, li
 	} else {
 		for _, refund := range refunds {
 			if !refund.CommissionDeducted {
-				recoverOne(ctx, db, repository, EventRefundCommissionDeduct, refund.ID, refund.OrderID, &refundStats, logger)
+				recoverOne(ctx, db, repository, EventRefundCommissionDeduct, refund.ID, refund.OrderID, &refundStats, logger, true)
 			}
 			if !refund.AssetReset {
-				recoverOne(ctx, db, repository, EventRefundAssetProcess, refund.ID, refund.OrderID, &refundStats, logger)
+				recoverOne(ctx, db, repository, EventRefundAssetProcess, refund.ID, refund.OrderID, &refundStats, logger, true)
 			}
 		}
 	}
@@ -138,16 +138,21 @@ func Recover(ctx context.Context, db *gorm.DB, repository *outbox.Repository, li
 		zap.Int("退款已补发", refundStats.Resent), zap.Int("退款无需补发", refundStats.Unchanged), zap.Int("退款失败", refundStats.Failed))
 }
 
-func recoverOne(ctx context.Context, db *gorm.DB, repository *outbox.Repository, eventType string, aggregateID, orderID uint, stats *RecoveryStats, logger *zap.Logger) {
+func recoverOne(ctx context.Context, db *gorm.DB, repository *outbox.Repository, eventType string, aggregateID, orderID uint, stats *RecoveryStats, logger *zap.Logger, retryDelivered bool) {
 	eventID := outboxid.Stable(eventType+":", strconv.FormatUint(uint64(aggregateID), 10))
 	var event model.OutboxEvent
 	err := db.WithContext(ctx).Where("event_id = ?", eventID).First(&event).Error
 	if err == nil {
-		if event.Status != constants.OutboxStatusFailed {
+		if event.Status == constants.OutboxStatusPending || event.Status == constants.OutboxStatusDelivering {
 			stats.Unchanged++
 			return
 		}
-		result := db.WithContext(ctx).Model(&model.OutboxEvent{}).Where("id = ? AND status = ?", event.ID, constants.OutboxStatusFailed).Updates(map[string]any{
+		// 已投递只代表入队成功，不代表业务处理成功；业务幂等的退款后处理允许重投。
+		if event.Status == constants.OutboxStatusDelivered && !retryDelivered {
+			stats.Unchanged++
+			return
+		}
+		result := db.WithContext(ctx).Model(&model.OutboxEvent{}).Where("id = ? AND status = ?", event.ID, event.Status).Updates(map[string]any{
 			"status": constants.OutboxStatusPending, "retry_count": 0, "next_attempt_at": time.Now().UTC(),
 			"last_error_code": "", "last_error_summary": "", "updated_at": time.Now().UTC(),
 		})

internal/query/retention/retention.go

@@ -3,6 +3,7 @@ package retention
 
 import (
 	"context"
+	"database/sql"
 	"time"
 
 	"gorm.io/gorm"
@@ -55,17 +56,17 @@ func Load(ctx context.Context, db *gorm.DB, sources ...Source) (Info, error) {
 }
 
 func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *time.Location) (time.Time, bool, error) {
-	var cleanedEnd *time.Time
+	var cleanedEnd sql.NullTime
 	if err := db.WithContext(ctx).Model(&model.LogArchiveRun{}).
 		Where("source = ? AND cleaned_at IS NOT NULL", source).
 		Select("MAX(range_end)").Scan(&cleanedEnd).Error; err != nil {
 		return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计留存清理边界失败")
 	}
-	if cleanedEnd != nil {
+	if cleanedEnd.Valid {
-		return cleanedEnd.In(location), true, nil
+		return cleanedEnd.Time.In(location), true, nil
 	}
 
-	var earliest *time.Time
+	var earliest sql.NullTime
 	table, column := "tb_audit_event", "occurred_at"
 	if source == SourceIntegration {
 		table, column = "tb_integration_log", "created_at"
@@ -73,8 +74,8 @@ func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *t
 	if err := db.WithContext(ctx).Table(table).Select("MIN(" + column + ")").Scan(&earliest).Error; err != nil {
 		return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计在线数据边界失败")
 	}
-	if earliest != nil {
+	if earliest.Valid {
-		return earliest.In(location), false, nil
+		return earliest.Time.In(location), false, nil
 	}
 	now := time.Now().In(location)
 	return time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, location), false, nil

internal/service/refund/service.go

@@ -268,7 +268,7 @@ func (s *Service) Approve(ctx context.Context, id uint, req *dto.ApproveRefundRe
 		return err
 	}
 
-	refund, err := s.refundStore.GetByID(ctx, id)
+	refund, err := s.refundStore.GetByIDForOperation(ctx, id)
 	if err != nil {
 		return errors.New(errors.CodeNotFound, "退款申请不存在")
 	}
@@ -690,7 +690,7 @@ func (s *Service) Resubmit(ctx context.Context, id uint, req *dto.ResubmitRefund
 		return errors.New(errors.CodeUnauthorized, "未授权访问")
 	}
 
-	refund, err := s.refundStore.GetByID(ctx, id)
+	refund, err := s.refundStore.GetByIDForOperation(ctx, id)
 	if err != nil {
 		return errors.New(errors.CodeInvalidStatus, "仅已退回状态可重新提交")
 	}
@@ -835,8 +835,8 @@ func (s *Service) deductAllCommission(ctx context.Context, refundID uint) {
 	}
 }
 
-// deductSingleCommission 扣减单条佣金记录对应的代理钱包余额
+// deductSingleCommission 回扣单条佣金记录：先拒绝该店铺待审核提现释放冻结余额，
-// 使用乐观锁扣减（允许余额为负数），并创建交易流水
+// 再扣减佣金钱包（允许余额为负），最后失效佣金记录并创建流水。
 func (s *Service) deductSingleCommission(ctx context.Context, refund *model.RefundRequest, commission *model.CommissionRecord) error {
 	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		var current model.CommissionRecord
@@ -869,6 +869,9 @@ func (s *Service) deductSingleCommission(ctx context.Context, refund *model.Refu
 			First(&wallet).Error; err != nil {
 			return errors.Wrap(errors.CodeDatabaseError, err, "锁定退款佣金钱包失败")
 		}
+		if err := s.rejectPendingWithdrawals(ctx, tx, &wallet, current.ShopID, refund); err != nil {
+			return err
+		}
 		result := tx.WithContext(ctx).Model(&model.AgentWallet{}).
 			Where("id = ? AND version = ?", wallet.ID, wallet.Version).
 			Updates(map[string]any{"balance": gorm.Expr("balance - ?", current.Amount), "version": gorm.Expr("version + 1")})
@@ -903,6 +906,97 @@ func (s *Service) deductSingleCommission(ctx context.Context, refund *model.Refu
 	})
 }
 
+// rejectPendingWithdrawals 回扣佣金前拒绝该店铺所有待审核提现。
+// 提现冻结的是佣金余额，退款回扣优先级更高；先解冻并拒绝，避免已回扣佣金仍被提现。
+func (s *Service) rejectPendingWithdrawals(ctx context.Context, tx *gorm.DB, wallet *model.AgentWallet, shopID uint, refund *model.RefundRequest) error {
+	var withdrawals []model.CommissionWithdrawalRequest
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("shop_id = ? AND status = ?", shopID, constants.WithdrawalStatusPending).
+		Find(&withdrawals).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询待审核佣金提现失败")
+	}
+	if len(withdrawals) == 0 {
+		return nil
+	}
+	var shop model.Shop
+	if err := tx.WithContext(ctx).First(&shop, shopID).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "查询提现店铺失败")
+	}
+	for i := range withdrawals {
+		w := &withdrawals[i]
+		before := withdrawalRejectState(w)
+		if err := s.agentWalletStore.UnfreezeBalanceWithTx(ctx, tx, wallet.ID, w.Amount); err != nil {
+			return errors.Wrap(errors.CodeInternalError, err, "解冻提现冻结余额失败")
+		}
+		refType := constants.ReferenceTypeWithdrawal
+		remark := "退款佣金回扣，自动拒绝提现"
+		transaction := &model.AgentWalletTransaction{
+			AgentWalletID: wallet.ID, ShopID: shopID, UserID: refund.Creator,
+			TransactionType: constants.AgentTransactionTypeRefund, Amount: w.Amount,
+			BalanceBefore: wallet.Balance, BalanceAfter: wallet.Balance,
+			Status: constants.TransactionStatusSuccess, ReferenceType: &refType, ReferenceID: &w.ID,
+			Remark: &remark, Creator: refund.Creator, ShopIDTag: shopID,
+		}
+		if err := tx.WithContext(ctx).Create(transaction).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "创建自动拒绝提现流水失败")
+		}
+		now := time.Now()
+		result := tx.WithContext(ctx).Model(&model.CommissionWithdrawalRequest{}).
+			Where("id = ? AND status = ?", w.ID, constants.WithdrawalStatusPending).
+			Updates(map[string]any{
+				"status":        constants.WithdrawalStatusRejected,
+				"processed_at":  now,
+				"reject_reason": remark,
+				"updated_at":    now,
+			})
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "拒绝待审核提现失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "提现申请状态已变化")
+		}
+		w.Status = constants.WithdrawalStatusRejected
+		w.ProcessedAt = &now
+		w.RejectReason = remark
+		if err := s.appendWithdrawalRejectAudit(ctx, tx, w, wallet, transaction, &shop, before); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func withdrawalRejectState(w *model.CommissionWithdrawalRequest) map[string]any {
+	return map[string]any{
+		"status": w.Status, "amount": w.Amount, "fee": w.Fee, "actual_amount": w.ActualAmount,
+		"withdrawal_method": w.WithdrawalMethod, "processed_at": w.ProcessedAt, "reject_reason": w.RejectReason,
+	}
+}
+
+func (s *Service) appendWithdrawalRejectAudit(ctx context.Context, tx *gorm.DB, withdrawal *model.CommissionWithdrawalRequest, wallet *model.AgentWallet, transaction *model.AgentWalletTransaction, shop *model.Shop, before map[string]any) error {
+	if s.auditWriter == nil {
+		return errors.New(errors.CodeInvalidStatus, "退款统一审计接缝未配置")
+	}
+	primary := audit.CommissionWithdrawalResource(withdrawal, constants.AuditResourceRelationPrimary, constants.AuditResourceRoleWithdrawalTarget,
+		before, withdrawalRejectState(withdrawal))
+	primary.SubjectVisibility = constants.AuditSubjectResult
+	primary.SubjectSummary = "退款佣金回扣自动拒绝提现"
+	walletResource := audit.AgentWalletResource(wallet, constants.AuditResourceRelationAffected, constants.AuditResourceRoleWithdrawalWallet,
+		map[string]any{"balance": wallet.Balance, "frozen_balance": wallet.FrozenBalance},
+		map[string]any{"balance": wallet.Balance, "frozen_balance": wallet.FrozenBalance - withdrawal.Amount})
+	walletResource.SubjectVisibility = constants.AuditSubjectInternalOnly
+	transactionResource := audit.AgentWalletTransactionResource(transaction, constants.AuditResourceRelationAffected, constants.AuditResourceRoleWithdrawalTransaction)
+	transactionResource.SubjectVisibility = constants.AuditSubjectInternalOnly
+	shopResource := audit.ShopResource(shop, constants.AuditResourceRelationReference, constants.AuditResourceRoleWithdrawalShop)
+	shopResource.SubjectVisibility = constants.AuditSubjectInternalOnly
+	return s.auditWriter.Append(ctx, tx, audit.AppendInput{
+		EventID:    "commission-withdrawal:" + strconv.FormatUint(uint64(withdrawal.ID), 10) + ":refund-rejected",
+		ActionCode: constants.AuditActionCommissionWithdrawalRejected, Summary: "退款佣金回扣自动拒绝提现",
+		ScopeType: constants.AuditScopePlatform, Result: constants.AuditResultSuccess,
+		CorrelationID: withdrawal.WithdrawalNo, Metadata: map[string]any{"amount": withdrawal.Amount, "status": withdrawal.Status},
+		Resources: []audit.ResourceInput{primary, walletResource, transactionResource, shopResource},
+	})
+}
+
 // handleRefundAssetProcessing 幂等处理退款后的资产状态。
 // 包括退款套餐精准失效、尝试接续待生效主套餐和必要时停机；全部完成后才设置完成标记。
 func (s *Service) handleRefundAssetProcessing(ctx context.Context, refundID uint) {

internal/store/postgres/refund_store.go

@@ -33,7 +33,7 @@ func (s *RefundStore) Create(ctx context.Context, req *model.RefundRequest) erro
 	return s.db.WithContext(ctx).Create(req).Error
 }
 
-// GetByID 根据 ID 查询退款申请（含数据权限过滤）
+// GetByID 根据 ID 查询退款申请详情（含读取数据权限过滤）。
 func (s *RefundStore) GetByID(ctx context.Context, id uint) (*model.RefundRequest, error) {
 	var req model.RefundRequest
 	query := s.db.WithContext(ctx).
@@ -41,7 +41,22 @@ func (s *RefundStore) GetByID(ctx context.Context, id uint) (*model.RefundReques
 		Select("tb_refund_request.*, tb_shop.shop_name AS shop_name").
 		Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL").
 		Where("tb_refund_request.id = ?", id)
-	query = applyRefundScope(ctx, query)
+	query = applyRefundReadScope(ctx, query)
+	if err := query.First(&req).Error; err != nil {
+		return nil, err
+	}
+	return &req, nil
+}
+
+// GetByIDForOperation 根据 ID 查询退款申请（含写操作数据权限过滤）。
+func (s *RefundStore) GetByIDForOperation(ctx context.Context, id uint) (*model.RefundRequest, error) {
+	var req model.RefundRequest
+	query := s.db.WithContext(ctx).
+		Model(&model.RefundRequest{}).
+		Select("tb_refund_request.*, tb_shop.shop_name AS shop_name").
+		Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL").
+		Where("tb_refund_request.id = ?", id)
+	query = applyRefundOperationScope(ctx, query)
 	if err := query.First(&req).Error; err != nil {
 		return nil, err
 	}
@@ -70,7 +85,7 @@ func (s *RefundStore) List(ctx context.Context, opts *store.QueryOptions, filter
 		Model(&model.RefundRequest{}).
 		Select("tb_refund_request.*, tb_shop.shop_name AS shop_name").
 		Joins("LEFT JOIN tb_shop ON tb_shop.id = tb_refund_request.shop_id AND tb_shop.deleted_at IS NULL")
-	query = applyRefundScope(ctx, query)
+	query = applyRefundReadScope(ctx, query)
 
 	if filters != nil {
 		if filters.Status != nil {
@@ -113,9 +128,25 @@ func (s *RefundStore) List(ctx context.Context, opts *store.QueryOptions, filter
 	return requests, total, nil
 }
 
-// applyRefundScope 应用退款单专属数据权限。
+// applyRefundReadScope 应用退款单读取数据权限。
-// 退款申请对代理按创建人隔离，避免上级代理通过店铺层级看到下级申请。
+// 代理仅可查看直接所属店铺的申请，不包含下级代理店铺。
-func applyRefundScope(ctx context.Context, query *gorm.DB) *gorm.DB {
+func applyRefundReadScope(ctx context.Context, query *gorm.DB) *gorm.DB {
+	switch middleware.GetUserTypeFromContext(ctx) {
+	case constants.UserTypeSuperAdmin, constants.UserTypePlatform:
+		return query
+	case constants.UserTypeAgent:
+		shopID := middleware.GetShopIDFromContext(ctx)
+		if shopID == 0 {
+			return query.Where("1 = 0")
+		}
+		return query.Where("tb_refund_request.shop_id = ?", shopID)
+	default:
+		return query.Where("1 = 0")
+	}
+}
+
+// applyRefundOperationScope 应用退款单写操作数据权限。
+func applyRefundOperationScope(ctx context.Context, query *gorm.DB) *gorm.DB {
 	switch middleware.GetUserTypeFromContext(ctx) {
 	case constants.UserTypeSuperAdmin, constants.UserTypePlatform:
 		return query

migrations/000207_fix_agent_wallet_tx_type_constraint.down.sql

@@ -0,0 +1,10 @@
+-- 回滚到旧的交易类型白名单（不含 commission_deduct 与 adjustment）。
+-- 注意：若已存在 commission_deduct 或 adjustment 流水，回滚会因违反检查约束而失败，属预期保护。
+ALTER TABLE tb_agent_wallet_transaction
+    DROP CONSTRAINT chk_agent_tx_type;
+
+ALTER TABLE tb_agent_wallet_transaction
+    ADD CONSTRAINT chk_agent_tx_type
+    CHECK (transaction_type IN ('recharge', 'deduct', 'refund', 'commission', 'withdrawal'));
+
+COMMENT ON COLUMN tb_agent_wallet_transaction.transaction_type IS '交易类型：recharge-充值 adjustment-人工调整 deduct-扣款 refund-退款 commission-分佣 withdrawal-提现';

migrations/000207_fix_agent_wallet_tx_type_constraint.up.sql

@@ -0,0 +1,20 @@
+-- 修复代理钱包交易类型检查约束缺少 commission_deduct 与 adjustment 的问题。
+-- 代码常量与列注释早已包含这两种类型，但 chk_agent_tx_type 从未同步，
+-- 导致写入退款佣金回扣（commission_deduct）和人工余额调整（adjustment）流水时
+-- 违反检查约束，退款佣金回扣因此持续失败、无法收回佣金。
+ALTER TABLE tb_agent_wallet_transaction
+    DROP CONSTRAINT chk_agent_tx_type;
+
+ALTER TABLE tb_agent_wallet_transaction
+    ADD CONSTRAINT chk_agent_tx_type
+    CHECK (transaction_type IN (
+        'recharge',
+        'deduct',
+        'refund',
+        'commission',
+        'withdrawal',
+        'commission_deduct',
+        'adjustment'
+    ));
+
+COMMENT ON COLUMN tb_agent_wallet_transaction.transaction_type IS '交易类型：recharge-充值 adjustment-人工调整 deduct-扣款 refund-退款 commission-分佣 commission_deduct-退款佣金回扣 withdrawal-提现';

migrations/000208_fix_asset_wallet_tx_type_constraint.down.sql

@@ -0,0 +1,8 @@
+-- 回滚到旧的交易类型白名单（不含 exchange）。
+-- 注意：若已存在 exchange 流水，回滚会因违反检查约束而失败，属预期保护。
+ALTER TABLE tb_asset_wallet_transaction
+    DROP CONSTRAINT chk_card_tx_type;
+
+ALTER TABLE tb_asset_wallet_transaction
+    ADD CONSTRAINT chk_card_tx_type
+    CHECK (transaction_type IN ('recharge', 'deduct', 'refund'));

migrations/000208_fix_asset_wallet_tx_type_constraint.up.sql

@@ -0,0 +1,9 @@
+-- 修复资产钱包交易类型检查约束缺少 exchange 的问题。
+-- 代码常量 AssetTransactionTypeExchange 已用于换货余额迁移，
+-- 但 chk_card_tx_type 从未同步，导致写入 exchange 流水时违反检查约束。
+ALTER TABLE tb_asset_wallet_transaction
+    DROP CONSTRAINT chk_card_tx_type;
+
+ALTER TABLE tb_asset_wallet_transaction
+    ADD CONSTRAINT chk_card_tx_type
+    CHECK (transaction_type IN ('recharge', 'deduct', 'refund', 'exchange'));

migrations/000209_allow_commission_wallet_negative_balance.down.sql

@@ -0,0 +1,13 @@
+-- 回滚：恢复佣金（commission）钱包不允许负余额的旧约束。
+-- 注意：若已存在负余额佣金数据，回滚会因违反检查约束而失败，属预期保护。
+ALTER TABLE tb_agent_wallet
+    DROP CONSTRAINT chk_agent_wallet_available_balance;
+
+ALTER TABLE tb_agent_wallet
+    ADD CONSTRAINT chk_agent_wallet_available_balance
+    CHECK (
+        (wallet_type = 'main' AND (balance::numeric - frozen_balance::numeric +
+            CASE WHEN credit_enabled THEN credit_limit::numeric ELSE 0::numeric END) >= 0::numeric)
+        OR
+        (wallet_type = 'commission' AND balance >= 0 AND frozen_balance <= balance)
+    );

migrations/000209_allow_commission_wallet_negative_balance.up.sql

@@ -0,0 +1,14 @@
+-- 允许佣金（commission）钱包出现负余额：退款佣金回扣优先于提现，
+-- 回扣后店铺佣金可能倒欠平台，负余额由回扣流程显式允许。
+-- 提现冻结仍受 frozen_balance <= GREATEST(balance, 0) 约束：负余额时不允许冻结新提现。
+ALTER TABLE tb_agent_wallet
+    DROP CONSTRAINT chk_agent_wallet_available_balance;
+
+ALTER TABLE tb_agent_wallet
+    ADD CONSTRAINT chk_agent_wallet_available_balance
+    CHECK (
+        (wallet_type = 'main' AND (balance::numeric - frozen_balance::numeric +
+            CASE WHEN credit_enabled THEN credit_limit::numeric ELSE 0::numeric END) >= 0::numeric)
+        OR
+        (wallet_type = 'commission' AND frozen_balance <= GREATEST(balance, 0))
+    );

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-18

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/design.md

@@ -0,0 +1,31 @@
+## Context
+
+退款列表和详情当前共用按创建人过滤的数据访问方法。详情读取还被退款审批、退回和重新提交等写操作用于加载退款申请，因此直接把该方法改为按店铺过滤，会扩大既有写操作的对象范围。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让代理仅在退款列表和详情读取时按当前登录账号的直接所属店铺查看退款。
+- 保持下级代理店铺不可见，并保持退款写操作的既有创建人权限边界。
+
+**Non-Goals:**
+- 不改变平台和超级管理员的可见范围。
+- 不改变代理创建退款、审批、退回、拒绝或重新提交的授权规则。
+- 不补齐历史退款中缺失的店铺归属数据。
+
+## Decisions
+
+- 读取路径以认证上下文中的直接 `ShopID` 与退款申请的 `ShopID` 精确匹配，不使用包含下级店铺的 `SubordinateShopIDs`。这是账号所属店铺的稳定事实，且能直接满足排除下级代理的要求。
+- 为列表与详情读取使用店铺可见范围；写操作继续通过创建人范围加载退款申请。读取与写入分别显式选择权限范围，避免共享查询方法导致查看权限扩展为操作权限。
+- 代理上下文没有有效 `ShopID` 时施加恒假条件，不回退至未过滤查询。备选方案是返回参数错误；选择空结果/不存在以与现有未授权对象查询行为一致，并避免暴露数据存在性。
+
+## Risks / Trade-offs
+
+- [历史退款的 `shop_id` 为空] → 该类记录不会对代理可见，仍由平台和超级管理员查询；不在本次改动中推断或回填归属。
+- [读取与写入使用不同权限方法] → 在方法名称和调用处明确区分读取可见性与操作授权，并在实现后逐一检查退款服务中全部按 ID 加载的调用者。
+
+## Migration Plan
+
+1. 发布应用代码；无需数据迁移。
+2. 使用同店铺不同账号、下级店铺和未绑定店铺账号分别验证列表及详情。
+3. 如需回滚，恢复代理退款读取的创建人过滤；数据库数据不受影响。

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+代理账号当前仅能按退款申请创建人查看退款，导致同一店铺的其他账号创建退款后，本店代理无法在退款管理中查询或查看详情。
+
+## What Changes
+
+- 将代理账号的退款列表和详情可见范围从“本人创建”调整为“与当前代理同一店铺”。
+- 同店铺内其他账号创建的退款申请对该店铺代理可见。
+- 代理账号仍不得因本次调整看到下级代理店铺的退款申请；平台和超级管理员既有全量可见范围不变。
+
+## Capabilities
+
+### New Capabilities
+
+- 无。
+
+### Modified Capabilities
+
+- `order-refund-exchange`: 调整代理账号查询退款列表和详情时的数据可见范围。
+
+## Impact
+
+- 影响 `GET /api/admin/refunds` 与 `GET /api/admin/refunds/{id}` 的代理数据权限过滤。
+- 预计修改退款数据访问层及其调用所依赖的当前账号店铺范围获取逻辑；不新增接口、依赖或数据库结构。

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/specs/order-refund-exchange/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: 代理退款查询按所属店铺隔离
+系统 SHALL 允许代理账号通过 `GET /api/admin/refunds` 查询其当前所属店铺的全部退款申请，并通过 `GET /api/admin/refunds/{id}` 查询其中任一申请详情，不以申请创建账号作为查询条件。该范围 SHALL 不包含下级代理店铺、其他店铺或未关联店铺的退款申请；代理账号未关联店铺时，列表 SHALL 为空且详情 SHALL 返回不存在。平台和超级管理员的既有退款查询范围 SHALL 保持不变。
+
+#### Scenario: 查看同店铺其他账号提交的退款
+- **GIVEN** 当前代理所属店铺存在由另一账号创建的退款申请
+- **WHEN** 该代理查询退款列表或该申请详情
+- **THEN** 系统返回该退款申请
+
+#### Scenario: 查询下级代理店铺的退款
+- **GIVEN** 当前代理的下级代理店铺存在退款申请
+- **WHEN** 当前代理查询退款列表或该申请详情
+- **THEN** 系统不返回该退款申请，详情查询返回不存在
+
+#### Scenario: 未绑定店铺的代理查询退款
+- **GIVEN** 当前代理账号未关联店铺
+- **WHEN** 该代理查询退款列表或退款申请详情
+- **THEN** 系统返回空列表或不存在，且不泄露任何退款申请

openspec/changes/archive/2026-08-18-agent-refund-shop-visibility/tasks.md

@@ -0,0 +1,10 @@
+## 1. 退款读取权限
+
+- [x] 1.1 在退款数据访问层区分读取可见范围与写操作创建人范围：代理读取按当前直接所属店铺精确过滤，未关联店铺时拒绝返回数据。
+- [x] 1.2 将退款列表和详情读取接入店铺可见范围，并逐一核对退款服务所有按 ID 加载的写操作仍使用既有创建人范围。
+
+## 2. 验证
+
+- [x] 2.1 执行 gofmt，并构建 `./cmd/api` 和 `./cmd/worker`，确认修改可编译。
+- [x] 2.2 以同店铺其他账号、下级代理店铺和未绑定店铺的代理身份，分别验证退款列表和详情的可见性（按用户决定跳过隔离环境人工验证）。
+- [x] 2.3 执行 `openspec validate agent-refund-shop-visibility --strict`，确认变更工件有效。

openspec/changes/fix-audit-retention-null-boundary/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-18

openspec/changes/fix-audit-retention-null-boundary/design.md

@@ -0,0 +1,45 @@
+## Context
+
+`internal/query/retention` 以聚合查询计算审计与外部交互日志的在线留存边界。PostgreSQL 在没有匹配行时会为 `MAX` 和 `MIN` 返回 `NULL`，而当前扫描目标不能接收空值，导致所有依赖该边界的审计调查接口失败。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 将空聚合结果识别为“尚无边界”，而非数据库错误。
+- 保持已有已清理边界、最早在线记录和当月兜底的语义。
+- 修复所有通过同一留存边界查询函数进入的审计接口。
+
+**Non-Goals:**
+
+- 不执行审计物理清理，不改变归档或保留策略。
+- 不修改数据库结构、迁移记录或历史审计数据。
+- 不修改 API 路由、权限或响应字段。
+
+## Decisions
+
+### 使用可空时间承接 SQL 聚合结果
+
+留存边界查询使用标准库可空时间值承接 `MAX(range_end)` 与 `MIN(<time-column>)`。仅在值有效时转换为目标时区并作为边界返回。
+
+拒绝将聚合结果用当前时间或固定时间 SQL `COALESCE`：这会把“尚未清理”误判为已归档，改变响应中的留存语义。
+
+### 同时覆盖已清理和最早在线两个聚合路径
+
+`MAX(range_end)` 是本次线上错误入口；`MIN` 在在线表为空时具有相同的空值扫描风险。两个路径共用相同的可空聚合边界，应一次修复。
+
+## Risks / Trade-offs
+
+- [风险] 空边界被误判为已清理，错误拒绝历史查询 → 仅在聚合值有效时设置已清理标记与归档边界。
+- [风险] 修复遗漏其他审计接口 → 保持修改在所有审计查询共用的留存边界函数内。
+
+## Migration Plan
+
+1. 修改留存边界的空时间扫描逻辑。
+2. 格式化并构建 API。
+3. 仅替换 API 二进制并重启 API Unit。
+4. 以 `GET /api/admin/audit/events?page=1&page_size=20` 验证无已清理记录时接口不再返回 500。
+
+### Rollback
+
+无数据库迁移。若 API 启动或查询异常，覆盖回本次发布前 API 二进制并重启 API Unit。

openspec/changes/fix-audit-retention-null-boundary/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+生产环境尚未执行审计物理清理时，留存边界查询中的 `MAX(range_end)` 返回 SQL `NULL`，当前实现无法扫描该值，导致 `GET /api/admin/audit/events` 等审计查询返回服务端错误。
+
+## What Changes
+
+- 将审计及外部交互日志留存边界的可空聚合结果作为可空时间处理。
+- 没有完成物理清理记录时，审计查询继续返回在线数据，且 `archived_before` 保持为空。
+- 没有在线审计或集成交互数据时，保留现有的当月起始时间兜底边界。
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+- `operations-audit`: 审计调查在尚无已完成物理清理记录时仍可查询在线审计事实。
+
+## Impact
+
+- 代码：`internal/query/retention/retention.go`。
+- API：修复全局审计事件、时间线、资源活动、风险和资金审计等依赖留存边界的既有查询。
+- 数据库：无迁移、无数据修复。
+- 部署：仅需重新构建和发布 API 二进制。

openspec/changes/fix-audit-retention-null-boundary/specs/operations-audit/spec.md

@@ -0,0 +1,49 @@
+## MODIFIED Requirements
+
+### Requirement: 审计时间线
+
+系统 SHALL 支持按事件、操作者、资源、请求、关联标识和资金维度查询已记录的审计事实。新建的 `tb_integration_log` 在已取得稳定审计事件时 SHALL 写入其内部 ID 作为 `audit_event_id`，并且该日志的非空 `integration_id` SHALL 出现在对应事件列表和事件详情的 `investigation_refs.integration_refs` 中；关联生成失败时系统 MUST 保留 Integration Log 并记录可排查告警，且 MUST NOT 按名称、时间或摘要推断关联。历史 Integration Log 不在本要求的回填范围内。审计事件的构造、校验或持久化失败 MUST 记录可关联的结构化错误日志和二次失败记录，且 MUST NOT 改变已通过业务校验的业务操作结果或接口响应。尚无完成物理清理记录时，审计调查接口 MUST 继续查询在线审计事实，且返回的留存边界不得将数据标记为已归档。
+
+#### Scenario: 审计时间线
+
+- **GIVEN** 审计事实已存在
+- **WHEN** 使用对应维度查询
+- **THEN** 返回匹配的事实与稳定动作编码，不用访问日志替代
+
+#### Scenario: 事件返回已关联外部交互引用
+
+- **GIVEN** 一个在线审计事件有 `tb_integration_log.audit_event_id` 指向其内部 ID 的外部交互记录
+- **WHEN** 查询全局审计事件列表或该事件详情
+- **THEN** 该事件的 `investigation_refs.integration_refs` 返回该记录的 `integration_id`
+
+#### Scenario: 事件没有关联外部交互引用
+
+- **GIVEN** 一个在线审计事件没有稳定关联的外部交互记录
+- **WHEN** 查询全局审计事件列表或该事件详情
+- **THEN** `investigation_refs.integration_refs` 返回空数组
+
+#### Scenario: 新外部交互日志具有稳定审计关联
+
+- **GIVEN** 系统即将记录一次新的外部调用、入站回调或未发送裁决
+- **WHEN** 写入对应 Integration Log
+- **THEN** 该记录保存非空 `audit_event_id`，且其目标 Audit Event 已存在
+
+#### Scenario: 缺少审计关联时保留外部交互日志
+
+- **GIVEN** 一次新的外部交互日志没有稳定审计事件关联
+- **WHEN** 系统尝试写入该 Integration Log
+- **THEN** 系统持久化该 Integration Log、记录可排查告警，并返回空 `integration_refs`
+
+#### Scenario: 审计写入失败不阻断业务
+
+- **GIVEN** 一个业务操作已通过自身输入、权限和状态校验
+- **WHEN** 该操作的审计事件构造、校验或持久化失败
+- **THEN** 系统提交或返回该业务操作原本的结果，并以请求关联标识、动作编码和资源标识记录审计失败
+
+#### Scenario: 尚无物理清理记录时查询在线审计
+
+- **GIVEN** 审计或外部交互日志尚无完成物理清理的归档运行记录
+- **WHEN** 调用任一依赖留存边界的审计调查接口
+- **THEN** 系统返回当前在线数据或空列表
+- **AND** 响应中的 `archived_before` 为空
+- **AND** 系统不得因空留存边界返回服务端错误

openspec/changes/fix-audit-retention-null-boundary/tasks.md

@@ -0,0 +1,10 @@
+## 1. 留存边界空值处理
+
+- [x] 1.1 将已清理边界与最早在线记录的聚合结果改为可空时间扫描，仅在结果有效时设置对应边界。
+- [x] 1.2 保持无已清理记录时 `archived_before` 为空，以及无在线记录时按当月起始时间兜底的现有语义。
+
+## 2. 验证与发布
+
+- [x] 2.1 格式化修改文件并构建 API。
+- [ ] 2.2 验证未执行物理清理时 `GET /api/admin/audit/events?page=1&page_size=20` 不再返回服务端错误。
+- [ ] 2.3 仅发布并重启 API 二进制；不执行数据库迁移、不改 Worker 配置。

openspec/specs/order-refund-exchange/spec.md

@@ -16,6 +16,28 @@
 - **WHEN** 再次审批、发货、完成、取消或重新提交
 - **THEN** 系统返回状态冲突且不重复改变资产、余额或业务状态
 
+### Requirement: 代理退款查询按所属店铺隔离
+
+系统 SHALL 允许代理账号通过 `GET /api/admin/refunds` 查询其当前所属店铺的全部退款申请，并通过 `GET /api/admin/refunds/{id}` 查询其中任一申请详情，不以申请创建账号作为查询条件。该范围 SHALL 不包含下级代理店铺、其他店铺或未关联店铺的退款申请；代理账号未关联店铺时，列表 SHALL 为空且详情 SHALL 返回不存在。平台和超级管理员的既有退款查询范围 SHALL 保持不变。
+
+#### Scenario: 查看同店铺其他账号提交的退款
+
+- **GIVEN** 当前代理所属店铺存在由另一账号创建的退款申请
+- **WHEN** 该代理查询退款列表或该申请详情
+- **THEN** 系统返回该退款申请
+
+#### Scenario: 查询下级代理店铺的退款
+
+- **GIVEN** 当前代理的下级代理店铺存在退款申请
+- **WHEN** 当前代理查询退款列表或该申请详情
+- **THEN** 系统不返回该退款申请，详情查询返回不存在
+
+#### Scenario: 未绑定店铺的代理查询退款
+
+- **GIVEN** 当前代理账号未关联店铺
+- **WHEN** 该代理查询退款列表或退款申请详情
+- **THEN** 系统返回空列表或不存在，且不泄露任何退款申请
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。

openspec/specs/package-lifecycle/spec.md

@@ -38,6 +38,25 @@
 - **WHEN** 操作者为已有系列授权添加套餐
 - **THEN** 系统返回同一店铺和系列的候选套餐及其授权状态，且不改变现有套餐管理提交接口的调价和删除语义
 
+### Requirement: 套餐使用记录价格快照
+
+系统 SHALL 在创建套餐使用记录时分别快照套餐成本价与零售价：`paid_amount`（成本价）SHALL 取订单 `seller_cost_price`（销售成本价，即卖家店铺向平台结算的成本），`retail_amount`（零售价）SHALL 取订单 `total_amount`（零售总价）。成本价与实付金额在个人客户场景下不相等时，`paid_amount` MUST 使用成本价而非实付金额。
+
+#### Scenario: 个人客户购买时快照成本价与零售价
+
+- **WHEN** 个人客户为资产购买套餐，店铺成本价 10900 分，零售价 15900 分，客户实付 15900 分
+- **THEN** 创建的套餐使用记录 `paid_amount = 10900`，`retail_amount = 15900`
+
+#### Scenario: 代理钱包自购时快照成本价与零售价
+
+- **WHEN** 代理以钱包支付为自有资产购买套餐，成本价 7000 分，零售价 9900 分
+- **THEN** 创建的套餐使用记录 `paid_amount = 7000`，`retail_amount = 9900`
+
+#### Scenario: 赠送套餐时快照零成本价与零售价
+
+- **WHEN** 平台赠送套餐，零售价 9900 分，成本价 0 分
+- **THEN** 创建的套餐使用记录 `paid_amount = 0`，`retail_amount = 9900`
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。