thread-master/docs/post-project-plan.md

Post Project 計劃（文案任務 Flow A 砍掉重做）

取代 backend/docs/threads-automation-gap-plan.md 中文案自動營運閉環的舊版 Flow A。Flow B（海巡獲客：brand / placement_topic / outreach_drafts / PatrolPage）不在本計劃範圍。

1. 動機

舊版文案任務（Flow A）流程過重：

• 一個任務跑 5 個 worker（analyze → expand-graph → scan-viral → matrix → copy-draft），加上 refill-publish-inventory 自動補庫存旁路。

• 中間產 research map、knowledge graph、scan_posts、相似帳號 / 受眾樣本等中介資料，前端被 pipeline 狀態綁住。

• 使用者真正要的是：

  單純 po 文、相似貼文模仿、發想主題、AI 找網路資料、矩陣產 N 篇、定時發送、可選人設、可貼參考貼文讓 AI 學風格。

本計劃把 Flow A 整包砍掉重做，換成線性可操作的「發文計畫（Post Project）」。

2. 範圍

砍

• Persona 文案流（copy_mission / copy_draft 全部）
• refill-publish-inventory worker 與其 publish_inventory policy 接面
• 5 個文案 worker（analyze-copy-mission / expand-copy-mission-graph / generate-copy-matrix / generate-copy-draft / refill-publish-inventory）
• library/copymission/、library/matrix/copy_generate.go、library/viral/mission_*.go、library/viral/research_map.go
• prompt files matrix_copy.*
• 前端 MissionsPage + pages/missions/
• copy_missions / copy_drafts 兩個 MongoDB collection（drop）

不動

• Flow B（brand / placement_topic outreach_drafts、PatrolPage 海巡獲客）
• outreach_drafts model / library/outreach / generate-outreach-draft worker
• knowledge_graph model（brand / placement_topic 共用）
• scan_post 通用 viral 採樓能力（移除 CopyMissionID 欄位即可）
• publish_queue / publish_analytics 通用發布與量測
• scheduler / reaper / sweeper / token-sweeper / refresh-threads-token 通用 worker
• Persona model / API（沿用）

新增

• 兩個 collection：post_projects / post_drafts
• 一個 worker：go-generate-post-matrix
• 三個同步 LLM endpoint：research-topics / analyze-style / generate-matrix
• 一條線性的前端 wizard 頁面
• 三份 prompt files（post_matrix_generate / analyze_style / research_topics）

3. 資料模型

post_projects

欄位	型態	說明
_id	ObjectID
tenant_id	string
owner_uid	string
persona_id	ObjectID	關聯 personas
label	string	使用者自訂專案名
topic	string	使用者選定 / 編輯後的主題描述
web_research_summary	string	research-topics 回傳的摘要
web_research_refs	[]object	[{url, title, snippet}]
style_profile	object	analyze-style 回的結構化風格
style_summary	string	給前端顯示的風格短述
style_references	[]string	使用者貼進來的參考貼文原文
status	string	topic_set / style_set / matrix_generating / drafts_ready / archived
matrix_draft_count	int	矩陣產生的草稿數
created_at / updated_at	int64	unix nanoseconds（UTC+0）

style_profile 建議結構：

{
  "tone": "親切、口語、像跟朋友聊天",
  "length": "短至中（80-180 字）",
  "structure": ["hook", "故事", "takeaway", "互動問句"],
  "emoji_usage": "少量，平均 1-2 顆，放結尾",
  "hook_style": "提問或反差句",
  "avoid": ["過度口號", "廉價 emoji 疊字"]
}

post_drafts

欄位	型態	說明
_id	ObjectID
tenant_id	string
project_id	ObjectID	關聯 post_project
persona_id	ObjectID
topic	string	snapshot 主題（生成時）
angle	string	AI 給該篇的角度標籤
hook	string	AI 給的 hook
text	string	草稿本文
rationale	string	AI 說為何這樣寫
sources	[]object	[{url, title}] 引用網路資料
status	string	draft / scheduled / published
publish_queue_id	ObjectID?	排入佇列後回填
scheduled_at	int64?	排程時間
published_post_id	string?	發布後 Threads post id
created_at / updated_at	int64	unix nanoseconds

publish_queue.queue_item 改欄位

• copy_mission_id / copy_draft_id → post_project_id / post_draft_id（可空，舊資料不再解析）
• 既有 outreach 排程不受影響（Flow B 不靠這兩欄）

publish_inventory policy

• 移除 copy_mission_id 欄位（refill worker 已砍）
• publish_inventory 對 outreach 是否仍有用需確認；若只服務文案 refill 則整個 model 一併砍。階段 1 解耦時若發現 inventory 僅供 refill，連 collection 一起 drop。

4. API

新 generate/api/post_project.api，import 至 gateway.api。

Prefix: /api/v1/personas (scope) 與 /api/v1/post-projects (資源)

POST   /api/v1/personas/:personaId/post-projects
GET    /api/v1/personas/:personaId/post-projects
GET    /api/v1/post-projects/:projectId
PATCH  /api/v1/post-projects/:projectId          (label / topic / status)
DELETE /api/v1/post-projects/:projectId

POST   /api/v1/post-projects/:projectId/research-topics    sync:  { seed } -> { suggestions[], refs[] }
POST   /api/v1/post-projects/:projectId/analyze-style      sync:  { references:[{text}] } -> { style_profile, style_summary }
POST   /api/v1/post-projects/:projectId/generate-matrix    async job: enqueue generate-post-matrix
POST   /api/v1/post-projects/:projectId/drafts/:draftId/regenerate  async job: 重生單篇

GET    /api/v1/post-projects/:projectId/drafts
PATCH  /api/v1/post-projects/:projectId/drafts/:draftId   (text / angle / sources)
DELETE /api/v1/post-projects/:projectId/drafts/:draftId

POST   /api/v1/post-projects/:projectId/drafts/schedule   body: [{draft_id, send_at}] -> publish_queue.Create

Envelope：code/message/data/error；列表用 page/pageSize + pagination/list。

5. Worker

internal/worker/job/generate_post_matrix.go

• workerType = "go-generate-post-matrix"
• step = "post_matrix_generate"
• 讀 project.topic + project.style_profile + persona + project.web_research_refs
• 組 prompt → LLM 一次吐 N 篇（N=5 預設）
• 寫 N 個 post_drafts doc
• 更新 project.status = drafts_ready、matrix_draft_count = N
• 過程中 RefreshRunLock + Heartbeat，不做 cancel 自行設狀態

regenerate 走同一個 worker 同一 template，payload 帶 target_draft_id：

• 有 → 刪舊 draft / 重生一篇覆蓋
• 無 → 全新矩陣

6. Library

新 internal/library/post_matrix/（取代 library/copymission/）：

• analyze_style.go：貼文 → LLM → 吐 style_profile JSON + style_summary
• research_topics.go：seed → 內部 websearch（node-tool-keyword-search 或 library/viral/crawler_search） → LLM 摘要 + 主題候選
• generate.go：組 prompt → LLM → N 篇 post_drafts

prompt files（internal/library/prompt/files/）：

• post_matrix_generate.system.md / .user.md
• analyze_style.system.md / .user.md
• research_topics.system.md / .user.md

7. 前端

7.1 新頁面 web/src/pages/PostProjectsPage.tsx

取代 MissionsPage，5-step wizard（沿用 PageTitle / Card / Field / Input / Textarea / Button / Badge）：

1. 人設：下拉選 Persona
2. 主題：
   • Textarea 輸入 seed 或想法
   • 按鈕「給我主題靈感」→ research-topics（同步） → 顯示 3-5 張主題卡（含摘要 + 來源）
   • 點卡片自動填 Textarea，或手動編輯
   • 「再查一次」換一批
3. 風格（可選）：
   • Textarea 貼 1~N 篇參考貼文（空行分隔）
   • 按鈕「分析風格」→ analyze-style（同步） → 顯示 style_profile 條列
   • 可重貼、重新分析
4. 矩陣：
   • 按鈕「產生 5 篇草稿」→ generate-matrix job → polling 進度
   • 顯示 N 張草稿卡（Hook / Text / Angle / Sources）
   • 每張可：編輯 / 刪除 / 重生單篇
5. 排程：
   • 勾選草稿 → 展開 datetime-local 輸入
   • 「排入佇列」→ drafts/schedule
   • 顯示排程清單（沿用 publish_queue 顯示元件）

7.2 路由 / 導覽

• App.tsx：case "posts": return <PostProjectsPage />，加進 validPages / accountRequiredPages
• acAssets.ts navApps：把原 missions 換成 posts（label「發文計畫」，sublabel POST）
• mobileNavKeys 同步替換
• AcIcon：mission 換 posts SVG（鉛筆 + 對話框 stack 線條稿）
• validPages / accountRequiredPages 移除 "missions"

7.3 API client

api/haixun.ts：

• 刪 types CopyMission、ContentInboxItem、CopyMissionID 等相關
• 刪 endpoints copyMissions / createCopyMission / inspireCopyMission / startCopyMissionAnalyze / startCopyMissionMatrix / scheduleMissionDrafts / persona copy-drafts 系列
• 新 types PostProject / PostDraft / StyleProfile
• 新 endpoints createPostProject / listPostProjects / researchTopics / analyzeStyle / generateMatrix / regenerateDraft / listPostDrafts / updatePostDraft / deletePostDraft / schedulePostDrafts
• 保留 outreach_drafts endpoints（Flow B）

8. Infra / deploy

deploy/docker-compose.yml：

• 刪 worker-copy-mission-analyze / worker-copy-mission-expand-graph / worker-copy-matrix / worker-copy-draft / worker-refill-publish-inventory 五個 service
• 新 worker-post-matrix：HAIXUN_JOB_WORKER_TYPE=go-generate-post-matrix / HAIXUN_JOB_WORKER_ID=go-generate-post-matrix
• 保留：worker-scan-viral、worker-outreach-draft、其餘通用 worker

9. Migration

internal/bootstrap/init.go 加 idempotent migration block：

• db.RunCommand({dropIndexes: "publish_queue"}) 必要時重 EnsureIndexes
• 寫一個 tool subcommand（沿用 backend/cmd/tool）或 init runtime 做一次性：
  • drop copy_missions collection（忽略 not exist）
  • drop copy_drafts collection（忽略 not exist）
  • rename publish_queue.copy_mission_id → post_project_id、copy_draft_id → post_draft_id（對存量資料，若有人 queue 還沒發）
  • 移除 publish_inventory.policy.copy_mission_id 欄位（或整 drop publish_inventories collection，階段 1 確認後決定）
• 新 EnsureIndexes post_projects（tenant+owner+status）、post_drafts（project_id+status）

執行：首次 make prod-install 跑 init，後續 make prod-rebuild 即可。

10. 執行階段

階段	動作	驗證
1. 後端解耦	scan_viral 拔 CopyMission/CopyDraft 依賴；刪 refill_publish_inventory.go；service_context 對應移除；publish_queue / publish_inventory entity 改欄位	go test ./... Flow B 仍綠
2. 刪除 Flow A 後端	api / handler / logic / model / worker template / library / prompt 全砍；make gen-api 重產	go test ./... 通過
3. 前端清 Flow A	MissionsPage / missions 目錄 / App.tsx / Layout / acAssets / haixun.ts 清 off	make web-build 通過
4. Infra 清理	docker-compose.yml 刪 5 個 worker service	docker compose config 過
5. 新後端實作	post_project / post_draft model + usecase + repository；post_project.api + generate_post_matrix.go worker + library/post_matrix + prompt files；job template 註冊	go test ./... 通過
6. 新前端	PostProjectsPage + 5-step wizard；AcIcon 新 icon	make web-build 通過
7. DB migration	bootstrap init drop / rename / EnsureIndexes	docker run init 過
8. 煙霧測試	開 project → 靈感 → 風格 → 矩陣 → 排程 → sweeper 發；Flow B outreach 仍可；JobsPage 顯示新 type	部署在 dev 環境實測

每階段結束跑 go mod tidy && make fmt && go test ./... && make web-build。

11. 風險 / 開放問題

1. websearch 串接：library/viral/crawler_search.go 與 node-tool-keyword-search 服務是否適合 research-topics 用？實作時驗證呼叫 path；不順則直接打內部 node-tool-keyword-search HTTP。
2. publish_queue rename 對存量資料：先做 null-tolerant（舊資料視為已發 / 忽略），降低遷移負擔；正式上線前可一次性 rename script。
3. publish_inventory 是否完全沒用：階段 1 確認；若 Flow B 不依賴，整包砍。
4. style_profile 形態：採 JSON 結構化（語氣 / 長度 / 結構 / emoji / hook_style / avoid），方便前端顯示；prompt 需校調測試。
5. 矩陣批次數：MVP 固定 N=5；後續可加 count query 參數，受 persona 配額上限保護。
6. regenerate 是否保留 sources：MVP 整篇重來，不保留；後續可加「保留 sources」選項。

12. 不在本計劃範圍

• Flow B 重做（若日後需要另開計劃）
• Persona model 改造（沿用）
• publish_queue_sweeper 行為修改（沿用）
• A/B 測試、自動成效優化（屬另一個閉環計劃）