|
|
@@ -0,0 +1,252 @@
|
|
|
+# Longyi Wholesale Module
|
|
|
+
|
|
|
+一个用于 Bagisto 的批发询盘(Wholesale)模块,对应 `asteriahair.com/wholesale` 的询盘功能。前端用户通过 API 提交批发询盘,后台管理员在 Sales 菜单下查看和管理这些询盘记录。
|
|
|
+
|
|
|
+## 功能特性
|
|
|
+
|
|
|
+- ✅ 前台公开 API 提交询盘(无需登录)
|
|
|
+- ✅ 询盘字段校验(姓名、邮箱必填)
|
|
|
+- ✅ 中英文提示文案
|
|
|
+- ✅ 后台 Sales 菜单新增「批发询盘」目录
|
|
|
+- ✅ 后台询盘列表(DataGrid:搜索 / 排序 / 分页)
|
|
|
+- ✅ 后台删除询盘记录
|
|
|
+- ✅ 基于角色的权限控制(ACL)
|
|
|
+
|
|
|
+## 目录结构
|
|
|
+
|
|
|
+```
|
|
|
+Longyi/Wholesale/
|
|
|
+├── src/
|
|
|
+│ ├── Config/
|
|
|
+│ │ ├── admin-menu.php # 后台菜单(sales.wholesale)
|
|
|
+│ │ └── acl.php # 权限配置
|
|
|
+│ ├── Database/
|
|
|
+│ │ └── Migrations/ # message 表迁移
|
|
|
+│ ├── DataGrids/
|
|
|
+│ │ └── MessageDataGrid.php # 后台列表
|
|
|
+│ ├── Helpers/
|
|
|
+│ │ └── ApiResponse.php # 统一 API 返回格式
|
|
|
+│ ├── Http/Controllers/
|
|
|
+│ │ ├── Admin/WholesaleController.php # 后台控制器
|
|
|
+│ │ └── WholesaleController.php # 前台 API 控制器
|
|
|
+│ ├── Models/
|
|
|
+│ │ └── Message.php # 询盘模型
|
|
|
+│ ├── Providers/
|
|
|
+│ │ └── WholesaleServiceProvider.php
|
|
|
+│ ├── Resources/
|
|
|
+│ │ ├── lang/{en,zh_CN}/app.php # 中英文文案
|
|
|
+│ │ └── views/admin/index.blade.php
|
|
|
+│ └── Routes/
|
|
|
+│ ├── admin-routes.php # 后台路由
|
|
|
+│ └── shop-routes.php # 前台 API 路由
|
|
|
+```
|
|
|
+
|
|
|
+## 安装步骤
|
|
|
+
|
|
|
+### 1. 确认插件已注册
|
|
|
+
|
|
|
+`bootstrap/providers.php` 中已添加:
|
|
|
+
|
|
|
+```php
|
|
|
+Longyi\Wholesale\Providers\WholesaleServiceProvider::class,
|
|
|
+```
|
|
|
+
|
|
|
+`composer.json` 的 `autoload.psr-4` 中已添加命名空间映射:
|
|
|
+
|
|
|
+```json
|
|
|
+"Longyi\\Wholesale\\": "packages/Longyi/Wholesale/src/"
|
|
|
+```
|
|
|
+
|
|
|
+### 2. 生成自动加载
|
|
|
+
|
|
|
+```bash
|
|
|
+composer dump-autoload
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 运行数据库迁移
|
|
|
+
|
|
|
+```bash
|
|
|
+php artisan migrate
|
|
|
+```
|
|
|
+
|
|
|
+这将创建 `message` 表,用于存储批发询盘记录。
|
|
|
+
|
|
|
+### 4. 清理缓存
|
|
|
+
|
|
|
+```bash
|
|
|
+php artisan config:clear
|
|
|
+php artisan route:clear
|
|
|
+php artisan view:clear
|
|
|
+```
|
|
|
+
|
|
|
+### 5. 配置后台角色权限
|
|
|
+
|
|
|
+首次使用需要到后台 **设置 → 角色** 中,为管理员角色勾选以下权限,否则侧边栏不显示「批发询盘」菜单:
|
|
|
+
|
|
|
+- `sales.wholesale` —— 查看批发询盘列表
|
|
|
+- `sales.wholesale.delete` —— 删除询盘记录
|
|
|
+
|
|
|
+## 数据表结构
|
|
|
+
|
|
|
+`message` 表:
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| `message_id` | int unsigned PK, auto increment | 主键 |
|
|
|
+| `name` | varchar(200) | 姓名 |
|
|
|
+| `Email` | varchar(50) | 邮箱 |
|
|
|
+| `number` | varchar(300) | 联系方式 |
|
|
|
+| `message` | varchar(600) | 留言内容 |
|
|
|
+| `country` | varchar(50) | 国家 |
|
|
|
+| `created_at` | timestamp | 提交时间 |
|
|
|
+| `business_name` | varchar(300) | 公司名称 |
|
|
|
+| `business_role` | varchar(50) | 公司角色 |
|
|
|
+
|
|
|
+> 注意:表的主键为 `message_id`(非 `id`),且只有 `created_at` 字段(无 `updated_at`),模型已做相应适配(`$timestamps = false`)。
|
|
|
+
|
|
|
+## 前端 API
|
|
|
+
|
|
|
+### 提交批发询盘
|
|
|
+
|
|
|
+**请求:**
|
|
|
+
|
|
|
+```http
|
|
|
+POST /api/wholesale
|
|
|
+Content-Type: application/json
|
|
|
+```
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "John Doe",
|
|
|
+ "email": "john@example.com",
|
|
|
+ "number": "+1 234 567 8900",
|
|
|
+ "message": "I'm interested in your wholesale products.",
|
|
|
+ "country": "United States",
|
|
|
+ "business_name": "ABC Trading Co.",
|
|
|
+ "business_role": "Distributor"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**字段说明:**
|
|
|
+
|
|
|
+| 字段 | 必填 | 类型 | 长度限制 |
|
|
|
+|------|:---:|------|:---:|
|
|
|
+| `name` | ✅ | string | 200 |
|
|
|
+| `email` | ✅ | email | 50 |
|
|
|
+| `number` | ❌ | string | 300 |
|
|
|
+| `message` | ❌ | string | 600 |
|
|
|
+| `country` | ❌ | string | 50 |
|
|
|
+| `business_name` | ❌ | string | 300 |
|
|
|
+| `business_role` | ❌ | string | 50 |
|
|
|
+
|
|
|
+**成功响应:**
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "message": "您的询盘已提交成功。",
|
|
|
+ "data": {
|
|
|
+ "id": 1
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**失败响应:**
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": false,
|
|
|
+ "message": "错误信息",
|
|
|
+ "data": []
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 统一返回格式
|
|
|
+
|
|
|
+本模块的 API 统一使用 `Longyi\Wholesale\Helpers\ApiResponse` 返回,格式与 `RewardPoints` 模块一致:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "success": true,
|
|
|
+ "message": "Success",
|
|
|
+ "data": {}
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+支持的静态方法:
|
|
|
+
|
|
|
+| 方法 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `ApiResponse::success($data, $message, $code)` | 成功响应(默认 200) |
|
|
|
+| `ApiResponse::paginated($data, $paginator, $message, $code)` | 带分页的成功响应 |
|
|
|
+| `ApiResponse::error($message, $data, $code)` | 错误响应(默认 400) |
|
|
|
+| `ApiResponse::unauthorized($message)` | 未授权响应(401) |
|
|
|
+| `ApiResponse::validationError($message, $errors)` | 验证错误响应(422) |
|
|
|
+
|
|
|
+## 后台管理
|
|
|
+
|
|
|
+### 访问入口
|
|
|
+
|
|
|
+后台侧边栏 **Sales → 批发询盘(Wholesale)**,路由:
|
|
|
+
|
|
|
+```
|
|
|
+GET /admin/sales/wholesale # 询盘列表
|
|
|
+DELETE /admin/sales/wholesale/{id} # 删除询盘
|
|
|
+```
|
|
|
+
|
|
|
+### 列表功能
|
|
|
+
|
|
|
+- 列表展示:ID、姓名、邮箱、联系方式、公司名称、公司角色、国家、留言内容、提交时间
|
|
|
+- 支持按姓名 / 邮箱 / 联系方式 / 公司名称 / 留言内容搜索
|
|
|
+- 支持按 ID、时间等排序、分页
|
|
|
+- 支持删除单条询盘记录(需 `sales.wholesale.delete` 权限)
|
|
|
+
|
|
|
+## JavaScript / Fetch 使用示例
|
|
|
+
|
|
|
+```javascript
|
|
|
+async function submitWholesaleEnquiry(formData) {
|
|
|
+ try {
|
|
|
+ const response = await fetch('/api/wholesale', {
|
|
|
+ method: 'POST',
|
|
|
+ headers: {
|
|
|
+ 'Content-Type': 'application/json',
|
|
|
+ 'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content,
|
|
|
+ },
|
|
|
+ body: JSON.stringify({
|
|
|
+ name: formData.name,
|
|
|
+ email: formData.email,
|
|
|
+ number: formData.number,
|
|
|
+ message: formData.message,
|
|
|
+ country: formData.country,
|
|
|
+ business_name: formData.business_name,
|
|
|
+ business_role: formData.business_role,
|
|
|
+ }),
|
|
|
+ });
|
|
|
+
|
|
|
+ const data = await response.json();
|
|
|
+
|
|
|
+ if (data.success) {
|
|
|
+ console.log('提交成功:', data.data);
|
|
|
+ return data.data;
|
|
|
+ } else {
|
|
|
+ console.error('提交失败:', data.message);
|
|
|
+ }
|
|
|
+ } catch (error) {
|
|
|
+ console.error('错误:', error);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 依赖要求
|
|
|
+
|
|
|
+- PHP >= 8.2
|
|
|
+- Laravel >= 11.0
|
|
|
+- Bagisto 2.x
|
|
|
+
|
|
|
+## 许可证
|
|
|
+
|
|
|
+MIT License
|
|
|
+
|
|
|
+## 作者
|
|
|
+
|
|
|
+Longyi Team <dev@longyi.com>
|