文档维护与验证约定

归属与版本

Core 文档维护框架契约、接入方式和源码参考；数据库设计与业务错误码登记归 design/standards，业务规则归对应业务域，启动器环境归应用项目，前端工程规范归前端仓库。

规范只有一个正文，AI、教程和反模式引用它。新专题在总索引登记，明确适用版本、源码依据和验证范围。当前文档基线为 3.0.0-SNAPSHOT，最近系统核验为 2026-09-19；变化频繁的能力另记验证日期。

何时更新

修改公共接口/泛型、生命周期、配置项、依赖矩阵、权限租户语义、返回/异常或样例命令时，同一变更复核对应专题与示例。纯内部重构且行为不变，不机械更新所有文档日期。

新文件先加入总索引；迁移旧文件时更新入链，可保留简短过渡页，不能保留两套互相冲突的规范正文。历史执行记录应注明历史版本，不作为新模块必读规范。

本地检查

python3 scripts/check-docs.py
python3 scripts/check-docs.py --workspace

检查器需要 Python 3.9 或更新版本。默认检查本仓 Markdown 的内联文件链接、可解析的标题锚点、总索引覆盖、代码围栏、机器专用路径及常见凭据模式；对缺少外部仓库的链接计数提示跳过。--workspace 要求外部目标也存在。普通输出只报告问题位置和类型。

检查器不访问 HTTP(S) 链接，不解析图片或引用式链接，也不能识别“文件仍存在但规范已经废弃”的语义；这些情况需要人工核对。--json 包含链接目标供审查，分享报告前应检查目标是否包含不宜公开的信息。

它不能证明 Java 示例编译、API 真实返回、复杂权限或事务语义。代码示例优先链接到可编译源码；变更相关行为时执行测试规范的相应层级。

事实核验流程

1. 对照 POM 确认依赖/模块；对照源码确认类型、签名、默认值与条件。
2. 区分规范要求、当前实现、设计建议和执行证据。
3. 对命令核对工作目录、工具链、目标模块和测试选择；运行结果记录用例数量。
4. 明确环境依赖与未执行项，不通过编造地址、配置或结果填补缺口。
5. 保留既有用户修改，只提交本次改动；代码与文档冲突时先查证原因。

两类读者的持续验收

AI 试用任务：新建小模块、修改查询、增加事务动作。记录自造接口、遗漏目标栈、租户/权限遗漏和需要人工补充的规则。

开发人员试用任务：依教程启动，新增字段/查询/动作并说明各层职责和回滚语义。由未参与框架实现的人记录卡点。人工试用结果需要真实参与者，不能由作者自评冒充完成。

自动检查和作者核验已经执行的范围见验证记录。