first commit

2026-09-11 01:45:04 +08:00
commit 0a8d60d87f
145 changed files with 40978 additions and 0 deletions
@@ -0,0 +1,218 @@
+---
+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 条