hfb_sys/docs/前端Vue组件详细适配清单.md

前端Vue组件适配清单

概述

后端已100%完成金额分字段重构，前端基础设施（工具函数、API类型）已完成。 本文档列出所有需要修改的Vue组件及具体改动点。

---

一、WalletView.vue

文件: frontend/src/features/wallet/views/WalletView.vue

1. 添加 import（第28行后）

import { formatCent, formatCentWithSymbol } from '@/shared/utils/money'

2. 删除本地 formatMoney 函数（第225-227行）

// 删除这3行
function formatMoney(value: number) {
  return `¥${(Math.round(Number(value || 0) * 10) / 10).toFixed(1)}`
}

3. 修改 walletMetrics（第54、61行）

// 第54行
value: formatCentWithSymbol(account.value.available_balance_cent),

// 第61行  
value: formatCentWithSymbol(account.value.frozen_balance_cent),

4. 修改模板中的余额显示（第282行）

<!-- 旧 -->
<strong>{{ account ? formatMoney(account.available_balance) : '¥0.00' }}</strong>

<!-- 新 -->
<strong>{{ account ? formatCentWithSymbol(account.available_balance_cent) : '¥0.0' }}</strong>

5. 修改模板中的流水显示（第380、383行）

<!-- 第380行：流水金额 -->
{{ amountPrefix(row.direction) }}{{ formatCent(row.amount_cent) }}

<!-- 第383行：余额 -->
{{ formatCent(row.balance_after_cent) }}

6. 修改充值金额显示（第326、408行）

<!-- 第326行：快速金额按钮 -->
{{ formatCentWithSymbol(amount * 100) }}  <!-- amount是元，转为分显示 -->

<!-- 第408行：支付金额 -->
{{ formatCent(activeRechargePayment.amount_cent) }}

---

二、WithdrawalView.vue

文件: frontend/src/features/wallet/views/WithdrawalView.vue

1. 添加 import

import { formatCent, formatCentWithSymbol, yuanToCent } from '@/shared/utils/money'

2. 修改余额显示（第179、187行）

<!-- 第179行 -->
<div class="balance-value">{{ formatCentWithSymbol(account?.available_balance_cent) }}</div>

<!-- 第187行 -->
<div class="balance-value frozen">{{ formatCentWithSymbol(account?.frozen_balance_cent) }}</div>

3. 修改金额比较（第77行）

// 旧
account.value && withdrawForm.value.amount <= account.value.available_balance

// 新
account.value && withdrawForm.value.amount <= (account.value.available_balance_cent / 100)

4. 修改表单提交（第98行附近的 createWithdrawal 调用）

// 旧
await createWithdrawal(withdrawForm.value)

// 新
await createWithdrawal({
  payment_account_id: withdrawForm.value.payment_account_id,
  amount_cent: yuanToCent(withdrawForm.value.amount),
})

5. 修改提现记录显示（模板中所有 withdrawal.amount 的地方）

{{ formatCent(withdrawal.amount_cent) }}
{{ formatCent(withdrawal.fee_cent) }}
{{ formatCent(withdrawal.actual_amount_cent) }}

---

三、Order 相关组件

3.1 orders.ts API类型定义

文件: frontend/src/features/orders/api/orders.ts

找到 Order 和 Checkout 接口，修改所有金额字段：

export interface Order {
  // ... 其他字段
  display_amount_cent: number
  rent_amount_cent?: number
  owner_rent_amount_cent?: number
  deposit_amount_cent: number
  deposit_original_amount_cent: number
  deposit_waived_amount_cent: number
  platform_fee_cent?: number
  // ... 其他字段
}

export interface Checkout {
  // ... 其他字段
  display_amount_cent: number
  rent_amount_cent?: number
  owner_rent_amount_cent?: number
  platform_fee_cent?: number
  deposit_amount_cent: number
  consumable_amount_cent: number
  other_amount_cent: number
  deposit_deduct_amount_cent: number
  renter_refund_amount_cent?: number
  owner_income_amount_cent?: number
  // ... 其他字段
}

export interface PaymentOrder {
  // ... 其他字段
  amount_cent: number
  // ... 其他字段
}

3.2 OrderDetailView.vue

文件: frontend/src/features/orders/views/OrderDetailView.vue

1. 添加 import：

import { formatCent, formatCentWithSymbol } from '@/shared/utils/money'

2. 全局搜索替换所有金额显示：

<!-- 订单金额 -->
{{ formatCent(order.display_amount_cent) }}
{{ formatCent(order.rent_amount_cent) }}
{{ formatCent(order.owner_rent_amount_cent) }}
{{ formatCent(order.deposit_amount_cent) }}

<!-- 结算金额 -->
{{ formatCent(checkout.renter_refund_amount_cent) }}
{{ formatCent(checkout.owner_income_amount_cent) }}
{{ formatCent(checkout.platform_fee_cent) }}

3.3 MobileOrdersView.vue

文件: frontend/src/features/orders/views/MobileOrdersView.vue

1. 添加 import：

import { formatCent } from '@/shared/utils/money'

2. 修改 money 函数（第122-124行）：

function money(value: unknown) {
  return formatCent(Number(value || 0))
}

3. 修改 orderRentAmount 函数（第134-137行）：

function orderRentAmount(order: Order) {
  if (isOwner(order)) return Number(order.owner_rent_amount_cent ?? order.display_amount_cent ?? 0)
  return Number(order.rent_amount_cent ?? order.display_amount_cent ?? 0)
}

---

四、Listing 相关组件

4.1 listings.ts API类型定义

文件: frontend/src/features/listings/api/listings.ts

export interface Listing {
  // ... 其他字段
  price_cent: number
  deposit_amount_cent: number
  // ... 其他字段
}

4.2 ListingCard.vue

文件: 搜索 ListingCard.vue 或类似的组件

1. 添加 import：

import { formatCent, formatCentWithSymbol } from '@/shared/utils/money'

2. 修改价格显示：

{{ formatCent(listing.price_cent) }}
{{ formatCent(listing.deposit_amount_cent) }}

4.3 ListingForm.vue（创建/编辑商品）

文件: 搜索创建商品的表单组件

1. 添加 import：

import { yuanToCent } from '@/shared/utils/money'

2. 提交时转换：

async function submit() {
  const payload = {
    ...form,
    price_cent: yuanToCent(form.price),
    deposit_amount_cent: yuanToCent(form.deposit_amount),
  }
  // 删除旧字段
  delete payload.price
  delete payload.deposit_amount
  
  await createListing(payload)
}

---

五、AdminFinance 相关组件

文件: 搜索 AdminFinance 或 FinanceView 组件

修改要点

1. 导入 formatCent
2. 将所有 *_amount_cent 字段用 formatCent 显示
3. 旧的 float64 字段仍用 formatMoney 显示（如 platform_income_amount）

<!-- Cent字段用 formatCent -->
{{ formatCent(summary.total_flow_amount_cent) }}
{{ formatCent(summary.channel_net_amount_cent) }}

<!-- 旧字段用 formatMoney -->
{{ formatMoney(summary.platform_income_amount) }}

---

六、批量操作指南

VSCode 全局搜索替换（推荐）

1. 字段名替换 (在 .vue 和 .ts 文件中):

available_balance → available_balance_cent
frozen_balance → frozen_balance_cent
amount → amount_cent
balance_after → balance_after_cent
price → price_cent
deposit_amount → deposit_amount_cent

2. 函数调用替换 (仅在模板中):

formatMoney(xxx.amount) → formatCent(xxx.amount_cent)
formatMoneyWithSymbol(xxx.amount) → formatCentWithSymbol(xxx.amount_cent)

注意事项

⚠️ 不要替换的情况：

• 表单中用户输入的金额变量（保持元）
• 常量定义（如 MIN_AMOUNT = 10，仍然是元）
• formatMoney 用于旧的 float64 字段（AdminFinance中）

✅ 必须替换的情况：

• API响应中的 *_cent 字段
• 显示给用户的金额
• 发送给后端的金额（需要用 yuanToCent 转换）

---

七、测试检查清单

完成修改后，逐一测试：

功能测试

• 钱包页面：余额正确显示
• 钱包页面：流水记录金额正确
• 充值功能：输入元，后端收到分
• 提现页面：余额显示正确
• 提现功能：输入元，后端收到分，显示手续费
• 订单详情：所有金额正确显示
• 订单列表：金额显示正确
• 商品列表：价格押金显示正确
• 商品发布：输入元，后端收到分

显示精度测试

用开发者工具检查：

// 12345分 应该显示为 "123.5"
formatCent(12345) === "123.5" ✓

// 12344分 应该显示为 "123.4"  
formatCent(12344) === "123.4" ✓

// 1分 应该显示为 "0.0"
formatCent(1) === "0.0" ✓

边界值测试

• 零金额：formatCent(0) → "0.0"
• 最小充值：0.01元 = 1分
• 最小提现：10元 = 1000分
• 最大提现：5000元 = 500000分

---

八、常见问题排查

Q: 编译错误 "Property 'available_balance' does not exist"

A: 类型定义已改为 available_balance_cent，检查是否正确导入了新的类型定义。

Q: 显示的金额不对（如 123.45 显示成 12345）

A: 忘记用 formatCent 格式化，应该是 formatCent(xxx.amount_cent) 而不是直接显示。

Q: 提交表单时后端报错 "amount_cent is required"

A: 检查是否用 yuanToCent() 转换了用户输入。

Q: 测试充值时金额对不上

A: 检查 PaymentOrder 接口是否改为 amount_cent，显示时是否用 formatCent(payment.amount_cent)。

---

九、快速参考

常用代码片段

<script setup lang="ts">
// 1. 导入
import { formatCent, formatCentWithSymbol, yuanToCent } from '@/shared/utils/money'

// 2. 显示金额
const displayBalance = formatCentWithSymbol(account.available_balance_cent)

// 3. 提交表单
async function submit() {
  await api.post('/endpoint', {
    amount_cent: yuanToCent(form.amount)
  })
}
</script>

<template>
  <!-- 4. 模板中显示 -->
  <div>余额：{{ formatCent(account.available_balance_cent) }}</div>
  
  <!-- 5. 用户输入（元） -->
  <el-input-number v-model="form.amount" :min="0.01" :precision="2" />
</template>

---

预计工作量: 2-3小时
难度: 低（机械性查找替换）
风险: 低（TypeScript会提示错误）

完成后记得：

1. 运行 npm run build 检查编译
2. 启动开发服务器测试每个功能
3. 提交代码前再次检查显示精度

祝顺利！ 🚀