Initial commit

app/mzl/common/services/BaseService.php

@@ -0,0 +1,198 @@
+<?php
+
+namespace app\mzl\common\services;
+
+use app\mzl\common\utils\SimpleQueryBuilder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Collection;
+
+/**
+ * 通用基础服务类 BaseService
+ */
+abstract class BaseService
+{
+    /**
+     * Eloquent 模型实例
+     * @var Model
+     */
+    protected Model $model;
+
+    /**
+     * 允许的字段列表
+     */
+    protected $allowedFields = [];
+
+    // 声明需要多语言翻译
+    protected array $translatable = [];
+
+    /**
+     * 从$data中提取出源文本字段，并从$data里删除它们
+     */
+    protected function extractSourceFields(array &$data): array
+    {
+        $source = [];
+        foreach ($this->translatable as $field) {
+            if (array_key_exists($field, $data)) {
+                $source[$field] = $data[$field];
+                unset($data[$field]);
+            }
+        }
+        return $source;
+    }
+
+    /**
+     * 子类必须实现：返回模型类名
+     *
+     * @return string 模型类名
+     */
+    abstract public function getModel(): string;
+
+    /**
+     * 构造函数，初始化模型实例
+     */
+    public function __construct()
+    {
+        $this->model = new ($this->getModel());
+    }
+
+    /**
+     * 子类定义：场景化查询配置
+     * 返回一个关联数组，键为场景名称，值为查询配置数组或闭包
+     *
+     * @return array<string, array|\Closure> 查询配置数组或闭包
+     */
+    public function queryScenes(): array
+    {
+        return [];
+    }
+
+    /**
+     * 根据场景和请求参数，取到完整的 Builder 配置
+     *
+     * @param array $params 请求参数
+     * @param string $scene 场景名称
+     * @return array 查询配置数组
+     */
+    protected function getQueryConfig(array $params, string $scene): array
+    {
+        $scenes = $this->queryScenes();
+        $cfg    = $scenes[$scene] ?? [];
+        return is_callable($cfg) ? $cfg($params) : $cfg;
+    }
+
+    /**
+     * 构造Builder
+     */
+    protected function createQueryBuilder(array $params, string $scene): SimpleQueryBuilder
+    {
+        $config  = $this->getQueryConfig($params, $scene);
+        return (new SimpleQueryBuilder($this->model))->applyQueryConfig($config);
+    }
+
+    /**
+     * 分页列表
+     *
+     * @param array $params 请求参数
+     * @param string $scene 场景名称，默认为 'default'
+     * @return LengthAwarePaginator 分页结果
+     */
+    public function list(array $params = [], string $scene = 'default'): LengthAwarePaginator
+    {
+        return $this->createQueryBuilder($params, $scene)->paginate();
+    }
+
+    /**
+     * 不分页列表
+     *
+     * @param array $params 请求参数
+     * @param string $scene 场景名称，默认为 'default'
+     * @return Collection 查询结果集合
+     */
+    public function all(array $params = [], string $scene = 'default'): Collection
+    {
+        return $this->createQueryBuilder($params, $scene)->get();
+    }
+
+    /**
+     * 自定义传入配置查询
+     *
+     * @param array $config 查询配置
+     * @param bool $paginate 是否分页，默认为 true
+     * @return LengthAwarePaginator|Collection 查询结果，分页或集合
+     */
+    public function query(array $config, bool $paginate = true): LengthAwarePaginator|Collection
+    {
+        $builder = new SimpleQueryBuilder($this->model);
+        $builder->applyQueryConfig($config);
+        return $paginate ? $builder->paginate() : $builder->get();
+    }
+
+    /**
+     * 按主键取一条（带关联）
+     */
+    public function getById(int $id, array $params = [], string $scene = 'default'): ?Model
+    {
+        return $this->createQueryBuilder($params, $scene)
+                    ->build()
+                    ->whereKey($id)
+                    ->first();
+    }
+
+    /**
+     * 按过滤条件取一条（带关联，不限主键）
+     */
+    public function getOne(array $params = [], string $scene = 'default'): ?Model
+    {
+        return $this->createQueryBuilder($params, $scene)
+                    ->build()
+                    ->first();
+    }
+
+    /**
+     * 查找单个模型实例
+     *
+     * @param int $id 模型ID
+     * @return Model|null 模型实例或null
+     */
+    public function find(int $id): ?Model
+    {
+        return $this->model->find($id);
+    }
+
+    /**
+     * 创建新模型实例
+     *
+     * @param array $data 创建数据
+     * @return Model 新创建的模型实例
+     */
+    public function create(array $data): Model
+    {
+        return $this->model->create($data);
+    }
+
+    /**
+     * 更新现有模型实例
+     *
+     * @param int $id 模型ID
+     * @param array $data 更新数据
+     * @return bool 更新是否成功
+     */
+    public function update(int $id, array $data): bool
+    {
+        $record = $this->find($id);
+        return $record ? $record->update($data) : false;
+    }
+
+    /**
+     * 删除模型实例
+     *
+     * @param int $id 模型ID
+     * @return bool 删除是否成功
+     */
+    public function delete(int $id): bool
+    {
+        $record = $this->find($id);
+        return $record ? $record->delete() : false;
+    }
+}