MintOffice — Tehniline¶

Tehniline kaaslane MintOffice'i operaatori juhendile. Operaatori juhend juhatab sind läbi töölaua nõustaja; see lehekülg on arendajale: millised hoidlad sulle kuuluvad, mida iga üks juhib ja kuidas kliendi "Osta"-klikist saab töötav agent sinu enda domeenil.

Agent customization repo partner-portal-example Brand Partner API viide

Kuidas tükid kokku sobivad¶

White-label MintOffice'i seadistus on kolm kihti, mis kuuluvad kolmele erinevale poolele:

┌──────────────────────────┐   ┌──────────────────────────┐   ┌──────────────────────────┐
│  Sinu pood               │   │  MintOffice (keskne)     │   │  Iga kliendi agent       │
│  (partner-portal-*)      │──▶│  mint.mintbot.ai         │──▶│  agent1.sinubränd.com    │
│  sinubränd.com           │   │  + deploy worker         │   │  (üks VPS kliendi kohta) │
└──────────────────────────┘   └──────────────────────────┘   └──────────────────────────┘
      sina majutad                 mintbot majutab               mintbot majutab (agendi kohta)

Pood — sinu kliendile suunatud veebisait. Näitab paketikaarte, võtab vastu "Osta"-kliki, edastab tellimuse MintOffice'ile, võtab vastu webhook'i sündmused. Sa forkid näidise, brändid selle ja majutad enda domeenil.
MintOffice keskne — jookseb mint.mintbot.ai-l. Omab Brand Partner API-t, Stripe'i integratsiooni, partneripõhist saladuste varamut (Telegrami boti token, Zone.ee API võti, …), deploy worker'it, tuluraamatut. Mintbot haldab seda iga partneri jaoks; sa ei jooksuta seda kunagi ise.
Iga kliendi agent — pühendatud VPS, mille deploy worker käivitab, kui tellimus on makstud. Keskne deployb ise standardse, bränditu baasagendi; seejärel kloonib VPS sinu Agent customization repo ja jooksutab seda lokaalselt, et rakendada sinu persona, paneeli teema ja lisatööriistad. Keskne ei käivita kunagi sinu hoidlat — seda teeb ainult agendi enda VPS. Klient suhtleb sinu Telegrami boti või veebipaneeli kaudu sinu apex-domeeni alamdomeenil (agent1.sinubränd.com).

Kaks hoidlat, mis sulle kuuluvad¶

White-label bränding paikneb kahes eraldi hoidlas, kummalgi oma ülesanne. Sa omad ja majutad neid sõltumatult, sellise rütmiga, nagu sinu brändile sobib.

1. Agent customization repo — milline iga kliendi agent välja näeb¶

Sinu Agent customization repo juhib personat, mida agent kasutab, paneeli teemat (CSS/JS), mida klient brauseris näeb, ja kõiki lisatööriistu või kliendispetsiifilist seadistust, mille tahad baasagendi peale kihiti lisada. Erinevalt vanast "template-forki" mudelist ei klooni ega jooksuta keskne seda hoidlat kunagi. Selle asemel teeb keskne ise täie standardse deploy ja seejärel kloonib agendi enda VPS sinu hoidla ja jooksutab seda lokaalselt — nii et see on sinu kood, sinu kontrolli all, agendi masinas.


Mis see on	GitHubi hoidla, mille juurkaustas on kaks skripti — `install.sh` ja `update.sh` — pluss kõik varad (teemafailid, persona tekst, tööriistade definitsioonid), mida need skriptid paigaldavad. See kuulub täielikult sulle; pole lubatud-nimekirja ega keskset "küpsetamise" sammu.
Lähtepunkt	`mintbot-ai/agent-template` — valmis forkimiseks mõeldud näidishoidla. Juurkaustas on `install.sh` / `update.sh` pluss `theme/` (paneeli CSS/JS) ja `persona/` (brändihääl) varad ning `lib/common.sh` abifunktsioonidega. Tuleb kaasa kohatäite-brändiga ExampleAI, mille nimetad ümber. Forki see, vaheta sisse oma bränding, pushi ja suuna nõustaja oma forki HTTPS-URL-ile.
MintOffice'iga ühendatud läbi	Töölaud → Settings → Agent customization repo → kleebi oma hoidla HTTPS-URL. Keskne renderdab URL-i agendi VPS-i keskkonda; VPS kutsub `git clone`, kui standardne deploy on terve.
Tõrkeisoleeritud	Puuduv, ebaõnnestuv või aeglane skript ei lase kunagi deploy'l ebaõnnestuda, ei blokeeri baaspaketi uuendust ega lõhu kliendi agenti. Tõrked logitakse VPS-is ja tuuakse sinuni — need ei jõua kunagi lõppkliendini.

`install.sh` / `update.sh` leping¶

Hoidla juur on leping: kaks skripti, mida agendi enda VPS jooksutab oma elutsükli täpselt määratud punktides.

install.sh — jookseb üks kord, agendi enda VPS-is, pärast seda, kui standardne deploy on lõppenud ja agent on terve. Siin paigaldad oma kohanduse: lisad oma teema, kohandad personat, registreerid lisatööriistu, teed kliendispetsiifilise seadistuse. Agent on selle jooksmise ajal juba elus ja teenindab; install.sh kihistab sinu brändi peale.
update.sh — jookseb pärast iga paketiuuendust VPS-is. Valikuline. Kui agent uuendab ise oma baaspaketti, jooksutab ta seejärel sinu update.sh, et saaksid oma kihi uue baasi peale uuesti rakendada või kohandada. Jäta fail välja, kui sinu kohandus jääb baasiuuenduste järel puutumatuks.

Uuenduse järjekord

Igal uuendusel rakendatakse kõigepealt baaspakett — see on white-label baasagent, mida hoitakse upstream-uuenduste rajal — ja seejärel jookseb sinu update.sh selle peale. Sinu kiht rakendatakse alati uusima baasi vastu, mitte kunagi vastupidi.

Tõrkeisolatsioon — sinu skriptid ei saa kliendi agenti lõhkuda

Kohandusskriptid jooksevad parima-püüde režiimis ja on täielikult eraldatud allkirjastatud baasist. Kui install.sh või update.sh puudub, annab vea või jookseb aeglaselt:

deploy õnnestub ikka ja agent jääb terveks,
baaspaketi uuendust ei blokeerita ega tagasi pöörata,
tõrge logitakse VPS-is ja tuuakse sinuni, operaatorini — see ei jõua kunagi lõppkliendini.

Keskseid "lepingu-teste" ega katkestatud deploy'sid pole, sest keskne ei jooksuta kunagi sinu koodi. Vastutasu: katkine skript jätab agendi vaikselt tavalise baasi peale sinu bränditud kihi asemel, seega testi oma hoidlat DEV-deploy'l, enne kui suunad sellele päris agendid.

Turvalisus — see on sinu vastutusala

Keskne ei käivita kunagi sinu hoidlat. Ainult agendi enda VPS kloonib ja jooksutab seda, samade õigustega, millega agent ise sellel masinal jookseb (sinu skriptid jooksevad sinu kliendi enda VPS-is, mitte mõnel jagatud infrastruktuuril). Hoidla URL on ainult GitHub HTTPS, valideeritud enne salvestamist; kloon on madal, mahupiiratud ja ajapiiratud, ning sinu skriptid jooksevad timeout'iga ja ilma saladusteta keskkonnas. Kõik, mida sinu skriptid teevad, on sinu enda vastutusalas — selgelt eraldatud allkirjastatud baaspaketist, mida keskne juhib. Kuna lõppkasutajad ei tohi kunagi näha aluseks olevat baasbrändi, hoia oma persona ja teema mintbot-bränditust vabad ning esita ainult oma brändi.

2. Poe portaal — mida sinu klient enne ostmist näeb¶

Pood on veebisait, kuhu kliendid jõuavad, sirvivad pakette, klikivad Osta, suunatakse Stripe'i ja tulevad tänulehele tagasi. See võtab ka vastu MintOffice'i webhook'i kohaletoimetusi, et sinu enda süsteemid teaksid, millal tellimus on makstud, millal selle agent on valmis, millal see aegub.


Näidishoidla	`mintbot-ai/partner-portal-example` — MIT-litsentsiga FastAPI + SQLite, dokeriseeritud, tuleb kaasa ExampleAI brändiga, mille vahetad välja. Realiseerib maandumislehe, `/buy`, tänu-/tühistuslehed, allkirjastatud webhook'i vastuvõtja, HTTP-Basic-auth `/admin` sündmuste sirvija.
MintOffice'iga ühendatud läbi	Töölaud → Settings → API access → sea Webhook URL väärtuseks `https://<sinu-host>/webhooks/mintoffice` ja kopeeri allkirjastamise saladus portaali `.env`-i.
Sina majutad seda	Kõikjal, kus on HTTPS — sinu enda VPS, serverless-platvorm või mõne kliendiagendi kõrval. Mintbot ei majuta poodi.

Näidisportaal on väike (paarsada rida FastAPI-t) ja README juhatab ümberbrändimise läbi iga puutepunkti — .env konfiguratsioon, CSS-muutujad, tekst, tõlked. Forki see, vaheta sisse oma bränd ja majuta enda domeenil.

Otsast-otsani deploy voog¶

Mis tegelikult juhtub, kui klient klikib sinu poes Osta:

1. Klient ⟶ POST /buy sinu poes
                │
                ▼
2. Pood ⟶ POST /api/v1/orders MintOffice'ile (sinu API võtmega)
                │       tagastab checkout_url
                ▼
3. Klient ⟶ Stripe Checkout (mintboti Stripe'i konto)
                │
                ▼
4. Stripe webhook ⟶ MintOffice märgib tellimuse makstuks
                │       saadab order.paid webhook'i sinu portaali
                │       lisab deploy-töö järjekorda
                ▼
5. Deploy worker ⟶ käivitab VPS-i
                ⟶ jooksutab täie standardse deploy (white-label baasagent)
                ⟶ loob DNS A-kirje sinu Zone.ee mandaatidega
                ⟶ väljastab Let's Encrypt sertifikaadi
                ⟶ ootab, kuni agent on terve
                │
                ▼
6. Agendi VPS ⟶ kloonib sinu Agent customization repo (URL-i renderdab keskne)
             ⟶ jooksutab install.sh üks kord, agendi enda VPS-is
             ⟶ rakendab sinu persona / teema / lisatööriistad peale
             │   (ebaõnnestuv või puuduv skript logitakse, pole kunagi fataalne)
             ▼
7. agent.ready webhook ⟶ toimetatakse sinu portaali
                       ⟶ saadetakse bränditud üleandmise e-kiri (pigeon@mintbot.ai)
                       ⟶ klient saab avada https://agent1.sinubränd.com

Sammud 2 ja 4 toimuvad üle Brand Partner API. Samm 5 on täielikult MintOffice'i sees — sinu pood ei pea teadma, kuidas VPS või Let's Encrypt töötavad. Samm 6 jooksutab sinu koodi agendi enda VPS-is; keskne ei käivita seda kunagi. Igal juhul saab sinu pood lihtsalt kätte elutsükli sündmused.

Jooksvad uuendused¶

Pärast käivitamist uuendab iga agent oma baaspaketti upstream-rütmis. Järjekord on fikseeritud:

1. Agendi VPS ⟶ rakendab kõigepealt uue baaspaketi uuenduse
              │   (white-label baasagent)
              ▼
2. Agendi VPS ⟶ jooksutab peale sinu Agent customization repo update.sh
              │   rakendab / kohandab sinu kihti uue baasi vastu
              ▼
   (update.sh on valikuline; ebaõnnestuv või puuduv skript logitakse,
    ei blokeeri ega pööra baasiuuendust tagasi, ei lõhu agenti)

Brand Partner API¶

REST-pind, mille MintOffice avab sinu poele (ja muudele sinu integratsioonidele), elab omal lehel:

Brand Partner API viide

Kiire mõttemudel:

Autentimine — Authorization: Bearer ***. Üks võti partneri kohta; roteeri Settings → API access alt.
Kirjutamised on idempotentsed — iga POST võtab Idempotency-Key päise; sama võtmega uuesti proovides korratakse algset vastust.
Lugemised on odavad — GET /api/v1/settings tagastab kogu sinu mittesaladusliku konfiguratsiooni (režiimid, apex-domeen, hinnastus, valmidus) sinu poe või paigaldaja-agendi jaoks.
Elutsüklit juhivad webhook'id — order.created, order.paid, agent.ready, agent.failed, agent.expired. HMAC-SHA256 allkirjastatud, kuni 7 kordusproovi.
DNS on proksitud — POST /api/v1/dns/records upsertib A-kirje sinu apexil ilma et sinu portaal kunagi hoiaks upstream-pakkuja API võtit. MintOffice hoiab Zone.ee mandaadi serveripoolel krüpteeritult ja teeb upstream-kutse sinu nimel.

Mida omab MintOffice vs. mida omad sina¶

Kiire viide küsimusele "kus see fakt elab ja kes saab seda muuta":

Fakt / vara	Elab kus	Sa saad seda muuta läbi
Kliendi paketihinnad	MintOffice DB	Töölaud → Settings → Pricing
Agendi persona (SOUL.md)	Sinu Agent customization repo, rakendatud VPS-is `install.sh` / `update.sh` poolt	Pushi hoidlasse
Paneeli teema (CSS / JS)	Sinu Agent customization repo, rakendatud VPS-is `install.sh` / `update.sh` poolt	Pushi hoidlasse
Poe tekst, paigutus, paketikaardid	Sinu poe hoidla	Pushi ja deployi oma portaal uuesti
Kliendile nähtav brändinimi e-kirjades	MintOffice (juhitud `product_name`-ist tellimuse kohta, sinu apex tagavaraks)	Sea tellimuse kohta `POST /api/v1/orders`-il
Telegrami boti token, Zone.ee API võti	MintOffice'i saladuste varamu (krüpteeritud)	Töölaud → Settings → Domain / Bot
Stripe API integratsioon	MintOffice (mintboti Stripe'i konto)	Pole partneri seadistatav
Kliendi töötav agent (SOUL.md, config)	Agendi enda VPS	Agent ise (pärast esmast seemnestamist)
Tuluraamat	MintOffice DB	Ainult lugemiseks `GET /api/v1/revenue` kaudu

Agent-VPS-esmane jaotus on oluline: keskne deployb standardse baasagendi ja astub tagasi. Sinu persona ja teema rakendatakse VPS-is sinu enda install.sh poolt (ja rakendatakse uuesti update.sh-iga pärast iga baasiuuendust) — keskne ei küpseta neid kunagi sisse. Sealt edasi omab agent oma SOUL.md-d ja config.yaml-i: klient võib vabalt paluda oma agendil personat muuta, BYOK-võti seada, mudelit vahetada — ilma et puudutaks sinu Agent customization repo't või sinu poodi.

Kuhu siit edasi¶

Oled operaator, kes seab üles oma partnerikontot — alusta MintOffice — Ülevaade lehega. See juhatab läbi töölaua nõustaja samm-sammult.
Ehitad integratsiooni — alusta Brand Partner API viitest, seejärel klooni partner-portal-example töötava lähtealusena.
Brändid agenti ennast ümber — forki agent-template, millel on juba install.sh / update.sh juurkaustas pluss teema ja persona varad. Vaheta sisse oma bränding, pushi ja suuna nõustaja oma forki HTTPS-URL-ile.
Tahad näha seda kõike töötamas — agent99.cc on elav mintbot.dev partner. Tee seal testtellimus, et näha sama voogu, mille ise üles sead.