به محتوای اصلی

مدل داده

مدل داده قلب پروژه است: موجودیت‌ها، فیلدها، قیدها و روابط را اینجا تعریف می‌کنید و API از روی همین تعریف ساخته می‌شود.

موجودیت‌ها

هر موجودیت یک نام نمایشی فارسی دارد («سفارش») و یک شناسهٔ انگلیسی (order) که در آدرس اندپوینت می‌نشیند. شناسه باید انگلیسی، حروف کوچک و بدون فاصله باشد — مثل order_item. موجودیت بدون فیلد مجاز نیست.

انواع فیلد

متن، عدد، بولین، تاریخ، ساعت، ایمیل، موبایل، نشانی وب، فهرست (enum) و JSON. برای موبایل، شماره‌ها در قالب استاندارد E.164 (مثل +98912...) ذخیره می‌شوند و ارقام فارسی ورودی به‌صورت خودکار نرمال می‌شوند.

فیلد ساعت برای ساعتِ روز بدون تاریخ است — ساعت ورود، شروع شیفت، ساعت کاری. مقدارش به شکل استاندارد ISO 8601 و ۲۴ساعته ذخیره و برگردانده می‌شود: "08:30"، و ثانیه فقط وقتی صفر نباشد ("08:30:15"). ورودی "8:30"، "08:30:00" و "۰۸:۳۰" همه به "08:30" تبدیل می‌شوند. منطقهٔ زمانی، 24:00 و AM/PM پذیرفته نمی‌شوند. فیلتر و مرتب‌سازی روی آن به ترتیب زمانی درست کار می‌کند:

GET /v1/attendance?filter[check_in][gte]=08:00&sort=check_in

برای «دقیقه از ابتدای روز» در فیلد عددی نگه ندارید؛ فیلد ساعت هم اعتبارسنجی بازه را دارد و هم در پاسخ API همان چیزی است که کاربر می‌خواند.

قیدها

روی هر فیلد می‌توانید قید بگذارید: الزامی، یکتا، حداقل/حداکثر (طول یا مقدار) و الگوی regex. قیدها همان ابتدا تعریف شوند تا دادهٔ نامعتبر هرگز ذخیره نشود؛ درخواستی که قید را نقض کند با خطای ۴۲۲ و پیام روشن رد می‌شود.

فیلدهایی که فقط شما می‌نویسید

بعضی فیلدها را کاربر اپ می‌بیند ولی نباید خودش تعیین کند: وضعیت سفارش، مبلغ کل، قیمت لحظهٔ خرید. برای این‌ها در ویرایشگر فیلد، «نوشتن این فیلد» را روی «فقط شما (کلید API و ادمین)» بگذارید. در تعریف مدل داده این همان writeScope: "admin" است و در قالب‌ها write_scope: admin.

از آن به بعد این فیلد را فقط این‌ها می‌نویسند: کلید Production روی سرور خودتان، کاربری با نقش مدیر، ctx.db.admin در فانکشن‌ها، ویرایش و ورود داده از پنل، و قانون‌ها. کاربر عادی، نقش‌های سفارشی و فانکشن با ctx.db معمولی اگر مقدار تازه‌ای بفرستند، کل درخواست رد می‌شود؛ هیچ بخشی از آن نوشته نمی‌شود و فیلد بی‌صدا کنار گذاشته نمی‌شود. (کلید عمومی اصلاً نمی‌نویسد و زودتر با publishable_read_only رد می‌شود.) ساخت از مسیر تو در تو هم همین‌طور است، و ثبت گروهی این‌طور:

  • ساخت گروهی (POST /{entity}/bulk): اگر حتی یک رکورد مقدار تازه بدهد، کل دسته رد می‌شود و هیچ رکوردی ثبت نمی‌شود.
  • ویرایش گروهی (PATCH /{entity}/bulk): هر رکورد جدا سنجیده می‌شود. در حالت partial همان رکورد با field_admin_only در errors می‌آید و پاسخ ۲۰۷ است؛ در حالت atomic کل دسته با همان کد و اندیس رکورد رد می‌شود.
PATCH /v1/order/{id}        ← با توکن کاربر عادی
{"status": "paid"}

403
{"code": "field_admin_only", "detail": "فیلد «status» (وضعیت) را فقط مدیر پروژه می‌نویسد: …"}

در ویرایش، فرستادن همان مقدار فعلی ایراد ندارد — به شرطی که فرستنده هم این رکورد را بخواند و هم این فیلد را؛ پس اپی که رکورد را می‌خواند و همهٔ فیلدهایش را برمی‌گرداند نمی‌شکند. هنگام ساخت فقط مقدار پیش‌فرض فیلد پذیرفته است، یا اگر پیش‌فرض ندارد، null. ستون مالک (با شناسهٔ خود فرستنده) و کلید خارجیِ مسیر تو در تو را خود موتور پر می‌کند و فرستادنشان رد نمی‌شود. دیدن فیلد را این گزینه عوض نمی‌کند؛ آن کار «دیدن این فیلد» است.

فیلدی که هم الزامی است، هم فقط-مدیر و مقدار پیش‌فرض ندارد، یعنی کاربران اپ در این جدول رکورد نمی‌سازند و فقط سرور می‌نویسد. اگر عمداً چنین جدولی می‌خواهید درست است؛ وگرنه برای فیلد مقدار پیش‌فرض بگذارید (مثلاً سفارش با وضعیت «در انتظار» شروع شود).

فیلد محاسباتی

فیلدی که ذخیره نمی‌شود و هنگام خواندن، از روی بقیهٔ فیلدها محاسبه می‌شود. فرمول با زبان CEL نوشته می‌شود:

total_with_tax = total * 1.09

برای مقادیر مشتق‌شده (مثل قیمت با مالیات) همیشه به‌جای ذخیره، فیلد محاسباتی به‌کار ببرید تا هیچ‌وقت ناهماهنگ نشود.

روابط

سه نوع رابطه پشتیبانی می‌شود: belongsTo (تعلق به والد)، hasMany (یک‌به‌چند) و manyToMany (چندبه‌چند). بعد از تعریف رابطه:

# رکوردهای مرتبط را همراه پاسخ بگیرید
GET /v1/order?include=order_item

# یا از مسیر تو در تو استفاده کنید
GET /v1/order/{id}/order_item

تغییر مدل بعد از انتشار

تغییرات با «ذخیره و اعمال» اجرا می‌شوند و فیکارو قبل از اعمال می‌گوید هر تغییر ایمن است یا مخرب — جزئیات در مفاهیم پایه. مستندات و خروجی‌های پروژه (Postman ،Bruno ،SDK) بعد از هر اعمال، خودکار به‌روز می‌شوند.

ویرایش مدل داده روی موبایل فقط-خواندنی است؛ برای طراحی مدل از دسکتاپ استفاده کنید.