# h5rpg

**Repository Path**: mapleKirito/h5rpg

## Basic Information

- **Project Name**: h5rpg
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docs/ 目录说明

> 版本：v1.0（2026-07-10）
> 维护者：项目全员

---

## 一、四区结构概览

```
docs/
├── game-design/     ← 设计文档（唯一且最新的设计来源）
├── archive/         ← 历史归档（已完成的阶段文档、留档材料）
├── sprints/         ← 进行中的开发任务
├── code/            ← 固定维护的标准化技术文档
└── README.md        ← 本文件
```

---

## 二、各区用途与使用规范

### 2.1 game-design/ — 设计文档

**定位**：项目唯一且最新的设计来源。所有功能、机制、数值、架构的最终设计均以此目录为准，其他任何地方不得存在第二份"设计文档"。

**内容**（9 份基线文档）：

| 文件 | 说明 |
|------|------|
| `00-index.md` | 设计文档索引入口 |
| `01-概述与愿景.md` | 项目概述与愿景 |
| `02-属性与成长系统.md` | 属性、成长、升级机制 |
| `03-战斗系统核心机制.md` | 行动条、回合、伤害公式 |
| `04-技能体系.md` | 技能分类、效果、配表 |
| `05-战斗双模式系统.md` | CLIENT / SERVER 模式架构 |
| `06-客户端战斗场景设计.md` | 客户端战斗 UI/UX |
| `07-接口协议与数据结构.md` | 前后端协议定义 |
| `08-任务拆解与开发路线.md` | 开发路线图与阶段规划 |

**同步更新规范**：
- 设计变更必须先更新 `game-design/` 对应文档，再修改代码。
- 每次设计更新后，在 `game-design/00-index.md` 中记录变更日志。
- 禁止在 `game-design/` 之外的任何位置单独维护设计文档副本。

---

### 2.2 archive/ — 历史归档

**定位**：存放已完成的阶段规划、历史留档材料、过期但需保留参考价值的文档。

**现有内容**：

| 子目录/文件 | 来源 |
|------------|------|
| `战斗架构改造/` | 战斗架构改造全流程历史文档（规划、执行、评估、追溯） |
| `sprints/` | 已完成的 P0 阶段规划文档 |
| `技能体系规划设计/` | 技能体系规划的历史讨论与方案 |
| `全局开发状态与评审反馈.md` | 历史全局评审记录（game-design/08 已覆盖开发路线） |
| `后续待办事项.md` | 历史散落待办（后续待办应在 sprints 子文件夹 README 中管理） |
| `管理后台开发文档.md` | 管理后台独立子系统文档（非设计基线也非接口文档） |
| `技能系统设计与功能验证.md` | 技能验证任务（game-design/04 已覆盖） |
| `P0待办清单.md` | 客户端 P0 待办 |
| `P0待办清单_服务端.md` | 服务端 P0 待办 |
| `客户端开发结果review-2026-06-19.md` | 客户端历史 Review |
| `服务端阶段Review反馈-2026-06-21-P0.md` | 服务端历史 Review |

**使用规范**：
- 只读参考，不修改、不更新归档文件。
- 新的留档材料放入对应的子目录或作为松散文件放入 archive/ 根级。

---

### 2.3 sprints/ — 进行中的任务

**定位**：存放当前开发周期进行中的任务规划文档。

**子文件夹结构规范**：

```
sprints/
└── P{N}-{阶段简述}/       ← 每个进行中的阶段一个子文件夹
    ├── README.md           ← 本阶段概览 + 待办清单 + 完成标准
    ├── 任务-01-xxx.md       ← 具体任务文档（可选）
    └── ...
```

每个阶段子文件夹必须包含 `README.md`，内容至少包括：
- 阶段目标与范围
- 待办事项清单（附状态：待开始/进行中/已完成/阻塞）
- 完成标准（验收条件）
- 依赖关系（前置任务与阻塞项）
- 关联的 game-design 文档引用

**生命周期**：
- 阶段启动 → 在 `sprints/` 下创建子文件夹
- 阶段进行中 → 更新 README.md 中的待办状态
- 阶段完成 → 整个子文件夹移入 `archive/sprints/`

**当前状态**：sprints/ 为空，暂无进行中的任务。

---

### 2.4 code/ — 标准化技术文档

**定位**：固定维护两份标准化文档，作为前后端协作的契约来源。

| 文件 | 维护视角 | 说明 |
|------|---------|------|
| `接口文档.md` | **服务端视角** | 所有客户端 API 接口的权威契约：路径、方法、参数、返回结构、错误码。服务端实现与客户端调用均以此为准。 |
| `客户端反馈需求文档.md` | **客户端视角** | 客户端向服务端提出接口需求、Bug、字段调整、联调阻塞点的沟通通道。客户端只能通过此文档与服务端沟通，不得越权修改 `server/` 代码。 |

**维护规范**：
- `接口文档.md`：服务端负责维护更新，客户端只读引用。每次接口变更必须同步更新。
- `客户端反馈需求文档.md`：客户端负责新增需求记录，服务端负责更新处理状态。双方按文档中定义的流程协作。
- 两份文档均需标注版本号和更新日期。

---

## 三、文档去重原则

1. **设计类文档**：只能存在于 `game-design/`，其他目录不得出现设计文档。
2. **接口类文档**：只能存在于 `code/`，其他地方不得出现接口协议副本。
3. **任务类文档**：进行中任务在 `sprints/`，已完成的归档到 `archive/sprints/`。
4. 如果发现内容重复或冲突，以 `game-design/` 或 `code/` 为准。