# 需求：新项目概述

> 状态：**大致需求**（基于策划原型 + 已整理配表推断，非正式功能需求）  
> 日期：2026-08-17  
> 原型参考：[xiaopiu 项目](https://www.xiaopiu.com/h5/byId?type=project&id=6a718cee552cb040ea2a00f9)（仅作参考，正式需求开发时逐项给出）  
> 关联：[需求-模块保留.md](./需求-模块保留.md)、[方案-项目结构整理与遗留清理.md](./方案-项目结构整理与遗留清理.md)

## 1. 背景与文档范围

当前仓库 **AdLikeXy** 由老项目完整复制而来，正在改造为 **新产品**。本文档描述：

- 新产品与老项目的 **核心差异**
- 局外 / 局内 **大致功能边界**
- **12 张配表** 与玩法模块的映射关系
- 核心 **业务流程**

**不包含**：各功能的交互细节、数值验收、美术规范。每项功能开发前须另写 `docs/需求-{功能名}.md` 作为正式需求。

---

## 2. 与老项目的五大差异

| 维度 | 老项目 | 新项目 |
|------|--------|--------|
| **进度** | 章节闯关（Chapter）、难度、章节宝箱、副本 | **段位制**：胜利 +1 星、失败 -1 星；[`Rank.json`](../assets/bundles/first/config/Rank.json) |
| **战斗形态** | Solo PVE 波次塔防 | **1v1 对抗**：玩家 vs AI，同图双阵营；**不做联机** |
| **对抗架构** | 早期半图镜像（已删除） | **阵营区域方案**：`MapGrid.CampAreaID` + `CampAreaPolicy preset=pvp` |
| **地图与背包** | 可拖 type3 格子改怪物路线；刷新文字+格子+金手指 | **路线固定**；仅刷新 **文字 + 铲**；合成玩法复用 |
| **局外** | 5 Tab + 任务/签到/基金/副本/皮肤/引流小游戏等 | **大幅精简**（见 §4）；导航形态待美术定稿 |

```mermaid
flowchart LR
    subgraph old [老项目]
        Chapter[闯关制]
        SoloPVE[Solo PVE]
        GridDrag[拖格子改路]
        ManyMeta[大量局外]
    end
    subgraph newProj [新项目]
        Rank[段位制]
        PvAI[玩家 vs AI]
        CampArea[阵营区域对抗]
        SlimMeta[精简局外]
    end
    Chapter --> Rank
    SoloPVE --> PvAI
    GridDrag --> CampArea
    ManyMeta --> SlimMeta
```

---

## 3. 配表体系

新项目配表已收敛为 **12 张**，定义于 [`ConfigTableData.TableNames`](../assets/script/game/ConfigTableData.ts)。旧表（Chapter、Shop、Task、Sign、Lottery、Weapon1/2…）已从 `first/config` 删除。

### 3.1 配表总览

```mermaid
flowchart TB
    subgraph meta [局外]
        Const[Const 常量]
        Rank[Rank 段位]
        Item[Item 道具]
        Weapon[Weapon 神兵]
        Hero[Hero 神将]
        Headicon[Headicon 头像]
    end
    subgraph battle [局内]
        Level[Level 战场]
        Text[Text 字池含铲子]
        Skill[Skill 词条]
        Battlebuff[Battlebuff 道具]
        Monster[Monster 怪物]
        Monster1[Monster1 血量组]
    end
    Rank --> Level
    Rank --> AI[AI 行为配置]
    Text --> Hero
    Weapon --> Hero
    Battlebuff --> ShopWheel[商店/转盘]
    Level --> Monster
```

### 3.2 旧表 → 新表映射

| 老表 | 新表 | 说明 |
|------|------|------|
| Chapter / Chapter_monster | **Level** | 战场关卡与出怪；匹配按 Const 31~37 当天池随机 Level.id |
| Chapter 难度/奖励 | **Rank** | 段位进度、每日俸禄、AI 参数 |
| Weapon1 | **Hero** | 战斗单位（基础字/合成神将/道具功能） |
| Weapon2 | **Text** | 背包刷新字池；type=4 为铲子 |
| Weapon3/4、Role | — | 已删除，数值合并到 Hero |
| Shop / ShopBuy | **Battlebuff** + **Item** | 局外道具商店改读 Battlebuff |
| Task / TaskReward | — | 已删除 |
| sign | — | 由论功行赏替代 |
| Lottery | — | 转盘逻辑保留，配置改读 Battlebuff + Const |
| ConstConf / Const_weight | **Const** | 合并为单常量表 |
| base_atk | **Skill**（部分） | 战斗技能配置；术语见战斗需求说明 |
| Skin / Replica / NewFun 等 | — | 已删除 |

### 3.3 关键字段说明

#### Rank（段位）

| 字段 | 含义 |
|------|------|
| `name` | 段位名称（人仙·一、真仙·四…） |
| `level` | 段内星级上限（5） |
| `reward` | 每日俸禄：`道具id\|数量` |
| `diffcult` | 局内难度加值 |
| `weapondrop` / `weaponweight` | 装备掉落概率与品质权重 |
| `aiweapon` | AI 装备品质分布（白/绿/蓝/紫/橙） |
| `aiusead` | AI 使用广告道具概率（万分比） |
| `aiusechanzi` | AI 铲子使用类型权重（3 档，见 [需求-AI决策.md](./需求-AI决策.md) §6.2） |
| `aiusetext` | AI 普通字使用类型权重（2 档，见 [需求-AI决策.md](./需求-AI决策.md) §6.3） |
| `charactersweight` | 局内字池选档（元素 N → Text.numberN）；玩家读己方段位，AI 读对手段位（见 [需求-AI决策.md](./需求-AI决策.md)） |

#### Level（战场）

| 字段 | 含义 |
|------|------|
| `name` | 战场名：花果山 / 东海龙宫 / 幽冥地府 / 天庭 |
| `monster` | 波次出怪串（替代 Chapter_monster） |
| `boss` / `bosspro` | Boss 波次与概率 |
| `startnumber` | 初始桃子数量 |
| `reward` / `loserreward` | 胜负奖励：`道具id\|数量`（多项逗号分隔） |
| `map` | 地图资源（暂空时按 id → `mapLayer{id}`） |

#### Text（字池）

| type | 含义 |
|------|------|
| 1 | 基础字 |
| 2 | 武将组合字 |
| 3 | buff 文字 |
| 4 | **铲** |

| 字段 | 含义 |
|------|------|
| `quality` | 品质：`0` 白 / `1` 绿 / `2` 蓝 / `3` 紫 / `4` 橙（全项目约定见 [需求-品质约定.md](./需求-品质约定.md)） |
| `number1~20` | 各档位下该字最大持有数量 |

#### Hero（神将）

| 字段 | 含义 |
|------|------|
| `herotype` | 1 基础字 / 2 合成神将 / 3 道具功能 |
| `quality` | 1 绿 / 2 蓝 / 3 紫 / 4 橙（无白色；与全局 0~4 约定一致） |
| `text` | 组成文字 id 列表 |
| `weapon` | 武器类型（刀/枪/棍/弓/特殊） |
| `atk_id` | 各等级普攻技能 id |
| `level_limit` | 局内等级上限 |

#### Battlebuff（局外道具）

| type | 含义 |
|------|------|
| 1 | **主动**道具（局内 2 槽，原型） |
| 2 | **被动**道具（局内 6 槽，原型） |
| 3 | 局外功能（如体力道具） |

道具 **当日有效**（原型约定）；商店购买、转盘抽取均从此表读取。

#### Const（关键常量 id）

| id | 含义 |
|----|------|
| 1~3 | 体力初始/上限/恢复 |
| 4~5 | 战斗刷新桃子消耗 |
| 6 | 开战体力消耗 |
| 7~8 | 转盘刷新几率、商店广告权重 |
| 10 | 波次间隔 |
| 11 | 匹配星级偏移权重：相对玩家 `-5~+4` 星共 10 档（见 [需求-AI决策.md](./需求-AI决策.md)） |
| 12 | 对方主动道具数量权重（`-1,0,+1`），结果 clamp 0~2 |
| 14 | 对方被动道具数量权重（`-2,-1,0,+1`），结果 clamp 0~6 |
| 15~16 | 玩家连胜≥3：加强 AI（主动/被动「+1」档权重加成；满上限则加到 0 档） |
| 17~18 | 玩家连败≥3：削弱 AI（主动「-1」/被动「-2」档权重加成） |
| 30 | 连败组合字保底万分比（见 [需求-背包刷新.md](./需求-背包刷新.md) §4.3） |

---

## 4. 局外需求（原型图 1~8）

> 以下均为 **大致需求**，开发时须出正式 `docs/需求-*.md`。

### 4.1 保留 / 新建

| 模块 | 原型 | 功能要点 | 配表 | 代码方向 |
|------|------|----------|------|----------|
| **首页** | 图1 | 头像/金币/体力、设置、公告、段位星、开始游戏、排行榜、神将武器入口 | Rank, Headicon, Item, Const | 改造 `UIPanelHome`；去掉章节选关 |
| **论功行赏** | 图2 | 昨日段位奖励 + 昨日胜场奖励，每日领取 | Rank.reward | **新建 UI**；替代 7 日签到主流程 |
| **平台奖励** | 图1 侧边按钮 | 侧边栏奖励、添桌奖励 | 平台 SDK | 保留入口，与论功行赏并列 |
| **神将武器** | 图3~4 | 神将网格 + 武器库、拖拽装备、详情、按品质批量出售 | Weapon, Hero, Item | 改造 `UIpageWeapon` |
| **商店** | 图5~6 | 购买主动/被动道具、我的道具栏、当日有效、满栏提示、删除确认 | Battlebuff, Const | 新建或大幅改造（旧 Shop 已删） |
| **道具大转盘** | 图7~8 | 3×3 抽奖（分享/广告）、我的道具、满栏替换弹窗 | Battlebuff, Const 7~8 | 改造 `UITurnTable` |
| **排行榜** | 图1 备注 | 段位榜 + **今日胜场榜** | Rank + SDK TTRank | **新建 UI** |

### 4.2 删除 / 不再做

| 老模块 | 删除理由 |
|--------|----------|
| 章节闯关（Chapter、选难度、跳关、章节礼包） | Rank + Level 替代 |
| 副本 Tab（Replica、pageDungeon） | 无配表、原型无 |
| 角色 Tab / 皮肤养成 | 无 Role/Skin 表；神将由 Hero 表达 |
| 任务成就（taskView） | Task 表已删 |
| 7 日签到主流程（sign7Day） | 论功行赏替代 |
| 商业化弹窗（基金/月卡/首充/连续购） | MVP 不做 |
| 功能解锁（NewFun） | 表已删 |
| 引流小游戏（attractingTrafficGame） | 明确删除 |
| 离线收益（wipeOut） | 原型无，可后删 |
| 旧商店宝箱/碎片逻辑 | Shop 表已删 |

### 4.3 局外导航（待美术定稿）

- **方案 A**：单页首页 + 功能入口（对齐当前原型）
- **方案 B**：精简底部 Tab（如 首页 / 商店 / 神将武器）

共同约束：删除 Role、Replica Tab。

---

## 5. 局内需求（原型图 9~16）

### 5.1 对抗架构：阵营方案

采用 **阵营区域方案**（全图逻辑坐标，不做半图镜像）：

```mermaid
flowchart TB
    subgraph map [同一张全图 mapLayerN]
        Camp1[阵营区域1 己方路径与部署区]
        Camp2[阵营区域2 AI路径与部署区]
    end
    MapGrid["MapGrid.CampAreaID"] --> Topology["MapTopology.campAreaByCell"]
    Topology --> Pathfinder["Pathfinder 按 campAreaId 分区寻路"]
    Pathfinder --> Move[怪物沿各自固定路径移动]
    Policy["CampAreaPolicy preset=pvp"] --> Systems[出怪/索敌/部署/经济隔离]
```

| 组件 | 路径 | 职责 |
|------|------|------|
| 地图标注 | `MapGrid.CampAreaID` | 编辑器每格配置阵营（原型橙/灰双路径） |
| 拓扑导入 | `importTopologyFromMapManager` + `campAreaMapValidation` | 出怪口/攻击点绑定 campAreaId |
| 寻路 | `Pathfinder` | 多阵营独立距离场，怪物不跨区 |
| 策略 | `CampAreaPolicy` preset `pvp` | 部署、出怪、索敌等全维度隔离 |
| 会话 | `BattleSession.campPolicy` | 开战 `resolveCampAreaPolicy(topology, 'pvp')` |
| 双槽 | `PvPBattleMode` | 玩家/AI 各一槽；部署区全图 |

**已删除的半图镜像 API**：`createHalfRegion`、`mirrorCellToTop` / `mirrorCellFromTop`、`pvpHalfRows`、`toDisplayCell`。

### 5.2 可复用（与老项目相同）

| 模块 | 路径/说明 |
|------|-----------|
| 地图管线 | `CocosBattleMapHost` + `mapLayer1`（已编辑，须含双阵营 CampAreaID）→ mapLayer2~4 待编辑 |
| 波次出怪 | `WaveSpawner` + Level.monster/boss |
| 汉字背包合成 | `MergeSession` + `BattleBagSession` |
| 铲 | Text type=4 → `Weapon2TileType.Shovel` 放置逻辑 |
| 战斗 ECS | `BattleRuntime` + `DeploySync` |
| 词条三选1 | Skill 表 |
| UI 骨架 | `UIBattleGame`（需大幅裁剪） |

### 5.3 需改造 / 新建

| 需求 | 改造方向 |
|------|----------|
| 玩家 vs AI | 双玩家槽 local + AI，各绑 `campAreaId`；`campPolicy=pvp` |
| 固定路线 | 拓扑导入后锁定 walkable；删除 type3 堵路校验与路径 rebuild |
| 仅文字+铲子 | 刷新池改读 Text 表；删 GachaMode、type3 格子、地图内二次拖字 |
| 对抗 UI | 上下对称：敌方/己方头像、被动栏、波次（原型） |
| 局内弹窗 | 神将图鉴、本局字库（概率+已抽字）、点击文字详情 |
| 胜负与段位 | 结算 → 星数变化 → 存档；匹配读 Const 11 |
| 局外道具带入 | 开战携带 Battlebuff 主动×2 + 被动×6（原型，正式需求待确认槽位数） |

### 5.4 明确删除的局内逻辑

| 模块 | 说明 |
|------|------|
| type3 扩展格子 | 拖格子改路线，新项目不需要 |
| GachaMode / ChoukaScript | 抽卡铲子+障碍刷格 |
| PathFlowLinePresenter 拖路预览 | 固定路线后无意义 |
| 章节拖格子引导 | Chapter1BattleGuidePresenter 等 |
| 副本专属机制 UI | 按新产品 Hero/机制裁剪 |

---

## 6. 核心流程

### 6.1 匹配与战斗

```mermaid
sequenceDiagram
    participant Home as 首页
    participant Match as 匹配
    participant Battle as BattleRuntime
    participant Bag as BattleBagSession
    participant ECS as BattleSession

    Home->>Match: 消耗体力，按 Rank 匹配 Level 与 AI
    Match->>Battle: 双玩家槽 + campPolicy=pvp
    Battle->>Bag: 初始化 Text 字池与段位上限
    Bag->>ECS: DeploySync 按 campAreaId 部署
    ECS->>ECS: 双方各自区域出怪沿固定路径
    ECS->>Home: 胜负结算，星数 ±1
```

### 6.2 每日奖励

```mermaid
sequenceDiagram
    participant Player as 玩家
    participant Merit as 论功行赏
    participant Platform as 平台奖励

    Note over Player: 每日 0 点结算昨日数据
    Player->>Merit: 领取昨日段位奖励 Rank.reward
    Player->>Merit: 领取昨日胜场奖励
    Player->>Platform: 侧边栏/添桌奖励（独立入口）
```

---

## 7. 待后续正式需求的功能

以下功能 **仅有大致边界**，开发前须逐项出 `docs/需求-*.md`：

| 序号 | 功能 | 备注 |
|------|------|------|
| 1 | 首页与开始游戏 | 导航形态待美术 |
| 2 | 段位星展示与升降星规则 | 边界星、保段等数值待策划 |
| 3 | 论功行赏 | 胜场奖励公式 |
| 4 | 排行榜（含今日胜场榜） | SDK 对接细节 |
| 5 | 神将武器（装备/回收） | 拖拽交互、分页 |
| 6 | 道具商店 | 槽位数、刷新规则、广告购 |
| 7 | 道具大转盘 | 权重、替换流程 |
| 8 | 匹配与 AI | 正式需求见 [需求-AI决策.md](./需求-AI决策.md) |
| 9 | 局内战斗全流程 | 对抗 UI、道具带入、结算 |
| 10 | 局内弹窗 | 图鉴、字库、点击详情 |

---

## 8. 相关文档

| 文档 | 说明 |
|------|------|
| [需求-模块保留.md](./需求-模块保留.md) | 模块保留/删除清单（已确认） |
| [方案-项目结构整理与遗留清理.md](./方案-项目结构整理与遗留清理.md) | 代码与资源整理实施路线 |
| [assets/script/battle/docs/需求说明.md](../assets/script/battle/docs/需求说明.md) | 战斗术语与架构约束（待增新项目差异章节） |
| [需求-AI决策.md](./需求-AI决策.md) | 匹配与 AI 局内决策（正式需求） |
| [项目分析报告.md](./项目分析报告.md) | 老项目基线参考 |