# 文字三国策略游戏

**Repository Path**: cnzkai/sg

## Basic Information

- **Project Name**: 文字三国策略游戏
- **Description**: 前端uniapp,后端php(thinkphp6)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 三国策略游戏 · 完整策划文档

> 版本：v1.0  ｜  最后更新：2026-07-02  ｜  项目代号：`sg`
> 仿《热血三国》文字版策略游戏，500×500 世界地图，16 种建筑，6 种兵种，异步回合制战斗，5 种队列体系。

---

## 目录

1. [系统总览](#1-系统总览)
2. [建筑系统](#2-建筑系统)
3. [资源系统](#3-资源系统)
4. [名将系统](#4-名将系统)
5. [兵种与征兵系统](#5-兵种与征兵系统)
6. [战斗系统](#6-战斗系统)
7. [地图与野地系统](#7-地图与野地系统)
8. [行军与驿站系统](#8-行军与驿站系统)
9. [城防系统](#9-城防系统)
10. [科技系统](#10-科技系统)
11. [市场系统](#11-市场系统)
12. [装备系统](#12-装备系统)
13. [队列系统](#13-队列系统)
14. [侦察系统](#14-侦察系统)
15. [竞技场系统](#15-竞技场系统)
16. [医馆系统](#16-医馆系统)
17. [增援系统](#17-增援系统)
18. [联盟系统](#18-联盟系统)
19. [爵位与声望系统](#19-爵位与声望系统)
20. [民心系统](#20-民心系统)
21. [任务系统](#21-任务系统)
22. [商城与道具系统](#22-商城与道具系统)
23. [定时任务与调度](#23-定时任务与调度)
24. [API 路由总表](#24-api-路由总表)
25. [数据库表索引](#25-数据库表索引)

---

## 1. 系统总览

### 1.1 技术架构

| 层级 | 技术栈 | 说明 |
|------|--------|------|
| 后端 | ThinkPHP 6（PHP 7.4） | `server/app/sg/` |
| 前端 | uni-app（Vue 2） | `client/`，支持 H5 + 小程序 + App |
| 数据库 | MySQL 5.7 | 表前缀 `tpw_sg_` |
| 定时任务 | ThinkPHP Console | 每分钟 crontab |

### 1.2 核心货币

| 货币 | 来源 | 用途 |
|------|------|------|
| 银两（silver） | 税收、市场出售、任务 | 建造、征兵、科技、招募名将 |
| 粮食（food） | 农田、野地加成 | 建造、征兵、军队消耗 |
| 木材/石料/铁矿 | 伐木场/采石场/冶炼厂 | 建造、城防工具制造 |
| 黄金（gold） | 充值、任务 | 洗髓、刷新招贤馆、购买队列、加速 |
| 声望（fame） | 战斗、占领野地 | 爵位晋升 |

### 1.3 资源生产基础设计

每座城池拥有 4 块资源地（农田/伐木场/采石场/冶炼厂），Lv.1 单块 100/小时（4 块合计 400 基础产量），每升 1 级 4 块各 +40（合计 +160/小时）。

---

## 2. 建筑系统

**关键文件**：`server/app/sg/model/City.php`、`server/config/build_config.json`、`server/app/sg/controller/Build.php`

### 2.1 建筑类型（共 16 种）

| 字段 | 名称 | 功能 | time_base | uselevel |
|------|------|------|-----------|----------|
| official | 官府 | 行政中心，限制其他建筑上限、决定野地占领数 | 100 | 0.2 |
| wall | 城墙 | 提升城池耐久 | 90 | 1 |
| drill | 校场 | 决定出征队列数，进入竞技场 | 80 | 0.2 |
| tower | 烽火台 | 预警范围，进入城防部署 | 80 | 5 |
| follower | 招贤馆 | 名将上限与星级 | 70 | 1 |
| school | 学校 | 科技等级上限与队列 | 70 | 1 |
| station | 驿站 | 行军速度加成 | 60 | 1 |
| market | 市场 | 交易税率与银两上限 | 60 | 1 |
| hospital | 医馆 | 伤兵治疗速度 | 50 | 1 |
| warehouse | 仓库 | 资源存储上限（每级 +10%） | 50 | 2 |
| camp | 军营 | 兵力上限（每级 +1000） | 40 | 1000 |
| house | 民房 | 人口（每级 +50） | 40 | 1000 |
| farmland | 农田 | 粮食产量 | 30 | 10 |
| lumber | 伐木场 | 木材产量 | 30 | 10 |
| quarry | 采石场 | 石料产量 | 30 | 10 |
| smelter | 冶炼厂 | 铁矿产量 | 30 | 10 |

> 已删除建筑：**鸿胪寺**（diplomatic），联盟功能改为从主城 union-bar 直接进入。

### 2.2 升级消耗公式

```
factor = targetLevel² / 2
silver = floor(base_silver × factor)
food   = floor(base_food   × factor)
wood   = floor(base_wood   × factor)
stone  = floor(base_stone  × factor)
iron   = floor(base_iron   × factor)
time   = floor(time_base   × factor)   单位：秒
```

- 配置来源：`tpw_sg_build_cost_config` 表
- 兜底默认值（配置缺失时）：silver=2000, food=500, wood=1000, stone=1500, iron=500, time=120

### 2.3 等级限制

- 所有建筑等级 **不得超过官府等级**
- 官府硬上限 **50 级**
- 建筑入口映射（前端 `buildPageMap`）：

| 建筑 | 页面路径 |
|------|----------|
| school | `/pages/tech` |
| market | `/pages/market` |
| hospital | `/pages/hospital` |
| camp | `/pages/recruit` |
| follower | `/pages/recruitHero` |
| wall | `/pages/wall` |
| official | `/pages/official` |
| drill | `/pages/arena`（竞技场） |
| tower | `/pages/defense`（城防部署） |

### 2.4 建造队列

- 默认 **2 个**建造队列
- 官府每 10 级 +1 队列
- 加速：1 黄金 = 60 秒（`goldCost = max(1, ceil(remain/60))`）
- 取消建造：资源**全额返还**

### 2.5 官府专属功能

| 功能 | 冷却 | 消耗 | 效果 |
|------|------|------|------|
| 手动增收 | 6 小时 | 粮食 = 人口×2 | 银两 = `floor((人口×4+市场×40)×官府等级×0.5)`，民心 -2 |
| 祈福安民 | 12 小时 | 银两 = 官府×500，粮食 = 官府×300 | 民心 +10（上限100） |

### 2.6 官府野地占领显示

官府详情页显示：`野地：占领数 / 可占领总数`，以及野地资源加成明细（粮/木/石/铁 +N/h）。

---

## 3. 资源系统

**关键文件**：`server/app/sg/model/City.php`（`getStatsAttr`）、`server/app/sg/service/Resource.php`

### 3.1 产量公式

```
人口 people = house等级 × 50
兵力上限 troops_cap = camp等级 × 1000 + tongshuai任命加成
银两/小时 tax_rate = (people × 4 + market等级 × 40) × official等级
粮食/小时 food_rate = 400 + farmland等级 × 160
木材/小时 wood_rate = 400 + lumber等级 × 160
石料/小时 stone_rate = 400 + quarry等级 × 160
铁矿/小时 iron_rate = 400 + smelter等级 × 160
城墙耐久 durability = 2000 + wall等级 × 1000
```

### 3.2 资源上限公式

```
cap = 20000 + build_level × 5000
final_cap = floor(cap × (1 + warehouse等级 × 0.1))
```

- 银→market / 粮→farmland / 木→lumber / 石→quarry / 铁→smelter
- 仓库每级全局 +10%

### 3.3 结算机制

```
每秒产量 = 每小时产量 / 3600
实际产出 = 每秒产量 × 离线秒数 × 民心效率
```

- 在线结算：每分钟执行（`sg:resource` 命令），2 分钟内活跃视为在线
- 离线结算：登录时按 `city.last_settle` 增量结算
- 野地加成由 `City::getStatsAttr` 统一计算并并入 `*_rate` 字段，避免重复

### 3.4 人口增长规则

| 民心 | 人口增长 |
|------|----------|
| ≥ 50 | 每小时增长 people_cap × 5% |
| 30-49 | 停止增长 |
| 1-29 | 每小时减少 people_cap × 5% |
| 0 | 触发建筑降级惩罚 |

### 3.5 名将任命加成

| 职位 | 加成效果 |
|------|----------|
| 城守（内政） | 资源产量 +neizheng×1%，银两 +neizheng×2% |
| 军师（智谋） | 科技速度 +zhimou×1%，行军速度 +zhimou×0.5% |
| 主将（统帅） | 兵种攻击 +tongshuai×0.5%，兵力上限 +tongshuai×10 |

### 3.6 新城池初始资源

```
silver=5000, food=8000, wood=8000, stone=8000, iron=8000, people=100
official=1, farmland=1, lumber=1, quarry=1, smelter=1, house=1, warehouse=1, market=1
```

---

## 4. 名将系统

**关键文件**：`server/app/sg/controller/Hero.php`、`server/app/sg/model/Hero.php`、`server/app/sg/service/HeroExpService.php`

### 4.1 四维属性

| 属性 | 字段 | 说明 |
|------|------|------|
| 武力 | wuli | 影响攻击力 |
| 智谋 | zhimou | 影响防御力、科技速度 |
| 内政 | neizheng | 影响资源产量 |
| 统帅 | tongshuai | 影响带兵上限、兵种攻击 |
| 速度 | speed | 影响先手判定、行军速度 |

### 4.2 名将状态

| status | 含义 |
|--------|------|
| 0 | 闲置 |
| 1 | 驻守 |
| 2 | 出征 |
| 3 | 受伤 |
| 4 | 历练 |

### 4.3 星级与成长

- 星级 1-5 星，招贤馆最高刷 4 星
- 可招星级上限 = `min(4, 1 + floor(follower等级 / 3))`
- 成长上限（按星级）：1星30 / 2星40 / 3星50 / 4星60 / 5星80
- 招募初始成长 = `floor(growth_max × (0.6~1.0 随机))`
- 多维成长率 = `round(config_grow × (0.9 + rand(0,200)/1000), 2)`

### 4.4 招募机制

- 招募消耗银两 **50**（服务端硬编码）
- 名将上限 = 招贤馆等级
- 招贤馆池：固定 5 个，招募一个少一个
- 自动刷新间隔：1 小时（按等级减至 20 分钟）
- 手动刷新消耗黄金 **10**
- 星级校验：config_id 星级 ≤ 招贤馆可招星级上限

### 4.5 经验与升级

- 升级所需经验 = `level × 100`
- 升级加成：`wuli += wuli_grow`（四维同理）
- **每升 5 级自动学习 1 个随机技能**
- 技能升级上限 5 级

### 4.6 战斗力公式

```
base = (wuli + zhimou + tongshuai) × level + neizheng × 0.5
power = floor(base × (1 + growth / 200))
```

### 4.7 带兵上限

```
troop_cap = tongshuai × 100 + growth × 5
```

### 4.8 洗髓系统

- 每次消耗 **100 黄金**（中级档 70%-90%）
- 重置成长点数与多维成长率
- 档位：1初级(60%-80%) / 2中级(70%-90%) / 3高级(80%-100%)

### 4.9 历练系统

| 等级 | 名称 | 时长 | 经验 | 银两消耗 |
|------|------|------|------|----------|
| 1 | 白色历练 | 1 小时 | 100 | 1,000 |
| 2 | 绿色历练 | 2 小时 | 300 | 3,000 |
| 3 | 蓝色历练 | 4 小时 | 1,000 | 10,000 |
| 4 | 紫色历练 | 8 小时 | 3,000 | 30,000 |
| 5 | 红色历练 | 16 小时 | 10,000 | 100,000 |

- 已任命职位的名将不可历练
- 历练中 status=4

### 4.10 好感度系统

| 等级 | 范围 | 颜色 |
|------|------|------|
| 1 | 0-19 | 白 |
| 2 | 20-39 | 绿 |
| 3 | 40-59 | 蓝 |
| 4 | 60-79 | 紫 |
| 5 | 80-100 | 红 |

- 赠礼增加好感度（上限100），同时提升忠诚 `loyalty = min(100, loyalty + ceil(amount/5))`

### 4.11 传奇名将示例

| 名将 | 武力 | 智谋 | 内政 | 统帅 | 星级 |
|------|------|------|------|------|------|
| 吕布 | 100 | - | - | - | 5 |
| 关羽 | 97 | 75 | - | - | 5 |
| 张飞 | 98 | - | - | - | 5 |
| 赵云 | 96 | - | - | - | 5 |
| 诸葛亮 | - | 100 | 98 | - | 5 |
| 司马懿 | - | 96 | - | 90 | 5 |
| 曹操 | 80 | 94 | 98 | 95 | 5 |

---

## 5. 兵种与征兵系统

**关键文件**：`server/app/sg/controller/Troop.php`、`server/app/sg/model/TroopConfig.php`

### 5.1 兵种配置

| id | 名称 | 攻击 | 防御 | HP | 速度 | 银两 | 粮食 | 铁矿 | 时间(秒) | 克制 |
|----|------|------|------|----|----|------|------|------|---------|------|
| 1 | 民兵 | 5 | 3 | 30 | 10 | 30 | 10 | 0 | 5 | — |
| 2 | 弓兵 | 8 | 4 | 30 | 15 | 80 | 30 | 10 | 10 | 3,5 |
| 3 | 步兵 | 6 | 8 | 50 | 12 | 100 | 40 | 20 | 12 | 4 |
| 4 | 骑兵 | 12 | 6 | 40 | 25 | 200 | 60 | 40 | 20 | 2,3 |
| 5 | 长枪兵 | 7 | 10 | 50 | 10 | 120 | 40 | 20 | 12 | 4 |
| 6 | 攻城器械 | 20 | 5 | 80 | 8 | 300 | 100 | 80 | 30 | — |

### 5.2 兵种克制

- 克制系数：`coef = 1.0 + 0.5 × ratio`（最多 +50%）
- 取双方兵种克制加权平均

### 5.3 征兵规则

- 消耗：silver + food + iron × 数量
- 每兵消耗 **1 人口**
- 兵力上限校验：`当前总兵力 + 征兵数 ≤ camp等级 × 1000`
- 取消征兵：资源与人口**返还 50%**
- 征兵队列：默认 1，军营每 10 级 +1

---

## 6. 战斗系统

**关键文件**：`server/app/sg/service/BattleService.php`、`server/app/sg/controller/Battle.php`

### 6.1 回合制算法

- 最大回合：**12 回合**
- 默认伤兵率：**30%**

### 6.2 名将加成

```
攻方加成 atkBonus = 1 + atkHero.wuli / 200
守方加成 defBonus = 1 + defHero.zhimou / 200
```

### 6.3 防守策略加成

| 策略 | ID | 防御加成 | 撤退阈值 |
|------|----|----------|----------|
| 死战 | 1 | +10% | 不撤退 |
| 坚守 | 2 | +30% | 兵力 < 20% 撤退 |
| 撤退 | 3 | 无加成 | 兵力 < 50% 撤退 |

- 守方撤退视为攻方胜利
- 撤退后保留剩余兵力

### 6.4 每回合伤害公式

```
atkPower = sum(兵种攻击 × 数量) × atkBonus
defPower = sum(兵种防御 × 数量) × defBonus
restrainCoef = 兵种克制系数（平均，最多 +50%）

dmgToDef = max(atkPower - defPower × 0.5, atkPower × 0.1) × restrainCoef
dmgToAtk = max(defPower × 0.6 - atkPower × 0.3, defPower × 0.05)
```

### 6.5 先手判定

```
atkSpeedScore = totalSpeed(atkTroops) × (1 + atkHero.speed / 100)
defSpeedScore = totalSpeed(defTroops) × (1 + defHero.speed / 100)
attackerFirst = atkSpeedScore >= defSpeedScore
```

### 6.6 伤害→兵力损耗

```
killed = floor(totalDamage / 10)   // 每点伤害消灭 0.1 兵
按各兵种占比分摊，最少 1
```

### 6.7 战斗结果

| result | 含义 |
|--------|------|
| 0 | 攻方败 |
| 1 | 攻方胜 |
| 2 | 平局 |

### 6.8 伤兵处理

- 损失兵力的 30% 转入医馆 `tpw_sg_wounded` 表
- 攻方伤兵入源城医馆，守方伤兵入被攻城医馆
- **伤兵只入医馆表，不加回存活兵力**（避免治疗后双重计算）

### 6.9 战利品

| 模式 | base 公式 | silver | food | wood | stone | iron |
|------|-----------|--------|------|------|-------|------|
| 掠夺 | defInitTotal × 10 | base | base×2 | base×0.5 | base×0.5 | base×0.3 |
| 占领 | defInitTotal × 2 | base | base | — | — | — |

### 6.10 名将经验

| 结果 | 经验 |
|------|------|
| 胜利 | 50 |
| 失败 | 10 |
| 平局 | 20 |

### 6.11 出征模式

| mode | 含义 |
|------|------|
| 1 | 占领 |
| 2 | 掠夺 |
| 3 | 侦察 |
| 4 | 增援 |
| 5 | 返回 |

### 6.12 守军配置

| 地形 | 守军 |
|------|------|
| NPC 城池(type 2/3/4) | 总兵力 = level × 50，步兵40%/弓兵30%/骑兵30% |
| 玩家城池(type 1) | 城池驻军 `{troop_id: num}` |
| 野地(type 5-9) | `{1: level × 10}` 民兵 |

### 6.13 战斗类型

| type | 含义 |
|------|------|
| 1 | 野地占领战 |
| 2 | 玩家攻击战 |
| 4 | 擂台 1v1 |
| 5 | 竞技场 5v5 |

---

## 7. 地图与野地系统

**关键文件**：`server/app/sg/controller/City.php`（`occupy`）、`server/app/sg/service/WildlandService.php`

### 7.1 地图类型

500×500 = 250,000 格世界地图

| type | 名称 | 说明 |
|------|------|------|
| 0 | 预留 | — |
| 1 | 玩家城池 | 玩家主城 |
| 2 | 县城 | NPC，Lv.30 |
| 3 | 郡城 | NPC，Lv.40 |
| 4 | 州城 | NPC，Lv.50 |
| 5 | 平地 | 野地，粮×5半产 |
| 6 | 粮田 | 野地，加粮 |
| 7 | 森林 | 野地，加木 |
| 8 | 山地 | 野地，加石 |
| 9 | 矿洞 | 野地，加铁 |
| 10 | 首都 | NPC，最高级 |

### 7.2 野地占领规则

- 仅可占领 type 5-9 野地
- 占领上限 = **主城官府等级**
- 流程：扣兵力 → 战斗 → 胜利才能占领
- 野地守军 = `map.level × 10` 民兵
- 胜利奖励：声望 `50 + map.level × 10`
- 胜利掉落装备（30% + level×2%，封顶 70%）

### 7.3 野地资源加成

```
仅主城 official > 0 享受
加成 = 野地等级 × 10/小时（平地 type=5 × 5 半产）

类型映射：
  5 平地 → food × 5
  6 粮田 → food × 10
  7 森林 → wood × 10
  8 山地 → stone × 10
  9 矿洞 → iron × 10
```

### 7.4 野地每日衰减

- **每日 04:00** 所有已占领野地等级 -1
- 降至 0 时：
  - 归还驻军给主城
  - 删除附属城池记录
  - 地图恢复 **50 级**
  - owner_id 清零
- 幂等机制：标记文件 `runtime/wildland_decay_marker.txt` 记录最后衰减日期
- 触发：`sg:resource` 每分钟检查

### 7.5 地图懒加载

- 以当前坐标为中心向四个方向扩展 20 格
- 视口中心超出 [1, 500] 范围阻止加载
- 中心格坐标用 `Math.floor` 计算，避免偏移

---

## 8. 行军与驿站系统

**关键文件**：`server/app/sg/service/BattleService.php`（`marchDuration`）

### 8.1 行军时长公式

```
距离 = 切比雪夫距离 = max(|x1-x2|, |y1-y2|)
坐标转换: x = mapId % 500 + 1, y = floor(mapId / 500) + 1
名将速度: speed = 1 + hero.speed / 100
驿站加成: stationBuff = max(0.5, 1 - station等级 × 0.05)
duration = floor(距离 × 30 / speed × stationBuff)
最低 10 秒
```

### 8.2 驿站规则

- 每级减少 5% 行军时间，下限 50%（最高减半）
- 作用于：出征行进、战斗后返程、援军行军
- 军师任命额外加成：`marchSpeedBuff = max(0.3, stationBuff × (1 - marchBonus))`
- 基础 1 格 = 30 秒

---

## 9. 城防系统

**关键文件**：`server/app/sg/controller/Wall.php`、`server/app/sg/controller/City.php`（`defense`/`saveDefense`）

### 9.1 城墙

- 耐久 = `2000 + wall等级 × 1000`
- 城墙等级限制防御工具制造

### 9.2 防御工具

| 类型 | 名称 | 木 | 石 | 铁 | 时间(秒) | 防御力 | 需城墙等级 |
|------|------|----|----|----|---------|--------|-----------|
| trap | 陷阱 | 200 | 100 | 50 | 60 | 10 | 1 |
| wood | 滚木 | 500 | 0 | 0 | 120 | 20 | 3 |
| stone | 雷石 | 0 | 500 | 0 | 120 | 25 | 5 |
| refuse | 拒马 | 300 | 0 | 300 | 180 | 35 | 7 |

- 制造即时入账（不排队）
- 总防御力 = `sum(defense_power × num)`

### 9.3 防守策略配置

通过烽火台进入城防部署页面配置：

| 策略 | ID | 效果 |
|------|----|------|
| 死战 | 1 | 防御 +10%，不撤退 |
| 坚守 | 2 | 防御 +30%，兵力 <20% 撤退 |
| 撤退 | 3 | 无加成，兵力 <50% 撤退 |

### 9.4 烽火台侦察范围

- 基础 2 格
- 每级 +1 格

---

## 10. 科技系统

**关键文件**：`server/app/sg/controller/Tech.php`

### 10.1 科技配置

| 名称 | 类别 | 效果 | 满级 | 需学校等级 |
|------|------|------|------|-----------|
| 种植术 | 生产 | food_rate +5/级 | 10 | 1 |
| 伐木术 | 生产 | wood_rate +5/级 | 10 | 1 |
| 采石术 | 生产 | stone_rate +5/级 | 10 | 2 |
| 冶炼术 | 生产 | iron_rate +5/级 | 10 | 2 |
| 征税术 | 生产 | tax_rate +5/级 | 10 | 3 |
| 兵法 | 军事 | attack +3/级 | 10 | 3 |
| 甲胄 | 军事 | defense +3/级 | 10 | 3 |
| 医术 | 军事 | wound_rate +2/级 | 10 | 5 |
| 建筑学 | 内政 | build_speed +5/级 | 10 | 2 |
| 仓储术 | 内政 | cap +10/级 | 10 | 2 |
| 城墙加固 | 城防 | durability +10/级 | 10 | 3 |
| 陷阱术 | 城防 | wall_attack +5/级 | 10 | 4 |

### 10.2 研究机制

- 消耗 = `cost_base × cost_factor^level`
- 队列上限：默认 1，学校每 10 级 +1

---

## 11. 市场系统

**关键文件**：`server/app/sg/controller/Market.php`

### 11.1 交易规则

- 商品：food/wood/stone/iron/silver
- 出售数量最少 100
- 不能购买自己的挂单

### 11.2 手续费（税率）

```
taxRate = max(0.0, 0.20 - market等级 × 0.01)
// 1级 20%，每升 1 级 -1%，直至 0%
tax = floor(price × taxRate)
totalPay = price + tax
```

### 11.3 挂单队列

- 默认 1
- 市场**每 5 级 +1**（注意：与其他队列每 10 级不同）
- 撤销挂单：商品全额返还

---

## 12. 装备系统

**关键文件**：`server/app/sg/controller/Equip.php`、`server/app/sg/service/BattleService.php`（`dropEquip`）

### 12.1 装备槽位

| slot | 类型 | 字段 |
|------|------|------|
| 1 | 武器 | equip_weapon |
| 2 | 护甲 | equip_armor |
| 3 | 坐骑 | equip_mount |
| 4 | 宝物 | equip_treasure |

### 12.2 装备掉落

```
掉落率 = 30% + min(40%, level × 2%)   // 封顶 70%
品质：level≤3 → 1-2星；level≤6 → 3-4星；level>6 → 4-5星
```

### 12.3 装备出售

- 售价 = `star × 50` 银两

### 12.4 装备示例

| 装备 | 星级 | 属性 |
|------|------|------|
| 青铜剑 | 1 | 武+5 |
| 寒铁剑 | 2 | 武+10 |
| 丈八蛇矛 | 4 | 武+25 统+8 |
| 倚天剑 | 5 | 武+30 智+5 统+5 |
| 青龙偃月刀 | 5 | 武+35 统+10 |
| 赤兔马 | 5 | 武+5 速+20 |
| 孙子兵法 | 5 | 智+15 政+10 统+10 |

---

## 13. 队列系统

**关键文件**：`server/app/sg/service/QueueService.php`、`server/app/sg/controller/Queue.php`

### 13.1 队列类型

| 类型 | 中文名 | 对应建筑 | 默认 | 建筑加成 |
|------|--------|----------|------|----------|
| build | 建造队列 | 官府 | 2 | 每 10 级 +1 |
| recruit | 征兵队列 | 军营 | 1 | 每 10 级 +1 |
| tech | 科技队列 | 学校 | 1 | 每 10 级 +1 |
| march | 出征队列 | 校场 | 1 | 每 10 级 +1 |
| market | 市场队列 | 市场 | 1 | **每 5 级 +1** |

### 13.2 永久队列购买

- 基础价格：**100 黄金**
- 递增价格：`100 × (已购买数 + 1)` 黄金
- 每类型最多购买 **5 个**永久队列
- 存 `queue_buff` 表，`expire_at=0` 表示永久

### 13.3 临时队列道具

- 道具名后缀解析时效：1日(24h)/2日(48h)/3日(72h)/7日(168h)/30日(720h)
- `expire_at > 0` 表示临时

### 13.4 队列不足处理

- 队列满时服务器返回 **HTTP 460**
- 前端 `api.js` 统一拦截 460，弹出购买入口
- 购买成功后自动重试原请求

---

## 14. 侦察系统

**关键文件**：`server/app/sg/controller/Scout.php`、`server/app/sg/service/ScoutService.php`

### 14.1 侦察机制

- 对任意 map_id 执行侦察，生成报告
- 报告内容：target_type、target_name、target_user、troops、resource、def_build

### 14.2 报告分类

| 目标 | target_type | 返回内容 |
|------|-------------|----------|
| 玩家城池 | 1 | 城池名、玩家名、完整驻军、五资源、wall/official 等级 |
| NPC 城池 | 2 | 兵力 = level×50（步40%/弓30%/骑30%） |
| 野地 | 3 | 兵力 = `{1: level×10}` |

### 14.3 报告列表

- 最多返回 30 条历史报告
- 侦察结果以战报形式展示，跳转 `/pages/scout?id=报告ID`

---

## 15. 竞技场系统

**关键文件**：`server/app/sg/controller/Battle.php`（`arena5`/`rank`）、`server/app/sg/service/BattleService.php`（`arena5v5Battle`）

### 15.1 竞技场入口

- 校场建筑增加"进入"按钮
- 进入后为竞技场页面（5v5 名将战斗）

### 15.2 5v5 战斗规则

- 攻方：玩家选择 5 名闲置名将
- 防方：从全服名将池（status=0，按武力降序前 50）随机抽 5 个，不足用配置池补足
- 依次单挑：

```
atkPower = wuli × 0.6 + tongshuai × 0.4 + rand(0, 20)
defPower = wuli × 0.6 + tongshuai × 0.4 + rand(0, 20)
```

- 胜场多者胜

### 15.3 声望奖励

```
声望 = 胜场数 × 30 + (整体胜利 ? 50 : 0)
```

### 15.4 排行榜

- 按声望降序，前 50 名
- 显示我的排名与声望

---

## 16. 医馆系统

**关键文件**：`server/app/sg/controller/Hospital.php`、`server/app/sg/model/Wounded.php`

### 16.1 伤兵机制

- 战斗损失兵力的 30% 进入 `tpw_sg_wounded` 表（status=0 待治疗）
- **伤兵只入医馆表，不加回存活兵力**

### 16.2 治疗规则

- 需医馆等级 > 0
- 治疗速度 = `max(10, 60 / hospital等级)` 秒/兵
- 治疗消耗银两 = `伤兵总数 × 5`
- 治疗时长 = `伤兵总数 × 治疗速度`

### 16.3 结算归队

- 治愈后**必须调用 `CityTroop::addTroops()` 加回驻军**
- 再更新 status=2（已结算）

---

## 17. 增援系统

**关键文件**：`server/app/sg/controller/Reinforce.php`

### 17.1 派兵增援

- 仅可增援联盟成员（`union_id` 一致）或自己
- 行军时长 = `正常行军 × 1.5`
- 兵力暂存 `reinforce` 表，不直接 addTroops

### 17.2 撤回

- 兵力返还源玩家主城（`user.city_id`）
- status：0 已派出/驻扎 → 1 已撤回

---

## 18. 联盟系统

**关键文件**：`server/app/sg/controller/Union.php`

### 18.1 创建与加入

- 创建消耗黄金 **500**
- 联盟名 2-12 字
- 入口：主城 union-bar 直接进入联盟详情

### 18.2 职位

| 职位 | ID |
|------|----|
| 盟主 | 1 |
| 副盟 | 2 |
| 普通成员 | 4 |

- 初始成员上限 30，每升 1 级 +10
- 盟主不可直接退出（需转让或解散）

### 18.3 捐献与升级

- 可捐 silver/food/wood/stone/iron，最少 100
- 贡献度 = `amount / 100`
- 联盟经验 = 贡献度
- 升级需 exp = `level × 1000`

---

## 19. 爵位与声望系统

**关键文件**：`server/app/sg/service/NobilityService.php`

### 19.1 爵位阈值

| 爵位 | 声望阈值 |
|------|----------|
| 平民 | 0 |
| 里长 | 1,000 |
| 乡长 | 5,000 |
| 县丞 | 20,000 |
| 县令 | 80,000 |
| 太守 | 300,000 |
| 刺史 | 1,000,000 |
| 州牧 | 5,000,000 |

### 19.2 爵位加成

| 爵位 | 资源产量 | 兵力上限 | 出征队列 |
|------|----------|----------|----------|
| 平民 | 0 | 0 | 0 |
| 里长 | +5% | +500 | 0 |
| 乡长 | +10% | +1,500 | 0 |
| 县丞 | +15% | +3,000 | 0 |
| 县令 | +20% | +5,000 | +1 |
| 太守 | +30% | +10,000 | +1 |
| 刺史 | +40% | +20,000 | +2 |
| 州牧 | +50% | +50,000 | +3 |

### 19.3 声望来源

| 来源 | 声望 |
|------|------|
| 擂台 1v1 胜利 | +100 |
| 竞技场 5v5 | 胜场×30 + 整体胜利50 |
| 占领野地 | 50 + level×10 |

---

## 20. 民心系统

**关键文件**：`server/app/sg/service/MoraleService.php`

### 20.1 民心效率

| 民心 | 生产效率 | 人口增长 |
|------|----------|----------|
| ≥ 70 | 100% | 正常增长 |
| 50-69 | 70% | 正常增长 |
| 30-49 | 50% | 停止增长 |
| 1-29 | 30% | 负增长 |
| 0 | 30% | 触发建筑降级 |

### 20.2 自然恢复

- 每 **360 秒（6 分钟）+1**，上限 100
- 默认民心 80

### 20.3 民心 = 0 惩罚

- 随机选 1 个等级 > 0 的建筑降 1 级
- 民房降级同步人口
- 降级后民心恢复到 5

### 20.4 民心变动场景

| 场景 | 变动 |
|------|------|
| 被攻击 | 下降 |
| 资源不足 | 下降 |
| 增收苛政 | -2 |
| 祈福 | +10 |

---

## 21. 任务系统

**关键文件**：`server/app/sg/model/UserTask.php`

### 21.1 任务类型

| type | 含义 |
|------|------|
| 1 | 主线任务 |
| 2 | 日常任务 |
| 3 | 成就任务 |

### 21.2 触发机制

- 等级型任务：progress 取最大值
- 次数型任务：progress 累加
- 达到 `target_num` 自动标记完成（status=1）

### 21.3 任务示例

**主线**：
- 初出茅庐：官府升 2 级 → 奖 {silver:500, food:500}
- 招兵买马：招募 100 兵 → 奖 {silver:1000, wood:500}
- 招贤纳士：招募 1 名将 → 奖 {gold:50}
- 小试牛刀：赢 1 场野地战 → 奖 {gold:20, fame:100}
- 开疆拓土：占领 1 块野地 → 奖 {silver:2000}

**日常**：每日签到、日常建造(3次)、日常征兵(200人)、日常战斗(3场)

**成就**：百战名将（累计赢 100 场，奖 {gold:500, fame:10000}）

---

## 22. 商城与道具系统

**关键文件**：`server/app/sg/controller/Shop.php`、`client/pages/shop.vue`

### 22.1 货币

- 1 元 = 10 钻石
- 充值入口：主城黄金点击进入 `/pages/shop?tab=recharge`

### 22.2 道具配置

| 名称 | 类型 | 效果 | 价格(钻石) |
|------|------|------|-----------|
| 资源大礼包 | 1 | 五资源各+5000 | 100 |
| 资源中礼包 | 1 | 五资源各+1000 | 30 |
| 资源小礼包 | 1 | 五资源各+200 | 10 |
| 建造加速1小时 | 2 | 减队列3600秒 | 20 |
| 建造加速10分钟 | 2 | 减队列600秒 | 5 |
| 征兵加速1小时 | 2 | 减队列3600秒 | 20 |
| 科技加速1小时 | 2 | 减队列3600秒 | 20 |
| 普通宝箱 | 3 | 1-3星装备 | 30 |
| 稀有宝箱 | 3 | 2-4星装备 | 80 |
| 传说宝箱 | 3 | 3-5星装备 | 200 |
| 招贤令 | 4 | 随机≤3星名将 | 50 |
| 高级招贤令 | 4 | 随机≤5星名将 | 200 |
| 迁城令 | 6 | 随机迁移城池 | 500 |
| 改名卡 | 6 | 修改名称 | 100 |

### 22.3 前端页面结构

- **shop.vue**：背包 + 充值 两个 tab（已删除队列购买 tab）
- **道具页（equip.vue）**：实际即为背包功能，展示装备与材料
- 队列购买入口：在队列不足场景中自动弹出（460 响应码）

---

## 23. 定时任务与调度

**关键文件**：`server/app/sg/command/ResourceProduce.php`

### 23.1 资源结算命令

```
sg:resource   // 每分钟 crontab 执行
```

- 在线玩家资源结算（2 分钟内活跃视为在线）
- 野地每日 04:00 衰减检查（`WildlandService::maybeDailyDecay`）
- 出征队列到达结算（`March::settleArrived`）
- 返程队列结算（`March::settleReturned`）
- 建造队列完成结算（`BuildQueue::settleFinished`）

### 23.2 在线判定

- `last_offline` 在 120 秒内视为在线

---

## 24. API 路由总表

### 24.1 用户模块

| 方法 | 路由 | 说明 |
|------|------|------|
| POST | /user/login | 登录 |
| GET | /user/info | 用户信息 |
| POST | /user/recharge | 充值 |

### 24.2 城池模块

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | /city | 城池列表 |
| GET | /city/:id | 城池详情 |
| POST | /city/switch | 切换主城 |
| POST | /city/occupy | 占领野地 |
| POST | /city/levy | 手动增收 |
| POST | /city/pray | 祈福安民 |
| GET | /city/defense/:id | 城防部署信息 |
| POST | /city/defense/save | 保存防守策略 |

### 24.3 建筑模块

| 方法 | 路由 | 说明 |
|------|------|------|
| POST | /build/upgrade | 升级建筑 |
| POST | /build/cancel | 取消建造 |
| POST | /build/speed | 加速建造 |

### 24.4 名将模块

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | /hero | 名将列表 |
| GET | /hero/:id | 名将详情 |
| GET | /hero/recruit/list | 招贤馆列表 |
| POST | /hero/recruit | 招募名将 |
| POST | /hero/refresh/pool | 刷新招贤馆 |
| POST | /hero/:id/dismiss | 解雇名将 |
| POST | /hero/:id/skill/upgrade | 升级技能 |
| POST | /hero/:id/appoint | 任命职位 |
| POST | /hero/:id/wash | 洗髓（100黄金） |
| POST | /hero/:id/gift | 赠礼 |
| GET | /hero/explore/config | 历练配置 |
| GET | /hero/:id/explore | 历练状态 |
| POST | /hero/:id/explore/start | 开始历练 |
| POST | /hero/:id/explore/claim | 领取历练奖励 |

### 24.5 战斗模块

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | /battle | 战报列表 |
| GET | /battle/:id | 战报详情 |
| POST | /battle/arena | 擂台 1v1 |
| POST | /battle/arena5 | 竞技场 5v5 |
| GET | /battle/rank | 声望排行榜 |

### 24.6 其他模块

| 方法 | 路由 | 说明 |
|------|------|------|
| POST | /march | 出征 |
| GET | /map | 地图加载 |
| GET | /map/owner | 地格归属 |
| GET | /map/:id | 地格详情 |
| GET | /scout/list | 侦察报告列表 |
| GET | /scout/:id | 侦察报告详情 |
| POST | /scout/do | 执行侦察 |
| GET | /wall/:cityId | 城防信息 |
| POST | /wall/build | 制造防御工具 |
| GET | /equip | 装备列表 |
| POST | /equip/equip | 装备 |
| POST | /equip/unequip | 卸下 |
| POST | /equip/sell/:id | 出售 |
| GET | /shop/items | 道具列表 |
| GET | /shop/bag | 背包 |
| POST | /shop/buy | 购买 |
| POST | /shop/use | 使用道具 |
| POST | /queue/buy | 购买队列 |

---

## 25. 数据库表索引

| 表名 | 说明 |
|------|------|
| tpw_sg_user | 用户 |
| tpw_sg_city | 城池（含野地附属记录，official=0） |
| tpw_sg_city_troop | 城池驻军 |
| tpw_sg_map | 世界地图 |
| tpw_sg_hero | 名将 |
| tpw_sg_hero_config | 名将配置 |
| tpw_sg_hero_skill | 名将技能 |
| tpw_sg_hero_explore | 名将历练 |
| tpw_sg_recruit_pool | 招贤馆池 |
| tpw_sg_explore_config | 历练配置 |
| tpw_sg_troop_config | 兵种配置 |
| tpw_sg_build_cost_config | 建筑升级配置 |
| tpw_sg_build_queue | 建造队列 |
| tpw_sg_tech_config | 科技配置 |
| tpw_sg_user_tech | 用户科技 |
| tpw_sg_march | 出征队列 |
| tpw_sg_battle | 战报 |
| tpw_sg_wounded | 伤兵 |
| tpw_sg_wall_defense | 城防工具 |
| tpw_sg_defense_config | 防御工具配置 |
| tpw_sg_equip | 装备 |
| tpw_sg_equip_config | 装备配置 |
| tpw_sg_market | 市场挂单 |
| tpw_sg_scout | 侦察报告 |
| tpw_sg_union | 联盟 |
| tpw_sg_union_member | 联盟成员 |
| tpw_sg_task_config | 任务配置 |
| tpw_sg_user_task | 用户任务 |
| tpw_sg_item_config | 道具配置 |
| tpw_sg_user_item | 用户道具 |
| tpw_sg_queue_buff | 队列加成 |
| tpw_sg_reinforce | 增援 |
| tpw_sg_resource_cap_config | 资源上限配置 |
| tpw_sg_notice | 公告 |
| tpw_sg_mail | 邮件 |

---

## 附录：关键工程约束

1. **伤兵数据**仅写入 `tpw_sg_wounded` 表，禁止同时加回存活兵力
2. **医馆治愈**必须调用 `CityTroop::addTroops()` 加回驻军后再更新 status=2
3. **守方玩家城池兵力**格式必须为 `{troop_id: num}` 字典格式
4. **玩家城池被攻击后**必须调用 `CityTroop::consumeTroops()` 扣除守方损失
5. **野地占领**必须先触发战斗，胜利后才能创建城池
6. **所有控制器操作**需使用主城而非首城数据（优先取 `user.city_id`）
7. **地图 API 路由**需按特定路由优先于参数路由的顺序注册（`map/owner` 需在 `map/:id` 之前）
8. **所有读取详情接口**（City/Battle/Hospital 等）必须校验 token + owner 一致性，不一致返回 403
9. **Hero 招募 cost** 必须服务端硬编码，禁止用 `request_input('cost')`
10. **PHP 模型文件**必须一个文件一个类（PSR-4 规范），文件名 = 类名.php
11. **使用 `data()` 方法**批量赋值设置模型字段，避免直接赋值 `name` 属性（ThinkPHP Model 保留属性）
12. **英雄招募时**必须为 `name` 字段提供有效值，该字段无默认值
13. **英雄招募时**服务端需校验 `config_id` 星级 ≤ 招贤馆等级
14. **建筑队列**默认数量为 2，官府每 10 级 +1
15. **所有按钮**必须使用全局类 `.btn-action`（主操作）或 `.btn-ghost`（次操作）
16. **前端 API 请求**必须包含 `fail` 回调，`uni.hideLoading()` 需放在 `complete` 回调中

---

> 本文档基于代码实现整理，所有数值、公式、常量均来自实际代码。如有调整，请同步更新此文档。