# 桌游项目开发规范

本文档定义了桌游项目的开发流程、目录结构、文件命名和内容规范。

---

## 📁 目录结构规范

```
boardgames/
├── README.md                    # 桌游索引（必须）
├── development-guide.md         # 本开发规范文档
├── category/                    # 按类别分类的桌游（必须）
│   ├── strategy/               # 策略类桌游
│   ├── party/                  # 派对类桌游
│   ├── card/                   # 卡牌类桌游
│   └── cooperative/            # 合作类桌游
├── tools/                      # 工具集（必须）
│   ├── README.md              # 工具说明文档
│   └── *.html                 # 各种工具文件
└── resources/                  # 资源文件（可选）
    ├── images/                # 桌游图片
    └── rules/                 # 规则说明
```

### 规则说明

1. **category/** 下按游戏类别创建子目录
2. **每个游戏**必须有独立的目录，目录名使用英文小写+连字符（如 `treasure-hunter`）
3. **每个游戏目录**至少包含 `README.md` 文件
4. **tools/** 存放所有工具类HTML文件

---

## 📝 文件命名规范

| 文件类型 | 命名规则 | 示例 |
| :--- | :--- | :--- |
| 游戏目录 | 英文小写+连字符 | `treasure-hunter` |
| 游戏说明 | `README.md` | `README.md` |
| 打印文档 | `printables.html` | `printables.html` |
| 工具文件 | 英文小写+连字符+.html | `card-maker.html` |
| 图片文件 | 英文小写+连字符+描述 | `game-map.png` |

---

## 📋 README.md 内容规范

每个游戏的 `README.md` 必须包含以下章节（按顺序）：

### 1. 游戏概述
- 简要介绍游戏背景和玩法
- 说明适合人群

### 2. 游戏信息表格
```markdown
| 属性 | 说明 |
| :--- | :--- |
| **玩家人数** | X-X人 |
| **游戏时长** | XX-XX分钟 |
| **适合年龄** | XX岁以上 |
| **难度** | 简单/中等/困难 |
```

### 3. 详细物料清单（必须）
包含：
- 必选道具表格（物品名称、数量、用途、是否可替代）
- 卡牌道具表格（卡牌类型、数量、图示、用途）
- 按玩家人数的打印参考表格
- 建议准备物品

### 4. 游戏地图详解（如有地图）
- 地图布局概览（使用ASCII或Emoji展示）
- 地形类型说明表格
- 地图特点和资源统计

### 5. 道具详解（必须）
- 资源卡说明（类型、图示、获得方式、用途）
- 工具卡说明（工具、图示、建造所需资源、使用效果）
- 陷阱卡说明（类型、图示、效果、应对方法）
- 宝藏卡说明

### 6. 游戏规则
- 准备阶段（分步骤说明）
- 游戏流程（每个回合的操作）
- 胜利条件

### 7. 完整游戏流程示例
提供1-2个完整的回合示例，让新手一看就会。

### 8. 新手策略提示

### 9. 变体规则（可选）

### 10. 常见问题（必须）
解答新手可能遇到的问题。

### 11. 相关链接
- 打印道具链接：`*打印道具请参考 [printables.html](printables.html) 文件*`

---

## 🎮 添加新桌游流程

### 步骤1：创建游戏目录
```bash
cd boardgames/category/<类别>/
mkdir <游戏目录名>
cd <游戏目录名>
```

### 步骤2：创建游戏说明文档
创建 `README.md`，按照内容规范编写。

### 步骤3：创建打印文档（可选但推荐）
创建 `printables.html`，包含：
- 游戏地图（如有）
- 所有卡牌
- 玩家棋子
- 其他道具

**重要**：打印文档必须包含：
1. CSS中设置背景打印：
```css
@media print {
    * {
        -webkit-print-color-adjust: exact !important;
        print-color-adjust: exact !important;
    }
}
```
2. 打印提示中说明勾选"背景图形"
3. 建议使用卡纸打印

### 步骤4：更新索引
在 `boardgames/README.md` 的桌游索引表格中添加新游戏：
```markdown
| [游戏名称](category/<类别>/<游戏目录>/README.md) | 类别 | X-X人 | XX-XX分钟 | 简单/中等/困难 |
```

### 步骤5：检查链接
确保所有链接都是可点击的Markdown链接格式：
- ✅ `[显示文本](相对路径)`
- ❌ `文件名` 或 `` `文件名` ``

---

## 🛠️ 工具使用规范

### 卡牌生成器 (card-maker.html)

**用途**：快速创建和打印桌游卡牌

**使用方法**：
1. 打开 `tools/card-maker.html`
2. 填写卡牌信息（名称、图标、类型、描述、颜色）
3. 点击"添加卡牌"加入列表
4. 点击"打印卡牌"按钮打印

**注意事项**：
- 打印前务必勾选"背景图形"选项
- 建议使用卡纸打印增加耐用性
- 打印后可裁剪并塑封

### 创建新工具

1. 在 `tools/` 目录创建新的 `.html` 文件
2. 在 `tools/README.md` 中添加工具说明
3. 确保工具是纯前端实现（HTML/CSS/JavaScript）
4. 添加使用说明和打印建议

---

## 🖨️ 打印文档规范

### HTML打印文档必备元素

#### 1. CSS背景打印支持
```css
@media print {
    * {
        -webkit-print-color-adjust: exact !important;
        print-color-adjust: exact !important;
    }
}
```

#### 2. 打印提示
```html
<div class="print-hint">
    <strong>⚠️ 重要打印提示：</strong>
    <ul>
        <li>使用A4纸张打印，建议设置<strong>最小边距</strong></li>
        <li>在打印对话框中，务必<strong>勾选"背景图形"</strong>选项</li>
        <li>卡牌和棋子建议使用<strong>卡纸</strong>打印</li>
    </ul>
</div>
```

#### 3. 隐藏打印提示
```css
@media print {
    .print-hint {
        display: none;
    }
}
```

### 打印内容建议

| 内容 | 建议纸张 | 打印设置 |
| :--- | :--- | :--- |
| 游戏地图 | 普通A4纸 | 最小边距，勾选背景图形 |
| 卡牌 | 卡纸 | 最小边距，勾选背景图形 |
| 棋子 | 卡纸 | 最小边距，勾选背景图形 |
| 规则说明 | 普通A4纸 | 最小边距 |

---

## 🔗 链接规范

### Markdown链接格式

所有文件引用必须使用可点击的Markdown链接：

| 场景 | 正确格式 | 错误格式 |
| :--- | :--- | :--- |
| 引用同目录文件 | `[printables.html](printables.html)` | `printables.html` |
| 引用子目录文件 | `[README.md](category/strategy/game/README.md)` | `category/strategy/game/README.md` |
| 引用上级目录 | `[README.md](../README.md)` | `../README.md` |

### 检查清单
- [ ] 所有内部文件引用都是可点击链接
- [ ] 链接路径正确（相对路径）
- [ ] 链接文本具有描述性
- [ ] 在IDE中点击可以正确跳转

---

## ✅ 发布前检查清单

在提交新桌游前，请确认：

### 文件完整性
- [ ] 游戏目录已创建
- [ ] `README.md` 已创建并包含全部必要章节
- [ ] `printables.html` 已创建（如需要）
- [ ] 所有文件命名符合规范

### 内容质量
- [ ] 游戏信息表格完整
- [ ] 物料清单详细（含数量、图示）
- [ ] 道具详解完整（资源卡、工具卡、陷阱卡、宝藏卡）
- [ ] 游戏规则清晰，新手能看懂
- [ ] 有完整游戏流程示例
- [ ] 常见问题已解答

### 打印优化
- [ ] `printables.html` 包含背景打印CSS
- [ ] 打印提示包含"勾选背景图形"说明
- [ ] 建议使用卡纸打印

### 链接检查
- [ ] `README.md` 中的文件链接可点击
- [ ] `boardgames/README.md` 索引已更新
- [ ] 所有链接路径正确
- [ ] 在浏览器/IDE中测试链接可跳转

### 代码规范
- [ ] HTML文件格式正确
- [ ] CSS样式完整
- [ ] 无JavaScript错误
- [ ] 支持现代浏览器

---

## 📌 最佳实践

1. **新手优先**：游戏规则要简单明了，新手一看就会
2. **物料清单详细**：列出所有需要的物品和数量，避免打印缺失
3. **道具结合介绍**：用道具来说明游戏规则，而不是孤立地介绍
4. **示例驱动**：提供完整的游戏流程示例
5. **打印友好**：确保打印时背景图形正确显示
6. **链接完整**：所有文件引用都可点击打开
7. **图标统一**：使用Emoji图标增加可读性

---

## 🚫 常见错误

| 错误 | 正确做法 |
| :--- | :--- |
| 游戏说明过于简单 | 详细说明每个道具和规则，提供示例 |
| 物料清单不明确 | 列出具体数量和图示 |
| 打印无背景 | 添加CSS背景打印支持，提示勾选背景图形 |
| 链接不可点击 | 使用`[文本](路径)`格式 |
| 地图无介绍 | 添加地图布局、地形说明、资源统计 |
| 缺少流程示例 | 提供1-2个完整回合示例 |

---

*最后更新：2026-04-29*