FloorVisualizer/README.md

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_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 天前的日志