Initial import: shopdb-flask multi-site asset platform

Flask + Vue rewrite of the classic-ASP shopdb, built as a plugin
framework so sister GE Aerospace sites can adopt it. Product version
0.7.0-pre-0.8.0, plugin contract 0.11.0, 966 backend tests.

Key entry points:
- docs/INSTALL-WINDOWS-IIS.md - tested Windows + IIS install runbook
  (own-site and subpath deployment methods)
- docs/PILOT-DEPLOY.md - production pilot: stand up + import + verify
- docs/IMPORT-API.md - schema-agnostic legacy data import contract
- scripts/site_imports/wjf/ - West Jefferson reference import loader
- docs/adr/ - twelve accepted architecture decision records

migrations/env.py

@@ -0,0 +1,169 @@
+import logging
+from logging.config import fileConfig
+
+from flask import current_app
+
+from alembic import context
+from sqlalchemy.ext.compiler import compiles
+from sqlalchemy.schema import CreateTable
+
+
+# Force every table the migrations create on MySQL to utf8mb4 + DYNAMIC row
+# format. Without this a fresh `flask db upgrade` inherits the server default
+# charset, so a box whose default is latin1 (common on older MySQL) silently
+# builds a latin1 schema that drifts from the utf8mb4 production target. The
+# DYNAMIC row format also keeps utf8mb4 indexes under the 767-byte prefix limit
+# on pre-5.7 InnoDB. Scoped to the mysql dialect so the SQLite test DB is
+# untouched.
+@compiles(CreateTable, "mysql")
+def _mysql_create_table_utf8mb4(element, compiler, **kw):
+    sql = compiler.visit_create_table(element, **kw)
+    if "CHARSET" not in sql.upper():
+        sql = sql.rstrip().rstrip(";")
+        sql += (
+            " ENGINE=InnoDB DEFAULT CHARSET=utf8mb4"
+            " COLLATE=utf8mb4_unicode_ci ROW_FORMAT=DYNAMIC"
+        )
+    return sql
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+fileConfig(config.config_file_name)
+logger = logging.getLogger('alembic.env')
+
+
+def get_engine():
+    try:
+        # this works with Flask-SQLAlchemy<3 and Alchemical
+        return current_app.extensions['migrate'].db.get_engine()
+    except (TypeError, AttributeError):
+        # this works with Flask-SQLAlchemy>=3
+        return current_app.extensions['migrate'].db.engine
+
+
+def get_engine_url():
+    try:
+        return get_engine().url.render_as_string(hide_password=False).replace(
+            '%', '%%')
+    except AttributeError:
+        return str(get_engine().url).replace('%', '%%')
+
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+# from myapp import mymodel
+# target_metadata = mymodel.Base.metadata
+config.set_main_option('sqlalchemy.url', get_engine_url())
+target_db = current_app.extensions['migrate'].db
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def get_metadata():
+    if hasattr(target_db, 'metadatas'):
+        return target_db.metadatas[None]
+    return target_db.metadata
+
+
+def run_migrations_offline():
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url, target_metadata=get_metadata(), literal_binds=True
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+
+    # this callback is used to prevent an auto-migration from being generated
+    # when there are no changes to the schema
+    # reference: http://alembic.zzzcomputing.com/en/latest/cookbook.html
+    def process_revision_directives(context, revision, directives):
+        if getattr(config.cmd_opts, 'autogenerate', False):
+            script = directives[0]
+            if script.upgrade_ops.is_empty():
+                directives[:] = []
+                logger.info('No changes in schema detected.')
+
+    conf_args = current_app.extensions['migrate'].configure_args
+    if conf_args.get("process_revision_directives") is None:
+        conf_args["process_revision_directives"] = process_revision_directives
+
+    connectable = get_engine()
+
+    # Alembic creates alembic_version.version_num as VARCHAR(32), but some
+    # revision ids in this chain exceed 32 chars. On MySQL that truncates the
+    # stored id, so the next migration's version bump matches 0 rows and the
+    # upgrade dies. Force the column wide in its OWN committed connection first
+    # (keeping it out of alembic's migration transaction), so long ids never
+    # truncate - fresh or existing.
+    try:
+        with connectable.connect() as prep:
+            prep.exec_driver_sql(
+                'CREATE TABLE IF NOT EXISTS alembic_version '
+                '(version_num VARCHAR(128) NOT NULL, '
+                'CONSTRAINT alembic_version_pkc PRIMARY KEY (version_num))'
+            )
+            prep.exec_driver_sql(
+                'ALTER TABLE alembic_version MODIFY version_num VARCHAR(128) NOT NULL'
+            )
+            prep.commit()
+    except Exception:
+        # Non-MySQL backends (e.g. sqlite in tests) - alembic's default is fine.
+        pass
+
+    with connectable.connect() as connection:
+        # Relax the session sql_mode for the migration run. Some historical
+        # migrations seed reference rows with raw INSERTs that omit NOT-NULL
+        # timestamp columns (the ORM supplies those via Python defaults at
+        # runtime, but a raw migration INSERT does not). MySQL 5.x's lax default
+        # accepted that; strict MySQL 8 rejects it with 1364 "Field 'createddate'
+        # doesn't have a default value". Dropping STRICT_TRANS_TABLES for the
+        # migration session only (the app's own connections keep their mode)
+        # makes the chain portable across MySQL versions.
+        try:
+            connection.exec_driver_sql(
+                "SET SESSION sql_mode = 'NO_ENGINE_SUBSTITUTION'")
+        except Exception:
+            pass  # non-MySQL backends (e.g. sqlite in tests)
+
+        context.configure(
+            connection=connection,
+            target_metadata=get_metadata(),
+            **conf_args
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()