ATP - ناوبری فضای کاری پرونده (GET /api/v1/invention-cases/{invention_case_id}/workspace-navigation/)

Endpoint

GET /api/v1/invention-cases/{invention_case_id}/workspace-navigation/

هدف آزمون

دریافت projection سبک مراحل سطح‌بالا برای ناوبری سلسله‌مراتبی UI (ADR-0012).

شرایط آزمون

• سرویس core-api در حال اجرا باشد
• هدر Authorization با access token معتبر
• کاربر عضو workspace پرونده باشد
• کاتالوگ capability و workflow definition منتشرشده seed شده باشد

فرآیند آزمون

1. ایجاد یا انتخاب invention case با دسترسی
2. GET /workspace-navigation/ با access token
3. بررسی case_id، workflow، steps[] و revision
4. برای هر step قابل دسترس، GET substeps همان step_key
5. پس از SSE/workflow.changed با revision جدید، دوباره poll کنید

معرفی ویژگی

endpoint کاننیکال ناوبری سطح‌بالا برای frontend-mvp. مراحل از CaseModuleInstance و WorkflowStepDefinition مشتق می‌شوند؛ محتوای دامنه (متن draft، snapshot خام) برنمی‌گردد.

• steps[]: key، title، renderer_key، order_index، availability، status، feature
• feature: { key, version } برای pin نسخه ProductFeature
• revision: عدد صحیح برای invalidation کش UI پس از رویدادها
• بدون config/apps.: مسیرهای import پایتون و config خام در پاسخ نیست
• مکمل /workflow/ و /workflow-state/؛ جایگزین آن‌ها در Phase 5 نیست

سناریوی آزمون

سناریو 1: ناوبری پرونده با ماژول‌های prior_art و patent_drafting

1. ایجاد case و عضویت OWNER
2. GET workspace-navigation
3. بررسی 200 و case_id برابر invention_case_id
4. بررسی وجود steps با keyهای prior_art و patent_drafting
5. بررسی order_index اولین step برابر ۰ و feature.version از نوع int

سناریو 2: خطا — کاربر بدون دسترسی

1. احراز هویت با کاربری خارج از workspace
2. GET workspace-navigation
3. دریافت 403 یا 404
4. بررسی عدم افشای steps

سناریو 3: سازگاری با workflow قدیمی

1. GET workspace-navigation و GET /workflow/
2. بررسی هر دو 200
3. بررسی همپوشانی منطقی ماژول‌ها/steps

سناریو 4: پس از افزایش revision

1. ثبت رویداد دامنه (مثلاً آپلود سند)
2. poll workspace-navigation
3. بررسی revision ≥ مقدار قبلی

قالب API

Swagger

get:
  summary: ناوبری فضای کاری پرونده
  responses:
    200:
      description: عملیات موفق
    401:
      description: احراز هویت نامعتبر یا ناقص

نمونه ورودی

curl -X GET "http://localhost:8000/api/v1/invention-cases/{invention_case_id}/workspace-navigation/" \
  -H "Authorization: Bearer <access>" \
  -H "Content-Type: application/json"

نمونه خروجی

{
  "success": true,
  "data": {
    "case_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "workflow": { "key": "patent_drafting", "name": "Patent Drafting" },
    "current_step_key": "prior_art",
    "revision": 3,
    "steps": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "key": "prior_art",
        "title": "Prior art",
        "description": null,
        "renderer_key": "prior-art",
        "substep_provider_key": "prior_art",
        "order_index": 0,
        "required": true,
        "availability": { "visible": true, "available": true, "read_only": false },
        "status": { "execution": "not_started", "attention": "none" },
        "progress": null,
        "feature": { "key": "prior_art", "version": 1 },
        "actions": [],
        "badges": []
      }
    ]
  }
}

Status Codes

• 200: projection ناوبری برگردانده شد
• 401: احراز هویت نامعتبر
• 403: بدون دسترسی به workspace
• 404: پرونده یافت نشد

نتیجه مورد انتظار

پاسخ JSON با steps مرتب‌شده، feature pin، و revision. پاسخ نباید شامل config خام یا مسیرهای apps.* باشد.

روال صحت‌سنجی

1. بررسی 200 و فیلدهای case_id / revision / steps
2. بررسی steps[0].order_index == 0
3. بررسی وجود feature.key و feature.version برای هر step
4. بررسی "config" و "apps." در JSON پاسخ وجود ندارد
5. بررسی 403/404 برای کاربر بدون عضویت
6. مقایسه سازگاری با GET /workflow/ روی همان case

توضیحات

• ADR-0012: Hierarchical Workflow Projections
• پس از SSE با event_type و revision، این query را invalidate کنید
• برای جزئیات زیرمرحله از GET .../workflow/steps/{step_key}/substeps/ استفاده کنید

جریان یکپارچه‌سازی

Frontend shell
  │
  ├─ GET workspace-navigation  → steps + revision
  │
  └─ per selected step:
       GET workflow/steps/{step_key}/substeps/  → substeps + revision

SSE workflow.changed / event_type → invalidate navigation + substeps