stage 1

sql/schema.sql

@@ -1,7 +1,15 @@
+-- This schema supports the phase-1 hybrid proof of concept.
+-- The database stores centrally managed configuration only: templates,
+-- lookup values, image policy, export settings, and lightweight app flags.
+-- Completed reports are intentionally excluded from the server in this phase;
+-- they remain browser-local artifacts exported by the client.
+
 CREATE DATABASE IF NOT EXISTS check_list CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
 USE check_list;
 
+-- Template identity stays separate from version rows so a single checklist can
+-- publish multiple definitions over time while preserving a stable code.
 CREATE TABLE IF NOT EXISTS templates (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   code VARCHAR(100) NOT NULL,
@@ -13,6 +21,9 @@ CREATE TABLE IF NOT EXISTS templates (
   UNIQUE KEY uq_templates_code (code)
 );
 
+-- Each template version stores a full JSON definition snapshot. That keeps the
+-- frontend contract simple because the client can render a form from one payload
+-- without performing additional joins or reconstruction logic.
 CREATE TABLE IF NOT EXISTS template_versions (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   template_id BIGINT UNSIGNED NOT NULL,
@@ -29,6 +40,9 @@ CREATE TABLE IF NOT EXISTS template_versions (
     ON DELETE CASCADE
 );
 
+-- Lookup sets support dropdown-style fields in a normalized way. The template
+-- JSON references the set by code, while individual values remain editable as
+-- data rather than hardcoded frontend options.
 CREATE TABLE IF NOT EXISTS lookup_sets (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   code VARCHAR(100) NOT NULL,
@@ -55,6 +69,9 @@ CREATE TABLE IF NOT EXISTS lookup_values (
     ON DELETE CASCADE
 );
 
+-- Image rules are server-managed so administrators can tighten or relax client
+-- behavior, such as size limits or attachment counts, without changing browser
+-- code. The client reads the active row and enforces it locally.
 CREATE TABLE IF NOT EXISTS image_rules (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   code VARCHAR(100) NOT NULL,
@@ -72,6 +89,9 @@ CREATE TABLE IF NOT EXISTS image_rules (
   UNIQUE KEY uq_image_rules_code (code)
 );
 
+-- Export profiles represent the eventual shape of the generated ZIP/XLSX output.
+-- The current PoC only reads this information, but separating it now makes later
+-- export customization easier.
 CREATE TABLE IF NOT EXISTS export_profiles (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   code VARCHAR(100) NOT NULL,
@@ -86,6 +106,9 @@ CREATE TABLE IF NOT EXISTS export_profiles (
   UNIQUE KEY uq_export_profiles_code (code)
 );
 
+-- Small application settings that do not justify dedicated tables are stored as
+-- JSON key/value pairs. This keeps the schema lean during the PoC phase while
+-- still allowing centrally managed frontend behavior.
 CREATE TABLE IF NOT EXISTS app_config (
   id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   config_key VARCHAR(100) NOT NULL,
@@ -95,3 +118,40 @@ CREATE TABLE IF NOT EXISTS app_config (
   PRIMARY KEY (id),
   UNIQUE KEY uq_app_config_key (config_key)
 );
+
+-- Submitted reports are stored server-side for centralized review and archival.
+-- The browser creates reports locally first; this table receives them when the
+-- operator explicitly submits. The report_uuid links back to the browser-local
+-- report ID so resubmissions are idempotent via ON DUPLICATE KEY UPDATE.
+CREATE TABLE IF NOT EXISTS reports (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  report_uuid CHAR(36) NOT NULL,
+  report_number VARCHAR(100) NOT NULL,
+  template_code VARCHAR(100) NOT NULL,
+  template_version INT NOT NULL,
+  status ENUM('draft', 'in_progress', 'ready_for_export', 'exported', 'archived') NOT NULL DEFAULT 'draft',
+  answers_json JSON NOT NULL,
+  submitted_at DATETIME NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_reports_uuid (report_uuid),
+  KEY idx_reports_template (template_code, template_version),
+  KEY idx_reports_status (status)
+);
+
+-- The audit log captures every administrative mutation so the team can trace
+-- when configuration changed and what the previous value was. Each row stores
+-- the entity type, the entity identifier, the action, and JSON snapshots of
+-- the old and new values.
+CREATE TABLE IF NOT EXISTS audit_log (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  entity_type VARCHAR(100) NOT NULL,
+  entity_code VARCHAR(200) NOT NULL,
+  action VARCHAR(50) NOT NULL,
+  old_value_json JSON NULL,
+  new_value_json JSON NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  KEY idx_audit_entity (entity_type, entity_code)
+);

sql/seed.sql

@@ -1,5 +1,11 @@
+-- Seed data provides one complete end-to-end example for the frontend:
+-- a checklist template, lookup values, image policy, export profile, and a few
+-- app-level settings. The goal is not exhaustive coverage but a realistic shape
+-- that exercises the dynamic form renderer and admin configuration flow.
+
 USE check_list;
 
+-- Register the template shell first so later version rows can reference it.
 INSERT INTO templates (code, name, description)
 VALUES (
   'incoming-inspection',
@@ -12,6 +18,9 @@ ON DUPLICATE KEY UPDATE
 
 SET @template_id = (SELECT id FROM templates WHERE code = 'incoming-inspection');
 
+-- The JSON payload below is intentionally close to the frontend contract. That
+-- makes it easy to inspect how the browser creates fields, validation hints, and
+-- attachment requirements without another transformation layer in the backend.
 INSERT INTO template_versions (
   template_id,
   version_number,
@@ -126,6 +135,8 @@ ON DUPLICATE KEY UPDATE
   definition_json = VALUES(definition_json),
   published_at = VALUES(published_at);
 
+-- Lookups are seeded separately because multiple templates may eventually reuse
+-- the same option sets, such as pass/fail or standardized status lists.
 INSERT INTO lookup_sets (code, name)
 VALUES
   ('pass-fail', 'Pass/Fail'),
@@ -150,6 +161,7 @@ ON DUPLICATE KEY UPDATE
   sort_order = VALUES(sort_order),
   is_default = VALUES(is_default);
 
+-- The image rule row is the configuration edited by the administrator UI.
 INSERT INTO image_rules (
   code,
   name,
@@ -185,6 +197,7 @@ ON DUPLICATE KEY UPDATE
   max_attachments_per_field = VALUES(max_attachments_per_field),
   is_active = VALUES(is_active);
 
+-- Export profile settings are placeholders for the later XLSX/ZIP phase.
 INSERT INTO export_profiles (
   code,
   name,
@@ -211,6 +224,7 @@ ON DUPLICATE KEY UPDATE
   include_export_timestamp = VALUES(include_export_timestamp),
   is_active = VALUES(is_active);
 
+-- App config values fine-tune the client without changing code.
 INSERT INTO app_config (config_key, config_value_json)
 VALUES
   ('autosave', '{"enabled": true, "intervalSeconds": 20}'),