@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/pdf-processing-pro/scripts/analyze_form.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""
+Analyze PDF form fields and structure.
+
+Usage:
+    python analyze_form.py input.pdf [--output fields.json] [--verbose]
+
+Returns:
+    JSON with all form fields, types, positions, and metadata
+
+Exit codes:
+    0 - Success
+    1 - File not found
+    2 - Invalid PDF
+    3 - Processing error
+"""
+
+import sys
+import json
+import logging
+import argparse
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+try:
+    from pypdf import PdfReader
+except ImportError:
+    print("Error: pypdf not installed. Run: pip install pypdf", file=sys.stderr)
+    sys.exit(3)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class FormField:
+    """Represents a PDF form field."""
+
+    def __init__(self, name: str, field_dict: Dict[str, Any]):
+        self.name = name
+        self.raw_data = field_dict
+
+    @property
+    def field_type(self) -> str:
+        """Get field type."""
+        ft = self.raw_data.get('/FT', '')
+        type_map = {
+            '/Tx': 'text',
+            '/Btn': 'button',  # checkbox or radio
+            '/Ch': 'choice',   # dropdown or list
+            '/Sig': 'signature'
+        }
+        return type_map.get(ft, 'unknown')
+
+    @property
+    def value(self) -> Optional[str]:
+        """Get current field value."""
+        val = self.raw_data.get('/V')
+        return str(val) if val else None
+
+    @property
+    def default_value(self) -> Optional[str]:
+        """Get default field value."""
+        dv = self.raw_data.get('/DV')
+        return str(dv) if dv else None
+
+    @property
+    def is_required(self) -> bool:
+        """Check if field is required."""
+        flags = self.raw_data.get('/Ff', 0)
+        # Bit 2 indicates required
+        return bool(flags & 2)
+
+    @property
+    def is_readonly(self) -> bool:
+        """Check if field is read-only."""
+        flags = self.raw_data.get('/Ff', 0)
+        # Bit 1 indicates read-only
+        return bool(flags & 1)
+
+    @property
+    def options(self) -> List[str]:
+        """Get options for choice fields."""
+        if self.field_type != 'choice':
+            return []
+
+        opts = self.raw_data.get('/Opt', [])
+        if isinstance(opts, list):
+            return [str(opt) for opt in opts]
+        return []
+
+    @property
+    def max_length(self) -> Optional[int]:
+        """Get max length for text fields."""
+        if self.field_type == 'text':
+            return self.raw_data.get('/MaxLen')
+        return None
+
+    @property
+    def rect(self) -> Optional[List[float]]:
+        """Get field position and size [x0, y0, x1, y1]."""
+        return self.raw_data.get('/Rect')
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        result = {
+            'name': self.name,
+            'type': self.field_type,
+            'required': self.is_required,
+            'readonly': self.is_readonly
+        }
+
+        if self.value is not None:
+            result['value'] = self.value
+
+        if self.default_value is not None:
+            result['default_value'] = self.default_value
+
+        if self.options:
+            result['options'] = self.options
+
+        if self.max_length is not None:
+            result['max_length'] = self.max_length
+
+        if self.rect:
+            result['position'] = {
+                'x0': float(self.rect[0]),
+                'y0': float(self.rect[1]),
+                'x1': float(self.rect[2]),
+                'y1': float(self.rect[3]),
+                'width': float(self.rect[2] - self.rect[0]),
+                'height': float(self.rect[3] - self.rect[1])
+            }
+
+        return result
+
+
+class PDFFormAnalyzer:
+    """Analyzes PDF forms and extracts field information."""
+
+    def __init__(self, pdf_path: str):
+        self.pdf_path = Path(pdf_path)
+        self.reader: Optional[PdfReader] = None
+        self._validate_file()
+
+    def _validate_file(self) -> None:
+        """Validate PDF file exists and is readable."""
+        if not self.pdf_path.exists():
+            logger.error(f"PDF not found: {self.pdf_path}")
+            raise FileNotFoundError(f"PDF not found: {self.pdf_path}")
+
+        if not self.pdf_path.is_file():
+            logger.error(f"Not a file: {self.pdf_path}")
+            raise ValueError(f"Not a file: {self.pdf_path}")
+
+        if self.pdf_path.suffix.lower() != '.pdf':
+            logger.error(f"Not a PDF file: {self.pdf_path}")
+            raise ValueError(f"Not a PDF file: {self.pdf_path}")
+
+    def analyze(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Analyze PDF and extract all form fields.
+
+        Returns:
+            Dictionary mapping field names to field information
+        """
+        try:
+            self.reader = PdfReader(str(self.pdf_path))
+
+            if not self.reader.pages:
+                logger.warning("PDF has no pages")
+                return {}
+
+            logger.info(f"Analyzing PDF with {len(self.reader.pages)} pages")
+
+            # Get form fields
+            raw_fields = self.reader.get_fields()
+
+            if not raw_fields:
+                logger.warning("PDF has no form fields")
+                return {}
+
+            logger.info(f"Found {len(raw_fields)} form fields")
+
+            # Process fields
+            fields = {}
+            for field_name, field_dict in raw_fields.items():
+                try:
+                    field = FormField(field_name, field_dict)
+                    fields[field_name] = field.to_dict()
+                except Exception as e:
+                    logger.warning(f"Error processing field {field_name}: {e}")
+                    continue
+
+            return fields
+
+        except Exception as e:
+            logger.error(f"Error analyzing PDF: {e}")
+            raise
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Get summary statistics."""
+        fields = self.analyze()
+
+        summary = {
+            'total_fields': len(fields),
+            'field_types': {},
+            'required_fields': [],
+            'readonly_fields': [],
+            'fields_with_values': []
+        }
+
+        for field_name, field_data in fields.items():
+            # Count by type
+            field_type = field_data['type']
+            summary['field_types'][field_type] = summary['field_types'].get(field_type, 0) + 1
+
+            # Required fields
+            if field_data.get('required'):
+                summary['required_fields'].append(field_name)
+
+            # Read-only fields
+            if field_data.get('readonly'):
+                summary['readonly_fields'].append(field_name)
+
+            # Fields with values
+            if field_data.get('value'):
+                summary['fields_with_values'].append(field_name)
+
+        return summary
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description='Analyze PDF form fields',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  %(prog)s form.pdf
+  %(prog)s form.pdf --output fields.json
+  %(prog)s form.pdf --output fields.json --verbose
+  %(prog)s form.pdf --summary
+
+Exit codes:
+  0 - Success
+  1 - File not found
+  2 - Invalid PDF
+  3 - Processing error
+        '''
+    )
+
+    parser.add_argument('input', help='Input PDF file')
+    parser.add_argument('--output', '-o', help='Output JSON file (default: stdout)')
+    parser.add_argument('--summary', '-s', action='store_true', help='Show summary only')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+
+    args = parser.parse_args()
+
+    # Set log level
+    if args.verbose:
+        logger.setLevel(logging.DEBUG)
+    else:
+        logger.setLevel(logging.WARNING)
+
+    try:
+        # Analyze form
+        analyzer = PDFFormAnalyzer(args.input)
+
+        if args.summary:
+            result = analyzer.get_summary()
+        else:
+            result = analyzer.analyze()
+
+        # Output
+        json_output = json.dumps(result, indent=2)
+
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(json_output)
+            logger.info(f"Saved to {args.output}")
+        else:
+            print(json_output)
+
+        return 0
+
+    except FileNotFoundError:
+        logger.error(f"File not found: {args.input}")
+        return 1
+
+    except ValueError as e:
+        logger.error(f"Invalid input: {e}")
+        return 2
+
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 3
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/templates/.claude/skills/postgres/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: postgres
+description: PostgreSQL conventions and patterns for UKit SQL work.
+enabledByDefault: false
+---
+
+# PostgreSQL Skill Pack
+
+Enabled: false
+
+AI suggests SQL only. User runs via psql. Read reference files for full examples:
+- `reference/fn_rpt_examples.sql` - Report function patterns
+- `reference/fn_get_examples.sql` - Get functions with permissions
+- `reference/utility_functions.sql` - Utility functions & table templates
+
+## Data Types (ONLY 3)
+
+| Type | Use for |
+|------|---------|
+| `VARCHAR` | Text, dates, timestamps, JSON, UUIDs |
+| `NUMERIC` | Numbers (`NUMERIC(16,2)` for money) |
+| `BOOLEAN` | True/false |
+
+**NEVER use:** DATE, TIMESTAMP, INTEGER, BIGINT, JSON, JSONB, UUID, TEXT
+
+## Naming
+
+| Object | Pattern | Example |
+|--------|---------|---------|
+| Table | `snake_case` | `users` |
+| PK | `id_<table>` | `id_users` |
+| View | `v_<name>` | `v_billing` |
+| Function | `fn_<name>` | `fn_get_users` |
+| Report fn | `fn_rpt_<name>` | `fn_rpt_billing` |
+| Index | `idx_{table}_{cols}` | `idx_orders_user_id` |
+
+## Mandatory Workflow
+
+1. **Query structure first** (`\d schema.table` or `information_schema`)
+2. **Check if view exists** (`\dv schema.*`)
+3. View exists → `CREATE FUNCTION RETURNS SETOF view_name`
+4. View missing → Create view first, then function
+
+**NEVER:** Use `RETURNS TABLE`, create views inside functions, skip `DROP FUNCTION IF EXISTS`
+
+## Function Pattern (Preferred)
+
+```sql
+DROP FUNCTION IF EXISTS schema.fn_rpt_name;
+CREATE OR REPLACE FUNCTION schema.fn_rpt_name()
+    RETURNS SETOF schema.v_report_name
+AS $$
+BEGIN
+    RETURN QUERY SELECT * FROM schema.v_report_name ORDER BY created_on DESC;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT * FROM schema.fn_rpt_name();
+```
+
+## Key Rules
+
+- `DROP` before `CREATE`. Explicit casts (`::VARCHAR`, `::NUMERIC(16,2)`)
+- Declare + initialize variables. NULL checks for flags.
+- `ORDER BY` in RETURN QUERY. Alias all tables. Test query after function.
+- `CASE WHEN`: `(CASE WHEN cond THEN TRUE ELSE FALSE END) AS col`
+- JSONB: `jsonb_array_elements_text(col::jsonb)`, `(t.detail::jsonb -> 0 ->>'key')::VARCHAR`
+- Indexes for WHERE/JOIN/ORDER columns. `EXPLAIN ANALYZE` on large tables.
+- Parameterized queries only. No `SELECT *` in app code.

package/templates/.claude/skills/postgres/reference/fn_get_examples.sql

@@ -0,0 +1,208 @@
+-- =============================================
+-- GET FUNCTION EXAMPLES
+-- Pattern: fn_get_<name> - Returns SETOF view
+-- With user permissions and computed columns
+-- =============================================
+
+
+-- =============================================
+-- Example 1: Get with Role-based Permissions
+-- Pattern: Single role check + permission table lookup
+-- =============================================
+
+DROP FUNCTION IF EXISTS qas.fn_get_collect_point;
+CREATE OR REPLACE FUNCTION qas.fn_get_collect_point(_username VARCHAR)
+    RETURNS SETOF qas.v_collect_point
+AS
+$$
+DECLARE
+    v_role              VARCHAR;
+    v_is_admin1         BOOLEAN := FALSE;
+    v_is_admin2         BOOLEAN := FALSE;
+    t_can_edit_after_approved BOOLEAN := FALSE;
+BEGIN
+    -- Get user role
+    SELECT usergroup INTO v_role FROM qas.user WHERE username = _username;
+
+    -- Check admin roles
+    IF v_role LIKE '%Collect Point Admin 1%' THEN
+        v_is_admin1 = TRUE;
+    END IF;
+
+    IF v_role LIKE '%Collect Point Admin 2%' THEN
+        v_is_admin2 = TRUE;
+    END IF;
+
+    -- Get permission from permission table
+    SELECT can_edit_after_approved INTO t_can_edit_after_approved
+    FROM qas.permission
+    WHERE usergroup IN (SELECT jsonb_array_elements_text(v_role::jsonb))
+      AND menu = 'Collect Point'
+      AND can_edit_after_approved IS TRUE;
+
+    -- NULL check
+    IF t_can_edit_after_approved IS NULL THEN
+        t_can_edit_after_approved = FALSE;
+    END IF;
+
+    RETURN QUERY
+        SELECT c.id_collect_point,
+               c.running_no,
+               c.receipt_no,
+               c.date_receipt,
+               c.date_of_upload,
+               c.stamp_product,
+               c.status,
+               c.history,
+               c.created_on,
+               c.username,
+               c.remark,
+               c.remark_admin2,
+               c.attach_file,
+               c.attach_image,
+               c.id_sub_dealer,
+               c.name_of_store,
+               c.crm_user_id,
+               c.sub_dealer_province,
+               c.store_region,
+               c.id_dealer,
+               c.name_of_seller,
+               c.region1_salesrep,
+               c.region3_division,
+               c.customer_code,
+               c.total_point,
+               c.total_amount,
+               -- Computed permission columns
+               (CASE WHEN (v_is_admin1 AND c.status = 'DRAFT') OR (v_is_admin2 AND c.status = 'DRAFT1') THEN TRUE ELSE FALSE END) AS can_edit_quantity,
+               (CASE WHEN v_is_admin2 AND c.status = 'DRAFT1' THEN TRUE ELSE FALSE END) AS can_edit_multiplier,
+               (CASE WHEN (v_is_admin1 AND c.status = 'DRAFT') OR (v_is_admin2 AND c.status = 'DRAFT1') THEN TRUE ELSE FALSE END) AS can_save,
+               t_can_edit_after_approved AS can_edit_after_approved,
+               c.detail,
+               c.approved_date,
+               c.approved_by
+        FROM qas.v_collect_point c
+        ORDER BY c.created_on DESC;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT * FROM qas.fn_get_collect_point('khoaln@scg.com');
+
+
+-- =============================================
+-- Example 2: Get with Multiple Permission Flags
+-- Pattern: Permission table + role-based overrides + JSONB access
+-- =============================================
+
+DROP FUNCTION IF EXISTS qas.fn_get_review_transaction_4_not_eligible;
+CREATE OR REPLACE FUNCTION qas.fn_get_review_transaction_4_not_eligible(_username VARCHAR)
+    RETURNS SETOF qas.v_review_transaction
+AS
+$$
+DECLARE
+    t_usergroup               VARCHAR;
+    t_can_edit_after_approved BOOLEAN := FALSE;
+    t_can_reject              BOOLEAN := FALSE;
+    t_can_not_eligible        BOOLEAN := FALSE;
+    t_can_confirm             BOOLEAN := FALSE;
+    t_can_approve             BOOLEAN := FALSE;
+    t_can_save                BOOLEAN := FALSE;
+BEGIN
+    -- Get user group
+    SELECT usergroup INTO t_usergroup FROM qas.user WHERE username = _username;
+
+    -- Get base permission
+    SELECT can_edit_after_approved INTO t_can_edit_after_approved
+    FROM qas.permission
+    WHERE usergroup IN (SELECT jsonb_array_elements_text(t_usergroup::jsonb))
+      AND menu = 'Collect Point'
+      AND can_edit_after_approved IS TRUE;
+
+    IF t_can_edit_after_approved IS NULL THEN
+        t_can_edit_after_approved = FALSE;
+    END IF;
+
+    -- Role-based permission overrides
+    IF t_usergroup LIKE '%"Collect Point Admin 1"%' THEN
+        t_can_edit_after_approved = FALSE;
+        t_can_reject = TRUE;
+        t_can_not_eligible = FALSE;
+        t_can_confirm = TRUE;
+        t_can_approve = FALSE;
+    END IF;
+
+    IF t_usergroup LIKE '%"Collect Point Admin 2"%' THEN
+        t_can_edit_after_approved = FALSE;
+        t_can_reject = TRUE;
+        t_can_not_eligible = FALSE;
+        t_can_confirm = FALSE;
+        t_can_approve = TRUE;
+    END IF;
+
+    RETURN QUERY
+        SELECT t.id_review_transaction,
+               t.running_no,
+               t.image_name,
+               t.image_name_show,
+               t.user_id,
+               t.ref_id,
+               t.last_name,
+               t.first_name,
+               t.id_sub_dealer,
+               t.name_of_store,
+               t.post_code,
+               t.sub_dealer_province,
+               t.store_region,
+               t.address,
+               t.survey_date,
+               t.date_of_upload,
+               -- JSONB access with fallback
+               (CASE
+                    WHEN t.doc_date <> '' THEN t.doc_date
+                    ELSE (CASE
+                              WHEN (t.detail::jsonb -> 0 ->> 'doc_date')::VARCHAR <> ''
+                                  THEN (t.detail::jsonb -> 0 ->> 'doc_date')::VARCHAR
+                              ELSE ''
+                        END)
+                   END) AS doc_date,
+               t.detail,
+               t.is_confirm,
+               t.confirm_user,
+               t.confirm_time,
+               t.is_reject,
+               t.reject_by,
+               t.reject_time,
+               t.reject_reason,
+               t.not_eligible,
+               t.not_eligible_username,
+               t.not_eligible_time,
+               t.is_approved,
+               t.approved_by,
+               t.approved_time,
+               -- Permission flags
+               t_can_edit_after_approved AS can_edit_after_approved,
+               t_can_reject AS can_reject,
+               t_can_not_eligible AS can_not_eligible,
+               t_can_confirm AS can_confirm,
+               t_can_approve AS can_approve,
+               (CASE WHEN t_can_edit_after_approved AND is_reject IS TRUE THEN TRUE ELSE FALSE END) AS can_save,
+               t.doc_number,
+               t.doc_number_show,
+               t.customer_id,
+               t.dealer_code,
+               t.dealer_name,
+               t.username,
+               t.created_on,
+               t.total_get_point,
+               t.total_get_point_amount,
+               t.status,
+               t.last_changed_time,
+               t.history,
+               t.remark
+        FROM qas.v_review_transaction t
+        WHERE t.not_eligible = TRUE
+        ORDER BY t.last_changed_time DESC;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT * FROM qas.fn_get_review_transaction_4_not_eligible('hungdq@scg.com')
+WHERE id_review_transaction = '6639d394-4576-4013-a8b0-8e40cbab9c6d';