tehran_taj/docs/parity/_inv-tgt-api.md

Inventory — apps/api (target backend)

Evidence-based inventory. All path:line citations are relative to apps/api/. Read-only audit; no source file was modified.

---

1. Stack & versions

Source: package.json.

Item	Value	Cite
Package name / version	api @ 0.0.1, private	package.json:2-4
NestJS core	@nestjs/core ^10.4.0	package.json:27
NestJS common	@nestjs/common ^10.4.0	package.json:26
NestJS platform	@nestjs/platform-express ^10.4.0	package.json:30
NestJS JWT	@nestjs/jwt ^12.0.1	package.json:28
NestJS Passport	@nestjs/passport ^10.0.3	package.json:29
Prisma client	@prisma/client ^5.19.0	package.json:31
Prisma CLI (dev)	prisma ^5.19.0	package.json:47
bcryptjs	^3.0.3	package.json:32
class-transformer	^0.5.1	package.json:33
class-validator	^0.14.1	package.json:34
passport / passport-jwt	^0.7.0 / ^4.0.1	package.json:35-36
rxjs	^7.8.1	package.json:38
Workspace dep	@gold-bank/shared-types (workspace:*)	package.json:25
TypeScript	^5.5.0	package.json:50
esbuild (release bundler)	^0.25.0	package.json:46
ts-node	^10.9.2	package.json:49

NOT present (relevant negatives): no @nestjs/config, no @nestjs/schedule, no @nestjs/websockets/socket.io, no @nestjs/swagger, no @nestjs/throttler, no HTTP client (axios), no SMS/payment SDK, no multer types (multer ships inside platform-express; a local interface is declared instead — admin-uploads.controller.ts:21-26).

Scripts: dev = nest start --watch; build:release = prisma generate → clean-dist → nest build → bundle-release (package.json:7-9). Prisma seed command: ts-node --transpile-only prisma/seed.ts (package.json:19-21).

---

2. Bootstrap

2.1 src/main.ts

Concern	Value	Cite
Pre-boot hook	await prepareDatabase() — runs SQL migrations + one-time seed BEFORE Nest is created	main.ts:19
App type	NestExpressApplication	main.ts:21
Global prefix	api	main.ts:22
Global pipe	ValidationPipe({ whitelist: true, transform: true }) — no forbidNonWhitelisted, no transformOptions	main.ts:23
Global filter	PrismaExceptionFilter	main.ts:24
Global interceptors	NONE registered	(absent in main.ts)
CORS	app.enableCors() — defaults, i.e. origin: *, no credentials, no allowlist	main.ts:25
Static assets	useStaticAssets(UPLOAD_DIR ?? cwd/storage/uploads, { prefix: '/uploads/', index:false, dotfiles:'deny' }) — mounted OUTSIDE the api prefix	main.ts:28-36
Custom MIME	.avif → image/avif injected via setHeaders (serve-static's bundled mime predates avif)	main.ts:11-16, 32-35
Port	Number(process.env.PORT ?? 3000)	main.ts:37
Bind host	0.0.0.0 (explicit, for nginx/container reachability)	main.ts:41
EADDRINUSE	Logs guidance and process.exit(1); explicitly does NOT fall back to another port	main.ts:42-52

Global guards are NOT registered in main.ts — they are registered via APP_GUARD in AuthModule (see §9).

2.2 src/app.module.ts

@Module({ imports: [...] }), no controllers/providers of its own (app.module.ts:28-57). 24 imported modules, in declared order:

#	Module	Cite
1	PrismaModule	app.module.ts:30
2	AuthModule	app.module.ts:31
3	AdminTableModule	app.module.ts:32
4	AdminOrdersModule	app.module.ts:33
5	AdminCitiesModule	app.module.ts:34
6	AdminPreOrdersModule	app.module.ts:35
7	AdminWorkshopsModule	app.module.ts:36
8	AdminCustomersModule	app.module.ts:37
9	AdminCommentsModule	app.module.ts:38
10	AdminProductsModule	app.module.ts:39
11	AdminCategoriesModule	app.module.ts:40
12	AdminDocumentsModule	app.module.ts:41
13	AdminPromotionsModule	app.module.ts:42
14	AdminUsersModule	app.module.ts:43
15	AdminBranchesModule	app.module.ts:44
16	AdminInvoicesModule	app.module.ts:45
17	AdminMiscModule	app.module.ts:46
18	AdminUploadsModule	app.module.ts:47
19	AdminDashboardModule	app.module.ts:48
20	CatalogModule	app.module.ts:49
21	CustomersModule	app.module.ts:50
22	SalesAgentModule	app.module.ts:51
23	OrdersModule	app.module.ts:52
24	AccountingModule	app.module.ts:53
25	PricingModule	app.module.ts:54

(25 entries; PrismaModule is infrastructure, giving 24 feature/infra modules under src/modules/ + prisma.)

---

3. Modules (every module under src/)

Module file	Controllers	Services / Providers	Imports	Exports
src/prisma/prisma.module.ts	—	PrismaService (prisma.module.ts:6)	—	PrismaService (:7)
src/modules/auth/auth.module.ts	AuthController (:24)	AuthService, JwtStrategy, APP_GUARD→JwtAuthGuard, APP_GUARD→PermissionsGuard (:25-31)	PrismaModule, PassportModule, JwtModule.register (:12-23)	AuthService (:32)
src/modules/admin-table/admin-table.module.ts	—	TableService (:10)	—	TableService (:11)
src/modules/admin-orders/admin-orders.module.ts	AdminOrdersController (:9)	AdminOrdersService (:10)	PrismaModule, OrdersModule (:8)	—
src/modules/admin-cities/admin-cities.module.ts	AdminCitiesController (:7)	— (uses PrismaService directly in controller, admin-cities.controller.ts:13)	PrismaModule (:6)	—
src/modules/admin-preorders/admin-preorders.module.ts	AdminPreOrdersController (:8)	AdminPreOrdersService (:9)	PrismaModule (:7)	—
src/modules/admin-workshops/admin-workshops.module.ts	AdminWorkshopsController (:8)	— (reuses AdminBranchesService)	PrismaModule, AdminBranchesModule (:7)	—
src/modules/admin-customers/admin-customers.module.ts	AdminCustomersController (:8)	AdminCustomersService (:9)	PrismaModule (:7)	AdminCustomersService (:10)
src/modules/admin-comments/admin-comments.module.ts	AdminCommentsController (:8)	AdminCommentsService (:9)	PrismaModule (:7)	—
src/modules/admin-products/admin-products.module.ts	AdminProductsController (:8)	AdminProductsService (:9)	PrismaModule (:7)	—
src/modules/admin-categories/admin-categories.module.ts	AdminCategoriesController (:8)	AdminCategoriesService (:9)	PrismaModule (:7)	—
src/modules/admin-documents/admin-documents.module.ts	AdminDocumentsController (:9)	AdminDocumentsService (:10)	PrismaModule, AccountingModule (:8)	—
src/modules/admin-promotions/admin-promotions.module.ts	AdminPromotionsController (:8)	AdminPromotionsService (:9)	PrismaModule (:7)	—
src/modules/admin-users/admin-users.module.ts	AdminUsersController (:8)	AdminUsersService (:9)	PrismaModule (:7)	—
src/modules/admin-branches/admin-branches.module.ts	AdminBranchesController (:8)	AdminBranchesService (:9)	PrismaModule (:7)	AdminBranchesService (:12)
src/modules/admin-invoices/admin-invoices.module.ts	AdminInvoicesController (:8)	AdminInvoicesService (:9)	PrismaModule (:7)	—
src/modules/admin-misc/admin-misc.module.ts	AdminMiscController, PublicSliderController (:9)	AdminMiscService (:10)	PrismaModule (:8)	—
src/modules/admin-uploads/admin-uploads.module.ts	AdminUploadsController, PublicUploadsController (:9)	AdminUploadsService (:10)	PrismaModule (:8)	AdminUploadsService (:11)
src/modules/admin-dashboard/admin-dashboard.module.ts	AdminDashboardController (:8)	AdminDashboardService (:9)	PrismaModule (:7)	—
src/modules/catalog/catalog.module.ts	CatalogController (:6)	CatalogService (:7)	—	CatalogService (:8)
src/modules/customers/customers.module.ts	CustomersController (:6)	CustomersService (:7)	—	CustomersService (:8)
src/modules/sales-agent/sales-agent.module.ts	SalesAgentController (:6)	SalesAgentService (:7)	—	SalesAgentService (:8)
src/modules/orders/orders.module.ts	OrdersController (:9)	OrdersService (:10)	CatalogModule, AccountingModule (:8)	OrdersService (:11)
src/modules/accounting/accounting.module.ts	AccountingController (:6)	LedgerService (:7)	—	LedgerService (:8)
src/modules/pricing/pricing.module.ts	PricingController (:6)	PricingService (:7)	—	PricingService (:8)

Controllers: 25. Services: 22 (+ TableService, PrismaService).

---

4. Endpoints (exhaustive)

Global prefix api (main.ts:22) is included in every path below. @Public() = JwtAuthGuard bypassed (guards.ts:15). No @RequirePermission = authenticated but no rid check.

4.1 AuthController — @Controller('admin/auth') (auth.controller.ts:15)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/auth/login	login (auth.controller.ts:22)	@Public(), @HttpCode(200) (:19,21)	LoginDto (:22)
GET	/api/admin/auth/me	me (auth.controller.ts:28)	auth required; @CurrentAdmin() (:28)	—

4.2 AdminOrdersController — @Controller('admin/orders') (admin-orders.controller.ts:16)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/orders/list	list (:24)	@HttpCode(200), @RequirePermission('order.list') (:22-23), @CurrentAdmin()	TableQueryDto (:24)
POST	/api/admin/orders/wholesale/list	listWholesale (:46)	@HttpCode(200), @RequirePermission('order.omde') (:44-45)	TableQueryDto
POST	/api/admin/orders/tamin/list	listTamin (:54)	@HttpCode(200), @RequirePermission('order.tamin') (:52-53)	TableQueryDto
POST	/api/admin/orders/delete	remove (:62)	@HttpCode(200), @RequirePermission('order.omde') (:60-61)	inline { id: string }
POST	/api/admin/orders/create	createFromAdmin (:70)	@HttpCode(200), @RequirePermission('order.create') (:68-69), @CurrentAdmin()	inline { customer_id, order_items[], sts?, note? } (:72-77)
GET	/api/admin/orders/type-options	typeOptions (:86)	@RequirePermission('order.create') (:85)	—
GET	/api/admin/orders/status-options	statusOptions (:92)	@RequirePermission('order.list') (:91)	—
POST	/api/admin/orders/status	setStatus (:100)	@HttpCode(200), @RequirePermission('order.list') (:98-99), @CurrentAdmin()	UpdateOrderStatusDto (admin-orders/update-status.dto.ts)
GET	/api/admin/orders/:id	findOne (:106)	@RequirePermission('order.list') (:105)	—

4.3 AdminCitiesController — @Controller('admin/cities') (admin-cities.controller.ts:11)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/cities/list	list (:17)	@HttpCode(200); no rid, but NOT @Public() → JWT still required (:8-10 comment claims ungated; only the rid check is skipped)	—

4.4 AdminPreOrdersController — @Controller('admin/pre-orders') (admin-preorders.controller.ts:13)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/pre-orders/list	list (:20)	@HttpCode(200), @RequirePermission('order.makeOrder') (:18-19)	TableQueryDto
GET	/api/admin/pre-orders/status-options	statusOptions (:26)	@RequirePermission('order.makeOrder') (:25)	—
GET	/api/admin/pre-orders/:id	findOne (:32)	@RequirePermission('order.makeOrder') (:31)	—
PUT	/api/admin/pre-orders/:id	update (:38)	@RequirePermission('order.makeOrder') (:37)	Record<string, unknown> (untyped)
DELETE	/api/admin/pre-orders/:id	remove (:44)	@RequirePermission('order.makeOrder') (:43)	—

4.5 AdminWorkshopsController — @Controller('admin/workshops') (admin-workshops.controller.ts:18)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/workshops/list	list (:24)	@HttpCode(200); no rid (:22-23)	TableQueryDto
POST	/api/admin/workshops	create (:31)	@HttpCode(200), @RequirePermission('workshop.create') (:29-30)	Record<string, unknown>
GET	/api/admin/workshops/active/:id	toggleActive (:37)	@RequirePermission('workshop.list') (:36)	—
GET	/api/admin/workshops/:id	findOne (:43)	@RequirePermission('workshop.list') (:42)	—
PUT	/api/admin/workshops/:id	update (:49)	@RequirePermission('workshop.list') (:48)	Record<string, unknown>

4.6 AdminCustomersController — @Controller('admin/customers-omde') (admin-customers.controller.ts:17)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/customers-omde/list	listAll (:28)	@HttpCode(200), @RequirePermission('persons.list.client.omde') (:26-27)	TableQueryDto
POST	/api/admin/customers-omde/banker/list	listBanker (:35)	@HttpCode(200), persons.list.client.omde (:33-34)	TableQueryDto
POST	/api/admin/customers-omde/shopkeeper/list	listShopkeeper (:42)	@HttpCode(200), persons.list.client.omde (:40-41)	TableQueryDto
POST	/api/admin/customers-omde/non-verified/list	listNonVerified (:49)	@HttpCode(200), persons.list.client.omde (:47-48)	TableQueryDto
POST	/api/admin/customers-omde/archived/list	listArchived (:56)	@HttpCode(200), persons.list.client.omde (:54-55)	TableQueryDto
POST	/api/admin/customers-omde/single/list	listSingle (:64)	@HttpCode(200), persons.list.client.single (:62-63), @CurrentAdmin() (branch scoping :65)	TableQueryDto
POST	/api/admin/customers-omde/single	createSingle (:72)	@HttpCode(200), persons.create (:70-71)	Record<string, unknown>
GET	/api/admin/customers-omde/query/reagent	queryReagents (:82)	@RequirePermission('persons.create') (:81)	—
POST	/api/admin/customers-omde/wallet/charge	chargeWallet (:90)	@HttpCode(200), @RequirePermission('wallet') (:88-89)	inline { customer_id, value }
POST	/api/admin/customers-omde/create	create (:97)	@HttpCode(200), persons.create (:95-96)	Record<string, unknown>
PUT	/api/admin/customers-omde/:id	update (:103)	persons.list.client.omde.edit (:102)	Record<string, unknown>
POST	/api/admin/customers-omde/reagent/list	listReagents (:111)	@HttpCode(200), persons.list.sellers (:109-110)	TableQueryDto
GET	/api/admin/customers-omde/reagent/:id	reagentDetail (:118)	persons.list.sellers.view (:117)	—
GET	/api/admin/customers-omde/:id/orders	customerOrders (:125)	persons.list.client.omde.view.orders (:124)	—
GET	/api/admin/customers-omde/:id/documents	customerDocuments (:132)	persons.list.client.omde.view.documents (:131)	—
GET	/api/admin/customers-omde/:id/wallet	customerWallet (:139)	@RequirePermission('wallet') (:138)	—
GET	/api/admin/customers-omde/dashboard/:id	dashboard (:145)	persons.list.client.omde.view (:144)	—
GET	/api/admin/customers-omde/archive/:id	toggleArchive (:151)	persons.list.client.omde.edit (:150)	—
POST	/api/admin/customers-omde/toggle-active	toggleActive (:158)	@HttpCode(200), persons.list.client.omde.edit (:156-157)	inline { id }
POST	/api/admin/customers-omde/toggle-sts	toggleSts (:165)	@HttpCode(200), persons.list.client.omde.edit (:163-164)	inline { id }
POST	/api/admin/customers-omde/verify	verify (:172)	@HttpCode(200), persons.list.client.omde.edit (:170-171)	inline { customer_id, sts_verify_step_one?, sts_verify_step_two? } (:174)
POST	/api/admin/customers-omde/credit	updateCredit (:182)	@HttpCode(200), persons.list.client.omde.edit (:180-181)	inline { id, gram_level?, percent? }
GET	/api/admin/customers-omde/:id	findOne (:188)	persons.list.client.omde.view (:187)	—

4.7 AdminCommentsController — @Controller('admin/comments') (admin-comments.controller.ts:15)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/comments/list	list (:22)	@HttpCode(200), @RequirePermission('comment') (:20-21)	TableQueryDto
GET	/api/admin/comments/status-options	statusOptions (:28)	comment (:27)	—
POST	/api/admin/comments/sts	changeStatus (:35)	@HttpCode(200), comment (:33-34)	inline { id: string; sts: number }
POST	/api/admin/comments	create (:42)	@HttpCode(200), comment (:40-41)	inline { product_id, customer_id, comment, reply_to? } (:43)
GET	/api/admin/comments/:id	findOne (:50)	comment (:49)	—
DELETE	/api/admin/comments/:id	remove (:56)	comment (:55)	—

4.8 AdminProductsController — @Controller('admin/products') (admin-products.controller.ts:18)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/products/list	list (:25)	@HttpCode(200), product.list (:23-24)	TableQueryDto
POST	/api/admin/products/variants/list	listVariants (:32)	@HttpCode(200), product.list (:30-31)	TableQueryDto & { product_id? }
POST	/api/admin/products/by-ids	byIds (:44)	@HttpCode(200), product.list (:42-43)	inline { products_id: string[] }
POST	/api/admin/products/variants/create	createVariant (:55)	@HttpCode(200), order.create (:53-54)	inline { product_id, title, grams }
GET	/api/admin/products/show-type-options	showTypeOptions (:61)	product.list (:60)	—
GET	/api/admin/products/brands	brands (:67)	product.list (:66)	—
POST	/api/admin/products/brands-table	brandsTable (:75)	@HttpCode(200), product.list (:73-74)	TableQueryDto
GET	/api/admin/products/collections	collections (:82)	product.list (:81)	—
POST	/api/admin/products/change-percent/count	changePercentCount (:89)	@HttpCode(200), product.percent (:87-88)	inline { brand_id?, category_id? }
POST	/api/admin/products/change-percent/apply	changePercent (:96)	@HttpCode(200), product.percent (:94-95)	inline { percent, brand_id?, category_id? }
POST	/api/admin/products/create	create (:103)	@HttpCode(200), product.create (:101-102)	Record<string, unknown>
POST	/api/admin/products/delete/:id	remove (:110)	@HttpCode(200), product.list.edit (:108-109)	—
GET	/api/admin/products/:id/variants	variantsOf (:116)	product.list (:115)	—
GET	/api/admin/products/:id	findOne (:122)	product.list (:121)	—
PUT	/api/admin/products/:id	update (:128)	product.list.edit (:127)	Record<string, unknown>

4.9 AdminCategoriesController — @Controller('admin/categories') (admin-categories.controller.ts:14)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/categories/list	list (:21)	@HttpCode(200), collection.list (:19-20)	TableQueryDto
GET	/api/admin/categories/tree	tree (:27)	collection.list (:26); @Query('type')	—
GET	/api/admin/categories/type-options	typeOptions (:33)	collection.list (:32)	—
POST	/api/admin/categories/collections/list	listCollections (:41)	@HttpCode(200), collection.list (:39-40)	TableQueryDto
POST	/api/admin/categories/collections	createCollection (:48)	@HttpCode(200), collection.create (:46-47)	inline { title, description?, is_active? }
PUT	/api/admin/categories/collections/:id	updateCollection (:53)	collection.list.edit (:52)	inline { title?, description?, is_active? }
DELETE	/api/admin/categories/collections/:id	removeCollection (:63)	collection.list.edit (:62)	—
POST	/api/admin/categories	create (:71)	@HttpCode(200), collection.create (:69-70)	Record<string, unknown>
GET	/api/admin/categories/:id	findOne (:77)	collection.list (:76)	—
PUT	/api/admin/categories/:id	update (:83)	collection.list.edit (:82)	Record<string, unknown>
DELETE	/api/admin/categories/:id	remove (:89)	collection.list.edit (:88)	—

4.10 AdminDocumentsController — @Controller('admin/documents') (admin-documents.controller.ts:17)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/documents/list	list (:24)	@HttpCode(200), document.list (:22-23)	TableQueryDto
GET	/api/admin/documents/type-options	typeOptions (:30)	document.list (:29)	—
GET	/api/admin/documents/query/customer	queryCustomers (:36)	document.create (:35)	—
POST	/api/admin/documents/wallet/list	listWallet (:43)	@HttpCode(200), wallet (:41-42)	TableQueryDto
GET	/api/admin/documents/wallet/config	getWalletConfig (:50)	config.wallet (:49)	—
POST	/api/admin/documents/wallet/config	setWalletConfig (:57)	@HttpCode(200), config.wallet (:55-56)	Record<string, unknown>
GET	/api/admin/documents/wallet/birthday/config	getBirthdayConfig (:63)	config.wallet (:62)	—
POST	/api/admin/documents/wallet/birthday/config	setBirthdayConfig (:70)	@HttpCode(200), config.wallet (:68-69)	Record<string, unknown>
POST	/api/admin/documents	create (:77)	@HttpCode(200), document.create (:75-76), @CurrentAdmin()	Record<string, unknown>
POST	/api/admin/documents/:id/confirm	toggleConfirm (:85)	@HttpCode(200), document.list.edit (:83-84), @CurrentAdmin()	—
GET	/api/admin/documents/:id	findOne (:91)	document.list (:90)	—
PUT	/api/admin/documents/:id	update (:97)	document.list.edit (:96)	Record<string, unknown>
DELETE	/api/admin/documents/:id	remove (:103)	document.list.edit (:102)	—

4.11 AdminPromotionsController — @Controller('admin/promotions') (admin-promotions.controller.ts:12)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/promotions/list	list (:19)	@HttpCode(200), offers.list (:17-18)	TableQueryDto
GET	/api/admin/promotions/scope-options	scopeOptions (:25)	offers.list (:24)	—
GET	/api/admin/promotions/usage-options	usageOptions (:31)	offers.list (:30)	—
GET	/api/admin/promotions/auto	getAutoPromotion (:37)	offers.autopromotion (:36)	—
POST	/api/admin/promotions/auto	setAutoPromotion (:44)	@HttpCode(200), offers.autopromotion (:42-43)	inline { state?, discount_percent? }
GET	/api/admin/promotions/exclusions	listExclusions (:51)	offersIgnore (:50)	—
POST	/api/admin/promotions/exclusions	createExclusion (:58)	@HttpCode(200), offersIgnore (:56-57)	inline { type: number; item_id?: string[] }
DELETE	/api/admin/promotions/exclusions/:id	removeExclusion (:64)	offersIgnore (:63)	—
POST	/api/admin/promotions	create (:72)	@HttpCode(200), offers.create (:70-71)	Record<string, unknown>
GET	/api/admin/promotions/:id	findOne (:78)	offers.list (:77)	—
PUT	/api/admin/promotions/:id	update (:84)	offers.list.edit (:83)	Record<string, unknown>
DELETE	/api/admin/promotions/:id	remove (:90)	offers.list.edit (:89)	—

4.12 AdminUsersController — @Controller('admin/users') (admin-users.controller.ts:16)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/users/list	list (:23)	@HttpCode(200), user.list (:21-22)	TableQueryDto
GET	/api/admin/users/role-options	roleOptions (:29)	user.list (:28)	—
GET	/api/admin/users/types	listUserTypes (:36)	user.list (:35)	—
POST	/api/admin/users/types	createUserType (:44)	@HttpCode(200), user.permission.create (:42-43)	inline { val?, title? }
GET	/api/admin/users/types/:ut/roles	getRoles (:51)	user.permission (:50)	—
POST	/api/admin/users/roles	setRoles (:59)	@HttpCode(200), user.permission.edit (:57-58)	inline { ut, roles: string[] }
DELETE	/api/admin/users/types/:ut/roles/:rid	revokeRole (:66)	user.permission.edit (:65)	—
GET	/api/admin/users/me	myData (:72)	auth only, no rid; @CurrentAdmin() (:71-72)	—
POST	/api/admin/users	create (:79)	@HttpCode(200), user.create (:77-78)	Record<string, unknown>
GET	/api/admin/users/:id	findOne (:85)	user.list (:84)	—
PUT	/api/admin/users/:id	update (:91)	user.list.edit (:90)	Record<string, unknown>
DELETE	/api/admin/users/:id	remove (:97)	user.list.remove (:96), @CurrentAdmin()	—

4.13 AdminBranchesController — @Controller('admin/branches') (admin-branches.controller.ts:14)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/branches/list	listBranches (:22)	@HttpCode(200), branch.list (:20-21)	TableQueryDto
GET	/api/admin/branches/user-list	userList (:28)	branch.create (:27)	—
POST	/api/admin/branches	createBranch (:35)	@HttpCode(200), branch.create (:33-34)	Record<string, unknown>
GET	/api/admin/branches/active/:id	toggleBranchActive (:41)	branch.list (:40)	—
GET	/api/admin/branches/:id	findBranch (:47)	branch.list (:46)	—
PUT	/api/admin/branches/:id	updateBranch (:53)	branch.list (:52)	Record<string, unknown>

4.14 AdminInvoicesController — @Controller('admin/invoices') (admin-invoices.controller.ts:15)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/invoices/list	list (:22)	@HttpCode(200), invoice.list (:20-21)	TableQueryDto
GET	/api/admin/invoices/branch-list	branchList (:28)	invoice.create (:27)	—
POST	/api/admin/invoices	create (:35)	@HttpCode(200), invoice.create (:33-34), @CurrentAdmin()	inline { branch_id?, products?, note? }
GET	/api/admin/invoices/:id	findOne (:44)	invoice.list (:43)	—
PUT	/api/admin/invoices/:id	update (:50)	invoice.list (:49)	inline { branch_id?, products?, note? }
DELETE	/api/admin/invoices/:id	remove (:59)	invoice.list (:58)	—

4.15 AdminMiscController — @Controller('admin/misc') (admin-misc.controller.ts:21)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/misc/cities/list	listCities (:29)	@HttpCode(200), cities.list (:27-28)	TableQueryDto
POST	/api/admin/misc/cities	createCity (:36)	@HttpCode(200), cities.create (:34-35)	inline { title?, name?, province? }
GET	/api/admin/misc/cities/percent/:id	getCityPercent (:42)	cities.list (:41)	—
GET	/api/admin/misc/cities/percent-aux/:id	getCityPercentAux (:48)	cities.list (:47)	—
PUT	/api/admin/misc/cities/:id	updateCity (:54)	cities.list.view.edit (:53)	Record<string, never>
DELETE	/api/admin/misc/cities/:id	removeCity (:60)	cities.list.remove (:59)	—
POST	/api/admin/misc/sms/list	listSms (:68)	@HttpCode(200), sms.list (:66-67)	TableQueryDto
POST	/api/admin/misc/sms	sendSms (:75)	@HttpCode(200), sms.create (:73-74), @CurrentAdmin()	inline { type?, mobile?, text? }
POST	/api/admin/misc/notify/list	listNotifications (:86)	@HttpCode(200), notify.me (:84-85)	TableQueryDto
POST	/api/admin/misc/notify	createNotification (:93)	@HttpCode(200), notify.create (:91-92), @CurrentAdmin()	inline { title?, text?, body?, type? }
POST	/api/admin/misc/notify/customer	notifyCustomer (:103)	@HttpCode(200), notify.create (:101-102), @CurrentAdmin()	inline { customer_id?, title?, text?, body? }
GET	/api/admin/misc/notify/read/:id	markRead (:112)	notify.me (:111)	—
GET	/api/admin/misc/notify/:id	findNotification (:118)	notify.me (:117)	—
POST	/api/admin/misc/newsletter/list	listNewsletter (:126)	@HttpCode(200), newsletters (:124-125)	TableQueryDto
GET	/api/admin/misc/log/customers	logCustomers (:133)	statics (:132)	—
GET	/api/admin/misc/log/customer/:id	customerLog (:139)	statics (:138)	—
GET	/api/admin/misc/dashboard-links	dashboardLinks (:146)	config.report (:145)	—
GET	/api/admin/misc/const	listConsts (:152)	config.statics (:151)	—
POST	/api/admin/misc/brands	createBrand (:159)	@HttpCode(200), config.statics.brand.create (:157-158)	inline { title }
PUT	/api/admin/misc/brands/:id	updateBrand (:165)	config.statics.brand.edit (:164)	inline { title }
DELETE	/api/admin/misc/brands/:id	removeBrand (:171)	config.statics.brand.remove (:170)	—
GET	/api/admin/misc/const/slider	getSlider (:186)	custom.config.statics.slider (:185)	—
PUT	/api/admin/misc/const/slider	setSlider (:192)	custom.config.statics.slider (:191)	Record<string, unknown>
DELETE	/api/admin/misc/const/slider	removeSlider (:198)	custom.config.statics.slider (:197)	—
GET	/api/admin/misc/const/:key	getConst (:204)	config.statics (:203); assertNotSliderKey (:205,229-233)	—
PUT	/api/admin/misc/const/:key	setConst (:211)	config.statics (:210); assertNotSliderKey	Record<string, unknown>, reads body.val fallback (:214)
DELETE	/api/admin/misc/const/:key	removeConst (:219)	config.statics (:218); assertNotSliderKey	—

4.16 PublicSliderController — @Public() @Controller('home') (public-slider.controller.ts:16-17)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/home/slider	getSlider (:22)	@Public() class-level (:16)	—

4.17 AdminUploadsController — @Controller('admin/files') (admin-uploads.controller.ts:45)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/admin/files/create	create (:52)	@HttpCode(200), @UseInterceptors(FileInterceptor('file')) (:50-51), @UploadedFile(), @Body('purpose'), @CurrentAdmin(); auth required, no rid (rationale :38-44)	multipart file + purpose (no DTO class)
GET	/api/admin/files/:id	findOne (:61)	auth only, no rid (:60)	—

4.18 PublicUploadsController — @Public() @Controller('uploads') (public-uploads.controller.ts:14-15)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/uploads/:filename	stream (:19)	@Public() class-level (:14); @Header('Cache-Control','public, max-age=86400') (:18)	—

4.19 AdminDashboardController — @Controller('admin/dashboard') (admin-dashboard.controller.ts:15)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/admin/dashboard/overview	overview (:21)	dashboard.view (:20)	—
GET	/api/admin/dashboard/omde	omde (:28) — deprecated alias	dashboard.view (:27)	—
GET	/api/admin/dashboard/tak	tak (:34) — deprecated alias	dashboard.view (:33)	—
GET	/api/admin/dashboard/report/order-item	orderItemReport (:42)	report.order.item (:41); @Query('start_date'/'end_date')	—
GET	/api/admin/dashboard/report/product	productReport (:49)	report.product (:48); @Query(...)	—

4.20 CatalogController — @Public() @Controller('catalog/products') (catalog.controller.ts:5-6)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/catalog/products	list (:11)	@Public() class-level (:5)	—

4.21 CustomersController — @Public() @Controller('customers') (customers.controller.ts:5-6)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/customers	list (:11)	@Public() class-level	—
GET	/api/customers/:id	get (:16)	@Public()	—
GET	/api/customers/:id/orders	getOrders (:21)	@Public()	—
GET	/api/customers/:id/ledger-entries	getLedgerEntries (:26)	@Public()	—

4.22 SalesAgentController — @Controller('sales-agent') (sales-agent.controller.ts:21)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/sales-agent/me	me (:26)	auth required, no rid; identity-scoped in service (role==='SALES_EXPERT', sales-agent.service.ts:36-40)	—
GET	/api/sales-agent/my-customers	myCustomers (:31)	auth, no rid; @Query('search')	—
POST	/api/sales-agent/verify-acting-as	verifyActingAs (:37)	@HttpCode(200) (:36); auth, no rid	inline { customerId }

4.23 OrdersController — @Public() @Controller('orders') (orders.controller.ts:7-8)

METHOD	Full path	Handler	Guards/decorators	DTO
POST	/api/orders	create (:13)	@Public() class-level	CreateOrderDto
GET	/api/orders/:id	get (:18)	@Public()	—
PATCH	/api/orders/:id/status	updateStatus (:23)	@Public()	UpdateOrderStatusDto (orders/dto)

4.24 AccountingController — @Public() @Controller('accounting') (accounting.controller.ts:7-8)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/accounting/customers/:customerId/balance	getBalance (:13)	@Public() class-level	—
POST	/api/accounting/customers/:customerId/reconcile	reconcile (:18)	@Public()	—
POST	/api/accounting/repayments/gold	postGoldRepayment (:23)	@Public()	PostGoldRepaymentDto
POST	/api/accounting/repayments/rial	postRialRepayment (:28)	@Public()	PostRialRepaymentDto
POST	/api/accounting/entries/:entryId/confirm	confirmEntry (:33)	@Public()	—

4.25 PricingController — @Public() @Controller('pricing') (pricing.controller.ts:5-6)

METHOD	Full path	Handler	Guards/decorators	DTO
GET	/api/pricing/latest	getLatest (:11)	@Public(); @Query('karatPerMille'), defaults 750 (:12)	—

4.26 Endpoint totals

Controller	Routes
AuthController	2
AdminOrdersController	9
AdminCitiesController	1
AdminPreOrdersController	5
AdminWorkshopsController	5
AdminCustomersController	23
AdminCommentsController	6
AdminProductsController	15
AdminCategoriesController	11
AdminDocumentsController	13
AdminPromotionsController	12
AdminUsersController	12
AdminBranchesController	6
AdminInvoicesController	6
AdminMiscController	27
PublicSliderController	1
AdminUploadsController	2
PublicUploadsController	1
AdminDashboardController	5
CatalogController	1
CustomersController	4
SalesAgentController	3
OrdersController	3
AccountingController	5
PricingController	1
TOTAL	179

Unauthenticated (@Public()) surface — 15 routes: all of AccountingController (5), OrdersController (3), CustomersController (4), CatalogController (1), PricingController (1), PublicSliderController (1), PublicUploadsController (1). Note /api/accounting/* writes to the ledger and /api/orders creates gold-debt-bearing orders while being fully public (accounting.controller.ts:7, orders.controller.ts:7).

---

5. DTOs (every class, fields, class-validator rules)

Only 6 DTO files / 8 DTO classes exist. Most admin routes take untyped Record<string, unknown> or inline object literals (no validation beyond the global whitelist pipe, which strips nothing on a plain Record type).

src/modules/auth/dto/login.dto.ts — LoginDto

Field	Type	Validators	Cite
phone	string	@IsString(), @IsNotEmpty()	:11-13
password	string	@IsString(), @IsNotEmpty()	:15-17

src/modules/accounting/dto/post-gold-repayment.dto.ts — PostGoldRepaymentDto

Field	Type	Validators	Cite
customerId	string	@IsString()	:4-5
instrument	'MELTED_GOLD'|'TRANSFER'|'CHEQUE'|'CASH'	@IsIn([...])	:7-8
rawValue	number	@IsNumber(), @IsPositive()	:10-12
karatPerMille?	number	@IsOptional(), @IsNumber()	:14-16
pricePerGramRial?	number	@IsOptional(), @IsNumber(), @IsPositive()	:18-21
note?	string	@IsOptional(), @IsString()	:23-25

src/modules/accounting/dto/post-rial-repayment.dto.ts — PostRialRepaymentDto

Field	Type	Validators	Cite
customerId	string	@IsString()	:4-5
amount	number	@IsNumber(), @IsPositive()	:7-9
note?	string	@IsOptional(), @IsString()	:11-13

src/modules/orders/dto/create-order.dto.ts — CreateOrderItemInputDto

Field	Type	Validators	Cite
productVariantId	string	@IsString()	:6-7
quantity	number	@IsInt(), @Min(1)	:9-11
wagePercent	number	@IsNumber() (no min/max — negative or >100 accepted)	:14-15
discountPercent?	number	@IsOptional(), @IsNumber()	:17-19
flatRialCharge?	number	@IsOptional(), @IsNumber()	:22-24

src/modules/orders/dto/create-order.dto.ts — CreateOrderDto

Field	Type	Validators	Cite
customerId	string	@IsString()	:28-29
branchId?	string	@IsOptional(), @IsString()	:31-33
channel?	OrderChannel	@IsOptional(), @IsEnum(OrderChannel); defaults RETAIL in service	:40-42
items	CreateOrderItemInputDto[]	@IsArray(), @ArrayMinSize(1), @ValidateNested({each:true}), @Type(()=>CreateOrderItemInputDto)	:44-48

src/modules/orders/dto/update-order-status.dto.ts — UpdateOrderStatusDto

Field	Type	Validators	Cite
status	OrderStatus	@IsEnum(OrderStatus)	:5-6
note?	string	@IsOptional(), @IsString()	:8-10
actorAdminUserId?	string	@IsOptional(), @IsString() — client-supplied actor id on a @Public() route	:12-14

src/modules/admin-orders/update-status.dto.ts — UpdateOrderStatusDto (distinct class, same name)

Field	Type	Validators	Cite
orderId	string	@IsString()	:12-13
status	OrderStatus	@IsEnum(OrderStatus)	:15-16
note?	string	@IsOptional(), @IsString()	:18-20
remove?	boolean	@IsOptional(), @IsBoolean() — true = delete that status event	:23-25

src/modules/admin-table/table-query.dto.ts — TableFilterDto

Field	Type	Validators	Cite
id?	number|string	@IsOptional() (accepted, ignored)	:22-23
field?	string	@IsOptional(), @IsString()	:25-27
op?	string	@IsOptional(), @IsIn(['=','!=','>','>=','<','<=','like','in','between','null','notnull'])	:32-34
value?	unknown	@IsOptional()	:36-37
value2?	unknown	@IsOptional() (used by between)	:39-40

src/modules/admin-table/table-query.dto.ts — TableQueryDto

Field	Type	Validators	Cite
search?	string	@IsOptional(), @IsString()	:51-53
filters?	TableFilterDto[]	@IsOptional(), @IsArray(), @ValidateNested({each:true}), @Type(()=>TableFilterDto)	:55-59
page?	number	@IsOptional(), @Type(()=>Number), @IsInt(), @Min(1)	:61-65
limit?	number	@IsOptional(), @Type(()=>Number), @IsInt(), @Min(1), @Max(500)	:67-72
order?	string	@IsOptional(), @IsString() — '+field' asc / '-field' desc	:75-77
select?	string[]	@IsOptional(), @IsArray()	:80-82
titles?	Record<string,string>	@IsOptional()	:85-86
report_title?	string	@IsOptional(), @IsString()	:88-90
op?	'excel'|'json'|'print'	@IsOptional(), @IsIn([...]) — always rejected by assertNotExport	:97-99
total?	number	@IsOptional() (echoed back)	:102-103

---

6. Prisma schema (prisma/schema.prisma, 911 lines)

Generator: prisma-client-js, binaryTargets = ["native","debian-openssl-3.0.x"] (schema.prisma:6-10). Datasource: postgresql, url from env("DATABASE_URL") (schema.prisma:12-15). Header note: "All money/weight fields use Decimal, never Float, to avoid rounding drift in debt math" (schema.prisma:4).

6.1 Enums (14)

Enum	Values	Cite
AdminRole	SUPER_ADMIN, SYSTEM_APPROVER, SALES_EXPERT, WORKSHOP_SUPERVISOR, ACCOUNTANT	:21-27
CustomerKind	SALES_AGENT (legacy-only), APP_SHOPKEEPER, WALK_IN_SHOPKEEPER, BANKER, WORKSHOP_SUPERVISOR, RETAIL	:45-52
VerificationStep	UNVERIFIED, STEP_ONE_SUBMITTED, STEP_TWO_SUBMITTED, VERIFIED	:54-59
OrderChannel	RETAIL, WHOLESALE	:64-67
OrderStatus	SUSPENDED, PLACED, ADMIN_APPROVED, SOURCING, PREPARING, DELIVERED_TO_AGENT, DELIVERED_TO_CUSTOMER, CANCELLED	:69-78
PreOrderStatus	PLACED, ADMIN_APPROVED, WORKSHOP_APPROVED, READY_TO_SHIP, DELIVERED, CANCELLED	:80-87
LedgerCurrency	GOLD_GRAM, RIAL	:89-92
LedgerDirection	DEBIT (increases owed), CREDIT (decreases owed)	:94-97
LedgerSourceType	ORDER_STOCK, ORDER_PRE_ORDER, REPAYMENT_MELTED_GOLD, REPAYMENT_TRANSFER, REPAYMENT_CHEQUE, REPAYMENT_CASH, WALLET_BONUS, ADJUSTMENT	:99-108
ProductImageRole	FEATURED, FEATURED_MOBILE, GALLERY, GALLERY_MOBILE	:367-372
CommentStatus	PENDING, APPROVED, REJECTED	:655-659
PromotionScope	PRODUCT, CATEGORY, CUSTOMER, BRAND	:704-709
PromotionUsage	ONCE, UNTIL_END_DATE	:712-715
MessageAudience	SINGLE_NUMBER, MULTIPLE_NUMBERS, ALL_CUSTOMERS, WHOLESALE_CUSTOMERS, RETAIL_CUSTOMERS, SALES_AGENTS	:805-812

6.2 Models (29)

City (:114-126)

Field	Type	Default / Attrs
id	String	@id @default(cuid())
name	String	—
province	String?	—
percent	Decimal?	@db.Decimal(6,3) — per-city wage surcharge (:120)
percentAux	Decimal?	@db.Decimal(6,3) (:121)
customers/addresses/branches/preOrders	relations	Customer[], CustomerAddress[], Branch[], PreOrder[] (:122-125)

AdminUser (:128-170)

Field	Type	Default / Attrs
id	String	@id @default(cuid())
fullName	String	—
mobile	String	@unique (:131)
passwordHash	String	—
role	AdminRole	—
userTypeId	Int?	FK → UserType (:137-138)
branchId	String?	FK → Branch (:139-140)
wagePercent	Decimal?	@db.Decimal(6,3) — commission on referred orders (:141)
isActive	Boolean	@default(true) (:142)
createdAt	DateTime	@default(now()) (:143)
avatarFileId	String?	FK → UploadedFile (relation AdminUserAvatar) (:150-151)
address, storeName, pasazhName, memberCode	String?	legacy sales-agent fields (:152-155)
Relations	referredCustomers (ReferralAgent), supervisedWorkshops, branchAllocations, postedLedgerEntries, orderStatusEvents, preOrderStatusEvents, sentSmsMessages, sentNotifications, uploadedFiles	:157-165
Indexes	@@index([role]), @@index([userTypeId]), @@index([avatarFileId])	:167-169

Customer (:172-238)

Field	Type	Default / Attrs
id	String	@id @default(cuid())
fullName	String	—
mobile	String	@unique (:175)
nationalCode	String	@unique (:176)
passwordHash	String	—
cityId / city	String? / City?	(:178-179)
kind	CustomerKind	@default(APP_SHOPKEEPER) (:183)
phone, address, storeName, pasazhName, zone, memberCode	String?	(:187-193)
referredByAgentId	String?	FK → AdminUser (ReferralAgent) (:195-196)
goldCreditLimitGrams	Decimal	@default(0) @db.Decimal(14,4) — legacy gram_level (:200)
goldDebtGrams	Decimal	@default(0) @db.Decimal(14,4) — legacy remain (cache) (:201)
fiatDebtRial	Decimal	@default(0) @db.Decimal(20,2) — legacy rial_remain (cache) (:202)
verificationStep	VerificationStep	@default(UNVERIFIED) (:204)
nationalIdImageUrl, businessLicenseUrl, shopImageUrl	String?	KYC docs (:205-207)
avatarFileId	String?	FK → UploadedFile (CustomerAvatar) (:212-213)
canPlaceOrders	Boolean	@default(true) — legacy sts (:219)
isActive	Boolean	@default(true) — legacy active (:221)
isArchived	Boolean	@default(false) (:223)
createdAt / updatedAt	DateTime	@default(now()) / @updatedAt (:224-225)
Relations	addresses, orders, preOrders, ledgerEntries, walletBonuses, comments, promotions, notifications, activityLogs	:227-235
Index	@@index([referredByAgentId])	:237

CustomerAddress (:240-248)

id (cuid PK), customerId→Customer, cityId?→City, addressLine String, isDefault Boolean @default(false).

Branch (:250-263)

id (cuid PK), name, address?, phone?, isActive @default(true) (:257), cityId?→City, relations adminUsers/orders/allocations.

Workshop (:265-276)

id (cuid PK), name, address?, phone?, supervisorId?→AdminUser (WorkshopSupervisor), isActive @default(true), preOrders.

Category (:282-299)

id (cuid PK), title, type Int @default(1) (1=site,2=mobile), imageUrl?, iconUrl?, metaTag?, description?, parentId?→self (CategoryTree), children, products, promotions.

Brand (:301-306)

id (cuid PK), title, products, promotions.

Collection (:310-316)

id (cuid PK), title, description?, isActive @default(true), products (CollectionProduct[]).

CollectionProduct (:318-325)

collectionId→Collection, productId→Product; @@id([collectionId, productId]) (:324).

Product (:327-348)

id (cuid PK), title, description?, categoryId?→Category, brandId?→Brand, productCode String? @unique (:336), showType Int @default(3) (1 site/2 mobile/3 both) (:338), isActive @default(true), createdAt @default(now()); relations variants, images, collections, comments, promotions, allocationItems.

ProductImage (:350-365)

id (cuid PK), productId→Product, url String, sortOrder Int @default(0), role ProductImageRole @default(GALLERY) (:359), variants ProductVariant[].

ProductVariant (:374-402)

Field	Type	Default / Attrs
id	String	cuid PK
productId	String	→ Product
title	String	—
sku	String?	@unique (:379)
rashWeightGrams	Decimal	@db.Decimal(14,4) — raw weight before making charge (:381)
defaultWagePercent	Decimal	@db.Decimal(6,3) (:383)
qty	Int	@default(0) (:387)
isPreOrder	Boolean	@default(false) (:389)
isActive	Boolean	@default(true) (:390)
imageId	String?	→ ProductImage, onDelete: SetNull (:396-397)
Index	@@index([imageId])	:401

Order (:408-439)

Field	Type	Default / Attrs
id	String	cuid PK
orderNumber	String	@unique (:410)
customerId	String	→ Customer (:411-412)
branchId	String?	→ Branch (:413-414)
channel	OrderChannel	@default(RETAIL) (:416)
status	OrderStatus	@default(PLACED) (:417)
totalGoldWeightGrams	Decimal	@db.Decimal(14,4) — incl. wage (:420)
wageWeightGrams	Decimal	@db.Decimal(14,4) — pure making-charge component (:422)
flatRialCharge	Decimal	@default(0) @db.Decimal(20,2) — legacy rial_input (:424)
isSuspendedOverCreditLimit	Boolean	@default(false) (:426)
deliveredAt	DateTime?	setting it triggers debt recognition (:427)
createdAt/updatedAt	DateTime	@default(now()) / @updatedAt (:429-430)
Relations	items, statusEvents, ledgerEntries, convertedFromPreOrder	:432-435
Indexes	@@index([customerId]), @@index([status])	:437-438

OrderItem (:441-456)

Field	Type	Default / Attrs
id	String	cuid PK
orderId / productVariantId	String	→ Order / ProductVariant
quantity	Int	—
rashWeightGramsSnapshot	Decimal	@db.Decimal(14,4) (:450)
wagePercentSnapshot	Decimal	@db.Decimal(6,3) (:451)
discountPercentSnapshot	Decimal	@default(0) @db.Decimal(6,3) (:452)
computedWeightGrams	Decimal	@db.Decimal(14,4) = rash*(1+(wage-discount)/100) (:453-454)
flatRialCharge	Decimal	@default(0) @db.Decimal(20,2) (:455)

OrderStatusEvent (:458-470)

id (cuid PK), orderId→Order, fromStatus OrderStatus?, toStatus OrderStatus, note?, actorAdminUserId?→AdminUser, createdAt @default(now()); @@index([orderId]) (:469).

PreOrder (:476-505)

id (cuid PK), customerId→Customer, cityId?→City, workshopId?→Workshop, status PreOrderStatus @default(PLACED) (:484), designImageUrl?, colorName?, sizeSpec?, stoneColor?, minaColor?, estimatedWeightGrams Decimal? @db.Decimal(14,4) (:491), estimatedPriceRial Decimal? @db.Decimal(20,2) (:492), description?, convertedOrderId String? @unique →Order (:496-497), createdAt/updatedAt, statusEvents; @@index([customerId]) (:504).

PreOrderStatusEvent (:507-519)

id (cuid PK), preOrderId→PreOrder, changes Json (field-level diff, :512), actorAdminUserId?→AdminUser, ipAddress?, createdAt; @@index([preOrderId]) (:518).

LedgerEntry (:525-571) — core accounting row

Field	Type	Default / Attrs
id	String	cuid PK
customerId	String	→ Customer (:527-528)
currency	LedgerCurrency	(:530)
direction	LedgerDirection	(:531)
sourceType	LedgerSourceType	(:532)
amount	Decimal	@db.Decimal(20,4) — always positive; sign from direction (:533-534)
karatPerMille	Int?	purity for melted gold (:537)
pricePerGramRialAtEntry	Decimal?	@db.Decimal(20,2) — for CASH (:539)
orderId	String?	→ Order (:541-542)
confirmed	Boolean	@default(false) — pending entries excluded from cached balance (:545)
confirmedAt	DateTime?	(:546)
postedByAdminUserId	String?	→ AdminUser (:547-548)
labName, hallmark, accountName, bankName, transferTo	String?	instrument metadata (:555-559)
originalValue	Decimal?	@db.Decimal(14,4) — pre-karat-normalization weight (:561)
priceRial	Decimal?	@db.Decimal(20,2) (:563)
receivedAt	DateTime?	(:564)
note	String?	(:566)
createdAt	DateTime	@default(now()) (:567)
Indexes	@@index([customerId, currency]), @@index([orderId])	:569-570

GoldPriceQuote (:574-582)

id (cuid PK), karatPerMille Int, pricePerGramRial Decimal @db.Decimal(20,2) (:577), source String, quotedAt DateTime @default(now()) (:579); @@index([karatPerMille, quotedAt]) (:581).

WalletBonus (:585-597)

id (cuid PK), customerId→Customer, orderId String? (no FK relation declared, :589), goldGrams Decimal @db.Decimal(14,4) (:590), grantedAt @default(now()), expiresAt DateTime (required) (:592), consumedAt DateTime?, isActive Boolean @default(true); @@index([customerId, isActive]) (:596).

UserType (:620-632)

id Int @id (legacy ut, not cuid) (:623), title String, isActive @default(true), createdAt @default(now()); relations permissions, adminUsers; @@map("user_type") (:631).

Permission (:634-644)

rid String (dotted id), userTypeId Int → UserType onDelete: Cascade (:638); @@id([rid, userTypeId]) composite PK (:641), @@index([userTypeId]) (:642), @@map("permission") (:643).

Comment (:661-681)

id (cuid PK), productId→Product, customerId→Customer, body String, status CommentStatus @default(PENDING) (:668), replyToId?→self (CommentReplies), replies, createdAt/updatedAt; @@index([productId]), @@index([customerId]), @@index([status]) (:678-680).

Setting (:690-694)

key String @id, value Json, updatedAt @updatedAt. Replaces legacy config_static.

Promotion (:717-746)

id (cuid PK), title, description?, scope PromotionScope @default(PRODUCT) (:721), usage PromotionUsage @default(ONCE) (:722), discountPercent Decimal @db.Decimal(6,3) (:724), isActive @default(true), platform Int @default(3) (:727), startsAt?/endsAt?, and exactly one of productId/categoryId/customerId/brandId per scope (:733-740), createdAt/updatedAt; @@index([scope, isActive]) (:745).

PromotionExclusion (:752-760)

id (cuid PK), type Int, itemId String, createdAt; @@unique([type, itemId]) (:758), @@index([type]) (:759).

BranchAllocation (:769-784)

id (cuid PK), branchId→Branch, allocatorAdminUserId?→AdminUser (AllocationAuthor), note?, createdAt, items; @@index([branchId]) (:783).

BranchAllocationItem (:786-796)

id (cuid PK), allocationId→BranchAllocation onDelete: Cascade (:789), productId→Product, weightGrams Decimal? @db.Decimal(14,4) (:793); @@unique([allocationId, productId]) (:795).

SmsMessage (:814-829)

id (cuid PK), audience MessageAudience, recipients String? (comma-separated), body String, sentCount Int @default(0) (:821), sentByAdminUserId?→AdminUser (SmsAuthor), createdAt; @@index([createdAt]) (:828).

Notification (:831-845)

id (cuid PK), title, body, audience MessageAudience @default(ALL_CUSTOMERS) (:835), sentByAdminUserId?→AdminUser (NotificationAuthor), createdAt, recipients; @@index([createdAt]) (:844).

NotificationRecipient (:848-858)

id (cuid PK), notificationId→Notification onDelete: Cascade (:851), customerId→Customer, readAt DateTime?; @@unique([notificationId, customerId]) (:856), @@index([customerId, readAt]) (:857).

NewsletterSubscriber (:861-869)

id (cuid PK), email String?, mobile String?, createdAt; @@unique([email]), @@unique([mobile]) (:867-868).

CustomerActivityLog (:873-883)

id (cuid PK), customerId→Customer, action String (free-form key), detail String?, createdAt; @@index([customerId, createdAt]) (:882).

UploadedFile (:892-911)

id (cuid PK), url String, originalName, mimeType, sizeBytes Int, purpose String?, uploadedByAdminUserId?→AdminUser (FileUploader), createdAt, customerAvatars/adminUserAvatars back-relations; @@index([purpose]) (:910).

6.3 Decimal precision map (no Float anywhere in the schema)

Precision	Used for	Examples
Decimal(14,4)	gold weights in grams	Customer.goldCreditLimitGrams/goldDebtGrams (:200-201), Order.totalGoldWeightGrams/wageWeightGrams (:420,422), OrderItem.rash/computedWeight (:450,454), ProductVariant.rashWeightGrams (:381), WalletBonus.goldGrams (:590), LedgerEntry.originalValue (:561), PreOrder.estimatedWeightGrams (:491), BranchAllocationItem.weightGrams (:793)
Decimal(20,2)	Rial money	Customer.fiatDebtRial (:202), Order.flatRialCharge (:424), OrderItem.flatRialCharge (:455), GoldPriceQuote.pricePerGramRial (:577), LedgerEntry.pricePerGramRialAtEntry/priceRial (:539,563), PreOrder.estimatedPriceRial (:492)
Decimal(20,4)	ledger amount (dual-currency, so finer than money)	LedgerEntry.amount (:534)
Decimal(6,3)	percentages	City.percent/percentAux (:120-121), AdminUser.wagePercent (:141), ProductVariant.defaultWagePercent (:383), OrderItem.wagePercentSnapshot/discountPercentSnapshot (:451-452), Promotion.discountPercent (:724)

---

7. Migrations & seed

7.1 prisma/migrations/* (in order)

#	Folder / file	Note
—	0002_admin_schema.sql	bare .sql at the migrations root (not a folder) — sorts first lexically
1	20260910113720_first	initial schema
2	20260914165255_sync_schema_drift
3	20260916141751_add_retail_customer_kind	adds CustomerKind.RETAIL
4	20260917120000_customer_name_parts_and_percent
5	20260918090000_customer_parent_agent_self_relation
6	20260918120000_add_product_image_role	adds ProductImageRole
7	20260921090000_add_variant_image	adds ProductVariant.imageId
8	20260921120000_agent_is_admin_user	sales agent moves Customer→AdminUser
—	migration_lock.toml	provider = "postgresql"

Custom migration runner (not prisma migrate deploy): src/prisma/migrate.ts applies the .sql files itself through the Prisma client and records them in a tracking table _goldbank_migrations (migrate.ts:5,7-13). Reason: the release image is copy-only and has no Prisma CLI (migrate.ts:10-12). Migrations dir resolved from MIGRATIONS_DIR or one of 4 fallbacks (migrate.ts:20-36). SQL is split statement-by-statement because Postgres rejects multi-statement parameterised queries (migrate.ts:38-42, splitSqlStatements). Invoked from prepareDatabase() before Nest boots (bootstrap.ts:104-134, main.ts:19).

7.2 prisma/seed.ts (738 lines) — what it creates

Entity	What	Cite
Dev passwords	DEV_PASSWORD = 'admin1234', bcrypt cost 10; DEV_TEST_PHONE = '09128081392' whose password is the phone number itself (dev-only)	seed.ts:16-24
Cities (4)	تهران / مشهد / اصفهان / تبریز, fixed ids city-tehran etc.	:33-38
Branches (2)	Tehran, Mashhad	:41-49
Workshop (1)	upsert	:51
UserTypes + Permissions (5)	see table below	:66-110
AdminUsers (6 upserts)	dev test user 09128081392 (SUPER_ADMIN, ut 85, branchId null); 09120000001 مدیر ارشد سیستم (SUPER_ADMIN, ut 85, branchId null — deliberately branch-less so head office is not branch-scoped, :140-143); 09121234567 رضا احمدی (SALES_EXPERT, ut 86, Tehran, wagePercent 1.5); 09129876543 سارا کریمی (SALES_EXPERT, ut 86, Mashhad, wagePercent 1.2); 09123334444 هومن یزدانی (WORKSHOP_SUPERVISOR, ut 88); 09125556666 فرزانه محمودی (ACCOUNTANT, ut 87, branchId null)	:118-194
Customers	customerData array, upserted with PLACEHOLDER_PASSWORD_HASH	:197-333
Categories (5)	انگشتر، دستبند، گردنبند، گوشواره، سکه و شمش	:341-347
Brands (2)	Montzar, Artisan	:349-358
Products + variants + images	from productDefs; placeholder image /img/no-items.png	:29, 360-462
Collection	featured + 3 CollectionProduct rows	:465-484
GoldPriceQuote	{ karatPerMille: 750, pricePerGramRial: '61500000', source: 'seed-illustrative' } — create, not upsert, so a re-seed appends another quote	:487-489
Order ORD-SEED-0002	RETAIL, status PLACED, rash 2.400, wage 7.5% → computed via parseFloat(...).toFixed(4) (float math in the seed only)	:494-527
Order ORD-SEED-0001	WHOLESALE, DELIVERED_TO_CUSTOMER, rash 3.100, wage 9%, flatRialCharge 500000, deliveredAt: now, 3 status events	:542-580
Ledger entries	GOLD_GRAM DEBIT ORDER_STOCK (confirmed) + RIAL DEBIT ORDER_STOCK (confirmed) + a pending GOLD_GRAM CREDIT REPAYMENT_MELTED_GOLD 1.5000 @ 750‰ (confirmed: false) to demo the confirm flow	:582-625
Cached balances	customer1 incremented by the posted debt (:608-611); customer2 set to goldDebt 8.2500 / fiat 2000000; customer5 zeroed	:608-630
PreOrders (2)	preorder-0001 PLACED, preorder-0002 ADMIN_APPROVED	:635-667
Comments (3)	one APPROVED, one PENDING, one REJECTED	:672-700
Variant stock	every variant gets qty = 5 + (i%4), isPreOrder = i%5===0	:705-711
Product codes	P-0001, P-0002, … by title asc	:712-718
Setting rows	NONE — the seed creates no Setting rows at all. wallet.config, wallet.birthday, promotion.auto, mobile_main_slider are created lazily on first write (admin-documents.service.ts:421-428, admin-promotions.service.ts:261-282) and read back as {} / defaults until then (admin-documents.service.ts:416-419, admin-promotions.service.ts:256-259)

Seed UserTypes and their rids (seed.ts:66-98):

ut id	Title	rids
85	مدیر ارشد	ALL_RIDS — all 144 (seed.ts:68)
86	کارشناس فروش	order.list, order.create, order.omde, order.makeOrder, persons.list.client.omde, persons.list.client.omde.view, persons.list.client.single, persons.list.client.single.view, persons.create, product.list, dashboard.view, comment (12) (:72-77)
87	حسابدار	document.list, document.create, document.list.edit, invoice.list, invoice.create, wallet, config.wallet, report.order.item, report.product, config.report, dashboard.view (11) (:82-86)
88	سرپرست کارگاه	workshop.list, workshop.create, order.tamin, order.list, product.list (5) (:91)
89	کاربر شعبه	buy.order.list, order.create, persons.create, branch.list (4) (:96)

Only leaf rids are stored; ancestors derived at runtime (seed.ts:64-65). Permissions written with createMany({ skipDuplicates: true }) (:106-109).

Idempotency: everything uses upsert except goldPriceQuote.create (:487) and the ledger/order blocks, which are guarded by a findUnique on the seed order number (:494-497, :542-543).

---

8. Business logic

8.1 Gold price

• PricingService.recordQuote(karatPerMille, pricePerGramRial, source) → inserts a GoldPriceQuote (pricing.service.ts:9-13). No caller anywhere in src/ — the only write path is unused; quotes only enter via the seed.
• PricingService.getLatestQuote(karat) → newest quote for that karat, 404 if none (pricing.service.ts:15-22).
• GET /api/pricing/latest?karatPerMille= defaults to 750 (pricing.controller.ts:11-12).
• No external price feed, no scheduler, no HTTP fetch — nothing refreshes quotes automatically.

8.2 Gram / weight calculation (the central formula)

OrdersService.createOrder (orders.service.ts:32-109):

• Per line: netPercent = wagePercent - discountPercent; computedWeightGrams = rashWeight * (netPercent/100 + 1) — all Prisma.Decimal arithmetic (.sub, .div, .add, .mul), no float (orders.service.ts:39-43).
• rashWeight is snapshotted from the variant at order time and never re-read (orders.service.ts:39, schema.prisma:449).
• totalGoldWeightGrams = Σ computedWeight * qty (orders.service.ts:57-60); totalRashWeightGrams = Σ rash * qty (:61-64); wageWeightGrams = total - totalRash (:65).
• flatRialCharge = Σ item.flatRialCharge * qty (:66-69).
• No rounding / quantization is applied in code — precision is enforced only by the column types Decimal(14,4) / Decimal(20,2) at write time (schema.prisma:420-424).
• Admin path (AdminOrdersService.createFromAdmin, admin-orders.service.ts:287-339) deliberately delegates to OrdersService.createOrder rather than recomputing; client-sent totals (total_price, total_weight, gold_price_original) are ignored and recomputed server-side (admin-orders.service.ts:283-286). Wage falls back to variant.defaultWagePercent when not negotiated (:316).

8.3 Fees / commissions / tax / spread

• Wage (اجرت / making charge) is the only fee: a percentage on the raw weight, expressed as extra gold weight, not money (ProductVariant.defaultWagePercent, OrderItem.wagePercentSnapshot).
• Discount: OrderItem.discountPercentSnapshot, subtracted from wage before applying.
• Flat Rial charge: per-unit non-gold cost, e.g. stones (Order.flatRialCharge, schema.prisma:423-424).
• Agent commission: AdminUser.wagePercent Decimal(6,3) (schema.prisma:141) — stored and displayed (sales-agent.service.ts:92) but never applied to any calculation.
• City surcharges: City.percent / percentAux (schema.prisma:118-121), readable via GET admin/misc/cities/percent/:id and percent-aux/:id (admin-misc.controller.ts:40-50) but never used in pricing.
• Bulk wage change: AdminProductsService.changePercent sets defaultWagePercent across a brand/category filter via updateMany, using new Prisma.Decimal(String(percent)) (admin-products.service.ts:641-657); changePercentCount previews the affected count (:630-639).
• Tax / VAT: no tax logic anywhere.
• Spread / buy-vs-sell price: none — a single GoldPriceQuote.pricePerGramRial per karat, no bid/ask.

8.4 Rounding & precision (Decimal vs float) — exact findings

• Schema: zero Float fields; every monetary/weight/percent column is Decimal with explicit @db.Decimal(p,s) (see §6.3), per the stated design rule (schema.prisma:4).
• Ledger math: entirely Prisma.Decimal — amount.lte(0), .neg(), .mul(), .div(), .sub(), .gt() (ledger.service.ts:34-35, 95, 131, 178, 189, 300-302).
• Order math: entirely Prisma.Decimal (orders.service.ts:39-69).
• Float leaks found (3):
  1. ledger.service.ts:189 — CASH conversion divides by GRAMS_PER_MESGHAL, a JS number literal 4.331802 (packages/shared-types/src/index.ts:9). Decimal.div(number) coerces the number, so the constant itself carries binary-float representation into an otherwise-Decimal chain. The formula is flagged in its own comment as "worth stakeholder review" (ledger.service.ts:186-187).
  2. admin-dashboard.service.ts:148 and :347 — sorting aggregates with Number(b.weight) - Number(a.weight), i.e. Decimal→float for ordering only (display, not stored).
  3. prisma/seed.ts:500, 509, 547, 560 — parseFloat(...).toFixed(4) to compute demo order weights. Seed-only; not a runtime path.
• Explicit rounding calls: none. No Math.round, toFixed or Decimal.toDecimalPlaces in src/. All quantization is implicit at the DB column scale.
• Karat normalization: goldGrams = raw * karatPerMille / 750, with STANDARD_KARAT_PER_MILLE = 750 (ledger.service.ts:178, packages/shared-types/src/index.ts:6).

8.5 Wallet / balance

• Source of truth: LedgerEntry (append-only). Customer.goldDebtGrams / fiatDebtRial are denormalized caches (schema.prisma:198-202, ledger.service.ts:23-27).
• applyToBalance: signedDelta = DEBIT ? amount : -amount, applied with Prisma { increment: signedDelta } on the matching currency field (ledger.service.ts:88-103).
• getBalance reads the cache + credit limit (ledger.service.ts:270-282).
• reconcileBalance recomputes from confirmed entries only: goldDebits - goldCredits, rialDebits - rialCredits, and overwrites the cache (ledger.service.ts:284-304); sumConfirmed uses aggregate._sum filtered on confirmed: true (:306-312). Documented as periodic/on-demand self-healing, unlike legacy's recompute-on-every-write (:284-288). Nothing schedules it — it only runs via POST /api/accounting/customers/:customerId/reconcile, which is @Public().
• Wallet bonus is a separate concept from debt: WalletBonus in gold grams with a mandatory expiresAt. chargeWallet validates grams > 0 and applies a hardcoded one-year expiry because the column is required (admin-customers.service.ts:734-749, expiry at :743-744). It does not post a ledger entry, so a granted bonus never touches goldDebtGrams despite LedgerSourceType.WALLET_BONUS existing (schema.prisma:106) — that enum value has no producer in src/.
• Wallet listings: AdminDocumentsService.listWallet (admin-documents.service.ts:369-409), AdminCustomersService.customerWallet (admin-customers.service.ts:701-714).

8.6 Buy / sell orders

• There is no buy/sell gold trading flow. "Orders" are jewelry/product orders that incur gold-weight debt. No BUY/SELL side, no order matching, no quote-locking.
• Order placement: OrdersService.createOrder (orders.service.ts:32-109); admin builder path AdminOrdersService.createFromAdmin (admin-orders.service.ts:287-339).
• Order number: ORD-${Date.now()}-${random6} (orders.service.ts:148-151) — not collision-proof by construction, relies on the @unique column.
• Order deletion refuses once ledger entries exist (admin-orders.service.ts:217-221); otherwise cascades events+items+order in one transaction (:223-228).

8.7 Deposit / withdraw / transfers

• No customer-initiated deposit or withdrawal, and no customer-to-customer transfer. "TRANSFER" (REPAYMENT_TRANSFER) means a bank remittance repayment instrument, not an internal transfer (ledger.service.ts:193-196, schema.prisma:104).
• The only inbound value flow is a repayment document filed by an admin (§8.9).

8.8 Order & transaction statuses and transitions

Order status labels (admin-orders.service.ts:16-25):

Enum	Farsi label
SUSPENDED	معلق (سقف اعتبار)
PLACED	ثبت شده
ADMIN_APPROVED	تایید مدیر
SOURCING	در حال تامین
PREPARING	در حال آماده‌سازی
DELIVERED_TO_AGENT	تحویل به نماینده
DELIVERED_TO_CUSTOMER	تحویل به مشتری
CANCELLED	لغو شده

Declared flow (STATUS_FLOW, admin-orders.service.ts:28-35): PLACED → ADMIN_APPROVED → SOURCING → PREPARING → DELIVERED_TO_AGENT → DELIVERED_TO_CUSTOMER. SUSPENDED and CANCELLED are outside the flow.

Transition mechanics (OrdersService.updateStatus, orders.service.ts:111-139):

• No state-machine validation — any status may be set from any status; STATUS_FLOW is used only to render the timeline (admin-orders.service.ts:249-258).
• deliveredAt is stamped on DELIVERED_TO_CUSTOMER (orders.service.ts:120).
• Debt recognition fires at DELIVERED_TO_AGENT, not at DELIVERED_TO_CUSTOMER (orders.service.ts:133-135; mirrors legacy sts>4).
• Idempotency guard: debt posts only if (newStatus === DELIVERED_TO_AGENT && !order.deliveredAt) (orders.service.ts:133). Note the asymmetry: deliveredAt is set by DELIVERED_TO_CUSTOMER but guards the DELIVERED_TO_AGENT posting — so two successive DELIVERED_TO_AGENT transitions without an intervening DELIVERED_TO_CUSTOMER would both post debt.
• Every transition writes an OrderStatusEvent with fromStatus/toStatus/note/actor (orders.service.ts:124-126).
• Status removal (remove: true): refuses DELIVERED_TO_AGENT because the debt is already posted (admin-orders.service.ts:381-386); otherwise deletes the newest matching event and rolls the order back to the latest remaining event's status, defaulting to PLACED (:388-404).
• Legacy numeric codes 1–6 map onto the enum in statusFromLegacyCode (admin-orders.service.ts:346-356).

Pre-order statuses: PLACED, ADMIN_APPROVED, WORKSHOP_APPROVED, READY_TO_SHIP, DELIVERED, CANCELLED (schema.prisma:80-87); diffs recorded as JSON in PreOrderStatusEvent.changes (schema.prisma:512). Conversion to a real Order is modelled by PreOrder.convertedOrderId (schema.prisma:496-497) but no service method performs the conversion.

Ledger entry "status": the boolean confirmed is the only lifecycle. Order-debt entries are self-confirming (confirmed: true); repayments start pending (confirmed: false) — an intentional deviation from legacy, which auto-confirmed (ledger.service.ts:18-19, 113-146, 213, 65-73).

Comment statuses: PENDING → APPROVED/REJECTED via POST admin/comments/sts with legacy codes 1/2/3 (schema.prisma:655-659, admin-comments.controller.ts:35, admin-comments.service.ts:150).

8.9 Repayments (the real "transaction" path)

LedgerService.postGoldRepayment (ledger.service.ts:156-218) normalizes four instruments into gold grams, then posts a pending GOLD_GRAM CREDIT:

Instrument	Formula	Required extra	sourceType	Cite
MELTED_GOLD	raw * karatPerMille / 750	karatPerMille (400 if missing)	REPAYMENT_MELTED_GOLD	:173-180
CASH	raw / (pricePerGramRial / 4.331802)	pricePerGramRial (400 if missing)	REPAYMENT_CASH	:182-191
TRANSFER	raw (1:1 grams)	—	REPAYMENT_TRANSFER	:193-196
CHEQUE	raw (1:1 grams)	—	REPAYMENT_CHEQUE	:197-200

postRialRepayment posts a RIAL CREDIT with sourceType: REPAYMENT_CASH, also pending (ledger.service.ts:225-242) — explicitly noted as not present in legacy (:220-224). postAdjustment posts an ADJUSTMENT in either currency/direction, always confirmed: true, requires note and postedByAdminUserId (ledger.service.ts:244-268) — no caller in src/. postEntry rejects non-positive amounts (amount.lte(0) → 400, ledger.service.ts:34-36). confirmEntry is idempotent (returns early if already confirmed) and then applies to the balance (ledger.service.ts:74-86).

Admin document path (AdminDocumentsService, admin-documents.service.ts):

• Legacy type codes 1..4 → LedgerSourceType (:26-31); instrument name mapping (:34-39); Farsi labels (:48-57).
• create picks the raw figure per instrument: CASH→price, MELTED_GOLD→original_value ?? value, else value (:226-231), delegates to postGoldRepayment, then patches instrument metadata (:233-249).
• toggleConfirm is a bidirectional toggle: confirm delegates to LedgerService.confirmEntry; un-confirm reverses the cached balance in a transaction (CREDIT → +amount, DEBIT → -amount) and clears the flag (:309-338).
• update refuses to change the amount of a confirmed entry (400, :284-288); allows metadata/note always and amount on unconfirmed entries (:290-294).
• remove refuses to delete a confirmed entry (400, :347-357).

8.10 Credit limit / suspension (the "limits" logic)

• Single limit: Customer.goldCreditLimitGrams (legacy gram_level).
• Check at placement: isSuspendedOverCreditLimit = (totalGoldWeightGrams + customer.goldDebtGrams) > customer.goldCreditLimitGrams (orders.service.ts:71-74).
• Over limit → the order is created with status SUSPENDED, not rejected; the flag is persisted and a status event notes "Credit limit exceeded" (orders.service.ts:75, 88, 101).
• The check uses the cached goldDebtGrams, which excludes pending repayments (ledger.service.ts:306-312) — so an unconfirmed repayment does not relax the limit.
• canPlaceOrders is never enforced in OrdersService.createOrder — it is toggled (admin-customers.service.ts:773-780) and exposed, but no order path reads it.
• Limit edits: updateCredit (requires gram_level, admin-customers.service.ts:852-864) and update (:612-614), both via new Prisma.Decimal(String(...)).
• No per-order, daily, or per-customer transaction-count limits exist.

8.11 KYC / verification

• VerificationStep enum: UNVERIFIED → STEP_ONE_SUBMITTED → STEP_TWO_SUBMITTED → VERIFIED (schema.prisma:54-59).
• Document URLs on Customer: nationalIdImageUrl, businessLicenseUrl, shopImageUrl (schema.prisma:205-207); persisted on create from national_id_image/business_license/shop_image (admin-customers.service.ts:591-593).
• AdminCustomersService.verify (admin-customers.service.ts:790-816) takes legacy { customer_id, sts_verify_step_one|sts_verify_step_two } where 2 = accept, anything else = reject:
  • step-one accept → STEP_TWO_SUBMITTED; step-one reject → UNVERIFIED (:801-805)
  • step-two accept → VERIFIED; step-two reject → STEP_ONE_SUBMITTED (:806-810)
  • neither key → 400 (:811-813)
• Verification is never enforced anywhere — no order, ledger or limit path reads verificationStep. The non_verified list scope only filters the grid (admin-customers.service.ts:170-193).
• nationalCode is @unique but falls back to the mobile number when not supplied (admin-customers.service.ts:530, 567) — so retail customers systematically carry a national code equal to their phone.

8.12 OTP / SMS

• No OTP implementation of any kind: no OTP model, no code generation, no verification endpoint, no expiry. (Grep for otp over src/ returns nothing.)
• SMS is persistence-only — no provider, no HTTP call. AdminMiscService.sendSms validates a non-empty body, resolves the audience and recipient list, and writes an SmsMessage row with sentCount = recipients.length (admin-misc.service.ts:176-195). Nothing is actually transmitted.
• Audience codes (admin-misc.service.ts:205-221): -1→SINGLE_NUMBER, 0→ALL_CUSTOMERS, 1→SALES_AGENTS, 2→WHOLESALE_CUSTOMERS, 9→MULTIPLE_NUMBERS; plus name aliases single/multiple/all/omde/tak/reagent. RETAIL_CUSTOMERS is reachable only by name — the legacy markup had no numeric option for it (noted :202-203).
• The customer reactivation SMS legacy sent is deliberately not fired (admin-customers.service.ts:754-757).

8.13 Notifications

• Notification + NotificationRecipient (per-customer read state), schema.prisma:831-858.
• createNotification (broadcast by audience) / notifyCustomer (single) / markNotificationRead / findNotification / listNotifications (admin-misc.service.ts:263, 291, 388, 317, 347).
• Delivery is in-database only — no push, email or SMS dispatch.

8.14 Payment gateway + callbacks

• None. No gateway module, no redirect/verify endpoints, no callback route, no zarinpal/sadad/IPG reference, no signature verification, and no outbound HTTP client in the dependency list. Money enters the system exclusively as an admin-filed repayment document (§8.9).

8.15 File uploads

• AdminUploadsService.store (admin-uploads.service.ts:37-69):
  • 400 if no file (:42); max 8 MB MAX_BYTES = 8*1024*1024 (:33, 43-45)
  • MIME allowlist: image/(jpeg|png|gif|webp|svg+xml) or application/pdf (:30, 46-48) — note SVG is accepted, and it is later served inline (public-uploads.controller.ts:23-26), an XSS vector
  • Stored name: md5(Date.now() + originalname + randomUUID()) + ext (:50-54)
  • Written to getUploadDir(), row created with url = '/uploads/<stored>' (:56-68)
• Path resolution + traversal defence: resolveStoredUpload takes basename, rejects ./.., checks the resolved path stays under the upload dir, and also probes a nested uploads/uploads/ leftover (upload-path.ts:34-48).
• Serving: static mount at /uploads/ (main.ts:28-36) and a streaming controller at /api/uploads/:filename with a 1-day cache header (public-uploads.controller.ts:17-27), because the user-app's axios base is /api (:9-13).
• Deliberately not ported: webp re-encoding, watermarking, thumbnailing (dead in legacy too) (admin-uploads.service.ts:20-22).

8.16 Settings

• One key/value table: Setting { key @id, value Json, updatedAt } (schema.prisma:690-694), replacing legacy config_static.
• Generic CRUD: getConst / setConst / listConsts / removeConst (admin-misc.service.ts:464-491), exposed at GET|PUT|DELETE admin/misc/const/:key under config.statics.
• Known keys: wallet.config, wallet.birthday (admin-documents.controller.ts:51,58,64,71), promotion.auto (admin-promotions.service.ts:257,262,275-280), mobile_main_slider (admin-misc.controller.ts:188,193,199).
• The slider key is privilege-separated: dedicated routes require custom.config.statics.slider, and assertNotSliderKey blocks reaching mobile_main_slider through the generic config.statics routes (admin-misc.controller.ts:184-200, 224-233).
• setAutoPromotion validates 0 ≤ discount_percent ≤ 100 (admin-promotions.service.ts:261-266).
• Settings are read with fallbacks, never seeded (§7.2).

8.17 XTable query engine (TableService) — shared by every admin grid

• Operators → Prisma: =,!=,>,>=,<,<=,like(→contains, % stripped, mode:'insensitive'),in,between(value+value2),null,notnull (table.service.ts:56-91).
• Field allowlist enforced per call; unknown field → 400 Field not filterable (table.service.ts:49-53) — also applied to sort fields (:121).
• Dotted paths nested into relation filters (customer.fullName → {customer:{fullName:…}}) (table.service.ts:42-47).
• Defaults: page=1, limit=10 (table.service.ts:95-96); limit capped at 500 by the DTO (@Max(500)).
• Sort: '+field' asc / '-field' desc, default {createdAt:'desc'} (table.service.ts:116-124).
• Response envelope { rows, query:{search,filters,total,limit,page} } (table.service.ts:137-148).
• Exports are unimplemented and rejected loudly: any op → 400 (table.service.ts:150-157), called by every list method as assertNotExport.

8.18 Branch scoping

AdminOrdersService.list narrows to admin.branchId whenever the caller has one (admin-orders.controller.ts:39, admin-orders.service.ts:75-81), faithfully reproducing legacy. The seed keeps head-office admins branch-less precisely so they are not scoped (seed.ts:140-143, admin-orders.controller.ts:33-37). Same pattern for listSingle (admin-customers.controller.ts:65).

---

9. Auth

Concern	Implementation	Cite
Strategy	passport-jwt, named 'jwt', token from Authorization: Bearer	jwt.strategy.ts:30-37
JWT secret	process.env.JWT_SECRET ?? 'dev-only-insecure-secret' — same insecure fallback in two places	auth.module.ts:16, jwt.strategy.ts:35
Expiry	process.env.JWT_EXPIRES_IN ?? '12h', cast to `${number}h`	auth.module.ts:20
ignoreExpiration	false (expiry enforced)	jwt.strategy.ts:34
Refresh tokens	NONE — no refresh endpoint, no refresh token, no rotation, no revocation/blacklist. A token is valid until it expires.	(absent)
Token payload	{ sub: user.id, mobile } only — no roles/permissions baked in	auth.service.ts:43, jwt.strategy.ts:7-10
Per-request principal	validate() re-reads the AdminUser + userType.permissions on every request, so permission changes take effect immediately	jwt.strategy.ts:39-61, comment :49-50
Inactive users	!user || !user.isActive → 401	jwt.strategy.ts:45-47
Password hashing	bcryptjs, bcrypt.compare on login; cost 10 on customer create and in the seed	auth.service.ts:38, admin-customers.service.ts:572, seed.ts:17
Login response	{ id, name, fullName, mobile, role, ut, branch_id, api_token, roles:[{rid}] } — legacy shape	auth.service.ts:45-55
Enumeration defence	bad phone and bad password both return 401 (legacy returned 404/422)	auth.service.ts:24-26, 34-41
GET admin/auth/me	returns raw (unexpanded) rids as permission[]; the frontend runs checkParent()	auth.service.ts:58-88, esp. :86

Guards — both registered globally via APP_GUARD in AuthModule (auth.module.ts:29-30):

Guard	Behaviour	Cite
JwtAuthGuard extends AuthGuard('jwt')	Reads IS_PUBLIC_KEY via reflector.getAllAndOverride on handler and class; @Public() → allow; otherwise super.canActivate. Secure-by-default (inverse of legacy's allowlist).	guards.ts:35-49, comment :27-34
PermissionsGuard	Reads REQUIRED_RID_KEY; no rid → allow. Otherwise requires req.user (else 403) and user.permissions.includes(requiredRid) (else 403 Missing permission: <rid>).	guards.ts:52-71

Decorators:

Decorator	Key	Cite
@Public()	SetMetadata('isPublic', true)	guards.ts:14-15
@RequirePermission(rid)	SetMetadata('requiredRid', rid)	guards.ts:18-19
@CurrentAdmin()	createParamDecorator → req.user as AuthenticatedAdmin	guards.ts:22-25

Permission model:

• Permissions attach to the UserType (ut), never to an individual admin — every admin of a type shares one set (schema.prisma:600-618, Permission composite PK [rid, userTypeId] :641).
• expandWithParents(rids) derives ancestors at request time: granting persons.list.client.omde implicitly grants persons.list.client, persons.list, persons (acl.constants.ts:194-203, applied jwt.strategy.ts:60). Port of legacy checkParent().
• getParents walks up only — a rid never implies its children; the resulting legacy quirk (holding wallet does not grant wallet.list) is deliberately preserved as a documented legacy bug (acl.constants.ts:171-192).
• setRoles replaces a user type's whole rid set inside one transaction (deleteMany + createMany skipDuplicates) — and performs no validation against ALL_RIDS, so an arbitrary string can be stored as a rid (admin-users.service.ts:317-332).
• revokeRole removes one rid, 404 if absent (admin-users.service.ts:335-346).
• AdminRole (the coarse enum) is used for business rules, not for route gating — the only enforcement is SalesAgentService.assertIsSalesExpert (role !== 'SALES_EXPERT' → 403, sales-agent.service.ts:36-40) and queryReagents filtering role: 'SALES_EXPERT' (admin-customers.service.ts:719).

9.1 All role names

AdminRole (5) — schema.prisma:21-27, labels admin-users.service.ts:353-361: SUPER_ADMIN (مدیر ارشد), SYSTEM_APPROVER (تایید مدیر سیستم), SALES_EXPERT (کارشناس فروش), WORKSHOP_SUPERVISOR (سرپرست کارگاه), ACCOUNTANT (حسابدار).

UserType rows seeded (5) — seed.ts:66-98: 85 مدیر ارشد, 86 کارشناس فروش, 87 حسابدار, 88 سرپرست کارگاه, 89 کاربر شعبه.

9.2 All permission names (ALL_RIDS, 144 leaf rids)

Source: src/modules/auth/acl.constants.ts:17-161. Derived as the union of 58 route-gated (meta.role) + 100 in-view ($hasPermission) legacy rids (acl.constants.ts:4-13).

Group	Rids
branch	branch.create, branch.list
buy	buy.order.list
cities	cities.create, cities.list, cities.list.remove, cities.list.view, cities.list.view.edit
collection	collection.create, collection.list, collection.list.edit, collection.list.remove
comment	comment, comment.remove, comment.state, comment.view, comment.view.edit
config	config.report, config.statics, config.statics.brand, config.statics.brand.create, config.statics.brand.edit, config.statics.brand.remove, config.statics.tags, config.statics.tags.create, config.statics.tags.edit, config.statics.tags.remove, config.wallet
custom	custom.config.statics.slider, custom.config.statics.tags.banner.ids
dashboard	dashboard.view
document	document.create, document.list, document.list.confirm, document.list.deny, document.list.edit, document.list.get, document.list.remove
invoice	invoice.create, invoice.list
newsletters	newsletters
notify	notify.create, notify.me
offers	offers.autopromotion, offers.create, offers.create.tak, offers.list, offers.list.edit, offers.list.remove, offers.list.tak.edit, offers.list.tak.remove, offersIgnore
order	order.create, order.list, order.list.pdf, order.list.sts, order.list.sts.remove, order.list.sts.submit, order.list.view, order.list.view.edit, order.makeOrder, order.makeOrder.get, order.makeOrder.remove, order.makeOrder.state, order.makeOrder.state.remove, order.makeOrder.state.submit, order.makeOrder.view, order.makeOrder.view.edit, order.omde, order.omde.get, order.omde.remove, order.omde.state, order.omde.state.remove, order.omde.state.submit, order.omde.view, order.omde.view.edit, order.omde.view.remove, order.tamin, order.tamin.state, order.tamin.state.remove, order.tamin.state.submit, order.tamin.view, order.tamin.view.edit
persons	persons.create, persons.create.client, persons.create.customer.tak, persons.create.seller, persons.list.client.omde, persons.list.client.omde.able, persons.list.client.omde.able.order, persons.list.client.omde.edit, persons.list.client.omde.unable, persons.list.client.omde.unable.order, persons.list.client.omde.view, persons.list.client.omde.view.documents, persons.list.client.omde.view.orders, persons.list.client.single, persons.list.client.single.edit, persons.list.client.single.view, persons.list.sellers, persons.list.sellers.able, persons.list.sellers.able.order, persons.list.sellers.edit, persons.list.sellers.unable, persons.list.sellers.unable.order, persons.list.sellers.view, persons.list.sellers.view.documents, persons.list.sellers.view.orders
product	product.create, product.list, product.list.edit, product.list.group.edit, product.list.remove, product.list.variants, product.list.variants.add, product.list.variants.edit, product.list.variants.remove, product.list.view, product.percent
report	report.order.item, report.product
sms	sms.create, sms.create.all, sms.create.multiple, sms.create.omde, sms.create.reagent, sms.create.single, sms.list
statics	statics
user	user.create, user.list, user.list.create, user.list.edit, user.list.remove, user.permission, user.permission.create, user.permission.edit
wallet	wallet, wallet.charge, wallet.list, wallet.percent
workshop	workshop.create, workshop.list

Rids declared but never enforced by any route (declared-only; the panel may use them client-side): comment.remove, comment.state, comment.view, comment.view.edit, config.statics.tags* (4), custom.config.statics.tags.banner.ids, document.list.confirm, document.list.deny, document.list.get, document.list.remove, cities.list.view, collection.list.remove, offers.create.tak, offers.list.remove, offers.list.tak.edit, offers.list.tak.remove, order.list.pdf, order.list.sts*, order.list.view*, order.makeOrder.get/remove/state*/view*, order.omde.get/remove/state*/view*, order.tamin.state*/view*, persons.create.client/customer.tak/seller, persons.list.*.able/unable*, persons.list.client.single.edit, persons.list.sellers.edit/able/unable*/view.documents/view.orders, product.list.group.edit/remove/variants*/view, sms.create.all/multiple/omde/reagent/single, user.list.create, wallet.charge/list/percent, buy.order.list, newsletters is enforced, statics is enforced.

---

10. Jobs / cron / schedulers / websockets

None of any kind. Verified by grep over src/: no @nestjs/schedule, ScheduleModule, @Cron, @Interval, setInterval, node-cron, @WebSocketGateway, SubscribeMessage, OnGatewayInit, or socket.io. Confirmed absent from package.json dependencies too.

The only non-request-triggered work is the boot-time sequence in prepareDatabase() (bootstrap.ts:104-134), executed once before NestFactory.create:

1. Returns immediately if RUN_MIGRATIONS === 'false' (bootstrap.ts:105).
2. runMigrations(prisma) applies pending .sql files and logs which were applied (bootstrap.ts:111-117).
3. Returns if RUN_SEED === 'false' (bootstrap.ts:119).
4. Resolves the seed script from SEED_SCRIPT / cwd/seed.js / ../../seed.js; warns and skips if none found (bootstrap.ts:12-19, 121-125).
5. runOnce(prisma, 'seed:initial', ...) spawns the seed as a child process, gated on a marker row so an interrupted seed is retried next boot (bootstrap.ts:127-131, comment :100-102).
6. Always $disconnect() in finally (bootstrap.ts:132-134).

Consequences worth noting: reconcileBalance (ledger.service.ts:289) is described as "run periodically" but has no scheduler; WalletBonus.expiresAt is never swept; GoldPriceQuote is never refreshed.

---

11. Env / config keys

No @nestjs/config / ConfigService anywhere — every value is read directly from process.env at module-evaluation or call time, which means JwtModule.register captures JWT_SECRET once at import (auth.module.ts:15-22).

Key	Used at	Default / fallback	Purpose
DATABASE_URL	prisma/schema.prisma:14 (env("DATABASE_URL"))	none (required)	Postgres connection
PORT	main.ts:37	3000	HTTP listen port
UPLOAD_DIR	main.ts:28, upload-path.ts:13	<cwd>/storage/uploads	upload read/write root
JWT_SECRET	auth.module.ts:16, jwt.strategy.ts:35	'dev-only-insecure-secret'	JWT signing + verification
JWT_EXPIRES_IN	auth.module.ts:20	'12h'	token lifetime
RUN_MIGRATIONS	bootstrap.ts:29	unset → migrations run; 'false' skips	boot-time migration switch
RUN_SEED	bootstrap.ts:43	unset → seed runs once; 'false' skips	boot-time seed switch
SEED_SCRIPT	bootstrap.ts:13	falls back to cwd/seed.js, ../../seed.js	seed script location
MIGRATIONS_DIR	migrate.ts:22	falls back to cwd/migrations, ../../migrations, ../../prisma/migrations, cwd/prisma/migrations	migrations location

.env.example declares only 2 of the 9: DATABASE_URL and PORT (.env.example:1-7). PORT must be kept in sync manually with the repo-root API_PORT because Nest/Prisma only load this app's own .env (.env.example:3-6). JWT_SECRET in particular is undocumented there, so a deployment that forgets it silently runs on the hardcoded dev secret.

---

12. Cross-cutting notes (evidence-backed)

#	Observation	Cite
1	15 routes are fully unauthenticated, including ledger writes (POST accounting/repayments/*, POST accounting/entries/:id/confirm) and order creation/status changes (POST orders, PATCH orders/:id/status)	accounting.controller.ts:7, orders.controller.ts:7
2	orders/dto/update-order-status.dto.ts accepts a client-supplied actorAdminUserId on a @Public() route, so audit actor is attacker-controlled there	update-order-status.dto.ts:12-14, orders.controller.ts:22-24
3	JWT_SECRET has an insecure hardcoded fallback duplicated in two files and is absent from .env.example	auth.module.ts:16, jwt.strategy.ts:35, .env.example
4	enableCors() with no options → Access-Control-Allow-Origin: * for every route	main.ts:25
5	ValidationPipe lacks forbidNonWhitelisted; most admin bodies are Record<string, unknown>, so whitelisting has nothing to strip	main.ts:23, e.g. admin-products.controller.ts:103
6	setRoles stores arbitrary strings as rids — no check against ALL_RIDS	admin-users.service.ts:317-332
7	Debt idempotency guard for DELIVERED_TO_AGENT tests deliveredAt, which is only set by DELIVERED_TO_CUSTOMER	orders.service.ts:120, 133
8	No status-transition validation — any OrderStatus reachable from any other	orders.service.ts:111-139
9	canPlaceOrders and verificationStep are toggled/stored but never enforced on any order path	admin-customers.service.ts:773-780, 790-816 vs orders.service.ts:32-109
10	reconcileBalance, postAdjustment, PricingService.recordQuote, and LedgerSourceType.WALLET_BONUS/ORDER_PRE_ORDER have no scheduled or in-app producer	ledger.service.ts:244-304, pricing.service.ts:9-13, schema.prisma:100,106
11	SVG accepted on upload and streamed back disposition: 'inline'	admin-uploads.service.ts:30, public-uploads.controller.ts:23-26
12	nationalCode (unique) silently defaults to the mobile number	admin-customers.service.ts:530, 567
13	Two distinct DTO classes share the name UpdateOrderStatusDto with different shapes	orders/dto/update-order-status.dto.ts:4, admin-orders/update-status.dto.ts:11
14	Grid exports (op: excel/json/print) are declared in the DTO but always 400	table-query.dto.ts:97-99, table.service.ts:150-157
15	The Setting table is never seeded; all config keys materialize on first write	seed.ts (no setting. call), admin-documents.service.ts:416-428
16	Seed ships a dev account whose password equals its phone number (09128081392) with SUPER_ADMIN + all 144 rids	seed.ts:23-24, 118-129