# 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 | 解锁条件表达式 |