113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# 萌芽小店 · 后端（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`，请指向本服务监听的 **协议 + 主机 + 端口**。
|