deploy rater (Docker/FastAPI): registration + completeness gate + /api/submit → dataset

static/mobile.html

@@ -294,6 +294,7 @@
 <header class="top" id="topBar">
   <button class="icon" id="drawerBtn" title="Cases">☰</button>
   <span class="title" id="topTitle">Video user study</span>
+  <button class="icon" id="helpBtn" title="How to rate" style="font-size:18px">?</button>
   <span class="pill" id="syncPill" data-state="idle">●</span>
   <select id="langSelect" title="Language"></select>
 </header>
@@ -333,6 +334,20 @@
   </div>
 </aside>
 
+<!-- Rating instructions overlay (mobile) — toggled via the "?" header button.
+     Auto-opened on first launch; user can close + reopen any time. -->
+<div id="helpOverlay" class="overlay hidden" role="dialog" aria-modal="true">
+  <div class="reg-card" style="max-width:520px">
+    <div class="top-row">
+      <h2 id="helpHeader">How to rate</h2>
+      <button class="btn" id="helpCloseBtn"
+              style="background:transparent;border:none;color:var(--fg);font-size:22px;cursor:pointer">✕</button>
+    </div>
+    <div id="helpBody" style="font-size:13px;line-height:1.6;color:var(--fg);max-height:60vh;overflow-y:auto"></div>
+    <button class="go-btn" id="helpDismissBtn" style="margin-top:14px"><span id="helpDismissText">Got it</span></button>
+  </div>
+</div>
+
 <!-- Registration overlay -->
 <div id="loginOverlay" class="overlay" role="dialog" aria-modal="true">
   <div class="reg-card">
@@ -455,6 +470,9 @@ const STRINGS = {
     reg_email:"Email", reg_email_ph:"e.g. alex@example.com",
     reg_note:"Affiliation / notes (optional)", reg_note_ph:"e.g. INSAIT, internal pilot, etc.",
     reg_continue:"Continue →",
+    help_title:"How to rate",
+    help_dismiss:"Got it",
+    help_body_html:"<p>For each case watch all videos via the <b>A / B / C</b> tabs at the top, then rate each one on every sub-question below. Slot order is shuffled per rater but stable within a case.</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>Likert (1 = worst, 5 = best)</h4><p>1 Very poor · 2 Poor · 3 Fair · 4 Good · 5 Excellent</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>3 dimensions × 9 sub-questions</h4><ul style='padding-left:18px;margin:6px 0'><li><b>Instruction following</b> — re-read the prompt, especially the red-highlighted phrases.</li><li><b>Temporal consistency</b> — focus on how characters, objects, and environment change across frames.</li><li><b>Realism</b> — notice obvious out-of-place / unnatural moments.</li></ul><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>Tips</h4><ul style='padding-left:18px;margin:6px 0'><li><b>Click 💾 to save progress at any time.</b> Click <b>Submit study</b> once everything is rated — otherwise your scores don't count.</li><li>For BGM / subtitle / sound questions, unmute the video first.</li><li>Score motion logic / camera low if the video has little to no movement.</li></ul>",
     reg_foot:"Submissions are written to the <code>dehezhang2/Frameworker_User_Study</code> dataset on Hugging Face.",
     reg_err_name:"Please enter your name.",
     reg_err_email:"Please enter a valid email address.",
@@ -494,6 +512,9 @@ const STRINGS = {
     reg_email:"邮箱", reg_email_ph:"例如:xiaoming@example.com",
     reg_note:"所属单位 / 备注(可选)", reg_note_ph:"例如:INSAIT、内部预测试 等",
     reg_continue:"继续 →",
+    help_title:"评分说明",
+    help_dismiss:"知道了",
+    help_body_html:"<p>每个案例,先在顶部的 <b>A / B / C</b> 视频标签切换观看每个视频,然后在下方对每个视频的每个子问题打分。视频顺序按评分人随机分配,但同一案例内保持一致。</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>李克特量表(1 = 最差,5 = 最佳)</h4><p>1 很差 · 2 差 · 3 一般 · 4 好 · 5 极佳</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>3 个维度 × 9 个子问题</h4><ul style='padding-left:18px;margin:6px 0'><li><b>指令遵循</b> — 请先看清提示词,尤其是标红的部分。</li><li><b>时间一致性</b> — 关注人物、物品和环境在帧间的变化。</li><li><b>真实感</b> — 留意视频中不和谐或有明显问题的地方。</li></ul><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>操作提示</h4><ul style='padding-left:18px;margin:6px 0'><li><b>随时点击 💾 保存进度;</b>全部完成后必须点击「提交研究」,否则评分不会被计入。</li><li>BGM / 字幕 / 配乐 等问题请先打开视频声音聆听。</li><li>运动逻辑 / 相机运动 若几乎没有运动,请打低分。</li></ul>",
     reg_foot:"提交将写入 Hugging Face 上的 <code>dehezhang2/Frameworker_User_Study</code> 数据集。",
     reg_err_name:"请输入您的姓名。",
     reg_err_email:"请输入有效的邮箱地址。",
@@ -533,6 +554,9 @@ const STRINGS = {
     reg_email:"Имейл", reg_email_ph:"напр. alex@example.com",
     reg_note:"Принадлежност / бележки (по избор)", reg_note_ph:"напр. INSAIT, вътрешен пилот",
     reg_continue:"Продължи →",
+    help_title:"Как се оценява",
+    help_dismiss:"Разбрах",
+    help_body_html:"<p>За всеки случай гледайте всички видеа чрез табовете <b>A / B / C</b> отгоре, след това оценете всяко по всеки под-въпрос отдолу.</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>Ликерт (1 = най-лошо, 5 = най-добро)</h4><p>1 Много слабо · 2 Слабо · 3 Средно · 4 Добро · 5 Отлично</p><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>3 измерения × 9 под-въпроса</h4><ul style='padding-left:18px;margin:6px 0'><li><b>Следване на инструкции</b> — прочетете подканата, особено маркираните в червено фрази.</li><li><b>Времева съгласуваност</b> — съсредоточете се върху промените на хора, обекти и среда между кадрите.</li><li><b>Реализъм</b> — забележете неестествени моменти.</li></ul><h4 style='color:var(--accent);margin-top:14px;font-size:13px'>Съвети</h4><ul style='padding-left:18px;margin:6px 0'><li><b>Щракнете 💾, за да запазите прогрес по всяко време;</b> щракнете <b>Изпрати проучването</b> накрая — иначе оценките не се броят.</li><li>За въпроси относно BGM / субтитри / звук включете звука първо.</li><li>Дайте нисък резултат за логика на движението / камера, ако има малко движение.</li></ul>",
     reg_foot:"Изпращанията се записват в <code>dehezhang2/Frameworker_User_Study</code> на Hugging Face.",
     reg_err_name:"Моля, въведете името си.",
     reg_err_email:"Моля, въведете валиден имейл адрес.",
@@ -1292,6 +1316,25 @@ function openRegister(){
   applyRegistrationI18n();
 }
 function closeRegister(){ document.getElementById("loginOverlay").classList.add("hidden"); }
+
+/* ----- help / 评分说明 overlay (mobile only) ----- */
+const HELP_SEEN_KEY = "user_study_help_seen_v1";
+function openHelp(){
+  applyHelpI18n();
+  document.getElementById("helpOverlay").classList.remove("hidden");
+}
+function closeHelp(){
+  document.getElementById("helpOverlay").classList.add("hidden");
+  try { localStorage.setItem(HELP_SEEN_KEY, "1"); } catch(e){}
+}
+function applyHelpI18n(){
+  const h = document.getElementById("helpHeader");
+  if (h) h.textContent = t("help_title");
+  const body = document.getElementById("helpBody");
+  if (body) body.innerHTML = t("help_body_html");
+  const btn = document.getElementById("helpDismissText");
+  if (btn) btn.textContent = t("help_dismiss");
+}
 function applyRegistrationI18n(){
   document.getElementById("regHeader").textContent = t("reg_title");
   document.getElementById("regLead").textContent = t("reg_lead");
@@ -1398,6 +1441,9 @@ function hideSubmittedOverlay(){ document.getElementById("submittedOverlay").cla
 
   // wire DOM events
   document.getElementById("drawerBtn").onclick = openDrawer;
+  document.getElementById("helpBtn").onclick = openHelp;
+  document.getElementById("helpCloseBtn").onclick = closeHelp;
+  document.getElementById("helpDismissBtn").onclick = closeHelp;
   document.getElementById("drawerCloseBtn").onclick = closeDrawer;
   document.getElementById("drawerBackdrop").onclick = closeDrawer;
   document.getElementById("prevBtn").onclick = () => step(-1);
@@ -1431,6 +1477,11 @@ function hideSubmittedOverlay(){ document.getElementById("submittedOverlay").cla
     renderShell();
     closeRegister();
     probeSync();
+    // Auto-open the rubric popup once per device. The user can manually
+    // reopen it any time via the "?" header button.
+    try {
+      if (localStorage.getItem(HELP_SEEN_KEY) !== "1") openHelp();
+    } catch (e) {}
   }
   // Always fetch admin-curated highlights; available even before registration
   // gate clears so the prompt shows highlights as soon as the rater enters.