---
name: zt-closet-wxmini 前端实现
overview: 基于 stitch_ai_ui 的 14 个高保真页面原型与 zt-closet-backend 的 42 个接口，在现有微信小程序骨架（TypeScript + skyline + glass-easel）上，完整实现「纸条AI衣橱」小程序：网络层、鉴权、5 个 tabBar 页与 8 个二级页，全部接通后端接口。
design:
  styleKeywords:
    - iOS HIG
    - 清爽克制
    - 毛玻璃
    - 发丝分隔线
    - 系统蓝
    - SF Symbols 线性图标
  fontSystem:
    fontFamily: PingFang SC
    heading:
      size: 34px
      weight: 700
    subheading:
      size: 17px
      weight: 600
    body:
      size: 15px
      weight: 400
  colorSystem:
    primary:
      - "#007AFF"
      - "#5856D6"
      - "#FF2D55"
    background:
      - "#F2F2F7"
      - "#FFFFFF"
    text:
      - "#000000"
      - "#8E8E93"
      - "#C7C7CC"
    functional:
      - "#34C759"
      - "#FF9500"
      - "#FF3B30"
      - "#FFCC00"
todos:
  - id: network-foundation
    content: 搭建 request/token 刷新与全局配置、工具函数
    status: completed
  - id: tabbar-components
    content: 实现自定义 tabBar 与空态、骨架屏、衣物卡片等公共组件
    status: completed
    dependencies:
      - network-foundation
  - id: clothes-flow
    content: 实现登录、衣橱、上传、衣物详情页
    status: completed
    dependencies:
      - tabbar-components
  - id: outfit-flow
    content: 实现穿搭、穿搭详情、创建编辑穿搭页
    status: completed
    dependencies:
      - tabbar-components
  - id: ai-horoscope
    content: 实现 AI 推荐与运势页
    status: completed
    dependencies:
      - tabbar-components
  - id: notice-profile-share
    content: 实现通知、我的、衣柜分享（列表/创建/详情）页
    status: completed
    dependencies:
      - tabbar-components
  - id: mall-order
    content: 实现商城与订单支付退款页
    status: completed
    dependencies:
      - tabbar-components
---

## 产品概述

「纸条AI衣橱」微信小程序：用户拍照上传衣物，AI 自动抠图并识别 15 项属性，自由组合衣物创建穿搭、生成 AI 穿搭推荐（结合星座运势）、把衣橱或精选衣物分享给好友、在社区公开穿搭并互动，还可购买会员或额度包解锁更多次数。产品气质为清爽、克制、可信赖的私人衣橱助手。

## 核心功能

- 微信授权登录：`wx.login` 换 token，首次登录自动注册并发放免费额度
- 衣橱管理：两列衣物网格、分类筛选、上传衣物（异步 AI 处理 + 状态轮询）、衣物详情查看与属性编辑、删除（含额度回退规则）
- 穿搭管理：我的穿搭/已收藏分段、创建/编辑穿搭（1~10 件衣物多选）、穿搭详情、公开到社区（扣额度）、点赞与收藏
- AI 穿搭推荐：场景选择、生成中状态、结果预览、保存为穿搭（含 180 秒并发锁与额度不足处理）
- 每日运势：星座自动推算，综合/爱情/工作/财富四项评分 + 幸运色/幸运数字
- 衣柜分享：我的分享列表、创建分享（部分/全量 + 有效期）、分享详情（属主/访客视角）
- 通知中心：列表/详情/未读红点/单条已读
- 额度与会员商城、订单支付（微信 JSAPI 支付）与退款申请
- 个人资料：头像/昵称/性别/生日编辑、我的额度/订单/分享/收藏/额度明细入口

## 视觉规范

严格遵循 iOS HIG 设计语言：系统分组灰底 #F2F2F7 + 纯白卡片 + 0.5px 发丝分隔线 #E5E5EA，强调色系统蓝 #007AFF，SF Symbols 风格线性图标，底部毛玻璃 tabBar，所有页面为 750rpx 宽、左右安全边距 32rpx。

## 技术栈

- 平台：微信小程序（TypeScript），沿用现有 `skyline` 渲染器 + `glass-easel` 组件框架
- 组件：不引入第三方组件库，纯 WXSS 手写，复用现有 `navigation-bar` 自定义导航栏
- 网络：基于 `wx.request` 自建请求层（鉴权、统一响应解析、Token 自动刷新、错误码处理）
- 后端：Go + Gin，统一前缀 `/api/v1`，42 个接口，接口契约以 `/root/zt-closet-backend/接口文档.md` 为准

## 实现方案

### 整体策略

在现有小程序骨架（`miniprogram/`）上重写：清理模板页，新增网络层、公共组件、自定义 tabBar 与 16 个页面文件（UI 原型 14 个功能模块中，「衣柜分享」含 3 个子页面，落地为 3 个路由）。所有请求统一走 `request.ts`，页面只关心数据绑定与交互，遵循「页面 → 组件/工具 → 网络层 → 后端 API」的单向数据流。

### 模块划分

- **网络层（utils）**：`config.ts`（baseURL 占位 + 错误码表）、`request.ts`（统一请求 + 拦截逻辑）、`auth.ts`（token 存取）、`format.ts`（金额分转元、秒转时间、相对时间）
- **公共组件（components）**：复用 `navigation-bar`；新增 `empty-state`（空态）、`skeleton`（骨架屏）、`clothes-card`（衣物卡片，含多选态）、`tag`（状态胶囊）
- **全局壳**：`app.ts`/`app.json`/`app.wxss`（页面注册、登录态、全局样式变量）、`custom-tab-bar/`（5 tab 自定义 tabBar，base64 SVG 线性图标）
- **页面层（16 个路由）**：5 个 tabBar 页 + 登录页 + 10 个二级页

### 系统架构

```mermaid
flowchart LR
    subgraph Pages[页面层 16 路由]
        P1[登录]
        P2[衣橱 tab]
        P3[穿搭 tab]
        P4[运势 tab]
        P5[通知 tab]
        P6[我的 tab]
        P7[上传/衣物详情]
        P8[穿搭详情/创建编辑]
        P9[AI 推荐]
        P10[衣柜分享×3]
        P11[商城/订单]
    end
    subgraph Components[公共组件]
        C1[navigation-bar]
        C2[custom-tab-bar]
        C3[empty-state]
        C4[skeleton]
        C5[clothes-card]
        C6[tag]
    end
    subgraph Network[网络层]
        N1[request.ts 拦截/刷新]
        N2[auth.ts]
        N3[config.ts]
    end
    Pages --> Components
    Pages --> Network
    Network --> API[后端 /api/v1]
```

### 关键实现要点

- **请求封装**：统一解析 `body.code`（业务成败只看 code，不依赖 HTTP 状态码）；401 时自动调用 `POST /user/refresh-token`（同时传 refresh/access 两个 token），成功后整体替换并重试原请求，失败则清登录态重走登录；单独处理 `code===21001`（账号禁用，HTTP 200）与 `code===10003`（AI 并发锁，HTTP 429）
- **Token 管理**：`access_token`/`refresh_token`/`expire_time` 存本地存储，所有需鉴权接口自动注入 `Authorization: Bearer`
- **数据换算**：金额统一 `分 ÷ 100` 展示为 `¥ + 两位小数`；时间 `秒 × 1000`；相对时间格式化（刚刚/x分钟前/今天/YYYY-MM-DD）
- **上传异步轮询**：上传返回 `clothes_uuid` 后轮询 `GET /clothes/:uuid/status`（1~2 秒，上限 60 次），终态 4 成功 / 5 失败（展示 `fail_reason`）
- **字段陷阱**：更新衣物主色请求字段用 `color`（响应才是 `color_main`）；通知 `is_read` 1=未读 2=已读；AI 推荐响应衣物列表字段名是 `outfit_item`；衣柜分享惰性过期需同时判断 `status` 与 `expire_time`
- **性能**：列表分页 `page_size ≤ 50`，下拉刷新 + 上拉加载；图片懒加载；点赞/收藏做乐观更新 + 失败回滚（接口幂等）
- **日志与安全**：请求失败仅记录 `code`/`msg`，不打印 token 与用户敏感信息；删除/取消/退款等不可逆操作全部二次确认

### 目录结构

```
miniprogram/
├── app.json                          # [MODIFY] 注册 16 个页面、5 个 tabBar、全局样式/渲染配置
├── app.ts                            # [MODIFY] 全局登录态初始化、静默登录、全局数据
├── app.wxss                          # [MODIFY] 全局样式变量（色板/圆角/间距/字阶）、通用卡片/按钮/表单样式
├── utils/
│   ├── config.ts                     # [NEW] baseURL 占位常量（HTTPS 域名待填）、错误码映射、额度/状态枚举
│   ├── request.ts                    # [NEW] wx.request Promise 封装，注入鉴权头、解析 code、401 自动刷新重试、21001/10003 处理
│   ├── auth.ts                       # [NEW] token 的读写清除、是否已登录判断、登出
│   └── format.ts                     # [NEW] 金额/时间/相对时间格式化工具
├── custom-tab-bar/
│   ├── index.ts/.wxml/.wxss/.json    # [NEW] 5 tab 自定义 tabBar，毛玻璃底 + 线性 SVG 图标，选中 #007AFF
├── components/
│   ├── navigation-bar/               # [REUSE] 复用现有自定义导航栏（返回/标题/右侧 slot）
│   ├── empty-state/                  # [NEW] 空态组件（线性插画占位 + 主文案 + 说明 + 按钮）
│   ├── skeleton/                     # [NEW] 骨架屏卡片（呼吸动画）
│   ├── clothes-card/                 # [NEW] 衣物卡片（1:1 图区、处理状态徽标、多选态描边 + 对勾）
│   └── tag/                          # [NEW] 状态胶囊标签（系统色浅底 + 深字）
└── pages/
    ├── login/                        # [NEW] 微信授权登录页：插画 + 产品名 + 微信一键登录
    ├── wardrobe/                     # [NEW] 衣橱 tab：分类筛选 + 统计 + 两列网格 + 悬浮上传按钮
    ├── upload/                       # [NEW] 上传衣物：拍照/相册 + 处理中步骤条 + 失败态
    ├── clothes-detail/               # [NEW] 衣物详情：大图 + 15 项属性 + 编辑态 + 删除
    ├── outfit/                       # [NEW] 穿搭 tab：我的穿搭/已收藏分段 + 卡片流
    ├── outfit-detail/                # [NEW] 穿搭详情：拼图封面 + 点赞/收藏/公开 + 更多面板
    ├── outfit-edit/                  # [NEW] 创建/编辑穿搭：表单 + 衣物多选 + 保存/删除
    ├── ai-recommend/                 # [NEW] AI 推荐：场景选择 + 生成中 + 结果页 + 保存
    ├── horoscope/                    # [NEW] 运势 tab：星座大卡 + 四项评分 + 幸运色/数字
    ├── notification/                 # [NEW] 通知 tab：筛选 + 列表 + 未读红点
    ├── notification-detail/          # [NEW] 通知详情：进入即标记已读
    ├── closet-share/                 # [NEW] 衣柜分享列表：我的分享 + 新建入口
    ├── closet-share-create/          # [NEW] 创建分享：类型选择 + 衣物多选 + 有效期面板
    ├── closet-share-detail/          # [NEW] 分享详情：属主/访客视角 + 失效态
    ├── mall/                          # [NEW] 额度与会员商城：会员卡 + 额度网格 + 商品列表 + 订单确认
    ├── order/                         # [NEW] 我的订单：状态筛选 + 支付/取消/退款
    └── profile/                       # [NEW] 我的 tab：个人信息 + 功能列表 + 编辑资料
```

## 实施注意事项

- **保留向后兼容**：不删除现有 `navigation-bar` 组件；仅删除模板页 `pages/logs` 并替换 `pages/index`
- **渲染兼容**：保留 `skyline` 渲染器；自定义 tabBar 若在 skyline 下定位异常，回退方案为在 `app.json` 移除 `renderer`/`componentFramework` 切回 webview（单点配置，不影响页面代码）
- **appid 对齐风险**：`project.config.json` 的 appid（`wxfc03c59fc1bb4de5`）与后端 `configs/config.yaml` 中 `WechatMini.AppID`（`wx47cffdcb7f8c57c3`）不一致，会导致 `wx.login` 换 openid 失败，联调前需由用户统一
- **baseURL 占位**：`config.ts` 中保留 HTTPS 域名占位常量，用户填写真实域名后全局生效，无需改页面代码

## 设计风格

遵循 Apple HIG 的 iOS 原生视觉语言：清爽、克制、以内容为中心。页面背景统一 iOS 分组灰 #F2F2F7，内容承载于纯白卡片（圆角 16pt），用 0.5px 发丝分隔线区分层次，避免浓烈渐变与彩色阴影；强调色系统蓝 #007AFF，情感化点赞/收藏用系统粉 #FF2D55，辅助靛蓝 #5856D6。图标为 SF Symbols 风格线性描边，底部 tabBar 采用半透明毛玻璃 + 顶部发丝线。

## 布局与交互

- 顶部：复用自定义 navigation-bar，二级页左上角返回箭头，右上角保留微信胶囊安全区
- 底部：自定义 tabBar 五个入口（衣橱/穿搭/运势/通知/我的），选中系统蓝、未选中系统灰
- 内容：两列衣物网格（1:1 图区、12pt 间距）；穿搭/AI 推荐为纵向卡片流 + 错落拼图封面
- 反馈：空态居中线性插画 + 主文案 + 引导按钮；加载态骨架屏呼吸动画；轻提示毛玻璃圆角浮层；确认操作为 iOS 居中 Alert；底部动作面板为 iOS sheet（grabber + 圆角 + 取消项独立成组）
- 列表均支持下拉刷新与上拉加载，分页每页不超过 50 条