first commit

about/ruc_format.md

@@ -0,0 +1,203 @@
+RUC Form Integration
+1. Overview
+
+This document defines the implementation of a RUC (Registro Único del Contribuyente) input form for the application.
+
+The goal is to:
+
+Collect valid Paraguayan RUC numbers
+
+Reduce user input errors
+
+Improve user experience
+
+Ensure basic legal and invoicing compliance
+
+The RUC field will be used for:
+
+Invoicing
+
+Payments
+
+Registrations
+
+Business verification
+
+Tax-related records
+
+2. RUC Format Specification
+
+A valid RUC has the following structure:
+
+6 to 8 digits + "-" + 1 check digit
+
+
+Examples:
+
+4521876-5
+80012345-6
+12345678-9
+
+
+Rules:
+
+Only numbers and one hyphen
+
+The hyphen is always before the last digit
+
+No spaces or letters allowed
+
+Maximum length: 10 characters (including "-")
+
+3. User Interface Requirements
+3.1 Input Field
+
+The RUC input field must:
+
+Accept only numeric input
+
+Auto-insert the hyphen
+
+Show placeholder example
+
+Display validation errors
+
+Example UI:
+
+[ RUC: 12345678-9 ]
+
+
+Attributes:
+
+Required field (when invoicing enabled)
+
+Mobile-friendly
+
+Copy-paste safe
+
+Accessible (label + aria support)
+
+3.2 Placeholder Text
+
+Default placeholder:
+
+12345678-9
+
+
+Optional localized versions:
+
+Spanish:
+
+Ej: 12345678-9
+
+
+English:
+
+Example: 12345678-9
+
+4. Client-Side Validation
+4.1 Format Validation
+
+The frontend must verify:
+
+Pattern: /^[0-9]{6,8}-[0-9]{1}$/
+
+Exactly one hyphen
+
+Correct digit count
+
+Invalid examples:
+
+1234-5
+123456789
+ABC123-4
+
+4.2 Check Digit Validation
+
+The verification digit must be validated using modulo 11.
+
+Purpose:
+
+Detect mistyped RUC numbers
+
+Prevent fake entries
+
+Improve data quality
+
+Validation occurs:
+
+On input blur
+
+On form submit
+
+Before backend submission
+
+4.3 Auto-Formatting
+
+The system must:
+
+Remove non-numeric characters
+
+Automatically insert "-"
+
+Limit input to 9 digits
+
+Behavior:
+
+User types:
+
+45218765
+
+
+System shows:
+
+4521876-5
+
+
+This improves usability and reduces errors.
+
+5. Error Handling
+5.1 Error Messages
+
+When validation fails, show:
+
+Format error:
+
+Formato inválido. Ej: 12345678-9
+
+
+Check digit error:
+
+RUC inválido. Verifique el número.
+
+
+Empty field:
+
+Este campo es obligatorio.
+
+
+Messages should be:
+
+Clear
+
+Short
+
+Non-technical
+
+Localized
+
+5.2 Visual Feedback
+
+Invalid input must:
+
+Highlight input in red
+
+Show error text below field
+
+Disable submit if blocking
+
+Valid input must:
+
+Show neutral or success state
+
+Remove error messages