小程序首页配置

2026-08-14 12:41:18 +08:00
parent 889f987f17
commit 8b3cef5af0
21 changed files with 1350 additions and 3 deletions
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Http\Controllers\Client;
+
+use App\Exceptions\RepositoryException;
+use App\Http\Requests\Client\BannerFormRequest;
+use App\Models\HomeBannerModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Modules\AnnoRoute\Attribute\DeleteRoute;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+use Modules\Common\Http\Controllers\BaseController;
+use Modules\SystemTool\Services\SysFileService;
+
+/**
+ * 首页轮播图配置（小程序首页）
+ */
+#[RequestAttribute('/client/banner', 'client.banner')]
+class BannerController extends BaseController
+{
+    protected array $searchField = [
+        'status' => '=',
+    ];
+
+    protected array $quickSearchField = ['title'];
+
+    /** 轮播图列表（默认按排序升序） */
+    #[GetRoute(authorize: 'query')]
+    public function query(Request $request): JsonResponse
+    {
+        $params = $request->all();
+        $pageSize = $params['pageSize'] ?? 10;
+        $data = $this->buildSearch($params, HomeBannerModel::query())
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->paginate($pageSize)
+            ->toArray();
+        return $this->success($data);
+    }
+
+    /** 上传轮播图片（文件分组：客户端配置） */
+    #[PostRoute('/upload', 'create')]
+    public function uploadImage(Request $request, SysFileService $service): JsonResponse
+    {
+        $data = $request->validate(['file' => 'required|file']);
+        $result = $service->upload(
+            $data['file'],
+            12,
+            20,
+            Auth::id()
+        );
+        return $this->success($result);
+    }
+
+    /** 新增轮播图 */
+    #[PostRoute(authorize: 'create')]
+    public function create(BannerFormRequest $request): JsonResponse
+    {
+        HomeBannerModel::create($request->validated());
+        return $this->success();
+    }
+
+    /** 编辑轮播图 */
+    #[PutRoute(route: '/{id}', authorize: 'update', where: ['id' => '[0-9]+'])]
+    public function update(int $id, BannerFormRequest $request): JsonResponse
+    {
+        $model = HomeBannerModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('轮播图不存在');
+        }
+        $model->update($request->validated());
+        return $this->success();
+    }
+
+    /** 删除轮播图 */
+    #[DeleteRoute(route: '/{id}', authorize: 'delete', where: ['id' => '[0-9]+'])]
+    public function delete(int $id): JsonResponse
+    {
+        $model = HomeBannerModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('轮播图不存在');
+        }
+        $model->delete();
+        return $this->success();
+    }
+}
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Http\Controllers\Client;
+
+use App\Exceptions\RepositoryException;
+use App\Http\Requests\Client\NavFormRequest;
+use App\Models\HomeNavModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Modules\AnnoRoute\Attribute\DeleteRoute;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+use Modules\Common\Http\Controllers\BaseController;
+use Modules\SystemTool\Services\SysFileService;
+
+/**
+ * 宫格导航配置（小程序首页）
+ */
+#[RequestAttribute('/client/nav', 'client.nav')]
+class NavController extends BaseController
+{
+    protected array $searchField = [
+        'status' => '=',
+    ];
+
+    protected array $quickSearchField = ['name'];
+
+    /** 导航列表（默认按排序升序） */
+    #[GetRoute(authorize: 'query')]
+    public function query(Request $request): JsonResponse
+    {
+        $params = $request->all();
+        $pageSize = $params['pageSize'] ?? 10;
+        $data = $this->buildSearch($params, HomeNavModel::query())
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->paginate($pageSize)
+            ->toArray();
+        return $this->success($data);
+    }
+
+    /** 上传导航图标（文件分组：客户端配置） */
+    #[PostRoute('/upload', 'create')]
+    public function uploadImage(Request $request, SysFileService $service): JsonResponse
+    {
+        $data = $request->validate(['file' => 'required|file']);
+        $result = $service->upload(
+            $data['file'],
+            12,
+            20,
+            Auth::id()
+        );
+        return $this->success($result);
+    }
+
+    /** 新增导航 */
+    #[PostRoute(authorize: 'create')]
+    public function create(NavFormRequest $request): JsonResponse
+    {
+        HomeNavModel::create($request->validated());
+        return $this->success();
+    }
+
+    /** 编辑导航 */
+    #[PutRoute(route: '/{id}', authorize: 'update', where: ['id' => '[0-9]+'])]
+    public function update(int $id, NavFormRequest $request): JsonResponse
+    {
+        $model = HomeNavModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('导航不存在');
+        }
+        $model->update($request->validated());
+        return $this->success();
+    }
+
+    /** 删除导航 */
+    #[DeleteRoute(route: '/{id}', authorize: 'delete', where: ['id' => '[0-9]+'])]
+    public function delete(int $id): JsonResponse
+    {
+        $model = HomeNavModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('导航不存在');
+        }
+        $model->delete();
+        return $this->success();
+    }
+}
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Http\Controllers\Client;
+
+use App\Exceptions\RepositoryException;
+use App\Http\Requests\Client\PromoFormRequest;
+use App\Models\HomePromoModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Modules\AnnoRoute\Attribute\DeleteRoute;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+use Modules\Common\Http\Controllers\BaseController;
+use Modules\SystemTool\Services\SysFileService;
+
+/**
+ * 促销推荐卡片配置（小程序首页）
+ */
+#[RequestAttribute('/client/promo', 'client.promo')]
+class PromoController extends BaseController
+{
+    protected array $searchField = [
+        'status' => '=',
+    ];
+
+    protected array $quickSearchField = ['title', 'sub_title'];
+
+    /** 促销卡片列表（默认按排序升序） */
+    #[GetRoute(authorize: 'query')]
+    public function query(Request $request): JsonResponse
+    {
+        $params = $request->all();
+        $pageSize = $params['pageSize'] ?? 10;
+        $data = $this->buildSearch($params, HomePromoModel::query())
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->paginate($pageSize)
+            ->toArray();
+        return $this->success($data);
+    }
+
+    /** 上传卡片图片（文件分组：客户端配置） */
+    #[PostRoute('/upload', 'create')]
+    public function uploadImage(Request $request, SysFileService $service): JsonResponse
+    {
+        $data = $request->validate(['file' => 'required|file']);
+        $result = $service->upload(
+            $data['file'],
+            12,
+            20,
+            Auth::id()
+        );
+        return $this->success($result);
+    }
+
+    /** 新增促销卡片 */
+    #[PostRoute(authorize: 'create')]
+    public function create(PromoFormRequest $request): JsonResponse
+    {
+        HomePromoModel::create($request->validated());
+        return $this->success();
+    }
+
+    /** 编辑促销卡片 */
+    #[PutRoute(route: '/{id}', authorize: 'update', where: ['id' => '[0-9]+'])]
+    public function update(int $id, PromoFormRequest $request): JsonResponse
+    {
+        $model = HomePromoModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('促销卡片不存在');
+        }
+        $model->update($request->validated());
+        return $this->success();
+    }
+
+    /** 删除促销卡片 */
+    #[DeleteRoute(route: '/{id}', authorize: 'delete', where: ['id' => '[0-9]+'])]
+    public function delete(int $id): JsonResponse
+    {
+        $model = HomePromoModel::find($id);
+        if (empty($model)) {
+            throw new RepositoryException('促销卡片不存在');
+        }
+        $model->delete();
+        return $this->success();
+    }
+}
@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Models\HomeBannerModel;
+use App\Models\HomeNavModel;
+use App\Models\HomePromoModel;
+use Illuminate\Http\JsonResponse;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序首页配置（轮播图 + 宫格导航 + 促销推荐卡片，仅返回启用项）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class HomeController extends BaseMiniController
+{
+    /** 首页配置聚合：banners / navs / promos，按 sort 升序 */
+    #[GetRoute('/home', authorize: false)]
+    public function index(): JsonResponse
+    {
+        $banners = HomeBannerModel::query()
+            ->where('status', HomeBannerModel::STATUS_NORMAL)
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->get(['id', 'title', 'image_id', 'link', 'sort']);
+
+        $navs = HomeNavModel::query()
+            ->where('status', HomeNavModel::STATUS_NORMAL)
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->get(['id', 'name', 'image_id', 'link', 'sort']);
+
+        $promos = HomePromoModel::query()
+            ->where('status', HomePromoModel::STATUS_NORMAL)
+            ->orderBy('sort')
+            ->orderBy('id')
+            ->get(['id', 'title', 'sub_title', 'image_id', 'link', 'sort']);
+
+        return $this->success([
+            'banners' => $banners,
+            'navs' => $navs,
+            'promos' => $promos,
+        ]);
+    }
+}
@@ -57,10 +57,8 @@ class ProductController extends BaseMiniController

    /**
     * 商品列表：价格取当前门店客户等级价；
-     * 未绑定门店/门店未设客户等级 → 仍可浏览，price 为 null（不可见价格，加购/下单另由前置校验拦截）；
-     * ?category_id=&keyword=&page=&pageSize=
     */
-    #[GetRoute('/product/list', authorize: true)]
+    #[GetRoute('/product/list', authorize: false)]
    public function products(Request $request): JsonResponse
    {
        $user = $this->currentUser($request);
@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Http\Requests\Client;
+
+use Modules\Common\Http\Requests\BaseFormRequest;
+
+/**
+ * 首页轮播图 创建/编辑 验证
+ */
+class BannerFormRequest extends BaseFormRequest
+{
+    protected $stopOnFirstFailure = true;
+
+    public function rules(): array
+    {
+        return [
+            'title' => 'required|string|max:50',
+            'image_id' => 'required|integer|min:1',
+            'link' => 'nullable|string|max:255',
+            'sort' => 'nullable|integer|min:0',
+            'status' => 'required|integer|in:0,1',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'title.required' => '轮播图标题不能为空',
+            'title.max' => '轮播图标题最长 50 个字符',
+            'image_id.required' => '请上传轮播图片',
+            'link.max' => '跳转链接最长 255 个字符',
+            'status.in' => '状态只能是 0 或 1',
+        ];
+    }
+}
@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Http\Requests\Client;
+
+use Modules\Common\Http\Requests\BaseFormRequest;
+
+/**
+ * 宫格导航 创建/编辑 验证
+ */
+class NavFormRequest extends BaseFormRequest
+{
+    protected $stopOnFirstFailure = true;
+
+    public function rules(): array
+    {
+        return [
+            'name' => 'required|string|max:50',
+            'image_id' => 'required|integer|min:1',
+            'link' => 'nullable|string|max:255',
+            'sort' => 'nullable|integer|min:0',
+            'status' => 'required|integer|in:0,1',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'name.required' => '导航名称不能为空',
+            'name.max' => '导航名称最长 50 个字符',
+            'image_id.required' => '请上传导航图标',
+            'link.max' => '跳转链接最长 255 个字符',
+            'status.in' => '状态只能是 0 或 1',
+        ];
+    }
+}
@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Http\Requests\Client;
+
+use Modules\Common\Http\Requests\BaseFormRequest;
+
+/**
+ * 促销推荐卡片 创建/编辑 验证
+ */
+class PromoFormRequest extends BaseFormRequest
+{
+    protected $stopOnFirstFailure = true;
+
+    public function rules(): array
+    {
+        return [
+            'title' => 'nullable|string|max:50',
+            'sub_title' => 'nullable|string|max:100',
+            'image_id' => 'required|integer|min:1',
+            'link' => 'nullable|string|max:255',
+            'sort' => 'nullable|integer|min:0',
+            'status' => 'required|integer|in:0,1',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'title.required' => '卡片标题不能为空',
+            'title.max' => '卡片标题最长 50 个字符',
+            'sub_title.max' => '副标题最长 100 个字符',
+            'image_id.required' => '请上传卡片图片',
+            'link.max' => '跳转链接最长 255 个字符',
+            'status.in' => '状态只能是 0 或 1',
+        ];
+    }
+}
@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Modules\SystemTool\Models\SysFileModel;
+
+/**
+ * 小程序首页轮播图
+ */
+class HomeBannerModel extends Model
+{
+    /** 状态：停用 */
+    public const int STATUS_DISABLED = 0;
+    /** 状态：正常 */
+    public const int STATUS_NORMAL = 1;
+
+    protected $table = 'mini_home_banner';
+    protected $primaryKey = 'id';
+
+    protected $fillable = [
+        'title',
+        'image_id',
+        'link',
+        'sort',
+        'status',
+    ];
+
+    protected $casts = [
+        'image_id' => 'integer',
+        'sort' => 'integer',
+        'status' => 'integer',
+        'created_at' => 'datetime:Y-m-d H:i:s',
+        'updated_at' => 'datetime:Y-m-d H:i:s',
+    ];
+
+    protected $appends = ['image_url'];
+
+    protected $with = ['image'];
+
+    /**
+     * 关联图片
+     */
+    public function image(): HasOne
+    {
+        return $this->hasOne(SysFileModel::class, 'id', 'image_id');
+    }
+
+    /**
+     * 图片链接
+     */
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image?->preview_url;
+    }
+}
@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Modules\SystemTool\Models\SysFileModel;
+
+/**
+ * 小程序首页宫格导航
+ */
+class HomeNavModel extends Model
+{
+    /** 状态：停用 */
+    public const int STATUS_DISABLED = 0;
+    /** 状态：正常 */
+    public const int STATUS_NORMAL = 1;
+
+    protected $table = 'mini_home_nav';
+    protected $primaryKey = 'id';
+
+    protected $fillable = [
+        'name',
+        'image_id',
+        'link',
+        'sort',
+        'status',
+    ];
+
+    protected $casts = [
+        'image_id' => 'integer',
+        'sort' => 'integer',
+        'status' => 'integer',
+        'created_at' => 'datetime:Y-m-d H:i:s',
+        'updated_at' => 'datetime:Y-m-d H:i:s',
+    ];
+
+    protected $appends = ['image_url'];
+
+    protected $with = ['image'];
+
+    /**
+     * 关联图标
+     */
+    public function image(): HasOne
+    {
+        return $this->hasOne(SysFileModel::class, 'id', 'image_id');
+    }
+
+    /**
+     * 图标链接
+     */
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image?->preview_url;
+    }
+}
@@ -0,0 +1,58 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Modules\SystemTool\Models\SysFileModel;
+
+/**
+ * 小程序首页促销推荐卡片
+ */
+class HomePromoModel extends Model
+{
+    /** 状态：停用 */
+    public const int STATUS_DISABLED = 0;
+    /** 状态：正常 */
+    public const int STATUS_NORMAL = 1;
+
+    protected $table = 'mini_home_promo';
+    protected $primaryKey = 'id';
+
+    protected $fillable = [
+        'title',
+        'sub_title',
+        'image_id',
+        'link',
+        'sort',
+        'status',
+    ];
+
+    protected $casts = [
+        'image_id' => 'integer',
+        'sort' => 'integer',
+        'status' => 'integer',
+        'created_at' => 'datetime:Y-m-d H:i:s',
+        'updated_at' => 'datetime:Y-m-d H:i:s',
+    ];
+
+    protected $appends = ['image_url'];
+
+    protected $with = ['image'];
+
+    /**
+     * 关联图片
+     */
+    public function image(): HasOne
+    {
+        return $this->hasOne(SysFileModel::class, 'id', 'image_id');
+    }
+
+    /**
+     * 图片链接
+     */
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image?->preview_url;
+    }
+}
@@ -0,0 +1,76 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     * 小程序首页配置：轮播图 / 宫格导航 / 促销推荐卡片（后台维护图片、名称、跳转链接）
+     */
+    public function up(): void
+    {
+        if (! Schema::hasTable('mini_home_banner')) {
+            Schema::create('mini_home_banner', function (Blueprint $table) {
+                $table->increments('id')->comment('轮播图ID');
+                $table->string('title', 50)->nullable()->comment('标题');
+                $table->integer('image_id')->nullable()->default(0)->comment('轮播图片（sys_file ID）');
+                $table->string('link', 255)->nullable()->default('')->comment('小程序跳转链接（如 /pages/goods/detail?id=1）');
+                $table->integer('sort')->default(0)->comment('排序（越小越靠前）');
+                $table->integer('status')->default(1)->comment('状态（1正常 0停用）');
+                $table->timestamps();
+                $table->comment('小程序首页轮播图');
+            });
+        }
+
+        if (! Schema::hasTable('mini_home_nav')) {
+            Schema::create('mini_home_nav', function (Blueprint $table) {
+                $table->increments('id')->comment('导航ID');
+                $table->string('name', 50)->nullable()->comment('导航名称');
+                $table->integer('image_id')->nullable()->default(0)->comment('导航图标（sys_file ID）');
+                $table->string('link', 255)->nullable()->default('')->comment('小程序跳转链接');
+                $table->integer('sort')->default(0)->comment('排序（越小越靠前）');
+                $table->integer('status')->default(1)->comment('状态（1正常 0停用）');
+                $table->timestamps();
+                $table->comment('小程序首页宫格导航');
+            });
+        }
+
+        if (! Schema::hasTable('mini_home_promo')) {
+            Schema::create('mini_home_promo', function (Blueprint $table) {
+                $table->increments('id')->comment('卡片ID');
+                $table->string('title', 50)->nullable()->comment('卡片标题');
+                $table->string('sub_title', 100)->nullable()->default('')->comment('副标题/促销文案');
+                $table->integer('image_id')->nullable()->default(0)->comment('卡片图片（sys_file ID）');
+                $table->string('link', 255)->nullable()->default('')->comment('小程序跳转链接');
+                $table->integer('sort')->default(0)->comment('排序（越小越靠前）');
+                $table->integer('status')->default(1)->comment('状态（1正常 0停用）');
+                $table->timestamps();
+                $table->comment('小程序首页促销推荐卡片');
+            });
+        }
+
+        // 文件分组：客户端配置图片（幂等，已有库补充分组记录）
+        DB::table('sys_file_group')->insertOrIgnore([
+            'id' => 12,
+            'name' => '客户端配置',
+            'sort' => 11,
+            'describe' => '小程序首页轮播图/宫格导航/促销卡片图片',
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('mini_home_promo');
+        Schema::dropIfExists('mini_home_nav');
+        Schema::dropIfExists('mini_home_banner');
+    }
+};
@@ -264,6 +264,50 @@ class PermissionSeeder extends Seeder
                    ],
                ],
            ],
+            [
+                'type' => 'menu',
+                'key' => 'procurement.client',
+                'name' => '客户端配置',
+                'icon' => 'MobileOutlined',
+                'children' => [
+                    [
+                        'type' => 'route',
+                        'key' => 'client.banner',
+                        'name' => '首页轮播图',
+                        'path' => '/client/banner',
+                        'children' => [
+                            ['type' => 'rule', 'key' => 'client.banner.query', 'name' => '查询'],
+                            ['type' => 'rule', 'key' => 'client.banner.create', 'name' => '新增'],
+                            ['type' => 'rule', 'key' => 'client.banner.update', 'name' => '编辑'],
+                            ['type' => 'rule', 'key' => 'client.banner.delete', 'name' => '删除'],
+                        ],
+                    ],
+                    [
+                        'type' => 'route',
+                        'key' => 'client.nav',
+                        'name' => '宫格导航',
+                        'path' => '/client/nav',
+                        'children' => [
+                            ['type' => 'rule', 'key' => 'client.nav.query', 'name' => '查询'],
+                            ['type' => 'rule', 'key' => 'client.nav.create', 'name' => '新增'],
+                            ['type' => 'rule', 'key' => 'client.nav.update', 'name' => '编辑'],
+                            ['type' => 'rule', 'key' => 'client.nav.delete', 'name' => '删除'],
+                        ],
+                    ],
+                    [
+                        'type' => 'route',
+                        'key' => 'client.promo',
+                        'name' => '促销推荐卡片',
+                        'path' => '/client/promo',
+                        'children' => [
+                            ['type' => 'rule', 'key' => 'client.promo.query', 'name' => '查询'],
+                            ['type' => 'rule', 'key' => 'client.promo.create', 'name' => '新增'],
+                            ['type' => 'rule', 'key' => 'client.promo.update', 'name' => '编辑'],
+                            ['type' => 'rule', 'key' => 'client.promo.delete', 'name' => '删除'],
+                        ],
+                    ],
+                ],
+            ],
            [
                'type' => 'menu',
                'name' => 'AI',
@@ -70,6 +70,7 @@ class SysDataSeeder extends Seeder
            ['id' => 9, 'name' => '分类图片', 'sort' => 8, 'describe' => '存放商品分类图标', 'created_at' => $date, 'updated_at' => $date],
            ['id' => 10, 'name' => '商品封面图片', 'sort' => 9, 'describe' => '存放商品封面图片', 'created_at' => $date, 'updated_at' => $date],
            ['id' => 11, 'name' => '商品详情图片', 'sort' => 10, 'describe' => '存放商品详情图片', 'created_at' => $date, 'updated_at' => $date],
+            ['id' => 12, 'name' => '客户端配置', 'sort' => 11, 'describe' => '小程序首页轮播图/宫格导航/促销卡片图片', 'created_at' => $date, 'updated_at' => $date],
        ]);
    }
 }
@@ -0,0 +1,172 @@
+# 小程序首页接口文档
+
+> 适用端：微信小程序（h5 仓库，Taro）
+> 后台配置入口：PC 后台「客户端配置」菜单（首页轮播图 / 宫格导航 / 促销推荐卡片）
+> 更新日期：2026-08-14
+
+## 通用约定
+
+| 项 | 说明 |
+|---|---|
+| 根地址 | `BASE_URL`（见 `src/utils/request.ts`，如 `http://localhost:8000/index.php`） |
+| 认证 | 请求头 `Authorization: Bearer {token}`，token 来自登录接口，本地存储 key `auth_token` |
+| 响应包络 | `{ success: boolean, data: T, msg?: string, showType?: number }` |
+| 失败处理 | `success=false` 时 `msg` 为中文错误信息；HTTP 401 表示登录过期，需重新登录 |
+
+## GET /mini/home
+
+首页配置聚合接口：一次返回轮播图、宫格导航、促销推荐卡片三组数据，均为**启用状态（status=1）**且按 `sort` 升序（越小越靠前）。
+
+- **权限**：需登录（Bearer token）
+- **请求参数**：无
+
+### 响应示例
+
+```json
+{
+  "success": true,
+  "msg": "ok",
+  "data": {
+    "banners": [
+      {
+        "id": 1,
+        "title": "新鲜直采",
+        "image_id": 123,
+        "link": "/pages/goods/detail?id=1",
+        "sort": 0,
+        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/xxx.jpg"
+      }
+    ],
+    "navs": [
+      {
+        "id": 1,
+        "name": "蔬菜专区",
+        "image_id": 124,
+        "link": "/pages/category/index?id=1",
+        "sort": 0,
+        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/yyy.png"
+      }
+    ],
+    "promos": [
+      {
+        "id": 1,
+        "title": "限时特惠",
+        "sub_title": "全场 8 折起",
+        "image_id": 125,
+        "link": "/pages/promo/detail?id=1",
+        "sort": 0,
+        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/zzz.jpg"
+      }
+    ]
+  }
+}
+```
+
+### 字段说明
+
+**banners（轮播图）**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | number | 轮播图 ID |
+| title | string | 标题（后台维护，可用于无障碍/占位） |
+| image_id | number | 图片文件 ID（sys_file），一般无需使用 |
+| **image_url** | string \| null | 轮播图片完整 URL，直接用于 `<Image src>`；未传图时为 null |
+| link | string | 小程序页面跳转路径，**空字符串表示点击不跳转** |
+| sort | number | 排序值（已按此升序返回，前端无需再排） |
+
+**navs（宫格导航）**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | number | 导航 ID |
+| name | string | 导航名称（宫格文字） |
+| **image_url** | string \| null | 导航图标完整 URL |
+| link | string | 小程序页面跳转路径，空字符串不跳转 |
+| sort | number | 排序值 |
+
+**promos（促销推荐卡片）**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | number | 卡片 ID |
+| title | string | 卡片标题 |
+| sub_title | string | 副标题/促销文案，可能为空字符串 |
+| **image_url** | string \| null | 卡片图片完整 URL |
+| link | string | 小程序页面跳转路径，空字符串不跳转 |
+| sort | number | 排序值 |
+
+### 前端接入示例
+
+`src/services/home.ts`（新增）：
+
+```ts
+import { get } from '@/utils/request'
+
+/** 首页轮播图项 */
+export interface HomeBanner {
+  id: number
+  title: string
+  image_id: number
+  image_url: string | null
+  link: string
+  sort: number
+}
+
+/** 首页宫格导航项 */
+export interface HomeNav {
+  id: number
+  name: string
+  image_id: number
+  image_url: string | null
+  link: string
+  sort: number
+}
+
+/** 首页促销推荐卡片 */
+export interface HomePromo {
+  id: number
+  title: string
+  sub_title: string
+  image_id: number
+  image_url: string | null
+  link: string
+  sort: number
+}
+
+/** 首页配置聚合数据 */
+export interface HomeConfig {
+  banners: HomeBanner[]
+  navs: HomeNav[]
+  promos: HomePromo[]
+}
+
+/** 首页配置（轮播图 + 宫格导航 + 促销卡片）：GET /mini/home */
+export function getHomeConfigApi() {
+  return get<HomeConfig>('/mini/home')
+}
+```
+
+页面中使用（跳转需兼容空链接）：
+
+```tsx
+const [config, setConfig] = useState<HomeConfig>({ banners: [], navs: [], promos: [] })
+
+useEffect(() => {
+  getHomeConfigApi().then(res => setConfig(res.data))
+}, [])
+
+/** 统一跳转：link 为空不跳转 */
+function handleLink(link: string) {
+  if (!link) return
+  Taro.navigateTo({ url: link })
+}
+```
+
+### 注意事项
+
+1. **三组数据均可能为空数组**（后台未配置或全部停用），页面需做空态处理。
+2. `image_url` 可能为 `null`（后台未上传图片），渲染前判空。
+3. `link` 为小程序内部页面路径（以 `/` 开头），用 `Taro.navigateTo` 跳转；若目标为 tabBar 页面需改用 `Taro.switchTab`（建议后台配置时避免填 tabBar 路径）。
+4. 数据实时生效：后台修改后，小程序下次进入首页请求即为最新内容，无缓存。
+5. 接口需登录后调用；未登录（401）会由 request 封装自动跳登录页。
@@ -0,0 +1,20 @@
+import type {ISysFileInfo} from "@/domain/iSysFile.ts";
+
+/** 小程序首页轮播图 */
+export default interface IHomeBanner {
+  id?: number;
+  title?: string;
+  image_id?: number;
+  image?: ISysFileInfo;
+  image_url?: string;
+  link?: string;
+  sort?: number;
+  status?: number;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export const HOME_BANNER_STATUS_MAP: Record<number, { text: string; color: string }> = {
+  0: { text: '停用', color: 'error' },
+  1: { text: '正常', color: 'success' },
+};
@@ -0,0 +1,20 @@
+import type {ISysFileInfo} from "@/domain/iSysFile.ts";
+
+/** 小程序首页宫格导航 */
+export default interface IHomeNav {
+  id?: number;
+  name?: string;
+  image_id?: number;
+  image?: ISysFileInfo;
+  image_url?: string;
+  link?: string;
+  sort?: number;
+  status?: number;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export const HOME_NAV_STATUS_MAP: Record<number, { text: string; color: string }> = {
+  0: { text: '停用', color: 'error' },
+  1: { text: '正常', color: 'success' },
+};
@@ -0,0 +1,21 @@
+import type {ISysFileInfo} from "@/domain/iSysFile.ts";
+
+/** 小程序首页促销推荐卡片 */
+export default interface IHomePromo {
+  id?: number;
+  title?: string;
+  sub_title?: string;
+  image_id?: number;
+  image?: ISysFileInfo;
+  image_url?: string;
+  link?: string;
+  sort?: number;
+  status?: number;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export const HOME_PROMO_STATUS_MAP: Record<number, { text: string; color: string }> = {
+  0: { text: '停用', color: 'error' },
+  1: { text: '正常', color: 'success' },
+};
@@ -0,0 +1,131 @@
+import React from 'react';
+import { Image, Tag, Typography } from 'antd';
+import XinTable from '@/components/XinTable';
+import type { XinTableColumn, XinTableProps } from '@/components/XinTable/typings.ts';
+import type IHomeBanner from '@/domain/iHomeBanner.ts';
+import { HOME_BANNER_STATUS_MAP } from '@/domain/iHomeBanner.ts';
+
+const { Title, Text } = Typography;
+
+/**
+ * 首页轮播图配置（小程序首页）
+ */
+const HomeBannerPage: React.FC = () => {
+  const columns: XinTableColumn<IHomeBanner>[] = [
+    {
+      title: 'ID',
+      dataIndex: 'id',
+      hideInForm: true,
+      hideInSearch: true,
+      width: 70,
+      align: 'center',
+    },
+    {
+      title: '标题',
+      dataIndex: 'title',
+      valueType: 'text',
+      required: true,
+      rules: [{ required: true, message: '请输入轮播图标题' }],
+    },
+    {
+      title: '轮播图片',
+      dataIndex: 'image_id',
+      valueType: 'image',
+      required: true,
+      rules: [{ required: true, message: '请上传轮播图片' }],
+      fieldProps: {
+        action: '/client/banner/upload',
+        mode: 'single',
+        maxCount: 1,
+        changeType: 'id',
+      },
+      render: (_, record: IHomeBanner) => {
+        const url = record.image_url;
+        if (!url) return '-';
+        return (
+          <Image
+            src={url}
+            width={80}
+            height={40}
+            style={{ objectFit: 'cover', borderRadius: 4 }}
+          />
+        );
+      },
+      align: 'center',
+      hideInSearch: true,
+    },
+    {
+      title: '跳转链接',
+      dataIndex: 'link',
+      valueType: 'text',
+      hideInSearch: true,
+      fieldProps: {
+        placeholder: '小程序页面路径，如 /pages/goods/detail?id=1',
+      },
+      render: (_, record) => record.link || '-',
+    },
+    {
+      title: '排序',
+      dataIndex: 'sort',
+      valueType: 'digit',
+      hideInSearch: true,
+      initialValue: 0,
+      fieldProps: { min: 0, precision: 0 },
+      align: 'center',
+      width: 80,
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      valueType: 'radioButton',
+      initialValue: 1,
+      fieldProps: {
+        options: [
+          { value: 1, label: '正常' },
+          { value: 0, label: '停用' },
+        ],
+      },
+      render: (_, record) => {
+        const item = HOME_BANNER_STATUS_MAP[record.status ?? 1];
+        return <Tag color={item?.color}>{item?.text}</Tag>;
+      },
+      align: 'center',
+      width: 90,
+    },
+    {
+      title: '创建时间',
+      dataIndex: 'created_at',
+      hideInForm: true,
+      hideInSearch: true,
+      align: 'center',
+    },
+  ];
+
+  const tableProps: XinTableProps<IHomeBanner> = {
+    api: '/client/banner',
+    columns,
+    rowKey: 'id',
+    accessName: 'client.banner',
+    formProps: {
+      grid: true,
+      colProps: { span: 12 },
+      layout: 'vertical',
+      rowProps: { gutter: 24 },
+    },
+    modalProps: { width: 640 },
+  };
+
+  return (
+    <>
+      <div className="mb-5">
+        <Title level={3}>首页轮播图</Title>
+        <Text type="secondary">
+          小程序首页顶部轮播图；停用后不展示，排序越小越靠前；跳转链接为小程序页面路径，留空则点击不跳转。
+        </Text>
+      </div>
+      <XinTable<IHomeBanner> {...tableProps} />
+    </>
+  );
+};
+
+export default HomeBannerPage;
@@ -0,0 +1,131 @@
+import React from 'react';
+import { Image, Tag, Typography } from 'antd';
+import XinTable from '@/components/XinTable';
+import type { XinTableColumn, XinTableProps } from '@/components/XinTable/typings.ts';
+import type IHomeNav from '@/domain/iHomeNav.ts';
+import { HOME_NAV_STATUS_MAP } from '@/domain/iHomeNav.ts';
+
+const { Title, Text } = Typography;
+
+/**
+ * 宫格导航配置（小程序首页）
+ */
+const HomeNavPage: React.FC = () => {
+  const columns: XinTableColumn<IHomeNav>[] = [
+    {
+      title: 'ID',
+      dataIndex: 'id',
+      hideInForm: true,
+      hideInSearch: true,
+      width: 70,
+      align: 'center',
+    },
+    {
+      title: '导航名称',
+      dataIndex: 'name',
+      valueType: 'text',
+      required: true,
+      rules: [{ required: true, message: '请输入导航名称' }],
+    },
+    {
+      title: '导航图标',
+      dataIndex: 'image_id',
+      valueType: 'image',
+      required: true,
+      rules: [{ required: true, message: '请上传导航图标' }],
+      fieldProps: {
+        action: '/client/nav/upload',
+        mode: 'single',
+        maxCount: 1,
+        changeType: 'id',
+      },
+      render: (_, record: IHomeNav) => {
+        const url = record.image_url;
+        if (!url) return '-';
+        return (
+          <Image
+            src={url}
+            width={40}
+            height={40}
+            style={{ objectFit: 'cover', borderRadius: 4 }}
+          />
+        );
+      },
+      align: 'center',
+      hideInSearch: true,
+    },
+    {
+      title: '跳转链接',
+      dataIndex: 'link',
+      valueType: 'text',
+      hideInSearch: true,
+      fieldProps: {
+        placeholder: '小程序页面路径，如 /pages/category/index',
+      },
+      render: (_, record) => record.link || '-',
+    },
+    {
+      title: '排序',
+      dataIndex: 'sort',
+      valueType: 'digit',
+      hideInSearch: true,
+      initialValue: 0,
+      fieldProps: { min: 0, precision: 0 },
+      align: 'center',
+      width: 80,
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      valueType: 'radioButton',
+      initialValue: 1,
+      fieldProps: {
+        options: [
+          { value: 1, label: '正常' },
+          { value: 0, label: '停用' },
+        ],
+      },
+      render: (_, record) => {
+        const item = HOME_NAV_STATUS_MAP[record.status ?? 1];
+        return <Tag color={item?.color}>{item?.text}</Tag>;
+      },
+      align: 'center',
+      width: 90,
+    },
+    {
+      title: '创建时间',
+      dataIndex: 'created_at',
+      hideInForm: true,
+      hideInSearch: true,
+      align: 'center',
+    },
+  ];
+
+  const tableProps: XinTableProps<IHomeNav> = {
+    api: '/client/nav',
+    columns,
+    rowKey: 'id',
+    accessName: 'client.nav',
+    formProps: {
+      grid: true,
+      colProps: { span: 12 },
+      layout: 'vertical',
+      rowProps: { gutter: 24 },
+    },
+    modalProps: { width: 640 },
+  };
+
+  return (
+    <>
+      <div className="mb-5">
+        <Title level={3}>宫格导航</Title>
+        <Text type="secondary">
+          小程序首页宫格入口（如商品分类、促销活动等）；停用后不展示，排序越小越靠前。
+        </Text>
+      </div>
+      <XinTable<IHomeNav> {...tableProps} />
+    </>
+  );
+};
+
+export default HomeNavPage;
@@ -0,0 +1,138 @@
+import React from 'react';
+import { Image, Tag, Typography } from 'antd';
+import XinTable from '@/components/XinTable';
+import type { XinTableColumn, XinTableProps } from '@/components/XinTable/typings.ts';
+import type IHomePromo from '@/domain/iHomePromo.ts';
+import { HOME_PROMO_STATUS_MAP } from '@/domain/iHomePromo.ts';
+
+const { Title, Text } = Typography;
+
+/**
+ * 促销推荐卡片配置（小程序首页）
+ */
+const HomePromoPage: React.FC = () => {
+  const columns: XinTableColumn<IHomePromo>[] = [
+    {
+      title: 'ID',
+      dataIndex: 'id',
+      hideInForm: true,
+      hideInSearch: true,
+      width: 70,
+      align: 'center',
+    },
+    {
+      title: '卡片标题',
+      dataIndex: 'title',
+      valueType: 'text',
+    },
+    {
+      title: '副标题',
+      dataIndex: 'sub_title',
+      valueType: 'text',
+      hideInSearch: true,
+      fieldProps: {
+        placeholder: '促销文案，如「限时特惠 8 折起」',
+      },
+      render: (_, record) => record.sub_title || '-',
+    },
+    {
+      title: '卡片图片',
+      dataIndex: 'image_id',
+      valueType: 'image',
+      required: true,
+      rules: [{ required: true, message: '请上传卡片图片' }],
+      fieldProps: {
+        action: '/client/promo/upload',
+        mode: 'single',
+        maxCount: 1,
+        changeType: 'id',
+      },
+      render: (_, record: IHomePromo) => {
+        const url = record.image_url;
+        if (!url) return '-';
+        return (
+          <Image
+            src={url}
+            width={80}
+            height={40}
+            style={{ objectFit: 'cover', borderRadius: 4 }}
+          />
+        );
+      },
+      align: 'center',
+      hideInSearch: true,
+    },
+    {
+      title: '跳转链接',
+      dataIndex: 'link',
+      valueType: 'text',
+      hideInSearch: true,
+      fieldProps: {
+        placeholder: '小程序页面路径，如 /pages/promo/detail?id=1',
+      },
+      render: (_, record) => record.link || '-',
+    },
+    {
+      title: '排序',
+      dataIndex: 'sort',
+      valueType: 'digit',
+      hideInSearch: true,
+      initialValue: 0,
+      fieldProps: { min: 0, precision: 0 },
+      align: 'center',
+      width: 80,
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      valueType: 'radioButton',
+      initialValue: 1,
+      fieldProps: {
+        options: [
+          { value: 1, label: '正常' },
+          { value: 0, label: '停用' },
+        ],
+      },
+      render: (_, record) => {
+        const item = HOME_PROMO_STATUS_MAP[record.status ?? 1];
+        return <Tag color={item?.color}>{item?.text}</Tag>;
+      },
+      align: 'center',
+      width: 90,
+    },
+    {
+      title: '创建时间',
+      dataIndex: 'created_at',
+      hideInForm: true,
+      hideInSearch: true,
+      align: 'center',
+    },
+  ];
+
+  const tableProps: XinTableProps<IHomePromo> = {
+    api: '/client/promo',
+    columns,
+    rowKey: 'id',
+    accessName: 'client.promo',
+    formProps: {
+      grid: true,
+      colProps: { span: 12 },
+      layout: 'vertical',
+    },
+    modalProps: { width: 640 },
+  };
+
+  return (
+    <>
+      <div className="mb-5">
+        <Title level={3}>促销推荐卡片</Title>
+        <Text type="secondary">
+          小程序首页促销位卡片；副标题展示促销文案，停用后不展示，排序越小越靠前。
+        </Text>
+      </div>
+      <XinTable<IHomePromo> {...tableProps} />
+    </>
+  );
+};
+
+export default HomePromoPage;