company_entry
اصلاح هنگام ثبت، نمایش سؤال و suggestion؛ بدون تغییر پنهان یا canonical approval.
فصل ۰۷ · یکپارچهسازی
API برای backend سازمان، نه مرورگر عمومی
سامانهٔ ورود اطلاعات GS1 ایران از backend مورد اعتماد به Assist API v2 متصل میشود. end-user identity و مجوز upstream باید در سازمان مدیریت و با claim مصوب به GS1AI منتقل شود.
Assist API v2 PILOTScoped onboarding انجام نشدهAI proposals OFF
مرز اتصال
UI شرکت/استان/کارشناسفرم و نمایش پیشنهاد
←Backend GS1 ایرانهویت و authorization
←mTLS + OIDC هدفاکنون ROADMAP
←/api/v2workflow-scoped contract
←Deterministic harnessproposal اختیاری و خاموش
Assist token با OpenAI key فرق دارد
Assist token فقط workflow محدود سامانهٔ سازمان را باز میکند و نباید در JavaScript یا اپ قابل دانلود قرار گیرد. کلید provider در سرور GS1AI میماند.
چهار workflow و سطح اختیار
province_review
رفع ابهام، evidence و ارجاع؛ بدون دسترسی expert monitoring.
expert_monitoring
rule IDs، provenance، proposalهای ردشده و risk؛ نیازمند نقش expert.
knowledge_qa
پرسش مستند؛ تا RAG فعال نیست باید unavailable/abstain مدیریت شود.
خلاصه endpointهای Assist v2 و عملیات پایدار
| Method | Path | کارکرد |
|---|---|---|
| GET | /api/v2/capabilities | کشف workflow مجاز، policy و وضعیت AI/memory |
| POST | /api/v2/records:validate | اعتبارسنجی قطعی و proposal اختیاری |
| POST | /api/v2/knowledge:query | پرسش RAG همراه citation یا abstain |
| POST | /api/v2/feedback | ثبت feedback نامزد و hash-chain |
| GET | /api/v2/feedback/summary | خلاصه audit برای principal مجاز؛ نه service token |
| DELETE | /api/v2/sessions/{id} | حذف context نشست همان caller نامدار |
| POST | /api/v1/ops/runs | ثبت تکی/دستهای پایدار؛ idempotency بدون افشای run کاربر دیگر |
| GET | /api/v1/ops/history | تاریخچهٔ سروری: مدیر در سطح سازمان؛ سایر نقشها فقط ساختهشده/تخصیصیافته |
| GET | /api/v1/ops/runs/{id}/semantic-summary | پوشش facet و unresolved فقطخواندنی برای run مجاز |
تاریخچهٔ مرورگر با تاریخچهٔ API یکی نیست
حافظهٔ محلی یک دستگاه فقط برای بازکردن سریع نتیجه است. پروندهای که باید روی دستگاه دیگر دیده شود باید بهعنوان run سروری ثبت شده باشد و کاربر با همان principal یا بهعنوان مدیر/مسئول تخصیصیافته وارد شود.
نمونهٔ امن PowerShell
مقدار secret را در خط فرمان یا تاریخچه قرار ندهید؛ متغیر نمونه زیر فقط placeholder است.
$headers = @{
Authorization = "Bearer <GS1-issued-assist-token>"
"Content-Type" = "application/json"
}
$body = @{
workflow = "company_entry"
text = "گوشت گوساله بی استخوان 1000 گرم"
mode = "auto"
ai_mode = "off"
} | ConvertTo-Json
Invoke-RestMethod `
-Method Post `
-Uri "https://gs1ai.online/api/v2/records:validate" `
-Headers $headers `
-Body $bodyاول capabilities
قبل از فعالکردن فرم، client باید workflowها و flagهای واقعی را کشف و assert کند.
ai_mode=propose تضمین نیست
server flag و provider policy همچنان حاکماند؛ پاسخ deterministic با AI unavailable یک نتیجهٔ معتبر و قابل نمایش است.
قرارداد پاسخ و نمایش UI
| Status | معنای رابط | اقدام |
|---|---|---|
| accepted | کنترل قطعی کافی | نمایش دلیل؛ در صورت policy ثبت |
| suggested | پیشنهاد وجود دارد، auto_apply=false | diff و provenance به کاربر |
| needs_clarification | پرسش مشخص لازم است | گرفتن داده تکمیلی |
| expert_required | ریسک یا ابهام بالاست | ارجاع و حفظ trace |
| abstain | شاهد یا policy کافی نیست | مسیر انسانی؛ پاسخ حدسی ممنوع |
در تمام حالتها trace_id، provenance، risk، questions و rejected proposal reasons باید برای پایش قابل نگهداری باشند.
قرارداد خطا و Retry
| HTTP | رفتار client |
|---|---|
| 400 | درخواست را اصلاح کنید؛ retry خودکار نکنید |
| 401 | credential را refresh/replace کنید؛ loop ممنوع |
| 403 | policy یا workflow scope را به مالک ارجاع دهید |
| 429 | backoff نمایی محدود با jitter |
| 502/503 | fallback قطعی/انسانی؛ retry فقط برای readهای idempotent |
| timeout بازخورد | retry کور نکنید؛ idempotency feedback هنوز کامل نیست |
چکلیست onboarding IT
- Contract و volumeOpenAPI revision، owner، SLA، peak و data-class map.
- IdentityOIDC claim mapping، mTLS و credential جدا برای هر workflow.
- Client UXaccepted/suggested/clarification/expert/abstain صریح و بدون write-back پنهان.
- Observabilitytrace، timeout، retry، rate limit، alert و redaction.
- Staging acceptancecontract، negative auth، degraded deterministic و feedback candidate.
- Production canaryشرکت/استان/کارشناس، rollback و پذیرش مالک؛ هنوز انجام نشده است.