---
name: 前后端逻辑对齐
overview: 以后端最新代码为准，修复前端与后端不一致的地方，重点解决用户额度调整语义错配、额度凭证（grants）功能缺失、商品与订单字段缺失等问题。
todos:
  - id: align-user-types-api
    content: 对齐用户额度/凭证类型并新增 revokeGrant 回收 API
    status: completed
  - id: update-user-view
    content: 更新用户页额度发放表单与详情凭证列表回收
    status: completed
    dependencies:
      - align-user-types-api
  - id: align-goods-types-view
    content: 补齐商品 valid_days 等字段并更新商品表单与展示
    status: completed
  - id: align-order-types-view
    content: 补齐订单虚拟支付字段、枚举并更新订单详情展示
    status: 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`（1~100000000）与 `expire_days`（1~3650）。这是当前最严重的不一致，修复后功能才可用。
- **补齐凭证管理闭环**：`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 严格对齐）：

```ts
// 额度发放请求（后端 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[]
}
```