# 技术架构说明: “蚊子”传播系统

## 1. 概述

本文档旨在为“蚊子”传播系统定义清晰、统一的技术架构，以指导后续的开发和运维工作。项目将遵循前后端分离的现代Web应用架构模式。

- **后端**: 基于 **Spring Boot 3** 的微服务架构，负责所有业务逻辑、数据处理和API输出。
- **前端**: 基于 **Vue 3** 的单页面应用（SPA），负责提供给“活动管理员”的管理后台界面和“终端参与者”的用户中心界面。

## 2. 技术选型 (Tech Stack)

| 领域 | 技术选型 | 备注 |
| :--- | :--- | :--- |
| **后端框架** | Spring Boot 3.x | 使用Java 17, 提供强大的生态和快速开发能力。 |
| **前端框架** | Vue 3.x | 使用 Composition API 和 `<script setup>` 语法，提升代码可读性和复用性。 |
| **构建工具** | Maven (后端), Vite (前端) | Vite提供极速的开发服务器和构建体验。 |
| **数据库** | PostgreSQL | 功能强大的开源关系型数据库，支持JSON等复杂数据类型。 |
| **数据访问** | Spring Data JPA / Hibernate | 简化数据库操作，实现ORM。 |
| **API安全** | Spring Security | 处理API Key认证及未来可能的用户认证。 |
| **消息队列** | RabbitMQ | 用于奖励发放等异步任务处理，通过Spring AMQP集成。 |
| **缓存** | Redis | 用于缓存热点数据，如排行榜。 |
| **UI组件库** | Element Plus | 成熟、丰富的Vue 3组件库。 |
| **前端状态管理**| Pinia | Vue 3官方推荐的状态管理库，轻量且直观。 |
| **API客户端** | Axios | 成熟的HTTP客户端，用于前后端交互。 |

## 3. 系统架构图

```mermaid
graph TD
    subgraph 用户端
        A[浏览器/移动端] --> B{前端应用 (Vue 3)};
    end

    subgraph 服务端
        B --> C{API网关/负载均衡};
        C --> D[后端主应用 (Spring Boot)];
        D -- JDBC --> E[PostgreSQL数据库];
        D -- AMQP --> F[RabbitMQ消息队列];
        D -- Redis Client --> G[Redis缓存];
        H[奖励发放Worker] -- AMQP --> F;
    end

    subgraph 第三方服务
        D --> I{第三方奖励系统 API};
        J[客户应用] --> C;
    end
```

## 4. 核心模块设计思路

- **活动管理 (Activity Management)**: 后端提供完整的CRUD API，前端通过表单驱动，实现活动的动态配置。
- **数据分析 (Data Analytics)**: 后端通过定时任务（`@Scheduled`）预先计算和聚合每日统计数据，存入统计表，避免前端查询时实时计算的性能瓶颈。
- **用户端体验 (User Experience)**: 
    - **短链接**: 后端提供一个专门的服务，负责长链接到短链接的转换和重定向。
    - **海报生成**: 后端使用Java图像处理库（如 `thumbnailator`）生成海报，并设计降级方案，在高负载时仅返回数据由前端`canvas`进行渲染。
- **系统集成 (System Integration)**: 
    - **回调API**: 通过Spring Security的过滤器链实现`X-API-Key`的认证和速率限制。
    - **异步奖励**: 采用消息队列实现核心业务（回调处理）与非核心业务（奖励发放）的解耦，提高系统的响应速度和可靠性。

## 5. 部署与运维 (DevOps)

- **容器化**: 前后端应用都将被打包成Docker镜像。
- **CI/CD**: 设立GitHub Actions工作流，在代码推送到主分支时，自动运行测试、构建Docker镜像并推送到镜像仓库。
- **部署**: 推荐使用Kubernetes (K8s) 或云服务商提供的容器服务（如 AWS ECS, Google Cloud Run）进行部署，以实现弹性伸缩和高可用性。