AdLike2048/docs/方案-项目结构整理与遗留清理.md

# 方案：项目结构整理与遗留清理

> 日期：2026-08-17  
> 状态：实施中（Phase 0 文档已完成）  
> 关联：[需求-新项目概述.md](./需求-新项目概述.md)、[需求-模块保留.md](./需求-模块保留.md)、[遗留代码收敛方案.md](./遗留代码收敛方案.md)

## 1. 目标

将当前仓库（老项目完整复制）收敛为 **新产品结构**：

1. 配表、存档、战斗入口对齐 **12 张新表** 与段位制
2. 删除不再使用的局外模块、bundle、引流小游戏
3. 局内战斗接入 **阵营区域对抗**（非镜像 PvP），裁剪 type3 格子与 Gacha 模式
4. 保留并扩展 MX 框架层，避免重复造轮子

---

## 2. 现状与目标差距

| 层面 | 现状 | 目标 |
|------|------|------|
| 配表 | `first/config` 已换 12 张新表；大量 TS 仍引用 Chapter/Shop/Weapon1 等 | 代码只读新表；清理死类型与枚举 |
| 存档 | `GameData` 含 chapter、关卡进度等 | 改为 rankId、rankStars、dailyWins、昨日段位等 |
| 局外 UI | 5 Tab + 70+ 弹窗，多数绑旧表 | 保留首页/神兵/商店/转盘/排行榜等，删副本/角色/任务等 |
| 战斗 | Solo PVE + type3 改路 + Gacha | 阵营 PvAI + 固定路线 + Text 字池 |
| 对抗架构 | 早期半图镜像（已删除） | `CampAreaPolicy=pvp` + 双 campAreaId |
| 资源 | attractingTrafficGame、allBuyShops、replica 等 bundle 仍在 | 按清单删除并更新预载 |

---

## 3. 分阶段实施

### Phase 0 — 文档与门禁 ✅

| 项 | 状态 |
|----|------|
| [需求-新项目概述.md](./需求-新项目概述.md) | ✅ |
| 本文档 | ✅ |
| [需求-模块保留.md](./需求-模块保留.md) 确认 | ✅ |
| [项目说明.md](./项目说明.md) 索引更新 | ✅ |

### Phase 1 — 配表与类型层迁移

**目标**：编译层面对齐新表，不删 UI，避免雪崩。

| 任务 | 文件/动作 |
|------|-----------|
| 清理死代码 | `ConfigTableData.ts` 中 `SkillCostType` 章节相关、`IShopItemData` 等旧接口 |
| 类型对齐 | `AutoTable.ts` 保留新表接口；旧表接口标记废弃或删除（无引用后） |
| Level 构建 | 改造 `ChapterLevelBuilder.ts` → 读 `Level` 表，重命名为 `LevelDefBuilder` 或等价 |
| 合成配置 | `WeaponComposeConfigProvider` → `TextComposeConfigProvider`（Text + Hero） |
| 存档字段 | `GameData.ts` / `ConfigProjectData.ts`：删 chapter 相关，增段位字段 |
| Rank 消费 | 新建 `RankDataManager` 或并入 `ConfigProjectData` 读 Rank 表 |

**禁止**：Phase 1 完成前批量删除 UI 目录。

### Phase 2 — 局外裁剪与壳改造

**删除顺序**（先断引用，再删文件，最后删 bundle）：

```
ConfigRes.UIID 注销
  → 删除对应 TS 脚本
    → 删除 prefab / bundle
      → 更新 ResPkgBuilder 预载
```

| 步骤 | 内容 |
|------|------|
| 2.1 | `ConfigRes.ts` 注销废弃 UIID（见 §5.1） |
| 2.2 | 删除 TS 目录（见 §5.2） |
| 2.3 | 改造保留模块：PanelHome、pageWeapon、TurnTable |
| 2.4 | 新建：论功行赏 UI、排行榜 UI、新商店 UI |
| 2.5 | 删除 bundle：attractingTrafficGame、replica、allBuyShops 子包；视情况 role |
| 2.6 | 大厅导航按美术方案 A/B 落地（§7） |

### Phase 3 — 局内战斗改造

| 步骤 | 内容 |
|------|------|
| 3.1 | 地图：mapLayer1 校验双 CampAreaID；补齐 mapLayer2~4 |
| 3.2 | 开战：`resolveCampAreaPolicy(topology, 'pvp')`；双玩家槽绑 campAreaId |
| 3.3 | `PvPBattleMode` 双槽全图；部署隔离按 campAreaId |
| 3.4 | `BattleBagSession`：删 type3、路径 rebuild、`MapPlaceValidator` type3 逻辑 |
| 3.5 | 刷新池：`BagWeaponPool` 改读 Text 表；铲子 = Text type=4 |
| 3.6 | 新建 `AiOpponentController`（Rank.aiweapon / aiusead / charactersweight） |
| 3.7 | `UIBattleGame` 裁剪：Gacha、副本机制 UI、章节引导 |
| 3.8 | 对抗 UI：上下阵营信息栏、局外道具槽 |

### Phase 4 — 资源与引用清扫

| 任务 | 说明 |
|------|------|
| grep 旧表名 | `Chapter\|Weapon1\|Weapon2\|Lottery\|ShopBuy\|NewFun` |
| 规范审计 | `python tools/规范审计.py --list` |
| 删未引用资源 | prefab、spine、音效（按 bundle 逐项） |
| 更新预载 | `ResPkgBuilder.ts`、`ConfigRes.ts` bundle 映射 |
| 战斗文档 | `battle/docs/需求说明.md` 增「新项目差异」章节 |

### Phase 5 — 验收

| 项 | 标准 |
|----|------|
| 启动链 | [test/启动链冒烟清单.md](../test/启动链冒烟清单.md) 通过 |
| 配表 | 12 张表全加载，Const 校验无 error |
| 编译 | 无旧表名引用 |
| 单局流程 | 首页 → 匹配 → 阵营战斗 → 胜负加星 |
| 每日 | 论功行赏可领；平台奖励入口可用 |

---

## 4. 必改核心文件

### 4.1 配表与数据

| 文件 | 改动 |
|------|------|
| `assets/script/game/ConfigTableData.ts` | 仅 12 表；清理旧 getter |
| `assets/script/interface/AutoTable.ts` | 新表类型；删旧表 interface |
| `assets/script/game/GameData.ts` | 段位存档字段 |
| `assets/script/game/ConfigProjectData.ts` | 删闯关逻辑，增 Rank/Level |
| `assets/script/game/ConfigRes.ts` | UIID 与 bundle 裁剪 |
| `assets/script/game/ResPkgBuilder.ts` | 预载列表 |

### 4.2 战斗

| 文件 | 改动 |
|------|------|
| `assets/script/battle/config/ChapterLevelBuilder.ts` | → Level 表 |
| `assets/script/battle/bag/WeaponComposeConfigProvider.ts` | → Text + Hero |
| `assets/script/battle/bag/BattleBagSession.ts` | 删 type3/路径逻辑 |
| `assets/script/battle/bag/BagWeaponPool.ts` | 读 Text 表 |
| `assets/script/battle/runtime/BattleRuntime.ts` | 阵营双玩家 + AI |
| `assets/script/ui/BattleGame/UIBattleGame.ts` | 大幅裁剪 |
| `assets/mx/module/battle/core/BattleSession.ts` | campPolicy=pvp |

### 4.3 局外

| 文件 | 改动 |
|------|------|
| `assets/script/ui/PanelHome/UIPanelHome.ts` | 段位首页 |
| `assets/script/ui/pageWeapon/UIpageWeapon.ts` | Weapon/Hero 新表 |
| `assets/script/ui/TurnTable/UITurnTable.ts` | Battlebuff 配置 |
| `assets/script/ui/MainUI/UIMainUI.ts` | Tab 裁剪（待美术） |

---

## 5. 可删除清单

### 5.1 ConfigRes UIID（计划注销）

以下 UI 模块在新产品中 **不做**，开发时从 `UIID` / `UIConfigs` 移除：

| 类别 | UI 目录 |
|------|---------|
| 副本 | `Replica/`, `ReplicaBox/`, `pageDungeon/`, `dungeonBox/`, `PopHelp/` |
| 角色养成 | `pageUserLevelup/`, `pageUserLevelupDetail/`, `skin/`, `skinLevel/` |
| 章节相关 | `selectDifficult/`, `jumpGameLevel/`, `chapterGift/`, `challengeTip/` |
| 任务 | `taskView/` |
| 签到主流程 | `sign7Day/`（论功行赏替代） |
| 商业化 | `PopFund/`, `PopGiftmonth/`, `PopFirstRecharge/`, `PopContinuouslyBag/`, `diamondShop/` |
| 活动 | `SignNewYear/` |
| 功能解锁 | `GetNewFun/`, `PopUnLockBtn/` |
| 叙事 | `saveText/`, `LayerGuide/`, `StoryLine` 相关 |
| 引流 | `atGameChoose` 及 attractingTraffic 相关 UIID |
| 其他 | `wipeOut/`, `boxLevelupDetail/`, `PanelCDK/`, `PanelComplain/` |

### 5.2 TS 目录（Phase 2 删除）

```
assets/script/attractingTraffic‌Game/          # 引流小游戏
assets/bundles/attractingTraffic‌Game/         # 对应 bundle
assets/script/ui/Replica/
assets/script/ui/ReplicaBox/
assets/script/ui/pageDungeon/
assets/script/ui/taskView/
assets/script/ui/sign7Day/                    # 主流程替代后
assets/script/ui/PopFund/
assets/script/ui/PopGiftmonth/
assets/script/ui/PopFirstRecharge/
assets/script/ui/PopContinuouslyBag/
assets/script/ui/pageUserLevelup/
assets/script/ui/pageUserLevelupDetail/
assets/script/ui/skin/
assets/script/ui/skinLevel/
assets/script/ui/selectDifficult/
assets/script/ui/jumpGameLevel/
assets/script/ui/chapterGift/
assets/script/newFun/                         # NewFun 解锁
assets/script/manager/TargetTaskManager.ts
assets/script/manager/ConstReplicaManager.ts
assets/script/manager/ChapterDataManager.ts   # 评估后删或极简化
assets/script/manager/ChapterFieldResolver.ts
assets/script/activity/                       # 季节性活动
```

### 5.3 Bundle（Phase 2~4 删除）

| Bundle | 说明 |
|--------|------|
| `attractingTrafficGame` | 引流小游戏 |
| `replica` | 副本 |
| `role` | 角色 Tab（若无其他引用） |
| `fund`, `giftMonth`, `firstRecharge`, `continuouslyBag`, `diamondShop`, `chapterGift` | 商业化子包 |

### 5.4 战斗遗留（Phase 3 删除或停用）

| 路径 | 说明 |
|------|------|
| `PvPBattleMode` | 双玩家槽 + 全图部署区；半图镜像 API 已删 |
| `assets/script/ui/BattleGame/ChoukaScript.ts` | Gacha 模式 |
| `assets/script/ui/BattleGame/ObstacleBrushController.ts` | 障碍刷格 |
| `assets/script/battle/view/Chapter1BattleGuidePresenter.ts` | 拖格子引导 |
| `assets/script/battle/view/MapLayer2BattleGuidePresenter.ts` | 金手指引导（视新引导重做） |
| `assets/script/battle/view/PathFlowLinePresenter.ts` | 拖路预览 |
| `assets/script/ui/BattleGame/JPS.ts` | 旧寻路 |

---

## 6. 配表与存档迁移

### 6.1 存档字段（建议）

| 新字段 | 类型 | 说明 |
|--------|------|------|
| `rankId` | number | 当前段位 id（Rank 表） |
| `rankStars` | number | 当前段内星数（0~level） |
| `dailyWins` | number | 今日胜场 |
| `yesterdayRankId` | number | 昨日结算时段位（论功行赏） |
| `yesterdayWins` | number | 昨日胜场 |
| `meritClaimedDate` | string | 论功行赏领取日期 |
| `dailyItems` | array | 当日 Battlebuff 道具（主动+被动） |
| `heroWeapons` | object | 神将装备映射 |

**删除字段**（迁移后）：`chapter`、`chapterBox`、`replicaProgress`、`taskProgress`、`sign7Day` 等。

### 6.2 旧存档策略

- 新产品上线视为 **新档**；不做老档自动迁移（除非另行需求）
- 开发阶段可清空本地存储验证

---

## 7. 局外导航方案（待美术定稿）

| 方案 | 描述 | 影响文件 |
|------|------|----------|
| **A：单页入口** | 首页集中入口（原型） | `UIPanelHome` 承载全部跳转；可简化或移除 `UIMainUI` Tab |
| **B：精简 Tab** | 底部 2~3 Tab（首页/商店/神将武器） | 改造 `UIMainUI`，删 Role/Replica Tab |

**共同约束**：

- 删除 Role、Replica Tab 及 bundle 依赖
- 排行榜、论功行赏、转盘可作为首页入口或独立弹窗

---

## 8. 风险与回滚

| 风险 | 缓解 |
|------|------|
| 代码仍引旧表导致编译失败 | Phase 1 先改类型与 Builder，再删 UI |
| 删 bundle 后 prefab 引用断裂 | 用编辑器「引用查找」+ grep 确认零引用 |
| 阵营地图配置错误 | `campAreaMapValidation` 开战前校验，失败 warn 并中止 |
| 原型细节与正式需求不符 | 文档标「待正式需求」，不擅自实现 |

**回滚**：按 Phase 提交 Git，每 Phase 结束前保持可编译、可进游戏。

---

## 9. 相关文档

| 文档 | 说明 |
|------|------|
| [需求-新项目概述.md](./需求-新项目概述.md) | 产品大致需求 |
| [需求-模块保留.md](./需求-模块保留.md) | 模块保留/删除决策 |
| [遗留代码收敛方案.md](./遗留代码收敛方案.md) | 代码规范收敛 |
| [开发规范.md](./开发规范.md) | 生成代码必遵 |