erp-report-engine 是一个面向 ERP 数据库的只读、可自验证数据层，主要用途是自动生成每周报告，并为 AI 智能体提供受防护的数据库访问。它适用于 Logo Tiger、Netsis、Mikro 等土耳其中小企业 ERP 所用的数据库（均为 MSSQL），也可用于 SQLite、PostgreSQL 等。资料称它无需 BI 许可证，也无需在 ERP 服务器安装代理，并且不执行写入操作。
主要能力
- 定时运行执行 9 条经审计的 SELECT 语句，输出一个自包含的 HTML 报告：相对 8 周基线的四个 KPI、带命名驱动因素的发现、数据质量门禁，以及与源数据对账的行数。
- 内置演示数据库，可运行演示命令查看样本报告，样例报告中包含故意植入的三个数据质量问题，均由门禁捕获。
- 通过 MCP 服务器向 AI 智能体暴露 ERP，智能体使用规范化实体（如 orders，而非 LG_001_01_ORFICHE）进行交互，并处于相同的只读防护与审计跟踪之下。
- 提供可选的 AI 摘要功能（--narrate）：仅向模型提供经审计的聚合数据（KPI、发现、账龄/集中度，绝不提供原始行），报告会打印模型看到的完整载荷，以便核验。未配置密钥时该标志不生效。支持任何兼容 OpenAI 的端点，包括本地无密钥模型（Ollama / LM Studio）。
- 内置投递：run --send 可通过 SMTP 邮件发送报告、向 Slack 或 Teams 发布摘要（Power Automate Workflows），并在成功或失败时 ping healthchecks.io 的 dead-man's-switch。所有密钥来自环境变量，通道失败仅记录日志而不会致命。
- 提供 Power BI Command Center：以 PBIP 项目形式作为代码编写，包含 TMDL 语义模型（星型架构、28 个文档化 DAX 度量，其中包括用 DAX 绘制每个客户迷你走势图和每个项目覆盖条的 SVG 微图表度量、应收账龄事实与度量、基于无间隙周序号的 Time Shift 计算组、字段参数），PBIR 报告（5 页 / 30 个视觉对象，由脚本从紧凑规格生成），以及暗色未来主题（已通过 Microsoft 官方主题架构验证）。
- 提供独立的只读 SQL 防护包 readonly-sql-guard（pip install readonly-sql-guard），仅依赖 re 和 sqlglot。
使用方式
- 60 秒演示（无需 ERP）：可通过 pipx 安装，命令如 pipx install "erp-report-engine[mssql]"（用于 Logo Tiger / Netsis / Mikro，SQL Server）或 [postgres]。也提供 Docker 支持：docker build -t erp-report-engine . 然后 docker run --rm -v "$PWD:/work" erp-report-engine run -c config.demo.yaml。SQLite 和 PostgreSQL 开箱即用；MSSQL 需添加 Microsoft 的 ODBC 驱动。
- 连接自有 ERP：将连接 URL 放入环境变量（绝不写入文件），复制 config.example.yaml → config.yaml，然后先用 dry-run 验证：validate 会检查连接、检验 profile 契约并对账计数，不触碰其他内容。
- 可用调度器运行；每次运行追加到 state.db，使报告能够表达“连续第三周下降”等跨运行记忆。退出码可供调度器分支判断：0 成功、2 配置错误、3 数据库/连接错误、4 契约错误（profile 架构错误或源计数无法对账）、5 在 --strict 下的数据质量失败、1 其他意外。机器可读结果输出到 stdout，日志输出到 stderr，可选通过 --log-file run.jsonl 写入 JSON 行文件。建议在 CI 中运行 validate --strict，在数字无法对账时使流水线失败。
- MCP 服务器提供六个工具，全部经由受防护路径；规范化模型也发布为机器可读契约 model.json（或 erp-report-engine schema）。
安全模型
- 只读在四个层面强制：词法、解析树、副作用函数防护、只读会话。
- 临时 SQL（智能体路径）更严格：query 和 guarded_query 以严格模式运行，默认拒绝防护无法命名的每个函数；sqlglot 的函数注册表作为允许列表。所有四个内置 profile 均通过该检查。
- 指出 MSSQL 没有会话级只读开关，因此建议在最小权限只读登录下运行引擎（MSSQL 用 db_datareader，PostgreSQL 用仅 SELECT 授权，理想情况是只读副本）。防护是纵深防御，授权是最终保障层。
- 防护附带可复现的信任基准：跨四种方言的 28 个格式良好的 SQL 攻击，全部被拒绝，以及仍必须通过的合法读取。基准还展示较弱防护（以 SELECT 开头的头部检查、写关键字黑名单）在同样 28 个用例上的差距：它们分别拒绝 6 和 9 个，关键字扫描甚至会阻止文本中包含“delete”一词的合法读取，而该防护拒绝全部 28 个且不阻止任何合法读取。
- profile 变量标识符安全（^[A-Za-z0-9_]{1,16}$），密钥绝不放在配置文件中（加载器拒绝任何形式的嵌入凭据，使用 url_env），每条执行的语句都随报告审计跟踪发布，单次查询有行数上限（默认 500k）。
- 测试套件向防护投掷大量注入尝试（多语句、三种语法的注释走私、事务控制拼接 ROLLBACK / COMMIT、SELECT INTO、锁定提示、隐藏在 CTE 中的 DELETE），期望每一个都抛出异常。
包含的 profile
- generic — 规范化架构，也是编写自有 profile 的模板。
- logo_tiger — MSSQL 上的 Logo Tiger / GO：LG_{firm}_{period}_ORFICHE 订单头与 CLCARD 客户、ORFLINE 行、STINVTOT 库存总计、TRCODE = 2 销售过滤，以及可选的来自 PAYTRANS 的应收账龄（installment TOTAL − PAID，MODULENR = 4）。Logo 架构因版本而异，profile 带有字段说明。
- netsis — MSSQL 上的 Logo Netsis 3（每公司一库）：TBLSIPAMAS / TBLSIPATRA 销售订单（FTIRSIP = '6'）、TBLCASABIT 客户、TBLSTOKPH 库存总计，以及可选的来自 TBLCAHAR 的应收账龄。字段映射自真实生产集成，弱点（订单状态、交货日期、AR 结算方法）在行内标记。
- mikro — MSSQL 上的 Mikro ERP（Mikro Yazılım，Fly/Jump/V16–V17）：SIPARISLER（sip_ 前缀，行级）销售订单、CARI_HESAPLAR 客户、STOK_HAREKETLERI 现有库存（sth_tip 进出），以及可选的来自 CARI_HESAP_HAREKETLERI 的应收账龄（cha_vade 到期日）。弱点（sip_tip 销售过滤、总计是否含增值税、订单无发货日期、纯运行余额 AR 台账无未结项标志）在行内标记。
Logo Tiger、Netsis 和 Mikro 合起来覆盖土耳其 SME ERP 市场的大部分（均为 MSSQL）。为其他 ERP（SAP B1、Odoo、自定义系统）编写 profile 意味着编写三条 SELECT 语句输出规范化列，可以是独立 YAML 并通过 profile: 指向，或放入 erp_report_engine/profiles/ 随包发布。
适用场景
- 需要从 ERP 数据库自动生成每周经营报告、且不愿使用或购买 BI 工具的企业。
- 需要让 AI 智能体以可证明只读、可审计的方式查询 ERP 数据的场景。
- 希望在 MCP 生态中安全暴露 ERP 实体（如 orders）而非原始表的开发者。
- 需要可嵌入自有 MCP 服务器或数据库工具的独立只读 SQL 防护的场景。
限制
- 资料明确 MSSQL 没有会话级只读开关，因此最终保障需依赖数据库层的最小权限只读登录或只读副本。
- 内置 profile 存在需针对具体版本核验的弱点，例如 netsis 的订单状态、交货日期、AR 结算方法，mikro 的 sip_tip 销售过滤、增值税包含性、无发货日期、AR 台账弱点。
- 资料未提供收费、价格、平台支持范围、性能指标或具体效果承诺；除上述内容外，其他细节暂未提供。
