#TryAndRun-TvT/fast_qr_moonbit

基于 MoonBit 的高性能二维码（QR Code）生成库。 纯 MoonBit 实现、无外部依赖，逐位对齐 Rust 参考库 fast_qr v0.14.0。

本页是落地页：只给「能做什么 / 怎么用 / 边界在哪 / 去哪看细节」。 数字、参数、实验设计与历史记录一律在 docs/， 本页的每条结论都带出处链接。

#目录

• 功能特性
• 能力与局限
• 快速开始
• 构建与运行
• 性能与体积
• 测试
• 文档索引
• 项目结构
• 工程约定与贡献
• License

#功能特性

• 纯 MoonBit 实现，无外部依赖，可直接 moon add 依赖到你的项目。
• 标准合规：ISO/IEC 18004 —— 版本 V01–V40、四种纠错级别、三模式自动编码 （Numeric / Alphanumeric / Byte）+ 自动回退、8 种掩码评分择优。
• 逐字节对齐参考：矩阵与 fast_qr v0.14.0 全量快照逐位一致，可被第三方解码器读回原文。
• 单后端产物：仅 wasm-gc（体积小、性能好；宿主需支持 GC 提案）。
• 两用接口：过程式 QRCode::build 编排入口 + 链式 QRBuilder 便捷构造器。
• 多样输出：终端字符画（to_str/print）与 SVG 字符串（SvgBuilder，6 种模块形状）。

#能力与局限

• 编码模式仅支持 Byte/Alphanumeric/Numeric；Kanji 模式暂不支持（与参考 fast_qr 一致）。
• 输入按 ASCII 字节 处理（非 ASCII 多字节字符的语义见 S6 评审记录 的优化建议）。
• 产物形态面向 wasm：MoonBit Int 32 位、纠错位流 KEEP_LAST=33（取 Rust wasm32 分支）， 对真实 QR 语义无差别（详见 S9 评估记录 §2.4）。
• 仅支持 wasm-gc：moon.mod 声明 supported_targets = "+wasm-gc"，下游 native/JS 消费者会被构建系统 直接拒绝（实测 does not support target backend 'native'）。库本身是纯 MoonBit，此为有意的分发范围收缩； 其中 native 另需系统 C 编译器（当前 CI/本地镜像未装）。
• 宿主需支持 wasm-gc（GC 提案）：如 Node ≥ 22 / V8、启用 GC 的 wasmtime；CLI println 依赖 spectest.print_char 导入（非标准 WASI）。wasm(WASI) 通用兜底已移除，宿主接入面相应变窄。 取舍与复核见 S9n wasm-gc 收敛审计 §1。

#快速开始

moon add TryAndRun-TvT/fast_qr_moonbit

发布状态：已发布（首个版本）；本页为仓库当前文档，可能领先于线上归档， 精确版本以 mooncakes 页面 为准。

import {
  "TryAndRun-TvT/fast_qr_moonbit/lib",
}

///|
test "readme_quick_start" {
  let qr = @lib.QRBuilder::from_string("https://example.com/").build()
  match qr {
    Ok(q) => {
      // V02 → 边长 4*2+17 = 25；访问器返回 Option（手搓 QRCode 无元数据）
      assert_eq(q.size(), 25)
      assert_eq(q.version().unwrap().width(), q.size())
      assert_eq(q.ecl().unwrap(), @lib.ECL::Q)
      assert_true(q.to_str().length() > 0)
      let svg = @lib.SvgBuilder::default()
        .module_color("#0000ff")
        .background_color("#ffffff")
        .shape(@lib.Shape::RoundedSquare)
        .to_str(q)
      assert_true(svg.has_prefix("<svg"))
    }
    Err(_) => abort("README 示例内容构建失败")
  }
}

上面的 mbt check 块是 document test：moon test 会真编译、真运行它—— 改公共 API 而不同步改示例，测试直接变红。机制与踩坑见 README优化-冗余清理与最佳实践.md §6.3。

#构建与运行

curl -fsSL https://cli.moonbitlang.cn/install/unix.sh | bash
export PATH="$HOME/.moon/bin:$PATH"

moon build lib                    # 编译库包
moon build cmd/main --release     # 编译 CLI（唯一后端 wasm-gc）
moon run   cmd/main               # 运行 CLI 演示（终端字符画 + SVG）
moon test                         # 运行单元/快照/文档测试

bash scripts/gates.sh                 # 全量；支持 STAGES="check test" / SKIP_SLOW=1

门禁阶段清单、脚本分组与逐个用途见 AGENTS.md §三 · S9r §4 脚本分组。 -Oz 体积最优档的命令、moon-wasm-opt 参数与「为何要 --disable-custom-descriptors」，见 S9r §1。

#性能与体积

数字仅作选型与迭代基线，不代表对 fast_qr 的追赶承诺。本页只给量级； 表格、参数、统计离散与护栏见 S9r · 明细。

• 性能 vs fast_qr-wasm32：单次 build 慢 ≈1.0–2.2×（点数越小差距越大）， 逐位对齐 sha256 零差异；差距集中在 8 轮掩码择优主循环。 复跑 bash scripts/bench-host.sh　→ 口径 S9p · 离散 S9q
• 性能 vs 生态 moonqr：全程快 2.7–4.3×（同 run 比值；同输入 / ECL H / 强制版本 / 自动择优）。 复跑 bash scripts/bench-moonqr.sh（moon CLI 直调，钉版 moonqr@0.2.0）　→ S9u
• 体积 vs fast_qr：库对库对称锚点 ≈0.65×（本仓库更小）；差距大头是运行时地板，非 QR 实现。 复跑 bash scripts/bench-size.sh　→ S9i
• 优化状态：已落地 P0 掩码特化 + P2 评分去闭包/列缓冲 + P2b + 矩阵介质去 Array 间接（FixedArray[Int]，V40 宿主 ≈−15%、体积 ≈−6%），V40H 受控 A/B −26%（输出逐位不变）； 待做与上限见 S9n · S9k
• 报告纪律：只引用同 run 内成对比值；绝对毫秒绑定 Node 版本与调度态，跨环境不可比（S9q）。

#测试

• 分层：黑盒 *_test.mbt（锁公共契约）/ 白盒 *_wbtest.mbt（锁实现）/ README mbt check（文档测试）。
• 证据链：变异检测（植入最小缺陷须被检出）+ 第三方解码回读（jsQR 读回原文）+ 黄金值钉版重建 + 与参考 wasm 逐位 sha256 差分。
• 门禁：bash scripts/gates.sh（全量）· 单项 scripts/test.sh、scripts/coverage.sh --floor。
• 维护入口：S10 测试 roadmap（覆盖矩阵 + 七条铁律）· S10b 覆盖率报告 · S10c 真 bug 修复记录。

用例数与文件数不写进 README——它们随实现漂移，写死必然自相矛盾。需要数字时以 moon test 实跑为准。

#文档索引

本页只保留落地页所需的入口；文件名前缀 S<N> 为按实现顺序编号的阶段文档。 面向本仓库读者的完整导航（读者路径 / 按议题 / 全量清单）在 docs/README.md； 面向发布归档读者（mooncakes 落地页）的明细承接一律用仓库绝对链接（见文末「链接约定」）。

全量清单（含 docs/ 全部篇目与角色）在 docs/README.md §8。 新增文档须同步更新该文件与本表，否则 bash scripts/docs-link-check.sh 与 scripts/docs-consistency.sh ③ 会红（死链零容忍 + 索引覆盖）。

#链接约定（摘要）

#项目结构

.
├── moon.mod                    # MoonBit 模块配置
├── moon.pkg                    # 模块根空包：README 文档测试宿主（不写库代码）
├── lib/                        # 库包（公共 API）
│   ├── ecl / version / mode / mask.mbt  # 公共枚举（ECL/Version/Mode/Mask）
│   ├── module / qr / qr_build / qr_builder.mbt  # 容器、编排入口、链式构造器
│   ├── helpers / svg / shape.mbt        # 输出层（终端画 + SVG）
│   ├── *_test.mbt / *_wbtest.mbt        # 黑盒测试 / 白盒测试
│   └── internal/               # 实现子包（各带 moon.pkg；不反向依赖 lib）
│       ├── constants/          #   常量表 + 容量/元数据表
│       ├── bitstream/          #   位流缓冲（CompactQR）
│       ├── reedsolomon/        #   GF(256) 除法 + 交织
│       ├── data_encoding/      #   三模式编码 + 自动回退
│       └── matrix/             #   放置 / 掩码 / 评分
├── cmd/                        # 可执行包：main（CLI）/ bench / qr-min / host-probe
├── docs/                       # 项目文档（入口 = docs/README.md，见「文档索引」）
│   ├── README.md               #   目录首页：读者路径 + 分类地图 + 全量清单（§8 生成物）
│   ├── 01-规格/ 02-证据/        #   D2 分类：实现规格 / 审计数据
│   ├── 03-过程/ 04-元/          #   D2 分类：历史基线+发布过程 / 文档与 README 元规范
│   ├── 移植参考/                #   fast_qr 外部语料（自成一域，由域首页统辖）
│   └── assets/                 #   文档资源（qr-example.svg = README 示例码）
├── scripts/                    # 构建/门禁/基准脚本（分组见 S9r §4）
├── .githooks/ .cnb.yml         # 可选 Git 钩子 / 云原生构建配置
├── AGENTS.md                   # AI 协作代理指南（贡献前必读）
├── README.mbt.md -> README.md  # 文档测试入口（符号链接；正文在 README.md）
└── LICENSE                     # Apache-2.0

布局纪律：模块根只放元数据；库代码一律 lib/，实现细节 lib/internal/（不要建 src/）； 唯一例外是根空 moon.pkg（README 文档测试宿主）；测试放所属包内，*_test.mbt（黑盒）与 *_wbtest.mbt（白盒）不可混用。 文件级职责见 moonbit-实现布局与文件职责.md。

#工程约定与贡献

• 硬性约定（贡献前必读）：AGENTS.md——密钥/Token 永不入库、 不提交本地配置与构建产物、MoonBit 布局、文档死链零容忍、README 只保留结论+出处。
• 门禁：bash scripts/gates.sh（一键全量；没有 push CI，本地跑是唯一自动闸门）。
• 发布：bash scripts/publish.sh（默认干跑）。凭据属本地私有，发布不进 CI。
• 问题与建议：提交至仓库 Issue。
• Git 钩子（可选）：git config core.hooksPath .githooks（属个人本地配置，仓库不代设）。

#License