详细方案 · cmx-megasheet

架构ARCHITECTURE

五层，从数据模型到自定义元素Five layers, from data model to custom element

🧮

core

数据模型（零 DOM，可 Node 单测）：Workbook / Worksheet / Cell / Range / Style / SparseMatrix / SelectionModel / EditCommands（快照命令撤销）/ Clipboard / FillEngine / find / sort / validation。Data model (DOM-free, unit-testable in Node): Workbook / Worksheet / Cell / Range / Style / SparseMatrix / SelectionModel / EditCommands (snapshot-command undo) / Clipboard / FillEngine / find / sort / validation.

🔣

formula

公式引擎（纯逻辑）：Tokenizer → Parser(Pratt) → Evaluator → DependencyGraph（三色环）→ FormulaEngine；272 内置函数分数学/财务/统计/数据库/文本/引用族；QM/QC/JE/FS/REF 报表取数。Formula engine (pure logic): Tokenizer → Pratt Parser → Evaluator → DependencyGraph (3-color cycle) → FormulaEngine; 272 built-ins across math/finance/stats/database/text/ref; QM/QC/JE/FS/REF report fetches.

🖼️

render

画布渲染 + 交互（面向最小 RenderContext2D，可 mock 测）：SheetGeometry（getCellRect/hitTest）· PaneLayout（冻结/尾冻结/拆分 3-band）· Viewport · SheetRenderer · CellEditor · condFormat · numFmt · drawChart/drawSparkline。Canvas render + interaction (against a minimal RenderContext2D, mockable): SheetGeometry (getCellRect/hitTest) · PaneLayout (freeze/trailing/split 3-band) · Viewport · SheetRenderer · CellEditor · condFormat · numFmt · drawChart/drawSparkline.

💾

io

导入导出（零依赖）：snapshot（中性 JSON）· xlsx · csv · ssjson · zip/deflate/inflate · exportHtml/exportPdf/paginate。Import/export (zero-dep): snapshot (neutral JSON) · xlsx · csv · ssjson · zip/deflate/inflate · exportHtml/exportPdf/paginate.

🧩

element

<cmx-megasheet> 自定义元素 + ReportModel 输入契约。组件边界 = 公式栏 + 画布 + 页签栏 + 主题（工具栏留宿主）。约 150 个公共方法。The <cmx-megasheet> custom element + ReportModel input contract. Component boundary = formula bar + canvas + tab bar + theme (toolbar left to the host). ~150 public methods.

📤

index.ts

统一出口：既可作 <cmx-megasheet> 元素用，也可作库 import { Workbook, FormulaEngine } 用。A single entry: use as the <cmx-megasheet> element, or as a library via import { Workbook, FormulaEngine }.

硬约束INVARIANTS

六条不变式，贯穿全程Six invariants, held throughout

① 消费方零改Consumers change nothing

公共门面稳如契约，宿主 designer.js/report-applier.js 一个字节没动就换了内核。The public facade is a contract; hosts swapped kernels without a byte changed.

② src 浏览器纯净Browser-pure src

核心无 node 类型，可在真浏览器与 Node 双跑。No node types in the core — runs in both a real browser and Node.

③ 零运行时依赖Zero runtime deps

dependencies: {}——ZIP/DEFLATE/XLSX/PDF/图表/公式全自研。dependencies: {} — ZIP/DEFLATE/XLSX/PDF/charts/formula all in-house.

④ 画=点共享纯几何Draw = hit, shared geometry

getCellRect 与 hitTest 严格互逆，跨冻结/拆分/滚动/缩放恒成立。getCellRect and hitTest are strict inverses across freeze/split/scroll/zoom.

⑤ 可撤销 = 命令模式Undoable = command pattern

所有可撤销操作走快照命令，undo/redo 对称还原。Every undoable op is a snapshot command; undo/redo restore symmetrically.

⑥ 既有测试零回归No test regressions

945 单测常绿，每个里程碑另有 headless Chrome 真机自检。945 unit tests always green; each milestone also self-checks in headless Chrome.

🔣 公式引擎Formula engine

A1 语法：相对/绝对 $、跨表 Sheet1!A1、整列 A:A、整行 1:1、数组字面量 {1,2;3,4}、命名区域。依赖图拓扑重算 + 三色标记环检测（#CIRC!）+ 增量重算。A1 syntax: relative/absolute $, cross-sheet Sheet1!A1, whole column A:A, whole row 1:1, array literals {1,2;3,4}, named ranges. Topological recalc + 3-color cycle detection (#CIRC!) + incremental recalc.

数学/三角

Math/Trig

SIN COS LN LOG PI FACT COMBIN CEILING.MATH BASE ROMAN

财务

Finance

PMT FV PV NPV IRR XIRR MIRR SLN SYD DDB EFFECT

查找引用

Lookup

VLOOKUP HLOOKUP INDEX MATCH XLOOKUP ADDRESS INDIRECT

数据库 D

Database

DSUM DGET DCOUNT DAVERAGE

💾 IO · 数据格式IO · data formats

格式	Format	说明	Notes
JSON	`format:"cmx-megasheet"`，稀疏、不含视图态，单一事实源`format:"cmx-megasheet"`, sparse, view-free, single source of truth
XLSX	零依赖 ZIP+DEFLATE；值/公式/样式/合并/尺寸/多表/冻结/筛选/验证全保真（openpyxl 互通）Zero-dep ZIP+DEFLATE; values/formulas/styles/merges/sizes/sheets/freeze/filter/validation fully preserved (openpyxl-interop)
CSV	RFC-4180 引号转义，分隔符可选（`, ; \t`），可选 BOMRFC-4180 quote escaping, selectable delimiter (`, ; \t`), optional BOM
SSJSON	读历史工作簿，平滑迁移入中性快照Reads legacy workbooks, migrates smoothly into the neutral snapshot
HTML/PDF	HTML 带条件格式底色；零依赖手写 PDF（真浏览器可解析）HTML with conditional-format shading; zero-dep handwritten PDF (real browsers parse it)

详细方案说明Design & Scheme