TrueGrowth/openspec/changes/add-social-auto-publishing/design.md

Context

The referenced project, dreammis/social-auto-upload, currently documents sau CLI commands as the main path and keeps the historical web UI as legacy. Its active model supports login, check, upload-video, and upload-note commands for core platforms such as Douyin, Kuaishou, Xiaohongshu, Bilibili, and YouTube, with additional uploader modules for Video Channel, Baijiahao, TikTok, and others.

TrueGrowth already has a React/Nx workbench shell, a left navigation, local runtime bridges, task queues, prompt history result previews, and unified asset concepts. The integration should feel native to TrueGrowth instead of exposing a foreign web app.

The historical sau_frontend is still useful as a workflow reference. Its actual pages are Dashboard, AccountManagement, MaterialManagement, PublishCenter, and About. The behaviors to carry forward are account status loading/validation, QR/SSE login feedback, material upload/preview/selection, tabbed publish drafts, per-draft account/platform/topic/schedule configuration, batch publishing progress, cancellation, and per-draft success/failure reporting.

Goals

• Let users review all publishable finished images and videos in one place.
• Let users authorize and manage multiple social accounts per platform.
• Let users compose one publishing draft and fan it out to multiple channels/accounts.
• Let users publish immediately or schedule supported platforms.
• Reuse social-auto-upload behavior through a local bridge so platform automation remains isolated and upgradeable.
• Preserve a clear audit trail from generated asset to publish job to channel result.

Non-Goals

• Do not copy the legacy sau_frontend UI into TrueGrowth.
• Do not promise every upstream uploader has the same maturity; surface unsupported fields and unsupported media types per channel.
• Do not store raw cookies or credentials in frontend state.
• Do not block the proposal on a remote cloud service; the first implementation can use the local runtime.

Decisions

• Decision: Create a native TrueGrowth publish workspace with tabs for "发布任务" and "账号授权"; publishable asset selection lives inside the publish-task form and publish history lives beside the form.
• Decision: Represent publishable content as normalized PublishableAsset records derived from existing tasks/assets/history rather than duplicating large media blobs.
• Decision: Add a local runtime adapter with operations equivalent to sau <platform> login, check, upload-video, and upload-note.
• Decision: Start with the CLI-supported stable channels from upstream CLI docs: Douyin, Kuaishou, Xiaohongshu, and Bilibili. YouTube can be visible only after the local bridge exposes its CLI command surface. Other upstream uploaders can appear as planned/experimental until their command wrappers are implemented.
• Decision: Store only account aliases, platform, status, cookie/session file references, last check time, and capability metadata in app-facing state. Secrets remain under the local runtime's controlled directory.
• Decision: Replace the upstream "multiple publish tabs" UI with TrueGrowth "campaign drafts": each draft can contain selected finished assets and multiple channel/account targets, while still preserving the upstream ability to add several draft groups and batch-submit them with progress.

UI Shape

• Left nav item: 自动发布, near "素材" and "任务" because it operates on finished content.
• Dashboard header: connected account counts, abnormal/expired account counts, enabled channel counts, publishable asset counts, queued jobs, failed jobs, and recent publish results.
• Asset center grid/list: first-level filters for 素材, 作品, 已发布 plus media type and source tags.
• Composer: selected assets, local upload fallback, asset-center picker, title, description/note, intelligent publish copy helper, tags/topics, original declaration, channel-specific options, account selector, schedule selector, validation summary, and submit action.
• Account page: platform filters, search, account rows, login/check actions, QR or browser-login progress, last status, and capability badges for video, image-note, schedule, cover, draft-only, and product-link support.
• Job page: queue grouped by publishing campaign, showing per-channel progress, logs, retries, cancellation, and source asset links.

Upstream Workflow Mapping

• Dashboard maps to TrueGrowth summary cards and quick actions inside the auto-publishing workspace.
• AccountManagement maps to "账号授权": quick load accounts first, run background status validation, allow add/edit/delete, re-login failed accounts, and display login progress or QR guidance.
• MaterialManagement maps to the route-level "资产中心" plus the publish-task asset picker: TrueGrowth generated assets are first-class, while manual upload remains available for assets not created in the system.
• PublishCenter maps to "发布任务": upstream publish tabs become campaign drafts; local upload and asset-center selection become the publish content picker; account/platform/topic/schedule/original/product/draft controls become target-aware composer sections.
• Upstream /postVideo single payload maps to TrueGrowth PublishCampaign plus one PublishJob per account/platform target so mixed success and retry are tracked precisely.

Runtime Bridge

• The frontend calls a local TrueGrowth runtime endpoint, not the upstream CLI directly.
• The runtime bridge validates file availability, exports remote/blob assets to a local file when required by sau, invokes the platform command, streams logs, and records result status.
• Platform capabilities are data-driven so new upstream support can be enabled without rewriting the page.
• Login operations may open an interactive browser or show QR guidance depending on the platform; the UI must reflect that the user may need to complete authorization outside the page.
• Login/status operations should support the upstream legacy behavior pattern of fast account listing plus slower validation. If the bridge can emit QR or browser-login progress, the UI should stream it; otherwise it should show the command/log state and required user action.
• Upload command options must map channel-specific CLI fields, including --schedule, --thumbnail, --thumbnail-landscape, --thumbnail-portrait, Douyin --product-link and --product-title, and Bilibili --tid.

Risks / Trade-offs

• Browser automation can be fragile as platforms change. Mitigation: show per-channel health, command logs, retries, and account check status.
• Some generated media may only exist as remote URLs or cache URLs. Mitigation: add an export/materialization step before enqueueing upload jobs.
• Schedules differ across platforms. Mitigation: validate per target and allow fallback to immediate publish or mark unsupported before submission.
• Multi-account parallelism can trigger platform risk controls. Mitigation: provide concurrency limits per platform/account.

Migration Plan

1. Introduce the UI route and local data models behind a workbench page.
2. Implement read-only finished asset aggregation.
3. Implement account authorization bridge and status checks.
4. Implement publish draft creation and local queue persistence.
5. Connect stable sau commands for video and image-note publishing.
6. Add job logs, retries, and publish history.

Open Questions

• Should the first release install or vendor social-auto-upload, or should it detect a user-provided sau binary/path?
• Which platforms are required for the first production milestone beyond Douyin, Kuaishou, Xiaohongshu, Bilibili, and YouTube?
• Should publish history sync into the existing task center, or remain scoped to the auto-publishing workspace?