Merge branch 'develop'

- Stamp version, channel and vendor into META-INF/build-info.properties
- Read build metadata at runtime from BuildProperties instead of expanded YAML
- Remove app.common placeholders from application.yaml
- Derive the OpenAPI info version from the packaged build version
- Point the OCI image source label at the GitHub repository
- Drop redundant repository blocks from settings.gradle.kts

.gitea/workflows/server-build-and-deploy.yml

@@ -5,11 +5,14 @@ on:
     types: [published]
 
 env:
-  APP_NAME: delta-force-guide-server
+  APP_NAME: ahsarah-guide-server
 
 jobs:
   build-and-release:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
     steps:
       - uses: actions/checkout@v4
 
@@ -63,8 +66,8 @@ jobs:
       - name: Build and push Docker image
         uses: docker/build-push-action@v6
         with:
-          context: .
+          context: server
-          file: Dockerfile.ci
+          file: server/Dockerfile.ci
           build-args: |
             JAR_FILE=${{ steps.jar.outputs.file }}
             IMAGE_VERSION=${{ gitea.event.release.tag_name }}
@@ -83,4 +86,4 @@ jobs:
         with:
           destination_container_repo: ${{ vars.DOCKER_HUB_USERNAME }}/${{ env.APP_NAME }}
           provider: dockerhub
-          readme_file: README.md
+          readme_file: server/README.md

.gitea/workflows/web-build-and-deploy.yml

@@ -0,0 +1,115 @@
+name: Build and Deploy
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build release archive
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build release archive
+        run: pnpm build:tar
+
+      - name: Clean up previous build artifacts on server
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          command: rm -rf /tmp/dist.tar.gz /tmp/dist.tar.gz/
+
+      - name: Upload artifact to server
+        uses: appleboy/scp-action@v0.1.7
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          source: "dist.tar.gz"
+          target: "/tmp/"
+
+  upload-release-asset:
+    name: Upload to Gitea Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artifact from server
+        env:
+          DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ vars.DEPLOY_USER }}
+          DEPLOY_PORT: ${{ vars.DEPLOY_PORT }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -e
+          SSH_DIR="${RUNNER_TEMP}/ssh"
+          mkdir -p "$SSH_DIR"
+          chmod 700 "$SSH_DIR"
+          printf '%s\n' "$DEPLOY_SSH_KEY" > "$SSH_DIR/key"
+          chmod 600 "$SSH_DIR/key"
+          scp -i "$SSH_DIR/key" \
+              -P "$DEPLOY_PORT" \
+              -o StrictHostKeyChecking=accept-new \
+              -o UserKnownHostsFile="$SSH_DIR/known_hosts" \
+              "${DEPLOY_USER}@${DEPLOY_HOST}:/tmp/dist.tar.gz" \
+              ./dist.tar.gz
+          rm -rf "$SSH_DIR"
+
+      - name: Upload release asset via Gitea API
+        run: |
+          set -e
+          RELEASE_ID=$(jq -r '.release.id' "$GITEA_EVENT_PATH")
+          URL="${GITEA_SERVER_URL}/api/v1/repos/${GITEA_REPOSITORY}/releases/${RELEASE_ID}/assets?name=dist.tar.gz"
+          curl -fsSL \
+            -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/gzip" \
+            --data-binary "@dist.tar.gz" \
+            "${URL}"
+
+  deploy-to-server:
+    name: Deploy to onixbyte.cn
+    needs: [build, upload-release-asset]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Extract archive and deploy
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          script_stop: true
+          script: |
+            set -e
+            DEPLOY_PATH="${{ vars.DEPLOY_PATH }}"
+            mkdir -p "$DEPLOY_PATH"
+            rm -rf "$DEPLOY_PATH"/*
+            tar -xzf /tmp/dist.tar.gz -C "$DEPLOY_PATH" --strip-components=1
+            chown -R caddy:caddy "$DEPLOY_PATH"
+            rm -f /tmp/dist.tar.gz

.github/workflows/server-build-and-deploy.yml

@@ -0,0 +1,95 @@
+name: Server Build and Deploy
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+env:
+  APP_NAME: ahsarah-guide-server
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 21 (Corretto)
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: corretto
+          cache: gradle
+
+      - name: Build with Gradle
+        run: >
+          ./gradlew bootJar -x test
+          -PartefactVersion="${{ github.event.release.tag_name }}"
+          -PbuildChannel=stable
+          -Pvendor=${{ vars.VENDOR }}
+
+      - name: Resolve JAR file path
+        id: jar
+        run: |
+          JAR_PATH=$(find build/libs -name '*.jar' | head -1)
+          echo "file=$JAR_PATH" >> "$GITHUB_OUTPUT"
+
+      - name: Prepare release asset
+        id: asset
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          FILE="${{ steps.jar.outputs.file }}"
+          ASSET_NAME="${APP_NAME}-${TAG}.jar"
+          cp "${FILE}" "../${ASSET_NAME}"
+          echo "path=${ASSET_NAME}" >> "$GITHUB_OUTPUT"
+
+      - name: Upload JAR to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ steps.asset.outputs.path }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+      - name: Generate image tags
+        id: meta
+        run: |
+          DOCKERHUB_USER="${{ vars.DOCKER_HUB_USERNAME }}"
+          echo "tag_version=${DOCKERHUB_USER}/${APP_NAME}:${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+          echo "tag_latest=${DOCKERHUB_USER}/${APP_NAME}:latest" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: server
+          file: server/Dockerfile.ci
+          build-args: |
+            JAR_FILE=${{ steps.jar.outputs.file }}
+            IMAGE_VERSION=${{ github.event.release.tag_name }}
+            IMAGE_VENDOR=${{ vars.VENDOR }}
+            BUILD_DATE=${{ github.event.release.published_at }}
+          push: true
+          tags: |
+            ${{ steps.meta.outputs.tag_version }}
+            ${{ steps.meta.outputs.tag_latest }}
+
+      - name: Push README to Docker Hub
+        uses: christian-korneck/update-container-description-action@v1
+        env:
+          DOCKER_USER: ${{ vars.DOCKER_HUB_USERNAME }}
+          DOCKER_PASS: ${{ secrets.DOCKER_HUB_TOKEN }}
+        with:
+          destination_container_repo: ${{ vars.DOCKER_HUB_USERNAME }}/${{ env.APP_NAME }}
+          provider: dockerhub
+          readme_file: server/README.md

.github/workflows/web-build-and-deploy.yml

@@ -0,0 +1,109 @@
+name: Web Build and Deploy
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build release archive
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build release archive
+        run: pnpm build:tar
+
+      - name: Clean up previous build artefacts on server
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          command: rm -rf /tmp/dist.tar.gz /tmp/dist.tar.gz/
+
+      - name: Upload artefact to server
+        uses: appleboy/scp-action@v0.1.7
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          source: "dist.tar.gz"
+          target: "/tmp/"
+
+  upload-release-asset:
+    name: Upload to GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artefact from server
+        env:
+          DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ vars.DEPLOY_USER }}
+          DEPLOY_PORT: ${{ vars.DEPLOY_PORT }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -e
+          SSH_DIR="${RUNNER_TEMP}/ssh"
+          mkdir -p "$SSH_DIR"
+          chmod 700 "$SSH_DIR"
+          printf '%s\n' "$DEPLOY_SSH_KEY" > "$SSH_DIR/key"
+          chmod 600 "$SSH_DIR/key"
+          scp -i "$SSH_DIR/key" \
+              -P "$DEPLOY_PORT" \
+              -o StrictHostKeyChecking=accept-new \
+              -o UserKnownHostsFile="$SSH_DIR/known_hosts" \
+              "${DEPLOY_USER}@${DEPLOY_HOST}:/tmp/dist.tar.gz" \
+              ./dist.tar.gz
+          rm -rf "$SSH_DIR"
+
+      - name: Upload release asset to GitHub
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist.tar.gz
+
+  deploy-to-server:
+    name: Deploy to onixbyte.cn
+    needs: [build, upload-release-asset]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Extract archive and deploy
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ vars.DEPLOY_HOST }}
+          username: ${{ vars.DEPLOY_USER }}
+          port: ${{ vars.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          script_stop: true
+          script: |
+            set -e
+            DEPLOY_PATH="${{ vars.DEPLOY_PATH }}"
+            mkdir -p "$DEPLOY_PATH"
+            rm -rf "$DEPLOY_PATH"/*
+            tar -xzf /tmp/dist.tar.gz -C "$DEPLOY_PATH" --strip-components=1
+            chown -R caddy:caddy "$DEPLOY_PATH"
+            rm -f /tmp/dist.tar.gz

.gitignore

@@ -97,7 +97,7 @@ fabric.properties
 # Editor-based HTTP Client
 http-client.private.env.json
 
-### Server
+### Java
 # Compiled class file
 *.class
 
@@ -111,26 +111,18 @@ http-client.private.env.json
 .mtj.tmp/
 
 # Package Files #
+*.jar
 *.war
 *.nar
 *.ear
 *.zip
 *.tar.gz
 *.rar
-*.jar
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
 replay_pid*
 
-# Config
-config/*.yml
-config/*.yaml
-config/*.properties
-
-# Tests
-test/
-
 ### Gradle
 .gradle
 **/build/
@@ -143,13 +135,6 @@ test/
 gradle-app.setting
 .gradletasknamecache
 
-### Claude Code
-.claude/settings.local.json
-.claude/memory/
-.claude/plans/
-.claude/worktrees/
-.claude/scheduled_tasks.json
-
 # Eclipse Gradle plugin generated files
 # Eclipse Core
 .project
@@ -158,5 +143,100 @@ gradle-app.setting
 
 gradle.properties
 
+### Node.js
+# Logs
+logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Vite logs files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+### Server-specific
+# Config
+server/config/*.yml
+server/config/*.yaml
+server/config/*.properties
+
+# Tests
+server/test/
+
 # frp config
 frpc.toml
+
+### Claude Code
+.claude/settings.local.json
+.claude/memory/
+.claude/plans/
+.claude/worktrees/
+.claude/scheduled_tasks.json

CLAUDE.md

@@ -2,16 +2,25 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Coding Standards
+## Monorepo Structure
+
+- `server/` — Java 21 + Spring Boot 3.5 + Gradle (Kotlin DSL) REST API backend
+- `web/` — React 19 + Vite 8 + TypeScript + Ant Design 6 + Tailwind CSS 4 frontend
+
+## Server
+
+### Coding Standards
 
 - **Style**: Follow the Google Java Coding Style as the foundation.
 - **Indentation**: Use 4 spaces — no tabs.
 - **Line length**: Maximum 100 characters per line.
 - **Comments**: All code comments must use British English spelling (e.g. "colour" not "color", "behaviour" not "behavior", "serialise" not "serialize", "analyse" not "analyze", "traveller" not "traveler").
 
-## Build & Test Commands
+### Build & Test Commands
 
 ```bash
+cd server
+
 # Build the project (skip tests)
 ./gradlew build -x test
 
@@ -19,10 +28,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ./gradlew test
 
 # Run a single test class
-./gradlew test --tests "com.onixbyte.deltaforceguide.service.PasswordEncoderTest"
+./gradlew test --tests "com.onixbyte.ahsarahguide.service.PasswordEncoderTest"
-
-# Run a specific test method
-./gradlew test --tests "com.onixbyte.deltaforceguide.service.PasswordEncoderTest.generatePassword"
 
 # Build the full JAR
 ./gradlew bootJar
@@ -30,14 +36,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 The project uses Gradle with Java 21 (Amazon Corretto). Tests use JUnit 5 with the Spring Boot test framework, H2 in-memory database for test runtime, and Spring Security test support. Tests require an active `dev` profile.
 
-## Code Architecture
+### Code Architecture
 
-**Delta Force Guide Server** — A REST API backend for managing Delta Force game firearm builds/modifications.
+**Ahsarah Guide Server** — A REST API backend for managing firearm builds/modifications.
 
 ### Package structure
 
 ```
-com.onixbyte.deltaforceguide
+com.onixbyte.ahsarahguide
 ├── client/           # External service clients (TokenClient for JWT)
 ├── config/           # Spring beans: Security, CORS, Cache/Redis, Jackson, MyBatis, Spring Data
 ├── controller/       # REST controllers (Firearm, Modification, Tag, Auth)
@@ -65,16 +71,9 @@ com.onixbyte.deltaforceguide
 - **JPA + native queries**: Most CRUD uses Spring Data JPA. Native queries (in `ModificationRepository`) handle JSONB tag filtering with Postgres `@>` operator.
 - **Custom auth flow**: JWT tokens in httpOnly cookies (`AccessToken`). Spring Security with a custom `UsernamePasswordAuthenticationProvider` and `TokenAuthenticationFilter`. Tokens are auto-renewed within 5 min of expiry.
 - **JSONB storage**: `Modification.tags` and `Modification.accessories` (including nested `Tuning` objects) are stored as JSONB columns using Hypersistence Utils `JsonType`.
-- **Strict layering**: The call chain must follow `Controller → Service → Manager → Repository/Mapper`. Skipping layers (e.g. Controller calling Manager directly, Service calling Repository directly) is not permitted. Each layer has a distinct responsibility: Controller handles HTTP concerns, Service contains business logic, Manager manages `@Transactional` boundaries and data access coordination, Repository/Mapper handles raw data access.
+- **Strict layering**: The call chain must follow `Controller → Service → Manager → Repository/Mapper`. Skipping layers (e.g. Controller calling Manager directly, Service calling Repository directly) is not permitted.
 - **DTOs as Java records**: All request/response objects are immutable records with static `from()` factory methods for entity→DTO conversion.
-- **Flyway migrations**: SQL migrations in `src/main/resources/db/migration/` — V2 (init), V3 (bullet/damage fields), V4 (user), V5 (accessories JSONB column).
+- **Flyway migrations**: SQL migrations in `src/main/resources/db/migration/`.
-
-### Data model
-
-- `firearm` table: id, name, type (int→FirearmType enum), level, calibre, fire_rate, armour_damage, body_damage, review
-- `modification` table: id, firearm_id (FK→firearm), name, code, tags (jsonb), accessories (jsonb), note, author, video_url
-- `app_user` table: id, username, email
-- `user_credential` table: user_id, provider, credential (hashed)
 
 ### API endpoints
 
@@ -94,16 +93,61 @@ com.onixbyte.deltaforceguide
 
 Conventional commits: `feat:`, `chore:`, `fix:`. Messages are in English, present tense imperative style.
 
-### External dependencies
+---
 
-- **DB**: PostgreSQL (via Flyway migrations), H2 in test
+## Web
-- **Cache**: Redis (via Spring Cache + RedisTemplate with GenericJackson2JsonRedisSerializer)
-- **Auth**: java-jwt (auth0), BCrypt
-- **Docs**: springdoc-openapi (Swagger UI) on dev profile
-- **Onixbyte internal libs**: version-catalogue, tuple, common-toolbox, math-toolbox, identity-generator, captcha, regions
-- **AWS**: S3 SDK
 
-### Profiles
+### Commands
 
-- `dev`: Enables Swagger UI, connects to dev DB/Redis at `dfguide.onixbyte.cn`. Config in `config/application-dev.yaml`.
+```bash
-- Default profile: Used for production, no Swagger, connects to production datasource.
+cd web
+
+pnpm install          # Install dependencies (pnpm required)
+pnpm dev              # Start Vite dev server
+pnpm build            # TypeScript check + Vite production build
+pnpm build:tar        # Build + tar.gz archive (used by CI)
+pnpm preview          # Preview production build locally
+pnpm lint             # ESLint
+```
+
+No test suite exists in this project.
+
+### Architecture
+
+Chinese-language SPA for browsing and managing Ahsarah Guide (阿萨拉向导). The frontend talks to the Spring Boot backend via REST APIs.
+
+**App shell** (`src/main.tsx`): React 19 + React Router 7 + Redux Toolkit + Ant Design 6 + Tailwind CSS 4. Wraps the router in Redux `Provider` → `PersistGate` (Redux Persist) → Ant Design `StyleProvider`/`ConfigProvider` (locale `zh_CN`).
+
+**Routing** (`src/router/index.tsx`): Two layout groups:
+- `HeroLayout` (nav header + footer) for `/`, `/firearms`, `/mod-codes`
+- `EmptyLayout` (minimal) for `/login`
+All page components are lazy-loaded via `createBrowserRouter` + `lazy()`.
+
+**State** (`src/store/`): Redux Toolkit with two slices — `auth` (current user) and `firearms` (paginated firearm list). State is persisted to `localStorage` or `sessionStorage` based on the `VITE_REDUX_STORAGE` env var. Use typed hooks from `src/hooks/store.ts` (`useAppDispatch`, `useAppSelector`).
+
+**API layer** (`src/api/`): Axios instance (`src/shared/web-client/`) with base URL from `VITE_API_BASE_URL`, 10s timeout, and credentials. API modules: `FirearmApi`, `ModificationApi`, `TagApi`, `AuthApi`.
+
+**Pages**:
+- `FirearmsPage` — paginated card grid with type filter, create/edit modals (admin-only), delete with popconfirm
+- `ModCodesPage` — paginated list with tag multi-select and firearmId query param filter, create/edit modals with nested accessory/tuning form lists
+- `LoginPage` — simple username/password form, dispatches `setCurrentUser` on success
+
+**Shared form components**: `FirearmForm` and `ModificationForm` are reused by both create and edit modals. `ModificationForm` fetches all firearms for its weapon selector and supports a `lockFirearmId` prop that disables the selector (used when navigating from a specific firearm).
+
+**Type system** (`src/types/`): `Firearm` with weapon stats, `Modification` with nested `Accessory[]` → `Tuning[]`, `Page<T>` for paginated API responses, `User` for auth.
+
+**Vite config**: Alias `@` → `./src`. Plugins: React, Tailwind CSS 4, port checker. Build uses rolldown with manual chunk splitting for React, Redux, Ant Design, React Router, and rc-* packages.
+
+**Styling**: Tailwind CSS 4 with CSS layers (`theme, base, antd, components, utilities`). Responsive grid for mod code cards (1→2→3→4 columns). Prettier: 100 print width, no semicolons, double quotes, trailing commas ES5.
+
+### Environment variables
+
+```
+VITE_API_BASE_URL=/api        # Backend API base URL
+VITE_REDUX_STORAGE=local      # "local" or "session" for Redux persistence
+```
+
+### Contributing conventions
+
+- User-facing copy, documentation, and code comments in British English
+- Commit messages use `chore:` prefix for dependency updates (per Dependabot config)

README.md

@@ -1,150 +1,38 @@
-# Delta Force Guide Server
+# Ahsarah Guide (阿萨拉向导)
 
-REST API backend for managing **Delta Force** game firearm builds and modifications. Provides endpoints to browse, create, and share weapon configurations including attachments, tuning setups, tags, and build reviews.
+Ahsarah Guide is a full-stack web application for browsing and managing firearm modification guides.
 
+## Monorepo Structure
 
-## Tech Stack
+| Directory | Stack | Description |
-
+|-----------|-------|-------------|
-| Layer     | Technology                                                 |
+| `server/` | Java 21 + Spring Boot 3.5 + Gradle | REST API backend |
-|-----------|------------------------------------------------------------|
+| `web/` | React 19 + Vite 8 + TypeScript + Ant Design 6 | Web frontend |
-| Language  | Java 21 (Amazon Corretto)                                  |
-| Framework | Spring Boot 3.x (Web, Security, Data JPA, Cache, Actuator) |
-| Build     | Gradle (Kotlin DSL)                                        |
-| Database  | PostgreSQL (Flyway migrations, JSONB columns)              |
-| Cache     | Redis (2-hour TTL)                                         |
-| Auth      | Custom JWT via httpOnly cookies + BCrypt                   |
-| API Docs  | springdoc-openapi (Swagger UI, dev profile only)           |
-| Container | Multi-stage Docker image (Amazon Corretto 21 → Alpine)     |
-| CI/CD     | GitHub Actions — builds on release publish                 |
-
 
 ## Quick Start
 
-### Prerequisites
+### Server
 
-- JDK 21 (Amazon Corretto recommended)
+Prerequisites: JDK 21 (Amazon Corretto), PostgreSQL, Redis
-- PostgreSQL
-- Redis
-
-### Configure
-
-Copy and customise the development config:
 
 ```bash
-cp config/application-prod.yaml.example \
+cd server
-   config/application-dev.yaml
+cp config/application-prod.yaml.example config/application-dev.yaml
-```
+# Edit config/application-dev.yaml with your database and Redis credentials
-
-Fill in your datasource and Redis connection details, then place the production config at `config/`, then enable it by environment variable `SPRING_PROFILES_ACTIVE`.
-
-### Build
-
-```bash
-# Compile (skip tests)
-./gradlew build -x test
-
-# Run all tests
-./gradlew test
-
-# Build executable JAR
 ./gradlew bootJar
+java -jar build/libs/ahsarah-guide-server-*.jar
 ```
 
-### Run
+### Web
+
+Prerequisites: Node.js 20+, pnpm
 
 ```bash
-SPRING_PROFILES_ACTIVE=prod java -jar build/libs/delta-force-guide-server-$version.jar
+cd web
+pnpm install
+pnpm dev
 ```
 
-Swagger UI is available at `http://localhost:8080/swagger-ui.html` when the `dev` profile is active.
-
-## Data Model
-
-- **Firearm** — weapon base stats (name, type, level, calibre, fire rate, armour/body damage, review)
-- **Modification** — a build attached to a firearm, with name, code, tags (JSONB), accessories including nested tuning objects (JSONB), author notes, and video links
-- **App User** — registered user (username, email) with hashed credentials via BCrypt
-
-Tags and accessories are stored as PostgreSQL JSONB columns using [Hypersistence Utils](https://github.com/vladmihalcea/hypersistence-utils), enabling flexible per-build metadata and filtering with the `@>` operator.
-
-
-## Architecture
-
-```
-Controller  →  Service  →  Manager  →  Repository / Mapper
-   (HTTP)      (logic)     (@Transactional)  (data access)
-```
-
-The call chain is strictly enforced — skipping layers is not permitted. All request/response objects are Java records with static `from()` factory methods for entity-to-DTO conversion.
-
-
-## Docker
-
-```bash
-# Build image
-docker pull registry.onixbyte.cn/onixbyte/delta-force-guide-server:latest
-
-# Run container
-docker run -p 8080:8080 \
-  -v /path/to/config:/app/config \
-  -e SPRING_PROFILES_ACTIVE=$your_active_profiles
-  delta-force-guide-server
-```
-
-Pre-built images are published to **Self-hosted GitLab Container Registry** (`registry.onixbyte.cn/onixbyte/delta-force-guide-server`) on every release.
-
-
-## CI/CD
-
-GitLab CI triggers on **tags**. The pipeline:
-
-1. Builds the boot JAR with the release tag as the version
-2. Uploads the JAR as a release asset
-3. Builds and pushes a multi-arch Docker image to GHCR tagged with both `:latest` and `:<version>`
-
-No tests are run in CI by design — tests are expected to pass locally before a release is cut.
-
-
-## Profiles
-
-| Profile | Purpose                                                               |
-|---------|-----------------------------------------------------------------------|
-| `dev`   | Enables Swagger UI, connects to dev DB/Redis at `dfguide.onixbyte.cn` |
-| default | Production mode, no Swagger, uses production datasource               |
-
-
-## Project Structure
-
-```
-src/main/java/com/onixbyte/deltaforceguide/
-├── client/          External service HTTP clients
-├── config/          Spring bean definitions (Security, CORS, Cache, Jackson, MyBatis)
-├── controller/      REST controllers
-├── domain/
-│   ├── converter/   JPA attribute converters
-│   ├── dto/         Request/response records
-│   └── entity/      JPA entities
-├── enumeration/     Enums (FirearmType)
-├── exception/       Custom BizException with HTTP status mapping
-├── filter/          TokenAuthenticationFilter (JWT through OncePerRequestFilter)
-├── manager/         @Transactional wrappers around repositories
-├── mapper/          MyBatis mapper interfaces (reserved for future use)
-├── properties/      @ConfigurationProperties records
-├── repository/      Spring Data JPA repositories
-├── security/
-│   ├── authentication/  Custom UsernamePasswordAuthentication
-│   └── provider/        UsernamePasswordAuthenticationProvider
-├── service/         Business logic
-├── shared/          Constants and utility classes
-└── utils/           General-purpose helpers
-```
-
-
-## Versioning
-
-The application exposes its version at `/versions` (GET).
-
-
 ## Licence
 
-This project is licensed under the [MIT Licence](LICENCE). Copyright &copy; 2026 OnixByte.
+MIT. See [LICENCE](LICENCE) for details.
-

build.gradle.kts

@@ -1,78 +0,0 @@
-plugins {
-    java
-    alias(libs.plugins.spring.boot)
-    alias(libs.plugins.spring.dependency.management)
-}
-
-val artefactVersion: String by project
-val buildChannel: String by project
-val vendor: String by project
-
-group = "com.onixbyte.helix"
-version = artefactVersion
-
-tasks.withType<JavaCompile> {
-    options.encoding = "UTF-8"
-}
-
-java {
-    sourceCompatibility = JavaVersion.VERSION_21
-    targetCompatibility = JavaVersion.VERSION_21
-    toolchain {
-        languageVersion = JavaLanguageVersion.of(21)
-    }
-}
-
-dependencies {
-    implementation(libs.jspecify.core)
-    implementation(platform(libs.aws.sdk.bom))
-    implementation(libs.aws.sdk.s3)
-    implementation(libs.commons.io)
-    implementation(libs.commons.lang)
-    implementation(libs.commons.collections)
-    implementation(libs.hypersistence.core)
-    implementation(platform(libs.onixbyte.versionCatalogue))
-    implementation(libs.onixbyte.tuple)
-    implementation(libs.onixbyte.commonToolbox)
-    implementation(libs.onixbyte.mathToolbox)
-    implementation(libs.onixbyte.identityGenerator)
-    implementation(libs.onixbyte.captcha)
-    implementation(libs.onixbyte.regions)
-    implementation(libs.onixbyte.cryptoToolbox)
-    implementation(libs.jwt.core)
-    implementation(libs.spring.boot.configurationProcessor)
-    implementation(libs.spring.boot.actuator)
-    implementation(libs.spring.boot.starter.web)
-    implementation(libs.spring.boot.starter.webFlux)
-    implementation(libs.spring.boot.starter.validation)
-    implementation(libs.spring.boot.starter.redis)
-    implementation(libs.spring.boot.starter.cache)
-    implementation(libs.spring.boot.starter.jpa)
-    implementation(libs.mybatis.starter.core)
-    implementation(libs.flyway.core)
-    implementation(libs.flyway.postgresql)
-    implementation(libs.jackson.jsr310)
-    implementation(libs.spring.boot.starter.doc)
-    implementation(libs.spring.boot.starter.security)
-    testImplementation(libs.spring.boot.starter.test)
-    testImplementation(libs.reactor.test)
-    testImplementation(libs.mybatis.starter.test)
-    testImplementation(libs.spring.security.test)
-    runtimeOnly(libs.postgres.driver)
-    testRuntimeOnly(libs.h2.database)
-    testRuntimeOnly(libs.junit.launcher)
-}
-
-tasks.processResources {
-    filesMatching("application.yaml") {
-        expand(
-            "appVersion" to artefactVersion,
-            "channel" to buildChannel,
-            "vendor" to vendor
-        )
-    }
-}
-
-tasks.test {
-    useJUnitPlatform()
-}

config/application-prod.yaml.example

@@ -1,57 +0,0 @@
-spring:
-  datasource:
-    url: jdbc:postgresql://localhost:5432/dfguide_dev
-    username: postgres
-    password: 123456
-    driver-class-name: org.postgresql.Driver
-  data:
-    redis:
-      host: localhost
-      port: 6379
-      database: 0
-      # password: qwerty # Uncomment if password is necessary
-
-logging:
-  pattern:
-    # dateformat: dd MMM yyyy HH:mm:ss.SSS # Modify this for custom date format.
-
-app:
-  cookie:
-    http-only: true
-    secure: false
-    same-site: none
-    path: '/'
-    max-age: P1D
-  cors:
-    allowed-origins: # Cross-origin allowed origins
-      - "http://localhost:5173" # Dev server for vite.
-      - "http://localhost:4173" # Preview server for vite.
-    allow-credentials: true # Must be set to `true` since we are using cookie. You can change it only when you have modified how this application executing authentication.
-    allow-private-network: false
-    allowed-headers:
-      - "Content-Type"
-      - "Authorization"
-    allowed-methods:
-      - GET
-      - POST
-      - PUT
-      - PATCH
-      - DELETE
-    exposed-headers:
-      - "Content-Type"
-      - "Authorization"
-    max-age: PT2H
-  jwt:
-    issuer: dfguide.local # Issuer host
-    secret: qwertyuiopasdfghjklzxcvbnm123456 # JWT singing secret, a 32-byte long or longer string is recommended
-    valid-time: PT2H # JWT valid duration
-  webhook:
-    github:
-      secret: 123456
-      allowed-users: [ octotcat, onixbyte ]
-
-springdoc:
-  api-docs:
-    enabled: true # Set to `false` if you do not need api docs (recommended in production mode).
-  swagger-ui:
-    enabled: true # Set to `false` if you do not need swagger ui (recommended in production mode).

server/Dockerfile

@@ -6,5 +6,5 @@ RUN chmod +x ./gradlew && \
 
 FROM amazoncorretto:21-alpine AS runner
 WORKDIR /app
-COPY --from=builder /app/build/libs/delta-force-guide-server-1.0.0.jar app.jar
+COPY --from=builder /app/build/libs/ahsarah-guide-server-*.jar app.jar
 ENTRYPOINT ["java", "-jar", "app.jar"]

server/Dockerfile.ci

@@ -8,11 +8,11 @@ ARG BUILD_DATE
 
 COPY ${JAR_FILE} app.jar
 
-LABEL org.opencontainers.image.title="delta-force-guide-server" \
+LABEL org.opencontainers.image.title="ahsarah-guide-server" \
-      org.opencontainers.image.description="REST API backend for managing Delta Force game firearm builds and modifications" \
+      org.opencontainers.image.description="REST API backend for Ahsarah Guide" \
       org.opencontainers.image.version="${IMAGE_VERSION}" \
       org.opencontainers.image.vendor="${IMAGE_VENDOR}" \
-      org.opencontainers.image.source="https://git.onixbyte.com/onixbyte/delta-force-guide-server" \
+      org.opencontainers.image.source="https://github.com/onixbyte/ahsarah-guide" \
       org.opencontainers.image.licenses="MIT" \
       org.opencontainers.image.created="${BUILD_DATE}"
 

server/build.gradle.kts

@@ -0,0 +1,69 @@
+plugins {
+    java
+    alias(libs.plugins.spring.boot)
+    alias(libs.plugins.spring.dependency.management)
+}
+
+val artefactVersion: String by project
+val buildChannel: String by project
+val vendor: String by project
+
+group = "com.onixbyte.ahsarahguide"
+version = artefactVersion
+
+tasks.withType<JavaCompile> {
+    options.encoding = "UTF-8"
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_21
+    targetCompatibility = JavaVersion.VERSION_21
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+// Generate META-INF/build-info.properties at build time. The build version comes
+// from the project version (driven by the git tag in CI); channel and vendor are
+// stamped alongside it so the runtime no longer needs template placeholders.
+springBoot {
+    buildInfo {
+        properties {
+            additional.set(
+                mapOf(
+                    "channel" to buildChannel,
+                    "vendor" to vendor
+                )
+            )
+        }
+    }
+}
+
+dependencies {
+    // BOMs are imported as platforms, so they cannot be bundled.
+    implementation(platform(libs.aws.sdk.bom))
+    implementation(platform(libs.onixbyte.versionCatalogue))
+
+    implementation(libs.bundles.utilities)
+    implementation(libs.bundles.onixbyte)
+    implementation(libs.bundles.web)
+    implementation(libs.bundles.persistence)
+    implementation(libs.bundles.security)
+    implementation(libs.bundles.cache)
+    implementation(libs.bundles.observability)
+    implementation(libs.bundles.mail)
+    implementation(libs.bundles.aws)
+    implementation(libs.bundles.docs)
+
+    // Annotation processor for @ConfigurationProperties; kept out of bundles.
+    implementation(libs.spring.boot.configurationProcessor)
+
+    runtimeOnly(libs.postgres.driver)
+
+    testImplementation(libs.bundles.testing)
+    testRuntimeOnly(libs.bundles.testRuntime)
+}
+
+tasks.test {
+    useJUnitPlatform()
+}

server/config/application-prod.yaml.example

@@ -0,0 +1,131 @@
+spring:
+  datasource:
+    # PostgreSQL connection URL.
+    url: jdbc:postgresql://localhost:5432/dfguide_dev
+
+    # PostgreSQL username.
+    username: postgres
+
+    # PostgreSQL password.
+    password: 123456
+
+    # PostgreSQL JDBC driver class name.
+    driver-class-name: org.postgresql.Driver
+  data:
+    redis:
+      # Redis server host.
+      host: localhost
+
+      # Redis server port.
+      port: 6379
+
+      # Redis database index.
+      #
+      # Default to 0.
+      database: 0
+
+      # Redis server password.
+      #
+      # Uncomment if the server requires a password.
+      #
+      # password: qwerty
+
+logging:
+  pattern:
+    # Date format used in log output. Uncomment to use a custom format.
+    #
+    # Default to the date format provided by Spring Boot.
+    # dateformat: dd MMM yyyy HH:mm:ss.SSS
+
+app:
+  cookie:
+    # Whether the cookie is accessible from JavaScript. Keep `true` to mitigate XSS attacks.
+    http-only: true
+
+    # Whether the cookie is only sent over HTTPS. Set to `true` in production is recommended.
+    secure: true
+
+    # SameSite policy of the cookie.
+    #
+    # NOTE that `none` requires `secure` to be `true`.
+    same-site: none
+
+    # Cookie path.
+    path: '/'
+
+    # Cookie max age.
+    max-age: P1D
+  cors:
+    # Cross-origin allowed origins. Add your custom origins here.
+    allowed-origins: []
+
+    # Whether to allow credentials (cookies, authorisation headers) in cross-origin requests.
+    #
+    # Must be `true` since the application uses cookies for authentication. Change it only when
+    # the authentication mechanism no longer relies on cookies.
+    allow-credentials: true
+
+    # Whether to allow requests originating from private network addresses.
+    allow-private-network: false
+
+    # Headers allowed in cross-origin requests.
+    allowed-headers:
+      - "Content-Type"
+      - "Authorization"
+
+    # HTTP methods allowed in cross-origin requests.
+    #
+    # Methods are matched against Spring's HttpMethod, so they must be written in UPPER CASE.
+    # e.g., GET, POST, PUT, PATCH, DELETE, OPTIONS
+    allowed-methods:
+      - GET
+      - POST
+      - PUT
+      - PATCH
+      - DELETE
+
+    # Response headers exposed to the browser in cross-origin responses.
+    exposed-headers:
+      - "Content-Type"
+      - "Authorization"
+
+    # How long the CORS pre-flight response may be cached by the browser.
+    #
+    # Default to PT2H (2 hours).
+    max-age: PT2H
+  jwt:
+    # Issuer identifier, domain name is recommended.
+    issuer: ahsarah-guide.local
+
+    # Token signing secret, a 32-byte long or longer string is recommended.
+    secret: qwertyuiopasdfghjklzxcvbnm123456
+
+    # Token valid duration.
+    #
+    # Default to PT2H (2 hours).
+    valid-time: PT2H
+
+    # Token renew threshold.
+    #
+    # If valid time of this token is less than this value, then a new token will be delivered to
+    # the user.
+    #
+    # Default to PT5M (5 min).
+    renew-threshold: PT5M
+  webhook:
+    github:
+      # GitHub webhook secret. Used to verify the signature of incoming webhook requests.
+      secret: 123456
+
+      # GitHub usernames allowed to trigger webhook events.
+      allowed-users: [ octocat, onixbyte ]
+
+springdoc:
+  api-docs:
+    # Whether to expose the OpenAPI documentation. Set to `false` if you do not need it
+    # (recommended in production mode).
+    enabled: true
+  swagger-ui:
+    # Whether to expose the Swagger UI. Set to `false` if you do not need it
+    # (recommended in production mode).
+    enabled: true

server/gradle/libs.versions.toml

@@ -59,6 +59,11 @@ spring-boot-actuator = { group = "org.springframework.boot", name = "spring-boot
 spring-boot-starter-security = { group = "org.springframework.boot", name = "spring-boot-starter-security" }
 jwt-core = { group = "com.auth0", name = "java-jwt", version.ref = "javaJwtVersion" }
 
+# Java Mail & Templating
+spring-boot-starter-mail = { module = "org.springframework.boot:spring-boot-starter-mail" }
+spring-boot-starter-thymeleaf = { group = "org.springframework.boot", name = "spring-boot-starter-thymeleaf" }
+thymeleaf-extras-springsecurity6 = { group = "org.thymeleaf.extras", name = "thymeleaf-extras-springsecurity6" }
+
 # Spring Doc
 spring-boot-starter-doc = { group = "org.springdoc", name = "springdoc-openapi-starter-webmvc-ui", version.ref = "springDocVersion" }
 
@@ -73,6 +78,89 @@ reactor-test = { group = "io.projectreactor", name = "reactor-test", version.ref
 junit-launcher = { group = "org.junit.platform", name = "junit-platform-launcher", version.ref = "junitPlatformVersion" }
 mybatis-starter-test = { group = "org.mybatis.spring.boot", name = "mybatis-spring-boot-starter-test", version.ref = "mybatisVersion" }
 
+[bundles]
+# General utilities
+utilities = [
+    "jspecify-core",
+    "commons-io",
+    "commons-lang",
+    "commons-collections",
+    "jackson-jsr310",
+]
+
+# Onixbyte ecosystem (the version-catalogue BOM stays out of bundles, it is imported as a platform)
+onixbyte = [
+    "onixbyte-tuple",
+    "onixbyte-commonToolbox",
+    "onixbyte-cryptoToolbox",
+    "onixbyte-mathToolbox",
+    "onixbyte-identityGenerator",
+    "onixbyte-captcha",
+    "onixbyte-regions",
+]
+
+# Web layer
+web = [
+    "spring-boot-starter-web",
+    "spring-boot-starter-webFlux",
+    "spring-boot-starter-validation",
+]
+
+# Persistence and database
+persistence = [
+    "spring-boot-starter-jpa",
+    "mybatis-starter-core",
+    "hypersistence-core",
+    "flyway-core",
+    "flyway-postgresql",
+]
+
+# Security and authentication
+security = [
+    "spring-boot-starter-security",
+    "jwt-core",
+]
+
+# Caching (Redis)
+cache = [
+    "spring-boot-starter-redis",
+    "spring-boot-starter-cache",
+]
+
+# Observability
+observability = [
+    "spring-boot-actuator",
+]
+
+# Mail and templating
+mail = [
+    "spring-boot-starter-mail",
+    "spring-boot-starter-thymeleaf",
+    "thymeleaf-extras-springsecurity6",
+]
+
+# AWS cloud services
+aws = [
+    "aws-sdk-s3",
+]
+
+# API documentation
+docs = [
+    "spring-boot-starter-doc",
+]
+
+# Testing
+testing = [
+    "spring-boot-starter-test",
+    "spring-security-test",
+    "reactor-test",
+    "mybatis-starter-test",
+]
+testRuntime = [
+    "h2-database",
+    "junit-launcher",
+]
+
 [plugins]
 spring-boot = { id = "org.springframework.boot", version.ref = "springBootVersion" }
 spring-dependency-management = { id = "io.spring.dependency-management", version.ref = "springDependencyManagementVersion" }

server/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "ahsarah-guide-server"

server/src/main/java/com/onixbyte/ahsarahguide/AhsarahGuideApplication.java

@@ -0,0 +1,20 @@
+package com.onixbyte.ahsarahguide;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableAsync;
+
+/**
+ * Entry point for the Ahsarah Guide Server application.
+ *
+ * @author zihluwang
+ */
+@EnableAsync
+@SpringBootApplication
+public class AhsarahGuideApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(AhsarahGuideApplication.class, args);
+    }
+
+}

server/src/main/java/com/onixbyte/ahsarahguide/client/EmailClient.java

@@ -0,0 +1,109 @@
+package com.onixbyte.ahsarahguide.client;
+
+import jakarta.mail.MessagingException;
+import jakarta.mail.internet.InternetAddress;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.mail.javamail.MimeMessageHelper;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Component;
+import org.thymeleaf.TemplateEngine;
+import org.thymeleaf.context.Context;
+
+import java.io.UnsupportedEncodingException;
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+
+@Component
+public class EmailClient {
+
+    private static final Logger log = LoggerFactory.getLogger(EmailClient.class);
+
+    private final JavaMailSender mailSender;
+
+    private final TemplateEngine emailTemplateEngine;
+
+    @Autowired
+    public EmailClient(
+            JavaMailSender mailSender,
+            TemplateEngine emailTemplateEngine
+    ) {
+        this.mailSender = mailSender;
+        this.emailTemplateEngine = emailTemplateEngine;
+    }
+
+    private String fromAddress;
+
+    @Autowired
+    public void setFromAddress(@Value("${spring.mail.username}") String fromAddress) {
+        this.fromAddress = fromAddress;
+    }
+
+    /**
+     * Send a template-based HTML email asynchronously.
+     *
+     * @param toRecipient  recipient email address
+     * @param subject      subject line
+     * @param templateName template name (without .html extension, under mail-templates/)
+     * @param variables    context variables required by the template
+     */
+    @Async
+    public void sendTemplateMail(String toRecipient, String subject, String templateName, Map<String, Object> variables) {
+        try {
+            // Render HTML content using the dedicated email template engine
+            var context = new Context();
+            if (variables != null && !variables.isEmpty()) {
+                context.setVariables(variables);
+            }
+            var htmlBody = emailTemplateEngine.process(templateName, context);
+
+            log.debug("htmlBody={}", htmlBody);
+
+            // Build the MIME message
+            var message = mailSender.createMimeMessage();
+            var helper = new MimeMessageHelper(
+                    message,
+                    MimeMessageHelper.MULTIPART_MODE_MIXED_RELATED,
+                    StandardCharsets.UTF_8.name()
+            );
+
+            helper.setFrom(new InternetAddress(fromAddress, "阿萨拉向导", StandardCharsets.UTF_8.name()));
+            helper.setTo(toRecipient);
+            helper.setSubject(subject);
+            helper.setText(htmlBody, true);
+
+            // Dispatch the message
+            mailSender.send(message);
+            log.info("Successfully dispatched email to: [{}] with subject: [{}]", toRecipient, subject);
+
+        } catch (MessagingException | UnsupportedEncodingException ex) {
+            log.error("Failed to construct or send email to: [{}], subject: [{}]", toRecipient, subject, ex);
+            // Handle or rethrow custom business exception if required
+        } catch (Exception ex) {
+            log.error("Unexpected error occurred while processing email for: [{}]", toRecipient, ex);
+        }
+    }
+
+    /**
+     * Convenience method specifically for sending registration/login verification codes.
+     *
+     * @param toRecipient   target recipient email
+     * @param username      display username
+     * @param code          verification code string
+     * @param expireMinutes expiration time in minutes
+     */
+    @Async
+    public void sendVerificationCode(String toRecipient, String username, String code, int expireMinutes) {
+        var subject = "【阿萨拉向导】账号注册验证码";
+        var variables = Map.<String, Object>of(
+                "username", username,
+                "code", code,
+                "expireMinutes", expireMinutes
+        );
+
+        sendTemplateMail(toRecipient, subject, "verification-code", variables);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/client/TokenClient.java

@@ -1,12 +1,12 @@
-package com.onixbyte.deltaforceguide.client;
+package com.onixbyte.ahsarahguide.client;
 
 import com.auth0.jwt.JWT;
 import com.auth0.jwt.JWTVerifier;
 import com.auth0.jwt.algorithms.Algorithm;
 import com.auth0.jwt.interfaces.DecodedJWT;
-import com.onixbyte.deltaforceguide.domain.entity.User;
+import com.onixbyte.ahsarahguide.domain.entity.User;
-import com.onixbyte.deltaforceguide.properties.TokenProperties;
+import com.onixbyte.ahsarahguide.properties.TokenProperties;
-import com.onixbyte.deltaforceguide.utils.DateTimeUtil;
+import com.onixbyte.ahsarahguide.utils.DateTimeUtil;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 

server/src/main/java/com/onixbyte/ahsarahguide/config/AppConfig.java

@@ -1,29 +1,34 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
-import com.onixbyte.deltaforceguide.interceptor.GitHubWebhookInterceptor;
+import com.onixbyte.ahsarahguide.interceptor.GitHubWebhookInterceptor;
-import com.onixbyte.deltaforceguide.interceptor.TrafficInterceptor;
+import com.onixbyte.ahsarahguide.interceptor.TrafficInterceptor;
-import com.onixbyte.deltaforceguide.properties.AppProperties;
+import com.onixbyte.ahsarahguide.security.resolver.CurrentUserArgumentResolver;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.web.method.support.HandlerMethodArgumentResolver;
 import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
+import java.util.List;
+
 @Configuration
-@EnableConfigurationProperties(AppProperties.class)
 public class AppConfig implements WebMvcConfigurer {
 
     private final TrafficInterceptor trafficInterceptor;
 
     private final GitHubWebhookInterceptor gitHubWebhookInterceptor;
 
+    private final CurrentUserArgumentResolver currentUserArgumentResolver;
+
     @Autowired
     public AppConfig(
             TrafficInterceptor trafficInterceptor,
-            GitHubWebhookInterceptor gitHubWebhookInterceptor
+            GitHubWebhookInterceptor gitHubWebhookInterceptor,
+            CurrentUserArgumentResolver currentUserArgumentResolver
     ) {
         this.trafficInterceptor = trafficInterceptor;
         this.gitHubWebhookInterceptor = gitHubWebhookInterceptor;
+        this.currentUserArgumentResolver = currentUserArgumentResolver;
     }
 
     @Override
@@ -32,4 +37,9 @@ public class AppConfig implements WebMvcConfigurer {
         registry.addInterceptor(gitHubWebhookInterceptor)
                 .addPathPatterns("/webhooks/github");
     }
+
+    @Override
+    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
+        resolvers.add(currentUserArgumentResolver);
+    }
 }

server/src/main/java/com/onixbyte/ahsarahguide/config/CacheConfig.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
-import com.onixbyte.deltaforceguide.shared.JacksonRedisSerialiser;
+import com.onixbyte.ahsarahguide.shared.JacksonRedisSerialiser;
 import org.springframework.cache.annotation.EnableCaching;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

server/src/main/java/com/onixbyte/ahsarahguide/config/CorsConfig.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
-import com.onixbyte.deltaforceguide.properties.CorsProperties;
+import com.onixbyte.ahsarahguide.properties.CorsProperties;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

server/src/main/java/com/onixbyte/ahsarahguide/config/EmailTemplateConfig.java

@@ -0,0 +1,37 @@
+package com.onixbyte.ahsarahguide.config;
+
+import com.onixbyte.captcha.text.TextProducer;
+import com.onixbyte.captcha.text.impl.DefaultTextProducer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.thymeleaf.TemplateEngine;
+import org.thymeleaf.spring6.SpringTemplateEngine;
+import org.thymeleaf.templatemode.TemplateMode;
+import org.thymeleaf.templateresolver.ClassLoaderTemplateResolver;
+import org.thymeleaf.templateresolver.ITemplateResolver;
+
+import java.nio.charset.StandardCharsets;
+
+@Configuration
+public class EmailTemplateConfig {
+
+    @Bean
+    public TemplateEngine emailTemplateEngine() {
+        var resolver = new ClassLoaderTemplateResolver();
+        // Template files are located under src/main/resources/mail-templates/
+        resolver.setPrefix("mail-templates/");
+        resolver.setSuffix(".html");
+        resolver.setTemplateMode(TemplateMode.HTML);
+        resolver.setCharacterEncoding(StandardCharsets.UTF_8.name());
+        resolver.setCacheable(true); // Enable caching for the production environment
+
+        var templateEngine = new SpringTemplateEngine();
+        templateEngine.addTemplateResolver(resolver);
+        return templateEngine;
+    }
+
+    @Bean
+    public TextProducer textProducer() {
+        return DefaultTextProducer.builder().build();
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/config/FilterConfig.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
-import com.onixbyte.deltaforceguide.filter.WebhookFilter;
+import com.onixbyte.ahsarahguide.filter.WebhookFilter;
 import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

server/src/main/java/com/onixbyte/ahsarahguide/config/JacksonConfig.java

@@ -1,7 +1,7 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
 import com.fasterxml.jackson.databind.SerializationFeature;
-import com.onixbyte.deltaforceguide.shared.JacksonModules;
+import com.onixbyte.ahsarahguide.shared.JacksonModules;
 import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

server/src/main/java/com/onixbyte/ahsarahguide/config/MyBatisConfig.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.context.annotation.Configuration;
@@ -9,7 +9,7 @@ import org.springframework.context.annotation.Configuration;
  * @author zihluwang
  */
 @Configuration
-@MapperScan(basePackages = {"com.onixbyte.deltaforceguide.mapper"})
+@MapperScan(basePackages = {"com.onixbyte.ahsarahguide.mapper"})
 public class MyBatisConfig {
 }
 

server/src/main/java/com/onixbyte/ahsarahguide/config/OpenApiConfiguration.java

@@ -0,0 +1,45 @@
+package com.onixbyte.ahsarahguide.config;
+
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Contact;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.info.License;
+import io.swagger.v3.oas.models.OpenAPI;
+import org.springdoc.core.customizers.OpenApiCustomizer;
+import org.springframework.boot.info.BuildProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@OpenAPIDefinition(
+        info = @Info(
+                title = "Ahsarah Guide Server",
+                description = "API for Ahsarah Guide",
+                contact = @Contact(
+                        name = "Zihlu Wang",
+                        email = "zihlu.wang@onixbyte.com"
+                ),
+                license = @License(
+                        name = "MIT",
+                        url = "https://onixbyte.dev/onixbyte/ahsarah-guide/raw/branch/main/LICENCE"
+                )
+        )
+)
+@Configuration
+public class OpenApiConfiguration {
+
+    /**
+     * Overrides the OpenAPI info version with the packaged build version so the
+     * docs always match the released artefact instead of a hard-coded value.
+     *
+     * @param buildProperties the build-info properties generated at build time
+     * @return customiser that stamps the build version onto the API info
+     */
+    @Bean
+    public OpenApiCustomizer versionCustomizer(BuildProperties buildProperties) {
+        return openApi -> {
+            if (openApi.getInfo() != null) {
+                openApi.getInfo().setVersion(buildProperties.getVersion());
+            }
+        };
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/config/SecurityConfig.java

@@ -1,12 +1,16 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
 import com.auth0.jwt.JWT;
 import com.auth0.jwt.JWTVerifier;
 import com.auth0.jwt.algorithms.Algorithm;
-import com.onixbyte.deltaforceguide.filter.TokenAuthenticationFilter;
+import com.onixbyte.ahsarahguide.exeption.ForbiddenException;
-import com.onixbyte.deltaforceguide.properties.CookieProperties;
+import com.onixbyte.ahsarahguide.exeption.UnauthorisedException;
-import com.onixbyte.deltaforceguide.properties.TokenProperties;
+import com.onixbyte.ahsarahguide.filter.TokenAuthenticationFilter;
-import com.onixbyte.deltaforceguide.security.provider.UsernamePasswordAuthenticationProvider;
+import com.onixbyte.ahsarahguide.properties.CookieProperties;
+import com.onixbyte.ahsarahguide.properties.TokenProperties;
+import com.onixbyte.ahsarahguide.security.provider.UsernamePasswordAuthenticationProvider;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -34,10 +38,12 @@ import org.springframework.web.cors.CorsConfigurationSource;
 @EnableConfigurationProperties({TokenProperties.class, CookieProperties.class})
 public class SecurityConfig {
 
+    private static final Logger log = LoggerFactory.getLogger(SecurityConfig.class);
+
     /**
      * Configures the HTTP security filter chain including endpoint authorisation and JWT filter.
      *
-     * @param http the HTTP security builder
+     * @param httpSecurity the HTTP security builder
      * @return the configured security filter chain
      */
     @Bean
@@ -55,12 +61,23 @@ public class SecurityConfig {
                 .authorizeHttpRequests((customiser) -> customiser
                         .anyRequest().permitAll()
                 )
+                .exceptionHandling(customiser -> customiser
+                        .authenticationEntryPoint((request, response, authException) -> {
+                            log.error("Unauthenticated request: {}", request, authException);
+                            throw new UnauthorisedException("请先登录");
+                        })
+                        .accessDeniedHandler((request, response, accessDeniedException) -> {
+                            log.error("Denied request: {}", request, accessDeniedException);
+                            throw new ForbiddenException("权限不足");
+                        })
+                )
                 .addFilterAfter(tokenAuthenticationFilter, ExceptionTranslationFilter.class)
                 .build();
     }
 
     /**
      * Provides the BCrypt password encoder for credential hashing.
+     *
      * @return the BCrypt password encoder
      */
     @Bean

server/src/main/java/com/onixbyte/ahsarahguide/config/SpringDataConfig.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
 import org.springframework.context.annotation.Configuration;
 import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
@@ -9,7 +9,7 @@ import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
  * @author zihluwang
  */
 @Configuration
-@EnableJpaRepositories(basePackages = {"com.onixbyte.deltaforceguide.repository"})
+@EnableJpaRepositories(basePackages = {"com.onixbyte.ahsarahguide.repository"})
 public class SpringDataConfig {
 }
 

server/src/main/java/com/onixbyte/ahsarahguide/config/WebhookConfig.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.config;
+package com.onixbyte.ahsarahguide.config;
 
-import com.onixbyte.deltaforceguide.properties.GitHubWebhookProperties;
+import com.onixbyte.ahsarahguide.properties.GitHubWebhookProperties;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Configuration;
 

server/src/main/java/com/onixbyte/ahsarahguide/controller/AdminController.java

@@ -0,0 +1,59 @@
+package com.onixbyte.ahsarahguide.controller;
+
+import com.onixbyte.ahsarahguide.domain.dto.ManageRoleRequest;
+import com.onixbyte.ahsarahguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.Positive;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * REST controller for administrative user and role management.
+ *
+ * @author zihluwang
+ */
+@Tag(name = "管理员", description = "管理员用户与角色管理")
+@RestController
+@RequestMapping("/admin")
+@Validated
+@RequiresAuth
+public class AdminController {
+
+    private final UserService userService;
+
+    public AdminController(UserService userService) {
+        this.userService = userService;
+    }
+
+    @Operation(description = "为用户分配角色（仅超级管理员可操作）")
+    @PreAuthorize("hasRole('SUPER_USER')")
+    @PutMapping("/users/{id}/roles")
+    public ResponseEntity<Void> assignRole(
+            @PathVariable @Positive(message = "用户ID必须为正数") Long id,
+            @Valid @RequestBody ManageRoleRequest request
+    ) {
+        userService.assignRole(id, request.role());
+        return ResponseEntity.noContent().build();
+    }
+
+    @Operation(description = "移除用户角色（仅超级管理员可操作）")
+    @PreAuthorize("hasRole('SUPER_USER')")
+    @DeleteMapping("/users/{id}/roles/{role}")
+    public ResponseEntity<Void> removeRole(
+            @PathVariable @Positive(message = "用户ID必须为正数") Long id,
+            @PathVariable String role
+    ) {
+        userService.removeRole(id, role);
+        return ResponseEntity.noContent().build();
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/controller/AuthController.java

@@ -0,0 +1,62 @@
+package com.onixbyte.ahsarahguide.controller;
+
+import com.onixbyte.ahsarahguide.domain.dto.*;
+import com.onixbyte.ahsarahguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.service.AuthService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * REST controller for user authentication endpoints (login, logout).
+ *
+ * @author zihluwang
+ */
+@Tag(name = "用户鉴权", description = "处理用户登录与退出功能")
+@RestController
+@RequestMapping("/auth")
+public class AuthController {
+
+    private final AuthService authService;
+
+    public AuthController(AuthService authService) {
+        this.authService = authService;
+    }
+
+    @Operation(description = "用户登录")
+    @PostMapping("/login")
+    public ResponseEntity<UserResponse> login(@Validated @RequestBody LoginRequest request) {
+        var user = authService.login(request);
+        return authService.getUserResponseResponseEntity(user);
+    }
+
+    @RequiresAuth
+    @Operation(description = "退出登录")
+    @PostMapping("/logout")
+    public ResponseEntity<Void> logout() {
+        var expiredCookie = authService.logout();
+        return ResponseEntity.noContent()
+                .header(HttpHeaders.SET_COOKIE, expiredCookie.toString())
+                .build();
+    }
+
+    @Operation(description = "发送邮件验证码")
+    @PostMapping("/verification-code")
+    public SendVerificationCodeResponse sendVerificationCode(@Validated @RequestBody SendVerificationCodeRequest request) {
+        var verificationCodeId = authService.sendVerificationCode(request);
+        return new SendVerificationCodeResponse(verificationCodeId);
+    }
+
+    @Operation(description = "用户注册")
+    @PostMapping("/register")
+    public ResponseEntity<UserResponse> register(@Validated @RequestBody RegisterRequest request) {
+        var user = authService.register(request);
+        return authService.getUserResponseResponseEntity(user);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/controller/DailyPasswordController.java

@@ -1,7 +1,7 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
-import com.onixbyte.deltaforceguide.domain.dto.DailyPasswordResponse;
+import com.onixbyte.ahsarahguide.domain.dto.DailyPasswordResponse;
-import com.onixbyte.deltaforceguide.service.DailyPasswordService;
+import com.onixbyte.ahsarahguide.service.DailyPasswordService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.GetMapping;

server/src/main/java/com/onixbyte/ahsarahguide/controller/FirearmController.java

@@ -1,11 +1,11 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
-import com.onixbyte.deltaforceguide.domain.dto.FirearmRequest;
+import com.onixbyte.ahsarahguide.domain.dto.FirearmRequest;
-import com.onixbyte.deltaforceguide.domain.dto.FirearmResponse;
+import com.onixbyte.ahsarahguide.domain.dto.FirearmResponse;
-import com.onixbyte.deltaforceguide.domain.dto.PageResponse;
+import com.onixbyte.ahsarahguide.domain.dto.PageResponse;
-import com.onixbyte.deltaforceguide.enumeration.FirearmType;
+import com.onixbyte.ahsarahguide.enumeration.FirearmType;
-import com.onixbyte.deltaforceguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.security.annotation.RequiresAuth;
-import com.onixbyte.deltaforceguide.service.FirearmService;
+import com.onixbyte.ahsarahguide.service.FirearmService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Max;

server/src/main/java/com/onixbyte/ahsarahguide/controller/GlobalExceptionHandler.java

@@ -0,0 +1,44 @@
+package com.onixbyte.ahsarahguide.controller;
+
+import com.onixbyte.ahsarahguide.domain.dto.ErrorResponse;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.AccessDeniedException;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.server.ResponseStatusException;
+
+/**
+ * Global exception handler that translates exceptions into standard error responses.
+ *
+ * @author zihluwang
+ */
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(ResponseStatusException.class)
+    public ResponseEntity<ErrorResponse> handleResponseStatusException(ResponseStatusException exception) {
+        var status = exception.getStatusCode();
+        return ResponseEntity.status(status)
+                .body(new ErrorResponse(exception.getReason()));
+    }
+
+    @ExceptionHandler(AuthenticationException.class)
+    public ResponseEntity<ErrorResponse> handleAuthenticationException(AuthenticationException exception) {
+        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                .body(new ErrorResponse("请先登录"));
+    }
+
+    @ExceptionHandler(AccessDeniedException.class)
+    public ResponseEntity<ErrorResponse> handleAccessDeniedException(AccessDeniedException exception) {
+        var authentication = SecurityContextHolder.getContext().getAuthentication();
+        var httpStatus = authentication == null || !authentication.isAuthenticated()
+                ? HttpStatus.UNAUTHORIZED
+                : HttpStatus.FORBIDDEN;
+        var message = httpStatus == HttpStatus.UNAUTHORIZED ? "请先登录" : "权限不足";
+        return ResponseEntity.status(httpStatus)
+                .body(new ErrorResponse(message));
+    }
+}
+

server/src/main/java/com/onixbyte/ahsarahguide/controller/ModificationController.java

@@ -1,11 +1,13 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
-import com.onixbyte.deltaforceguide.domain.dto.ModificationBatchCreateRequest;
+import com.onixbyte.ahsarahguide.domain.dto.ModificationBatchCreateRequest;
-import com.onixbyte.deltaforceguide.domain.dto.ModificationRequest;
+import com.onixbyte.ahsarahguide.domain.dto.ModificationRequest;
-import com.onixbyte.deltaforceguide.domain.dto.ModificationResponse;
+import com.onixbyte.ahsarahguide.domain.dto.ModificationResponse;
-import com.onixbyte.deltaforceguide.domain.dto.PageResponse;
+import com.onixbyte.ahsarahguide.domain.dto.PageResponse;
-import com.onixbyte.deltaforceguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.domain.entity.User;
-import com.onixbyte.deltaforceguide.service.ModificationService;
+import com.onixbyte.ahsarahguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.security.resolver.CurrentUser;
+import com.onixbyte.ahsarahguide.service.ModificationService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -66,15 +68,21 @@ public class ModificationController {
     @RequiresAuth
     @Operation(description = "创建改装")
     @PostMapping
-    public ModificationResponse create(@Valid @RequestBody ModificationRequest request) {
+    public ModificationResponse create(
-        return modificationService.create(request);
+            @CurrentUser User user,
+            @Valid @RequestBody ModificationRequest request
+    ) {
+        return modificationService.create(request, user);
     }
 
     @RequiresAuth
     @Operation(description = "批量创建改装")
     @PostMapping("/batch")
-    public List<ModificationResponse> batchCreate(@Valid @RequestBody ModificationBatchCreateRequest request) {
+    public List<ModificationResponse> batchCreate(
-        return modificationService.batchCreate(request.modifications());
+            @CurrentUser User user,
+            @Valid @RequestBody ModificationBatchCreateRequest request
+    ) {
+        return modificationService.batchCreate(request.modifications(), user);
     }
 
     @RequiresAuth

server/src/main/java/com/onixbyte/ahsarahguide/controller/TagController.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -6,7 +6,7 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
-import com.onixbyte.deltaforceguide.service.ModificationService;
+import com.onixbyte.ahsarahguide.service.ModificationService;
 
 import java.util.List;
 

server/src/main/java/com/onixbyte/ahsarahguide/controller/UserController.java

@@ -0,0 +1,79 @@
+package com.onixbyte.ahsarahguide.controller;
+
+import com.onixbyte.ahsarahguide.domain.dto.BuildSummaryResponse;
+import com.onixbyte.ahsarahguide.domain.dto.ChangePasswordRequest;
+import com.onixbyte.ahsarahguide.domain.dto.PageResponse;
+import com.onixbyte.ahsarahguide.domain.dto.UpdateProfileRequest;
+import com.onixbyte.ahsarahguide.domain.dto.UserProfileResponse;
+import com.onixbyte.ahsarahguide.domain.entity.User;
+import com.onixbyte.ahsarahguide.security.annotation.RequiresAuth;
+import com.onixbyte.ahsarahguide.security.resolver.CurrentUser;
+import com.onixbyte.ahsarahguide.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * REST controller for the current user's profile management endpoints.
+ *
+ * @author zihluwang
+ */
+@Tag(name = "用户个人中心", description = "当前用户的资料管理与密码修改")
+@RestController
+@RequestMapping("/user")
+@Validated
+@RequiresAuth
+public class UserController {
+
+    private final UserService userService;
+
+    public UserController(UserService userService) {
+        this.userService = userService;
+    }
+
+    @Operation(description = "获取当前登录用户的个人资料")
+    @GetMapping("/me")
+    public UserProfileResponse profile(@CurrentUser User user) {
+        return userService.getProfile(user);
+    }
+
+    @Operation(description = "修改当前用户的个人资料（昵称与邮箱）")
+    @PutMapping("/me")
+    public UserProfileResponse updateProfile(
+            @CurrentUser User user,
+            @Valid @RequestBody UpdateProfileRequest request
+    ) {
+        return userService.updateProfile(user, request);
+    }
+
+    @Operation(description = "修改当前用户的登录密码")
+    @PutMapping("/me/password")
+    public ResponseEntity<Void> changePassword(
+            @CurrentUser User user,
+            @Valid @RequestBody ChangePasswordRequest request
+    ) {
+        userService.changePassword(user, request);
+        return ResponseEntity.noContent().build();
+    }
+
+    @Operation(description = "分页查询当前用户的改枪码列表")
+    @GetMapping("/me/builds")
+    public PageResponse<BuildSummaryResponse> builds(
+            @CurrentUser User user,
+            @RequestParam(defaultValue = "0") @Min(0) int page,
+            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size
+    ) {
+        return userService.getBuilds(user, PageRequest.of(page, size));
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/controller/VersionController.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
-import com.onixbyte.deltaforceguide.service.AppService;
+import com.onixbyte.ahsarahguide.service.AppService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.GetMapping;

server/src/main/java/com/onixbyte/ahsarahguide/controller/WebhookController.java

@@ -1,8 +1,10 @@
-package com.onixbyte.deltaforceguide.controller;
+package com.onixbyte.ahsarahguide.controller;
 
-import com.onixbyte.deltaforceguide.domain.dto.GitHubIssueRequest;
+import com.onixbyte.ahsarahguide.domain.dto.GitHubIssueRequest;
-import com.onixbyte.deltaforceguide.service.WebhookService;
+import com.onixbyte.ahsarahguide.service.WebhookService;
-import com.onixbyte.deltaforceguide.shared.GitHubWebhookHeader;
+import com.onixbyte.ahsarahguide.shared.GitHubWebhookHeader;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.ResponseEntity;
@@ -12,19 +14,21 @@ import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "WebHook")
 @RestController
-@RequestMapping("/webhooks/github")
+@RequestMapping("/webhooks")
-public class GitHubWebhookController {
+public class WebhookController {
 
-    private static final Logger log = LoggerFactory.getLogger(GitHubWebhookController.class);
+    private static final Logger log = LoggerFactory.getLogger(WebhookController.class);
 
     private final WebhookService webhookService;
 
-    public GitHubWebhookController(WebhookService webhookService) {
+    public WebhookController(WebhookService webhookService) {
         this.webhookService = webhookService;
     }
 
-    @PostMapping
+    @Operation(description = "GitHub WebHook 接口")
+    @PostMapping("/github")
     public ResponseEntity<Void> handleWebhook(
             @RequestHeader(GitHubWebhookHeader.EVENT) String event,
             @RequestBody GitHubIssueRequest request

server/src/main/java/com/onixbyte/ahsarahguide/domain/converter/FirearmTypeConverter.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.converter;
+package com.onixbyte.ahsarahguide.domain.converter;
 
-import com.onixbyte.deltaforceguide.enumeration.FirearmType;
+import com.onixbyte.ahsarahguide.enumeration.FirearmType;
 import jakarta.persistence.AttributeConverter;
 import jakarta.persistence.Converter;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/converter/ModificationStatusConverter.java

@@ -0,0 +1,28 @@
+package com.onixbyte.ahsarahguide.domain.converter;
+
+import com.onixbyte.ahsarahguide.enumeration.ModificationStatus;
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+import java.util.Optional;
+
+/**
+ * JPA attribute converter that maps {@link ModificationStatus} enum to/from its integer database representation.
+ *
+ * @author zihluwang
+ */
+@Converter
+public class ModificationStatusConverter implements AttributeConverter<ModificationStatus, Integer> {
+
+    @Override
+    public Integer convertToDatabaseColumn(ModificationStatus attribute) {
+        return Optional.ofNullable(attribute)
+                .map(ModificationStatus::getCode)
+                .orElse(null);
+    }
+
+    @Override
+    public ModificationStatus convertToEntityAttribute(Integer dbData) {
+        return ModificationStatus.fromCode(dbData);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/AccessoryRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/AccessoryResponse.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.domain.entity.Accessory;
+import com.onixbyte.ahsarahguide.domain.entity.Accessory;
 
 import java.util.List;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/BuildSummaryResponse.java

@@ -0,0 +1,20 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import java.util.List;
+
+/**
+ * Response record summarising a user's custom modification build.
+ * This is a skeleton record whose {@code from()} factory will be fully implemented
+ * when the CustomModification entity is introduced in a future issue.
+ *
+ * @author zihluwang
+ */
+public record BuildSummaryResponse(
+        Long id,
+        String name,
+        String code,
+        String firearmName,
+        List<String> tags
+) {
+    // from() factory to be implemented when CustomModification entity lands
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ChangePasswordRequest.java

@@ -0,0 +1,23 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+
+/**
+ * Request record for changing the current user's password.
+ *
+ * @author zihluwang
+ */
+public record ChangePasswordRequest(
+        @NotBlank(message = "旧密码不能为空")
+        String oldPassword,
+
+        @NotBlank(message = "新密码不能为空")
+        @Size(min = 8, max = 128, message = "密码长度必须在8-128个字符之间")
+        @Pattern(
+                regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$",
+                message = "密码必须包含至少一个大写字母、一个小写字母和一个数字"
+        )
+        String newPassword
+) {}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/DailyPassword.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 /**
  * DTO representing a single daily-generated password for a map.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/DailyPasswordData.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import java.time.LocalDateTime;
 import java.util.List;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/DailyPasswordMetadata.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 /**
  * DTO holding metadata about the daily password source and update tracking.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/DailyPasswordResponse.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 /**
  * Response DTO wrapping daily password data with metadata.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/EmailVerificationCode.java

@@ -0,0 +1,8 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+public record EmailVerificationCode(
+        String username,
+        String email,
+        String code
+) {
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ErrorResponse.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 /**
  * Standard error response body returned on API failures.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/FirearmRequest.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.enumeration.FirearmType;
+import com.onixbyte.ahsarahguide.enumeration.FirearmType;
 
 /**
  * Request DTO for creating or updating a firearm.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/FirearmResponse.java

@@ -1,7 +1,7 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.domain.entity.Firearm;
+import com.onixbyte.ahsarahguide.domain.entity.Firearm;
-import com.onixbyte.deltaforceguide.enumeration.FirearmType;
+import com.onixbyte.ahsarahguide.enumeration.FirearmType;
 
 /**
  * Response DTO for a firearm record, including associated modifications.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/GitHubIssueRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/GitHubWebhookIssue.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/GitHubWebhookLabel.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/GitHubWebhookRepository.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/GitHubWebhookSender.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.PropertyNamingStrategies;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/LoginRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ManageRoleRequest.java

@@ -0,0 +1,13 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import jakarta.validation.constraints.NotBlank;
+
+/**
+ * Request record for managing a user's role assignment.
+ *
+ * @author zihluwang
+ */
+public record ManageRoleRequest(
+        @NotBlank(message = "角色不能为空")
+        String role
+) {}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ModificationBatchCreateRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ModificationBatchDeleteRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.Positive;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ModificationRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/ModificationResponse.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.domain.entity.Modification;
+import com.onixbyte.ahsarahguide.domain.entity.Modification;
 
 import java.util.List;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/PageResponse.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import org.springframework.data.domain.Page;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/RegisterRequest.java

@@ -0,0 +1,31 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+
+/**
+ * Registration request containing the new user account information.
+ *
+ * @author zihluwang
+ */
+@Schema(description = "注册请求")
+public record RegisterRequest(
+        @NotBlank(message = "用户名不能为空")
+        @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED)
+        String username,
+        @NotBlank(message = "邮箱不能为空")
+        @Email(message = "邮箱格式不正确")
+        @Schema(description = "邮箱", requiredMode = Schema.RequiredMode.REQUIRED)
+        String email,
+        @Schema(description = "昵称")
+        String nickname,
+        @Schema(description = "头像链接")
+        String avatarUrl,
+        @NotBlank(message = "密码不能为空")
+        @Schema(description = "密码", requiredMode = Schema.RequiredMode.REQUIRED)
+        String password,
+        @NotBlank(message = "验证码 ID 不能为空") String verificationCodeId,
+        @NotBlank(message = "验证码不能为空") String verificationCode
+) {
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/SendVerificationCodeRequest.java

@@ -0,0 +1,9 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import jakarta.validation.constraints.NotBlank;
+
+public record SendVerificationCodeRequest(
+        @NotBlank(message = "用户名不能为空") String username,
+        @NotBlank(message = "电子邮箱地址不能为空") String email
+) {
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/SendVerificationCodeResponse.java

@@ -0,0 +1,6 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+public record SendVerificationCodeResponse(
+        String verificationCodeId
+) {
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/TuningRequest.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/TuningResponse.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.domain.entity.Tuning;
+import com.onixbyte.ahsarahguide.domain.entity.Tuning;
 
 /**
  * Response DTO for a tuning adjustment on an accessory.

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/UpdateProfileRequest.java

@@ -0,0 +1,14 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Size;
+
+/**
+ * Request record for updating the current user's profile information.
+ *
+ * @author zihluwang
+ */
+public record UpdateProfileRequest(
+        @Size(min = 1, max = 64, message = "昵称长度必须在1-64个字符之间")
+        String nickname
+) {}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/UserProfileResponse.java

@@ -0,0 +1,44 @@
+package com.onixbyte.ahsarahguide.domain.dto;
+
+import com.onixbyte.ahsarahguide.domain.entity.User;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+/**
+ * Response record for the current user's full profile information.
+ *
+ * @author zihluwang
+ */
+public record UserProfileResponse(
+        Long id,
+        String username,
+        String nickname,
+        String email,
+        String avatarUrl,
+        Boolean enabled,
+        LocalDateTime createdAt,
+        List<String> roles
+) {
+
+    /**
+     * Creates a {@code UserProfileResponse} from a {@link User} entity and its assigned roles.
+     *
+     * @param user  the user entity
+     * @param roles the list of role names assigned to the user
+     * @return the constructed response
+     */
+    public static UserProfileResponse from(User user, List<String> roles) {
+        return new UserProfileResponse(
+                user.getId(),
+                user.getUsername(),
+                user.getNickname() == null || user.getNickname().isBlank()
+                        ? user.getUsername() : user.getNickname(),
+                user.getEmail(),
+                user.getAvatarUrl(),
+                user.getEnabled(),
+                user.getCreatedAt(),
+                roles
+        );
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/domain/dto/UserResponse.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.domain.dto;
+package com.onixbyte.ahsarahguide.domain.dto;
 
-import com.onixbyte.deltaforceguide.domain.entity.User;
+import com.onixbyte.ahsarahguide.domain.entity.User;
 
 import java.time.LocalDateTime;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/Accessory.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
 import java.util.ArrayList;
 import java.util.List;

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/Firearm.java

@@ -1,7 +1,7 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
-import com.onixbyte.deltaforceguide.domain.converter.FirearmTypeConverter;
+import com.onixbyte.ahsarahguide.domain.converter.FirearmTypeConverter;
-import com.onixbyte.deltaforceguide.enumeration.FirearmType;
+import com.onixbyte.ahsarahguide.enumeration.FirearmType;
 import jakarta.persistence.CascadeType;
 import jakarta.persistence.Column;
 import jakarta.persistence.Convert;

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/Modification.java

@@ -1,11 +1,15 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
+import com.onixbyte.ahsarahguide.domain.converter.ModificationStatusConverter;
+import com.onixbyte.ahsarahguide.enumeration.ModificationStatus;
 import io.hypersistence.utils.hibernate.type.json.JsonType;
 import jakarta.persistence.*;
 import org.hibernate.annotations.Type;
 
+import java.time.OffsetDateTime;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Entity representing a firearm modification or build configuration.
@@ -25,6 +29,10 @@ public class Modification {
     @GeneratedValue(strategy = GenerationType.IDENTITY)
     private Long id;
 
+    @ManyToOne
+    @JoinColumn(name = "user_id")
+    private User user;
+
     @ManyToOne(fetch = FetchType.LAZY, optional = false)
     @JoinColumn(name = "firearm_id", nullable = false, foreignKey = @ForeignKey(name = "fk_modification_firearm"))
     private Firearm firearm;
@@ -36,11 +44,11 @@ public class Modification {
     private String code;
 
     @Type(JsonType.class)
-    @Column(name = "tags", columnDefinition = "jsonb")
+    @Column(name = "tags", columnDefinition = "jsonb", nullable = false)
     private List<String> tags = new ArrayList<>();
 
     @Type(JsonType.class)
-    @Column(name = "accessories", columnDefinition = "jsonb")
+    @Column(name = "accessories", columnDefinition = "jsonb", nullable = false)
     private List<Accessory> accessories = new ArrayList<>();
 
     @Column(name = "note", columnDefinition = "TEXT")
@@ -52,6 +60,16 @@ public class Modification {
     @Column(name = "video_url", length = 512)
     private String videoUrl;
 
+    @Column(name = "status", nullable = false)
+    @Convert(converter = ModificationStatusConverter.class)
+    private ModificationStatus status = ModificationStatus.DRAFT;
+
+    @Column(name = "create_by")
+    private Long createBy;
+
+    @Column(name = "create_time", nullable = false)
+    private OffsetDateTime createTime;
+
     public Long getId() {
         return id;
     }
@@ -132,6 +150,38 @@ public class Modification {
         this.videoUrl = videoUrl;
     }
 
+    public User getUser() {
+        return user;
+    }
+
+    public void setUser(User user) {
+        this.user = user;
+    }
+
+    public Long getCreateBy() {
+        return createBy;
+    }
+
+    public void setCreateBy(Long createBy) {
+        this.createBy = createBy;
+    }
+
+    public OffsetDateTime getCreateTime() {
+        return createTime;
+    }
+
+    public void setCreateTime(OffsetDateTime createTime) {
+        this.createTime = createTime;
+    }
+
+    public ModificationStatus getStatus() {
+        return status;
+    }
+
+    public void setStatus(ModificationStatus status) {
+        this.status = status;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -139,6 +189,7 @@ public class Modification {
     public static class Builder {
 
         private Long id;
+        private User user;
         private Firearm firearm;
         private String name;
         private String code;
@@ -147,12 +198,20 @@ public class Modification {
         private String note;
         private String author;
         private String videoUrl;
+        private Long createBy;
+        private OffsetDateTime createTime;
+        private ModificationStatus status;
 
         public Builder id(Long id) {
             this.id = id;
             return this;
         }
 
+        public Builder user(User user) {
+            this.user = user;
+            return this;
+        }
+
         public Builder firearm(Firearm firearm) {
             this.firearm = firearm;
             return this;
@@ -193,17 +252,36 @@ public class Modification {
             return this;
         }
 
+        public Builder createBy(Long createBy) {
+            this.createBy = createBy;
+            return this;
+        }
+
+        public Builder createTime(OffsetDateTime createTime) {
+            this.createTime = createTime;
+            return this;
+        }
+
+        public Builder status(ModificationStatus status) {
+            this.status = status;
+            return this;
+        }
+
         public Modification build() {
             Modification modification = new Modification();
             modification.id = this.id;
+            modification.user = this.user;
             modification.firearm = this.firearm;
             modification.name = this.name;
             modification.code = this.code;
-            modification.tags = this.tags == null ? new ArrayList<>() : this.tags;
+            modification.tags = Optional.ofNullable(this.tags).orElseGet(ArrayList::new);
-            modification.accessories = this.accessories == null ? new ArrayList<>() : this.accessories;
+            modification.accessories = Optional.ofNullable(this.accessories).orElseGet(ArrayList::new);
             modification.note = this.note;
             modification.author = this.author;
             modification.videoUrl = this.videoUrl;
+            modification.createBy = this.createBy;
+            modification.createTime = Optional.ofNullable(this.createTime).orElseGet(OffsetDateTime::now);
+            modification.status = Optional.ofNullable(this.status).orElse(ModificationStatus.DRAFT);
             return modification;
         }
     }

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/Tuning.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
 import java.util.Objects;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/User.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
 import jakarta.persistence.CascadeType;
 import jakarta.persistence.Column;
@@ -7,8 +7,10 @@ import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
 import jakarta.persistence.OneToMany;
+import jakarta.persistence.PreUpdate;
 import jakarta.persistence.Table;
 
+import java.time.LocalDateTime;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -31,6 +33,21 @@ public class User {
     @Column(name = "email", nullable = false)
     private String email;
 
+    @Column(name = "nickname")
+    private String nickname;
+
+    @Column(name = "avatar_url")
+    private String avatarUrl;
+
+    @Column(name = "enabled", nullable = false)
+    private Boolean enabled = true;
+
+    @Column(name = "created_at", nullable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
     @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
     private List<UserCredential> credentials = new ArrayList<>();
 
@@ -58,6 +75,51 @@ public class User {
         this.email = email;
     }
 
+    public String getNickname() {
+        return nickname;
+    }
+
+    public void setNickname(String nickname) {
+        this.nickname = nickname;
+    }
+
+    public String getAvatarUrl() {
+        return avatarUrl;
+    }
+
+    public void setAvatarUrl(String avatarUrl) {
+        this.avatarUrl = avatarUrl;
+    }
+
+    public Boolean getEnabled() {
+        return enabled;
+    }
+
+    public void setEnabled(Boolean enabled) {
+        this.enabled = enabled;
+    }
+
+    public LocalDateTime getCreatedAt() {
+        return createdAt;
+    }
+
+    public void setCreatedAt(LocalDateTime createdAt) {
+        this.createdAt = createdAt;
+    }
+
+    public LocalDateTime getUpdatedAt() {
+        return updatedAt;
+    }
+
+    public void setUpdatedAt(LocalDateTime updatedAt) {
+        this.updatedAt = updatedAt;
+    }
+
+    @PreUpdate
+    private void onUpdate() {
+        this.updatedAt = LocalDateTime.now();
+    }
+
     public List<UserCredential> getCredentials() {
         return credentials;
     }
@@ -85,6 +147,11 @@ public class User {
         private Long id;
         private String username;
         private String email;
+        private String nickname;
+        private String avatarUrl;
+        private Boolean enabled;
+        private LocalDateTime createdAt;
+        private LocalDateTime updatedAt;
         private List<UserCredential> credentials;
 
         public Builder id(Long id) {
@@ -102,6 +169,31 @@ public class User {
             return this;
         }
 
+        public Builder nickname(String nickname) {
+            this.nickname = nickname;
+            return this;
+        }
+
+        public Builder avatarUrl(String avatarUrl) {
+            this.avatarUrl = avatarUrl;
+            return this;
+        }
+
+        public Builder enabled(Boolean enabled) {
+            this.enabled = enabled;
+            return this;
+        }
+
+        public Builder createdAt(LocalDateTime createdAt) {
+            this.createdAt = createdAt;
+            return this;
+        }
+
+        public Builder updatedAt(LocalDateTime updatedAt) {
+            this.updatedAt = updatedAt;
+            return this;
+        }
+
         public Builder credentials(List<UserCredential> credentials) {
             this.credentials = credentials;
             return this;
@@ -112,6 +204,12 @@ public class User {
             user.id = this.id;
             user.username = this.username;
             user.email = this.email;
+            user.nickname = this.nickname == null || this.nickname.isBlank()
+                    ? this.username : this.nickname;
+            user.avatarUrl = this.avatarUrl;
+            user.enabled = this.enabled == null || this.enabled;
+            user.createdAt = this.createdAt;
+            user.updatedAt = this.updatedAt;
             user.credentials = this.credentials == null ? new ArrayList<>() : this.credentials;
             return user;
         }

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/UserCredential.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
 import jakarta.persistence.Column;
 import jakarta.persistence.AttributeOverride;

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/UserCredentialId.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.domain.entity;
+package com.onixbyte.ahsarahguide.domain.entity;
 
 import jakarta.persistence.Embeddable;
 

server/src/main/java/com/onixbyte/ahsarahguide/domain/entity/UserRole.java

@@ -0,0 +1,101 @@
+package com.onixbyte.ahsarahguide.domain.entity;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.ForeignKey;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MapsId;
+import jakarta.persistence.Table;
+
+/**
+ * Entity representing a role assignment linking a user to a security role.
+ * <p>
+ * A user owns at most one role assignment, so the user ID is the primary key.
+ *
+ * @author zihluwang
+ */
+@Entity
+@Table(name = "user_role")
+public class UserRole {
+
+    @Id
+    @Column(name = "user_id")
+    private Long userId;
+
+    @MapsId("userId")
+    @ManyToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(name = "user_id", nullable = false, foreignKey = @ForeignKey(name = "fk_user_role_user"))
+    private User user;
+
+    @Column(name = "role", nullable = false, length = 32)
+    private String role;
+
+    public Long getUserId() {
+        return userId;
+    }
+
+    public void setUserId(Long userId) {
+        this.userId = userId;
+    }
+
+    public User getUser() {
+        return user;
+    }
+
+    public void setUser(User user) {
+        this.user = user;
+        if (user != null) {
+            this.userId = user.getId();
+        }
+    }
+
+    public String getRole() {
+        return role;
+    }
+
+    public void setRole(String role) {
+        this.role = role;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+
+        private User user;
+        private Long userId;
+        private String role;
+
+        public Builder user(User user) {
+            this.user = user;
+            return this;
+        }
+
+        public Builder userId(Long userId) {
+            this.userId = userId;
+            return this;
+        }
+
+        public Builder role(String role) {
+            this.role = role;
+            return this;
+        }
+
+        public UserRole build() {
+            UserRole userRole = new UserRole();
+            userRole.user = this.user;
+            userRole.role = this.role;
+            if (this.user != null) {
+                userRole.userId = this.user.getId();
+            }
+            if (this.userId != null) {
+                userRole.userId = this.userId;
+            }
+            return userRole;
+        }
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/enumeration/FirearmType.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.enumeration;
+package com.onixbyte.ahsarahguide.enumeration;
 
 /**
  * Enumeration of firearm types in the Delta Force game.

server/src/main/java/com/onixbyte/ahsarahguide/enumeration/ModificationStatus.java

@@ -0,0 +1,44 @@
+package com.onixbyte.ahsarahguide.enumeration;
+
+import java.util.Arrays;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/**
+ * Enumeration of modification statuses.
+ * <p>
+ * Each status is associated with an integer code used for database persistence.
+ *
+ * @author zihluwang
+ */
+public enum ModificationStatus {
+
+    DRAFT(0),
+    PENDING_APPROVAL(1),
+    PUBLISHED(2);
+
+    private final int code;
+
+    ModificationStatus(int code) {
+        this.code = code;
+    }
+
+    public int getCode() {
+        return code;
+    }
+
+    public static final Map<Integer, ModificationStatus> CODE_MAP = Arrays.stream(values())
+            .collect(Collectors.toMap(ModificationStatus::getCode, Function.identity()));
+
+    /**
+     * Resolve a ModificationStatus from its integer code.
+     *
+     * @param code the integer code, may be null
+     * @return the corresponding ModificationStatus, or null if the code is null
+     * @throws IllegalArgumentException if the code does not match any known status
+     */
+    public static ModificationStatus fromCode(Integer code) {
+        return CODE_MAP.get(code);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/BadRequestException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class BadRequestException extends ResponseStatusException {
+
+    public BadRequestException(String reason) {
+        super(HttpStatus.BAD_REQUEST, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/ConflictException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class ConflictException extends ResponseStatusException {
+
+    public ConflictException(String reason) {
+        super(HttpStatus.CONFLICT, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/ForbiddenException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class ForbiddenException extends ResponseStatusException {
+
+    public ForbiddenException(String reason) {
+        super(HttpStatus.FORBIDDEN, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/InternalServerErrorException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class InternalServerErrorException extends ResponseStatusException {
+
+    public InternalServerErrorException(String reason) {
+        super(HttpStatus.INTERNAL_SERVER_ERROR, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/NotFoundException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class NotFoundException extends ResponseStatusException {
+
+    public NotFoundException(String reason) {
+        super(HttpStatus.NOT_FOUND, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/exeption/UnauthorisedException.java

@@ -0,0 +1,11 @@
+package com.onixbyte.ahsarahguide.exeption;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+public class UnauthorisedException extends ResponseStatusException {
+
+    public UnauthorisedException(String reason) {
+        super(HttpStatus.UNAUTHORIZED, reason);
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/filter/TokenAuthenticationFilter.java

@@ -1,11 +1,12 @@
-package com.onixbyte.deltaforceguide.filter;
+package com.onixbyte.ahsarahguide.filter;
 
 import com.auth0.jwt.exceptions.JWTVerificationException;
-import com.onixbyte.deltaforceguide.client.TokenClient;
+import com.onixbyte.ahsarahguide.client.TokenClient;
-import com.onixbyte.deltaforceguide.exeption.BizException;
+import com.onixbyte.ahsarahguide.exeption.UnauthorisedException;
-import com.onixbyte.deltaforceguide.manager.UserManager;
+import com.onixbyte.ahsarahguide.manager.CookieManager;
-import com.onixbyte.deltaforceguide.security.authentication.UsernamePasswordAuthentication;
+import com.onixbyte.ahsarahguide.manager.UserManager;
-import com.onixbyte.deltaforceguide.service.CookieService;
+import com.onixbyte.ahsarahguide.manager.UserRoleManager;
+import com.onixbyte.ahsarahguide.security.authentication.UsernamePasswordAuthentication;
 import jakarta.servlet.FilterChain;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.http.Cookie;
@@ -15,10 +16,11 @@ import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpHeaders;
-import org.springframework.http.HttpStatus;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.stereotype.Component;
 import org.springframework.web.filter.OncePerRequestFilter;
+import org.springframework.web.server.ResponseStatusException;
 import org.springframework.web.servlet.HandlerExceptionResolver;
 import org.springframework.web.util.WebUtils;
 
@@ -27,6 +29,7 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 /**
  * Servlet filter that extracts and validates JWT tokens from httpOnly cookies for each request.
@@ -40,19 +43,22 @@ public class TokenAuthenticationFilter extends OncePerRequestFilter {
     private static final Duration ACCESS_TOKEN_RENEW_THRESHOLD = Duration.ofMinutes(5);
 
     private final UserManager userManager;
+    private final UserRoleManager userRoleManager;
     private final TokenClient tokenClient;
-    private final CookieService cookieService;
+    private final CookieManager cookieManager;
     private final HandlerExceptionResolver handlerExceptionResolver;
 
     public TokenAuthenticationFilter(
             UserManager userManager,
+            UserRoleManager userRoleManager,
             TokenClient tokenClient,
-            CookieService cookieService,
+            CookieManager cookieManager,
             HandlerExceptionResolver handlerExceptionResolver
     ) {
         this.userManager = userManager;
+        this.userRoleManager = userRoleManager;
         this.tokenClient = tokenClient;
-        this.cookieService = cookieService;
+        this.cookieManager = cookieManager;
         this.handlerExceptionResolver = handlerExceptionResolver;
     }
 
@@ -83,16 +89,20 @@ public class TokenAuthenticationFilter extends OncePerRequestFilter {
 
             var userWrapper = userManager.findByUsername(username);
             if (userWrapper.isEmpty()) {
-                throw new BizException(HttpStatus.UNAUTHORIZED, "登录已过期，请重新登录");
+                throw new UnauthorisedException("登录已过期，请重新登录");
             }
 
             var user = userWrapper.get();
-            var authentication = UsernamePasswordAuthentication.authenticated(user);
+            var roles = userRoleManager.findAllByUserId(user.getId());
+            var authorities = roles.stream()
+                    .map(r -> new SimpleGrantedAuthority(r.getRole()))
+                    .collect(Collectors.toList());
+            var authentication = UsernamePasswordAuthentication.authenticated(user, authorities);
             SecurityContextHolder.getContext().setAuthentication(authentication);
 
             if (shouldRenew(decodedToken.getExpiresAt().toInstant())) {
                 var renewedToken = tokenClient.generateToken(user);
-                var renewedTokenCookie = cookieService.buildCookie("AccessToken", renewedToken);
+                var renewedTokenCookie = cookieManager.buildCookie("AccessToken", renewedToken);
                 response.addHeader(HttpHeaders.SET_COOKIE, renewedTokenCookie.toString());
             }
 
@@ -100,8 +110,8 @@ public class TokenAuthenticationFilter extends OncePerRequestFilter {
         } catch (JWTVerificationException e) {
             log.error("JWT verification failed.", e);
             handlerExceptionResolver.resolveException(request, response, null,
-                    new BizException(HttpStatus.UNAUTHORIZED, "登录已过期，请重新登录"));
+                    new UnauthorisedException("登录已过期，请重新登录"));
-        } catch (BizException e) {
+        } catch (ResponseStatusException e) {
             handlerExceptionResolver.resolveException(request, response, null, e);
         }
     }

server/src/main/java/com/onixbyte/ahsarahguide/filter/WebhookFilter.java

@@ -1,6 +1,6 @@
-package com.onixbyte.deltaforceguide.filter;
+package com.onixbyte.ahsarahguide.filter;
 
-import com.onixbyte.deltaforceguide.wrapper.RepeatedlyReadRequestWrapper;
+import com.onixbyte.ahsarahguide.wrapper.RepeatedlyReadRequestWrapper;
 import jakarta.servlet.*;
 import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.stereotype.Component;

server/src/main/java/com/onixbyte/ahsarahguide/interceptor/GitHubWebhookInterceptor.java

@@ -1,16 +1,16 @@
-package com.onixbyte.deltaforceguide.interceptor;
+package com.onixbyte.ahsarahguide.interceptor;
 
 import com.onixbyte.crypto.util.CryptoUtil;
-import com.onixbyte.deltaforceguide.exeption.BizException;
+import com.onixbyte.ahsarahguide.exeption.InternalServerErrorException;
-import com.onixbyte.deltaforceguide.manager.WebhookManager;
+import com.onixbyte.ahsarahguide.exeption.UnauthorisedException;
-import com.onixbyte.deltaforceguide.shared.GitHubWebhookHeader;
+import com.onixbyte.ahsarahguide.manager.WebhookManager;
-import com.onixbyte.deltaforceguide.wrapper.RepeatedlyReadRequestWrapper;
+import com.onixbyte.ahsarahguide.shared.GitHubWebhookHeader;
+import com.onixbyte.ahsarahguide.wrapper.RepeatedlyReadRequestWrapper;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-import org.springframework.http.HttpStatus;
 import org.springframework.stereotype.Component;
 import org.springframework.web.servlet.HandlerInterceptor;
 
@@ -44,7 +44,7 @@ public class GitHubWebhookInterceptor implements HandlerInterceptor {
             @NonNull Object handler
     ) {
         if (!(request instanceof RepeatedlyReadRequestWrapper req)) {
-            throw new BizException(HttpStatus.INTERNAL_SERVER_ERROR,
+            throw new InternalServerErrorException(
                     "Request body is not readable");
         }
 
@@ -58,7 +58,7 @@ public class GitHubWebhookInterceptor implements HandlerInterceptor {
         if (signatureHeader == null || signatureHeader.isBlank()) {
             log.warn("Missing {} header from ip={}",
                     GitHubWebhookHeader.SIGNATURE_256, request.getRemoteAddr());
-            throw new BizException(HttpStatus.UNAUTHORIZED,
+            throw new UnauthorisedException(
                     "Missing webhook signature header");
         }
 
@@ -70,13 +70,13 @@ public class GitHubWebhookInterceptor implements HandlerInterceptor {
                     computed.getBytes(StandardCharsets.UTF_8),
                     signatureHeader.getBytes(StandardCharsets.UTF_8))) {
                 log.warn("Invalid webhook signature from ip={}", request.getRemoteAddr());
-                throw new BizException(HttpStatus.UNAUTHORIZED, "Invalid webhook signature");
+                throw new UnauthorisedException("Invalid webhook signature");
             }
 
             return true;
         } catch (NoSuchAlgorithmException | InvalidKeyException e) {
             log.error("Failed to compute HMAC-SHA256", e);
-            throw new BizException(HttpStatus.INTERNAL_SERVER_ERROR,
+            throw new InternalServerErrorException(
                     "Failed to verify webhook signature");
         }
     }

server/src/main/java/com/onixbyte/ahsarahguide/interceptor/TrafficInterceptor.java

@@ -1,4 +1,4 @@
-package com.onixbyte.deltaforceguide.interceptor;
+package com.onixbyte.ahsarahguide.interceptor;
 
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;

server/src/main/java/com/onixbyte/ahsarahguide/manager/AppManager.java

@@ -0,0 +1,27 @@
+package com.onixbyte.ahsarahguide.manager;
+
+import org.springframework.boot.info.BuildProperties;
+import org.springframework.stereotype.Component;
+
+@Component
+public class AppManager {
+
+    private final BuildProperties buildProperties;
+
+    public AppManager(BuildProperties buildProperties) {
+        this.buildProperties = buildProperties;
+    }
+
+    /**
+     * Retrieves the application version.
+     *
+     * @return the version string of this application
+     */
+    public String getVersion() {
+        return "v%s-%s by @%s".formatted(
+                buildProperties.getVersion(),
+                buildProperties.get("channel"),
+                buildProperties.get("vendor")
+        );
+    }
+}

server/src/main/java/com/onixbyte/ahsarahguide/manager/CookieManager.java

@@ -1,23 +1,44 @@
-package com.onixbyte.deltaforceguide.service;
+package com.onixbyte.ahsarahguide.manager;
 
-import com.onixbyte.deltaforceguide.manager.CookieManager;
+import com.onixbyte.ahsarahguide.properties.CookieProperties;
+import org.springframework.boot.web.server.Cookie;
 import org.springframework.http.ResponseCookie;
-import org.springframework.stereotype.Service;
+import org.springframework.stereotype.Component;
 
 import java.time.Duration;
 
 /**
- * Service for building HTTP cookies with configurable properties.
+ * Manager providing cookie construction operations with configurable properties.
  *
  * @author zihluwang
  */
-@Service
+@Component
-public class CookieService {
+public class CookieManager {
 
-    private final CookieManager cookieManager;
+    private final CookieProperties cookieProperties;
 
-    public CookieService(CookieManager cookieManager) {
+    public CookieManager(CookieProperties cookieProperties) {
-        this.cookieManager = cookieManager;
+        this.cookieProperties = cookieProperties;
+    }
+
+    public Boolean getHttpOnly() {
+        return cookieProperties.httpOnly();
+    }
+
+    public Boolean getSecure() {
+        return cookieProperties.secure();
+    }
+
+    public Cookie.SameSite getSameSite() {
+        return cookieProperties.sameSite();
+    }
+
+    public String getPath() {
+        return cookieProperties.path();
+    }
+
+    public Duration getMaxAge() {
+        return cookieProperties.maxAge();
     }
 
     /**
@@ -28,7 +49,7 @@ public class CookieService {
      * @return a configured ResponseCookie
      */
     public ResponseCookie buildCookie(String cookieName, String value) {
-        return buildCookieInternal(cookieName, value, cookieManager.getMaxAge());
+        return buildCookieInternal(cookieName, value, getMaxAge());
     }
 
     /**
@@ -57,11 +78,11 @@ public class CookieService {
             Duration maxAge
     ) {
         return ResponseCookie.from(name, value)
-                .secure(cookieManager.getSecure())
+                .secure(getSecure())
                 .maxAge(maxAge)
-                .httpOnly(cookieManager.getHttpOnly())
+                .httpOnly(getHttpOnly())
-                .path(cookieManager.getPath())
+                .path(getPath())
-                .sameSite(cookieManager.getSameSite().attributeValue())
+                .sameSite(getSameSite().attributeValue())
                 .build();
     }
 }