<?php

namespace app\common\traits\crud;

use support\Request;

/**
 * CRUD 操作控制器 Trait
 * 提供通用的增删改查控制器方法，通过调用 service 层实现业务逻辑解耦。
 */
trait CrudControllerTrait
{
    /**
     * 获取资源列表（GET /resource）
     *
     * @param Request $request 请求对象
     * @return mixed 返回分页数据及总数
     */
    public function index(Request $request)
    {
        $raw = $this->service->serviceList($request);
        $data = $this->transformData($raw, method_exists($this, 'indexFormat')
                                 ? [$this, 'indexFormat']
                                 : null);
        return $this->success($data);
    }

    /**
     * 获取指定资源详情（GET /resource/{id}）
     *
     * @param Request $request 请求对象
     * @param int|string $id 资源 ID
     * @return mixed 返回资源详情数据
     */
    public function show(Request $request)
    {
        $raw = $this->service->serviceShow($request);
        $data = $this->transformData($raw, method_exists($this, 'showFormat')
                                 ? [$this, 'showFormat']
                                 : null);
        return $this->success($data);
    }

    /**
     * 创建新资源（POST /resource）
     *
     * @param Request $request 请求对象
     * @return mixed 返回创建成功的数据或信息
     */
    public function store(Request $request)
    {
        $res = $this->service->serviceStore($request);
        return $this->success($res, '创建成功');
    }

    /**
     * 更新指定资源（PUT/PATCH /resource/{id}）
     *
     * @param Request $request 请求对象
     * @return mixed 返回更新成功的数据或信息
     */
    public function update(Request $request)
    {
        $res = $this->service->serviceUpdate($request);
        return $this->success($res, '更新成功');
    }

    /**
     * 删除指定资源（DELETE /resource/{id}）
     *
     * @param Request $request 请求对象
     * @return mixed 返回删除操作结果
     */
    public function destroy(Request $request)
    {
        $count = $this->service->serviceDestroy($request);
        return $this->success([], "删除了 {$count} 条");
    }


    // ----------------------------------------------------------------
    // 以下三个钩子方法，**在使用此 Trait 的 Controller** 中实现
    // ----------------------------------------------------------------

    /**
     * 字段名格式化：例如全部下划线
     *
     * @param string $field
     * @return string
     */
    // protected function fieldFormatter(string $field): string
    // {
    //     return snake_case($field);
    // }

    /**
     * 字段级后置加工规则
     * 
     * @return array<string,callable> 
     *   键为 “点号嵌套”或 “通配符” 字段路径，
     *   值为 fn($value, $row)=>mixed
     */
    // protected function getFieldTransforms(): array
    // {
    //     return [
    //         'name'           => fn($v,$row)=>strtoupper($v),
    //         'orders.*.total' => fn($v,$row)=>number_format($v,2),
    //     ];
    // }

    /**
     * 结果级后置加工：接收整个数组，可任意增删改
     *
     * @param array $data
     * @return array
     */
    // protected function postFormat(array $data): array
    // {
    //     // 例如重命名 records 为 items
    //     if (isset($data['records'])) {
    //         $data['items'] = $data['records'];
    //         unset($data['records']);
    //     }
    //     return $data;
    // }
}