شاپکور — پلتفرم فروشگاهی سازمانی فارسی
یک پلتفرم فروشگاهی فارسیمحور و قابل استفاده مجدد که از پایه طراحی و پیادهسازی کردم (نخستین استقرار برای رد اکسسوری): کاتالوگ تنوعدار، دفترکل چندانباری، پرداخت درگاهی و کارتبهکارت، دسترسی مبتنی بر قابلیت و CMS پویا.
سال
2026
نقش
بنیانگذار و توسعهدهنده فولاستک
فناوریها
Next.js • TypeScript • PostgreSQL
داستان پروژه
شاپکور یک پلتفرم فروشگاهی فارسیمحور و قابل استفاده مجدد است که از پایه — نخستین بار برای رد اکسسوری — طراحی کردم تا کشف محصول در ویترین، دفترکل موجودی چندانباری، پرداخت دوگانه آنلاین و کارتبهکارت، دسترسی RBAC و CMS پویا را در یک مونولیت ماژولار یکپارچه کند.
مسئلهها و اولویتها
- 01جلوگیری از فروش بیش از موجودی و خطای انبار در خرید همزمان با دفترکل تغییرناپذیر چندانباری و رزرو زماندار.
- 02پشتیبانی همزمان از درگاه پرداخت آنلاین و انتقال کارتبهکارت با فیش خصوصی، تطبیق مالی و شمارهکارت نسخهدار.
- 03اعمال دسترسی دقیق مبتنی بر قابلیت (بیش از ۵۵ مجوز)، چرخش دو-توکنی با کشف بازپخش، تایید دومرحلهای TOTP و تایید مجدد.
- 04ارائه معماری فارسیمحور و قابل استفاده مجدد با نرمالسازی جستوجو، تقویم جلالی، حساب صحیح BigInt، الگوی Outbox و CMS پویا.
آنچه پیادهسازی کردم
ویترین و کاتالوگ ماژولار با نرمالسازی جستوجوی فارسی، تنوعهای چندبعدی، ستهای ترکیبی، موتور تخفیف و صفحهساز نسخهدار CMS.
قصد خرید تراکنشی، دفترکل رزرو موجودی، بهای تمامشده میانگین موزون، پرداخت دوگانه درگاه/فیش و بازرسی مرجوعی.
چرخش دو-توکنی نشست، رمزنگاری Argon2id و TOTP، بیش از ۵۵ قابلیت RBAC، صف Outbox، ممیزی تغییرناپذیر و CI/CD خودکار.
نقش و مسئولیت من
شاپکور را از ابتدا تا انتها بهعنوان یک پلتفرم فروشگاهی فارسیمحور و قابل استفاده مجدد (نخستین استقرار برای رد اکسسوری) طراحی و پیادهسازی کردم؛ شامل مدلسازی دامنه، طرحواره PostgreSQL، معماری امنیت، رابط ویترین و پنل، آزمون خودکار و تحویل Docker CI/CD. گزارش تفصیلی پایین معماری و مرزهای آن را شرح میدهد.
خروجی کار
- هسته فروشگاهی ماژولار و قابل استفاده مجدد برای کشف محصول، تسویه، ارسال، بازرسی مرجوعی، تیکت پشتیبانی و CMS.
- تضمین قواعد مالی و موجودی با تراکنشهای PostgreSQL 18، تریگر ممیزی تغییرناپذیر و صف Outbox با pg-boss.
- آزمونشده در لایههای واحد، یکپارچگی PostgreSQL، قرارداد API، گارد نقاط ورود و سناریوهای مرورگر fa-IR همراه با CI/CD خودکار Docker.
نگاهی به درون شاپکور؛ گزارش محصول و مهندسی
بررسی دقیق معماری یک پلتفرم فروشگاهی فارسیمحور و قابل استفاده مجدد — نخستین بار برای رد اکسسوری پیادهسازی شده — که کشف محصول در ویترین، کاتالوگ تنوعدار، دفترکل چندانباری، پرداخت دوگانه درگاه و کارتبهکارت، دسترسی مبتنی بر مجوز و CMS را در یک مونولیت ماژولار به هم متصل میکند.
محصول و کد در ۱۷ نوامبر ۲۰۲۶ بررسی شدهاند. تصاویر ویترین فروشگاه و پنل مدیریت از نصب مرجع رد اکسسوری در محیط محلی با دادههای نمایشی تهیه شدهاند و هیچ اطلاعات واقعی مشتری، کارمند یا پرداخت ندارند. مطالب زیر رفتار پیادهسازیشده و بررسیشده را بدون آمار ساختگی ترافیک یا درآمد شرح میدهند.
یک چرخه یکپارچه تجارت الکترونیک
- ۱
کشف با جستوجوی فارسی
- ۲
انتخاب تنوع و رزرو موجودی
- ۳
تأیید هویت و پیشفاکتور
- ۴
پرداخت درگاهی یا فیش بانکی
- ۵
تخصیص، بستهبندی و ارسال
- ۶
ممیزی، پشتیبانی و نگهداری
۰۱ — مسئله محصول و چشمانداز معماری
بسیاری از فروشگاههای سفارشی در شکاف بین ویترین و عملیات روزانه دچار مشکل میشوند: مدل کاتالوگ از تنوعهای چندبعدی یا ستهای ترکیبی پشتیبانی نمیکند، موجودی در خریدهای همزمان دچار خطا میشود، فیشهای کارتبهکارت در پیامرسانها رها میشوند و کارکنان با یک رمز مشترک وارد پنل میشوند.
شاپکور را بهعنوان یک هسته فروشگاهی فارسیمحور و قابل استفاده مجدد — با رد اکسسوری بهعنوان نخستین استقرار عملیاتی — در قالب یک مونولیت ماژولار دقیق طراحی و پیادهسازی کردم. منطق دامنه در ماژولهای مجزا زیر src/modules/ (کاتالوگ، انبار، تسویه، سفارش، پرداخت، ارسال، تخفیفها، مرجوعی، مشتریان، محتوا، بازاریابی، مجوزها، ممیزی، گزارشها و تنظیمات) و لایه زیرساختی زیر src/platform/ تفکیک شده است.
این پلتفرم به خریداران در موبایل و دسکتاپ، اپراتورهای انبار و بستهبندی، واحد مالی برای تطبیق فیش و بازپرداخت، ویرایشگران محتوا، کارشناسان پشتیبانی تیکت و مالک فروشگاه برای مدیریت نقشها و سلامت سیستم سرویس میدهد.
۰۲ — ویترین فروشگاه، نرمالسازی جستوجوی فارسی و سئو
ویترین عمومی با Next.js App Router و رندر سمت سرور برای صفحات کاتالوگ، دستهبندی، کالکشن، محصول، مجله، سوالات متداول و صفحات CMS ساخته شده است. کاربران میتوانند بر اساس دستههای سلسلهمراتبی، کالکشنهای دستی یا قاعدهمند، بازه قیمت، موجودبودن، تخفیف و ویژگیهای فنی محصول فیلتر کنند.
از آنجا که جستوجوی فارسی معمولاً ترکیبی از حروف عربی و فارسی است، یک نرمالساز اختصاصی پیش از جستوجو در محصولات، SKUها و دستهها، حروف ک/ی، ة/ه، ارقام فارسی/عربی/لاتین و نیمفاصله را یکسانسازی میکند. کالاهای ناموجود نیز امکان ثبت اطلاعرسانی موجودی و افزودن به علاقهمندیها را دارند.
بهداشت سئو بهصورت زیرساختی پیاده شده است: نقشه سایت پویا، robots، تولید تصویر OpenGraph و ریدایرکتهای ۳۱۰/۳۰۲ ذخیرهشده در پایگاه داده (با کش ۳۰ ثانیهای در پراکسی درخواست) از شکستن لینکها هنگام تغییر اسلاگ جلوگیری میکنند و اعتبارسنجی محیط تولید، HTTPS و تنظیمات ایندکس را کنترل میکند.
۰۳ — مدلسازی کاتالوگ: ویژگیها، تنوعها و ستهای ترکیبی
محصولات چرخه عمر صریح DRAFT، PUBLISHED و ARCHIVED دارند. هر محصول میتواند گزینهها و مقادیر متنوع (مانند رنگ، سایز یا آبکاری) داشته باشد که به رکوردهای ProductVariant با کد انبار (SKU) یکتا، وزن، قیمت خطخورده و قیمت صحیح BigInt به ریال نگاشت میشوند.
فراتر از تنوعهای تکی، ساختار BundleComponent امکان تعریف ستها و بستههای هدیه متصل به SKUهای پایه را میدهد و AttributeDefinition با انواع TEXT، NUMBER و SELECT مشخصات فنی ساختاریافته و فیلترپذیر را فراهم میکند.
دیدگاههای خریداران از مسیر تاییدشده (PENDING، APPROVED، REJECTED) عبور میکنند و رسانه محصولات بین فایلهای عمومی کاتالوگ و مدارک خصوصی عملیاتی تفکیک شده است.
۰۴ — دفترکل چندانباری و بهای تمامشده میانگین موزون
موجودی هرگز با افزایش یا کاهش ساده شمارنده تغییر نمیکند. شاپکور مانده هر تنوع در هر انبار (StockLocation) را با سه مقدار صریح onHand، reserved و committed نگه میدارد و همواره قاعده available = onHand - reserved - committed با مقادیر نامنفی را تضمین میکند.
هر تغییر یک رکورد تغییرناپذیر InventoryMovement (شامل رسید خرید، رزرو، آزادسازی، فروش، ارسال، بازگشت به انبار، ضایعات، انتقال و اصلاح) با کلید یکتای idempotencyKey ثبت میکند تا تکرار درخواست موجب دوبارهشماری نشود. آستانه سفارش مجدد نیز هشدارهای کمبود موجودی را در داشبورد نمایش میدهد.
تأمین کالا از طریق Supplier، PurchaseReceipt و PurchaseLine به دفترکل CostAllocation متصل است که بهای تمامشده میانگین موزون را به ریال صحیح برای ارزشگذاری انبار محاسبه میکند.
۰۵ — سبد خرید معتبر، قصد خرید و ماشین وضعیت سفارش
سبد خرید مهمان و کاربر واردشده از طریق کوکی HttpOnly سمت سرور نگهداری و هنگام ورود ادغام میشود. ورود به تسویه یک CheckoutIntent با وضعیتهای DRAFT، VERIFIED، FINALIZED و ABANDONED میسازد و برای مهمانانی که شماره آنها هنوز تایید نشده، اعتبارسنجی پیامکی OTP (VerifiedIntentGrant) را الزامی میکند.
پیش از ثبت نهایی، سرور یک پیشفاکتور معتبر (Quote) شامل قیمت لحظهای کالا، هزینه ارسال و تخفیف محاسبه میکند. نهاییسازی درون تراکنش PostgreSQL با محافظت IdempotencyRecord و ایجاد رزروهای زماندار انجام میشود تا خرید همزمان باعث فروش بیش از موجودی نشود.
پس از ثبت، ماشینهای وضعیت مجزا، چرخه مالی سفارش (OrderState) را از چرخه فیزیکی آمادهسازی و ارسال (FulfillmentState) جدا میکنند تا گذارهای غیرمجاز در مرز دامنه رد شوند.
۰۶ — پرداخت دوگانه: درگاه آنلاین و بررسی فیش کارتبهکارت
تجارت الکترونیک در ایران نیازمند پشتیبانی همزمان از درگاه پرداخت آنلاین و انتقال کارتبهکارت است. شاپکور هر دو مسیر را بهصورت یکپارچه زیر PaymentAttempt و PaymentEvent در وضعیتهای CREATED تا SUCCEEDED، FAILED، REJECTED، EXPIRED و UNKNOWN مدل میکند.
پرداخت آنلاین پشت یک آداپتور ایزوله قرار دارد (همراه با SandboxPaymentGatewayAdapter کامل برای شبیهسازی موفقیت، خطا، وضعیت نامشخص و مغایرتگیری در تست و CI) تا اتصال به درگاه واقعی بدون تغییر در منطق سبد و سفارش انجام شود.
در پرداخت کارتبهکارت، شمارهکارتهای مقصد با BankDestinationRevision نسخهبندی میشوند تا سفارشهای قدیمی شماره کارت زمان خرید را حفظ کنند. تصویر فیش در فضای خصوصی و غیرقابل کش ذخیره میشود و واحد مالی در صف بررسی فیشها بهصورت اتمیک تأیید یا رد را ثبت میکند؛ بازپرداختها نیز چرخه Refund مجزا دارند.
۰۷ — موتور تخفیفها، کدهای هدیه و کمپینهای بازاریابی
تمام محاسبات مالی با اعداد صحیح BigInt به ریال و نرخ تخفیف درصدی با واحد صدم درصد (basis points؛ هر ۱۰۰ واحد معادل ۱ درصد) همراه با سقف ریالی اختیاری انجام میشود تا خطای گردکردن یا مبلغ منفی رخ ندهد.
موتور تخفیف از کدهای کوپن و تخفیفهای خودکار سبد (مبلغ ثابت، درصدی و ارسال رایگان) با هدفگیری دسته یا محصول، شرط خرید اول، حداقل مبلغ سبد و سقف استفاده کل یا هر مشتری پشتیبانی میکند. هنگام تسویه، رزرو تخفیف اتمیک ایجاد و تنها با قطعیشدن سفارش مصرف میشود.
کمپینهای بازاریابی از طریق CampaignRevision زمانبندیشده در جایگاههای نوار بالا، پاپآپ و بنر میانی منتشر میشوند و آمار نمایش و تعامل را ثبت میکنند.
۰۸ — ارسال، نسخهبندی تعرفه و بازرسی مرجوعی
روشها و تعرفههای ارسال با ShippingMethodRevision نسخهبندی میشوند تا تغییر هزینه پست روی سفارشهای قبلی اثر نگذارد. اپراتورهای انبار از صفحه سفارش و برگه بستهبندی چاپی، مرسولهها را از انتخاب تا بستهبندی، ارسال جزئی یا کامل و تحویل پیش میبرند.
هر مرسوله (Shipment) ردیفهای مشخصی را به رویدادهای رهگیری (TrackingEvent) متصل میکند تا ارسال چندبستهای یا جزئی با ردیابی دقیق اقلام ممکن باشد.
مرجوعی پس از تحویل از چرخه صریح ReturnRequest و بازرسی ساختاریافته ReturnInspection عبور میکند تا بر اساس نتیجه بررسی، کالا به موجودی قابل فروش برگردد یا بهعنوان ضایعات ثبت شود.
۰۹ — حساب کاربری، پیگیری سفارش و سیستم تیکت پشتیبانی
مشتریان احراز هویتشده در بخش /account/* به مدیریت آدرسهای استان/شهر ایران، نشستهای فعال، اعلانها، درخواستهای مرجوعی و تاریخچه سفارشها دسترسی دارند. رضایت بازاریابی نیز بهطور صریح در CustomerConsent ثبت میشود.
خریداران مهمان میتوانند بدون ورود کامل و از طریق مسیر /track-order با توکن امن یکتا (viewTokenHash) وضعیت سفارش خود را پیگیری کرده و فیش پرداخت را بارگذاری کنند.
پشتیبانی مشتریان درون همان مدل رابطهای با تیکتهای دستهبندیشده و دارای اولویت (Ticket و TicketMessage) و یادداشتهای داخلی کارشناسان (CustomerNote) پیادهسازی شده است.
۱۰ — CMS پویا، صفحهساز خانه و تنظیمات نسخهبندیشده
بهجای کدنویسی ثابت بلوکهای صفحه اصلی، شاپکور در مسیر /admin/home-builder یک صفحهساز نسخهبندیشده (HomeLayoutRevision) با بلوکهای HomeSection ارائه میدهد که پیشنمایش و انتشار ساختاریافته دارد.
صفحات ثابت، منوهای ناوبری، سوالات متداول و مقالات مجله از مدلهای نسخهدار با وضعیت پیشنویس، منتشرشده و بایگانی استفاده میکنند. محتوای متنی بلند با ویرایشگر TipTap نوشته و پیش از نمایش سمت سرور پاکسازی (Sanitize) میشود.
تنظیمات فروشگاه مانند هویت برند، اطلاعات تماس و حسابهای بانکی نیز از همین چرخه پیشنویس و انتشار پیروی میکنند تا تغییرات قابل ممیزی و بازگشت باشند.
۱۱ — احراز هویت دو-توکنی، تایید دومرحلهای TOTP و تایید مجدد
نشستهای مشتری و کارمند فضای مجزا و چرخه دو-توکنی دارند: توکن دسترسی ۱۵ دقیقهای امضاشده با HMAC-SHA256 و بررسی timingSafeEqual، همراه با توکن تازهسازی ۲۵۶ بیتی که هش کلیددار آن در PostgreSQL ذخیره میشود. کوکیها روی HTTPS با پیشوند __Host-، HttpOnly و SameSite=Strict برای کارکنان تنظیم میشوند.
چرخش توکن تازهسازی با پنجره ۱۰ ثانیهای همزمانی تبها (prevRefreshTokenHash) کنترل میشود. هرگونه استفاده مجدد از توکن مصرفشده پس از این بازه، کل خانواده نشست (tokenFamilyId) را باطل کرده و رویداد امنیتی REFRESH_TOKEN_REUSE_DETECTED را ثبت میکند.
حسابهای کارکنان از رمزنگاری Argon2id، احراز هویت دومرحلهای TOTP با کدهای بازیابی یکبارمصرف و پنجره ۱۰ دقیقهای تایید هویت مجدد (Step-Up Re-auth) برای عملیات حساس مانند تغییر نقش یا پشتیبانگیری استفاده میکنند.
۱۲ — دسترسی مبتنی بر قابلیت (RBAC) و خط لوله امنیت درخواست
سطوح دسترسی با بیش از ۵۵ کلید قابلیت (Capability) در ۱۴ حوزه عملیاتی و ۶ نقش پیشفرض سیستمی (مالک، مدیر، ویرایشگر کاتالوگ، اپراتور ارسال، پشتیبانی و بازاریابی) تعریف شدهاند. هر درخواست محافظتشده مجوزهای مؤثر و نسخه دسترسی (authzRevision) را زنده از پایگاه داده میخواند تا لغو دسترسی بلافاصله اعمال شود.
پراکسی مرکزی (src/proxy.ts) شناسه ردیابی درخواست، هدرهای امنیتی (X-Content-Type-Options، X-Frame-Options: DENY، Referrer-Policy و Permissions-Policy)، تازهسازی بیصدای توکن و حفاظت مسیرهای /admin/* و /account/* را انجام میدهد.
مسیرهای تغییردهنده داده، حفاظت CSRF هممبدا، محدودیت نرخ ترکیبی حافظه + PostgreSQL (RateLimitBucket) و اعتبارسنجی امضای باینری فایلهای تصویری (رد فایلهای اجرایی و اسکریپتها) را اجرا میکنند.
۱۳ — الگوی Outbox تراکنشی، پردازش پسزمینه و ممیزی تغییرناپذیر
تغییرات کسبوکار هرگز پیامک، ایمیل یا وبهوک را مستقیماً درون تراکنش پایگاه داده صدا نمیزنند؛ بلکه یک رکورد OutboxEvent با کلید یکتای dedupeKey ثبت میکنند تا پردازشگر pg-boss با سازوکار تلاش مجدد و صف خطا آنها را ارسال کند.
رویدادهای حساس در جدول AuditEvent ثبت میشوند که در سطح PostgreSQL توسط تریگر پایگاه داده در برابر هرگونه UPDATE یا DELETE محافظت میشود.
ابزارهای عملیاتی شامل موتور پشتیبانگیری خودکار SQL و فایلهای رسانه در قالب tar با زمانبندی و ارسال ایمیل، همراه با مسیرهای بررسی سلامت (/api/v1/health/*) برای کانتینرها است.
۱۴ — بومیسازی فارسیمحور، تقویم جلالی و PWA
تمام رابط کاربری — از فیلترهای ویترین تا جداول پنل و برگههای بستهبندی — بهصورت بومی برای راستبهچپ فارسی، ارقام فارسی و منطقه زمانی تهران طراحی شدهاند.
ابزارهای مشترک دامنه تبدیل تاریخ جلالی، فهرست استانها و شهرهای ایران و نمایش مبلغ به تومان/ریال را در صفحات سمت سرور، ایمیلها و کامپوننتهای کلاینت یکسان نگه میدارند.
مانیفست وباپلیکیشن و صفحه اختصاصی /offline امکان نصب PWA را فراهم میکنند، در حالی که پنل مدیریت، تسویه حساب و فیشهای خصوصی بهصورت صریح نیازمند اتصال آنلاین باقی میمانند.
۱۵ — آزمون چندلایه، قرارداد نقاط ورود و تحویل CI/CD
مخزن دارای آزمونهای خودکار در چهار لایه با Vitest و Playwright است: ۳۴۲ آزمون واحد برای محاسبات مالی، ماشینهای وضعیت، نرمالساز و امنیت؛ ۱۱۱ آزمون یکپارچگی روی PostgreSQL 18 واقعی؛ آزمونهای قرارداد API و ۲۳ سناریوی مرورگر در محیط fa-IR.
بررسیهای استاتیک اختصاصی تضمین میکنند که همه مسیرهای API و نقاط ورود سرور دارای گارد احراز هویت/CSRF صریح باشند (check:entrypoints) و مستندات معماری با کد همگام بمانند (check:docs).
خط لوله GitHub Actions در هر پوش روی PostgreSQL 18، بررسی تایپ، لینت، آزمونهای واحد، یکپارچگی، ساخت و Playwright را اجرا میکند و روی شاخه main تصویر Docker غیرریشه Node 24 را ساخته، مهاجرتهای Prisma را اعمال و سلامت سرویس را بررسی میکند.
۱۶ — دستاورد شاپکور و مرزهای توسعه آینده
شاپکور مالکیت کامل یک سیستم تجارت الکترونیک سازمانی را نشان میدهد: از طراحی طرحواره ۱٬۸۹۶ خطی PostgreSQL و ماشینهای وضعیت انبار و پرداخت تا RBAC دقیق، چرخش دو-توکنی، CMS پویا و تحویل خودکار CI/CD.
کدبیس بهگونهای معماری شده که هستهای قابل استفاده مجدد برای فروشگاههای دیگر باشد: اتصال به درگاه پرداخت و پنل پیامک واقعی تنها نیازمند پیادهسازی آداپتورهای ارائهدهنده است، بدون آنکه منطق تسویه، رزرو یا دفترکل مالی تغییر کند.
مرزهای فعلی نیز بهصورت شفاف مشخص شدهاند: مدل کنونی برای استقرار تکفروشگاهی به ازای هر نمونه طراحی شده و تمام تصاویر و دادههای این گزارش از محیط محلی و دادههای آزمایشی بررسیشده تهیه شدهاند، نه ادعای آمار ترافیک واقعی.
نگاهی نزدیکتر
ثبتشده در ۲۶ آبان ۱۴۰۵
صفحه اصلی فروشگاه 1 / 12
دادههای ساختگی نمایشیتصاویر ویترین فروشگاه و پنل مدیریت از نصب مرجع رد اکسسوریِ شاپکور در محیط محلی با دادههای نمایشی تهیه شدهاند و هیچ اطلاعات واقعی مشتری، کارمند یا پرداخت ندارند.
با مسئله مشابهی روبهرو هستید؟
ایده یا محصول فعلیتان را معرفی کنید تا درباره کاری که نیاز دارید صحبت کنیم.