docs: add delta-force-guide project documentation

Add English and Chinese docs for the Delta Force Guide full-stack app (Spring Boot backend + React frontend) with architecture, API reference, and live site link.
2026-05-23 08:57:35 +08:00
parent 6449bc0e87
commit ac8a2e90d8
4 changed files with 278 additions and 0 deletions
@@ -0,0 +1,91 @@
+---
+title: Delta Force Guide API
+---
+
+## Backend API Overview
+
+The backend is a Spring Boot 3 application organised under the base package `com.onixbyte.deltaforceguide`:
+
+| Package                                     | Description                       |
+|---------------------------------------------|-----------------------------------|
+| `controller`                                | REST API endpoint controllers     |
+| `service`                                   | Business logic layer              |
+| `repository`                                | MyBatis data access layer         |
+| `domain`                                    | JPA entity and domain objects     |
+| `config`                                    | Spring configuration (security, cache, etc.) |
+| `properties`                                | Configuration property classes    |
+| `enumeration`                               | Enumerated types                  |
+| `shared`                                    | Shared utilities                  |
+
+## API Endpoints
+
+### Authentication
+
+| Method | Path                  | Description              | Auth |
+|--------|-----------------------|--------------------------|------|
+| `POST` | `/api/auth/login`     | Log in with credentials  | No   |
+| `POST` | `/api/auth/refresh`   | Refresh access token     | No   |
+| `GET`  | `/api/auth/profile`   | Get current user profile | Yes  |
+
+### Firearms
+
+| Method   | Path                  | Description              |
+|----------|-----------------------|--------------------------|
+| `GET`    | `/api/firearms`       | List firearms (paginated, filterable by type) |
+| `GET`    | `/api/firearms/:id`   | Get firearm by ID        |
+| `POST`   | `/api/firearms`       | Create a new firearm     |
+| `PUT`    | `/api/firearms/:id`   | Update an existing firearm |
+| `DELETE` | `/api/firearms/:id`   | Remove a firearm         |
+
+### Modifications
+
+| Method   | Path                              | Description                    |
+|----------|-----------------------------------|--------------------------------|
+| `GET`    | `/api/modifications`              | List modifications (paginated, filterable by firearm and tags) |
+| `GET`    | `/api/modifications/:id`          | Get modification by ID         |
+| `POST`   | `/api/modifications`              | Create a modification          |
+| `POST`   | `/api/modifications/batch`        | Batch create modifications     |
+| `PUT`    | `/api/modifications/:id`          | Update a modification          |
+| `DELETE` | `/api/modifications/:id`          | Remove a modification          |
+| `DELETE` | `/api/modifications/batch-delete` | Batch remove modifications     |
+
+### Tags
+
+| Method | Path                  | Description           |
+|--------|-----------------------|-----------------------|
+| `GET`  | `/api/tags`           | List all tags         |
+
+## Frontend Routes
+
+| Path          | Layout      | Page              | Description                     |
+|---------------|-------------|-------------------|---------------------------------|
+| `/`           | Hero Layout | Firearms Browser  | Home page — firearm list        |
+| `/firearms`   | Hero Layout | Firearms Browser  | Firearm detail and search       |
+| `/mod-codes`  | Hero Layout | Modification Codes| Modification code library       |
+| `/legal`      | Hero Layout | Legal             | Legal and privacy information   |
+| `/login`      | Empty Layout| Login             | User authentication page        |
+
+## Frontend State Management
+
+Redux Toolkit with Redux Persist manages:
+
+- **Auth state** — Access tokens, refresh tokens, user profile
+- **Settings state** — User preferences persisted to local storage
+
+## API Client
+
+The frontend uses a shared `WebClient` wrapper around Axios that handles:
+
+- Base URL configuration (pointing to the backend API)
+- JWT access token injection via request interceptors
+- Automatic token refresh on 401 responses
+
+## Infrastructure
+
+| Component     | Technology                  |
+|---------------|-----------------------------|
+| Database      | PostgreSQL (with Flyway migrations) |
+| Cache         | Redis (session/token storage) |
+| File Storage  | AWS S3 (firearm images)     |
+| Containerisation | Docker                   |
+| Deployment    | Docker Compose behind Nginx  |
@@ -0,0 +1,48 @@
+---
+title: Delta Force Guide
+---
+
+import { Tabs, Tab } from "@rspress/core/theme"
+
+## Introduction
+
+Delta Force Guide is a full-stack web application providing a searchable library of firearm modification codes for the game Delta Force. It consists of two components:
+
+- **Web Frontend** — A React-based SPA for browsing, filtering, and copying modification codes.
+- **Backend Server** — A Spring Boot REST API handling data persistence, authentication, and content management.
+
+The live site is available at **[dfguide.onixbyte.cn](https://dfguide.onixbyte.cn)**.
+
+## Features
+
+- **Firearm Browser** — Browse a curated list of in-game firearms with detailed stats.
+- **Modification Code Library** — Search and filter modification codes by weapon, mode, and tags.
+- **One-Click Copy** — Copy modification codes directly from the interface.
+- **Efficient Rendering** — Large lists rendered smoothly with window virtualisation.
+- **Authentication** — User login with JWT-based auth and CAPTCHA verification.
+- **Admin Panel** — Full CRUD operations for firearms and modification data.
+- **Static-Friendly** — Frontend deployed as a static site with API proxy.
+
+## Architecture
+
+| Component     | Tech Stack                                                    |
+|---------------|---------------------------------------------------------------|
+| **Frontend**  | React 19, TypeScript, Tailwind CSS 4, Ant Design 6, React Router 7, Redux Toolkit, TanStack Virtual |
+| **Backend**   | Spring Boot 3, Java 21, PostgreSQL, MyBatis, Flyway, Redis |
+| **Auth**      | JWT (access + refresh tokens), CAPTCHA integration           |
+| **Storage**   | AWS S3 for image uploads                                     |
+
+The frontend is a static site served by Vite, communicating with the Spring Boot REST API backend. Authentication uses JWT access and refresh tokens with Redis-backed refresh token management.
+
+## Repositories
+
+- [delta-force-guide-server](https://github.com/onixbyte/delta-force-guide-server) — Spring Boot backend
+- [delta-force-guide-web](https://github.com/onixbyte/delta-force-guide-web) — React frontend
+
+## Quick Links
+
+- **Live Site:** [dfguide.onixbyte.cn](https://dfguide.onixbyte.cn)
+
+## License
+
+Delta Force Guide is open-source software released under the MIT Licence.