feat(收口): 补齐 8 月迭代缺口并同步 Spec 与证据链
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled

- 新增六对成对迁移 000232–000237:H5 弹窗类型、退款结算标识与申请人备注、优先轮询事实字段与两个新终态、通道阈值命中留痕、手机号最近解绑人、提现资格校验留痕
- 退款:原因必填与申请人备注、来源支付与渠道流水冻结、线下处理流水号补录审计、按订单查询可选退款方式、企微审批材料补齐且新增字段缺失映射即明确失败
- 优先轮询:人工关闭、有效期到期独立周期任务、失败与过期人工重触发、事实字段与异常重试查询、资产解析端点只读投影
- 通道阈值:命中事实同事务留痕与命中记录查询;员工账单:列表筛选与详情投影;商户池:列表投影与统计周期语义;H5:弹窗类型与类别排序
- 手机号:有效关联数量与最近解绑人、短信验证码失败次数限制;导出:佣金明细十五列与报表序号列
- 时间筛选:三处新增筛选纳入统一严格解析契约,员工账单产生时间参数改名
- 同步 12 份主 Spec 需求、两端点与异步任务证据链,门禁 context-health 与 OpenSpec 校验通过
This commit is contained in:
2026-09-18 15:34:29 +08:00
parent 5e78809b93
commit 5ed6b39deb
142 changed files with 7878 additions and 964 deletions

View File

@@ -193,29 +193,21 @@ func (s *ManagementService) ListPools(ctx context.Context, req dto.PaymentMercha
if err := query.Count(&total).Error; err != nil {
return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "统计商户池失败")
}
var pools []model.PaymentMerchantPool
if err := query.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&pools).Error; err != nil {
var rows []model.PaymentMerchantPool
if err := query.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池失败")
}
poolIDs := make([]uint, 0, len(pools))
for index := range pools {
poolIDs = append(poolIDs, pools[index].ID)
pools := make([]*model.PaymentMerchantPool, 0, len(rows))
for index := range rows {
pools = append(pools, &rows[index])
}
membersByPool := make(map[uint][]uint, len(pools))
if len(poolIDs) > 0 {
var members []model.PaymentMerchantPoolMember
if err := s.db.WithContext(ctx).Where("pool_id IN ?", poolIDs).Order("pool_id ASC, sort_order ASC").Find(&members).Error; err != nil {
return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池成员失败")
}
for index := range members {
member := &members[index]
membersByPool[member.PoolID] = append(membersByPool[member.PoolID], member.MerchantID)
}
projections, err := loadPoolProjections(ctx, s.db, pools, time.Now())
if err != nil {
return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池成员失败")
}
result := make([]*dto.PaymentMerchantPoolResponse, 0, len(pools))
for index := range pools {
pool := &pools[index]
result = append(result, &dto.PaymentMerchantPoolResponse{ID: pool.ID, Name: pool.Name, PaymentMethod: pool.PaymentMethod, Enabled: pool.Status == model.PaymentMerchantStatusEnabled, Strategy: pool.Strategy, ThresholdAmount: pool.ThresholdAmount, ThresholdCount: pool.ThresholdCount, StatisticCycle: pool.StatisticCycle, TimePeriodValue: pool.TimePeriodValue, TimePeriodUnit: pool.TimePeriodUnit, TimePeriodStartedAt: pool.TimePeriodStartedAt, RoutingEpoch: pool.RoutingEpoch, MemberIDs: membersByPool[pool.ID], Remark: pool.Remark})
for _, pool := range pools {
result = append(result, poolResponse(pool, projections[pool.ID]))
}
return result, total, nil
}
@@ -232,7 +224,7 @@ func (s *ManagementService) GetPool(ctx context.Context, id uint) (*dto.PaymentM
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池失败")
}
return poolResponse(ctx, s.db, &pool)
return s.poolView(ctx, &pool, time.Now())
}
// ListMerchants 分页查询特权商户配置。
@@ -429,8 +421,19 @@ func (s *ManagementService) SavePool(ctx context.Context, id uint, req dto.Payme
if !creating && poolEpochChanged(&pool, &req, previousMemberIDs) {
pool.RoutingEpoch++
}
// 时间轮询池修改周期数值、单位、起始时间或成员顺序并保存成功时,起点由服务端按保存成功时间重算,
// 忽略请求携带的旧起点,避免前端时钟或漏传导致时段漂移。
restartTimedSlot := !creating && strings.TrimSpace(req.Strategy) == model.PaymentMerchantStrategyTime && timedSlotChanged(&pool, &req, previousMemberIDs)
pool.Name, pool.PaymentMethod, pool.Strategy, pool.Remark = strings.TrimSpace(req.Name), strings.TrimSpace(req.PaymentMethod), strings.TrimSpace(req.Strategy), strings.TrimSpace(req.Remark)
pool.ThresholdAmount, pool.ThresholdCount, pool.StatisticCycle, pool.TimePeriodValue, pool.TimePeriodUnit, pool.TimePeriodStartedAt = req.ThresholdAmount, req.ThresholdCount, req.StatisticCycle, req.TimePeriodValue, req.TimePeriodUnit, req.TimePeriodStartedAt
if creating {
// 创建按请求起点;请求缺省起点时取保存时间。
restartTimedSlot = pool.Strategy == model.PaymentMerchantStrategyTime && pool.TimePeriodStartedAt == nil
}
savedAt := time.Now()
if restartTimedSlot {
pool.TimePeriodStartedAt = &savedAt
}
if req.Enabled {
var others int64
if err := tx.Model(&model.PaymentMerchantPool{}).Where("payment_method = ? AND status = ? AND id <> ?", pool.PaymentMethod, model.PaymentMerchantStatusEnabled, pool.ID).Count(&others).Error; err != nil {
@@ -479,7 +482,7 @@ func (s *ManagementService) SavePool(ctx context.Context, id uint, req dto.Payme
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "保存商户池失败")
}
return poolResponse(ctx, s.db, &pool)
return s.poolView(ctx, &pool, time.Now())
}
// SetPoolEnabled enables or disables a pool after rechecking the active-pool and member invariants.
@@ -537,7 +540,7 @@ func (s *ManagementService) SetPoolEnabled(ctx context.Context, id uint, enabled
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新商户池状态失败")
}
return poolResponse(ctx, s.db, &pool)
return s.poolView(ctx, &pool, time.Now())
}
func validatePoolMembers(ctx context.Context, tx *gorm.DB, method string, ids []uint) error {
@@ -582,6 +585,17 @@ func poolEpochChanged(pool *model.PaymentMerchantPool, request *dto.PaymentMerch
return pool.StatisticCycle == nil || (*pool.StatisticCycle != "day" && *pool.StatisticCycle != "month") || !sameMemberSet(previousMemberIDs, request.MemberIDs)
}
// timedSlotChanged 判断保存时间轮询池时是否需要按保存成功时间重算时段起点:
// 周期数值、单位、起始时间或成员顺序任一变化即视为需要重算。
func timedSlotChanged(pool *model.PaymentMerchantPool, request *dto.PaymentMerchantPoolRequest, previousMemberIDs []uint) bool {
if !sameInt64(pool.TimePeriodValue, request.TimePeriodValue) ||
!sameString(pool.TimePeriodUnit, request.TimePeriodUnit) ||
!sameTime(pool.TimePeriodStartedAt, request.TimePeriodStartedAt) {
return true
}
return !sameMemberOrder(previousMemberIDs, request.MemberIDs)
}
func sameMemberOrder(left, right []uint) bool {
if len(left) != len(right) {
return false
@@ -633,16 +647,25 @@ func sameTime(a, b *time.Time) bool {
func merchantResponse(m *model.PaymentMerchant) *dto.PaymentMerchantResponse {
return &dto.PaymentMerchantResponse{ID: m.ID, Name: m.Name, PaymentMethod: m.PaymentMethod, ProviderType: m.ProviderType, MerchantIdentity: m.MerchantIdentity, Credentials: m.Credentials, CredentialVersion: m.CredentialVersion, Enabled: m.Status == model.PaymentMerchantStatusEnabled, Remark: m.Remark, CreatedAt: m.CreatedAt, UpdatedAt: m.UpdatedAt}
}
func poolResponse(ctx context.Context, db *gorm.DB, p *model.PaymentMerchantPool) (*dto.PaymentMerchantPoolResponse, error) {
var rows []model.PaymentMerchantPoolMember
if err := db.WithContext(ctx).Where("pool_id = ?", p.ID).Order("sort_order ASC").Find(&rows).Error; err != nil {
return nil, err
// poolResponse 组装商户池响应,成员、成员计数与命中成员由只读投影提供。
func poolResponse(p *model.PaymentMerchantPool, projection poolProjection) *dto.PaymentMerchantPoolResponse {
response := &dto.PaymentMerchantPoolResponse{ID: p.ID, Name: p.Name, PaymentMethod: p.PaymentMethod, Enabled: p.Status == model.PaymentMerchantStatusEnabled, Strategy: p.Strategy, ThresholdAmount: p.ThresholdAmount, ThresholdCount: p.ThresholdCount, StatisticCycle: p.StatisticCycle, TimePeriodValue: p.TimePeriodValue, TimePeriodUnit: p.TimePeriodUnit, TimePeriodStartedAt: p.TimePeriodStartedAt, RoutingEpoch: p.RoutingEpoch, MemberIDs: projection.MemberIDs, EnabledMemberCount: projection.EnabledMembers, MemberCount: len(projection.MemberIDs), UpdatedAt: p.UpdatedAt, Remark: p.Remark}
if projection.CurrentMerchant != nil {
merchantID := projection.CurrentMerchant.ID
response.CurrentMerchantID = &merchantID
response.CurrentMerchantName = projection.CurrentMerchant.Name
}
ids := make([]uint, 0, len(rows))
for _, row := range rows {
ids = append(ids, row.MerchantID)
return response
}
// poolView 读取商户池的只读列表投影并组装响应。
func (s *ManagementService) poolView(ctx context.Context, pool *model.PaymentMerchantPool, now time.Time) (*dto.PaymentMerchantPoolResponse, error) {
projections, err := loadPoolProjections(ctx, s.db, []*model.PaymentMerchantPool{pool}, now)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池成员失败")
}
return &dto.PaymentMerchantPoolResponse{ID: p.ID, Name: p.Name, PaymentMethod: p.PaymentMethod, Enabled: p.Status == model.PaymentMerchantStatusEnabled, Strategy: p.Strategy, ThresholdAmount: p.ThresholdAmount, ThresholdCount: p.ThresholdCount, StatisticCycle: p.StatisticCycle, TimePeriodValue: p.TimePeriodValue, TimePeriodUnit: p.TimePeriodUnit, TimePeriodStartedAt: p.TimePeriodStartedAt, RoutingEpoch: p.RoutingEpoch, MemberIDs: ids, Remark: p.Remark}, nil
return poolResponse(pool, projections[pool.ID]), nil
}
// GetAuthorization 查询特权全局授权配置。

View File

@@ -249,58 +249,145 @@ func (l *RuntimeLoader) SelectForNewPaymentWithTx(ctx context.Context, tx *gorm.
return &RouteSelection{Merchant: chosen, Pool: &pool}, nil
}
func chooseMerchant(ctx context.Context, tx *gorm.DB, pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, now time.Time) (*model.PaymentMerchant, error) {
// routingOutcome 是只读选路结果。
type routingOutcome struct {
// Merchant 是当前命中成员。
Merchant *model.PaymentMerchant
// OpenNewRound 为真表示每轮累计已全部达标,调用方需以条件更新开启新一轮。
OpenNewRound bool
}
// routeStats 是已按统计世代隔离的商户成功累计。
type routeStats struct {
amounts map[uint]int64
counts map[uint]int64
}
// newRouteStats 创建空的成功累计聚合。
func newRouteStats() routeStats {
return routeStats{amounts: map[uint]int64{}, counts: map[uint]int64{}}
}
// add 累加一条成功事实。
func (s routeStats) add(row *model.PaymentMerchantRoutingSuccess) {
s.amounts[row.MerchantID] += row.Amount
s.counts[row.MerchantID]++
}
// statisticCycle 返回金额/笔数池的统计周期。
func statisticCycle(pool *model.PaymentMerchantPool) (string, error) {
if pool.StatisticCycle == nil {
return "", errors.New(errors.CodeInvalidStatus, "商户池统计周期未配置")
}
return *pool.StatisticCycle, nil
}
// thresholdValue 返回金额/笔数池的达标阈值。
func thresholdValue(pool *model.PaymentMerchantPool) (int64, error) {
if pool.Strategy == model.PaymentMerchantStrategyAmount {
if pool.ThresholdAmount == nil {
return 0, errors.New(errors.CodeInvalidStatus, "金额轮询阈值未配置")
}
return *pool.ThresholdAmount, nil
}
if pool.ThresholdCount == nil {
return 0, errors.New(errors.CodeInvalidStatus, "笔数轮询阈值未配置")
}
return *pool.ThresholdCount, nil
}
// selectRouteMember 只读计算当前命中成员,与支付创建共用同一套规则:
// 金额/笔数取成员顺序中第一个未达阈值的成员;「每轮累计」全部达标时取成员顺序第一项,
// 由调用方开启新一轮;自然日与自然月全部达标时视为当期无可用成员;时间方式按当前时段计算。
// 池内只有一个启用成员时该成员固定命中,不因达到阈值被跳过、也不因全部达标被拒绝,
// 该规则优先于自然周期拒绝语义,短路在全部达标判定之前。
// 本函数 MUST NOT 写库:不创建支付单、不推进统计世代、不计入成功累计。
func selectRouteMember(pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, stats routeStats, now time.Time) (routingOutcome, error) {
if len(merchants) == 0 {
return nil, errors.New(errors.CodeNoPaymentConfig, "暂无可用商户")
return routingOutcome{}, errors.New(errors.CodeNoPaymentConfig, "暂无可用商户")
}
if pool.Strategy == model.PaymentMerchantStrategyTime {
return chooseTimedMerchant(pool, merchants, now)
merchant, err := chooseTimedMerchant(pool, merchants, now)
if err != nil {
return routingOutcome{}, err
}
return routingOutcome{Merchant: merchant}, nil
}
if pool.Strategy != model.PaymentMerchantStrategyAmount && pool.Strategy != model.PaymentMerchantStrategyCount {
return nil, errors.New(errors.CodeInvalidStatus, "商户池轮询策略无效")
return routingOutcome{}, errors.New(errors.CodeInvalidStatus, "商户池轮询策略无效")
}
if pool.StatisticCycle == nil {
return nil, errors.New(errors.CodeInvalidStatus, "商户池统计周期未配置")
cycle, err := statisticCycle(pool)
if err != nil {
return routingOutcome{}, err
}
threshold, err := thresholdValue(pool)
if err != nil {
return routingOutcome{}, err
}
if len(merchants) == 1 {
return routingOutcome{Merchant: merchants[0]}, nil
}
for _, merchant := range merchants {
if pool.Strategy == model.PaymentMerchantStrategyAmount {
if stats.amounts[merchant.ID] < threshold {
return routingOutcome{Merchant: merchant}, nil
}
continue
}
if stats.counts[merchant.ID] < threshold {
return routingOutcome{Merchant: merchant}, nil
}
}
if cycle != "round" {
return routingOutcome{}, errors.New(errors.CodeNoPaymentConfig, "当前周期暂无可用商户")
}
return routingOutcome{Merchant: merchants[0], OpenNewRound: true}, nil
}
func chooseMerchant(ctx context.Context, tx *gorm.DB, pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, now time.Time) (*model.PaymentMerchant, error) {
var stats routeStats
if pool.Strategy == model.PaymentMerchantStrategyAmount || pool.Strategy == model.PaymentMerchantStrategyCount {
loaded, err := loadPoolRouteStats(ctx, tx, pool, now)
if err != nil {
return nil, err
}
stats = loaded
}
outcome, err := selectRouteMember(pool, merchants, stats, now)
if err != nil {
return nil, err
}
if !outcome.OpenNewRound {
return outcome.Merchant, nil
}
// 每轮累计全部达标:当轮结束,以条件更新递增统计世代开启新一轮;
// 世代已被并发改变时按并发冲突拒绝本次创建,绝不在旧世代上重复累计。
if err := advanceRoutingEpoch(ctx, tx, pool); err != nil {
return nil, err
}
return outcome.Merchant, nil
}
// loadPoolRouteStats 读取单个商户池当前统计世代的成功累计。
// 自然日与自然月周期只统计支付时间不早于当期窗口起点的成功事实。
func loadPoolRouteStats(ctx context.Context, tx *gorm.DB, pool *model.PaymentMerchantPool, now time.Time) (routeStats, error) {
cycle, err := statisticCycle(pool)
if err != nil {
return routeStats{}, err
}
query := tx.WithContext(ctx).Where("pool_id = ? AND routing_epoch = ?", pool.ID, pool.RoutingEpoch)
if start, limited := routingWindowStart(*pool.StatisticCycle, now); limited {
if start, limited := routingWindowStart(cycle, now); limited {
query = query.Where("paid_at >= ?", start)
}
var rows []model.PaymentMerchantRoutingSuccess
if err := query.Find(&rows).Error; err != nil {
return nil, err
return routeStats{}, err
}
amounts := make(map[uint]int64, len(merchants))
counts := make(map[uint]int64, len(merchants))
for _, row := range rows {
amounts[row.MerchantID] += row.Amount
counts[row.MerchantID]++
stats := newRouteStats()
for index := range rows {
stats.add(&rows[index])
}
for _, merchant := range merchants {
if pool.Strategy == model.PaymentMerchantStrategyAmount {
if pool.ThresholdAmount == nil {
return nil, errors.New(errors.CodeInvalidStatus, "金额轮询阈值未配置")
}
if amounts[merchant.ID] < *pool.ThresholdAmount {
return merchant, nil
}
continue
}
if pool.ThresholdCount == nil {
return nil, errors.New(errors.CodeInvalidStatus, "笔数轮询阈值未配置")
}
if counts[merchant.ID] < *pool.ThresholdCount {
return merchant, nil
}
}
if *pool.StatisticCycle != "round" {
return nil, errors.New(errors.CodeNoPaymentConfig, "当前统计周期内暂无可用商户")
}
if err := advanceRoutingEpoch(ctx, tx, pool); err != nil {
return nil, err
}
return merchants[0], nil
return stats, nil
}
func chooseTimedMerchant(pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, now time.Time) (*model.PaymentMerchant, error) {
@@ -353,6 +440,115 @@ func advanceRoutingEpoch(ctx context.Context, tx *gorm.DB, pool *model.PaymentMe
return nil
}
// poolProjection 是商户池列表投影的只读计算结果。
type poolProjection struct {
// MemberIDs 是按顺序排列的成员商户ID。
MemberIDs []uint
// EnabledMembers 是成员中当前启用且支付方式与池一致的商户数量。
EnabledMembers int
// CurrentMerchant 是当前命中成员;池停用或无可用成员时为空。
CurrentMerchant *model.PaymentMerchant
}
// loadPoolProjections 按页批量计算成员计数与当前命中成员,供列表与详情投影复用。
// 只读:不创建支付单、不推进统计世代、不计入成功累计;查询次数为常数,不随池数量线性增长。
// 池停用或没有可用成员时当前命中成员为空,不影响其余字段返回。
func loadPoolProjections(ctx context.Context, db *gorm.DB, pools []*model.PaymentMerchantPool, now time.Time) (map[uint]poolProjection, error) {
projections := make(map[uint]poolProjection, len(pools))
if len(pools) == 0 {
return projections, nil
}
poolIDs := make([]uint, 0, len(pools))
for _, pool := range pools {
poolIDs = append(poolIDs, pool.ID)
}
var members []model.PaymentMerchantPoolMember
if err := db.WithContext(ctx).Where("pool_id IN ?", poolIDs).Order("pool_id ASC, sort_order ASC").Find(&members).Error; err != nil {
return nil, err
}
membersByPool := make(map[uint][]uint, len(pools))
merchantIDs := make([]uint, 0, len(members))
for index := range members {
member := &members[index]
membersByPool[member.PoolID] = append(membersByPool[member.PoolID], member.MerchantID)
merchantIDs = append(merchantIDs, member.MerchantID)
}
merchants := make(map[uint]*model.PaymentMerchant)
if len(merchantIDs) > 0 {
var rows []model.PaymentMerchant
if err := db.WithContext(ctx).Where("id IN ? AND status = ?", merchantIDs, model.PaymentMerchantStatusEnabled).Find(&rows).Error; err != nil {
return nil, err
}
for index := range rows {
merchant := &rows[index]
merchants[merchant.ID] = merchant
}
}
// 金额与笔数启用池当前世代的成功累计一次查出:按池拼出「池 + 世代(+ 当期窗口起点)」
// 条件,既避免逐池查询,也避免把其他世代与上一周期的成功事实读进内存。
terms := make([]string, 0, len(pools))
args := make([]any, 0, len(pools)*3)
for _, pool := range pools {
if pool.Status != model.PaymentMerchantStatusEnabled || len(membersByPool[pool.ID]) == 0 {
continue
}
if pool.Strategy != model.PaymentMerchantStrategyAmount && pool.Strategy != model.PaymentMerchantStrategyCount {
continue
}
cycle, err := statisticCycle(pool)
if err != nil {
continue
}
if start, limited := routingWindowStart(cycle, now); limited {
terms = append(terms, "(pool_id = ? AND routing_epoch = ? AND paid_at >= ?)")
args = append(args, pool.ID, pool.RoutingEpoch, start)
continue
}
terms = append(terms, "(pool_id = ? AND routing_epoch = ?)")
args = append(args, pool.ID, pool.RoutingEpoch)
}
statsByPool := make(map[uint]routeStats, len(pools))
if len(terms) > 0 {
var rows []model.PaymentMerchantRoutingSuccess
if err := db.WithContext(ctx).Where(strings.Join(terms, " OR "), args...).Find(&rows).Error; err != nil {
return nil, err
}
for index := range rows {
row := &rows[index]
stats, ok := statsByPool[row.PoolID]
if !ok {
stats = newRouteStats()
statsByPool[row.PoolID] = stats
}
stats.add(row)
}
}
for _, pool := range pools {
ordered := orderedEnabledMembers(pool, membersByPool[pool.ID], merchants)
projection := poolProjection{MemberIDs: membersByPool[pool.ID], EnabledMembers: len(ordered)}
if pool.Status == model.PaymentMerchantStatusEnabled {
if outcome, err := selectRouteMember(pool, ordered, statsByPool[pool.ID], now); err == nil {
projection.CurrentMerchant = outcome.Merchant
}
}
projections[pool.ID] = projection
}
return projections, nil
}
// orderedEnabledMembers 按成员顺序返回启用且支付方式与池一致的商户。
func orderedEnabledMembers(pool *model.PaymentMerchantPool, memberIDs []uint, merchants map[uint]*model.PaymentMerchant) []*model.PaymentMerchant {
ordered := make([]*model.PaymentMerchant, 0, len(memberIDs))
for _, id := range memberIDs {
merchant := merchants[id]
if merchant == nil || merchant.Status != model.PaymentMerchantStatusEnabled || merchant.PaymentMethod != pool.PaymentMethod {
continue
}
ordered = append(ordered, merchant)
}
return ordered
}
// FreezeRoute writes only non-sensitive route facts onto the payment.
func FreezeRoute(payment *model.Payment, route *RouteSelection) {
if payment == nil || route == nil || route.Merchant == nil || route.Pool == nil {