74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# Project: TelegaApp (Alias Game WebApp)
|
|
|
|
## Overview
|
|
This project is a Spring Boot backend application designed to serve as the host for a Telegram WebApp game, specifically "Alias". The application integrates with the Telegram Bot API to manage the bot interface and will serve the game logic and web resources.
|
|
|
|
## Technology Stack
|
|
* **Language:** Java 17
|
|
* **Framework:** Spring Boot 3.2.5
|
|
* **Build Tool:** Maven
|
|
* **Telegram Library:** `telegrambots-spring-boot-starter` (6.9.7.1)
|
|
* **Frontend (Planned):** React, TypeScript, Vite (to be integrated into `src/main/resources/static`)
|
|
|
|
## Architecture & Structure
|
|
The project follows a standard Maven and Spring Boot directory structure:
|
|
|
|
* `src/main/java/com/example/telegaapp`: Source code root.
|
|
* `TelegaAppApplication.java`: Entry point.
|
|
* `bot/TelegramBot.java`: Handles Telegram updates (Long Polling) and WebApp launching.
|
|
* `controller/`: REST and potentially WebSocket controllers.
|
|
* `src/main/resources`: Configuration and static assets.
|
|
* `application.properties`: Configuration for server port and Telegram credentials.
|
|
* `static/`: Location for the built frontend application.
|
|
|
|
## Building and Running
|
|
|
|
### Prerequisites
|
|
* JDK 17+
|
|
* Maven
|
|
|
|
### Commands
|
|
* **Run Application:**
|
|
```bash
|
|
mvn spring-boot:run
|
|
```
|
|
* **Build JAR:**
|
|
```bash
|
|
mvn clean package
|
|
```
|
|
* **Run Tests:**
|
|
```bash
|
|
mvn test
|
|
```
|
|
|
|
## Configuration
|
|
Configuration is managed in `src/main/resources/application.properties`.
|
|
Key properties:
|
|
* `server.port`: Defaults to `8080`.
|
|
* `telegram.bot.username`: The username of the bot.
|
|
* `telegram.bot.token`: The authentication token from BotFather.
|
|
* `telegram.webapp.url`: The HTTPS URL where the WebApp is hosted (required for the WebApp button).
|
|
|
|
## Architecture & Design Principles
|
|
|
|
### Extensibility & Scalability
|
|
* **Interface-Driven Design:** Core components (like Word providers, Game rules) must be defined by interfaces. This allows swapping implementations (e.g., switching from JSON files to a Database) without modifying the business logic.
|
|
* **Loose Coupling:**
|
|
* The **WebSocket Controller** should act *only* as a router/adapter. It converts incoming messages to Service calls and Service events to outgoing messages. It should contain *zero* game logic.
|
|
* The **Game Service** should not know about WebSocket implementation details.
|
|
* **State Management:** While currently In-Memory, the design must support migrating the `GameState` to an external store (Redis) in the future. Avoid relying on object identity (`==`) for game entities; use IDs.
|
|
|
|
### Coding Standards & Best Practices
|
|
|
|
* **Comments & Documentation:**
|
|
* **Mandatory Javadoc:** All public interfaces, classes, and complex methods must have Javadoc explaining *what* they do and *how* to use them.
|
|
* **"Why" over "What":** Inline comments are required for complex algorithmic logic (e.g., score calculation, state transitions). Focus on explaining the *intent* and the *reasoning* behind the code, not just translating syntax into English.
|
|
* **DTOs (Data Transfer Objects):** Strict separation between Domain models (internal logic) and DTOs (API contracts). Never return a mutable entity directly to the client.
|
|
* **Error Handling:** Use global exception handlers (`@ControllerAdvice` / `@MessageExceptionHandler`). Failures should be graceful and informative to the user.
|
|
* **Testing:** Logic should be testable in isolation. Unit tests for the Game Engine are critical.
|
|
|
|
## Current Status
|
|
* Basic Spring Boot application setup.
|
|
* Telegram Bot polling implemented (`TelegramBot.java`).
|
|
* `/start` command sends a button to open the Web App.
|
|
* **Pending:** WebSocket setup, Game logic service, Frontend implementation. |