# 洪荒大陆 · 游戏设计项目

> **当前阶段：游戏设计阶段 — 暂停技术实现**
>
> 在宣布进入开发阶段前**不做技术实现**。代码骨架保留项目结构，不继续开发。
> 设计文档位于 `docs/`，按策划职能分层组织。

## 设计文档总览

文档按 **世界观 → 系统 → 数值 → 产品 → 技术选型 → 美术 → 测试 → 运营** 的依赖链分层：

| 目录 | 内容 | 文档数 |
|------|------|--------|
| `docs/00_项目概述/` | 决策总索引、开发规范、里程碑 | 10+ |
| `docs/01_世界观与剧情/` | 世界观设定、神话体系 | 4 |
| `docs/02_种族与角色/` | 19 种族设计、境界体系、转生转化 | 12 |
| `docs/03_核心机制/` | 底层机制、能量体系、渡劫、数值平衡 | 5 |
| `docs/04_战斗系统/` | ATB 战斗、技能总库、PVP | 6 |
| `docs/05_功法与职业/` | 功法、职业、生活技能、丹药 | 5 |
| `docs/06_经济系统/` | 经济循环、拍卖、玩家驱动经济 | 3 |
| `docs/07_地图与世界/` | 五层世界、副本遗迹、随机事件 | 7 |
| `docs/08_装备系统/` | 装备打造、强化、本命法宝 | 2 |
| `docs/09_社交系统/` | 帮派、好友、洞府、新手引导 | 12 |
| `docs/10_产品需求/` | PRD 需求文档（核心玩法/战斗/经济/社交/职业/装备/新手引导） | 10 |
| `docs/11_技术选型/` | 技术栈选型总览（详细 TDD 待开发阶段补充） | 1 |
| `docs/12_美术需求/` | UI 规范 | 1 |

### 快速链接

- [决策总索引](docs/00_项目概述/GDD-00-决策总索引.md) - 所有核心决策的单一事实源
- [开发规范](docs/00_项目概述/开发规范/) - 项目约束与编码标准
- [技术选型总览](docs/11_技术选型/技术选型总览.md) - 技术栈选型与架构概览

### 1. 准备环境变量

```bash
cp .env.example .env
```

`.env` 中已包含本地开发默认值，通常无需修改。

### 2. 一键启动全部服务

```bash
docker compose up -d
```

首次启动会自动完成：

- 拉取/构建 PostgreSQL 16、Nakama 3.24.2、Valkey 8、Nacos 2.x 镜像
- 自动创建 `nakama`（Nakama 元数据）和 `honghuang`（游戏业务）两个数据库
- 在 `honghuang` 库执行 `database/migrations/001_init_schema.up.sql`（含种族、境界、世界层、货币等 seed 数据）
- 自动创建 Nacos namespace `honghuang` 并导入 `configs/nacos/*.yaml`
- 编译并加载 `server/honghuang-server.so` 插件

### 3. 查看服务状态

```bash
docker compose ps
docker compose logs -f nakama
```

### 4. 常用端口

| 服务      | 端口     | 说明                              |
| --------- | -------- | --------------------------------- |
| Nakama    | 7349     | gRPC API                          |
| Nakama    | 7350     | Realtime / HTTP API               |
| Nakama    | 7351     | Console（admin / password）       |
| PostgreSQL| 5432     | 业务库 `honghuang` + Nakama 库    |
| Valkey    | 6379     | Redis 兼容缓存                    |
| Nacos     | 8848     | 配置中心 http://localhost:8848/nacos |

### 5. 停止/重置

```bash
# 停止服务
docker compose down

# 停止并清空所有本地数据卷（彻底重置）
docker compose down -v

# 只重启 Nakama
docker compose restart nakama
```

## 目录说明

- `docs/` — 游戏设计文档（GDD/PRD/技术选型/开发规范），按策划职能分层
  - `00_项目概述/` — 决策总索引、开发规范、里程碑
  - `01~09/` — 按系统分层的设计文档（世界观→种族→机制→战斗→职业→经济→地图→装备→社交）
  - `10_产品需求/` — PRD 需求文档
  - `11_技术选型/` — 技术栈选型总览（详细 TDD 待开发阶段补充）
  - `12_美术需求/` — UI 规范
  - `15_归档/` — 过程稿、审阅记录、废弃文档
- `AGENTS.md` — 项目强约束（人机协作/文档体系/技术合规等）
- `client/` — Cocos Creator 项目骨架（设计阶段保留结构，不开发）
- `server/` — 服务端骨架（设计阶段保留结构，不开发）
- `docker-compose.yml` — 本地开发环境配置（设计阶段保留）
- `database/migrations/` — 数据库迁移脚本
- `configs/nacos/` — Nacos 动态配置（GDD-21 数值参数）
- `docker/` — 各服务 Dockerfile 与初始化脚本
- `api/` — Protobuf / OpenAPI 定义
- `client/` — Cocos Creator 3.x 客户端资源（骨架阶段）
- `docs/` — GDD / TDD / PRD 等设计文档（**核心产出**）
  - `docs/设计文档/` — GDD-00~33 游戏设计文档
  - `docs/技术文档/` — TDD-01~10 技术设计文档
  - `docs/需求文档/` — PRD-01~03 需求文档
  - `docs/ai-collab/` — AI协作记录

## 本地开发 tip

- 修改 `server/` 源码后，重新构建 Nakama 镜像：

  ```bash
  docker compose up -d --build nakama
  ```

- 修改 `configs/nacos/*.yaml` 后，重新执行配置导入：

  ```bash
  docker compose run --rm nacos-init
  ```

- 数据库迁移脚本可通过 `scripts/migrate.sh`、`scripts/seed.sh`、`scripts/reset.sh` 在本地 psql 环境执行（需安装 PostgreSQL 客户端）。