FloorVisualizer
AI 换地板可视化后端服务 —— 上传房间照片，AI 自动识别地面区域并生成换地板效果图。
技术栈
- 语言: Go 1.23+
- 数据库: PostgreSQL 15
- 缓存/队列: Redis 7
- AI: OpenRouter API (Gemini 3 Pro / Flash)
- 部署: Docker Compose
快速开始
本地开发
# 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。
生产部署
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_idGET /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 天前的日志
