# CardGame

**Repository Path**: zhihao2023/card-game

## Basic Information

- **Project Name**: CardGame
- **Description**: 卡牌游戏
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-19
- **Last Updated**: 2025-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 卡牌自走棋游戏

## 项目wiki

[DeepWiki](https://deepwiki.com/zhihao2022/card-game/1-overview)

[card-game - zhihao2023 的文档仓库 | OpenDeekWiki | OpenDeekWiki](https://opendeep.wiki/zhihao2023/card-game)

## 项目概述与技术架构详解 —— 卡牌自走棋游戏

### 1. 项目介绍

#### 1.1 项目目的

该项目是一个结合卡牌收集与自走棋策略元素的游戏，旨在为玩家提供构建多样化卡组、培养角色并体验策略战斗的游戏过程。

近年来，卡牌收集机制已成为移动游戏领域的核心驱动力之一。玩家对收集行为的偏好源于人性深层的成就感和收藏欲，这与传统集换式卡牌（TCG）的文化基因一脉相承。

自走棋品类核心吸引力在于将策略深度与操作减负相结合：自动战斗机制适配移动端操作习惯，而羁绊系统、随机刷新等规则保留策略博弈空间。

卡组构筑的自由度是卡牌游戏差异化的核心竞争点。值得注意的是，《三国杀》等产品通过文化符号植入（如历史人物技能设计）证明：卡组不仅是策略载体，更是叙事延伸与用户身份表达的重要媒介。

#### 1.2 核心目标

- 提供多套卡组管理与自定义配置。
- 实现角色的多属性系统，包括生命值、法力值、攻击力、技能系统及Buff/Debuff管理。
- 搭建关卡系统，涵盖抽卡、角色部署、技能使用、法力管理、战斗结算及奖励机制。
- 实现局外系统的卡牌购买、角色培养与装备升级。
- 提供多种游戏模式，包括主界面功能、卡牌背包、商店系统和战斗模式（随机和关卡模式）。

#### 1.3 目标用户

对策略卡牌游戏、自走棋类玩法感兴趣的玩家，以及游戏开发者研究策略游戏架构。

#### 1.4 技术领域及应用场景

- 游戏开发，尤其是基于Java和Spring Boot的网页游戏后端系统。
- 战略卡牌与自走棋类游戏系统设计。
- 浏览器端前端静态资源交互。

### 2. 技术架构

#### 2.1 高层次架构概览

本系统基于Spring Boot框架构建，采用MVC架构模式，分层清晰：

- Controller层（如 BattleController, ShopController, GameController, DeckController）负责处理请求和响应。
- Service层（如 DeckService）承担业务逻辑处理。
- Dao层负责与数据库的数据交互。
- Model层维护业务实体与接口，如角色（Role）、卡牌（Card）、关卡（Level）等。
- 静态资源层管理前端HTML、CSS、JS等文件，支持页面交互。

#### 2.2 架构组件与职责划分

| 组件           | 主要职责                                               |
| -------------- | ------------------------------------------------------ |
| Controller层   | 请求接收、转发，页面跳转及业务逻辑入口                 |
| Service层      | 业务规则实现，游戏核心逻辑处理                         |
| Dao层          | 数据持久化接口实现，数据访问控制                       |
| Model层        | 定义游戏核心实体及接口，业务数据模型保持               |
| 前端静态资源层 | 用户界面展示和交互，支持游戏操作如卡牌展示、角色信息等 |

#### 2.3 设计模式与架构原则

- 应用Spring Boot的依赖注入和自动配置特性。
- 使用接口和实现类分离（如ICard、Card，IDeckService、DeckService），符合面向接口开发，便于扩展和测试。
- 采用DAO模式进行数据访问封装。
- 业务逻辑与表现层分离，符合单一职责原则。

#### 2.4 系统边界与集成点

- 系统边界：Web客户端请求通过Controller层进入服务器端，经过Service处理与数据库持久层交互，返回结果至前端。
- 集成点：前端通过REST API与后端交互；后端通过Dao层和数据库集成。

#### 2.5 架构示意图 (Mermaid)

```mermaid
graph TD
  Client[前端客户端]
  Controller(Controller 层)
  Service(Service 层)
  Dao(Dao 层)
  Database[(数据库)]

  Client -->|HTTP请求| Controller
  Controller -->|调用| Service
  Service -->|操作| Dao
  Dao -->|数据存取| Database

  subgraph 前端静态资源
    Client
  end

  subgraph 后端 Java 程序
    Controller --> Service --> Dao
  end
```

### 3. 实现细节

#### 3.1 主程序入口代码示例

```java
package com.cardgame;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"com.cardgame"})
public class CardGameApplication {
    public static void main(String[] args) {
        SpringApplication.run(CardGameApplication.class, args);
    }
}
```

该类启动Spring Boot应用，扫描com.cardgame包下组件。

#### 3.2 主要模块与实现亮点

- **Model层**：接口如ICard、IRole定义，具体实现Card、Role，清晰体现了接口与实现分离。
- **Dao层**：如CardDao、RoleDao及其接口定义，负责数据访问。
- **Service层**：如DeckService实现了IDeckService，处理卡组业务逻辑。
- **Controller层**：负责请求处理与页面跳转。

#### 3.3 配置管理示例（pom.xml）

- 使用Spring Boot 3.2.3版本。
- 使用Java 21版本。
- 依赖包括spring-boot-starter-web，spring-boot-starter-test和lombok（简化代码）。

关键依赖版本管理和编码规范配置均包含于pom.xml中，方便构建与部署。

#### 3.4 外部依赖与集成示例

- Spring Boot框架，涵盖Web和测试支持。
- Lombok简化Java代码编写。
- 前端通过JS异步请求REST接口，如`fetchMoney()`获取当前金钱。

#### 3.5 组件关系图 (Mermaid)

```mermaid
graph LR
  Controller --> Service
  Service --> Dao
  Dao --> Database
  Model -. Controls .-> Service
  Controller -. Interacts .-> Frontend[前端UI资源]
```

### 4. 关键功能解析

#### 4.1 卡组管理系统

##### 描述

支持多套卡组的配置与管理，卡组中包含角色卡、装备卡、行动卡等。

##### 实现亮点示例代码

（前端卡牌生成方法示例）

```javascript
function createCardElement(card) {
    const cardDiv = document.createElement('div');
    cardDiv.className = `card`;

    let statsHTML = '';
    switch(card.type) {
        case 'role':
            statsHTML = `
                <div class="stat"><span>生命值：</span><span>${card.hp}</span></div>
                <div class="stat"><span>攻击力：</span><span>${card.attack}</span></div>
            `;
            break;
        case 'action':
            statsHTML = `
                ${card.addSelfHP ? `<div class="stat"><span>回血：</span><span>+${card.addSelfHP}</span></div>` : ''}
                ${card.addSelfMP ? `<div class="stat"><span>回蓝：</span><span>+${card.addSelfMP}</span></div>` : ''}
                ${card.addSelfMPMAX ? `<div class="stat"><span>增加法力上限：</span><span>+${card.addSelfMPMAX}</span></div>` : ''}
                ${card.addEnemyHP ? `<div class="stat"><span>对敌方伤害：</span><span>${card.addEnemyHP}</span></div>` : ''}
                ${card.addEnemyMP ? `<div class="stat"><span>减少敌方蓝量：</span><span>${card.addEnemyMP}</span></div>` : ''}
                ${card.cost ? `<div class="stat"><span>技能消耗：</span><span>${card.cost}</span></div>` : ''}
            `;
            break;
        // 省略...
    }

    cardDiv.innerHTML = `
        <img class="card-image" src="${card.imageUrl || 'https://via.placeholder.com/240x160?text=卡牌立绘'}" alt="${card.name}">
        <div class="card-content">
            <div class="card-name">${card.name}</div>
            <div class="card-stats">
                ${statsHTML}
            </div>
        </div>
    `;

    return cardDiv;
}
```

##### 使用示例

玩家通过页面交互，可视化查看、选取并修改卡组，前端JS动态生成角色和卡牌卡片界面。

#### 4.2 角色系统

- 多属性设计，涵盖生命值、法力值、技能效果、装备加成以及Buff/Debuff管理。
- 通过接口(ISkill, IRole)定义，支持灵活扩展。
- 技能与伤害计算集成在战斗流程中。

#### 4.3 战斗与关卡流程

- 抽卡 > 角色部署 > 技能使用 > 法力管理 > 战斗结算 > 奖励分配。
- 局外系统支持购买角色卡、装备卡。

#### 4.4 功能架构示意 (Mermaid)

```mermaid
graph TD
  DeckService --> CardDao
  RoleSystem --> BuffSystem
  BattleController --> DeckService
  BattleController --> RoleSystem
  ShopController --> RoleSystem
  ShopController --> DeckService
```

### 5. 核心流程与机制

#### 5.1 游戏流程解析

```mermaid
flowchart TD
  A[游戏开始] --> B[抽卡阶段]
  B --> C[角色部署]
  C --> D[技能使用]
  D --> E[法力值管理]
  E --> F[战斗结算]
  F --> G[奖励获取]
  G --> H{继续游戏?}
  H -->|是| B
  H -->|否| I[游戏结束]
```

#### 5.2 状态与数据管理

- 角色、卡牌状态通过Model对象统一管理。
- Buff/Debuff作为状态效果独立对象处理。
- 法力值系统封装放在角色模型内支持动态调整。

#### 5.3 同步异步处理

- 前端调用REST API为异步请求。
- 服务端流程基于同步调用链，单线程处理游戏逻辑，适合本地或小规模在线对战。

### 6. 总结及建议

#### 6.1 架构评估

- 架构清晰，采用Spring Boot框架，利于扩展维护。
- 接口与实现分离，有利于模块复用及单元测试。
- 前后端分离设计合理，UI交互丰富。

#### 6.2 优势与良好实践

- 规范的项目结构。
- 明确的分层架构。
- 友好的前端交互设计。

#### 6.3 潜在改进点

- 增加API安全控制机制，防止未授权访问。
- 配置动态管理，可引入Spring Profile支持多环境。
- 战斗逻辑可进一步拆分为独立模块以支持多线程或分布式。
- 增强异常与日志管理，提升系统健壮性。

#### 6.4 后续发展建议

- 增加单元与集成测试覆盖。
- 优化UI交互体验，支持响应式设计。
- 引入玩家数据统计与分析。
- 考虑多平台支持（移动端、小程序等）。

### 7. 参考链接

- [项目README.md](https://gitee.com/zhihao2023/card-game/blob/master/README.md)
- [主程序入口CardGameApplication.java](https://gitee.com/zhihao2023/card-game/blob/master/src/main/java/com/cardgame/CardGameApplication.java)
- [前端静态资源common.js](https://gitee.com/zhihao2023/card-game/blob/master/src/main/resources/static/js/common.js)
- [pom.xml文件](https://gitee.com/zhihao2023/card-game/blob/master/pom.xml)

## 项目分工

|          | DAO层  | Model层 | Service层 | Controller层 |  前端  |
| :------: | :----: | :-----: | :-------: | :----------: | :----: |
| 存档模块 | 丁怡哲 | 丁怡哲  |  丁怡哲   |    马子豪    | 马子豪 |
| 角色模块 | 丁怡哲 | 丁怡哲  |  丁怡哲   |    马子豪    | 马子豪 |
| 卡牌模块 | 丁怡哲 | 马子豪  |  丁怡哲   |    马子豪    | 马子豪 |
| 卡组模块 | 丁怡哲 | 丁怡哲  |  丁怡哲   |    马子豪    | 马子豪 |
| buff模块 | 高玉正 | 高玉正  |  高玉正   |    高玉正    | 马子豪 |
| 商店模块 |   /    |    /    |  马子豪   |    马子豪    | 马子豪 |
| 战斗模块 | 高玉正 | 丁怡哲  |  丁怡哲   |    高玉正    | 马子豪 |

### 后端

- 丁怡哲
  - Model层和Service层的战斗模块
  - DAO层、Model层和Service层的存档模块
  - DAO层、Model层和Service层的角色模块
  - DAO层、Model层和Service层的卡组模块
  - DAO层、Service层的卡牌模块
- 高玉正
  - DAO层、Model层的buff模块
  - DAO层、Controller层的战斗模块

- 马子豪
  - Model层的卡牌模块
  - Service层、Controller层的商店模块
  - Controller层的存档模块
  - Controller层的卡组模块
- ai协助
  - 模块初始化（一些比较基础的字段和方法，例如生命值、魔法值等）（后期均经过大量手工修改）

### 前端

- 马子豪
  - 开始界面以及前端逻辑
  - 角色商店界面以及前端逻辑
  - 卡组商店界面以及前端逻辑
  - 卡组编辑界面以及前端逻辑
  - 战斗界面以及前端逻辑
- ai协助
  - 界面初始化（包括html、css、javascript文件的初始化）（后期均经过大量手工修改）