lawless-design/docs/00_项目概述/开发规范/规范-项目目录与编码标准.md

# 规范-项目目录与编码标准

> **位置**: `docs/开发规范/规范-项目目录与编码标准.md`
> **版本**: v1.0
> **日期**: 2026-07-08
> **关联**: AGENTS.md

---

## 1. 项目目录结构

```
lawless/
├── docs/                          # 📁 全部文档
│   ├── 设计文档/ (GDD)             # 游戏设计文档 — 策划产出
│   ├── 需求文档/ (PRD)             # 产品需求文档 — 产品产出
│   ├── 技术文档/ (TDD)             # 技术设计文档 — 技术产出
│   ├── 开发规范/                   # 本目录
│   ├── 美术文档/                   # UI规范、原画需求、动效说明
│   ├── 运营文档/                   # 活动策划、数据分析、GM手册
│   └── 协议文档/                   # API/Protobuf/OpenAPI
│
├── client/                        # 📁 客户端（Cocos Creator 3.8.8）
│   ├── assets/
│   │   ├── scripts/                # TypeScript 脚本
│   │   │   ├── data/               # 数据模型/配置表/常量
│   │   │   ├── systems/            # 核心系统（能量/时间/网络/战斗）
│   │   │   ├── app/                # 应用状态/业务逻辑
│   │   │   ├── ui/                 # UI 组件
│   │   │   │   ├── scenes/         # 场景控制器（登录/选角/主界面）
│   │   │   │   ├── screens/        # 功能界面（战斗/背包/设置）
│   │   │   │   ├── components/     # 可复用 UI 组件
│   │   │   │   └── common/         # UI 工具类（SceneUI 等）
│   │   │   └── GameManager.ts      # 游戏主管理器
│   │   ├── scenes/                 # Cocos 场景文件（.scene）
│   │   ├── resources/              # 静态资源
│   │   │   ├── prefabs/            # 预制体
│   │   │   ├── textures/           # 纹理/精灵
│   │   │   ├── animations/         # 动画/Spine
│   │   │   └── fonts/              # 字体
│   │   └── bundles/                # Asset Bundle（热更）
│   ├── build/                      # 构建输出
│   └── project.json
│
├── server/                         # 📁 服务端（Go + Nakama）
│   ├── src/
│   │   ├── main.go                 # 入口
│   │   ├── handlers/               # HTTP/gRPC 处理器
│   │   ├── services/               # 业务服务层
│   │   ├── models/                 # 数据模型
│   │   ├── repositories/           # 数据访问层（DAO）
│   │   ├── match/                  # Realtime Match 逻辑（AOI/位置同步）
│   │   ├── rpc/                    # Nakama RPC 实现
│   │   └── middleware/             # 中间件（认证/限流/日志/异常恢复）
│   ├── configs/                    # 服务端配置模板
│   ├── migrations/                 # 数据库迁移脚本
│   └── Makefile
│
├── api/                            # 📁 协议定义
│   ├── proto/
│   │   └── honghuang.proto         # Protobuf 定义
│   └── openapi.yaml                # OpenAPI 3.0 规范
│
├── database/                       # 📁 数据库
│   ├── migrations/                 # 迁移脚本（up/down）
│   ├── seeds/                      # 种子数据
│   └── schemas/                    # 表结构文档
│
├── configs/                        # 📁 配置中心模板（Nacos）
│   └── nacos/
│       ├── global.yaml
│       ├── combat.yaml
│       ├── economy.yaml
│       ├── map.yaml
│       ├── event.yaml
│       └── cultivation.yaml
│
├── tools/                          # 📁 工具脚本
│   └── scripts/
│       ├── generate_proto.sh       # 生成协议代码
│       ├── build_client.sh         # 客户端构建
│       └── build_server.sh         # 服务端构建
│
├── tests/                          # 📁 测试
│   ├── unit/                       # 单元测试
│   ├── integration/                # 集成测试
│   └── e2e/                        # 端到端测试
│
├── docker/                         # 📁 Docker 配置
│   ├── Dockerfile.client
│   ├── Dockerfile.server
│   └── docker-compose.yml
│
├── AGENTS.md                       # 项目强约束
├── README.md                       # 项目说明
└── CHANGELOG.md                    # 版本变更日志
```

### 1.1 目录禁止行为

- ❌ 在根目录堆放零散文件（必须放入对应子目录）
- ❌ 把服务端代码放在 `client/` 下，反之亦然
- ❌ 用中文或特殊字符命名代码文件/目录（仅限文档可用中文名）
- ❌ 删除或重命名已有标准目录

---

## 2. 文档编写标准

### 2.1 元信息头部（必须）

```markdown
# 标题

> **文档类型**: 游戏设计文档(GDD) / 产品需求文档(PRD) / 技术设计文档(TDD)
> **版本**: vX.Y
> **日期**: YYYY-MM-DD
> **关联文档**: [列出相关的 GDD/PRD/TDD 编号]
> **作者**: [agent 标识]

---

## 已确认决策记录
| # | 决策 | 来源 |
|---|------|------|

## 待确认事项
| # | 问题 | 状态 |
|---|------|------|

## 正文...

---

## 版本记录
- **vX.Y**（YYYY-MM-DD）: [变更摘要]
```

### 2.2 内容规范

- Markdown 格式，UTF-8 编码
- 一级标题 = 文档标题；二级 = 章节；三级 = 小节
- 表格用于枚举、对照、参数表
- 决策用 `✅N`，待确认用 `❓N`
- 所有数值必须标注来源（如"来源: GDD-21 §3.1"）
- 禁止 TODO/FIXME 残留（要么解决，要么列入待确认表）

---

## 3. 代码编写标准

### 3.1 文件头注释（必须）

```typescript
/**
 * @file GameManager.ts
 * @brief 游戏主管理器 — 管理游戏状态、界面切换、数据流
 * @author [agent标识]
 * @date 2026-07-08
 * @sync GDD-02 ✅158, GDD-23 ✅159
 * @version 2.0
 */
```

### 3.2 TypeScript 规范

```typescript
// ✅ 正确：显式类型 + 常量提取 + 注释来源
const ENERGY_REGEN_SECLUSION_COEFFICIENT = 2.25; // GDD-23 ✅159 四档恢复: 闭关

interface CharacterData {
  energyCurrent: number;    // 主动资源 (✅158)
  energyCap: number;        // 成长进度 (✅158)
}

// ❌ 错误：魔法数字 + 无类型 + 无注释
const x = 2.25;
let y: any;
```

| 规则 | 说明 |
|------|------|
| `"strict": true` | 严格模式，禁止隐式 any |
| 显式返回类型 | 函数必须声明返回类型 |
| 禁止 `any` | 除非 interfacing with JS 库 |
| PascalCase 类名 | `class EnergySystem` |
| camelCase 函数/变量 | `calculateRegenCoefficient` |
| UPPER_SNAKE_CASE 常量 | `MAX_INVENTORY_SLOTS` |

### 3.3 Go 规范

- 遵循 `gofmt` 格式
- 导出函数必须注释（`// CalculateDamage ...`）
- 错误处理：显式检查 `if err != nil`，禁止忽略错误
- 数据库查询使用参数化查询（防 SQL 注入）

### 3.4 禁止行为

- ❌ 魔法数字（无来源注释的裸数字）
- ❌ 硬编码配置（所有可调参数走 Nacos/配置文件）
- ❌ 硬编码用户可见文本（走 i18n 本地化表）
- ❌ `console.log` 残留（用分级日志：debug/info/warn/error）
- ❌ 注释掉的代码块（要么删除，要么说明原因）

---

## 4. 美术/UI 标准

### 4.1 资源命名

```
[类型]_[功能]_[状态]_[尺寸].[ext]

btn_login_normal_120x60.png
icon_energy_fill_32x32.png
bg_main_title_1920x1080.jpg
```

### 4.2 UI 设计文档必须包含

- 界面层级结构图（树状）
- 各元素尺寸、位置、颜色、字体
- 交互流程图（点击后的状态变化）
- 与代码的对接说明（节点命名、事件绑定）

---

## 5. 依赖管理

| 规则 | 说明 |
|------|------|
| 锁定版本 | `package-lock.json` / `go.mod` + `go.sum` |
| 安全审查 | 新增依赖查 CVE 漏洞库 |
| 禁止废弃依赖 | last update > 2 年 的不引入 |
| 定期扫描 | 每月运行 `npm audit` / `govulncheck` |

---

## 6. 测试标准

| 测试类型 | 覆盖要求 | 文件位置 |
|----------|----------|----------|
| 单元测试 | 核心业务逻辑（能量/战斗/经济） | `tests/unit/` 或 `server/src/xxx_test.go` |
| 集成测试 | 系统间交互（登录→战斗→结算） | `tests/integration/` |
| 端到端测试 | 完整用户流程 | `tests/e2e/` |
| 性能测试 | 战斗并发/API 压测 | `tests/perf/` |

---

## 7. 版本记录

- **v1.0**（2026-07-08）: 初始版本，覆盖目录结构、文档标准、代码规范、美术标准、依赖管理、测试标准