<?php

namespace XZD\AI\V5\Theme;

/**
 * 主题适配器接口 — V5 架构
 *
 * 定义主题适配层必须实现的所有方法。
 * 新增主题只需实现此接口 + 注册到 AdapterRegistry 即可。
 */
interface AdapterInterface
{
    // ===== 身份信息 =====
    public function getThemeName(): string;
    public function getThemeVersion(): string;
    public function isDarkMode(): bool;

    // ===== 能力声明 =====
    /** @return array<string, array{available: bool, reason: string, source: string}> */
    public function getCapabilities(): array;

    // ===== 积分系统 =====
    public function getPoints(int $userId): int;
    public function addPoints(int $userId, int $amount, string $reason, int $operatorId): array;
    public function deductPoints(int $userId, int $amount, string $reason, int $operatorId): array;

    // ===== 余额系统 =====
    public function getBalance(int $userId): float;
    public function addBalance(int $userId, float $amount, string $reason, int $operatorId): array;
    public function deductBalance(int $userId, float $amount, string $reason, int $operatorId): array;

    // ===== VIP 系统 =====
    public function getVipLevel(int $userId): int;
    public function setVipLevel(int $userId, int $level, int $days): array;
    public function removeVip(int $userId): array;

    // ===== 封禁/黑名单 =====
    public function isBanned(int $userId): bool;
    public function banUser(int $userId, string $reason, int $operatorId): array;
    public function unbanUser(int $userId, int $operatorId): array;

    // ===== 通知系统 =====
    public function sendNotification(int $userId, string $title, string $content, int $senderId): array;
    public function sendBulkNotification(array $userIds, string $title, string $content, int $operatorId): array;
    public function sendWebhook(string $url, array $payload, string $event): array;

    // ===== 签到系统 =====
    public function getCheckinStatus(int $userId): array;
    public function doCheckin(int $userId): array;

    // ===== 勋章系统 =====
    public function getMedals(int $userId): array;
    public function addMedal(int $userId, string $medalId): array;
    public function removeMedal(int $userId, string $medalId): array;

    // ===== 邀请系统 =====
    public function getInviteStats(int $userId): array;

    // ===== 订单系统 =====
    public function getOrders(int $userId, int $limit): array;
    public function getShopProducts(int $limit): array;
    public function getProductDetail(int $productId): array;
    public function getVipLevels(): array;
    public function getPointsConfig(): array;

    // ===== 论坛系统 =====
    public function getForumTopics(int $userId, int $limit): array;
    public function getForumPlates(array $params): array;
    public function searchForumTopics(string $keyword, int $limit, int $offset): array;
    public function getForumStats(): array;

    // ===== UI 适配 =====
    public function getThemeColors(): array;
    public function getBubblePosition(): array;
    public function getButtonContainerSelector(): ?string;
    public function hasIntegratedButton(): bool;
    public function getPageContextRules(): array;

    // ===== SEO 适配 =====
    public function setSEOTitle(int $postId, string $title): bool;
    public function setSEODescription(int $postId, string $desc): bool;
    public function setSEOKeywords(int $postId, array $keywords): bool;

    // ===== Gutenberg 块映射 =====

    /**
     * 返回抽象类型→具体Gutenberg块的映射表
     * key=抽象类型(插件统一标识), value=该主题的具体块名
     *
     * 支持的抽象类型:
     *   paragraph, heading, list, quote, code, image, table,
     *   alert, styled_heading, code_highlight, styled_quote,
     *   feature_card, collapse, button_group, post_card,
     *   post_list, seamless_img, separator, preformatted,
     *   pullquote, details
     *
     * @return array<string, string> 抽象类型→块名, 不可用时值为空字符串
     */
    public function getBlockMapping(): array;

    /**
     * 构建一个Gutenberg块数组, 适配当前主题的块类型
     *
     * @param string $abstractType 抽象类型(paragraph, code_highlight等)
     * @param array $data 块内容数据
     * @return array Gutenberg块数组(含blockName/attrs/innerHTML/innerContent/innerBlocks), 不支持的返回空
     */
    public function buildBlock(string $abstractType, array $data): array;

    /**
     * 获取AI写作时的块格式指导 (作为system prompt的一部分)
     * 告诉AI当前主题支持哪些块、块名是什么、HTML结构是怎样的
     */
    public function getAIBlockGuidelines(): string;

    /**
     * 返回文本块的块名列表 (润色/改写/翻译时需要处理这些块)
     * @return array<string>
     */
    public function getTextBlockNames(): array;

    /**
     * 返回编辑器中可用AI操作的块类型列表 (供JS面板使用)
     * @return array 可直接JSON序列化给前端
     */
    public function getEditorBlockConfig(): array;
}
