110 lines
6.3 KiB
Markdown
110 lines
6.3 KiB
Markdown
---
|
||
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[]
|
||
}
|
||
``` |