# clothes-manager

**Repository Path**: Baisux/clothes-manager

## Basic Information

- **Project Name**: clothes-manager
- **Description**: 个人衣物管理 - H5 小程序
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人衣物管理 - H5 小程序

## 快速开始

```bash
npm install
npm run dev      # 开发模式，访问 http://localhost:3000
npm run build    # 构建生产版本
npm run preview  # 预览生产版本
```

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | React 19 + TypeScript 6 |
| 构建 | Vite 8 + vite-plugin-pwa |
| 路由 | react-router-dom v7 |
| 存储 | Supabase PostgreSQL + Supabase Storage（图片） |
| 样式 | 纯 CSS + CSS Variables |

## 项目结构

```
clothes-manager/
├── docs/
│   ├── PRD.md                      # 产品需求文档
│   ├── supabase.md                 # Supabase 配置与建表说明
│   └── hbuilderx-package-guide.md  # HBuilderX 打包指南
├── public/
│   └── favicon.svg                 # 站点图标
├── src/
│   ├── main.tsx                    # 应用入口
│   ├── App.tsx                     # 路由配置
│   ├── types/
│   │   └── index.ts               # 所有 TypeScript 类型定义
│   ├── services/
│   │   ├── supabase.ts            # Supabase 客户端初始化（支持运行时配置）
│   │   ├── db.ts                  # 数据库封装（Supabase Client）
│   │   ├── clothesService.ts      # 衣物 CRUD 操作
│   │   ├── washService.ts         # 清洗批次 CRUD 操作
│   │   ├── dictionaryService.ts   # 字典数据 CRUD 操作
│   │   ├── outfitService.ts       # 穿搭记录/套装 CRUD 操作
│   │   ├── weatherService.ts      # 天气数据获取（wttr.in + IP 定位）
│   │   ├── exportService.ts       # 数据导入导出（JSON/CSV/ZIP + 策略选择）
│   │   └── imageService.ts        # 图片压缩 + Supabase Storage 上传/删除
│   ├── hooks/
│   │   ├── useClothes.ts          # 衣物数据 hooks
│   │   ├── useWash.ts             # 清洗数据 hooks
│   │   ├── useOutfit.ts           # 穿搭记录 hooks
│   │   ├── useOutfitSet.ts        # 搭配套装 hooks
│   │   ├── useOnlineStatus.ts     # 网络在线/离线状态
│   │   └── useSyncStatus.ts      # 同步时间状态
│   ├── contexts/
│   │   ├── DictionaryContext.tsx   # 字典全局上下文
│   │   └── WeatherContext.tsx     # 天气全局上下文
│   ├── utils/
│   │   ├── constants.ts           # 默认枚举常量 + WASH_LIFE_LIMITS + DISCARD_REASONS
│   │   ├── dateUtils.ts           # 日期格式化工具
│   │   ├── id.ts                  # UUID 生成
│   │   ├── validators.ts          # 表单校验
│   │   ├── recommendations.ts     # 穿搭推荐算法
│   │   └── zip.ts                 # ZIP 打包/解压工具（jszip）
│   ├── components/
│   │   ├── Layout/                # 底部 Tab 导航布局 + InstallPrompt
│   │   ├── Icon/                  # 统一 SVG 图标组件（30+ 图标，currentColor 适配）
│   │   ├── ClothCard/             # 衣物卡片
│   │   ├── FilterBar/             # 搜索 + 筛选栏
│   │   ├── WashBatchCard/         # 清洗批次卡片
│   │   ├── ImageCrop/             # 图片裁剪（Canvas 矩形框选）
│   │   ├── EmptyState/            # 空状态占位
│   │   ├── InstallPrompt/         # PWA 安装提示横幅
│   │   ├── ExportMenu/            # 导出选项弹窗（JSON/CSV/ZIP）
│   │   └── ImportWizard/          # 导入多步向导
│   ├── pages/
│   │   ├── Home/                  # 首页（天气卡片/统计/提醒/快捷操作/最近记录）
│   │   ├── ClothesList/           # 衣物列表（筛选/搜索）
│   │   ├── ClothesDetail/         # 衣物详情（生命周期进度条/淘汰信息/清洗时间线）
│   │   ├── ClothesForm/           # 衣物添加/编辑表单（含淘汰信息/裁剪上传/删除确认）
│   │   ├── Outfits/               # 穿搭主页（天气/推荐/记录列表）
│   │   ├── OutfitForm/            # 穿搭记录/编辑表单
│   │   ├── OutfitSets/            # 搭配套装列表
│   │   ├── OutfitSetForm/         # 搭配套装表单
│   │   ├── OutfitCalendar/        # 穿搭日历
│   │   ├── WashList/              # 清洗记录列表
│   │   ├── WashForm/              # 创建洗衣批次
│   │   ├── Stats/                 # 数据统计看板（含清洗寿命提醒）
│   │   ├── Settings/              # 字典管理
│   │   ├── Reminders/             # 提醒设置
│   │   ├── SupabaseConfig/        # Supabase 连接配置（运行时修改）
│   │   ├── Mine/                  # 我的（入口页）
│   │   └── Migrate/               # 图片迁移工具
│   └── styles/
│       ├── variables.css           # CSS 变量（主题色）
│       └── global.css             # 全局样式重置
├── index.html
├── package.json
├── vite.config.ts
└── tsconfig.json
```

## 路由表

| 路径 | 页面 | 说明 |
|------|------|------|
| `/` | Home | 首页概览 |
| `/clothes` | ClothesList | 衣物列表 |
| `/clothes/new` | ClothesForm | 添加衣物 |
| `/clothes/:id` | ClothesDetail | 衣物详情 |
| `/clothes/:id/edit` | ClothesForm | 编辑衣物 |
| `/wash` | WashList | 清洗记录列表 |
| `/wash/new` | WashForm | 创建洗衣批次 |
| `/mine` | Mine | 我的（入口：字典管理/统计看板/提醒设置/图片迁移/Supabase配置/导出导入） |
| `/stats` | Stats | 数据统计看板 |
| `/settings` | Settings | 字典管理 |
| `/reminders` | Reminders | 提醒设置 |
| `/supabase-config` | SupabaseConfig | Supabase 连接配置（运行时修改） |
| `/outfits` | Outfits | 穿搭记录 |
| `/outfits/new` | OutfitForm | 记录穿搭 |
| `/outfits/:id/edit` | OutfitForm | 编辑穿搭 |
| `/outfit-sets` | OutfitSets | 搭配套装列表 |
| `/outfit-sets/new` | OutfitSetForm | 新建套装 |
| `/outfit-calendar` | OutfitCalendar | 穿搭日历 |
| `/migrate` | Migrate | 图片迁移（一次性工具） |

## 数据流

```
用户操作 → Page 组件 → Custom Hook → Service 函数 → Supabase PostgreSQL
                                         ↓
                                   刷新 state → 重新渲染
```

数据库使用 Supabase PostgreSQL，包含五个表：
- `clothes` — 衣物数据（含生命周期字段：淘汰/转卖日期、原因、转卖价格）
- `washBatches` — 洗衣批次数据
- `outfits` — 穿搭记录数据
- `outfitSets` — 搭配套装数据
- `dictionaries` — 字典数据（品类/材质/颜色等可配置选项 + 提醒设置）

## 环境变量

复制 `.env.example` 为 `.env`，填入 Supabase 项目凭证：

```env
VITE_SUPABASE_URL=https://xxxxxxxxxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJxxxxxxxxxxxxxx
```

也可在应用内「我的 → Supabase 配置」页面运行时修改，保存后自动刷新生效。优先级：App 内设置 > 环境变量（仅开发环境）。

**注意**：生产构建不会包含 `.env` 信息，用户需要手动配置 Supabase 连接。

详细 Supabase 使用说明见 [docs/supabase.md](docs/supabase.md)。

## 设计风格

- 主色调 `#5B8C5A`（鼠尾草绿），主色渐变 `#5B8C5A → #7aa879`
- 辅助色 `#d64545`（暖红，用于警告/删除）、`#e6a700`（提醒）、`#4a90d9`（信息）
- 最大宽度 430px，居中布局，移动端适配
- 底部五 Tab 导航：首页 / 衣物 / 穿搭 / 清洗 / 我的（固定定位 + 毛玻璃 + 激活态指示条）
- 全 SVG 图标系统，跨浏览器/PWA 渲染一致
- 设计 Token 体系：颜色/阴影/间距/字体/圆角/动画时长全部 CSS Variable 化

## 当前进度

| 阶段 | 状态 | 说明 |
|------|------|------|
| V1.0 核心功能 | ✅ 已完成 | 衣物 CRUD、清洗管理、首页概览 |
| 🔄 Supabase 迁移 | ✅ 已完成 | 方案一 Supabase PostgreSQL，支持多设备数据共享 |
| V1.1 数据统计看板 | ✅ 已完成 | 数据统计看板、字典管理、图片迁移至 Supabase Storage |
| V1.2 穿搭模块 | ✅ 已完成 | 穿搭记录、搭配套装、穿搭日历、天气联动推荐 |
| V1.2.1 | ✅ 已完成 | "我的"入口页、首页快捷入口优化、最近添加图片固定尺寸 |
| V1.2.2 | ✅ 已完成 | 存放位置字典化（chip 选择 + 列表筛选 + 字典管理） |
| V1.2.3 | ✅ 已完成 | 首页"久未清洗"提醒新增可展开详情：穿搭次数、最后穿搭时间、上次清洗时间 |
| V1.2.4 | ✅ 已完成 | 图片裁剪上传（自由矩形框选 + 使用原图 + 逐张裁剪） |
| V1.3.0 智能提醒 | ✅ 已完成 | 提醒阈值可配置、穿搭次数清洗提醒、提醒设置页 |
| V1.3.2 穿搭编辑 | ✅ 已完成 | 穿搭记录可编辑回填、编辑入口、穿着次数修正、日期预填 |
| V1.3.1 生命周期 | ✅ 已完成 | 衣物状态扩展、淘汰/转卖记录、清洗寿命追踪、实际使用成本 |
| V1.4 数据管理 | ✅ 已完成 | 导入导出增强（CSV/ZIP/预览/策略）、PWA（App Shell 缓存/安装提示）、多设备同步 UI |
| V1.4.1 安全增强 | ✅ 已完成 | 移除构建产物中的环境变量、生产环境强制手动配置、路由守卫自动跳转 |
| V1.4.2 Bug 修复 | ✅ 已完成 | 修复 washBatches 表缺少 duration 列导致的 PGRST204 错误；修复 formatDateRelative 时区问题导致"今天"显示"-1天前" |
| V1.5.0 UI 设计升级 | ✅ 已完成 | 全 SVG 图标系统替代 emoji（解决跨浏览器/PWA 显示不一致）、设计 Token 体系（颜色/阴影/间距/字体/动画）、Home/Layout/Mine 等核心页面视觉重构；**补充**：清理全部业务页面遗留 emoji（衣物分类 8 项、UI 控件 ✕ ✓ ✅ ⬜ 等共 21 处），新增 9 个 Icon 类型 |

## 待开发功能

按 PRD 文档 §8 未来扩展方向规划：

- **V2.0**: AI 照片归类、胶囊衣橱、深色模式

## 已完成功能

### V1.0 核心功能
- [x] 衣物 CRUD（名称/图片/品类/品牌/价格/材质/颜色/尺码/季节/厚度/存放位置/洗涤要求/状态）
- [x] 衣物列表（品类/季节/状态筛选 + 关键词搜索）
- [x] 衣物详情（信息展示 + 清洗历史时间线）
- [x] 洗衣批次管理（多选衣物/日期/方式/水温/柔顺剂/烘干/备注）
- [x] 首页概览（衣物统计/总价值/快捷操作/最近清洗/最近添加）
- [x] 图片上传（多图，自动压缩为 WebP + Supabase Storage 对象存储，向后兼容旧 base64 数据）
- [x] Supabase PostgreSQL 持久化存储（方案一迁移完成）
- [x] 局域网多设备访问兼容（UUID 生成兜底 + 错误提示）

### V1.1 增强体验
- [x] 数据统计看板（资产概览/品类分布/季节分布/颜色分布/清洗频次/消费排行）
- [x] 字典管理（品类/材质/颜色/季节/厚度/洗涤要求/清洗方式，存储于 Supabase dictionaries 表）
- [x] 动态字典全局上下文（DictionaryContext），修改实时同步所有页面
- [x] 图片迁移至 Supabase Storage（自动压缩为 WebP，单张 50-150KB，向后兼容旧 base64 数据）

### V1.2 穿搭模块
- [x] 穿搭记录（每日穿搭记录，支持多选衣物/场景标签/天气快照/穿搭照片）
- [x] 搭配套装管理（创建/编辑/删除套装，设置适用季节/温度范围/场景）
- [x] 穿搭日历（月度日历视图，点击日期查看当日穿搭详情）
- [x] 天气联动（IP 定位获取天气，首页天气卡片，基于天气推荐套装）
- [x] 一键穿搭（从推荐套装一键记录为当日穿搭）

### V1.2.1 体验优化
- [x] "我的"入口页（统计摘要/字典管理/统计看板/图片迁移入口）
- [x] 首页快捷操作优化（移除字典管理入口，新增记录穿搭入口）
- [x] 首页最近添加图片固定 76×76 尺寸，横向滚动显示

### V1.2.2 存放位置字典化
- [x] 存放位置纳入字典管理（Settings 页面可增删排序）
- [x] 衣物表单存放位置改为 chip 快捷选择 + 自定义输入
- [x] 衣物列表新增存放位置筛选下拉框

### V1.2.4 图片裁剪上传
- [x] ImageCrop 裁剪组件（Canvas 绘制 + Pointer Events 交互，自由矩形框选/移动/调整大小）
- [x] imageService 新增 cropImage、uploadBlob 函数
- [x] 衣物表单集成裁剪流程（选图 → 裁剪 → 上传，逐张处理；支持"使用原图"跳过裁剪）
- [x] 裁剪界面自适应容器尺寸（ResizeObserver），动态光标反馈，防误触处理

### V1.3.0 智能提醒
- [x] 提醒阈值可配置（闲置天数/久未清洗天数/穿搭次数，存 Supabase dictionaries 表）
- [x] 穿搭次数清洗提醒（穿搭 N 次后未清洗自动提醒）
- [x] 提醒设置页（/reminders，支持自定义阈值和恢复默认）
- [x] 首页提醒改造（三类提醒分区展示，阈值从配置读取）
- [x] "我的"页新增提醒设置入口

### V1.3.2 穿搭编辑
- [x] 编辑模式表单回填已有穿搭数据（日期/场景/衣物/照片/备注/天气）
- [x] 穿搭列表/今日穿搭/日历详情添加点击编辑入口
- [x] 编辑保存时仅对新增衣物增加穿着次数（修复重复计算）
- [x] 支持 ?date= 查询参数预填日期（日历"记录"按钮生效）
- [x] 编辑模式标题显示"编辑穿搭"

### V1.3.1 生命周期
- [x] 衣物状态扩展：新增"已捐赠/转卖"状态（donated）
- [x] 淘汰/转卖记录：日期、原因（磨损/过时/不合身/不喜欢/其他）、转卖价格
- [x] 清洗寿命追踪：基于材质建议清洗次数上限，详情页进度条展示，接近/达到上限告警
- [x] 实际使用成本计算：(购买价格 - 转卖价格) / 穿着次数
- [x] 统计看板新增清洗寿命提醒 TOP 10、已捐赠/转卖计数
- [x] 筛选栏新增"已捐赠/转卖"状态选项

### V1.4 数据管理
- [x] PWA 支持（manifest + vite-plugin-pwa + App Shell 缓存 + 安装提示横幅）
- [x] 多设备同步 UI（同步状态栏、手动刷新、在线/离线状态提示、页面焦点自动刷新）
- [x] CSV 导出（衣物列表电子表格格式，BOM 头兼容 Excel）
- [x] ZIP 导出（JSON 数据 + 衣物图片打包备份）
- [x] 导入增强（多步向导：选文件 → 预览 → 策略选择 → 确认）
- [x] 导入策略（合并/追加/覆盖三种模式）
- [x] Supabase 运行时配置（App 内设置页修改 URL/Key，无需重新构建）
- [x] HBuilderX APK 打包支持（相对路径 base、打包指南）

### V1.4.1 安全增强
- [x] 移除构建产物中的环境变量信息（生产构建时替换为空字符串）
- [x] 开发环境优先使用 `.env`，生产环境强制手动配置
- [x] 路由守卫：未配置时自动跳转到 `/supabase-config` 页面
- [x] 配置页面增强：添加输入验证、格式检查、提示信息

### V1.5.0 UI 设计升级
- [x] **统一 SVG 图标系统**（`src/components/Icon/`，30+ 图标），彻底替换 emoji
  - 解决不同浏览器/系统 emoji 渲染不一致问题
  - 解决 PWA 打包后部分 emoji 显示为方框
  - 支持 `currentColor` 主题适配、自定义大小
- [x] **设计 Token 体系**（`src/styles/variables.css`）
  - 颜色：主色渐变、警告/信息/危险色阶
  - 阴影层级：sm/md/lg/xl 四档
  - 间距系统：xs-3xl 七档
  - 字体变量：font-sans / font-display
  - 圆角与过渡时长统一
- [x] **核心页面视觉重构**
  - Home：统计卡片悬停动效、staggered 进场动画、提醒卡片层次优化
  - Layout：底部 Tab 改为固定定位 + 毛玻璃 + 激活态指示条
  - Mine：头部高光渐变、悬浮胶囊式同步状态栏（脉冲动画 + 圆角刷新按钮）
  - WashBatchCard / 通用按钮 / EmptyState 等组件统一样式
- [x] 全局动画工具类（fadeIn / slideUp / scaleIn / pulse）
- [x] **补充清理（v1.5.0 后续）**：彻底替换业务页面残留 emoji，统一走 Icon 组件
  - 衣物分类（8 项）：`CATEGORY_ICONS` 由 emoji 字符串改为 `IconName` 映射，新增 `shirt/pants/dress/coat/underwear/bag/shoes/tshirt` 8 个图标，影响 ClothCard、ClothesDetail、Outfits、OutfitSets、OutfitCalendar、Stats
  - UI 控件：所有关闭/移除按钮 `✕` → `<Icon name="close" />`（FilterBar、ExportMenu、ImportWizard、OutfitForm、OutfitSetForm、ClothesForm、Settings、ImageCrop）
  - 勾选状态：`✓` `✅` → `<Icon name="check" />`、`⬜` → `<Icon name="square" />`（OutfitForm、OutfitSetForm、WashForm、ImportWizard）
  - 保留：天气 emoji（`weatherService.getWeatherIcon` 彩色显示效果好）、Migrate 调试日志中的 ✅ ❌（纯文本日志非 UI）
- [x] **图标优化（v1.5.0 补充）**：优化 4 个语义不清的图标设计
  - `clothes`：原衬衫形状与 `shirt` 重复 → 改为衣柜/抽屉形状（带分隔线）
  - `outfit`：原不直观的矩形组合 → 改为衣架挂衣服形状（顶部挂钩）
  - `empty`：原衣服形状 → 改为空盒子形状（中间横线）
  - `dry`：原盾牌形状 → 改为三条风曲线（表示吹干/风干）

## 后续开发指引

1. **新增页面**：在 `src/pages/` 下创建新目录，参考现有页面结构
2. **新增数据表**：在 Supabase SQL Editor 中创建新表，并在 `src/services/` 下创建对应的 Service
3. **新增路由**：在 `src/App.tsx` 中添加 Route
4. **样式变量**：全局 CSS 变量定义在 `src/styles/variables.css`
5. **常量**：品类/季节等枚举默认值在 `src/utils/constants.ts`，可通过字典管理页面动态修改