@tcos/broker-parser 0.1.0

package/dist/core/registry.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * PluginRegistry — 券商插件注册表
+ *
+ * 管理所有已注册的 IBrokerPlugin 实例，支持：
+ * - 按名称精确获取
+ * - 列出全部已注册插件
+ * - 自动检测 PDF 所属券商（取置信度最高者）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginRegistry = void 0;
+class PluginRegistry {
+    constructor() {
+        this.plugins = new Map();
+    }
+    /** 注册一个券商插件 */
+    register(plugin) {
+        this.plugins.set(plugin.name, plugin);
+    }
+    /** 按名称获取插件，找不到则抛异常 */
+    getPlugin(name) {
+        const plugin = this.plugins.get(name);
+        if (!plugin) {
+            throw new Error(`Unknown broker: "${name}". Use --list-parsers to see available parsers.`);
+        }
+        return plugin;
+    }
+    /** 列出所有已注册插件 */
+    listPlugins() {
+        return Array.from(this.plugins.values());
+    }
+    /**
+     * 自动检测 PDF 所属券商
+     * 遍历所有插件调用 detect()，返回置信度最高且 >= 0.5 的插件
+     */
+    async autoDetect(filePath) {
+        let bestPlugin = null;
+        let bestScore = 0;
+        for (const plugin of this.plugins.values()) {
+            const score = await plugin.detect(filePath);
+            if (score > bestScore) {
+                bestScore = score;
+                bestPlugin = plugin;
+            }
+        }
+        if (!bestPlugin || bestScore < 0.5) {
+            throw new Error('Cannot auto-detect broker from this PDF. Try specifying with -b (e.g., -b phillip).');
+        }
+        return bestPlugin;
+    }
+}
+exports.PluginRegistry = PluginRegistry;
+//# sourceMappingURL=registry.js.map

package/dist/core/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAIH,MAAa,cAAc;IAA3B;QACmB,YAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IA6C9D,CAAC;IA3CC,eAAe;IACf,QAAQ,CAAC,MAAqB;QAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,sBAAsB;IACtB,SAAS,CAAC,IAAY;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,iDAAiD,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,gBAAgB;IAChB,WAAW;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,QAAgB;QAC/B,IAAI,UAAU,GAAyB,IAAI,CAAC;QAC5C,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;gBACtB,SAAS,GAAG,KAAK,CAAC;gBAClB,UAAU,GAAG,MAAM,CAAC;YACtB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,UAAU,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;QACJ,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AA9CD,wCA8CC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types/statement';
+export * from './types/raw';
+export * from './types/formatter';
+export * from './types/plugin';
+export { PhillipPlugin } from './parsers/phillip';
+export { ParsePipeline } from './core/pipeline';
+export type { ParseOptions, ParseResult, ParseTimings } from './core/pipeline';
+export { PluginRegistry } from './core/registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+// broker-parser 公共 API 入口
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginRegistry = exports.ParsePipeline = exports.PhillipPlugin = void 0;
+__exportStar(require("./types/statement"), exports);
+__exportStar(require("./types/raw"), exports);
+__exportStar(require("./types/formatter"), exports);
+__exportStar(require("./types/plugin"), exports);
+var phillip_1 = require("./parsers/phillip");
+Object.defineProperty(exports, "PhillipPlugin", { enumerable: true, get: function () { return phillip_1.PhillipPlugin; } });
+var pipeline_1 = require("./core/pipeline");
+Object.defineProperty(exports, "ParsePipeline", { enumerable: true, get: function () { return pipeline_1.ParsePipeline; } });
+var registry_1 = require("./core/registry");
+Object.defineProperty(exports, "PluginRegistry", { enumerable: true, get: function () { return registry_1.PluginRegistry; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,0BAA0B;;;;;;;;;;;;;;;;;AAE1B,oDAAkC;AAClC,8CAA4B;AAC5B,oDAAkC;AAClC,iDAA+B;AAC/B,6CAAkD;AAAzC,wGAAA,aAAa,OAAA;AACtB,4CAAgD;AAAvC,yGAAA,aAAa,OAAA;AAEtB,4CAAiD;AAAxC,0GAAA,cAAc,OAAA"}

package/dist/parsers/phillip/extract.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+pdfplumber 字符提取脚本
+
+供 TypeScript 规则引擎调用，输出 JSON 格式的字符数据。
+
+使用方法:
+python3 scripts/poc/pdfplumber_extract.py <pdf_path> --json
+"""
+
+import pdfplumber
+import json
+import sys
+import os
+from typing import List, Dict, Any
+
+
+def extract_chars_from_pdf(pdf_path: str) -> Dict[str, Any]:
+    """
+    从 PDF 提取所有页面的字符及其坐标
+
+    返回结构:
+    {
+        "file": "文件名",
+        "totalPages": 页数,
+        "pages": [
+            {
+                "pageNum": 1,
+                "chars": [
+                    {"text": "A", "x0": 10.0, "x1": 15.0, "top": 20.0, "bottom": 30.0},
+                    ...
+                ],
+                "text": "完整文本"
+            }
+        ]
+    }
+    """
+    result = {
+        "file": os.path.basename(pdf_path),
+        "totalPages": 0,
+        "pages": []
+    }
+
+    with pdfplumber.open(pdf_path) as pdf:
+        result["totalPages"] = len(pdf.pages)
+
+        for i, page in enumerate(pdf.pages):
+            page_data = {
+                "pageNum": i + 1,
+                "chars": [],
+                "text": ""
+            }
+
+            # 提取字符及坐标
+            for char in page.chars:
+                page_data["chars"].append({
+                    "text": char["text"],
+                    "x0": round(char["x0"], 2),
+                    "x1": round(char["x1"], 2),
+                    "top": round(char["top"], 2),
+                    "bottom": round(char["bottom"], 2)
+                })
+
+            # 提取完整文本
+            page_data["text"] = page.extract_text() or ""
+
+            result["pages"].append(page_data)
+
+    return result
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python3 pdfplumber_extract.py <pdf_path> [--json]", file=sys.stderr)
+        sys.exit(1)
+
+    pdf_path = sys.argv[1]
+
+    if not os.path.exists(pdf_path):
+        print(f"Error: File not found: {pdf_path}", file=sys.stderr)
+        sys.exit(1)
+
+    result = extract_chars_from_pdf(pdf_path)
+
+    # 始终输出 JSON (供 TypeScript 调用)
+    print(json.dumps(result, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/dist/parsers/phillip/extractor.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Phillip pdfplumber Stage 1 提取器
+ *
+ * 纯 PDF 表格提取，不做业务逻辑处理。
+ * 输出统一的 RawTableData 格式，供 Stage 2 处理。
+ *
+ * 职责：
+ * 1. 调用 pdfplumber 提取字符坐标
+ * 2. 按行/列分组
+ * 3. 提取原始字段值
+ * 4. 不做分类、不做字段合并
+ */
+import { RawTableData, IStage1Extractor, PdfplumberExtractorConfig } from '../../types/raw';
+/**
+ * Phillip pdfplumber Stage 1 提取器
+ */
+export declare class PhillipPdfplumberExtractor implements IStage1Extractor {
+    private config;
+    constructor(config?: Partial<Omit<PdfplumberExtractorConfig, 'type'>>);
+    /**
+     * 从 PDF 提取原始表格数据
+     */
+    extract(pdfPath: string): Promise<RawTableData>;
+    /**
+     * 调用 pdfplumber Python 脚本
+     */
+    private callPdfplumber;
+    /**
+     * 提取账户信息
+     *
+     * 辉立日结单格式示例:
+     * 客戶名稱 Name : SUN XIAOXU 客戶編號 A/C No : M596241
+     * 日期 Issue Date : 05/11/25
+     */
+    private extractAccountInfo;
+    /**
+     * 提取交易记录
+     *
+     * 跨页状态传递：inTransactionSection 和 lastTransaction 在页面间保持，
+     * 确保多页结单中 Page 2+ 即使没有区域标记也能继续提取交易。
+     */
+    private extractTransactions;
+    /**
+     * 合并跨页续行
+     * 识别规则：tradeDate 为空字符串 = 续行
+     */
+    private mergeCrossPageContinuations;
+    /**
+     * 从单页提取交易记录（支持跨页状态）
+     *
+     * 与原 extractPageTransactions 的区别：
+     * - 接收上一页的状态（是否在交易区域、最后一条交易）
+     * - 返回当前页处理后的状态，供下一页继续使用
+     * - 确保多页结单中 Page 2+ 没有区域标记时也能正确提取交易
+     *
+     * @param chars - 页面字符数据
+     * @param _warnings - 警告信息数组
+     * @param initialInSection - 初始是否在交易区域
+     * @param initialLastTx - 初始最后一条交易（用于续行合并）
+     * @returns 交易数据和更新后的状态
+     */
+    private extractPageTransactionsWithState;
+    /**
+     * 解析单行交易记录
+     * 只提取原始字段值，不做业务分类
+     */
+    private parseTransactionLine;
+    /**
+     * 智能提取字段 - 基于列位置
+     *
+     * 辉立日结单列边界参考:
+     * - tradeDate:   x = 30-65
+     * - settleDate:  x = 65-110
+     * - product:     x = 100-145 (可选，如 UT)
+     * - refNo:       x = 130-180
+     * - type:        x = 170-230
+     * - particulars: x = 195-490
+     * - debit:       x = 480-530
+     * - credit:      x = 530-580
+     */
+    private extractFieldsWithSmartBoundaries;
+    /**
+     * 提取续行中的摘要内容
+     */
+    private extractContinuationText;
+    /**
+     * 按 Y 坐标分组字符
+     */
+    private groupCharsByY;
+    /**
+     * 按间隔分组字符
+     */
+    private groupCharsByGap;
+    /**
+     * 获取一行的文本
+     */
+    private getLineText;
+    /**
+     * 检查是否匹配任意关键词
+     */
+    private matchesAny;
+    /**
+     * 检查是否是表头或分隔行
+     */
+    private isHeaderOrSeparator;
+    /**
+     * 检查是否是 PDF 页眉或页脚行
+     *
+     * 多页结单中每页都会重复出现的页面级标题和页脚，
+     * 与交易表格的表头行不同。跨页提取交易时需要跳过这些行。
+     *
+     * 注意：getLineText 将字符直接拼接，可能没有空格（如 "A/CNo:" 而非 "A/C No :"），
+     * 因此匹配模式需要兼容无空格情况。
+     */
+    private isPageHeaderOrFooter;
+    /**
+     * 解析金额
+     */
+    private parseAmount;
+    /**
+     * 提取持仓数据
+     *
+     * 包含两部分：
+     * 1. Account Details - 现金余额
+     * 2. Securities Portfolio - 股票/基金持仓
+     *
+     * 注意：Securities Portfolio 支持跨页提取，状态在页面之间传递
+     *
+     * @param pdfData - pdfplumber 输出数据
+     * @param warnings - 警告信息数组
+     * @returns 持仓数据数组
+     */
+    private extractHoldings;
+    /**
+     * 从 Account Details 区域提取现金余额
+     *
+     * 辉立日结单 Account Details 格式示例：
+     * | Currency | Balance C/F | Unsettled T+1 | ... | Available Balance |
+     * | HKD      | 63,832.41   | 0.00          | ... | 63,832.41         |
+     * | USD      | -0.30       | 0.00          | ... | -0.30             |
+     * | HKD(Base)| 63,830.07   | ...           | ... | 63,830.07         |  <- 跳过
+     *
+     * @param chars - 页面字符数据
+     * @param warnings - 警告信息数组
+     * @returns 现金余额数组
+     */
+    private extractAccountDetailsHoldings;
+    /**
+     * 检查是否是 Account Details 表头行
+     */
+    private isAccountDetailsHeader;
+    /**
+     * 解析现金余额行
+     *
+     * 行格式: Currency Balance_C/F Unsettled_T+1 ... Available_Balance Ref_ExRate DR_Int_Rate
+     * 示例:   HKD      63,832.41    0.00          ... 63,832.41         1.0000      列表1(Sch1)
+     *
+     * @param chars - 行字符数据
+     * @returns 现金余额持仓或 null
+     */
+    private parseCashBalanceLine;
+    /**
+     * 从 Securities Portfolio 区域提取股票/基金持仓（支持跨页状态）
+     *
+     * - 接收上一页的状态（是否在 Portfolio 区域、当前货币、最后一条持仓）
+     * - 返回当前页处理后的状态，供下一页继续使用
+     * - 不再依赖结束标记（如 E. & O. E.）来判断区域结束
+     *
+     * @param chars - 页面字符数据
+     * @param warnings - 警告信息数组
+     * @param initialInSection - 初始是否在 Portfolio 区域
+     * @param initialCurrency - 初始货币
+     * @param initialLastHolding - 初始最后一条持仓（用于续行合并）
+     * @returns 持仓数据和更新后的状态
+     */
+    private extractPortfolioHoldingsWithState;
+    /**
+     * 检查是否是 Portfolio 表头或汇总行
+     */
+    private isPortfolioHeaderOrFooter;
+    /**
+     * 检查是否是续行（中文名称行）
+     *
+     * 续行特征：
+     * 1. 以 "股票" 或 "基金" 开头
+     * 2. 右侧没有数值金额
+     */
+    private isPortfolioContinuationLine;
+    /**
+     * 从续行中提取中文名称
+     */
+    private extractChineseNameFromLine;
+    /**
+     * 解析单行持仓数据
+     *
+     * 列边界（基于 pdfplumber 坐标分析）：
+     * - Product (Equity/UT): x0 < 60
+     * - Market (XHKG/OTCU/XNGS): x0 = 80-115
+     * - InstrumentCd: x0 = 115-165
+     * - DisplayName: x0 = 160-270
+     * - Qty B/F: x0 = 260-295
+     * - LastBoughtOn (可选日期): x0 = 295-340
+     * - Qty C/F: x0 = 340-385
+     * - ClsPrice: x0 = 385-435
+     * - Market Value: x0 = 435-485
+     * - MgnRatio: x0 = 490-520
+     * - Margin Value: x0 = 530-570
+     *
+     * @param chars - 行字符数据
+     * @param currency - 当前货币
+     * @returns 持仓数据或 null
+     */
+    private parsePortfolioLine;
+}
+//# sourceMappingURL=extractor.d.ts.map

package/dist/parsers/phillip/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../src/parsers/phillip/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EACL,YAAY,EAIZ,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,iBAAiB,CAAC;AA4FzB;;GAEG;AACH,qBAAa,0BAA2B,YAAW,gBAAgB;IACjE,OAAO,CAAC,MAAM,CAA4B;gBAE9B,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;IAQrE;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA6BrD;;OAEG;YACW,cAAc;IAwC5B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAiBnC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,gCAAgC;IAkFxC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gCAAgC;IA8GxC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAmB/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IA2B5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,eAAe;IAoCvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,6BAA6B;IA2CrC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IAmC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iCAAiC;IA0FzC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAyBjC;;;;;;OAMG;IACH,OAAO,CAAC,2BAA2B;IAiBnC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAYlC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,kBAAkB;CAyG3B"}