roapskipper/TEAM4

# AuctionSpace: 实时在线拍卖系统 🚀 ## 简介 (Abstract) **AuctionSpace** 是一个基于 Client-Server 架构的在线拍卖系统，完全使用 Java 21 和 JavaFX 17+ 开发。该系统提供实时拍卖体验，支持并发处理以避免数据争用（Lost Update、Race Condition），并集成了自动竞价、防狙击以及直观的价格波动图表等高级功能。 界面设计采用 **“The Heritage”** 概念——灵感来自苏富比的传统奢华风格，采用深勃艮第红（`#722F37`）搭配奶油色（`#FBF9F6`）背景，以及 Playfair Display + Lato 字体组合。 本项目由 **K70I-IT6 班第 4 小组**（越南国立大学河内分校 - 科技大学）开发。 ## 👥 团队成员与任务分工 (Team Roles) | 成员 | 主要角色 | 具体任务 | | :--- | :--- | :--- | | **Hải Anh** | Backend & Architect | 设计系统架构，处理并发（同时竞拍），实现主要设计模式（Singleton、Factory）。 | | **Trung** | Database & Logic | 管理 Database (DAO)，编写 User/Item 管理逻辑，处理状态转换逻辑和中标计分。 | | **Bình** | Frontend (GUI) | 开发所有 JavaFX/FXML 界面（动态表单），处理实时价格曲线（价格图表）的显示并集成 Observer Client。 | | **Lộc** | Networking & QA | 处理 Socket/API 连接，实现 Auto-Bidding、Anti-sniping，编写单元测试 并在 GitHub Actions 上设置 CI/CD。 | ## 🌟 核心功能与业务亮点 (Key Features) 系统满足所有必做功能，并最大程度集成了题目要求的加分功能： ### 1. 核心功能 (Core Functions) - **4级权限管理：** 登录/注册支持4种角色： - **Super Admin：** 拥有系统所有权限，为普通 Admin 生成 admin code。 - **普通 Admin：** 封禁账号，标记违规商品（登录时需要输入 admin code）。 - **Seller：** 发布商品，创建拍卖会。 - **Bidder：** 参与拍卖，出价。 - **拍卖会管理 (状态机)：** 严格执行状态转换 `PENDING → RUNNING → FINISHED → PAID / CANCELLED`。 - **异常处理：** 严格拦截各种情况：出价低于当前价、拍卖会已关闭时出价、网络突然断开（Socket timeout）。 ### 2. 高级功能 (Advanced & Bonus Features) - **并发出价：** 彻底解决数十人在千分之一秒内同时按下出价按钮时的*Lost Update*和*Race Condition*问题。确保数据完整性（不会有人被错扣钱，不会有两个赢家）。 - **自动竞价：** 用户设置 *maxBid* 和 *increment*，系统使用算法 自动加价竞争榜首。 - **防狙击算法：** 如果在最后几秒检测到突然出价，会自动延长拍卖时间。 - **实时价格曲线：** 使用折线图 将出价历史可视化，实时绘制，无需刷新页面。 ### 3. 出价限制规则 (Bid Cap Rule) 为了防止恶意“抬价”或错误出价（例如：1次出价从1百万跳到5亿），系统基于拍卖会的当前价格（`x`）应用**阶梯限制**。允许的最高出价 = `multiplier × x`，其中系数 `multiplier` 随着价格的增加而降低： | 当前价格范围 (x) | 最大系数 | 允许的最大出价 | | :--- | :---: | :--- | | `0 < x < 1.000.000` | **5x** | 当前价格的5倍 | | `1.000.000 ≤ x < 5.000.000` | **4x** | 当前价格的4倍 | | `5.000.000 ≤ x < 25.000.000` | **3x** | 当前价格的3倍 | | `25.000.000 ≤ x < 50.000.000` | **2x** | 当前价格的2倍 | | `50.000.000 ≤ x < 100.000.000` | **1.8x** | 当前价格的1.8倍 | | `100.000.000 ≤ x < 250.000.000` | **1.5x** | 当前价格的1.5倍 | | `250.000.000 ≤ x ≤ 500.000.000` | **1.3x** | 当前价格的1.3倍 | **设计依据：** - **越贵越严：** 对于便宜的商品 (< 1百万)，用户可以大手笔出价 (5倍) 以快速竞争。对于昂贵的商品 (> 2.5亿)，系数降至 1.3倍，因为绝对差额已经非常大——不需要高倍数。 - **防止“恶意竞价”：** 用户无法通过出价过高来震慑他人，从而“破坏游戏”。 - **保护买家心理：** 避免在看到价格发生不合理暴涨时产生 FOMO。 该规则一致应用于**手动出价**和**自动出价最大限制**——用户为系统自动出价设置的 `maxBid` 不能超过此限制。 ## 🏗 面向对象设计 (OOP) 与架构 系统严格遵守 OOP 的4个核心原则，并使用分层的 MVC Client-Server 架构。 ### 1. 应用 OOP 的 4 个原则 - **封装：** 保护所有系统数据（private/protected 字段），仅允许通过经过审查的 getter/setter 进行访问。 - **继承：** 建立清晰的对象层级（例如：`Admin`、`Bidder`、`Seller` 继承自 `User`）。 - **多态：** 根据不同的产品类型重写 诸如 `getDetails()` 或 `calculateFee()` 等方法。 - **抽象：** 声明抽象类（`Item`）和接口，作为 5 个产品类别（电子产品、艺术品、时尚单品、收藏品、车辆）的标准蓝图。 ### 2. 应用的设计模式 - **Factory Method：** 动态创建产品类型（`ItemFactory`），与 JavaFX 界面上的 Dynamic Form 灵活结合。 - **Observer Pattern：** 同步多用户界面。Server 充当 Subject，通过 Socket 将价格更新信号推送到各个 Client（Observers），而无需进行会导致网络拥塞的轮询。 - **Singleton Pattern：** 管理到 Database（`DatabaseManager`）和 `AuctionManager` 的唯一连接线程。 ## 🎨 界面设计 (UI/UX) 界面采用了 **The Heritage** 概念，并在整个系统中保持一致的设计原则： | 组件 | 规范 | | :--- | :--- | | **概念** | 传统、富有、历史悠久（灵感来自苏富比） | | **主背景** | 奶油色 `#FBF9F6` | | **卡片 / Card** | 纯白色 `#FFFFFF` | | **强调色 / 按钮** | 深勃艮第红 `#722F37` | | **文字** | 炭灰色 `#2C2C2C` | | **标题字体** | Playfair Display | | **正文字体** | Lato | | **卡片效果** | 柔和阴影：`dropshadow(three-pass-box, rgba(0,0,0,0.08), 15, 0, 0, 4)` | | **竞价计时器** | 使用等宽字体（表格数字）以便倒计时时不会横向抖动 | ## 📂 项目结构 系统按照 MVC 和 Client-Server 模型清晰地划分为多个模块： ``` AuctionSystem/ ├── src/ │ ├── main/ │ │ ├── java/com/team4/ │ │ │ ├── client/ # Giao tiếp mạng phía Client (ApiClient, Client) │ │ │ ├── controller/ # Controller cho các màn JavaFX │ │ │ ├── dao/ # Data Access Object — truy vấn Database │ │ │ ├── db/ # Quản lý kết nối DB (DatabaseManager - Singleton) │ │ │ ├── factory/ # Factory Pattern khởi tạo 5 loại sản phẩm │ │ │ ├── handler/ # Xử lý request/response Client - Server │ │ │ ├── model/ # Các thực thể (User, Item, Auction, AutoBidding...) │ │ │ ├── network/ # Quản lý gói tin và giao tiếp mạng chung │ │ │ ├── observer/ # Observer Pattern cho cập nhật Real-time │ │ │ ├── server/ # Lõi Server xử lý API và Socket │ │ │ ├── service/ # Luồng nghiệp vụ chính (AuctionManager) │ │ │ ├── util/ # Tiện ích (UserSession, Hash...) │ │ │ ├── Launcher.java # Điểm khởi chạy ứng dụng (Bypass JavaFX module layer) │ │ │ ├── Main.java # Cấu hình JavaFX Application │ │ │ └── TestConnect.java # Test nhanh kết nối DB │ │ └── resources/ │ │ ├── com/team4/view/ │ │ │ ├── admin_auctions.fxml │ │ │ ├── admin_dashboard.fxml │ │ │ ├── admin_users.fxml │ │ │ ├── bidder_auctions.fxml │ │ │ ├── bidding_room.fxml │ │ │ ├── login.fxml │ │ │ ├── main.fxml │ │ │ ├── profile.fxml │ │ │ ├── seller_products.fxml │ │ │ └── style.css # CSS theo concept The Heritage │ │ ├── fonts/ # Font Playfair Display & Lato (TTF) │ │ ├── data.sql # Dữ liệu khởi tạo mẫu │ │ ├── schema.sql # Định nghĩa cấu trúc Database (MySQL) │ │ ├── database.properties # Cấu hình kết nối DB │ │ └── logback.xml # Cấu hình logging │ └── test/ # Unit Test (JUnit) ├── target/ # Output build của Maven (auto-generated) ├── KeHoachTrienKhaiBackend_AuctionSystem.pdf # Tài liệu kế hoạch Backend ├── API_Contract.md # Đặc tả giao tiếp API Client - Server ├── Query.sql # Các câu truy vấn mẫu / debug ├── .env.example # Mẫu file biến môi trường ├── .gitignore ├── pom.xml # Cấu hình Maven & Dependencies └── README.md # Tài liệu tổng quan dự án ``` ## 🛠 标准与技术 系统设计符合行业标准： | 类别 | 技术/标准 | | :--- | :--- | | **语言** | Java 21 | | **GUI Framework** | JavaFX 17+ (FXML, CSS) | | **Database** | MySQL 8.0 (charset `utf8mb4_unicode_ci`) | | **网络通信** | Socket TCP (实时) + REST API JSON (CRUD) | | **构建工具** | Apache Maven | | **编码规范** | Google Java Style Guide | | **版本控制** | Git — Conventional Commits，按 feature 分支 | | **测试** | JUnit 5 | | **CI/CD** | GitHub Actions | ## 📅 路线图与当前进度 - [x] **第一阶段：** 需求分析，OOP 设计，Database 结构设计以及技术选型。 - [x] **第二阶段：** 构建 Backend 基础，Server-Client 收发 JSON，配置 Singleton & Factory。 - [x] **第三阶段：** 完整开发 JavaFX GUI — 4种角色的登录/注册，各角色的 dashboard，拍卖室，个人资料，应用 The Heritage 概念和响应式布局。 - [ ] **第四阶段（进行中）：** 处理并发（加锁防止 Lost Update），Auto-Bidding，Anti-sniping，通过 Observer Pattern 更新实时价格图表。 - [ ] **第五阶段：** 完善单元测试，按 Google Style 重构代码，打包并编写最终文档。 ## 💻 构建与运行指南 ### 环境要求 - **JDK 21** (或更高版本) - **Maven 3.8+** - 运行在 `localhost:3306` 的 **MySQL 8.0** ### 操作步骤 ``` # 1. Clone 项目到本地 git clone https://github.com/roapskipper/TEAM4.git cd TEAM4/AuctionSystem # 2. 配置环境变量 cp .env.example .env # 打开 .env 并根据你本地的 MySQL 填写 DB_USER, DB_PASSWORD # 3. 创建 database 并 import schema + 示例 data mysql -u root -p < src/main/resources/schema.sql mysql -u root -p auction_system < src/main/resources/data.sql # 4. 安装 dependencies mvn clean install # 5. 运行 Server (terminal 1) mvn exec:java -Dexec.mainClass="com.team4.server.ApiServer" # 6. 运行 Client Application (terminal 2) # 必须从 Launcher.java 文件运行，以 bypass JDK 11+ 上 JavaFX 的 module layer 错误 mvn exec:java -Dexec.mainClass="com.team4.Launcher" ``` ## 🔐 测试账号 使用以下账号访问 Client Application 并测试相应的权限流程： | 角色 | Username | Password | Admin Code | 主要功能 | | :--- | :--- | :--- | :--- | :--- | | **Super Admin** | `superadmin` | `admin123` | `adminteam4` | 管理整个系统，为普通 Admin 生成代码。 | | **Seller (Mixi Shop)** | `domixi` | `seller123` | — | 发布商品，创建和管理自己的拍卖会。 | | **Seller (Shop Chất)** | `daucatmoi` | `seller123` | — | 同上 — 用于测试多卖家场景。 | | **Bidder (1千万)** | `ueteee` | `bidder123` | — | 以较低余额参与拍卖 — 测试余额不足逻辑。 | | **Bidder (1亿)** | `thichthimua` | `bidder123` | — | 以较高余额参与拍卖 — 测试正常出价流程。 | ## ⚠️ 重要提示

标签：C/S架构, DAO模式, GitHub Actions, Java 21, JavaFX 17, JUnit, Socket编程, UI设计, 二手交易, 价格曲线, 传统奢华风, 全英文项目, 单例模式, 单元测试, 在线拍卖系统, 域名枚举, 实时竞价, 工厂模式, 数据库管理, 桌面应用, 竞拍平台, 自动出价, 自动笔记, 观察者模式, 设计模式, 防狙击