From 7add7e65e5a25066537db6a65e5ffc1ada79f949 Mon Sep 17 00:00:00 2001
From: xiaoqu <xiaoqu@xiaoqus-MacBook-Pro.local>
Date: Fri, 11 Sep 2026 23:18:16 +0800
Subject: [PATCH] slark WIP snapshot (fence 1789139896433)

---
 .../sql/rollback/V4__token_principal_type.down.sql  |  5 +++++
 .../java/me/iiv/agent/entity/svc/AgentApiKey.java   | 13 ++++++++++++-
 .../db/migration/V4__token_principal_type.sql       |  5 +++++
 .../main/resources/db/migration/checksums.sha256    |  1 +
 4 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 xiaoqu-agent-service/sql/rollback/V4__token_principal_type.down.sql
 create mode 100644 xiaoqu-agent-service/src/main/resources/db/migration/V4__token_principal_type.sql

diff --git a/xiaoqu-agent-service/sql/rollback/V4__token_principal_type.down.sql b/xiaoqu-agent-service/sql/rollback/V4__token_principal_type.down.sql
new file mode 100644
index 0000000..ffd1ba4
--- /dev/null
+++ b/xiaoqu-agent-service/sql/rollback/V4__token_principal_type.down.sql
@@ -0,0 +1,5 @@
+-- 回滚 V4：删除 principal_type 列。回滚后服务 Token 无法被识别（AuthService 不再区分主体类型），
+-- 存量 principal_type='service' 的 Token 会因 user_id 为空无法解析人员而 401，等于全部失效；
+-- 回滚前应先禁用或删除服务 Token（UPDATE agent_api_key SET status=0 WHERE principal_type='service'）。
+ALTER TABLE agent_api_key
+    DROP COLUMN principal_type;
diff --git a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/svc/AgentApiKey.java b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/svc/AgentApiKey.java
index df9f7fc..2da78ce 100644
--- a/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/svc/AgentApiKey.java
+++ b/xiaoqu-agent-service/src/main/java/me/iiv/agent/entity/svc/AgentApiKey.java
@@ -26,6 +26,12 @@ public class AgentApiKey implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
+    /** 主体类型：用户委托（绑定 user_id，行级权限跟随人员） */
+    public static final String PRINCIPAL_TYPE_USER = "user";
+
+    /** 主体类型：租户服务（Open API 服务密钥签发，不绑定人员） */
+    public static final String PRINCIPAL_TYPE_SERVICE = "service";
+
     /**
      * 主键
      */
@@ -33,10 +39,15 @@ public class AgentApiKey implements Serializable {
     private Long id;
 
     /**
-     * 所属人（m0.user.id）
+     * 所属人（m0.user.id）；principal_type=service 时为 NULL
      */
     private Long userId;
 
+    /**
+     * 主体类型：user=用户委托 service=租户服务
+     */
+    private String principalType;
+
     /**
      * ak 前缀（展示用，如 xqak_abcd1234）
      */
diff --git a/xiaoqu-agent-service/src/main/resources/db/migration/V4__token_principal_type.sql b/xiaoqu-agent-service/src/main/resources/db/migration/V4__token_principal_type.sql
new file mode 100644
index 0000000..34b09b0
--- /dev/null
+++ b/xiaoqu-agent-service/src/main/resources/db/migration/V4__token_principal_type.sql
@@ -0,0 +1,5 @@
+-- Token 主体类型（REQ-20260911-0014）：user=用户委托（ensure/后台签发，绑定 user_id）
+-- service=租户服务（Open API 服务密钥签发，不绑定人员，行级权限不适用）
+-- 存量行由 DEFAULT 回填为 user
+ALTER TABLE agent_api_key
+    ADD COLUMN principal_type VARCHAR(16) NOT NULL DEFAULT 'user' COMMENT '主体类型：user=用户委托 service=租户服务' AFTER user_id;
diff --git a/xiaoqu-agent-service/src/main/resources/db/migration/checksums.sha256 b/xiaoqu-agent-service/src/main/resources/db/migration/checksums.sha256
index 1b754bd..cabce88 100644
--- a/xiaoqu-agent-service/src/main/resources/db/migration/checksums.sha256
+++ b/xiaoqu-agent-service/src/main/resources/db/migration/checksums.sha256
@@ -1,3 +1,4 @@
 f8ec43a4fda81382d5675bc59fe7f4339f2e38a5b4241c260c3569e33b43a26d  V1__init.sql
 0ad892601e891a18712b1b6a613c392c94e63492dc14f4f779375c092a3acab6  V2__p4_admin.sql
 0b6e407106156911f5fe83a13b342eeec5986e2e1e5b37b6797431a8720e1332  V3__token_cipher.sql
+be1c366f36b1f0ec9e10d04be5e7619580e4ec14683b50ee44a2f351f6d35454  V4__token_principal_type.sql