مستندات جدول‌ها
مستندات جدول‌ها، توضیح فارسیِ هر جدول و ستون پایگاه‌دادهٔ شماست: هر جدول چه چیزی را نگه می‌دارد، هر ستون چه معنایی و چه واحدی دارد و جدول‌ها چگونه به هم وصل‌اند. عامل هوشمند پیش از نوشتن هر پرس‌وجو این مستندات را می‌خواند؛ پس کیفیت پاسخ‌ها بیش از هر چیز به کیفیت همین مستندات بستگی دارد.
اوبا این مستندات را با هوش مصنوعی پیش‌نویس می‌کند و شما بازبینی و تأییدشان می‌کنید.
کجا انجام می‌شود؟
Section titled “کجا انجام می‌شود؟”- هنگام راه‌اندازی شرکت: در مرحلهٔ «مستندات جدول‌ها».
- بعد از آن: در صفحهٔ هر اتصال، زبانهٔ «دانش داده»، بخش «مستندات جدول‌ها».
بالای این بخش یک نوار خلاصه وضعیت را می‌گوید: «مستند شده: … از …»، تعداد جدول‌هایی که «منتظر پاسخ شما» هستند و آخرین «به‌روزرسانی شبانه». جزئیات بیشتر (سطح مستندات، جدول‌های تغییرکرده و …) در «جزئیات مستندسازی» جمع شده است.
پیش از شروع
Section titled “پیش از شروع”- اتصال آزمایش شده و موفق باشد (افزودن اتصال).
- توضیح پایگاه‌داده را ذخیره کرده باشید. اگر ذخیره نکرده باشید، اوبا پیش از تولید یادآوری می‌کند؛ می‌توانید بدون آن هم ادامه دهید، ولی مستندات کم‌دقت‌تر می‌شوند.
- تولید مستندات از اعتبار بستهٔ شرکت کم می‌کند. تعداد جدول‌هایی که توضیح هوش مصنوعی می‌گیرند هم به بستهٔ شما بستگی دارد؛ بقیهٔ جدول‌ها با مستندات پایه (ساختارشان) شناخته می‌شوند.
انتخاب بخش‌ها و جدول‌ها
Section titled “انتخاب بخش‌ها و جدول‌ها”«انتخاب جدول‌ها…» را بزنید تا پنل کناری «انتخاب جدول‌ها» باز شود:
- بخش‌های پایگاه‌داده (شِما). بسیاری از پایگاه‌داده‌ها جدول‌ها را در چند بخش (شِما) نگه می‌دارند. «نمایش بخش‌های پایگاه‌داده» را بزنید، بخش‌های لازم را انتخاب و «ذخیرهٔ محدوده» را بزنید. «افزودن همهٔ بخش‌های پایگاه‌داده» همهٔ بخش‌های دارای جدول را یک‌جا اضافه می‌کند. اگر پایگاه‌داده ماژول‌های جدا دارد، در «ماژول‌های پایگاه‌داده» می‌توانید ماژول‌های بی‌استفاده را کنار بگذارید.
- جدول‌ها. با «جست‌وجوی نام جدول» جدول‌ها را پیدا کنید، تیک بزنید (یا «انتخاب همه» / «هیچ‌کدام») و «ذخیرهٔ انتخاب» را بزنید. تا انتخاب ذخیره نشود، تولید شروع نمی‌شود.
اگر پنل را با تغییرات ذخیره‌نشده ببندید، اوبا پیش از کنار گذاشتن آن‌ها می‌پرسد. در راه‌اندازی شرکت همین انتخاب‌ها مستقیم در صفحه نمایش داده می‌شوند.
تولید و بازبینی
Section titled “تولید و بازبینی”- تولید را شروع کنید. بار اول روی «تولید مستندات» بزنید (در راه‌اندازی شرکت: «تولید مستندات با هوش مصنوعی»). بعدها همین دکمه بسته به وضعیت، «ادامهٔ تولید (جدول‌های باقی‌مانده)»، «به‌روزرسانی جدول‌های تغییرکرده» یا «بررسی جدول‌های جدید» می‌شود. اگر جدول‌ها زیاد باشند، کار در چند نوبت انجام می‌شود و پنجرهٔ «تأیید مستندسازی چندنوبتی» برآورد کار را نشان می‌دهد؛ «تأیید و شروع مستندسازی» را بزنید.
- منتظر بمانید یا بروید. تولید روی سرور انجام می‌شود و با بستن صفحه متوقف نمی‌شود. برای توقف، «لغو تولید» یا «توقف پس از این نوبت» را بزنید.
- پیش‌نویس‌ها را بازبینی کنید. در «پیش‌نویس جدول‌ها» برای هر جدول «تأیید»، «ویرایش» یا «بازتولید این جدول» را بزنید.
- نهایی کنید. پس از بازبینی، «ثبت نهایی همهٔ پیش‌نویس‌ها» را بزنید. پیام «همهٔ پیش‌نویس‌ها تأیید شدند» یعنی مستندات برای گفت‌وگو آماده است. جدول‌هایی که تولیدشان ناموفق بوده، مانع ثبت بقیه نمی‌شوند؛ بعداً آن‌ها را کامل کنید.
منوی «گزینه‌های بیشتر مستندسازی» کنار دکمهٔ اصلی، «بازتولید کامل» و «افزودن سند دستی» را دارد. سندهای دستی (مثلاً فرهنگ دادهٔ شرکت) در «سندهای دستی» زیر همین بخش فهرست می‌شوند.
پس از نهایی شدن، اوبا برای همان اتصال حداکثر شش پرسش پیشنهادی می‌سازد که روی صفحهٔ آغاز گفت‌وگو نمایش داده می‌شوند.
پرسش‌ها و پاسخ‌های مستندسازی
Section titled “پرسش‌ها و پاسخ‌های مستندسازی”اگر عامل دربارهٔ جدولی مطمئن نبوده، پرسشش را در «پرسش‌ها و پاسخ‌های مستندسازی» می‌بینید و نوار خلاصه می‌گوید چند جدول منتظر پاسخ شماست. تولید بقیهٔ جدول‌ها منتظر پاسخ نمی‌ماند. پاسخ شما در مستندات همان جدول ثبت می‌شود؛ کنار هر پاسخ، پاسخ‌دهنده و زمان پاسخ آمده است.
در هر پیش‌نویس چه چیزی را بررسی کنید؟
Section titled “در هر پیش‌نویس چه چیزی را بررسی کنید؟”- معنای جدول: آیا هر ردیف یک سفارش است یا یک قلم سفارش؟
- واحد ستون‌های عددی: ریال، تومان، کیلوگرم، تن، درصد.
- کدها و وضعیت‌ها: معنای هر مقدار، مثلاً ۳ = لغوشده. جدول‌های کد را در جدول‌های کد و ارتباط‌ها هم تأیید کنید.
- تاریخ‌ها: میلادی یا شمسی، و کدام ستون تاریخ مبنای گزارش است.
- رابطه‌ها: کدام ستون به کدام جدول اشاره دارد.
سطح مستندسازی: پایه · کوتاه · کامل
Section titled “سطح مستندسازی: پایه · کوتاه · کامل”هر جدول یکی از سه سطح مستندات را دارد و نشان سطح روی کارت هر پیش‌نویس دیده می‌شود (با نگه داشتن نشانگر روی نشان، معنایش را می‌بینید):
| نشان | چه چیزی دارد |
|---|---|
| «پایه» | فقط ساختار جدول: ستون‌ها، کلیدها و رابطه‌ها، بدون توضیح هوش مصنوعی. |
| «کوتاه» | یک توضیح کوتاه دربارهٔ اینکه جدول چه چیزی نگه می‌دارد. |
| «کامل» | توضیح جدول همراه با معنای تک‌تک ستون‌هایش. |
اگر بستهٔ شما تعداد جدول‌های دارای توضیح هوش مصنوعی را محدود کند، جدول‌های مهم از پیش انتخاب می‌شوند و بقیه «فقط مستندات پایه» می‌گیرند؛ با «مستندسازی کامل شود» یا «فقط مستندات پایه» و سپس «ذخیرهٔ اولویت‌ها» این را تغییر دهید.
نشان‌های دیگر
Section titled “نشان‌های دیگر”- «خانوادهٔ جدول»، «پارتیشن»، «کپی‌های هم‌ساختار»: جدول‌های پارتیشن‌شده و نسخه‌های هم‌ساختار (مثلاً یک جدول برای هر سال) یک بار توضیح داده می‌شوند. اگر عضوی واقعاً متفاوت است، «جدا کردن از خانواده» را بزنید.
- «این جدول خالی است»: جدول خالی فقط مستندات پایه می‌گیرد.
- «جدول مشتق — بدون فیلتر اسکن نکنید» و «جدول لاگ — بدون فیلتر اسکن نکنید»: این جدول‌ها مهم شمرده نمی‌شوند و عامل از خواندن کامل آن‌ها پرهیز می‌کند.
به‌روز ماندن مستندات
Section titled “به‌روز ماندن مستندات”اگر برای اتصال «به‌روزرسانی شبانه» روشن باشد، هر شب ساختار پایگاه‌داده دوباره خوانده می‌شود و فقط جدول‌های تازه یا تغییرکرده دوباره مستند می‌شوند. این گزینه را در زبانهٔ «پیشرفته» تنظیم کنید (تنظیمات پیشرفتهٔ اتصال). نتیجهٔ آخرین اجرا در «جزئیات مستندسازی» آمده است؛ زمان آن نسبی نوشته می‌شود (مثلاً «۲ ساعت پیش») و تاریخ دقیق با نگه داشتن نشانگر دیده می‌شود. برای بررسی دستی، «بررسی جدول‌های جدید» را بزنید.
پایگاه‌داده‌های بزرگ
Section titled “پایگاه‌داده‌های بزرگ”- فهرست جدول‌ها محدودیتی ندارد و کار دسته‌به‌دسته روی سرور انجام می‌شود.
- پیش از شروع، اوبا هزینهٔ برآوردی را با اعتبار باقی‌مانده مقایسه می‌کند. اگر کافی نباشد، پیام «اعتبار باقی‌مانده برای تکمیل آشنایی با این پایگاه داده کافی نیست» با دو گزینهٔ «انتخاب جداول کمتر» و «تماس با پشتیبانی» (برای افزایش اعتبار) نمایش داده می‌شود.
- برای پایگاه‌داده‌ای با صدها یا هزاران جدول، «حالت پایگاه‌دادهٔ بزرگ» را در زبانهٔ «پیشرفته» روشن کنید.
نقاط پایانی API
Section titled “نقاط پایانی API”برای اتصال REST API، به‌جای جدول‌ها نقاط پایانی مستند می‌شوند. در زبانهٔ «دانش داده»، بخش «نقاط پایانی API و قابلیت‌ها»:
- نقاط پایانی موردنظر را (هر خط یک مورد) بنویسید و «شناسایی نقاط پایانی» را بزنید. برای هر کدام نمونه‌برداری می‌شود و یک سند پیش‌نویس در «مستندات جدول‌ها» ساخته می‌شود.
- برای هر نقطهٔ پایانی مشخص کنید کدام پارامترها «فیلتر» هستند و نوع صفحه‌بندی چیست، سپس تنظیمات را ذخیره کنید.
- پیش‌نویس‌ها را مانند جدول‌ها بازبینی و نهایی کنید.
مدیر شرکت فرضی «پخش البرز» در «انتخاب جدول‌ها…» بخش sales را انتخاب و ۴۰ جدول آن را تیک می‌زند. در پیش‌نویس جدول OrderItems، عامل ستون Qty را «مقدار» و واحدش را نامشخص نوشته است. کارشناس فروش آن را ویرایش می‌کند: «تعداد کارتن؛ هر کارتن ۱۲ عدد». در «پرسش‌ها و پاسخ‌های مستندسازی» عامل پرسیده است که Status = 5 یعنی چه؛ پاسخ «مرجوعی کامل» ثبت می‌شود. سپس «ثبت نهایی همهٔ پیش‌نویس‌ها» را می‌زند.
اشکالات رایج
Section titled “اشکالات رایج”| پیام یا نشانه | علت محتمل | چه کنید |
|---|---|---|
| «تغییر انتخاب جدول‌ها هنوز ذخیره نشده است…» | تیک‌ها ذخیره نشده‌اند | «ذخیرهٔ انتخاب» را بزنید. |
| «تولید مستندات جدول‌ها برای این اتصال از قبل در حال اجراست.» | تولید دیگری در جریان است | صبر کنید تا تمام شود. |
| «تعداد اسناد این اتصال به سقف مجاز رسیده است» یا «مستندسازی دوباره انجام نشد چون سقف مستندسازی بستهٔ شما پر شده است.» | سقف بسته | جدول‌های کم‌اهمیت را «فقط مستندات پایه» کنید، یا مدیر شرکت ارتقای بسته را از پشتیبانی درخواست کند. |
| پیش‌نویس جدولی ناقص یا ناموفق است | قطع اتصال یا نبود مجوز خواندن جدول | اتصال را آزمایش کنید، مجوز SELECT را بررسی و سپس «بازتولید این جدول» را بزنید. |
| پاسخ‌ها واحد یا معنی را اشتباه می‌گویند | مستندات جدول مربوط نادرست است | پیش‌نویس را ویرایش و دوباره ثبت کنید. |