4Set-Server/user_guide_conflicts.html at master · herman925/4Set-Server · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>User Guide: Handling Conflicts - 4Set System</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script src="assets/js/tailwind.config.js"></script>
  <link rel="stylesheet" href="assets/css/theme_pantone_light_1.css">
  <link rel="stylesheet" href="assets/css/global.css">
  <link rel="stylesheet" href="assets/css/user-guides.css">
  <link rel="icon" type="image/x-icon" href="assets/favicon.ico">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono&display=swap" rel="stylesheet">
  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
  <script src="assets/js/smart-navigation.js"></script>
  <style>
    body {
      font-family: 'Inter', sans-serif;
      background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
    }
  </style>
</head>
<body class="min-h-screen">
  <header class="bg-white shadow-md sticky top-0 z-50">
    <div class="container mx-auto px-6 py-4">
      <div class="flex items-center justify-between">
        <div class="flex items-center gap-4">
          <a href="index.html" class="text-2xl font-bold" style="color: var(--primary)">4Set System</a>
          <span class="text-gray-400">|</span>
          <h1 class="text-xl font-semibold text-gray-700">User Guide: Handling Data Conflicts</h1>
        </div>
        <div class="flex items-center gap-3">
          <a href="quick_start_guide.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Quick Start Guide">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="M12 20V10"></path>
              <path d="M18 20V4"></path>
              <path d="M6 20v-4"></path>
            </svg>
          </a>
          <a href="user_guide_uploader.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Assessment Uploader Guide">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"></path>
              <polyline points="17 8 12 3 7 8"></polyline>
              <line x1="12" y1="3" x2="12" y2="15"></line>
            </svg>
          </a>
          <a href="user_guide_checking_system.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Checking System Guide">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <polyline points="9 11 12 14 22 4"></polyline>
              <path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"></path>
            </svg>
          </a>
          <a href="user_guide_processor_setup.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Processor Agent Setup Guide">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
              <circle cx="12" cy="12" r="3"></circle>
              <path d="M12 1v6m0 6v6"></path>
              <path d="m4.93 4.93 4.24 4.24m5.66 5.66 4.24 4.24"></path>
              <path d="m1 12 6 0m6 0 6 0"></path>
              <path d="m4.93 19.07 4.24-4.24m5.66-5.66 4.24-4.24"></path>
            </svg>
          </a>
          <a href="guide_homepage.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Back to Guide Homepage">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"></path>
              <path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"></path>
            </svg>
          </a>
          <a href="index.html" class="text-gray-600 hover:text-primary transition p-2 rounded-lg hover:bg-gray-100" title="Back to System Home">
            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
              <path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path>
              <polyline points="9 22 9 12 15 12 15 22"></polyline>
            </svg>
          </a>
        </div>
      </div>
    </div>
  </header>

  <div class="container mx-auto px-6 py-8">
    <div class="flex gap-8">
      <aside class="sidebar w-64 flex-shrink-0">
        <div class="bg-white rounded-lg shadow-lg p-6">
          <h2 class="text-lg font-bold mb-4" style="color: var(--primary)">Table of Contents</h2>
          <nav class="space-y-2">
            <a href="#overview" class="toc-link block text-sm text-gray-700 py-1">1. Overview</a>
            <a href="#conflict-detection" class="toc-link block text-sm text-gray-700 py-1">2. Conflict Detection</a>
            <a href="#handling" class="toc-link block text-sm text-gray-700 py-1">3. Handling Conflicts</a>
            <a href="#scenarios" class="toc-link block text-sm text-gray-700 py-1">4. Common Scenarios</a>
            <a href="#best-practices" class="toc-link block text-sm text-gray-700 py-1">5. Best Practices</a>
          </nav>
        </div>
      </aside>

      <main class="flex-1 max-w-4xl">
        <div class="bg-white rounded-lg shadow-lg p-8 mb-8">
          <div class="mb-8 pb-6 border-b border-gray-200">
            <div class="flex flex-wrap gap-4 text-sm text-gray-600">
              <div><strong>Version:</strong> 1.0</div>
              <div><strong>Last Updated:</strong> October 25, 2025</div>
              <div><strong>Target Audience:</strong> System Operators, Data Administrators</div>
            </div>
          </div>

          <section id="overview" class="content-section mb-12">
            <h2 class="text-3xl font-bold mb-6" style="color: var(--primary)">
              <span class="step-number">1</span>
              Overview
            </h2>

            <!-- Source Note -->
            <div class="mb-6 p-4 bg-blue-50 border-l-4 border-blue-500 rounded">
              <p class="text-sm text-gray-700">
                📄 <strong>Markdown Source:</strong> This guide is also available in markdown format at
                <a href="PRDs/data_conflicts_user_guide_prd.md" class="text-blue-600 hover:underline font-mono">PRDs/data_conflicts_user_guide_prd.md</a>
              </p>
            </div>

            <p class="text-gray-700 mb-6 text-lg leading-relaxed">
              The 4Set Processor Agent includes <strong>Data Overwrite Protection</strong> to prevent accidental corruption of existing assessment data. This feature can be <strong>enabled or disabled</strong> by administrators based on their workflow preferences.
            </p>

            <!-- Configuration Notice -->
            <div class="diagram-box bg-blue-50 border-blue-300 mb-6">
              <h4 class="font-semibold mb-3">⚙️ Configuration Option</h4>
              <p class="text-sm text-gray-700 mb-2">
                Data Overwrite Protection is <strong>optional and configurable</strong> via <code>config/agent.json</code>:
              </p>
              <pre class="bg-gray-800 text-green-400 p-3 rounded text-xs overflow-x-auto">{
  "dataProtection": {
    "enableDataOverwriteProtection": true  // Set to false to disable
  }
}</pre>
              <ul class="space-y-2 text-sm text-gray-700 mt-3">
                <li>• <strong>When ENABLED (default):</strong> Protects against accidental data overwrites (as described below)</li>
                <li>• <strong>When DISABLED:</strong> Allows full data overwrites during processor agent uploads to JotForm</li>
                <li>• This setting applies to processor agent uploads only - file validation workflow is preserved regardless</li>
              </ul>
            </div>

            <h3 class="text-2xl font-semibold mb-4">What Gets Protected? (When Protection is Enabled)</h3>

            <div class="grid md:grid-cols-2 gap-6">
              <div class="diagram-box bg-green-50 border-green-300">
                <h4 class="font-semibold mb-3">✅ Protected Fields</h4>
                <p class="text-sm text-gray-700 mb-2">Cannot Overwrite:</p>
                <ul class="space-y-1 text-sm text-gray-700">
                  <li>• All assessment answers</li>
                  <li>• Demographic data (if filled)</li>
                  <li>• Any non-administrative field with data</li>
                </ul>
              </div>

              <div class="diagram-box bg-yellow-50 border-yellow-300">
                <h4 class="font-semibold mb-3">❌ Exception Fields</h4>
                <p class="text-sm text-gray-700 mb-2">Can Overwrite:</p>
                <ul class="space-y-1 text-sm text-gray-700">
                  <li>• student-id</li>
                  <li>• child-name</li>
                  <li>• school-id, district</li>
                  <li>• class-id, class-name</li>
                  <li>• computerno</li>
                </ul>
              </div>
            </div>
          </section>

          <section id="conflict-detection" class="content-section mb-12">
            <h2 class="text-3xl font-bold mb-6" style="color: var(--primary)">
              <span class="step-number">2</span>
              Conflict Detection (When Protection is Enabled)
            </h2>

            <div class="diagram-box bg-yellow-50 border-yellow-300 mb-4">
              <p class="text-sm text-gray-700">
                ⚠️ <strong>Note:</strong> This section applies only when <code>enableDataOverwriteProtection</code> is set to <code>true</code> in the configuration. When disabled, conflict detection is skipped and all fields can be overwritten.
              </p>
            </div>

            <h3 class="text-2xl font-semibold mb-4">What Triggers a Conflict?</h3>

            <div class="diagram-box">
              <p class="text-gray-700 mb-3">A conflict is detected when:</p>
              <ol class="list-decimal ml-6 space-y-2 text-gray-700">
                <li>✅ An existing submission already exists (same sessionkey)</li>
                <li>✅ A protected field has a non-empty value in JotForm</li>
                <li>✅ The new PDF has a <strong>different</strong> non-empty value</li>
                <li>✅ The field is <strong>not</strong> in the exception list</li>
              </ol>
            </div>

            <h3 class="text-2xl font-semibold mb-4 mt-6">What Does NOT Trigger a Conflict?</h3>

            <div class="grid md:grid-cols-2 gap-4">
              <div class="diagram-box bg-gray-50 border-gray-300">
                <ul class="space-y-2 text-sm text-gray-700">
                  <li>❌ Inserting data into blank fields</li>
                  <li>❌ Same value (no change)</li>
                </ul>
              </div>
              <div class="diagram-box bg-gray-50 border-gray-300">
                <ul class="space-y-2 text-sm text-gray-700">
                  <li>❌ Null/empty new value</li>
                  <li>❌ Exception fields (admin data)</li>
                </ul>
              </div>
            </div>
          </section>

          <section id="handling" class="content-section mb-12">
            <h2 class="text-3xl font-bold mb-6" style="color: var(--primary)">
              <span class="step-number">3</span>
              Handling Conflicts
            </h2>

            <div class="space-y-6">
              <div class="diagram-box bg-blue-50 border-blue-300">
                <h3 class="text-xl font-semibold mb-4">Step 1: Identify Conflicted Files</h3>
                <p class="text-gray-700 mb-3">Conflicted files are automatically moved to the <code>Unsorted/</code> folder:</p>
                <pre class="text-xs">OneDrive/
└── 97 - Project RAW Data/
    └── PDF Form Data/
        └── Unsorted/
            ├── 12345_20250101_10_30.pdf
            └── 12345_20250101_10_30.json</pre>
              </div>

              <div class="diagram-box bg-purple-50 border-purple-300">
                <h3 class="text-xl font-semibold mb-4">Step 2: Review the Log</h3>
                <ol class="list-decimal ml-6 space-y-2 text-gray-700 text-sm">
                  <li>Open daily log: <code>logs/YYYYMMDD_processing_agent.csv</code></li>
                  <li>Search for <code>DATA_OVERWRITE_DIFF</code> entries</li>
                  <li>Review conflict details</li>
                </ol>
                <div class="bg-white rounded p-3 mt-3">
                  <p class="text-xs font-mono text-gray-700">Example: "ERV_Q1 (QID 30): existing='A' → new='B'"</p>
                </div>
              </div>

              <div class="diagram-box bg-green-50 border-green-300">
                <h3 class="text-xl font-semibold mb-4">Step 3: Investigate the Cause</h3>
                <p class="text-gray-700 mb-2">Ask yourself:</p>
                <ul class="list-disc ml-6 space-y-1 text-gray-700 text-sm">
                  <li>Is this a re-upload?</li>
                  <li>Is the existing data correct?</li>
                  <li>Is the new data correct?</li>
                  <li>Was there an administrative error?</li>
                </ul>
              </div>

              <div class="diagram-box bg-yellow-50 border-yellow-300">
                <h3 class="text-xl font-semibold mb-4">Step 4: Resolve the Conflict</h3>

                <div class="collapsible-section">
                  <div class="collapsible-header">
                    <h4 class="font-semibold">Option A: Keep Existing Data</h4>
                    <span class="text-xl">▼</span>
                  </div>
                  <div class="collapsible-content">
                    <p class="text-sm text-gray-700 mb-2">If the existing data is correct:</p>
                    <ol class="list-decimal ml-6 space-y-1 text-sm text-gray-700">
                      <li>Archive the conflicted PDF (move to backup folder)</li>
                      <li>Delete the JSON file from Unsorted/</li>
                      <li>No further action needed</li>
                    </ol>
                  </div>
                </div>

                <div class="collapsible-section">
                  <div class="collapsible-header">
                    <h4 class="font-semibold">Option B: Manually Update JotForm</h4>
                    <span class="text-xl">▼</span>
                  </div>
                  <div class="collapsible-content">
                    <p class="text-sm text-gray-700 mb-2">If the new data is correct:</p>
                    <ol class="list-decimal ml-6 space-y-1 text-sm text-gray-700">
                      <li>Log into JotForm</li>
                      <li>Search for the submission by sessionkey</li>
                      <li>Manually edit the submission</li>
                      <li>Document the change</li>
                      <li>Archive PDF and JSON from Unsorted/</li>
                    </ol>
                  </div>
                </div>

                <div class="collapsible-section">
                  <div class="collapsible-header">
                    <h4 class="font-semibold">Option C: Delete and Re-Upload</h4>
                    <span class="text-xl">▼</span>
                  </div>
                  <div class="collapsible-content">
                    <div class="alert-box alert-warning mb-3">
                      <strong>⚠️ Warning:</strong> Permanently deletes original data. Use only if certain.
                    </div>
                    <ol class="list-decimal ml-6 space-y-1 text-sm text-gray-700">
                      <li>Log into JotForm</li>
                      <li>Find and DELETE the existing submission</li>
                      <li>Move the PDF back to <code>incoming/</code></li>
                      <li>Agent will process as new submission</li>
                    </ol>
                  </div>
                </div>
              </div>
            </div>
          </section>

          <section id="scenarios" class="content-section mb-12">
            <h2 class="text-3xl font-bold mb-6" style="color: var(--primary)">
              <span class="step-number">4</span>
              Common Scenarios
            </h2>

            <div class="space-y-4">
              <div class="collapsible-section">
                <div class="collapsible-header">
                  <h3 class="text-lg font-semibold">Scenario 1: Legitimate Re-Assessment</h3>
                  <span class="text-xl">▼</span>
                </div>
                <div class="collapsible-content">
                  <p class="text-gray-700 mb-2"><strong>Situation:</strong> Student took assessment again with different answers</p>
                  <p class="text-gray-700 mb-3"><strong>Resolution:</strong></p>
                  <ul class="list-disc ml-6 space-y-1 text-gray-700">
                    <li>If first assessment valid → Keep existing (Option A)</li>
                    <li>If second should replace → Delete old and re-upload (Option C)</li>
                    <li>Document which assessment was kept</li>
                  </ul>
                </div>
              </div>

              <div class="collapsible-section">
                <div class="collapsible-header">
                  <h3 class="text-lg font-semibold">Scenario 2: Wrong Student ID</h3>
                  <span class="text-xl">▼</span>
                </div>
                <div class="collapsible-content">
                  <p class="text-gray-700 mb-2"><strong>Situation:</strong> PDF has wrong student ID</p>
                  <p class="text-gray-700 mb-3"><strong>Resolution:</strong></p>
                  <ol class="list-decimal ml-6 space-y-1 text-gray-700">
                    <li>Correct the student ID in the PDF filename</li>
                    <li>Re-scan with correct ID</li>
                    <li>Upload the corrected PDF</li>
                    <li>Archive incorrect PDF from Unsorted/</li>
                  </ol>
                </div>
              </div>

              <div class="collapsible-section">
                <div class="collapsible-header">
                  <h3 class="text-lg font-semibold">Scenario 3: Data Entry Correction</h3>
                  <span class="text-xl">▼</span>
                </div>
                <div class="collapsible-content">
                  <p class="text-gray-700 mb-2"><strong>Situation:</strong> Field marked incorrectly during assessment</p>
                  <p class="text-gray-700 mb-3"><strong>Resolution:</strong></p>
                  <ul class="list-disc ml-6 space-y-1 text-gray-700">
                    <li>If 1-2 fields → Option B (manual JotForm edit)</li>
                    <li>If many fields → Option C (delete and re-upload)</li>
                    <li>Document the correction in operator log</li>
                  </ul>
                </div>
              </div>
            </div>
          </section>

          <section id="best-practices" class="content-section mb-12">
            <h2 class="text-3xl font-bold mb-6" style="color: var(--primary)">
              <span class="step-number">5</span>
              Best Practices
            </h2>

            <div class="grid md:grid-cols-2 gap-6">
              <div class="diagram-box bg-green-50 border-green-300">
                <h3 class="text-lg font-semibold mb-3">✅ DO:</h3>
                <ul class="space-y-2 text-sm text-gray-700">
                  <li>• Review logs daily for conflicts</li>
                  <li>• Investigate each conflict before action</li>
                  <li>• Document all manual changes</li>
                  <li>• Keep backups of conflicted PDFs</li>
                  <li>• Communicate with administrators</li>
                </ul>
              </div>

              <div class="diagram-box bg-red-50 border-red-300">
                <h3 class="text-lg font-semibold mb-3">❌ DON'T:</h3>
                <ul class="space-y-2 text-sm text-gray-700">
                  <li>• Blindly delete submissions</li>
                  <li>• Ignore conflicts</li>
                  <li>• Disable protection</li>
                  <li>• Re-upload same PDF repeatedly</li>
                </ul>
              </div>
            </div>

            <div class="diagram-box bg-blue-50 border-blue-300 mt-6">
              <h3 class="text-lg font-semibold mb-3">🔍 Prevention Tips</h3>
              <ul class="space-y-2 text-sm text-gray-700">
                <li>✓ <strong>Unique session keys:</strong> Never reuse student ID + date + time</li>
                <li>✓ <strong>Quality control:</strong> Verify PDFs before uploading</li>
                <li>✓ <strong>Training:</strong> Ensure operators understand workflow</li>
                <li>✓ <strong>Communication:</strong> Coordinate with other operators</li>
              </ul>
            </div>
          </section>
        </div>

        <footer class="text-center text-gray-600 text-sm py-8">
          <p><strong>4Set System</strong> - KeySteps@JC (Phase Two)</p>
          <p class="mt-2">The Education University of Hong Kong | Version 1.0 | October 2025</p>
        </footer>
      </main>
    </div>
  </div>

  <script src="assets/js/user-guides.js"></script>
  <script>
    document.addEventListener('DOMContentLoaded', () => {
      setTimeout(() => {
        document.querySelectorAll('.collapsible-header span:last-child').forEach(arrow => {
          const content = arrow.closest('.collapsible-header').nextElementSibling;
          arrow.textContent = content.classList.contains('active') ? '▲' : '▼';
          arrow.classList.add('arrow');
        });
      }, 100);
    });
  </script>
</body>
</html>