diff --git a/backend/docs/modules_design/customer-api.md b/backend/docs/modules_design/customer-api.md new file mode 100644 index 0000000..6d088be --- /dev/null +++ b/backend/docs/modules_design/customer-api.md @@ -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": "zhangsan@example.com", + "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": "zhangsan@example.com", + "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": "zhangsan@example.com", + "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" + } +} +``` diff --git a/backend/docs/modules_design/customer.md b/backend/docs/modules_design/customer.md index a7b406c..1f23bee 100644 --- a/backend/docs/modules_design/customer.md +++ b/backend/docs/modules_design/customer.md @@ -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 @@ ### 优化客户服务 - **服务分级**: 根据客户等级提供差异化服务 - **及时响应**: 通过状态管理及时识别问题客户 -- **个性化**: 根据客户偏好(授权类型)提供合适的解决方案 +- **个性化**: 根据客户属性提供合适的解决方案 ### 支撑业务决策 - **客户分析**: 通过等级、类型分布了解客户结构 diff --git a/backend/internal/models/customer.go b/backend/internal/models/customer.go index 2f42211..af21c7d 100644 --- a/backend/internal/models/customer.go +++ b/backend/internal/models/customer.go @@ -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"` diff --git a/backend/migrations/001_create_customers_table.sql b/backend/migrations/001_create_customers_table.sql index 9b832a7..99c14cf 100644 --- a/backend/migrations/001_create_customers_table.sql +++ b/backend/migrations/001_create_customers_table.sql @@ -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', diff --git a/backend/migrations/002_insert_sample_data.sql b/backend/migrations/002_insert_sample_data.sql index 7973b9e..360ebd9 100644 --- a/backend/migrations/002_insert_sample_data.sql +++ b/backend/migrations/002_insert_sample_data.sql @@ -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', '测试客户，已禁用，用于演示禁用状态',