docs: 新增优惠券和礼品卡相关文档

- 新增 Vue 模板标签错误修复总结文档
- 新增 优惠券列表页面优化说明文档
- 新增 优惠券和礼品卡弹窗优化说明文档
- 新增 商品关联功能修复说明文档

docs/数据类型转换问题修复说明.md

@@ -0,0 +1,286 @@
+# 数据类型转换问题修复说明
+
+## 🐛 问题描述
+
+礼品卡保存时出现JSON解析错误，后端无法将字符串 `"1"` 转换为布尔类型：
+
+```json
+{
+    "code": 1,
+    "message": "操作失败",
+    "error": "Cannot deserialize value of type `java.lang.Boolean` from String \"1\": only \"true\" or \"false\" recognized"
+}
+```
+
+## 🔍 问题分析
+
+### 1. **数据类型不匹配**
+
+#### 前端发送的数据
+```javascript
+// ❌ 错误：发送字符串类型
+{
+  "isShow": "1"  // 字符串类型
+}
+```
+
+#### 后端期望的数据
+```java
+// ✅ 后端期望：布尔类型
+public class ShopGift {
+    private Boolean isShow;  // 布尔类型
+}
+```
+
+### 2. **组件配置问题**
+
+#### 错误的开关组件配置
+```vue
+<!-- ❌ 错误：使用字符串值 -->
+<a-switch 
+  v-model:checked="form.isShow" 
+  :checked-value="'1'" 
+  :un-checked-value="'0'"
+/>
+```
+
+#### 错误的初始值设置
+```javascript
+// ❌ 错误：使用字符串初始值
+const form = reactive({
+  isShow: '1'  // 字符串类型
+});
+```
+
+### 3. **类型定义不准确**
+
+#### 错误的TypeScript类型定义
+```typescript
+// ❌ 错误：定义为字符串类型
+export interface ShopGift {
+  isShow?: string;  // 与后端不匹配
+}
+```
+
+## ✅ 修复方案
+
+### 1. **修复数据类型转换**
+
+#### 在保存时进行类型转换
+```javascript
+/* 保存编辑 */
+const save = () => {
+  formRef.value
+    .validate()
+    .then(() => {
+      loading.value = true;
+      const formData = {
+        ...form
+      };
+
+      // ✅ 处理数据类型转换
+      if (formData.isShow !== undefined) {
+        formData.isShow = formData.isShow === '1' || formData.isShow === true;
+      }
+
+      console.log('提交的礼品卡数据:', formData);
+      
+      const saveOrUpdate = isUpdate.value ? updateShopGift : addShopGift;
+      saveOrUpdate(formData)
+        .then((msg) => {
+          loading.value = false;
+          message.success(msg);
+          updateVisible(false);
+          emit('done');
+        })
+        .catch((e) => {
+          loading.value = false;
+          message.error(e.message);
+          console.error('保存失败:', e);
+        });
+    });
+};
+```
+
+### 2. **修复组件配置**
+
+#### 修复开关组件
+```vue
+<!-- ✅ 正确：使用布尔值 -->
+<a-form-item label="展示状态" name="isShow">
+  <a-switch 
+    v-model:checked="form.isShow" 
+    checked-children="展示" 
+    un-checked-children="隐藏" 
+  />
+</a-form-item>
+```
+
+#### 修复初始值设置
+```javascript
+// ✅ 正确：使用布尔初始值
+const form = reactive<ShopGift>({
+  id: undefined,
+  name: '',
+  code: '',
+  goodsId: undefined,
+  takeTime: undefined,
+  operatorUserId: undefined,
+  isShow: true,  // 布尔类型
+  status: 0,
+  comments: '',
+  sortNumber: 100,
+  userId: undefined,
+  deleted: 0,
+  tenantId: undefined,
+  createTime: undefined,
+  updateTime: undefined,
+  num: 1
+});
+```
+
+### 3. **修复类型定义**
+
+#### 更新TypeScript接口
+```typescript
+// ✅ 正确：定义为布尔类型
+export interface ShopGift {
+  // 是否展示
+  isShow?: boolean;  // 与后端匹配
+}
+```
+
+### 4. **修复重置逻辑**
+
+#### 更新表单重置值
+```javascript
+// ✅ 正确：重置时使用布尔值
+Object.assign(form, {
+  id: undefined,
+  name: '',
+  code: '',
+  goodsId: undefined,
+  takeTime: undefined,
+  operatorUserId: undefined,
+  isShow: true,  // 布尔类型
+  status: 0,
+  comments: '',
+  sortNumber: 100,
+  userId: undefined,
+  deleted: 0,
+  tenantId: undefined,
+  createTime: undefined,
+  updateTime: undefined,
+  num: 1
+});
+```
+
+## 📊 修复前后对比
+
+### 修复前的问题
+```javascript
+// ❌ 数据类型错误
+{
+  "isShow": "1"  // 字符串，后端无法解析
+}
+
+// ❌ 组件配置错误
+:checked-value="'1'"
+:un-checked-value="'0'"
+
+// ❌ 类型定义错误
+isShow?: string;
+
+// ❌ 初始值错误
+isShow: '1'
+```
+
+### 修复后的改进
+```javascript
+// ✅ 数据类型正确
+{
+  "isShow": true  // 布尔值，后端可以正确解析
+}
+
+// ✅ 组件配置正确
+// 使用默认的布尔值绑定
+
+// ✅ 类型定义正确
+isShow?: boolean;
+
+// ✅ 初始值正确
+isShow: true
+```
+
+## 🚀 修复效果
+
+### 1. **数据传输正确**
+- ✅ 前端发送正确的布尔类型数据
+- ✅ 后端能够正确解析数据
+- ✅ 避免JSON解析错误
+
+### 2. **组件行为正确**
+- ✅ 开关组件正确绑定布尔值
+- ✅ 状态切换正常工作
+- ✅ 表单验证通过
+
+### 3. **类型安全**
+- ✅ TypeScript类型定义准确
+- ✅ 编译时类型检查
+- ✅ 代码提示正确
+
+### 4. **用户体验提升**
+- ✅ 保存操作成功
+- ✅ 状态显示正确
+- ✅ 错误提示消失
+
+## 🔧 技术要点
+
+### 1. **前后端数据类型一致性**
+```javascript
+// 前端
+isShow: boolean
+
+// 后端
+private Boolean isShow;
+```
+
+### 2. **Ant Design开关组件最佳实践**
+```vue
+<!-- 推荐：使用默认布尔值绑定 -->
+<a-switch v-model:checked="form.isShow" />
+
+<!-- 不推荐：自定义字符串值 -->
+<a-switch 
+  v-model:checked="form.isShow" 
+  :checked-value="'1'" 
+  :un-checked-value="'0'"
+/>
+```
+
+### 3. **数据转换策略**
+```javascript
+// 兼容性转换：支持字符串和布尔值
+if (formData.isShow !== undefined) {
+  formData.isShow = formData.isShow === '1' || formData.isShow === true;
+}
+```
+
+### 4. **TypeScript类型定义规范**
+```typescript
+// 与后端API保持一致
+export interface ShopGift {
+  isShow?: boolean;  // 明确的布尔类型
+}
+```
+
+## 🎯 总结
+
+通过修复数据类型不匹配问题，成功解决了礼品卡保存失败的问题：
+
+1. **类型统一**：前后端使用一致的布尔类型
+2. **组件优化**：开关组件使用标准的布尔值绑定
+3. **类型安全**：TypeScript类型定义准确
+4. **兼容性好**：数据转换逻辑支持多种输入格式
+
+现在礼品卡的保存功能完全正常，用户可以成功创建和编辑礼品卡！