novelws 5.4.0 → 5.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/server/index.d.ts.map +1 -1
  2. package/dist/server/index.js +2 -3
  3. package/dist/server/index.js.map +1 -1
  4. package/package.json +1 -1
  5. package/templates/scripts/db_init_protagonist.py +172 -57
  6. package/templates/scripts/phase_a_init_db.py +544 -206
package/dist/server/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS7C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,+CAgD7D;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,+GAWlE"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS7C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,+CA4C7D;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,+GAWlE"}
package/dist/server/index.js CHANGED
@@ -37,9 +37,8 @@ export function createApp(projectRoot, ds) {
37
37
  app.use('/api/stats', createStatsRouter(ds));
38
38
  }
39
39
  // 静态文件服务（生产模式）
40
- // 在 CJS 环境 (Jest/tsc 编译后) __dirname 可用
41
- // 在 ESM 环境 (tsx 直接运行) 需要从 dashboardDir 参数或 dist 目录推断
42
- const dashboardDir = path.resolve(typeof __dirname !== 'undefined' ? __dirname : process.cwd(), typeof __dirname !== 'undefined' ? path.join('..', 'dashboard') : path.join('dist', 'dashboard'));
40
+ // 从用户项目目录的 dashboard 文件夹提供静态文件
41
+ const dashboardDir = path.resolve(projectRoot, 'dashboard');
43
42
  app.use(express.static(dashboardDir));
44
43
  // SPA fallback：非 /api 路由返回 index.html
45
44
  app.get(/^(?!\/api).*/, (_req, res) => {
package/dist/server/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "novelws",
3
- "version": "5.4.0",
3
+ "version": "5.4.1",
4
4
  "type": "module",
5
5
  "description": "Claude Code 专用的 AI 小说创作工具 - 深度集成 Slash Commands 和 Agent Skills",
6
6
  "keywords": [
package/templates/scripts/db_init_protagonist.py CHANGED
@@ -36,88 +36,111 @@ def get_db_config(config):
36
36
 
37
37
 
38
38
  DDL = f"""
39
+ -- ============================================================
40
+ -- 主角相关表结构（5张表）
41
+ -- Schema: {SCHEMA}
42
+ -- ============================================================
43
+
39
44
  -- 主角技能主表
45
+ -- 说明：记录主角学会的所有技能
40
46
  CREATE TABLE IF NOT EXISTS {SCHEMA}.protagonist_skills (
41
- id SERIAL PRIMARY KEY,
42
- skill_name VARCHAR(100) NOT NULL UNIQUE,
43
- skill_category VARCHAR(20) NOT NULL,
44
- skill_level VARCHAR(50),
45
- parent_skill_id INT REFERENCES {SCHEMA}.protagonist_skills(id),
46
- description TEXT,
47
- acquired_chapter INT NOT NULL,
48
- acquired_method VARCHAR(200),
49
- last_used_chapter INT,
50
- use_count INT DEFAULT 0,
51
- status VARCHAR(20) DEFAULT 'active'
47
+ id SERIAL PRIMARY KEY,
48
+ skill_name VARCHAR(100) NOT NULL UNIQUE, -- 技能名称（唯一）
49
+ skill_category VARCHAR(20) NOT NULL, -- 技能分类：账本脑/符/阵/被动/功法等
50
+ skill_level VARCHAR(50), -- 技能等级：入门/固化/小成/大成
51
+ parent_skill_id INT REFERENCES {SCHEMA}.protagonist_skills(id), -- 父技能ID（技能树）
52
+ description TEXT, -- 技能描述/效果说明
53
+ acquired_chapter INT NOT NULL, -- 获得章节号
54
+ acquired_method VARCHAR(200), -- 获得方式：自悟/修炼突破/副本掉落/交易等
55
+ last_used_chapter INT, -- 最后使用章节号
56
+ use_count INT DEFAULT 0, -- 使用次数
57
+ status VARCHAR(20) DEFAULT 'active' -- 状态：active(可用)/locked(锁定)/forgotten(遗忘)
52
58
  );
53
59
 
54
60
  -- 技能时序表
61
+ -- 说明：记录技能的每次使用/变化事件
55
62
  CREATE TABLE IF NOT EXISTS {SCHEMA}.protagonist_skill_events (
56
- id SERIAL PRIMARY KEY,
57
- skill_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_skills(id),
58
- chapter_number INT NOT NULL,
59
- event_type VARCHAR(30) NOT NULL,
60
- detail TEXT,
61
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
63
+ id SERIAL PRIMARY KEY,
64
+ skill_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_skills(id), -- 技能ID
65
+ chapter_number INT NOT NULL, -- 事件发生章节号
66
+ event_type VARCHAR(30) NOT NULL, -- 事件类型：acquired(获得)/upgraded(升级)/used(使用)/forgotten(遗忘)
67
+ detail TEXT, -- 事件详情
68
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
62
69
  );
63
70
 
64
- -- 装备/道具主表
71
+ -- 主角装备/道具主表
72
+ -- 说明：记录主角当前拥有的所有物品
65
73
  CREATE TABLE IF NOT EXISTS {SCHEMA}.protagonist_inventory (
66
- id SERIAL PRIMARY KEY,
67
- item_name VARCHAR(100) NOT NULL,
68
- item_type VARCHAR(30) NOT NULL,
69
- quantity INT DEFAULT 1,
70
- quality VARCHAR(30),
71
- description TEXT,
72
- acquired_chapter INT NOT NULL,
73
- acquired_method VARCHAR(200),
74
- status VARCHAR(20) DEFAULT 'held',
75
- UNIQUE(item_name, acquired_chapter)
74
+ id SERIAL PRIMARY KEY,
75
+ item_name VARCHAR(100) NOT NULL, -- 物品名称
76
+ item_type VARCHAR(30) NOT NULL, -- 物品类型：装备/材料/消耗品/工具
77
+ quantity INT DEFAULT 1, -- 数量
78
+ quality VARCHAR(30), -- 品质：普通/稀有/精良/史诗/传说
79
+ description TEXT, -- 物品描述
80
+ acquired_chapter INT NOT NULL, -- 获得章节号
81
+ acquired_method VARCHAR(200), -- 获得方式：拾取/交易/制作/副本掉落
82
+ status VARCHAR(20) DEFAULT 'held', -- 状态：held(持有)/consumed(已消耗)/equipped(装备中)
83
+ UNIQUE(item_name, acquired_chapter) -- 同一物品同名只能有一条记录
76
84
  );
77
85
 
78
86
  -- 道具时序表
87
+ -- 说明：记录物品的获取、使用、消耗等事件
79
88
  CREATE TABLE IF NOT EXISTS {SCHEMA}.protagonist_inventory_events (
80
- id SERIAL PRIMARY KEY,
81
- item_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_inventory(id),
82
- chapter_number INT NOT NULL,
83
- event_type VARCHAR(30) NOT NULL,
84
- quantity_change INT DEFAULT 0,
85
- detail TEXT,
86
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
89
+ id SERIAL PRIMARY KEY,
90
+ item_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_inventory(id), -- 物品ID
91
+ chapter_number INT NOT NULL, -- 事件发生章节号
92
+ event_type VARCHAR(30) NOT NULL, -- 事件类型：acquired(获得)/used(使用)/lost(丢失)/given(赠予)
93
+ quantity_change INT DEFAULT 0, -- 数量变化（正数增加，负数减少）
94
+ detail TEXT, -- 事件详情
95
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
87
96
  );
88
97
 
89
98
  -- 修炼进度表
99
+ -- 说明：记录主角的修炼突破历程
90
100
  CREATE TABLE IF NOT EXISTS {SCHEMA}.protagonist_cultivation (
91
- id SERIAL PRIMARY KEY,
92
- chapter_number INT NOT NULL,
93
- level VARCHAR(50) NOT NULL,
94
- progress_pct DECIMAL(5,1),
95
- breakthrough_type VARCHAR(20),
96
- trigger VARCHAR(200),
97
- detail TEXT,
98
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
101
+ id SERIAL PRIMARY KEY,
102
+ chapter_number INT NOT NULL, -- 记录发生的章节号
103
+ level VARCHAR(50) NOT NULL, -- 修炼等级/境界（如：段1·炼气前期）
104
+ progress_pct DECIMAL(5,1), -- 进度百分比（0-100）
105
+ breakthrough_type VARCHAR(20), -- 突破类型：major(大境界突破)/minor(小境界提升)
106
+ trigger VARCHAR(200), -- 触发原因：修炼突破/副本战斗/特殊事件
107
+ detail TEXT, -- 详情描述
108
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
99
109
  );
100
110
 
101
- -- 索引
102
- CREATE INDEX IF NOT EXISTS idx_skills_category ON {SCHEMA}.protagonist_skills(skill_category);
103
- CREATE INDEX IF NOT EXISTS idx_skills_status ON {SCHEMA}.protagonist_skills(status);
104
- CREATE INDEX IF NOT EXISTS idx_skill_events_skill ON {SCHEMA}.protagonist_skill_events(skill_id);
105
- CREATE INDEX IF NOT EXISTS idx_skill_events_vol ON {SCHEMA}.protagonist_skill_events(volume_id);
106
- CREATE INDEX IF NOT EXISTS idx_skill_events_type ON {SCHEMA}.protagonist_skill_events(event_type);
107
- CREATE INDEX IF NOT EXISTS idx_inventory_type ON {SCHEMA}.protagonist_inventory(item_type);
108
- CREATE INDEX IF NOT EXISTS idx_inventory_status ON {SCHEMA}.protagonist_inventory(status);
109
- CREATE INDEX IF NOT EXISTS idx_inv_events_item ON {SCHEMA}.protagonist_inventory_events(item_id);
110
- CREATE INDEX IF NOT EXISTS idx_inv_events_vol ON {SCHEMA}.protagonist_inventory_events(volume_id);
111
- CREATE INDEX IF NOT EXISTS idx_cultivation_vol ON {SCHEMA}.protagonist_cultivation(volume_id);
112
- CREATE INDEX IF NOT EXISTS idx_cultivation_ch ON {SCHEMA}.protagonist_cultivation(chapter_number);
113
-
114
- -- 视图
111
+ -- ============================================================
112
+ -- 索引（提升查询性能）
113
+ -- ============================================================
114
+
115
+ -- 技能相关索引
116
+ CREATE INDEX IF NOT EXISTS idx_skills_category ON {SCHEMA}.protagonist_skills(skill_category); -- 按技能分类查询
117
+ CREATE INDEX IF NOT EXISTS idx_skills_status ON {SCHEMA}.protagonist_skills(status); -- 按状态查询技能
118
+ CREATE INDEX IF NOT EXISTS idx_skill_events_skill ON {SCHEMA}.protagonist_skill_events(skill_id); -- 按技能查询事件
119
+ CREATE INDEX IF NOT EXISTS idx_skill_events_vol ON {SCHEMA}.protagonist_skill_events(volume_id); -- 按卷查询技能事件
120
+ CREATE INDEX IF NOT EXISTS idx_skill_events_type ON {SCHEMA}.protagonist_skill_events(event_type); -- 按事件类型查询
121
+
122
+ -- 背包相关索引
123
+ CREATE INDEX IF NOT EXISTS idx_inventory_type ON {SCHEMA}.protagonist_inventory(item_type); -- 按物品类型查询
124
+ CREATE INDEX IF NOT EXISTS idx_inventory_status ON {SCHEMA}.protagonist_inventory(status); -- 按状态查询背包
125
+ CREATE INDEX IF NOT EXISTS idx_inv_events_item ON {SCHEMA}.protagonist_inventory_events(item_id); -- 按物品查询事件
126
+ CREATE INDEX IF NOT EXISTS idx_inv_events_vol ON {SCHEMA}.protagonist_inventory_events(volume_id); -- 按卷查询背包事件
127
+
128
+ -- 修炼进度索引
129
+ CREATE INDEX IF NOT EXISTS idx_cultivation_vol ON {SCHEMA}.protagonist_cultivation(volume_id); -- 按卷查询修炼进度
130
+ CREATE INDEX IF NOT EXISTS idx_cultivation_ch ON {SCHEMA}.protagonist_cultivation(chapter_number); -- 按章节查询修炼进度
131
+
132
+ -- ============================================================
133
+ -- 视图（常用查询）
134
+ -- ============================================================
135
+
136
+ -- 当前持有物品视图：显示主角当前背包中的所有物品
115
137
  CREATE OR REPLACE VIEW {SCHEMA}.current_inventory AS
116
138
  SELECT item_name, item_type, quantity, quality, description, acquired_chapter
117
139
  FROM {SCHEMA}.protagonist_inventory
118
140
  WHERE status = 'held'
119
141
  ORDER BY item_type, item_name;
120
142
 
143
+ -- 技能总览视图：显示所有技能的概览信息及使用统计
121
144
  CREATE OR REPLACE VIEW {SCHEMA}.skill_overview AS
122
145
  SELECT s.skill_name, s.skill_category, s.skill_level, s.status,
123
146
  s.acquired_chapter, s.use_count,
@@ -127,10 +150,102 @@ LEFT JOIN {SCHEMA}.protagonist_skill_events e ON s.id = e.skill_id
127
150
  GROUP BY s.id
128
151
  ORDER BY s.skill_category, s.acquired_chapter;
129
152
 
153
+ -- 修炼进度曲线视图：按章节展示修炼进度变化
130
154
  CREATE OR REPLACE VIEW {SCHEMA}.cultivation_curve AS
131
155
  SELECT chapter_number, level, progress_pct, breakthrough_type, trigger
132
156
  FROM {SCHEMA}.protagonist_cultivation
133
157
  ORDER BY chapter_number;
158
+
159
+ -- ============================================================
160
+ -- 表和字段的中文注释（COMMENT ON）
161
+ -- ============================================================
162
+
163
+ -- protagonist_skills 表注释
164
+ COMMENT ON TABLE {SCHEMA}.protagonist_skills IS '主角技能主表：记录主角学会的所有技能';
165
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.id IS '主键ID';
166
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_name IS '技能名称';
167
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_category IS '技能分类：账本脑/符/阵/被动/功法等';
168
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_level IS '技能等级：入门/固化/小成/大成';
169
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.parent_skill_id IS '父技能ID（技能树）';
170
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.description IS '技能描述/效果说明';
171
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.acquired_chapter IS '获得章节号';
172
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.acquired_method IS '获得方式：自悟/修炼突破/副本掉落/交易等';
173
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.last_used_chapter IS '最后使用章节号';
174
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.use_count IS '使用次数';
175
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.status IS '状态：active(可用)/locked(锁定)/forgotten(遗忘)';
176
+
177
+ -- protagonist_skill_events 表注释
178
+ COMMENT ON TABLE {SCHEMA}.protagonist_skill_events IS '技能时序表：记录技能的每次使用/变化事件';
179
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.id IS '主键ID';
180
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.skill_id IS '技能ID';
181
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.chapter_number IS '事件发生章节号';
182
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.event_type IS '事件类型：acquired(获得)/upgraded(升级)/used(使用)/forgotten(遗忘)';
183
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.detail IS '事件详情';
184
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.volume_id IS '所属卷ID';
185
+
186
+ -- protagonist_inventory 表注释
187
+ COMMENT ON TABLE {SCHEMA}.protagonist_inventory IS '主角装备/道具主表：记录主角当前拥有的所有物品';
188
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.id IS '主键ID';
189
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.item_name IS '物品名称';
190
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.item_type IS '物品类型：装备/材料/消耗品/工具';
191
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.quantity IS '数量';
192
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.quality IS '品质：普通/稀有/精良/史诗/传说';
193
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.description IS '物品描述';
194
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.acquired_chapter IS '获得章节号';
195
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.acquired_method IS '获得方式：拾取/交易/制作/副本掉落';
196
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.status IS '状态：held(持有)/consumed(已消耗)/equipped(装备中)';
197
+
198
+ -- protagonist_inventory_events 表注释
199
+ COMMENT ON TABLE {SCHEMA}.protagonist_inventory_events IS '道具时序表：记录物品的获取、使用、消耗等事件';
200
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.id IS '主键ID';
201
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.item_id IS '物品ID';
202
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.chapter_number IS '事件发生章节号';
203
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.event_type IS '事件类型：acquired(获得)/used(使用)/lost(丢失)/given(赠予)';
204
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.quantity_change IS '数量变化（正数增加，负数减少）';
205
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.detail IS '事件详情';
206
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.volume_id IS '所属卷ID';
207
+
208
+ -- protagonist_cultivation 表注释
209
+ COMMENT ON TABLE {SCHEMA}.protagonist_cultivation IS '修炼进度表：记录主角的修炼突破历程';
210
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.id IS '主键ID';
211
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.chapter_number IS '记录发生的章节号';
212
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.level IS '修炼等级/境界（如：段1·炼气前期）';
213
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.progress_pct IS '进度百分比（0-100）';
214
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.breakthrough_type IS '突破类型：major(大境界突破)/minor(小境界提升)';
215
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.trigger IS '触发原因：修炼突破/副本战斗/特殊事件';
216
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.detail IS '详情描述';
217
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.volume_id IS '所属卷ID';
218
+
219
+ -- ============================================================
220
+ -- 视图的中文注释（COMMENT ON）
221
+ -- ============================================================
222
+
223
+ -- current_inventory 视图注释
224
+ COMMENT ON VIEW {SCHEMA}.current_inventory IS '当前背包：显示主角当前持有的物品';
225
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.item_name IS '物品名称';
226
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.item_type IS '物品类型';
227
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.quantity IS '数量';
228
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.quality IS '品质';
229
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.description IS '物品描述';
230
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.acquired_chapter IS '获得章节';
231
+
232
+ -- skill_overview 视图注释
233
+ COMMENT ON VIEW {SCHEMA}.skill_overview IS '技能总览：显示所有技能的概览信息及使用统计';
234
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_name IS '技能名称';
235
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_category IS '技能分类';
236
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_level IS '技能等级';
237
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.status IS '技能状态';
238
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.acquired_chapter IS '获得章节';
239
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.use_count IS '使用次数';
240
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.total_events IS '事件总数';
241
+
242
+ -- cultivation_curve 视图注释
243
+ COMMENT ON VIEW {SCHEMA}.cultivation_curve IS '修炼进度曲线：按章节展示修炼进度变化';
244
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.chapter_number IS '章节号';
245
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.level IS '修炼等级';
246
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.progress_pct IS '进度百分比';
247
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.breakthrough_type IS '突破类型';
248
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.trigger IS '触发原因';
134
249
  """
135
250
 
136
251
  # ── 技能数据（vol-001~003） ──
package/templates/scripts/phase_a_init_db.py CHANGED
@@ -36,285 +36,556 @@ def get_db_config(config):
36
36
 
37
37
 
38
38
  # ─────────────────────────────────────────────
39
- # DDL: 建 schema + 20 张核心表
39
+ # DDL: 建 schema + 20 张核心表（带中文注释）
40
40
  # ─────────────────────────────────────────────
41
41
  DDL = f"""
42
+ -- ============================================================
43
+ -- 小说数据库核心表结构
44
+ -- Schema: {SCHEMA}
45
+ -- ============================================================
46
+
42
47
  DROP SCHEMA IF EXISTS {SCHEMA} CASCADE;
43
48
  CREATE SCHEMA {SCHEMA};
44
49
 
45
- -- 1) phases: 纪元
50
+ -- 1) phases: 纪元表（记录小说的时代/纪元划分）
51
+ -- 说明：每个纪元代表小说中的一个完整时代，包含多卷内容
46
52
  CREATE TABLE {SCHEMA}.phases (
47
- id SERIAL PRIMARY KEY,
48
- phase_number INT NOT NULL UNIQUE,
49
- title VARCHAR(100) NOT NULL,
50
- theme VARCHAR(200),
51
- vol_start INT NOT NULL,
52
- vol_end INT NOT NULL,
53
- protagonist_level_start VARCHAR(50),
54
- protagonist_level_end VARCHAR(50),
55
- stage_level VARCHAR(50),
56
- growth_keyword VARCHAR(200),
57
- core_conflict TEXT,
58
- status VARCHAR(20) DEFAULT 'planned'
53
+ id SERIAL PRIMARY KEY,
54
+ phase_number INT NOT NULL UNIQUE, -- 纪元编号（如：第1纪元、第2纪元）
55
+ title VARCHAR(100) NOT NULL, -- 纪元标题/名称
56
+ theme VARCHAR(200), -- 纪元主题（如：觉醒、成长、决战等）
57
+ vol_start INT NOT NULL, -- 起始卷号（本纪元从哪一卷开始）
58
+ vol_end INT NOT NULL, -- 结束卷号（本纪元到哪一卷结束）
59
+ protagonist_level_start VARCHAR(50), -- 主角初始等级/境界
60
+ protagonist_level_end VARCHAR(50), -- 主角结束等级/境界
61
+ stage_level VARCHAR(50), -- 当前境界等级（如：炼气期、筑基期）
62
+ growth_keyword VARCHAR(200), -- 成长关键词（如：觉醒、突破、蜕变）
63
+ core_conflict TEXT, -- 核心冲突/矛盾
64
+ status VARCHAR(20) DEFAULT 'planned' -- 状态：planned(计划中)/active(进行中)/completed(已完成)
59
65
  );
60
66
 
61
- -- 2) volumes: 卷
67
+ -- 2) volumes: 卷表（记录每卷的基本信息）
68
+ -- 说明：卷是介于纪元和章节之间的单位，一个纪元包含多卷
62
69
  CREATE TABLE {SCHEMA}.volumes (
63
- id SERIAL PRIMARY KEY,
64
- phase_id INT NOT NULL REFERENCES {SCHEMA}.phases(id),
65
- vol_number INT NOT NULL UNIQUE,
66
- title VARCHAR(200) NOT NULL,
67
- arc_type VARCHAR(50),
68
- instance_name VARCHAR(100),
69
- instance_type VARCHAR(100),
70
- instance_level VARCHAR(50),
71
- protagonist_level_range VARCHAR(100),
72
- chapter_count INT DEFAULT 100,
73
- outline_path TEXT,
74
- summary_path TEXT,
75
- status VARCHAR(20) DEFAULT 'planned'
70
+ id SERIAL PRIMARY KEY,
71
+ phase_id INT NOT NULL REFERENCES {SCHEMA}.phases(id), -- 所属纪元ID
72
+ vol_number INT NOT NULL UNIQUE, -- 卷号（如：第1卷、第2卷）
73
+ title VARCHAR(200) NOT NULL, -- 卷标题
74
+ arc_type VARCHAR(50), -- 剧情弧类型（如：日常、副本、高潮）
75
+ instance_name VARCHAR(100), -- 副本名称（如果有）
76
+ instance_type VARCHAR(100), -- 副本类型（如：秘境、禁地、遗迹）
77
+ instance_level VARCHAR(50), -- 副本等级/难度
78
+ protagonist_level_range VARCHAR(100), -- 主角等级范围
79
+ chapter_count INT DEFAULT 100, -- 章节数量（预估或实际）
80
+ outline_path TEXT, -- 大纲文件路径
81
+ summary_path TEXT, -- 卷概要文件路径
82
+ status VARCHAR(20) DEFAULT 'planned' -- 状态：planned(计划中)/writing(写作中)/completed(已完成)
76
83
  );
77
84
 
78
- -- 3) chapters: 章节
85
+ -- 3) chapters: 章节表（记录每个章节的详细信息）
86
+ -- 说明：章节是小说最基本的叙事单元
79
87
  CREATE TABLE {SCHEMA}.chapters (
80
- id SERIAL PRIMARY KEY,
81
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id),
82
- chapter_number INT NOT NULL,
83
- global_chapter_number INT NOT NULL UNIQUE,
84
- title VARCHAR(300),
85
- synopsis_path TEXT,
86
- content_path TEXT,
87
- synopsis_summary TEXT,
88
- synopsis_keywords TEXT[],
89
- status VARCHAR(20) DEFAULT 'planned',
90
- word_count INT DEFAULT 0,
91
- scene_location VARCHAR(200),
92
- time_in_story VARCHAR(200),
93
- pov_character VARCHAR(100) DEFAULT '主角'
88
+ id SERIAL PRIMARY KEY,
89
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id), -- 所属卷ID
90
+ chapter_number INT NOT NULL, -- 卷内章节序号（第1章、第2章...）
91
+ global_chapter_number INT NOT NULL UNIQUE, -- 全局章节序号（全书第X章）
92
+ title VARCHAR(300), -- 章节标题
93
+ synopsis_path TEXT, -- 章节梗概文件路径
94
+ content_path TEXT, -- 章节正文文件路径
95
+ synopsis_summary TEXT, -- 梗概摘要（简短描述）
96
+ synopsis_keywords TEXT[], -- 关键词数组（用于检索和分类）
97
+ status VARCHAR(20) DEFAULT 'planned', -- 状态：planned/synopsis/draft/final
98
+ word_count INT DEFAULT 0, -- 字数
99
+ scene_location VARCHAR(200), -- 场景地点
100
+ time_in_story VARCHAR(200), -- 故事内时间（如：第XX天、辰时）
101
+ pov_character VARCHAR(100) DEFAULT '主角' -- 视角角色（POV）
94
102
  );
95
103
 
96
- -- 4) characters: 角色主表
104
+ -- 4) characters: 角色主表（记录所有角色的基本信息）
105
+ -- 说明：包括主角、配角、反派等所有重要角色
97
106
  CREATE TABLE {SCHEMA}.characters (
98
- id SERIAL PRIMARY KEY,
99
- name VARCHAR(100) NOT NULL UNIQUE,
100
- aliases TEXT[],
101
- role_type VARCHAR(50),
102
- first_appearance_vol INT,
103
- first_appearance_ch INT,
104
- cultivation_level VARCHAR(100),
105
- faction VARCHAR(200),
106
- status VARCHAR(20) DEFAULT 'active'
107
+ id SERIAL PRIMARY KEY,
108
+ name VARCHAR(100) NOT NULL UNIQUE, -- 角色名称（唯一）
109
+ aliases TEXT[], -- 别名/称呼数组
110
+ role_type VARCHAR(50), -- 角色类型：protagonist(主角)/supporting(配角)/antagonist(反派)/npc
111
+ first_appearance_vol INT, -- 首次登场卷号
112
+ first_appearance_ch INT, -- 首次登场章节号
113
+ cultivation_level VARCHAR(100), -- 修为等级/境界
114
+ faction VARCHAR(200), -- 所属阵营/势力
115
+ status VARCHAR(20) DEFAULT 'active' -- 状态：active(活跃)/deceased(死亡)/disappeared(消失)
107
116
  );
108
117
 
109
- -- 5) character_states: 角色状态快照（按卷）
118
+ -- 5) character_states: 角色状态快照表（按卷记录角色状态）
119
+ -- 说明：每个角色在每卷结束时的状态快照，用于追踪角色成长轨迹
110
120
  CREATE TABLE {SCHEMA}.character_states (
111
- id SERIAL PRIMARY KEY,
112
- character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id),
113
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id),
114
- cultivation_level VARCHAR(100),
115
- location VARCHAR(200),
116
- state_summary TEXT,
117
- last_appearance INT,
118
- UNIQUE(character_id, volume_id)
121
+ id SERIAL PRIMARY KEY,
122
+ character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id), -- 角色ID
123
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id), -- 卷ID
124
+ cultivation_level VARCHAR(100), -- 当前修为等级
125
+ location VARCHAR(200), -- 当前所在位置
126
+ state_summary TEXT, -- 状态摘要
127
+ last_appearance INT, -- 最后登场章节号
128
+ UNIQUE(character_id, volume_id) -- 每个角色每卷只有一条记录
119
129
  );
120
130
 
121
- -- 6) plot_threads: 情节线
131
+ -- 6) plot_threads: 情节线表（记录小说的主要情节线）
132
+ -- 说明：一条情节线可能跨越多卷，包含多个关键事件
122
133
  CREATE TABLE {SCHEMA}.plot_threads (
123
- id SERIAL PRIMARY KEY,
124
- name VARCHAR(200) NOT NULL,
125
- thread_type VARCHAR(50),
126
- status VARCHAR(30) DEFAULT 'active',
127
- description TEXT,
128
- start_volume_id INT REFERENCES {SCHEMA}.volumes(id),
129
- volume_id INT REFERENCES {SCHEMA}.volumes(id),
130
- key_events JSONB DEFAULT '[]'::jsonb
134
+ id SERIAL PRIMARY KEY,
135
+ name VARCHAR(200) NOT NULL, -- 情节线名称
136
+ thread_type VARCHAR(50), -- 情节类型：main(主线)/sub(支线)/background(暗线)
137
+ status VARCHAR(30) DEFAULT 'active', -- 状态：active(进行中)/resolved(已解决)/dormant(潜伏)
138
+ description TEXT, -- 情节线描述
139
+ start_volume_id INT REFERENCES {SCHEMA}.volumes(id), -- 起始卷ID
140
+ volume_id INT REFERENCES {SCHEMA}.volumes(id), -- 当前所属卷ID
141
+ key_events JSONB DEFAULT '[]'::jsonb -- 关键事件数组（JSON格式）
131
142
  );
132
143
 
133
- -- 7) foreshadowing: 伏笔
144
+ -- 7) foreshadowing: 伏笔表（记录埋设的伏笔）
145
+ -- 说明：记录伏笔的埋设、暗示和回收情况
134
146
  CREATE TABLE {SCHEMA}.foreshadowing (
135
- id SERIAL PRIMARY KEY,
136
- code VARCHAR(20) UNIQUE,
137
- plot_thread_id INT REFERENCES {SCHEMA}.plot_threads(id),
138
- description TEXT NOT NULL,
139
- planted_chapter_id INT REFERENCES {SCHEMA}.chapters(id),
140
- hinted_chapter_id INT REFERENCES {SCHEMA}.chapters(id),
141
- resolved_chapter_id INT REFERENCES {SCHEMA}.chapters(id),
142
- status VARCHAR(30) DEFAULT 'planted',
143
- importance VARCHAR(20) DEFAULT 'major',
144
- note TEXT
147
+ id SERIAL PRIMARY KEY,
148
+ code VARCHAR(20) UNIQUE, -- 伏笔编码（如：FP001、FATE-001）
149
+ plot_thread_id INT REFERENCES {SCHEMA}.plot_threads(id), -- 关联的情节线ID
150
+ description TEXT NOT NULL, -- 伏笔描述
151
+ planted_chapter_id INT REFERENCES {SCHEMA}.chapters(id), -- 埋设章节ID
152
+ hinted_chapter_id INT REFERENCES {SCHEMA}.chapters(id), -- 暗示章节ID（可选）
153
+ resolved_chapter_id INT REFERENCES {SCHEMA}.chapters(id), -- 解决章节ID（伏笔回收）
154
+ status VARCHAR(30) DEFAULT 'planted', -- 状态：planted(已埋设)/hinted(已暗示)/partially_resolved(部分解决)/resolved(已解决)
155
+ importance VARCHAR(20) DEFAULT 'major', -- 重要程度：major(重要)/minor(次要)/key(关键)
156
+ note TEXT -- 备注
145
157
  );
146
158
 
147
- -- 8) chapter_foreshadowing: 伏笔×章节关联
159
+ -- 8) chapter_foreshadowing: 伏笔×章节关联表
160
+ -- 说明：记录每个章节涉及哪些伏笔（埋设、暗示、解决）
148
161
  CREATE TABLE {SCHEMA}.chapter_foreshadowing (
149
- id SERIAL PRIMARY KEY,
150
- foreshadowing_id INT NOT NULL REFERENCES {SCHEMA}.foreshadowing(id),
151
- chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id),
152
- action_type VARCHAR(20) NOT NULL,
153
- UNIQUE(foreshadowing_id, chapter_id, action_type)
162
+ id SERIAL PRIMARY KEY,
163
+ foreshadowing_id INT NOT NULL REFERENCES {SCHEMA}.foreshadowing(id), -- 伏笔ID
164
+ chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id), -- 章节ID
165
+ action_type VARCHAR(20) NOT NULL, -- 动作类型：plant(埋设)/hint(暗示)/resolve(解决)
166
+ UNIQUE(foreshadowing_id, chapter_id, action_type) -- 同一伏笔在同一章节只有一种动作
154
167
  );
155
168
 
156
- -- 9) chapter_participants: 章节×角色关联
169
+ -- 9) chapter_participants: 章节角色参与表
170
+ -- 说明：记录每个章节有哪些角色出场，以及角色在章节中的定位
157
171
  CREATE TABLE {SCHEMA}.chapter_participants (
158
- id SERIAL PRIMARY KEY,
159
- chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id),
160
- character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id),
161
- role_in_chapter VARCHAR(50),
162
- UNIQUE(chapter_id, character_id)
172
+ id SERIAL PRIMARY KEY,
173
+ chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id), -- 章节ID
174
+ character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id), -- 角色ID
175
+ role_in_chapter VARCHAR(50), -- 章节中的角色作用：protagonist(主角)/supporting(配角)/antagonist(反派)/mentioned(提及)
176
+ UNIQUE(chapter_id, character_id) -- 同一角色在同一章节只出现一次
163
177
  );
164
178
 
165
- -- 10) relationships: 角色关系
179
+ -- 10) relationships: 角色关系表（记录角色之间的关系）
180
+ -- 说明：记录任意两个角色之间的关系，可按卷追踪关系变化
166
181
  CREATE TABLE {SCHEMA}.relationships (
167
- id SERIAL PRIMARY KEY,
168
- character_a_id INT NOT NULL REFERENCES {SCHEMA}.characters(id),
169
- character_b_id INT NOT NULL REFERENCES {SCHEMA}.characters(id),
170
- relationship_type VARCHAR(100),
171
- current_status TEXT,
172
- note TEXT,
173
- last_update_chapter INT,
174
- volume_id INT REFERENCES {SCHEMA}.volumes(id),
175
- UNIQUE(character_a_id, character_b_id, volume_id)
182
+ id SERIAL PRIMARY KEY,
183
+ character_a_id INT NOT NULL REFERENCES {SCHEMA}.characters(id), -- 角色A ID
184
+ character_b_id INT NOT NULL REFERENCES {SCHEMA}.characters(id), -- 角色B ID
185
+ relationship_type VARCHAR(100), -- 关系类型：friend(朋友)/enemy(敌人)/family(家人)/rival(对手)/mentor(师徒)等
186
+ current_status TEXT, -- 当前关系状态描述
187
+ note TEXT, -- 备注
188
+ last_update_chapter INT, -- 最后更新时的章节号
189
+ volume_id INT REFERENCES {SCHEMA}.volumes(id), -- 所属卷ID
190
+ UNIQUE(character_a_id, character_b_id, volume_id) -- 同一对角色在同一卷只有一条关系记录
176
191
  );
177
192
 
178
- -- 11) timeline_events: 时间线
193
+ -- 11) timeline_events: 时间线事件表
194
+ -- 说明：记录小说中的重要事件，按时间线排列
179
195
  CREATE TABLE {SCHEMA}.timeline_events (
180
- id SERIAL PRIMARY KEY,
181
- chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id),
182
- event_description TEXT NOT NULL,
183
- story_time VARCHAR(200),
184
- location VARCHAR(200),
185
- tags TEXT[] DEFAULT '{{}}',
186
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
196
+ id SERIAL PRIMARY KEY,
197
+ chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id), -- 关联章节ID
198
+ event_description TEXT NOT NULL, -- 事件描述
199
+ story_time VARCHAR(200), -- 故事内时间（如：黎明时分、三年后）
200
+ location VARCHAR(200), -- 事件发生地点
201
+ tags TEXT[] DEFAULT '{{}}', -- 标签数组（如：战斗、突破、死亡）
202
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
187
203
  );
188
204
 
189
- -- 12) cross_volume_refs: 跨卷引用
205
+ -- 12) cross_volume_refs: 跨卷引用表
206
+ -- 说明：记录章节之间的跨卷引用/呼应关系
190
207
  CREATE TABLE {SCHEMA}.cross_volume_refs (
191
- id SERIAL PRIMARY KEY,
192
- source_chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id),
193
- target_chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id),
194
- ref_type VARCHAR(50),
195
- description TEXT
208
+ id SERIAL PRIMARY KEY,
209
+ source_chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id), -- 源章节（引用方）
210
+ target_chapter_id INT NOT NULL REFERENCES {SCHEMA}.chapters(id), -- 目标章节（被引用方）
211
+ ref_type VARCHAR(50), -- 引用类型：callback(呼应)/foreshadow(前情提要)/parallel(平行)
212
+ description TEXT -- 描述
196
213
  );
197
214
 
198
- -- 13) character_key_changes: 角色章级变更历史
215
+ -- 13) character_key_changes: 角色关键变化表
216
+ -- 说明：记录角色在特定章节发生的重要变化/转折
199
217
  CREATE TABLE {SCHEMA}.character_key_changes (
200
- id SERIAL PRIMARY KEY,
201
- character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id),
202
- chapter_number INT NOT NULL,
203
- change_desc TEXT NOT NULL,
204
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
218
+ id SERIAL PRIMARY KEY,
219
+ character_id INT NOT NULL REFERENCES {SCHEMA}.characters(id), -- 角色ID
220
+ chapter_number INT NOT NULL, -- 变化发生的章节号
221
+ change_desc TEXT NOT NULL, -- 变化描述
222
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
205
223
  );
206
224
 
207
- -- 14) relationship_history: 关系变迁历史
225
+ -- 14) relationship_history: 关系变迁历史表
226
+ -- 说明：记录角色关系的演变历史
208
227
  CREATE TABLE {SCHEMA}.relationship_history (
209
- id SERIAL PRIMARY KEY,
210
- relationship_id INT NOT NULL REFERENCES {SCHEMA}.relationships(id),
211
- chapter_number INT NOT NULL,
212
- status_desc TEXT NOT NULL,
213
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
228
+ id SERIAL PRIMARY KEY,
229
+ relationship_id INT NOT NULL REFERENCES {SCHEMA}.relationships(id), -- 关系ID
230
+ chapter_number INT NOT NULL, -- 变化发生的章节号
231
+ status_desc TEXT NOT NULL, -- 状态描述
232
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
214
233
  );
215
234
 
216
- -- 15) plot_thread_events: 情节线关键事件（展开表）
235
+ -- 15) plot_thread_events: 情节线关键事件展开表
236
+ -- 说明：展开记录情节线中的每个关键事件
217
237
  CREATE TABLE {SCHEMA}.plot_thread_events (
218
- id SERIAL PRIMARY KEY,
219
- plot_thread_id INT NOT NULL REFERENCES {SCHEMA}.plot_threads(id),
220
- chapter_number INT NOT NULL,
221
- event_desc TEXT NOT NULL,
222
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
238
+ id SERIAL PRIMARY KEY,
239
+ plot_thread_id INT NOT NULL REFERENCES {SCHEMA}.plot_threads(id), -- 所属情节线ID
240
+ chapter_number INT NOT NULL, -- 事件发生的章节号
241
+ event_desc TEXT NOT NULL, -- 事件描述
242
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
223
243
  );
224
244
 
225
- -- 索引
226
- CREATE INDEX idx_chapters_volume ON {SCHEMA}.chapters(volume_id);
227
- CREATE INDEX idx_chapters_global ON {SCHEMA}.chapters(global_chapter_number);
228
- CREATE INDEX idx_char_states_vol ON {SCHEMA}.character_states(volume_id);
229
- CREATE INDEX idx_foreshadowing_status ON {SCHEMA}.foreshadowing(status);
230
- CREATE INDEX idx_timeline_chapter ON {SCHEMA}.timeline_events(chapter_id);
231
- CREATE INDEX idx_timeline_tags ON {SCHEMA}.timeline_events USING GIN(tags);
232
- CREATE INDEX idx_plot_threads_status ON {SCHEMA}.plot_threads(status);
233
- CREATE INDEX idx_plot_threads_vol ON {SCHEMA}.plot_threads(volume_id);
234
- CREATE INDEX idx_char_key_changes_char ON {SCHEMA}.character_key_changes(character_id);
235
- CREATE INDEX idx_char_key_changes_vol ON {SCHEMA}.character_key_changes(volume_id);
236
- CREATE INDEX idx_rel_history_rel ON {SCHEMA}.relationship_history(relationship_id);
237
- CREATE INDEX idx_rel_history_vol ON {SCHEMA}.relationship_history(volume_id);
238
- CREATE INDEX idx_plot_events_thread ON {SCHEMA}.plot_thread_events(plot_thread_id);
239
- CREATE INDEX idx_plot_events_vol ON {SCHEMA}.plot_thread_events(volume_id);
245
+ -- ============================================================
246
+ -- 索引（提升查询性能）
247
+ -- ============================================================
248
+
249
+ -- 章节相关索引
250
+ CREATE INDEX idx_chapters_volume ON {SCHEMA}.chapters(volume_id); -- 按卷查询章节
251
+ CREATE INDEX idx_chapters_global ON {SCHEMA}.chapters(global_chapter_number); -- 按全局章号查询
252
+
253
+ -- 角色状态索引
254
+ CREATE INDEX idx_char_states_vol ON {SCHEMA}.character_states(volume_id); -- 按卷查询角色状态
255
+
256
+ -- 伏笔相关索引
257
+ CREATE INDEX idx_foreshadowing_status ON {SCHEMA}.foreshadowing(status); -- 按状态查询伏笔
258
+
259
+ -- 时间线索引
260
+ CREATE INDEX idx_timeline_chapter ON {SCHEMA}.timeline_events(chapter_id); -- 按章节查询时间线
261
+ CREATE INDEX idx_timeline_tags ON {SCHEMA}.timeline_events USING GIN(tags); -- 按标签查询时间线
262
+
263
+ -- 情节线索引
264
+ CREATE INDEX idx_plot_threads_status ON {SCHEMA}.plot_threads(status); -- 按状态查询情节线
265
+ CREATE INDEX idx_plot_threads_vol ON {SCHEMA}.plot_threads(volume_id); -- 按卷查询情节线
266
+
267
+ -- 角色变化索引
268
+ CREATE INDEX idx_char_key_changes_char ON {SCHEMA}.character_key_changes(character_id); -- 按角色查询变化
269
+ CREATE INDEX idx_char_key_changes_vol ON {SCHEMA}.character_key_changes(volume_id); -- 按卷查询变化
270
+
271
+ -- 关系历史索引
272
+ CREATE INDEX idx_rel_history_rel ON {SCHEMA}.relationship_history(relationship_id); -- 按关系查询历史
273
+ CREATE INDEX idx_rel_history_vol ON {SCHEMA}.relationship_history(volume_id); -- 按卷查询关系历史
274
+
275
+ -- 情节线事件索引
276
+ CREATE INDEX idx_plot_events_thread ON {SCHEMA}.plot_thread_events(plot_thread_id); -- 按情节线查询事件
277
+ CREATE INDEX idx_plot_events_vol ON {SCHEMA}.plot_thread_events(volume_id); -- 按卷查询事件
278
+
279
+ -- ============================================================
280
+ -- 主角相关表（16-20）：记录主角的技能、背包、修炼进度等
281
+ -- ============================================================
240
282
 
241
283
  -- 16) protagonist_skills: 主角技能主表
284
+ -- 说明：记录主角学会的所有技能
242
285
  CREATE TABLE {SCHEMA}.protagonist_skills (
243
- id SERIAL PRIMARY KEY,
244
- skill_name VARCHAR(100) NOT NULL UNIQUE,
245
- skill_category VARCHAR(20) NOT NULL,
246
- skill_level VARCHAR(50),
247
- parent_skill_id INT REFERENCES {SCHEMA}.protagonist_skills(id),
248
- description TEXT,
249
- acquired_chapter INT NOT NULL,
250
- acquired_method VARCHAR(200),
251
- last_used_chapter INT,
252
- use_count INT DEFAULT 0,
253
- status VARCHAR(20) DEFAULT 'active'
286
+ id SERIAL PRIMARY KEY,
287
+ skill_name VARCHAR(100) NOT NULL UNIQUE, -- 技能名称
288
+ skill_category VARCHAR(20) NOT NULL, -- 技能分类：账本脑/符/阵/被动/功法等
289
+ skill_level VARCHAR(50), -- 技能等级：入门/固化/小成/大成
290
+ parent_skill_id INT REFERENCES {SCHEMA}.protagonist_skills(id), -- 父技能ID（技能树）
291
+ description TEXT, -- 技能描述/效果说明
292
+ acquired_chapter INT NOT NULL, -- 获得章节号
293
+ acquired_method VARCHAR(200), -- 获得方式：自悟/修炼突破/副本掉落/交易等
294
+ last_used_chapter INT, -- 最后使用章节号
295
+ use_count INT DEFAULT 0, -- 使用次数
296
+ status VARCHAR(20) DEFAULT 'active' -- 状态：active(可用)/locked(锁定)/forgotten(遗忘)
254
297
  );
255
298
 
256
299
  -- 17) protagonist_skill_events: 技能时序表
300
+ -- 说明：记录技能的每次使用/变化事件
257
301
  CREATE TABLE {SCHEMA}.protagonist_skill_events (
258
- id SERIAL PRIMARY KEY,
259
- skill_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_skills(id),
260
- chapter_number INT NOT NULL,
261
- event_type VARCHAR(30) NOT NULL,
262
- detail TEXT,
263
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
302
+ id SERIAL PRIMARY KEY,
303
+ skill_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_skills(id), -- 技能ID
304
+ chapter_number INT NOT NULL, -- 事件发生章节号
305
+ event_type VARCHAR(30) NOT NULL, -- 事件类型：acquired(获得)/upgraded(升级)/used(使用)/forgotten(遗忘)
306
+ detail TEXT, -- 事件详情
307
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
264
308
  );
265
309
 
266
- -- 18) protagonist_inventory: 装备/道具主表
310
+ -- 18) protagonist_inventory: 主角装备/道具主表
311
+ -- 说明：记录主角当前拥有的所有物品
267
312
  CREATE TABLE {SCHEMA}.protagonist_inventory (
268
- id SERIAL PRIMARY KEY,
269
- item_name VARCHAR(100) NOT NULL,
270
- item_type VARCHAR(30) NOT NULL,
271
- quantity INT DEFAULT 1,
272
- quality VARCHAR(30),
273
- description TEXT,
274
- acquired_chapter INT NOT NULL,
275
- acquired_method VARCHAR(200),
276
- status VARCHAR(20) DEFAULT 'held',
277
- UNIQUE(item_name, acquired_chapter)
313
+ id SERIAL PRIMARY KEY,
314
+ item_name VARCHAR(100) NOT NULL, -- 物品名称
315
+ item_type VARCHAR(30) NOT NULL, -- 物品类型：装备/材料/消耗品/工具
316
+ quantity INT DEFAULT 1, -- 数量
317
+ quality VARCHAR(30), -- 品质：普通/稀有/精良/史诗/传说
318
+ description TEXT, -- 物品描述
319
+ acquired_chapter INT NOT NULL, -- 获得章节号
320
+ acquired_method VARCHAR(200), -- 获得方式：拾取/交易/制作/副本掉落
321
+ status VARCHAR(20) DEFAULT 'held', -- 状态：held(持有)/consumed(已消耗)/equipped(装备中)
322
+ UNIQUE(item_name, acquired_chapter) -- 同一物品同名只能有一条记录
278
323
  );
279
324
 
280
325
  -- 19) protagonist_inventory_events: 道具时序表
326
+ -- 说明：记录物品的获取、使用、消耗等事件
281
327
  CREATE TABLE {SCHEMA}.protagonist_inventory_events (
282
- id SERIAL PRIMARY KEY,
283
- item_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_inventory(id),
284
- chapter_number INT NOT NULL,
285
- event_type VARCHAR(30) NOT NULL,
286
- quantity_change INT DEFAULT 0,
287
- detail TEXT,
288
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
328
+ id SERIAL PRIMARY KEY,
329
+ item_id INT NOT NULL REFERENCES {SCHEMA}.protagonist_inventory(id), -- 物品ID
330
+ chapter_number INT NOT NULL, -- 事件发生章节号
331
+ event_type VARCHAR(30) NOT NULL, -- 事件类型：acquired(获得)/used(使用)/lost(丢失)/given(赠予)
332
+ quantity_change INT DEFAULT 0, -- 数量变化（正数增加，负数减少）
333
+ detail TEXT, -- 事件详情
334
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
289
335
  );
290
336
 
291
337
  -- 20) protagonist_cultivation: 修炼进度表
338
+ -- 说明：记录主角的修炼突破历程
292
339
  CREATE TABLE {SCHEMA}.protagonist_cultivation (
293
- id SERIAL PRIMARY KEY,
294
- chapter_number INT NOT NULL,
295
- level VARCHAR(50) NOT NULL,
296
- progress_pct DECIMAL(5,1),
297
- breakthrough_type VARCHAR(20),
298
- trigger VARCHAR(200),
299
- detail TEXT,
300
- volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id)
340
+ id SERIAL PRIMARY KEY,
341
+ chapter_number INT NOT NULL, -- 记录发生的章节号
342
+ level VARCHAR(50) NOT NULL, -- 修炼等级/境界（如：段1·炼气前期）
343
+ progress_pct DECIMAL(5,1), -- 进度百分比（0-100）
344
+ breakthrough_type VARCHAR(20), -- 突破类型：major(大境界突破)/minor(小境界提升)
345
+ trigger VARCHAR(200), -- 触发原因：修炼突破/副本战斗/特殊事件
346
+ detail TEXT, -- 详情描述
347
+ volume_id INT NOT NULL REFERENCES {SCHEMA}.volumes(id) -- 所属卷ID
301
348
  );
302
349
 
303
- -- protagonist 索引
304
- CREATE INDEX idx_skills_category ON {SCHEMA}.protagonist_skills(skill_category);
305
- CREATE INDEX idx_skills_status ON {SCHEMA}.protagonist_skills(status);
306
- CREATE INDEX idx_skill_events_skill ON {SCHEMA}.protagonist_skill_events(skill_id);
307
- CREATE INDEX idx_skill_events_vol ON {SCHEMA}.protagonist_skill_events(volume_id);
308
- CREATE INDEX idx_skill_events_type ON {SCHEMA}.protagonist_skill_events(event_type);
309
- CREATE INDEX idx_inventory_type ON {SCHEMA}.protagonist_inventory(item_type);
310
- CREATE INDEX idx_inventory_status ON {SCHEMA}.protagonist_inventory(status);
311
- CREATE INDEX idx_inv_events_item ON {SCHEMA}.protagonist_inventory_events(item_id);
312
- CREATE INDEX idx_inv_events_vol ON {SCHEMA}.protagonist_inventory_events(volume_id);
313
- CREATE INDEX idx_cultivation_vol ON {SCHEMA}.protagonist_cultivation(volume_id);
314
- CREATE INDEX idx_cultivation_ch ON {SCHEMA}.protagonist_cultivation(chapter_number);
350
+ -- 主角相关索引
351
+ CREATE INDEX idx_skills_category ON {SCHEMA}.protagonist_skills(skill_category); -- 按技能分类查询
352
+ CREATE INDEX idx_skills_status ON {SCHEMA}.protagonist_skills(status); -- 按状态查询技能
353
+ CREATE INDEX idx_skill_events_skill ON {SCHEMA}.protagonist_skill_events(skill_id); -- 按技能查询事件
354
+ CREATE INDEX idx_skill_events_vol ON {SCHEMA}.protagonist_skill_events(volume_id); -- 按卷查询技能事件
355
+ CREATE INDEX idx_skill_events_type ON {SCHEMA}.protagonist_skill_events(event_type); -- 按事件类型查询
356
+
357
+ CREATE INDEX idx_inventory_type ON {SCHEMA}.protagonist_inventory(item_type); -- 按物品类型查询
358
+ CREATE INDEX idx_inventory_status ON {SCHEMA}.protagonist_inventory(status); -- 按状态查询背包
359
+ CREATE INDEX idx_inv_events_item ON {SCHEMA}.protagonist_inventory_events(item_id); -- 按物品查询事件
360
+ CREATE INDEX idx_inv_events_vol ON {SCHEMA}.protagonist_inventory_events(volume_id); -- 按卷查询背包事件
361
+
362
+ CREATE INDEX idx_cultivation_vol ON {SCHEMA}.protagonist_cultivation(volume_id); -- 按卷查询修炼进度
363
+ CREATE INDEX idx_cultivation_ch ON {SCHEMA}.protagonist_cultivation(chapter_number); -- 按章节查询修炼进度
364
+
365
+ -- ============================================================
366
+ -- 表和字段的中文注释（COMMENT ON）
367
+ -- ============================================================
368
+
369
+ -- phases 表注释
370
+ COMMENT ON TABLE {SCHEMA}.phases IS '纪元表：记录小说的时代/纪元划分，每个纪元代表小说中的一个完整时代';
371
+ COMMENT ON COLUMN {SCHEMA}.phases.id IS '主键ID';
372
+ COMMENT ON COLUMN {SCHEMA}.phases.phase_number IS '纪元编号（如：第1纪元、第2纪元）';
373
+ COMMENT ON COLUMN {SCHEMA}.phases.title IS '纪元标题/名称';
374
+ COMMENT ON COLUMN {SCHEMA}.phases.theme IS '纪元主题（如：觉醒、成长、决战等）';
375
+ COMMENT ON COLUMN {SCHEMA}.phases.vol_start IS '起始卷号（本纪元从哪一卷开始）';
376
+ COMMENT ON COLUMN {SCHEMA}.phases.vol_end IS '结束卷号（本纪元到哪一卷结束）';
377
+ COMMENT ON COLUMN {SCHEMA}.phases.protagonist_level_start IS '主角初始等级/境界';
378
+ COMMENT ON COLUMN {SCHEMA}.phases.protagonist_level_end IS '主角结束等级/境界';
379
+ COMMENT ON COLUMN {SCHEMA}.phases.stage_level IS '当前境界等级（如：炼气期、筑基期）';
380
+ COMMENT ON COLUMN {SCHEMA}.phases.growth_keyword IS '成长关键词（如：觉醒、突破、蜕变）';
381
+ COMMENT ON COLUMN {SCHEMA}.phases.core_conflict IS '核心冲突/矛盾';
382
+ COMMENT ON COLUMN {SCHEMA}.phases.status IS '状态：planned(计划中)/active(进行中)/completed(已完成)';
383
+
384
+ -- volumes 表注释
385
+ COMMENT ON TABLE {SCHEMA}.volumes IS '卷表：记录每卷的基本信息，卷是介于纪元和章节之间的单位';
386
+ COMMENT ON COLUMN {SCHEMA}.volumes.id IS '主键ID';
387
+ COMMENT ON COLUMN {SCHEMA}.volumes.phase_id IS '所属纪元ID';
388
+ COMMENT ON COLUMN {SCHEMA}.volumes.vol_number IS '卷号（如：第1卷、第2卷）';
389
+ COMMENT ON COLUMN {SCHEMA}.volumes.title IS '卷标题';
390
+ COMMENT ON COLUMN {SCHEMA}.volumes.arc_type IS '剧情弧类型（如：日常、副本、高潮）';
391
+ COMMENT ON COLUMN {SCHEMA}.volumes.instance_name IS '副本名称（如果有）';
392
+ COMMENT ON COLUMN {SCHEMA}.volumes.instance_type IS '副本类型（如：秘境、禁地、遗迹）';
393
+ COMMENT ON COLUMN {SCHEMA}.volumes.instance_level IS '副本等级/难度';
394
+ COMMENT ON COLUMN {SCHEMA}.volumes.protagonist_level_range IS '主角等级范围';
395
+ COMMENT ON COLUMN {SCHEMA}.volumes.chapter_count IS '章节数量（预估或实际）';
396
+ COMMENT ON COLUMN {SCHEMA}.volumes.outline_path IS '大纲文件路径';
397
+ COMMENT ON COLUMN {SCHEMA}.volumes.summary_path IS '卷概要文件路径';
398
+ COMMENT ON COLUMN {SCHEMA}.volumes.status IS '状态：planned(计划中)/writing(写作中)/completed(已完成)';
399
+
400
+ -- chapters 表注释
401
+ COMMENT ON TABLE {SCHEMA}.chapters IS '章节表：记录每个章节的详细信息，章节是小说最基本的叙事单元';
402
+ COMMENT ON COLUMN {SCHEMA}.chapters.id IS '主键ID';
403
+ COMMENT ON COLUMN {SCHEMA}.chapters.volume_id IS '所属卷ID';
404
+ COMMENT ON COLUMN {SCHEMA}.chapters.chapter_number IS '卷内章节序号（第1章、第2章...）';
405
+ COMMENT ON COLUMN {SCHEMA}.chapters.global_chapter_number IS '全局章节序号（全书第X章）';
406
+ COMMENT ON COLUMN {SCHEMA}.chapters.title IS '章节标题';
407
+ COMMENT ON COLUMN {SCHEMA}.chapters.synopsis_path IS '章节梗概文件路径';
408
+ COMMENT ON COLUMN {SCHEMA}.chapters.content_path IS '章节正文文件路径';
409
+ COMMENT ON COLUMN {SCHEMA}.chapters.synopsis_summary IS '梗概摘要（简短描述）';
410
+ COMMENT ON COLUMN {SCHEMA}.chapters.synopsis_keywords IS '关键词数组（用于检索和分类）';
411
+ COMMENT ON COLUMN {SCHEMA}.chapters.status IS '状态：planned(计划中)/synopsis(梗概)/draft(草稿)/final(定稿)';
412
+ COMMENT ON COLUMN {SCHEMA}.chapters.word_count IS '字数';
413
+ COMMENT ON COLUMN {SCHEMA}.chapters.scene_location IS '场景地点';
414
+ COMMENT ON COLUMN {SCHEMA}.chapters.time_in_story IS '故事内时间（如：第XX天、辰时）';
415
+ COMMENT ON COLUMN {SCHEMA}.chapters.pov_character IS '视角角色（POV）';
416
+
417
+ -- characters 表注释
418
+ COMMENT ON TABLE {SCHEMA}.characters IS '角色主表：记录所有角色的基本信息，包括主角、配角、反派等';
419
+ COMMENT ON COLUMN {SCHEMA}.characters.id IS '主键ID';
420
+ COMMENT ON COLUMN {SCHEMA}.characters.name IS '角色名称（唯一）';
421
+ COMMENT ON COLUMN {SCHEMA}.characters.aliases IS '别名/称呼数组';
422
+ COMMENT ON COLUMN {SCHEMA}.characters.role_type IS '角色类型：protagonist(主角)/supporting(配角)/antagonist(反派)/npc';
423
+ COMMENT ON COLUMN {SCHEMA}.characters.first_appearance_vol IS '首次登场卷号';
424
+ COMMENT ON COLUMN {SCHEMA}.characters.first_appearance_ch IS '首次登场章节号';
425
+ COMMENT ON COLUMN {SCHEMA}.characters.cultivation_level IS '修为等级/境界';
426
+ COMMENT ON COLUMN {SCHEMA}.characters.faction IS '所属阵营/势力';
427
+ COMMENT ON COLUMN {SCHEMA}.characters.status IS '状态：active(活跃)/deceased(死亡)/disappeared(消失)';
428
+
429
+ -- character_states 表注释
430
+ COMMENT ON TABLE {SCHEMA}.character_states IS '角色状态快照表：按卷记录角色状态，用于追踪角色成长轨迹';
431
+ COMMENT ON COLUMN {SCHEMA}.character_states.id IS '主键ID';
432
+ COMMENT ON COLUMN {SCHEMA}.character_states.character_id IS '角色ID';
433
+ COMMENT ON COLUMN {SCHEMA}.character_states.volume_id IS '卷ID';
434
+ COMMENT ON COLUMN {SCHEMA}.character_states.cultivation_level IS '当前修为等级';
435
+ COMMENT ON COLUMN {SCHEMA}.character_states.location IS '当前所在位置';
436
+ COMMENT ON COLUMN {SCHEMA}.character_states.state_summary IS '状态摘要';
437
+ COMMENT ON COLUMN {SCHEMA}.character_states.last_appearance IS '最后登场章节号';
438
+
439
+ -- plot_threads 表注释
440
+ COMMENT ON TABLE {SCHEMA}.plot_threads IS '情节线表：记录小说的主要情节线，可能跨越多卷';
441
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.id IS '主键ID';
442
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.name IS '情节线名称';
443
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.thread_type IS '情节类型：main(主线)/sub(支线)/background(暗线)';
444
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.status IS '状态：active(进行中)/resolved(已解决)/dormant(潜伏)';
445
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.description IS '情节线描述';
446
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.start_volume_id IS '起始卷ID';
447
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.volume_id IS '当前所属卷ID';
448
+ COMMENT ON COLUMN {SCHEMA}.plot_threads.key_events IS '关键事件数组（JSON格式）';
449
+
450
+ -- foreshadowing 表注释
451
+ COMMENT ON TABLE {SCHEMA}.foreshadowing IS '伏笔表：记录埋设的伏笔，包括埋设、暗示和回收情况';
452
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.id IS '主键ID';
453
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.code IS '伏笔编码（如：FP001、FATE-001）';
454
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.plot_thread_id IS '关联的情节线ID';
455
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.description IS '伏笔描述';
456
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.planted_chapter_id IS '埋设章节ID';
457
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.hinted_chapter_id IS '暗示章节ID（可选）';
458
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.resolved_chapter_id IS '解决章节ID（伏笔回收）';
459
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.status IS '状态：planted(已埋设)/hinted(已暗示)/partially_resolved(部分解决)/resolved(已解决)';
460
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.importance IS '重要程度：major(重要)/minor(次要)/key(关键)';
461
+ COMMENT ON COLUMN {SCHEMA}.foreshadowing.note IS '备注';
462
+
463
+ -- chapter_foreshadowing 表注释
464
+ COMMENT ON TABLE {SCHEMA}.chapter_foreshadowing IS '伏笔×章节关联表：记录每个章节涉及哪些伏笔';
465
+ COMMENT ON COLUMN {SCHEMA}.chapter_foreshadowing.id IS '主键ID';
466
+ COMMENT ON COLUMN {SCHEMA}.chapter_foreshadowing.foreshadowing_id IS '伏笔ID';
467
+ COMMENT ON COLUMN {SCHEMA}.chapter_foreshadowing.chapter_id IS '章节ID';
468
+ COMMENT ON COLUMN {SCHEMA}.chapter_foreshadowing.action_type IS '动作类型：plant(埋设)/hint(暗示)/resolve(解决)';
469
+
470
+ -- chapter_participants 表注释
471
+ COMMENT ON TABLE {SCHEMA}.chapter_participants IS '章节角色参与表：记录每个章节有哪些角色出场';
472
+ COMMENT ON COLUMN {SCHEMA}.chapter_participants.id IS '主键ID';
473
+ COMMENT ON COLUMN {SCHEMA}.chapter_participants.chapter_id IS '章节ID';
474
+ COMMENT ON COLUMN {SCHEMA}.chapter_participants.character_id IS '角色ID';
475
+ COMMENT ON COLUMN {SCHEMA}.chapter_participants.role_in_chapter IS '章节中的角色作用：protagonist(主角)/supporting(配角)/antagonist(反派)/mentioned(提及)';
476
+
477
+ -- relationships 表注释
478
+ COMMENT ON TABLE {SCHEMA}.relationships IS '角色关系表：记录角色之间的关系，可按卷追踪变化';
479
+ COMMENT ON COLUMN {SCHEMA}.relationships.id IS '主键ID';
480
+ COMMENT ON COLUMN {SCHEMA}.relationships.character_a_id IS '角色A ID';
481
+ COMMENT ON COLUMN {SCHEMA}.relationships.character_b_id IS '角色B ID';
482
+ COMMENT ON COLUMN {SCHEMA}.relationships.relationship_type IS '关系类型：friend(朋友)/enemy(敌人)/family(家人)/rival(对手)/mentor(师徒)等';
483
+ COMMENT ON COLUMN {SCHEMA}.relationships.current_status IS '当前关系状态描述';
484
+ COMMENT ON COLUMN {SCHEMA}.relationships.note IS '备注';
485
+ COMMENT ON COLUMN {SCHEMA}.relationships.last_update_chapter IS '最后更新时的章节号';
486
+ COMMENT ON COLUMN {SCHEMA}.relationships.volume_id IS '所属卷ID';
487
+
488
+ -- timeline_events 表注释
489
+ COMMENT ON TABLE {SCHEMA}.timeline_events IS '时间线事件表：记录小说中的重要事件，按时间线排列';
490
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.id IS '主键ID';
491
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.chapter_id IS '关联章节ID';
492
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.event_description IS '事件描述';
493
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.story_time IS '故事内时间（如：黎明时分、三年后）';
494
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.location IS '事件发生地点';
495
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.tags IS '标签数组（如：战斗、突破、死亡）';
496
+ COMMENT ON COLUMN {SCHEMA}.timeline_events.volume_id IS '所属卷ID';
497
+
498
+ -- cross_volume_refs 表注释
499
+ COMMENT ON TABLE {SCHEMA}.cross_volume_refs IS '跨卷引用表：记录章节之间的跨卷引用/呼应关系';
500
+ COMMENT ON COLUMN {SCHEMA}.cross_volume_refs.id IS '主键ID';
501
+ COMMENT ON COLUMN {SCHEMA}.cross_volume_refs.source_chapter_id IS '源章节（引用方）';
502
+ COMMENT ON COLUMN {SCHEMA}.cross_volume_refs.target_chapter_id IS '目标章节（被引用方）';
503
+ COMMENT ON COLUMN {SCHEMA}.cross_volume_refs.ref_type IS '引用类型：callback(呼应)/foreshadow(前情提要)/parallel(平行)';
504
+ COMMENT ON COLUMN {SCHEMA}.cross_volume_refs.description IS '描述';
505
+
506
+ -- character_key_changes 表注释
507
+ COMMENT ON TABLE {SCHEMA}.character_key_changes IS '角色关键变化表：记录角色在特定章节发生的重要变化/转折';
508
+ COMMENT ON COLUMN {SCHEMA}.character_key_changes.id IS '主键ID';
509
+ COMMENT ON COLUMN {SCHEMA}.character_key_changes.character_id IS '角色ID';
510
+ COMMENT ON COLUMN {SCHEMA}.character_key_changes.chapter_number IS '变化发生的章节号';
511
+ COMMENT ON COLUMN {SCHEMA}.character_key_changes.change_desc IS '变化描述';
512
+ COMMENT ON COLUMN {SCHEMA}.character_key_changes.volume_id IS '所属卷ID';
513
+
514
+ -- relationship_history 表注释
515
+ COMMENT ON TABLE {SCHEMA}.relationship_history IS '关系变迁历史表：记录角色关系的演变历史';
516
+ COMMENT ON COLUMN {SCHEMA}.relationship_history.id IS '主键ID';
517
+ COMMENT ON COLUMN {SCHEMA}.relationship_history.relationship_id IS '关系ID';
518
+ COMMENT ON COLUMN {SCHEMA}.relationship_history.chapter_number IS '变化发生的章节号';
519
+ COMMENT ON COLUMN {SCHEMA}.relationship_history.status_desc IS '状态描述';
520
+ COMMENT ON COLUMN {SCHEMA}.relationship_history.volume_id IS '所属卷ID';
521
+
522
+ -- plot_thread_events 表注释
523
+ COMMENT ON TABLE {SCHEMA}.plot_thread_events IS '情节线关键事件展开表：展开记录情节线中的每个关键事件';
524
+ COMMENT ON COLUMN {SCHEMA}.plot_thread_events.id IS '主键ID';
525
+ COMMENT ON COLUMN {SCHEMA}.plot_thread_events.plot_thread_id IS '所属情节线ID';
526
+ COMMENT ON COLUMN {SCHEMA}.plot_thread_events.chapter_number IS '事件发生的章节号';
527
+ COMMENT ON COLUMN {SCHEMA}.plot_thread_events.event_desc IS '事件描述';
528
+ COMMENT ON COLUMN {SCHEMA}.plot_thread_events.volume_id IS '所属卷ID';
529
+
530
+ -- protagonist_skills 表注释
531
+ COMMENT ON TABLE {SCHEMA}.protagonist_skills IS '主角技能主表：记录主角学会的所有技能';
532
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.id IS '主键ID';
533
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_name IS '技能名称';
534
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_category IS '技能分类：账本脑/符/阵/被动/功法等';
535
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.skill_level IS '技能等级：入门/固化/小成/大成';
536
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.parent_skill_id IS '父技能ID（技能树）';
537
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.description IS '技能描述/效果说明';
538
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.acquired_chapter IS '获得章节号';
539
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.acquired_method IS '获得方式：自悟/修炼突破/副本掉落/交易等';
540
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.last_used_chapter IS '最后使用章节号';
541
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.use_count IS '使用次数';
542
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skills.status IS '状态：active(可用)/locked(锁定)/forgotten(遗忘)';
543
+
544
+ -- protagonist_skill_events 表注释
545
+ COMMENT ON TABLE {SCHEMA}.protagonist_skill_events IS '技能时序表：记录技能的每次使用/变化事件';
546
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.id IS '主键ID';
547
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.skill_id IS '技能ID';
548
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.chapter_number IS '事件发生章节号';
549
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.event_type IS '事件类型：acquired(获得)/upgraded(升级)/used(使用)/forgotten(遗忘)';
550
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.detail IS '事件详情';
551
+ COMMENT ON COLUMN {SCHEMA}.protagonist_skill_events.volume_id IS '所属卷ID';
552
+
553
+ -- protagonist_inventory 表注释
554
+ COMMENT ON TABLE {SCHEMA}.protagonist_inventory IS '主角装备/道具主表：记录主角当前拥有的所有物品';
555
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.id IS '主键ID';
556
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.item_name IS '物品名称';
557
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.item_type IS '物品类型：装备/材料/消耗品/工具';
558
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.quantity IS '数量';
559
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.quality IS '品质：普通/稀有/精良/史诗/传说';
560
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.description IS '物品描述';
561
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.acquired_chapter IS '获得章节号';
562
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.acquired_method IS '获得方式：拾取/交易/制作/副本掉落';
563
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory.status IS '状态：held(持有)/consumed(已消耗)/equipped(装备中)';
564
+
565
+ -- protagonist_inventory_events 表注释
566
+ COMMENT ON TABLE {SCHEMA}.protagonist_inventory_events IS '道具时序表：记录物品的获取、使用、消耗等事件';
567
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.id IS '主键ID';
568
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.item_id IS '物品ID';
569
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.chapter_number IS '事件发生章节号';
570
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.event_type IS '事件类型：acquired(获得)/used(使用)/lost(丢失)/given(赠予)';
571
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.quantity_change IS '数量变化（正数增加，负数减少）';
572
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.detail IS '事件详情';
573
+ COMMENT ON COLUMN {SCHEMA}.protagonist_inventory_events.volume_id IS '所属卷ID';
574
+
575
+ -- protagonist_cultivation 表注释
576
+ COMMENT ON TABLE {SCHEMA}.protagonist_cultivation IS '修炼进度表：记录主角的修炼突破历程';
577
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.id IS '主键ID';
578
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.chapter_number IS '记录发生的章节号';
579
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.level IS '修炼等级/境界（如：段1·炼气前期）';
580
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.progress_pct IS '进度百分比（0-100）';
581
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.breakthrough_type IS '突破类型：major(大境界突破)/minor(小境界提升)';
582
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.trigger IS '触发原因：修炼突破/副本战斗/特殊事件';
583
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.detail IS '详情描述';
584
+ COMMENT ON COLUMN {SCHEMA}.protagonist_cultivation.volume_id IS '所属卷ID';
315
585
  """
316
586
 
317
587
  VIEWS = f"""
588
+ -- 写作仪表盘视图：按纪元统计卷、章节、字数等汇总信息
318
589
  CREATE OR REPLACE VIEW {SCHEMA}.writing_dashboard AS
319
590
  SELECT
320
591
  p.phase_number,
@@ -331,6 +602,7 @@ LEFT JOIN {SCHEMA}.chapters ch ON ch.volume_id = v.id
331
602
  GROUP BY p.id, p.phase_number, p.title
332
603
  ORDER BY p.phase_number;
333
604
 
605
+ -- 未解决伏笔视图：显示所有未回收的伏笔
334
606
  CREATE OR REPLACE VIEW {SCHEMA}.open_foreshadowing AS
335
607
  SELECT
336
608
  f.code, f.description, f.status,
@@ -342,6 +614,7 @@ JOIN {SCHEMA}.chapters ch ON f.planted_chapter_id = ch.id
342
614
  WHERE f.status IN ('planted', 'hinted', 'partially_resolved')
343
615
  ORDER BY ch.chapter_number;
344
616
 
617
+ -- 角色总览视图：显示所有角色的状态和在各卷的位置
345
618
  CREATE OR REPLACE VIEW {SCHEMA}.character_overview AS
346
619
  SELECT
347
620
  c.name, c.role_type, c.status,
@@ -352,12 +625,14 @@ LEFT JOIN {SCHEMA}.character_states cs ON c.id = cs.character_id
352
625
  LEFT JOIN {SCHEMA}.volumes v ON cs.volume_id = v.id
353
626
  ORDER BY c.name, v.vol_number;
354
627
 
628
+ -- 当前背包视图：显示主角当前持有的物品
355
629
  CREATE OR REPLACE VIEW {SCHEMA}.current_inventory AS
356
630
  SELECT item_name, item_type, quantity, quality, description, acquired_chapter
357
631
  FROM {SCHEMA}.protagonist_inventory
358
632
  WHERE status = 'held'
359
633
  ORDER BY item_type, item_name;
360
634
 
635
+ -- 技能总览视图：显示所有技能的概览信息及使用统计
361
636
  CREATE OR REPLACE VIEW {SCHEMA}.skill_overview AS
362
637
  SELECT s.skill_name, s.skill_category, s.skill_level, s.status,
363
638
  s.acquired_chapter, s.use_count,
@@ -367,10 +642,73 @@ LEFT JOIN {SCHEMA}.protagonist_skill_events e ON s.id = e.skill_id
367
642
  GROUP BY s.id
368
643
  ORDER BY s.skill_category, s.acquired_chapter;
369
644
 
645
+ -- 修炼进度曲线视图：按章节展示修炼进度变化
370
646
  CREATE OR REPLACE VIEW {SCHEMA}.cultivation_curve AS
371
647
  SELECT chapter_number, level, progress_pct, breakthrough_type, trigger
372
648
  FROM {SCHEMA}.protagonist_cultivation
373
649
  ORDER BY chapter_number;
650
+
651
+ -- ============================================================
652
+ -- 视图的中文注释（COMMENT ON）
653
+ -- ============================================================
654
+
655
+ -- writing_dashboard 视图注释
656
+ COMMENT ON VIEW {SCHEMA}.writing_dashboard IS '写作仪表盘：按纪元统计卷、章节、字数等汇总信息';
657
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.phase_number IS '纪元编号';
658
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.phase_title IS '纪元标题';
659
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.total_volumes IS '总卷数';
660
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.completed_volumes IS '已完成卷数';
661
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.total_chapters IS '总章节数';
662
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.final_chapters IS '定稿章节数';
663
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.synopsis_chapters IS '已写梗概章节数';
664
+ COMMENT ON COLUMN {SCHEMA}.writing_dashboard.total_words IS '总字数';
665
+
666
+ -- open_foreshadowing 视图注释
667
+ COMMENT ON VIEW {SCHEMA}.open_foreshadowing IS '未解决伏笔：显示所有未回收的伏笔';
668
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.code IS '伏笔编码';
669
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.description IS '伏笔描述';
670
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.status IS '伏笔状态';
671
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.planted_at IS '埋设章节号';
672
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.planted_time IS '埋设时间';
673
+ COMMENT ON COLUMN {SCHEMA}.open_foreshadowing.note IS '备注';
674
+
675
+ -- character_overview 视图注释
676
+ COMMENT ON VIEW {SCHEMA}.character_overview IS '角色总览：显示所有角色的状态和在各卷的位置';
677
+ COMMENT ON COLUMN {SCHEMA}.character_overview.name IS '角色名称';
678
+ COMMENT ON COLUMN {SCHEMA}.character_overview.role_type IS '角色类型';
679
+ COMMENT ON COLUMN {SCHEMA}.character_overview.status IS '角色状态';
680
+ COMMENT ON COLUMN {SCHEMA}.character_overview.location IS '所在位置';
681
+ COMMENT ON COLUMN {SCHEMA}.character_overview.state_summary IS '状态摘要';
682
+ COMMENT ON COLUMN {SCHEMA}.character_overview.last_appearance IS '最后登场章节';
683
+ COMMENT ON COLUMN {SCHEMA}.character_overview.vol_number IS '卷号';
684
+ COMMENT ON COLUMN {SCHEMA}.character_overview.volume_title IS '卷标题';
685
+
686
+ -- current_inventory 视图注释
687
+ COMMENT ON VIEW {SCHEMA}.current_inventory IS '当前背包：显示主角当前持有的物品';
688
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.item_name IS '物品名称';
689
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.item_type IS '物品类型';
690
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.quantity IS '数量';
691
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.quality IS '品质';
692
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.description IS '物品描述';
693
+ COMMENT ON COLUMN {SCHEMA}.current_inventory.acquired_chapter IS '获得章节';
694
+
695
+ -- skill_overview 视图注释
696
+ COMMENT ON VIEW {SCHEMA}.skill_overview IS '技能总览：显示所有技能的概览信息及使用统计';
697
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_name IS '技能名称';
698
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_category IS '技能分类';
699
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.skill_level IS '技能等级';
700
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.status IS '技能状态';
701
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.acquired_chapter IS '获得章节';
702
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.use_count IS '使用次数';
703
+ COMMENT ON COLUMN {SCHEMA}.skill_overview.total_events IS '事件总数';
704
+
705
+ -- cultivation_curve 视图注释
706
+ COMMENT ON VIEW {SCHEMA}.cultivation_curve IS '修炼进度曲线：按章节展示修炼进度变化';
707
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.chapter_number IS '章节号';
708
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.level IS '修炼等级';
709
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.progress_pct IS '进度百分比';
710
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.breakthrough_type IS '突破类型';
711
+ COMMENT ON COLUMN {SCHEMA}.cultivation_curve.trigger IS '触发原因';
374
712
  """
375
713
 
376
714