# بازبینی ۱۴۰۵/۰۵/۰۵ — بازسازی انترپرایز بخش ضرر و زیان (زیان‌نگار)

هدف: رفع هر نه نقص شناسایی‌شده، انطباق کامل با قالب رسمی کارفرما
(«ساختار کلی لایحه ضرر و زیان») و یکپارچگی با موتور تأخیرات.

## ۱) موتور جمع‌بندی درست — `utils/lossFormulas.ts`

هر فرمول دو ویژگی جدید گرفت:

| ویژگی    | مقادیر                                    | نقش                         |
| -------- | ----------------------------------------- | --------------------------- |
| `kind`   | `additive` / `deduction_addon` / `offset` | تفکیک خسارت از کسور و تهاتر |
| `family` | `classic` / `sipo4311` / `common`         | دامنهٔ روش محاسباتی         |

`computeDamageTotals(results, method)` سه خطای محاسباتی نسخهٔ قبل را حذف می‌کند:

1. **جمع مضاعف دو روش** — روش کلاسیک و روش نشریه ۴۳۱۱ هر دو همان هزینهٔ
   مستمر را می‌سنجند؛ اکنون فقط خانوادهٔ روش منتخب به‌علاوهٔ `common` جمع می‌شود.
2. **کسور قانونی** دیگر خسارت مستقل شمرده نمی‌شود — ستون جداگانه.
3. **تهاتر مطالبات کارفرما** (جریمهٔ تأخیر) دیگر در مطالبات پیمانکار جمع نمی‌شود.

خروجی: `{ netTotal, deductionsTotal, grossTotal, offsetTotal, computableCount, inScopeCount }`.

## ۲) جداول تفکیکی منابع — `utils/damageResources.ts` (جدید)

چهار جدول منطبق بر قالب رسمی، با بازتولید دقیق متغیرهای موتور:

| جدول قالب      | محتوا                   | متغیرهای تولیدی                                                          |
| -------------- | ----------------------- | ------------------------------------------------------------------------ |
| جدول ۳- و ۴-   | نیروی انسانی بیکارمانده | `idleLaborDays` = Σ(نفر×روز)؛ `laborDailyBaseRate` = جمع ÷ نفر-روز       |
| جدول ۱۱-       | ماشین‌آلات متوقف        | `idleEquipmentDays`؛ `equipmentDailyRentalRate` = جمع ÷ (۰٫۴×دستگاه-روز) |
| جدول ۱۹- و ۲۰- | بالاسری                 | `overheadDailyRate` = جمع ÷ روزهای قابل جبران                            |
| —              | تمدید ضمانت‌نامه‌ها     | `guaranteeExtensionCosts`                                                |

ضریب ۰٫۴ فقط یک‌بار در `equipmentTotal` اعمال می‌شود و در نرخ میانگین خنثی
می‌گردد تا دوبار اعمال نشود. **جدول خالی هیچ کلیدی تولید نمی‌کند** تا ورودی
دستی کاربر بازنویسی نشود.

## ۳) استخراج خودکار از اسناد — `services/damageExtract.ts` (جدید)

همان انضباط ماژول ۵۰۹۰:

- مدل **محاسبه نمی‌کند** — فقط دادهٔ خام برمی‌دارد؛ فرمول‌ها در موتور اجرا می‌شوند.
- هیچ عددی بدون `sourceRef` + `sourceQuote` پذیرفته نمی‌شود؛ موارد ردشده شمارش و گزارش می‌شوند.
- مقدار مبهم ← `null` و درج در یادداشت‌ها (قاعدهٔ «حدس نزن»).
- هر ردیف با `verified: false` وارد می‌شود.
- ترتیب اعتبار در تعارض: پیمان > صورتجلسه > مکاتبه > گزارش.

دامنهٔ اسناد: پیمان/الحاقیه، اسناد مالی، مکاتبات، گزارشات پیشرفت، ادعاها.

## ۴) بازنویسی کامل — `components/damage/DamageClaimPage.tsx`

| نقص قبلی                                | اصلاح                                                                            |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| هیچ فراخوانی AI در کل پوشهٔ damage نبود | دکمهٔ «تدوین لایحه با ساختار رسمی» → `analyzeLegalDocuments(files, …, 'DAMAGE')` |
| بخش اول (مبانی فقهی و حقوقی) غایب       | `legalDirective` سلسله‌مراتب ۱-۱ تا ۴-۱ را الزامی می‌کند                         |
| صفر استخراج خودکار                      | کارت «منبع داده»: پیشنهاد خودکار + ورود دسته‌ای اکسل/CSV برای هر چهار جدول       |
| جمع ناهمگن `grandTotal`                 | چهار عدد جداگانه: خالص / کسور / ناخالص / تهاتر                                   |
| نبود جداول ریز                          | چهار جدول ویرایشی با جمع زندهٔ هر ردیف                                           |
| مشخصات پروژه hard-code                  | چهار فیلد ورودی، قابل پیش‌پرشدن از اسناد                                         |
| نبود پایداری                            | `localStorage` کلید `cm.damageClaim.v1`                                          |
| نبود واحد پول                           | `CURRENCY_LABEL = 'ریال'` روی همهٔ مبالغ                                         |
| `setTimeout(…, 500)` ساختگی             | حذف شد؛ محاسبه اکنون `useMemo` و لحظه‌ای است                                     |

افزوده‌های دیگر: انتخابگر روشØŒ قفل متغیرهایی که جدول ریز آن‌ها را می‌راند، بلوک
استناد + چک‌باکس «تأیید من با سند» برای هر ردیف و هر متغیر، دکمهٔ «تأیید همه
(پس از بررسی)»، گزارش سلول‌های تفسیرنشده در ورود دسته‌ای.

## ۵) خروجی PDF — `utils/pdfReport.ts`

`DamageReportData` گسترش یافت: `method`، `resources`، `totals`، `unverifiedCount` و
`formulas[].kind`. گزارش اکنون شامل بخش‌های ۱-۱-۲، ۲-۱-۲، ۳-۱-۲، جدول
ضمانت‌نامه‌ها و جمع‌بندی ۴-۲ (جدول ۲۸-) با چهار سطر خالص/کسور/ناخالص/تهاتر
است. ردیف صحه‌نخورده با برچسب «تأییدنشده» چاپ می‌شود.

## ۶) یکپارچگی — `App.tsx`

`<DamageClaimPage>` اکنون `files={selectedFiles}`، `defaultProjectName` و `onAiReport`
می‌گیرد. لایحهٔ تولیدشده با `analysisType = 'DAMAGE'` در `ResultsDisplay` همین صفحه
نمایش داده می‌شود و به خروجی Word/PDF، ممیزی استنادات و گفت‌وگوی هوشمند
متصل می‌شود — دقیقاً همان مسیری که لایحهٔ تأخیرات طی می‌کند.

## ۷) ضمانت عدم دستکاری اعداد توسط مدل

`engineDirective` اعداد موتور را عیناً به مدل تحمیل می‌کند و بازمحاسبه، گرد کردن
یا تعدیل را ممنوع می‌کند — همان الگوی `financialDirective` در لایحهٔ تأخیرات.
فرمول ناقص صریحاً «فاقد داده» اعلام می‌شود تا مدل عددسازی نکند.

## وضعیت بازبینی

- بررسی نحوی TS1xxx روی شش فایل تغییریافته: پاک.
- صحت ارجاع‌های متقابل بین چهار ماژول جدید/تغییریافته: پاک.
- باقیمانده برای آینده: تب اختصاصی بخشنامهٔ ۱۳۰۰ (تصمیم محصولی) و راستی‌آزمایی
  عددی با یک پروندهٔ واقعی کارفرما.