auto_agent/docs/智能化部署agent-demo最小DDL设计.md

智能化部署 Agent Demo 最小 DDL 设计

更新时间:2026-04-08

1. 文档目的

本文档用于定义 demo 第一阶段的最小数据库表结构,直接服务于以下目标:

1. 支撑 POST /api/agent/tasks
2. 支撑 POST /api/agent/tasks/{task_id}/confirm
3. 支撑 GET /api/agent/tasks/{task_id}
4. 为后续审批、审计、工具调用留出可扩展落点

当前约束:

1. demo 默认数据库采用 SQLite
2. 时间字段统一采用 yyyy-MM-dd HH:mm:ss.SSS
3. JSON 字段统一采用 snake_case
4. 复杂对象先以 JSON 字符串形式存储,后续切换 PostgreSQL 时可平滑升级为 JSONB

---

2. 本轮最小表清单

第一批仅落以下 4 张表:

1. task
2. approval_request
3. tool_call
4. audit_log

说明:

1. task 是主链路核心表。
2. approval_request 为高风险任务确认后进入审批预留。
3. tool_call 为后续软件 A 最小能力实现 / edge 验证接入预留。
4. audit_log 为关键动作审计预留。

---

3. 表结构设计

3.1 task

用途:

1. 存储自然语言原始输入。
2. 存储结构化意图快照。
3. 存储风险等级、审批状态和任务状态。
4. 存储结果摘要与时间戳。

字段:

1. task_id TEXT 主键
2. session_id TEXT 非空
3. tenant_id TEXT 非空
4. request_id TEXT 可空
5. input_text TEXT 非空
6. channel TEXT 非空
7. action_type TEXT 可空
8. app_code TEXT 可空
9. env TEXT 可空
10. version TEXT 可空
11. risk_level TEXT 非空
12. approval_status TEXT 非空
13. task_status TEXT 非空
14. parsed_intent_json TEXT 非空
15. missing_slots_json TEXT 非空
16. summary TEXT 可空
17. created_at TEXT 非空
18. updated_at TEXT 非空
19. confirmed_at TEXT 可空

建议索引:

1. idx_task_session_id
2. idx_task_tenant_id
3. idx_task_status
4. idx_task_created_at

3.2 approval_request

用途:

1. 为 HIGH 风险任务记录审批状态。
2. 为后续审批 demo 接口联调预留。

字段:

1. approval_id TEXT 主键
2. task_id TEXT 非空
3. approval_status TEXT 非空
4. risk_level TEXT 非空
5. operator_user_id TEXT 可空
6. operator_user_name TEXT 可空
7. approver_user_ids_json TEXT 非空
8. reason TEXT 可空
9. created_at TEXT 非空
10. updated_at TEXT 非空

建议索引:

1. idx_approval_task_id
2. idx_approval_status

3.3 tool_call

用途:

1. 记录软件 A 最小能力实现、edge 验证和后续工具调用轨迹。

字段:

1. tool_call_id TEXT 主键
2. task_id TEXT 非空
3. step_id TEXT 可空
4. tool_name TEXT 非空
5. request_payload_json TEXT 非空
6. response_payload_json TEXT 非空
7. success INTEGER 非空
8. duration_ms INTEGER 可空
9. started_at TEXT 可空
10. finished_at TEXT 可空

建议索引:

1. idx_tool_call_task_id
2. idx_tool_call_tool_name

3.4 audit_log

用途:

1. 记录任务创建、确认、审批等待和后续执行摘要。

字段:

1. audit_id TEXT 主键
2. task_id TEXT 非空
3. action TEXT 非空
4. operator_user_id TEXT 可空
5. operator_user_name TEXT 可空
6. target TEXT 可空
7. result TEXT 非空
8. detail_json TEXT 非空
9. timestamp TEXT 非空

建议索引:

1. idx_audit_task_id
2. idx_audit_action
3. idx_audit_timestamp

---

4. SQLite 参考 DDL

CREATE TABLE IF NOT EXISTS task (
  task_id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  tenant_id TEXT NOT NULL,
  request_id TEXT,
  input_text TEXT NOT NULL,
  channel TEXT NOT NULL,
  action_type TEXT,
  app_code TEXT,
  env TEXT,
  version TEXT,
  risk_level TEXT NOT NULL,
  approval_status TEXT NOT NULL,
  task_status TEXT NOT NULL,
  parsed_intent_json TEXT NOT NULL,
  missing_slots_json TEXT NOT NULL,
  summary TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  confirmed_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_task_session_id ON task (session_id);
CREATE INDEX IF NOT EXISTS idx_task_tenant_id ON task (tenant_id);
CREATE INDEX IF NOT EXISTS idx_task_status ON task (task_status);
CREATE INDEX IF NOT EXISTS idx_task_created_at ON task (created_at);

CREATE TABLE IF NOT EXISTS approval_request (
  approval_id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  approval_status TEXT NOT NULL,
  risk_level TEXT NOT NULL,
  operator_user_id TEXT,
  operator_user_name TEXT,
  approver_user_ids_json TEXT NOT NULL,
  reason TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_approval_task_id ON approval_request (task_id);
CREATE INDEX IF NOT EXISTS idx_approval_status ON approval_request (approval_status);

CREATE TABLE IF NOT EXISTS tool_call (
  tool_call_id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  step_id TEXT,
  tool_name TEXT NOT NULL,
  request_payload_json TEXT NOT NULL,
  response_payload_json TEXT NOT NULL,
  success INTEGER NOT NULL,
  duration_ms INTEGER,
  started_at TEXT,
  finished_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_tool_call_task_id ON tool_call (task_id);
CREATE INDEX IF NOT EXISTS idx_tool_call_tool_name ON tool_call (tool_name);

CREATE TABLE IF NOT EXISTS audit_log (
  audit_id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  action TEXT NOT NULL,
  operator_user_id TEXT,
  operator_user_name TEXT,
  target TEXT,
  result TEXT NOT NULL,
  detail_json TEXT NOT NULL,
  timestamp TEXT NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_audit_task_id ON audit_log (task_id);
CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log (action);
CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit_log (timestamp);

---

5. 后续演进建议

1. 当 demo 从单机联调进入多人并发联调时,优先切换到 PostgreSQL。
2. 切换后可将 parsed_intent_json、missing_slots_json、detail_json 等字段升级为 JSONB。
3. 若后续引入独立 worker 和多实例抢任务,再补 task_step、edge_task 等表。