feat: 客户管理模块接口设计

2025-08-11 21:53:12 +08:00
1 parent 0279083c59
commit aa43a51db5
@@ -0,0 +1,205 @@
+# 客户管理API设计
+
+## 1. API概览
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/customers` | 查询客户列表 |
+| GET | `/api/customers/{id}` | 获取客户详情 |
+| POST | `/api/customers` | 创建客户 |
+| PUT | `/api/customers/{id}` | 更新客户信息 |
+| DELETE | `/api/customers/{id}` | 删除客户(软删除) |
+| PATCH | `/api/customers/{id}/status` | 修改客户状态 |
+
+---
+
+## 2. 数据模型
+
+### 客户信息结构
+```json
+{
+  "id": "uuid",
+  "customer_code": "CUS-2025-0001",
+  "customer_name": "北京科技有限公司",
+  "customer_type": "enterprise",
+  "contact_person": "张三",
+  "contact_title": "技术总监",
+  "email": "[email protected]",
+  "phone": "13800138000",
+  "address": "北京市朝阳区科技园区100号",
+  "company_size": "medium",
+  "customer_level": "vip",
+  "status": "active",
+  "description": "重要客户，需要优先技术支持",
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-20T15:45:00Z",
+  "created_by": "admin_uuid",
+  "updated_by": "admin_uuid"
+}
+```
+
+### 字段说明
+- `customer_type`: `individual` | `enterprise` | `government` | `education`
+- `company_size`: `small` | `medium` | `large` | `enterprise`
+- `customer_level`: `normal` | `vip` | `enterprise` | `strategic`
+- `status`: `active` | `disabled`
+
+---
+
+## 3. API详细设计
+
+### 3.1 查询客户列表
+```
+GET /api/customers
+```
+
+**Query参数**
+- `page`: 页码，默认1
+- `page_size`: 每页条数，默认20，最大100
+- `search`: 搜索关键词(支持客户编码、名称、联系人、邮箱)
+- `customer_type`: 客户类型筛选
+- `customer_level`: 客户等级筛选
+- `status`: 状态筛选
+- `sort`: 排序字段，默认`created_at`
+- `order`: 排序方向，默认`desc`
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "list": [
+      {
+        "id": "uuid",
+        "customer_code": "CUS-2025-0001",
+        "customer_name": "北京科技有限公司",
+        "customer_type": "enterprise",
+        "contact_person": "张三",
+        "email": "[email protected]",
+        "customer_level": "vip",
+        "status": "active",
+        "created_at": "2025-01-15T10:30:00Z"
+      }
+    ],
+    "total": 100,
+    "page": 1,
+    "page_size": 20,
+    "total_pages": 5
+  }
+}
+```
+
+### 3.2 获取客户详情
+```
+GET /api/customers/{id}
+```
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    // 完整的客户信息结构
+  }
+}
+```
+
+### 3.3 创建客户
+```
+POST /api/customers
+```
+
+**请求体**
+```json
+{
+  "customer_name": "北京科技有限公司",
+  "customer_type": "enterprise",
+  "contact_person": "张三",
+  "contact_title": "技术总监",
+  "email": "[email protected]",
+  "phone": "13800138000",
+  "address": "北京市朝阳区科技园区100号",
+  "company_size": "medium",
+  "customer_level": "normal",
+  "description": "新客户",
+  "status": "active"
+}
+```
+
+**必填字段**
+- `customer_name`: 客户名称
+- `contact_person`: 联系人姓名
+- `customer_level`: 客户等级
+- `customer_type`: 客户类型
+- `company_size`: 企业规模
+- `status`: 状态
+
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "客户创建成功",
+  "data": {
+    // 创建后的完整客户信息
+  }
+}
+```
+
+### 3.4 更新客户信息
+```
+PUT /api/customers/{id}
+```
+
+**请求体**: 与创建客户相同，但所有字段都是可选的
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "客户信息更新成功",
+  "data": {
+    // 更新后的完整客户信息
+  }
+}
+```
+
+### 3.5 删除客户
+```
+DELETE /api/customers/{id}
+```
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "客户删除成功",
+  "data": null
+}
+```
+
+### 3.6 修改客户状态
+```
+PATCH /api/customers/{id}/status
+```
+
+**请求体**
+```json
+{
+  "status": "disabled"
+}
+```
+
+**响应示例**
+```json
+{
+  "code": 0,
+  "message": "客户状态更新成功",
+  "data": {
+    "id": "uuid",
+    "status": "disabled"
+  }
+}
+```
@@ -40,8 +40,7 @@

 - `email` - 主邮箱
  - **作用**: 授权激活通知、过期提醒、技术支持的主要渠道
-  - **必填**: 是
-  - **唯一**: 建议唯一
+  - **必填**: 否
  - **验证**: 邮箱格式验证

 - `phone` - 电话号码
@@ -63,13 +62,6 @@
  - **必填**: 否
  - **用途**: 制定差异化授权策略

-### 授权配置  
- `preferred_license_type` - 首选授权类型 (在线/离线/混合)
-  - **作用**: 影响授权码生成策略和验证方式
-  - **枚举**: online(在线) | offline(离线) | hybrid(混合)
-  - **必填**: 否
-  - **默认**: online
-  - **意义**: 在线需要联网验证，离线可本地验证

 ### 客户分级
 - `customer_level` - 客户等级 (普通/VIP/企业/战略)
@@ -197,7 +189,7 @@

 ### 商业信息卡片
 ```
-企业规模: 中型企业             首选授权: 在线授权
+企业规模: 中型企业
 备注描述: 重要客户，IoT平台采购方，需要优先技术支持
 ```
 **用途**: 业务背景了解，制定针对性服务策略
@@ -337,7 +329,7 @@
 ### 优化客户服务
 - **服务分级**: 根据客户等级提供差异化服务
 - **及时响应**: 通过状态管理及时识别问题客户
- **个性化**: 根据客户偏好(授权类型)提供合适的解决方案
+- **个性化**: 根据客户属性提供合适的解决方案

 ### 支撑业务决策
 - **客户分析**: 通过等级、类型分布了解客户结构
@@ -14,11 +14,10 @@ type Customer struct {
 	CustomerType         string         `gorm:"type:varchar(20);not null;default:'enterprise';index" json:"customer_type"`
 	ContactPerson        string         `gorm:"type:varchar(100);not null" json:"contact_person"`
 	ContactTitle         *string        `gorm:"type:varchar(100)" json:"contact_title"`
-	Email                string         `gorm:"type:varchar(255);uniqueIndex;not null" json:"email"`
+	Email                *string        `gorm:"type:varchar(255)" json:"email"`
 	Phone                *string        `gorm:"type:varchar(20)" json:"phone"`
 	Address              *string        `gorm:"type:text" json:"address"`
 	CompanySize          *string        `gorm:"type:varchar(20)" json:"company_size"`
-	PreferredLicenseType string         `gorm:"type:varchar(20);default:'online'" json:"preferred_license_type"`
 	CustomerLevel        string         `gorm:"type:varchar(20);not null;default:'normal';index" json:"customer_level"`
 	Status               string         `gorm:"type:varchar(20);not null;default:'active';index" json:"status"`
 	Description          *string        `gorm:"type:text" json:"description"`
@@ -13,7 +13,7 @@ CREATE TABLE customers (
    -- 联系信息
    contact_person VARCHAR(100) NOT NULL,
    contact_title VARCHAR(100),
-    email VARCHAR(255) NOT NULL UNIQUE,
+    email VARCHAR(255),
    phone VARCHAR(20),
    
    -- 地址信息
@@ -22,9 +22,6 @@ CREATE TABLE customers (
    -- 商业属性
    company_size VARCHAR(20) COMMENT '企业规模: small, medium, large, enterprise',
    
-    -- 授权配置
-    preferred_license_type VARCHAR(20) DEFAULT 'online' COMMENT '授权类型: online, offline, hybrid',
-    
    -- 客户分级
    customer_level VARCHAR(20) NOT NULL DEFAULT 'normal' COMMENT '客户等级: normal, vip, enterprise, strategic',
    
@@ -12,7 +12,7 @@ ON DUPLICATE KEY UPDATE sequence_number = 5;
 INSERT INTO customers (
    customer_code, customer_name, customer_type, 
    contact_person, contact_title, email, phone, 
-    address, company_size, preferred_license_type, 
+    address, company_size, 
    customer_level, status, description, 
    created_at, updated_at, created_by
 ) VALUES 
@@ -27,7 +27,6 @@ INSERT INTO customers (
    '13800138000',
    '北京市朝阳区科技园区100号', 
    'medium', 
-    'online',
    'vip', 
    'active', 
    '重要客户，IoT平台采购方，需要优先技术支持', 
@@ -44,7 +43,6 @@ INSERT INTO customers (
    '13900139000',
    '上海市浦东新区张江高科技园区200号', 
    NULL, 
-    'offline',
    'normal', 
    'active', 
    '个人开发者，主要用于学习和小型项目', 
@@ -61,7 +59,6 @@ INSERT INTO customers (
    '010-12345678',
    '某市政府大楼信息化中心', 
    'large', 
-    'hybrid',
    'enterprise', 
    'active', 
    '政府客户，智慧城市项目，需要专项技术支持', 
@@ -78,7 +75,6 @@ INSERT INTO customers (
    '010-62785678',
    '北京市海淀区清华大学计算机学院', 
    'large', 
-    'online',
    'strategic', 
    'active', 
    '重点高校合作伙伴，科研项目合作，享受教育优惠政策', 
@@ -95,7 +91,6 @@ INSERT INTO customers (
    '13700137000',
    '测试地址', 
    'small', 
-    'online',
    'normal', 
    'disabled', 
    '测试客户，已禁用，用于演示禁用状态',