codymaster 4.5.4 → 4.8.0

package/skills/cm-frappe-agent/skills/doctype-patterns/SKILL.md

@@ -1,576 +0,0 @@
----
-name: doctype-patterns
-description: Frappe DocType creation patterns, field types, controller hooks, and data modeling best practices. Use when creating DocTypes, designing data models, adding fields, or setting up document relationships in Frappe/ERPNext.
----
-
-# Frappe DocType Patterns
-
-Comprehensive guide to creating and configuring DocTypes in Frappe Framework, the core building block for all Frappe applications.
-
-## When to Use This Skill
-
-- Creating new DocTypes
-- Adding or modifying fields on DocTypes
-- Designing data models and relationships
-- Setting up naming patterns and autoname
-- Configuring permissions and workflows
-- Creating child tables
-- Working with Virtual or Single DocTypes
-
-## DocType Directory Structure
-
-When you create a DocType named "My Custom DocType" in module "My Module":
-
-```
-my_app/
-└── my_module/
-    └── doctype/
-        └── my_custom_doctype/
-            ├── my_custom_doctype.json      # DocType definition
-            ├── my_custom_doctype.py        # Python controller
-            ├── my_custom_doctype.js        # Client script
-            ├── test_my_custom_doctype.py   # Test file
-            └── __init__.py
-```
-
-## DocType JSON Structure
-
-```json
-{
-  "name": "My Custom DocType",
-  "module": "My Module",
-  "doctype": "DocType",
-  "engine": "InnoDB",
-  "field_order": ["field1", "field2"],
-  "fields": [
-    {
-      "fieldname": "field1",
-      "fieldtype": "Data",
-      "label": "Field 1",
-      "reqd": 1
-    }
-  ],
-  "permissions": [
-    {
-      "role": "System Manager",
-      "read": 1,
-      "write": 1,
-      "create": 1,
-      "delete": 1
-    }
-  ],
-  "autoname": "naming_series:",
-  "naming_rule": "By \"Naming Series\" field",
-  "is_submittable": 0,
-  "istable": 0,
-  "issingle": 0,
-  "track_changes": 1,
-  "sort_field": "modified",
-  "sort_order": "DESC"
-}
-```
-
-## Field Types Reference
-
-### Text Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Data` | Single line text (140 chars) | Names, codes, short text |
-| `Small Text` | Multi-line text | Short descriptions |
-| `Text` | Multi-line text (unlimited) | Long descriptions |
-| `Text Editor` | Rich text with formatting | Content, notes |
-| `Code` | Syntax-highlighted code | Python, JS, JSON |
-| `HTML Editor` | WYSIWYG HTML | Email templates |
-| `Markdown Editor` | Markdown input | Documentation |
-| `Password` | Masked input | Secrets (stored encrypted) |
-
-### Numeric Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Int` | Integer | Counts, quantities |
-| `Float` | Decimal number | Measurements |
-| `Currency` | Money with precision | Prices, amounts |
-| `Percent` | 0-100 percentage | Discounts, rates |
-| `Rating` | Star rating (0-1) | Reviews, scores |
-
-### Date/Time Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Date` | Date only | Birth dates, due dates |
-| `Datetime` | Date and time | Timestamps |
-| `Time` | Time only | Schedules |
-| `Duration` | Time duration | Task duration |
-
-### Selection Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Select` | Dropdown options | Status, type |
-| `Check` | Boolean checkbox | Flags, toggles |
-| `Autocomplete` | Text with suggestions | Tags |
-
-### Link Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Link` | Reference to another DocType | Foreign key relationship |
-| `Dynamic Link` | Reference based on another field | Polymorphic links |
-| `Table` | Child table (1-to-many) | Line items, details |
-| `Table MultiSelect` | Many-to-many via link | Multiple selections |
-
-### Special Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Attach` | Single file attachment | Documents |
-| `Attach Image` | Image with preview | Photos, logos |
-| `Image` | Display image from URL field | Gallery |
-| `Signature` | Signature pad | Approvals |
-| `Geolocation` | Map coordinates | Locations |
-| `Barcode` | Barcode/QR display | Inventory |
-| `JSON` | JSON data | Configuration |
-
-### Layout Fields
-| Type | Description | Use Case |
-|------|-------------|----------|
-| `Section Break` | Horizontal section divider | Form organization |
-| `Column Break` | Vertical column divider | Multi-column layout |
-| `Tab Break` | Tab navigation | Large forms |
-| `HTML` | Static HTML content | Instructions, headers |
-| `Heading` | Section heading | Visual separation |
-| `Button` | Clickable button | Actions |
-
-## Field Options
-
-### Common Field Properties
-```json
-{
-  "fieldname": "customer",
-  "fieldtype": "Link",
-  "label": "Customer",
-  "options": "Customer",
-  "reqd": 1,
-  "unique": 0,
-  "in_list_view": 1,
-  "in_standard_filter": 1,
-  "in_global_search": 1,
-  "bold": 1,
-  "read_only": 0,
-  "hidden": 0,
-  "print_hide": 0,
-  "no_copy": 0,
-  "allow_in_quick_entry": 1,
-  "translatable": 0,
-  "default": "",
-  "description": "Select the customer",
-  "depends_on": "eval:doc.is_customer",
-  "mandatory_depends_on": "eval:doc.status=='Active'",
-  "read_only_depends_on": "eval:doc.docstatus==1"
-}
-```
-
-### Link Field Options
-```json
-{
-  "fieldname": "customer",
-  "fieldtype": "Link",
-  "options": "Customer",
-  "filters": {
-    "disabled": 0,
-    "customer_type": "Company"
-  },
-  "ignore_user_permissions": 0
-}
-```
-
-### Select Field Options
-```json
-{
-  "fieldname": "status",
-  "fieldtype": "Select",
-  "options": "\nDraft\nPending\nApproved\nRejected",
-  "default": "Draft"
-}
-```
-
-### Dynamic Link
-```json
-{
-  "fieldname": "party_type",
-  "fieldtype": "Link",
-  "options": "DocType"
-},
-{
-  "fieldname": "party",
-  "fieldtype": "Dynamic Link",
-  "options": "party_type"
-}
-```
-
-## Naming Patterns (autoname)
-
-### Naming Series
-```json
-{
-  "autoname": "naming_series:",
-  "naming_rule": "By \"Naming Series\" field"
-}
-```
-Add a naming_series field:
-```json
-{
-  "fieldname": "naming_series",
-  "fieldtype": "Select",
-  "options": "INV-.YYYY.-\nINV-.MM.-.YYYY.-",
-  "default": "INV-.YYYY.-"
-}
-```
-
-### Field-Based Naming
-```json
-{
-  "autoname": "field:customer_code",
-  "naming_rule": "By fieldname"
-}
-```
-
-### Expression-Based
-```json
-{
-  "autoname": "format:{customer_type}-{###}",
-  "naming_rule": "Expression"
-}
-```
-
-### Hash/Random
-```json
-{
-  "autoname": "hash",
-  "naming_rule": "Random"
-}
-```
-
-### Prompt (Manual)
-```json
-{
-  "autoname": "Prompt",
-  "naming_rule": "Set by user"
-}
-```
-
-## Controller Lifecycle Hooks
-
-```python
-# my_doctype.py
-import frappe
-from frappe.model.document import Document
-
-class MyDocType(Document):
-    # ===== BEFORE DATABASE OPERATIONS =====
-
-    def autoname(self):
-        """Set the document name before saving"""
-        self.name = f"{self.prefix}-{frappe.generate_hash()[:8]}"
-
-    def before_naming(self):
-        """Called before autoname, can modify naming logic"""
-        pass
-
-    def validate(self):
-        """Validate data before save (called on insert and update)"""
-        self.validate_dates()
-        self.calculate_totals()
-
-    def before_validate(self):
-        """Called before validate"""
-        pass
-
-    def before_save(self):
-        """Called before document is saved to database"""
-        self.modified_by_script = True
-
-    def before_insert(self):
-        """Called before new document is inserted"""
-        self.set_defaults()
-
-    # ===== AFTER DATABASE OPERATIONS =====
-
-    def after_insert(self):
-        """Called after new document is inserted"""
-        self.notify_users()
-
-    def on_update(self):
-        """Called after document is saved (insert or update)"""
-        self.update_related_docs()
-
-    def after_save(self):
-        """Called after on_update, always runs"""
-        pass
-
-    def on_change(self):
-        """Called when document changes in database"""
-        pass
-
-    # ===== SUBMISSION WORKFLOW =====
-
-    def before_submit(self):
-        """Called before document is submitted"""
-        self.validate_for_submit()
-
-    def on_submit(self):
-        """Called after document is submitted"""
-        self.create_gl_entries()
-
-    def before_cancel(self):
-        """Called before document is cancelled"""
-        self.validate_cancellation()
-
-    def on_cancel(self):
-        """Called after document is cancelled"""
-        self.reverse_gl_entries()
-
-    def on_update_after_submit(self):
-        """Called when submitted doc is updated (limited fields)"""
-        pass
-
-    # ===== DELETION =====
-
-    def before_delete(self):
-        """Called before document is deleted"""
-        self.check_dependencies()
-
-    def after_delete(self):
-        """Called after document is deleted"""
-        self.cleanup_attachments()
-
-    def on_trash(self):
-        """Called when document is trashed"""
-        pass
-
-    def after_restore(self):
-        """Called after document is restored from trash"""
-        pass
-
-    # ===== CUSTOM METHODS =====
-
-    def validate_dates(self):
-        if self.end_date and self.start_date > self.end_date:
-            frappe.throw("End date cannot be before start date")
-
-    def calculate_totals(self):
-        self.total = sum(d.amount for d in self.items)
-```
-
-## Child Table (Table Field)
-
-### Parent DocType
-```json
-{
-  "fieldname": "items",
-  "fieldtype": "Table",
-  "label": "Items",
-  "options": "My DocType Item",
-  "reqd": 1
-}
-```
-
-### Child DocType JSON
-```json
-{
-  "name": "My DocType Item",
-  "module": "My Module",
-  "doctype": "DocType",
-  "istable": 1,
-  "editable_grid": 1,
-  "fields": [
-    {
-      "fieldname": "item",
-      "fieldtype": "Link",
-      "options": "Item",
-      "in_list_view": 1,
-      "reqd": 1
-    },
-    {
-      "fieldname": "qty",
-      "fieldtype": "Float",
-      "in_list_view": 1
-    },
-    {
-      "fieldname": "rate",
-      "fieldtype": "Currency",
-      "in_list_view": 1
-    },
-    {
-      "fieldname": "amount",
-      "fieldtype": "Currency",
-      "in_list_view": 1,
-      "read_only": 1
-    }
-  ]
-}
-```
-
-## Single DocType (Settings)
-
-For application settings that have only one record:
-
-```json
-{
-  "name": "My App Settings",
-  "module": "My Module",
-  "doctype": "DocType",
-  "issingle": 1,
-  "fields": [
-    {
-      "fieldname": "enable_feature",
-      "fieldtype": "Check",
-      "label": "Enable Feature"
-    },
-    {
-      "fieldname": "api_key",
-      "fieldtype": "Password",
-      "label": "API Key"
-    }
-  ]
-}
-```
-
-Access in code:
-```python
-settings = frappe.get_single("My App Settings")
-if settings.enable_feature:
-    do_something()
-```
-
-## Virtual DocType
-
-DocType without database table, computed on-the-fly:
-
-```json
-{
-  "name": "My Virtual DocType",
-  "module": "My Module",
-  "doctype": "DocType",
-  "is_virtual": 1
-}
-```
-
-Controller:
-```python
-class MyVirtualDocType(Document):
-    @staticmethod
-    def get_list(args):
-        # Return list of virtual documents
-        return [{"name": "doc1", "value": 100}]
-
-    @staticmethod
-    def get_count(args):
-        return len(MyVirtualDocType.get_list(args))
-
-    @staticmethod
-    def get_stats(args):
-        return {}
-```
-
-## Permissions
-
-```json
-{
-  "permissions": [
-    {
-      "role": "System Manager",
-      "read": 1,
-      "write": 1,
-      "create": 1,
-      "delete": 1,
-      "submit": 1,
-      "cancel": 1,
-      "amend": 1,
-      "report": 1,
-      "export": 1,
-      "import": 1,
-      "share": 1,
-      "print": 1,
-      "email": 1
-    },
-    {
-      "role": "Sales User",
-      "read": 1,
-      "write": 1,
-      "create": 1,
-      "if_owner": 1
-    }
-  ]
-}
-```
-
-## Best Practices
-
-### Naming Conventions (Strict English Only)
-- **CRITICAL**: **NEVER** use non-ASCII or accented characters (e.g., Vietnamese) in DocType names or fieldnames. This causes fatal SQL parsing errors in MariaDB/Frappe Insights.
-- **DocType Names**: English, singular, Title Case with spaces (e.g., "Sales Invoice", not "Hóa đơn bán hàng").
-- **Fieldnames**: English, `snake_case` (e.g., `customer_name`, not `tên_khách_hàng`).
-- **Localization**: Use the `label` field for non-English display text (e.g., `"fieldname": "violation_name", "label": "Tên vi phạm"`).
-
-### Field Design
-- Put most important fields first
-- Use Section Breaks to organize
-- Use Tab Breaks for complex forms
-- Set `in_list_view` for key fields
-- Set `in_standard_filter` for filterable fields
-
-### Performance
-- Index frequently queried fields with `search_index: 1`
-- Use `read_only` to prevent unnecessary validation
-- Limit child table rows with `max_attachments`
-
-### Data Integrity
-- Use `unique: 1` for unique constraints
-- Set appropriate `reqd` (required) flags
-- Use `depends_on` for conditional visibility
-- Use `mandatory_depends_on` for conditional requirements
-
-## Common Patterns
-
-### Status Field Pattern
-```json
-{
-  "fieldname": "status",
-  "fieldtype": "Select",
-  "options": "\nDraft\nPending Approval\nApproved\nRejected",
-  "default": "Draft",
-  "in_list_view": 1,
-  "in_standard_filter": 1,
-  "read_only": 1,
-  "allow_on_submit": 1
-}
-```
-
-### Amount Calculation Pattern
-```json
-[
-  {"fieldname": "qty", "fieldtype": "Float"},
-  {"fieldname": "rate", "fieldtype": "Currency"},
-  {"fieldname": "amount", "fieldtype": "Currency", "read_only": 1}
-]
-```
-With controller:
-```python
-def validate(self):
-    for item in self.items:
-        item.amount = flt(item.qty) * flt(item.rate)
-    self.total = sum(item.amount for item in self.items)
-```
-
-### Linked Document Pattern
-```json
-{
-  "fieldname": "customer",
-  "fieldtype": "Link",
-  "options": "Customer",
-  "reqd": 1
-},
-{
-  "fieldname": "customer_name",
-  "fieldtype": "Data",
-  "fetch_from": "customer.customer_name",
-  "read_only": 1
-}
-```