# HTML拓客页面与后端服务对接说明

## 🎯 对接目标

将HTML前端拓客页面与.NET Core后端服务对接，实现真实的拓客数据入库功能。

## 🔧 后端服务信息

### **API接口地址**
```
POST /api/Extend/LqTkjlb
```

### **请求格式**
```json
{
  "tksj": 1640995200000,        // 拓客时间 (时间戳)
  "tkry": "张三",               // 拓客人员
  "gkxm": "李女士",             // 顾客姓名
  "dhhm": "13800138000",        // 电话号码
  "gmzs": 5,                    // 购买张数
  "zffs": "微信",               // 支付方式
  "sfjwx": "是",                // 是否加微信
  "bz": "备注信息"              // 备注
}
```

### **响应格式**
```json
{
  "success": true,
  "message": "操作成功",
  "data": null
}
```

## 📱 前端页面功能

### **1. 配置区域**
- **API基础地址**: 配置后端服务地址 (默认: http://localhost:5000)
- **访问令牌**: 可选的认证令牌
- **测试连接**: 测试与后端服务的连接状态

### **2. 表单字段**
- **拓客时间**: 日期时间选择器
- **拓客门店**: 门店选择下拉框
- **拓客人员**: 人员选择下拉框
- **顾客姓名**: 文本输入框
- **电话号码**: 手机号输入框 (带格式验证)
- **购买张数**: 数字输入框
- **支付方式**: 支付方式选择
- **是否加微信**: 是/否选择
- **备注**: 多行文本输入框

### **3. 数据验证**
- 必填字段验证
- 手机号格式验证 (1[3-9]xxxxxxxxx)
- 购买张数范围验证 (> 0)

## 🚀 使用步骤

### **步骤1: 启动后端服务**
```bash
# 进入后端项目目录
cd netcore

# 启动服务
dotnet run --project src/Application/NCC.API
```

### **步骤2: 配置前端页面**
1. 打开 `html/expansion.html`
2. 在"后端服务配置"区域设置正确的API地址
3. 点击"测试连接"验证服务是否可用

### **步骤3: 填写拓客数据**
1. 填写基本信息 (时间、门店、人员)
2. 填写客户信息 (姓名、电话、购买数量等)
3. 选择支付方式和微信状态
4. 添加备注信息

### **步骤4: 提交数据**
1. 点击"提交数据"按钮
2. 系统自动验证数据格式
3. 发送数据到后端服务
4. 显示提交结果

## 🔍 数据映射关系

| 前端字段 | 后端字段 | 数据类型 | 说明 |
|---------|---------|---------|------|
| expansionTime | tksj | 时间戳 | 转换为毫秒时间戳 |
| expansionStaff | tkry | 字符串 | 拓客人员姓名 |
| customerName | gkxm | 字符串 | 顾客姓名 |
| customerPhone | dhhm | 字符串 | 电话号码 |
| buyCount | gmzs | 整数 | 购买张数 |
| payMethod | zffs | 字符串 | 支付方式 |
| isWeChat | sfjwx | 字符串 | 是否加微信 |
| remark | bz | 字符串 | 备注信息 |

## ⚠️ 注意事项

### **1. 后端服务要求**
- 确保后端服务正在运行
- 检查API地址是否正确
- 验证网络连接是否正常

### **2. 数据格式要求**
- 时间字段必须转换为时间戳格式
- 数字字段必须为有效数字
- 字符串字段不能为空

### **3. 错误处理**
- 网络连接失败
- 服务器内部错误
- 数据验证失败
- 认证失败

## 🐛 常见问题

### **Q1: 无法连接到后端服务**
**A**: 检查后端服务是否启动，API地址是否正确

### **Q2: 提交失败显示HTTP 500错误**
**A**: 检查后端服务日志，可能是数据库连接问题

### **Q3: 数据提交成功但数据库中没有记录**
**A**: 检查后端服务的数据库连接和事务处理

### **Q4: 手机号验证失败**
**A**: 确保输入的是11位有效手机号，格式为1[3-9]xxxxxxxxx

## 📊 测试数据示例

```json
{
  "tksj": 1640995200000,
  "tkry": "张三",
  "gkxm": "李女士",
  "dhhm": "13800138000",
  "gmzs": 3,
  "zffs": "微信",
  "sfjwx": "是",
  "bz": "首次到店，对服务很满意"
}
```

## 🔗 相关文件

- **前端页面**: `html/expansion.html`
- **后端服务**: `netcore/src/Modularity/Extend/NCC.Extend/LqTkjlbService.cs`
- **数据实体**: `netcore/src/Modularity/Extend/NCC.Extend.Entitys/Entity/LqTkjlbEntity.cs`
- **API接口**: `netcore/src/Modularity/Extend/NCC.Extend.Interfaces/ILqTkjlbService.cs`

## ✅ 对接完成检查清单

- [ ] 后端服务正常启动
- [ ] 前端页面能正常访问
- [ ] API连接测试成功
- [ ] 表单数据验证正常
- [ ] 数据提交成功
- [ ] 数据库中有对应记录
- [ ] 错误处理正常工作

完成以上步骤后，HTML前端拓客页面就成功对接了后端服务，可以实现真实的拓客数据入库功能！