<?php
// OpenAPI metadata and component schemas for swagger-php.
// Annotation-only; does nothing at runtime.

/**
 * @OA\OpenApi(
 *   @OA\Info(
 *     title="Casadoc Mobile API (plain PHP)",
 *     version="1.0.0",
 *     description="Mobile REST API in plain PHP. Bearer tokens, uniform JSON."
 *   ),
 *   @OA\Server(url="/userportal/api", description="Casadoc Mobile API")
 * )
 *
 * @OA\SecurityScheme(
 *   securityScheme="bearerAuth",
 *   type="http",
 *   scheme="bearer",
 *   description="Token from POST /login.php. Header: Authorization: Bearer <token>"
 * )
 *
 * @OA\Tag(name="Auth", description="Login, tokens, current user")
 * @OA\Tag(name="Homes", description="Properties")
 * @OA\Tag(name="Documents", description="Document requirements, files, sections")
 * @OA\Tag(name="Owners", description="Owners and home links")
 * @OA\Tag(name="Sharing", description="Home sharing and invitations")
 * @OA\Tag(name="Reference", description="Read-only reference data")
 *
 * @OA\Response(response="Unauthorized", description="Missing/invalid token",
 *   @OA\JsonContent(ref="#/components/schemas/Error"))
 * @OA\Response(response="Forbidden", description="No access to resource",
 *   @OA\JsonContent(ref="#/components/schemas/Error"))
 * @OA\Response(response="NotFound", description="Not found",
 *   @OA\JsonContent(ref="#/components/schemas/Error"))
 * @OA\Response(response="ValidationError", description="Validation error",
 *   @OA\JsonContent(ref="#/components/schemas/Error"))
 * @OA\Response(response="Success", description="Success",
 *   @OA\JsonContent(@OA\Property(property="success", type="boolean", example=true)))
 */
final class OpenApiMeta
{
}

/**
 * @OA\Schema(schema="Error",
 *   @OA\Property(property="error", type="object",
 *     @OA\Property(property="code", type="string", example="forbidden"),
 *     @OA\Property(property="message", type="string"),
 *     @OA\Property(property="fields", type="object", nullable=true,
 *       description="field -> array of errors (422 only)")
 *   )
 * )
 */
final class ErrorSchema
{
}

/**
 * @OA\Schema(schema="User",
 *   @OA\Property(property="id", type="integer"),
 *   @OA\Property(property="first_name", type="string", nullable=true),
 *   @OA\Property(property="last_name", type="string", nullable=true),
 *   @OA\Property(property="email", type="string", format="email"),
 *   @OA\Property(property="username", type="string", nullable=true),
 *   @OA\Property(property="phone", type="string", nullable=true),
 *   @OA\Property(property="address", type="string", nullable=true),
 *   @OA\Property(property="avatar", type="string", nullable=true, description="absolute URL")
 * )
 */
final class UserSchema
{
}

/**
 * @OA\Schema(schema="Home",
 *   @OA\Property(property="idhome", type="integer"),
 *   @OA\Property(property="name", type="string", nullable=true),
 *   @OA\Property(property="comment", type="string", nullable=true),
 *   @OA\Property(property="fulladdress", type="string", nullable=true),
 *   @OA\Property(property="address", type="string", nullable=true),
 *   @OA\Property(property="zip", type="string", nullable=true),
 *   @OA\Property(property="city", type="string", nullable=true),
 *   @OA\Property(property="country", type="string", nullable=true),
 *   @OA\Property(property="latitude", type="string", nullable=true),
 *   @OA\Property(property="longitude", type="string", nullable=true),
 *   @OA\Property(property="mainphoto", type="string", nullable=true),
 *   @OA\Property(property="photo_url", type="string", nullable=true),
 *   @OA\Property(property="cadastral_municipality", type="string", nullable=true),
 *   @OA\Property(property="cadastral_section", type="string", nullable=true),
 *   @OA\Property(property="cadastral_sheet", type="string", nullable=true),
 *   @OA\Property(property="cadastral_particle", type="string", nullable=true),
 *   @OA\Property(property="cadastral_sub", type="string", nullable=true),
 *   @OA\Property(property="cadastral_category", type="string", nullable=true),
 *   @OA\Property(property="cadastral_class", type="string", nullable=true),
 *   @OA\Property(property="cadastral_surface", type="string", nullable=true),
 *   @OA\Property(property="cadastral_rendita", type="string", nullable=true),
 *   @OA\Property(property="cadastral_notes", type="string", nullable=true),
 *   @OA\Property(property="is_owner", type="boolean"),
 *   @OA\Property(property="documents_count", type="integer", description="uploaded files for the property"),
 *   @OA\Property(property="expiring_count", type="integer", description="expiring within 60 days or already expired")
 * )
 */
final class HomeSchema
{
}

/**
 * @OA\Schema(schema="Section",
 *   @OA\Property(property="idsections", type="integer"),
 *   @OA\Property(property="section_name", type="string"),
 *   @OA\Property(property="description", type="string", nullable=true)
 * )
 */
final class SectionSchema
{
}

/**
 * @OA\Schema(schema="UploadedFile",
 *   @OA\Property(property="id", type="integer"),
 *   @OA\Property(property="document_id", type="integer"),
 *   @OA\Property(property="title", type="string", nullable=true, description="user-defined display name; falls back to the requirement name"),
 *   @OA\Property(property="idhome", type="integer", nullable=true),
 *   @OA\Property(property="owner_id", type="integer", nullable=true),
 *   @OA\Property(property="filename", type="string"),
 *   @OA\Property(property="size", type="integer", nullable=true, description="bytes on disk, null if missing"),
 *   @OA\Property(property="url", type="string"),
 *   @OA\Property(property="expiry_date", type="string", format="date", nullable=true),
 *   @OA\Property(property="expiry_status", type="integer", nullable=true, description="tinyint 0/1"),
 *   @OA\Property(property="note", type="string", nullable=true),
 *   @OA\Property(property="created_at", type="string", nullable=true)
 * )
 */
final class UploadedFileSchema
{
}

/**
 * @OA\Schema(schema="DocumentRequirement",
 *   description="Document template (documents) plus its uploaded files",
 *   @OA\Property(property="document_id", type="integer"),
 *   @OA\Property(property="document_name", type="string"),
 *   @OA\Property(property="page_id", type="integer", nullable=true),
 *   @OA\Property(property="idsections", type="integer", nullable=true),
 *   @OA\Property(property="section_name", type="string", nullable=true),
 *   @OA\Property(property="max_documents", type="integer"),
 *   @OA\Property(property="is_required", type="boolean"),
 *   @OA\Property(property="notes", type="string", nullable=true),
 *   @OA\Property(property="files", type="array", @OA\Items(ref="#/components/schemas/UploadedFile"))
 * )
 */
final class DocumentRequirementSchema
{
}

/**
 * @OA\Schema(schema="DocumentTemplate",
 *   @OA\Property(property="document_id", type="integer"),
 *   @OA\Property(property="document_name", type="string"),
 *   @OA\Property(property="page_id", type="integer", nullable=true),
 *   @OA\Property(property="idsections", type="integer", nullable=true),
 *   @OA\Property(property="section_name", type="string", nullable=true),
 *   @OA\Property(property="max_documents", type="integer"),
 *   @OA\Property(property="is_required", type="boolean"),
 *   @OA\Property(property="notes", type="string", nullable=true)
 * )
 */
final class DocumentTemplateSchema
{
}

/**
 * @OA\Schema(schema="Page",
 *   @OA\Property(property="idpages", type="integer"),
 *   @OA\Property(property="namepages", type="string"),
 *   @OA\Property(property="slug", type="string"),
 *   @OA\Property(property="descriptionpages", type="string", nullable=true)
 * )
 */
final class PageSchema
{
}

/**
 * @OA\Schema(schema="Owner",
 *   @OA\Property(property="owner_id", type="integer"),
 *   @OA\Property(property="owner_type", type="string", enum={"individual","company"}),
 *   @OA\Property(property="first_name", type="string", nullable=true),
 *   @OA\Property(property="last_name", type="string", nullable=true),
 *   @OA\Property(property="company_name", type="string", nullable=true),
 *   @OA\Property(property="tax_code", type="string"),
 *   @OA\Property(property="email", type="string", nullable=true),
 *   @OA\Property(property="phone", type="string", nullable=true),
 *   @OA\Property(property="address", type="string", nullable=true),
 *   @OA\Property(property="postal_code", type="string", nullable=true),
 *   @OA\Property(property="city", type="string", nullable=true),
 *   @OA\Property(property="province", type="string", nullable=true),
 *   @OA\Property(property="country", type="integer", nullable=true),
 *   @OA\Property(property="role", type="string", nullable=true)
 * )
 */
final class OwnerSchema
{
}

/**
 * @OA\Schema(schema="HomeOwner",
 *   @OA\Property(property="owner", ref="#/components/schemas/Owner"),
 *   @OA\Property(property="ownership_percentage", type="number", format="float"),
 *   @OA\Property(property="notes", type="string", nullable=true)
 * )
 */
final class HomeOwnerSchema
{
}

/**
 * @OA\Schema(schema="SharingRole",
 *   @OA\Property(property="idrole", type="integer"),
 *   @OA\Property(property="role_name", type="string"),
 *   @OA\Property(property="description", type="string", nullable=true),
 *   @OA\Property(property="permissions", type="array", @OA\Items(type="string"))
 * )
 */
final class SharingRoleSchema
{
}

/**
 * @OA\Schema(schema="Share",
 *   @OA\Property(property="idsharing", type="integer"),
 *   @OA\Property(property="idhome", type="integer"),
 *   @OA\Property(property="shared_email", type="string", format="email"),
 *   @OA\Property(property="idshareduser", type="integer", nullable=true),
 *   @OA\Property(property="role", ref="#/components/schemas/SharingRole", nullable=true),
 *   @OA\Property(property="sharing_type", type="string"),
 *   @OA\Property(property="shared_sections", type="array", @OA\Items(type="integer")),
 *   @OA\Property(property="expiration_date", type="string", format="date", nullable=true),
 *   @OA\Property(property="status", type="string", enum={"pending","accepted","rejected"})
 * )
 */
final class ShareSchema
{
}