نخستین کامیت همسایه یک readme است که ساعت ۱۵:۲۰ به وقت تهران در ۷ فوریهٔ ۲۰۲۶ ثبت شد. همان بعدازظهر نُه کامیت دیگر از جنس سند پشتش آمد. اولین کد ساعت ۱۹:۱۰ رسید، سه ساعت و پنجاه دقیقه بعد از readme.
همسایه یک محصول مدیریت ساختمان برای ساختمان‌های مسکونی در ایران است: شارژ، پرداخت، تیکت، حاکمیت ساختمان و حسابداری پشت همهٔ این‌ها. هنوز در حال توسعه است. با Docker Compose و داده‌های نمایشی اجرا می‌شود و پرداخت آنلاین از جریان آزمایشی sandbox می‌گذرد. بیشتر کامیت‌ها از من است و چند مشارکت‌کنندهٔ دیگر هم بخش‌های کوچک‌تری اضافه کرده‌اند.
صفحهٔ مطالعهٔ موردی استک را شرح می‌دهد. این یادداشت‌ها به شکل‌گیری کار می‌پردازند و از روی سوابق مخزن نوشته شده‌اند، بدون اینکه خاطره‌ای رویش اضافه شده باشد. هر جا کامیت یا سندی دلیلی را گفته باشد، همان را می‌آورم. هر جا دلیلی ثبت نشده، تغییر را شرح می‌دهم و همین را هم می‌گویم.
ده کامیت سند
بین ۱۵:۲۰ و ۱۸:۳۹ این‌ها به مخزن اضافه شد: یک نقشهٔ راه فازبندی‌شده، یک استراتژی محصول، پرسوناها، اپیک‌ها، گاردریل‌های اجرایی، دروازه‌های مرحله‌ای، برنامه‌های بک‌اند و فرانت‌اند برای هر فاز و یک نقشهٔ راه یکپارچه. پس سندها واقعاً زودتر از کد آمدند، با فاصله‌ای کمتر از چهار ساعت.
سندهای استراتژی رقیب را همان ترکیب صفحه‌گسترده، گروه تلگرام و دفترچهٔ کاغذی می‌دانند که ساختمان از قبل با آن کار می‌کند. یکی از اصول این است: «هر ریال باید قابل ردیابی باشد». ضدهدف‌ها خرید و فروش ملک را کنار می‌گذارند. دو پرسونا بالاترین اولویت را دارند: مدیر حرفه‌ای که سه تا پنج مجتمع را اداره می‌کند، و مدیر داوطلبی که می‌خواهد در برابر اتهام مدرک داشته باشد و کار را راحت به مدیر بعدی تحویل بدهد. قسمت ۲ به مدل دسترسی‌ای می‌پردازد که باید از این تحویل پشتیبانی کند.
نقشهٔ راه با فاز ۰ شروع می‌شود، یک فاز پژوهشی چهار تا شش‌هفته‌ای با دست‌کم ۲۰ مصاحبه با مدیران و دست‌کم ۱۰۰ پاسخ پرسش‌نامه از ساکنان. چهار تا شش هفته در فاصلهٔ یک readme و اولین کامیت کد در همان روز جا نمی‌شود و مخزن هیچ خروجی‌ای از آن فاز ندارد. هر چه پیش از ساخته شدن مخزن رخ داده باشد بیرون از چیزی است که مخزن می‌تواند نشان بدهد، پس این یادداشت‌ها از همان کامیت اول شروع می‌شوند.
عصر ۷ فوریه
اولین کامیت کد یک API فاز ۱ را روی .NET 10 با معماری onion پیاده کرد. عدد درشت این کامیت گمراه‌کننده است: ۸۵۶ فایل و ۳۵٬۵۲۵ خط، که ۷۹۷ فایلش خروجی بیلد در bin و obj بود. سورس آن کامیت ۵۹ فایل و ۲٬۰۷۳ خط بود. سیزده دقیقه بعد، کامیت بعدی هر ۷۹۷ فایل بیلد را حذف کرد و پورتال‌های RTL ادمین و ساختمان را اضافه کرد.
یک فایل Docker Compose با یک کانتینر API و یک کانتینر وب ساعت ۱۹:۵۱ اضافه شد. پشتیبانی از PostgreSQL و Redis ساعت ۲۲:۱۰ آمد و SQLite هم به‌عنوان گزینه ماند. ساعت ۲۲:۲۲ پنل‌ها اولین بازطراحی‌شان را گرفتند. ساعت ۲۲:۳۶ کامیتی برچسب‌ها و پیام‌های فارسی پنل‌های داشبورد را برگرداند، اولین مورد از اصلاح‌های متنی که قسمت ۵ به آن‌ها می‌پردازد. آن روز با ۲۱ کامیت تمام شد.
شکل تاریخچه
شاخهٔ اصلی ۱٬۱۳۲ کامیت دارد، از ۷ فوریه تا ۱۱ اکتبر ۲۰۲۶.
| ماه (۲۰۲۶) | کامیت‌ها |
|---|---|
| فوریه | 84 |
| مارس | 1 |
| آوریل | 311 |
| مه | 470 |
| ژوئن | 235 |
| ژوئیه | 0 |
| اوت | 30 |
| سپتامبر | 0 |
| اکتبر | 1 |
شلوغ‌ترین روز ۴ ژوئن بود با ۶۱ کامیت، که بیشترشان یک تست سناریو در هر کامیت بودند، و بعد از آن ۱۹ آوریل با ۵۰ کامیت. تعداد کامیت معیار ضعیفی برای میزان کار است و پیام‌های این کامیت‌ها بعد از اواخر ماه مه کوتاه‌تر و کم‌اطلاع‌تر می‌شوند، پس از ژوئن به بعد شواهد کمتر می‌شود. لاگ هیچ کامیت git revert ندارد، با این حال خیلی چیزها برگردانده شد، همیشه با یک کامیت رو به جلو که چیزی را حذف یا بازنویسی می‌کرد.
شمردن فایل‌ها در چند کامیت نمای دیگری می‌دهد:
| تاریخ | اتریبیوت‌های xUnit | فایل‌های Vitest | فایل‌های .cs بک‌اند | فایل‌های سورس فرانت‌اند | فایل‌های مایگریشن |
|---|---|---|---|---|---|
| ۱۲ فوریه | 3 | 0 | 188 | 26 | 0 |
| ۱۰ آوریل | 118 | 0 | 636 | 86 | 3 |
| ۳ مه | 125 | 53 | 674 | 767 | 6 |
| ۱۶ مه | 307 | 72 | 751 | 892 | 16 |
| ۴ ژوئن | 363 | 85 | 785 | 919 | 38 |
| ۲۴ ژوئن | 392 | 86 | 860 | 963 | 52 |
| ۱۱ اکتبر | 392 | 97 | 860 | 1,029 | 53 |
ستون xUnit خط‌های اتریبیوت [Fact] و [Theory] را می‌شمارد و این عدد از تعداد حالت‌هایی که اجرا می‌شوند کمتر است. فایل‌های بک‌اند مایگریشن‌ها را شامل نمی‌شوند و فایل‌های مایگریشن هم فایل‌های designer و snapshot را. فایل‌های سورس فرانت‌اند همهٔ فایل‌های اسکریپت زیر front-end/src هستند. فرانت‌اند در حدود سه هفته از ۸۶ فایل به ۷۶۷ فایل جهید، در جریان بازمعماری‌ای که قسمت ۶ به آن می‌پردازد. شمارش xUnit در ۱۶ مه، روزی که تست‌های حسابداری اضافه شدند، در یک روز ۱۸۰ تا بالا رفت. این ستون‌ها اندازه را نشان می‌دهند و چیزی دربارهٔ کیفیت نمی‌گویند.
ماه‌ها کجا رفتند
بقیهٔ فوریه به چرخش‌های معماری و نسخهٔ اول فیچرها گذشت: ۶۳ کامیت که پایگاه دادهٔ audit، CRUD ادمین و اپیک‌های مالی هم بینشان بود. آوریل با ۱۲۰ کامیت در نُه روز شروع شد که کمبودهای حاکمیت، رزرو، اسناد، تیکت و هویت را پر می‌کردند و این بازه با اسکیماهای PostgreSQL و جدا شدن به دو هاست API تمام شد.
از ۱۵ آوریل تا ۸ مه تمرکز کار روی فرانت‌اند بود: ۳۲۳ کامیت شامل مایگریشن به React Query، مرزبندی لایه‌ها در ۳۶۰ فایل و انتقال به TypeScript که در یک کامیت نام ۶۹۳ فایل را عوض کرد. نوبت بک‌اند از ۹ تا ۱۶ مه رسید، با ۸۱ کامیت که لایهٔ persistence را بر اساس اسکیما گروه‌بندی کردند و پروژه‌های حسابداری را ساختند. نیمهٔ دوم مه، با ۲۵۷ کامیت، صرف آنبوردینگ، بازطراحی پورتال‌ها و اولین پروژهٔ اندروید شد. ۲۳۵ کامیت ژوئن به کار روی ساختمان‌های کوچک محدود شد، از جمله ۴۸ اسپک سناریو در یک روز و عمق بیشتر در بخش مالی مثل کنترل هزینه، مانده‌های افتتاحیه و سررسیدها.
اوت یک دور کار دوروزه روی دیزاین سیستم آورد با ۲۷ کامیت غیر merge، و تنها کامیت اکتبر هم یک دور اصلاح بصری روی ۴۴ فایل در صفحه‌های لندینگ، احراز هویت و داشبورد است. اگر لاگ را بر اساس اولین کلمهٔ پیام مرتب کنیم، ۲۴۵ کامیت با feat شروع می‌شوند، ۱۸۷ با refactor، ۱۵۱ با add و ۸۳ با fix.
چه بر سر نقشهٔ راه آمد
نقشهٔ راه برای هر کدام از فازهای ۱ تا ۴ بین ۶ تا ۱۲ هفته تخمین زده بود. کامیت‌هایی که این برچسب‌ها را داشتند با چند روز فاصله آمدند: همهٔ اپیک‌های مالی در ۲۳ فوریه، ماژول‌های خدماتی فاز ۳ در ۲۶ فوریه، حاکمیت و دارایی‌های فاز ۴ در ۲۷ فوریه. برچسب‌ها از کد جلو زدند. فهرست کمبودهایی که ۵ آوریل اضافه شد هنوز اجرای جریمهٔ دیرکرد، رشته‌نظرهای تیکت و اکشن‌های گردش کار SLA را باز نگه داشته بود، و کامیت دیگری در همان روز ماک‌های دارایی و سند را با جریان‌های واقعی API جایگزین کرد.
| فاز | عنوان | وضعیت در مخزن |
|---|---|---|
| 0 | کشف نیاز | بدون خروجی در مخزن |
| 1 | MVP پایه | پیاده‌سازی‌شده |
| 2 | مالی و کنترل | پیاده‌سازی‌شده |
| 3 | خدمات و مشارکت | پیاده‌سازی‌شده |
| 4 | حاکمیت و دارایی‌ها | پیاده‌سازی‌شده |
| 5 | رشد | تا حدی؛ اشتراک‌ها در ۲۵ مه حذف شدند |
| ۵ تکمیلی | آنبوردینگ و آمادگی برای رشد | در ماه مه اضافه شد؛ ویزارد و ایمپورت اکسل بعداً انجام شدند و موارد دیگر در آن زمان کمبود ثبت شده بودند |
| 6 | ساختمان هوشمند | فقط در حد برنامه |
| 7 | شبکهٔ مدیران حرفه‌ای | فقط در حد برنامه |
پیاده‌سازی‌شده یعنی کد در محصولی وجود دارد که هنوز در حال توسعه است. سندها همچنین بین فازها دروازه‌های مرحله‌ای، یک فریز دامنهٔ کار پیش از هر نسخهٔ نامزد انتشار و KPI برای هر فاز تعریف می‌کنند، همه طوری نوشته‌شده که انگار برای یک شرکت است. مخزن هیچ دادهٔ KPI ندارد و تا جایی که تاریخچه نشان می‌دهد، کار منتظر این دروازه‌ها نماند.
سند فاز ۵ دو مورد مرتبط را خارج از دامنه گذاشته بود: پشتیبانی کامل چندزبانه و بازطراحی بنیادی معماری در دوران رشد. هر دو با این حال در ماه مه رخ دادند. یک مشارکت‌کنندهٔ دیگر پشتیبانی انگلیسی و LTR را اضافه کرد و بک‌اند به ماژول‌ها شکسته شد که قسمت ۴ به آن می‌پردازد.
چند تغییر بزرگ دلیل ثبت‌شده‌ای ندارند. مدیریت اشتراک در ۲۵ مه حذف شد: ۷۴ فایل پاک شد، ۴٬۱۹۵ خط رفت، جدول‌ها drop شدند و readme هنوز از آن نام می‌برد. در ۳ ژوئن یک بک‌لاگ جدید و یک سند سناریو به سراغ ساختمانی ۸ واحدی با یک مدیر رفتند، در حالی که استراتژی در ابتدا ساختمان‌های بزرگ‌تر را هدف گرفته بود. سندها ساختمان کوچک را توصیف می‌کنند، بی‌آنکه این چرخش را توضیح بدهند.
سبک معماری هم در ۱۶ روز سه بار عوض شد: onion با ریپازیتوری در ۸ فوریه، Clean Architecture با MediatR در ۱۲ فوریه و بازسازی DDD در ۲۳ فوریه. فقط مورد وسطی انگیزه‌ای ثبت کرده، در پیام کامیتش: «شکستن سرویس‌های یکپارچه (حدود ۲٬۴۰۰ خط) به بیش از ۵۰ هندلر متمرکز MediatR».
بازگشت‌های کوچک‌تری هم در همین ماه‌ها پخش‌اند. در ۹ آوریل، ۱۹ فایل مایگریشن با یک فایل جایگزین شدند، در کامیتی که حدود ۳۰٬۰۰۰ خط را حذف کرد؛ قسمت ۴ به آن می‌پردازد. یک پیش‌نویس آنبوردینگ که در حافظهٔ مرورگر بود در ۲۰ مه به سرور منتقل شد که موضوع قسمت ۳ است. در ۱۶ ژوئن کامیتی CRUD طرح اقساط را اضافه کرد و کامیت دیگری با عنوان «حذف طرح اقساط» همان روز آمد، هرچند پوشهٔ فیچر هنوز سر جایش است. این تغییر آخر هم دلیل ثبت‌شده‌ای ندارد.
سولوشن در وضعیت امروز
بک‌اند ۱۱ پروژه دارد:
back-end/src Hamsayeh.Api.Admin Hamsayeh.Api.User Hamsayeh.Api.Shared Hamsayeh.Domain Hamsayeh.Application Hamsayeh.Infrastructure Hamsayeh.Accounting.Domain Hamsayeh.Accounting.Application Hamsayeh.Accounting.Infrastructure back-end/tests Hamsayeh.Application.Tests Hamsayeh.Api.Tests
تا ۱۰ آوریل یک پروژهٔ API بود و بعد دو هاست با زیرساخت مشترک. پروژهٔ دوازدهم، Hamsayeh.Accounting.Contracts، در ۱۶ مه ساخته شد و در ۲۱ مه به دلیل بی‌استفاده بودن حذف شد. از ۸۶۰ فایل .cs بیرون از مایگریشن‌ها، ۴۹۴ فایل در Hamsayeh.Application است. Infrastructure ۱۱۱ فایل دارد، Domain ۹۲ فایل، دو هاست API روی هم ۴۶ فایل و سه پروژهٔ حسابداری ۱۰۵ فایل.
این چیدمان حسابداری را جداتر از آنچه هست نشان می‌دهد. دامنه و persistence آن پروژه‌های خودشان را دارند، اما بیشتر کامندها و هندلرهای حسابداری هنوز در Hamsayeh.Application/Features هستند: Charges ۲۸ فایل دارد، PenaltyRules ۱۸، Funds ۱۵، InstallmentPlans ۱۴ و Payments ۱۳. Hamsayeh.Accounting.Application انتزاع‌ها و ثبت‌های دفتر کل را نگه می‌دارد. تا جایی که کد نشان می‌دهد، این مرز برای دامنه و persistence محکم است و برای use caseها نرم‌تر.
قسمت ۲ یک فرض اولیه از این تاریخچه را برمی‌دارد، اینکه هر فرد یک نقش دارد، و دنبال می‌کند که جایگزین کردنش چه چیزهایی لازم داشت.
این یادداشت به انگلیسی هم منتشر شده است: نسخهٔ انگلیسی.