Imported from masterUNG/shoponlinemasterung (AGENTS.md). Install upstream with npx skills add masterUNG/shoponlinemasterung. Copyright stays with the author.

AGENTS.md

คู่มือสำหรับ agent และผู้พัฒนาที่แก้ไข repository นี้ ให้ยึดโค้ดและ configuration ใน repository เป็น source of truth หากเอกสารขัดกับ implementation ให้ตรวจสอบโค้ด อัปเดต implementation/เอกสารให้สอดคล้องกัน และระบุผลกระทบที่พบ

Project overview

แอป Flutter ร้านค้าออนไลน์ชื่อ Ung Shop
Dart SDK: ^3.11.4
State management, dependency injection และ routing: GetX
Backend: Firebase Authentication และ Cloud Firestore
Customer app ใช้ initial route /login บน Android, iOS, macOS และ Windows
Web ใช้ initial route /login-admin-web และเป็น Admin Web
Linux runner มีใน repository แต่ firebase_options.dart ยังไม่รองรับ Linux
Firebase project ปัจจุบัน: shopinglinemasterung
App version ที่ตรวจล่าสุด: 1.0.13+13 (23 สิงหาคม 2026)
Version/build number ให้อ่านและแก้ที่ pubspec.yaml เป็นหลัก; Android, iOS และ macOS รับค่า version จาก Flutter build variables

Repository map

lib/
├── app/routes/                 # GetX route names, pages และ bindings
├── core/                       # สี พิกัดร้าน ค่าคงที่ และ helper UI กลาง
├── model/                      # Firestore/domain models
├── services/                   # Admin authorization และ reviewer mode
├── modules/
│   ├── login/                  # Customer login/register
│   ├── main_home/              # Customer bottom navigation
│   ├── mall/                   # Product feed/detail และ add-to-cart
│   ├── cart/                   # Cart, fulfillment และ order transaction
│   ├── order/                  # Customer order history/payment slip
│   ├── profile/                # Profile, phone, location, account deletion
│   ├── login_admin_web/        # Admin authentication
│   └── main_home_web/          # Dashboard/products/stock/orders
├── firebase_options.dart       # Generated by FlutterFire CLI
└── main.dart                   # Firebase initialization และ platform entry route

ไฟล์ระดับ root ที่สำคัญ:

pubspec.yaml: dependencies, assets และ app version
firestore.rules: authorization และ validation ของ Firestore
firebase.json: FlutterFire apps, Hosting และ Firestore Rules deployment
test/widget_test.dart: model และ pure business-logic tests ที่มีอยู่
resource/: privacy policy และ support HTML
images/: logo, app icon และ PromptPay QR

Architecture and conventions

แต่ละ GetX module แบ่ง bindings/, controllers/ และ views/
ลงทะเบียน controller/service ผ่าน Binding; อย่า Get.put ซ้ำใน view
ReviewerModeService เป็น permanent GetX service และเก็บ demo cart ใน memory
Controller ที่ subscribe Firestore ต้องเก็บ StreamSubscription และ cancel ใน onClose
UI ใช้ Material 3 และสีจาก AppConstant; ใช้ theme ก่อน hardcode style ใหม่
ข้อความ UI ปัจจุบันเป็นภาษาไทยเป็นหลัก คงรูปแบบภาษาของหน้าที่แก้
Error Snackbar ให้ใช้ AppSnackbar.error(...) หรือ AppSnackbar.errorSnackBar(...) เพื่อให้พื้นแดง ตัวอักษรขาว และแสดง 10 วินาที
Snackbar ข้อความสำเร็จไม่ต้องใช้ AppSnackbar.error เพื่อไม่ให้แสดงเป็นสีแดง
ใช้ const widget/constructor เมื่อทำได้ และทำตาม flutter_lints
อย่า refactor ไฟล์ขนาดใหญ่ เช่น main_home_web/widgets/main_home_web_sections.dart นอกขอบเขตงาน

สถานะ Admin Web UI ปัจจุบัน:

Dashboard ผูก action ของเมนูลัดแล้ว: เพิ่มสินค้าเปิด dialog ส่วนแก้ไขราคาและ ปรับสต๊อกจะเปลี่ยนไป section ที่เกี่ยวข้อง
ปุ่มดูสินค้าทั้งหมด จัดการสินค้า และดูออเดอร์ทั้งหมดบน Dashboard จะเปลี่ยนไป section Products หรือ Orders
หน้า Products, Stock และ Orders ยังมีปุ่ม Export/จัดการสินค้า/เติมสต๊อก/ ดูทั้งหมดบางตำแหน่งที่ยังไม่ได้ผูก action ให้ตรวจทีละหน้าก่อนแก้
ช่องค้นหาบน Admin Web มี search state และกรองสินค้า/ออเดอร์จริงแล้ว

Routing and platform behavior

Route names อยู่ใน lib/app/routes/app_routes.dart
Route-to-view/binding mapping อยู่ใน lib/app/routes/app_pages.dart
lib/main.dart เลือก Web เป็น Admin และ non-Web เป็น Customer ด้วย kIsWeb
หากเพิ่ม route ให้เพิ่มทั้ง route constant, GetPage และ binding ที่ต้องใช้
ห้ามสมมติว่า Linux รันได้จนกว่าจะ configure FlutterFire สำหรับ Linux

Firestore contract

Collections หลัก:

users/{uid}: customer/admin profile
users/{uid}/cart/{productId}: cart item snapshot
product/{productId}: product catalog and stock
orders/{orderId}: order, fulfillment and payment audit data

เมื่อเพิ่ม/ลบ/เปลี่ยน field:

อัปเดต model/parser/serializer และจุดเขียนข้อมูลทั้งหมด
รักษา backward compatibility สำหรับ document เก่าโดยมี default ที่เหมาะสม
อัปเดต firestore.rules โดยเฉพาะ keys().hasOnly(...) และ affectedKeys().hasOnly(...)
อัปเดตตัวอย่าง schema ใน README.md
เพิ่มหรือปรับ test สำหรับ mapping/validation ที่เป็น pure logic

ค่าที่เป็น contract และไม่ควรเปลี่ยนโดยไม่ตรวจ flow ทั้งระบบ:

Order status: pending, accepted, preparing, ready, completed, cancelled
Payment method: promptpay, cash
Payment status: unpaid, waiting_verify, paid, rejected
Fulfillment type: pickup, delivery
User role: customer, admin

Order creation, stock decrement, order cancellation/stock restore และ payment review ใช้ Firestore transactions หรือ restricted updates อยู่แล้ว ให้คง atomicity และ audit fields เช่น paidAt, stockRestoredAt, cashCollectedAt ไว้

ข้อจำกัดด้าน security ที่ต้องคำนึง:

ลูกค้าที่ sign in สามารถลด field product.stock ตาม Rules เพื่อรองรับ client order transaction
Logic สำคัญยังอยู่ client-side ไม่ใช่ Cloud Functions
รูป, avatar และ payment slip ยังเก็บ Base64 ใน Firestore
สิทธิ์ลบสินค้าใช้ users/{uid}.permissions.canDeleteProducts == true ทั้งใน AdminRoleService และ firestore.rules

Product and image handling

Product รองรับรูปหลักและ gallery สูงสุด 4 รูปใน Admin UI
Base64 อาจมี data URI prefix; decoder ต้องรองรับทั้งแบบมีและไม่มี prefix
อย่าเพิ่ม binary หรือ secret ใหม่เข้า repository โดยไม่จำเป็น
ถ้าย้ายรูปไป Firebase Storage ต้องออกแบบ migration/backward compatibility สำหรับ Base64 เดิม

Local setup

flutter pub get
flutter run
flutter run -d chrome

flutter run บน non-Web เปิด Customer app
flutter run -d chrome เปิด Admin Web
Firebase Authentication ต้องเปิด Email/Password
Android ใช้ compile/target SDK 36, min SDK 24 และ Java 17
Android release signing อ่าน android/key.properties; ไฟล์นี้เป็น local secret และต้องไม่ commit

รูปแบบ android/key.properties:

storePassword=...
keyPassword=...
keyAlias=...
storeFile=/absolute/path/to/upload-keystore.jks

Validation before handoff

รันอย่างน้อย:

dart format --output=none --set-exit-if-changed lib test
flutter analyze
flutter test

เลือกตรวจเพิ่มตามงาน:

flutter build web
flutter build apk

งานเอกสารอย่างเดียวไม่จำเป็นต้อง build ทุก platform แต่ต้องตรวจคำสั่ง/เลขเวอร์ชัน กับ configuration จริง
งาน Firestore Rules ควรตรวจ Rules และ flow ที่เกี่ยวข้อง; repository ยังไม่มี emulator Rules tests
หาก test/analyze fail จากปัญหาที่มีอยู่เดิม ให้ระบุ command และ error ที่ชัดเจน ห้ามรายงานว่าผ่าน

Generated and vendor files

อย่าแก้ด้วยมือหากไม่จำเป็น:

lib/firebase_options.dart — regenerate ด้วย FlutterFire CLI
android/app/google-services.json
ios/Runner/GoogleService-Info.plist
macos/Runner/GoogleService-Info.plist
**/GeneratedPluginRegistrant.*
**/generated_plugin_registrant.*
**/generated_plugins.cmake
ios/Pods/, macos/Pods/ และ Pod-generated files
.dart_tool/, build/

หาก dependencies เปลี่ยน ให้ commit lockfile ที่เกี่ยวข้องซึ่ง tool สร้างขึ้น (pubspec.lock, Podfile.lock) และอย่าแก้ checksum เอง

Documentation responsibilities

อัปเดต README.md เมื่อมีการเปลี่ยน:

feature/status/known limitation
dependency, SDK, supported platform หรือ setup
Firestore schema, role, status transition หรือ security rule
version/release/deploy command
shop-specific constant เช่น location, delivery radius, QR หรือ admin email

README เป็นเอกสารสำหรับผู้พัฒนาและเจ้าของร้าน ส่วน AGENTS.md เป็นข้อกำหนดสำหรับ การแก้โค้ด จึงหลีกเลี่ยงการคัดลอกรายละเอียด feature ทุกอย่างซ้ำกัน

Git hygiene

ตรวจ git status ก่อนและหลังแก้ไข
รักษาการเปลี่ยนแปลงเดิมของผู้ใช้และอย่าแก้ไฟล์นอก scope
ห้าม commit secret เช่น android/key.properties, keystore หรือ credential
อย่าใช้ destructive Git commands เพื่อแก้ปัญหา worktree
commit ควรมี scope เดียวและข้อความอธิบายผลลัพธ์

shoponlinemasterung

About