syntax = "proto3";

package hyapp.user.v1;

option go_package = "hyapp.local/api/proto/user/v1;userv1";

// RequestMeta 是 user-service 所有内部 RPC 的最小追踪元信息。
message RequestMeta {
  string request_id = 1;
  string caller = 2;
  string gateway_node_id = 3;
  int64 sent_at_ms = 4;
  string device_id = 5;
  string client_ip = 6;
  string user_agent = 7;
  string country_by_ip = 8;
  string session_id = 9;
  string app_code = 10;
}

// App 是 user-service 维护的 App 注册表投影，用于把客户端包名映射到内部租户键。
message App {
  int64 app_id = 1;
  string app_code = 2;
  string app_name = 3;
  string package_name = 4;
  string platform = 5;
  string status = 6;
  int64 created_at_ms = 7;
  int64 updated_at_ms = 8;
}

// ResolveAppRequest 允许 gateway 按包名/平台解析 app_code，也允许后台显式校验 app_code。
message ResolveAppRequest {
  RequestMeta meta = 1;
  string package_name = 2;
  string platform = 3;
  string app_code = 4;
}

message ResolveAppResponse {
  App app = 1;
}

// UserStatus 表达用户主状态，业务服务只消费稳定枚举。
enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ACTIVE = 1;
  USER_STATUS_DISABLED = 2;
  USER_STATUS_BANNED = 3;
}

// User 是用户主数据投影，包含稳定身份、当前短号和基础资料。
message User {
  int64 user_id = 1;
  UserStatus status = 2;
  int64 created_at_ms = 3;
  int64 updated_at_ms = 4;
  string display_user_id = 5;
  string default_display_user_id = 6;
  string display_user_id_kind = 7;
  int64 display_user_id_expires_at_ms = 8;
  string username = 9;
  string gender = 10;
  string country = 11;
  string avatar = 12;
  string birth = 13;
  string language = 14;
  int64 country_id = 15;
  string country_name = 16;
  string country_display_name = 17;
  int64 region_id = 18;
  string region_code = 19;
  string region_name = 20;
  bool profile_completed = 21;
  int64 profile_completed_at_ms = 22;
  string onboarding_status = 23;
  string iso_numeric = 24;
  string phone_country_code = 25;
  bool country_enabled = 26;
  string app_code = 27;
}

// AuthToken 是登录、刷新和注册完成后返回给 gateway 的访问令牌投影。
message AuthToken {
  int64 user_id = 1;
  string session_id = 2;
  string access_token = 3;
  string refresh_token = 4;
  int64 expires_in_sec = 5;
  string token_type = 6;
  string display_user_id = 7;
  string default_display_user_id = 8;
  string display_user_id_kind = 9;
  int64 display_user_id_expires_at_ms = 10;
  bool profile_completed = 11;
  string onboarding_status = 12;
  string app_code = 13;
}

// GetUserRequest 查询单个用户主状态。
message GetUserRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
}

// GetUserResponse 返回单个用户主状态。
message GetUserResponse {
  User user = 1;
}

// BatchGetUsersRequest 批量查询用户主状态。
message BatchGetUsersRequest {
  RequestMeta meta = 1;
  repeated int64 user_ids = 2;
}

// BatchGetUsersResponse 返回按 user_id 索引的用户主状态。
message BatchGetUsersResponse {
  map<int64, User> users = 1;
}

// UpdateUserProfileRequest 修改用户可自助维护的基础资料。
message UpdateUserProfileRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  optional string username = 3;
  optional string avatar = 4;
  optional string birth = 5;
  optional string gender = 6;
}

// UpdateUserProfileResponse 返回更新后的用户资料投影。
message UpdateUserProfileResponse {
  User user = 1;
}

// ChangeUserCountryRequest 单独修改用户国家；该字段有冷却期和变更日志。
message ChangeUserCountryRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string country = 3;
}

// ChangeUserCountryResponse 返回更新后的用户资料和下一次可修改时间。
message ChangeUserCountryResponse {
  User user = 1;
  int64 next_change_allowed_at_ms = 2;
}

// CompleteOnboardingRequest 是注册页唯一资料提交入口。
message CompleteOnboardingRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string username = 3;
  string avatar = 4;
  string country = 5;
  string gender = 6;
}

// CompleteOnboardingResponse 返回固化后的最小注册状态。
message CompleteOnboardingResponse {
  User user = 1;
  bool profile_completed = 2;
  int64 profile_completed_at_ms = 3;
  string onboarding_status = 4;
  AuthToken token = 5;
}

// Country 是国家主数据投影，客户端和普通用户流程只提交 country_code。
message Country {
  int64 country_id = 1;
  string country_name = 2;
  string country_code = 3;
  string country_display_name = 4;
  int32 sort_order = 6;
  int64 created_at_ms = 7;
  int64 updated_at_ms = 8;
  string iso_alpha3 = 9;
  string iso_numeric = 10;
  string phone_country_code = 11;
  bool enabled = 12;
  string flag = 13;
  string app_code = 14;
}

// Region 是区域主数据投影，countries 只包含当前 active 国家码。
message Region {
  int64 region_id = 1;
  string region_code = 2;
  string name = 3;
  string status = 4;
  repeated string countries = 5;
  int32 sort_order = 6;
  int64 created_at_ms = 7;
  int64 updated_at_ms = 8;
  string app_code = 9;
}

message ListCountriesRequest {
  RequestMeta meta = 1;
  optional bool enabled = 3;
}

message ListCountriesResponse {
  repeated Country countries = 1;
}

// UpdateCountryRequest 只修改国家展示字段，不修改 country_code。
message UpdateCountryRequest {
  RequestMeta meta = 1;
  int64 country_id = 2;
  string country_name = 3;
  string country_display_name = 4;
  int32 sort_order = 5;
  int64 operator_user_id = 6;
  string iso_alpha3 = 7;
  string iso_numeric = 8;
  string phone_country_code = 9;
  string flag = 10;
}

message CountryResponse {
  Country country = 1;
}

message ListRegistrationCountriesRequest {
  RequestMeta meta = 1;
}

message ListRegistrationCountriesResponse {
  repeated Country countries = 1;
}

message ListRegionsRequest {
  RequestMeta meta = 1;
  string status = 2;
}

message ListRegionsResponse {
  repeated Region regions = 1;
}

message GetRegionRequest {
  RequestMeta meta = 1;
  int64 region_id = 2;
}

// UpdateRegionRequest 只修改区域展示字段，不修改 countries。
message UpdateRegionRequest {
  RequestMeta meta = 1;
  int64 region_id = 2;
  string region_code = 3;
  string name = 4;
  int32 sort_order = 5;
  int64 operator_user_id = 6;
}

message ReplaceRegionCountriesRequest {
  RequestMeta meta = 1;
  int64 region_id = 2;
  repeated string countries = 3;
  int64 operator_user_id = 4;
}

message RegionResponse {
  Region region = 1;
}

// UserIdentity 是 user_id 和当前 active display_user_id 的绑定投影。
message UserIdentity {
  int64 user_id = 1;
  string display_user_id = 2;
  string status = 3;
  string default_display_user_id = 4;
  string display_user_id_kind = 5;
  int64 display_user_id_expires_at_ms = 6;
  string app_code = 7;
}

// GetUserIdentityRequest 按 user_id 查询当前短号。
message GetUserIdentityRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
}

// GetUserIdentityResponse 返回当前短号绑定。
message GetUserIdentityResponse {
  UserIdentity identity = 1;
}

// ResolveDisplayUserIDRequest 把客户端展示短号解析成系统 user_id。
message ResolveDisplayUserIDRequest {
  RequestMeta meta = 1;
  string display_user_id = 2;
}

// ResolveDisplayUserIDResponse 返回 active 短号归属。
message ResolveDisplayUserIDResponse {
  UserIdentity identity = 1;
}

// ChangeDisplayUserIDRequest 修改用户短号，必须由 user-service 保证事务一致。
message ChangeDisplayUserIDRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string new_display_user_id = 3;
  string reason = 4;
  int64 operator_user_id = 5;
}

// ChangeDisplayUserIDResponse 返回修改后的 active 绑定。
message ChangeDisplayUserIDResponse {
  UserIdentity identity = 1;
}

// ApplyPrettyDisplayUserIDRequest 申请临时靓号并覆盖当前展示号。
message ApplyPrettyDisplayUserIDRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string pretty_display_user_id = 3;
  int64 lease_duration_ms = 4;
  string payment_receipt_id = 5;
}

// ApplyPrettyDisplayUserIDResponse 返回申请成功后的当前展示号和租约。
message ApplyPrettyDisplayUserIDResponse {
  UserIdentity identity = 1;
  string lease_id = 2;
}

// ExpirePrettyDisplayUserIDRequest 主动触发靓号过期恢复。
message ExpirePrettyDisplayUserIDRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string lease_id = 3;
}

// ExpirePrettyDisplayUserIDResponse 返回恢复后的默认短号身份。
message ExpirePrettyDisplayUserIDResponse {
  UserIdentity identity = 1;
}

// UserService 提供用户主状态、基础资料和注册资料读写接口。
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc BatchGetUsers(BatchGetUsersRequest) returns (BatchGetUsersResponse);
  rpc UpdateUserProfile(UpdateUserProfileRequest) returns (UpdateUserProfileResponse);
  rpc ChangeUserCountry(ChangeUserCountryRequest) returns (ChangeUserCountryResponse);
  rpc CompleteOnboarding(CompleteOnboardingRequest) returns (CompleteOnboardingResponse);
}

// AppRegistryService 是 gateway 解析 package_name -> app_code 的内部入口。
service AppRegistryService {
  rpc ResolveApp(ResolveAppRequest) returns (ResolveAppResponse);
}

// CountryAdminService 只保留 App 后端需要承接的国家查询和展示字段更新 RPC。
// 创建国家、启用/禁用国家属于 hyapp-admin-server 后台能力，不在 user-service 暴露 RPC。
service CountryAdminService {
  rpc ListCountries(ListCountriesRequest) returns (ListCountriesResponse);
  rpc UpdateCountry(UpdateCountryRequest) returns (CountryResponse);
}

// CountryQueryService 承载 App 注册页公开国家列表查询。
service CountryQueryService {
  rpc ListRegistrationCountries(ListRegistrationCountriesRequest) returns (ListRegistrationCountriesResponse);
}

// RegionAdminService 只保留 App 后端需要承接的区域查询、展示字段更新和国家归属替换 RPC。
// 创建区域、启用/禁用区域属于 hyapp-admin-server 后台能力，不在 user-service 暴露 RPC。
service RegionAdminService {
  rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse);
  rpc GetRegion(GetRegionRequest) returns (RegionResponse);
  rpc UpdateRegion(UpdateRegionRequest) returns (RegionResponse);
  rpc ReplaceRegionCountries(ReplaceRegionCountriesRequest) returns (RegionResponse);
}

// UserIdentityService 是短号解析和变更的唯一内部 owner。
service UserIdentityService {
  rpc GetUserIdentity(GetUserIdentityRequest) returns (GetUserIdentityResponse);
  rpc ResolveDisplayUserID(ResolveDisplayUserIDRequest) returns (ResolveDisplayUserIDResponse);
  rpc ChangeDisplayUserID(ChangeDisplayUserIDRequest) returns (ChangeDisplayUserIDResponse);
  rpc ApplyPrettyDisplayUserID(ApplyPrettyDisplayUserIDRequest) returns (ApplyPrettyDisplayUserIDResponse);
  rpc ExpirePrettyDisplayUserID(ExpirePrettyDisplayUserIDRequest) returns (ExpirePrettyDisplayUserIDResponse);
}