架构决策记录

以下决策区分总纲要求与本次实施建议。开发过程中若调整，应留下原因、替代方案、影响任务和验证方式。

ADR-001｜模块化单体优先

本次建议。 先用 FastAPI 模块与 Celery worker 隔离在线/批处理责任，不为每个功能建独立服务。好处是调用关系容易阅读、调试与事务边界更清楚；代价是共享发布和进程资源。只有出现独立扩容、隔离或团队所有权要求时，再评估服务拆分。

总纲要求。 PostgreSQL 管治理资产，Milvus 管 dense，OpenSearch 管 lexical；V0 起全部接入，无 pgvector 过渡阶段。代价是本地资源与运维复杂度，所以 V0 必须记录资源实测，提供小数据开发参数，但不以替换基础设施消解原目标。

总纲要求。 Join Graph 从 PostgreSQL 关系加载，先不引入 Neo4j。图算法与业务基数验证可以独立测试；关系规模、更新频率和查询复杂度超出内存方案时再评估专用数据库。最短路径不等于正确业务 Join。

根据总纲细化。 V1 的简单基线仍需 SQLGlot、只读账户、允许对象、超时与行数限制。V4 增加完整授权、成本、IR、修复与结果规则。不能用“为了测 Baseline”解释执行危险 SQL。

总纲要求。 先把单次问数能力做成可检验服务，再将它们适配为工具。代价是早期不展示复杂 Agent 效果，收益是能归因每层质量，避免无限工具循环掩盖业务问题。

本轮已实现。 根目录 plan/ 保存勾选状态，站点在开发/构建时同步副本，任务卡片读取派生统计。浏览器不写文件，也不使用 localStorage 伪造开发完成状态。静态站部署后需要重新构建才能更新计划。

本次细化。 原文净销售额示例未完整定义退款、税与日期角色。V0 输出口径草案和手算夹具，V3 通过回归与审核发布。保留冲突比选一个貌似合理但未经确认的定义更利于教学和数据治理。

本次细化。 以问题家族隔离锁定测试集与调优/Verified Queries，防止简单改写泄漏。代价是可用示例减少，收益是评测更能说明泛化能力。系统回退后允许诊断失败，但不能静默把测试答案加到召回库后继续报告同一测试分数。

本次建议，原文未定。 控制数据与模拟业务数据使用不同数据库、账户与连接。第一阶段聚焦一个 SQL 方言可减少多驱动复杂度；数据源与执行 adapter 保留未来扩展入口，但本期不提前承诺跨库联邦查询。

写清具体触发、选项、理由、代价、影响任务、验证证据及可逆条件。不要记录“因为业界都这样做”，也不要把未经验证的性能猜测当结论。