@rglabs/butterfly 2.0.1 → 2.1.0

package/.claude/commands/docs-page-layout.md

@@ -0,0 +1,12 @@
+Read the page layout documentation from docs/page-layout.md.
+
+Provide guidance on organizing object add/edit page layouts including:
+- Creating and managing object_tabs (groups/tabs)
+- Creating object_sections (higher-level grouping)
+- Assigning fields to tabs via edit_place_no
+- Field positioning (edit_position, edit_order_no)
+- Column sizes (left_column_size, column_size)
+- Bulk layout ordering via API or butterfly-cli layout command
+- section_title for visual section headers within tabs
+
+Focus on the specific layout task the user asks about, or provide an overview if no specific task is mentioned.

package/CLAUDE.md

@@ -109,6 +109,46 @@ See [docs/translations.md](docs/translations.md) for full documentation.
 
 See [docs/twig-helpers.md](docs/twig-helpers.md) for full documentation.
 
+## Email Sending (Quick Reference)
+
+```twig
+{# Send email directly #}
+{{ sendEmail('recipient@example.com', 'Subject', '<p>HTML body</p>') }}
+
+{# Send using cms_email_templates (recommended pattern) #}
+{% set tpl = db().table('cms_email_templates').where('alias', 'template-alias').first() %}
+{% set replacements = {} %}
+{% for key, val in vars %}
+  {% set replacements = replacements|merge({('{{ ' ~ key ~ ' }}'): val}) %}
+{% endfor %}
+{{ sendEmail(recipient, tpl.subject|replace(replacements), tpl.content|replace(replacements)) }}
+```
+
+**Email Templates (`cms_email_templates`):**
+- Store HTML email templates with `{{ variable_name }}` placeholders in subject and content
+- Use `alias` field for programmatic lookup
+- `test_data` field: JSON with sample values for preview
+- `preview` field: calculated field that renders content with test_data, shown in edit page
+- Templates should use **inline CSS** (not classes) for email client compatibility
+- Link to state machine via `bfy_state_machine_id` for organization
+
+**Important:** Twig `|replace` filter requires a **mapping** (associative array), NOT individual string arguments. Build replacements map with `|merge`.
+
+## Settings (Quick Reference)
+
+```twig
+{# Get single setting value #}
+{% set value = setting('group_alias', 'setting_alias') %}
+
+{# Get all settings in a group #}
+{% set all = setting('group_alias') %}
+{{ all.setting_alias.value }}
+```
+
+**Tables:** `cms_setting_groups` (groups by alias) → `cms_settings` (individual settings)
+
+See [docs/twig-helpers.md](docs/twig-helpers.md#settings) for full documentation.
+
 ## JavaScript Field Updates (Quick Reference)
 
 | Field Types | Method |
@@ -124,13 +164,34 @@ See [docs/object-specs/js-field-updates.md](docs/object-specs/js-field-updates.m
 /admin/SINGULAR_TABLE_NAME/list
 /admin/SINGULAR_TABLE_NAME/add
 /admin/SINGULAR_TABLE_NAME/edit/ID
+/admin/cms_report/view/REPORT_ID
 ```
 
 For non-default database: `/admin/DATABASE_ALIAS/SINGULAR_TABLE_NAME/...`
 
 ## Object Menu Placement
 
-Format: `MainMenu>SubMenu>MenuItemName` or with icons: `MainMenu::icon>SubMenu::icon>Item::icon`
+Admin menus have 3 levels. Levels 1-2 are created in `cms_admin_menus`, level 3 is set on the object itself.
+
+### Step 1: Create Main Menu (Level 1) and Sub Menu (Level 2) in `cms_admin_menus`
+
+```bash
+# Level 1 - Main menu
+butterfly-cli record add cms_admin_menus --data '{"title":"Menu Name","parent_id":0,"icon":"b-icon-icon-name"}'
+# Returns ID, e.g. 67
+
+# Level 2 - Sub menu (parent_id = main menu ID)
+butterfly-cli record add cms_admin_menus --data '{"title":"Sub Menu","parent_id":67,"icon":"b-icon-icon-name"}'
+# Returns ID, e.g. 68
+```
+
+### Step 2: Assign Object to Menu (Level 3) via `main_menu_id` + `sub_menu_id`
+
+```bash
+butterfly-cli record edit objects --id <object_id> --data '{"main_menu_id":<main_menu_id>,"sub_menu_id":<sub_menu_id>}'
+```
+
+**Do NOT** create level 3 entries in `cms_admin_menus`. The object itself becomes the menu item when `main_menu_id` and `sub_menu_id` are set.
 
 ## Object Default Permissions
 
@@ -159,6 +220,46 @@ butterfly-cli record add <table_name> --data '{"bfy_workspace_id": <workspace_id
 
 See [docs/workspaces.md](docs/workspaces.md) for full documentation.
 
+## Page Generation Guidelines
+
+When a task requires generating a page:
+
+- **Simple pages** (single table, basic CRUD): Use standard Butterfly object pages.
+- **Complex pages** (multiple table relations, complex design, custom layouts): Use **custom report pages** with Butterfly endpoints and objects for data operations.
+
+### Custom Report Page Approach
+
+For complex pages, create a custom report page with HTML/Twig template and use Butterfly's AJAX endpoints to save/update data:
+
+```
+POST /admin/ajax/cms_object/operation?do=TABLE_NAME__OPERATION
+Content-Type: application/x-www-form-urlencoded; charset=UTF-8
+X-Requested-With: XMLHttpRequest
+```
+
+**Example - saving page data via AJAX:**
+```javascript
+$.ajax({
+    url: '/admin/ajax/cms_object/operation?do=TABLE_NAME__edit',
+    type: 'POST',
+    data: {
+        csrf_token: csrfToken,
+        id: recordId,
+        field1: value1,
+        field2: value2
+    },
+    success: function(response) { /* handle response */ }
+});
+```
+
+**Key points:**
+- Use `?do=TABLE_NAME__add` for creating new records
+- Use `?do=TABLE_NAME__edit` for updating existing records
+- Always include `csrf_token` in the request data
+- Use `X-Requested-With: XMLHttpRequest` header
+- Content type should be `application/x-www-form-urlencoded`
+- For employee/user-related forms, auto-populate fields (department, role, sicil no, location, email) from the `employees` table using the logged-in user context
+
 ## Project-Specific Instructions
 
 Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructions.
@@ -187,6 +288,9 @@ Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructi
 - [docs/bfy-splitting.md](docs/bfy-splitting.md) - BFY file splitting for large files
 - [docs/translations.md](docs/translations.md) - Translations and i18n
 - [docs/WORKFLOW_API.md](docs/WORKFLOW_API.md) - Workflow node types
+- [docs/butterfly_upload_api_docs-2.md](docs/butterfly_upload_api_docs-2.md) - File upload (admin panel & REST API)
+- [docs/pdf-generation.md](docs/pdf-generation.md) - PDF generation from templates
+- [docs/IMPLEMENTATION_PROMPT.md](docs/IMPLEMENTATION_PROMPT.md) - Process module implementation template
 
 **Slash Commands:**
 
@@ -199,3 +303,65 @@ Always check if `docs/PROJECT_SPECIFIC.md` exists and prioritize those instructi
 | `/docs-webservice` | When creating API endpoints or webservices using reports with `custom_seo` |
 
 > **AI INSTRUCTION:** Always use the relevant slash command before working on any task related to that topic. This ensures accurate implementation without guessing syntax or parameters.
+
+## Custom Report Page Best Practices
+
+### Turkish Characters
+Always use proper Turkish characters in UI text (not ASCII equivalents):
+- ç, ş, ü, ö, ğ, ı, İ (not c, s, u, o, g, i, I)
+- Examples: Seçiniz, Bütçe, Açıklama, Bölümü, Görevi, Değişiklikleri, Düzenleme
+
+### Child Record Duplication Prevention
+When a custom report page saves a parent record + child records (e.g., expense items, team members):
+- **On edit/update**: Always **delete existing child records first**, then re-add all current rows. Otherwise each save duplicates all children.
+- **There is NO `delete_where` endpoint.** Delete each record individually: `?do=TABLE__delete` with `id` parameter.
+- Pass existing child record IDs from Twig to JS via `window._data.existingIds` JSON. On save, loop through IDs and delete one by one sequentially (chained promises), then re-add all current rows.
+- **Chain deletes sequentially** (not parallel) to avoid race conditions — use `.then()` chaining.
+- **On add**: Save parent first, get the returned `response.id`, then save children with that ID.
+
+### Reserved Parameter Names
+The following parameter names are reserved by Butterfly and must NOT be used in custom report pages:
+- `id` — reserved by the system (page/report internal ID)
+
+Use alternative names like `form_id`, `record_id`, etc. Example:
+```twig
+{% set editId = getParameter('form_id') %}
+```
+```javascript
+window.location.href = url + '?form_id=' + recordId;
+```
+
+### Current User Access
+- Use `currentUser('field')` to access user fields — NOT `app.user.username` or `app.user.*`.
+- Example: `currentUser('sicil_no')`, `currentUser('id')`, `currentUser('email')`
+
+### Twig Functions That DO NOT Exist
+- `csrf_token()` — does NOT exist in Butterfly Twig. Get CSRF token via JavaScript: `$('meta[name="csrf-token"]').attr('content')`.
+
+### UI Dialog Functions
+- **Deletions/destructive actions**: Use `rg_confirm('message', callback)` instead of native `confirm()`.
+- **Error/info messages**: Use `rg_alert('message')` instead of native `alert()`.
+- Never use native browser `alert()` or `confirm()` dialogs.
+
+### State Machine Transitions
+- The role field on transitions is `bfy_state_machine_role_ids` (plural), NOT `bfy_state_machine_role_id`.
+- Transition display name field is `button_title`, not `name`.
+
+### State Machine `state` Column vs Manual `status`
+- When an object has a `state` type field bound to a state machine, the state machine manages the `state` column automatically.
+- **Do NOT create a separate `status` field** or manually set status values. Use the `state` column everywhere (queries, filters, conditions).
+- State values are the `system_name` from `bfy_state_machine_states` (e.g., `created`, `taslak`, `onay_bekliyor`).
+- In custom report pages, check `record.state` for readonly/edit logic, NOT a manual `status` field.
+- For new records, the state machine auto-assigns the initial state on creation — do not set it manually in JS.
+
+### Rendering Dynamic Table Rows
+- Render existing data rows via JavaScript (from a `window._data` JSON object set in Twig), NOT via Twig `{% for %}` loops in `<tbody>`.
+- This prevents duplication issues: JS owns all row rendering, Twig only provides the initial data as JSON.
+- Pattern: `{% set dataJson = records|json_encode %}` then `<script>window._data = {{ dataJson|raw }};</script>`
+
+### Tailwind CSS for Modern UI
+- Use Tailwind CDN: `<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">`
+- Prefer Tailwind utility classes over custom CSS in report pages.
+
+### Report Download Type
+- Use `butterfly-cli download -t reports` (NOT `-t cms_reports`) to download reports.

package/README.md

@@ -21,8 +21,8 @@ butterfly setup
 # 2. Download all resources
 butterfly download
 
-# 3. Start watching for changes
-butterfly start
+# 3. Upload changes
+butterfly upload <path>
 ```
 
 ## Commands
@@ -84,26 +84,6 @@ butterfly download --cleanup
 
 ---
 
-### `butterfly start`
-
-Watch for local file changes and sync them to the Butterfly platform in real-time.
-
-```bash
-butterfly start
-
-# Custom directory
-butterfly start -o ./my-resources
-```
-
-Supported file types for sync:
-- Object specs (`spec.json`, `code.js`, `style.css`, `*.bfy`, `*.yaml`)
-- Reports (`report.json`, `query.json`, `*.bfy`, `*.js`)
-- Workflows (`workflow.json`, `version.json`, `node.json`, `code.bfy`, `params.yaml`, `connections.json`)
-- AI Tasks (`task.json`, `prompt.twig`, `*.twig`)
-- And more...
-
----
-
 ### `butterfly upload`
 
 Upload specific files or folders to the platform.

package/dist/commands/setup.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import { render, Box, Text } from 'ink';
+import { spawn } from 'child_process';
 import { SetupForm } from '../components/SetupForm.js';
 import { saveAuthConfig } from '../utils/auth.js';
 import { ButterflyAPI } from '../utils/api.js';
@@ -24,7 +25,19 @@ const SetupCommand = ({ onExit }) => {
             }
             await copyDocs();
             setStatus('success');
-            setTimeout(() => onExit(0), 2000);
+            setTimeout(() => {
+                setStatus('downloading');
+                const child = spawn('butterfly-cli', ['download'], {
+                    stdio: 'inherit',
+                    shell: true,
+                });
+                child.on('close', (code) => {
+                    onExit(code || 0);
+                });
+                child.on('error', () => {
+                    onExit(1);
+                });
+            }, 1000);
         }
         catch (error) {
             setErrorMessage(error instanceof Error ? error.message : 'Unknown error');
@@ -36,6 +49,7 @@ const SetupCommand = ({ onExit }) => {
         status === 'input' && React.createElement(SetupForm, { onSubmit: handleSubmit }),
         status === 'testing' && React.createElement(Text, { color: "yellow" }, "Testing connection..."),
         status === 'success' && React.createElement(Text, { color: "green" }, "\u2713 Configuration saved successfully in .butterfly/config.json, docs copied to docs/ and commands to .claude/commands/"),
+        status === 'downloading' && React.createElement(Text, { color: "yellow" }, "Starting download..."),
         status === 'error' && React.createElement(Text, { color: "red" },
             "\u2717 Error: ",
             errorMessage)));

package/dist/commands/view-report.d.ts

@@ -0,0 +1,8 @@
+interface ViewReportOptions {
+    id?: string;
+    alias?: string;
+    raw?: boolean;
+}
+export default function viewReportCommand(options: ViewReportOptions): Promise<void>;
+export {};
+//# sourceMappingURL=view-report.d.ts.map

package/dist/commands/view-report.js

@@ -0,0 +1,89 @@
+import { loadAuthConfig } from '../utils/auth.js';
+import { ButterflyAPI } from '../utils/api.js';
+function stripHtmlToText(html) {
+    let text = html;
+    text = text.replace(/<head[\s\S]*?<\/head>/gi, '');
+    text = text.replace(/<script[\s\S]*?<\/script>/gi, '');
+    text = text.replace(/<style[\s\S]*?<\/style>/gi, '');
+    text = text.replace(/<br\s*\/?>/gi, '\n');
+    text = text.replace(/<hr\s*\/?>/gi, '\n---\n');
+    text = text.replace(/<\/(?:p|div|h[1-6]|li|tr|section|article|header|footer|blockquote)>/gi, '\n');
+    text = text.replace(/<\/(?:th|td)>\s*<(?:th|td)[^>]*>/gi, '\t');
+    text = text.replace(/<[^>]+>/g, '');
+    text = text.replace(/&amp;/g, '&');
+    text = text.replace(/&lt;/g, '<');
+    text = text.replace(/&gt;/g, '>');
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    text = text.replace(/&nbsp;/g, ' ');
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text
+        .split('\n')
+        .map(line => line.trim())
+        .filter((line, i, arr) => {
+        if (line === '')
+            return i > 0 && arr[i - 1] !== '';
+        return true;
+    })
+        .join('\n')
+        .trim();
+    return text;
+}
+export default async function viewReportCommand(options) {
+    try {
+        if (!options.id && !options.alias) {
+            console.error('ERROR: Either --id or --alias is required');
+            process.exit(1);
+        }
+        if (options.id && options.alias) {
+            console.error('ERROR: Cannot use both --id and --alias together');
+            process.exit(1);
+        }
+        const config = await loadAuthConfig();
+        if (!config) {
+            console.error('ERROR: No authentication configured. Run "butterfly-cli setup" first.');
+            process.exit(1);
+        }
+        const api = new ButterflyAPI(config);
+        await api.authenticate();
+        let reportId;
+        if (options.id) {
+            reportId = options.id;
+        }
+        else {
+            const records = await api.fetchTableAdvanced('cms_reports', {
+                column: 'alias',
+                value: options.alias
+            });
+            if (records.length === 0) {
+                console.error(`ERROR: Report not found with alias "${options.alias}"`);
+                process.exit(1);
+            }
+            reportId = records[0].id;
+        }
+        const viewPath = `/admin/cms_report/view/${reportId}?bfy_focus_content=true`;
+        const response = await api.httpClient.get(viewPath, {
+            responseType: 'text',
+            headers: {
+                'Accept': 'text/html'
+            }
+        });
+        const html = response.data;
+        if (!html || html.length === 0) {
+            console.error('ERROR: Empty response from report view');
+            process.exit(1);
+        }
+        if (options.raw) {
+            console.log(html);
+        }
+        else {
+            console.log(stripHtmlToText(html));
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`ERROR: ${error.message}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=view-report.js.map

package/dist/index.js

@@ -12,11 +12,12 @@ import codeCommand from './commands/code.js';
 import layoutCommand from './commands/layout.js';
 import syncDocsCommand from './commands/sync-docs.js';
 import translateCommand from './commands/translate.js';
+import viewReportCommand from './commands/view-report.js';
 config();
 program
     .name('butterfly-cli')
     .description('CLI tool to download resources from the Butterfly platform')
-    .version('2.0.1');
+    .version('2.0.2');
 program
     .command('setup')
     .description('Configure authentication for the Butterfly platform')
@@ -113,5 +114,12 @@ program
     .option('--format <format>', 'Output format: json or table (default: table)')
     .option('--limit <count>', 'Limit number of results')
     .action(translateCommand);
+program
+    .command('view-report')
+    .description('Run a report and display the rendered result')
+    .option('--id <id>', 'Report ID')
+    .option('--alias <alias>', 'Report alias')
+    .option('--raw', 'Output full HTML instead of plain text')
+    .action(viewReportCommand);
 program.parse();
 //# sourceMappingURL=index.js.map

package/docs/IMPLEMENTATION_PROMPT.md

@@ -0,0 +1,252 @@
+# Süreç Yönetimi Modülü - Implementation Prompt
+
+Bu prompt, çok tablolu bir form sistemi, onay akışı (state machine), e-posta bildirimleri, dashboard ve admin menü içeren eksiksiz bir süreç yönetimi modülünü sıfırdan oluşturmak için kullanılır.
+
+---
+
+## Prompt
+
+Aşağıdaki adımları sırasıyla uygula. Her adımda CLAUDE.md'deki kurallara uy. Proje gereksinim dokümanını referans al.
+
+### Faz 1: Object'leri Oluştur
+
+`butterfly-cli record add` ile gereksinim dokümanındaki object'leri ve field'larını oluştur.
+
+**Genel kurallar:**
+- Her object için tablo adı, field'lar ve field tipleri gereksinim dokümanında belirtilir
+- Parent-child ilişkilerinde child tablolarda parent'a `dropdown` tipinde referans field oluştur
+- **`status` alanı oluşturMA** — state machine `state` alanını yönetecek
+- Tarih formatı JS'den custom format gelecekse (`dd.mm.YYYY HH:mm` gibi), `datetime` DEĞİL `string` tipi kullan
+
+### Faz 2: State Machine (Onay Akışı)
+
+Gereksinim dokümanındaki onay akışına göre state machine oluştur.
+
+**Genel yapı:**
+- State'ler: Gereksinime göre tanımla (system_name + görünen ad)
+- Roller: Süreçteki rol gruplarını tanımla
+- Geçişler: From → To, buton adı ve yetkili rol
+
+**ÖNEMLİ:**
+- Transition role alanı `bfy_state_machine_role_ids` (çoğul), `bfy_state_machine_role_id` DEĞİL
+- Transition görünen ad alanı `button_title`, `name` DEĞİL
+
+**Ana object'e `state` tipi field ekle:** `val_1` = state machine ID
+
+### Faz 3: E-posta Şablonları
+
+**`cms_email_templates` nesnesine 2 yeni field ekle:**
+- `test_data` (textarea) — JSON format örnek veri
+- `preview` (calculated) — content + test_data'yı birleştirip önizleme gösteren alan
+
+**Preview calculated kodu:**
+- `test_data` JSON'ını parse et, varsayılan değerlerle birleştir
+- `|replace(replacements)` ile placeholderları değiştir (replace **mapping** alır, string DEĞİL)
+- Subject + body'yi rendered olarak göster
+
+**E-posta şablonlarını oluştur (`cms_email_templates`):**
+- Her state geçişi için uygun şablon tanımla (onay, red, bildirim vb.)
+- Alias formatı: `process-alias-action` (örn: `surec-onay-bekliyor`)
+
+**Şablon içeriği:** Inline CSS ile modern e-posta tasarımı. Değişkenler `{{ variable_name }}` formatında.
+
+**Her geçişin `action_code`'unda:**
+```twig
+{% set tpl = db().table('cms_email_templates').where('alias', 'ALIAS').first() %}
+{% set replacements = {} %}
+{% for key, val in vars %}
+  {% set replacements = replacements|merge({('{{ ' ~ key ~ ' }}'): val}) %}
+{% endfor %}
+{{ sendEmail(recipient, tpl.subject|replace(replacements), tpl.content|replace(replacements)) }}
+```
+
+### Faz 4: Custom Report — Detay Formu
+
+Report oluştur, tek query ile tam form HTML'i.
+
+**Kritik kurallar:**
+- `form_id` parametresi kullan (`id` RESERVED)
+- `currentUser('sicil_no')` ile çalışan bilgisi al (`app.user.username` YOK)
+- CSRF token JS ile al: `$('meta[name="csrf-token"]').attr('content')` (`csrf_token()` Twig fonksiyonu YOK)
+- Tailwind CSS CDN kullan
+- `rg_confirm()` / `rg_alert()` kullan (native alert/confirm DEĞİL)
+- Mevcut satırları Twig `{% for %}` ile DEĞİL, JS ile render et (window._data JSON'ından)
+- `state` alanını kontrol et (manual `status` DEĞİL)
+
+**Form bölümleri (gereksinime göre uyarla):**
+1. Header — tarih, referans no
+2. Talep eden bilgileri — employee/user tablosundan otomatik
+3. Form bilgileri — gereksinime özel alanlar
+4. Tekrarlanabilir satırlar (child records) — otomatik toplam, ondalık 2 basamak
+5. Ekler — dosya yükleme (varsa)
+6. Durum badge'i — `record.state` ile renk kodlu
+7. Aksiyon butonları — isDraft kontrolü ile koşullu
+
+**JS (script.js) mimarisi:**
+- `saveForm()` → Promise döner, requestId ile resolve olur
+- Add: Ana kayıt ekle → response.id al → child kayıtları ekle
+- Edit: Ana kayıt düzenle → mevcut child'ları sil (tek tek sequential `__delete`) → yeniden ekle
+- `triggerTransition(requestId, transitionId)` — state alanına JSON gönder
+- Save butonu: saveForm → redirect
+- Submit butonu: rg_confirm → saveForm → triggerTransition → redirect
+- Delete butonu: rg_confirm → child'ları sil → ana kaydı sil → dashboard'a redirect
+- **Read-only modu:** `isReadonly` flag ile tüm input'ları disable et, ekleme/silme butonlarını gizle
+
+### Faz 5: Dashboard
+
+İkinci report oluştur.
+
+**Bölümler:**
+1. **Taleplerim** — Giriş yapan kullanıcının tüm talepleri (taslak dahil), `state` alanına göre durum badge'leri
+2. **Onay Bekleyenler** — İlgili state'teki talepler
+3. **Yeni Talep** butonu → form report'una link
+
+**ÖNEMLİ:** Tüm durum filtreleri ve etiketleri `state` alanını kullanmalı (`status` DEĞİL).
+
+### Faz 6: Admin Menü
+
+**`cms_admin_menus` tablosunda Level 1 + Level 2 oluştur:**
+```
+Ana Menü (parent_id: 0)                     ← Level 1
+├── Alt Menü 1 (parent_id: main_menu_id)    ← Level 2
+├── Alt Menü 2                               ← Level 2
+└── Alt Menü 3                               ← Level 2
+```
+
+**Object'lere `main_menu_id` + `sub_menu_id` ata (Level 3):**
+- Her object'i uygun alt menüye bağla
+
+**3. seviye menü öğelerini `cms_admin_menus`'e ekleME** — object üzerinden `main_menu_id` + `sub_menu_id` ile yapılır.
+
+### Faz 7: Örnek Veri
+
+Test için örnek kayıtlar ekle (gereksinime göre).
+
+---
+
+## Sık Yapılan Hatalar (Bunları YAPMA)
+
+| Hata | Doğrusu |
+|------|---------|
+| `status: 'draft'` manual set etmek | State machine `state` alanını otomatik yönetir |
+| `record.status` kontrol etmek | `record.state` kullan (state machine system_name'leri) |
+| `csrf_token()` Twig'de kullanmak | JS'de `$('meta[name="csrf-token"]').attr('content')` |
+| `app.user.username` kullanmak | `currentUser('sicil_no')` |
+| `id` parametresi kullanmak | `form_id` kullan (`id` reserved) |
+| `alert()` / `confirm()` kullanmak | `rg_alert()` / `rg_confirm()` |
+| `bfy_state_machine_role_id` (tekil) | `bfy_state_machine_role_ids` (çoğul) |
+| Transition name alanı | `button_title` alanı kullan |
+| Custom format tarih datetime type | string type kullan (custom format dd.mm.YYYY HH:mm) |
+| `|replace('old', 'new')` string ile | `|replace({'old': 'new'})` mapping ile |
+| Child satırları Twig for loop ile render | JS'den render et (window._data JSON) |
+| Edit'te child'ları tekrar add etmek | Önce mevcut child'ları tek tek sil, sonra yeniden ekle |
+| `delete_where` endpoint kullanmak | Yok. Tek tek `__delete` ile sil (sequential promise chain) |
+| `butterfly-cli download -t cms_reports` | `-t reports` kullan |
+| 3. seviye menüyü cms_admin_menus'e eklemek | Object üzerinden main_menu_id + sub_menu_id ile yap |
+| jQuery UI'ı head'e koymak | jQuery yüklendikten sonra body sonuna koy |
+| PDF template'te `db().table()` kullanmak | `db('default', false).table()` kullan (permission bypass) |
+| Dosyayı doğrudan `cms_object/operation` ile yüklemek | Önce `file_helper/upload_file` ile yükle, sonra filename'i kaydet |
+| `file_upload` field input name'ini column adı yapmak | Input name mutlaka `file_upload` olmalı |
+| REST API kullanarak admin içi dosya yüklemek | Admin panel endpoint (`/admin/ajax/file_helper/upload_file`) kullan |
+| Fonksiyonları `$(document).ready()` içinde tanımlamak | Global scope'ta tanımla, sadece init kodu ready içinde olsun |
+| `employees` tablosu varsaymak | `currentUser('email')`, `currentUser('name')` kullan |
+
+---
+
+## Dosya Yükleme Entegrasyonu
+
+Custom report sayfalarında dosya yükleme **iki aşamalı** yapılır:
+
+### Adım 1: Dosyayı Yükle
+
+```javascript
+function uploadFile(file) {
+  return new Promise(function(resolve, reject) {
+    var fd = new FormData();
+    fd.append('file_upload', file);           // input name mutlaka 'file_upload'
+    fd.append('uuid', 'upload-' + Date.now());
+    fd.append('original_filename', file.name);
+    fd.append('total_file_size', file.size);
+
+    $.ajax({
+      url: '/admin/ajax/file_helper/upload_file?alias=import',  // alias URL param olarak
+      type: 'POST',
+      data: fd,
+      processData: false,
+      contentType: false,
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+      success: function(response) {
+        if (response.success && response.filename) {
+          resolve(response.filename);
+        } else {
+          rg_alert(response.message || 'Dosya yüklenemedi.');
+          reject('Upload failed');
+        }
+      },
+      error: function() { reject('Upload error'); }
+    });
+  });
+}
+```
+
+### Adım 2: Kaydı filename ile oluştur
+
+```javascript
+var filename = await uploadFile(fileInput.files[0]);
+$.ajax({
+  url: '/admin/ajax/cms_object/operation?do=tablo__add',
+  type: 'POST',
+  data: { csrf_token: csrfToken, parent_id: parentId, dosya: filename }
+});
+```
+
+### Storage Alias Ayarları
+
+- Alias'lar `cms_file_uploads` tablosunda tanımlıdır
+- `extensions` alanı izin verilen uzantıları belirler (virgülle ayrılmış)
+- Object spec'teki `file_upload` field'ın `val_1` parametresi alias adını belirtir
+- Yeni uzantı eklemek: `butterfly-cli record edit cms_file_uploads --id <id> --data '{"extensions":"mevcut,yeni"}'`
+
+Detaylı dokümantasyon: [docs/butterfly_upload_api_docs-2.md](butterfly_upload_api_docs-2.md)
+
+---
+
+## JS Scope ve Mimari Kuralları
+
+### Fonksiyon Tanımlama
+
+Custom report sayfalarında **tüm fonksiyonlar global scope'ta** tanımlanmalı. `$(document).ready()` içinde sadece init kodu olmalı:
+
+```javascript
+// ✅ DOĞRU: Global scope'ta
+function calculateTotal() { /* ... */ }
+function addRow() { /* ... */ }
+function saveForm() { /* ... */ }
+
+$(document).ready(function() {
+  // Sadece init: değişken atamaları, ilk render, event listener'lar
+  var csrfToken = $('meta[name="csrf-token"]').attr('content');
+  renderExistingRows();
+});
+```
+
+```javascript
+// ❌ YANLIŞ: ready() içinde tanımlama
+$(document).ready(function() {
+  function calculateTotal() { /* ... */ }  // onclick'ten erişilemez!
+  window.calculateTotal = calculateTotal;  // race condition riski
+});
+```
+
+**Neden?** HTML `onclick` attributeleri global scope'taki fonksiyonları çağırır. `$(document).ready()` içindeki fonksiyonlar closure'da kalır ve erişilemez. `window.XXX =` ataması ise timing sorunlarına yol açabilir (fonksiyon henüz atanmadan çağrılabilir).
+
+### Tailwind CSS Select Reset Sorunu
+
+Tailwind CSS `select` elementlerinin görünümünü sıfırlar. Custom select'ler için:
+
+```css
+.form-select, .data-table select {
+  appearance: auto;
+  background-color: #fff;
+}
+```