مدل داده
مدل داده قلب پروژه است: موجودیتها، فیلدها، قیدها و روابط را اینجا تعریف میکنید و 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) بعد از هر اعمال، خودکار بهروز میشوند.
ویرایش مدل داده روی موبایل فقط-خواندنی است؛ برای طراحی مدل از دسکتاپ استفاده کنید.