Doc Writer

Overview

为 EsportManager 2 项目编写规范的技术文档。确保文档风格统一、结构清晰、易于维护。

文档目录结构

code

docs/
├── README.md                    # 文档索引（必须更新）
├── CONTRIBUTING.md              # 文档编写指南
├── 01-overview/                 # 项目概览
├── 02-game-design/              # 游戏设计/策划
├── 03-core-systems/             # 核心系统文档
├── 04-technical/                # 技术开发文档
├── 05-ai/                       # AI 系统文档
└── archive/                     # 归档（已废弃的旧文档）

目录用途

目录	用途	适合内容
`01-overview`	项目总览	架构图、技术栈、目录结构
`02-game-design`	游戏策划	游戏规则、赛事设计、数值设计
`03-core-systems`	核心系统	各业务系统的设计与实现
`04-technical`	技术开发	API、数据库、前后端指南
`05-ai`	AI 系统	AI 决策、算法说明
`archive`	归档	已废弃但保留参考的旧文档

工作流程

1. 确定文档类型和目录

根据内容选择目录：

code

游戏规则/数值设计 → 02-game-design/
业务系统实现     → 03-core-systems/
开发技术指南     → 04-technical/
AI/算法相关      → 05-ai/

2. 创建文件（遵循命名规范）

命名规则：

•使用英文 + 短横线：player-system.md
•全部小写
•简洁明确

code

✅ 正确：player-system.md, match-simulation.md
❌ 错误：选手系统.md, PlayerSystem.md, player_system.md

3. 使用模板编写

系统文档模板

markdown

# 系统名称

## 概述

一句话描述系统的核心功能和目的。

## 核心概念

解释关键术语和概念。

## 数据结构

\`\`\`rust
pub struct ExampleModel {
    pub id: u64,
    pub name: String,
}
\`\`\`

## 核心流程

\`\`\`
步骤1 → 步骤2 → 步骤3
\`\`\`

## 规则说明

| 规则 | 说明 |
|------|------|
| 规则1 | 详细说明 |

## API 接口

| 接口 | 描述 |
|------|------|
| `api_name` | 功能描述 |

## 文件位置

| 文件 | 说明 |
|-----|------|
| `src-tauri/src/xxx.rs` | 核心实现 |

技术文档模板

markdown

# 技术主题

## 概述

技术背景和用途说明。

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| xxx | x.x | 用途说明 |

## 使用方法

### 基本用法

\`\`\`typescript
// 代码示例
\`\`\`

## 最佳实践

1. **实践1**：说明
2. **实践2**：说明

## 文件位置

| 文件 | 说明 |
|-----|------|
| `path/to/file` | 说明 |

4. 更新文档索引

在 docs/README.md 中添加新文档链接：

markdown

### 03-core-systems 核心系统
- [新系统](03-core-systems/new-system.md) - 新系统描述

编写规范

语言

•主体使用中文
•专业术语保留英文：API、SDK、BO3
•代码、文件名、命令使用英文

格式

元素	规范
标题	`#` 文档标题，`##` 主章节，`###` 子章节
代码块	必须标注语言类型
表格	用于对比、配置、参数说明
列表	有序=步骤流程，无序=并列项目

内容规范

•开头有概述 - 1-2 句话说明主题
•结尾有文件位置 - 列出相关源码路径
•图表优先 - 能用图表说明的不用大段文字
•代码示例 - 关键功能必须有示例

文档审查清单

写完文档后检查：

• 文件名符合命名规范（英文、小写、短横线）
• 放置在正确的目录下
• 包含概述部分
• 包含文件位置部分
• 代码块标注了语言类型
• 已更新 README.md 索引

废弃文档处理

当文档不再需要时：

•不要直接删除
•移动到 archive/ 目录
•从 README.md 索引中移除链接

bash

mv docs/03-core-systems/old-system.md docs/archive/

注意事项

•先读后写 - 写新文档前先阅读相关源码
•保持简洁 - 避免冗余，突出重点
•及时更新 - 代码变更后同步更新文档
•不重复造轮子 - 检查是否已有类似文档