chore: sync local updates

.java-test/后端文档.md

@@ -0,0 +1,112 @@
+# 萌芽小店 · 后端（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`，请指向本服务监听的 **协议 + 主机 + 端口**。