wenzi/docs/architecture.md

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

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. 系统架构图

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）进行部署，以实现弹性伸缩和高可用性。