zt-closet-manage-frontend/.codebuddy/plans/前后端逻辑对齐_ced8a4e5.md

name, overview, todos

name	overview	todos
前后端逻辑对齐	以后端最新代码为准，修复前端与后端不一致的地方，重点解决用户额度调整语义错配、额度凭证（grants）功能缺失、商品与订单字段缺失等问题。	id content status align-user-types-api 对齐用户额度/凭证类型并新增 revokeGrant 回收 API completed id content status dependencies update-user-view 更新用户页额度发放表单与详情凭证列表回收 completed align-user-types-api id content status align-goods-types-view 补齐商品 valid_days 等字段并更新商品表单与展示 completed id content status align-order-types-view 补齐订单虚拟支付字段、枚举并更新订单详情展示 completed

用户需求

后端管理代码有更新，需全量核对后端（/root/zt-closet-manage-backend）与前端（/root/zt-closet-manage-frontend）的逻辑一致性。以后端最新代码为基准，前端做适配，确保接口字段、请求语义、枚举映射完全对齐。

核对结论与变更点

经全量对比，登录鉴权、仪表盘、内容审核、通知、退款、响应结构与错误码均已一致，无需改动。存在以下 5 处不一致需要修复：

1. 用户额度调整语义错配（功能不可用）：后端已改为「发放额度凭证」语义，请求体为 quota_type + amount + expire_days；前端仍使用旧的 quota_type + new_total + reason，导致提交必失败。
2. 用户额度凭证（grants）功能缺失：后端用户详情已返回 grants 列表，并提供 DELETE /users/:uuid/grants/:id 回收接口；前端类型、API、页面展示与回收操作均缺失。
3. 商品字段缺失：后端商品新增 valid_days（有效期天数，可编辑）及只读的 product_id、product_status（虚拟支付道具）；前端类型、表单与列表展示均未覆盖。
4. 订单字段缺失：后端订单新增 xpay_product_id、xpay_platform、xpay_env（虚拟支付信息）；前端类型与详情展示均未覆盖。
5. 支付渠道枚举缺失：后端支付渠道为「1=微信支付、2=微信虚拟支付」；前端 PAY_CHANNEL 仅定义 value=1，虚拟支付订单会显示为 -。

技术栈

• 前端：Vue 3 + TypeScript + Element Plus + Pinia + axios（沿用现有架构，不引入新依赖）
• 后端：Go + Gin（只读参考，不修改）

实现方案

以后端 internal/dto/*.go 的 JSON tag 与路由为唯一基准，逐项对齐前端 src/types、src/api、src/utils/constants 与对应 src/views 页面。

关键决策

• 额度调整语义重构：将前端 UserQuotaAdjustRequest 改为 { quota_type, amount, expire_days }，移除 new_total、reason。页面表单同步改为「发放数量 + 有效期天数」，提交 amount（1100000000）与 expire_days（13650）。这是当前最严重的不一致，修复后功能才可用。
• 补齐凭证管理闭环：UserDetailResponse 增加 grants: UserGrantItem[]；api/user.ts 新增 revokeGrant 调用 DELETE /users/:uuid/grants/:id；详情抽屉展示凭证列表（类型/来源/数量/已用/到期/关联 ID）并增加「回收」操作，回收成功后重新拉取详情刷新。
• 只读字段与可编辑字段分离：商品 product_id、product_status 为只读，仅展示、不参与创建/更新提交；valid_days 可编辑，加入表单回显与提交。商品更新接口为「传什么改什么」的指针语义，前端编辑时仅提交可编辑字段。
• 枚举与展示对齐：constants.ts 新增 GRANT_SOURCE（1=会员包、2=加量包、3=广告激励），PAY_CHANNEL 补充 value=2（微信虚拟支付）。
• 单位约定不变：价格仍为「分」，前端继续用 yuanToCents/formatMoney 换算，避免引入新的金额逻辑。

实现注意事项

• 所有字段命名严格遵循后端 JSON tag（snake_case），禁止自创字段名。
• 复用现有 httpGet/httpPost/httpPut/httpDelete 与 enumLabel/enumTag/enumOptions/formatDate/formatText 工具，不新增请求层逻辑。
• 回收凭证后需重新调用 getUserDetail 刷新详情，避免展示陈旧数据。
• 保持现有页面结构与组件风格，仅做字段级调整，不做无关重构。

目录结构

zt-closet-manage-frontend/
├── src/
│   ├── types/
│   │   ├── user.ts        # [MODIFY] UserQuotaAdjustRequest 改为 amount+expire_days；新增 UserGrantItem；UserDetailResponse 增加 grants
│   │   ├── goods.ts       # [MODIFY] GoodsItem 增加 valid_days/product_id/product_status；GoodsCreateRequest、GoodsUpdateRequest 增加 valid_days
│   │   └── order.ts       # [MODIFY] OrderItem 增加 xpay_product_id/xpay_platform/xpay_env
│   ├── api/
│   │   └── user.ts        # [MODIFY] 新增 revokeGrant(uuid, grantId) 调用 DELETE /users/:uuid/grants/:id
│   ├── utils/
│   │   └── constants.ts   # [MODIFY] 新增 GRANT_SOURCE 枚举；PAY_CHANNEL 补充 value=2
│   └── views/
│       ├── user/
│       │   └── UserListView.vue   # [MODIFY] 额度表单改为发放数量+有效期天数；详情抽屉展示 grants 并增加回收操作
│       ├── goods/
│       │   └── GoodsListView.vue  # [MODIFY] 表单增加 valid_days；列表/详情展示 product_id、product_status
│       └── order/
│           └── OrderListView.vue  # [MODIFY] 订单详情抽屉展示虚拟支付字段

关键代码结构

用户域核心类型（需与后端 dto/user.go 严格对齐）：

// 额度发放请求（后端 UserQuotaAdjustRequest）
export interface UserQuotaAdjustRequest {
  quota_type: number   // 1=上传 2=AI 3=社区分享 4=衣柜分享
  amount: number       // 发放数量，min=1
  expire_days: number  // 有效期天数，min=1
}

// 用户额度凭证（后端 UserGrantItem）
export interface UserGrantItem {
  id: number
  quota_type: number
  amount: number
  used: number
  source: number       // 1=会员包 2=加量包 3=广告激励
  expire_time: number  // 秒，0=跟随 VIP
  ref_id: string
  created_at: number
}

// 用户详情（后端 UserDetailResponse）
export interface UserDetailResponse extends UserListItem {
  quotas: QuotaItem[]
  grants: UserGrantItem[]
}