提交

2026-05-28 20:23:32 +08:00
commit f6c8230248
7 changed files with 402827 additions and 0 deletions
--- a/quest_schema.md
+++ b/quest_schema.md
@@ -0,0 +1,351 @@
+# Quest 表数据建模文档
+
+## 1. 表概述
+
+`quest` 表用于存储游戏中的任务数据，包括主线任务、日常任务、周常任务、成就等多种任务类型。
+
+## 2. 字段定义
+
+### 2.1 字段列表
+
+| 字段名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| id | int | 是 | - | 任务唯一标识 |
+| category | int | 是 | - | 任务类型 |
+| next | int | 否 | 0 | 下一个任务ID |
+| desc | string | 是 | - | 任务描述 |
+| type | int | 是 | - | 任务行为类型 |
+| target | int | 是 | - | 任务目标值 |
+| openUI_type | int | 是 | - | 界面跳转类型 |
+| openUI_desc | string | 是 | - | 界面跳转描述 |
+| rewards | string[] | 否 | - | 任务奖励 |
+| score | int | 是 | 0 | 任务积分 |
+| auto | int | 是 | 0 | 自动领奖标识 |
+| extra | string | 否 | null | 额外数据 |
+
+### 2.2 字段详细定义
+
+#### 2.2.1 id 字段
+
+**类型**: int  
+**约束**: 必须唯一，不允许重复
+
+**构成规则**: `category类型数字 + 4位序号（从0001开始）`
+
+**格式示例**:
+- category=1(主线) → 10001, 10002, 10003...
+- category=2(日常) → 20001, 20002, 20003...
+- category=9(成就) → 90001, 90002, 90003...
+
+**校验规则**:
+- 必须为5位数字
+- 第一位必须与category字段匹配
+- 后四位必须从0001开始连续递增
+
+#### 2.2.2 category 字段（任务类型）
+
+**类型**: int  
+**约束**: 枚举值
+
+**允许值**:
+
+| 值 | 描述 |
+|----|------|
+| 1 | 主线任务 |
+| 2 | 日常任务 |
+| 3 | 通行证任务 |
+| 4 | 修炼任务 |
+| 5 | 周常任务 |
+| 6 | 公会任务 |
+| 7 | 委托任务 |
+| 8 | 称号任务 |
+| 9 | 成就任务 |
+| 10 | 七日任务 |
+
+#### 2.2.3 next 字段
+
+**类型**: int  
+**约束**: 非负整数，根据category字段决定
+
+**填写规则**:
+1. 当category=1(主线任务)时：
+   - 如果存在后续任务，填写下一个任务的ID
+   - 如果不存在后续任务（当前为流程终点），填写0
+2. 当category≠1时：
+   - 无论是否存在后续任务，统一填写0
+
+**说明**:
+- 表示当前任务完成后解锁的下一个任务ID
+- 值为0表示没有后续任务或当前任务分类不需要链式任务
+
+#### 2.2.4 desc 字段（任务描述）
+
+**类型**: string  
+**约束**: 必须与type和target字段关联
+
+**生成规则**: `type字段对应的中文描述 + target字段的数值（格式化后）+ 单位`
+
+**数值单位转换规则**:
+- 当数值 >= 100000000（1亿）时，转换为"亿"为单位，保留整数（例如：500000000 → "5亿"）
+- 当数值 >= 10000（1万）且 < 100000000（1亿）时，转换为"万"为单位，保留整数（例如：9000000 → "900万"）
+- 当数值 < 10000（1万）时，保持原数值（例如：1000 → "1000"）
+
+**文本格式规范**:
+- 所有描述文本必须以中文句号"。"结尾
+- 不得使用英文句号"."或其他符号结尾
+
+**示例**:
+- type=9(消耗X金币), target=1000 → "消耗1000金币。"
+- type=9(消耗X金币), target=9000000 → "消耗900万金币。"
+- type=9(消耗X金币), target=500000000 → "消耗5亿金币。"
+- type=1(招募X次), target=5 → "招募5次。"
+
+**校验规则**: 
+- desc字段必须能通过type和target字段反向推导验证
+- 必须符合数值单位转换规则
+- 必须以中文句号"。"结尾
+
+#### 2.2.5 type 字段（任务行为类型）
+
+**类型**: int  
+**约束**: 枚举值，根据category字段决定取值范围
+
+**允许值及对应描述（category≠9时）**:
+
+| 值 | 描述 |
+|----|------|
+| 1 | 招募X次 |
+| 2 | 英雄升级X次 |
+| 3 | 英雄升阶X次 |
+| 4 | 主角升级X次 |
+| 5 | 装备升级X次 |
+| 6 | 通过X关主线关卡 |
+| 7 | 通过X波敌人 |
+| 8 | 商店消费X次 |
+| 9 | 消耗X金币 |
+| 10 | 消耗X钻石 |
+| 11 | 登录X天 |
+| 12 | 开X次宝箱 |
+| 13 | 挑战X次副本 |
+| 14 | 挑战X次竞技场 |
+| 15 | 获得X个英雄 |
+| 16 | 领取X次游历奖励 |
+| 17 | 世界频道发言X次 |
+
+**允许值及对应描述（category=9成就任务时）**:
+
+| 值 | 描述 |
+|----|------|
+| 1 | 累计招募X次 |
+| 2 | 英雄累计升级X次 |
+| 3 | 英雄累计升阶X次 |
+| 4 | 主角累计升级X次 |
+| 5 | 装备累计升级X次 |
+| 6 | 累计通关X关主线关卡 |
+| 7 | 累计通关X波敌人 |
+| 8 | 商店累计消费X次 |
+| 9 | 累计消耗X金币 |
+| 10 | 累计消耗X钻石 |
+| 11 | 累计登录X天 |
+| 12 | 无X |
+| 13 | 累计挑战副本X次 |
+| 14 | 累计挑战竞技场X次 |
+| 15 | 累计获得X位英雄 |
+| 16 | 累计领取X次挂机奖励 |
+| 17 | 累计消耗X秒 |
+| 18 | 累计点赞好友X次 |
+| 19 | 累计英雄委托X次 |
+| 20 | 累计击败X个敌人 |
+| 21 | 战力达到X万 |
+| 22 | 主角到达X阶 |
+| 23 | 累计委托X次 |
+
+#### 2.2.6 target 字段（任务目标值）
+
+**类型**: int  
+**约束**: 正整数
+
+**说明**: 存储任务目标的具体数值，如"招募5次"中的5
+
+#### 2.2.7 openUI_type 字段（界面跳转类型）
+
+**类型**: int  
+**约束**: 枚举值，由type字段决定
+
+**允许值及对应描述**:
+
+| 值 | 描述 |
+|----|------|
+| 1 | UI_MainPanel |
+| 2 | UI_DrawCardPanel |
+| 3 | UI_ShopPanel |
+| 4 | UI_FBPanel |
+| 5 | UI_IdlePanel |
+| 6 | UI_ChatPanel |
+| 7 | UI_EquipPanel |
+| 8 | UI_HeroPanel |
+| 9 | UI_FriendPanel |
+| 10 | UI_ArePanel |
+
+**type与openUI_type映射关系**:
+
+| type | openUI_type | openUI_desc |
+|------|-------------|-------------|
+| 1 | 2 | UI_DrawCardPanel |
+| 2 | 8 | UI_HeroPanel |
+| 3 | 8 | UI_HeroPanel |
+| 4 | 8 | UI_HeroPanel |
+| 5 | 7 | UI_EquipPanel |
+| 6 | 1 | UI_MainPanel |
+| 7 | 1 | UI_MainPanel |
+| 8 | 3 | UI_ShopPanel |
+| 9 | 3 | UI_ShopPanel |
+| 10 | 3 | UI_ShopPanel |
+| 11 | 1 | UI_MainPanel |
+| 12 | 1 | UI_MainPanel |
+| 13 | 4 | UI_FBPanel |
+| 14 | 10 | UI_ArePanel |
+| 15 | 2 | UI_DrawCardPanel |
+| 16 | 5 | UI_IdlePanel |
+| 17 | 6 | UI_ChatPanel |
+
+#### 2.2.8 openUI_desc 字段（界面跳转描述）
+
+**类型**: string  
+**约束**: 必须与openUI_type字段严格对应
+
+**对应关系**:
+
+| openUI_type | openUI_desc |
+|-------------|-------------|
+| 1 | UI_MainPanel |
+| 2 | UI_DrawCardPanel |
+| 3 | UI_ShopPanel |
+| 4 | UI_FBPanel |
+| 5 | UI_IdlePanel |
+| 6 | UI_ChatPanel |
+| 7 | UI_EquipPanel |
+| 8 | UI_HeroPanel |
+| 9 | UI_FriendPanel |
+| 10 | UI_ArePanel |
+
+#### 2.2.9 rewards 字段（任务奖励）
+
+**类型**: string[]  
+**格式**: `item_<物品ID>_<数量>,item_<物品ID>_<数量>,...`
+
+**示例**: `item_10000001_2400,item_10000002_50`
+
+#### 2.2.10 score 字段（任务积分）
+
+**类型**: int  
+**约束**: 根据category字段计算
+
+**取值规则**:
+
+| category | score |
+|----------|-------|
+| 2(日常) | 20 |
+| 5(周常) | 20 |
+| 6(公会) | 20 |
+| 10(七日任务) | 20 |
+| 9(成就) | 25 |
+| 其他 | 0 |
+
+#### 2.2.11 auto 字段
+
+**类型**: int  
+**约束**: 固定值
+
+**允许值**:
+- 0: 否（手动领奖）
+
+#### 2.2.12 extra 字段
+
+**类型**: string  
+**约束**: 固定值
+
+**允许值**:
+- null: 无额外数据
+
+## 3. 数据校验规则
+
+### 3.1 字段级校验
+
+| 字段 | 校验规则 | 错误类型 |
+|------|----------|----------|
+| id | 必须为5位数字，第一位与category匹配，后四位从0001开始 | 格式错误/重复/不连续 |
+| category | 必须在1-10范围内 | 枚举值错误 |
+| next | 必须为非负整数，若不为0则必须存在对应id | 范围错误/引用错误 |
+| desc | 必须符合type+target的组合规则（category=9时使用成就映射） | 格式错误/逻辑错误 |
+| type | category=9时必须在1-23范围内；其他category必须在1-17范围内 | 枚举值错误 |
+| target | 必须为正整数 | 范围错误 |
+| openUI_type | 必须与type字段正确映射 | 映射错误 |
+| openUI_desc | 必须与openUI_type字段正确对应 | 映射错误 |
+| score | 必须根据category字段正确计算 | 计算错误 |
+| auto | 必须为0 | 固定值错误 |
+| extra | 必须为null | 固定值错误 |
+
+### 3.2 记录级校验
+
+1. **id唯一性**: 所有记录的id字段必须唯一
+2. **外键引用**: next字段引用的id必须存在
+3. **逻辑一致性**: desc、type、target三者必须保持逻辑一致
+4. **界面跳转一致性**: openUI_type、openUI_desc、type三者必须保持一致
+
+## 4. 数据索引设计
+
+### 4.1 索引字段
+
+| 索引名 | 字段 | 类型 | 说明 |
+|--------|------|------|------|
+| idx_id | id | 主键 | 唯一标识，快速查询 |
+| idx_category | category | 普通索引 | 按任务类型检索 |
+| idx_type | type | 普通索引 | 按行为类型检索 |
+
+### 4.2 检索方式
+
+- **按id查询**: `SELECT * FROM quest WHERE id = ?`
+- **按category查询**: `SELECT * FROM quest WHERE category = ?`
+- **按type查询**: `SELECT * FROM quest WHERE type = ?`
+- **组合查询**: `SELECT * FROM quest WHERE category = ? AND type = ?`
+
+## 5. 数据导入导出规范
+
+### 5.1 CSV文件格式
+
+- **编码**: UTF-8
+- **分隔符**: 逗号(,)
+- **文件位置**: `csv_output/quest.csv`
+- **首行**: 字段名（英文）
+- **第二行**: 字段类型
+- **第三行**: 字段说明
+- **数据行**: 从第四行开始
+
+### 5.2 格式示例
+
+```csv
+id,category,next,desc,type,target,openUI_type,openUI_desc,rewards,score,auto,extra
+int,int,int,string,int,int,int,string,string[],int,int,string
+主键,分类,下一个任务,描述,子类型,任务目标,打开界面类型,打开界面描述,奖励,每日任务活跃度,自动领奖,额外数据
+10001,1,10002,通过1关主线关卡,6,1,1,UI_MainPanel,"item_10000001_2400,item_10000002_50",0,0,null
+```
+
+## 6. 扩展计划
+
+### 6.1 待扩展表格
+
+| 表格名 | 用途 | 优先级 |
+|--------|------|--------|
+| quest_progress | 玩家任务进度 | 高 |
+| quest_group | 任务组/任务链 | 中 |
+| quest_condition | 任务解锁条件 | 中 |
+
+### 6.2 未来扩展字段
+
+| 字段名 | 类型 | 用途 |
+|--------|------|------|
+| start_time | datetime | 任务开始时间 |
+| end_time | datetime | 任务结束时间 |
+| repeat_type | int | 重复类型（每日/每周/一次性） |
+| unlock_condition | string | 解锁条件表达式 |