chore: checkpoint 第一版

migrations/000046_ops_firmware_management.down.sql

@@ -0,0 +1,13 @@
+BEGIN;
+
+ALTER TABLE firmware_release
+    DROP COLUMN created_source,
+    DROP COLUMN published_at,
+    DROP COLUMN mandatory,
+    DROP COLUMN release_channel,
+    ALTER COLUMN household_id SET NOT NULL;
+
+ALTER TABLE firmware_rollout
+    ALTER COLUMN household_id SET NOT NULL;
+
+COMMIT;

migrations/000046_ops_firmware_management.up.sql

@@ -0,0 +1,22 @@
+BEGIN;
+
+ALTER TABLE firmware_release
+    ALTER COLUMN household_id DROP NOT NULL,
+    ADD COLUMN release_channel varchar(24) NOT NULL DEFAULT 'STABLE'
+        CHECK (release_channel IN ('STABLE','BETA','INTERNAL')),
+    ADD COLUMN mandatory boolean NOT NULL DEFAULT false,
+    ADD COLUMN published_at timestamptz,
+    ADD COLUMN created_source varchar(24) NOT NULL DEFAULT 'CUSTOMER'
+        CHECK (created_source IN ('CUSTOMER','OPS'));
+
+ALTER TABLE firmware_rollout
+    ALTER COLUMN household_id DROP NOT NULL;
+
+COMMENT ON COLUMN firmware_release.household_id IS
+    'Optional customer household scope. NULL denotes a tenant-wide release created from the maintenance portal.';
+COMMENT ON COLUMN firmware_release.created_source IS
+    'Identifies whether the release was created from the customer portal or the maintenance portal.';
+COMMENT ON COLUMN firmware_rollout.household_id IS
+    'Optional customer household scope. NULL denotes a tenant-wide rollout created from the maintenance portal.';
+
+COMMIT;

migrations/000047_hardware_agent_runtime.down.sql

@@ -0,0 +1,9 @@
+BEGIN;
+
+DROP TABLE IF EXISTS hardware_agent_event;
+DROP TABLE IF EXISTS hardware_agent_session;
+DROP TABLE IF EXISTS hardware_agent_device_binding;
+DROP INDEX IF EXISTS conversation_runtime_status_idx;
+ALTER TABLE conversation DROP COLUMN IF EXISTS runtime_type;
+
+COMMIT;

migrations/000047_hardware_agent_runtime.up.sql

@@ -0,0 +1,79 @@
+BEGIN;
+
+ALTER TABLE conversation
+    ADD COLUMN runtime_type varchar(32) NOT NULL DEFAULT 'legacy_voicechat'
+    CHECK (runtime_type IN ('legacy_voicechat', 'volc_hardware_agent'));
+
+CREATE INDEX conversation_runtime_status_idx
+    ON conversation (runtime_type, status, created_at DESC);
+
+CREATE TABLE hardware_agent_device_binding (
+    id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    public_id           uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+    tenant_id           uuid NOT NULL REFERENCES tenant(id),
+    device_id           uuid NOT NULL,
+    provider            varchar(40) NOT NULL DEFAULT 'volcengine',
+    product_key         varchar(200),
+    provider_device_ref varchar(200),
+    credential_ref      varchar(500),
+    bot_id              varchar(200) NOT NULL,
+    transport           varchar(32) NOT NULL DEFAULT 'high_quality'
+                        CHECK (transport IN ('high_quality', 'low_load')),
+    status              varchar(24) NOT NULL DEFAULT 'ACTIVE'
+                        CHECK (status IN ('ACTIVE', 'DISABLED', 'REVOKED')),
+    created_at          timestamptz NOT NULL DEFAULT now(),
+    updated_at          timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT hardware_agent_binding_device_tenant_fk FOREIGN KEY (device_id, tenant_id)
+        REFERENCES device (id, tenant_id),
+    CONSTRAINT hardware_agent_binding_device_key UNIQUE (device_id)
+);
+CREATE INDEX hardware_agent_binding_tenant_status_idx
+    ON hardware_agent_device_binding (tenant_id, status);
+
+CREATE TABLE hardware_agent_session (
+    id                       uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    public_id                uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+    tenant_id                uuid NOT NULL REFERENCES tenant(id),
+    conversation_id          uuid NOT NULL UNIQUE,
+    provider                 varchar(40) NOT NULL DEFAULT 'volcengine',
+    provider_session_ref     varchar(200) NOT NULL UNIQUE,
+    bot_id                   varchar(200) NOT NULL,
+    transport                varchar(32) NOT NULL
+                             CHECK (transport IN ('high_quality', 'low_load')),
+    session_nonce_digest     char(64) NOT NULL,
+    config_digest            char(64) NOT NULL,
+    status                   varchar(32) NOT NULL
+                             CHECK (status IN ('READY', 'STARTING', 'ACTIVE', 'STOPPING', 'COMPLETED', 'FAILED', 'EXPIRED')),
+    wait_for_session_update  boolean NOT NULL DEFAULT true,
+    provider_started_at      timestamptz,
+    provider_ended_at        timestamptz,
+    last_event_at            timestamptz,
+    last_event_sequence      bigint NOT NULL DEFAULT 0 CHECK (last_event_sequence >= 0),
+    created_at               timestamptz NOT NULL DEFAULT now(),
+    updated_at               timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT hardware_agent_session_conversation_tenant_fk FOREIGN KEY (conversation_id, tenant_id)
+        REFERENCES conversation (id, tenant_id)
+);
+CREATE INDEX hardware_agent_session_tenant_status_idx
+    ON hardware_agent_session (tenant_id, status, updated_at DESC);
+
+CREATE TABLE hardware_agent_event (
+    id                    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id             uuid NOT NULL REFERENCES tenant(id),
+    conversation_id       uuid NOT NULL,
+    event_id              varchar(255) NOT NULL,
+    sequence_no           bigint NOT NULL CHECK (sequence_no > 0),
+    event_type            varchar(64) NOT NULL,
+    occurred_at           timestamptz NOT NULL,
+    payload_digest        char(64) NOT NULL,
+    created_at            timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT hardware_agent_event_conversation_tenant_fk FOREIGN KEY (conversation_id, tenant_id)
+        REFERENCES conversation (id, tenant_id),
+    CONSTRAINT hardware_agent_event_key UNIQUE (tenant_id, event_id),
+    CONSTRAINT hardware_agent_event_sequence_key UNIQUE (conversation_id, sequence_no)
+);
+
+COMMENT ON COLUMN conversation.runtime_type IS
+    'legacy_voicechat uses platform-managed RTC/VoiceChat; volc_hardware_agent uses device-to-provider audio with platform control-plane sessions.';
+
+COMMIT;

migrations/000048_hardware_agent_capability_guardrails.down.sql

@@ -0,0 +1,12 @@
+BEGIN;
+
+ALTER TABLE hardware_agent_session
+    DROP COLUMN dynamic_config_applied_at,
+    DROP COLUMN provider_connection_ref,
+    DROP COLUMN capability_snapshot,
+    DROP COLUMN sdk_version;
+
+ALTER TABLE hardware_agent_device_binding
+    DROP COLUMN minimum_sdk_version;
+
+COMMIT;

migrations/000048_hardware_agent_capability_guardrails.up.sql

@@ -0,0 +1,17 @@
+BEGIN;
+
+ALTER TABLE hardware_agent_device_binding
+    ADD COLUMN minimum_sdk_version varchar(80);
+
+ALTER TABLE hardware_agent_session
+    ADD COLUMN sdk_version varchar(80) NOT NULL DEFAULT 'unknown',
+    ADD COLUMN capability_snapshot jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN provider_connection_ref varchar(200),
+    ADD COLUMN dynamic_config_applied_at timestamptz;
+
+COMMENT ON COLUMN hardware_agent_device_binding.minimum_sdk_version IS
+    'Minimum Volcengine hardware-agent SDK version accepted for new sessions.';
+COMMENT ON COLUMN hardware_agent_session.capability_snapshot IS
+    'Immutable device capability declaration used for privacy and runtime admission decisions.';
+
+COMMIT;

migrations/000049_hardware_agent_platform_provisioning.down.sql

@@ -0,0 +1,5 @@
+BEGIN;
+
+DROP TABLE IF EXISTS hardware_agent_provider_credential;
+
+COMMIT;

migrations/000049_hardware_agent_platform_provisioning.up.sql

@@ -0,0 +1,40 @@
+BEGIN;
+
+CREATE TABLE hardware_agent_provider_credential (
+    id                    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    public_id             uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+    tenant_id             uuid NOT NULL REFERENCES tenant(id),
+    device_id             uuid NOT NULL,
+    provider              varchar(40) NOT NULL DEFAULT 'volcengine',
+    credential_ref        varchar(500) NOT NULL UNIQUE,
+    instance_id           varchar(200) NOT NULL,
+    product_key           varchar(200) NOT NULL,
+    provider_device_name  varchar(128) NOT NULL,
+    hardware_id           varchar(200) NOT NULL,
+    key_version           bigint NOT NULL DEFAULT 1 CHECK (key_version > 0),
+    encrypted_secret      bytea NOT NULL,
+    nonce                 bytea NOT NULL,
+    status                varchar(24) NOT NULL DEFAULT 'ACTIVE'
+                          CHECK (status IN ('ACTIVE', 'REVOKED')),
+    issued_at             timestamptz NOT NULL DEFAULT now(),
+    rotated_at            timestamptz,
+    revoked_at            timestamptz,
+    created_at            timestamptz NOT NULL DEFAULT now(),
+    updated_at            timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT hardware_agent_provider_credential_device_tenant_fk
+        FOREIGN KEY (device_id, tenant_id) REFERENCES device (id, tenant_id),
+    CONSTRAINT hardware_agent_provider_credential_device_key UNIQUE (device_id),
+    CONSTRAINT hardware_agent_provider_credential_provider_name_key
+        UNIQUE (provider, instance_id, product_key, provider_device_name)
+);
+
+CREATE INDEX hardware_agent_provider_credential_tenant_status_idx
+    ON hardware_agent_provider_credential (tenant_id, status, updated_at DESC);
+
+COMMENT ON TABLE hardware_agent_provider_credential IS
+    'Platform-managed per-device provider credentials. Product secrets remain outside the database; device secrets are AEAD-encrypted with a dedicated platform master key.';
+
+COMMENT ON COLUMN hardware_agent_provider_credential.encrypted_secret IS
+    'Volcengine device_secret encrypted with VOLC_HARDWARE_DEVICE_CREDENTIAL_MASTER_KEY; never returned in logs or audit detail.';
+
+COMMIT;

migrations/000050_device_activation_state_machine.down.sql

@@ -0,0 +1,22 @@
+BEGIN;
+
+UPDATE hardware_agent_provider_credential
+SET status='REVOKED',revoked_at=COALESCE(revoked_at,now())
+WHERE status='SUSPENDED';
+
+ALTER TABLE hardware_agent_provider_credential
+    DROP CONSTRAINT hardware_agent_provider_credential_status_check;
+ALTER TABLE hardware_agent_provider_credential
+    ADD CONSTRAINT hardware_agent_provider_credential_status_check
+        CHECK (status IN ('ACTIVE','REVOKED'));
+
+DROP TABLE device_activation_transition;
+DROP INDEX device_tenant_activation_state_idx;
+ALTER TABLE device
+    DROP CONSTRAINT device_activation_state_check,
+    DROP COLUMN activation_updated_at,
+    DROP COLUMN activation_reason,
+    DROP COLUMN activation_revision,
+    DROP COLUMN activation_state;
+
+COMMIT;

migrations/000050_device_activation_state_machine.up.sql

@@ -0,0 +1,76 @@
+BEGIN;
+
+ALTER TABLE device
+    ADD COLUMN activation_state varchar(24),
+    ADD COLUMN activation_revision bigint NOT NULL DEFAULT 1,
+    ADD COLUMN activation_reason text,
+    ADD COLUMN activation_updated_at timestamptz NOT NULL DEFAULT now();
+
+UPDATE device d
+SET activation_state = CASE
+    WHEN d.status = 'revoked' THEN 'REVOKED'
+    WHEN EXISTS (SELECT 1 FROM device_binding b WHERE b.device_id=d.id AND b.unbound_at IS NULL)
+         AND EXISTS (SELECT 1 FROM device_credential dc WHERE dc.device_id=d.id AND dc.status='active')
+         AND (
+            COALESCE((SELECT dt.desired_config->>'voice_runtime' FROM device_twin dt WHERE dt.device_id=d.id),'legacy_voicechat') <> 'volc_hardware_agent'
+            OR EXISTS (
+                SELECT 1 FROM hardware_agent_provider_credential pc
+                WHERE pc.device_id=d.id AND pc.status='ACTIVE'
+            )
+         ) THEN 'ACTIVE'
+    WHEN EXISTS (
+        SELECT 1 FROM device_binding b
+        WHERE b.device_id=d.id AND b.unbound_at IS NULL
+    ) THEN 'BOUND'
+    ELSE 'CLAIMABLE'
+END,
+activation_reason = 'migration-50-backfill';
+
+ALTER TABLE device
+    ALTER COLUMN activation_state SET NOT NULL,
+    ALTER COLUMN activation_state SET DEFAULT 'FACTORY',
+    ADD CONSTRAINT device_activation_state_check
+        CHECK (activation_state IN ('FACTORY','CLAIMABLE','BOUND','PROVISIONING','ACTIVE','LOST','REVOKED'));
+
+CREATE INDEX device_tenant_activation_state_idx
+    ON device(tenant_id,activation_state,activation_updated_at DESC);
+
+CREATE TABLE device_activation_transition (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    public_id uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL REFERENCES tenant(id),
+    device_id uuid NOT NULL REFERENCES device(id),
+    from_state varchar(24),
+    to_state varchar(24) NOT NULL,
+    reason text NOT NULL,
+    source varchar(80) NOT NULL,
+    actor_type varchar(40) NOT NULL,
+    actor_public_id uuid,
+    request_id varchar(160),
+    activation_revision bigint NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT device_activation_transition_from_check CHECK (
+        from_state IS NULL OR from_state IN ('FACTORY','CLAIMABLE','BOUND','PROVISIONING','ACTIVE','LOST','REVOKED')
+    ),
+    CONSTRAINT device_activation_transition_to_check CHECK (
+        to_state IN ('FACTORY','CLAIMABLE','BOUND','PROVISIONING','ACTIVE','LOST','REVOKED')
+    ),
+    UNIQUE(device_id,activation_revision)
+);
+
+CREATE INDEX device_activation_transition_tenant_device_idx
+    ON device_activation_transition(tenant_id,device_id,created_at DESC);
+
+INSERT INTO device_activation_transition(
+    tenant_id,device_id,from_state,to_state,reason,source,actor_type,activation_revision
+)
+SELECT tenant_id,id,NULL,activation_state,'migration-50-backfill','migration','system',activation_revision
+FROM device;
+
+ALTER TABLE hardware_agent_provider_credential
+    DROP CONSTRAINT hardware_agent_provider_credential_status_check;
+ALTER TABLE hardware_agent_provider_credential
+    ADD CONSTRAINT hardware_agent_provider_credential_status_check
+        CHECK (status IN ('ACTIVE','SUSPENDED','REVOKED'));
+
+COMMIT;

migrations/000051_hardware_agent_license_pool.down.sql

@@ -0,0 +1,23 @@
+BEGIN;
+
+WITH transitioned AS (
+    UPDATE device d
+    SET activation_state='ACTIVE',activation_revision=activation_revision+1,
+        activation_reason='license-v51-rollback',activation_updated_at=now(),version=version+1,updated_at=now()
+    FROM device_twin dt
+    WHERE dt.device_id=d.id AND d.status='registered' AND d.activation_state='PROVISIONING'
+      AND d.activation_reason='license-required-v51'
+      AND COALESCE(dt.desired_config->>'voice_runtime','legacy_voicechat')='volc_hardware_agent'
+      AND EXISTS (SELECT 1 FROM hardware_agent_provider_credential pc WHERE pc.device_id=d.id AND pc.status='ACTIVE')
+    RETURNING d.tenant_id,d.id,d.activation_revision
+)
+INSERT INTO device_activation_transition(
+    tenant_id,device_id,from_state,to_state,reason,source,actor_type,activation_revision
+)
+SELECT tenant_id,id,'PROVISIONING','ACTIVE','回滚License强制门禁','migration-51-rollback','system',activation_revision
+FROM transitioned;
+
+DROP TABLE hardware_agent_license;
+DROP FUNCTION enforce_hardware_license_device_state();
+
+COMMIT;

migrations/000051_hardware_agent_license_pool.up.sql

@@ -0,0 +1,85 @@
+BEGIN;
+
+CREATE TABLE hardware_agent_license (
+    id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    public_id           uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
+    tenant_id           uuid NOT NULL REFERENCES tenant(id),
+    provider            varchar(40) NOT NULL DEFAULT 'volcengine',
+    instance_id         varchar(200) NOT NULL,
+    product_key         varchar(200) NOT NULL,
+    license_ref         varchar(200) NOT NULL UNIQUE,
+    payload_digest      varchar(64) NOT NULL CHECK (payload_digest ~ '^[0-9a-f]{64}$'),
+    encrypted_payload   bytea NOT NULL,
+    nonce               bytea NOT NULL,
+    status              varchar(24) NOT NULL DEFAULT 'AVAILABLE'
+                        CHECK (status IN ('AVAILABLE','ALLOCATED','ACTIVE','SUSPENDED','EXPIRED','REVOKED')),
+    allocated_device_id uuid,
+    allocated_at        timestamptz,
+    activated_at        timestamptz,
+    expires_at          timestamptz NOT NULL,
+    released_at         timestamptz,
+    revoked_at          timestamptz,
+    last_error_code     varchar(100),
+    created_at          timestamptz NOT NULL DEFAULT now(),
+    updated_at          timestamptz NOT NULL DEFAULT now(),
+    version             bigint NOT NULL DEFAULT 1 CHECK (version > 0),
+    CONSTRAINT hardware_agent_license_device_tenant_fk
+        FOREIGN KEY (allocated_device_id, tenant_id) REFERENCES device(id,tenant_id),
+    CONSTRAINT hardware_agent_license_assignment_check CHECK (
+        (status='AVAILABLE' AND allocated_device_id IS NULL) OR
+        (status IN ('ALLOCATED','ACTIVE','SUSPENDED') AND allocated_device_id IS NOT NULL) OR
+        status IN ('EXPIRED','REVOKED')
+    )
+);
+
+CREATE UNIQUE INDEX hardware_agent_license_device_active_key
+    ON hardware_agent_license(allocated_device_id)
+    WHERE status IN ('ALLOCATED','ACTIVE','SUSPENDED');
+CREATE INDEX hardware_agent_license_pool_idx
+    ON hardware_agent_license(tenant_id,provider,instance_id,product_key,status,expires_at);
+
+CREATE FUNCTION enforce_hardware_license_device_state() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+    changed_revision bigint;
+BEGIN
+    IF NEW.allocated_device_id IS NOT NULL
+       AND NEW.status IN ('SUSPENDED','EXPIRED','REVOKED')
+       AND OLD.status IS DISTINCT FROM NEW.status THEN
+        UPDATE device
+        SET activation_state='PROVISIONING',activation_revision=activation_revision+1,
+            activation_reason='license-' || lower(NEW.status),activation_updated_at=now(),version=version+1,updated_at=now()
+        WHERE id=NEW.allocated_device_id AND tenant_id=NEW.tenant_id AND activation_state='ACTIVE'
+        RETURNING activation_revision INTO changed_revision;
+        IF changed_revision IS NOT NULL THEN
+            INSERT INTO device_activation_transition(
+                tenant_id,device_id,from_state,to_state,reason,source,actor_type,activation_revision
+            ) VALUES(
+                NEW.tenant_id,NEW.allocated_device_id,'ACTIVE','PROVISIONING',
+                '硬件智能体License状态变为' || NEW.status,'license-state-trigger','system',changed_revision
+            );
+        END IF;
+    END IF;
+    RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER hardware_agent_license_device_state_trigger
+AFTER UPDATE OF status ON hardware_agent_license
+FOR EACH ROW EXECUTE FUNCTION enforce_hardware_license_device_state();
+
+WITH transitioned AS (
+    UPDATE device d
+    SET activation_state='PROVISIONING',activation_revision=activation_revision+1,
+        activation_reason='license-required-v51',activation_updated_at=now(),version=version+1,updated_at=now()
+    FROM device_twin dt
+    WHERE dt.device_id=d.id AND d.status='registered' AND d.activation_state='ACTIVE'
+      AND COALESCE(dt.desired_config->>'voice_runtime','legacy_voicechat')='volc_hardware_agent'
+    RETURNING d.tenant_id,d.id,d.activation_revision
+)
+INSERT INTO device_activation_transition(
+    tenant_id,device_id,from_state,to_state,reason,source,actor_type,activation_revision
+)
+SELECT tenant_id,id,'ACTIVE','PROVISIONING','硬件智能体必须分配并确认有效License','migration-51','system',activation_revision
+FROM transitioned;
+
+COMMIT;

migrations/000052_device_factory_reset.down.sql

@@ -0,0 +1,14 @@
+BEGIN;
+
+DELETE FROM web_event WHERE event_type='device.binding.reset';
+
+ALTER TABLE web_event DROP CONSTRAINT web_event_event_type_check;
+ALTER TABLE web_event ADD CONSTRAINT web_event_event_type_check CHECK (event_type IN (
+    'device.presence.changed',
+    'conversation.started','conversation.completed','conversation.failed',
+    'story.created','story.revised','media.upload.completed','export.ready',
+    'privacy_request.updated','device.command.updated'));
+
+ALTER TABLE device DROP COLUMN IF EXISTS factory_reset_counter;
+
+COMMIT;

migrations/000052_device_factory_reset.up.sql

@@ -0,0 +1,17 @@
+BEGIN;
+
+ALTER TABLE device
+    ADD COLUMN factory_reset_counter bigint NOT NULL DEFAULT 0
+    CHECK (factory_reset_counter >= 0);
+
+COMMENT ON COLUMN device.factory_reset_counter IS
+    'Monotonic counter supplied by the physical device for authenticated factory-reset replay protection.';
+
+ALTER TABLE web_event DROP CONSTRAINT web_event_event_type_check;
+ALTER TABLE web_event ADD CONSTRAINT web_event_event_type_check CHECK (event_type IN (
+    'device.presence.changed','device.binding.reset',
+    'conversation.started','conversation.completed','conversation.failed',
+    'story.created','story.revised','media.upload.completed','export.ready',
+    'privacy_request.updated','device.command.updated'));
+
+COMMIT;