# 智能化部署 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 demo / 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 demo、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

```sql
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` 等表。