# 新项目说明与工作约定

> 更新日期：2026-10-04

## 1. 项目背景

当前仓库 **AdLikeXy** 的代码来源于 **老项目完整复制**，作为新项目的起点：

- **保留**：MX 框架（`assets/mx/`）、资源/启动管线、部分业务模块与编辑器扩展
- **目标**：在老项目基础框架上 **裁剪、改造、增量开发**，产出 **一款新的小游戏产品**
- **需求节奏**：具体玩法与功能需求将 **逐步给出**，按迭代落地

老项目形态参见 [`项目分析报告.md`](./项目分析报告.md)（塔防 + 汉字背包、多渠道马甲等）。新项目未必沿用全部玩法与渠道配置，以后续需求文档为准。

**局内战斗范围（Slice5 起）：** 仅 **五行数字合成** + **单格上阵**（开地 / 互换沿用背包与 Merge 规则）。详见 [`需求-五行合成.md`](./需求-五行合成.md)。

## 2. 目录与文件约定

除 Cocos 默认目录（`assets/`、`extensions/`、`library/`、`build/` 等）外，工作区约定如下：

| 目录 | 用途 | 是否提交 Git |
|------|------|----------------|
| **`docs/`** | 项目文档；**Plan 模式生成的需求/规划文档** | 是 |
| **`test/`** | **测试相关文件**（用例、夹具、测试说明等） | 是 |
| **`tools/`** | **项目脚本**（构建、批处理、配表辅助等，长期维护） | 是 |
| **`temp/py/`** | **临时 Python 脚本**（一次性分析、迁移、验证） | 否（`temp/` 已在 `.gitignore`） |

### 2.1 `docs/` — 文档与需求

- 项目分析、性能说明、战斗接入、**开发规范** 等常驻文档
- **开发规范**：[`开发规范.md`](./开发规范.md)（AI 与人工必读）
- **Plan 模式** 产出的需求说明、迭代计划、技术方案 → 一律放在 `docs/`
- **文档命名一律使用简体中文文件名**
- 建议命名：
  - 需求：`docs/需求-{主题}.md` 或 `docs/计划/{主题}.md`
  - 方案：`docs/方案-{主题}.md`
- 避免在 `assets/` 下散落仅用于协作的 Markdown（战斗模块内历史文档可保留）

### 2.2 `test/` — 测试

- 单元测试、集成测试、手工测试清单、测试数据
- 与 **游戏运行时资源** 分离，勿与 `assets/` 混放
- Cocos / TypeScript 测试框架选型待需求明确后补充

### 2.3 `tools/` — 项目脚本（根目录）

- **根目录 `tools/`**：本仓库维护的脚本（Python、Node、Shell 等）
- **勿与** `extensions/tools/`（Cocos **编辑器扩展**）混淆：
  - `extensions/tools/` → 编辑器插件、构建钩子
  - `tools/` → 仓库级自动化与辅助脚本

### 2.4 `temp/py/` — 临时 Python

- Cocos Creator 已使用根目录 `temp/` 作为 **引擎缓存**（构建产物、日志等）
- **临时、可丢弃** 的 Python 脚本统一放在 **`temp/py/`**
- 因 `temp/` 被 `.gitignore` 忽略，**不会进入版本库**；若脚本需要长期保留，应迁移到 `tools/`

## 3. 开发原则（新项目阶段）

1. **先需求后改动**：无对应 `docs/` 需求说明时，大规模删改老代码前先确认范围
2. **优先复用 MX**：UI、资源、启动、战斗内核等优先扩展 `assets/mx/`，避免重复造轮子
3. **渐进剥离**：老项目玩法（章节、马甲 SDK、引流小游戏等）按需求 **显式删除或替换**，避免静默残留
4. **渠道与 SDK**：`sdk/config/*` 多渠道马甲为老项目遗留；新项目需单独规划渠道与 `sdkConfig.config`
5. **文档同步**：功能迭代完成后，更新或新增 `docs/` 内相关说明

## 4. 文档索引

| 文档 | 说明 |
|------|------|
| [项目说明.md](./项目说明.md) | 本文：新项目背景与约定 |
| [开发规范.md](./开发规范.md) | **开发规范**（AI 生成代码强制标准） |
| [需求-新项目概述.md](./需求-新项目概述.md) | **新产品大致需求**（段位制 + 对抗战斗 + 配表映射） |
| [需求-AI决策.md](./需求-AI决策.md) | 匹配与 AI 局内决策（刷新/拖动/落子/道具） |
| [需求-星期地图随机.md](./需求-星期地图随机.md) | 匹配进战按 Const 31~37 当天池随机 Level |
| [需求-五行合成.md](./需求-五行合成.md) | **局内**五行数字合成 + 单格上阵（当前战斗范围） |
| [需求-首局神将字.md](./需求-首局神将字.md) | ~~首局神将字保底~~（**已废弃**，见五行合成） |
| [方案-项目结构整理与遗留清理.md](./方案-项目结构整理与遗留清理.md) | 代码/资源整理 **分阶段实施** 路线 |
| [需求-模块保留.md](./需求-模块保留.md) | 模块保留/删除清单（**已确认**） |
| [遗留代码收敛方案.md](./遗留代码收敛方案.md) | 遗留代码向规范 **分阶段收敛** 方案 |
| [计划-试点启动链.md](./计划-试点启动链.md) | Phase 2 启动链试点 |
| [项目分析报告.md](./项目分析报告.md) | 老项目代码库静态分析（基线参考） |
| [性能打点说明.md](./性能打点说明.md) | 性能打点 `PF-*` 说明（若继续沿用） |
| [方案-加载性能优化.md](./方案-加载性能优化.md) | 冷启动最小集、静默下载、点击优先 |
| [方案-英雄经验升级.md](./方案-英雄经验升级.md) | 英雄等级上限与击杀/助攻经验升级 |
| [需求-组合英雄绑定.md](./需求-组合英雄绑定.md) | ~~组合英雄绑定~~（**已废弃**，见五行合成） |
| [需求-神将唯一合成.md](./需求-神将唯一合成.md) | ~~神将唯一合成~~（**已废弃**，见五行合成） |
| [需求-装备掉落.md](./需求-装备掉落.md) | 击杀怪物掉落武器碎片 |
| [需求-音效.md](./需求-音效.md) | 新音效资源与播放时机 |
| [方案-配表异常.md](./方案-配表异常.md) | 配表与实现对不上时统一 `【配表异常】` 告警 |

## 5. 待后续补充

- [x] 模块保留清单（[`需求-模块保留.md`](./需求-模块保留.md)，已确认）
- [x] 启动链试点计划与冒烟清单
- [x] 新产品大致需求（[`需求-新项目概述.md`](./需求-新项目概述.md)）
- [x] 项目结构整理方案（[`方案-项目结构整理与遗留清理.md`](./方案-项目结构整理与遗留清理.md)）
- [ ] 新产品名称、目标平台与发行渠道
- [ ] 各功能正式需求（`docs/需求-{功能}.md`，开发时逐项给出）