<?php

namespace XZD\AI\V5\Theme;

/**
 * 主题适配器接口 — 定义主题适配层必须实现的所有方法
 */
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块名的映射表，不支持的值为空字符串
     * @return array<string, string>
     */
    public function getBlockMapping(): array;

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

    /**
     * AI写作时的块格式指导，作为 system prompt 的一部分
     */
    public function getAIBlockGuidelines(): string;

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

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