unillett/variance-input

Variance 与 Medite 集成

该项目自动化并提供管理界面，用于生成传统的 Variance 发布文件。编辑可上传文本版本、生成 Medite 比对结果、管理摹本，并使用源自 _lignes 文件的分页标记组装发布资产包。具体功能包括：

• 集中管理版本、_lignes 文件、摹本和比对清单
• 自动运行 Medite 并提供基于角色的分页注入反馈
• 单一"导出"操作即可生成符合传统格式的资产包（仅包含比对结果和清单选定的摹本）

项目分为以下组件：

• Laravel – 管理界面、API、任务队列、分页服务
• Medite（Flask + Celery） – 运行对齐引擎并生成 TEI/XHTML 比对输出
• Variance web（传统 PHP） – 面向公众的查看器，用于展示管理应用准备的资产
• variance-proxy（Nginx） – 统一入口点（http://localhost:8080），可通过单个端口访问 Laravel（/admin）、传统 Variance（/）和 Medite 端点

详细文档：descr/architecture.md、descr/workflow.md、descr/facsimiles.md、descr/queues_jobs.md、descr/api_endpoints.md、descr/deployment_notes.md。

最近更新：descr/updates_2026-02-04.md。

---

快速开始

1. 克隆与启动

bash
git clone https://github.com/unil-lettres/variance-input.git
cd variance-input
docker compose up -d --build

这将启动：

• laravel（管理 Web 应用，通过代理访问 http://localhost:8080/admin）
• medite（Flask API，运行于 http://localhost:5000）
• laravel-queue（用于分页和摹本任务的队列 worker）
• 支持服务（MariaDB、Redis、Nginx 代理、传统 PHP 站点）

2. 环境配置

• 复制 laravel/example.env 到 laravel/.env，根据需要调整数据库/队列设置
• 若需 /admin/health 暴露运行中的提交 SHA，在创建/重建 laravel 和 laravel-queue 容器前设置 APP_GIT_SHA=$(git rev-parse HEAD)
• 若管理界面挂载在子路径下（例如 /admin），设置 ADMIN_BASE_PATH=admin 使生成的 URL 包含前缀
• MEDITE_STATUS_URL 控制"Medite 任务"菜单链接，默认值 /medite/（通过 variance-proxy 代理），确保本地和 staging 主机无需硬编码 localhost 即可使用
• laravel-queue 服务运行 laravel/scripts/run-queue-workers.sh，为 facsimiles 和 page-markers 队列生成多个 worker（QUEUE_WORKERS，默认 5 个）

3. 初始设置（首次运行）

bash
docker compose exec laravel php artisan migrate
docker compose exec laravel php artisan db:seed   # 可选：加载测试数据

---

日常工作流程

• 上传版本 – 在"版本"卡片中点击"上传版本"，在 storage/app/public/uploads/versions/ 下生成 TEI 容器
• 附加分页标记（_lignes） – 上传 _lignes 文本文件，队列将在 storage/app/private/pagination/{version}.json 生成描述所有分页标记的辅助文件
• 导入和管理摹本 – 批量上传图像（可选），使用"摹本"清单管理器选择每个比对对应的文件（JSON 清单与比对表格状态保持同步）
• 运行 Medite – 从"比对"卡片启动比对，Medite 将 XHTML/TEI 组件写入 storage/app/public/uploads/{author}/{work}/comparisons/{id}
• 注入分页标记 – 按角色（源/目标）点击"注入分页"，将 _lignes 标记合并到 Medite XHTML 文件中
• 导出传统资产包 – 点击"导出"下载包含已发布比对文件夹和 JSON 清单引用的摹本（源/目标）的 zip 文件
• 发布（可选） – 通过"发布"开关保持比对与传统公共目录同步

---

常用命令

---

项目结构（简版）

├── docker-compose.yml
├── descr/                    # 开发者文档
├── laravel/                  # 管理应用（PHP/Laravel）
│   ├── app/
│   ├── routes/
│   └── ...
├── medite/                   # Flask + Celery Medite 运行器
│   └── app/variance/...
├── variance/                 # 传统 PHP 前端（开发环境下只读）
└── variance_data/            # 运行时上传文件和生成输出

---

完整流程

1. 上传版本（"版本"卡片）

• 接受 .txt 文件（≤ 8 MB，text/plain）
• 可选提示：original_encoding（UTF‑8 / Windows‑1252 / ISO‑8859‑1）
• VersionController::store 将原始 TXT 写入 storage/app/public/uploads/versions/{base}.txt，标准化文本（UTF‑8 LF，空白折叠），保留内嵌 <pb> 标签，插入 <lb/>，并将 TEI 保存到 storage/app/public/uploads/versions/{base}.xml
• 应用从 storage/app/public/uploads/versions 读取 TEI，若不存在则回退到 public/uploads/versions 或 variance/uploads/versions（传统/导入数据）
• 创建包含生成文件夹 slug 的 versions 记录

2. 上传 _lignes 文件

• 原始文件保存到 storage/app/private/lignes/{version_id}.txt
• ApplyLignesJob 解析 _lignes 条目，与 TEI 文本匹配，并在 storage/app/private/pagination/{version_id}.json 存储分页辅助 JSON，包含 { char_index, page, image_code, phrase, context }
• 版本级进度跟踪保存在 storage/app/tmp/pager/{version_id}.json，供 UI 显示辅助文件就绪状态
• _lignes 上传限制为 4 MB
• 若 TEI 已包含 <pb> 标签，可使用 POST /api/versions/{version}/pagination/from-pb 直接构建辅助文件

3. 管理摹本和清单

• 通过摹本轮播批量上传图像；任务将标准化原始图像（img_*）并生成缩略图
• 清单管理器列出所有比对（源/目标），选择比对时高亮当前 JSON 清单中已发布的图像
• 变更写入 storage/app/public/uploads/{author}/{work}/{version}/images_{role}_{author--work--comparison}.json，并立即反映在比对表格（"JSON"状态）中

4. 运行 Medite

• 从比对表格启动，MediteController::runMedite 调用 Flask 服务执行 Celery 任务
• Medite 将 TEI 差异 + XHTML 组件写入 /app/uploads/{author}/{work}/comparisons/{comparison_id}，Laravel 将其镜像到 storage/app/public/uploads/{author}/{work}/comparisons/{id}
• 比对元数据存储/更新到数据库

5. 注入分页标记

• 点击"注入分页"，ComparisonController::applyPageMarkers 确保两个版本都有辅助文件，标记比对为排队状态，并调度 InjectComparisonPaginationJob
• 任务加载 storage/app/private/pagination/{version}.json，在记录的偏移位置将 <span class="page-marker"> 标签注入 source.xhtml / target.xhtml，并保存更新后的文件
• 比对范围进度写入 storage/app/tmp/pager/comparisons/{comparison_id}.json；UI 轮询此端点显示每个角色（源/目标）的状态（排队→运行中→完成）
• 可选：POST /api/comparisons/{comparison}/pagination/from-xhtml 可从 source.xhtml / target.xhtml 中已有的 <pb> 标签重建辅助文件

6. 导出传统资产包

• "导出"生成包含已发布比对目录的 zip 文件，每个角色仅包含 JSON 清单引用的摹本图像（及清单本身）

7. 可选发布

• 使用"发布"按钮将比对制品复制到 storage/app/public/uploads/{author}/{work}/{comparison_folder}，并镜像到 variance/uploads/{author}/{work}/{comparison_folder} 供传统站点使用

后台任务

• 分页任务（ApplyLignesJob、InjectComparisonPaginationJob）在 page-markers 队列运行；摹本处理使用 facsimiles 队列
• laravel-queue 容器运行 laravel/scripts/run-queue-workers.sh，为 facsimiles,page-markers 生成多个 queue:work 进程
• 手动执行：docker compose exec laravel php artisan queue:work --queue=page-markers --stop-when-empty

健康状态（顶部横幅点）

• 正常（绿色）：系统健康
• 降级（橙色）：警告级问题；应用仍可用。例如：磁盘空间低于警告阈值但高于临界值、队列积压但无硬故障、调度器心跳过期
• 故障（红色）：严重影响功能的问题。例如：数据库不可用、Medite 健康检查失败、达到临界磁盘空间

可配置健康阈值：

• HEALTHCHECK_DISK_WARN_GB（默认 10）
• HEALTHCHECK_DISK_CRIT_GB（默认 5）
• HEALTHCHECK_MEDITE_WARN_MS（默认 2500）
• HEALTHCHECK_FAILED_JOBS_WARN（默认 1）
• HEALTHCHECK_FAILED_JOBS_CRIT（默认 10）

制品速查表

---

内部结构

深入了解可查看：

• laravel/app/Services/PageMarkerService.php
• laravel/app/Jobs/ApplyLignesJob.php
• laravel/app/Jobs/InjectComparisonPaginationJob.php
• medite/app/flask_app.py

所有权与许可

Variance 与 Medite 集成由SIER（教学与研究基础设施服务） 开发，隶属于洛桑大学文学院（<[***]>）。许可目前正在内部审核中；本仓库为私有，现阶段不授予任何再分发权利。

祝您比对愉快！ :)