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;
  string platform = 11;
  string language = 12;
  string timezone = 13;
}

// 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;
  InviteOverview invite = 28;
}

// InviteOverview 是我的页可直接展示的邀请码和邀请计数 read model。
message InviteOverview {
  string my_invite_code = 1;
  bool invite_enabled = 2;
  int64 invite_count = 3;
  int64 valid_invite_count = 4;
  int64 valid_invite_threshold_coin = 5;
}

// InviteBinding 表示注册完成请求本次是否新绑定邀请关系。
message InviteBinding {
  bool bound = 1;
  string invite_code = 2;
  int64 inviter_user_id = 3;
}

// UserMicLifetimeStats 是用户维度的麦上累计基础指标，不区分主播/公会身份。
message UserMicLifetimeStats {
  int64 user_id = 1;
  int64 seat_occupied_ms = 2;
  int64 mic_online_ms = 3;
  int64 session_count = 4;
  int64 first_mic_at_ms = 5;
  int64 last_mic_at_ms = 6;
  int64 updated_at_ms = 7;
  string app_code = 8;
}

// GetUserMicLifetimeStatsRequest 查询单个用户全部历史麦位时长。
message GetUserMicLifetimeStatsRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
}

message GetUserMicLifetimeStatsResponse {
  UserMicLifetimeStats stats = 1;
}

// CronBatchRequest 是 cron-service 触发 user-service 后台批处理的统一请求。
message CronBatchRequest {
  RequestMeta meta = 1;
  string run_id = 2;
  string worker_id = 3;
  int32 batch_size = 4;
  int64 lock_ttl_ms = 5;
  int64 pending_publish_max_age_ms = 6;
  int64 publishing_session_max_age_ms = 7;
}

// CronBatchResponse 返回一个批处理 run 的执行摘要。
message CronBatchResponse {
  int32 claimed_count = 1;
  int32 processed_count = 2;
  int32 success_count = 3;
  int32 failure_count = 4;
  bool has_more = 5;
}

// 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;
}

message BusinessUserLookupRequest {
  RequestMeta meta = 1;
  int64 actor_user_id = 2;
  string scene = 3;
  string keyword = 4;
  int32 page_size = 5;
}

message BusinessUserLookupItem {
  int64 user_id = 1;
  string display_user_id = 2;
  string username = 3;
  string avatar = 4;
  UserStatus status = 5;
  int64 region_id = 6;
  string region_code = 7;
  string region_name = 8;
}

message BusinessUserLookupResponse {
  repeated BusinessUserLookupItem users = 1;
}

// UserProfileStats 是我的页顶部统计 read model；不得在查询时实时扫描关系链或礼物流水。
message UserProfileStats {
  int64 user_id = 1;
  int64 visitors_count = 2;
  int64 following_count = 3;
  int64 friends_count = 4;
  int64 updated_at_ms = 5;
  string app_code = 6;
}

// GetMyProfileStatsRequest 查询我的页顶部统计计数。
message GetMyProfileStatsRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
}

message GetMyProfileStatsResponse {
  UserProfileStats stats = 1;
}

message RecordProfileVisitRequest {
  RequestMeta meta = 1;
  int64 visitor_user_id = 2;
  int64 target_user_id = 3;
}

message RecordProfileVisitResponse {
  bool recorded = 1;
  UserProfileStats target_stats = 2;
}

message ProfileVisitRecord {
  int64 visitor_user_id = 1;
  int64 target_user_id = 2;
  int64 visit_count = 3;
  int64 last_visited_at_ms = 4;
}

message ListProfileVisitorsRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  int32 page = 3;
  int32 page_size = 4;
}

message ListProfileVisitorsResponse {
  repeated ProfileVisitRecord records = 1;
  int64 total = 2;
}

message FollowUserRequest {
  RequestMeta meta = 1;
  int64 follower_user_id = 2;
  int64 followee_user_id = 3;
}

message FollowUserResponse {
  bool following = 1;
  UserProfileStats follower_stats = 2;
}

message UnfollowUserRequest {
  RequestMeta meta = 1;
  int64 follower_user_id = 2;
  int64 followee_user_id = 3;
}

message UnfollowUserResponse {
  bool following = 1;
  UserProfileStats follower_stats = 2;
}

message FollowRecord {
  int64 follower_user_id = 1;
  int64 followee_user_id = 2;
  int64 followed_at_ms = 3;
}

message ListFollowingRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  int32 page = 3;
  int32 page_size = 4;
  // cursor_updated_at_ms/cursor_user_id 用于内部关系流按时间游标扫描；公开 HTTP 列表仍可继续使用 page/page_size。
  int64 cursor_updated_at_ms = 5;
  int64 cursor_user_id = 6;
}

message ListFollowingResponse {
  repeated FollowRecord records = 1;
  int64 total = 2;
}

message ApplyFriendRequest {
  RequestMeta meta = 1;
  int64 requester_user_id = 2;
  int64 target_user_id = 3;
}

message ApplyFriendResponse {
  FriendApplication application = 1;
  bool already_friends = 2;
}

message AcceptFriendApplicationRequest {
  RequestMeta meta = 1;
  int64 accepter_user_id = 2;
  int64 requester_user_id = 3;
}

message AcceptFriendApplicationResponse {
  FriendRecord friend = 1;
}

message DeleteFriendRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  int64 friend_user_id = 3;
}

message DeleteFriendResponse {
  bool deleted = 1;
}

message FriendRecord {
  int64 user_id = 1;
  int64 friend_user_id = 2;
  int64 friended_at_ms = 3;
}

message ListFriendsRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  int32 page = 3;
  int32 page_size = 4;
  // cursor_updated_at_ms/cursor_user_id 用于内部关系流按时间游标扫描；公开 HTTP 列表仍可继续使用 page/page_size。
  int64 cursor_updated_at_ms = 5;
  int64 cursor_user_id = 6;
}

message ListFriendsResponse {
  repeated FriendRecord records = 1;
  int64 total = 2;
}

message FriendApplication {
  int64 requester_user_id = 1;
  int64 target_user_id = 2;
  string status = 3;
  int64 created_at_ms = 4;
  int64 updated_at_ms = 5;
}

message ListFriendApplicationsRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string direction = 3;
  int32 page = 4;
  int32 page_size = 5;
}

message ListFriendApplicationsResponse {
  repeated FriendApplication applications = 1;
  int64 total = 2;
}

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

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

// ListUserIDsRequest 给低频后台 fanout/重算任务按 user_id 游标读取目标用户。
message ListUserIDsRequest {
  RequestMeta meta = 1;
  string target_scope = 2;
  int64 cursor_user_id = 3;
  int32 page_size = 4;
  int64 region_id = 5;
  string country = 6;
}

// ListUserIDsResponse 返回一页递增 user_id，调用方必须用 next_cursor_user_id 继续。
message ListUserIDsResponse {
  repeated int64 user_ids = 1;
  int64 next_cursor_user_id = 2;
  bool done = 3;
}

// 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;
  int64 old_region_id = 3;
  int64 new_region_id = 4;
  bool region_changed = 5;
}

// SetUserStatusRequest 是封禁、停用和恢复用户的通用内部入口。
// 非 active 状态会同步吊销 refresh session，并把仍在有效期内的 access session 写入 gateway denylist。
message SetUserStatusRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  UserStatus status = 3;
  int64 operator_user_id = 4;
  string reason = 5;
  // operator_type 区分 admin、app_user、system，避免不同身份体系共用一个整数 ID 后无法追溯。
  string operator_type = 6;
}

// SetUserStatusResponse 返回用户当前状态和封禁相关副作用结果。
// 外部副作用字段用于后台或 App 管理入口判断是否需要重试补偿。
message SetUserStatusResponse {
  User user = 1;
  int64 revoked_session_count = 2;
  bool im_kicked = 3;
  string im_kick_error = 4;
  bool room_evicted = 5;
  string room_id = 6;
  bool rtc_kicked = 7;
  string room_evict_error = 8;
  string rtc_kick_error = 9;
  bool access_token_revoked = 10;
  string access_token_revoke_error = 11;
}

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

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

// BindPushTokenRequest 绑定当前登录用户的系统推送 token。
// push token 只服务离线触达，不作为登录凭证或设备身份凭证。
message BindPushTokenRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string device_id = 3;
  string push_token = 4;
  string provider = 5;
  string platform = 6;
  string app_version = 7;
  string language = 8;
  string timezone = 9;
}

message BindPushTokenResponse {
  bool bound = 1;
  int64 updated_at_ms = 2;
}

// DeletePushTokenRequest 删除或失效当前登录用户的系统推送 token。
// push_token 可为空；为空时按 user_id + device_id 失效该设备的 active token。
message DeletePushTokenRequest {
  RequestMeta meta = 1;
  int64 user_id = 2;
  string device_id = 3;
  string push_token = 4;
}

message DeletePushTokenResponse {
  bool deleted = 1;
  int64 updated_at_ms = 2;
}

// 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 BusinessUserLookup(BusinessUserLookupRequest) returns (BusinessUserLookupResponse);
  rpc GetMyProfileStats(GetMyProfileStatsRequest) returns (GetMyProfileStatsResponse);
  rpc BatchGetUsers(BatchGetUsersRequest) returns (BatchGetUsersResponse);
  rpc ListUserIDs(ListUserIDsRequest) returns (ListUserIDsResponse);
  rpc GetUserMicLifetimeStats(GetUserMicLifetimeStatsRequest) returns (GetUserMicLifetimeStatsResponse);
  rpc UpdateUserProfile(UpdateUserProfileRequest) returns (UpdateUserProfileResponse);
  rpc ChangeUserCountry(ChangeUserCountryRequest) returns (ChangeUserCountryResponse);
  rpc SetUserStatus(SetUserStatusRequest) returns (SetUserStatusResponse);
  rpc CompleteOnboarding(CompleteOnboardingRequest) returns (CompleteOnboardingResponse);
}

// UserSocialService 承载用户访问、关注和好友关系。
service UserSocialService {
  rpc RecordProfileVisit(RecordProfileVisitRequest) returns (RecordProfileVisitResponse);
  rpc ListProfileVisitors(ListProfileVisitorsRequest) returns (ListProfileVisitorsResponse);
  rpc FollowUser(FollowUserRequest) returns (FollowUserResponse);
  rpc UnfollowUser(UnfollowUserRequest) returns (UnfollowUserResponse);
  rpc ListFollowing(ListFollowingRequest) returns (ListFollowingResponse);
  rpc ApplyFriend(ApplyFriendRequest) returns (ApplyFriendResponse);
  rpc AcceptFriendApplication(AcceptFriendApplicationRequest) returns (AcceptFriendApplicationResponse);
  rpc DeleteFriend(DeleteFriendRequest) returns (DeleteFriendResponse);
  rpc ListFriends(ListFriendsRequest) returns (ListFriendsResponse);
  rpc ListFriendApplications(ListFriendApplicationsRequest) returns (ListFriendApplicationsResponse);
}

// UserCronService 只给 cron-service 调用，业务状态仍由 user-service owner 修改。
service UserCronService {
  rpc ProcessLoginIPRiskBatch(CronBatchRequest) returns (CronBatchResponse);
  rpc ProcessRegionRebuildBatch(CronBatchRequest) returns (CronBatchResponse);
  rpc CompensateMicOpenSessions(CronBatchRequest) returns (CronBatchResponse);
}

// UserDeviceService 承载 App 设备推送 token 的绑定和失效。
service UserDeviceService {
  rpc BindPushToken(BindPushTokenRequest) returns (BindPushTokenResponse);
  rpc DeletePushToken(DeletePushTokenRequest) returns (DeletePushTokenResponse);
}

// 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);
}