@mulsok/traders-client 0.1.0

package/dist/server/screener/engine.js

@@ -0,0 +1,856 @@
+/**
+ * 범용 스크리너 엔진 (apps/client)
+ *
+ * 설계 원칙 (ADR-008):
+ *   - 페르소나 전략은 프롬프트에 살아 있고, 스크리닝 조건은 **DSL(JSON)** 로 표현
+ *   - 엔진은 도메인 중립 · 페르소나 비의존
+ *   - 하드코딩된 페르소나 전용 스크리너(구 neoul-screening.ts) 를 폐기하고 이로 통합
+ *
+ * DSL:
+ *   {
+ *     maOrder: { asc: [20, 60, 120] }          // MA20 < MA60 < MA120 (역배열이면 desc)
+ *     volumeAvgMultiple: { baselineDays: 90, minRatio: 5 }
+ *     circulatingVolumeRatio: { minPct: 30 }
+ *     priceRange: { minKrw: 1000, maxKrw: 100000 }
+ *     marketCapRange: { minKrw: 50_000_000_000 }   // 500억 이상 (listCount * price)
+ *     excludeStates: ["관리종목", "정리매매", "투자주의환기종목"]
+ *     marketIn: ["kospi", "kosdaq"]
+ *   }
+ *
+ * 실행:
+ *   const hits = await runScreener({ maOrder: { desc: [20, 60, 120] } });
+ *   → 후보 종목 code[] 반환 · LLM 은 code 들만 받고 상세 분석
+ *
+ * 데이터 소스:
+ *   - universe: SQLite universe 테이블 (ka10099 배치 결과)
+ *   - candles:  SQLite daily_candles 테이블 (ka10081 배치 결과)
+ *
+ * 배치가 선행되어야 함. 없으면 `empty` 결과 + 경고 메시지.
+ */
+import { countUniverse, getCandles, listUniverse, } from "../db/sqlite.js";
+/**
+ * 「보통주만」 필터 — ETF/ETN/ELW/우선주/리츠/스팩 제외 (선택).
+ *
+ * 양음양·역배열 등 「세력 의도 + 매물대」 패턴은 보통주에만 의미.
+ * ETF/ETN 은 운용사 발행이라 캔들 패턴이 종목 자체 의도와 무관 → 제외 권장.
+ */
+const ETF_NAME_PREFIXES = [
+    "KODEX", "TIGER", "KBSTAR", "ARIRANG", "ACE", "KOSEF", "HANARO",
+    "SOL", "PLUS", "RISE", "KIWOOM", "TIMEFOLIO", "FOCUS", "BNK",
+    "마이다스", "신한", "한투", "삼성KODEX", "미래에셋",
+];
+const ETF_NAME_KEYWORDS = ["ETF", "ETN", "선물인버스", "레버리지", "ELS", "ELW", "워런트"];
+const REIT_KEYWORDS = ["리츠", "REITs", "REIT"];
+const SPAC_KEYWORDS = ["스팩", "SPAC"];
+function isPreferredCode(code) {
+    // 한국 6자리 보통주 = 끝자리 0. 우선주 = 5/6/7/8/9 (1우/2우B/3우B 등).
+    if (!/^\d{6}$/.test(code))
+        return false;
+    const last = code.charCodeAt(5) - 48;
+    return last >= 5 && last <= 9;
+}
+function isAlphaInCode(code) {
+    // ETF/ETN 액티브 등은 종목 코드에 알파벳 (예: 0148J0)
+    return /[A-Za-z]/.test(code);
+}
+function isNonCommon(name, code) {
+    if (isPreferredCode(code))
+        return { excluded: true, reason: "preferred" };
+    if (isAlphaInCode(code))
+        return { excluded: true, reason: "code_alpha" };
+    const upper = name.toUpperCase();
+    for (const p of ETF_NAME_PREFIXES) {
+        if (name.startsWith(p) || upper.startsWith(p))
+            return { excluded: true, reason: `etf_prefix:${p}` };
+    }
+    for (const kw of ETF_NAME_KEYWORDS) {
+        if (name.includes(kw) || upper.includes(kw))
+            return { excluded: true, reason: `keyword:${kw}` };
+    }
+    for (const kw of REIT_KEYWORDS) {
+        if (name.includes(kw) || upper.includes(kw))
+            return { excluded: true, reason: `reit:${kw}` };
+    }
+    for (const kw of SPAC_KEYWORDS) {
+        if (name.includes(kw) || upper.includes(kw))
+            return { excluded: true, reason: `spac:${kw}` };
+    }
+    // 종목명 끝이 "우" 또는 "우B" 같은 우선주 패턴 (코드로 안 잡힌 케이스 보강)
+    if (/우[A-Z]?$/.test(name) || /우\d$/.test(name)) {
+        return { excluded: true, reason: "name_preferred_suffix" };
+    }
+    return { excluded: false };
+}
+export async function runScreener(filter) {
+    const start = Date.now();
+    const universeSize = countUniverse();
+    const diagnostics = {
+        universeAfterStaticFilter: 0,
+        rejectedBy: {
+            priceRange: 0,
+            marketCapRange: 0,
+            excludeStates: 0,
+            nonCommon: 0,
+            maOrder: 0,
+            volumeAvgMultiple: 0,
+            circulatingVolumeRatio: 0,
+            candlePattern: 0,
+            noCandles: 0,
+        },
+        patternReject: {},
+        samples: [],
+    };
+    if (universeSize === 0) {
+        return {
+            filter,
+            candidates: [],
+            universeSize: 0,
+            evaluated: 0,
+            skippedNoCandles: 0,
+            elapsedMs: Date.now() - start,
+            diagnostics,
+            dataAsOf: undefined,
+        };
+    }
+    // 데이터 기준일 추적 — 평가된 candle 중 가장 최신 date (D-0)
+    let latestCandleDate = "";
+    const markets = filter.marketIn ?? ["kospi", "kosdaq"];
+    const rows = [];
+    for (const m of markets) {
+        rows.push(...listUniverse({ market: m }));
+    }
+    const hits = [];
+    let evaluated = 0;
+    let skippedNoCandles = 0;
+    const addSample = (row, stoppedAt, detail) => {
+        if (diagnostics.samples.length < 5) {
+            diagnostics.samples.push({ code: row.code, name: row.name, stoppedAt, detail });
+        }
+    };
+    for (const row of rows) {
+        // 1차 static 필터 (DB 만으로 판단 가능)
+        if (filter.excludeStates) {
+            if (filter.excludeStates.some((bad) => (row.state ?? "").includes(bad))) {
+                diagnostics.rejectedBy.excludeStates++;
+                continue;
+            }
+        }
+        // 보통주만 (ETF·ETN·ELW·우선주·리츠·스팩 제외)
+        if (filter.excludeNonCommon) {
+            const nc = isNonCommon(row.name, row.code);
+            if (nc.excluded) {
+                diagnostics.rejectedBy.nonCommon++;
+                addSample(row, "non_common", nc.reason ?? "");
+                continue;
+            }
+        }
+        if (filter.priceRange) {
+            if (filter.priceRange.minKrw !== undefined && row.last_price_krw < filter.priceRange.minKrw) {
+                diagnostics.rejectedBy.priceRange++;
+                continue;
+            }
+            if (filter.priceRange.maxKrw !== undefined && row.last_price_krw > filter.priceRange.maxKrw) {
+                diagnostics.rejectedBy.priceRange++;
+                continue;
+            }
+        }
+        if (filter.marketCapRange) {
+            const cap = row.last_price_krw * row.list_count;
+            if (filter.marketCapRange.minKrw !== undefined && cap < filter.marketCapRange.minKrw) {
+                diagnostics.rejectedBy.marketCapRange++;
+                continue;
+            }
+            if (filter.marketCapRange.maxKrw !== undefined && cap > filter.marketCapRange.maxKrw) {
+                diagnostics.rejectedBy.marketCapRange++;
+                continue;
+            }
+        }
+        diagnostics.universeAfterStaticFilter++;
+        // 2차 candles 기반 필터
+        const needsCandles = !!filter.maOrder ||
+            !!filter.volumeAvgMultiple ||
+            !!filter.circulatingVolumeRatio ||
+            (!!filter.candlePatterns && filter.candlePatterns.length > 0);
+        if (!needsCandles) {
+            hits.push(buildHit(row, [], [], {}));
+            evaluated++;
+            continue;
+        }
+        // 패턴별 최소 요구 일수 (필수 평가에 필요한 만큼만 · 가산점은 candles 충분할 때만 적용)
+        const patternMinDays = (filter.candlePatterns ?? []).reduce((m, p) => {
+            if (p.kind === "yinYangBull") {
+                const baselineDays = p.params?.d1VolumeBaselineDays ?? 60;
+                // longMaBonus 는 추가 정보 (없어도 패턴 평가 가능) · 필수는 baseline 만
+                return Math.max(m, Math.max(baselineDays + 3, 22));
+            }
+            if (p.kind === "yinYangUpperShadow")
+                return Math.max(m, 12);
+            if (p.kind === "yinYangSideways") {
+                const range = p.params?.sidewaysDaysRange ?? [3, 10];
+                return Math.max(m, range[1] + 5);
+            }
+            if (p.kind === "morningStar")
+                return Math.max(m, 3);
+            if (p.kind === "engulfingBull")
+                return Math.max(m, 2);
+            if (p.kind === "hammer")
+                return Math.max(m, 1);
+            if (p.kind === "maRebound")
+                return Math.max(m, p.params.ma);
+            return m;
+        }, 0);
+        const maxPeriod = Math.max(...(filter.maOrder?.asc ?? []), ...(filter.maOrder?.desc ?? []), filter.volumeAvgMultiple?.baselineDays ?? 0, patternMinDays, 5);
+        const candles = getCandles(row.code, maxPeriod + 2);
+        if (candles.length < maxPeriod) {
+            skippedNoCandles++;
+            diagnostics.rejectedBy.noCandles++;
+            continue;
+        }
+        evaluated++;
+        // 가장 최신 candle date 추적 (DESC 정렬이라 [0])
+        if (candles[0]?.date && candles[0].date > latestCandleDate) {
+            latestCandleDate = candles[0].date;
+        }
+        const reasons = [];
+        const ma = {};
+        // MA order
+        if (filter.maOrder) {
+            const periods = filter.maOrder.asc ?? filter.maOrder.desc;
+            const isAsc = !!filter.maOrder.asc;
+            const values = periods.map((p) => {
+                const m = averageClose(candles, p);
+                ma[`ma${p}`] = m;
+                return m;
+            });
+            const ordered = isAsc
+                ? values.every((v, i) => i === 0 || v >= values[i - 1])
+                : values.every((v, i) => i === 0 || v <= values[i - 1]);
+            if (!ordered) {
+                diagnostics.rejectedBy.maOrder++;
+                addSample(row, "maOrder", `values=[${values.map((v) => Math.round(v)).join(",")}]`);
+                continue;
+            }
+            reasons.push(`MA${isAsc ? "정" : "역"}배열 ${periods.map((p, i) => `${p}일=${Math.round(values[i])}`).join(" → ")}`);
+        }
+        // Volume average multiple
+        if (filter.volumeAvgMultiple) {
+            const baselineDays = filter.volumeAvgMultiple.baselineDays;
+            if (candles.length < baselineDays + 1) {
+                skippedNoCandles++;
+                diagnostics.rejectedBy.noCandles++;
+                continue;
+            }
+            const d0 = candles[0];
+            const baseline = candles.slice(1, baselineDays + 1);
+            const avgVol = baseline.reduce((s, c) => s + c.volume, 0) / baseline.length;
+            const ratio = avgVol > 0 ? d0.volume / avgVol : 0;
+            if (ratio < filter.volumeAvgMultiple.minRatio) {
+                diagnostics.rejectedBy.volumeAvgMultiple++;
+                addSample(row, "volumeAvgMultiple", `ratio=${ratio.toFixed(2)}`);
+                continue;
+            }
+            reasons.push(`거래량 ${baselineDays}일 평균 대비 ${ratio.toFixed(1)}배`);
+        }
+        // Circulating volume ratio
+        if (filter.circulatingVolumeRatio) {
+            if (row.list_count <= 0) {
+                diagnostics.rejectedBy.circulatingVolumeRatio++;
+                continue;
+            }
+            const d0 = candles[0];
+            const pct = (d0.volume / row.list_count) * 100;
+            if (pct < filter.circulatingVolumeRatio.minPct) {
+                diagnostics.rejectedBy.circulatingVolumeRatio++;
+                addSample(row, "circulatingVolumeRatio", `${pct.toFixed(2)}%`);
+                continue;
+            }
+            reasons.push(`유통주식수 대비 거래량 ${pct.toFixed(1)}%`);
+        }
+        // 캔들 패턴 프리셋 (mode 에 따라 AND 또는 ANY)
+        // 통과 = score 1 / 실패 = 0 · 가산점 평가는 LLM 영역
+        const matchedPatterns = [];
+        const humanSummaries = [];
+        const aggregatedMetrics = {};
+        if (filter.candlePatterns && filter.candlePatterns.length > 0) {
+            const mode = filter.candlePatternsMode ?? "and";
+            const matches = filter.candlePatterns.map((spec) => ({
+                kind: spec.kind,
+                result: matchCandlePattern(spec, candles, row),
+            }));
+            // 진단 집계 (탈락 이유)
+            for (const m of matches) {
+                if (!m.result.passed) {
+                    const failKey = m.result.failReason ?? "unknown";
+                    diagnostics.patternReject[m.kind] = diagnostics.patternReject[m.kind] ?? {};
+                    diagnostics.patternReject[m.kind][failKey] =
+                        (diagnostics.patternReject[m.kind][failKey] ?? 0) + 1;
+                }
+            }
+            if (mode === "and") {
+                const allPassed = matches.every((m) => m.result.passed);
+                if (!allPassed) {
+                    diagnostics.rejectedBy.candlePattern++;
+                    const firstFail = matches.find((m) => !m.result.passed);
+                    if (firstFail)
+                        addSample(row, `candlePattern:${firstFail.kind}`, firstFail.result.failReason ?? "unknown");
+                    continue;
+                }
+                for (const m of matches) {
+                    matchedPatterns.push(m.kind);
+                    reasons.push(`【${m.kind}】 ${m.result.reasons.join(" / ")}`);
+                    if (m.result.humanSummary)
+                        humanSummaries.push(m.result.humanSummary);
+                    Object.assign(aggregatedMetrics, m.result.metrics);
+                }
+            }
+            else {
+                const passedMatches = matches.filter((m) => m.result.passed);
+                if (passedMatches.length === 0) {
+                    diagnostics.rejectedBy.candlePattern++;
+                    if (matches[0])
+                        addSample(row, `candlePattern:${matches[0].kind}`, matches[0].result.failReason ?? "unknown");
+                    continue;
+                }
+                for (const m of passedMatches) {
+                    matchedPatterns.push(m.kind);
+                    reasons.push(`【${m.kind}】 ${m.result.reasons.join(" / ")}`);
+                    if (m.result.humanSummary)
+                        humanSummaries.push(m.result.humanSummary);
+                    Object.assign(aggregatedMetrics, m.result.metrics);
+                }
+            }
+        }
+        hits.push(buildHit(row, reasons, humanSummaries, ma, candles, matchedPatterns, aggregatedMetrics));
+    }
+    // 정렬
+    const sort = filter.sort ?? { by: "score", order: "desc" };
+    const order = sort.order ?? "desc";
+    hits.sort((a, b) => {
+        const av = sortValue(a, sort.by);
+        const bv = sortValue(b, sort.by);
+        return order === "asc" ? av - bv : bv - av;
+    });
+    const limited = filter.limit ? hits.slice(0, filter.limit) : hits;
+    return {
+        filter,
+        candidates: limited,
+        universeSize,
+        evaluated,
+        skippedNoCandles,
+        elapsedMs: Date.now() - start,
+        diagnostics,
+        dataAsOf: latestCandleDate || undefined,
+    };
+}
+function sortValue(h, by) {
+    switch (by) {
+        case "score": return h.score;
+        case "changePct": return h.todayChangePct;
+        case "volume": return h.todayVolume;
+        case "marketCap": return h.lastPriceKrw * h.listCount;
+    }
+}
+function matchCandlePattern(spec, candles, row) {
+    switch (spec.kind) {
+        case "yinYangBull": return matchYinYangBull(spec.params ?? {}, candles);
+        case "yinYangUpperShadow": return matchYinYangUpperShadow(spec.params ?? {}, candles);
+        case "yinYangSideways": return matchYinYangSideways(spec.params ?? {}, candles);
+        case "engulfingBull": return matchEngulfingBull(spec.params ?? {}, candles);
+        case "morningStar": return matchMorningStar(spec.params ?? {}, candles);
+        case "hammer": return matchHammer(spec.params ?? {}, candles);
+        case "maRebound": return matchMaRebound(spec.params, candles, row);
+    }
+}
+/**
+ * 양음양 패턴 1 · 기본형 (5일선 눌림)
+ *
+ * D-1 장대양봉 + 평소 평균 대비 대량거래 → D-0 음봉 + 거래량 감소 + 5일선 미이탈.
+ * taeeun-life v2 원본 충실 · 거래량 비교는 N일 평균 대비 (단순 D-2 1일 대비 X).
+ */
+export function matchYinYangBull(p, candles) {
+    // 기본값
+    const d1MinChangePct = p.d1MinChangePct ?? 5;
+    const d1MaxChangePct = p.d1MaxChangePct ?? 20;
+    const baselineDays = p.d1VolumeBaselineDays ?? 60;
+    const d1MinVolumeRatio = p.d1MinVolumeRatio ?? 1.5;
+    const d1ExceptionalVolumeRatio = p.d1ExceptionalVolumeRatio ?? 3;
+    const d0MaxVolumeRatio = p.d0MaxVolumeRatio ?? 0.8;
+    const d0IdealVolumeRatio = p.d0IdealVolumeRatio ?? 0.6;
+    const d0MustBeBearish = p.d0MustBeBearish ?? true;
+    const d0BodyIdeal = p.d0BodyRatioIdeal ?? [0.4, 0.6];
+    const d0BodyAcceptable = p.d0BodyRatioAcceptable ?? [0.15, 0.7];
+    const d0BodyMarginalScore = p.d0BodyRatioMarginalScore ?? 1;
+    const mustHoldMa = p.mustHoldMa ?? 5;
+    const idealClusterPct = p.maClusterIdealPct ?? 5;
+    const acceptClusterPct = p.maClusterAcceptablePct ?? 7;
+    const clusterPeriods = p.maClusterPeriods ?? [5, 10, 20];
+    const maOrderBonus = p.maOrderBonus ?? true;
+    const longMaBreakoutBonus = p.longMaBreakoutBonus ?? true;
+    const d0HighVolumeExclude = p.d0HighVolumeExclude ?? true;
+    const tradingValueBonus = p.tradingValueBonus ?? true;
+    const tvTier1 = p.tradingValueTier1Krw ?? 10_000_000_000; // 100억
+    const tvTier2 = p.tradingValueTier2Krw ?? 100_000_000_000; // 1000억
+    // 최소 candles 수 (baseline + D-2 + D-1 + D-0 + 안전)
+    const minCandles = Math.max(baselineDays + 3, 22);
+    if (candles.length < minCandles)
+        return fail(`candles<${minCandles}`);
+    const d0 = candles[0];
+    const d1 = candles[1];
+    const d2 = candles[2];
+    /* ─── D-1 장대양봉 + 평균 대비 대량거래 ─── */
+    if (d2.close_krw <= 0)
+        return fail("d2_closed_zero");
+    const d1ChangePct = ((d1.close_krw - d2.close_krw) / d2.close_krw) * 100;
+    if (d1.close_krw <= d1.open_krw)
+        return fail("d1_not_bullish");
+    if (d1ChangePct < d1MinChangePct)
+        return fail(`d1_change_below_${d1MinChangePct}`);
+    if (d1ChangePct > d1MaxChangePct)
+        return fail(`d1_change_above_${d1MaxChangePct}`);
+    // 거래량: N일 평균 대비 (D-1 자체 제외 · D-2 부터 N일)
+    const baselineSlice = candles.slice(2, 2 + baselineDays);
+    const avgVolume = baselineSlice.reduce((s, c) => s + c.volume, 0) / baselineSlice.length;
+    const d1VolumeMultipleAvg = avgVolume > 0 ? d1.volume / avgVolume : 0;
+    if (d1VolumeMultipleAvg < d1MinVolumeRatio) {
+        return fail(`d1_avg_volume_ratio_below_${d1MinVolumeRatio}`);
+    }
+    /* ─── D-0 음봉 + 거래량 감소 ─── */
+    if (d0MustBeBearish && d0.close_krw >= d0.open_krw)
+        return fail("d0_not_bearish");
+    const d0VolumeRatio = d1.volume > 0 ? d0.volume / d1.volume : 0;
+    if (d0VolumeRatio > d0MaxVolumeRatio)
+        return fail(`d0_volume_ratio_above_${d0MaxVolumeRatio}`);
+    if (d0HighVolumeExclude && d0.volume >= d1.volume)
+        return fail("d0_high_volume_excluded");
+    /* ─── 음봉 몸통 / 양봉 몸통 비율 ─── */
+    const d1Body = Math.max(0, d1.close_krw - d1.open_krw);
+    const d0Body = Math.max(0, d0.open_krw - d0.close_krw); // 음봉이므로 open - close
+    const d0BodyRatio = d1Body > 0 ? d0Body / d1Body : 0;
+    if (d0BodyRatio < d0BodyAcceptable[0])
+        return fail(`d0_body_too_narrow_${d0BodyRatio.toFixed(2)}`);
+    if (d0BodyRatio > d0BodyAcceptable[1])
+        return fail(`d0_body_too_wide_${d0BodyRatio.toFixed(2)}`);
+    /* ─── 5일선 미이탈 (hard) ─── */
+    const ma5 = averageClose(candles, mustHoldMa);
+    if (d0.close_krw <= ma5)
+        return fail("below_ma5");
+    /* ─── 이평선 군집 (5일선 hard cutoff) ─── */
+    // taeeun-life v2 원본: "단기 이평선 (5일선 등) 이 -5%권" — 핵심은 5일선
+    // → MA5 거리 hard cutoff (acceptable * 1.5 = 약 10%) · 군집 score 는 5/10/20 평균
+    // 5일선 -10% 이격 = 분할매수 기준점 활용 가능 한계
+    let clusterIdeal = false;
+    let clusterAcceptable = false;
+    let clusterAvgDistancePct = 0;
+    if (clusterPeriods.length >= 2) {
+        const values = clusterPeriods.map((per) => averageClose(candles, per)).filter((v) => v > 0);
+        if (values.length === clusterPeriods.length) {
+            const cur = d0.close_krw;
+            // hard: 5일선과의 거리만 (가장 가까워야 할 단기선)
+            const ma5Distance = Math.abs(cur - ma5) / cur * 100;
+            const hardCutoff = acceptClusterPct * 1.5; // 7 * 1.5 = 10.5% (단기선 한계)
+            if (ma5Distance > hardCutoff) {
+                return fail(`ma5_distance_above_${hardCutoff.toFixed(1)}pct (${ma5Distance.toFixed(1)}%)`);
+            }
+            // 군집 평가 (전체 평균)
+            clusterAvgDistancePct = values.reduce((s, v) => s + Math.abs(cur - v) / cur * 100, 0) / values.length;
+            clusterIdeal = clusterAvgDistancePct <= idealClusterPct;
+            clusterAcceptable = clusterAvgDistancePct <= acceptClusterPct;
+        }
+    }
+    /* ─── 정배열 단계 차등 (MA5 > MA10 > MA20 > MA60 > MA120) ─── */
+    let maOrderTiers = 0; // 0=비정배열, 2=3단(5/10/20), 3=4단(+60), 4=5단(+120 완전체)
+    if (maOrderBonus) {
+        const ma10 = averageClose(candles, 10);
+        const ma20 = averageClose(candles, 20);
+        if (ma5 > 0 && ma10 > 0 && ma20 > 0 && ma5 > ma10 && ma10 > ma20) {
+            maOrderTiers = 2; // 3단 정배열 +2
+            if (candles.length >= 60) {
+                const ma60 = averageClose(candles, 60);
+                if (ma60 > 0 && ma20 > ma60) {
+                    maOrderTiers = 3; // 4단 +3
+                    if (candles.length >= 120) {
+                        const ma120 = averageClose(candles, 120);
+                        if (ma120 > 0 && ma60 > ma120) {
+                            maOrderTiers = 4; // 5단 완전체 +4
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /* ─── 역배열 → 60·120일선 첫 돌파 가산점 ─── */
+    //
+    // "D-1 양봉이 장기 MA 첫 돌파" 의 정확 정의:
+    //   D-1 close ≥ D-1 시점 MA  (어제 종가가 어제 MA 위)
+    //   D-2 close < D-2 시점 MA  (그 전날까지는 MA 아래)
+    //
+    // D-1 시점 MA60 = candles[1..60] 평균 = averageClose(candles.slice(1), 60)
+    // D-2 시점 MA60 = candles[2..61] 평균 = averageClose(candles.slice(2), 60)
+    let breakthroughLongMa = null;
+    if (longMaBreakoutBonus) {
+        if (candles.length >= 62) {
+            const d1Ma60 = averageClose(candles.slice(1), 60);
+            const d2Ma60 = averageClose(candles.slice(2), 60);
+            if (d1Ma60 > 0 && d2Ma60 > 0 && d1.close_krw >= d1Ma60 && d2.close_krw < d2Ma60) {
+                breakthroughLongMa = 60;
+            }
+        }
+        if (candles.length >= 122) {
+            const d1Ma120 = averageClose(candles.slice(1), 120);
+            const d2Ma120 = averageClose(candles.slice(2), 120);
+            // 120 이 더 강한 신호 · 60 위에 덮어쓰기
+            if (d1Ma120 > 0 && d2Ma120 > 0 && d1.close_krw >= d1Ma120 && d2.close_krw < d2Ma120) {
+                breakthroughLongMa = 120;
+            }
+        }
+    }
+    /*
+     * 통과 표시 (score = 1) + 필수 조건 사람용 요약.
+     * 가산점 평가 (정배열·거래량 폭발·이상적 음봉·돌파·거래대금 등) 는 LLM 영역.
+     * raw 측정값은 metrics 에 담아 LLM 에 전달.
+     */
+    void d1ExceptionalVolumeRatio;
+    void d0IdealVolumeRatio;
+    void d0BodyIdeal;
+    void d0BodyMarginalScore;
+    void idealClusterPct;
+    void acceptClusterPct;
+    void clusterIdeal;
+    void clusterAcceptable;
+    void tradingValueBonus;
+    void tvTier1;
+    void tvTier2;
+    const reasons = [
+        `양음양 [D-1 +${d1ChangePct.toFixed(1)}% · 평균 ${baselineDays}일 거래량 ${d1VolumeMultipleAvg.toFixed(1)}배]`,
+        `[D-0 음봉 · D-1 거래량의 ${(d0VolumeRatio * 100).toFixed(0)}% · 몸통 비율 ${(d0BodyRatio * 100).toFixed(0)}%]`,
+        `MA${mustHoldMa} 위`,
+    ];
+    let maAlignmentLabel = "mixed";
+    if (maOrderTiers === 4)
+        maAlignmentLabel = "asc_5_10_20_60_120";
+    else if (maOrderTiers === 3)
+        maAlignmentLabel = "asc_5_10_20_60";
+    else if (maOrderTiers === 2)
+        maAlignmentLabel = "asc_5_10_20";
+    // 트레이더 톤 자연어 풀이
+    const volMultLabel = d1VolumeMultipleAvg >= 5
+        ? `평소의 ${d1VolumeMultipleAvg.toFixed(1)}배가 폭발적으로 터지면서`
+        : d1VolumeMultipleAvg >= 2
+            ? `평소보다 ${d1VolumeMultipleAvg.toFixed(1)}배 많은 거래량으로`
+            : `거래량이 늘어나며`;
+    const d0VolPct = Math.round(d0VolumeRatio * 100);
+    const d0VolLabel = d0VolPct <= 30
+        ? `오늘 거래량은 어제의 ${d0VolPct}% 밖에 안 돼요. 매도 압박이 거의 없다는 뜻이에요`
+        : `오늘 거래량은 어제의 ${d0VolPct}% 수준으로 줄어, 잠시 숨고르기 중이에요`;
+    const trendLabel = maOrderTiers >= 3
+        ? "단기·중기 이평선이 모두 정배열로 추세가 살아있어요"
+        : maOrderTiers === 2
+            ? "5·10·20일선 정배열로 단기 추세는 살아있어요"
+            : `${mustHoldMa}일 이동평균선 위에서 잘 버티고 있어요`;
+    const humanSummary = `어제 ${volMultLabel} ${d1ChangePct.toFixed(1)}% 강하게 올랐어요. ${d0VolLabel}. ${trendLabel}.`;
+    const d1TradingValue = d1.close_krw * d1.volume;
+    const metrics = {
+        d1ChangePct: Number(d1ChangePct.toFixed(2)),
+        d1VolumeMultipleAvg: Number(d1VolumeMultipleAvg.toFixed(2)),
+        d1VolumeBaselineDays: baselineDays,
+        d0VolumeRatio: Number(d0VolumeRatio.toFixed(3)),
+        d0BodyRatioVsD1: Number(d0BodyRatio.toFixed(3)),
+        d1TradingValueKrw: Math.round(d1TradingValue),
+        maAlignment: maAlignmentLabel,
+        maClusterDistancePct: Number(clusterAvgDistancePct.toFixed(2)),
+        longMaBreakthrough: breakthroughLongMa,
+    };
+    return { passed: true, score: 1, reasons, humanSummary, metrics };
+}
+/**
+ * 양음양 패턴 2 · 윗꼬리형 (당일 회전)
+ *
+ * D-1 윗꼬리 긴 대량거래 양봉 + 마감이 단기 MA 위 → D-0 거래량 ≤ 50% + 시초 음수.
+ * 분봉 데이터 없이 일봉만으로 추정 가능한 부분만 체크. 정밀 검증은 LLM 이 종합.
+ */
+export function matchYinYangUpperShadow(p, candles) {
+    if (candles.length < 12)
+        return fail("candles<12");
+    const d0 = candles[0];
+    const d1 = candles[1];
+    const d2 = candles[2];
+    const minUpperShadowRatio = p.d1MinUpperShadowRatio ?? 1.0;
+    const mustCloseAboveMa = p.d1MustCloseAboveMa ?? [5, 10];
+    const d0MaxVolumeRatio = p.d0MaxVolumeRatio ?? 0.5;
+    const d0OpenBelowD1Close = p.d0OpenBelowD1Close ?? true;
+    const d1MaxChangePct = p.d1MaxChangePct ?? 22;
+    const mustHoldMa = p.mustHoldMa ?? 5;
+    /* D-1 양봉 + 윗꼬리 길어야 함 */
+    if (d1.close_krw <= d1.open_krw)
+        return fail("d1_not_bullish");
+    const d1Body = d1.close_krw - d1.open_krw;
+    if (d1Body <= 0)
+        return fail("d1_no_body");
+    /* D-1 등락률 max (20% 초과 급등 제외 · v2 원본) */
+    if (d2 && d2.close_krw > 0) {
+        const d1ChangePct = ((d1.close_krw - d2.close_krw) / d2.close_krw) * 100;
+        if (d1ChangePct > d1MaxChangePct)
+            return fail(`d1_change_above_${d1MaxChangePct}`);
+    }
+    const d1UpperShadow = d1.high_krw - d1.close_krw;
+    const upperShadowRatio = d1UpperShadow / d1Body;
+    if (upperShadowRatio < minUpperShadowRatio)
+        return fail(`upper_shadow_ratio_below_${minUpperShadowRatio}`);
+    /* D-0 close > MA5 (5일선 미이탈 hard · 너울 §필수) */
+    if (candles.length >= mustHoldMa) {
+        const ma = averageClose(candles, mustHoldMa);
+        if (ma > 0 && d0.close_krw <= ma)
+            return fail(`upper_shadow_d0_below_ma${mustHoldMa}`);
+    }
+    /*
+     * D-1 마감이 단기 이평선 위.
+     * taeeun-life v2 원본: "5일선, 10일선 위에서 끝나야만 다음 날 공략 가능"
+     * 해석:
+     *  - 5일선 위는 hard (필수)
+     *  - 10일선 위까지 있으면 가산점 (둘 다 위 = 더 이상적)
+     */
+    const periodPriority = [...mustCloseAboveMa].sort((a, b) => a - b); // [5, 10]
+    const baseMaPeriod = periodPriority[0]; // 보통 5
+    const baseMa = candles.length >= baseMaPeriod + 1
+        ? averageClose(candles.slice(1), baseMaPeriod) : 0;
+    if (baseMa <= 0 || d1.close_krw <= baseMa) {
+        return fail(`d1_close_not_above_ma${baseMaPeriod}`);
+    }
+    let aboveAllShortMas = true;
+    const aboveMaList = [baseMaPeriod];
+    for (const period of periodPriority.slice(1)) {
+        if (candles.length < period + 1) {
+            aboveAllShortMas = false;
+            continue;
+        }
+        const ma = averageClose(candles.slice(1), period);
+        if (ma > 0 && d1.close_krw > ma)
+            aboveMaList.push(period);
+        else
+            aboveAllShortMas = false;
+    }
+    /* D-0 거래량 ≤ 50% + (옵션) 시초 음수 */
+    const d0VolumeRatio = d1.volume > 0 ? d0.volume / d1.volume : 0;
+    if (d0VolumeRatio > d0MaxVolumeRatio)
+        return fail(`d0_volume_ratio_above_${d0MaxVolumeRatio}`);
+    if (d0OpenBelowD1Close && d0.open_krw >= d1.close_krw)
+        return fail("d0_open_not_below_d1_close");
+    /* D-1 거래량은 그래도 평소보다 많아야 (의미 있는 윗꼬리) · D-2 대비 1.5x 가벼운 체크 */
+    const d1vsd2 = d2.volume > 0 ? d1.volume / d2.volume : 0;
+    if (d1vsd2 < 1.2)
+        return fail(`d1_volume_too_normal_${d1vsd2.toFixed(2)}`);
+    void aboveAllShortMas;
+    const reasons = [
+        `윗꼬리형 [D-1 양봉 + 윗꼬리/몸통 ${upperShadowRatio.toFixed(1)}배]`,
+        `MA[${aboveMaList.join("·")}] 위 마감`,
+        `[D-0 거래량 ${(d0VolumeRatio * 100).toFixed(0)}% · 시초 음수]`,
+    ];
+    const d0VolPct = Math.round(d0VolumeRatio * 100);
+    const maListLabel = aboveMaList.length > 0 ? aboveMaList.map((p) => `${p}일선`).join("·") : "단기선";
+    const humanSummary = `어제 큰 매물대 (윗꼬리 ${upperShadowRatio.toFixed(1)}배) 를 만났지만 ${maListLabel} 위에서 마감했어요. 오늘은 거래량이 어제의 ${d0VolPct}% 로 줄고 시초가는 음수 — 매도세가 빠지고 있다는 신호예요.`;
+    const metrics = {
+        upperShadowRatio: Number(upperShadowRatio.toFixed(2)),
+        upperShadowAboveMas: aboveMaList,
+        d0VolumeRatio: Number(d0VolumeRatio.toFixed(3)),
+    };
+    return { passed: true, score: 1, reasons, humanSummary, metrics };
+}
+/**
+ * 양음양 패턴 3 · 횡보형 (이격 관리 · 다분할)
+ *
+ * 양봉 이후 N일간 거래량 감소시키며 단기 MA 위 횡보.
+ */
+export function matchYinYangSideways(p, candles) {
+    const range = p.sidewaysDaysRange ?? [3, 10];
+    const maxAvgVol = p.sidewaysMaxAvgVolumeRatio ?? 0.7;
+    const mustStayMa = p.mustStayAboveMa ?? 5;
+    const minBigBullishPct = p.bigBullishMinChangePct ?? 5;
+    const maxBigBullishPct = p.bigBullishMaxChangePct ?? 22;
+    const bullishMinGapPct = p.bullishMinGapPct ?? 5;
+    const requireGapConvergence = p.requireGapConvergence ?? true;
+    if (candles.length < range[1] + 10)
+        return fail(`candles<${range[1] + 10}`);
+    /* 양봉을 찾는다 (D-N) · 가장 최근 양봉 ≥ minBigBullishPct */
+    let bigBullishIdx = -1;
+    for (let i = range[0]; i <= range[1]; i++) {
+        const c = candles[i];
+        const prev = candles[i + 1];
+        if (!c || !prev || prev.close_krw <= 0)
+            continue;
+        if (c.close_krw <= c.open_krw)
+            continue;
+        const pct = ((c.close_krw - prev.close_krw) / prev.close_krw) * 100;
+        /* 20% 초과 폭등은 v2 원본 제외 조건 위반 · 양봉 후보로 부적합 */
+        if (pct > maxBigBullishPct)
+            continue;
+        if (pct >= minBigBullishPct) {
+            bigBullishIdx = i;
+            break;
+        }
+    }
+    if (bigBullishIdx < 0)
+        return fail(`no_big_bullish_in_${range[0]}~${range[1]}d (within ${minBigBullishPct}~${maxBigBullishPct}%)`);
+    const bigBullish = candles[bigBullishIdx];
+    const d0 = candles[0];
+    /* 이후 ~ D-0 횡보 + 거래량 감소 + MA 위 유지 */
+    const sidewaysSlice = candles.slice(0, bigBullishIdx); // [D-0, ..., D-(N-1)]
+    if (sidewaysSlice.length === 0)
+        return fail("no_sideways_period");
+    const avgVolDuringSideways = sidewaysSlice.reduce((s, c) => s + c.volume, 0) / sidewaysSlice.length;
+    const volRatio = bigBullish.volume > 0 ? avgVolDuringSideways / bigBullish.volume : 0;
+    if (volRatio > maxAvgVol)
+        return fail(`sideways_avg_vol_too_high_${volRatio.toFixed(2)}`);
+    // MA 위 유지 (각 시점의 MA 로 정확 비교 · D-0 ma 단일 비교는 부정확)
+    for (let offset = 0; offset < bigBullishIdx; offset++) {
+        const sliceFromOffset = candles.slice(offset);
+        const maAtOffset = averageClose(sliceFromOffset, mustStayMa);
+        if (maAtOffset > 0 && sliceFromOffset[0].close_krw <= maAtOffset) {
+            return fail(`broke_below_ma${mustStayMa}_at_d${offset}`);
+        }
+    }
+    const ma = averageClose(candles, mustStayMa);
+    /* ─── 이격 확대 + 수렴 검증 (taeeun-life v2 핵심) ─── */
+    // 양봉 시점 ma5 = candles.slice(bigBullishIdx) 의 첫 5개 평균
+    const bigBullishMa = averageClose(candles.slice(bigBullishIdx), mustStayMa);
+    if (bigBullishMa <= 0)
+        return fail("bigBullish_ma_invalid");
+    const bigBullishGapPct = ((bigBullish.close_krw - bigBullishMa) / bigBullishMa) * 100;
+    if (bigBullishGapPct < bullishMinGapPct) {
+        return fail(`bullish_gap_too_small_${bigBullishGapPct.toFixed(1)}%`);
+    }
+    // 오늘 이격
+    const todayGapPct = ((d0.close_krw - ma) / ma) * 100;
+    if (requireGapConvergence && todayGapPct >= bigBullishGapPct) {
+        return fail(`gap_not_converging (${bigBullishGapPct.toFixed(1)}%→${todayGapPct.toFixed(1)}%)`);
+    }
+    const gapShrinkPct = bigBullishGapPct - todayGapPct;
+    const reasons = [
+        `횡보형 [D-${bigBullishIdx + 1} 장대양봉 후 ${sidewaysSlice.length}일 횡보]`,
+        `[횡보 평균 거래량 ${(volRatio * 100).toFixed(0)}% · MA${mustStayMa} 위 유지]`,
+        `[이격 ${bigBullishGapPct.toFixed(1)}%→${todayGapPct.toFixed(1)}% · ${gapShrinkPct.toFixed(1)}%p 수렴]`,
+    ];
+    const daysAgo = bigBullishIdx + 1;
+    const sidewaysDays = sidewaysSlice.length;
+    const volPct = Math.round(volRatio * 100);
+    const volLabel = volPct <= 30
+        ? `그동안 거래량은 평소의 ${volPct}% 정도로 거의 잔잔했어요. 보통 이런 매집 후엔 한 번 더 움직임이 나오곤 해요`
+        : volPct <= 50
+            ? `그동안 거래량은 평소의 ${volPct}% 수준으로 가라앉았는데 — 매수세가 차분히 들어오고 있다는 신호예요`
+            : `그동안 거래량은 평소의 ${volPct}% 수준이에요`;
+    const humanSummary = `${daysAgo}일 전 큰 양봉 이후 ${sidewaysDays}일째 잔잔한 흐름이에요. ${volLabel}. 가격이 ${mustStayMa}일선에 점점 가까워지면서 (이격 ${bigBullishGapPct.toFixed(1)}% → ${todayGapPct.toFixed(1)}%) 매수 시점이 가까워졌어요.`;
+    const metrics = {
+        sidewaysBigBullishIdx: bigBullishIdx,
+        sidewaysAvgVolRatio: Number(volRatio.toFixed(3)),
+        sidewaysBullishGapPct: Number(bigBullishGapPct.toFixed(2)),
+        sidewaysTodayGapPct: Number(todayGapPct.toFixed(2)),
+        sidewaysGapShrinkPct: Number(gapShrinkPct.toFixed(2)),
+    };
+    return { passed: true, score: 1, reasons, humanSummary, metrics };
+}
+/** Bullish Engulfing: D-1 음봉 + D-0 양봉이 D-1 body 감싸기 */
+function matchEngulfingBull(_p, candles) {
+    if (candles.length < 2)
+        return fail();
+    const d0 = candles[0];
+    const d1 = candles[1];
+    const d1IsBearish = d1.close_krw < d1.open_krw;
+    const d0IsBullish = d0.close_krw > d0.open_krw;
+    if (!d1IsBearish || !d0IsBullish)
+        return fail();
+    if (d0.open_krw > d1.close_krw)
+        return fail(); // D-0 시가가 D-1 종가 이하
+    if (d0.close_krw < d1.open_krw)
+        return fail(); // D-0 종가가 D-1 시가 이상
+    const reasons = ["장악형 양봉 (D-0 캔들이 D-1 body 포함)"];
+    return { passed: true, score: 1, reasons, metrics: {} };
+}
+/** Morning Star: D-2 음봉 → D-1 작은 몸통 → D-0 양봉 (D-2 중간 이상 회복) */
+function matchMorningStar(_p, candles) {
+    if (candles.length < 3)
+        return fail();
+    const [d0, d1, d2] = [candles[0], candles[1], candles[2]];
+    if (d2.close_krw >= d2.open_krw)
+        return fail(); // D-2 음봉
+    const d1Body = Math.abs(d1.close_krw - d1.open_krw);
+    const d2Body = Math.abs(d2.close_krw - d2.open_krw);
+    if (d1Body > d2Body * 0.3)
+        return fail(); // D-1 작은 몸통
+    if (d0.close_krw <= d0.open_krw)
+        return fail(); // D-0 양봉
+    const d2Mid = (d2.open_krw + d2.close_krw) / 2;
+    if (d0.close_krw < d2Mid)
+        return fail(); // D-2 중간 위
+    return { passed: true, score: 1, reasons: ["샛별형 (Morning Star)"], metrics: {} };
+}
+/** Hammer: 긴 아래꼬리 + 짧은 몸통 + 짧은 윗꼬리 */
+function matchHammer(p, candles) {
+    if (candles.length < 1)
+        return fail();
+    const c = candles[0];
+    const body = Math.abs(c.close_krw - c.open_krw);
+    const lowerTail = Math.min(c.open_krw, c.close_krw) - c.low_krw;
+    const upperTail = c.high_krw - Math.max(c.open_krw, c.close_krw);
+    if (body <= 0)
+        return fail();
+    const ratio = lowerTail / body;
+    const minRatio = p.minTailBodyRatio ?? 2;
+    if (ratio < minRatio)
+        return fail();
+    if (upperTail > body * 0.5)
+        return fail();
+    return { passed: true, score: 1, reasons: [`망치형 (아래꼬리/몸통=${ratio.toFixed(1)}x)`], metrics: {} };
+}
+/** MA Rebound: 종가가 특정 MA 부근에서 반등 (저가 < MA < 종가) */
+function matchMaRebound(p, candles, _row) {
+    if (candles.length < p.ma)
+        return fail();
+    const c = candles[0];
+    const maVal = averageClose(candles, p.ma);
+    if (maVal <= 0)
+        return fail();
+    if (c.low_krw >= maVal)
+        return fail(); // 터치 확인
+    if (c.close_krw <= maVal)
+        return fail(); // 회복 확인
+    const bouncePct = ((c.close_krw - c.low_krw) / c.low_krw) * 100;
+    const minBounce = p.minBouncePct ?? 1;
+    if (bouncePct < minBounce)
+        return fail();
+    return {
+        passed: true,
+        score: 1,
+        reasons: [`MA${p.ma} 반등 (${bouncePct.toFixed(1)}%)`],
+        metrics: {},
+    };
+}
+function fail(reason = "unknown") {
+    return { passed: false, score: 0, reasons: [], metrics: {}, failReason: reason };
+}
+function buildHit(row, reasons, humanSummaries, ma, candles, matchedPatterns = [], rawMetrics = {}) {
+    const d0 = candles?.[0];
+    const d1 = candles?.[1];
+    const todayChangePct = d0 && d1 && d1.close_krw > 0 ? ((d0.close_krw - d1.close_krw) / d1.close_krw) * 100 : 0;
+    return {
+        code: row.code,
+        name: row.name,
+        market: row.market,
+        listCount: row.list_count,
+        lastPriceKrw: row.last_price_krw,
+        todayVolume: d0?.volume ?? 0,
+        todayChangePct,
+        matchedPatterns,
+        reasons,
+        humanSummaries,
+        ma,
+        rawMetrics: rawMetrics,
+        // score: 통과 패턴 수 (deprecated · LLM 이 rawMetrics 보고 평가)
+        score: matchedPatterns.length,
+    };
+}
+function averageClose(candles, period) {
+    if (candles.length < period)
+        return 0;
+    const sum = candles.slice(0, period).reduce((s, c) => s + c.close_krw, 0);
+    return sum / period;
+}
+//# sourceMappingURL=engine.js.map