You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
6.3 KiB
6.3 KiB
新项目说明与工作约定
更新日期：2026-10-04
1. 项目背景
当前仓库 AdLikeXy 的代码来源于 老项目完整复制，作为新项目的起点：
- 保留：MX 框架（
assets/mx/）、资源/启动管线、部分业务模块与编辑器扩展 - 目标：在老项目基础框架上 裁剪、改造、增量开发，产出 一款新的小游戏产品
- 需求节奏：具体玩法与功能需求将 逐步给出，按迭代落地
老项目形态参见 项目分析报告.md（塔防 + 汉字背包、多渠道马甲等）。新项目未必沿用全部玩法与渠道配置，以后续需求文档为准。
局内战斗范围（Slice5 起）： 仅 五行数字合成 + 单格上阵（开地 / 互换沿用背包与 Merge 规则）。详见 需求-五行合成.md。
2. 目录与文件约定
除 Cocos 默认目录（assets/、extensions/、library/、build/ 等）外，工作区约定如下：
| 目录 | 用途 | 是否提交 Git |
|---|---|---|
docs/ |
项目文档；Plan 模式生成的需求/规划文档 | 是 |
test/ |
测试相关文件（用例、夹具、测试说明等） | 是 |
tools/ |
项目脚本（构建、批处理、配表辅助等，长期维护） | 是 |
temp/py/ |
临时 Python 脚本（一次性分析、迁移、验证） | 否（temp/ 已在 .gitignore） |
2.1 docs/ — 文档与需求
- 项目分析、性能说明、战斗接入、开发规范 等常驻文档
- 开发规范：
开发规范.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. 开发原则（新项目阶段）
- 先需求后改动：无对应
docs/需求说明时，大规模删改老代码前先确认范围 - 优先复用 MX：UI、资源、启动、战斗内核等优先扩展
assets/mx/，避免重复造轮子 - 渐进剥离：老项目玩法（章节、马甲 SDK、引流小游戏等）按需求 显式删除或替换，避免静默残留
- 渠道与 SDK：
sdk/config/*多渠道马甲为老项目遗留；新项目需单独规划渠道与sdkConfig.config - 文档同步：功能迭代完成后，更新或新增
docs/内相关说明
4. 文档索引
| 文档 | 说明 |
|---|---|
| 项目说明.md | 本文：新项目背景与约定 |
| 开发规范.md | 开发规范（AI 生成代码强制标准） |
| 需求-新项目概述.md | 新产品大致需求（段位制 + 对抗战斗 + 配表映射） |
| 需求-AI决策.md | 匹配与 AI 局内决策（刷新/拖动/落子/道具） |
| 需求-星期地图随机.md | 匹配进战按 Const 31~37 当天池随机 Level |
| 需求-五行合成.md | 局内五行数字合成 + 单格上阵（当前战斗范围） |
| 需求-首局神将字.md | |
| 方案-项目结构整理与遗留清理.md | 代码/资源整理 分阶段实施 路线 |
| 需求-模块保留.md | 模块保留/删除清单（已确认） |
| 遗留代码收敛方案.md | 遗留代码向规范 分阶段收敛 方案 |
| 计划-试点启动链.md | Phase 2 启动链试点 |
| 项目分析报告.md | 老项目代码库静态分析（基线参考） |
| 性能打点说明.md | 性能打点 PF-* 说明（若继续沿用） |
| 方案-加载性能优化.md | 冷启动最小集、静默下载、点击优先 |
| 方案-英雄经验升级.md | 英雄等级上限与击杀/助攻经验升级 |
| 需求-组合英雄绑定.md | |
| 需求-神将唯一合成.md | |
| 需求-装备掉落.md | 击杀怪物掉落武器碎片 |
| 需求-音效.md | 新音效资源与播放时机 |
| 方案-配表异常.md | 配表与实现对不上时统一 【配表异常】 告警 |
| 方案-GM可视化模块.md | 可视化可扩展 GM（mx 壳 + 项目命令注册） |
5. 待后续补充
- 模块保留清单（
需求-模块保留.md，已确认） - 启动链试点计划与冒烟清单
- 新产品大致需求（
需求-新项目概述.md） - 项目结构整理方案（
方案-项目结构整理与遗留清理.md） - 新产品名称、目标平台与发行渠道
- 各功能正式需求（
docs/需求-{功能}.md，开发时逐项给出）