-- =============================================================================
-- TopFans 本地数据库注释补齐
-- 为所有缺少 COMMENT 的表和字段添加中文注释
-- =============================================================================

BEGIN;

-- =============================================================================
-- 1. activities（运营活动）
-- =============================================================================
COMMENT ON TABLE public.activities IS '运营活动表。支持粉丝应援、铸爱等各类活动配置，通过 stage_configs 定义阶段规则。';
COMMENT ON COLUMN public.activities.id IS '主键，自增';
COMMENT ON COLUMN public.activities.activity_type IS '活动类型：supporting（粉丝应援）| castlove（铸爱）| minting（铸造）等';
COMMENT ON COLUMN public.activities.title IS '活动标题';
COMMENT ON COLUMN public.activities.theme IS '活动主题，如「夏日应援计划」';
COMMENT ON COLUMN public.activities.description IS '活动描述文本';
COMMENT ON COLUMN public.activities.star_id IS 'FK -> stars.star_id，所属明星/星球';
COMMENT ON COLUMN public.activities.start_time IS '活动开始时间，毫秒时间戳';
COMMENT ON COLUMN public.activities.end_time IS '活动结束时间，毫秒时间戳';
COMMENT ON COLUMN public.activities.overall_end_time IS '整体截止时间（含结算期），毫秒时间戳';
COMMENT ON COLUMN public.activities.target_progress IS '目标进度值（如总应援量），默认 1000';
COMMENT ON COLUMN public.activities.current_progress IS '当前进度值';
COMMENT ON COLUMN public.activities.status IS '活动状态：pending | active | completed | cancelled';
COMMENT ON COLUMN public.activities.stage_configs IS '阶段配置 JSON，定义各阶段解锁条件与奖励';
COMMENT ON COLUMN public.activities.icon IS '活动图标 URL';
COMMENT ON COLUMN public.activities.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.activities.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 2. activity_assets（活动作品/资产）
-- =============================================================================
COMMENT ON TABLE public.activity_assets IS '活动作品关联表。记录活动中用户提交的作品，如镭射卡、光栅卡生成图。';
COMMENT ON COLUMN public.activity_assets.id IS '主键，自增';
COMMENT ON COLUMN public.activity_assets.asset_id IS 'FK -> assets.id，关联资产';
COMMENT ON COLUMN public.activity_assets.owner_uid IS '作品所有者用户 ID';
COMMENT ON COLUMN public.activity_assets.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.activity_assets.activity_id IS 'FK -> activities.id，所属活动';
COMMENT ON COLUMN public.activity_assets.activity_type IS '活动类型，冗余 activities.activity_type';
COMMENT ON COLUMN public.activity_assets.name IS '作品名称';
COMMENT ON COLUMN public.activity_assets.cover_url IS '作品封面图 OSS URL';
COMMENT ON COLUMN public.activity_assets.like_count IS '点赞数';
COMMENT ON COLUMN public.activity_assets.status IS '状态：0=正常 | 1=隐藏 | 2=删除';
COMMENT ON COLUMN public.activity_assets.metadata IS '扩展元数据 JSON';
COMMENT ON COLUMN public.activity_assets.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_assets.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 3. activity_contributions（活动贡献记录）
-- =============================================================================
COMMENT ON TABLE public.activity_contributions IS '活动贡献记录表。用户通过提交道具/氪金等方式对活动做贡献的流水。';
COMMENT ON COLUMN public.activity_contributions.id IS '主键，自增';
COMMENT ON COLUMN public.activity_contributions.activity_id IS 'FK -> activities.id';
COMMENT ON COLUMN public.activity_contributions.user_id IS '贡献用户 ID';
COMMENT ON COLUMN public.activity_contributions.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.activity_contributions.item_id IS 'FK -> activity_items.id，贡献道具';
COMMENT ON COLUMN public.activity_contributions.item_type IS '道具类型：crystal（水晶）| item（实物）等';
COMMENT ON COLUMN public.activity_contributions.quantity IS '道具数量，默认 1';
COMMENT ON COLUMN public.activity_contributions.crystal_spent IS '消耗的水晶数量';
COMMENT ON COLUMN public.activity_contributions.contribution_points IS '贡献值/积分';
COMMENT ON COLUMN public.activity_contributions.created_at IS '贡献时间，毫秒时间戳';

-- =============================================================================
-- 4. activity_items（活动道具/物品）
-- =============================================================================
COMMENT ON TABLE public.activity_items IS '活动道具配置表。定义应援活动中的可购买/消耗道具，如荧光棒、应援灯牌。';
COMMENT ON COLUMN public.activity_items.id IS '主键，自增';
COMMENT ON COLUMN public.activity_items.activity_id IS 'FK -> activities.id';
COMMENT ON COLUMN public.activity_items.item_type IS '道具类型标识';
COMMENT ON COLUMN public.activity_items.item_name IS '道具名称，如「荧光棒」「应援丝带」';
COMMENT ON COLUMN public.activity_items.icon_url IS '道具图标 URL';
COMMENT ON COLUMN public.activity_items.crystal_cost IS '道具水晶单价';
COMMENT ON COLUMN public.activity_items.contribution_points IS '道具附带的贡献值';
COMMENT ON COLUMN public.activity_items.sort_order IS '排序，越小越前';
COMMENT ON COLUMN public.activity_items.is_active IS '是否启用';
COMMENT ON COLUMN public.activity_items.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_items.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 5. activity_user_stats（活动用户统计）
-- =============================================================================
COMMENT ON TABLE public.activity_user_stats IS '活动维度用户统计表。记录每个用户在活动中的累计贡献和消耗。';
COMMENT ON COLUMN public.activity_user_stats.id IS '主键，自增';
COMMENT ON COLUMN public.activity_user_stats.activity_id IS 'FK -> activities.id';
COMMENT ON COLUMN public.activity_user_stats.user_id IS '用户 ID';
COMMENT ON COLUMN public.activity_user_stats.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.activity_user_stats.total_contribution IS '累计贡献值';
COMMENT ON COLUMN public.activity_user_stats.total_crystal_spent IS '累计消耗水晶';
COMMENT ON COLUMN public.activity_user_stats.total_items IS '累计提交道具数';
COMMENT ON COLUMN public.activity_user_stats.last_contribute_at IS '最近一次贡献时间';
COMMENT ON COLUMN public.activity_user_stats.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.activity_user_stats.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 6. asset_level_change_logs（资产等级变更日志）
-- =============================================================================
COMMENT ON TABLE public.asset_level_change_logs IS '资产等级变更日志表。记录藏品因展览时长/点赞数触发的等级升降流水。';
COMMENT ON COLUMN public.asset_level_change_logs.id IS '主键，自增';
COMMENT ON COLUMN public.asset_level_change_logs.asset_id IS 'FK -> assets.id';
COMMENT ON COLUMN public.asset_level_change_logs.from_level IS '变更前等级：N/R/SR/SSR';
COMMENT ON COLUMN public.asset_level_change_logs.to_level IS '变更后等级';
COMMENT ON COLUMN public.asset_level_change_logs.trigger_type IS '触发类型：exhibition_hours（展览时长）| likes（点赞数）| season_reset（赛季重置）';
COMMENT ON COLUMN public.asset_level_change_logs.trigger_hours IS '触发时的累计展览小时数';
COMMENT ON COLUMN public.asset_level_change_logs.trigger_likes IS '触发时的累计点赞数';
COMMENT ON COLUMN public.asset_level_change_logs.change_reason IS '变更原因描述';
COMMENT ON COLUMN public.asset_level_change_logs.created_at IS '变更时间，毫秒时间戳';

-- =============================================================================
-- 7. asset_level_records（资产等级记录）
-- =============================================================================
COMMENT ON TABLE public.asset_level_records IS '资产等级当前状态表。维护藏品在赛季内/终身的展览时长和点赞累积。';
COMMENT ON COLUMN public.asset_level_records.id IS '主键，自增';
COMMENT ON COLUMN public.asset_level_records.asset_id IS 'FK -> assets.id，UK';
COMMENT ON COLUMN public.asset_level_records.current_level IS '当前等级：N | R | SR | SSR';
COMMENT ON COLUMN public.asset_level_records.season_exhibition_hours IS '本赛季累计展览小时数';
COMMENT ON COLUMN public.asset_level_records.season_likes IS '本赛季累计获赞数';
COMMENT ON COLUMN public.asset_level_records.lifetime_exhibition_hours IS '终身累计展览小时数';
COMMENT ON COLUMN public.asset_level_records.lifetime_likes IS '终身累计获赞数';
COMMENT ON COLUMN public.asset_level_records.season_id IS '当前赛季 ID';
COMMENT ON COLUMN public.asset_level_records.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 8. asset_likes（资产点赞）
-- =============================================================================
COMMENT ON TABLE public.asset_likes IS '资产点赞记录表。记录用户对展览中藏品的点赞行为。';
COMMENT ON COLUMN public.asset_likes.id IS '主键，自增';
COMMENT ON COLUMN public.asset_likes.asset_id IS 'FK -> assets.id，被点赞的资产';
COMMENT ON COLUMN public.asset_likes.user_id IS '点赞用户 ID';
COMMENT ON COLUMN public.asset_likes.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.asset_likes.exhibition_id IS 'FK -> exhibitions.id，点赞时的展览场次';
COMMENT ON COLUMN public.asset_likes.created_at IS '点赞时间，毫秒时间戳';

-- =============================================================================
-- 9. asset_material_relations（资产-素材关联）
-- =============================================================================
COMMENT ON TABLE public.asset_material_relations IS '资产与素材的关联关系表。镭射卡铸造时写入多素材关联（backdrop/source/cutout/main），layer_order 定义层级。';
COMMENT ON COLUMN public.asset_material_relations.id IS '主键，自增';
COMMENT ON COLUMN public.asset_material_relations.asset_id IS 'FK -> assets.id';
COMMENT ON COLUMN public.asset_material_relations.material_id IS 'FK -> materials.id';
COMMENT ON COLUMN public.asset_material_relations.material_type IS '素材类型标识：backdrop | source | cutout | main | bg 等';
COMMENT ON COLUMN public.asset_material_relations.layer_order IS '合成层级：0=底纹 backdrop | 1=原图 source | 2=抠图 cutout | 3=主合成图 main';
COMMENT ON COLUMN public.asset_material_relations.pos_x IS '素材 X 偏移，可选';
COMMENT ON COLUMN public.asset_material_relations.pos_y IS '素材 Y 偏移，可选';
COMMENT ON COLUMN public.asset_material_relations.opacity IS '透明度，0-1，默认 1';
COMMENT ON COLUMN public.asset_material_relations.rotation IS '旋转角度，默认 0';
COMMENT ON COLUMN public.asset_material_relations.scale_x IS 'X 轴缩放，默认 1';
COMMENT ON COLUMN public.asset_material_relations.scale_y IS 'Y 轴缩放，默认 1';
COMMENT ON COLUMN public.asset_material_relations.version IS '乐观锁版本号';
COMMENT ON COLUMN public.asset_material_relations.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.asset_material_relations.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.asset_material_relations.deleted_at IS '软删除时间，NULL 表示未删除';

-- =============================================================================
-- 10. asset_registry（资产注册表）
-- =============================================================================
COMMENT ON TABLE public.asset_registry IS '资产注册表。每铸造生成一个藏品时写入一行，维护资产类型、所有者、展示状态等检索字段。';
COMMENT ON COLUMN public.asset_registry.id IS '主键，自增';
COMMENT ON COLUMN public.asset_registry.asset_id IS 'FK -> assets.id';
COMMENT ON COLUMN public.asset_registry.asset_type IS '资产类型：star_card（明星卡）| craft（手工创作）等';
COMMENT ON COLUMN public.asset_registry.owner_uid IS '当前持有者用户 ID';
COMMENT ON COLUMN public.asset_registry.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.asset_registry.grade IS '稀有度等级（0-4）';
COMMENT ON COLUMN public.asset_registry.collection_category IS '藏品分类标签';
COMMENT ON COLUMN public.asset_registry.activity_id IS '关联活动 ID，如铸爱活动';
COMMENT ON COLUMN public.asset_registry.activity_type IS '活动类型冗余';
COMMENT ON COLUMN public.asset_registry.status IS '状态：0=正常 | 1=隐藏 | 2=下架';
COMMENT ON COLUMN public.asset_registry.like_count IS '累计点赞数';
COMMENT ON COLUMN public.asset_registry.display_status IS '展示状态：0=在展 | 1=已撤展 | 2=预约中';
COMMENT ON COLUMN public.asset_registry.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.asset_registry.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 11. assets（资产/藏品主体表）
-- =============================================================================
COMMENT ON TABLE public.assets IS '资产主体表。TopFans 核心表之一，存储铸造生成的每一件数字藏品元数据。';
COMMENT ON COLUMN public.assets.id IS '主键，自增';
COMMENT ON COLUMN public.assets.owner_uid IS '所有者用户 ID';
COMMENT ON COLUMN public.assets.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.assets.name IS '藏品名称';
COMMENT ON COLUMN public.assets.cover_url IS '藏品封面图 OSS URL';
COMMENT ON COLUMN public.assets.material_url IS '素材原始 OSS URL（铸造时传入，可能含签名）';
COMMENT ON COLUMN public.assets.description IS '藏品描述文本';
COMMENT ON COLUMN public.assets.grade IS '稀有度等级（0-4 对应 N/R/SR/SSR）';
COMMENT ON COLUMN public.assets.tags IS '标签 JSON 数组，如 ["cast:star_card", "craft:laser"]';
COMMENT ON COLUMN public.assets.visibility IS '可见性：private | public | friend_only';
COMMENT ON COLUMN public.assets.info IS '扩展信息文本（前端展示用）';
COMMENT ON COLUMN public.assets.status IS '状态：0=正常 | 1=隐藏 | 2=删除';
COMMENT ON COLUMN public.assets.tx_hash IS '链上交易哈希（Web3 铸造时记录）';
COMMENT ON COLUMN public.assets.block_number IS '链上区块高度';
COMMENT ON COLUMN public.assets.like_count IS '累计点赞数';
COMMENT ON COLUMN public.assets.is_original IS '是否原创（区别于转赠/分发）';
COMMENT ON COLUMN public.assets.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.assets.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.assets.minted_at IS '铸造完成时间，毫秒时间戳';
COMMENT ON COLUMN public.assets.deleted_at IS '软删除时间，NULL 表示未删除';
COMMENT ON COLUMN public.assets.is_active IS '是否活跃（false=逻辑删除）';
COMMENT ON COLUMN public.assets.material_type IS '素材类型：fan_made（粉丝自制）| laser_card（镭射卡）| lenticular（光栅卡）等';

-- =============================================================================
-- 12. booth_slots（展台/摊位槽位）
-- =============================================================================
COMMENT ON TABLE public.booth_slots IS '展台槽位表。定义每个用户在展览馆中的展示位，与 fan_profiles 的 slot_limit 配合控制上限。';
COMMENT ON COLUMN public.booth_slots.slot_id IS '主键，自增';
COMMENT ON COLUMN public.booth_slots.host_profile_id IS 'FK -> fan_profiles.id，槽位所属的粉丝资料';
COMMENT ON COLUMN public.booth_slots.user_id IS '槽位所有者用户 ID';
COMMENT ON COLUMN public.booth_slots.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.booth_slots.slot_index IS '槽位序号（1-3 等）';
COMMENT ON COLUMN public.booth_slots.visibility IS '可见性：public | private | friend_only';
COMMENT ON COLUMN public.booth_slots.is_enabled IS '是否启用槽位';
COMMENT ON COLUMN public.booth_slots.unlock_type IS '解锁条件类型：default | level | mint_count | crystal';
COMMENT ON COLUMN public.booth_slots.unlock_value IS '解锁所需阈值';
COMMENT ON COLUMN public.booth_slots.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.booth_slots.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 13. collection_assets（收藏品/合集资产）
-- =============================================================================
COMMENT ON TABLE public.collection_assets IS '收藏品/合集资产表。区别于铸造的个人藏品，用于官方活动/主题合集中的资产记录。';
COMMENT ON COLUMN public.collection_assets.id IS '主键，自增';
COMMENT ON COLUMN public.collection_assets.asset_id IS 'FK -> assets.id';
COMMENT ON COLUMN public.collection_assets.owner_uid IS '所有者用户 ID';
COMMENT ON COLUMN public.collection_assets.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.collection_assets.name IS '收藏品名称';
COMMENT ON COLUMN public.collection_assets.cover_url IS '封面图 OSS URL';
COMMENT ON COLUMN public.collection_assets.category IS '收藏品分类';
COMMENT ON COLUMN public.collection_assets.like_count IS '点赞数';
COMMENT ON COLUMN public.collection_assets.status IS '状态：0=正常 | 1=隐藏';
COMMENT ON COLUMN public.collection_assets.metadata IS '扩展元数据 JSON';
COMMENT ON COLUMN public.collection_assets.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.collection_assets.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 14. exhibition_revenue_records（展览收益记录）
-- =============================================================================
COMMENT ON TABLE public.exhibition_revenue_records IS '展览收益记录表。用户在展览馆挂出藏品被点赞后按周期结算水晶收益。';
COMMENT ON COLUMN public.exhibition_revenue_records.id IS '主键，自增';
COMMENT ON COLUMN public.exhibition_revenue_records.user_id IS '收益收取人用户 ID（点赞者）';
COMMENT ON COLUMN public.exhibition_revenue_records.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.exhibition_revenue_records.exhibition_id IS 'FK -> exhibitions.id';
COMMENT ON COLUMN public.exhibition_revenue_records.asset_id IS '被点赞的资产 ID';
COMMENT ON COLUMN public.exhibition_revenue_records.slot_id IS 'FK -> booth_slots.slot_id，展位槽位';
COMMENT ON COLUMN public.exhibition_revenue_records.slot_owner_uid IS '槽位拥有者用户 ID（藏品挂出人）';
COMMENT ON COLUMN public.exhibition_revenue_records.slot_type IS '槽位类型/品质';
COMMENT ON COLUMN public.exhibition_revenue_records.crystal_amount IS '结算水晶金额';
COMMENT ON COLUMN public.exhibition_revenue_records.cycle_start_time IS '结算周期开始时间';
COMMENT ON COLUMN public.exhibition_revenue_records.cycle_end_time IS '结算周期结束时间';
COMMENT ON COLUMN public.exhibition_revenue_records.status IS '收益状态：claimable | claimed';
COMMENT ON COLUMN public.exhibition_revenue_records.claimed_at IS '领取时间';
COMMENT ON COLUMN public.exhibition_revenue_records.created_at IS '创建时间，毫秒时间戳';

-- =============================================================================
-- 15. exhibitions（展览记录）
-- =============================================================================
COMMENT ON TABLE public.exhibitions IS '展览记录表。藏品挂上展台即产生一条在展记录，撤展时软删除或标记 is_processed。';
COMMENT ON COLUMN public.exhibitions.id IS '主键，自增';
COMMENT ON COLUMN public.exhibitions.asset_id IS 'FK -> assets.id，在展资产';
COMMENT ON COLUMN public.exhibitions.slot_id IS 'FK -> booth_slots.slot_id，占用槽位';
COMMENT ON COLUMN public.exhibitions.host_profile_id IS 'FK -> fan_profiles.id，展台主人资料';
COMMENT ON COLUMN public.exhibitions.occupier_uid IS '当前占用者用户 ID（通常与 owner_uid 相同）';
COMMENT ON COLUMN public.exhibitions.occupier_star_id IS '占用者所在星球 ID';
COMMENT ON COLUMN public.exhibitions.start_time IS '挂展开始时间';
COMMENT ON COLUMN public.exhibitions.expire_at IS '挂展过期时间';
COMMENT ON COLUMN public.exhibitions.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.exhibitions.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.exhibitions.deleted_at IS '软删除时间（撤展），NULL 表示在展';
COMMENT ON COLUMN public.exhibitions.is_processed IS '收益是否已结算（结算后不再重复处理）';

-- =============================================================================
-- 16. fan_profiles（粉丝档案）
-- =============================================================================
COMMENT ON TABLE public.fan_profiles IS '粉丝档案表。记录用户在各明星/星球下的身份数据，等价于「星球主页」。一次注册可拥有多个 profile。';
COMMENT ON COLUMN public.fan_profiles.id IS '主键，自增';
COMMENT ON COLUMN public.fan_profiles.user_id IS 'FK -> users.id，所属用户';
COMMENT ON COLUMN public.fan_profiles.star_id IS 'FK -> stars.star_id，所属明星/星球';
COMMENT ON COLUMN public.fan_profiles.nickname IS '在该星球下的昵称';
COMMENT ON COLUMN public.fan_profiles.level IS '粉丝等级（1-N）';
COMMENT ON COLUMN public.fan_profiles.times IS '代数（换代数/重置次数）';
COMMENT ON COLUMN public.fan_profiles.social IS '社交值';
COMMENT ON COLUMN public.fan_profiles.coin_balance IS '金币余额';
COMMENT ON COLUMN public.fan_profiles.crystal_balance IS '水晶余额（核心消费货币）';
COMMENT ON COLUMN public.fan_profiles.tags IS '标签 JSON 数组，如 ["collector", "creator"]';
COMMENT ON COLUMN public.fan_profiles.avatar_url IS '头像 OSS URL';
COMMENT ON COLUMN public.fan_profiles.starbook_limit IS '星书限制数，默认 3';
COMMENT ON COLUMN public.fan_profiles.slot_limit IS '展台槽位限制数，默认 3';
COMMENT ON COLUMN public.fan_profiles.assets_count IS '持有藏品总数';
COMMENT ON COLUMN public.fan_profiles.like_bet_count IS '今日剩余点赞数（每日刷新）';
COMMENT ON COLUMN public.fan_profiles.chain_address IS '关联的链上钱包地址';
COMMENT ON COLUMN public.fan_profiles.is_active IS '是否活跃';
COMMENT ON COLUMN public.fan_profiles.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.fan_profiles.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.fan_profiles.revenue_boost_bps IS '收益加成系数（BPS 基点），100=+1%';

-- =============================================================================
-- 17. friend_requests（好友申请）
-- =============================================================================
COMMENT ON TABLE public.friend_requests IS '好友申请表。用户向其他用户发起的交友请求，支持 pending/accepted/rejected/expired 状态流转。';
COMMENT ON COLUMN public.friend_requests.id IS '主键，自增';
COMMENT ON COLUMN public.friend_requests.from_user_id IS '发起方用户 ID';
COMMENT ON COLUMN public.friend_requests.to_user_id IS '接收方用户 ID';
COMMENT ON COLUMN public.friend_requests.star_id IS '所属明星/星球 ID（同星球交友）';
COMMENT ON COLUMN public.friend_requests.message IS '申请留言';
COMMENT ON COLUMN public.friend_requests.status IS '申请状态：pending | accepted | rejected | expired';
COMMENT ON COLUMN public.friend_requests.created_at IS '申请时间，毫秒时间戳';
COMMENT ON COLUMN public.friend_requests.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.friend_requests.expires_at IS '过期时间';
COMMENT ON COLUMN public.friend_requests.processed_at IS '处理时间（接受/拒绝时记录）';

-- =============================================================================
-- 18. friendships（好友关系）
-- =============================================================================
COMMENT ON TABLE public.friendships IS '好友关系表。建立双向好友关系后产生的记录，配合 intimacy 亲密值系统。';
COMMENT ON COLUMN public.friendships.id IS '主键，自增';
COMMENT ON COLUMN public.friendships.user_id IS '用户 ID（双向记录中的一侧）';
COMMENT ON COLUMN public.friendships.friend_id IS '好友的用户 ID';
COMMENT ON COLUMN public.friendships.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.friendships.status IS '关系状态：accepted | blocked';
COMMENT ON COLUMN public.friendships.remark IS '好友备注';
COMMENT ON COLUMN public.friendships.intimacy IS '亲密值，互动越多越高';
COMMENT ON COLUMN public.friendships.created_at IS '建立时间，毫秒时间戳';
COMMENT ON COLUMN public.friendships.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 19. level_thresholds（等级阈值配置）
-- =============================================================================
COMMENT ON TABLE public.level_thresholds IS '藏品等级升降阈值配置表。定义 N/R/SR/SSR 各级所需的展览时长及点赞数阈值。';
COMMENT ON COLUMN public.level_thresholds.level IS '等级标识：N | R | SR | SSR';
COMMENT ON COLUMN public.level_thresholds.max_exhibition_hours IS '该等级最大展览小时数（超时可升级）';
COMMENT ON COLUMN public.level_thresholds.like_bet_count IS '该等级所需的基础点赞数';
COMMENT ON COLUMN public.level_thresholds.description IS '等级说明文本';

-- =============================================================================
-- 20. materials（素材文件）
-- =============================================================================
COMMENT ON TABLE public.materials IS '素材文件表。记录上传到 OSS 的图片素材，镭射卡铸造时写入 backdrop/source/cutout/main 等多条。';
COMMENT ON COLUMN public.materials.id IS '主键，自增';
COMMENT ON COLUMN public.materials.oss_key IS 'OSS 对象键（纯路径，不含域名）';
COMMENT ON COLUMN public.materials.original_name IS '原始文件名';
COMMENT ON COLUMN public.materials.file_size IS '文件大小（Bytes）';
COMMENT ON COLUMN public.materials.mime_type IS 'MIME 类型，如 image/png';
COMMENT ON COLUMN public.materials.width IS '图片宽度（px）';
COMMENT ON COLUMN public.materials.height IS '图片高度（px）';
COMMENT ON COLUMN public.materials.hash IS '文件哈希（SHA256）';
COMMENT ON COLUMN public.materials.created_by IS '上传人用户 ID';
COMMENT ON COLUMN public.materials.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.materials.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.materials.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.materials.deleted_at IS '软删除时间，NULL 表示未删除';

-- =============================================================================
-- 21. mint_cost_config（铸造费用配置）
-- =============================================================================
COMMENT ON TABLE public.mint_cost_config IS '铸造费用阶梯配置表。第 N 次铸造消耗多少水晶，支持递增/递减，已有的注释不覆盖。';

-- =============================================================================
-- 22. mint_orders（铸造订单）
-- =============================================================================
COMMENT ON TABLE public.mint_orders IS '铸造订单表。用户发起铸造后生成订单，经历 PENDING -> PROCESSING -> SUCCEEDED/FAILED 状态流转。';
COMMENT ON COLUMN public.mint_orders.order_id IS '主键，业务订单号（UUID）';
COMMENT ON COLUMN public.mint_orders.user_id IS '铸造用户 ID';
COMMENT ON COLUMN public.mint_orders.asset_id IS 'FK -> assets.id，铸造成功后的资产 ID';
COMMENT ON COLUMN public.mint_orders.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.mint_orders.status IS '订单状态：PENDING | PROCESSING | SUCCEEDED | FAILED';
COMMENT ON COLUMN public.mint_orders.cost_crystal IS '消耗水晶数';
COMMENT ON COLUMN public.mint_orders.error_message IS '失败原因';
COMMENT ON COLUMN public.mint_orders.retry_count IS '重试次数';
COMMENT ON COLUMN public.mint_orders.material_url IS '铸造时传入的素材 OSS key/URL';
COMMENT ON COLUMN public.mint_orders.name IS '藏品名称';
COMMENT ON COLUMN public.mint_orders.description IS '藏品描述';
COMMENT ON COLUMN public.mint_orders.material_type IS '素材类型标识';
COMMENT ON COLUMN public.mint_orders.event IS '关联事件/活动标识';
COMMENT ON COLUMN public.mint_orders.info IS '扩展信息 JSON 字符串';
COMMENT ON COLUMN public.mint_orders.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.mint_orders.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.mint_orders.minted_at IS '铸造完成时间，毫秒时间戳';

-- =============================================================================
-- 23. minting_activities（铸造活动）
-- =============================================================================
COMMENT ON TABLE public.minting_activities IS '铸造活动配置表。定义限时/主题铸造活动，如「夏日限定镭射卡铸造」。';
COMMENT ON COLUMN public.minting_activities.id IS '主键，自增';
COMMENT ON COLUMN public.minting_activities.title IS '活动标题';
COMMENT ON COLUMN public.minting_activities.description IS '活动描述';
COMMENT ON COLUMN public.minting_activities.cover_image IS '活动封面图 URL';
COMMENT ON COLUMN public.minting_activities.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.minting_activities.route IS '活动页面路由路径';
COMMENT ON COLUMN public.minting_activities.params IS '路由参数 JSON 字符串，与 route 配合使用（前端 uni.navigateTo url 拼接）';
COMMENT ON COLUMN public.minting_activities.is_active IS '是否启用';
COMMENT ON COLUMN public.minting_activities.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.minting_activities.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 24. onboarding_stage_config（新手引导阶段配置）
-- =============================================================================
COMMENT ON TABLE public.onboarding_stage_config IS '新手引导阶段配置表。定义注册后的引导流程分阶段任务与水晶奖励。';
COMMENT ON COLUMN public.onboarding_stage_config.id IS '主键，自增';
COMMENT ON COLUMN public.onboarding_stage_config.stage IS '阶段序号（1/2/3...）';
COMMENT ON COLUMN public.onboarding_stage_config.name IS '阶段名称，如「完善资料」「首次铸造」';
COMMENT ON COLUMN public.onboarding_stage_config.description IS '阶段描述';
COMMENT ON COLUMN public.onboarding_stage_config.required_task_keys IS '完成该阶段需要的任务 key 列表（逗号分隔）';
COMMENT ON COLUMN public.onboarding_stage_config.crystal_reward IS '阶段完成奖励水晶';
COMMENT ON COLUMN public.onboarding_stage_config.sort_order IS '排序';
COMMENT ON COLUMN public.onboarding_stage_config.is_active IS '是否启用';
COMMENT ON COLUMN public.onboarding_stage_config.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.onboarding_stage_config.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 25. season_decay_config（赛季衰减配置）
-- =============================================================================
COMMENT ON TABLE public.season_decay_config IS '赛季衰减配置表。赛季切换时，不同等级资产按比例保留展览时长/点赞数据。';
COMMENT ON COLUMN public.season_decay_config.id IS '主键，自增';
COMMENT ON COLUMN public.season_decay_config.season_id IS 'FK -> seasons.id';
COMMENT ON COLUMN public.season_decay_config.level IS '资产等级：N | R | SR | SSR';
COMMENT ON COLUMN public.season_decay_config.preserve_percent IS '保留百分比（0-100），100 表示全量保留';
COMMENT ON COLUMN public.season_decay_config.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 26. seasons（赛季）
-- =============================================================================
COMMENT ON TABLE public.seasons IS '赛季配置表。定义赛季周期（默认 84 天），赛季结束触发等级衰减重置。';
COMMENT ON COLUMN public.seasons.id IS '主键，赛季 ID';
COMMENT ON COLUMN public.seasons.name IS '赛季名称，如「2026-S1」';
COMMENT ON COLUMN public.seasons.duration_days IS '赛季持续天数，默认 84';
COMMENT ON COLUMN public.seasons.start_time IS '赛季开始时间，毫秒时间戳';
COMMENT ON COLUMN public.seasons.end_time IS '赛季结束时间，毫秒时间戳';
COMMENT ON COLUMN public.seasons.reset_strategy IS '重置策略：percentage_decay（百分比衰减）| full_reset（完全重置）';
COMMENT ON COLUMN public.seasons.reset_level IS '是否重置等级';
COMMENT ON COLUMN public.seasons.status IS '赛季状态：active | frozen | ended';
COMMENT ON COLUMN public.seasons.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.seasons.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 27. stars（明星/星球）
-- =============================================================================
COMMENT ON TABLE public.stars IS '明星/星球表。TopFans 核心实体，每个明星/偶像对应一个星球，用户在不同星球拥有独立身份（fan_profiles）。';
COMMENT ON COLUMN public.stars.star_id IS '主键，自增';
COMMENT ON COLUMN public.stars.name IS '星球/明星名称（中文）';
COMMENT ON COLUMN public.stars.tag IS '标签/别名';
COMMENT ON COLUMN public.stars.name_en IS '星球/明星名称（英文）';
COMMENT ON COLUMN public.stars.pic_url IS '代表图片 URL';
COMMENT ON COLUMN public.stars.description IS '星球描述';
COMMENT ON COLUMN public.stars.identity_id IS '身份标识（业务唯一 key）';
COMMENT ON COLUMN public.stars.is_active IS '是否启用';
COMMENT ON COLUMN public.stars.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.stars.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 28. task_definitions（任务定义）
-- =============================================================================
COMMENT ON TABLE public.task_definitions IS '任务定义表。定义每日/新手/活动任务模板，与 user_daily_task_progress 配合控制完成状态。';
COMMENT ON COLUMN public.task_definitions.id IS '主键，自增';
COMMENT ON COLUMN public.task_definitions.star_id IS '所属明星/星球 ID，空=全站通用';
COMMENT ON COLUMN public.task_definitions.task_key IS '任务唯一 key，如 daily_like_bet';
COMMENT ON COLUMN public.task_definitions.task_type IS '任务类型：daily | onboarding | activity';
COMMENT ON COLUMN public.task_definitions.name IS '任务名称';
COMMENT ON COLUMN public.task_definitions.description IS '任务描述';
COMMENT ON COLUMN public.task_definitions.crystal_reward IS '完成奖励水晶';
COMMENT ON COLUMN public.task_definitions.sort_order IS '排序';
COMMENT ON COLUMN public.task_definitions.is_active IS '是否启用';
COMMENT ON COLUMN public.task_definitions.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.task_definitions.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 29. task_reset_log（任务重置日志）
-- =============================================================================
COMMENT ON TABLE public.task_reset_log IS '任务重置日志表。记录每日/每周任务重置操作，防止重复重置。';
COMMENT ON COLUMN public.task_reset_log.id IS '主键，自增';
COMMENT ON COLUMN public.task_reset_log.reset_type IS '重置类型：daily | weekly | onboarding';
COMMENT ON COLUMN public.task_reset_log.last_reset_at IS '上次重置时间';
COMMENT ON COLUMN public.task_reset_log.created_at IS '创建时间，毫秒时间戳';

-- =============================================================================
-- 30. user_daily_task_progress（用户每日任务进度）
-- =============================================================================
COMMENT ON TABLE public.user_daily_task_progress IS '用户每日任务进度表。记录每个用户每天的各任务完成与领取状态。';
COMMENT ON COLUMN public.user_daily_task_progress.id IS '主键，自增';
COMMENT ON COLUMN public.user_daily_task_progress.user_id IS '用户 ID';
COMMENT ON COLUMN public.user_daily_task_progress.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.user_daily_task_progress.task_key IS '任务 key，对应 task_definitions.task_key';
COMMENT ON COLUMN public.user_daily_task_progress.status IS '任务状态：pending | completed | claimed';
COMMENT ON COLUMN public.user_daily_task_progress.completed_at IS '完成时间';
COMMENT ON COLUMN public.user_daily_task_progress.claimed_at IS '领取时间';
COMMENT ON COLUMN public.user_daily_task_progress.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.user_daily_task_progress.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 31. user_mint_count（用户铸造计数）
-- =============================================================================
COMMENT ON TABLE public.user_mint_count IS '用户铸造计数表。记录用户在各星球下的累计铸造次数（用于阶梯定价），已有的注释不覆盖。';

-- =============================================================================
-- 32. user_onboarding_progress（用户新手引导进度）
-- =============================================================================
COMMENT ON TABLE public.user_onboarding_progress IS '用户新手引导进度表。记录每个用户的新手任务完成状态。';
COMMENT ON COLUMN public.user_onboarding_progress.id IS '主键，自增';
COMMENT ON COLUMN public.user_onboarding_progress.user_id IS '用户 ID';
COMMENT ON COLUMN public.user_onboarding_progress.task_key IS '新手任务 key';
COMMENT ON COLUMN public.user_onboarding_progress.status IS '任务状态：pending | completed | claimed';
COMMENT ON COLUMN public.user_onboarding_progress.completed_at IS '完成时间';
COMMENT ON COLUMN public.user_onboarding_progress.claimed_at IS '奖励领取时间';
COMMENT ON COLUMN public.user_onboarding_progress.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.user_onboarding_progress.updated_at IS '更新时间，毫秒时间戳';

-- =============================================================================
-- 33. user_onboarding_status（用户新手引导整体状态）
-- =============================================================================
COMMENT ON TABLE public.user_onboarding_status IS '用户新手引导整体状态表。维护引导完成度、阶段奖励领取、首次登录奖励等汇总信息。';
COMMENT ON COLUMN public.user_onboarding_status.id IS '主键，自增';
COMMENT ON COLUMN public.user_onboarding_status.user_id IS '用户 ID';
COMMENT ON COLUMN public.user_onboarding_status.star_id IS '所属明星/星球 ID';
COMMENT ON COLUMN public.user_onboarding_status.is_onboarding_completed IS '是否完成全部引导';
COMMENT ON COLUMN public.user_onboarding_status.is_onboarding_claimed IS '是否已领取最终奖励';
COMMENT ON COLUMN public.user_onboarding_status.has_friend_display_bonus IS '是否有好友展示加成';
COMMENT ON COLUMN public.user_onboarding_status.onboarding_completed_at IS '引导完成时间';
COMMENT ON COLUMN public.user_onboarding_status.onboarding_claimed_at IS '最终奖励领取时间';
COMMENT ON COLUMN public.user_onboarding_status.claimed_stages IS '已领取的阶段列表（逗号分隔）';
COMMENT ON COLUMN public.user_onboarding_status.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.user_onboarding_status.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.user_onboarding_status.current_stage IS '当前引导阶段';
COMMENT ON COLUMN public.user_onboarding_status.status IS '整体状态：pending | in_progress | completed';
COMMENT ON COLUMN public.user_onboarding_status.is_first_login_bonus_claimed IS '是否已领取首次登录奖励';
COMMENT ON COLUMN public.user_onboarding_status.completed_at IS '完成时间，毫秒时间戳';
COMMENT ON COLUMN public.user_onboarding_status.claimed_at IS '奖励领取时间，毫秒时间戳';

-- =============================================================================
-- 34. users（用户主表）
-- =============================================================================
COMMENT ON TABLE public.users IS '用户主表。TopFans 核心用户身份表，记录登录凭证与基础信息，各星球详细数据见 fan_profiles。';
COMMENT ON COLUMN public.users.id IS '主键，自增';
COMMENT ON COLUMN public.users.mobile IS '手机号（登录用）';
COMMENT ON COLUMN public.users.password_hash IS '密码哈希';
COMMENT ON COLUMN public.users.access_token IS 'JWT 访问令牌';
COMMENT ON COLUMN public.users.token_expires_at IS '令牌过期时间，毫秒时间戳';
COMMENT ON COLUMN public.users.avatar_url IS '全局头像 URL';
COMMENT ON COLUMN public.users.global_wallet_address IS 'Web3 全局钱包地址';
COMMENT ON COLUMN public.users.is_active IS '是否激活';
COMMENT ON COLUMN public.users.created_at IS '创建时间，毫秒时间戳';
COMMENT ON COLUMN public.users.updated_at IS '更新时间，毫秒时间戳';
COMMENT ON COLUMN public.users.deleted_at IS '软删除时间，NULL 表示未删除';

COMMIT;
