三松项目库

CRK d85ad36b06 Optimize paginated product search		2 weeks ago
client	8cc8001d72 Initial project import	2 weeks ago
deploy	8cc8001d72 Initial project import	2 weeks ago
docs	8cc8001d72 Initial project import	2 weeks ago
server	d85ad36b06 Optimize paginated product search	2 weeks ago
.env.example	8cc8001d72 Initial project import	2 weeks ago
.gitignore	8cc8001d72 Initial project import	2 weeks ago
README.md	8cc8001d72 Initial project import	2 weeks ago
package.json	8cc8001d72 Initial project import	2 weeks ago
pnpm-workspace.yaml	8cc8001d72 Initial project import	2 weeks ago
pom.xml	8cc8001d72 Initial project import	2 weeks ago

三松礼品产品库

一个可直接使用 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 打开

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

启动后端：

mvn -pl server spring-boot:run

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

npm --prefix client install
npm --prefix client run dev

构建与测试

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

目录结构

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 只读商品快照表，并在每次用户搜索时调用远端第一页刷新最新数据。远端有关键词匹配时展示远端商品；远端无数据、不可用或没有匹配时继续使用原有本地商品数据。远端文本字段为空时映射为 -，价格为空时前端显示 -。

可配置项：

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

README.md