refactor(factor): 计划重构factor模块

docs/factor_design.md

@@ -0,0 +1,88 @@
+
+
+# 🚀 量化因子计算框架抽象设计与实施蓝图
+
+## 一、 系统架构设计（四层解耦模型）
+
+本系统采用严格的分层架构，每一层只需关注自己的输入与输出，层与层之间通过标准化的数据结构（如抽象语法树、需求清单、物理执行图）进行通信。
+
+### 1. 领域特定语言层（DSL Layer / 用户层）
+*   **职责**：提供对量化研究员极度友好的因子表达式编写接口，屏蔽所有底层计算引擎和数据库的痕迹。
+*   **输入**：研究员编写的数学与逻辑表达式。
+*   **输出**：纯粹的、无状态的**抽象语法树（AST）**。
+*   **边界约束**：本层绝对不允许依赖任何外部数据处理库。它只负责描述“计算逻辑是什么”，不涉及“怎么算”和“数据在哪”。
+
+### 2. 编译与分析层（Compiler Layer / 解析层）
+*   **职责**：接收 DSL 层生成的 AST，进行语法树分析与优化。
+*   **核心动作 1：依赖提取**。遍历语法树，找出所有的“叶子节点”（即基础数据字段），生成全局数据需求清单。
+*   **核心动作 2：图优化（可选）**。识别重复的子表达式结构，进行合并计算标记。
+*   **输出**：结构化的数据依赖清单（Set/List）和经过校验的 AST。
+
+### 3. 动态数据路由层（Data Router Layer / IO 层）
+*   **职责**：充当量化系统与底层多表数据库之间的桥梁。
+*   **核心逻辑**：基于元数据字典（记录字段所属的数据库表及数据频度），将分析层传递的“数据需求清单”转化为对数据库的最优查询指令。
+*   **输出**：在内存中组装好的、经过严格时间对齐与防未来函数处理的、极简的数据上下文（Data Context）。
+
+### 4. 物理执行引擎层（Execution Engine / 计算层）
+*   **职责**：将抽象的计算逻辑映射到具体的硬件或高性能计算库（如 Polars/向量化引擎）上并执行。
+*   **核心逻辑**：遍历 AST，将其翻译为物理引擎的执行算子。在这个翻译过程中，**系统隐式地强制注入量化计算的安全规则**（如截面分组、时序分组）。
+*   **输出**：最终的因子计算结果（面板数据表）。
+
+---
+
+## 二、 核心机制的具体实现逻辑（非代码描述）
+
+为了让 AI 准确理解你的意图，你需要向 AI 阐明以下四个核心逻辑的运作机制：
+
+### 1. 表达式树的生成机制 (符号化运算)
+*   **逻辑说明**：定义基础的变量节点（代表底层字段）和操作节点（代表加减乘除或函数）。通过重载面向对象语言的原生运算符（如算术运算符、比较运算符），使得变量节点参与运算时，不会抛出错误或执行计算，而是生成一个新的、包含左右子节点和操作符的父节点。
+*   **结果**：一个复杂的数学公式最终在内存里会变成一棵树状的数据结构。
+
+### 2. 动态 SQL 生成与按需加载机制
+*   **逻辑说明**：系统初始化时，加载一次数据库元数据（表名、列名、更新频率），形成路由字典。当收到需求清单时，系统不使用 `SELECT *`，而是通过路由字典找到字段对应的表，动态拼接 `SELECT [必要关联键], [需求字段] FROM [表名] WHERE[时间与股票池过滤]`。
+*   **结果**：极大降低数据库的 I/O 压力和网络传输负载。
+
+### 3. 数据对齐与防未来函数机制（极其重要）
+数据在内存中合并时，必须根据表的“频度属性”采取不同的关联策略：
+*   **同行频表（如日频基础与日频行情）**：以基准时间轴为左表，严格按照 `[资产标识, 交易日]` 进行精确匹配连接。
+*   **低频事件表（如财务报表）**：绝不能按自然日期或报告期关联。必须以“财报实际披露日”作为右表时间键，采用**“就近向后寻找匹配（Asof Join / Point-in-Time Join）”**策略。即某一天的财务数据，只能使用该日期之前（含当天）最新发布的那份财报。
+*   **防错铁律**：拼表完成后，必须强制按照 `[资产标识, 交易日]` 的优先级进行升序排序，为后续的滑动窗口计算提供物理连续性保障。
+
+### 4. 算子翻译与引擎方言注入机制
+物理层在将 AST 翻译为引擎执行图时，必须自动附加以下安全约束，这是研究员无需关心但系统必须保证的：
+*   **时序算子（如移动平均、动量）**：翻译时，必须向引擎下达强制指令——“本计算窗口必须被严格限制在单一资产的边界内”。
+*   **截面算子（如截面排名、行业中性化）**：翻译时，必须向引擎下达强制指令——“本计算必须在同一个交易日切片内横向展开”。
+
+---
+
+## 三、 Vibe Coding 实施与 Prompt 投喂计划
+
+在利用 AI 编写代码时，建议按照以下阶段逐步进行（可作为每个阶段发给 AI 的指令纲要）：
+
+### 里程碑 1：构建抽象语法树引擎 (DSL & AST)
+*   **任务指派**：要求 AI 设计一套纯粹的表达式树数据结构。包含基础节点类、变量节点类、二元/一元操作节点类、以及函数调用节点类。
+*   **验收标准**：通过重载运算符，可以随意组合变量（如 A, B, C），并且编写一个简单的打印函数，能够以可视化的方式（或 JSON 结构）输出这棵树的层次关系。绝不包含任何第三方数据处理库。
+
+### 里程碑 2：实现依赖解析器 (Compiler)
+*   **任务指派**：要求 AI 编写一个树遍历器（如使用 Visitor 模式）。该遍历器接收里程碑 1 产生的树根节点，递归访问所有分支，收集所有叶子节点（变量节点）的名称。
+*   **验收标准**：输入一个深层嵌套的复杂公式树，解析器能够准确、去重地返回该公式依赖的所有底层基础字段名称列表。
+
+### 里程碑 3：构建元数据路由与动态组装器 (Data Router)
+*   **任务指派**：要求 AI 设计一个数据上下文管理器。
+    1.  实现注册机制，能接收不同表的数据字典和频度属性（日频或 PIT 低频）。
+    2.  根据里程碑 2 提取的依赖列表，自动分配表归属，并生成最小化拉取数据的伪代码或抽象 SQL 查询计划。
+    3.  阐明并在代码结构中实现不同频度数据的合并对齐逻辑（精确连接与就近前向连接），以及最后的全局强制排序逻辑。
+*   **验收标准**：输入几个测试字段，管理器能正确输出不同表的查询指令清单，并展现合并逻辑的抽象流程。
+
+### 里程碑 4：构建物理引擎翻译器 (Translator)
+*   **任务指派**：指定一个高性能计算库（如 Polars）。要求 AI 编写一个翻译层，接收里程碑 1 的树节点，递归转化为该计算库的原生表达式对象。
+*   **验收约束**：在这个环节，要求 AI 必须在翻译时序函数时自动附加资产分组属性，在翻译截面函数时自动附加日期分组属性。
+*   **验收标准**：输入的抽象树被成功转化为计算引擎可以识别的执行计划对象，且分组属性被正确挂载。
+
+### 里程碑 5：系统顶层编排与端到端测试 (Orchestrator)
+*   **任务指派**：要求 AI 编写一个对外的 `FactorEngine` 类，作为系统的统一入口。
+*   **执行流编排**：接收研究员的表达式 -> 调用编译器解析依赖 -> 调用路由器连接数据库拉取并组装核心宽表 -> 调用翻译器生成物理执行计划 -> 将计划提交给计算引擎执行并行运算。
+*   **验收标准**：模拟少量的内存数据作为假数据库，完整跑通一条“从表达式注册，到自动按需取数，最终输出包含因子结果数据表”的全流程链路。
+
+---
+