ClothHub 家庭衣橱 & 穿搭模拟

一个运行在浏览器中的家庭衣橱管理与穿搭模拟工具，支持多终端通过网络访问，同步使用同一套衣物 / 套装 / 头像数据。前端基于 React + TypeScript + Vite，后端基于 Node.js + Express + SQLite，图片保存为本地文件，适合部署在树莓派 4B 等低功耗设备上长期运行。

---

项目结构

• clothhub-ui/：前端 Web 应用（React + TS + Vite）
  • 衣物管理（增删改查、分类、季节、标签、备注、图片上传）
  • 穿搭画布（拖拽衣物到人物画布、移动位置、缩放、旋转、调整图层顺序、删除当前衣物）
  • 头像管理（上传头像、选择头像，头像与套装关联）
  • 套装管理（保存 / 加载 / 删除套装）
  • 画布草稿：使用浏览器 localStorage 暂存当前画布状态（当前头像 + 衣物摆放），刷新后可继续编辑
• clothhub-server/：后端 API 服务（Express + SQLite）
  • SQLite 单文件数据库：data/clothhub.db
  • 图片文件：data/uploads/avatars, data/uploads/clothes
  • 提供衣物 / 套装 / 头像的 REST API，前端不再使用 localStorage 持久化数据
• package.json（根目录）：Monorepo 管理脚本（一次启动前后端、统一构建等）

---

开发环境启动（推荐用一条命令）

根目录脚本已经配置，可以在 d:\workspace\clothHub 只执行一个命令，同时启动后端和前端开发服务器。

cd d:\workspace\clothHub
npm install           # 第一次克隆项目后执行一次即可
npm run dev           # 同时启动 clothhub-server 和 clothhub-ui

等价于并行执行：

• cd clothhub-server && npm run dev（后端，默认端口 3001）
• cd clothhub-ui && npm run dev（前端，默认端口 5173）

启动完成后：

• 在浏览器访问前端：http://localhost:5173/
• 前端通过 Vite 代理访问后端：
  • /api/* → http://localhost:3001/api/*
  • /uploads/* → http://localhost:3001/uploads/*

如需单独启动某一侧：

• 只跑后端：npm run dev:server
• 只跑前端：npm run dev:ui

---

根目录脚本一览

根 package.json 中定义的脚本：

• npm run dev：并行启动前端和后端开发服务器。
• npm run dev:server：仅启动后端 clothhub-server 的 npm run dev。
• npm run dev:ui：仅启动前端 clothhub-ui 的 npm run dev。
• npm run build：依次执行：
  • npm run build:server → 在 clothhub-server 中运行 npm run build（编译 TypeScript，生成 dist）
  • npm run build:ui → 在 clothhub-ui 中运行 npm run build（编译 TS 并构建前端静态资源）
• npm run build:server：只构建后端。
• npm run build:ui：只构建前端。
• npm run start:server：在 clothhub-server 中执行 npm start（使用已构建好的 dist，适合生产 / 树莓派部署）。

前端开发仍然使用 Vite 自带的 HMR（热更新），不需要单独构建；后端开发使用 ts-node-dev 自动重启。

---

前端功能概览（clothhub-ui）

• 衣物管理

  • 支持类别：上衣 / 裤子 / 鞋子 / 帽子
  • 属性：名称、颜色、适用季节（春夏秋冬）、风格标签、备注、图片（base64 上传后由后端转为文件）、创建/更新时间
  • 支持按类别、季节、关键字（名称 / 颜色 / 标签 / 备注）过滤

• 头像管理

  • 上传头像图片，并保存在后端文件系统中（前端以 URL 引用）
  • 从下拉框选择当前使用的头像
  • 头像与套装之间可以关联：保存套装时记录 avatarId，加载套装时还原对应头像

• 穿搭画布

  • 左侧列表展示所有衣物，可「点击」或「拖拽」到右侧人物画布
  • 在画布中拖动衣物改变位置（基于相对坐标 x/y）
  • 选中控制（右侧控制板）：
    • 点击衣物图片即可选中，出现高亮描边
    • 右侧控制板显示「选中衣物调整」：
      • 缩放：滑块控制 scale（默认 1，支持放大/缩小）
      • 旋转：滑块控制 rotation（单位度数）
      • 图层顺序：按钮「置于最上层」提升 zIndex
      • 删除当前衣物：从画布中移除当前选中的衣物
    • 点击画布空白区域可取消选中
  • 底部支持将当前画布保存为「套装」或清空画布

• 套装管理

  • 将当前画布状态（头像 + 所有衣物的位置/缩放/旋转/层级）保存为套装
  • 套装列表显示名称、更新时间、单品数量
  • 载入套装会还原画布中的所有衣物摆放以及头像
  • 支持删除套装

• 画布草稿（本地）

  • 使用浏览器 localStorage 保存当前画布未保存状态（currentAvatarId / currentOutfitId / currentOutfitItems）
  • 刷新页面或误操作关闭后重新打开，可恢复上次编辑到一半的画布
  • 不会影响多终端共享的数据（只影响当前浏览器的编辑体验）

---

后端功能概览（clothhub-server）

详见 clothhub-server/README.md，核心要点：

• 技术栈

  • Node.js + Express
  • SQLite 数据库存储结构化数据（衣物 / 套装 / 头像）
  • 本地文件系统保存图片，数据库中只存图片路径

• 主要表结构

  • clothes：衣物基本信息 + 关联图片路径
  • avatars：头像基本信息 + 图片路径
  • outfits：套装基本信息（名称、描述、关联头像等）
  • outfit_items：套装中每件衣物的在画布上的位置 / 缩放 / 旋转 / 图层

• 主要 API（REST）

  • GET/POST /api/clothes，PUT/DELETE /api/clothes/:id
  • GET/POST /api/avatars，DELETE /api/avatars/:id
  • GET/POST /api/outfits，PUT/DELETE /api/outfits/:id
  • 静态图片：GET /uploads/avatars/...、GET /uploads/clothes/...

---

部署到树莓派 4B 的建议流程（简版）

1. 在树莓派上安装 Node.js（推荐 LTS 版本，如 18/20）。

2. 将本仓库拷贝到树莓派（git clone 或 scp）。

3. 在树莓派上执行（根目录）：

   cd clothHub
   npm install
   cd clothhub-server && npm install
   cd ../clothhub-ui && npm install
   cd ..
   
   npm run build           # 构建前后端
   npm run start:server    # 启动后端 API

4. 前端构建结果（clothhub-ui/dist）可以：

   • 交给 Nginx/静态服务器托管，或
   • 使用如 serve 之类的工具在树莓派上开启静态服务。

5. 构建前如需固定 API 地址，可在前端构建时设置：

   cd clothhub-ui
   VITE_API_URL=http://树莓派IP:3001 npm run build

   这样多台设备通过浏览器访问树莓派 IP，即可共享同一套衣橱与穿搭数据。

---

后续可扩展方向（备忘）

• 多用户账号 / 权限（不同家庭成员拥有独立衣橱） - 画布多草稿 / 历史版本管理
• 导出套装为图片分享
• 更丰富的图层操作（上移一层 / 下移一层 / 对齐 / 吸附等）

带删除线的条目表示曾经讨论过但目前暂不优先实现或已经被其他设计替代。未来可以按需要逐步扩展。