> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# تسجيل الجماهير القريبة من PHI

> جولة في سجل الجماهير القريبة من PHI: متى تعيّن قائمة أو مقطعاً، كيف يعمل PUT الاستبدال الكامل الذرّي، كيف يستجيب الفحص المسبق لإطلاق الحملة وكيف يُقرأ مسار التدقيق.

# تسجيل الجماهير القريبة من PHI

سجل الجماهير القريبة من PHI هو قائمة مؤسستك لقوائم جهات الاتصال والمقاطع التي يحمل أعضاؤها PHI — مثلاً، مرضى اختاروا outreach العلاج. توثّق مرجعية [ضوابط HIPAA](/compliance/hipaa#phi-adjacent-audience-registry) نقطتي النهاية؛ يرشدك هذا الدليل لتشغيلها في الإنتاج: ما تعيّنه، كيف تعمل دلالات الكتابة، ما يحدث عند إطلاق الحملة، وكيف يُقرأ مسار التدقيق.

السجل **مملوك للمستأجر**. لا تعيّن Devotel جماهيرنيابة عنك ولا تحصر PHI من أجلك — التعيينات هي تصحيحك، وهي ضوابط مقيدة بـ BAA تشغّلها أنت، وتتلقى فقط عندما يكون HIPAA في نطاق مؤسستك. إذا لم تكن قد نفّذت BAA وفعّلت وضع HIPAA، شغّل تسلسل [تهيئة HIPAA](/guides/hipaa-onboarding) أولاً.

## 1. متى توسم جمهوراً قريباً من PHI

يتابع التعيين **المصدر**: وسم الجماهير التي تحتوي بياناتها الأصلية على PHI، بغض النظر عما ترسله أي حملة فردية لها. الجمهور قريب من PHI بسبب من أين جاء أعضاؤه — استيراد تذكير مواعيد مرضى، قائمة opt-in outreach علاج — لا بسبب النص الذي تكتبه هذا الأسبوع. لهذا يعيش التعيين على الجمهور نفسه وليس على حملة: أي حملة تأخذ الجمهور، التعيين يسافر معه.

وسم جمهوراً قريباً من PHI عندما:

* استُورده أعضاؤه من نظام يحفظ PHI (تصدير EHR، مزامنة opt-in على بوابة مرضى).
* القائمة أو المقطع مُفلترة أو مجمّعة على معايير حاملة PHI (أوسمة قريبة من التشخيص، cohorts العلاج).
* خريطة بيانات مسؤول الامتثال تسجّل الجمهور كـ PHI في النطاق.

لا تعيّن جمهوراً "فقط للأمان". يربط التعيين [بوابة إطلاق BAA](#4-كيف-يستخدم-الفحص-المسبق-للإطلاق-السجل) على كل حملة تستخدم الجمهور — تعيين جماهير لا تحمل PHI يمنع إطلاقات لأسباب لا امتثالية.

**من يستطيع التصحيح:** كلا النقطتين النهيتين تتطلبان دور `owner` أو `admin` — نفس البوابة كـ [نقاط نهاية BAA](/compliance/baa). يتلقى `developer` أو `viewer` `403`. أجّل قرار التعيين لمسؤول الامتثال HIPAA؛ تسجّل المنصة *من* غيّر السجل على كل كتابة (انظر [مسار التدقيق](#5-مسار-التدقيق)).

## 2. اختيار معرفات قائمة vs. مقطع

يحفظ السجل معرّفات جماهير — كل مدخل هو إما **معرّف قائمة جهات الاتصال** أو **معرّف مقطع**، يُمرَّر كسلسلة نصية فقط. الفحص المسبق لإطلاق الحملة يحلّ فقط جماهير نوع `list` و`segment` ضد السجل؛ الجماهير المجمّعة لكل جهة اتصال (كل جهات الاتصال، رفع CSV، إدخال يدوي) تُقيّم مستلم-بعد-مستلم وقت الإرسال بدلاً من ذلك، ليس لها معرّف سجل للتعيين.

لإعادة استخراج المعرف لتعيين:

```bash theme={null}
# قوائم جهات الاتصال
GET /api/v1/contacts/lists

# المقاطع
GET /api/v1/contacts/segments
```

انسخ حقل `id` للقائمة أو المقطع الذي تعيّنه. المعرّفات هي 1–128 حرفاً بعد التقطيب؛ أي شيء أطول أو فارغ يُرفض مع `422` على الكتابة. يحفظ السجل بحد أقصى **500** معرّف لكل مؤسسة — `PUT` يحمل أكثر يعيد `422`.

> عيّن المعرّف **الأصلي**، لا نسخة downstream. إذا كانت قائمة حاملة PHI تغذّي مقطعاً مشتقاً، قرر إن كان المنقطع المشتق يحتوي PHI أيضاً وعيّنه صراحةً — يتحقق الفحص المسبق من المعرّف الذي ترجع إليه الحملة فعلاً، لا شيء آخر.

## 3. مبادلة PUT الذرّية

السجل لديه **عملية كتابة واحدة**: `PUT` استبدال كامل. لا `PATCH`، لا `DELETE` لكل معرّف — كل كتابة تستبدل المجموعة المعينة بكاملها في عبارة ذرية واحدة، بحيث لا يرى `GET` متزامن تحديثاً جزئيًا مطبقاً.

```bash theme={null}
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"]
}
```

تعكس الاستجابة المجموعة المخزّنة:

```json theme={null}
{
  "data": {
    "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"],
    "replaced": true
  }
}
```

الجسم **idem-potent**: إرسال نفس المجموعة الكاملة مرتين ينتج نفس السجل المخزّن وسطرين مختلفين من التدقيق. مجموعة فارغة تطهر كل تعيين:

```bash theme={null}
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": []
}
```

لأن الكتابة مبادلة، يجب على كل عميل متابعة **قراءة-تعديل-كتابة**: `GET` السجل الحالي، أضف أو أزل معرّفك في النتيجة، و`PUT` المجموعة الكاملة بالظهر. لا تبنِ الجسم من حالة محلية فقط — سيسقطها تعيينات أضاف مشغل آخر.

لرفع تعيين، `PUT` السجل بدون ذلك المعرّف. لإعادة التعيين، `PUT` مع إضافة المعرّف بالظهر. المعرّفات الفردية التي تتجاوز مبادلة تبقى؛ فقط العضوية في المجموعة مهمة.

## 4. كيف يستخدم الفحص المسبق للإطلاق السجل

بوابتان تحميان PHI في نقاط مختلفة، والسجل يغذّي الأولى:

1. **فحص مسبق للإطلاق (مستوى الحملة، بوابة صلبة).** قبل أن تغادر حملة مسودة/مجدولة، يحلّ الفحص المسبق معرّف جمهورها ضد السجل. معرّف معيّن بالإضافة إلى BAA ليس `executed` وضمن المدة يرفض الإطلاق مع `422 HIPAA_BAA_REQUIRED` — قبل تسجيل مستلم واحد. إذا لم يُقرأ حالة الامتثال، يفشل الفحص المسبق مغلقاً مع `500 HIPAA_BAA_GATE_DB_FAIL` بدلاً من السماح صميماً بالجمهور.
2. **بوابة إرسال لكل مستلم (وقت الرسالة، بدون تغيير).** بوابة الإرسال الحالية تزال تطبق على كل إرسال فردي ولا تستشير السجل — إرسالات legacy السرعية محكومة بها فقط.

إطلاق محظور يظهر مع الحتىاف أدناه. `details.reason` يخبرك بالضبط أي حالة BAA تفتحه:

```json theme={null}
{
  "error": {
    "code": "HIPAA_BAA_REQUIRED",
    "status": 422,
    "message": "The designated PHI-adjacent audience for this campaign requires an executed Business Associate Agreement (BAA) before outbound sends are permitted.",
    "details": {
      "reason": "pending",
      "audience": { "type": "list", "id": "list_9f2c1a" }
    }
  }
}
```

| `reason`     | ما يعنيه                                  | كيف تفتحه                                                 |
| ------------ | ----------------------------------------- | --------------------------------------------------------- |
| `not_signed` | PHI مُتصحح في النطاق لكن لم يُنفّذ BAA قط | نفّذ BAA — [مسار BAA](/compliance/baa)                    |
| `pending`    | بدأ تنفيذ BAA لكن لم يكتمل                | أكمل خطوة التنفيذ (`POST /api/v1/compliance/baa/execute`) |
| `expired`    | BAA المنفّذ تخطى مدته السنوية             | أعد تنفيذ BAA                                             |

هناك **طريقتان** لفتحها، وهما قرارات امتثال، لا قرارات منصة:

* **حلّ BAA** — نفّذه أو أعد تنفيذه حتى تمر البوابة. هذا هو المسار الصحيح عندما يحمل الجمهور PHI حقاً.
* **أزل التعيين** — `PUT` السجل بدون معرّف الجمهور. هذا هو المسار الصحيح *فقط* عندما عُيِّن الجمهور خطأً. رفع تعيين للالتفاف على البوابة مرئي في سجل تدقيقك.

في معالج الحملة بلوحة التحكم، يُظهر اختيار جمهور معيّن تحذيراً استشاريًا عند خطوة الجمهور. لا يمنع التحذير زر **التالي** — قد يرتفع التعيين أو يُنفّذ BAA قبل الإطلاق — لكن البوابة الصلبة عند الإطلاق تسريدائماً.

## 5. مسار التدقيق

قعود صنفان من السجلات في سجل تدقيق مؤسستك:

* **`hipaa.phi_audiences.set`** — صف واحد لكل `PUT`، تسجّل المستخدم العامل، والمؤسسة، ومجموعة معرّفات بعد الكتابة بالكامل. هذه حكاية الإصدار لديك: السجل لا يملك مصدر مراجعة منفصل — تسلسل صفوف التدقيق *هو* تاريخ الإصدار. لإعادة بناء ما عُيِّن في نقطة زمنية، امشِ في صفوف `set` للخلف؛ للعائد، `PUT` مجموعة معرّفات من صف سابق.
* **حتيات إطلاق `HIPAA_BAA_REQUIRED`** — كل إطلاق محظور يُسجّل مع السبب المحظّر والجمهور قيد التقييم. هذه الصفوف تضاعف كصفك للحوادث: حتىًا يعني إما أن عمل الامتثال معلق (BAA غير منفذ) أو تعيين وحملة في عدم اتفاق.

راجع كلا الصنفين بوتيرة تطابق برنامج امتثالك — أسبوعياً هو افتراضي عملي لمساحة عمل رعاية صحية نشطة. صدّر سجل التدقيق بجانب سجل الوصول إلى PHI عند تجميع دليل لتدقيق خارجي؛ حزمة HIPAA لـ [ملك الدليل](/compliance/evidence-binder) تعدّ وضع BAA وتسجيل الوصول إلى PHI إلى تنزيل موقّع.

**نوبة حادث للحتىاف غير المتوقع:**

1. اقرأ `details.reason` و`details.audience.id` للحتىاف.
2. تحقق من `GET /api/v1/compliance/baa/` — إذا كان BAA `pending`/`expired`/غير منفذ، حلّه عبر [مسار BAA](/compliance/baa).
3. إذا كان BAA سليمًا، تحقق مما إذا كان الجمهور يجب أن يُعيَّن ابتداءً: `GET /api/v1/compliance/hipaa/phi-audiences` وقارن مقابل خريطة بياناتك. ارفع تعيينًا خاطئًا بمبادلة (`PUT` بدون المعرّف).
4. سجّل النتيجة في سجل الحوادث الخاص — صفوف التدقيق أعلاه هي الدليل الذي تقتبسه.

## 6. تصليح مشاكل تداخل الكتابات المتزامن

`PUT` السجل نفسه لا يعيد `409` أبدًا — مبادلة العبارة الذرية الواحدة تعني أن كتابة تُcommit دائمًا، والكاتب الأخير يفوز. خطر الصراع هو **تحديات مفقودة بين المشغلين**، ليس كتابات مرفوضة:

* المشغل A والمشغل B كلاهما يعمل `GET` السجل.
* A يضيف `list_aaa` و`PUT`. B — يعمل من snapshot ما قبل A — يضيف `list_bbb` و`PUT`.
* مبادلة B تسقط `list_aaa` صميماً.

التخفيفات:

* **اقرأ قبل الكتابة مباشرة.** حافظ على نافذة قراءة-تعديل-كتابة قصيرة؛ لا تحمل سجلاً جالباً خلال جلسة تحرير — أعد `GET` عندما تكون جاهزاً لـ `PUT`.
* **تحقق بعد الكتابة.** `GET` مرة أخرى وأكد أن معرّفك حاضر وأن لا تعيين غير متصل ضاع. إذا اختفى شيء، تظهر صفوف `hipaa.phi_audiences.set` لسجل التدقيق كتابات من فوقها وما المجموعة التي يجب عودتها.
* **سلسل تحرير السجل تنظيميًا.** لأن التعيين تصحيح امتثال، وجّه التحريرات عبر دور واحد (مسؤول الامتثال) بدلاً من نشرها بين المشغلين — إصلاح إجرائي يزيل السباق كليًا.

إذا رأيت `422` بدلاً من النجاح، السبب هو تصديق، لا صراع: أكثر من **500** معرّف، معرّف فارغ بعد التقطيب، أو معرّف أطول من 128 حرفًا. قطّب وأعد المحاولة مع المجموعة الكاملة.

## انظر أيضًا

* [تعيينات الجماهير القريبة من PHI](/compliance/phi-audiences) — مرجعيةة النقطة النهائية لعقد السجل (سقف، دلالات الاستبدال، إجراء التدقيق)
* [ضوابط امتثال HIPAA](/compliance/hipaa) — مرجعيةة الضوابط الكاملة التي يغذّيها السجل
* [BAA — Business Associate Agreement](/compliance/baa) — دورة الحياة التي يفرضها الفحص المسبق للإطلاق
* [تهيئة HIPAA: من BAA إلى جاهز للتدقيق](/guides/hipaa-onboarding) — التسلسل الذي يأتي مساحة عمل رعاية صحية إلى جاهز للتدقيق قبل تعيين الجماهير
* [بوابات الإرسال](/compliance/send-gates) — بوابة لكل مستلم تكمل الفحص المسبق للإطلاق