<?php
declare (strict_types = 1);

namespace app\admin\controller\api;

use app\admin\model\Version as VersionModel;
use think\admin\Controller;
use think\facade\Request;

/**
 * 版本管理接口
 * @auth true
 * 
 * 接口说明：
 * ====================================================
 * 接口域名：{:sysconf('site_domain')}
 * 
 * 公共返回参数：
 * - code: 错误码，0表示成功，非0表示失败
 * - msg: 提示信息
 * - data: 返回的数据，请求失败时可能为空
 * 
 * 错误码说明：
 * - 0: 成功
 * - 1: 一般性错误(具体错误信息见msg)
 * - 401: 未授权或授权失败
 * - 404: 请求的资源不存在
 * - 500: 服务器内部错误
 * 
 * 版本号格式：x.x.x (例如: 3.4.1)
 * 平台类型：
 * - all: 全平台
 * - windows: Windows平台
 * - mac: Mac平台
 * - linux: Linux平台
 * ====================================================
 * 
 * 1. 获取最新版本 [GET] /admin/api.version/latest
 *    请求参数：
 *    - platform: 平台类型(all|windows|mac|linux), 默认为all
 *    返回数据：
 *    {
 *        "code": 0,
 *        "msg": "获取成功",
 *        "data": {
 *            "id": "1",
 *            "version_no": "3.4.1.4",
 *            "version_name": "听泉cursor助手",
 *            "download_url": "http://domain/upload/xxx.exe",
 *            "is_force": 1,                    // 是否强制更新(1是,0否)
 *            "min_version": "3.4.0.0",         // 最低要求版本
 *            "platform": "all",                // 平台类型
 *            "description": "版本描述",         // 版本描述
 *            "status": 1,                      // 状态(1启用,0禁用)
 *            "create_time": "2024-03-20 10:00:00"
 *        }
 *    }
 * 
 * 2. 检查版本更新 [GET] /admin/api.version/check
 *    请求参数：
 *    - version: 当前版本号(必填)
 *    - platform: 平台类型(all|windows|mac|linux), 默认为all
 *    返回数据：
 *    {
 *        "code": 0,
 *        "msg": "检查完成",
 *        "data": {
 *            "has_update": true,              // 是否有更新
 *            "is_force": 1,                   // 是否强制更新
 *            "version_info": {                // 新版本信息(has_update为true时返回)
 *                // 同上面的版本信息
 *            }
 *        }
 *    }
 * 
 * 错误返回示例：
 * {
 *     "code": 1,
 *     "msg": "请提供当前版本号",
 *     "data": null
 * }
 */
class Version extends Controller
{
    /**
     * 获取最新版本
     * @return void
     */
    public function latest()
    {
        $platform = $this->request->param('platform', 'all');
        $version = VersionModel::mk()->getLatestVersion($platform);
        if (!$version) {
            $this->error('暂无版本信息');
        }
        
        // 处理下载地址
        $version['download_url'] = $this->getFullUrl($version['download_url']);
        $this->success('获取成功', $version);
    }
    
    /**
     * 检查更新
     * @return void
     */
    public function check()
    {
        $currentVersion = $this->request->param('version');
        $platform = $this->request->param('platform', 'all');
        
        if (empty($currentVersion)) {
            $this->error('请提供当前版本号');
        }
        
        $result = VersionModel::mk()->checkUpdate($currentVersion, $platform);
        if (isset($result['error'])) {
            $this->error($result['error']);
        }
        
        // 如果有更新,处理下载地址
        if ($result['has_update'] && isset($result['version_info'])) {
            $result['version_info']['download_url'] = $this->getFullUrl($result['version_info']['download_url']);
        }
        
        $this->success('检查完成', $result);
    }

    /**
     * 获取完整的下载地址
     * @param string $path 相对路径
     * @return string
     */
    protected function getFullUrl($path)
    {
        return sysconf('site_domain') . $path;
    }
}