Review Analyzer Skill

# ==================== 数据源配置 ====================

# Sorftime API Key (可选，用于从 Sorftime 平台获取评论)
# 获取地址: https://www.sorftime.com/
SORFTIME_API_KEY=your_sorftime_api_key_here

# ==================== 分析配置 ====================

# 最大获取评论数 (默认: 500)
MAX_REVIEWS=500

# 每批处理数量 (默认: 30, 范围: 20-50)
# 注意: main.py命令行参数默认为20,此处为config.py中的默认值
BATCH_SIZE=30

# ==================== 输出配置 ====================

# 是否生成 HTML 报告 (默认: true)
GENERATE_HTML=true

# 报告署名 (默认: Buluu@新西楼)
HTML_CREATOR_NAME=Buluu@新西楼

# ==================== CLI 引擎配置 ====================

# CLI 引擎选择 (默认: 自动探测)
# - claude: 使用 Claude Code CLI (claude --print)
# - opencode: 使用 OpenCode CLI (opencode run)
# - 留空或不设置: 自动探测（优先 claude，其次 opencode）
CLI_ENGINE=claude

# CLI 调用超时时间，单位秒 (默认: 600)
CLI_TIMEOUT=600

# ==================== 高级配置 ====================

# 最大并发子代理数 (默认: 4, 上限: 8)
# 注意: 过高可能导致CLI超时,建议范围 2-6
MAX_CONCURRENT=4

# 最多识别的用户画像数 (默认: 4)
MAX_PERSONAS=4

# 每个画像的样本数 (默认: 6, 即 3正+3负)
SAMPLES_PER_PERSONA=6

# 环境变量
.env
.env.local

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# 虚拟环境
venv/
ENV/
env/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# 输出文件
output/
*.xlsx
*.csv.bak

# 系统文件
.DS_Store
Thumbs.db

# 测试
.pytest_cache/
.coverage
htmlcov/

# 日志
*.log

# 图表产物（测试/运行时生成）
diagrams/

review_id,body,rating,date,情感_总体评价,评论价值打分,打标时间
p01b2f3e-796,This power bank saved my trip! I was on a 12-hour flight and my phone battery was dying. This charged my iPhone from 10% to 100% twice and still had power left. The size is perfect for travel and doesn't feel too heavy in my bag.,5.0,2025-09-25,正面,8,2026-03-04 10:00:00
p02a6b3f2-e00,Great capacity for the price. I can charge my tablet and phone multiple times. The LED indicator is helpful to know how much juice is left. Only minor complaint is it takes about 4 hours to fully recharge.,4.0,2025-09-23,正面,7,2026-03-04 10:00:00
p03e5a6dc-1dc,Stopped working after 2 months. It was great at first but now it won't hold a charge. Very disappointed considering the price.,1.0,2025-09-22,负面,9,2026-03-04 10:00:00
p04e9a5d31-8aa,Compact and powerful. Love that it has 2 USB ports so I can charge multiple devices at once. The fast charging works great with my Samsung. Would recommend.,4.0,2025-09-21,正面,6,2026-03-04 10:00:00
p057b0fe9e-2a4,Excelente producto,5.0,2025-09-21,正面,3,2026-03-04 10:00:00
p06554c1a1-566,The best power bank I've owned. Charges my devices quickly and the build quality feels premium.,5.0,2025-09-21,正面,7,2026-03-04 10:00:00
p07414ad53-2c1,Works as described. Not the fastest charging but good enough for everyday use. The 20000mAh lasts me about 3-4 days of normal phone usage.,3.0,2025-09-21,中性,5,2026-03-04 10:00:00
p08e80c984-1f3,Doesn't support fast charging for iPhone as advertised. Misleading product description.,2.0,2025-09-20,负面,8,2026-03-04 10:00:00
p092b731eb0-f77,Amazing value! I've bought 3 of these for my family. Everyone loves them. The carrying pouch is a nice bonus.,5.0,2025-09-20,正面,6,2026-03-04 10:00:00
p1056c8c579-8a,Good backup charger. Keep it in my car for emergencies. Has saved me multiple times when my phone died while traveling.,4.0,2025-09-19,正面,7,2026-03-04 10:00:00

review_id,body,rating,date
p01b2f3e-796,This power bank saved my trip! I was on a 12-hour flight and my phone battery was dying. This charged my iPhone from 10% to 100% twice and still had power left. The size is perfect for travel and doesn't feel too heavy in my bag.,5.0,2025-09-25
p02a6b3f2-e00,Great capacity for the price. I can charge my tablet and phone multiple times. The LED indicator is helpful to know how much juice is left. Only minor complaint is it takes about 4 hours to fully recharge.,4.0,2025-09-23
p03e5a6dc-1dc,Stopped working after 2 months. It was great at first but now it won't hold a charge. Very disappointed considering the price.,1.0,2025-09-22
p04e9a5d31-8aa,Compact and powerful. Love that it has 2 USB ports so I can charge multiple devices at once. The fast charging works great with my Samsung. Would recommend.,4.0,2025-09-21
p057b0fe9e-2a4,Excelente producto,5.0,2025-09-21
p06554c1a1-566,The best power bank I've owned. Charges my devices quickly and the build quality feels premium.,5.0,2025-09-21
p07414ad53-2c1,Works as described. Not the fastest charging but good enough for everyday use. The 20000mAh lasts me about 3-4 days of normal phone usage.,3.0,2025-09-21
p08e80c984-1f3,Doesn't support fast charging for iPhone as advertised. Misleading product description.,2.0,2025-09-20
p092b731eb0-f77,Amazing value! I've bought 3 of these for my family. Everyone loves them. The carrying pouch is a nice bonus.,5.0,2025-09-20
p1056c8c579-8a,Good backup charger. Keep it in my car for emergencies. Has saved me multiple times when my phone died while traveling.,4.0,2025-09-19

MIT License

Copyright (c) 2026 Buluu@新西楼

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

#!/usr/bin/env python3
"""
Amazon 商品评论 AI 深度分析工具 - 主入口 V2.0 (Agent 原生版)
功能：支持交互式向导 + 全参数驱动 + Sorftime数据对接 + 多模板看板 + 飞书同步
"""

import sys
import argparse
import re
import os
from pathlib import Path
from datetime import datetime
import pandas as pd
from dotenv import load_dotenv

# 加载 .env 环境变量
load_dotenv()

# 导入核心模块
from src.data_loader import load_reviews_from_file, download_if_url
from src.review_analyzer import analyze_all
from src.user_persona_analyzer import analyze_user_personas
from src.insights_generator import calculate_stats_summary, generate_insights
from src.config import config

# V2.0 新模块
from src.data_fetchers import get_fetcher, list_fetchers
from src.output_manager import OutputManager
from src.prompts.manager import list_chapters


def print_intro():
    """打印工具详细说明"""
    print("""
🚀 多场景评论内容 AI 深度分析工具 V2.0 — Agent 原生版 Created By Buluu@新西楼
======================================================================
核心功能: 22维度智能标签 · 13章深度洞察报告 · 多风格可视化看板
数据来源: 本地CSV / Sorftime平台
输出方式: MD报告 + HTML看板(多模板) + 飞书同步(可选)
======================================================================
    """)


def config_wizard(total_available: int,
                  preset_max=None, preset_creator=None):
    """
    交互式配置向导（强制交互模式）

    Args:
        total_available: 可用的评论总数
        preset_max: 预设的分析数量（命令行提供）
        preset_creator: 预设的署名（命令行提供）

    Returns:
        tuple: (max_reviews, creator)
    """

    # Q1 (打标深度)
    print(f"🚀 欢迎使用电商评论AI深度洞察器 (V2.0 Created By Buluu@新西楼)")
    print(f"📦 [向导 1/2] 文件共有 {total_available} 条有效评论，您计划打标分析多少条？")
    if preset_max is not None:
        print(f"   [当前预设: {preset_max} 条]")
        max_rev_input = input(f"   请输入数量 (直接回车使用预设值 {preset_max} 条) >>> ").strip()
        max_rev = int(max_rev_input) if max_rev_input else preset_max
    else:
        print("   [默认值: 100 条，建议 100-300]")
        max_rev_input = input("   请输入数量 (直接回车使用默认值 100 条) >>> ").strip()
        max_rev = int(max_rev_input) if max_rev_input else 100
    # 确保不超过可用数量
    max_rev = min(max_rev, total_available)

    # Q2 (报告署名)
    print("\n✍️ [向导 2/2] 报告需要个性化署名吗？")
    if preset_creator is not None:
        print(f"   [当前预设: {preset_creator}]")
        creator_input = input(f"   请输入署名 (直接回车使用预设值 '{preset_creator}') >>> ").strip()
        creator = creator_input if creator_input else preset_creator
    else:
        print("   [留空默认为: AI Assistant]")
        creator_input = input("   请输入署名 (直接回车使用默认值) >>> ").strip()
        creator = creator_input if creator_input else None

    # 打印配置总结
    print("\n" + "=" * 60)
    print("✅ 配置确认：")
    print(f"   📊 分析数量: {max_rev} 条")
    print(f"   🤖 运行模式: CLI 本地模式")
    print(f"   ✍️  报告署名: {creator or 'AI Assistant'}")
    print("=" * 60 + "\n")

    return (max_rev, creator)


def save_tagged_reviews_to_csv(tagged_reviews: list, asin: str) -> Path:
    """将打标后的评论数据保存为 CSV 文件"""
    flattened_reviews = []
    for review in tagged_reviews:
        original_data = review.get("_original_data", {})
        flat_row = dict(original_data)
        tags = review.get("tags", {})
        for tag_key, tag_value in tags.items():
            if tag_key != "情感_总体评价":
                flat_row[tag_key] = tag_value
        flat_row["情感_总体评价"] = tags.get("情感_总体评价", "")
        flat_row["评论价值打分"] = review.get("info_score", 0)
        flat_row["打标时间"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        flattened_reviews.append(flat_row)

    df = pd.DataFrame(flattened_reviews)
    csv_path = config.get_csv_path(asin)
    df.to_csv(csv_path, index=False, encoding=config.CSV_ENCODING)
    return csv_path


def extract_asin_from_file(file_path: str) -> str:
    """从文件名提取 ASIN"""
    filename = Path(file_path).stem
    asin_pattern = r'[A-Z0-9]{10}'
    matches = re.findall(asin_pattern, filename.upper())
    return matches[0] if matches else filename.upper()[:10]


def is_interactive_environment():
    """检测是否在交互式终端环境中运行"""
    return sys.stdin.isatty()


def main():
    """主函数"""

    parser = argparse.ArgumentParser(description="Amazon Review Analyzer V2.0 — Agent 原生版")
    parser.add_argument("input_file", nargs="?", default=None,
                        help="输入 CSV/Excel 文件路径或 URL（使用 --source sorftime 时可省略）")
    # V2.0: 数据来源
    parser.add_argument("--source", choices=["csv", "sorftime"], default="csv",
                        help="数据来源: csv(默认) 或 sorftime")
    parser.add_argument("--asin", help="产品 ASIN（--source sorftime 时必填）")
    parser.add_argument("--site", default="US",
                        help="站点代码（默认 US，可选 UK/DE/JP 等）")
    # V2.0: 模板与输出
    parser.add_argument("--template", default="premium-gold",
                        help="可视化看板模板名称（默认 premium-gold，传 none 跳过HTML生成）")
    parser.add_argument("--feishu-sync", action="store_true",
                        help="同步结果到飞书文档（需要 lark-cli）")
    # 原有参数
    parser.add_argument("--engine", choices=["claude", "opencode"], default=None,
                        help="CLI 引擎: claude (默认) 或 opencode")
    parser.add_argument("--max-reviews", type=int, help="分析评论上限", default=None)
    parser.add_argument("--batch-size", type=int, default=20, help="批次大小")
    parser.add_argument("--concurrent", type=int, default=None,
                        help="最大并发批次数 (默认4, 上限8)")
    parser.add_argument("--creator", help="报告署名/品牌", default=None)
    parser.add_argument("--output-dir", help="自定义输出目录")
    args = parser.parse_args()

    # 参数校验
    if args.source == "sorftime" and not args.asin:
        parser.error("--source sorftime 需要 --asin 参数")
    if args.source == "csv" and not args.input_file:
        parser.error("CSV 模式需要提供输入文件路径")

    # 判断是否缺少关键参数
    _missing_params = []
    if args.max_reviews is None:
        _missing_params.append("--max-reviews")
    if args.creator is None:
        _missing_params.append("--creator")
    needs_interaction = len(_missing_params) > 0

    # 非交互环境 + 缺少参数 → 拒绝执行，报错退出
    if needs_interaction and not is_interactive_environment():
        print("=" * 70)
        print("❌ 缺少必要参数，无法在非交互式环境中运行")
        print("=" * 70)
        print()
        print("  缺少以下参数：")
        for p in _missing_params:
            print(f"    ⚠️  {p}")
        print()
        print("  请通过命令行提供完整参数：")
        print(f"    python3 main.py '{args.input_file}' \\")
        print("      --max-reviews 100 \\")
        print("      --creator '你的署名'")
        print()
        print("  💡 提示：如需使用交互式菜单，请直接在终端中运行此命令。")
        print("=" * 70)
        sys.exit(1)

    # 打印工具说明（向导第一步）
    print_intro()

    # 处理 --engine 参数
    if args.engine:
        config.CLI_ENGINE = args.engine
        print(f"🔧 CLI 引擎: {config.CLI_ENGINE}")

    # V2.0: 数据获取（支持 Sorftime 或本地 CSV）
    if args.source == "sorftime":
        print(f"\n📡 [数据获取] 从 Sorftime 获取评论数据...")
        print(f"   ASIN: {args.asin}, 站点: {args.site}")
        fetcher = get_fetcher("sorftime")
        if not fetcher.validate_config():
            print("❌ Sorftime 配置无效。请设置 SORFTIME_API_KEY 环境变量。")
            sys.exit(1)
        try:
            csv_path_str = fetcher.fetch(args.asin, fields=None, site=args.site)
            resolved_file = csv_path_str
            print(f"✅ 数据获取完成: {csv_path_str}")
        except Exception as e:
            print(f"❌ Sorftime 数据获取失败: {e}")
            sys.exit(1)
    else:
        # 原有 CSV 路径
        if not args.input_file:
            print("❌ CSV 模式需要提供输入文件路径")
            sys.exit(1)
        resolved_file = download_if_url(args.input_file)

    input_path = Path(resolved_file)
    if not input_path.exists():
        print(f"❌ 错误：找不到文件: {input_path}")
        sys.exit(1)

    # 2. 加载初始数据以获取评论总数
    reviews, original_df = load_reviews_from_file(resolved_file)
    total_available = len(reviews)
    print(f"📄 成功加载表格：检测到 {total_available} 条有效评论记录")

    # 3. 配置合并 (优先级：命令行 > 向导 > 默认)
    if not needs_interaction:
        # 两个参数都已通过命令行提供，跳过向导
        print(f"\n✅ 检测到完整命令行参数，跳过交互式向导")
        max_reviews = args.max_reviews
        creator = args.creator
    else:
        # 在 TTY 环境且缺少参数 → 启动交互式向导
        wizard_max_reviews, wizard_creator = config_wizard(
            total_available=total_available,
            preset_max=args.max_reviews,
            preset_creator=args.creator
        )
        print()  # 向导结束后添加空行
        # 向导结果优先
        max_reviews = wizard_max_reviews
        creator = wizard_creator

    # 应用配置
    if max_reviews:
        config.MAX_REVIEWS = max_reviews

    if creator:
        config.HTML_CREATOR_NAME = creator

    # 并发数配置
    if args.concurrent:
        config.MAX_CONCURRENT_AGENTS = args.concurrent

    # 模式固定为 CLI 本地模式
    engine_label = "OpenCode" if config.CLI_ENGINE == "opencode" else "Claude CLI"
    print(f"💡 模式：{engine_label} 本地模式 (全本地方案)")
    print(f"🔧 并发线程数: {config.MAX_CONCURRENT_AGENTS}")

    # 应用自定义输出目录
    if args.output_dir:
        output_path = Path(args.output_dir)
        if output_path.exists() and output_path.is_file():
            print(f"❌ 错误：输出路径是一个文件，不是目录: {output_path}")
            sys.exit(1)
        config.OUTPUT_DIR = output_path
        # 确保输出目录存在
        config.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
        print(f"📁 自定义输出目录: {config.OUTPUT_DIR}")

    asin = args.asin if args.source == "sorftime" else extract_asin_from_file(resolved_file)

    # 截断评论
    if len(reviews) > config.MAX_REVIEWS:
        print(f"✂️  评论总数 {len(reviews)} 超过上限，截取前 {config.MAX_REVIEWS} 条")
        reviews = reviews[:config.MAX_REVIEWS]

    try:
        # ========== 执行全流程 ==========

        # Phase 1: AI 深度打标分析
        print(f"\n🧠 [Phase 1/4] 评论AI深度打标分析中...")
        tagged_reviews = analyze_all(reviews, batch_size=args.batch_size)
        print(f"✅ [Phase 1/4] 评论打标完成！成功分析 {len(tagged_reviews)} 条评论\n")

        # Phase 2: 用户画像识别与降级逻辑配置
        print(f"👥 [Phase 2/4] 用户画像识别与降级逻辑配置中...")
        print(f"   - 正在分析 {len(tagged_reviews)} 条打标评论...")
        print(f"   - 识别用户画像中...")
        personas, golden_samples = analyze_user_personas(tagged_reviews)
        print(f"✅ [Phase 2/4] 用户画像识别完成！识别到 {len(personas)} 个画像，{len(golden_samples)} 条黄金样本\n")

        # Phase 3: AI 撰写深度战略洞察报告
        print(f"📝 [Phase 3/4] AI深度战略洞察报告生成中...")
        print(f"   - 正在生成 {len(personas)} 个用户画像分析...")
        print(f"   - 使用引擎: {engine_label}")
        stats = calculate_stats_summary(tagged_reviews)
        insights_md = generate_insights(
            stats=stats,
            personas=personas,
            golden_samples=golden_samples,
            asin=asin
        )
        if insights_md:
            print(f"✅ [Phase 3/4] 洞察报告已生成！字数约 {len(insights_md):,} 字\n")
        else:
            print(f"⚠️ [Phase 3/4] 洞察报告生成失败\n")

        # 保存 Markdown
        md_path = config.get_md_path(asin)
        if insights_md:
            with open(md_path, 'w', encoding='utf-8') as f:
                f.write(insights_md)

        # 保存 CSV
        csv_path = save_tagged_reviews_to_csv(tagged_reviews, asin)

        # Phase 4 (V2.0): 输出管理 — 统一生成 MD + HTML看板 + 飞书同步
        print(f"📦 [Phase 4/4] 生成完整输出包...")
        from src.output_manager import generate_outputs, select_template

        # 选择模板（none 表示跳过 HTML 生成）
        template_name = args.template
        if template_name.lower() == "none":
            template_name = None  # 跳过 HTML 看板
        else:
            # 如果模板不存在，使用默认
            try:
                from src.template_engine import list_templates as _lt
                available = [t["name"] for t in _lt()]
                if template_name not in available:
                    print(f"   ⚠️ 模板 '{template_name}' 不存在，使用默认模板")
                    template_name = available[0] if available else "premium-gold"
            except Exception:
                pass

        # 构建统计摘要
        summary = {
            "total": len(tagged_reviews),
            "tagged": stats["tagged"],
            "persona_count": len(personas),
            "avg_rating": stats.get("avg_rating", 0),
            "sentiment": stats.get("sentiment", {}),
            "top_tags": stats.get("top_tags", {})
        }

        # 准备分析数据给 OutputManager
        analysis_data_for_output = {
            "asin": asin,
            "product_name": asin,
            "total_reviews": len(tagged_reviews),
            "avg_rating": stats.get("avg_rating", 0),
            "summary": summary,
            "sentiment": stats.get("sentiment", {}),
            "sentiment_distribution": stats.get("sentiment", {}),
            "tag_statistics": stats.get("top_tags", {}),
            "top_tags": stats.get("top_tags", {}),
            "dimensional_stats": stats.get("dimensional_stats", {}),
            "personas": [{"name": p.get("name", ""), "count": p.get("count", 0), "tags": p.get("tags", {})} for p in personas],
            "golden_samples": golden_samples,
            "insights_md": insights_md,
            "statistics": stats,
        }

        output_config = {
            "template_name": template_name,
            "sync_feishu": args.feishu_sync,
            "output_dir": str(config.OUTPUT_DIR),
            "asin": asin,
            "creator": config.HTML_CREATOR_NAME,
        }

        output_results = generate_outputs(analysis_data_for_output, output_config)

        # 飞书同步结果
        feishu_result = output_results.get("feishu_result", {})
        if args.feishu_sync:
            if feishu_result and feishu_result.get("success"):
                print(f"   ✅ 飞书同步成功！")
                if feishu_result.get("doc_url"):
                    print(f"   📄 文档: {feishu_result['doc_url']}")
                wb_count = feishu_result.get("whiteboard_count", 0)
                if wb_count > 0:
                    print(f"   📊 白板图表: {wb_count} 个已渲染")
            else:
                error = feishu_result.get("error", "未知错误") if feishu_result else "同步失败"
                print(f"   ⚠️ 飞书同步失败: {error}")
                print(f"   💡 本地文件已安全生成，不影响使用")

        # 最终输出结果
        final_md = output_results.get("md_path", str(md_path))
        final_html = output_results.get("html_path", "")

        print("\n" + "✨" * 30)
        print("🎉 分析任务圆满完成！")
        print(f"  - 洞察报告: {Path(final_md).name}")
        print(f"  - 结构数据: {csv_path.name}")
        if final_html:
            print(f"  - 可视化看板: {Path(final_html).name} (模板: {template_name})")
        else:
            print(f"  - 可视化看板: 已跳过")
        if args.feishu_sync and feishu_result and feishu_result.get("doc_url"):
            print(f"  - 飞书文档: {feishu_result['doc_url']}")
            wb_count = feishu_result.get("whiteboard_count", 0)
            if wb_count > 0:
                print(f"  - 白板图表: {wb_count} 个")
        print("✨" * 30 + "\n")

    except Exception as e:
        print(f"\n❌ 引擎崩溃: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)


if __name__ == "__main__":
    main()

# 亚马逊商品评论标签体系配置
# Amazon Product Review Tag System Configuration
# 版本: V1
# 来源: 基于 n8n 工作流适配

# ==================== 标签维度定义 ====================
tag_dimensions:
  # 人群维度 (4个标签)
  人群:
    - name: 人群_性别
      options: [男性, 女性, 不明]
      description: 用户性别

    - name: 人群_年龄段
      options: [18-25, 26-35, 36-45, 46-55, 55+, 不明]
      description: 用户年龄段

    - name: 人群_职业
      options:
        - 医疗工作者
        - 体力劳动者
        - 办公室职员
        - 学生
        - 退休人员
        - 教师
        - 司机
        - 其他
        - 不明
      description: 根据评论内容推断的职业身份

    - name: 人群_购买角色
      options: [自用, 礼物, 商用, 不明]
      description: 购买目的

  # 场景维度 (1个标签)
  场景:
    - name: 场景_使用场景
      options:
        - 家用
        - 办公
        - 户外
        - 运动
        - 开车
        - 旅行
        - 其他
      description: 根据评论内容推断的使用场景

  # 功能维度 (2个标签)
  功能:
    - name: 功能_满意度
      options: [超出预期, 符合预期, 低于预期, 未提及]
      description: 整体功能满意度

    - name: 功能_具体功能
      type: text
      description: 简述用户提到的具体功能点，如：续航能力/防水功能/保暖效果/降噪功能等

  # 质量维度 (3个标签)
  质量:
    - name: 质量_材质
      options: [优秀, 良好, 一般, 差, 未提及]
      description: 材质质量评价

    - name: 质量_做工
      options: [精细, 一般, 粗糙, 未提及]
      description: 做工精细度

    - name: 质量_耐用性
      options: [耐用, 一般, 易坏, 未提及]
      description: 产品耐用性

  # 服务维度 (5个标签)
  服务:
    - name: 服务_发货速度
      options: [快, 正常, 慢, 未提及]
      description: 发货速度评价

    - name: 服务_包装质量
      options: [完好, 一般, 破损, 未提及]
      description: 包装质量

    - name: 服务_客服响应
      options: [及时, 一般, 迟缓, 未提及]
      description: 客服响应速度

    - name: 服务_退换货
      options: [顺畅, 一般, 困难, 未提及]
      description: 退换货体验

    - name: 服务_保修
      options: [有保修, 无保修, 未提及]
      description: 是否有保修

  # 体验维度 (4个标签)
  体验:
    - name: 体验_舒适度
      options: [舒适, 一般, 不适, 未提及]
      description: 使用舒适度

    - name: 体验_易用性
      options: [简单, 适中, 困难, 未提及]
      description: 易用性评价

    - name: 体验_外观设计
      options: [满意, 一般, 不满意, 未提及]
      description: 外观设计满意度

    - name: 体验_价格感知
      options: [超值, 合理, 偏贵, 未提及]
      description: 价格感知

  # 市场维度 (2个标签)
  市场:
    - name: 竞品_竞品对比
      type: text
      description: 用户提及的竞品品牌名称，如：品牌A/品牌B/品牌C等，如无则填'无'
      examples:
        - 品牌A
        - 品牌B
        - 品牌C
        - 无

    - name: 复购_复购意愿
      options: [会复购, 可能, 不会, 未提及]
      description: 复购意愿

  # 情感维度 (1个标签)
  情感:
    - name: 情感_总体评价
      options: [强烈推荐, 推荐, 中立, 不推荐, 强烈不推荐]
      description: 总体情感评价

# ==================== 评分规则 ====================
scoring:
  info_score:
    range: [1, 20]
    rules:
      - name: 基础分_字数
        condition: "评论字数 > 50"
        score: 1
      - name: 基础分_长评
        condition: "评论字数 > 200"
        score: 2
      - name: 标签分
        condition: "每个有效标签（非'未提及'）"
        score: 1
      - name: 加分_竞品
        condition: "提及竞品"
        score: 5
      - name: 加分_复购
        condition: "明确复购意愿"
        score: 3
      - name: 加分_场景
        condition: "描述使用场景"
        score: 2

# ==================== 输出格式 ====================
output_format:
  type: json
  structure:
    review_id: string
    sentiment: enum[强烈推荐, 推荐, 中立, 不推荐, 强烈不推荐]
    info_score: integer[1-20]
    tags: object

# ==================== 注意事项 ====================
notes:
  - 无依据的标签填"不明"或"未提及"
  - 职业标签、使用场景均需从评论内容中推断
  - info_score 反映评论的信息价值密度
  - 只返回纯JSON，不要任何解释文字

{
    "meta": {
        "product_name": "输入你的产品名称",
        "report_title": "评论深度分析洞察",
        "signature": "Created By 输入你的名字",
        "retail_price": "输入你的产品价格",
        "sample_size": "输入评论数量",
        "status": "Strategic Review"
    },
    "kpis": [
        {
            "title": "Surpass Expectation",
            "value": "55",
            "label": "超出预期",
            "desc": "极高的初始体验"
        },
        {
            "title": "Strong Recommend",
            "value": "60",
            "label": "强烈推荐",
            "desc": "品牌护城河稳固"
        },
        {
            "title": "Material Failure",
            "value": "15",
            "label": "致命缺陷",
            "desc": "关键组件易损",
            "is_danger": true
        },
        {
            "title": "Brand Churn",
            "value": "10",
            "label": "客户流失",
            "desc": "明确拒绝复购"
        }
    ],
    "market_insights": [
        {
            "icon": "fa-users-viewfinder",
            "title": "核心受众画像",
            "desc": "此处输入人群分析结论..."
        },
        {
            "icon": "fa-wand-magic-sparkles",
            "title": "易用性评估",
            "desc": "此处输入易用性结论..."
        },
        {
            "icon": "fa-gift",
            "title": "购买场景特征",
            "desc": "此处输入购买动机结论..."
        },
        {
            "icon": "fa-chess-knight",
            "title": "竞品威胁区隔",
            "desc": "此处输入竞品分析结论..."
        }
    ],
    "charts_data": {
        "sentiment": {
            "labels": [
                "超出预期",
                "符合预期",
                "低于预期"
            ],
            "data": [
                55,
                30,
                15
            ]
        },
        "features": {
            "labels": [
                "卖点1",
                "卖点2",
                "卖点3",
                "卖点4",
                "卖点5"
            ],
            "data": [
                30,
                25,
                20,
                15,
                10
            ]
        },
        "scenarios": {
            "labels": [
                "场景1",
                "场景2",
                "场景3",
                "场景4",
                "场景5"
            ],
            "data": [
                40,
                20,
                15,
                15,
                10
            ]
        },
        "price_perception": {
            "labels": [
                "物超所值",
                "偏贵",
                "合理"
            ],
            "data": [
                50,
                30,
                20
            ]
        },
        "design_usability": {
            "labels": [
                "正面评价1",
                "正面评价2",
                "负面1",
                "负面2"
            ],
            "data": [
                40,
                45,
                10,
                5
            ]
        },
        "durability": {
            "labels": [
                "严重易损",
                "质量稳定",
                "一般"
            ],
            "data": [
                15,
                75,
                10
            ]
        }
    },
    "strategy": {
        "moat_pros": [
            {
                "title": "护城河/优势 1",
                "desc": "深度解析..."
            },
            {
                "title": "护城河/优势 2",
                "desc": "深度解析..."
            }
        ],
        "vulnerability_cons": [
            {
                "title": "致命弱点/风险 1",
                "desc": "深度解析..."
            },
            {
                "title": "致命弱点/风险 2",
                "desc": "深度解析..."
            }
        ]
    },
    "execution_matrix": [
        {
            "urgency": "Immediate",
            "directive": "高管指令1",
            "details": "执行细节...",
            "roi": "预期ROI..."
        },
        {
            "urgency": "Short-Term",
            "directive": "高管指令2",
            "details": "执行细节...",
            "roi": "预期ROI..."
        },
        {
            "urgency": "Long-Term",
            "directive": "高管指令3",
            "details": "执行细节...",
            "roi": "预期ROI..."
        }
    ],
    "voc_quotes": [
        {
            "profile": "用户标签1 / Advocate",
            "quote": "正面原声内容...",
            "status": "High Satisfaction",
            "is_danger": false
        },
        {
            "profile": "用户标签2 / Detractor",
            "quote": "负面原声内容...",
            "status": "Severe Attrition",
            "is_danger": true
        },
        {
            "profile": "用户标签3 / Passive",
            "quote": "中立原声内容...",
            "status": "Premium Perception",
            "is_danger": false
        },
        {
            "profile": "用户标签4 / Detractor",
            "quote": "负面原声内容...",
            "status": "Trust Broken",
            "is_danger": true
        }
    ]
}

#!/usr/bin/env python3
"""
快速重放脚本：从已打标的 CSV 跳过 Phase 1，直接执行 Phase 2-5
用法：python3 replay_phase2to5.py <tagged_csv> [--template TEMPLATE]
"""
import sys
import os
import json
import argparse
from pathlib import Path
from datetime import datetime
from dotenv import load_dotenv

load_dotenv()

import pandas as pd

# 项目根目录
BASE_DIR = Path(__file__).parent
sys.path.insert(0, str(BASE_DIR))

from src.config import config
from src.user_persona_analyzer import analyze_user_personas
from src.insights_generator import calculate_stats_summary, generate_insights
from src.report_generator import generate_html_report
from src.output_manager import generate_outputs


def load_tagged_csv(csv_path: str) -> list:
    """从已打标 CSV 加载评论数据"""
    df = pd.read_csv(csv_path)
    reviews = []
    for _, row in df.iterrows():
        tags = {}
        tag_columns = [c for c in df.columns if any(
            prefix in c for prefix in
            ['人群_', '场景_', '功能_', '质量_', '服务_', '体验_', '竞品_', '复购_']
        )]
        for col in tag_columns:
            val = row.get(col)
            if pd.notna(val) and str(val).strip():
                tags[col] = str(val).strip()

        sentiment = str(row.get('情感_总体评价', '')).strip() if pd.notna(row.get('情感_总体评价')) else ''

        review = {
            'body': str(row.get('Content', row.get('content', ''))).strip(),
            'rating': int(row.get('Rating', row.get('rating', 0))) if pd.notna(row.get('Rating', row.get('rating'))) else 0,
            'sentiment': sentiment,
            'tags': tags,
            'date': str(row.get('Date', row.get('date', ''))).strip() if pd.notna(row.get('Date', row.get('date'))) else '',
            'author': str(row.get('Author', row.get('author', ''))).strip() if pd.notna(row.get('Author', row.get('author'))) else '',
        }
        reviews.append(review)
    return reviews


def extract_asin_from_path(csv_path: str) -> str:
    """从文件名或路径中提取 ASIN"""
    name = Path(csv_path).stem
    # 尝试从文件名中提取 ASIN (格式通常为 xxx_B0XXXXX)
    import re
    match = re.search(r'(B0[A-Z0-9]{7,})', name)
    if match:
        return match.group(1)
    return 'UNKNOWN'


def main():
    parser = argparse.ArgumentParser(description='重放 Phase 2-5（跳过打标）')
    parser.add_argument('csv_file', help='已打标的 CSV 文件路径')
    parser.add_argument('--template', default='stripe-executive', help='HTML 模板名称')
    parser.add_argument('--creator', default='Buluu@新西楼', help='署名')
    parser.add_argument('--output-dir', default=None, help='输出目录')
    args = parser.parse_args()

    csv_path = Path(args.csv_file)
    if not csv_path.exists():
        print(f"❌ 文件不存在: {csv_path}")
        sys.exit(1)

    asin = extract_asin_from_path(str(csv_path))
    print(f"📋 ASIN: {asin}, 模板: {args.template}")

    # 配置（统一 CLI 本地模式）
    config.HTML_CREATOR_NAME = args.creator
    if args.output_dir:
        config.OUTPUT_DIR = Path(args.output_dir)
        config.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

    # 加载已打标数据
    print(f"\n📄 加载已打标数据: {csv_path.name}")
    tagged_reviews = load_tagged_csv(str(csv_path))
    print(f"   ✅ 加载 {len(tagged_reviews)} 条已打标评论")

    # Phase 2: 用户画像
    print(f"\n👥 [Phase 2/4] 用户画像识别...")
    personas, golden_samples = analyze_user_personas(tagged_reviews)
    print(f"   ✅ {len(personas)} 个画像, {len(golden_samples)} 条黄金样本")

    # Phase 3: 洞察报告
    print(f"\n📝 [Phase 3/4] AI 深度洞察报告生成中...")
    stats = calculate_stats_summary(tagged_reviews)
    insights_md = generate_insights(
        stats=stats, personas=personas, golden_samples=golden_samples, asin=asin
    )
    if insights_md:
        print(f"   ✅ 报告已生成 ({len(insights_md):,} 字)")
    else:
        print(f"   ⚠️ 报告生成失败")
        insights_md = ""

    # 保存 MD
    md_path = config.get_md_path(asin)
    with open(md_path, 'w', encoding='utf-8') as f:
        f.write(insights_md)

    # Phase 4: HTML 看板 (V1 report_generator)
    print(f"\n🎨 [Phase 4a] V1 HTML 看板生成...")
    summary = {
        "total": len(tagged_reviews),
        "tagged": stats["tagged"],
        "persona_count": len(personas),
        "avg_rating": stats.get("avg_rating", 0),
        "sentiment": stats.get("sentiment", {}),
        "top_tags": stats.get("top_tags", {})
    }
    html_path = generate_html_report(
        asin=asin, summary=summary, personas=personas,
        sentiment_distribution=stats["sentiment"],
        tag_statistics=stats["top_tags"],
        golden_samples=golden_samples,
        insights_md=insights_md,
        creator_name=config.HTML_CREATOR_NAME
    )
    print(f"   ✅ V1 看板: {html_path.name if html_path else '失败'}")

    # Phase 5: OutputManager (V2 模板看板)
    print(f"\n📦 [Phase 4b] V2 模板看板生成 ({args.template})...")
    analysis_data = {
        "asin": asin, "product_name": asin,
        "total_reviews": len(tagged_reviews),
        "avg_rating": stats.get("avg_rating", 0),
        "summary": summary,
        "sentiment": stats.get("sentiment", {}),
        "sentiment_distribution": stats.get("sentiment", {}),
        "tag_statistics": stats.get("top_tags", {}),
        "top_tags": stats.get("top_tags", {}),
        "personas": [{"name": p.get("name",""), "count": p.get("count",0), "tags": p.get("tags",{})} for p in personas],
        "golden_samples": golden_samples,
        "insights_md": insights_md,
        "statistics": stats,
    }
    output_config = {
        "template_name": args.template,
        "sync_feishu": False,
        "output_dir": str(config.OUTPUT_DIR),
        "asin": asin,
        "creator": config.HTML_CREATOR_NAME,
    }
    output_results = generate_outputs(analysis_data, output_config)

    v2_html = output_results.get("html_path", "")
    print(f"   ✅ V2 看板: {v2_html}")

    print("\n" + "✨" * 30)
    print("🎉 重放完成！")
    print(f"  - 洞察报告: {md_path.name}")
    print(f"  - V1 看板: {html_path.name if html_path else 'N/A'}")
    print(f"  - V2 看板: {Path(v2_html).name if v2_html else 'N/A'}")
    print("✨" * 30)


if __name__ == "__main__":
    main()

# ==================== 核心依赖 ====================

# HTTP 客户端（数据获取 + API 调用）
requests==2.32.3

# HTML 解析库
beautifulsoup4==4.12.3

# ==================== 数据处理 ====================

# 数据处理和分析
pandas==2.2.3

# ==================== 模板引擎 ====================

# Jinja2 模板引擎 (用于 HTML 报告生成)
jinja2==3.1.4

# ==================== 配置管理 ====================

# 环境变量管理
python-dotenv==1.0.1

# ==================== 可选依赖 ====================

# 进度条显示
tqdm==4.66.4

# ==================== V2.0 新增依赖 ====================
# 以上依赖已足够，无需新增额外包
# - chart_engine: 纯 Python 实现
# - template_engine: 基于 Jinja2
# - feishu_sync: 通过 subprocess 调用 lark-cli
# - sorftime_fetcher: 通过 requests 调用 API

"""
评论分析 Skill - 核心包初始化

Amazon 商品评论 AI 深度分析工具 V1.0
"""

"""
配置管理模块 V2.0 — Agent 原生版

重大变更：
- 打标阶段改为 Prompt Router，宿主 Agent 直接执行，不再依赖 subprocess CLI
- 新增数据接入层配置（Sorftime 平台）
- 新增可视化模板系统配置
- 新增飞书同步配置
- 新增图表引擎配置
- 统一使用 CLI 引擎，不再支持 Gemini API
"""

import os
from dataclasses import dataclass, field
from pathlib import Path
from datetime import datetime


@dataclass
class Config:
    """全局配置类 V2.0 - Agent 原生版"""

    # ==================== 项目路径配置 ====================
    PROJECT_ROOT: Path = field(default_factory=lambda: Path(__file__).parent.parent)
    # 输出目录: 支持环境变量 OUTPUT_DIR 或命令行参数 --output-dir
    OUTPUT_DIR: Path = field(default_factory=lambda: Path(os.getenv("OUTPUT_DIR", "./output")))
    REFERENCES_DIR: Path = field(default_factory=lambda: Path(__file__).parent.parent / "references")
    ASSETS_DIR: Path = field(default_factory=lambda: Path(__file__).parent.parent / "assets")
    DATA_DIR: Path = field(default_factory=lambda: Path(__file__).parent.parent / "data")

    # ==================== CLI 引擎配置 ====================
    # 支持 claude / opencode 两种 CLI 引擎
    # claude  → subprocess: claude --print --dangerously-skip-permissions <prompt>
    # opencode → subprocess: opencode run <prompt>
    # 未指定时自动探测: 优先 claude，其次 opencode
    # V2.0 备注：打标阶段不再使用 CLI，由宿主 Agent 直接执行
    #            CLI 引擎仅用于洞察报告和 HTML 看板的生成
    CLI_ENGINE: str = ""  # 可选: claude / opencode / 留空自动探测
    CLAUDE_CLI_CMD: str = "claude"
    OPENCODE_CLI_CMD: str = "opencode"
    # CLI 调用超时时间（秒）- 从环境变量读取，默认 600 秒
    CLI_TIMEOUT: int = int(os.getenv("CLI_TIMEOUT", "600"))

    # ==================== V2.0: 数据接入配置 ====================
    DATA_SOURCE: str = "csv"  # 可选: csv / sorftime
    SORFTIME_API_KEY: str = os.getenv("SORFTIME_API_KEY", "")
    SORFTIME_MODE: str = "mcp"  # 可选: mcp / api / cli
    SORFTIME_BASE_URL: str = "https://mcp.sorftime.com"
    SORFTIME_MAX_REVIEWS: int = 100  # Sorftime 单次最多返回 100 条

    # ==================== V2.0: 可视化模板配置 ====================
    TEMPLATE_DIR: Path = field(default_factory=lambda: Path(__file__).parent / "templates")
    DEFAULT_TEMPLATE: str = "premium-gold"  # 默认模板名称

    # ==================== V2.0: 飞书同步配置 ====================
    FEISHU_SYNC: bool = False  # 是否同步到飞书（用户选择）
    LARK_CLI_CMD: str = "lark-cli"  # 飞书 CLI 命令名

    # ==================== V2.0: 图表引擎配置 ====================
    CHART_ENGINE: str = "chartjs"  # 可选: chartjs / echarts
    CHART_COLOR_PALETTE: str = "premium-gold"  # 颜色主题

    # ==================== V2.0: Prompt 模板配置 ====================
    PROMPTS_DIR: Path = field(default_factory=lambda: Path(__file__).parent / "prompts")
    INSIGHTS_CHAPTERS: str = "all"  # 可选: all / 自定义章节编号列表（如 "1,2,3,9,10"）

    # ==================== 分析配置 ====================
    MAX_REVIEWS: int = 500           # 最大获取评论数
    BATCH_SIZE: int = 30             # 每批处理数量 (30-50条)
    TAG_SYSTEM_PATH: str = "tag_system.yaml"

    # ==================== 用户画像配置 ====================
    PERSONA_MIN_COUNT: int = 3       # 成为画像的最小样本数
    MAX_PERSONAS: int = 4            # 最多识别的用户画像数
    SAMPLES_PER_PERSONA: int = 6     # 每个画像的样本数 (3正+3负)

    # ==================== 输出配置 ====================
    GENERATE_HTML: bool = True       # 是否生成 HTML 报告
    CSV_ENCODING: str = "utf-8-sig"  # CSV 文件编码
    PROJECT_NAME: str = "评论分析项目"  # 项目名称

    # ==================== 并发配置 ====================
    # 最大并发子进程数（调用 claude -p）- 从环境变量读取，默认 4
    MAX_CONCURRENT_AGENTS: int = int(os.getenv("MAX_CONCURRENT", "4"))

    # ==================== 快速模式配置 ====================
    QUICK_MODE_MAX_REVIEWS: int = 30  # 快速模式默认获取评论数

    # ==================== 报告生成配置 ====================
    INSIGHTS_FORMAT: str = "txt"  # 可选: md / txt
    HTML_CREATOR_NAME: str = os.getenv("HTML_CREATOR_NAME", "Buluu@新西楼")

    def __post_init__(self):
        """初始化后验证"""
        # 确保输出目录存在
        self.OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
        self.DATA_DIR.mkdir(parents=True, exist_ok=True)

        # 并发上限保护：超过 8 可能导致系统资源不足或 CLI rate limit
        MAX_CONCURRENT_CAP = 8
        if self.MAX_CONCURRENT_AGENTS > MAX_CONCURRENT_CAP:
            print(f"⚠️  并发数 {self.MAX_CONCURRENT_AGENTS} 超过上限 {MAX_CONCURRENT_CAP}，已自动调整为 {MAX_CONCURRENT_CAP}")
            self.MAX_CONCURRENT_AGENTS = MAX_CONCURRENT_CAP

        # V2.0: CLI 引擎不再是必须的（打标由宿主 Agent 执行）
        # 仅在洞察报告和 HTML 看板生成时才需要 CLI
        import shutil
        env_engine = os.getenv("CLI_ENGINE", "").lower()
        if env_engine in ("claude", "opencode"):
            self.CLI_ENGINE = env_engine

        if not self.CLI_ENGINE:
            # 自动探测: 优先 claude，其次 opencode，找不到也不报错
            if shutil.which(self.CLAUDE_CLI_CMD):
                self.CLI_ENGINE = "claude"
            elif shutil.which(self.OPENCODE_CLI_CMD):
                self.CLI_ENGINE = "opencode"
            else:
                # V2.0: 不再强制要求 CLI，但记录警告
                self.CLI_ENGINE = "none"

    @property
    def cli_cmd(self) -> str:
        """获取当前 CLI 引擎的命令名"""
        return self.OPENCODE_CLI_CMD if self.CLI_ENGINE == "opencode" else self.CLAUDE_CLI_CMD

    def build_cli_cmd(self, prompt: str) -> list:
        """构建 CLI 调用命令（统一入口）

        自动解析绝对路径并根据当前引擎类型构建正确的命令参数。
        V2.0: 当引擎为 "none" 时抛出 RuntimeError（仅洞察报告/看板生成需要 CLI）

        Args:
            prompt: 要传递给 CLI 的提示词

        Returns:
            命令列表，可直接传递给 subprocess.run()

        Raises:
            RuntimeError: 当 CLI 不可用时
        """
        import shutil

        if self.CLI_ENGINE == "none":
            raise RuntimeError(
                "❌ 当前无可用的 CLI 引擎。洞察报告和 HTML 看板生成需要 CLI。\n"
                "请安装 Claude Code 或 OpenCode 并加入 PATH"
            )

        cli_path = shutil.which(self.cli_cmd)
        if not cli_path:
            raise RuntimeError(
                f"❌ 找不到 CLI 引擎: {self.cli_cmd}\n"
                f"请确保已安装并加入 PATH"
            )

        if self.CLI_ENGINE == "opencode":
            return [cli_path, "run", prompt]
        else:
            return [cli_path, "--print", "--dangerously-skip-permissions", prompt]

    # ==================== V2.0: 新增方法 ====================

    def check_lark_cli(self) -> bool:
        """检查飞书 CLI 是否可用"""
        import shutil
        return shutil.which(self.LARK_CLI_CMD) is not None

    def check_sorftime_config(self) -> bool:
        """检查 Sorftime 配置是否可用"""
        return bool(self.SORFTIME_API_KEY)

    def list_templates(self) -> list:
        """列出可用的可视化模板"""
        if not self.TEMPLATE_DIR.exists():
            return []
        templates = []
        for d in sorted(self.TEMPLATE_DIR.iterdir()):
            if d.is_dir() and (d / "dashboard.html").exists():
                templates.append({
                    "name": d.name,
                    "path": str(d / "dashboard.html")
                })
        return templates

    def _get_project_dir(self, asin: str) -> Path:
        """获取项目输出目录: {ASIN}-{PROJECT_NAME}-{月.日}"""
        date_str = datetime.now().strftime("%-m.%-d")  # 格式: 2.13 (macOS)
        # 兼容不同系统的日期格式
        try:
            date_str = datetime.now().strftime("%-m.%-d")
        except ValueError:
            try:
                date_str = datetime.now().strftime("%#m.%#d")
            except ValueError:
                date_str = datetime.now().strftime("%m.%d").lstrip("0").replace(".0", ".")

        project_dir = self.OUTPUT_DIR / f"{asin}-{self.PROJECT_NAME}-{date_str}"
        project_dir.mkdir(parents=True, exist_ok=True)
        return project_dir

    @property
    def tag_system_path(self) -> Path:
        """获取标签体系配置文件路径"""
        return self.REFERENCES_DIR / self.TAG_SYSTEM_PATH

    def get_csv_path(self, asin: str) -> Path:
        """获取 CSV 输出路径: 评论采集及打标数据_{ASIN}.csv"""
        project_dir = self._get_project_dir(asin)
        return project_dir / f"评论采集及打标数据_{asin}.csv"

    def get_html_path(self, asin: str) -> Path:
        """获取 HTML 报告输出路径: 可视化洞察报告_{ASIN}.html"""
        project_dir = self._get_project_dir(asin)
        return project_dir / f"可视化洞察报告_{asin}.html"

    def get_md_path(self, asin: str) -> Path:
        """获取 Markdown 洞察输出路径: 分析洞察报告_{ASIN}.md"""
        project_dir = self._get_project_dir(asin)
        return project_dir / f"分析洞察报告_{asin}.md"


# 全局配置实例
config = Config()

"""
数据采集模块 - 多源评论数据统一接入层

支持多种数据源:
- CSV/Excel 本地文件 (CsvFetcher)
- Sorftime 平台 (SorftimeFetcher) - 支持 MCP / API / CLI 三种连接模式

所有数据采集器继承自 DataFetcher 基类，提供统一的 fetch / list_fields / validate_config 接口。
"""

from typing import Dict, List

from src.data_fetchers.base import DataFetcher
from src.data_fetchers.csv_fetcher import CsvFetcher
from src.data_fetchers.sorftime_fetcher import SorftimeFetcher

# 可用数据采集器注册表: 名称 -> 实现类
FETCHER_REGISTRY: Dict[str, type] = {
    "csv": CsvFetcher,
    "sorftime": SorftimeFetcher,
}


def get_fetcher(name: str, **kwargs) -> DataFetcher:
    """根据名称获取数据采集器实例

    Args:
        name: 采集器名称，支持 "csv" 和 "sorftime"
        **kwargs: 传递给采集器构造函数的额外参数

    Returns:
        DataFetcher 实例

    Raises:
        ValueError: 当 name 不在注册表中时
    """
    name = name.lower().strip()
    if name not in FETCHER_REGISTRY:
        available = ", ".join(FETCHER_REGISTRY.keys())
        raise ValueError(
            f"未知的采集器: '{name}'，可选项: [{available}]"
        )
    return FETCHER_REGISTRY[name](**kwargs)


def list_fetchers() -> List[dict]:
    """列出所有已注册的采集器及其描述

    Returns:
        包含 name, description, fields 的字典列表
    """
    result = []
    for name, cls in FETCHER_REGISTRY.items():
        instance = cls()
        result.append({
            "name": name,
            "display_name": instance.get_name(),
            "fields": instance.list_fields(),
        })
    return result


__all__ = [
    "DataFetcher",
    "CsvFetcher",
    "SorftimeFetcher",
    "FETCHER_REGISTRY",
    "get_fetcher",
    "list_fetchers",
]

"""
数据采集器抽象基类

所有数据采集器（CSV、Sorftime 等）必须继承此基类并实现其抽象方法。
提供统一的数据获取接口，使上层业务代码无需关心具体数据来源。
"""

import logging
from abc import ABC, abstractmethod
from typing import Dict, List, Optional

logger = logging.getLogger(__name__)


class DataFetcher(ABC):
    """数据采集器抽象基类

    子类必须实现:
    - fetch(): 根据 ASIN 获取评论数据并输出为标准化 CSV
    - list_fields(): 声明该采集器支持的标准字段
    - validate_config(): 验证连接/配置是否可用
    - get_name(): 返回采集器的显示名称

    设计约定:
    - fetch() 返回一个 CSV 文件路径，文件使用 utf-8-sig 编码
    - CSV 文件的列名必须与 list_fields() 中的 name 一一对应
    - 所有子类构造函数接受可选的 config 字典，用于传递连接参数
    """

    def __init__(self, config: Optional[Dict] = None):
        """初始化采集器

        Args:
            config: 可选的配置字典，可能包含 API Key、文件路径等信息
        """
        self._config = config or {}

    @abstractmethod
    def fetch(self, asin: str, fields: List[str], site: str = "US") -> str:
        """获取评论数据并保存为标准化 CSV 文件

        Args:
            asin: Amazon Standard Identification Number（或通用商品标识）
            fields: 需要获取的标准字段列表（来自 list_fields 返回的 name）
            site: 站点代码，默认 "US"，可选 "UK"/"DE"/"JP" 等

        Returns:
            生成的 CSV 文件的绝对路径

        Raises:
            FileNotFoundError: 当数据源不可达时
            ValueError: 当 ASIN 无效或参数不合法时
            RuntimeError: 当数据获取过程中出现不可恢复错误时
        """
        ...

    @abstractmethod
    def list_fields(self) -> List[dict]:
        """列出此采集器支持的标准字段

        Returns:
            字段描述列表，每个元素为包含以下键的字典:
            - name (str): 标准字段名，如 "review_body", "rating"
            - description (str): 字段的中文描述
            - required (bool): 此字段是否为采集器必须输出的字段
        """
        ...

    @abstractmethod
    def validate_config(self) -> bool:
        """验证采集器配置/连接是否可用

        用于在执行 fetch 前预先检查:
        - 文件路径是否存在 (CsvFetcher)
        - API Key 是否有效 (SorftimeFetcher)
        - 网络连通性等

        Returns:
            True 表示配置有效，可以执行 fetch；False 表示不可用
        """
        ...

    @abstractmethod
    def get_name(self) -> str:
        """返回采集器的显示名称

        Returns:
            如 "CSV本地文件", "Sorftime" 等
        """
        ...

    def get_config(self) -> Dict:
        """获取当前配置（只读副本）

        Returns:
            配置字典的浅拷贝
        """
        return dict(self._config)

    def update_config(self, updates: Dict) -> None:
        """更新配置参数

        Args:
            updates: 要合并到现有配置中的键值对
        """
        self._config.update(updates)
        logger.debug("配置已更新: %s", list(updates.keys()))