پرش به محتویات

مستندات فنی تری‌پیلون

این بخش منبع حقیقت فنی تری‌پیلون برای Backend، Frontend وب، اپلیکیشن Mobile و تصمیم‌های معماری است. مستندات محصول توضیح می‌دهند چه چیزی و چرا ساخته می‌شود؛ این بخش توضیح می‌دهد سیستم چگونه طراحی، پیاده‌سازی، آزمون، منتشر و بهره‌برداری می‌شود.

مخاطبان و دامنه

مخاطبان اصلی این بخش Tech Lead، Developer، QA، DevOps/SRE، Security Reviewer و هر Consumer فنی قراردادها هستند. راهنمای کاربر نهایی، PRD، UX Writing و تصمیم کسب‌وکاری در طراحی Moduleهای محصول و سایر بخش‌های مستندات محصول نگهداری می‌شوند و در این بخش تکرار نمی‌شوند.

ساختار

  • Backend: قواعد معماری و کدنویسی، مستندات Moduleها و Runbookهای عملیاتی API.
  • Frontend وب: معماری Feature-first، ابزارها، توسعه محلی، امنیت BFF و Runbookهای انتشار Web.
  • اپلیکیشن Mobile: معماری Flutter، ابزارهای تاییدشده، امنیت Client و راه‌اندازی محلی.
  • تصمیم‌های معماری: ADRهای پذیرفته‌شده، جایگزین‌شده یا ردشده و پیامدهای آن‌ها.

قواعد منبع حقیقت

  1. هر موضوع یک صفحه مرجع دارد؛ صفحه‌های دیگر خلاصه لازم را می‌نویسند و به مرجع لینک می‌دهند.
  2. قرارداد HTTP در OpenAPI Repository بک‌اند منبع ماشینی Schema است؛ صفحه API فقط Context، Rule، Error، Retry و مثال را تکمیل می‌کند.
  3. تغییر Behavior بدون به‌روزرسانی هم‌زمان سند Module، API، Migration، ADR یا Runbook مرتبط کامل نیست.
  4. فایل AGENTS.md نزدیک کد فقط Rule اجرایی Agent و مسیر منبع حقیقت را نگه می‌دارد؛ مستند فنی مستقل در Repository کد ساخته نمی‌شود.
  5. README.md هر Repository فقط Quick Start و لینک ورود به این بخش را نگه می‌دارد و جای مستند مرجع را نمی‌گیرد.
  6. سند برنامه‌ریزی‌شده باید وضعیت خود را صریح بنویسد و نباید رفتار تحویل‌نشده را به‌عنوان قابلیت موجود معرفی کند.

چرخه تغییر

flowchart LR Need[نیاز یا تغییر] --> Product[بررسی مستند محصول] Product --> Decision{تصمیم معماری مهم؟} Decision -->|بله| ADR[ثبت یا اصلاح ADR] Decision -->|خیر| Contract[طراحی Contract و Data] ADR --> Contract Contract --> Code[پیاده‌سازی و Test] Code --> Docs[به‌روزرسانی Module و Runbook] Docs --> Verify[Lint و Build سخت‌گیرانه] Verify --> Review[Review متناسب با ریسک]

حداقل محتوای هر صفحه

  • Front Matter معتبر با title، description، tags و owner؛
  • دقیقا یک H1 و بخش‌های کوتاه با هدف روشن؛
  • دامنه، خارج از دامنه، مالک و وضعیت؛
  • رفتار موفق، خطا، حالت مرزی و اثر امنیتی در صورت ارتباط؛
  • لینک Relative به سند محصول، Contract، Migration، ADR، Test یا Runbook مرتبط؛
  • داده ساختگی و بدون Secret، Credential یا اطلاعات شخصی واقعی.

کنترل کیفیت

پیش از Merge باید Navigation تولید شود، لینک‌ها بررسی شوند، git diff --check و mkdocs build --strict موفق باشند و Reviewer متناسب با ریسک سند را تایید کند. قرارداد کامل Lint و نگارش در Handbook با نام راهنمای مستند‌سازی در Root همین Repository نگهداری می‌شود.