94895cbc22
- Go API server with PostgreSQL + Redis - AI floor replacement (OpenRouter Gemini) - Product database (10 brands, 3539 products) - Recommendation engine, calculator, articles - Redis async queue + worker pool - Hot product caching, brand view tracking - JWT auth, favorites, projects - Docker deployment ready Co-Authored-By: Claude <noreply@anthropic.com>
177 lines
5.6 KiB
Markdown
177 lines
5.6 KiB
Markdown
# FloorVisualizer
|
||
|
||
AI 换地板可视化后端服务 —— 上传房间照片，AI 自动识别地面区域并生成换地板效果图。
|
||
|
||
## 技术栈
|
||
|
||
- **语言**: Go 1.23+
|
||
- **数据库**: PostgreSQL 15
|
||
- **缓存/队列**: Redis 7
|
||
- **AI**: OpenRouter API (Gemini 3 Pro / Flash)
|
||
- **部署**: Docker Compose
|
||
|
||
## 快速开始
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 1. 起依赖（仅 DB + Redis）
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
|
||
# 2. 导入产品数据
|
||
go run cmd/import/main.go
|
||
|
||
# 3. 启动服务
|
||
go run main.go
|
||
```
|
||
|
||
服务默认运行在 `http://localhost:8099`。
|
||
|
||
### 生产部署
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── main.go # 入口
|
||
├── cmd/
|
||
│ ├── import/main.go # 产品数据导入
|
||
│ ├── import_articles/main.go # 科普文章导入
|
||
│ └── scrape_logos/main.py # 品牌 Logo 刮取
|
||
├── internal/
|
||
│ ├── handler/ # HTTP 处理器
|
||
│ │ ├── router.go # 路由注册
|
||
│ │ ├── product_handler.go # 产品列表/详情
|
||
│ │ ├── floor_handler.go # AI 换地板
|
||
│ │ ├── auth_handler.go # 注册/登录
|
||
│ │ ├── user_handler.go # 用户/收藏/项目/头像
|
||
│ │ ├── recommend_handler.go # 智能推荐
|
||
│ │ ├── calc_handler.go # 面积计算
|
||
│ │ ├── article_handler.go # 科普文章
|
||
│ │ ├── upload_handler.go # 图片上传
|
||
│ │ └── health_handler.go # 健康检查
|
||
│ ├── model/ # 数据模型
|
||
│ ├── repository/ # 数据库操作
|
||
│ ├── service/ # 业务逻辑（推荐算法）
|
||
│ ├── middleware/ # 中间件（JWT、日志、访问记录）
|
||
│ ├── queue/ # Redis 队列（异步任务）
|
||
│ ├── openrouter/ # OpenRouter API 客户端
|
||
│ └── logger/ # 分级日志
|
||
├── data/products/ # 产品 JSON 数据（3539 条）
|
||
├── data/articles.json # 科普文章（30 篇）
|
||
├── knowledge_images/ # 文章图片
|
||
├── Dockerfile
|
||
├── docker-compose.yml # 生产部署
|
||
├── docker-compose.dev.yml # 本地开发
|
||
└── apifox-import.json # API 文档
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
### 服务配置
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PORT` | `8099` | HTTP 端口 |
|
||
| `DATABASE_URL` | `postgres://postgres:dev123456@localhost:5432/floorvisualizer?sslmode=disable` | 数据库连接 |
|
||
| `REDIS_ADDR` | `localhost:6379` | Redis 地址 |
|
||
| `JWT_SECRET` | 内置默认值 | JWT 签名密钥（生产务必修改） |
|
||
| `OPENROUTER_API_KEY` | 内置默认值 | OpenRouter API Key |
|
||
| `PROXY_URL` | `127.0.0.1:7897` | HTTP 代理（留空禁用） |
|
||
| `DISABLE_PROXY` | — | 设为 `true` 强制禁用代理 |
|
||
|
||
### 队列
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `WORKER_COUNT` | `5` | AI 生成并发 worker 数（1-20） |
|
||
|
||
### 日志
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `LOG_DIR` | `logs` | 日志目录 |
|
||
| `LOG_LEVEL` | `INFO` | 日志级别：DEBUG / INFO / WARN / ERROR |
|
||
|
||
## API 总览
|
||
|
||
所有接口统一返回 `{"code": 200, "data": {...}}` 信封格式。
|
||
|
||
### 认证
|
||
- `POST /auth/register` — 注册
|
||
- `POST /auth/login` — 登录
|
||
|
||
### 产品（公开）
|
||
- `GET /products` — 列表（多维度筛选+搜索+分页）
|
||
- `GET /products/{sku}` — 详情（含规格 specs、收藏状态）
|
||
- `GET /product-options` — 筛选选项（含品牌 logo、款式数、合集数）
|
||
|
||
### 推荐（公开）
|
||
- `GET /recommend/api?sku=xxx` — 跨品牌相似推荐
|
||
|
||
### 地板更换
|
||
- `GET /floor/options` — 地板样式+铺设方式+房间类型
|
||
- `POST /floor/generate` — 提交 AI 生成任务 → 返回 `job_id`
|
||
- `GET /floor/status?job_id=xxx` — 查询任务进度
|
||
|
||
### 用户（需 JWT）
|
||
- `GET /user/me` / `PUT /user/me` — 个人信息
|
||
- `POST /user/avatar` — 上传头像
|
||
- `GET /user/favorites` / `POST` / `DELETE` — 收藏管理
|
||
- `GET /user/projects` / `POST` / `PUT` / `DELETE` — 项目（生成记录）
|
||
- `GET /user/frequent-brands` — 常用品牌（浏览≥3 或 收藏≥2）
|
||
|
||
### 计算器
|
||
- `POST /calculator/calc` — 多房间面积+损耗+费用计算
|
||
|
||
### 文章（公开）
|
||
- `GET /articles` — 科普文章列表
|
||
- `GET /articles/{id}` — 文章详情
|
||
- `GET /articles/recommend` — 随机推荐
|
||
|
||
### 其他
|
||
- `POST /upload` — 通用图片上传
|
||
- `GET /healthz` — 健康检查
|
||
|
||
## 数字编码
|
||
|
||
### 铺设方式 (pattern_code)
|
||
| Code | 木地板 | 瓷砖 |
|
||
|------|--------|------|
|
||
| 1 | Straight Lay | — |
|
||
| 2 | Horizontal Lay | — |
|
||
| 3 | Herringbone | — |
|
||
| 4 | Chevron | — |
|
||
| 5 | — | Straight Grid |
|
||
| 6 | — | Running Bond |
|
||
| 7 | — | 1/3 Offset |
|
||
| 8 | — | Hexagonal |
|
||
| 9 | — | Diagonal (45°) |
|
||
|
||
### 房间类型 (room_code)
|
||
| Code | 房间 |
|
||
|------|------|
|
||
| 0 | Auto Detect |
|
||
| 1 | Living Room |
|
||
| 2 | Bedroom |
|
||
| 3 | Kitchen |
|
||
| 4 | Dining Room |
|
||
| 5 | Bathroom |
|
||
| 6 | Study Room |
|
||
| 7 | Hallway |
|
||
|
||
## 产品数据
|
||
|
||
10 个品牌，3539 条产品，涵盖 Hardwood / Engineered Wood / Laminate / SPC/LVP / Wood-Look Tile 五大品类。
|
||
|
||
数据存储在 `data/products/*.json`，首次使用需运行 `go run cmd/import/main.go` 导入 PostgreSQL。
|
||
|
||
## 日志
|
||
|
||
- **格式**: `2026-07-10 16:30:01 [INFO] main.go:96 Server started`
|
||
- **存储**: `logs/app-YYYY-MM-DD.log`，每天一个文件
|
||
- **清理**: 自动删除 30 天前的日志
|