ROMFASTSQL/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Romanian ERP database migration system for Oracle databases. The project generates DDL/DML migration scripts following strict naming conventions and safety patterns to ensure idempotent execution.

## Key Architecture Components

### PACK_MIGRARE Package
Central utility package (`system_instructions/knowledge_base/PACK_MIGRARE.pck`) that provides:
- `ColumnExist()` - Check if column exists before adding
- `ObjectExist()` - Check if database object exists  
- `ConstraintExist()` - Check if constraint exists
- `UpdateVersiune()` - Version tracking for migration scripts

### Migration Scripts Examples
You have multiple example migration scrips in `system_instructions/knowledge_base`

### Migration Script Structure
All migration scripts must follow this pattern:
1. Use PACK_MIGRARE functions to check existence before creating/modifying objects
2. Wrap DDL operations in PL/SQL blocks with existence checks
3. Use MERGE with NOT MATCHED clause for data insertions to prevent duplicates
4. End with `pack_migrare.UpdateVersiune('script_name')` call
5. Add brief Romanian comment at top describing changes

### Naming Conventions
- Script files: `ff_YYYY_MM_DD_NN_TYPE.sql` (e.g., `ff_2024_08_28_02_COMUN_EFACTURA.sql`)
- No schema names in DDL statements
- No quotes around table/column names
- Uppercase SQL keywords
- Romanian comments

## SQL Formatting Rules

**NEVER use:**
- Schema qualifiers (`"MARIUSM_AUTO"."JV2007"`)
- Quotes around object names (`"COLUMN_NAME"`)

**ALWAYS use:**
- Uppercase SQL keywords (`ALTER TABLE`, `ADD`, `NUMBER`)
- Existence checks via PACK_MIGRARE before DDL operations
- Default values and NOT NULL constraints for new columns
- `NUMBER(18,4) DEFAULT 0 NOT NULL` for monetary/tax columns

## Common Migration Patterns

### 1. Adding Columns (with existence check)
```sql
BEGIN
    IF PACK_MIGRARE.COLUMNEXIST('TABLE_NAME', 'COLUMN_NAME') = 0 THEN
        EXECUTE IMMEDIATE 'ALTER TABLE TABLE_NAME ADD COLUMN_NAME NUMBER(18,4) DEFAULT 0 NOT NULL';
    END IF;
END;
/
COMMENT ON COLUMN TABLE_NAME.COLUMN_NAME IS 'Romanian description';
```

### 2. Inserting Configuration Data (MERGE with NOT MATCHED)
```sql
MERGE INTO OPTIUNI a USING DUAL b ON (a.varname = 'CONFIG_KEY')
WHEN NOT MATCHED THEN
INSERT (VARNAME, VARTYPE, VARVALUE, VARDESC)
VALUES ('CONFIG_KEY', 'CHARACTER', 'value', 'Descriere in romana');
```

### 3. Inserting System Objects (with complex conditions)
```sql
MERGE INTO DEF_OBIECTE a USING DUAL b ON (a.id_obiect = 6089)
WHEN NOT MATCHED THEN
INSERT (ID_OBIECT, ID_PROGRAM, DESCRIERE, ID_TATA, COD, ID_UTILOP, DATAORA, STERS)
VALUES (6089, 2, 'Descriere obiect', 6082, '02', -3, SYSDATE, 0);
```

### 4. Creating/Replacing Views
```sql
CREATE OR REPLACE VIEW view_name AS
SELECT column1, column2
FROM table_name
WHERE conditions;
```

### 5. Simple Updates
```sql
UPDATE OPTIUNI SET VARVALUE = '1' 
WHERE VARNAME IN ('OPTION1', 'OPTION2');

UPDATE ANAF_EFACTURA_DETALII SET ARTICOL = TRIM(ARTICOL);
```

### 6. Script Completion (ALWAYS required)
```sql
exec pack_migrare.UpdateVersiune('ff_2024_MM_DD_NN_TYPE');
commit;
```

## Directory Structure

- `input/` - Input files and table definitions  
- `output/` - Generated migration scripts
- `system_instructions/` - Project documentation and examples (see [README](system_instructions/README.md) for details)
- `system_instructions/knowledge_base/` - Reference scripts and PACK_MIGRARE package

## Important Notes

- All scripts must be idempotent (safe to run multiple times)
- Never include NULL values or CLOB data in INSERT/MERGE statements
- Use direct DDL for COMMENT statements, not EXECUTE IMMEDIATE
- Script names must be dynamic based on current date