docs(campaigns): document phase 1 campaign management

Records what Phase 1 does and deliberately does not do: no Meta writes, no
launch or sync endpoint, previews rendered without creating objects, budget
minimums enforced locally, and the fact that a payment method can only be
attached in Meta Business Manager.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
AFFAANh
2026-08-02 19:06:14 +05:30
co-authored by Claude Opus 5
parent 3859f937a2
commit 4d205c1086
+43
View File
@@ -57,6 +57,49 @@ npm run local:import-json # perform the import
The import upserts by id and never deletes, so it is safe to re-run. The JSON The import upserts by id and never deletes, so it is safe to re-run. The JSON
files are left untouched as a backup. files are left untouched as a backup.
## Campaigns
Campaign records live in PostgreSQL. Apply the schema before first use:
```powershell
npm run local:migrate
```
Set `META_ADS_ACCESS_TOKEN` in Settings > Environments, and enable the
`meta_ads` MCP client if you also want campaign tools in chat.
### What Phase 1 does and does not do
Phase 1 owns campaign records, the approval workflow, budget guardrails and ad
preview. **It creates nothing in Meta.** The only Meta calls are two reads:
- `GET /act_<id>` for balance, spend and `min_daily_budget`
- `GET /act_<id>/generatepreviews` to render ad previews
There is deliberately no launch or sync endpoint. A campaign moves
`draft -> pending_approval -> approved` and stops there; pushing objects to
Meta arrives in Phase 2.
Ad previews are rendered from a creative spec and create no Meta objects, so
the wizard can show exactly how an ad will look across desktop feed, mobile
feed, Instagram feed, Instagram story, Facebook story and right column before
anything exists.
### Budget minimums
Each ad account publishes a `min_daily_budget` in minor units. The API rejects
a lower daily budget with `422` and a readable message rather than letting Meta
reject it opaquely later. If the account cannot be read (no token, rate limit),
the check is skipped and a warning is logged: the budget guardrail is not
enforced in that case.
### Delivery requires a payment method
Meta will not deliver ads until a funding source is attached to the ad account.
**This cannot be done from MaskanX** — the Marketing API does not allow
creating funding instruments, so it must be done in Meta Business Manager. The
Campaigns page shows a warning when no payment method is present.
### Clearing and restoring credentials ### Clearing and restoring credentials
**Stop MaskanX before clearing credentials.** A running app holds its **Stop MaskanX before clearing credentials.** A running app holds its