内置二维码模块说明（部署即用）

目标：装完就能用。不依赖 qrencode、zbarimg、Python 或任何外部程序；只要 PHP 正常（有 GD 最佳，无 GD 也能生成 SVG 二维码），动态收款码与收款码图片解析都可用。

一、文件清单

文件	作用
`includes/qr/QrEncoder.php`	二维码生成器（纯 PHP）：数字/字母数字/字节模式，版本 1~40 自适应，纠错 L/M/Q/H，8 种掩码按标准罚分择优；输出 PNG（GD）或 SVG，可给 data URI
`includes/qr/QrDecoder.php`	二维码解码器（纯 PHP + GD）：版本 1~10（约 270 字节以内，覆盖收款码/网址类），纠错 L/M/Q/H，任意 90° 旋转与缩放，Otsu 二值化 + 定位图形检测 + 仿射采样 + 多重三元组搜索 + RS 纠错（GF(256)/Berlekamp-Massey）
`install/qr-selftest.php`	自检脚本：`php install/qr-selftest.php`

二、接入点（系统内自动生效）

函数	行为
`findQrEncoder()`	优先返回 `'builtin'`（内置编码器）；环境里没有内置时才去找 `qrencode`
`renderQrPngDataUri($text, $size, $margin)`	内置编码器直接用 GD 渲染 `data:image/png;base64,…`；无 GD 时自动退化为 SVG data URI
`detectQrDecoder()`	优先返回 `['type' => 'builtin', 'cmd' => '']`，其后才是 `zbarimg` / `python zxing` / `pyzbar`
`decodeQrImage($file)`	内置解码器解析上传的收款码图片；失败后仍会尝试环境里的外部解码器

前台「支付码」页（payment-code.php）与后台「收款码与二维码解析」页（admin/pay-qr.php）无需改动，它们调用上面这些函数，因此自动变为"部署即用"。

三、自检与验证

php install/qr-selftest.php

覆盖 5 组断言：

容量表一致性：版本 1~40 × L/M/Q/H 共 160 组（总码字 = 数据 + 纠错×块数）；
标准样例：ISO/IEC 18004 中 "01234567"（版本 1-M）的数据码字应为 10 20 0C 56 61 80 EC 11 EC 11 EC 11 EC 11 EC 11，以及格式信息 BCH（M/mask0）；
编码→解码往返：版本 1~12、四档纠错、多种字节长度；
四向旋转：0/90/180/270 全部可解；
真实载荷：支付宝 https://qr.alipay.com/...、微信 wxp://...、中文备注等。

四、能力边界（如实说明）

项	支持情况
生成	版本 1~40（约 2900 字节以内），PNG/SVG
解析	版本 1~10（约 270 字节以内）。更大的版本（如超长网址）会：① 内置解码返回空 → ② 若环境里有 `zbarimg`/Python 解码器则自动回退给它
图片	清晰、正立/任意 90° 旋转、等比缩放的截图（含手机截图、电脑截图）。强透视畸变、低对比、模糊、反色二维码不在保证范围
反色	深底浅码暂不支持（如需可在 `QrDecoder::binarize()` 后加反色重试）

五、常见问题

Q：后台「收款码解析」页显示"已就绪：内置纯 PHP 解码器"但仍解不出来？ A：多为图片质量问题。请确认：图片是二维码截图原图（不是被压缩过的聊天缩略图）、二维码区域完整（四角未被裁掉）、对比度正常。可先在自检脚本中确认模块本身正常：php install/qr-selftest.php。

Q：为什么解析只支持到版本 10？ A：版本 10 已可容纳 271 字节（L 档）。个人收款码内容（https://qr.alipay.com/... / wxp://...）通常 30~120 字节，远在范围内。更大的二维码（长网址、vCard、Wi-Fi 配置等）请安装 zbarimg，系统会自动优先使用它。

Q：会不会因为内置解码器而跳过环境里更好的解码器？ A：不会。内置解码失败后仍会继续尝试外部解码器（若存在）。