# حزم الأدلة

> نزّل سجلا موقّعا يبين كيف أنجز تغيير واحد (المهمة والنماذج والموافقات والملاحظات والاختبارات والتسليم) وتحقق منه في المتصفح أو دون اتصال بالشبكة.

المصدر: https://aicodeops.dev/ar/docs/evidence-packs

حزمة الأدلة سجل موقّع يبين كيف أنجز تغيير واحد في AI CodeOps. وهي للمدققين ومراجعات الامتثال والعملاء الذين يحتاجون إلى بيان كيف وصل كود كتبه الذكاء الاصطناعي إلى الإنتاج.

## ما تحتويه الحزمة

لتغيير واحد (**Develop → Changes**، ثم تغيير):

- **المهمة:** الموجه المعطى للذكاء الاصطناعي، والنموذج والمزود والفئة، وملفات السياق.
- **التشغيلات:** الجلسة وكل تشغيل متابعة، مع الحالة والتوقيتات والرموز والتكلفة، ومزود كل خطوة وكيل ونموذجها.
- **النتيجة:** الملخص، والملفات المتغيرة، وتجزئة SHA-256 للفروقات. والكود نفسه غير مضمّن؛ والتجزئة تتيح لك مطابقته مع طلب السحب.
- **الموافقات:** كل طلب موافقة، ومن طلبه (وفي موافقة الجلسة نفسها، العضو الذي بدأ الجلسة)، ومن كان يستطيع الموافقة (الحقل `eligibleApprovers`: الأشخاص الذين سماهم الطلب والأدوار المسموح لها بالبت)، ومن وافق أو رفض فعلا (الحقلان `approvedBy` و `rejectedBy`)، وكل صوت (الحقل `votes`).
- **كل صوت:** في `votes` إدخال لكل صوت، بترتيب الإدلاء بها: حساب المصوت (`accountID`)، ودوره في مساحة العمل (`role`)، والصوت (`approve` أو `reject`)، والوقت (`decidedAt`)، والملاحظة. ويبين `roleAsOf` التاريخ الذي يعود إليه الدور: القيمة `vote` تعني الدور المسجل حين أدلي بالصوت؛ والقيمة `export` تعني الدور الذي كان له حين أنشئت الحزمة، وتستخدم للأصوات التي أدلي بها قبل تسجيل الأدوار، والقيمة `null` إذا غادر المصوت مساحة العمل بعد ذلك. وتكون قيمة `selfApproval` هي true حين يوافق المصوت على تغيير بدأه هو، ويبين `selfApprovalAllowedBy` سبب السماح بذلك. ويحمل `gateOverride` السبب الذي ذكره المصوت، وما قاله فحص الإصدار، حين يوافق على تغيير كان فحص الإصدار الخاص به فاشلا. وقائمة `decisions` الخام ما زالت موجودة، دون تغيير. وكلتاهما لا تحملان إلا الجولة الحالية: فحين تعاد فتح الموافقة، كأن يعدل تغيير موافق عليه، تفرغان، وتبقى الأصوات السابقة في قسم `audit` من الحزمة على شكل إدخالات `approval.decided`.
- **قرارات السياسة:** كل قرار allow أو deny أو ask اتخذته سياسات مساحة العمل أثناء التغيير.
- **الملاحظات والاختبارات:** ملاحظات المراجعة مع فرزها، ونتائج الاختبار (الناجح والفاشل والمتخطى والتغطية).
- **التسليم:** طلب السحب، وعملية النشر، وأي حادثة مرتبطة بالتغيير.
- **مسار التدقيق:** إدخالات سجل التدقيق المتعلقة بأي مما سبق.
- **الأشخاص:** عنوان البريد الإلكتروني خلف كل معرف حساب في الحزمة.

## نزّل حزمة

افتح **Changes**، واختر تغييرا، ثم اختر **Download evidence pack** (تنزيل حزمة الأدلة). وتحتاج إلى صلاحية التدقيق في مساحة العمل: وهي لدى المالكين والمسؤولين ومسؤولي الأمان. ويسجل كل تنزيل في سجل التدقيق لمساحة العمل.

## تحقق من حزمة في المتصفح

افتح [/evidence/verify](https://aicodeops.dev/evidence/verify) واختر الملف. ولا حاجة إلى حساب. تخبرك الصفحة هل التوقيع مطابق وأي مفتاح وقّعها.

## تحقق من حزمة دون اتصال بالشبكة

لست مضطرا إلى الثقة بأداة التحقق لدينا. الحقل `signature` في الحزمة توقيع Ed25519 على صيغة JSON القانونية (canonical) للحقل `payload`: مفاتيح الكائنات مرتبة في كل مستوى، ودون مسافات بيضاء. والمفاتيح العامة للمنصة موجودة على `/api/evidence?action=keys`. وباستخدام Node.js 20 أو أحدث يكون السكربت كما يلي:

```js
// verify-evidence.mjs <pack.json> <keys.json>
import { readFileSync } from "node:fs"
import { createPublicKey, verify } from "node:crypto"

const canonical = (v) =>
  v === null || typeof v !== "object"
    ? JSON.stringify(v)
    : Array.isArray(v)
      ? `[${v.map(canonical).join(",")}]`
      : `{${Object.keys(v)
          .sort()
          .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
          .join(",")}}`

const pack = JSON.parse(readFileSync(process.argv[2], "utf8"))
const { keys } = JSON.parse(readFileSync(process.argv[3], "utf8"))
const key = keys.find((k) => k.kid === pack.signature.kid)
if (!key) throw new Error(`unknown key ${pack.signature.kid}`)
const ok = verify(
  null,
  Buffer.from(canonical(pack.payload)),
  createPublicKey(key.publicKey),
  Buffer.from(pack.signature.value, "base64url"),
)
console.log(ok ? "VERIFIED" : "NOT VERIFIED: the pack was altered")
```

احفظ المفاتيح مرة واحدة، ثم شغّل السكربت:

```bash
curl -o keys.json "https://console.aicodeops.dev/api/evidence?action=keys"
node verify-evidence.mjs evidence-chg_....json keys.json
```

## المفاتيح وتدويرها

المفاتيح لا تحذف أبدا. حين يحال مفتاح إلى التقاعد يتوقف عن توقيع حزم جديدة، والحزم التي وقّعها تبقى قابلة للتحقق. واحتفظ بنسخة من `keys.json` مع سجلات التدقيق لديك إذا أردت تحققا لا يعتمد على الوصول إلى المنصة.

## الخطوات التالية

- [الموافقات والسياسات](https://aicodeops.dev/ar/docs/approvals-and-policies)
- [بوابات الجودة](https://aicodeops.dev/ar/docs/quality-gates)
- [API](https://aicodeops.dev/ar/docs/api)

## الأسئلة الشائعة

### هل تحتوي الحزمة على كودنا المصدري؟

لا. تسرد الملفات المتغيرة وتجزئة SHA-256 للفروقات، فتستطيع مطابقتها مع طلب السحب دون أن يغادر الكود مستودعك.

### هل تبقى الحزم القديمة قابلة للتحقق بعد إحالة مفتاح إلى التقاعد؟

نعم. المفاتيح لا تحذف أبدا. والمفتاح المتقاعد يتوقف عن توقيع حزم جديدة، والحزم التي وقّعها تبقى قابلة للتحقق.
