mp_audio_manage/app/Services/Canvas/CanvasService.php

<?php

namespace App\Services\Canvas;

use App\Facade\Site;
use App\Libs\Utils;
use Illuminate\Support\Facades\DB;

/**
 * 画布模式服务
 *
 * 核心模型：
 * 画布(mp_canvases) -> 节点(mp_canvas_nodes) + 关联(mp_canvas_node_rels) + 分镜数据(mp_canvas_segments)
 *
 * 画布为无限扩展画布，无固定宽高；节点无限扩展、无固定根节点，仅记录两两关联。
 * 关联查询一律按节点ID查邻接关系（a=node OR b=node），不依赖树形结构，
 * 因此无根节点不影响关联数据的获取；数据量大时可使用 graph 的局部子图查询。
 *
 * 节点类型说明：
 * - theme/subject/scene/prop/segment 属于"列表型"节点，可复用全局资产库或动漫分集中的数据
 * - text/image/video/audio 属于"内容型"节点
 * - 关联无方向、多对多，通过 (node_id_a, node_id_b) 且 a < b 归一化存储
 */
class CanvasService
{
    /** 节点类型白名单 */
    const NODE_TYPES = ['theme', 'subject', 'scene', 'prop', 'segment', 'text', 'image', 'video', 'audio'];

    /** 关联来源类型白名单 */
    const SOURCE_TYPES = ['none', 'product', 'episode'];

    /** 当前支持的画布文档 schema 版本 */
    const SUPPORTED_SCHEMA_VERSION = 1;

    /** 画布文档大小与图规模限制 */
    const MAX_DOCUMENT_BYTES = 2097152; // 2MB
    const MAX_NODES         = 2000;
    const MAX_EDGES         = 5000;
    const MAX_TEXT_LENGTH   = 50000;
    const MAX_URL_LENGTH    = 2048;
    const MAX_TITLE_LENGTH  = 100;

    /**
     * 画布摘要列表（分页，不返回完整图）
     *
     * @param array $data anime_id-动漫ID(可选) episode_id-剧集ID(可选) page-页码 page_size-每页数量
     * @return array
     */
    public function canvasList($data)
    {
        $uid        = Site::getUid();
        $cpid       = Site::getCpid();
        $anime_id   = (int)getProp($data, 'anime_id', 0);
        $episode_id = (int)getProp($data, 'episode_id', 0);
        $page       = max(1, (int)getProp($data, 'page', 1));
        $page_size  = min(100, max(1, (int)getProp($data, 'page_size', 20)));

        $query = DB::table('mp_canvases')
            ->where('uid', $uid)
            ->where('cpid', $cpid)
            ->where('is_deleted', 0)
            ->select('canvas_uuid as canvas_id', 'name as title', 'description', 'cover_url',
                'anime_id', 'episode_id', 'episode_number', 'schema_version', 'revision',
                'created_at', 'updated_at');

        if ($anime_id) {
            $query->where('anime_id', $anime_id);
        }
        if ($episode_id) {
            $query->where('episode_id', $episode_id);
        }

        $list = $query->orderByDesc('id')->paginate($page_size, ['*'], 'page', $page);

        $items = $list->map(function ($item) {
            $item = (array)$item;
            $item['created_at'] = transDate($item['created_at'], 'Y-m-d H:i:s');
            $item['updated_at'] = transDate($item['updated_at'], 'Y-m-d H:i:s');
            $item['scope']      = [
                'anime_id'       => (int)$item['anime_id'],
                'episode_id'     => (int)$item['episode_id'],
                'episode_number' => (int)$item['episode_number']
            ];
            unset($item['anime_id'], $item['episode_id'], $item['episode_number']);
            return $item;
        })->toArray();

        return [
            'meta' => getMeta($list),
            'list' => $items
        ];
    }

    /**
     * 创建画布（完整文档模式，兼容旧的 name-only 创建）
     *
     * @param array $data 完整画布文档或旧版 name/description/cover_url
     * @return array
     */
    public function createCanvas($data)
    {
        $uid  = Site::getUid();
        $cpid = Site::getCpid();
        $now  = date('Y-m-d H:i:s');

        if ($this->isDocumentRequest($data)) {
            $doc         = $this->validateDocument($data, true);
            $canvas_uuid = $doc['canvas_id'];
            if (DB::table('mp_canvases')->where('canvas_uuid', $canvas_uuid)->exists()) {
                Utils::throwError('20003:画布ID已存在');
            }

            $row = [
                'uid'            => $uid,
                'cpid'           => $cpid,
                'canvas_uuid'    => $canvas_uuid,
                'name'           => $doc['title'],
                'description'    => (string)getProp($data, 'description', ''),
                'cover_url'      => (string)getProp($data, 'cover_url', ''),
                'anime_id'       => $doc['scope']['anime_id'],
                'episode_id'     => $doc['scope']['episode_id'],
                'episode_number' => $doc['scope']['episode_number'],
                'schema_version' => self::SUPPORTED_SCHEMA_VERSION,
                'revision'       => 1,
                'document'       => json_encode($doc, JSON_UNESCAPED_UNICODE),
                'is_deleted'     => 0,
                'created_at'     => $now,
                'updated_at'     => $now
            ];
            $canvas_id = DB::table('mp_canvases')->insertGetId($row);
            if (!$canvas_id) {
                Utils::throwError('20003:创建画布失败');
            }
            $row['id'] = $canvas_id;
            return $this->buildDocument((object)$row);
        }

        // 旧版 name-only 创建，保留兼容
        $name = trim((string)getProp($data, 'name', ''));
        if ($name === '') {
            Utils::throwError('20003:请提供画布名称');
        }
        $canvas_uuid = $this->generateCanvasId();
        $canvas_id = DB::table('mp_canvases')->insertGetId([
            'uid'            => $uid,
            'cpid'           => $cpid,
            'canvas_uuid'    => $canvas_uuid,
            'name'           => $name,
            'description'    => (string)getProp($data, 'description', ''),
            'cover_url'      => (string)getProp($data, 'cover_url', ''),
            'schema_version' => self::SUPPORTED_SCHEMA_VERSION,
            'revision'       => 1,
            'document'       => null,
            'is_deleted'     => 0,
            'created_at'     => $now,
            'updated_at'     => $now
        ]);
        if (!$canvas_id) {
            Utils::throwError('20003:创建画布失败');
        }

        return $this->canvasDetail(['canvas_id' => $canvas_uuid]);
    }

    /**
     * 保存画布完整文档；revision 不匹配时返回冲突标记
     *
     * @param array $data 完整画布文档
     * @return array
     */
    public function editCanvas($data)
    {
        $canvas_id = (string)getProp($data, 'canvas_id', '');
        if ($canvas_id === '') {
            Utils::throwError('20003:请提供画布ID');
        }

        $canvas = $this->checkCanvas($canvas_id);
        $doc    = $this->validateDocument($data, false, $canvas);

        if ((int)$doc['revision'] !== (int)$canvas->revision) {
            return [
                'revision_conflict' => true,
                'canvas_id'         => $this->canvasKey($canvas),
                'revision'          => (int)$canvas->revision
            ];
        }

        $next_revision   = (int)$canvas->revision + 1;
        $doc['revision'] = $next_revision;
        $doc['canvas_id'] = $this->canvasKey($canvas);

        DB::table('mp_canvases')->where('id', $canvas->id)->update([
            'name'           => $doc['title'],
            'anime_id'       => $doc['scope']['anime_id'],
            'episode_id'     => $doc['scope']['episode_id'],
            'episode_number' => $doc['scope']['episode_number'],
            'schema_version' => self::SUPPORTED_SCHEMA_VERSION,
            'revision'       => $next_revision,
            'document'       => json_encode($doc, JSON_UNESCAPED_UNICODE),
            'updated_at'     => date('Y-m-d H:i:s')
        ]);

        return $this->canvasDetail(['canvas_id' => $doc['canvas_id']]);
    }

    /**
     * 删除画布（软删除画布/节点/分镜数据，物理删除关联）
     *
     * @param array $data canvas_id-画布ID
     * @return array
     */
    public function delCanvas($data)
    {
        $canvas_id = (string)getProp($data, 'canvas_id', '');
        $canvas    = $this->checkCanvas($canvas_id);
        $now       = date('Y-m-d H:i:s');

        DB::beginTransaction();
        try {
            DB::table('mp_canvases')->where('id', $canvas->id)->update(['is_deleted' => 1, 'updated_at' => $now]);
            DB::table('mp_canvas_nodes')->where('canvas_id', $canvas->id)->update(['is_deleted' => 1, 'updated_at' => $now]);
            DB::table('mp_canvas_segments')->where('canvas_id', $canvas->id)->update(['is_deleted' => 1, 'updated_at' => $now]);
            DB::table('mp_canvas_node_rels')->where('canvas_id', $canvas->id)->delete();
            DB::commit();
        } catch (\Throwable $e) {
            DB::rollBack();
            Utils::throwError('20003:删除画布失败');
        }

        return ['success' => 1];
    }

    /**
     * 打开指定画布，返回完整文档
     *
     * @param array $data canvas_id-画布ID（字符串 canvas_uuid 或旧数字ID）
     * @return array
     */
    public function canvasDetail($data)
    {
        $canvas_id = (string)getProp($data, 'canvas_id', '');
        $canvas    = $this->checkCanvas($canvas_id);
        return $this->buildDocument($canvas);
    }

    /**
     * 保存节点（创建/更新）
     *
     * 通用字段直接写 mp_canvas_nodes；node_type=segment 时同步写 mp_canvas_segments。
     * 分镜关键数据优先取 data.segment 子对象，缺省时回退到节点级字段。
     *
     * @param array $data canvas_id-画布ID node_id-节点ID(更新时) node_type-节点类型
     *                    name/content/text_prompt/pic_prompt/image_url/video_url/audio_url/
     *                    thumbnail_url/duration/pos_x/pos_y/z_index/size_w/size_h
     *                    source_type/source_product_id/source_anime_id/source_episode_id/source_ref/ext
     *                    segment-分镜数据子对象(可选)
     * @return array
     */
    public function saveNode($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id', 0);
        $node_type = (string)getProp($data, 'node_type', '');

        if (!in_array($node_type, self::NODE_TYPES, true)) {
            Utils::throwError('20003:无效的节点类型');
        }
        $this->checkCanvas($canvas_id);

        $uid  = Site::getUid();
        $cpid = Site::getCpid();
        $now  = date('Y-m-d H:i:s');

        $fields = [
            'name'               => (string)getProp($data, 'name', ''),
            'content'            => (string)getProp($data, 'content', ''),
            'text_prompt'        => (string)getProp($data, 'text_prompt', ''),
            'pic_prompt'         => (string)getProp($data, 'pic_prompt', ''),
            'image_url'          => (string)getProp($data, 'image_url', ''),
            'video_url'          => (string)getProp($data, 'video_url', ''),
            'audio_url'          => (string)getProp($data, 'audio_url', ''),
            'thumbnail_url'      => (string)getProp($data, 'thumbnail_url', ''),
            'duration'           => $this->nullableInt(getProp($data, 'duration', null)),
            'pos_x'              => (float)getProp($data, 'pos_x', 0),
            'pos_y'              => (float)getProp($data, 'pos_y', 0),
            'z_index'            => (int)getProp($data, 'z_index', 0),
            'size_w'             => $this->nullableFloat(getProp($data, 'size_w', null)),
            'size_h'             => $this->nullableFloat(getProp($data, 'size_h', null)),
            'source_type'        => (string)getProp($data, 'source_type', 'none'),
            'source_product_id'  => $this->nullableInt(getProp($data, 'source_product_id', null)),
            'source_anime_id'    => $this->nullableInt(getProp($data, 'source_anime_id', null)),
            'source_episode_id'  => $this->nullableInt(getProp($data, 'source_episode_id', null)),
            'source_ref'         => (string)getProp($data, 'source_ref', ''),
            'ext'                => $this->jsonEncode(getProp($data, 'ext', null))
        ];

        if (!in_array($fields['source_type'], self::SOURCE_TYPES, true)) {
            $fields['source_type'] = 'none';
        }

        DB::beginTransaction();
        try {
            $real_type = $node_type;
            if ($node_id) {
                $exists = DB::table('mp_canvas_nodes')
                    ->where('id', $node_id)
                    ->where('canvas_id', $canvas_id)
                    ->where('is_deleted', 0)
                    ->first();
                if (!$exists) {
                    Utils::throwError('20003:节点不存在');
                }
                // 更新时节点类型以库中为准，不允许变更
                $real_type = $exists->node_type;
                $fields['updated_at'] = $now;
                DB::table('mp_canvas_nodes')->where('id', $node_id)->update($fields);
            } else {
                $fields['canvas_id']  = $canvas_id;
                $fields['uid']        = $uid;
                $fields['cpid']       = $cpid;
                $fields['node_type']  = $node_type;
                $fields['is_deleted'] = 0;
                $fields['created_at'] = $now;
                $fields['updated_at'] = $now;
                $node_id = DB::table('mp_canvas_nodes')->insertGetId($fields);
                if (!$node_id) {
                    Utils::throwError('20003:保存节点失败');
                }
            }

            // 分镜节点同步分镜数据表
            if ($real_type === 'segment') {
                $this->syncSegment($canvas_id, $node_id, $data, $now);
            }
            DB::commit();
        } catch (\Throwable $e) {
            DB::rollBack();
            throw $e;
        }

        return ['node_id' => $node_id];
    }

    /**
     * 节点详情（含分镜数据与当前关联）
     *
     * @param array $data canvas_id-画布ID node_id-节点ID
     * @return array
     */
    public function nodeInfo($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id');
        $this->checkCanvas($canvas_id);

        $node = $this->getNode($canvas_id, $node_id);
        $node = $this->formatNode($node, $canvas_id);

        $node['rel_ids']       = $this->getNodeRelIds($canvas_id, $node_id);
        $node['related_nodes'] = $this->getRelatedNodes($canvas_id, $node_id);

        return $node;
    }

    /**
     * 获取节点的所有关联节点
     *
     * @param array $data canvas_id-画布ID node_id-节点ID
     * @return array
     */
    public function nodeRels($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id');
        $this->checkCanvas($canvas_id);
        $this->getNode($canvas_id, $node_id);

        return [
            'node_id'       => $node_id,
            'rel_ids'       => $this->getNodeRelIds($canvas_id, $node_id),
            'related_nodes' => $this->getRelatedNodes($canvas_id, $node_id)
        ];
    }

    /**
     * 保存节点关联（整体替换：先清空该节点的所有关联，再写入新关联）
     *
     * 关联无方向、多对多；内部统一归一化为 (小id, 大id) 存储，配合唯一索引防止重复。
     *
     * @param array $data canvas_id-画布ID node_id-节点ID related_ids-关联节点ID数组(可传逗号分隔字符串)
     * @return array
     */
    public function saveRels($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id');
        $this->checkCanvas($canvas_id);
        $this->getNode($canvas_id, $node_id);

        $related_ids = getProp($data, 'related_ids', []);
        if (!is_array($related_ids)) {
            $related_ids = $related_ids === '' ? [] : explode(',', (string)$related_ids);
        }
        $related_ids = array_values(array_unique(array_filter(array_map('intval', $related_ids))));
        // 去除自身关联
        $related_ids = array_values(array_diff($related_ids, [$node_id]));

        $pairs = [];
        if ($related_ids) {
            // 只允许关联同一画布下未删除的节点
            $valid_ids = DB::table('mp_canvas_nodes')
                ->where('canvas_id', $canvas_id)
                ->whereIn('id', $related_ids)
                ->where('is_deleted', 0)
                ->pluck('id')
                ->all();

            foreach ($valid_ids as $rid) {
                $a = (int)min($node_id, $rid);
                $b = (int)max($node_id, $rid);
                $pairs[$a . '_' . $b] = ['a' => $a, 'b' => $b];
            }
        }

        $now = date('Y-m-d H:i:s');
        DB::beginTransaction();
        try {
            DB::table('mp_canvas_node_rels')
                ->where('canvas_id', $canvas_id)
                ->where(function ($query) use ($node_id) {
                    $query->where('node_id_a', $node_id)
                        ->orWhere('node_id_b', $node_id);
                })
                ->delete();

            if ($pairs) {
                $rows = [];
                foreach ($pairs as $pair) {
                    $rows[] = [
                        'canvas_id'  => $canvas_id,
                        'node_id_a'  => $pair['a'],
                        'node_id_b'  => $pair['b'],
                        'created_at' => $now,
                        'updated_at' => $now
                    ];
                }
                DB::table('mp_canvas_node_rels')->insert($rows);
            }
            DB::commit();
        } catch (\Throwable $e) {
            DB::rollBack();
            Utils::throwError('20003:保存关联失败');
        }

        return ['success' => 1, 'rel_count' => count($pairs)];
    }

    /**
     * 删除节点（软删除节点/分镜数据，物理删除关联）
     *
     * @param array $data canvas_id-画布ID node_id-节点ID
     * @return array
     */
    public function delNode($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id');
        $this->checkCanvas($canvas_id);
        $node = $this->getNode($canvas_id, $node_id);
        $now  = date('Y-m-d H:i:s');

        DB::beginTransaction();
        try {
            DB::table('mp_canvas_nodes')->where('id', $node_id)->update(['is_deleted' => 1, 'updated_at' => $now]);
            DB::table('mp_canvas_node_rels')
                ->where('canvas_id', $canvas_id)
                ->where(function ($query) use ($node_id) {
                    $query->where('node_id_a', $node_id)
                        ->orWhere('node_id_b', $node_id);
                })
                ->delete();
            if ($node->node_type === 'segment') {
                DB::table('mp_canvas_segments')
                    ->where('canvas_id', $canvas_id)
                    ->where('node_id', $node_id)
                    ->update(['is_deleted' => 1, 'updated_at' => $now]);
            }
            DB::commit();
        } catch (\Throwable $e) {
            DB::rollBack();
            Utils::throwError('20003:删除节点失败');
        }

        return ['success' => 1];
    }

    /**
     * 画布关系图（供前端渲染）
     *
     * 不传 node_id 时返回画布全部节点与关联；传 node_id 时返回以该节点为中心、
     * 深度为 depth 的局部子图（按广度优先收集邻居；rels 只包含 BFS 展开过程中触及的边，
     * 即 depth=1 时仅返回中心节点的直接关联），适合大画布局部加载。
     * 局部子图模式下，每个节点/每条关联附带 level 字段（节点为距中心的跳数，
     * 关联为 BFS 展开时首次被触及的轮次），另附 levels 摘要便于前端逐层加载与动画。
     *
     * @param array $data canvas_id-画布ID node_id-中心节点ID(可选) depth-子图深度(可选,默认1)
     * @return array
     */
    public function graph($data)
    {
        $canvas_id = (int)getProp($data, 'canvas_id');
        $node_id   = (int)getProp($data, 'node_id', 0);
        $depth     = min(5, max(1, (int)getProp($data, 'depth', 1)));
        $this->checkCanvas($canvas_id);

        if ($node_id) {
            return $this->getSubGraph($canvas_id, $node_id, $depth);
        }

        return $this->getGraph($canvas_id);
    }

    /* ------------------------------------------------------------------ */
    /* 私有方法                                                            */
    /* ------------------------------------------------------------------ */

    /**
     * 校验画布归属并返回画布
     *
     * @param string|int $canvas_id
     * @return object
     */
    private function checkCanvas($canvas_id)
    {
        if ($canvas_id === '' || $canvas_id === null) {
            Utils::throwError('20003:请提供画布ID');
        }

        $query = DB::table('mp_canvases')
            ->where('uid', Site::getUid())
            ->where('cpid', Site::getCpid())
            ->where('is_deleted', 0);

        if (is_numeric($canvas_id)) {
            $query->where('id', (int)$canvas_id);
        } else {
            $query->where('canvas_uuid', (string)$canvas_id);
        }

        $canvas = $query->first();
        if (!$canvas) {
            Utils::throwError('20003:画布不存在或无权访问');
        }
        return $canvas;
    }

    /**
     * 画布对外资源 ID：优先字符串 canvas_uuid，旧数据兜底数字 id
     *
     * @param object $canvas
     * @return string
     */
    private function canvasKey($canvas)
    {
        $uuid = (string)getProp($canvas, 'canvas_uuid', '');
        return $uuid !== '' ? $uuid : (string)(int)getProp($canvas, 'id', 0);
    }

    /**
     * 生成前端可用的稳定画布 ID
     *
     * @return string
     */
    private function generateCanvasId()
    {
        return 'canvas-' . \Illuminate\Support\Str::uuid()->toString();
    }

    /**
     * 判断请求是否为完整文档创建
     *
     * @param mixed $data
     * @return bool
     */
    private function isDocumentRequest($data)
    {
        return is_array($data) && (
            array_key_exists('graph', $data) ||
            array_key_exists('schema_version', $data) ||
            array_key_exists('title', $data) ||
            array_key_exists('scope', $data) ||
            array_key_exists('canvas_id', $data)
        );
    }

    /**
     * 校验并规范化完整画布文档
     *
     * @param array       $data
     * @param bool        $isCreate
     * @param object|null $canvas
     * @return array
     */
    private function validateDocument($data, $isCreate, $canvas = null)
    {
        if (!is_array($data)) {
            Utils::throwError('20003:请求体格式不正确');
        }

        $schema_version = (int)getProp($data, 'schema_version', self::SUPPORTED_SCHEMA_VERSION);
        if ($schema_version !== self::SUPPORTED_SCHEMA_VERSION) {
            Utils::throwError('20003:不支持的schema_version');
        }

        $canvas_id = (string)getProp($data, 'canvas_id', '');
        if ($isCreate) {
            if ($canvas_id === '') {
                $canvas_id = $this->generateCanvasId();
            }
            if (mb_strlen($canvas_id) > 64) {
                Utils::throwError('20003:canvas_id长度超出限制');
            }
        } else {
            $key = $canvas ? $this->canvasKey($canvas) : '';
            if ($canvas_id !== '' && $canvas_id !== $key && $canvas_id !== (string)getProp($canvas, 'id', 0)) {
                Utils::throwError('20003:canvas_id与画布不一致');
            }
            $canvas_id = $key;
        }

        $revision = $isCreate ? 1 : (int)getProp($data, 'revision', -1);
        if (!$isCreate && $revision < 0) {
            Utils::throwError('20003:缺少revision');
        }

        $title = trim((string)getProp($data, 'title', getProp($data, 'name', '')));
        if ($title === '') {
            $title = '未命名画布';
        }
        if (mb_strlen($title) > self::MAX_TITLE_LENGTH) {
            Utils::throwError('20003:画布标题长度超出限制');
        }

        $scope = getProp($data, 'scope', []);
        if (!is_array($scope)) {
            Utils::throwError('20003:scope格式不正确');
        }
        $scope = $this->checkScope($scope);

        $graph = getProp($data, 'graph', []);
        if (!is_array($graph)) {
            Utils::throwError('20003:graph格式不正确');
        }
        $graph = $this->normalizeGraph($graph);

        $preferences = getProp($data, 'preferences', []);
        if (!is_array($preferences)) {
            $preferences = [];
        }

        $doc = [
            'schema_version' => self::SUPPORTED_SCHEMA_VERSION,
            'canvas_id'      => $canvas_id,
            'revision'       => $revision,
            'scope'          => $scope,
            'title'          => $title,
            'graph'          => $graph,
            'preferences'    => $preferences
        ];

        if (strlen(json_encode($doc, JSON_UNESCAPED_UNICODE)) > self::MAX_DOCUMENT_BYTES) {
            Utils::throwError('20003:画布文档大小超出限制');
        }
        $this->checkTextAndUrlLimits($doc);

        return $doc;
    }

    /**
     * 校验 scope 归属：动漫属于当前用户，剧集属于该动漫
     *
     * @param array $scope
     * @return array
     */
    private function checkScope($scope)
    {
        $anime_id   = (int)getProp($scope, 'anime_id', 0);
        $episode_id = (int)getProp($scope, 'episode_id', 0);
        if (!$anime_id || !$episode_id) {
            Utils::throwError('20003:scope.anime_id和scope.episode_id不能为空');
        }

        $anime = DB::table('mp_animes')
            ->where('id', $anime_id)
            ->where('user_id', Site::getUid())
            ->where('is_deleted', 0)
            ->first();
        if (!$anime) {
            Utils::throwError('20003:动漫不存在或无权访问');
        }

        $episode = DB::table('mp_anime_episodes')
            ->where('id', $episode_id)
            ->where('anime_id', $anime_id)
            ->first();
        if (!$episode) {
            Utils::throwError('20003:剧集不存在或不属于该动漫');
        }

        return [
            'anime_id'       => $anime_id,
            'episode_id'     => $episode_id,
            'episode_number' => (int)$episode->episode_number
        ];
    }

    /**
     * 图结构最小校验：节点/边数量、ID 唯一、边端点存在
     *
     * @param array $graph
     * @return array
     */
    private function normalizeGraph($graph)
    {
        $viewport = getProp($graph, 'viewport', ['x' => 0, 'y' => 0, 'zoom' => 1]);
        if (!is_array($viewport)) {
            $viewport = ['x' => 0, 'y' => 0, 'zoom' => 1];
        }
        $nodes = getProp($graph, 'nodes', []);
        $edges = getProp($graph, 'edges', []);
        if (!is_array($nodes)) {
            $nodes = [];
        }
        if (!is_array($edges)) {
            $edges = [];
        }

        if (count($nodes) > self::MAX_NODES) {
            Utils::throwError('20003:节点数超出限制');
        }
        if (count($edges) > self::MAX_EDGES) {
            Utils::throwError('20003:边数超出限制');
        }

        $nodeIds = [];
        foreach ($nodes as $node) {
            if (!is_array($node)) {
                Utils::throwError('20003:节点格式不正确');
            }
            $id = getProp($node, 'id', '');
            if ($id === '' || $id === null || !is_scalar($id)) {
                Utils::throwError('20003:节点ID不能为空');
            }
            $idKey = (string)$id;
            if (isset($nodeIds[$idKey])) {
                Utils::throwError('20003:节点ID重复：' . $idKey);
            }
            $nodeIds[$idKey] = true;
        }

        $edgeIds = [];
        foreach ($edges as $edge) {
            if (!is_array($edge)) {
                Utils::throwError('20003:边格式不正确');
            }
            $source = (string)getProp($edge, 'source', '');
            $target = (string)getProp($edge, 'target', '');
            if (!isset($nodeIds[$source]) || !isset($nodeIds[$target])) {
                Utils::throwError('20003:边端点不存在');
            }

            $edgeId = getProp($edge, 'id', '');
            if ($edgeId !== '' && $edgeId !== null) {
                if (!is_scalar($edgeId)) {
                    Utils::throwError('20003:边ID格式不正确');
                }
                $edgeKey = (string)$edgeId;
                if (isset($edgeIds[$edgeKey])) {
                    Utils::throwError('20003:边ID重复：' . $edgeKey);
                }
                $edgeIds[$edgeKey] = true;
            }
        }

        return [
            'viewport' => $viewport,
            'nodes'    => $nodes,
            'edges'    => $edges
        ];
    }

    /**
     * 递归限制文档内文本与 URL 长度
     *
     * @param mixed $value
     * @return void
     */
    private function checkTextAndUrlLimits($value)
    {
        if (is_string($value)) {
            if (strlen($value) > self::MAX_TEXT_LENGTH) {
                Utils::throwError('20003:文本内容长度超出限制');
            }
            if (preg_match('#^https?://#i', $value) && strlen($value) > self::MAX_URL_LENGTH) {
                Utils::throwError('20003:URL长度超出限制');
            }
            return;
        }
        if (!is_array($value)) {
            return;
        }
        foreach ($value as $item) {
            $this->checkTextAndUrlLimits($item);
        }
    }

    /**
     * 组装完整文档；旧画布无 document 时从节点/关联表构建
     *
     * @param object $canvas
     * @return array
     */
    private function buildDocument($canvas)
    {
        $raw = (string)getProp($canvas, 'document', '');
        if ($raw !== '') {
            $doc = json_decode($raw, true);
            if (is_array($doc)) {
                $doc['canvas_id']      = $this->canvasKey($canvas);
                $doc['revision']       = (int)getProp($canvas, 'revision', 1);
                $doc['schema_version'] = (int)getProp($canvas, 'schema_version', self::SUPPORTED_SCHEMA_VERSION);
                $doc['scope']          = $this->scopeFromRow($canvas);
                $doc['title']          = (string)getProp($canvas, 'name', getProp($doc, 'title', '未命名画布'));
                if (!isset($doc['graph']) || !is_array($doc['graph'])) {
                    $doc['graph'] = ['viewport' => ['x' => 0, 'y' => 0, 'zoom' => 1], 'nodes' => [], 'edges' => []];
                }
                if (!isset($doc['preferences']) || !is_array($doc['preferences'])) {
                    $doc['preferences'] = ['minimap_visible' => true, 'snap_to_grid_enabled' => false];
                }
                return $doc;
            }
        }
        return $this->buildLegacyDocument($canvas);
    }

    /**
     * 从画布行组装 scope
     *
     * @param object $canvas
     * @return array
     */
    private function scopeFromRow($canvas)
    {
        return [
            'anime_id'       => (int)getProp($canvas, 'anime_id', 0),
            'episode_id'     => (int)getProp($canvas, 'episode_id', 0),
            'episode_number' => (int)getProp($canvas, 'episode_number', 0)
        ];
    }

    /**
     * 旧画布文档兜底：由节点/关联表生成 graph
     *
     * @param object $canvas
     * @return array
     */
    private function buildLegacyDocument($canvas)
    {
        $graph = $this->getGraph((int)getProp($canvas, 'id', 0));

        $nodes = [];
        foreach ($graph['nodes'] as $node) {
            $node = (array)$node;
            if (isset($node['id'])) {
                $node['id'] = (string)$node['id'];
            }
            $nodes[] = $node;
        }

        $edges = [];
        foreach ($graph['rels'] as $rel) {
            $edges[] = [
                'id'     => (string)$rel['id'],
                'source' => (string)$rel['node_id_a'],
                'target' => (string)$rel['node_id_b']
            ];
        }

        return [
            'schema_version' => self::SUPPORTED_SCHEMA_VERSION,
            'canvas_id'      => $this->canvasKey($canvas),
            'revision'       => (int)getProp($canvas, 'revision', 1),
            'scope'          => $this->scopeFromRow($canvas),
            'title'          => (string)getProp($canvas, 'name', '未命名画布'),
            'graph'          => [
                'viewport' => ['x' => 0, 'y' => 0, 'zoom' => 1],
                'nodes'    => $nodes,
                'edges'    => $edges
            ],
            'preferences'    => [
                'minimap_visible'       => true,
                'snap_to_grid_enabled'  => false
            ]
        ];
    }

    /**
     * 校验节点归属并返回节点
     *
     * @param int $canvas_id
     * @param int $node_id
     * @return object
     */
    private function getNode($canvas_id, $node_id)
    {
        if (!$node_id) {
            Utils::throwError('20003:请提供节点ID');
        }
        $node = DB::table('mp_canvas_nodes')
            ->where('id', $node_id)
            ->where('canvas_id', $canvas_id)
            ->where('is_deleted', 0)
            ->first();
        if (!$node) {
            Utils::throwError('20003:节点不存在');
        }
        return $node;
    }

    /**
     * 同步分镜数据表（创建或更新）
     *
     * @param int    $canvas_id
     * @param int    $node_id
     * @param array  $data
     * @param string $now
     * @return void
     */
    private function syncSegment($canvas_id, $node_id, $data, $now)
    {
        $seg = getProp($data, 'segment');
        $seg = is_array($seg) ? $seg : [];

        $seg_fields = [
            'segment_number' => (int)getProp($seg, 'segment_number', 1),
            'name'           => (string)getProp($seg, 'name', getProp($data, 'name', '')),
            'text_prompt'    => (string)getProp($seg, 'text_prompt', getProp($data, 'text_prompt', '')),
            'pic_prompt'     => (string)getProp($seg, 'pic_prompt', getProp($data, 'pic_prompt', '')),
            'image_url'      => (string)getProp($seg, 'image_url', getProp($data, 'image_url', '')),
            'video_url'      => (string)getProp($seg, 'video_url', getProp($data, 'video_url', '')),
            'audio_url'      => (string)getProp($seg, 'audio_url', getProp($data, 'audio_url', '')),
            'duration'       => $this->nullableInt(getProp($seg, 'duration', getProp($data, 'duration', null))),
            'status'         => (string)getProp($seg, 'status', 'draft'),
            'ext'            => $this->jsonEncode(getProp($seg, 'ext', null))
        ];

        $exists = DB::table('mp_canvas_segments')
            ->where('canvas_id', $canvas_id)
            ->where('node_id', $node_id)
            ->where('is_deleted', 0)
            ->first();

        if ($exists) {
            $seg_fields['updated_at'] = $now;
            DB::table('mp_canvas_segments')->where('id', $exists->id)->update($seg_fields);
        } else {
            $seg_fields['canvas_id']  = $canvas_id;
            $seg_fields['node_id']    = $node_id;
            $seg_fields['uid']        = Site::getUid();
            $seg_fields['cpid']       = Site::getCpid();
            $seg_fields['is_deleted'] = 0;
            $seg_fields['created_at'] = $now;
            $seg_fields['updated_at'] = $now;
            DB::table('mp_canvas_segments')->insert($seg_fields);
        }
    }

    /**
     * 获取以指定节点为中心的局部子图（广度优先，最多 depth 层）
     *
     * 节点集合为距中心不超过 depth 跳的所有节点；
     * 关系集合为 BFS 展开过程中触及的边（至少一端距中心不超过 depth-1 跳），
     * 因此 depth=1 时只返回中心节点的直接关联，不会返回"邻居之间的边"。
     * 返回的节点带 level（距中心跳数，中心为 0），关联带 level（首次被触及的轮次），
     * 并提供 levels 摘要 [{level, node_ids, rel_ids}] 供前端逐层渲染。
     *
     * @param int $canvas_id
     * @param int $node_id
     * @param int $depth
     * @return array
     */
    private function getSubGraph($canvas_id, $node_id, $depth)
    {
        $this->getNode($canvas_id, $node_id);

        // 广度优先收集节点（节点只入队一次，避免环导致死循环）
        $collectedMap = [$node_id => 0];
        $collected    = [$node_id];
        $frontier     = [$node_id];
        $edgeMap      = [];

        for ($i = 0; $i < $depth; $i++) {
            $level = $i + 1;
            $rels = DB::table('mp_canvas_node_rels')
                ->where('canvas_id', $canvas_id)
                ->where(function ($query) use ($frontier) {
                    $query->whereIn('node_id_a', $frontier)
                        ->orWhereIn('node_id_b', $frontier);
                })
                ->get();

            $next = [];
            foreach ($rels as $rel) {
                $a = (int)$rel->node_id_a;
                $b = (int)$rel->node_id_b;
                // 只记录 BFS 展开过程中触及的边（去重），不返回"邻居之间的边"
                if (!isset($edgeMap[$a . '_' . $b])) {
                    $edgeMap[$a . '_' . $b] = [
                        'id'        => (int)$rel->id,
                        'node_id_a' => $a,
                        'node_id_b' => $b,
                        'level'     => $level
                    ];
                }
                foreach ([$a, $b] as $nid) {
                    if (!isset($collectedMap[$nid])) {
                        $collectedMap[$nid] = $level;
                        $collected[] = $nid;
                        $next[]      = $nid;
                    }
                }
            }

            if (!$next) {
                break;
            }
            $frontier = $next;
        }

        $nodes = DB::table('mp_canvas_nodes')
            ->where('canvas_id', $canvas_id)
            ->whereIn('id', $collected)
            ->where('is_deleted', 0)
            ->orderBy('z_index')
            ->orderBy('id')
            ->get()
            ->map(function ($node) use ($canvas_id, $collectedMap) {
                $node = $this->formatNode($node, $canvas_id);
                $node['level'] = $collectedMap[$node['id']];
                return $node;
            })
            ->toArray();

        $rels = array_values($edgeMap);
        usort($rels, function ($x, $y) {
            return $x['id'] - $y['id'];
        });

        // 层级摘要：每层包含的节点ID与关联ID
        $levelNodes = [];
        $levelRels  = [];
        foreach ($collected as $nid) {
            $levelNodes[$collectedMap[$nid]][] = $nid;
        }
        foreach ($rels as $rel) {
            $levelRels[$rel['level']][] = $rel['id'];
        }
        $levels = [];
        for ($lv = 0; $lv <= $depth; $lv++) {
            if (isset($levelNodes[$lv]) || isset($levelRels[$lv])) {
                $levels[] = [
                    'level'    => $lv,
                    'node_ids' => isset($levelNodes[$lv]) ? $levelNodes[$lv] : [],
                    'rel_ids'  => isset($levelRels[$lv]) ? $levelRels[$lv] : []
                ];
            }
        }

        return [
            'center_node_id' => $node_id,
            'depth'          => $depth,
            'levels'         => $levels,
            'nodes'          => $nodes,
            'rels'           => $rels
        ];
    }

    /**
     * 获取画布全量节点与关联
     *
     * @param int $canvas_id
     * @return array
     */
    private function getGraph($canvas_id)
    {
        $nodes = DB::table('mp_canvas_nodes')
            ->where('canvas_id', $canvas_id)
            ->where('is_deleted', 0)
            ->orderBy('z_index')
            ->orderBy('id')
            ->get()
            ->map(function ($node) use ($canvas_id) {
                return $this->formatNode($node, $canvas_id);
            })
            ->toArray();

        $rels = DB::table('mp_canvas_node_rels')
            ->where('canvas_id', $canvas_id)
            ->orderBy('id')
            ->get()
            ->map(function ($rel) {
                return [
                    'id'         => (int)$rel->id,
                    'node_id_a'  => (int)$rel->node_id_a,
                    'node_id_b'  => (int)$rel->node_id_b
                ];
            })
            ->toArray();

        return ['nodes' => $nodes, 'rels' => $rels];
    }

    /**
     * 格式化节点输出（分镜节点合并分镜数据表字段）
     *
     * @param object $node
     * @param int    $canvas_id
     * @return array
     */
    private function formatNode($node, $canvas_id)
    {
        $node = (array)$node;
        $node['ext'] = $node['ext'] ? json_decode($node['ext'], true) : null;

        if ($node['node_type'] === 'segment') {
            $segment = DB::table('mp_canvas_segments')
                ->where('canvas_id', $canvas_id)
                ->where('node_id', $node['id'])
                ->where('is_deleted', 0)
                ->first();
            if ($segment) {
                $segment = (array)$segment;
                // 分镜数据表为准，覆盖节点级同名关键字段
                foreach (['name', 'text_prompt', 'pic_prompt', 'image_url', 'video_url', 'audio_url', 'duration', 'ext'] as $field) {
                    $node[$field] = $segment[$field];
                }
                $node['segment_number'] = $segment['segment_number'];
                $node['status']         = $segment['status'];
            } else {
                $node['segment_number'] = null;
                $node['status']         = null;
            }
        }

        $node['id']              = (int)$node['id'];
        $node['canvas_id']       = (int)$node['canvas_id'];
        $node['pos_x']           = (float)$node['pos_x'];
        $node['pos_y']           = (float)$node['pos_y'];
        $node['z_index']         = (int)$node['z_index'];
        $node['duration']        = $node['duration'] !== null ? (int)$node['duration'] : null;
        $node['source_product_id'] = $node['source_product_id'] !== null ? (int)$node['source_product_id'] : null;
        $node['source_anime_id']   = $node['source_anime_id'] !== null ? (int)$node['source_anime_id'] : null;
        $node['source_episode_id'] = $node['source_episode_id'] !== null ? (int)$node['source_episode_id'] : null;

        return $node;
    }

    /**
     * 获取节点所有关联节点ID
     *
     * @param int $canvas_id
     * @param int $node_id
     * @return array
     */
    private function getNodeRelIds($canvas_id, $node_id)
    {
        $rels = DB::table('mp_canvas_node_rels')
            ->where('canvas_id', $canvas_id)
            ->where(function ($query) use ($node_id) {
                $query->where('node_id_a', $node_id)
                    ->orWhere('node_id_b', $node_id);
            })
            ->get();

        $ids = [];
        foreach ($rels as $rel) {
            $ids[] = (int)($rel->node_id_a == $node_id ? $rel->node_id_b : $rel->node_id_a);
        }
        return $ids;
    }

    /**
     * 获取节点的关联节点完整信息
     *
     * @param int $canvas_id
     * @param int $node_id
     * @return array
     */
    private function getRelatedNodes($canvas_id, $node_id)
    {
        $ids = $this->getNodeRelIds($canvas_id, $node_id);
        if (!$ids) {
            return [];
        }

        return DB::table('mp_canvas_nodes')
            ->where('canvas_id', $canvas_id)
            ->whereIn('id', $ids)
            ->where('is_deleted', 0)
            ->orderBy('id')
            ->get()
            ->map(function ($node) use ($canvas_id) {
                return $this->formatNode($node, $canvas_id);
            })
            ->toArray();
    }

    /**
     * 可空整型
     *
     * @param mixed $value
     * @return int|null
     */
    private function nullableInt($value)
    {
        return ($value === null || $value === '') ? null : (int)$value;
    }

    /**
     * 可空浮点
     *
     * @param mixed $value
     * @return float|null
     */
    private function nullableFloat($value)
    {
        return ($value === null || $value === '') ? null : (float)$value;
    }

    /**
     * JSON 编码（已是 JSON 字符串则原样保留）
     *
     * @param mixed $value
     * @return string|null
     */
    private function jsonEncode($value)
    {
        if ($value === null || $value === '') {
            return null;
        }
        if (is_string($value)) {
            return json_decode($value, true) !== null ? $value : json_encode($value, JSON_UNESCAPED_UNICODE);
        }
        return json_encode($value, JSON_UNESCAPED_UNICODE);
    }
}