# 供应商管理模块开发总结

## 📋 需求来源

根据 ONE-OS 前端原型 `/Users/kkfluous/Projects/ai-coding/ln-oneos/ONE-OS/web端/业务管理/供应商管理*.jsx` 进行后端设计开发。

## 🎯 功能概述

供应商管理模块用于管理企业的各类供应商信息，包括加氢站、充电站、维修站、保险公司、备件供应商等。

### 核心功能
- ✅ 供应商列表查询（支持多条件筛选）
- ✅ 供应商新增
- ✅ 供应商编辑
- ✅ 供应商查看
- ✅ 供应商删除
- 🔲 供应商导入（待实现）
- 🔲 供应商导出（待实现）

## 📊 数据模型

### 供应商信息表 (asset_supplier)

#### 基本信息
| 字段 | 类型 | 说明 | 必填 |
|------|------|------|------|
| id | BIGINT | 主键ID | ✓ |
| supplier_code | VARCHAR(50) | 供应商编码 | ✓ |
| coop_status | VARCHAR(20) | 合作状态 | ✓ |
| supplier_name | VARCHAR(100) | 供应商名称 | ✓ |
| type | VARCHAR(50) | 供应商类型 | ✓ |
| province | VARCHAR(50) | 省份 | |
| city | VARCHAR(50) | 城市 | |
| address | VARCHAR(255) | 详细地址 | |
| region | VARCHAR(20) | 区域 | |
| contact | VARCHAR(50) | 联系人 | |
| contact_mobile | VARCHAR(20) | 联系手机 | |
| contact_phone | VARCHAR(50) | 联系电话 | |
| email | VARCHAR(100) | 邮箱 | |
| credit_code_or_id | VARCHAR(100) | 统一社会信用代码/身份证号 | |
| remark | VARCHAR(500) | 备注 | |

#### 开票信息
| 字段 | 类型 | 说明 |
|------|------|------|
| tax_id | VARCHAR(100) | 税号 |
| invoice_address | VARCHAR(255) | 开票地址 |
| invoice_phone | VARCHAR(50) | 开票电话 |
| account | VARCHAR(100) | 账号 |
| opening_bank | VARCHAR(200) | 开户行 |
| mailing_address | VARCHAR(255) | 邮寄地址 |

#### 审计字段
| 字段 | 类型 | 说明 |
|------|------|------|
| creator | VARCHAR(64) | 创建者 |
| create_time | DATETIME | 创建时间 |
| updater | VARCHAR(64) | 更新者 |
| update_time | DATETIME | 更新时间 |
| deleted | BIT(1) | 是否删除 |
| tenant_id | BIGINT | 租户编号 |

### 索引设计
- PRIMARY KEY: `id`
- UNIQUE KEY: `uk_supplier_code` (supplier_code, deleted)
- INDEX: `idx_supplier_name` (supplier_name)
- INDEX: `idx_coop_status` (coop_status)
- INDEX: `idx_type` (type)
- INDEX: `idx_region` (region)
- INDEX: `idx_city` (city)
- INDEX: `idx_create_time` (create_time)
- INDEX: `idx_tenant_id` (tenant_id)

## 🏗️ 代码结构

### 后端文件清单

```
yudao-module-asset/yudao-module-asset-server/
├── src/main/java/cn/iocoder/yudao/module/asset/
│   ├── controller/admin/supplier/
│   │   ├── SupplierController.java          # 控制器
│   │   └── vo/
│   │       ├── SupplierBaseVO.java          # 基础 VO
│   │       ├── SupplierSaveReqVO.java       # 创建/更新 Request VO
│   │       ├── SupplierRespVO.java          # 响应 VO
│   │       └── SupplierPageReqVO.java       # 分页查询 Request VO
│   ├── service/supplier/
│   │   ├── SupplierService.java             # Service 接口
│   │   └── SupplierServiceImpl.java         # Service 实现
│   ├── convert/supplier/
│   │   └── SupplierConvert.java             # 对象转换
│   ├── dal/
│   │   ├── dataobject/supplier/
│   │   │   └── SupplierDO.java              # 数据对象
│   │   └── mysql/supplier/
│   │       └── SupplierMapper.java          # Mapper
│   └── enums/
│       └── ErrorCodeConstants.java          # 错误码（已更新）
└── sql/mysql/
    └── supplier.sql                          # 数据库脚本
```

## 🔌 API 接口

### 基础路径
```
/asset/supplier
```

### 接口列表

#### 1. 创建供应商
```
POST /asset/supplier/create
权限: asset:supplier:create
```

**Request Body**
```json
{
  "supplierCode": "GYS-2025-001",
  "coopStatus": "已合作",
  "supplierName": "嘉兴某某加氢站",
  "type": "加氢站",
  "province": "浙江省",
  "city": "嘉兴市",
  "address": "浙江省嘉兴市南湖区科技大道1号",
  "region": "华东",
  "contact": "张三",
  "contactMobile": "13800138001",
  "contactPhone": "0571-88888888",
  "email": "zhangsan@example.com",
  "creditCodeOrId": "91330400MA2XXXXX1",
  "remark": "",
  "taxId": "91330400MA2XXXXX1",
  "invoiceAddress": "浙江省嘉兴市南湖区科技大道1号",
  "invoicePhone": "0571-88888888",
  "account": "6222021234567890123",
  "openingBank": "中国工商银行嘉兴分行",
  "mailingAddress": "浙江省嘉兴市南湖区科技大道1号"
}
```

**Response**
```json
{
  "code": 0,
  "data": 1,
  "msg": "操作成功"
}
```

#### 2. 更新供应商
```
PUT /asset/supplier/update
权限: asset:supplier:update
```

**Request Body**
```json
{
  "id": 1,
  "supplierCode": "GYS-2025-001",
  "coopStatus": "已合作",
  "supplierName": "嘉兴某某加氢站",
  ...
}
```

#### 3. 删除供应商
```
DELETE /asset/supplier/delete?id=1
权限: asset:supplier:delete
```

#### 4. 获取供应商详情
```
GET /asset/supplier/get?id=1
权限: asset:supplier:query
```

**Response**
```json
{
  "code": 0,
  "data": {
    "id": 1,
    "supplierCode": "GYS-2025-001",
    "coopStatus": "已合作",
    "supplierName": "嘉兴某某加氢站",
    "type": "加氢站",
    "province": "浙江省",
    "city": "嘉兴市",
    "address": "浙江省嘉兴市南湖区科技大道1号",
    "region": "华东",
    "contact": "张三",
    "contactMobile": "13800138001",
    "contactPhone": "0571-88888888",
    "email": "zhangsan@example.com",
    "creditCodeOrId": "91330400MA2XXXXX1",
    "remark": "",
    "taxId": "91330400MA2XXXXX1",
    "invoiceAddress": "浙江省嘉兴市南湖区科技大道1号",
    "invoicePhone": "0571-88888888",
    "account": "6222021234567890123",
    "openingBank": "中国工商银行嘉兴分行",
    "mailingAddress": "浙江省嘉兴市南湖区科技大道1号",
    "creator": "admin",
    "createTime": "2025-01-10T09:30:00",
    "updater": "admin",
    "updateTime": "2025-01-10T09:30:00"
  },
  "msg": "操作成功"
}
```

#### 5. 分页查询供应商
```
GET /asset/supplier/page
权限: asset:supplier:query
```

**Query Parameters**
- `pageNo`: 页码（默认 1）
- `pageSize`: 每页数量（默认 10）
- `supplierCode`: 供应商编码（精确匹配）
- `coopStatus`: 合作状态列表（多选）
- `supplierName`: 供应商名称（模糊查询）
- `type`: 供应商类型列表（多选）
- `region`: 区域列表（多选）
- `city`: 城市（精确匹配）
- `creator`: 创建者（精确匹配）

**Response**
```json
{
  "code": 0,
  "data": {
    "list": [...],
    "total": 100
  },
  "msg": "操作成功"
}
```

## 📚 字典数据

### 合作状态 (coop_status)
- 已合作
- 终止合作
- 洽谈中
- 合约过期

### 供应商类型 (type)
- 备件供应商
- 保险公司
- 加氢站
- 充电站
- 维修站
- 救援车队
- 整车厂
- 其他

### 区域 (region)
- 华北
- 华东
- 华南
- 华中
- 东北
- 西南
- 西北

## ✅ 已完成工作

### 1. 数据库设计
- ✅ 创建 `asset_supplier` 表
- ✅ 设计合理的索引
- ✅ 添加菜单和权限配置

### 2. 后端代码
- ✅ DO (Data Object)
- ✅ Mapper
- ✅ VO (View Object)
- ✅ Convert (对象转换)
- ✅ Service 接口和实现
- ✅ Controller
- ✅ 错误码常量

### 3. 编译验证
- ✅ Maven 编译通过
- ✅ 无语法错误

### 4. 数据库初始化
- ✅ 供应商表创建成功（27 个字段）
- ✅ 菜单创建成功（ID: 5062）
- ✅ 5 个按钮权限创建成功

## 🔲 待完成工作

### 1. 导入导出功能
- 🔲 Excel 导入模板设计
- 🔲 Excel 导入功能实现
- 🔲 Excel 导出功能实现

### 2. 数据字典配置
- 🔲 在系统字典中配置合作状态
- 🔲 在系统字典中配置供应商类型

### 3. 前端开发
- 🔲 供应商列表页面
- 🔲 供应商新增页面
- 🔲 供应商编辑页面
- 🔲 供应商查看页面

### 4. 测试
- 🔲 单元测试
- 🔲 集成测试
- 🔲 API 接口测试

## 🎯 使用说明

### 启动服务
1. 确保数据库已初始化
2. 启动 `yudao-server` 应用
3. 访问 Swagger 文档: `http://localhost:48080/doc.html`

### API 测试
使用 Postman 或 Swagger UI 测试接口：
1. 先登录获取 token
2. 在请求头中添加 `Authorization: Bearer {token}`
3. 调用供应商管理接口

## 📝 注意事项

1. **供应商编码唯一性**: `supplier_code` 字段有唯一索引，不能重复
2. **手机号格式验证**: 使用正则表达式验证手机号格式
3. **邮箱格式验证**: 使用 `@Email` 注解验证邮箱格式
4. **软删除**: 使用 `deleted` 字段实现软删除，不会物理删除数据
5. **多租户**: 支持多租户隔离，通过 `tenant_id` 字段区分

## 🔗 相关模块

- 客户管理模块 (Customer)
- 车辆管理模块 (Vehicle)
- 停车场管理模块 (Parking)
- 车型参数管理模块 (VehicleModel)

---

**开发日期**: 2026-03-12
**开发人员**: AI Assistant
**版本**: v1.0.0