# zqyy_app — Web 管理后台表结构文档

## 变更说明

在 `zqyy_app` 数据库中新增 4 张表，支撑 Web 管理后台的用户认证、任务队列、执行日志和定时调度功能。

| 操作 | 表名 | 说明 |
|------|------|------|
| 新增 | admin_users | 管理后台操作员账户，绑定门店 site_id |
| 新增 | task_queue | ETL 任务执行队列，支持排序和状态流转 |
| 新增 | task_execution_log | 任务执行历史记录，含日志和摘要 |
| 新增 | scheduled_tasks | 定时调度任务，支持 5 种调度类型 |

### 新增字段概览

#### admin_users
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | SERIAL | PK | 自增主键 |
| username | VARCHAR(64) | UNIQUE NOT NULL | 登录用户名 |
| password_hash | VARCHAR(256) | NOT NULL | bcrypt 密码哈希 |
| display_name | VARCHAR(128) | | 显示名称 |
| site_id | BIGINT | NOT NULL | 绑定的门店 ID |
| is_active | BOOLEAN | DEFAULT TRUE | 是否启用 |
| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
| updated_at | TIMESTAMPTZ | DEFAULT NOW() | 更新时间 |

#### task_queue
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK, DEFAULT gen_random_uuid() | 队列任务 ID |
| site_id | BIGINT | NOT NULL | 门店隔离 |
| config | JSONB | NOT NULL | 序列化的 TaskConfig |
| status | VARCHAR(20) | NOT NULL, DEFAULT 'pending' | pending/running/success/failed/cancelled |
| position | INTEGER | NOT NULL, DEFAULT 0 | 队列排序位置 |
| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
| started_at | TIMESTAMPTZ | | 开始执行时间 |
| finished_at | TIMESTAMPTZ | | 执行完成时间 |
| exit_code | INTEGER | | 子进程退出码 |
| error_message | TEXT | | 错误信息 |

#### task_execution_log
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK, DEFAULT gen_random_uuid() | 日志 ID |
| queue_id | UUID | FK → task_queue(id) | 关联的队列任务（可空） |
| site_id | BIGINT | NOT NULL | 门店隔离 |
| task_codes | TEXT[] | NOT NULL | 执行的任务编码列表 |
| status | VARCHAR(20) | NOT NULL | 执行状态 |
| started_at | TIMESTAMPTZ | NOT NULL | 开始时间 |
| finished_at | TIMESTAMPTZ | | 结束时间 |
| exit_code | INTEGER | | 退出码 |
| duration_ms | INTEGER | | 执行时长（毫秒） |
| command | TEXT | | 实际执行的 CLI 命令 |
| output_log | TEXT | | stdout 完整日志 |
| error_log | TEXT | | stderr 日志 |
| summary | JSONB | | 执行摘要 |
| created_at | TIMESTAMPTZ | DEFAULT NOW() | 记录创建时间 |

#### scheduled_tasks
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK, DEFAULT gen_random_uuid() | 调度任务 ID |
| site_id | BIGINT | NOT NULL | 门店隔离 |
| name | VARCHAR(256) | NOT NULL | 调度任务名称 |
| task_codes | TEXT[] | NOT NULL | 任务编码列表 |
| task_config | JSONB | NOT NULL | 序列化的 TaskConfig |
| schedule_config | JSONB | NOT NULL | 序列化的 ScheduleConfig |
| enabled | BOOLEAN | DEFAULT TRUE | 是否启用 |
| last_run_at | TIMESTAMPTZ | | 上次执行时间 |
| next_run_at | TIMESTAMPTZ | | 下次执行时间 |
| run_count | INTEGER | DEFAULT 0 | 累计执行次数 |
| last_status | VARCHAR(20) | | 上次执行状态 |
| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
| updated_at | TIMESTAMPTZ | DEFAULT NOW() | 更新时间 |

### 索引

| 索引名 | 表 | 列 | 类型 | 说明 |
|--------|------|------|------|------|
| idx_admin_users_site | admin_users | site_id | B-tree | 按门店查询用户 |
| idx_task_queue_status | task_queue | status | B-tree | 按状态查询队列 |
| idx_task_queue_site_position | task_queue | site_id, position | 部分索引 (WHERE status='pending') | 取出待执行任务 |
| idx_execution_log_site_started | task_execution_log | site_id, started_at DESC | B-tree | 执行历史列表 |
| idx_scheduled_tasks_site | scheduled_tasks | site_id | B-tree | 按门店查询调度 |
| idx_scheduled_tasks_next_run | scheduled_tasks | next_run_at | 部分索引 (WHERE enabled=TRUE) | 查询到期调度 |

### 种子数据

- 默认管理员：`admin` / `admin123`，site_id=1
- 种子脚本：`db/zqyy_app/seeds/admin_web_seed.sql`

## 兼容性

- **ETL Connector**：无影响。新表位于 `zqyy_app` 库，ETL 数据仍在 `etl_feiqiu` 库
- **后端 API**：新增的 FastAPI 路由将读写这 4 张表，需配置 `zqyy_app` 数据库连接
- **小程序**：无影响。小程序通过 FDW 访问 ETL 数据，不涉及管理后台表
- **现有 zqyy_app 表**：无影响。新表与现有 users/roles/tasks 等表无外键关联

## 回滚策略

```sql
-- 按依赖顺序删除（task_execution_log 引用 task_queue）
BEGIN;
DROP TABLE IF EXISTS task_execution_log CASCADE;
DROP TABLE IF EXISTS task_queue CASCADE;
DROP TABLE IF EXISTS scheduled_tasks CASCADE;
DROP TABLE IF EXISTS admin_users CASCADE;
COMMIT;
```

## 验证 SQL

```sql
-- 1. 验证 4 张表均已创建
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_name IN ('admin_users', 'task_queue', 'task_execution_log', 'scheduled_tasks')
ORDER BY table_name;

-- 2. 验证索引已创建（应返回 6 条）
SELECT indexname, tablename
FROM pg_indexes
WHERE tablename IN ('admin_users', 'task_queue', 'task_execution_log', 'scheduled_tasks')
  AND indexname LIKE 'idx_%'
ORDER BY tablename, indexname;

-- 3. 验证默认管理员已插入
SELECT id, username, display_name, site_id, is_active
FROM admin_users
WHERE username = 'admin';

-- 4. 验证 task_queue 的部分索引条件
SELECT indexname, indexdef
FROM pg_indexes
WHERE indexname = 'idx_task_queue_site_position';

-- 5. 验证 task_execution_log 的外键约束
SELECT conname, conrelid::regclass, confrelid::regclass
FROM pg_constraint
WHERE conrelid = 'task_execution_log'::regclass
  AND contype = 'f';
```