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)
+);