59 lines
3.8 KiB
Markdown
59 lines
3.8 KiB
Markdown
|
# 阶段 A 契约清单（task_server / proc / task_commons → Rust）
|
|||
|
|
|
|||
|
|
本文档与 `htyts_models`、`htyts` crate 一并落地，供后续阶段 B/C 实现与现网对齐时对照。
|
|||
|
|
|
|||
|
|
## PostgreSQL：`DbTask` 表
|
|||
|
|
|
|||
|
|
Java 实体：仓库根目录下 [`task_commons/.../DbTask.java`](../../task_commons/src/main/java/cn/alchemystudio/taskcommons/db/DbTask.java)。
|
|||
|
|
|
|||
|
|
- **表名（已核对）：** 正式机 `alchemy-studio.cn` 上任务库为 `htytask_alchemy`、`htytask_huiwings`（`moicen` 等环境库名可能为 `htytask_moicen`，以该机 `\l` 为准）。`public` 下表名为 **`dbtask`**（非 `db_task`），与 [`htyts/src/schema.rs`](../htyts/src/schema.rs) 一致。
|
|||
|
|
- **核对命令（需本机可 `ssh weli@alchemy-studio.cn` 且 `sudo -u postgres` 免密）：** `sudo -n -u postgres psql -d htytask_alchemy -c '\d+ public.dbtask'`。直连 `psql -U postgres` 可能要求密码，可改用上述 `sudo`。
|
|||
|
|
- **已记录的列类型（`htytask_alchemy.public.dbtask`）：** `task_id varchar(255)` PK；`task_type` / `task_status` / `created_by` / `updated_by` `varchar(255)`；`hty_id` / `meta` 可空；`meta varchar(65535)`；`duration` `double precision`；`created_at` / `updated_at` `timestamp(6) without time zone`。
|
|||
|
|
- **列（与 Java 字段一致）：** `task_id` (PK), `hty_id`, `task_type`, `task_status`, `duration`, `created_by`, `created_at`, `updated_by`, `updated_at`, `meta`。
|
|||
|
|
- **枚举存字符串：** 与 Java `Enum.name()` 一致，如 `PENDING`, `UPLOAD_PICTURE`。Rust 侧解析见 `htyts_models::TaskStatus::from_str` / `TaskType::from_str`。
|
|||
|
|
|
|||
|
|
参考 DDL（**以现网为准**）：
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
-- VERIFY table name and types against production before use.
|
|||
|
|
CREATE TABLE IF NOT EXISTS dbtask (
|
|||
|
|
task_id TEXT PRIMARY KEY,
|
|||
|
|
hty_id TEXT,
|
|||
|
|
task_type TEXT NOT NULL,
|
|||
|
|
task_status TEXT NOT NULL,
|
|||
|
|
duration DOUBLE PRECISION,
|
|||
|
|
created_by TEXT NOT NULL,
|
|||
|
|
created_at TIMESTAMP NOT NULL,
|
|||
|
|
updated_by TEXT NOT NULL,
|
|||
|
|
updated_at TIMESTAMP NOT NULL,
|
|||
|
|
meta TEXT
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Redis
|
|||
|
|
|
|||
|
|
- Java：`task_commons` `BaseRedisService.TS_REDIS_PREFIX` = `"TS_"`；任务 payload 为 `TS_{task_id}` 的字符串值（JSON）。
|
|||
|
|
- Rust：`htyts_models::task_payload_redis_key` / `TS_REDIS_PREFIX`。
|
|||
|
|
- **Sudoer 缓存（与 AuthCore `HW_T_` 不同）：** Java `task_server` 的 `CheckAuthFilter` 使用 `TS_SUDO_T_{token_id}` 存 `HtyToken` JSON（见 `RedisTokenCacheService`）。Rust `htyts` 的 `create_task` / `update_task` 已按该语义校验（可选走 `HTYUC_URL` + `/api/v1/uc/verify_jwt_token`，环境变量 `AUTH_CHECKING` / `TOKEN_VERIFY` / `EXP_DAYS` 与 Java 对应）。
|
|||
|
|
- 与 `htycommons::redis_util` 中 `HW_`、`T_` 等前缀**不要混用**到任务 payload；sudoer 校验路径以 `task_server` 为准。
|
|||
|
|
|
|||
|
|
## HTTP 契约（后续阶段实现）
|
|||
|
|
|
|||
|
|
- **Task service** 前缀：`/api/v1/ts`（见 Java `TaskApp` + `TaskService`）。
|
|||
|
|
- **Proc 控制面：** `/api/v1/proc/start|stop|status`。
|
|||
|
|
- **Ts 客户端（proc → ts）：** `TsProxy` 路径 `create_task`, `update_task`, `one_pending_task`, `one_zombie_task`。
|
|||
|
|
- **AI 客户端：** `AiProxy` `/api/v1/ai` 下 `compare`, `watermark`, `compress`, `get_task_result`。
|
|||
|
|
|
|||
|
|
## 与 AuthCore 的复用（proc 侧）
|
|||
|
|
|
|||
|
|
以下类型在 Java 中来自 `task_commons`，Rust 侧 **优先使用 AuthCore 已有定义**：
|
|||
|
|
|
|||
|
|
- `ReqHtyResource`、`ReqRefResource` 等：在 **`htycommons::models`**（见 `htyuc_models` 对 `ReqHtyResource` 的引用与 `HtyResource::to_req`）。
|
|||
|
|
- 实现 proc 前请在 `AuthCore` 中 `grep` 上述类型名，避免在 `htyts_models` 重复定义。
|
|||
|
|
|
|||
|
|
## JSON 字段名
|
|||
|
|
|
|||
|
|
- `ReqTasksWithPage` 使用 `totalPage`（Java bean）。
|
|||
|
|
- `AudioFileAndAiScorePayload` 使用 `aiScorePayload` / `audioPayload`（已在 `htyts_models` 标注 `serde(rename = ...)`）。
|
|||
|
|
- 其它 payload 与 `CommonTaskResult` 若与现网抓包不一致，以 **实际响应** 为准并补 `serde` 别名。
|