ProStock/docs/factor_design.md

🚀 量化因子计算框架抽象设计与实施蓝图

一、 系统架构设计（四层解耦模型）

本系统采用严格的分层架构，每一层只需关注自己的输入与输出，层与层之间通过标准化的数据结构（如抽象语法树、需求清单、物理执行图）进行通信。

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 类，作为系统的统一入口。
• 执行流编排：接收研究员的表达式 -> 调用编译器解析依赖 -> 调用路由器连接数据库拉取并组装核心宽表 -> 调用翻译器生成物理执行计划 -> 将计划提交给计算引擎执行并行运算。
• 验收标准：模拟少量的内存数据作为假数据库，完整跑通一条“从表达式注册，到自动按需取数，最终输出包含因子结果数据表”的全流程链路。

---