跳到主要内容

8.2 事实来源

本页规定文档事实从哪里取得，以及发生冲突时以什么为准。目标是避免版本号、API 签名、配置默认值、JDK 矩阵和测试数字在多处手工维护。

1. 总原则​

可执行事实以源码、POM、自动配置元数据、测试和 CI 为准；文档负责解释和路由，不反向定义不存在的能力。

优先级如下：

  1. 当前分支的生产源码和构建配置。
  2. 能证明行为的自动化测试。
  3. 本章列出的稳定性和使用策略文档。
  4. 教程、示例和历史迁移记录。

计划、路线图、注释中的未来设计和已归档报告均不能证明当前功能已经可用。

2. 唯一事实源矩阵​

事实唯一事实源文档规则
当前版本、Maven 坐标、模块、依赖版本根 POM 和模块 POM文档中的当前版本应由发布流程同步或校验
发行产物 Java 版本maven.compiler.release 及模块覆盖不从 README 反推
完整构建所需 JDK根 POM 的 Enforcer 配置与产物 Java 版本分开描述
CI 实际验证 JDK 和命令.github/workflows/*.ymlTESTING.md 解释策略，不另造矩阵
类、方法、参数和返回类型src/main/java 及构建后的公开字节码Java 示例必须编译或由测试覆盖
配置键、类型和默认值DlzDbProperties配置参考 是展示页，不是反向事实源
Spring 自动装配自动配置类、spring.factories、AutoConfiguration.imports 和集成测试不使用历史配置类名
Solon 自动装配DlzDbSolonPlugin、Solon SPI 元数据和集成测试必须同时核对 DataSource 来源
覆盖率门槛根 POM 的 JaCoCo properties不在多个文档手写门槛
测试数和实际覆盖率Surefire、JaCoCo 与 CI 产物作为 CI 产物或发行附件保存，不在仓库维护历史快照
稳定 API、SPI、internal 政策API、SPI 与实现边界这是需要人工维护的兼容性契约
AI 推荐入口、硬约束和模板DLZ-DB AI 编程速读其他 AI 文档只能引用，不复制整套规则
面向人的文档导航文档中心根 README 只保留精简入口

3. 各入口的职责​

llms.txt​

用于让 AI 快速理解项目全貌：项目定位、模块、能力边界和文档路由。它不是编程 API 参考，不应包含完整方法表、返回类型表和大段 CRUD 模板。

docs/5.AI辅助/dlz-db-速读.md​

用于 AI 编程，是唯一的 AI 代码契约。入口选择、硬约束、最小模板、危险边界和禁止生成项集中维护于此。

docs/6.参考手册​

面向需要查精确用法的人和 AI。公共 API、配置、注解选项、稳定性边界、兼容性限制和常见问题各有单一主题，不在总览页重复整章内容。

教程和框架集成​

教程可以保留完成任务所需的局部示例，但不维护完整 API 或配置清单。框架集成文档只解释各框架特有的依赖、数据源、自动装配和事务差异。

报告与历史记录​

测试数、覆盖率、代码行数和耗时属于某个具体版本与 commit。如需保存，报告必须标注日期和基线，并放在 CI 产物或发行附件中。仓库不提交历史归档目录，历史报告也不能作为当前发行结论。

4. 变更影响路由​

代码或配置变化必查文档
新增/修改业务 API6.1-公共API.md、AI 编程速读、相关使用指南
新增注解或内置 Option6.3-注解与选项.md、边界文档
新增/修改 SPI6.4-API-SPI与实现边界.md、架构指南
新增配置字段或改变默认值6.2-配置参考.md、对应框架集成
改变 JDK、模块或 CI 矩阵POM/workflow、TESTING.md、6.5-兼容性与限制.md
改变迁移不兼容点7.2-v7升级到v8.md 或下一版本迁移页
只修改 internal 实现架构/实现说明；除非行为变化，不扩散到业务教程

5. 冲突处理​

发现文档与代码不一致时：

  1. 先确认当前分支、版本和模块，不用历史文档解释新源码。
  2. 通过生产源码和测试确认真实签名与行为。
  3. 如果代码行为是缺陷，在修代码和补测试之前，不把期望行为写成现状。
  4. 先修唯一主题页，再修引用它的局部教程。
  5. 搜索旧类名、旧包名和旧方法名，区分迁移说明与错误推荐。

不要新增独立的 project-info.yml 或类似文件去复制 POM 和源码事实。后续自动化应直接读取 POM、字节码、配置类和测试结果。