Holarch

مرجع

وصفة: Jira

اربط متطلبات Holarch بمشكلات Jira عبر REST API، وحوّل مشكلات Jira إلى تغييرات مُراجَعة في Holarch من خلال Claude؛ الإعداد، وسكربت مزامنة، ومثال تطبيقي، واستكشاف الأخطاء وإصلاحها.

طريقة استخدامها ←

في هذه الصفحة
  1. نظرة عامة
  2. المتطلبات المسبقة
  3. طريقة استخدامها
    1. متى ولماذا
    2. إعداد المزامنة
    3. إنشاء مشكلات Jira من المتطلبات المعتمدة
    4. الاحتفاظ بمفتاح Jira في Holarch (اختياري)
    5. تحويل مشكلة Jira إلى مقترح Holarch بـ Claude
    6. مثال عملي: المشروع التوضيحي CubeSat EO-1
    7. نصائح
  4. استكشاف الأخطاء وإصلاحها
  5. صفحات ذات صلة

نظرة عامة

تُبقي هذه الوصفة العمل الهندسي في Jira مرتبطًا بالمتطلبات في Holarch. ولها جزآن:

  • من Holarch إلى Jira (REST API): ينشئ برنامج نصي مشكلة Jira واحدة لكل متطلب معتمد. وترتبط كل مشكلة بالمتطلب في Holarch. شغّله مرة أخرى في أي وقت: يتخطى المتطلبات التي لها مشكلة أصلًا.
  • من Jira إلى Holarch (MCP، عبر Claude): يقرأ Claude مشكلة Jira، مثل طلب تغيير من عميل، ويقترح تغييرات المتطلبات المطابقة في Holarch. ولا يتغير شيء حتى تراجع المقترح وتطبّقه في Holarch.

ليس في Holarch موصّل Jira مدمج. تستخدم الوصفة REST API وMCP، فيمكنك تكييف كل خطوة.

المتطلبات المسبقة

  • خطة فيها API وMCP: Individual أو Team، أو الفترة التجريبية لـ Individual. وفي خطة Free، يملكهما أيضًا الحساب الذي له عنوان بريد إلكتروني أكاديمي موثَّق أو الذي في مؤسسة صف دراسي نشطة (الخطط والحدود).
  • مشروع Holarch أنت محرر فيه أو مالك له. وتحتاج المقترحات إلى دور المحرر.
  • رمز وصول شخصي: إعدادات الحساب ← رموز API ← رمز جديد. استخدم للقراءة فقط للبرنامج النصي من Holarch إلى Jira وقصره على المشروع (إنشاء رمز).
  • Jira Cloud: مشروع Jira تستطيع إنشاء مشكلات فيه، ورمز Atlassian API (إعدادات حساب Atlassian ← Security ← API tokens). ويستخدم Jira Data Center المسارات /rest/api/2/ ورمز وصول شخصيًا بدلًا من ذلك؛ راجع مرجع API الخاص به.
  • Python 3.9 أو أحدث مع حزمة requests (python3 -m pip install requests) للبرنامج النصي.
  • لجزء Claude: Claude متصل بـ Holarch (ربط Holarch بـ Claude). ولا يقرأ Claude مشكلات Jira بنفسه إلا حين يكون لديه أيضًا موصّل Jira؛ وإلا فالصق نص المشكلة في المحادثة.

طريقة استخدامها

متى ولماذا

تعيش المتطلبات في Holarch؛ وكثيرًا ما يُخطط العمل لبنائها واختبارها في Jira. وربط الاثنين يجيب عن سؤالين: “أي عمل في Jira ينفّذ هذا المتطلب؟” و“أي متطلبات يمسها طلب التغيير هذا؟”. شغّل المزامنة بعد كل مراجعة متطلبات، حين تصل متطلبات جديدة إلى Approved.

إعداد المزامنة

  1. في Holarch، أنشئ رمزًا للقراءة فقط مقصورًا على المشروع. وانسخه.
  2. اعثر على معرّف المشروع: يسرد GET /api/v1/projects مشاريعك مع id الخاص بها.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. اضبط متغيرات البيئة التي يقرؤها البرنامج النصي:
    • HOLARCH_TOKEN: رمز Holarch.
    • HOLARCH_PROJECT: معرّف المشروع.
    • JIRA_URL: موقع Jira الخاص بك، مثل https://your-site.atlassian.net.
    • JIRA_EMAIL وJIRA_API_TOKEN: البريد الإلكتروني لتسجيل دخولك إلى Atlassian ورمز API.
    • JIRA_PROJECT: مفتاح مشروع Jira، مثل EO.
  2. احفظ البرنامج النصي أدناه باسم holarch_to_jira.py.

إنشاء مشكلات Jira من المتطلبات المعتمدة

يقرأ البرنامج النصي كل متطلب عبر REST API، ويتخطى التي لها مشكلة Jira أصلًا، وينشئ Task لكل متطلب متبقٍّ الحالة فيه Approved.

# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


def requirements():
    offset = 0
    while True:
        page = holarch("GET", f"/projects/{PROJECT}/entities",
                       params={"class": "Requirement", "limit": 500, "offset": offset})
        yield from page["entities"]
        offset += page["limit"]
        if offset >= page["total"]:
            return


def linked_in_jira():
    """The Jira labels holarch-<requirement id> already on issues of the Jira project."""
    seen, token = set(), None
    while True:
        params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
        if token:
            params["nextPageToken"] = token
        r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
        r.raise_for_status()
        d = r.json()
        for issue in d.get("issues", []):
            seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
        token = d.get("nextPageToken")
        if not token:
            return seen


seen = linked_in_jira()
for req in requirements():
    if "holarch-" + req["id"] in seen:
        continue
    e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
    if e["attributes"].get("Status") != "Approved":
        continue
    text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
    fields = {
        "project": {"key": JIRA_PROJECT},
        "issuetype": {"name": "Task"},
        "summary": f"{e['number']} {e['name']}".strip(),
        "labels": ["holarch", "holarch-" + e["id"]],
        "description": {"type": "doc", "version": 1, "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
    }
    issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
    issue.raise_for_status()
    key = issue.json()["key"]
    print(f"{e['number']} {e['name']} -> {key}")
  1. شغّل python3 holarch_to_jira.py.

    ترى سطرًا واحدًا لكل مشكلة جديدة، مثل 2.1 Pointing Accuracy -> EO-12.

كيف يعمل:

  • يسرد GET /api/v1/projects/<project>/entities?class=Requirement المتطلبات، 500 في كل مرة.
  • يعطي GET /api/v1/projects/<project>/entities/<id> سمات كل متطلب (هنا الحالة) وurl الخاص به، وهو الرابط الذي يفتحه في Holarch.
  • تحصل كل مشكلة على تسميتي Jira holarch وholarch-<id>. ويعثر عليها التشغيل التالي ببحث في Jira ويتخطى تلك المتطلبات.
  • تُقرأ المتطلبات فقط. ولا يغيّر البرنامج النصي شيئًا في Holarch.

الاحتفاظ بمفتاح Jira في Holarch (اختياري)

لرؤية مفتاح Jira على المتطلب في Holarch، أضف سمة نصية واكتب المفتاح فيها.

  1. في Holarch، افتح الإعدادات ← المخطط الهيكلي، وانقر Requirement، وأضف سمة باسم Jira Key من النوع نص قصير (إضافة سمة إلى فئة).
  2. أنشئ رمز القراءة والكتابة للبرنامج النصي بدلًا من الرمز للقراءة فقط.
  3. في نهاية الحلقة الأخيرة في البرنامج النصي، بعد سطر print(…)، أضف:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

يُكتب التغيير مثل تعديل في التطبيق: يُسجَّل باسمك ويراه كل من يفتح المشروع. وضبط هذه السمة لا يعيد متطلبًا معتمدًا إلى المراجعة. وحين يستخدم المشروع التحكم في التهيئة، ترفض المتطلبات المعتمدة التغييرات المباشرة (409 change-control)؛ احتفظ بالمفتاح في Jira فقط، أو أجرِ التغيير عبر طلب تغيير.

تحويل مشكلة Jira إلى مقترح Holarch بـ Claude

استخدم هذا حين تطلب مشكلة Jira تغيير متطلب، مثل طلب عميل بتشديد قيمة.

  1. افتح Claude، متصلًا بـ Holarch بوصول القراءة واقتراح التغييرات.
  2. اسأل، مثلًا: “Read Jira issue EO-31. Find the Holarch requirements in the CubeSat project that it affects, and propose the changes it asks for. Mention EO-31 in the proposal summary.”

    بدون موصّل Jira، الصق ملخص المشكلة ووصفها في الرسالة بدلًا من ذلك.

  3. يقرأ Claude المشروع بـ list_projects وsearch_entities وget_entity. ويضيف كل تغيير إلى مقترح بـ update_entity (أو create_entity وrelate للمتطلبات الجديدة)، ثم يرسله بـ propose_changes.

    يجيب Claude بعنوان المقترح ورابط لمراجعته.

  4. في Holarch، افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “<title>”…، أو الإشعار تحت الجرس.
  5. تحقق من كل تغيير. ألغِ تحديد ما لا تريده، ثم انقر تطبيق المحدد.

    تُطبَّق التغييرات، ويُلغي تراجع واحد ذلك كله. ويعلِّم نص المتطلب المتغير روابط تتبعه للمراجعة، ويعود المتطلب المعتمد إلى In Review، كما في أي تعديل.

يمكن للبرامج النصية تقديم المقترح نفسه دون Claude: POST /api/v1/projects/<project>/proposal/changes مرة لكل تغيير، ثم POST /api/v1/projects/<project>/proposal مع title وsummary.

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

مثال عملي: المشروع التوضيحي CubeSat EO-1

  1. أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد.
  2. أنشئ رمزًا للقراءة فقط مقصورًا على المشروع التوضيحي، وشغّل holarch_to_jira.py على مشروع Jira اختباري.

    يحصل كل متطلب معتمد على مشكلة، مثل 2.1 Pointing Accuracy بالنص “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” والرابط إلى المتطلب.

  3. شغّل البرنامج النصي مرة أخرى.

    لا يطبع شيئًا: لكل متطلب معتمد مشكلته أصلًا.

  4. في Jira، أنشئ مشكلة EO-31 تطلب 0.08 درجة بدلًا من 0.1 درجة. واطلب من Claude اقتراح التغيير، كما أعلاه.
  5. في Holarch، راجع المقترح. يغيّر نص 2.1 Pointing Accuracy، وتعرض قائمة الأثر الخاصة به TC-04 Pointing Accuracy Test، التي تتحقق منه.

نصائح

  • أعطِ البرنامج النصي للمزامنة رمزًا خاصًا به للقراءة فقط، مقصورًا على المشروع. وأعطِ Claude اتصالًا منفصلًا.
  • احتفظ بالرموز في مخزن الأسرار أو في البيئة، لا في البرنامج النصي أبدًا.
  • ابحث في Jira عن المتطلبات وراء دورة عمل (sprint) بالتسمية holarch.
  • قد تتغير أرقام المتطلبات؛ أما التسمية holarch-<id> فلا. طابق على التسمية، لا على الرقم في الملخص.

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

الرسالة أو العَرَضالسبب والإصلاح
Holarch answered 401 token-invalidالرمز خاطئ أو ملغى أو منتهي الصلاحية. أنشئ رمزًا جديدًا تحت إعدادات الحساب ← رموز API.
Holarch answered 403 plan-apiخطة الحساب لا تتضمن API وMCP. ابدأ الفترة التجريبية لـ Individual أو اختر خطة؛ ثم يعمل الرمز مرة أخرى.
Holarch answered 403 org-policyأوقفت مؤسسة المشروع وصول API. اطلب ذلك من مسؤول المؤسسة.
Holarch answered 403 read-only-tokenكتابة Jira Key تحتاج إلى رمز القراءة والكتابة.
Holarch answered 400 unknown-attributeليس في المشروع سمة Jira Key لـ Requirement. أضفها في الإعدادات ← المخطط الهيكلي، أو أسقط الخطوة الاختيارية.
Holarch answered 409 change-controlالمتطلب خاضع للتحكم في التكوين. غيّره عبر طلب تغيير، أو احتفظ بالمفتاح في Jira فقط.
Holarch answered 429 rate-limitedأكثر من 600 طلب أو 120 تغييرًا في الدقيقة. انتظر الثواني المذكورة في Retry-After، ثم شغّل مرة أخرى؛ وتُتخطى المشكلات المنتهية.
يجيب Jira بـ 400رفض Jira حقول المشكلة، مثلًا نوع مشكلة ليس في المشروع. استخدم أحد أنواع مشكلات المشروع بدلًا من Task.
يجيب Jira بـ 401 أو 403تحقق من JIRA_EMAIL وJIRA_API_TOKEN ومن إذنك بإنشاء مشكلات في مشروع Jira.
لا يعرض Claude أدوات الكتابة في Holarchالاتصال للقراءة فقط. اتصل مرة أخرى بـ القراءة واقتراح التغييرات، ثم ابدأ محادثة جديدة.