xuqinmin12/lawless
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
main
lawless/docs/技术文档/TDD-04-数据库表结构设计.md

61 KiB
原始文件 永久链接 Blame 文件历史

TDD-04 数据库表结构设计

文档类型：技术设计文档（Technical Design Document） 版本：1.2 日期：2026-07-02 关联文档：TDD-00 技术栈与架构、GDD-00~GDD-21 相关系统设计

1. 文档信息

项目 说明
目标 为挂机手游《洪荒大陆》服务端定义 PostgreSQL 16 数据库表结构，覆盖角色、种族、境界、功法技能、物品经济、市场拍卖、组织、弟子、悬赏、地图副本、战斗、渡劫、社交、配置与审计等模块。
读者 服务端开发、数值策划、运维、测试
数据库 PostgreSQL 16（主库），pg_partman 分区扩展
缓存/外部 Valkey（玩家在线热数据）、Nakama（账户/社交/匹配）、Nacos（动态配置）
命名约定 小写下划线；表名复数；主键 uuid；字段用 small_snake_case；布尔用 is_/has_ 前缀；金额用 numeric(20,4)；JSONB 用于随机/引擎生成/战报/动态配置数据。

2. 数据库选型

  • PostgreSQL 16：支持 jsonb、range、partition、BRIN、GIN 索引，满足功法/技能/战报等半结构化数据存储。
  • pg_partman：用于 battle_logs、market_orders、economy_audit_logs 等按时间分区的大表。
  • Valkey：承载在线角色快照、排行榜、会话；DB 作为持久化事实源。
  • Nacos：存储热更数值参数，服务端通过配置中心读取，DB 仅保留历史快照与灰度记录。

3. 设计原则与约定

原则 说明
事实源单一 角色、经济、组织、关系等以 PostgreSQL 为唯一事实源；Valkey/Nakama 为缓存/投影。
境界/世界层级隔离 排行榜、市场、PVP 匹配统一按 realm_tier + minor_realm（或 world_tier）隔离。
JSONB 用于随机/引擎数据 功法实例、技能实例、装备随机词条、建筑等级、战报、地图组件配置等用 JSONB，避免表爆炸。
经济审计 所有货币产出/消耗写入 economy_audit_logs，按 faucet/sink 分类，支持实时通胀监控。
软删除/状态机 角色、组织、市场订单、悬赏等用 status 字段驱动生命周期，避免物理删除。
时间统一 数据库使用 timestamptz 存现实时间；游戏内时间 = 现实时间 × 3，由应用层计算。每日重置锚点 08:00（现实时间）。

4. ER 概览

players ──1:N── characters ──1:1── character_race_states
                     │
                     ├── N:M ── currency_balances
                     ├── N:M ── inventories / equipments
                     ├── N:M ── character_manuals / character_skills
                     ├── 1:N ── battles / battle_logs / tribulation_records / economy_audit_logs
                     ├── 1:N ── market_orders / auctions / intelligence_orders
                     ├── 1:N ── social_relations / lovers / sworn_brothers
                     ├── N:M ── guild_members (guilds)
                     │
guilds ──1:N── guild_territories / guild_diplomacy / guild_warehouses / disciples

world_layers ──1:N── maps ──1:N── regions ──1:N── zones ──1:N── zone_explorations / instances
instances ──1:N── instance_runs ──1:N── instance_loot

contracts ──1:1── bounties (when contract_type='bounty')
contracts ──1:N── contract_participants
bounties ──1:0..1── manhunt_records

5. 核心数据表设计

5.0 表名速查（按需求清单）

需求表名 本文表名 说明
players / characters players / characters 玩家账号与角色
character_race_states character_race_states 角色种族状态
realms / character_realms realms / character_realms 境界静态配置与角色境界进度
manuals / character_manuals manuals / character_manuals 功法模板与角色功法实例
skills / character_skills skills / character_skills 技能模板与角色技能实例
items / inventories / equipments items / inventories / equipments 物品模板、背包、装备槽
currencies / currency_balances currencies / currency_balances 货币定义与角色钱包
market_orders / auctions / auction_bids market_orders / auctions / auction_bids 交易行与拍卖
guilds / guild_members / guild_territories guilds / guild_members / guild_territories 四组织（门派/帮派/家族/玩家宗门）统一表
disciples / disciple_missions disciples / disciple_missions NPC 弟子与代派委托
bounties / contracts bounties / contracts 悬赏追杀与佣兵委托
maps / zones / instances maps / zones / instances 世界地图、区域、副本入口
battles / battle_logs battles / battle_logs 战斗头与战报日志
tribulation_records tribulation_records 渡劫记录
social_relations / lovers / sworn_brothers social_relations / lovers / sworn_brothers 社交关系链
intelligence_orders intelligence_orders 天机阁情报订单

5.1 账号与角色

players

字段 类型 约束 说明
id uuid PK 玩家账户唯一 ID
nakama_user_id uuid UQ Nakama 账户映射
platform varchar(32) ios / android / pc / guest
device_id_hash varchar(128) UQ, nullable 设备指纹哈希
status varchar(16) active / banned / deleted
created_at timestamptz 创建时间
updated_at timestamptz 更新时间

characters

字段 类型 约束 说明
id uuid PK 角色唯一 ID
player_id uuid FK → players.id, IX 所属玩家
name varchar(64) UQ 角色名
race_id varchar(32) IX 当前种族（见 GDD-01）
birth_race_id varchar(32) 创建时种族
birth_world_tier smallint 出生地世界层级（1~6）
world_tier smallint IX 当前世界层级（1~6，对应 GDD-18 六级世界）
realm_tier smallint IX 当前大境界（1~6，炼气~合体）
minor_realm smallint IX 小境界（1~3：初期/中期/圆满）
realm_status varchar(16) normal / tribulation_pending / breakthrough_ready
level int 细分等级/经验槽，用于境界内成长
exp bigint 当前经验/修为
status varchar(16) IX active / dead / sealed / deleted
base_stats jsonb {力,体,悟,速,灵,命,血} 基础值
battle_stats jsonb 战斗属性快照（ATB 用）
san_current smallint 当前 SAN（0~100）
san_max smallint SAN 上限
crime_score int IX 罪孽值
heavenly_value int 天道值
karma_value int 业力/戾气值（追杀令来源）
reputation_score int 声望口碑（GDD-16）
mercenary_score int 佣兵信用分（GDD-13）
hunter_prestige int 猎人威望（GDD-14）
last_online_at timestamptz IX 最后在线时间
daily_reset_at timestamptz 个人每日 08:00 重置标记
created_at timestamptz 创建时间
updated_at timestamptz 更新时间

注意：world_tier 与 realm_tier 在常规流程下对齐（1=炼气/出生地，2=筑基/洪荒主陆…6=合体/混沌之渊深层），但存在“跨界降临”“遗迹投影”等临时状态，两者必须独立存储。

5.2 种族与境界状态

character_race_states

字段 类型 约束 说明
character_id uuid PK, FK → characters.id
main_race_id varchar(32) 当前主种族
sub_branch_id varchar(32) 分支/进化支（如深潜裔分支、妖族血脉分支）
bloodline_data jsonb {血脉浓度,觉醒度,残响技能,祖地归属,进化路径}
is_rare_race boolean 是否稀有种族（龙族/混沌裔/巨人族/堕天使裔）
rebirth_count smallint 转生次数
conversion_cooldown_until timestamptz 下次可转化/转生时间
race_talents jsonb 已激活种族天赋实例
hidden_talents jsonb 隐藏天赋（GDD-10）
updated_at timestamptz

race_currency_wallets

稀有种族/特殊资源专用钱包（GDD-01 种族专属货币）。

字段 类型 约束 说明
character_id uuid PK, FK
race_currency_code varchar(32) PK 如 dragon_blood_token、chaos_essence
amount numeric(20,4) 余额
total_earned numeric(20,4) 累计获取（防通胀监控）
updated_at timestamptz

realms

境界静态配置表。

字段 类型 约束 说明
tier smallint PK 大境界 1~6
minor_realm_max smallint 小境界数量（3）
name varchar(64) 炼气/筑基/金丹/元婴/化神/合体
world_tier smallint 对应世界层级
main_currency_code varchar(32) 该境界主货币
is_tribulation_required boolean 是否需要渡劫突破
base_success_rate numeric(5,4) 渡劫基础成功率
attr_growth_template jsonb 每小境界属性成长模板

character_realms

角色每个大境界的进度与属性快照。

字段 类型 约束 说明
id uuid PK
character_id uuid FK, IX
realm_tier smallint 大境界
max_minor_reached smallint 达到的最高小境界
exp_in_tier bigint 当前境界累积修为
stats_snapshot jsonb 突破该境界时的属性快照
is_current boolean IX 是否为当前境界
updated_at timestamptz

realm_breakthrough_records

字段 类型 约束 说明
id uuid PK
character_id uuid FK, IX
from_realm_tier smallint
to_realm_tier smallint
from_minor_realm smallint
to_minor_realm smallint
is_success boolean 是否突破成功
is_break_world_barrier boolean 是否破界（晋级新世界）
source_world_tier smallint
target_world_tier smallint
created_at timestamptz IX

5.3 功法、心法与技能实例

manuals

功法/心法模板（静态配置，由策划/Nacos 维护）。

字段 类型 约束 说明
id varchar(64) PK 功法模板 ID
name varchar(128) 功法名
category varchar(32) universal / profession / racial / unique
domain varchar(32) 剑/体/法/丹/器/阵/神识/血/时/儒/释/道/种族
element varchar(16) 火/水/雷/土/木/阴/阳/混沌/none
alignment varchar(16) light / dark / neutral
max_layers smallint 最大层数
required_race varchar(32)[] 可学习种族白名单
required_profession varchar(32)[] 职业要求
base_attr jsonb 每级属性成长模板
skill_unlock_layers jsonb [{layer, skill_template_id, probability}]
version int 配置版本

character_manuals

字段 类型 约束 说明
id uuid PK 实例 ID
character_id uuid FK, IX
manual_id varchar(64) FK → manuals.id
instance_data jsonb {当前层数,熟练度,突破记录,随机属性,隐患状态}
is_buffing boolean IX 是否设为加持功法
buff_data jsonb 加持熟练度/顿悟状态/位阶
source_tag varchar(32) ORIGINAL / JADE_SLIP / DISCIPLE / NPC / EVENT
can_copy_to_jade_slip boolean 是否可拓印为玉简
copy_count_left smallint 剩余可拓印次数（超稀有/唯一限制）
created_at timestamptz
updated_at timestamptz

skills

技能模板/机制库（GDD-17）。

字段 类型 约束 说明
id varchar(64) PK 技能模板/机制 ID
name varchar(128) 显示名
category varchar(32) universal / profession / racial / unique
domain varchar(32)
archetype varchar(32) 强攻/连击/蓄力/范围/控制/DOT/护盾/治疗/…
element varchar(16)
alignment varchar(16)
damage_type varchar(16) physical / magical / true
scaling_attr varchar(8) 力/体/悟/速/灵/命/血
is_eldritch boolean 是否克苏鲁/邪术
san_cost smallint
san_gate jsonb {min, max} 低 SAN 解锁
san_scaling numeric(6,4) SAN 缩放系数
requirements jsonb {境界,属性,种族,职业,SAN 区间}
continuous_cost jsonb 持续代价（掉血/掉蓝/掉 SAN/掉产出）
flow varchar(32) transcript_jade_ok / no_transcript / unique_only
base_template jsonb ATB 参数/CD/消耗/目标/特效白名单
version int

character_skills

字段 类型 约束 说明
id uuid PK 技能实例 ID
character_id uuid FK, IX
skill_id varchar(64) FK → skills.id
custom_name varchar(128) 玩家自定义名（天品+/唯一）
instance_data jsonb {base_coef, cd, cost, target, effects, enchants, rarity, record}
source_tag varchar(32) ORIGINAL / JADE_SLIP / DISCIPLE / NPC / EVENT / TEACHING
proficiency int 熟练度
is_unique boolean IX 是否全服唯一技能
unique_holder_until timestamptz 唯一技能失传判定时间
lineage jsonb 师徒/亲密关系传授谱系（防无限复制）
created_at timestamptz
updated_at timestamptz

说明：instance_data 保存程序化生成结果（GDD-17 附.7 Skill Schema）。唯一技能全服单例通过 is_unique=true + 全局持有者校验实现。

5.4 物品、装备与经济

items

物品模板（静态配置）。

字段 类型 约束 说明
id varchar(64) PK 物品模板 ID
name varchar(128) 物品名
category varchar(32) 材料/丹药/符箓/装备/玉简/消耗品/任务道具/稀有宝物
sub_category varchar(32) 血脉碎片 / 传承功法 / 法宝 / 本命法器 / armor / weapon
stackable boolean 是否可堆叠
max_stack int 最大堆叠数
bind_type varchar(16) none / on_pickup / on_equip / account
world_tier smallint 适用世界层级
base_attr_template jsonb 基础属性模板
random_affix_pool jsonb 随机词条池
script_id varchar(64) 使用脚本/效果 ID
version int

inventories

字段 类型 约束 说明
id uuid PK
character_id uuid FK, IX
item_id varchar(64) FK → items.id
slot_type varchar(16) bag / warehouse / mail / auction_escrow
quantity int 数量（堆叠物）
instance_data jsonb 随机词条、强化等级、绑定状态、耐久、赃物/血债印标记
is_stolen boolean 赃物标记（GDD-14）
blood_debt_mark boolean 血债印标记
can_trade boolean 是否可交易
acquired_at timestamptz 获得时间
created_at timestamptz

equipments

字段 类型 约束 说明
character_id uuid PK, FK
slot_name varchar(32) PK weapon / head / body / hand / foot / accessory1 / accessory2 / life_item
inventory_id uuid FK → inventories.id, nullable 当前装备
updated_at timestamptz

currencies

货币定义（静态）。

字段 类型 约束 说明
code varchar(32) PK 货币代码
name varchar(64) 货币名
world_tier smallint 适用世界层级
is_premium boolean 是否充值货币（如鸿蒙紫气）
exchange_rules jsonb 兑换/税率规则

currency_balances

角色钱包。

字段 类型 约束 说明
character_id uuid PK, FK
currency_code varchar(32) PK, FK → currencies.code 铜钱/银两/下品灵石/中品灵石/魂晶/魔晶/仙晶/鸿蒙紫气 等
amount numeric(20,4) 余额
total_earned numeric(20,4) 累计获取
total_spent numeric(20,4) 累计消耗
updated_at timestamptz

注意：按 GDD-06，层 1~2 主货币为铜钱/银两，层 3 为灵石，层 4+ 为各阵营结晶货币。

economy_audit_logs

经济水龙头/下水道审计。

字段 类型 约束 说明
id bigint PK 自增/雪花
character_id uuid FK, IX 可为系统/组织
entity_type varchar(16) IX character / guild / system
entity_id uuid IX
currency_code varchar(32) IX
flow_type varchar(16) IX faucet / sink / transfer
reason_code varchar(64) IX 枚举：combat_drop / gathering / auction_tax / market_fee / death_penalty / insurance / tribulation / disciple_mission / instance_reward / admin_compensation 等
amount numeric(20,4) 正数=产出/转入，负数=消耗/转出
balance_after numeric(20,4) 操作后余额
related_id uuid nullable 关联订单/战斗/副本 ID
world_tier smallint IX 发生层级
created_at timestamptz IX

分区：按 created_at 月分区，保留 12 个月。

5.5 市场、拍卖与天机阁情报

market_orders

交易行挂单（GDD-06）。

字段 类型 约束 说明
id uuid PK
seller_id uuid FK → characters.id, IX
seller_guild_id uuid FK → guilds.id, nullable 势力/帮派代售
item_id varchar(64) IX
inventory_id uuid FK → inventories.id 托管物品
currency_code varchar(32) IX 结算货币
unit_price numeric(20,4) 单价
quantity int 数量
total_price numeric(20,4) 总价
tax_rate numeric(5,4) 交易税率
status varchar(16) IX active / sold / cancelled / expired
listed_at timestamptz IX
expired_at timestamptz
sold_at timestamptz
buyer_id uuid FK → characters.id, nullable

分区：按 listed_at 月分区，保留 6 个月。

auctions

拍卖（GDD-14）。

字段 类型 约束 说明
id uuid PK
seller_id uuid FK → characters.id, IX
guild_id uuid FK → guilds.id, nullable 势力拍卖归属
auction_type varchar(16) IX official / organization
item_id varchar(64)
inventory_id uuid FK → inventories.id 托管拍品
category varchar(32) IX rare_bloodline / rare_manual / jade_slip / secret_material / artifact / material
currency_code varchar(32)
start_price numeric(20,4) 起拍价
reserve_price numeric(20,4) 底价
min_increment_rate numeric(5,4) 最小加价比例
deposit_rate numeric(5,4) 保证金比例
tax_rate numeric(5,4) 税率
status varchar(16) IX preparing / active / extended / sold / expired / robbed
started_at timestamptz IX
ended_at timestamptz
is_anonymous boolean 卖家匿名
access_type varchar(16) public / private
risk_type varchar(16) 抢劫风险类型：rare_robbable / none
created_at timestamptz

auction_bids

字段 类型 约束 说明
id uuid PK
auction_id uuid FK → auctions.id, IX
bidder_id uuid FK → characters.id, IX
amount numeric(20,4) 出价
deposit_paid numeric(20,4) 已缴保证金
is_auto_bid boolean 是否自动出价
auto_max_amount numeric(20,4) 自动出价上限
bid_at timestamptz IX

分区：与 auctions 对齐，按 bid_at 月分区。

auction_blacklist_records

势力拍卖黑吃黑记录（GDD-14 §10）。

字段 类型 约束 说明
id uuid PK
guild_id uuid FK → guilds.id, IX
auction_id uuid FK → auctions.id
is_exposed boolean 是否东窗事发
exposed_at timestamptz
exposure_type varchar(16) report / arbitration / heaven_sense
punishment_level smallint 1/2/3
reputation_delta int
created_at timestamptz

intelligence_orders

天机阁情报订单（GDD-06 第十二章）。

字段 类型 约束 说明
id uuid PK
seller_id uuid FK → characters.id, IX
buyer_id uuid FK → characters.id, nullable, IX
intel_type varchar(32) IX resource / event / location / bounty_clue / instance_entry / unique_skill_clue
target_id uuid nullable 情报目标（玩家/区域/副本）
target_world_tier smallint IX
content_summary varchar(256) 摘要
detail_data jsonb 精确/模糊信息、坐标、概率
currency_code varchar(32)
price numeric(20,4)
purchase_count smallint 已被购买次数（防膨胀）
max_purchase smallint 同一份线索最多购买次数
status varchar(16) IX active / sold_out / expired
cooldown_until timestamptz 卖家冷却
created_at timestamptz IX

5.6 组织（门派/帮派/家族/玩家宗门）

guilds

四组织统一表（GDD-07 / GDD-16）。表名 guilds 为通用组织实体，不特指帮派。

字段 类型 约束 说明
id uuid PK
name varchar(128) UQ 势力名
org_type varchar(16) IX system_sect / player_sect / guild / family
world_tier smallint IX 所在世界层级
region_id uuid FK → regions.id, nullable 驻地所在地域
zone_id uuid FK → zones.id, nullable 驻地所在区域
leader_id uuid FK → characters.id 领主/掌门/族长
level smallint 组织等级
reputation int 势力声望/声誉
member_limit int 成员上限
tax_rate numeric(5,4) 势力拍卖/坊市税率（势力拍卖用）
diplomacy_policy jsonb 结盟/宣战/贸易协定状态
building_levels jsonb 各建筑等级与升级进度
funds jsonb 各币种组织资金
status varchar(16) IX active / dissolved / blacklisted
created_at timestamptz
dissolved_at timestamptz

guild_members

字段 类型 约束 说明
guild_id uuid PK, FK
character_id uuid PK, FK
role varchar(32) leader / vice / elder / elder_council / member / disciple_manager
joined_at timestamptz
contribution jsonb 各贡献值
daily_quota jsonb 今日代挂/委托时长配额
updated_at timestamptz

guild_territories

字段 类型 约束 说明
id uuid PK
guild_id uuid FK, IX
territory_type varchar(32) 炼丹房/炼器室/藏经阁/练功房/坊市/拍卖行/祖地祭坛/领地核心
level smallint
upgrade_progress jsonb 升级材料/进度
params jsonb 建筑产出参数
updated_at timestamptz

guild_diplomacy

字段 类型 约束 说明
id uuid PK
guild_a_id uuid FK → guilds.id, IX
guild_b_id uuid FK → guilds.id, IX
relation varchar(16) IX allied / at_war / trade / betrayed_cooldown
started_at timestamptz
ended_at timestamptz nullable

guild_warehouses

字段 类型 约束 说明
id uuid PK
guild_id uuid FK, IX
inventory_id uuid FK → inventories.id 物品实例
deposited_by uuid FK → characters.id
deposit_type varchar(16) common / tribute / black_eat
created_at timestamptz

5.7 弟子系统

disciples

NPC 弟子（GDD-07），与玩家师徒关系（GDD-16）区分。

字段 类型 约束 说明
id uuid PK
owner_id uuid FK → characters.id, IX 所属玩家
guild_id uuid FK → guilds.id, nullable 所属门派/帮派
name varchar(64) 弟子名
race_id varchar(32) 种族
quality varchar(16) common / fine / excellent / perfect / immortal
profession varchar(32) 职业/心法道倾向
stats jsonb 基础战斗属性
skills jsonb 已学技能实例
equipment jsonb 装备快照
daily_task_quota_min int 今日剩余代挂分钟数
death_rate_modifier numeric(5,4) 死亡率修正
status varchar(16) IX active / dead / dispatched / insurance_pending
tombstone_data jsonb 死亡后墓碑信息
created_at timestamptz
died_at timestamptz

disciple_missions

弟子代派任务/委托记录。

字段 类型 约束 说明
id uuid PK
disciple_id uuid FK → disciples.id, IX
owner_id uuid FK → characters.id, IX
contract_id uuid FK → contracts.id, nullable 关联悬赏/委托
mission_type varchar(16) mercenary / gathering / sect_proxy
difficulty smallint 1~6 星
success_rate numeric(5,4) 计算后成功率
death_rate numeric(5,4) 计算后死亡率
insurance_item_id uuid FK → inventories.id, nullable 保险道具
result varchar(16) pending / success / fail / death
rewards jsonb 奖励快照
started_at timestamptz
ended_at timestamptz

5.8 悬赏、追杀令与佣兵委托

contracts

佣兵委托与悬赏的公共头表。

字段 类型 约束 说明
id uuid PK
contract_type varchar(16) IX mercenary /限时委托 / bounty
publisher_id uuid FK → characters.id, IX 发布者
publisher_guild_id uuid FK → guilds.id, nullable 帮派集体发布
difficulty smallint 1~6 星
currency_code varchar(32) 报酬货币
base_reward numeric(20,4) 基础报酬
max_participants smallint 最大接取人数
status varchar(16) IX active / accepted / completed / failed / expired / cancelled
valid_until timestamptz IX 有效期
created_at timestamptz IX
completed_at timestamptz

bounties

悬赏与追杀令扩展表（对应 GDD-02 / GDD-13 / GDD-14）。

字段 类型 约束 说明
contract_id uuid PK, FK → contracts.id
bounty_type varchar(16) IX official_bounty / private_bounty /追杀令
target_id uuid FK → characters.id, nullable, IX 目标玩家
target_world_tier smallint IX 目标所在层级
reward_amount numeric(20,4) 悬赏金
fee_amount numeric(20,4) 手续费/报案费
is_anonymous boolean 私人悬赏匿名
report_count_today smallint 报官今日计数
trigger_probability numeric(5,4) 报官触发概率
clues jsonb 线索数据
item_inventory_id uuid FK → inventories.id, nullable 被追杀的宝物

contract_participants

字段 类型 约束 说明
id uuid PK
contract_id uuid FK → contracts.id, IX
character_id uuid FK → characters.id, IX
participant_type varchar(16) hunter / disciple_proxy / party_member
disciple_id uuid FK → disciples.id, nullable 弟子代派
status varchar(16) IX accepted / active / completed / failed
accepted_at timestamptz
completed_at timestamptz

manhunt_records

稀有宝物追杀令专属流程（GDD-14）。

字段 类型 约束 说明
bounty_id uuid PK, FK → bounties.contract_id
original_owner_id uuid FK → characters.id 原宝物持有者
current_holder_id uuid FK → characters.id 当前宝物持有者
window_end_at timestamptz 追杀窗口结束
outcome varchar(16) pending / returned / black_ate / failed
hunter_choice varchar(16) return / black_eat
compensation_paid numeric(20,4) 货币补偿
chase_right_until timestamptz 追主权有效期
created_at timestamptz

5.9 世界地图、区域、副本与遗迹

world_layers

字段 类型 约束 说明
tier smallint PK 1~6
name varchar(64) 种族出生地/洪荒主陆/洪荒腹地/太古秘境/混沌之渊·化神域/混沌之渊·合体域
display_layer smallint 显示用 layer（0~5），与 GDD-08 对齐
realm_tier smallint 对应境界大层
is_pvp_enabled boolean 是否开放 PVP
cross_tier_rules jsonb 跨界规则、税、掉落衰减

maps

世界地图层定义（可按世界层级、活动事件划分）。

字段 类型 约束 说明
id uuid PK
world_tier smallint FK → world_layers.tier, IX
name varchar(128) 地图名
map_type varchar(16) world / event / instance / ruin
seed bigint 程序化生成种子
layout_data jsonb 地图布局元数据
is_active boolean
created_at timestamptz

regions

字段 类型 约束 说明
id uuid PK
map_id uuid FK → maps.id, IX
world_tier smallint IX
name varchar(128) 地域名
theme varchar(32) 地貌主题
is_safe_zone boolean 是否安全区
pvp_rules jsonb PVP 规则

zones

字段 类型 约束 说明
id uuid PK
region_id uuid FK → regions.id, IX
zone_type varchar(16) IX stronghold / wild / secret / dungeon / ruins
name varchar(128)
terrain varchar(32) 山谷/洞窟/密林/沼泽/废墟/雪原/火山/水域/裂隙/遗迹场
weather varchar(32) 当前天候
resource_density smallint 资源点密度
danger_level smallint 1~6
rarity varchar(16) normal / resource_rich /奇遇高发 / dangerous
seed bigint 程序化生成种子
generated_data jsonb 地形/资源/事件/敌群配置
refreshed_at timestamptz
expires_at timestamptz nullable 临时/裂隙区域过期时间

zone_explorations

字段 类型 约束 说明
id uuid PK
zone_id uuid FK → zones.id, IX
character_id uuid FK → characters.id, IX
fog_state jsonb 迷雾探索进度
exploration_count int 探索次数
last_entered_at timestamptz

instances

副本入口/定义。

字段 类型 约束 说明
id uuid PK
zone_id uuid FK → zones.id, IX
instance_type varchar(16) IX permanent / random / ruin / event
theme varchar(32) 妖兽巢/古战场/邪修密窟/秘宝库/试炼塔/迷踪林/遗迹
world_tier smallint IX
recommended_realm_tier smallint
generated_layout jsonb 房间/波次/Boss/词缀/机关
affixes jsonb 词缀列表
max_parties smallint 同时承载队伍数
expires_at timestamptz nullable
created_at timestamptz

instance_runs

字段 类型 约束 说明
id uuid PK
instance_id uuid FK → instances.id, IX
party_leader_id uuid FK → characters.id, IX
party_members uuid[] 队员 ID 列表
difficulty_coefficient numeric(6,4) 动态难度 D
status varchar(16) IX in_progress / completed / failed / abandoned
battle_id uuid FK → battles.id, nullable 结算战斗
consumed_keys smallint 消耗副本钥匙数
started_at timestamptz IX
ended_at timestamptz

instance_loot

字段 类型 约束 说明
id uuid PK
run_id uuid FK → instance_runs.id, IX
character_id uuid FK → characters.id, IX
item_id varchar(64)
inventory_id uuid FK → inventories.id, nullable 已生成物品
currency_code varchar(32) nullable
currency_amount numeric(20,4)
is_resonance_copy boolean 是否残影拓本
completeness numeric(5,4) 残响完整度（10%~60%）
created_at timestamptz

world_ruin_records

破界遗迹记录（GDD-18 §5）。

字段 类型 约束 说明
id uuid PK
source_character_id uuid FK → characters.id, IX 破界者
source_world_tier smallint
region_id uuid FK → regions.id, IX
zone_id uuid FK → zones.id 遗迹入口区域
instance_id uuid FK → instances.id 关联遗迹副本
richness_score numeric(8,2) 丰厚度评分
snapshot_data jsonb 破界者技能/心法/装备/货币快照
total_extractable numeric(6,4) 可提取上限比例
extracted_ratio numeric(6,4) 已被提取比例
status varchar(16) IX active / depleted / expired
opened_at timestamptz IX
expires_at timestamptz IX

5.10 战斗与战报

battles

战斗头表（一次战斗一条记录）。

字段 类型 约束 说明
id uuid PK
battle_type varchar(16) IX expedition_pve / dungeon_pve / pvp / gvg / bounty / manhunt
world_tier smallint IX
realm_tier smallint IX
game_timestamp timestamptz 游戏内时间戳
attacker_id uuid FK → characters.id, nullable, IX
defender_id uuid FK → characters.id, nullable, IX
party_a uuid[] 攻击方队伍
party_b uuid[] 防守方队伍
status varchar(16) in_progress / completed
result_summary jsonb {winner, end_condition, final_hp}
created_at timestamptz IX

battle_logs

战报详情日志。

字段 类型 约束 说明
id uuid PK
battle_id uuid FK → battles.id, UQ, IX
report jsonb 完整文字战报（GDD-03 战报 Schema）
special_events jsonb 共鸣/元素反应/天罚/心魔等特殊事件
drops jsonb 掉落物快照
created_at timestamptz IX

分区：按 created_at 周分区，保留 8 周。

JSONB 索引：在 report->>'battle_id'、report->>'type' 上建 GIN 索引（jsonb_path_ops）。

player_kills

字段 类型 约束 说明
id uuid PK
killer_id uuid FK → characters.id, IX
victim_id uuid FK → characters.id, IX
battle_id uuid FK → battles.id
world_tier smallint IX
is_malice boolean 是否恶意 PK
karma_delta int 戾气变化
crime_delta int 罪孽变化
loot_taken jsonb 夺取物品快照
created_at timestamptz IX

5.11 渡劫记录

tribulation_records

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
realm_tier smallint 渡劫目标境界
minor_realm smallint 目标小境界
tribulation_type varchar(16) normal / heart_devil / qi_deviation / chaos /合体期
base_success_rate numeric(5,4) 基础成功率
modified_success_rate numeric(5,4) 修正后成功率
helper_ids uuid[] 护法者（道侣/结义）
result varchar(16) success / fail / backlash / death
penalties jsonb 失败惩罚：境界掉落、内力冻结、装备耐久、掉落物
drops_on_success jsonb 成功掉落（天材地宝/心法感悟）
san_snapshot smallint 渡劫前 SAN
created_at timestamptz IX

5.12 社交关系

social_relations

通用关系链。

字段 类型 约束 说明
id uuid PK
character_a_id uuid FK → characters.id, IX
character_b_id uuid FK → characters.id, IX
relation_type varchar(16) IX friend / companion / master / apprentice / enemy
intimacy int 亲密度
status varchar(16) IX active / cooldown / dissolved
cooldown_until timestamptz 解除冷却
created_at timestamptz
dissolved_at timestamptz

lovers

道侣关系扩展（GDD-16 §1.4）。

字段 类型 约束 说明
relation_id uuid PK, FK → social_relations.id
resonance int 共鸣度 0~10000
shared_residence_id uuid FK → guild_territories.id, nullable 共享洞府
combined_skill_id uuid FK → character_skills.id, nullable 合体技实例
vow_path varchar(16) 大道同行 / 生死与共 / 逍遥双修
teleport_cooldown_until timestamptz 传送冷却
mutual_benefits jsonb 双修/护法/传送加成配置
updated_at timestamptz

sworn_brothers

结义关系扩展（GDD-16 §1.4）。

字段 类型 约束 说明
relation_id uuid PK, FK → social_relations.id
group_id uuid UQ 义团 ID（2~5 人共享）
member_order smallint 长幼次序
shared_mission_slots jsonb 3 个共享委托栏位
group_buffs jsonb 队伍增益配置
flag_zone_id uuid FK → zones.id, nullable 义旗位置
updated_at timestamptz

说明：玩家与 NPC 弟子的从属关系放在 disciples.owner_id；玩家之间的师徒关系用 social_relations.relation_type = master / apprentice。

reputation_records

玩家互评/声望事件流水。

字段 类型 约束 说明
id bigint PK
character_id uuid FK → characters.id, IX 被评价者
source_id uuid FK → characters.id, IX 评价者
source_type varchar(16) trade / mercenary / master / party / report
delta int 声望变化
tag varchar(32) 标签：良心商人/可靠佣兵/黑心宰客
created_at timestamptz IX

5.13 配置与审计

dynamic_configs

Nacos 配置本地快照/灰度记录，非运行时主配置源。

字段 类型 约束 说明
id uuid PK
config_key varchar(128) UQ 配置键
namespace varchar(64) economy / combat / skill_gen / map_gen / drop
value jsonb 配置值
version int 版本
is_grayscale boolean 是否灰度
grayscale_ratio numeric(5,4) 灰度比例
effective_from timestamptz 生效时间
created_at timestamptz
updated_at timestamptz

daily_reset_tracking

字段 类型 约束 说明
character_id uuid PK, FK
reset_date date 已处理日期
report_count_used smallint 报官已用次数
instance_count_used smallint 副本基础次数已用
ruin_count_used smallint 遗迹探索次数已用
double_cultivation_minutes smallint 双修有效分钟数
fishing_games smallint 休闲玩法计数
updated_at timestamptz

6. 索引与分区策略

6.1 常用查询索引

表 索引字段 用途
characters (world_tier, realm_tier, power DESC) 境界隔离排行榜
characters (last_online_at) 在线判定、离线悬赏过期
inventories (character_id, slot_type) 背包查询
character_skills (character_id, is_unique) 唯一技能校验
contracts (publisher_id, contract_type, status) 我的发布/接取
bounties (target_id, bounty_type, target_world_tier) 目标悬赏列表
battles (attacker_id, created_at) 个人战报
battles (defender_id, created_at) 被攻击记录
economy_audit_logs (character_id, reason_code, created_at) 经济审计
market_orders (item_id, status, world_tier) 交易行搜索
auctions (status, auction_type, ended_at) 拍卖行列表
instances (world_tier, instance_type, expires_at) 副本入口列表

6.2 分区表清单

表 分区键 分区粒度 保留策略
economy_audit_logs created_at 月 12 个月
market_orders listed_at 月 6 个月
auction_bids bid_at 月 6 个月
battle_logs created_at 周 8 周
reputation_records created_at 月 6 个月

6.3 JSONB 索引建议

  • character_manuals.instance_data、character_skills.instance_data、inventories.instance_data、battle_logs.report 使用 GIN 索引（jsonb_path_ops）。
  • 常用过滤路径（如 instance_data->>'tier'）可建立函数索引。
  • 避免在频繁更新的 JSONB 字段上建过多 GIN 索引，防止写放大。

7. 数据流转与注意事项

  1. 角色创建：players → characters + character_race_states + currency_balances（初始化钱包）+ equipments（空槽位）。
  2. 功法/技能获取：模板表提供约束与默认值；实例表记录随机 roll 结果与来源标签；玉简复制时生成新实例并继承 source_tag=JADE_SLIP。
  3. 经济流转：任何货币变化必须写入 economy_audit_logs，并通过消息队列/Nakama 同步给经济监控服务。
  4. 市场交易：卖家物品从 inventories 转入托管态，market_orders 成交后更新双方 currency_balances 并写审计日志。
  5. 悬赏结算：bounties 完成时，根据 battles 校验击杀，更新 currency_balances、信用分、猎人威望，并写审计日志。
  6. 副本/遗迹：instances 生成后创建 instance_runs；结算时写入 battles / battle_logs 与 instance_loot；破界遗迹额外更新 world_ruin_records.extracted_ratio。
  7. 渡劫：characters.realm_status 进入 tribulation_pending；结算后更新境界并写入 tribulation_records。
  8. 社交关系：关系建立/解除更新 social_relations，道侣/结义额外写入 lovers / sworn_brothers，解除时设置 cooldown_until。
  9. 每日重置：daily_reset_tracking 按现实 08:00 批量重置；避免在 characters 表做大量单行更新。
  10. 配置热更：优先读 Nacos；dynamic_configs 仅做审计与灰度记录，服务端不应直接依赖它做实时逻辑。

8. GDD 冲突与待对齐项

编号 冲突/歧义 涉及文档 当前处理方案 建议
C01 世界层级编号：GDD-08 使用 layer 0~5（出生地=0），GDD-18 使用 一级世界~六级世界（1~6）。 GDD-08 / GDD-18 数据库主键采用 world_tier（1~6），并设 display_layer（0~5）作为显示别名；realm_tier 与 world_tier 对齐。 在 GDD-00 决策总索引中明确统一术语。
C02 境界隔离 SQL 示例：GDD-08 示例为 WHERE current_realm = $1 AND realm_tier = $1，语义重复/歧义。 GDD-08 数据库按 realm_tier（大境界）+ minor_realm（小境界）隔离；排行榜查询使用 (realm_tier, minor_realm, power DESC)。 确认示例是否为笔误，或补充 minor_realm 维度。
C03 货币层级与境界层级对应：GDD-06 说层 1~2 用铜钱/银两，层 3 用灵石，层 4+ 用结晶；若 world_tier 1=炼气、2=筑基，则炼气/筑基用铜钱/银两。 GDD-06 / GDD-18 currency_balances.currency_code 按 realm_tier 选择；交易/拍卖结算时校验货币可用性。 在 GDD-06 中统一使用 realm_tier 而非“层”描述货币。
C04 弟子 vs 师徒：GDD-07 的“弟子”是 NPC，GDD-16 的“师徒”是玩家关系。 GDD-07 / GDD-16 用 disciples 表存 NPC 弟子；social_relations.relation_type = master/apprentice 存玩家师徒。 文档中避免混用“弟子”一词，或加注区分。
C05 悬赏 vs 追杀令：GDD-02“追杀令”基于罪孽/戾气自动生成；GDD-13“悬赏”分报官/私人；GDD-14“追杀令”针对稀有宝物被抢。 GDD-02 / GDD-13 / GDD-14 用 contracts 表存公共头；bounties 表扩展悬赏/追杀令字段；manhunt_records 扩展宝物追杀流程。 明确三类追杀令的 UI 与规则边界。
C06 拍卖抢劫风险范围：GDD-14 §4.4 与 §11.1 对“玉简/功法/法宝/材料”是否可抢劫存在差异（仅稀有宝物可抢劫）。 GDD-14 auctions.risk_type 区分 rare_robbable 与 none；普通物品强制 none。 统一拍卖抢劫规则表述。
C07 深潜裔分支进化：GDD-01 深潜裔存在多分支进化路径，但部分文档仅提 race_id。 GDD-01 character_race_states.sub_branch_id + bloodline_data.evolution_path 保存分支状态。 在种族相关文档中统一分支字段。
C08 SAN 全民化：GDD-02 所有角色有 SAN；GDD-17 提到“对无 SAN 目标转恐惧替代”。 GDD-02 / GDD-17 characters 统一存储 san_current/san_max；非邪修/非深潜裔角色 SAN 惩罚较轻。 明确 SAN 机制对不同族/职业的差异化影响。

9. 新增系统表结构（GDD-29~33）

本节补充 GDD-29（聊天与信息传递）、GDD-30（成就里程碑与图鉴）、GDD-31（洞府与个人空间）、GDD-32（NPC与势力关系）、GDD-33（世界Boss与大型PVE协作）所需的数据表。命名约定、字段风格与上文保持一致。

9.1 聊天与信息传递（GDD-29）

chat_messages

聊天消息持久化表。区域频道消息不持久化（仅 Valkey 缓存），本表存储需审计/举报复核的频道消息。

字段 类型 约束 说明
id uuid PK 消息唯一 ID
channel_type varchar(16) IX REGION / FACTION / WORLD / GUILD / SECT / FAMILY / TEAM / WHISPER / VOICE_SCROLL
channel_id varchar(64) IX 频道标识（zone_id / guild_id / target_character_id 等）
world_tier smallint IX 发送时的世界层级
sender_id uuid FK → characters.id, IX 发送者角色 ID
msg_type varchar(16) IX TEXT / EMOJI / SYSTEM / BATTLE_REPORT / ITEM_LINK / LOCATION
content text 消息文本内容
extra_data jsonb 扩展数据（物品链接属性、战报 ID、位置坐标等）
is_muted boolean 是否被过滤/折叠
created_at timestamptz IX 发送时间

索引：

  • (channel_type, channel_id, created_at DESC) — 频道历史查询
  • (sender_id, created_at DESC) — 玩家发言记录
  • (created_at) BRIN — 过期清理

分区：按 created_at 周分区（pg_partman），保留 7 周，过期分区自动删除。

chat_report_records

聊天举报记录。

字段 类型 约束 说明
id uuid PK
reporter_id uuid FK → characters.id, IX 举报者
target_id uuid FK → characters.id, IX 被举报者
message_id uuid FK → chat_messages.id 被举报消息 ID
reason varchar(32) ABUSE / SPAM / FRAUD / HARASSMENT / OTHER
status varchar(16) IX PENDING / APPROVED / REJECTED
resolved_at timestamptz 处理时间
created_at timestamptz

索引：

  • (reporter_id, created_at DESC) — 举报者历史
  • (target_id, status) — 被举报者待处理查询
  • (status, created_at) — 审核队列

9.2 邮件系统（GDD-29 §10A）

mails

邮件表，承载系统邮件、玩家邮件、帮派/门派邮件、交易邮件。

字段 类型 约束 说明
id uuid PK
sender_id uuid FK → characters.id, nullable 发送者（系统邮件为 NULL）
receiver_id uuid FK → characters.id, IX 接收者
mail_type varchar(16) IX SYSTEM / PLAYER / GUILD / TRADE
subject varchar(128) 主题
content text 内容
attachments jsonb DEFAULT '[]' 附件（物品/货币，最多 6 格）
is_read boolean DEFAULT false 已读状态
is_collected boolean DEFAULT false 附件已领取
expires_at timestamptz IX 过期时间（默认 created_at + 30 天）
created_at timestamptz

索引：

  • (receiver_id, is_read, created_at DESC) — 收件箱查询
  • (expires_at) WHERE NOT is_collected — 过期清理（未领取附件的邮件优先清理）

9.3 成就、图鉴与称号（GDD-30）

achievements

成就定义表（静态配置，由策划/Nacos 维护）。

字段 类型 约束 说明
id varchar(64) PK 成就模板 ID（如 ach_kill_first_beast）
name varchar(128) 成就名称
description varchar(512) 成就描述
category varchar(16) IX combat / cultivation / exploration / crafting / social / collection / special
tier varchar(16) bronze / silver / gold / legendary
is_hidden boolean 是否隐藏成就（条件不可见）
conditions jsonb 达成条件列表（事件类型、阈值等）
rewards jsonb 奖励配置（称号、属性微增、物品、外观）
server_broadcast boolean 达成时是否全服广播
version int 配置版本

character_achievements

角色成就进度表。

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
achievement_id varchar(64) FK → achievements.id, IX
status varchar(16) unlocked / locked（隐藏成就未发现前不写入）
progress jsonb 当前进度快照（击杀数、累计值等）
unlocked_at timestamptz 解锁时间

唯一约束：(character_id, achievement_id)

codex_entries

图鉴条目定义表（静态配置）。图鉴类型包括怪物、功法、种族、装备、地图探索。

字段 类型 约束 说明
id varchar(64) PK 图鉴条目 ID
codex_type varchar(16) IX monster / manual / race / equipment / map
name varchar(128) 条目名称
source_ref_id varchar(64) IX 关联源数据 ID（template_id / manual_id / race_id 等）
unlock_levels jsonb 各解锁层级对应的信息内容定义
version int 配置版本

character_codex

角色图鉴记录表。

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
codex_entry_id varchar(64) FK → codex_entries.id, IX
unlock_level smallint 当前解锁层级（0~4，如怪物图鉴：初见/交手/熟知/通晓）
stats jsonb 统计数据（击杀次数、打造次数、接触次数等）
updated_at timestamptz

唯一约束：(character_id, codex_entry_id)

character_titles

角色称号表。

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
title_id varchar(64) 称号 ID（对应成就/里程碑/声望等来源的称号）
title_name varchar(64) 称号显示名
source varchar(16) achievement / milestone / honor / mercenary / domain / race / social / hidden
source_id varchar(64) 来源 ID（成就 ID / 里程碑 ID 等）
effect_type varchar(16) display / attribute / special
effects jsonb 属性效果列表（如 [{"type":"monster_damage_bonus","value":0.01}]）
rarity varchar(16) common / uncommon / rare / legendary / unique
is_unique boolean 是否全服唯一
slot_type varchar(16) equipped / display_1 / display_2 / display_3 / unequipped
equipped_at timestamptz 装备到槽位的时间
obtained_at timestamptz 获得时间

唯一约束：(character_id, title_id)

索引：

  • (character_id, slot_type) — 查询已装备/展示称号

9.4 洞府与个人空间（GDD-31）

caves

洞府主表。

字段 类型 约束 说明
id uuid PK 洞府唯一 ID
owner_id uuid FK → characters.id, UQ 所属玩家（每人最多 1 个洞府）
level smallint 洞府等级（1~9，对应九大境界）
world_tier smallint IX 所在世界层级
region_id uuid FK → regions.id, nullable 所在地域
zone_id uuid FK → zones.id, nullable 所在区域
terrain_quality varchar(16) poor / normal / good / excellent / immortal（地脉品质）
barrier_hp int 结界当前耐久
barrier_hp_max int 结界最大耐久
barrier_last_repair_at timestamptz 上次结界修复时间
active_arrays jsonb 已布阵法列表（类型/等级/材料品质/剩余维持时间）
appearance_id varchar(64) 当前外观 ID
partner_id uuid FK → characters.id, nullable 道侣 ID
partner_permission varchar(16) visit / facility_share / full_share
last_invaded_at timestamptz 上次被入侵时间
invasion_count_today smallint 今日被入侵次数（每日重置）
status varchar(16) active / abandoned / destroyed
created_at timestamptz
updated_at timestamptz

cave_facilities

洞府设施表。

字段 类型 约束 说明
id uuid PK 设施唯一 ID
cave_id uuid FK → caves.id, IX 所属洞府
facility_type varchar(16) training_room / alchemy_room / forge_room / library / herb_garden / mine_vein / array_core / disciple_quarters
level smallint 设施等级（受洞府等级上限约束）
state jsonb 运行状态（产出队列 / 弟子派驻 / 阵法配置）
last_collect_at timestamptz 上次收取产出时间
updated_at timestamptz

唯一约束：(cave_id, facility_type)

9.5 NPC与势力关系（GDD-32）

faction_reputation

势力声望表。每个玩家对七大势力各有独立声望值。

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
faction_id varchar(32) celestial_court / dragon_palace / underworld / demon_domain / witch_holy_land / demon_territory / eldritch_beyond
reputation_level varchar(16) hated / cold / neutral / friendly / revered / exalted / worshipped
reputation_value int 声望值（-10000 ~ 10000）
total_earned int 累计获取声望（防通胀监控）
updated_at timestamptz

唯一约束：(character_id, faction_id)

索引：

  • (character_id, reputation_level) — 按声望等级查询已解锁势力

npc_affinity

NPC 好感度表。每个玩家对每个可交互 NPC 有独立好感度。

字段 类型 约束 说明
id uuid PK
character_id uuid FK → characters.id, IX
npc_id varchar(64) NPC 唯一标识
affinity_level varchar(16) stranger / acquaintance / familiar / trusted / soulmate
affinity_value int 好感度值（0 ~ 1000）
last_interacted_at timestamptz 上次交互时间（用于衰减计算）
lock_until timestamptz nullable 信物锁定截止时间（锁定期间不衰减）
updated_at timestamptz

唯一约束：(character_id, npc_id)

索引：

  • (character_id, affinity_level) — 按好感度等级查询
  • (last_interacted_at) — 衰减批处理扫描

9.6 世界Boss与大型PVE协作（GDD-33）

world_boss_instances

世界Boss实例表。每只存活的 Boss 生成一条实例记录；镜像实例为独立记录。

字段 类型 约束 说明
id uuid PK 实例 ID
boss_template_id varchar(64) IX Boss 模板 ID（对应 GDD-19 怪物 Schema）
boss_class varchar(16) IX divine / auspicious / regional / event
current_hp bigint 当前血量（实时同步 Valkey）
max_hp bigint 最大血量（含参与人数缩放）
world_tier smallint IX 出没世界层级
region_id uuid FK → regions.id, nullable 出没地域
zone_id uuid FK → zones.id, nullable 出没区域
is_mirror boolean 是否镜像实例
parent_instance_id uuid FK → world_boss_instances.id, nullable 镜像对应的主实例
current_phase smallint 当前阶段（1~4）
is_frenzy boolean 是否进入狂暴状态
status varchar(16) IX alive / dead / despawned
participant_count int 当前参与人数
ownership_holder_id uuid FK → characters.id, nullable 当前归属权持有者
spawn_at timestamptz IX 刷新时间
death_at timestamptz 死亡时间
expires_at timestamptz 事件 Boss 过期时间（非事件 Boss 为 NULL）
created_at timestamptz

索引：

  • (status, boss_class) — 查询活跃 Boss 列表
  • (world_tier, status) — 按层级查询活跃 Boss

world_boss_participants

世界Boss参与记录表。记录每位玩家对每次 Boss 战的贡献数据。

字段 类型 约束 说明
id uuid PK
instance_id uuid FK → world_boss_instances.id, IX Boss 实例
character_id uuid FK → characters.id, IX 参与玩家
damage_dealt bigint 造成伤害（含境界修正后）
damage_taken bigint 承受伤害
healing_done bigint 治疗量
contribution_score numeric(16,4) 综合贡献度（伤害×0.7 + 承受×0.15 + 治疗×0.15）
ownership_score numeric(8,4) 归属权得分
rank int 个人排名
has_first_hit boolean 是否首击
has_last_hit boolean 是否尾刀
is_first_kill boolean 是否全服首杀
reward_type varchar(16) contribution / last_hit / first_hit / participation / first_kill / top3
rewards jsonb 奖励快照（物品/货币/称号）
is_reward_claimed boolean 奖励是否已领取
join_at timestamptz 加入时间
leave_at timestamptz 离开时间（战败/超时/Boss 死亡）

唯一约束：(instance_id, character_id)

索引：

  • (instance_id, contribution_score DESC) — 排名查询
  • (character_id, join_at DESC) — 个人参与历史

9.7 新增表索引与分区汇总

新增分区表

表 分区键 分区粒度 保留策略
chat_messages created_at 周 7 周

新增常用查询索引

表 索引字段 用途
chat_messages (channel_type, channel_id, created_at DESC) 频道历史消息
chat_messages (sender_id, created_at DESC) 玩家发言记录
mails (receiver_id, is_read, created_at DESC) 收件箱查询
character_achievements (character_id, achievement_id) UQ 成就进度查询
character_codex (character_id, codex_entry_id) UQ 图鉴记录查询
character_titles (character_id, slot_type) 已装备称号查询
caves (owner_id) UQ 洞府归属查询
faction_reputation (character_id, faction_id) UQ 声望查询
npc_affinity (character_id, npc_id) UQ 好感度查询
world_boss_instances (status, boss_class) 活跃 Boss 列表
world_boss_participants (instance_id, contribution_score DESC) Boss 排名查询

10. 版本记录

版本 日期 作者 变更说明
1.0 2026-06-30 Kimi Code CLI 初稿：完成账号、角色、种族境界、功法技能、物品经济、市场拍卖、组织、弟子、悬赏、地图副本、战斗、渡劫、社交、配置审计等表结构设计；定义索引、分区策略与 GDD 冲突项。
1.1 2026-06-30 Kimi Code CLI 按需求清单对齐表名：players、character_race_states、realms/character_realms、manuals/skills/items、inventories/equipments、currency_balances、auctions、guilds/guild_members/guild_territories、disciple_missions、bounties、maps、battles/battle_logs、lovers/sworn_brothers；拆分 contracts/bounties/battles/battle_logs；补充表名速查索引。
1.2 2026-07-02 Claude 新增 GDD-29~33 系统表结构（第 9 章）：chat_messages、chat_report_records、mails、achievements、character_achievements、codex_entries、character_codex、character_titles、caves、cave_facilities、faction_reputation、npc_affinity、world_boss_instances、world_boss_participants；含索引设计与分区策略。

TDD-04 v1.2 | 2026-07-02 | 数据库表结构设计