# RowCondition - serwerowe filtrowanie danych

`RowCondition` to mechanizm tworzenia warunków filtrujących wczytywane wiersze **na poziomie serwera SQL**. Warunki są tłumaczone na klauzulę `WHERE` zapytania SQL, dzięki czemu z bazy do pamięci aplikacji trafiają wyłącznie wiersze spełniające kryteria. Jest to **podstawowy sposób efektywnego odczytu danych** w logice biznesowej.

Najwygodniejsze API to budowa warunku z wyrażeń LINQ (`Expression<Predicate<TRow>>`) przez `RowCondition.FromExpression(...)` oraz aplikowanie wyrażeń bezpośrednio do `SubTable` i `View` przez indeksator i `AddExpression(...)`.

## Spis treści

- [Najważniejsze zasady](#najważniejsze-zasady)
- [Wzorce użycia w kodzie](#wzorce-użycia-w-kodzie)
  - [1. Indeksator `SubTable[expression]` - logika biznesowa](#1-indeksator-subtableexpression---logika-biznesowa)
  - [2. `View.AddExpression(...)` - listy w UI](#2-viewaddexpression---listy-w-ui)
  - [3. `Query.Table.AddExpression(...)` - zapytania niskopoziomowe](#3-querytableaddexpression---zapytania-niskopoziomowe)
  - [4. `RowCondition.FromExpression(...)` - jawne budowanie warunku](#4-rowconditionfromexpression---jawne-budowanie-warunku)
- [Zakres możliwych wyrażeń](#zakres-możliwych-wyrażeń)
  - [Odwołania do pól](#odwołania-do-pól)
  - [Wartości po stronie klienta](#wartości-po-stronie-klienta)
  - [Typy proste, enum, int](#typy-proste-enum-int)
  - [Bool](#bool)
  - [String](#string)
  - [Null / not null](#null--not-null)
  - [Referencje](#referencje)
  - [Operator IN - przynależność do zbioru](#operator-in---przynależność-do-zbioru)
  - [Operatory logiczne i wyrażenia złożone](#operatory-logiczne-i-wyrażenia-złożone)
  - [Pola złożone (Quantity, Currency, FromTo)](#pola-złożone-quantity-currency-fromto)
  - [Kolekcje powiązane (podlisty)](#kolekcje-powiązane-podlisty)
- [Ograniczenia - co się nie skompiluje do SQL](#ograniczenia---co-się-nie-skompiluje-do-sql)
- [Kiedy używać czego](#kiedy-używać-czego)

## Najważniejsze zasady

* W wyrażeniu LINQ można odwoływać się **wyłącznie do pól bazodanowych** (kolumn tabeli, pól złożonych, kolekcji powiązanych, cech). Próba użycia pola niebazodanowego rzuca `LinqConditionException`.
* Po lewej i prawej stronie operatora porównania może wystąpić wyrażenie liczone po stronie klienta lub pole bazodanowe - kolejność jest dowolna (`row.Prop == wyr` lub `wyr == row.Prop`).
* Po stronie klienta można używać dowolnych pól, właściwości, wywołań metod, wyrażeń arytmetycznych - są one zewaluowane przed wysłaniem do SQL i wstawione jako stała.
* Wszystkie porównania tekstowe są **case-insensitive**.
* Wyrażenie LINQ jest tłumaczone na SQL, ale **kompilator C# wymusza poprawność typów** - błędy wykrywane są na etapie budowy projektu, a nie wykonania.

## Wzorce użycia w kodzie

### 1. Indeksator `SubTable[expression]` - logika biznesowa

Najwygodniejszy sposób odczytu odfiltrowanych danych w kodzie biznesowym. Zwraca nowy `SubTable` zawierający tylko pasujące wiersze:

```csharp
var st = Session.GetHandel().DokHandlowe.WgMagazyn[
    dok => dok.Kontrahent.Kod == "ABC"
];

foreach (DokumentHandlowy dok in st) {
    // ... operacje na odfiltrowanych dokumentach
}
```

Generowane SQL łączy tabele referencyjne automatycznie (`LEFT OUTER JOIN`) i osadza warunek w `WHERE`:

```sql
select * from DokHandlowe t0
left outer join Kontrahenci t1 on t0.Kontrahent = t1.ID
where t1.[Kod] = @?
order by t0.[Magazyn], t0.[Data], t0.[Czas], t0.[ID]
```

Sortowanie pochodzi z klucza wybranego indeksatorem (tu: `WgMagazyn`).

### 2. `View.AddExpression(...)` - listy w UI

`View` to obiekt warstwy UI używany do prezentacji list. Można na niego nakładać kolejne warunki, które są łączone operatorem `AND`:

```csharp
View view = Session.GetTowary().Towary.PrimaryKey.CreateView();

// Generyczna wersja - jawny typ wiersza
view.AddExpression<Towar>(t => LinqConditionMethods.Like(t.Kod, "B*"));

// Wersja z jawnym castem w wyrażeniu - przydatna dla cech (indeksatora `row["..."]`)
view.AddExpression((Towar t) => t["Asortyment"] == null);
```

`AddExpression` można wywoływać wielokrotnie - każdy warunek dokłada koniunkcję do zapytania.

### 3. `Query.Table.AddExpression(...)` - zapytania niskopoziomowe

Stosowane w niskopoziomowym budowaniu zapytań (`Query`). API identyczne jak dla `View`.

### 4. `RowCondition.FromExpression(...)` - jawne budowanie warunku

Gdy warunek ma być przekazywany jako wartość (parametr, zwracany z metody), buduje się go jawnie:

```csharp
var cond = RowCondition.FromExpression<Towar>(
    t => t.Dostawca.Kod == "ABC" && t.Typ == TypTowaru.Towar
);
```

Powstały obiekt można potem podać do `SubTable`, `View`, `Query`. Tłumaczenie na string SQL-like uzyskuje się przez `cond.ToString()` - przydatne w testach jednostkowych.

## Zakres możliwych wyrażeń

Poniższe sekcje opisują, co można umieścić wewnątrz `Expression<Predicate<TRow>>`. Każda pozycja ma przykład C# oraz - tam gdzie to istotne - postać po `ToString()` (zgodną z konwencją trzymaną w testach).

### Odwołania do pól

```csharp
// Pole proste
t => t.Kod == "ABC"

// Pole referencyjne (JOIN po referencji)
t => t.Dostawca.OddzialFirmy.Nazwa == "Nazwa"
//  -> [Dostawca.OddzialFirmy.Nazwa]='Nazwa'

// Łańcuch referencji z polem złożonym
t => t.Dostawca.Kontakt.EMAIL == "a@a.com"
//  -> [Dostawca.Kontakt.EMAIL]='a@a.com'

// Pole prywatne / protected - dostęp przez indeksator z castem
op => (string)op["Password", RowVersion.Original] == "ABC"
//  -> Password='ABC'

// Cecha (feature) - indeksator po nazwie cechy, prawa strona jako (object)
op => op["NAME"] == (object)"VALUE"
//  -> [Features.NAME]='VALUE'

// Cecha na obiekcie referencyjnym
t => t.Dostawca["NAME"] != (object)"VALUE"
//  -> [Dostawca.Features.NAME]<>'VALUE'

// Porównanie dwóch kolumn tego samego wiersza
op => op.Name == op.FullName
//  -> [Name]=[FullName]
```

### Wartości po stronie klienta

Można odwoływać się do pól/zmiennych/metod zdefiniowanych po stronie kodu - są one liczone raz, przed wysłaniem do SQL, i osadzane jako stała:

```csharp
private readonly string FieldString = "ABC";
private string PropertyString => "ABC";

op => op.Name == FieldString                       // Name='ABC'
op => op.Name == PropertyString                    // Name='ABC'
op => op.Name == PropertyString.Substring(1, 2)    // Name='BC'
```

### Typy proste, enum, int

```csharp
op => op.ID == 123       // ID='123'
op => op.ID != 123
op => op.ID >  123
op => op.ID >= 123
op => op.ID <  123
op => op.ID <= 123

// Kolejność może być odwrócona
op => 123 > op.ID        // ID<'123'

// Enum
t => t.Typ == TypTowaru.Receptura    // Typ=Receptura
```

### Bool

```csharp
op => op.Locked          // Locked
op => !op.Locked         // NOT Locked
```

### String

Wszystkie porównania są case-insensitive.

```csharp
op => op.Name == "ABC"               // Name='ABC'
op => "ABC" != op.Name               // Name<>'ABC'

// Większość/mniejszość przez CompareTo - na obiekcie lub statycznie:
op => op.Name.CompareTo("ABC") > 0          // Name>'ABC'
op => op.Name.CompareTo("ABC") >= 0
op => op.Name.CompareTo("ABC") <  0
op => op.Name.CompareTo("ABC") <= 0
op => 0 > op.Name.CompareTo("ABC")          // Name<'ABC' (kolejność odwrócona)
op => string.Compare(op.Name, "ABC") > 0    // Name>'ABC'
op => 0 < string.Compare(op.Name, "ABC")    // Name>'ABC'
op => 0 < string.Compare("ABC", op.Name)    // Name<'ABC'

// Dopasowanie podciągu / prefiksu / sufiksu - generuje SQL LIKE z escapowaniem znaków '*' i '%'
op => op.Name.Contains("A*B%C")             // Name like '%A[*]B[%]C%'
op => op.Name.StartsWith("A*B%C")           // Name like 'A[*]B[%]C%'
op => op.Name.EndsWith("ABC")               // Name like '%ABC'

// Pełna maska SQL LIKE (znaki '%' i '_' traktowane jako wildcardy)
op => LinqConditionMethods.Like(op.Name, "AB%C")    // Name like 'AB%C'
```

### Null / not null

```csharp
op => op.Name == null     // Name Is Null
op => op.Name != null     // Name Is Not Null
```

### Referencje

```csharp
t => t.Dostawca == null
t => t.Dostawca != null

// Weryfikacja typu referencji (sprawdzenie tabeli docelowej polimorficznej referencji)
t => t.Jednostka is Jednostka     // Jednostka typeof Jednostki

// Warunek na obiekcie wskazywanym przez referencję - alternatywa do "t.Ref.Pole == ..."
t => LinqConditionMethods.Join(t.Dostawca, k => k.Kod == "ABC")
//  -> join Dostawca where (Kod='ABC')
```

### Operator IN - przynależność do zbioru

`LinqConditionMethods.In` zastępuje rozpisany ciąg `pole == v1 || pole == v2 || ...`. Argumenty można podać jako `params` lub jako tablicę. Działa dla różnych typów - intów, dat, procentów, stringów, referencji:

```csharp
// Stringi (params)
t => LinqConditionMethods.In(t.Kod, new[] { "BIKINI", "XYZ" })

// Daty
d => LinqConditionMethods.In(d.Data, Date.Today.PrevDay, Date.Today, Date.Today.NextDay)

// Inty - params
d => LinqConditionMethods.In(d.ID, 1, 2)

// Inty - tablica
d => LinqConditionMethods.In(d.ID, new[] { 1, 2 })

// Procenty
d => LinqConditionMethods.In(d.Rabat, Percent.Parse("10%"), Percent.Parse("20%"))

// Referencje
t => LinqConditionMethods.In(t.Dostawca, kontra1, kontra2)
t => LinqConditionMethods.In(t.Dostawca, kontraArr)
```

### Operatory logiczne i wyrażenia złożone

```csharp
// AND, OR, NOT
op => op.Locked && op.ID > 234           // Locked and ID>'234'
op => !op.Locked || op.Name == "ABC"     // NOT Locked or Name='ABC'

// Operator warunkowy ?: - rozwijany do dwóch wykluczających się gałęzi
op => op.Locked ? op.Name == "ABC" : op.FullName == "DEF"
//  -> Locked and Name='ABC' or NOT Locked and FullName='DEF'

// Nawiasy - normalne nawiasy C# sterują grupowaniem
t => (t.Typ == TypTowaru.Towar || t.Typ == TypTowaru.Usluga) && t.Dostawca != null
```

### Pola złożone (Quantity, Currency, FromTo)

Można porównywać całe pole złożone albo pojedyncze elementy (`.Value`, `.Symbol`, `.From`, `.To`, ...):

```csharp
// Porównanie całego Quantity
t => t.MasaNetto == new Quantity(123, "kg")     // MasaNetto='123 kg'

// Składowe Quantity
t => t.MasaNetto.Value  == 123                  // [MasaNetto.Value]='123'
t => t.MasaNetto.Symbol == "szt"                // [MasaNetto.Symbol]='szt'

// FromTo - cały zakres
e => e.Okres == new YearMonth(2020, 2).ToFromTo()     // Okres='...'

// FromTo - składowa
e => e.Okres.From == new Date(2020, 2, 2)             // [Okres.From]='...'

// FromTo - przynależność daty do zakresu
e => e.Okres.Contains(new Date(2020, 2, 2))
//  -> [Okres.From]<='...' and [Okres.To]>='...'

// FromTo - przynależność zakresu do zakresu
e => e.Okres.Contains(new YearMonth(2020, 2).ToFromTo())

// FromTo - przecięcie zakresów (część wspólna niepusta)
e => e.Okres.IsIntersected(new YearMonth(2020, 2).ToFromTo())
```

### Kolekcje powiązane (podlisty)

Dla pól reprezentujących powiązaną podlistę:

```csharp
// Podlista pusta / niepusta
t => t.AdresyWWW.IsEmpty                                // NOT exists AdresWWW.Zapis
t => t.AdresyWWW.Any                                    // exists AdresWWW.Zapis
t => t.AdresyWWW.Any()                                  // exists AdresWWW.Zapis

// Egzystencjalny - istnieje przynajmniej jeden element spełniający warunek
t => t.AdresyWWW.Any(adr => adr.Domyslny)
//  -> exists AdresWWW.Zapis where (Domyslny)

// Egzystencjalny przez referencję
t => t.Dostawca.AdresyWWW.Any(adr => adr.Domyslny)
//  -> exists AdresWWW.Zapis=Dostawca where (Domyslny)

// Uniwersalny - wszystkie elementy spełniają warunek (równoważne: NOT exists element spełniający NEG)
t => t.AdresyWWW.All(adr => adr.Domyslny)
//  -> NOT exists AdresWWW.Zapis where (NOT Domyslny)

t => t.Dostawca.AdresyWWW.All(adr => adr.Domyslny)
//  -> NOT exists AdresWWW.Zapis=Dostawca where (NOT Domyslny)
```

## Ograniczenia - co się nie skompiluje do SQL

* **Pola niebazodanowe** - próba użycia właściwości obliczanej w C# (np. `op.NewPassword`) rzuca `LinqConditionException`.
* **Referencje przez pole nie-bazodanowe** - np. `t.Dostawca.Adres.Faks` gdy `Adres` nie jest fizyczną referencją w bazie - również `LinqConditionException`.
* W praktyce: jeśli pole jest deklarowane jako property w `business.xml`, jest bazodanowe; jeśli jest dopisywane jako property w klasie partial - nie jest.

## Kiedy używać czego

| Cel | API |
|---|---|
| Odczyt odfiltrowanego zbioru danych w logice biznesowej | `SubTable[t => ...]` |
| Filtrowanie listy w UI | `View.AddExpression(...)` |
| Przekazywanie warunku jako wartości / kompozycja warunków | `RowCondition.FromExpression(...)` |
| Niskopoziomowe zapytanie (Query) | `Query.Table.AddExpression(...)` |

**Kod biznesowy nie powinien używać `View`** (to obiekt UI). Kod biznesowy filtruj przez `SubTable[expression]` lub 
`RowCondition.FromExpression`.
