# 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. 数据流转与注意事项

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 | ~~世界层级编号~~ **已修复**（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*