الدروس التعليمية

توليد تقارير التدقيق ووثائق الامتثال

استخدم IBM Bob لتحليل قاعدة كود Galaxium Travels وإنتاج تقارير تدقيق منظمة تغطي جودة الكود وصحة التبعيات والديون التقنية وحالة الامتثال. تعلم كيفية تجميع وثائق جاهزة لأصحاب المصلحة من التحليل المدعوم بالذكاء الاصطناعي.

التدقيق البرمجي ينتج الأدلة الوثائقية التي تعتمد عليها الفرق الهندسية والمراجعون الأمنيون وأصحاب مصلحة الامتثال قبل الشحن أو الاستحواذ أو اعتماد نظام ما.

في هذا الدرس، ستستخدم Bob لتحليل قاعدة كود Galaxium Travels بشكل منهجي وتوليد خمسة نتائج منظمة:

  1. ملخص جودة الكود: يُسلِّط الضوء على مشاكل القابلية للصيانة والتعقيد والأسلوب عبر قاعدة الكود.
  2. تدقيق التبعيات: يُشير إلى الحزم القديمة أو الضعيفة أو غير المستخدمة التابعة لأطراف ثالثة.
  3. تقييم الدين التقني: يُسجِّل الاختصارات والحلول البديلة والمناطق التي تحتاج إلى إعادة هيكلة.
  4. وثائق الامتثال: يُسجِّل النتائج مقابل المعايير التنظيمية أو التنظيمية ذات الصلة.
  5. تقرير تدقيق موحَّد لأصحاب المصلحة يجمع جميع النتائج: يجمع ما سبق في وثيقة واحدة قابلة للمشاركة.

ستُهيكل طلباتك للحصول على نتائج مفصّلة مدعومة بالأدلة دون اقتراحات للمعالجة.

بنهاية هذا الدرس، سيكون لديك مجموعة من وثائق التدقيق يمكنك مشاركتها مع أصحاب المصلحة واستخدامها كخط أساس لتخطيط المعالجة.

في هذا الدرس، قد تختلف مخرجات Bob عن الأمثلة اعتماداً على الحالة الراهنة لقاعدة الكود. استخدم التقارير المُولَّدة كنقطة انطلاق وصقّل النتائج قبل توزيعها على أصحاب المصلحة.

الميزات الرئيسية التي ستتعلمها

  • Context mentions: الإشارة إلى ملفات ومجلدات محددة في طلباتك باستخدام رمز @. تتيح mentions السياق لـ Bob معرفة الملفات التي يجب تحليلها بالضبط للحصول على نتائج دقيقة مدعومة بالأدلة.
  • وضع Agent: السماح لـ Bob بكتابة الملفات بشكل مستقل لحفظ النتائج المُولَّدة في مشروعك.
  • هندسة الطلبات للمخرجات المنظمة: هيكّل طلبك ليتضمن تنسيق المخرجات المطلوب للحصول على وثائق جاهزة لأصحاب المصلحة بدلاً من نثر سردي.

المتطلبات الأساسية

إعداد مساحة عملك

استنساخ مستودع Galaxium Travels

في الـ terminal، نفّذ الأمر التالي لاستنساخ مستودع Galaxium Travels النموذجي:

git clone https://github.com/IBM/galaxium-travels

يستخدم هذا الدرس الـ branch main للمستودع، وليس bob-learning-path-branch. خدمة الجرد Java والمكونات الأخرى التي يشير إليها هذا الدرس موجودة فقط في main.

تشغيل IBM Bob

شغّل IBM Bob IDE على حاسوبك.

فتح المشروع النموذجي

في Bob IDE، افتح مجلد galaxium-travels الذي استنسخته. إذا سأل Bob "Do you trust the authors of the files in the folder?"، انقر على Yes, I trust the authors.

راجع ملف README.md في المجلد الجذري للحصول على نظرة عامة على معمارية التطبيق. Galaxium Travels هو نظام حجز سفر فضائي متكامل مع خلفية Python FastAPI وواجهة أمامية React/TypeScript وخدمة جرد Java Spring Boot.

فتح واجهة دردشة Bob

إذا لم تكن واجهة الدردشة مفتوحة بالفعل، انقر على أيقونة Bob في شريط التنقل أو استخدم الاختصار Option + Command + B (Mac) أو Ctrl + Alt + B (Windows).

تهيئة سياق المشروع

Bob يبدأ في وضع Agent افتراضياً. إذا غيّرت الأوضاع، بدّل إلى وضع Agent قبل تشغيل أمر التهيئة. Bob يحتاج إلى كتابة الملفات لإعداد سياق المشروع. يستخدم هذا الدرس القدرات الافتراضية لوضع Agent بدلاً من تحديد الصلاحيات لكل مهمة، لذا يمكن لـ Bob قراءة وكتابة الملفات دون تكوين إضافي.

أدخل الأمر /init في حقل إدخال واجهة الدردشة.

/init

إذا كانت الموافقة التلقائية معطلة، يطلب Bob إذنك قبل قراءة الملفات وكتابة التغييرات. وافق على هذه الطلبات عند ظهورها — ينطبق هذا على أمر /init وعلى كل تقرير يكتبه Bob لاحقاً في الدرس.

يقرأ Bob الملفات ذات الصلة في المشروع ويُنشئ ملف AGENTS.md الرئيسي في المجلد الجذري، مع مجلد .bob/ يحتوي على ملفات AGENTS.md خاصة بكل وضع. تحقق من ظهور AGENTS.md ومجلد .bob/ في جذر المشروع قبل المتابعة. راجع الملفات المُولَّدة لتفهم ما استنتجه Bob عن هيكل المشروع ومكدس التقنيات والأنماط المهمة؛ فهذا السياق يحسّن مباشرة جودة التحليل في الطلبات اللاحقة.

توليد ملخص جودة الكود

ملخص جودة الكود يمنح المهندسين والمراجعين نظرة منظمة على المشاكل عبر قاعدة الكود: الأنماط المضادة، والضمانات المفقودة، وفجوات تغطية الاختبارات، والتناقضات التي تتراكم على مدار حياة المشروع. وعلى خلاف تقرير linter، يلخّص ملخص الجودة الذي يولّده Bob النتائج عبر اللغات والطبقات مع تفسيرات مقروءة وسياق للخطورة.

تمتد قاعدة كود Galaxium Travels عبر ثلاث حزم تقنية مختلفة: Python (الخلفية) وTypeScript (الواجهة) وJava (خدمة الحجز). صِغ طلبك لتحليل كل خدمة على حدة ثم إنتاج جدول موحّد بالنتائج. استخدم mentions السياق لإعطاء Bob نطاق ملفات دقيقًا بدلًا من أن يخمّن الملفات ذات الصلة.

بدء مهمة جديدة

انقر على زر + لبدء مهمة جديدة. بدء المهمة من جديد يحصر سياق هذا الطلب في الملفات التي تذكرها هنا بدلًا من حمل كل ما قرأه Bob أثناء /init.

توليد ملخص جودة الكود

في وضع Agent، أدخل الطلب التالي في حقل إدخال الدردشة:

Analyze the code quality of the Galaxium Travels application across all three
services.

For the Python backend, examine @booking_system_backend/server.py,
@booking_system_backend/models.py, @booking_system_backend/services, and
@booking_system_backend/tests.

For the TypeScript frontend, examine @booking_system_frontend/src.

For the Java hold service, examine
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.

Produce a structured Markdown file named `docs/audit/code-quality-summary.md`.
The content should include the following sections:
1. An overview table listing each component, language, files analyzed, and
   issue count by severity (Critical, High, Medium, Low).
2. Per-component findings, each with: severity label, issue title, file and
   approximate line reference, description, and impact.

Focus on: missing input validation, inconsistent error handling, authentication
and credential storage patterns, test coverage gaps, type safety, and logging
practices. Do not suggest fixes — only report findings with evidence from the
source files.

يحلّل Bob الخدمات الثلاث، وينشئ مجلد docs/audit/ إن لم يكن موجودًا، ويُنشئ ملف Markdown، ويعرض ملخصًا في واجهة الدردشة. يحتوي التقرير على الأقسام والبنية اللذين حددتهما، مع نتائج تستشهد بملفات وأسطر محددة من الكود كدليل.

التحقق من التقرير

افتح docs/audit/code-quality-summary.md في مستكشف ملفات Bob للتأكد من إنشاء الملف مع جدول النظرة العامة والنتائج لكل مكوّن قبل المتابعة.

تشغيل تدقيق التبعيات

تدقيق التبعيات يحدد ما إذا كانت المكتبات التي يعتمد عليها المشروع مثبتة على إصدارات موثوقة، وما إذا كانت استراتيجيات التثبيت متسقة عبر الحزمة متعددة اللغات، وما إذا كانت أي ممارسات لإعداد التبعيات تنطوي على مخاطر ترقية غير مضبوطة. يختلف هذا عن فحص CVE: فأنت تقيّم انضباط إدارة الإصدارات، لا الثغرات المعروفة فقط.

لمشروع Galaxium Travels ثلاث بيانات تعريف للتبعيات: booking_system_backend/requirements.txt (Python) وbooking_system_frontend/package.json (Node.js) وbooking_system_inventory_hold_service/pom.xml (Java/Maven). ضمّن الثلاثة كلها في mentions السياق.

بدء مهمة جديدة

انقر على زر + لبدء مهمة جديدة.

توليد تدقيق التبعيات

في وضع Agent، أدخل الطلب التالي في حقل إدخال الدردشة:

Audit the dependency manifests for all three services in the Galaxium Travels
repository.

Analyze @booking_system_backend/requirements.txt,
@booking_system_frontend/package.json, and
@booking_system_inventory_hold_service/pom.xml.

Produce a structured Markdown file named `docs/audit/dependency-audit.md`.
The content should include these sections:
1. Per-manifest findings table: package name, declared version or range,
   pinning status (exact, caret/tilde range, or unpinned), and a brief
   finding note.
2. Cross-cutting findings: consistency issues, missing tooling (lock files,
   audit CI steps, vulnerability scanners), and version drift risks.
3. Findings that require immediate attention before a production deployment,
   listed with rationale.

Report findings only. Do not generate upgrade commands or patch suggestions.

يحلل Bob بيانات التعريف ويكتب التقرير. ويتضمن جدولًا لحالة التثبيت وقسمًا للنتائج الشاملة.

التحقق من التقرير

افتح docs/audit/dependency-audit.md للتأكد من وجود جداول البيانات التعريفية وقسم النتائج الشاملة قبل المتابعة.

تقييم الدين التقني

يقيّم تقييم الدين التقني القرارات الهيكلية والمعمارية والتشغيلية التي تتراكم كلفتها بمرور الوقت. صِغ الطلب لفصل الدين إلى المعمارية والأمن والجاهزية التشغيلية وجودة الكود، ولتقييم خطورة كل بند وجهد معالجته حتى تستطيع القيادة ترتيب الأولويات.

يتضمن الطلب التالي AGENTS.md في mentions السياق ليمنح Bob معرفة بالمعمارية المستنتجة والأنماط التشغيلية، ما يساعد في تقييم الدين المعماري والتشغيلي. أنشأ أمر /init الذي شغّلته في قسم تهيئة سياق المشروع ملف AGENTS.md.

بدء مهمة جديدة

انقر على زر + لبدء مهمة جديدة.

توليد تقييم الدين التقني

في وضع Agent، أدخل الطلب التالي في حقل إدخال الدردشة:

Conduct a technical debt assessment of the Galaxium Travels application.
Analyze the full codebase across all three services:
@booking_system_backend, @booking_system_frontend, and
@booking_system_inventory_hold_service.

Also review @docker-compose.yml and @AGENTS.md for infrastructure and
operational context.

Produce a structured Markdown file named `docs/audit/technical-debt-assessment.md`.
The content should include these sections: Architecture Debt, Security Debt, Operational Readiness Debt, and Code Quality Debt.

For each debt item include:
- A severity label: [CRITICAL], [HIGH], [MEDIUM], or [LOW]
- An effort-to-resolve label: [DAYS], [WEEKS], or [MONTHS]
- A title
- The affected files or components
- A description of the debt and why it matters
- The consequence of leaving it unaddressed

Conclude with a summary table: category, count by severity, and total items.
Report findings only. Do not generate implementation plans or code.

يُحلِّل Bob قاعدة الكود ويكتب التقرير مع تسمية كل عنصر دين بتقديرات الخطورة والجهد.

التحقق من التقرير

افتح docs/audit/technical-debt-assessment.md للتأكد من وجود فئات الدين الأربع وجدول الملخص قبل المتابعة.

توليد وثائق الامتثال

تربط وثائق الامتثال الحالة الراهنة لقاعدة الكود بالضوابط التي يتوقع المنظمون والمدققون وفرق أمن المؤسسات وجودها في نظام إنتاجي. وبالنسبة إلى أصحاب المصلحة غير التقنيين، تجيب الوثيقة عن السؤال: «كيف يتعامل هذا النظام مع البيانات الحساسة، وكيف يُضبط الوصول، وأين توجد الفجوات؟»

صِغ طلبك ليغطي تصنيف البيانات والمصادقة والتحكم في الوصول وحماية البيانات وتغطية سجل التدقيق وامتثال التراخيص.

بدء مهمة جديدة

انقر على زر + لبدء مهمة جديدة.

توليد وثائق الامتثال

في وضع Agent، أدخل الطلب التالي في حقل إدخال الدردشة:

Generate compliance documentation for the Galaxium Travels application,
suitable for sharing with security reviewers and compliance stakeholders.

Analyze the following files and directories:
@booking_system_backend/models.py,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/requirements.txt,
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain,
@booking_system_inventory_hold_service/pom.xml,
@booking_system_frontend/src,
@booking_system_frontend/package.json,
@LICENSE.

Produce a structured Markdown file named `docs/audit/compliance-documentation.md`. The content should include these sections:
1. Data Classification — table of data elements, classification tier, storage
   location, and retention policy.
2. Authentication and Access Control — table of controls, implementation status
   (Implemented / Partial / Not Implemented), and a source reference or gap note.
3. Data Protection — table of controls, implementation status, and notes.
4. Audit Trail Coverage — what is logged, what is not, and where audit records
   are stored.
5. License Compliance — table of key dependencies (Python, Node, and Java) with
   their license and a compliance note.
6. Regulatory Applicability — brief assessment of GDPR, SOC 2, and PCI DSS
   applicability given the data the system handles.

Use neutral, factual language. Do not recommend remediations.

يُحلِّل Bob الملفات المصدرية ويكتب التقرير.

التحقق من التقرير

افتح docs/audit/compliance-documentation.md للتأكد من وجود الأقسام الستة قبل المتابعة.

تجميع تقرير تدقيق لأصحاب المصلحة

مع اكتمال أربعة تحليلات منفصلة، اطلب من Bob تجميعها في تقرير تدقيق واحد موجّه إلى القيادة. يختلف تقرير أصحاب المصلحة عن تحليلات الموضوعات المفردة: فهو يبدأ بملخص للنتائج، ويرتب البنود الأكثر قابلية للتنفيذ، ويقدم تسلسل معالجة موصى به يمكن للقراء غير التقنيين العمل به.

يستخدم الطلب mentions للسياق لتحميل التقارير الأربعة التي كتبها Bob في الأقسام السابقة. يقرأ Bob هذه الملفات ويجمعها في وثيقة واحدة بدل إعادة تحليل الكود، لذلك تعكس المخرجات النتائج التي راجعتها بالفعل.

بدء مهمة جديدة

انقر على زر + لبدء مهمة جديدة.

توليد تقرير تدقيق أصحاب المصلحة

في وضع Agent، أدخل الطلب التالي في حقل إدخال الدردشة:

Using @docs/audit/code-quality-summary.md, @docs/audit/dependency-audit.md,
@docs/audit/technical-debt-assessment.md,
and @docs/audit/compliance-documentation.md, compile a consolidated
stakeholder audit report for the Galaxium Travels application.

The audience is engineering leadership and security reviewers who need to
assess the system's production readiness and compliance posture without
reading four separate documents.

Structure the report as follows:
1. Executive Summary: 2-3 paragraphs covering overall state, most critical
   risks, and the highest-priority remediation categories.
2. Production Readiness Scorecard: a table scoring the system against six
   dimensions (Authentication, Data Protection, Observability, Dependency
   Health, Test Coverage, Operational Readiness) with a RAG status
   (Red / Amber / Green) and a one-line rationale for each.
3. Critical and High Findings: a consolidated table of all Critical and High
   severity findings from all four analyses, with category, finding title,
   affected component, and effort to resolve.
4. Recommended Remediation Sequence: an ordered list of the top 5 items to
   address first, with a brief rationale for the ordering.
5. Positive Findings: a brief section acknowledging controls and practices
   that are already well-implemented.

Do not repeat all findings in full. Reference the detailed documents for
complete findings. Save the report as `docs/audit/stakeholder-audit-report.md`.

يقرأ Bob التقارير الأربعة المحفوظة، ويجمع نتائجها، وينشئ docs/audit/stakeholder-audit-report.md. ولأنه يعمل من التقارير التي راجعتها بدل إعادة تحليل الكود المصدر، يظل التقرير الموحد متسقًا مع النتائج التفصيلية.

التحقق من التقرير

افتح docs/audit/stakeholder-audit-report.md للتأكد من وجود الملخص التنفيذي وبطاقة النتيجة والأقسام الخمسة. لديك الآن مجموعة كاملة من وثائق التدقيق في docs/audit/ لمشاركتها مع أصحاب المصلحة.

استكشاف الأخطاء وإصلاحها

تحليل Bob يغفل خدمة أو ملفاً

إذا كانت مخرجات Bob تفتقر إلى نتائج لمكوّن توقعت تغطيته، فالسبب الأكثر احتمالاً هو أن الطلب لم يتضمن الملف أو المجلد في mention السياق، أو أن نافذة السياق كانت ممتلئة جداً لـ Bob لقراءة كل المحتوى المُشار إليه في مرور واحد.

تحقق من mentions السياق

تحقق من أن mention @ في طلبك يُحل إلى المسار الصحيح. قد يشير Bob في واجهة الدردشة إلى ما إذا كان mention السياق قد حُل. إذا لم يتعرف Bob على mention، فقد يكون المسار مكتوبًا خطأ أو قد لا يكون المجلد موجودًا في نسختك المحلية.

بالنسبة إلى المجلدات التي تضم ملفات كثيرة، قد يقرأ Bob مجموعة فرعية فقط. ضيّق النطاق إلى المجلد الفرعي الأهم أو عدّد ملفات محددة بدل الإشارة إلى المجلد بالكامل.

قسّم التحليل إلى طلبات مركّزة

بدلًا من طلب واحد يغطي الخدمات الثلاث، شغّل ثلاثة طلبات منفصلة، واحدًا لكل خدمة، ثم اطلب من Bob دمج النتائج. على سبيل المثال، هذا هو الطلب الثالث المركّز بعد إنهاء تمريرتي Python وTypeScript:

غطّى تحليل جودة الكود الذي أجريناه سابقًا خلفية Python وواجهة TypeScript. أجرِ التحليل نفسه لخدمة الحجز في Java فقط، باستخدام @booking_system_inventory_hold_service/src. استخدم تنسيق المخرجات نفسه وتسميات الخطورة نفسها التي استخدمناها في التقارير السابقة.

بعد اكتمال كل تحليل مركّز، اطلب من Bob دمجها:

ادمج تحليلات جودة الكود الثلاثة الخاصة بكل خدمة في تقرير موحّد واحد باستخدام التنسيق نفسه الذي استعملناه للتقرير الأولي.

التقارير تحتوي على نتائج متضاربة عبر الطلبات

عند تشغيل جلسة متعددة الطلبات، قد تنتج الطلبات اللاحقة نتائج تبدو متناقضة مع النتائج السابقة. قد يحدث ذلك إذا استنتج Bob أشياء مختلفة من قراءات ملفات مختلفة، أو إذا كانت نتيجة سابقة غير دقيقة.

تحديد الادعاءات المتعارضة

اقتبس النتيجتين في طلب جديد واطلب من Bob حل التناقض مع مرجع ملف محدد. مثال:

في ملخص جودة الكود، ذكرت أن معالجة الأخطاء في server.py غير متسقة. وفي تقييم الدين التقني وصفت المشكلة نفسها بأنها غياب لمعالجة الأخطاء. راجع @booking_system_backend/server.py ووضّح أي الوصفين أدق، مع مرجع سطر محدد.

تحديث التقرير المتأثر

بعد أن يصدر Bob النتيجة المعتمدة، اطلب منه تحديث القسم المحدد في ملف التقرير المحفوظ. مثال، إذا كان تقييم الدين التقني أدق:

حدّث نتيجة معالجة الأخطاء في docs/audit/code-quality-summary.md لاستخدام الوصف المصحح. لا تغيّر أي قسم آخر.

Bob يضيف توصيات غير مطلوبة إلى التحليل

عندما يطلب من Bob «تحليل» أو «تقييم» من دون قيود صريحة، فإنه غالبًا يضم اقتراحات للمعالجة إلى جانب النتائج. وقد تكون التوصيات غير المطلوبة في تقرير امتثال أو تدقيق مشكلة: فقد تكون غير دقيقة أو تستند إلى افتراضات عن البيئة المستهدفة أو تربك أصحاب المصلحة الذين يتوقعون وثيقة نتائج فقط.

أضف التعليمة «أبلغ عن النتائج فقط. لا تولّد خطط تنفيذ أو كودًا أو اقتراحات للمعالجة.» إلى أي طلب تحليل يكون ذلك مهمًا فيه. وإذا كان Bob قد ولّد تقريرًا بمحتوى مختلط، فاطلب منه حذف التوصيات، مثلًا:

أزل جميع اقتراحات المعالجة وإرشادات التنفيذ وأمثلة الكود من docs/audit/code-quality-summary.md. أبقِ كل أوصاف النتائج وتسميات الخطورة ومراجع الملفات وبيانات الأثر كما هي تمامًا.

التنظيف

لإزالة النتائج التي أُنشئت في هذا الدرس:

  1. احذف مجلد docs/audit/ الذي يحتوي على التقارير الخمسة المُولَّدة.
  2. إذا كنت لا تريد الاحتفاظ بسياق المشروع الذي أنشأه Bob، احذف ملف AGENTS.md ومجلد .bob/ الذي أنشأه أمر /init.
  3. احذف مجلد galaxium-travels الذي استنسخته في إعداد مساحة عملك.

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

في هذا الدرس، استخدمت IBM Bob من أجل:

  • تهيئة سياق المشروع بـ /init حتى يعكس تحليل Bob هيكل المشروع ومكدس التقنيات
  • توليد أربعة نتائج تدقيق مركّزة: ملخص جودة الكود وتدقيق التبعيات وتقييم الدين التقني ووثائق الامتثال، كل منها مدعوم بأدلة من الملفات المصدرية
  • تجميع التحليلات الأربعة في تقرير تدقيق واحد لأصحاب المصلحة مع بطاقة جاهزية الإنتاج وتسلسل معالجة موصى به
  • استخدام وضع Agent وmentions السياق لحفظ كل تقرير على القرص، ما يبقي التحليلات مستقلة وفعالة في استخدام الرموز المميزة

تابع مع الموارد التالية:

ما رأيك في هذا الموضوع؟