zhengchiliu/zt-closet-wxmini-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35b814279eb4e12cc35e02209eda96848bb150bb
zt-closet-wxmini-frontend/.codebuddy/plans/zt-closet-wxmini_前端实现_171019e0.md
T
zhengchiliu 0a8d60d87f first commit
2026-09-11 01:45:04 +08:00

13 KiB
Raw Blame History

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

系统架构

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 条
Reference in New Issue View Git Blame Copy Permalink