128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
# MaalFlows Agent
|
|
|
|
Purpose: maintain the MaalFlows live chat widget and admin app.
|
|
|
|
## Project Shape
|
|
|
|
- Main application file: `server.js`.
|
|
- Frontend assets: `public/widget.js`, `public/admin.js`, `public/admin.css`, `public/admin.html`.
|
|
- Runtime: Node.js without a framework, SQLite through `better-sqlite3`.
|
|
- Local check command: `npm.cmd run check`.
|
|
- Production app is proxied by nginx on `app.black-week.cz` to `127.0.0.1:3400`.
|
|
|
|
## Work Rules
|
|
|
|
- Read the relevant code before editing.
|
|
- Keep changes small and focused on the user's request.
|
|
- Do not touch `.agents/sogo-mail-filter-agent.md` or `docs/mail-sogo-*` files unless the task is explicitly about SOGo mail filters.
|
|
- Preserve existing user changes. Do not reset, checkout, or delete unrelated work.
|
|
- For language/translation changes, protect conversation-level customer language from short greetings, product names, SKUs, colors, and other language-neutral text.
|
|
|
|
## Verification
|
|
|
|
Before finishing a code change, run:
|
|
|
|
```powershell
|
|
npm.cmd run verify
|
|
```
|
|
|
|
`verify` runs syntax checks, Tailwind CSS build, and Playwright UI smoke tests. If the change is documentation-only, `npm.cmd run check` is sufficient, but say that explicitly.
|
|
|
|
For any meaningful layout or styling change:
|
|
|
|
- Start or let Playwright start the local server.
|
|
- Use Playwright for visual inspection instead of judging only from code.
|
|
- Check at least desktop and mobile viewports when the UI surface can appear on both.
|
|
- Inspect screenshots for overlap, broken spacing, unreadable text, and inconsistent controls.
|
|
- Keep normal Playwright runs headless. Use headed/visible browser only while diagnosing a UI or scraping/browser-automation failure.
|
|
- If browser automation is added for external sources, choose the browser engine from source configuration, behave slowly and politely, and do not use Playwright to bypass site protections.
|
|
|
|
Playwright scripts:
|
|
|
|
```powershell
|
|
npm.cmd run test:ui
|
|
npm.cmd run test:ui:headed
|
|
```
|
|
|
|
Playwright screenshots and reports are ignored by Git.
|
|
|
|
## TailwindCSS
|
|
|
|
TailwindCSS is the main styling system for new and refactored UI. The source file is `src/styles/tailwind.css`, built to `public/tailwind.css` with:
|
|
|
|
```powershell
|
|
npm.cmd run build:css
|
|
```
|
|
|
|
Rules:
|
|
|
|
- Prefer reusable Tailwind component classes in `@layer components` over one-off CSS for repeated controls.
|
|
- Repeated controls should share the same structure: icon before text, centered text, chevron on the right, consistent icon size/color/alignment, height, padding, border, radius, hover, and focus states.
|
|
- Panel top bars should share height, border, background, text color, and button styling.
|
|
- If a master style exists, extend it instead of creating a second variant of the same control.
|
|
- Dark/light theme changes must apply consistently to sidebars, panels, tables/grids, modals, inputs, and controls.
|
|
- Data-heavy UI should stay compact, scannable, responsive, and avoid an Excel-like look unless explicitly required.
|
|
- Wide data workspaces should allow horizontal scrolling when content is wider than the viewport.
|
|
- Before finishing a UI component change, check similar components for style consistency.
|
|
|
|
## Git Workflow
|
|
|
|
Project remote:
|
|
|
|
```text
|
|
https://git.ma-al.com/rajch_ales/MaalFlows.git
|
|
```
|
|
|
|
The main branch is `main`.
|
|
|
|
After each completed project code change:
|
|
|
|
1. Review `git diff`.
|
|
2. Stage only files that belong to the change.
|
|
3. Commit with a concise message.
|
|
4. Push the current branch to `origin`.
|
|
5. Report what was changed, what was verified, and whether the push succeeded.
|
|
|
|
Do not stage unrelated untracked files such as historical audits, screenshots, exports, or mail-filter documentation unless the user explicitly asks for them.
|
|
|
|
If Git authentication is needed, this project follows the same HTTPS credential style as `D:\Codex\01-projekty\catalog-meaker-by-magic-ai`: read `GIT_USERNAME` and `GIT_PASSWORD` from that project's local `.env` only for the command that needs them. Never print those values, commit them, save them into `origin`, or leave credentials embedded in Git config.
|
|
|
|
## Production Update
|
|
|
|
After a successful push, update the production server.
|
|
|
|
Production details:
|
|
|
|
```text
|
|
Host: app.black-week.cz
|
|
SSH user: root
|
|
SSH key: C:/Users/DELL/.ssh/druhakapitola_hetzner
|
|
App directory: /var/www/maalflows
|
|
PM2 process: maalflows
|
|
Public URL: https://app.black-week.cz/admin
|
|
```
|
|
|
|
Deploy workflow:
|
|
|
|
1. SSH to `root@app.black-week.cz` with the `druhakapitola_hetzner` key.
|
|
2. In `/var/www/maalflows`, check `git status --short` first. Stop if there are unexpected local changes.
|
|
3. Ensure server `origin` is `https://git.ma-al.com/rajch_ales/MaalFlows.git`.
|
|
4. Fetch `origin main`. If HTTPS credentials are required, provide them via a one-command temporary credential helper from the local catalog project's `.env`; do not store credentials on the server.
|
|
5. Run `git merge --ff-only FETCH_HEAD`.
|
|
6. Run `npm install --omit=dev`.
|
|
7. Run `npm run check`.
|
|
8. Run `pm2 restart maalflows`.
|
|
9. Run `pm2 save`.
|
|
10. Verify:
|
|
|
|
```bash
|
|
cd /var/www/maalflows && git status --short
|
|
cd /var/www/maalflows && git log -1 --oneline
|
|
pm2 describe maalflows
|
|
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://127.0.0.1:3400/admin
|
|
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://127.0.0.1:3400/widget.js
|
|
curl -k -s -o /dev/null -w '%{http_code} %{content_type}\n' https://app.black-week.cz/admin
|
|
```
|
|
|
|
Expected verification: PM2 status `online`, local `/admin` and `/widget.js` return `200`, public HTTPS `/admin` returns `200`, and the server worktree is clean.
|