xuqinmin12/lawless-design
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
043624b590
lawless-design/docs/00_项目概述/开发规范/规范-项目目录与编码标准.md
xuqm fce1d7dcd4 initial: clean start
2026-07-09 14:39:17 +08:00

8.7 KiB
原始文件 Blame 文件历史

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

位置: 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 元信息头部（必须）

# 标题

> **文档类型**: 游戏设计文档(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 文件头注释（必须）

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

3.2 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）: 初始版本，覆盖目录结构、文档标准、代码规范、美术标准、依赖管理、测试标准