hyapp-server/services/room-service/internal/room/service/pipeline.go

package service

import (
	"bytes"
	"context"
	"log"
	"time"

	"hyapp/pkg/appcode"
	"hyapp/pkg/xerr"
	"hyapp/services/room-service/internal/room/command"
	"hyapp/services/room-service/internal/room/outbox"
	"hyapp/services/room-service/internal/room/rank"
	"hyapp/services/room-service/internal/room/state"
)

func (s *Service) mutateRoom(ctx context.Context, cmd command.Command, replayable bool, mutate func(now time.Time, current *state.RoomState, localRank *rank.LocalRank) (mutationResult, []outbox.Record, error)) (mutationResult, error) {
	if cmd.RoomID() == "" || cmd.ID() == "" || cmd.ActorUserID() == 0 {
		// command meta 是幂等、路由、审计和权限判断的共同基础，缺一不可。
		return mutationResult{}, xerr.New(xerr.InvalidArgument, "command meta is incomplete")
	}

	payload, seen, err := s.commandPayloadForIdempotency(ctx, cmd)
	if err != nil {
		return mutationResult{}, err
	}
	if seen {
		// 幂等命令不重新执行 mutate，也不会再次调用 wallet 或写 outbox。
		snapshot, err := s.currentSnapshot(ctx, cmd.RoomID())
		if err != nil {
			return mutationResult{}, err
		}

		return mutationResult{snapshot: snapshot}, nil
	}

	// 确保当前节点持有房间 lease，并在没有内存 Cell 时完成恢复。
	roomCell, err := s.ensureCell(ctx, cmd.RoomID())
	if err != nil {
		return mutationResult{}, err
	}

	value, err := roomCell.Do(ctx, func(current *state.RoomState, currentRank *rank.LocalRank) (any, error) {
		// 在副本上执行命令，只有 command log/outbox 保存成功后才整体替换当前状态。
		nextState := current.Clone()
		nextRank := currentRank.Clone()
		now := s.clock.Now()

		result, outboxRecords, err := mutate(now, nextState, nextRank)
		if err != nil {
			// 校验、钱包或业务失败时不提交状态，不写 command log。
			return nil, err
		}

		if result.snapshot == nil {
			// 无特殊返回需求的命令默认返回变更后的快照。
			result.snapshot = nextState.ToProto()
		}
		result.snapshot = snapshotWithApp(ctx, result.snapshot)

		if result.snapshot.GetVersion() != current.Version {
			// 版本变化代表本命令产生实际状态变更，需要持久化命令和事件。
			if err := s.repository.SaveCommand(ctx, CommandRecord{
				AppCode:     appcode.FromContext(ctx),
				RoomID:      cmd.RoomID(),
				RoomVersion: nextState.Version,
				CommandID:   cmd.ID(),
				CommandType: cmd.Type(),
				Payload:     commandPayloadForRecord(payload, result),
				Replayable:  replayable,
				CreatedAt:   now,
			}); err != nil {
				return nil, err
			}

			if len(outboxRecords) > 0 {
				// outbox 与 command log 共同构成恢复和房间外投递来源。
				if err := s.repository.SaveOutbox(ctx, outboxRecords); err != nil {
					return nil, err
				}
			}

			// 持久化成功后再替换内存状态，避免内存提交领先于恢复来源。
			current.ReplaceWith(nextState)
			currentRank.ReplaceWith(nextRank)
			result.snapshot = snapshotWithApp(ctx, current.ToProto())
			result.applied = true
		} else {
			// no-op 命令仍写入 command log，保证相同 command_id 重试可命中幂等，
			// 不同 payload 复用 command_id 会被后续入口拒绝为 CONFLICT。
			if err := s.repository.SaveCommand(ctx, CommandRecord{
				AppCode:     appcode.FromContext(ctx),
				RoomID:      cmd.RoomID(),
				RoomVersion: current.Version,
				CommandID:   cmd.ID(),
				CommandType: cmd.Type(),
				Payload:     payload,
				Replayable:  false,
				CreatedAt:   now,
			}); err != nil {
				return nil, err
			}
		}

		return result, nil
	})
	if err != nil {
		return mutationResult{}, err
	}

	result := value.(mutationResult)

	if result.applied && shouldSnapshot(result.snapshot, s.snapshotEveryN) {
		// 快照失败时返回错误，因为没有快照会增加恢复成本并可能影响 guard 查询。
		if err := s.persistSnapshot(ctx, result.snapshot); err != nil {
			return mutationResult{}, err
		}
	}
	if result.applied {
		// 列表读模型最终一致，失败只记录日志，不回滚已经提交的 Room Cell 命令。
		s.projectRoomListBestEffort(ctx, result.snapshot)
	}

	if result.applied && result.syncEvent != nil {
		// 同步腾讯云 IM 失败不回滚房间状态；outbox 后续负责补偿投递。
		if err := s.syncPublisher.PublishRoomEvent(ctx, *result.syncEvent); err == nil {
			// 同步投递成功后 best-effort 标记 published，避免补偿 worker 对同一 event_id 重复补投。
			markCtx, cancel := context.WithTimeout(context.Background(), defaultOutboxWorkerOptions().PublishTimeout)
			markErr := s.repository.MarkOutboxPublished(markCtx, result.syncEvent.EventID)
			cancel()
			if markErr != nil {
				log.Printf("worker=room_outbox node_id=%s event_id=%s room_id=%s status=mark_published_failed error=%q", s.nodeID, result.syncEvent.EventID, result.syncEvent.RoomID, trimOutboxError(markErr.Error()))
			}
		}
	}

	return result, nil
}

func (s *Service) commandPayloadForIdempotency(ctx context.Context, cmd command.Command) ([]byte, bool, error) {
	payload, err := command.Serialize(cmd)
	if err != nil {
		return nil, false, err
	}

	record, exists, err := s.repository.GetCommand(ctx, cmd.RoomID(), cmd.ID())
	if err != nil {
		return nil, false, err
	}
	if !exists {
		return payload, false, nil
	}
	currentIDPayload, err := command.IdempotencyPayload(payload)
	if err != nil {
		return nil, true, err
	}
	storedIDPayload, err := command.IdempotencyPayload(record.Payload)
	if err != nil {
		return nil, true, err
	}
	if record.CommandType != cmd.Type() || !bytes.Equal(storedIDPayload, currentIDPayload) {
		return nil, true, xerr.New(xerr.Conflict, "command_id payload conflict")
	}

	return payload, true, nil
}

func commandPayloadForRecord(defaultPayload []byte, result mutationResult) []byte {
	if len(result.commandPayload) > 0 {
		return result.commandPayload
	}
	return defaultPayload
}