13 KiB
13 KiB
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 个二级页，全部接通后端接口。 |
|
|
产品概述
「纸条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_read1=未读 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 条