hyapp-server/services/user-service/internal/domain/user/region.go

package user

import (
	"regexp"
	"strings"
)

const (
	// CountryStatusActive 表示国家可以被注册、改国家和区域配置选中。
	CountryStatusActive = "active"
	// CountryStatusDisabled 表示国家只保留历史展示，不再接受新写入。
	CountryStatusDisabled = "disabled"

	// RegionStatusActive 表示区域映射参与国家到区域的实时解析。
	RegionStatusActive = "active"
	// RegionStatusDisabled 表示区域停止解析并释放 active 国家归属。
	RegionStatusDisabled = "disabled"

	// RegionRebuildTaskStatusPending 表示历史用户区域快照等待后台重算。
	RegionRebuildTaskStatusPending = "pending"
	// RegionRebuildTaskStatusRunning 表示任务已被某个 user-service 节点 claim。
	RegionRebuildTaskStatusRunning = "running"
	// RegionRebuildTaskStatusCompleted 表示该 country 下历史用户已经按任务 revision 重算完成。
	RegionRebuildTaskStatusCompleted = "completed"
	// RegionRebuildTaskStatusSkipped 表示任务 revision 已过期，不能覆盖更新映射。
	RegionRebuildTaskStatusSkipped = "skipped"
	// RegionRebuildTaskStatusFailed 表示任务处理失败，等待人工或后续重试策略处理。
	RegionRebuildTaskStatusFailed = "failed"
)

var (
	countryCodePattern = regexp.MustCompile(`^[A-Z]{2,3}$`)
	regionCodePattern  = regexp.MustCompile(`^[A-Z0-9_]{2,32}$`)
)

var defaultCountryAliases = map[string]string{
	// USA 是当前 seed 中唯一需要兼容的 alpha-3 输入；canonical 仍统一写 US，避免美国被配置到两个区域。
	"USA": "US",
}

// Country 是国家主数据；外部只提交 CountryCode，CountryID 只用于管理和审计。
type Country struct {
	CountryID          int64
	CountryName        string
	CountryCode        string
	CountryDisplayName string
	Status             string
	SortOrder          int32
	CreatedByUserID    int64
	UpdatedByUserID    int64
	CreatedAtMs        int64
	UpdatedAtMs        int64
}

// Region 是业务区域主数据；Countries 只放 active 国家码快照。
type Region struct {
	RegionID        int64
	RegionCode      string
	Name            string
	Status          string
	Countries       []string
	SortOrder       int32
	CreatedByUserID int64
	UpdatedByUserID int64
	CreatedAtMs     int64
	UpdatedAtMs     int64
}

// RegionCountryMapping 表示一个 active 或历史国家到区域归属记录。
type RegionCountryMapping struct {
	RegionID    int64
	CountryCode string
	Status      string
	CreatedAtMs int64
	UpdatedAtMs int64
}

// RegionChangeLog 是管理端区域配置审计，不记录用户隐私资料。
type RegionChangeLog struct {
	RegionID       int64
	Operation      string
	BeforeJSON     string
	AfterJSON      string
	OperatorUserID int64
	RequestID      string
	CreatedAtMs    int64
}

// UserRegionRebuildTask 表示按国家分页刷新 users.region_id 的后台任务。
type UserRegionRebuildTask struct {
	TaskID          int64
	RegionID        int64
	CountryCode     string
	TargetRegionID  int64
	MappingRevision int64
	Status          string
	CursorUserID    int64
	LockedBy        string
	LockedUntilMs   int64
	AttemptCount    int32
	ErrorMessage    string
	CreatedAtMs     int64
	UpdatedAtMs     int64
}

// RegionRebuildProcessResult 描述单次 worker 处理结果，便于测试和日志输出。
type RegionRebuildProcessResult struct {
	TaskID         int64
	CountryCode    string
	TargetRegionID int64
	Status         string
	ProcessedUsers int
	CursorUserID   int64
	NoTask         bool
}

// CountryFilter 描述国家管理列表过滤条件。
type CountryFilter struct {
	Status string
}

// RegionFilter 描述区域管理列表过滤条件。
type RegionFilter struct {
	Status string
}

// CreateCountryCommand 描述创建国家主数据的事务输入。
type CreateCountryCommand struct {
	CountryName        string
	CountryCode        string
	CountryDisplayName string
	SortOrder          int32
	OperatorUserID     int64
	RequestID          string
	NowMs              int64
}

// UpdateCountryCommand 描述修改国家展示字段的事务输入，CountryCode 创建后不可变。
type UpdateCountryCommand struct {
	CountryID          int64
	CountryName        string
	CountryDisplayName string
	SortOrder          int32
	OperatorUserID     int64
	RequestID          string
	NowMs              int64
}

// DisableCountryCommand 描述停用国家主数据的事务输入。
type DisableCountryCommand struct {
	CountryID      int64
	OperatorUserID int64
	RequestID      string
	NowMs          int64
}

// CreateRegionCommand 描述创建区域及其 active 国家列表的事务输入。
type CreateRegionCommand struct {
	RegionCode     string
	Name           string
	Countries      []string
	SortOrder      int32
	OperatorUserID int64
	RequestID      string
	NowMs          int64
}

// UpdateRegionCommand 描述修改区域展示字段的事务输入，不修改 countries。
type UpdateRegionCommand struct {
	RegionID       int64
	RegionCode     string
	Name           string
	SortOrder      int32
	OperatorUserID int64
	RequestID      string
	NowMs          int64
}

// ReplaceRegionCountriesCommand 描述原子替换区域 active 国家归属的事务输入。
type ReplaceRegionCountriesCommand struct {
	RegionID       int64
	Countries      []string
	OperatorUserID int64
	RequestID      string
	NowMs          int64
}

// DisableRegionCommand 描述停用区域并释放 active 国家归属的事务输入。
type DisableRegionCommand struct {
	RegionID       int64
	OperatorUserID int64
	RequestID      string
	NowMs          int64
}

// NormalizeCountryCode 统一客户端和管理端提交的国家码形态。
func NormalizeCountryCode(code string) string {
	return strings.ToUpper(strings.TrimSpace(code))
}

// ValidCountryCode 校验本系统允许的两到三位大写英文国家码。
func ValidCountryCode(code string) bool {
	return countryCodePattern.MatchString(code)
}

// DefaultCountryAliases 返回内置 alias -> canonical 映射；生产 MySQL 通过 country_aliases 表持久化同一规则。
func DefaultCountryAliases() map[string]string {
	aliases := make(map[string]string, len(defaultCountryAliases))
	for alias, canonical := range defaultCountryAliases {
		aliases[alias] = canonical
	}

	return aliases
}

// NormalizeRegionCode 统一区域业务编码形态。
func NormalizeRegionCode(code string) string {
	return strings.ToUpper(strings.TrimSpace(code))
}

// ValidRegionCode 校验区域编码，避免自由文本进入唯一键和审计口径。
func ValidRegionCode(code string) bool {
	return regionCodePattern.MatchString(code)
}