<?php
/**
 * Melk_Advisory_Knowledge — بانک قوانین مالیاتی و حقوقی حوزه ملک (ایران)
 * مرجع آموزشی — جایگزین مشاوره رسمی نیست.
 */
if ( ! defined( 'ABSPATH' ) ) exit;

class Melk_Advisory_Knowledge {

    public static function tax_categories(): array {
        return [
            'capital_gains'    => [ 'label' => 'مالیات بر عایدی سرمایه', 'icon' => '📈' ],
            'transfer_duty'    => [ 'label' => 'مالیات نقل و انتقال', 'icon' => '🔄' ],
            'rental_income'    => [ 'label' => 'مالیات درآمد اجاره', 'icon' => '🏠' ],
            'vat_construction' => [ 'label' => 'ارزش افزوده ساخت', 'icon' => '🏗️' ],
            'municipal_charges'=> [ 'label' => 'عوارض شهرداری', 'icon' => '🏛️' ],
            'inheritance'      => [ 'label' => 'مالیات بر ارث', 'icon' => '📜' ],
            'partnership'      => [ 'label' => 'مشارکت در ساخت', 'icon' => '🤝' ],
            'pre_sale'         => [ 'label' => 'پیش‌فروش و قرارداد', 'icon' => '📋' ],
            'agency_business'  => [ 'label' => 'مالیات بنگاه املاک', 'icon' => '🏢' ],
            'valuation'        => [ 'label' => 'ارزش‌گذاری مالیاتی', 'icon' => '💰' ],
        ];
    }

    public static function legal_categories(): array {
        return [
            'deed_types'       => [ 'label' => 'انواع سند و مالکیت', 'icon' => '📜' ],
            'sale_contract'    => [ 'label' => 'قرارداد خرید و فروش', 'icon' => '📝' ],
            'partnership_law'  => [ 'label' => 'حقوق مشارکت در ساخت', 'icon' => '🤝' ],
            'lease_tenant'     => [ 'label' => 'اجاره و مستأجر', 'icon' => '🔑' ],
            'registry'         => [ 'label' => 'ثبت اسناد و انتقال', 'icon' => '🗂️' ],
            'municipality'     => [ 'label' => 'مجوز و بلامانع', 'icon' => '🏛️' ],
            'disputes'         => [ 'label' => 'اختلافات ملکی', 'icon' => '⚖️' ],
            'inheritance_law'  => [ 'label' => 'ارث و وصیت', 'icon' => '👨‍👩‍👧' ],
            'pre_sale_legal'   => [ 'label' => 'پیش‌فروش حقوقی', 'icon' => '🏗️' ],
            'power_attorney'   => [ 'label' => 'وکالت و نمایندگی', 'icon' => '✍️' ],
        ];
    }

    public static function tax_rules(): array {
        return [
            'capital_gains' => [
                'title'       => 'مالیات بر عایدی سرمایه (انتقال ملک)',
                'summary'     => 'بر درآمد حاصل از انتقال حقوق مالکیت املاک (فروش) مالیات عایدی سرمایه مطالبه می‌شود. مبنای محاسبه تفاوت ارزش فروش با بهای تمام‌شده (با لحاظ هزینه‌های قابل قبول) است.',
                'rate'        => 'طبق جدول نرخ‌های مصوب سازمان امور مالیاتی — نرخ‌ها بر اساس نوع ملک و مدت نگهداری متفاوت است.',
                'obligations' => [
                    'اظهارنامه مالیات بر عایدی سرمایه ظرف مهلت قانونی پس از انتقال',
                    'نگهداری اسناد خرید، پرداخت‌های ساخت، کارمزدها و هزینه‌های بهبود',
                    'استعلام ارزش معاملاتی از سامانه‌های مالیاتی در صورت نیاز',
                ],
                'exemptions'  => [
                    'معافیت‌های مقرر برای مسکن اصلی (مطابق قوانین جاری و شرایط احراز)',
                    'معافیت‌های خاص برای برخی انتقالات بین بستگان در چارچوب قانون',
                    'تنزیل بر اساس مدت نگهداری ملک در برخی مقررات',
                ],
                'risks'       => [ 'عدم اظهار به موقع → جریمه و بدهی معوق', 'اظهار کمتر از ارزش واقعی → جریمه و ممیزی' ],
                'refs'        => [ 'قانون مالیات‌های مستقیم', 'آیین‌نامه اجرایی مالیات بر عایدی سرمایه' ],
                'keywords'    => [ 'عایدی', 'فروش', 'انتقال', 'سود سرمایه', 'فروشنده' ],
            ],
            'transfer_duty' => [
                'title'   => 'مالیات نقل و انتقال قطعی',
                'summary' => 'مالی بر انتقال رسمی حقوق مالکیت در دفترخانه — معمولاً بر مبنای ارزش معامله یا ارزش کارشناسی (هر کدام بالاتر).',
                'rate'    => 'درصد مقرر در قانون مالیات‌های مستقیم (برای اشخاص حقیقی/حقوقی متفاوت).',
                'obligations' => [
                    'پرداخت قبل یا هنگام تنظیم سند رسمی',
                    'ارائه فیش مالیاتی به دفترخانه',
                    'تطابق ارزش اظهاری با ضوابط منطقه‌ای',
                ],
                'exemptions' => [ 'برخی انتقالات دولتی، وقف، و موارد مصرح در قانون' ],
                'risks' => [ 'توقف تنظیم سند بدون پرداخت', 'اختلاف ارزش معامله با کارشناسی' ],
                'refs' => [ 'ماده ۵۹ قانون مالیات‌های مستقیم' ],
                'keywords' => [ 'نقل و انتقال', 'دفترخانه', 'سند رسمی', 'فیش مالیاتی' ],
            ],
            'rental_income' => [
                'title'   => 'مالیات بر درآمد اجاره املاک',
                'summary' => 'درآمد حاصل از اجاره ملک (مسکونی، تجاری، اداری) مشمول مالیات بر درآمد است. مالک موظف به ثبت‌نام و ارائه اظهارنامه است.',
                'rate'    => 'طبق جدول ماده ۱۳۱ ق.م.م — با کسر معافیت و هزینه‌های قابل قبول.',
                'obligations' => [
                    'ثبت‌نام در نظام مالیاتی و دریافت کد اقتصادی در صورت نیاز',
                    'اظهار درآمد اجاره سالانه',
                    'نگهداری قرارداد اجاره و رسیدهای دریافت',
                    'کسر هزینه‌های نگهداری، تعمیرات و بیمه (طبق مقررات)',
                ],
                'exemptions' => [ 'معافیت درآمد اجاره مسکن در سقف مقرر (در صورت انطباق با قوانین جاری)' ],
                'risks' => [ 'اجاره بدون قرارداد رسمی → ریسک اظهار نشدن و جریمه', 'کسر غیرمجاز هزینه' ],
                'refs' => [ 'قانون مالیات‌های مستقیم — درآمد املاک' ],
                'keywords' => [ 'اجاره', 'مستأجر', 'درآمد', 'KOL', 'اظهارنامه' ],
            ],
            'vat_construction' => [
                'title'   => 'مالیات بر ارزش افزوده (ساخت و فروش)',
                'summary' => 'فروش واحدهای ساختمانی نوساز و برخی خدمات ساختمانی مشمول مالیات بر ارزش افزوده است. پیمانکاران و سازندگان باید در نظام ثبت‌نام کنند.',
                'rate'    => 'نرخ مصوب ارزش افزوده (معمولاً ۱۰٪ مگر معافیت).',
                'obligations' => [
                    'صدور فاکتور رسمی برای فروش واحد',
                    'پرداخت مالیات دوره‌ای',
                    'ثبت در سامانه مودیان',
                ],
                'exemptions' => [ 'برخی پروژه‌های مسکن حمایتی طبق قوانین خاص' ],
                'risks' => [ 'فروش بدون فاکتور → جریمه سنگین', 'عدم تفکیک مالیات در قرارداد مشارکت' ],
                'refs' => [ 'قانون مالیات بر ارزش افزوده' ],
                'keywords' => [ 'ارزش افزوده', 'VAT', 'سازنده', 'فاکتور', 'نوساز' ],
            ],
            'municipal_charges' => [
                'title'   => 'عوارض و مالیات شهرداری',
                'summary' => 'شامل عوارض نوسازی، پسماند، مشارکت در تأمین زیرساخت، و عوارض صدور پروانه. مبتنی بر ضابطه و تعرفه شهرداری محل.',
                'rate'    => 'تعرفه مصوب شورای شهر — متغیر بر اساس منطقه، کاربری و متراژ.',
                'obligations' => [
                    'پرداخت عوارض نوسازی سالانه',
                    'تسویه بدهی قبل از صدور پایان کار یا تفکیک',
                    'استعلام بدهی از سامانه شهرداری',
                ],
                'exemptions' => [ 'معافیت‌های محدود برای برخی کاربری‌ها یا ساختمان‌های خاص' ],
                'risks' => [ 'بدهی معوق → توقیف پرونده و عدم صدور مجوز', 'مغایرت متراژ ثبت‌شده با واقع' ],
                'refs' => [ 'قانون شهرداری', 'ضابطه محاسبه عوارض' ],
                'keywords' => [ 'عوارض', 'نوسازی', 'شهرداری', 'پسماند', 'پایان کار' ],
            ],
            'inheritance' => [
                'title'   => 'مالیات بر ارث و ماترک',
                'summary' => 'انتقال مالکیت املاک از طریق ارث مشمول مالیات بر ارث است. ارزیابی ماترک و پرداخت مالیات پیش از انتقال رسمی.',
                'rate'    => 'طبق طبقات ارث و نرخ‌های مقرر در ق.م.م.',
                'obligations' => [
                    'گواهی حصر وراثت',
                    'اظهارنامه مالیات بر ارث',
                    'پرداخت مالیات و دریافت گواهی تسویه',
                    'انتقال سند در دفترخانه',
                ],
                'exemptions' => [ 'معافیت‌های مقرر برای بستگان درجه یک در حد قانون' ],
                'risks' => [ 'اختلاف ارث → توقف انتقال', 'عدم پرداخت مالیات ارث' ],
                'refs' => [ 'قانون مالیات‌های مستقیم — فصل ارث' ],
                'keywords' => [ 'ارث', 'وراث', 'حصر وراثت', 'ماترک' ],
            ],
            'partnership' => [
                'title'   => 'مالیات در مشارکت در ساخت',
                'summary' => 'تقسیم واحدها بین مالک زمین و سازنده هر طرف را از نظر مالیاتی درگیر می‌کند: عایدی برای زمین، ارزش افزوده/عملکرد برای سازنده.',
                'rate'    => 'ترکیبی از عایدی، عملکرد و ارزش افزوده بسته به نقش طرفین.',
                'obligations' => [
                    'ثبت دقیق قرارداد مشارکت و سهم‌الشرکه',
                    'ارزیابی ارزش زمین و سهم ساخت در زمان تقسیم',
                    'اظهار هر طرف برای سهم خود',
                    'فاکتور و اسناد هزینه ساخت برای سازنده',
                ],
                'exemptions' => [],
                'risks' => [ 'قرارداد شفاهی → اختلاف مالیاتی و حقوقی', 'عدم تفکیک سهم‌ها در تقسیم' ],
                'refs' => [ 'قراردادهای مشارکت مدنی', 'بخشنامه‌های مالیاتی' ],
                'keywords' => [ 'مشارکت', 'سازنده', 'مالک زمین', 'تقسیم واحد' ],
            ],
            'pre_sale' => [
                'title'   => 'مالیات پیش‌فروش و فروش امانی',
                'summary' => 'پیش‌فروش واحد در حال ساخت تعهدات مالیاتی برای سازنده و حقوقی برای خریدار دارد. پرداخت‌های مرحله‌ای باید در قرارداد شفاف باشد.',
                'rate'    => 'ارزش افزوده و عایدی بسته به مرحله تحویل و نوع قرارداد.',
                'obligations' => [
                    'قرارداد پیش‌فروش ثبت‌شده/رسمی در چارچوب قانون',
                    'افشای وضعیت مالیاتی پروژه',
                    'صدور فاکتور در تحویل نهایی',
                ],
                'exemptions' => [],
                'risks' => [ 'پروژه نیمه‌کاره → از دست رفتن پیش‌پرداخت', 'عدم ثبت قرارداد' ],
                'refs' => [ 'قانون پیش‌فروش ساختمان' ],
                'keywords' => [ 'پیش‌فروش', 'off-plan', 'پیش‌پرداخت', 'تحویل' ],
            ],
            'agency_business' => [
                'title'   => 'مالیات بنگاه و مشاور املاک',
                'summary' => 'درآمد کمیسیون و خدمات مشاوره مشمول مالیات عملکرد یا ارزش افزوده (بسته به نوع فعالیت ثبت‌شده).',
                'rate'    => 'مالیات عملکرد بر درآمد خالص یا VAT بر خدمات.',
                'obligations' => [
                    'ثبت‌نام مالیاتی و صدور فاکتور برای کمیسیون',
                    'نگهداری دفتر حساب و قراردادهای معامله',
                    'کسر مالیات تکلیفی در پرداخت به برخی ذینفعان (در صورت مقرر)',
                ],
                'exemptions' => [],
                'risks' => [ 'دریافت نقدی بدون ثبت → ممیزی' ],
                'refs' => [ 'ق.م.م — درآمد مشاغل' ],
                'keywords' => [ 'بنگاه', 'کمیسیون', 'مشاور', 'فاکتور' ],
            ],
            'valuation' => [
                'title'   => 'ارزش‌گذاری برای اهداف مالیاتی',
                'summary' => 'سازمان امور مالیاتی و شهرداری‌ها ارزش‌های مرجع (کارشناسی، جدولی) تعیین می‌کنند. مغایرت ارزش معامله با ارزش منطقه‌ای ریسک ممیزی دارد.',
                'rate'    => 'N/A — مبنای محاسبه سایر مالیات‌ها.',
                'obligations' => [
                    'استعلام ارزش منطقه‌ای قبل از معامله',
                    'دریافت نظریه کارشناسی رسمی در اختلاف',
                    'ثبت ارزش واقعی در سند',
                ],
                'exemptions' => [],
                'risks' => [ 'ارزش پایین در سند → رد معامله یا جریمه' ],
                'refs' => [ 'بخشنامه‌های ارزش‌گذاری مالیاتی' ],
                'keywords' => [ 'کارشناسی', 'ارزش منطقه‌ای', 'قیمت منطقه‌ای', 'ممیزی' ],
            ],
        ];
    }

    public static function legal_topics(): array {
        return [
            'deed_types' => [
                'title'   => 'انواع سند مالکیت',
                'summary' => 'سند رسمی دفترخانه قوی‌ترین دلیل مالکیت است. قولنامه/مبایعه‌نامه تنها تعهدات قراردادی ایجاد می‌کند مگر با شرایط خاص.',
                'points'  => [
                    'سند تک‌برگ vs بنچاق — استعلام از ثبت اسناد',
                    'تفکیک — انتقال قطعی پس از صدور سند تفکیکی',
                    'قولنامه عادی: قبل از سند رسمی، حقوق قراردادی قابل پیگیری در دادگاه',
                    'بررسی رهن، توقیف، و حقوق ارتفاقی در استعلام',
                ],
                'checklist' => [ 'استعلام ۱۴ ماده‌ای', 'تطابق مشخصات مالک با کارت ملی', 'بررسی محدودیت انتقال' ],
                'refs' => [ 'قانون ثبت اسناد و املاک', 'آیین‌نامه دفاتر اسناد رسمی' ],
                'keywords' => [ 'سند', 'تک‌برگ', 'قولنامه', 'استعلام', 'رهن' ],
            ],
            'sale_contract' => [
                'title'   => 'قرارداد خرید و فروش ملک',
                'summary' => 'باید شامل مشخصات دقیق طرفین، ملک، قیمت، نحوه پرداخت، زمان تحویل و تنظیم سند باشد.',
                'points'  => [
                    'شرط تنظیم سند در دفترخانه و تقسیم هزینه‌ها',
                    'پرداخت‌های مرحله‌ای با چک/ضمانت',
                    'شرط فسخ در صورت عدم تنظیم سند',
                    'افشای بدهی شهرداری و مالیاتی',
                ],
                'checklist' => [ 'پیوست کروکی و مشخصات ثبتی', 'تعیین وجه التزام', 'حضور وکیل در معاملات پرریسک' ],
                'refs' => [ 'قانون مدنی — بیع', 'قانون ثبت' ],
                'keywords' => [ 'خرید', 'فروش', 'مبایعه', 'قولنامه', 'وجه التزام' ],
            ],
            'partnership_law' => [
                'title'   => 'حقوق مشارکت در ساخت',
                'summary' => 'قرارداد مشارکت مدنی بین مالک زمین و سازنده باید سهم‌الشرکه، زمان‌بندی، کیفیت، تحویل و حل اختلاف را شفاف کند.',
                'points'  => [
                    'تعیین درصد سهم مالک و سازنده (۴۰/۶۰، ۵۰/۵۰ و ...)',
                    'مسئولیت مجوزها، بیمه کارگاه، و استاندارد ساخت',
                    'حل اختلاف: داوری یا دادگاه',
                    'انتقال سهم قبل از پایان کار — محدودیت‌های قراردادی',
                ],
                'checklist' => [ 'پیوست نقشه و پروانه', 'جدول زمان‌بندی', 'ناظر مستقل', 'ثبت قرارداد در صورت امکان' ],
                'refs' => [ 'قانون مدنی — شرکت مدنی', 'عرف مشارکت' ],
                'keywords' => [ 'مشارکت', 'سازنده', 'سهم', 'قرارداد' ],
            ],
            'lease_tenant' => [
                'title'   => 'اجاره و حقوق مستأجر',
                'summary' => 'قانون روابط موجر و مستأجر (مصوب ۱۳۷۶ و اصلاحات) حقوق طرفین را در تمدید، فسخ و افزایش اجاره تنظیم می‌کند.',
                'points'  => [
                    'قرارداد اجاره رسمی یا عادی — مدت و مبلغ',
                    'حقوق مستأجر در تمدید (محدودیت‌های قانونی)',
                    'تخلیه: فقط با حکم دادگاه',
                    'ودیعه و نحوه استرداد',
                ],
                'checklist' => [ 'ثبت در سامانه ملی املاک (در صورت الزام)', 'تحویل فاکتور رسمی', 'بیمه و تعمیرات' ],
                'refs' => [ 'قانون روابط موجر و مستأجر' ],
                'keywords' => [ 'اجاره', 'مستأجر', 'موجر', 'تخلیه', 'ودیعه' ],
            ],
            'registry' => [
                'title'   => 'ثبت اسناد و انتقال رسمی',
                'summary' => 'انتقال مالکیت با سند رسمی در دفترخانه و ثبت در اداره ثبت اسناد نهایی می‌شود.',
                'points'  => [
                    'تهیه مدارک: سند، کارت ملی، فیش مالیاتی',
                    'حضور طرفین یا وکیل با وکالتنامه محضری',
                    'ثبت در دفتر املاک و صدور سند جدید',
                ],
                'checklist' => [ 'استعلام قبل از جلسه', 'تسویه شهرداری', 'پرداخت مالیات نقل و انتقال' ],
                'refs' => [ 'قانون ثبت اسناد و املاک' ],
                'keywords' => [ 'ثبت', 'دفترخانه', 'انتقال', 'سند رسمی' ],
            ],
            'municipality' => [
                'title'   => 'مجوز ساخت و بلامانع',
                'summary' => 'پروانه ساختمانی، پایان کار، و عدم خلاف از شهرداری برای معامله و وام ضروری است.',
                'points'  => [
                    'استعلام بلامانع شهرداری',
                    'بررسی تجاوز به حریم و بناهای غیرمجاز',
                    'تطابق کاربری با سند',
                ],
                'checklist' => [ 'کد نوسازی', 'استعلام ۱۴ ماده', 'بدهی عوارض' ],
                'refs' => [ 'قانون شهرداری', 'بنایی و طرح تفصیلی' ],
                'keywords' => [ 'شهرداری', 'پروانه', 'بلامانع', 'خلاف' ],
            ],
            'disputes' => [
                'title'   => 'اختلافات ملکی',
                'summary' => 'مرجع حل اختلاف: دادگاه عمومی، داوری (در صورت شرط قراردادی)، یا شورای حل اختلاف.',
                'points'  => [
                    'دعاوی مالکیت، تصرف، حقوق ارتفاقی',
                    'اجرای احکام تخلیه و انتقال',
                    'جلوگیری از فروش ملک درگیر دعوا',
                ],
                'checklist' => [ 'استعلام دادگاه', 'وکیل متخصص املاک', 'حفظ مستندات' ],
                'refs' => [ 'آیین دادرسی مدنی' ],
                'keywords' => [ 'اختلاف', 'دعوا', 'تصرف', 'داوری' ],
            ],
            'inheritance_law' => [
                'title'   => 'ارث و انتقال مالکیت',
                'summary' => 'تقسیم ارث طبق قانون مدنی و احکام شرعی/مدنی — گواهی حصر وراثت مبنای انتقال است.',
                'points'  => [
                    'سهم‌الارث قانونی',
                    'وصیت در حد ثلث',
                    'اختلاف وراث → دادگاه خانواده/حقوقی',
                ],
                'checklist' => [ 'حصر وراثت', 'مالیات ارث', 'توافق‌نامه تقسیم' ],
                'refs' => [ 'قانون مدنی — ارث', 'قانون حمایت خانواده' ],
                'keywords' => [ 'ارث', 'وراث', 'وصیت', 'حصر' ],
            ],
            'pre_sale_legal' => [
                'title'   => 'حقوق پیش‌فروش ساختمان',
                'summary' => 'قانون پیش‌فروش ساختمان الزامات ثبت قرارداد، ضمانات و حقوق خریدار را تعیین می‌کند.',
                'points'  => [
                    'ثبت قرارداد در سامانه/اداره مربوط',
                    'حقوق خریدار در تأخیر تحویل',
                    'خروج از پروژه و استرداد',
                ],
                'checklist' => [ 'مجوز پروژه', 'پیشرفت فیزیکی', 'ضمانت‌نامه' ],
                'refs' => [ 'قانون پیش‌فروش ساختمان' ],
                'keywords' => [ 'پیش‌فروش', 'خریدار', 'تحویل', 'ضمانت' ],
            ],
            'power_attorney' => [
                'title'   => 'وکالت در معاملات ملک',
                'summary' => 'وکالتنامه رسمی برای فروش/خرید باید اختیارات صریح (فروش، دریافت وجه، تنظیم سند) داشته باشد.',
                'points'  => [
                    'وکالت بلاعزل محدودیت‌های قانونی دارد',
                    'ابطال وکالت قبل از معامله',
                    'مسئولیت وکیل و موکل',
                ],
                'checklist' => [ 'بررسی اصالت وکالتنامه', 'تطابق مشخصات ملک', 'حدود اختیارات' ],
                'refs' => [ 'قانون مدنی — وکالت' ],
                'keywords' => [ 'وکالت', 'وکیل', 'نماینده', 'محضری' ],
            ],
        ];
    }

    public static function search( string $q, string $domain = 'all' ): array {
        $q = mb_strtolower( trim( $q ) );
        $out = [ 'tax' => [], 'legal' => [] ];
        if ( $domain === 'all' || $domain === 'tax' ) {
            foreach ( self::tax_rules() as $key => $rule ) {
                if ( self::_match( $q, $rule, $key ) ) {
                    $out['tax'][] = array_merge( [ 'key' => $key ], self::_public_tax( $key, $rule ) );
                }
            }
        }
        if ( $domain === 'all' || $domain === 'legal' ) {
            foreach ( self::legal_topics() as $key => $topic ) {
                if ( self::_match( $q, $topic, $key ) ) {
                    $out['legal'][] = array_merge( [ 'key' => $key ], self::_public_legal( $key, $topic ) );
                }
            }
        }
        return $out;
    }

    public static function get_tax( string $key ): ?array {
        $rules = self::tax_rules();
        if ( ! isset( $rules[ $key ] ) ) return null;
        return array_merge( [ 'key' => $key, 'category' => self::tax_categories()[ $key ] ?? [] ], $rules[ $key ] );
    }

    public static function get_legal( string $key ): ?array {
        $topics = self::legal_topics();
        if ( ! isset( $topics[ $key ] ) ) return null;
        return array_merge( [ 'key' => $key, 'category' => self::legal_categories()[ $key ] ?? [] ], $topics[ $key ] );
    }

    public static function list_tax_public(): array {
        $cats = self::tax_categories();
        $out  = [];
        foreach ( self::tax_rules() as $key => $rule ) {
            $out[] = self::_public_tax( $key, $rule, $cats[ $key ] ?? [] );
        }
        return $out;
    }

    public static function list_legal_public(): array {
        $cats = self::legal_categories();
        $out  = [];
        foreach ( self::legal_topics() as $key => $topic ) {
            $out[] = self::_public_legal( $key, $topic, $cats[ $key ] ?? [] );
        }
        return $out;
    }

    public static function build_ai_context(): string {
        $lines = [ '=== بانک دانش مالیات و حقوق ملک (خلاصه) ===' ];
        foreach ( self::tax_rules() as $key => $r ) {
            $lines[] = "[مالیات:{$key}] {$r['title']}: {$r['summary']}";
        }
        foreach ( self::legal_topics() as $key => $t ) {
            $lines[] = "[حقوق:{$key}] {$t['title']}: {$t['summary']}";
        }
        $lines[] = '=== پایان بانک دانش ===';
        return implode( "\n", $lines );
    }

    public static function quick_prompts(): array {
        return [
            [ 'topic' => 'tax', 'text' => 'مالیات فروش آپارتمان منطقه ۱ چقدر است؟' ],
            [ 'topic' => 'tax', 'text' => 'عوارض شهرداری قبل از تنظیم سند چگونه تسویه می‌شود؟' ],
            [ 'topic' => 'tax', 'text' => 'در مشارکت در ساخت چه مالیاتی برای مالک زمین و سازنده وجود دارد؟' ],
            [ 'topic' => 'legal', 'text' => 'قبل از خرید زمین چه استعلام‌هایی لازم است؟' ],
            [ 'topic' => 'legal', 'text' => 'تفاوت قولنامه و سند رسمی چیست؟' ],
            [ 'topic' => 'legal', 'text' => 'در قرارداد مشارکت چه بندهایی حتماً باید باشد؟' ],
        ];
    }

    private static function _public_tax( string $key, array $rule, array $cat = [] ): array {
        return [
            'key'     => $key,
            'icon'    => $cat['icon'] ?? '📋',
            'label'   => $cat['label'] ?? $rule['title'],
            'title'   => $rule['title'],
            'summary' => $rule['summary'],
        ];
    }

    private static function _public_legal( string $key, array $topic, array $cat = [] ): array {
        return [
            'key'     => $key,
            'icon'    => $cat['icon'] ?? '⚖️',
            'label'   => $cat['label'] ?? $topic['title'],
            'title'   => $topic['title'],
            'summary' => $topic['summary'],
        ];
    }

    private static function _match( string $q, array $item, string $key ): bool {
        if ( $q === '' ) return true;
        $hay = mb_strtolower( $key . ' ' . ( $item['title'] ?? '' ) . ' ' . ( $item['summary'] ?? '' ) );
        if ( mb_strpos( $hay, $q ) !== false ) return true;
        foreach ( (array) ( $item['keywords'] ?? [] ) as $kw ) {
            if ( mb_strpos( $q, mb_strtolower( $kw ) ) !== false ) return true;
        }
        return false;
    }
}
