# 三松礼品产品库

一个可直接使用 IntelliJ IDEA 打开的前后端工程，用于检索、筛选和导出海外礼品产品素材。

## 项目能力

- 中文关键词搜索、标签筛选、价格筛选和排序
- 产品详情、图片浏览、收藏与相似产品推荐
- 批量选择产品，后台异步下载图片并生成 ZIP
- 导出进度轮询、历史记录、下载和删除
- 开发环境使用 H2 文件数据库，启动时由 Flyway 自动建表并写入 22 条示例数据
- 生产环境可切换 PostgreSQL，附带 Nginx、systemd 和构建配置

## 技术栈

| 模块 | 技术 |
| --- | --- |
| 前端 | React 18、TypeScript、Vite 6、Tailwind CSS 4、React Router |
| 后端 | Java 8、Spring Boot 2.7.18、Spring Data JPA、Flyway |
| 数据库 | H2（开发/可选快速部署）、PostgreSQL（推荐生产） |
| 构建 | npm、Maven 3.9+ |

## 使用 IntelliJ IDEA 打开

1. 在 IDEA 选择 `File > Open`，打开整个 `D:\AAAAA\AAA-sans` 目录，不要只打开 `client` 或 `server`。
2. 将 Project SDK 设置为 JDK 8；后端构建与生产运行均要求 Java 主版本 1.8。
3. 等待 IDEA 导入根目录 `pom.xml` 和前端 `package.json`。
4. 首次运行前，在 IDEA Terminal 执行 `npm --prefix client install`。
5. 在运行配置中选择 `Fullstack`，或分别运行 `Backend` 和 `Frontend`。
6. 浏览器访问 <http://localhost:5173>，后端 API 位于 <http://localhost:8080/api>。

如果 IDEA 没有自动识别运行配置，可直接运行后端入口 `server/src/main/java/com/singsong/SingsongApplication.java`，再运行前端 `client/package.json` 中的 `dev` 脚本。

## 命令行开发

PowerShell 当前默认 Java 若不是 8，请先将 `JAVA_HOME` 和 `Path` 指向本机 JDK 8，并用 `java -version` 确认显示 `1.8.x`。

启动后端：

```powershell
mvn -pl server spring-boot:run
```

启动前端（另开一个终端）：

```powershell
npm --prefix client install
npm --prefix client run dev
```

## 构建与测试

```powershell
npm --prefix client run typecheck
npm --prefix client run build
mvn -pl server test
mvn -pl server package
```

## 目录结构

```text
AAA-sans/
|- client/                 React 前端源码
|  |- src/api/             后端接口封装
|  |- src/app/components/  页面和业务组件
|  |- src/contexts/        登录与收藏状态
|  `- src/types/           TypeScript 类型
|- server/                 Spring Boot 后端源码
|  |- src/main/java/       控制器、服务、实体、仓储和导出任务
|  |- src/main/resources/  配置与 Flyway 数据库脚本
|  `- src/test/            后端集成测试
|- docs/                   API、数据库和技术文档
|- deploy/                 Nginx、systemd 和构建脚本
|- pom.xml                 IDEA/Maven 根工程入口
`- package.json            前端统一脚本入口
```

## 本地数据

首次启动后端会创建 `server/data/` 和 `server/exports/`，两者均已加入 `.gitignore`。如需全新开发数据，可在后端停止后删除 `server/data/`，再次启动时 Flyway 会重新初始化。

开发环境的 H2 控制台地址为 <http://localhost:8080/api/h2-console>，JDBC URL 为 `jdbc:h2:file:./data/singsong`，用户名 `sa`，密码为空。

更详细的接口和数据库设计见 `docs/API_SPEC.md`、`docs/DATABASE.md` 和 `docs/TECH_STACK.md`。

## 客户 144 商品接口

关键词搜索会由后端访问客户 144 只读接口，API Key 不会发送给浏览器。密钥保存在已被 Git 忽略的 `server/config/application-secrets.yml`，生产环境建议通过 `CUSTOMER144_API_KEY` 环境变量注入。

外部接口没有关键词参数，因此后端会按接口规范分页维护 H2/PostgreSQL 只读商品快照表，并在每次用户搜索时调用远端第一页刷新最新数据。远端有关键词匹配时展示远端商品；远端无数据、不可用或没有匹配时继续使用原有本地商品数据。远端文本字段为空时映射为 `-`，价格为空时前端显示 `-`。

可配置项：

```text
CUSTOMER144_API_ENABLED=true
CUSTOMER144_API_BASE_URL=https://gift.singsong.cn/api/customer144
CUSTOMER144_API_KEY=通过安全渠道提供的密钥
```