# Media Publisher Extension Runtime V1（旧版设计）

> 旧版设计说明：本文描述的是基于浏览器插件、`plugin_installations`、`plugin_sessions` 的旧执行方案。自 2026-04-20 起，当前实现已切换到 `desktop_clients` / desktop client 架构。本文保留用于工作记录与方案追溯，不再作为当前实现依据。

## Goal

Browser extension actions must keep working for two different modes:

- Foreground actions triggered from the SaaS UI, such as bind and publish.
- Future background actions that continue after the SaaS page is closed, such as checking Doubao/Kimi inclusion status.

## Identity Model

Do not reuse the SaaS web JWT inside the extension background runtime.

Use two layers instead:

1. SaaS user session
   - Used only when the user is actively logged into the admin web app.
   - Registers or refreshes a plugin installation record.

2. Plugin installation identity
   - One record per browser installation.
   - Stored in `plugin_installations`.
   - Holds a long-lived installation token hash in the backend.
   - Lets future background jobs authenticate as a device/runtime, not as a browser tab.

## Current Tables

- `plugin_installations`
  - Stable browser installation identity.
- `plugin_sessions`
  - Short-lived action session for bind, check, publish.
- `publish_batches`
  - One multi-platform publish request.
- `publish_records`
  - One platform result row per publish.

## Current Flow

1. Admin page pings the extension.
2. Extension returns a stable `installation_key`.
3. Admin page calls `POST /api/tenant/media/plugin-installations/register`.
4. Backend returns `plugin_installation_id + installation_token`.
5. Admin page passes them back to the extension.
6. Extension stores that installation identity locally.
7. Bind or publish requests create short-lived `plugin_sessions`.
8. Callbacks write bind/publish results using session token validation.

## Future Background Tasks

Background jobs should be scheduled from the extension service worker using the stored installation identity.

Typical examples:

- Poll whether generated articles are included by Doubao/Kimi.
- Retry resolving a published article URL when only a platform draft ID is known.
- Re-check local platform login health.

Those future endpoints should authenticate with the installation token, not the SaaS web JWT.