Metadata-Version: 2.4
Name: sysnet-persons-model
Version: 1.2.7
Summary: SYSNET Persons Data Model
Author-email: Data Developer <info@sysnet.cz>
License-Expression: LicenseRef-SYSNET-FreeForHomeUse
Project-URL: Homepage, https://github.com/SYSNET-CZ/models/tree/main/persons
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Czech
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sysnet-pyutils>=1.7.0
Requires-Dist: pydantic[email]>=2.11.4
Dynamic: license-file

# sysnet-persons-model

**Sdílený datový model Registru osob SYSNET**

[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue)](https://www.python.org/)
[![Pydantic](https://img.shields.io/badge/pydantic-%E2%89%A52.11.4-red)](https://docs.pydantic.dev/)
[![PyPI](https://img.shields.io/badge/PyPI-sysnet--persons--model-orange)](https://pypi.org/project/sysnet-persons-model/)

Čistá Python knihovna — **bez FastAPI, bez MongoDB**. Slouží jako sdílená datová vrstva
importovaná dalšími službami SYSNET.

---

## Instalace

```bash
pip install sysnet-persons-model
```

---

## Rychlý start

```python
from persons_model.individual import IndividualType
from persons_model.person_entity import PersonEntityType
from persons_model.role import RoleType
from persons_model.common import RegistryType, MembershipEnum, MemberType
from persons_model.tag import TagType, TagItemType

# Vytvoření jednotlivce
person = IndividualType(
    identifier="550e8400-e29b-41d4-a716-446655440000",
    name="Jan Novák",
    username="jnovak",
)

# Přidání tagu
person.tags = TagType()
person.tags.add_tag(TagItemType(tag="aktivni", color="#00FF00"))
```

---

## Moduly

### `common` — Společné typy

| Třída / Enum | Popis |
|---|---|
| `RegistryEnum` | Identifikační registry (`CRZP`, `EMPTY`) |
| `RegistryType` | Reference na identifikační údaje (uuid, uri, other) |
| `MembershipEnum` | Typ členství: admin, representative, employee, department, general, other |
| `MemberType` | Členský záznam |
| `ContactType` | Kontaktní údaje osoby |
| `RedundantType` | Redundantní záznam (name, code, location, note) |
| `DepartmentType` | Útvar organizace (rozšiřuje `RedundantType` o `parent`) |
| `IssuingType` | Údaje pro vydávání dokladů |
| `ScopeType` | Definice rozsahu působnosti (Global, Regional, Local) |

### `individual` — Jednotlivci (uživatelé)

| Třída | Popis |
|---|---|
| `IndividualBaseType` | Základní atributy: jméno, username, DN, heslo, kontakty, adresy, GDPR |
| `IndividualEntryType` | Zkrácená položka pro seznam |
| `IndividualType` | Plný záznam osoby (rozšiřuje Base o identifier, pid, registry, tags, document) |
| `IndividualListType` | Stránkovaný seznam osob |

### `person_entity` — Subjekty

| Třída | Popis |
|---|---|
| `PersonEntityLinkType` | Odkaz na navázaný subjekt |
| `PersonEntityEntryType` | Položka subjektu v kontextu |
| `PersonEntityBaseType` | Základní atributy subjektu (včetně `scope`) |
| `PersonEntityType` | Plný záznam (fyzická / právnická osoba) |
| `PersonEntityListType` | Stránkovaný seznam subjektů |

### `role` — Role

| Třída / Enum | Popis |
|---|---|
| `RoleCategoryEnum` | `individual`, `personal`, `security`, `other` |
| `RoleCategoryType` | Boolean příznaky kategorií |
| `RoleBaseType` | Základ role (code, name, categories, note) |
| `RoleEntryType` | Položka seznamu rolí (rozšiřuje Base o identifier) |
| `RoleType` | Plná role s holders, admins, tags, document |
| `RoleListType` | Stránkovaný seznam rolí |

### `context` — Uživatelský kontext

| Třída | Popis |
|---|---|
| `ContextRolesType` | Role uživatele/subjektu (admin, holder) |
| `ContextPersonsType` | Subjekty uživatele (admin, contact, member, representative) |
| `ContextIndividualType` | Kompletní kontext konkrétního uživatele |

### `tag` — Tagy

| Třída | Popis |
|---|---|
| `TagItemType` | Jedna značka (tag, color) |
| `TagType` | Seznam tagů s metodami `has_tag`, `add_tag`, `remove_tag` |
| `TagListType` | Stránkovaný seznam tagů |

### `country` — Země (ISO 3166-1)

| Třída | Popis |
|---|---|
| `CountryType` | Stát: kódy n3/a2/a3, název česky a anglicky |
| `CountryListType` | Stránkovaný seznam zemí |
| `CountryMapType` | Seznam ve formátu code/value |

### `config` — Konfigurace

| Třída | Popis |
|---|---|
| `ConfigType` | Minimální konfigurace (`cache: Optional[StrictBool]`) |

---

## Vývoj

Viz [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) pro podrobnou vývojovou příručku.

```powershell
# Klonování a nastavení prostředí
cd D:\development\git\models\persons
.venv\Scripts\python.exe -m pip install -e .

# Spuštění testů
.venv\Scripts\python.exe -m pytest

# Spuštění testů s pokrytím
.venv\Scripts\python.exe -m pytest --cov=persons_model --cov-report=term-missing
```

---

## Technický stack

| Vrstva | Technologie | Verze |
|---|---|---|
| Datové modely | Pydantic v2 | ≥ 2.11.4 |
| Utility | sysnet-pyutils | ≥ 1.7.0 |
| Python | CPython | ≥ 3.10 |
| Testy | pytest + pytest-cov | 9.x / 7.x |

---

## Architektura

Viz [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

Všechny modely dodržují konzistentní vzor:
1. `BaseType` — základní atributy bez identifikátoru
2. `EntryType` — zkrácená položka pro seznamy
3. plný `Type` — rozšiřuje Base o `identifier`, `pid`, `registry`, `tags`, `document`
4. `ListType` — obálka pro stránkované výsledky (`hits`, `entries`)

---

## Verze

Aktuální verze: **1.2.0**

Repozitář: https://github.com/SYSNET-CZ/models/tree/main/persons
