文档站本地完成报告

日期：2026-10-29。用户选择先交付本地站点与发布包。本地入口 http://127.0.0.1:8089；最终可重建产物位于 infra/.build/docs-site。本报告只覆盖文档站，不把本地结果等同 GitLab Pages 上线。

任务完成

任务	交付与验证	状态
T001—T003	来源白名单、17 项精确依赖与官方分发散列、5 项边界测试	通过
T004—T007	首页、指南、MkDocs 薄适配与内置搜索，严格构建	通过
T008—T010	nginx、多阶段镜像、独立 Docker Compose；101:101、只读、healthy	通过
T011	CI 模板本地语法与默认分支发布规则检查	通过；远端未运行
T012	真实浏览器导航、检索、契约下载和子路径	通过
T013—T014	运行指南、四表报告、路线图与最终产物检查	以 tasks.md 和本地证据为完成门禁

Spec 符合度

需求/验收	结果	证据
FR-001/002，SC-001/002	首页分类、规范/ADR/指南可读，中文“权限”标题返回结果	browser-verification.json
FR-003/004，SC-003/004	白名单来源；未发布引用转成明确说明；严格构建与全部静态链接检查	publication.json、5 项单测
FR-005，SC-005	独立静态服务无数据库依赖；浏览器业务 API/外部资源请求均为零	compose.docs.yaml、浏览器证据
FR-006，SC-006/007	两次相同来源清单一致，归档全部文件 SHA-256 通过；根和 /project/docs/ 访问通过	final-verification.json、浏览器证据
FR-007，SC-008	CI 发布仅默认分支；接入步骤和未验证条件已列明	quickstart.md、CI 模板

宪法符合度

原则	核实结果	依据
范围红线	仅路线图已有文档站，不实现实验业务	docs-site-spec-001.md
框架优先	复用已批准 MkDocs 与内置主题/search；无新主题/插件	ADR-005、requirements.lock
分层与唯一权威	文档在 docs，工具在 infra；临时副本生成，源路径保留	publication.json、build.py
简单与中文	沿用框架；配置使用内置 CJK 分词和标题索引，页面正文中文	mkdocs.yml、guide.md
真实性	不读取旧仓库、不声称 Pages、DNS/TLS 或公网交付	quickstart.md

测试覆盖

检查	实际结果	限制
单元边界	5/5，通过：来源、缺失、越界/符号链接、静态链接/归档、404 基路径	仅文档构建器
静态构建	MkDocs strict、全部 HTML 本地资源与链接、归档文件清单/散列通过	不逐条请求外部链接，避免读取禁止的仓库
真实浏览器	4 组检查通过；规范/ADR/指南、中文标题、OpenAPI、子路径；错误/失败/外部资源/业务请求均为零	标题关键词检索，不承诺中文整句语义搜索
Docker	独立 8089 服务 healthy，非 root、只读；原有 8 个容器仍 healthy	本地单机预览
文档一致性	原批准快照、相对引用、任务依赖与契约检查通过	不替代远端 CI

实现过程中修复了内置 zh 在纯浏览器中缺少 jieba、数字章节锚点导致主题脚本错误、默认高亮引入 CDN 三项兼容问题；最终检查均使用修正后的配置。下载中断通过复用本机完整官方缓存恢复，未绕过锁文件和散列核验。

机器可读证据位于本地 evidence/browser-verification.json、evidence/final-verification.json；它们和截图不进入发布包。后续仍需新建远端、发布可信构建器镜像、接入 CI/Pages 与验证访问控制，随后才处理 lab-edu.team 的 DNS/TLS。