MintOffice — tehniline¶

Tehniline kaasleht MintOffice'i operaatorijuhendile. Operaatorijuhend viib sind läbi töölaua nõustaja; see leht on mõeldud arendajale: millised hoidlad sulle kuuluvad, mida igaüks neist juhib ja kuidas kliendi „Osta“-klõpsust saab sinu enda domeenil töötav agent.

kohandusmall partner-portal-example Brand Partner API viide

Kuidas tükid kokku sobivad¶

White-label MintOffice'i seadistus koosneb kolmest kihist, mis kuuluvad kolmele eri osapoolele:

┌──────────────────────────┐   ┌──────────────────────────┐   ┌──────────────────────────┐
│  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“-klõpsu, edastab tellimuse MintOffice'ile ja võtab vastu webhooki sündmused. Sina teed näidisest forki, brändid selle ja majutad oma domeenil.
MintOffice'i keskne osa — töötab aadressil mint.mintbot.ai. Selle käes on Brand Partner API, Stripe'i integratsioon, partneripõhine saladuste hoidla (Telegrami boti token, Zone.ee API võti, …), deploy worker ja tuluraamat. mintbot käitab seda kõigi partnerite jaoks; sina ei käivita seda kunagi ise.
Iga kliendi agent — privaatserver, mille deploy worker käivitab, kui tellimus on makstud. Keskne osa paigaldab ise standardse, brändita baasagendi; seejärel kloonib VPS sinu Agent customization repo ja käivitab selle kohapeal, et rakendada sinu persona, paneeli teema ja lisatööriistad. Keskne osa ei käivita sinu hoidlat kunagi — seda teeb ainult agendi enda VPS. Klient suhtleb sinu Telegrami boti või veebipaneeli kaudu sinu peadomeeni alamdomeenil (agent1.sinubränd.com).

Kaks hoidlat, mis sulle kuuluvad¶

White-label bränding elab kahes eraldi hoidlas, kummalgi oma ülesanne. Sina omad ja majutad neid teineteisest sõltumatult, sellises rütmis, 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 kliendipõhiseid seadistusi, mille tahad baasagendi peale kihina lisada. Erinevalt vanast „malli forkimise“ mudelist ei klooni ega käivita keskne osa seda hoidlat kunagi. Selle asemel teeb keskne osa ise täieliku standardpaigalduse ja seejärel kloonib agendi enda VPS sinu hoidla ja käivitab selle kohapeal — 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 hoidlate nimekirja ega keskset „sisseküpsetamise“ sammu.
Lähtepunkt	`mintbot-ai/agent-template` — forkimiseks valmis näidishoidla. Juurkaustas on `install.sh` / `update.sh` pluss `theme/` (paneeli CSS/JS) ja `persona/` (brändi hääl) varad ning abifunktsioonidega `lib/common.sh`. Tuleb kaasa kohatäitebrändiga ExampleAI, mille sina ümber nimetad. Tee fork, 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 osa renderdab URL-i agendi VPS-i keskkonda; VPS teeb `git clone`, kui standardpaigaldus on terve.
Tõrgete eest isoleeritud	Puuduv, vigane või aeglane skript ei nurja kunagi paigaldust, ei blokeeri baaspaketi uuendust ega lõhu kliendi agenti. Tõrked logitakse VPS-is ja tuuakse sinuni — lõppkliendini need kunagi ei jõua.

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

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

install.sh — käivitatakse üks kord, agendi enda VPS-is, pärast seda, kui standardpaigaldus on lõppenud ja agent on terve. Siin paigaldad oma kohanduse: lisad teema, kohandad personat, registreerid lisatööriistad, teed kliendipõhise seadistuse. Agent on selle jooksmise ajal juba elus ja teenindab; install.sh lisab sinu brändi kihina peale.
update.sh — käivitatakse pärast iga paketiuuendust VPS-is. Valikuline. Kui agent uuendab ise oma baaspaketti, käivitab ta seejärel sinu update.sh, et saaksid oma kihi uue baasi peale uuesti rakendada või kohandada. Jäta fail ära, kui sinu kohandus jääb baasiuuenduste järel niigi puutumata.

Uuenduste järjekord

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

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

Kohandusskriptid käivitatakse parima püüde põhimõttel ja need on allkirjastatud baasist täielikult eraldatud. Kui install.sh või update.sh puudub, annab vea või jookseb aeglaselt:

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

Keskseid „lepingu teste“ ega katkestatud paigaldusi pole, sest keskne osa ei käivita kunagi sinu koodi. Hind selle eest: katkine skript jätab agendi vaikselt tavalise baasi peale sinu bränditud kihi asemel, seega testi oma hoidlat DEV-deploy'ga, enne kui suunad sellele päris agendid.

Turvalisus — see on sinu vastutusala

Keskne osa ei käivita sinu hoidlat kunagi. Ainult agendi enda VPS kloonib ja käivitab selle, samade õigustega, millega agent ise sellel masinal töötab (sinu skriptid jooksevad sinu kliendi enda VPS-is, mitte jagatud taristul). Hoidla URL võib olla ainult GitHubi HTTPS ja see valideeritakse enne salvestamist; kloon on madal, mahu- ja ajapiiranguga ning sinu skriptid käivitatakse ajalimiidiga ja ilma saladusteta keskkonnas. Kõik, mida sinu skriptid teevad, on sinu enda vastutusalas — selgelt eraldatud allkirjastatud baaspaketist, mida juhib keskne osa. Kuna lõppkasutajad ei tohi kunagi näha aluseks olevat baasbrändi, hoia oma persona ja teema mintboti brändist vabad ning esita ainult oma brändi.

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

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


Näidishoidla	`mintbot-ai/partner-portal-example` — MIT-litsentsiga FastAPI + SQLite, dokkerdatud, tuleb kaasa ExampleAI brändiga, mille sina välja vahetad. Sisaldab maandumislehte, `/buy`-vormi, tänu-/tühistuslehti, allkirjastatud webhookide vastuvõtjat ja HTTP Basic -autentimisega `/admin` sündmuste sirvijat.
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`-faili.
Sina majutad	Ükskõik kus, kus on HTTPS — sinu enda VPS, serverless-platvorm või mõne oma kliendiagendi kõrval. mintbot poodi ei majuta.

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

Paigaldusvoog otsast lõpuni¶

Mis tegelikult juhtub, kui klient klõpsab 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'i webhook ⟶ MintOffice märgib tellimuse makstuks
                │       saadab order.paid webhooki sinu portaali
                │       lisab deploy-töö järjekorda
                ▼
5. Deploy worker ⟶ käivitab VPS-i
                ⟶ teeb täieliku standardpaigalduse (white-label baasagent)
                ⟶ loob DNS-i A-kirje sinu Zone.ee tunnustega
                ⟶ väljastab Let's Encrypti sertifikaadi
                ⟶ ootab, kuni agent on terve
                │
                ▼
6. Agendi VPS ⟶ kloonib sinu Agent customization repo (URL-i renderdab keskne osa)
             ⟶ käivitab install.sh üks kord, agendi enda VPS-is
             ⟶ rakendab sinu persona / teema / lisatööriistad peale
             │   (vigane või puuduv skript logitakse, pole kunagi fataalne)
             ▼
7. agent.ready webhook ⟶ toimetatakse sinu portaali
                       ⟶ saadetakse bränditud üleandmiskiri (pigeon@mintbot.ai)
                       ⟶ klient saab avada https://agent1.sinubränd.com

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

Jooksvad uuendused¶

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

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

Brand Partner API¶

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

Brand Partner API viide

Kiire mõttemudel:

Autentimine — Authorization: Bearer mo_live_…. Üks võti partneri kohta; roteeri jaotises Settings → API access.
Kirjutamised on idempotentsed — iga POST võtab Idempotency-Key päise; sama võtmega korduskatse esitab uuesti algse vastuse.
Lugemised on odavad — GET /api/v1/settings tagastab kogu sinu mittesalajase konfiguratsiooni (režiimid, peadomeen, hinnad, valmidus) sinu poe või paigaldaja-agendi tarbeks.
Elutsüklit juhivad webhookid — order.created, order.paid, agent.ready, agent.failed, agent.expired. HMAC-SHA256-ga allkirjastatud, kuni 7 korduskatset.
DNS käib läbi proksi — POST /api/v1/dns/records loob või uuendab A-kirje sinu peadomeenil, ilma et sinu portaal hoiaks kunagi DNS-pakkuja API võtit. MintOffice hoiab Zone.ee tunnuseid serveri poolel krüpteeritult ja teeb pakkuja poole päringu sinu nimel.

Mis kuulub MintOffice'ile ja mis sulle¶

Kiirviide küsimusele „kus see fakt elab ja kes saab seda muuta“:

Fakt / vara	Kus elab	Kuidas sina seda muudad
Kliendi paketihinnad	MintOffice'i andmebaas	Töölaud → Settings → Pricing
Agendi persona (SOUL.md)	Sinu Agent customization repo, rakendab VPS-is `install.sh` / `update.sh`	Pushi hoidlasse
Paneeli teema (CSS / JS)	Sinu Agent customization repo, rakendab VPS-is `install.sh` / `update.sh`	Pushi hoidlasse
Poe tekstid, paigutus, paketikaardid	Sinu poe hoidla	Pushi ja paigalda oma portaal uuesti
Kliendile nähtav brändinimi e-kirjades	MintOffice (tuleneb tellimuse `product_name`-ist, varuks sinu peadomeen)	Määra tellimuse kaupa `POST /api/v1/orders` päringus
Telegrami boti token, Zone.ee API võti	MintOffice'i saladuste hoidla (krüpteeritud)	Töölaud → Settings → Domain / Bot
Stripe'i API integratsioon	MintOffice (mintboti Stripe'i konto)	Partner ei saa seadistada
Kliendi töötav agent (SOUL.md, config)	Agendi enda VPS	Agent ise (pärast esmast seemnestamist)
Tuluraamat	MintOffice'i andmebaas	Ainult lugemiseks `GET /api/v1/revenue` kaudu

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

Kuhu siit edasi¶

Oled operaator, kes seab üles oma partnerikontot — alusta lehest MintOffice — ülevaade. See juhatab samm-sammult läbi töölaua nõustaja.
Ehitad integratsiooni — alusta Brand Partner API viitest, seejärel klooni partner-portal-example töötava lähtealusena.
Brändid agenti ennast ümber — tee fork hoidlast agent-template, mille juurkaustas on juba install.sh / update.sh 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 töötav mintbot.dev partner. Tee seal testtellimus, et näha sama voogu, mille ise üles sead.