# عقد تكامل نموذج روزا — الإصدار 1

هذا نموذج عرض محلي ببيانات وهمية. لا يرسل رسائل ولا يحصّل أموالًا. جميع الواجهات تستخدم المفتاح `roza.prototype.v1` على الأصل نفسه. الملفات المشتركة تنسخ آليًا إلى `assets/` داخل كل واجهة لتعمل منفردة عند تسليمها.

## تحميل الملفات

```html
<link rel="stylesheet" href="assets/roza.css">
<link rel="stylesheet" href="app.css">
<script src="assets/roza.js"></script>
<script src="app.js"></script>
```

## واجهة window.Roza

- `get()` نسخة من الحالة الحالية. `update(fn)` يمرر الحالة لـfn ثم يحفظها. `reset()` يعيد بيانات البداية. حدث `roza:change` يعلن التغييرات؛ تجنب إعادة بناء نموذج يدخله المستخدم عند كل ضغط مفتاح.
- `money(n)` ريال يمني؛ `esc(value)` تهريب HTML؛ `icon(name)` SVG names: home, calendar, grid, search, bell, user, users, wallet, box, check, arrow, plus, close, heart, star, settings, file, chart, clock, camera, chevron, logout, filter, download, menu, phone, location, truck, shield, wifi, flower, edit, trash, layers, share.
- `badge(value)` شارة HTML بمسمى عربي للحالة، `toast(message,type)` نوع success/error/info.
- `normalizePhone(value)` يوحد صيغ الهاتف اليمني المحلي و+967/00967 والمسافات والأرقام العربية لأغراض مقارنة الهوية، مع الحفاظ على معرف الحساب الداخلي.
- `findBooking(id)` نسخة الحجز، `createBooking(input)` يعيد الحجز الجديد أو يرمي Error برسالة عربية. `input`: modelId,date,hallId,customerId,customerName,phone,color,chair,flowers,notes,extras(array of service IDs),source(client/partner/admin),partnerId,method,contractStatus. إذا source=admin مهلة10دقائق، وmethod=transfer خارج الدوام يرفض قبل الإنشاء. باقي مهلة العميل إعداد عرض منفصل30دقيقة. تحسب الأسعار والعربون من الحالة. يمكن تمرير `id` فقط للتفاصيل لا لإنشاء هوية سجل مزيفة.
- `availableFlowerColors(modelId, date, { extras, excludeBookingId } = {})` يعيد أسماء ألوان الورد المتاحة من مخزون التصميم والخدمات. إذا كانت للكوشة خيارات ورد، يرسل `createBooking` اللون في `input.flowerColor`. يراجع المحرك الكمية ويخصصها عند إنشاء الطلب ويحفظ `booking.flowerColor`.
- `availableOffers({ modelId, date, hallId, source, partnerId })` يعيد عروض الحزم المنشورة المؤهلة. `quoteBooking({ modelId, date, hallId, source, partnerId, offerId, extras })` يعيد سعر الحزمة والخدمات المضافة والتخفيض المؤهل والإجمالي والعربون. يمكن إرسال `expectedQuoteKey` و`expectedTotal` إلى `createBooking` لحماية السعر الذي رآه المستخدم قبل الموافقة.
- يحتفظ الحجز بـ`pricing` لنسخة السعر والعرض والتخفيض وفئة الطرف وحالة اعتماد القاعة. إذا تغيرت الأهلية أو السعر قبل التأكيد، تظهر `pricingReview.reason` ويتيح `refreshBookingQuote(bookingId)` إعداد نسخة عقد جديدة صراحةً عندما تبقى موارد الحجز نفسها. تبقى أسعار الحجوزات المؤكدة محفوظة.
- `pay(id,method,amount)` يعيد الحجز؛ methods wallet/external/transfer/cash. `transfer` ينتظر review ولا يزيد paid. `approveTransfer(id)` يعتمد الدليل التجريبي. `verifyPayment(id,success)` يحسم checking؛ `external` يتبع settings.paymentScenario(success/checking/failed). wallet لعميل الحجز ومن وسيلة واحدة للعربون. cash متاح في اللوحة فقط. كرر الإجراء بعد نجاحه لا يضاعف المبلغ. لا تنشأ زيادة paid إلى أكثر من total.
- `approveContract(id)` يثبت موافقة النسخة الحالية ويؤكد فقط عند سداد العربون والتوفر. صاحب القاعة/الإدارة يعرض مسار موافقة العميل، لا اعتماد الشريك بديلًا عنه.
- `requestChange(id,type,details)` type=date/open/cancel/edit؛ details قد تحوي date,reason,modelId,color. يعيد طلبًا بالحالة pending. `approveChange(changeId)` يعتمد مع الحفاظ على النسخة السابقة؛ cancel يتيح المدفوع بالمحفظة ويقيد السحب حتى تحقق بديل، open يحرر الموارد ويعيد المحصل مرة واحدة.
- `assign(id,technicianId)` يربط الحجز بالفني، `advance(id,status)` مراحل received/installing/installed/withdrawn. البدء يتطلب السداد الكامل أو financialException مستقل، وصرف/مطابقة عهدة أو operationalException أو نقل معتمد. يُسجل offline في queue وlocalExecutionStatus دون نشر للعميل حتى sync.
- `uploadPhotos(id,files)` async، صور فقط وحتى1MB و3صورإجمالًا. `sync()` يراجع queue ضد النسخة والحالة ويعيد النتائج دون إعادة إحياء ملغى. `expireLocks()` يحرر pending المنتهي، `returnItems(id,returns)` returns array {itemId,quantity,condition} وتذهب للفحص، `inspectItems(id)` يتاح السليم فقط بعدالفحص، `directTransfer(fromId,toId,items)` ينقل العهدة دونمخزن، `qualifyReplacement(cancelledId,replacementId)` يغيّرأهليةالمتبقيلايضيفرصيدًا، `refund(id,amount)` يصرفالمؤهل المتبقي فقط. `exportCSV(filename,rows)` تنزيل CSV UTF8بـBOM.

## شكل الحالة

```js
{
 version:1,
 settings:{deposit:20000,officeOpen:true,offline:false,paymentScenario:'success',officeHours:'09:00–21:00',timezone:'Asia/Aden',loyaltyRate:1},
 profile:{id:'c1',name:'سارة أحمد',phone:'770000001',email:'sara@example.test',type:'customer',hallContact:'',location:'',maps:'',rent:0},
 catalog:[{id:'m1',name:'أوركيد الملكية',category:'الأكثر طلبًا',price:120000,image:'stage-1.jpg',colors:['أبيض عاجي','ذهبي','وردي'],width:6,height:3,description:'...',capacity:2,active:true,components:[{itemId:'i1',quantity:1}]}],
 halls:[{id:'h1',name:'قاعة ليلتي',width:8,height:4,location:'صنعاء',maps:'https://maps.google.com/...',rent:180000,contact:'770000010',partnerId:'p1'}],
 services:[{id:'sv1',name:'ورد طبيعي',price:15000,type:'consumable'}],
 customers:[{id:'c1',name:'سارة أحمد',phone:'770000001'},{id:'c2',name:'محمد علي',phone:'770000002'},{id:'c3',name:'ندى محمد',phone:'770000003'}],
 technicians:[{id:'t1',name:'أحمد صالح',rate:10},{id:'t2',name:'خالد علي',rate:8}],
 serviceStaff:[{id:'s1',name:'مريم حسن',rate:5}],
 wallets:{c1:{available:60000,withdrawable:20000,held:0,debt:0,points:240,transactions:[]},c2:{...},c3:{...}},
 bookings:[{id:'RZ-1024',customerId:'c1',customerName:'سارة أحمد',phone:'770000001',partnerId:null,hallId:'h1',hallName:'قاعة ليلتي',date:'2026-12-05',modelId:'m1',modelName:'أوركيد الملكية',color:'أبيض عاجي',chair:'عاجي',flowers:'أبيض',basePrice:120000,total:135000,paid:20000,deposit:20000,source:'client',status:'confirmed',contractStatus:'approved',contractVersion:1,paymentStatus:'verified',executionStatus:'assigned',technicianId:'t1',serviceId:'s1',notes:'...',extras:['sv1'],photos:[],items:[{itemId:'i1',name:'خلفية أوركيد',quantity:1,issued:0,returned:0,damaged:0,inspecting:0}],events:[{at:'ISO',text:'...',actor:'...'}],version:1,lockUntil:null,financialException:false,operationalException:false,contracts:[]}],
 inventory:[{id:'i1',name:'خلفية أوركيد',unit:'قطعة',total:5,available:3,reserved:2,issued:0,inspection:0,damaged:0,type:'returnable'}],
 payments:[{id:'P-1',bookingId:'RZ-1024',amount:20000,method:'external',status:'verified',date:'ISO'}],
 changes:[],queue:[],notifications:[{id:'n1',title:'...',body:'...',read:false}],
 accounts:[{code:'1',name:'الأصول',type:'asset'}],
 expenses:[{id:'E-1',name:'نقل وتجهيز',amount:12000,date:'2026-11-17',account:'المصروفات'}],
 audit:[],favorites:['m1'],reviews:[],offers:[],discounts:[],messages:[],users:[{id:'u1',name:'...',role:'admin',active:true}],permissions:{},
 hallAccounts:[{id:'p1',type:'partner',hallId:'h1',approvalStatus:'approved'}],
 ui:{adminRole:'admin',operationsRole:'technician',technicianId:'t1',serviceId:'s1',clientType:'customer'}
}
```

يحتفظ سجل الكوشة بـ`active` للنشر، و`image` لصورة الغلاف، و`components: [{ itemId, quantity, installation }]` للتجميعة. يمكن أن يتكرر الصنف بأكثر من طريقة تركيب. تجمع كمياته في بند عهدة واحد ويحفظ البند تفاصيل الاستخدام في `componentUses`. يدعم صنف المخزون حقول `category` و`variant` و`unit` و`image` للمكتبة.

تربط `flowerOptions: [{ color, itemId, quantity }]` كل بديل للورد بصنف مشترك من المخزون. تتيح `albums: [{ hallId, color, images }]` حفظ صور كل تنفيذ باسم القاعة ولون الورد الظاهر. غياب صورة لقاعة أو لون لا يؤثر في الحجز. الحقل `colors` للألوان العامة للتصميم، منفصل عن ألوان الورد ذات المخزون.

`offers: [{ id, name, modelId, serviceIds, price, audience, startDate, endDate, dateBasis, active, archivedAt }]` لسعر حزمة كوشة وخدمات. `discounts` يسجل بيانات السريان نفسها بالإضافة إلى `type`, `value`, `scope`, `priority`, `eligibility`, `allowWithOffer`, `allowWithLoyalty`. تضاف الخدمات الداخلة في العرض إلى التنفيذ والمخزون مرة واحدة. يُختار تخفيض واحد بحسب الأولوية، ويُحتسب على البنود التي تشملها القاعدة. يغطي السعر النهائي العربون الثابت لبدء الحجز. تحفظ `hallAccounts` معرف الشريك والقاعة وحالة الاعتماد وسجل المراجعة، وتظل صفة الشريك مستقلة عن مكان المناسبة.

يحتسب النموذج المحلي يوم المناسبة مع هوامش التجهيز والنقل والفحص. يحفظ فترة التخصيص في `booking.resourceWindow`. كميات الورد القابل للإرجاع والمخصصة لفترة تبقى ضمن رصيد الصرف الفعلي حتى تُصرف، وتحسب `availableFlowerColors` المتاح بعد الكميات المخصصة لفترات متداخلة. الأصناف المصروفة وتحت الفحص تظل خارج رصيد الصرف حتى الإرجاع والفحص.

`photos`: {id,url,status:'uploaded',at}. الصور المحلية في queue فقط. `queue`: {id,bookingId,action,payload,version,status:'pending'/'accepted'/'review',reason,at}. change:{id,bookingId,type,details,status,at}. لا تعرض بيانات عميل آخر في حساب c1؛ صاحب القاعة يرى partnerId=p1 فقط. لا تفترض أن كل حجز إسنادلفني واحدقيدمعماري، استخدام معرفواحدهنا مثالللعرضفقط.

مسموح إضافة حقول بواسطة update عند الحاجة لكن أبلغ الوكيل الرئيسي لتوثيقها. كل الأرقام والسياسات غير المثبتة بيانات عرض. root يراجع القواعد والأفعال ومصفوفة التغطية؛ الواجهات لا تثبت أمانالخادم.

امتدادات الواجهات: `booking.transferProof={name,type,size}` بيانات وصفية لدليل حوالة بعد التحقق من النوع والحجم فقط؛ لا تثبت تحصيلًا. `booking.issueRequested/issueRequestedAt` طلب الفني للصرف دون تغيير الكميات؛ يمسح علم الطلب عند اعتماد المخزن عبر issueItems. `serviceExecutionNote/serviceExecutionAt` ملاحظات مسؤول الخدمات. `profile.temporary` يميز حساب تسجيل تجريبي جديد مع معرف مستقل وحساب رصيد ابتدائي صفري. إعدادات الهوية والدخول هنا محلية تجريبية ولا تثبت ملكية حساب حقيقي.

حالة تنفيذ مسؤول الخدمات مستقلة في `serviceStatus` بالقيم assigned/received/installing/completed، مع `serviceReceived/serviceCompleted`. عند حفظ تحديث خدمة دون اتصال يستخدم `queue.action='serviceAdvance'` مع `payload={status,serviceStatus}`؛ يراجع المحرك النسخة والحالة ثم يحدث الخدمة فقط، ولا يغير مراحل الفني. تحفظ الحالة المحلية في localServiceStatus حتى المزامنة.
