Docs Build / build-and-deploy (push) Waiting to run

详情

- 移除 ConfigManager 配置管理器类
- 移除 GameManager 全局单例管理器类
- 移除 NetworkManager 网络连接管理器类
- 移除 CharacterData 和 ItemData 数据模型类
- 移除 BagScene、BattleScene、LobbyScene 等场景脚本
- 移除 EncounterBubble 和 EventFeedPanel UI组件脚本
- 更新代理邀请文档中的服务器连接方式
- 更新同步状态表格中的代理任务分配信息
- 添加 MiMo 任务完成总结和审查修复记录

2026-07-03 21:34:51 +08:00

62 KiB

原始文件 Blame 文件历史

TDD-04 数据库表结构设计

文档类型：技术设计文档（Technical Design Document）版本：1.5 日期：2026-07-06 关联文档：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~5）
world_tier	smallint	IX	当前世界层级（1~5，对应 GDD-18 五层世界 ✅136）
realm_tier	smallint	IX	当前大境界（1~9，炼气~飞升，✅116）
minor_realm	smallint	IX	小境界（1~3：初期/中期/圆满）
realm_status	varchar(16)		normal / tribulation_pending / breakthrough_ready
energy_current	bigint		能量当前值（可消耗，战斗/生产/仪式扣减，见 GDD-23 §2.3）
energy_cap	bigint		能量上限值（随时间持续增长=境界进度，不可消耗；不存在独立"经验值/内力"字段，✅158）
energy_cap_ceiling	bigint		当前小境界目标阈值（由 GDD-23 §2.2 公式计算，达到 energy_cap≥此值时按概率触发顿悟）
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~9
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~5（大陆五层分层，对齐 GDD-08 ✅136；均为洪荒大陆内部纵深区域，非独立世界）
name	varchar(64)		出生地/洪荒边境/太古秘境/混沌之渊/界域（GDD-08 §1.0 权威命名，不使用"凡界/灵界/道界/圣界/神域"）
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. 数据流转与注意事项

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

8. GDD 冲突与待对齐项

编号	冲突/歧义	涉及文档	当前处理方案	建议
C01	~~世界层级编号~~ 已修复（v1.3）：数据库 `world_tier` 从 1~6 改为 1~5（对齐 GDD-08 ✅136 五层世界），`realm_tier` 从 1~6 改为 1~9（对齐 ✅116 九大境界）。	GDD-08 / GDD-18	数据库主键采用 `world_tier`（1~5），并设 `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；含索引设计与分区策略。
1.3	2026-07-06	MiMoCode	五层世界对齐：world_layers 表 tier 从 1~6 改为 1~5（对齐 ✅136），world 名称更新为凡界/灵界/道界/圣界/神域；C01 冲突项确认已修复
1.4	2026-07-06	Claude	反转✅6同步（✅158）：characters 表移除 level/exp 字段，改为 energy_current/energy_cap/energy_cap_ceiling，不再有独立"经验/修为"字段
1.5	2026-07-06	Claude	命名冲突修复：world_layers.name 与并行任务（v1.3）产生的"凡界/灵界/道界/圣界/神域"命名冲突——GDD-08/GDD-02/GDD-23 已统一定案为"出生地/洪荒边境/太古秘境/混沌之渊/界域"（体现同一大陆纵深区域，而非独立世界），本表以此为准同步；表名/字段名 world_layers/world_tier 因引用面广予以保留，仅同步 name 字段取值

TDD-04 v1.5 | 2026-07-06 | 修复与并行任务（MiMoCode v1.3）的世界层级命名冲突：统一为 GDD-08 权威命名"出生地/洪荒边境/太古秘境/混沌之渊/界域"；同步✅158能量模型，characters表level/exp改为energy_current/energy_cap/energy_cap_ceiling

62 KiB 原始文件 Blame 文件历史 Unescape Escape