Module 1: 打造不盯盤的個人量化體系：價值投資、籌碼分析與 berich 自動化藍圖

"""
berich Quantitative Engine - Module 01 Multi-Factor Screener
============================================================
系統名稱：berich Lab 教學示範
核心功能：價值投資安全邊際 ＋ 主力籌碼集中度多因子選股引擎
"""

from __future__ import annotations
import logging
from dataclasses import dataclass
from typing import Dict, List, Optional, Protocol
import pandas as pd
import numpy as np

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] [berich-core] %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)
logger = logging.getLogger("berich")

@dataclass(frozen=True)
class StockSnapshot:
    stock_id: str
    name: str
    current_price: float
    pe_ratio: float
    pb_ratio: float
    fcf_yield: float
    revenue_yoy: float
    major_holder_ratio: float
    shareholder_count_change_pct: float
    chip_concentration_5d: float
    major_cost_line_20d: float
    high_price_60d: float = 125.0

@dataclass(frozen=True)
class ScreeningResult:
    stock_id: str
    name: str
    composite_score: float
    valuation_score: float
    chip_score: float
    is_passed: bool
    signal_tags: List[str]
    stop_loss_price: float
    resistance_price: float

class IClusterStrategy(Protocol):
    def evaluate_cluster_flow(self, stock_id: str) -> float:
        ...

class ValueChipScreener:
    def __init__(self, cluster_plugin: Optional[IClusterStrategy] = None):
        self.cluster_plugin = cluster_plugin

    def evaluate_valuation(self, stock: StockSnapshot) -> tuple[float, List[str]]:
        score = 0.0
        tags = []
        if stock.pe_ratio <= 12.0:
            score += 40.0
            tags.append("PE極度低估")
        elif stock.pe_ratio <= 15.0:
            score += 25.0
            tags.append("PE合理便宜")

        if stock.fcf_yield >= 0.05:
            score += 30.0
            tags.append("自由現金流充沛")

        if stock.revenue_yoy >= 0.10:
            score += 30.0
            tags.append("營收雙位數成長")

        return min(score, 100.0), tags

    def evaluate_chips(self, stock: StockSnapshot) -> tuple[float, List[str]]:
        score = 0.0
        tags = []
        if stock.chip_concentration_5d >= 20.0:
            score += 40.0
            tags.append("5日主力高度集中")
        elif stock.chip_concentration_5d >= 12.0:
            score += 25.0
            tags.append("主力顯著吸籌")

        if stock.major_holder_ratio >= 60.0:
            score += 30.0
            tags.append("千張大戶重度鎖碼")

        cost_diff_pct = ((stock.current_price - stock.major_cost_line_20d) / stock.major_cost_line_20d) * 100.0
        if -3.0 <= cost_diff_pct <= 3.0:
            score += 30.0
            tags.append("回測主力成本強支撐")

        return min(score, 100.0), tags

    def screen_stock(self, stock: StockSnapshot) -> ScreeningResult:
        v_score, v_tags = self.evaluate_valuation(stock)
        c_score, c_tags = self.evaluate_chips(stock)

        composite_score = (v_score * 0.4) + (c_score * 0.6)
        all_tags = v_tags + c_tags
        is_passed = (v_score >= 70.0) and (c_score >= 70.0) and (composite_score >= 75.0)

        stop_loss = round(stock.major_cost_line_20d * 0.95, 2)
        # 技術壓力參考位（由近 60 日波段最高價推導，僅供技術分析參考，非價格預測）
        resistance_price = round(stock.high_price_60d, 2)

        return ScreeningResult(
            stock_id=stock.stock_id,
            name=stock.name,
            composite_score=round(composite_score, 1),
            valuation_score=round(v_score, 1),
            chip_score=round(c_score, 1),
            is_passed=is_passed,
            signal_tags=all_tags,
            stop_loss_price=stop_loss,
            resistance_price=resistance_price,
        )

if __name__ == "__main__":
    demo_a = StockSnapshot(
        stock_id="DEMO_A",
        name="範例股A",
        current_price=108.0,
        pe_ratio=11.2,
        pb_ratio=1.45,
        fcf_yield=0.068,
        revenue_yoy=0.185,
        major_holder_ratio=62.4,
        shareholder_count_change_pct=-0.135,
        chip_concentration_5d=22.4,
        major_cost_line_20d=106.5,
        high_price_60d=125.0
    )

    screener = ValueChipScreener()
    res = screener.screen_stock(demo_a)
    logger.info(f"篩選標的：{res.name} ({res.stock_id})")
    logger.info(f"綜合評分：{res.composite_score} 分 | 符合條件：{res.is_passed}")
    logger.info(f"觸發訊號：{', '.join(res.signal_tags)}")
    logger.info(f"參考防守區：{res.stop_loss_price} 元 | 技術壓力參考位（近60日高點，非價格預測）：{res.resistance_price} 元")