Admin építése 61ade-vel: mezőleírások és saját műveletek

A 61ade a saját PHP- és TypeScript-alapú keretrendszerem webes adminfelületek építéséhez. A forrása ingyenesen elérhető a GitHubon. A DHTMLX-alapú felülethez belépést, jogosultságkezelést, kereshető listákat és szerkesztőűrlapokat ad; az alkalmazás adatait, mezőit és műveleteit PHP-ban vagy moduláris JSON-ban lehet leírni.

Egy névjegytár megépítésén mutatom meg, hogyan lehet ezekből az elemekből saját admint készíteni. A példában a közös mezőleírásból kereshető lista és szerkesztőűrlap készül, mellé CSV-importot és -exportot kapcsolunk. Az alkalmazást a Codexszel építtettem meg; alább a feladatprompt, a lényeges kódrészletek és a kipróbálható demó is elérhető.

Közös mezőleírás a listához és az űrlaphoz

A névjegytárhoz meg kellett adni a mezőket: név, e-mail-cím, telefon, cég, település, cím és megjegyzés. A 61ade-ben ugyanaz a mezőleírás szolgálja ki a listát és az adatlapot. A példa tényleges kódjából három mező:

new Field('name', 'Név', required: true, max: 120,
    column: ['minWidth' => 190]),
new Field('phone', 'Telefon', max: 40,
    column: ['width' => 155]),
new Field('city', 'Város', max: 100,
    column: ['width' => 140]),

A SqlResource ezt a leírást kapcsolja az adatbázis kontaktokat tároló táblájához. A mezők felirata, hosszkorlátja és kötelezősége közös definícióból származik; a táblázat és az űrlap megjelenítését a könyvtár intézi. Az agentnek nem kellett külön táblázatkomponenst, szerkesztőablakot és azokhoz saját mentési mechanizmust készítenie. A keresés, az oszlopszűrés és a rendezés is a meglévő listanézet része.

Ez egy másik adminnál is használható kiindulás. Egy eszköznyilvántartóban például a névjegy mezőit leltári szám, típus és állapot váltaná fel. Az adattáblát, a mezőleírást és a hozzájuk tartozó szabályokat kellene kialakítani; a lista és a szerkesztő közös alapját továbbra is a 61ade adná.

A prompt és a fejlesztési környezet

A feladathoz a 61ade könyvtára és dokumentációja, a használatához készült skillek és egy működő PHP-környezet is rendelkezésre állt. A feladat külön előírta, hogy ezek alapján dolgozzon, és a könyvtár meglévő felületeit használja. Így a belépés, a jogosultságkezelés vagy a fájlfeltöltés megoldását már adott rendszerhez kellett illesztenie.

A promptban az alkalmazás döntéseit rögzítettük: mely mezők kötelezők, mitől egyedi egy névjegy, és mi történjen importáláskor. Az ismert e-mail-cím frissítést, az új cím új rekordot jelent; hibás sor esetén a címlista maradjon változatlan. Ezekből az elvárásokból az agent meg tudta írni a saját kezelőket, és ugyanazokból az elvárásokból ellenőrizni is tudta az eredményt.

Az alábbi az eredeti, angol nyelvű feladatprompt. A környezetre vonatkozó része ehhez a projekthez tartozik; máshol a könyvtár, az adatkönyvtár és a tesztcím helyét hozzá kell igazítani. Olyan agent szükséges hozzá, amely forrást olvas, fájlokat módosít, parancsokat és böngészős próbákat futtat.

Relevant shared rules: Establish the working context; Project and platform boundaries; Placement and data handling; Project URLs; Minimal implementation; Implementation, validation and completion.

Build a working Hungarian contact-register demo with the existing 61ade library in this PHP project. Read the project's AGENTS.md and 61ade's 61ade-consumer and 61ade-application skills first. Use the library's actual documented APIs and existing examples; do not change the library.

Environment: the application belongs in public/contact-demo/ in the sanch.hu project. Keep private PHP implementation outside the public webroot, under includes/contact-demo/. The read-only library is /space/share/libs/61ade; link only packages/php outside the public webroot and packages/frontend/dist in a dedicated public assets directory. All SQLite files and persistent demo state belong under /space/share/data/sanch.hu/contact-demo/. Use the managed development URL https://dev.sanch.hu/contact-demo/. Do not deploy or change server configuration.

The application must do the following:
- Use 61ade's sign-in, shell, table, forms, validation, registered actions and permission checks. Do not build a second admin framework or a separate login system.
- Provide a Hungarian contact list with search, column filters, sorting, creation, editing and deletion. Fields: name (required), email (required, valid and unique ignoring case), phone, company, city, postal address, notes. Give the app a clear Hungarian name and useful empty/error states.
- Import a UTF-8 CSV file with the columns name,email,phone,company,city,address,notes. Accept a UTF-8 BOM and comma or semicolon separators. Validate the whole file before writing; on error report row numbers and leave the address book unchanged. Update matching email addresses and insert new ones. Show inserted/updated counts. Limit imports to 1 MiB and 1000 contacts. Reject ambiguous headers, malformed rows, duplicate emails within a file and invalid email addresses. Use a transaction and the framework's registered-action authorization/audit path.
- Export the current address book as a downloadable UTF-8 CSV with the same columns and BOM. Properly quote values and neutralize spreadsheet formulas. Make the export importable again; document any deliberate neutralization of unsafe cell values. Provide a downloadable sample CSV with clearly fictitious Hungarian contacts at reserved example.test email addresses.
- This is a publicly linked practice demo, not a shared real address book. Each visitor gets an independent SQLite copy of a prepared sample database; the SQLite file and session state remain outside the webroot. Use the 61ade demo login demo@example.test / 61ade-demo, with only contact-management permissions, and display these public demo credentials on sign-in. Explain briefly in Hungarian that the data is temporary and only fictional contacts should be used. Expire abandoned workspaces after 24 hours, with bounded cleanup and safe handling of active workspaces. Do not run schema migrations in HTTP requests: prepare the template explicitly from CLI, then copy it for visitors.
- Keep all server operations behind framework authorization and CSRF protection. Bound inputs and escape displayed values. Never expose private data, secrets, whole library source trees or SQLite files through public links.
- Use supported 61ade components and extension points for the import/export UI. If generic CSV tooling is missing, implement the smallest contact-specific registered handlers and project module, record this boundary, and report actual framework defects separately without patching 61ade.

Finish the implementation, initialize the demo data, and exercise it with Playwright on the managed development URL. Verify sign-in, CRUD, valid CSV import, rejected CSV with no partial writes, duplicate-email behavior, export/re-import, Unicode/quoted cells, spreadsheet-formula neutralization, unauthorized access, and isolation between two browser sessions. Fix application defects and rerun the affected checks. Preserve existing unrelated work. Record the exact checks, limitations and actual framework issues in the project's documentation. Retain a short setup/run guide and the sample CSV. Report what the library supplied and what application code you had to write; do not invent a time saving or claim the first attempt passed if corrections were needed. Do not deploy.

A névjegytár feladatleírása

A feladat: a 61ade kipróbálása egy névjegytár megépítésével.

CSV-import és -export a 61ade műveleteivel

A CSV-import és -export megmutatja, hogyan bővíthető ez az alap. A névjegyek beolvasási szabályaihoz saját kód készült, a műveleteket viszont a 61ade-ben regisztráltuk. A fájlt a könyvtár feltöltője veszi át, a végrehajtás a közös jogosultságellenőrzésen és naplózáson keresztül fut, az import tranzakciót használ. Az export a könyvtár letöltési válaszával adja vissza a kész fájlt.

Az alkalmazás saját része így jól körülírható: az adattábla és a mezők, az e-mail-címek egyedisége, a CSV feldolgozása, valamint a nyilvános demó látogatóinak külön ideiglenes adatbázisa. A 61ade forrásához ezek miatt nem kellett hozzányúlni. Nekem ez a példa legerősebb része: a kész adminfunkciók mellé a feladatra szabott működés is ugyanabban a rendszerben fér el.

Névjegykezelés, CSV-próbák és demó

A megvalósítás után a Codex Playwrighttal ellenőrizte a belépést, a névjegyek létrehozását, szerkesztését és törlését, a keresést és a szűrést. Az importpróbában egy fájl egy meglévő rekordot frissített, egy újat létrehozott. Egy másik, hibás sort tartalmazó fájlt a rendszer teljes egészében elutasított, és a címlista változatlan maradt. Az exportot, a visszaimportálást és két látogató adatainak elkülönítését is ellenőrizte.

A próbák közben javítani kellett az alkalmazás CSV-hibajelzésein, egységesíteni az import és az űrlap e-mail-ellenőrzését, valamint rendezni a demó fájlhozzáférését és munkamenet-kezelését. A végső, célzott Playwright-futtatás mind a négy tesztesete sikeres lett. Ebben a megvalósításban igazolt keretrendszerhibát nem találtunk.

A 61ade-vel elkészített példaalkalmazás kipróbálása
Belépés: demo@example.test / 61ade-demo. A fejlesztői demó minden látogatónak külön, ideiglenes címlistát ad; fiktív adatokat használj benne. A Minta CSV letöltése és visszaimportálása a négy kezdő rekordnál 0 új, 4 frissített eredményt ad. Az export a táblázatkezelőben képletként értelmezhető cellákat aposztróffal védi; ez visszaimportáláskor is megmarad, a + jellel kezdődő telefonszámoknál is.