bindbox-game/development_standards.md

开发规范与问题记录

项目概述

本项目基于 Vue 3 + TypeScript + Element Plus + Vite 技术栈开发的管理系统。

已发现的问题与解决方案

1. 时间字段处理错误

问题描述： 创建道具卡时出现数据库错误：Error 1292 (22007): Incorrect date value: '0000-00-00' for column 'valid_start' at row 1

问题原因：

• 当用户没有选择有效期时，代码仍然尝试提交时间字段
• 时间数据格式不正确或包含无效值
• 后端数据库不接受'0000-00-00'这样的无效日期

解决方案：

// 处理有效期 - 只有当时间范围有效时才添加时间字段
if (validTimeRange.value && validTimeRange.value.length === 2 && 
    validTimeRange.value[0] && validTimeRange.value[1]) {
  try {
    const startTime = new Date(validTimeRange.value[0]).getTime()
    const endTime = new Date(validTimeRange.value[1]).getTime()
    
    // 验证时间是否有效
    if (!isNaN(startTime) && !isNaN(endTime) && startTime > 0 && endTime > 0) {
      submitData.valid_start_unix = Math.floor(startTime / 1000)
      submitData.valid_end_unix = Math.floor(endTime / 1000)
    }
  } catch (error) {
    console.error('时间处理错误:', error)
  }
}

开发规范：

1. 时间字段处理：

   • 必须验证时间数据的有效性
   • 使用isNaN()检查时间戳是否为有效数字
   • 确保时间值大于0
   • 添加try-catch处理可能的异常

2. 数据提交原则：

   • 只提交有效和必要的数据字段
   • 避免提交null、undefined或无效的时间数据
   • 对可选字段进行严格的有效性检查

2. 价格字段数据类型错误

问题描述： 创建道具卡时出现错误：json: cannot unmarshal null into Go struct field createItemCardRequest.price of type int64

解决方案：

// 确保价格字段存在且为数字类型
if (submitData.price === undefined || submitData.price === null) {
  submitData.price = 0
} else {
  submitData.price = Number(submitData.price)
}

3. 组件结构错误

问题描述： 道具卡管理页面按钮不显示，原因是错误的组件插槽使用

解决方案： 使用独立的按钮区域布局，避免错误的插槽使用：

<!-- 搜索栏 -->
<ArtSearchBar />

<!-- 表格头部和按钮 -->
<div class="table-header-wrapper">
  <div class="header-actions">
    <el-button type="primary" @click="handleCreate">
      新增道具卡
    </el-button>
  </div>
</div>

<!-- 数据表格 -->
<ArtTable />

4. 数据枚举显示问题

问题描述： 状态、类型、范围、效果等字段显示为数字而不是对应的文本标签

解决方案：

1. 增强枚举映射函数的空值处理
2. 完善状态字段的多状态判断
3. 添加数据类型检查

// 增强的枚举映射函数
const getCardTypeLabel = (type: number) => cardTypeMap[type as keyof typeof cardTypeMap] || '未知'

// 完善的状态显示
{{ row.status === 1 ? '启用' : row.status === 2 ? '禁用' : '未知' }}

// 空值处理
{{ getCardTypeLabel(row.card_type || 0) }}

5. API路径404错误

问题描述： 优惠券API请求返回404错误：admin/system_coupons 路径不存在

问题原因： 后端API路径可能不存在或需要调整

解决方案：

1. 检查实际的API路径配置
2. 对比道具卡API路径确认一致性
3. 添加详细的请求调试信息
4. 检查代理配置是否正确

6. 数据枚举和操作按钮显示问题

问题描述： 道具卡管理页面中：

• 状态、类型、范围、效果等字段显示为数字而不是对应的文本标签
• 操作栏（编辑、删除按钮）不显示

问题原因：

1. 枚举映射函数没有正确处理空值
2. 使用了错误的按钮组件（原生的el-button而不是项目封装的ArtButtonTable）
3. 插槽模板语法正确但组件渲染有问题

解决方案：

1. 枚举显示修复：

<template #status="{ row }">
  <el-tag :type="row.status === 1 ? 'success' : 'danger'">
    {{ row.status === 1 ? '启用' : row.status === 2 ? '禁用' : '未知' }}
  </el-tag>
</template>

<template #card_type="{ row }">
  <el-tag>{{ getCardTypeLabel(row.card_type || 0) }}</el-tag>
</template>

2. 操作按钮修复：

<template #actions="{ row }">
  <ArtButtonTable type="edit" @click="handleEdit(row)" />
  <ArtButtonTable type="delete" @click="handleDelete(row)" />
</template>

3. 组件导入：

import ArtButtonTable from '@/components/core/forms/art-button-table/index.vue'

开发规范：

1. 组件使用规范：

   • 优先使用项目封装的组件（如ArtButtonTable）而不是原生Element Plus组件
   • 保持与其他页面一致的UI风格和交互体验
   • 使用项目统一的图标和样式系统

2. 枚举显示规范：

   • 所有状态字段必须提供完整的枚举映射
   • 处理空值和异常值情况，提供默认值
   • 使用统一的标签样式和颜色规范

3. 调试和日志：

   • 添加详细的数据结构检查日志
   • 验证枚举映射函数的正确性
   • 检查组件渲染和插槽绑定的正确性

前端开发规范

1. 表单数据处理

• 提交前必须清理数据，移除undefined和null值
• 对数字类型字段进行类型转换和验证
• 时间字段必须验证有效性
• 可选字段需要条件判断

2. 错误处理

• 所有API调用必须添加try-catch异常处理
• 用户友好的错误提示信息
• 控制台记录详细错误信息便于调试

3. 代码结构

• 保持组件单一职责原则
• 复杂的表单处理逻辑抽取为独立函数
• 添加必要的注释说明业务逻辑

4. 数据验证

• 前端表单必须进行完整的验证
• 后端返回的错误需要友好处理
• 特殊字段（如时间、价格）需要额外验证

后端接口规范

• 明确字段类型要求（如int64）
• 提供清晰的错误信息和错误码
• 对无效数据给出具体的错误描述

数据库规范

• 不允许插入'0000-00-00'等无效日期
• 时间字段必须有默认值或允许为null
• 数字类型字段不能接收字符串类型

---

最后更新：2025年11月14日 文档维护：开发团队