# 实现说明

## 数据路径

参数解析 → 有界文件读取与严格 UTF-8 解码 → CSV 状态机 → 表头及主键校验 → 建立索引 → 比较 → 确定排序 → 报告与退出码。

| 文件 | 实际职责 |
| --- | --- |
| `src/model.mbt` | 公共数据类型、限制、诊断与私有 Table 数据 |
| `src/csv.mbt` | 四状态 CSV 解析器；原值、物理位置和资源限制 |
| `src/diff.mbt` | 表头映射、比较规则、主键索引、差异和结果排序 |
| `src/report.mbt` | 文本、JSON、Markdown 和错误输出 |
| `src/cli/args.mbt` | 纯参数解释和格式选择 |
| `src/cmd/main/main.mbt` | 命令编排、诊断和退出码 |
| `src/cmd/main/host.mbt` | JS FFI：有界文件读取、UTF-8 解码、参数和标准流 |
| `tests/integration.mjs` | 独立结果对照与真实进程验证 |
| `scripts/` | 构建、验证与打包，不参与产品算法 |

`moon.mod` 使用 `source = "src"`，因此移动物理目录不会改变 `JingLan0v0/moonrow` 公共导入路径。核心模块按文件组织在一个可复用包里，CLI 单独成包，让模型和解析/比较代码无需跨包相互依赖，同时保留清晰职责。MoonBit 单元测试与对应包同目录，进程集成测试在顶层 `tests/`，业务 CSV 样例在顶层 `examples/`。

## 关键决定

1. 按记录主键匹配，避免把行重排识别成修改。
2. 对组合主键的每段采用“UTF-16 长度:内容”编码；段长度限定边界，不受数据包含逗号、竖线、冒号或 emoji 影响。
3. 明确拒绝重复键，避免选择第一条或最后一条掩盖歧义。
4. 精确字符串比较，保留 `001` 与 `1` 等业务区别。
5. 显式调用 `lexical_compare` 排序。当前 MoonBit 默认字符串 Compare 先比较长度，不适合作为这里约定的字典序。
6. JSON 使用 MoonBit 标准库序列化；文本转义控制字符；Markdown 用数字字符实体转义标点以免原始值注入 HTML 或改变表格结构。
7. `Table` 对外为不透明类型，不能从外部改写解析后表格，避免绕过列数/表头校验。`headers()` 返回副本。
8. JS 宿主只提供文件读取、解码、参数、标准流和退出码；CSV 解析、匹配与报告均由 MoonBit 实现。

## 复杂度与资源

解析随字符数线性推进；比较用哈希索引，预期工作量取决于记录数、键长度和比较列数；差异记录按主键排序。两份表和差异结果在内存中，空间占用大于原始 CSV 字节数，不承诺无限规模。

宿主先检查已打开文件的大小，再分块读取到最多 10 MiB + 1 字节，以处理读取期间增长的文件；读取后仍检查总量。读取的内容不会发送到网络。

## 独立验证

MoonBit 测试验证公共接口、解析错误、组合主键、排序、资源边界和性质。Node 集成测试真实启动最终产物，并用独立对象模型计算 25 组固定种子的预期结果，双向核对全部 JSON 内容；该参考实现不解析 CSV、不共享产品编码方法。

## 后续维护

更改行为先更新 `limitations.md` 与相应测试；JSON 结构若不兼容需更改 schema_version。每次运行 `moon info` 和 `moon fmt`，评估接口 diff。当前只承诺通过验证的 JS 后端。