Fix fresh-install migration blocker + add preflight, seed admin, first-run endpoints

Validated a clean install on MySQL 5.6 end to end and fixed the blockers.

- migrations/env.py: force alembic_version.version_num to VARCHAR(128) in its
  own committed connection before running migrations. It was VARCHAR(32); the
  revision id 7d02_widen_notification_employee_cols (37 chars) truncated, so the
  next migration's version bump matched 0 rows and `flask db upgrade` died at
  7d03 on a fresh DB. Now upgrades run clean to head.
- flask db-utils preflight: checks Python, required env, DB connectivity, and
  the MySQL 5.6 utf8mb4 index flags (innodb_large_prefix/Barracuda) - the 767
  prerequisite - and prints exact fixes. Exits non-zero on blockers.
- flask seed admin --username --email [--password]: real first-admin command
  (generates + prints a password once). The docs referenced it but only the
  dev-only test-user existed.
- setup endpoints for a UI-driven first run: /setup/needs-admin,
  /setup/create-admin (guarded to zero-users), /setup/seed-reference.
- Wizard: drop the PC-access-domain question (always .device.geaerospace.net);
  the setting keeps its default.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

shopdb/core/api/setup.py

@@ -5,12 +5,13 @@ server work: seeding common starter data and marking setup finished. Site,
 plugin, and map configuration reuse the existing settings / plugins APIs.
 """
 
-from flask import Blueprint
+from flask import Blueprint, request, current_app
 from flask_jwt_extended import jwt_required
+from werkzeug.security import generate_password_hash
 
 from shopdb.extensions import db
-from shopdb.core.models import Vendor, Setting
-from shopdb.utils.responses import success_response
+from shopdb.core.models import Vendor, Setting, User, Role
+from shopdb.utils.responses import success_response, error_response, ErrorCodes
 from shopdb.utils.authz import require_role
 
 setup_bp = Blueprint('setup', __name__)
@@ -28,6 +29,57 @@ STARTER_VENDORS = [
 ]
 
 
+@setup_bp.route('/needs-admin', methods=['GET'])
+def needs_admin():
+    """True when no users exist yet - the app's very first run. Public so the
+    login screen can offer to create the first admin."""
+    return success_response({'needsadmin': User.query.count() == 0})
+
+
+@setup_bp.route('/create-admin', methods=['POST'])
+def create_admin():
+    """Create the first admin. Only works while there are zero users, so it
+    can't be abused after setup. No auth (there is no one to auth as yet)."""
+    if User.query.count() > 0:
+        return error_response(ErrorCodes.FORBIDDEN,
+                              'An account already exists; sign in instead.', http_code=403)
+    data = request.get_json() or {}
+    username = (data.get('username') or '').strip()
+    email = (data.get('email') or '').strip()
+    password = data.get('password') or ''
+    if not (username and email and password):
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              'username, email and password are required')
+
+    admin_role = Role.query.filter_by(rolename='admin').first()
+    if not admin_role:
+        admin_role = Role(rolename='admin', description='Administrator')
+        db.session.add(admin_role)
+
+    user = User(username=username, email=email,
+                passwordhash=generate_password_hash(password), isactive=True)
+    user.roles.append(admin_role)
+    db.session.add(user)
+    db.session.commit()
+    return success_response({'username': username}, message='Admin created', http_code=201)
+
+
+@setup_bp.route('/seed-reference', methods=['POST'])
+@jwt_required()
+@require_role('admin')
+def seed_reference():
+    """Seed core reference data + permissions + default settings. Idempotent -
+    reuses the same routines as the `flask seed ...` CLI commands."""
+    # Invoke the seed CLI commands in a proper click context via the runner.
+    runner = current_app.test_cli_runner()
+    for command in ('reference-data', 'permissions', 'settings'):
+        result = runner.invoke(args=['seed', command])
+        if result.exit_code not in (0, None):
+            return error_response(ErrorCodes.INTERNAL_ERROR,
+                                  f'seed {command} failed: {result.output}', http_code=500)
+    return success_response(message='Reference data, permissions and settings seeded.')
+
+
 @setup_bp.route('/seed-starter', methods=['POST'])
 @jwt_required()
 @require_role('admin')