چیت‌شیت
توضیح‌دهنده‌های دیاگرام، نمودار و زیرساخت
Diagram, Chart and Infrastructure Explainers
چهار پروژه‌ی توضیح‌دهنده‌ی محلی. آن‌ها را اجرا کنید، به آن‌ها ورودی بدهید، خروجی‌هایشان را بخوانید و خطاهایشان را رفع کنید.
فهرست مطالب
چهار پروژه در کنار هم
مقایسه| فاکتور | Chart Storyboard Builder | Diagram Reading Companion | Infrastructure Plan Explainer | Service Ownership Navigator |
|---|---|---|---|---|
| زبان | Python 3.10+ | Node 22.18 یا جدیدتر | Python 3.10+ | Node 22.18 یا جدیدتر |
| ورودی | csv، roles، periods، charts | svg، graph | فایل JSON پلن Terraform | catalog، path |
| خروجی‌ها | chart-N.svg، chart-specs.json، storyboard.html | graph.json، analysis.json، report.html | change-brief.md، resource-impact.json، review.html | handoff.json، catalog.json، report.html |
| فایل بازنگری | ندارد | آرگومان سوم، ترتیب بازنگری‌شده | ندارد | ندارد |
| هرگز انجام نمی‌دهد | استنتاج تاریخ‌ها یا روابط علیتی | خواندن معنا از هندسه‌ی SVG | اعمال یک پلن | ارسال اعلان‌ها |
اجرای مرجع
دستورها| دستور | کاری که انجام می‌دهد |
|---|---|
python3 cli.py samples/input.json --output demo-output | نمونه‌ی نمودار یا زیرساخت |
node cli.ts sample.json output | نمونه‌ی دیاگرام یا مالکیت |
node cli.ts <input.json> <dir> <review.json> | دیاگرام با ترتیب بازنگری‌شده‌ی شما |
node cli.ts --help | خط آرگومان را چاپ می‌کند |
python3 scripts/project_test.py <project> --all --solution --strict | مرجع را ارزیابی و نمره‌دهی می‌کند |
python3 scripts/project_test.py <project> --init <dir> | یک استارتر می‌سازد |
توضیح یک پلن واقعی Terraform
کدbash
terraform show -json saved.plan > input.json # پلن ذخیره‌شده به‌صورت JSON
python3 cli.py input.json --output review # هرگز پلن را اعمال نمی‌کند
# review/change-brief.md آدرس‌ها با انکر‌های محلی
# review/resource-impact.json یال‌های گراف و منابع
# review/review.html تغییرات، یال‌ها، موارد حل‌نشده
پایپ‌لاین توضیح‌دهنده‌ی پلن
گام‌به‌گام- load_planفقط نگارش اصلی 1 را می‌پذیرد. اکشن‌ها و مقادیر ماسک‌شده‌ی
beforeوafterرا نگه می‌دارد. - load_planمقادیر حساس را به‌صورت
[sensitive]و مقادیر محاسبه‌شده را به‌صورت[unknown]نمایش می‌دهد. - classifyهر توالی دقیق اکشن‌ها را به یک نام اکشن نگاشت می‌کند.
- impact_graphارجاعات و
depends_onرا بر اساس طولانی‌ترین پیشوند آدرس پیوند می‌دهد. - impact_graphمتغیرهای
var،local،path،count،each،terraformوselfرا نادیده می‌گیرد. - explainخروجی Markdown را با یک انکر به ازای هر آدرس و وابستگی‌های اعلام‌شده می‌نویسد.
توالی‌های اکشن
دستورها| دستور | کاری که انجام می‌دهد |
|---|---|
["create"] | create |
["update"] | update، درجا |
["delete", "create"] | replace |
["create", "delete"] | replace |
["delete"] | delete |
`["read"]`, `["no-op"]`, `["forget"]` | read، بدون عملیات (no-op)، صرف‌نظر (forget) |
any other list | unsupported action sequence |
Diagram companion
معماریقواعد نمودار
مفهوم‌ها- roles
- مقادیر
group،valueوunitنام ستون‌های CSV و یک واحد نمایش را تعیین می‌کنند. - کاهنده‌ها
- شامل
sum،meanوcount. شمارش از مقادیر غیرخالی استفاده می‌کند، واحدrecords. - گرامر
barبرای دسته‌بندی‌ها،lineبرای دوره‌های مرتب‌شده.- مقدار خالی
- مقدار مفقود است، نه صفر. خط در آن نقطه قطع می‌شود.
- periods
- ترتیب را مشخص می‌کند. دوره‌ی غایب به‌صورت null رسم می‌شود.
- محور
- همیشه شامل صفر است.
- حاشیه‌نویسی
- نیازمند یک نقطه‌ی رسم‌شده است. متن، مقدار دقیق و واحد را دریافت می‌کند.
قواعد مالکیت
مفهوم‌ها- اولویت با آخرین تطابق
- آخرین قانون تطبیق‌یافته، مالکان نهایی را تعیین می‌کند.
- مهارشده (Anchored)
- الگویی که با
/شروع شود یا شامل/باشد از ریشه تطبیق داده می‌شود. - وایلدکاردها
- کاراکتر
*درون یک بخش می‌ماند،**/چند پوشه را پوشش می‌دهد،?یک کاراکتر است. - دایرکتوری
- اسلش انتهایی
/، پوشه و تمام محتویات زیر آن را تطبیق می‌دهد. - سرویس
- طولانی‌ترین
rootسرویسی که مسیر را در بر می‌گیرد. - مالکان
- فقط نام‌های
@userیا@org/team. - لینک‌های ران‌بوک
- لینک‌های محلی باید به یک فایل ران‌بوک ارائه‌شده اشاره کنند.
پیش‌فرض‌ها و محدودیت‌ها
پیش‌فرض‌ها| تنظیم | پیش‌فرض | نکته |
|---|---|---|
reducer | sum | به ازای هر نمودار در charts |
grammar | bar | یا line |
schema_version | 1 | مشخصات نمودار و خلاصه‌ی پلن |
SVG size | 500000 | حداکثر کاراکترها |
Rule source | CODEOWNERS | نام در ردیف‌های شواهد |
Output folder | output | آرگومان دوم CLIهای Node |
Chart width | 640 | حداقل عرض SVG به پیکسل |
پیام‌های خطا و راهکارها
عیب‌یابیunsupported Terraform JSON format major- علت
- فایل از نوع
terraform show -jsonنیست - راه‌حل
- پلن ذخیره‌شده را به‌صورت JSON اکسپورت کنید
periods omit data or duplicate a group- علت
- یک گروه داده در
periodsوجود ندارد - راه‌حل
- هر گروه را دقیقاً یک بار فهرست کنید
annotation needs a unique plotted point- علت
- یادداشت روی یک گروه خالی یا نامشخص
- راه‌حل
- یک نقطه‌ی دارای مقدار را حاشیه‌نویسی کنید
Node missing from SVG or duplicated- علت
- شناسه‌ی مانیفست فاقد
idدر SVG است - راه‌حل
- ویژگی
idرا به المان SVG اضافه کنید
Unsupported SVG element- علت
- تگ خارج از زیرمجموعه‌ی مجاز و امن است
- راه‌حل
- از اَشکال، متن،
g،titleوdescاستفاده کنید
Review order must contain every node exactly once- علت
- ترتیب قدیمی یا ناقص است
- راه‌حل
- هر شناسه‌ی گره را دقیقاً یک بار درج کنید
Earlier matching rules name different owners; last matching rule wins- علت
- قوانین همپوشانی دارند
- راه‌حل
- بررسی کنید که قانون آخر درست باشد
Missing local runbook link- علت
- ران‌بوک به فایلی ارجاع می‌دهد که ارائه نشده است
- راه‌حل
- فایل را به
runbooksاضافه کنید
نمونه‌های حل‌شده
پرسش و پاسخ- W1 با sum چه مقداری رسم می‌کند؟
- 18. ردیف‌های آن شامل 8 و 10 است.
- چه بر سر W2 و W3 می‌آید؟
- W2 خالی و W3 غایب است. هر دو به‌صورت مفقود رسم می‌شوند.
- چرا پایگاه داده از نوع replace است؟
- اکشن‌های آن ابتدا
deleteو سپسcreateهستند. - خلاصه برای رمز عبور چه چیزی را نشان می‌دهد؟
[sensitive]، حتی درون آرایه‌ها.- مالک
services/images/cache/store.tsکیست؟ - طبق آخرین قانون،
@fictional/cache. - دیاگرام در کجا branch می‌شود؟
- در
check، به سمتshareوclarify.
نکات
نکته‌ها- یال‌های گراف وابستگی‌های اعلام‌شده هستند، نه ترتیب اجرای پرووایدر.
- ابزار پلن زمان خرابی، هزینه یا ترتیب کامل اجرا را پیش‌بینی نمی‌کند.
- یک ترتیب خوانش صرفاً پیشنهادی برای بازنگری است، نه اثبات روش آموزش.
- فایل‌های SVG نمودار شامل
titleوdescهستند و هیچ JavaScriptی ندارند. - فرمت مالکیت یک زیرمجموعه‌ی محلی است، نه فرمت کامل CODEOWNERS.