# 配置表 CSV 固定格式说明

本文档基于 `../samples/skill_list2.csv`、`../index.html` 和表格编辑器的实际读取逻辑整理。后续如果要手写或维护同类 CSV，优先按 `../samples/Sample.csv` 的结构来写。

注意：`../samples/Sample.csv` 里的 `skill_id`、`skill_name`、`skill_quality` 等只是技能表示例字段。后续做其他配置表时，这些字段名、中文标题、类型、必填规则、导出规则都可以按业务修改。真正固定的是配置行格式、行标记、字段对齐关系和 CSV 写法。

## 一句话结论

这个 CSV 不是普通“第一行表头”的格式。它前 10 行是元数据区，`COLUMNS::` 定义字段名，`TYPES::` 定义字段类型，`TYPES::` 之后才是注释行和正式数据行。字段内容可以变，但这些元数据行必须存在，并且每一列必须一一对齐。

## 工具行为

- 表格编辑器适合直接打开并编辑这种完整配置 CSV。它会读取 `TBLNM::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::`，并在下载时保留元数据区。
- `../index.html` 适合从 Excel 导出“筛选后的数据 CSV/JSON”。它会按 `EXPCOL::` 过滤导出列，并按 `PK`、`REQUIRED` 做校验。
- 注意：`../index.html` 的 CSV 导出结果不等同于 `../samples/skill_list2.csv` 这种完整源格式。它会只导出 `EXPCOL::` 标记的列，因此不适合作为完整模板的再编辑源。

## 固定与可变

固定部分：

- A 列的控制标记，例如 `TBLNM::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::`。
- `REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::` 这些配置行必须存在。
- 同一字段在所有配置行里必须占用同一列。例如 C 列如果是 `skill_id`，那么 C 列的 `REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`TYPES::` 都是在描述这个字段。
- `TYPES::` 之后才开始写注释行或数据行。
- 正式数据行 A 列留空；注释行 A 列以 `#` 开头。

可变部分：

- `TBLNM::` 后面的表名可以改，例如从 `skill_list` 改成其他配置表名。
- `# 标题` 行的中文显示名可以改。
- `COLUMNS::` 后面的字段名可以改，例如 `skill_id`、`skill_name` 都不是固定字段。
- `TYPES::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::` 可以随字段调整。
- 字段数量可以增加或减少，但每一行的列数和字段位置要同步调整。

请保持这些行的顺序和含义：

| 行 | A 列标记 | 作用 |
| --- | --- | --- |
| 1 | `# 备注` | 表的中文说明，B 列可写当前表的中文名 |
| 2 | `TBLNM::` | 表名，B 列为内部表名，例如 `skill_list` 或其他配置表名 |
| 3 | 空行 | 分隔 |
| 4 | `REQUIRED::` | 从 B 列开始标记字段是否必填，使用 `TRUE` 或 `FALSE` |
| 5 | `COL-OPT::` | 字段选项，常用 `PK` 表示主键，`VER` 表示版本字段 |
| 6 | `EXPCOL::` | 是否导出，`TRUE` 导出，`FALSE` 或空值不导出 |
| 7 | 空行 | 分隔 |
| 8 | `# 标题` | 中文显示名。以 `#` 开头且与前一列标题同名时，会被编辑器当作提示列 |
| 9 | `COLUMNS::` | 程序字段名，后续逻辑依赖这一行 |
| 10 | `TYPES::` | 字段类型，例如 `INT`、`STRING`、`ENUM`、`long(14)` |
| 11+ | 空白或 `#`/数据 | `#` 开头为注释行，A 列为空为正式数据行 |

## 示例字段含义

下面字段来自 `../samples/Sample.csv` / `../samples/skill_list2.csv`，只是技能表样例。做其他表时可以替换成自己的字段。

| CSV 列 | 示例字段名 | 类型 | 示例规则 |
| --- | --- | --- | --- |
| A | 控制列 | - | 正式数据行留空；注释行以 `#` 开头；配置行写 `xxx::` |
| B | `version` | `long(14)` | 版本字段，`COL-OPT::` 为 `VER`，默认不导出 |
| C | `skill_id` | `INT` | 主键，必填，必须为整数，建议全表唯一 |
| D | `skill_name` | `STRING` | 技能名称，必填 |
| E | `skill_quality` | `ENUM` | 技能品质，必填。参考值：`Common`、`Fine`、`Rare`、`Epic`、`Legendary`、`Mythic` |
| F | `s_deck` | `STRING` | 技能品质中文说明，例如“白色 普通”，辅助阅读，默认不导出 |
| G | `skill_type` | `ENUM` | 技能类型，必填。参考值：`ActiveSkill`、`PassiveSkill`、`AuraSkill`、`TriggerSkill`、`ClassSkill`、`PermanentSkill` |
| H | `st_deck` | `STRING` | 技能类型中文说明，例如“主动技能”，辅助阅读，默认不导出 |
| I | `skill_prototype_group` | `STRING` | 技能原型组，必填，关联 `skill_prototype_config` |
| J | `animation_id` | `STRING` | 效果动画，非必填，但当前配置为导出列 |
| K | `skill_description` | `STRING` | 技能描述，必填 |
| L | `note` | `STRING` | 内部备注，非必填，当前 `EXPCOL::` 为空，Excel 转换导出时不会导出 |
| M-O | 预留 | - | 这是样例里的预留列；如果你的表需要更多字段，可以把预留列改成正式字段，但要同步更新所有配置行 |

## 修改字段时的检查清单

- 改字段名：更新 `COLUMNS::` 对应列。
- 改中文显示：更新 `# 标题` 对应列。
- 改类型：更新 `TYPES::` 对应列。
- 改是否必填：更新 `REQUIRED::` 对应列，只写 `TRUE` 或 `FALSE`。
- 改是否导出：更新 `EXPCOL::` 对应列，导出写 `TRUE`，不导出写 `FALSE` 或留空。
- 改主键：更新 `COL-OPT::`，主键列写 `PK`。转换工具会跳过主键为空的数据行。
- 改版本字段：更新 `COL-OPT::`，版本列写 `VER`。
- 增删字段：所有元数据行和数据行都要同步增删对应列，避免列错位。

## 数据行写法

- 正式数据行的 A 列必须留空，例如：`,,900001,示例主动技能,...`
- 注释行的 A 列以 `#` 开头，例如：`# 备注,-,查看备注,...`
- 在当前技能表示例中，`skill_id` 是主键。其他表请以自己的 `COL-OPT::` 里标记为 `PK` 的字段为准；主键为空的数据行会被转换工具跳过。
- 在当前技能表示例中，必填列是 `skill_id`、`skill_name`、`skill_quality`、`skill_type`、`skill_prototype_group`、`skill_description`。其他表请以自己的 `REQUIRED::` 行为准。
- 在当前技能表示例中，`skill_prototype_group` 如果只有一个值，可以写 `[101]`；如果包含英文逗号，必须用英文双引号包起来，例如 `"[103,113]"`。
- 单元格中只要包含英文逗号 `,`、英文双引号 `"`、换行符，就必须按 CSV 规则加英文双引号；单元格内的英文双引号要写成两个双引号。
- 中文逗号 `，` 不是分隔符，不强制加引号。
- 文件建议使用 UTF-8 编码。工具可以读取带 BOM 的 UTF-8，下载 CSV 时也会带 BOM，方便 Excel 打开中文。

## 常见坑

- 不要删除 `REQUIRED::`、`COL-OPT::`、`EXPCOL::`、`COLUMNS::`、`TYPES::` 这几行，否则转换工具会判定文件无效。
- 不要只改 `COLUMNS::`，却忘了同步 `# 标题`、`TYPES::`、`REQUIRED::`、`COL-OPT::`、`EXPCOL::`。
- 不要只在数据行增加列，元数据行没有定义的列不会被工具稳定识别。
- 在当前技能表示例中，`# 技能品质` 和 `# 技能类型` 是说明/提示列，不是正式导出字段；它们和前一列中文标题相同，编辑器会把它们识别成提示信息。
- `Red` 在 `../samples/skill_list2.csv` 的最后一行出现过，但它不在前面稳定样例品质序列里。正式使用前建议和配置枚举表确认。
- 使用 `../index.html` 导出时，如果取消勾选配置行，导出的 CSV 会缺少对应配置行；如果目的是继续维护完整源 CSV，不建议用该导出结果覆盖源文件。
