Outreach Service

@nx/outreach thu thập yêu cầu từ form liên hệ và đăng ký newsletter từ marketing site công khai. Khi submit, nó broadcast một WebSocket event real-time tới các room quan sát của admin. Đây là một leaf service không có Kafka và chỉ phụ thuộc nội bộ vào @nx/core.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/outreach
Code	SVC-00110-OUTREACH ⚠️ trùng với @nx/licensing (SVC-00110); không đăng ký trong core ServiceCodes
Loại	Microservice
Runtime	Bun
Base Class	VerifierApplication
Vị trí	packages/outreach
Base Path	/v1/api/outreach
Dev Port	31110
Container Port	3000 (external 31110)
Snowflake ID	10
DB Schema	outreach (2 bảng: Inquiry, Subscriber)
Binding Namespace	@nx/outreach
Owner	outreach-team

2. Mục đích & Phạm vi

Bao gồm	Không bao gồm
Thu thập yêu cầu contact / sales / demo / partner	Gửi email / SMTP (không có mail component)
Subscribe / unsubscribe newsletter (idempotent)	Publish Kafka event (không có)
Thống kê subscriber cho admin dashboard	Tự động hóa CRM pipeline (thủ công qua trường CRUD)
Thông báo WebSocket real-time khi có yêu cầu mới	Scope merchant đa-tenant (bảng global)

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, DI, BaseService, ControllerFactory, VerifierApplication
@venizia/ignis-helpers	WebSocketEmitter, HTTP, env helpers
hono	Framework HTTP server (qua IGNIS)
@hono/zod-openapi	Schema route → OpenAPI spec
@scalar/hono-api-reference	Viewer tương tác /doc
drizzle-orm	Truy cập DB qua PostgresCoreDataSource
pg	PostgreSQL driver

Nội bộ:

Package	Mục đích
@nx/core	Tất cả schema/repository (Inquiry, Subscriber), VerifierApplication, BaseSocketEventService, Redis factory, migration loader, repository permission/role/policy

@nx/core là phụ thuộc nội bộ duy nhất. Không có client service anh em.

4. Cấu trúc Project

packages/outreach/
├── src/
│   ├── application.ts          # Application extends VerifierApplication
│   ├── index.ts                # Entry → bootstrapApplication()
│   ├── migrate.ts              # Migration entry → bootstrapMigration()
│   ├── common/                 # RestPaths, constants, keys
│   ├── components/
│   │   └── websocket/          # ApplicationWebSocketComponent + OutreachSocketEventService
│   ├── controllers/
│   │   ├── inquiry/            # InquiryController (+ /submit)
│   │   ├── subscriber/         # SubscriberController (+ subscribe/unsubscribe/statistics)
│   │   └── permissions.ts      # OutreachPermissions (CRUD perms cho cả hai entity)
│   ├── datasources/            # PostgresCoreDataSource binding
│   ├── errors/                 # SubscriberErrors, WorkerErrors
│   ├── migrations/processes/   # 0001 seed-permissions, 0002 seed-role-permissions
│   ├── repositories/           # SubscriberRepository (custom getStatistics) + re-exports
│   └── services/               # SubscriberService
├── package.json
└── tsconfig.json

5. Architecture

Chi tiết: xem Architecture.

6. Snapshot Domain

Không có khóa ngoại giữa các entity — cả hai là bảng thu thập độc lập. ERD đầy đủ + bảng theo từng entity: xem Domain Model.

7. Tổng quan bề mặt

REST controllers (tham chiếu đầy đủ render trực tiếp từ /v1/api/outreach/doc/openapi.json):

Controller	Base path	Endpoints
InquiryController	/inquiries	7 (CRUD + /submit)
SubscriberController	/subscribers	9 (CRUD + /subscribe, /unsubscribe, /statistics)

Async topics (tham chiếu đầy đủ trong API Events):

Hướng	Số lượng
Inbound (Kafka)	0 (không có)
Outbound (Kafka)	0 (không có)
WebSocket out	1 (INQUIRY_SUBMITTED)
BullMQ jobs in	0
BullMQ jobs out	0

8. Components

Component	File	Mục đích
ApplicationWebSocketComponent	src/components/websocket/component.ts	Build WebSocketEmitter backed bởi Redis (single/cluster), bind nó, đăng ký OutreachSocketEventService

9. Services

Service	File	Mô tả ngắn
SubscriberService	src/services/subscriber.service.ts	Subscribe idempotent, unsubscribe theo token, tổng hợp thống kê
OutreachSocketEventService	src/components/websocket/socket-event.service.ts	Broadcast INQUIRY_SUBMITTED tới room quan sát (bind bởi component, không trong configureServices)

10. Repositories

Repository	Bảng	Nguồn	Method tùy chỉnh
InquiryRepository	outreach.Inquiry	@nx/core (re-export)	—
SubscriberRepository	outreach.Subscriber	extends core repo	getStatistics() — rollup một-query (total / monthlyNew / by-status)

11. Entry Points

File	Mục đích
src/index.ts	Service entry → bootstrapApplication()
src/migrate.ts	Migration entry → bootstrapMigration()
src/application.ts	Lớp Application extends VerifierApplication

12. Configuration

Env vars + feature flags + dữ liệu seed: xem Configuration.

13. Operations

Deployment + observability + security + runbook: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Decisions
• REST endpoints — OpenAPI trực tiếp tại /v1/api/outreach/doc/openapi.json