# 萌芽小店 · 后端（mengyastore-backend-java）

基于 **Java 17、Spring Boot 3、Spring MVC、Spring Data JPA（Hibernate）** 的 REST API，配套 **Vue 3** 前端联调；可在 **IntelliJ IDEA** 中运行 `MengyastoreBackendJavaApplication` 进行开发与测试。

## 技术栈与 Maven 依赖

| 依赖 | 用途 |
|------|------|
| spring-boot-starter-web | REST、Jackson |
| spring-boot-starter-data-jpa | 实体、Repository、事务 |
| mysql-connector-j | MySQL JDBC |
| spring-boot-starter-amqp | RabbitMQ |
| spring-boot-starter-data-redis | Redis |
| spring-boot-starter-validation | Bean 校验 |
| spring-boot-starter-mail | Jakarta Mail（业务 SMTP 配置来自数据库） |
| spring-boot-starter-actuator | 健康检查（默认关闭 Mail 指标以免未配 SMTP 报错） |
| lombok | Getter 等样板代码 |

## 包结构

```
src/main/java/com/smyhub/store/mengyastorebackendjava/
├── MengyastoreBackendJavaApplication.java
├── config/           # AppProperties、CORS、RabbitMQ、Redis、RestTemplate、WebMvc
├── controller/       # 按域拆分；admin/ 为管理端
├── dto/request|response/
├── entity/           # JPA；entity/converter 处理 JSON 列
├── exception/        # BusinessException、GlobalExceptionHandler
├── mq/               # 拓扑、Payload、Producer、Consumer（随 app.rabbitmq-enabled）
├── repository/
├── security/         # 管理令牌与用户 Bearer 拦截器、ThreadLocal 用户
└── service/          # 业务与 SystemStatusService 等
```

## API 路由一览

### 公开

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查；含 RabbitMQ 状态（`ok` / `error` / `disabled`） |
| GET | `/api/products` | 上架商品列表（不含卡密与 `fixedContent`） |
| POST | `/api/products/{id}/view` | 记录浏览（进程内去重） |
| GET | `/api/stats` | 订单数、访问量 |
| POST | `/api/site/visit` | 站点访问计数 |
| GET | `/api/site/maintenance` | 维护状态 |
| POST | `/api/checkout` | 创建订单（可选 `Authorization: Bearer`） |
| POST | `/api/orders/{id}/confirm` | 确认订单 |

### 用户（Bearer，远程认证服务校验）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/orders` | 当前用户订单 |
| GET / POST | `/api/wishlist` | 列表；POST body `{"productId":"…"}` |
| DELETE | `/api/wishlist/{id}` | 删除，路径参数为商品 ID |
| GET / POST | `/api/chat/messages` | 消息列表；发送（带发送频控） |

### 管理端（`X-Admin-Token`；兼容 `Authorization`、`?token=`）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/verify` | 请求体 `{"token":"…"}`，**响应顶层** `{"valid":true/false}` |
| GET / POST / PUT / PATCH / DELETE | `/api/admin/products` | 商品 CRUD 与上下架 |
| POST | `/api/admin/site/maintenance` | 维护模式 |
| GET / POST | `/api/admin/site/smtp` | SMTP 配置读/写 |
| GET | `/api/admin/orders` | 订单列表 |
| DELETE | `/api/admin/orders/{id}` | 删除订单 |
| GET / POST / DELETE | `/api/admin/chat`、`/api/admin/chat/{account}` | 会话、回复、清空 |
| GET | `/api/admin/system-status` | 聚合 backend / mysql / redis / rabbitmq；JSON 外层为 `{"data":{…},"error":null}` |

其它管理接口的成功响应多为 `{"data":…,"error":null}` 形式。

## 数据库表（摘要）

开发环境常用 `spring.jpa.hibernate.ddl-auto: update` 同步表结构。

**products：** 商品信息；`fulfillment_type`：`card`（卡密库存）/ `fixed`（固定内容）；`fixed_content` 不在公开列表返回；含价格、标签 JSON、封面、截图 JSON、`active`、`require_login`、`max_per_account`、`total_sold`、`view_count`、`delivery_mode` 等。

**product_codes：** 每行一条卡密，关联 `product_id`；固定内容商品可不设。

**orders：** `delivered_codes` JSON、用户信息、`status`、`delivery_mode`、`notify_email`、联系方式等。

**site_settings：** 键值对，如 `totalVisits`、`maintenance`、`smtpHost`、`smtpPassword` 等。

**wishlists：** 用户账号与商品 ID 唯一约束。

**chat_messages：** 会话消息、`from_admin`、发送时间等。

## 配置说明（application.yaml）

| 项 | 说明 |
|----|------|
| `spring.datasource.*` | MySQL |
| `spring.jpa.hibernate.ddl-auto` | 如 `update` |
| `server.port` | HTTP 端口，需与前端 `VITE_API_BASE_URL` 一致 |
| `spring.rabbitmq.*` | Broker；`app.rabbitmq-enabled=false` 时不注册监听器与拓扑，避免无法连接时启动失败 |
| `spring.data.redis.*` | Redis；`app.redis-enabled=false` 时系统状态中 Redis 标记为未启用 |
| `app.admin-token` | 管理后台令牌 |
| `app.auth-api-url` | 用户 token 远程校验服务根地址（`POST …/api/auth/verify`） |
| `app.app-env` | `development` / `production` |
| `app.rabbitmq-enabled` | 是否启用 RabbitMQ 发信与消费者 |
| `app.redis-enabled` | 是否在系统状态中探测 Redis |
| `app.rabbitmq-env` / `app.redis-env` | `dev` / `prod`，影响交换机与队列名 |
| `app.cors-allowed-origins` | 逗号分隔的允许源 |
| `management.health.mail.enabled` | 建议 `false` 直至配置 SMTP |

**CORS：** 见 `CorsConfig`，包含 `Authorization`、`X-Admin-Token` 等请求头。

## 前端联调

前端 axios `baseURL` 来自环境变量或当前页 `origin`，请指向本服务监听的 **协议 + 主机 + 端口**。
