ตรวจสอบแก้ไชสร้างเอกสาร

2026-06-30 17:35:03 +07:00
parent a4fd166c51
commit e5766ea311
40 changed files with 8288 additions and 106 deletions
--- a/plans/task-p.7.1.md
+++ b/plans/task-p.7.1.md
@@ -0,0 +1,329 @@
+# Task P.7.1 - Notification Foundation
+
+## Objective
+Build a generic Notification Foundation for ALLA OS that supports event-driven notifications across multiple delivery channels.
+
+The first implementation target is `Email`, but the architecture must support future channels such as:
+- Email
+- Microsoft Teams
+- LINE OA
+- Slack
+- Mobile Push
+- SMS
+- Web Notification
+
+The Notification Foundation must not be coupled to CRM quotation only.
+
+## Background
+Completed phases:
+- P.4 PDF Runtime
+- P.5 Template Management
+- P.5.1 Production Hardening
+- P.6 Document Library
+- P.6.1 Document Sequence Refactor
+- P.7 Document Assembly Framework
+
+Current capability:
+
+```text
+Quotation -> Approved PDF -> Document Assembly -> Final Customer PDF
+```
+
+Next capability:
+
+```text
+Business Event -> Notification Event -> Notification Engine -> Email / Teams / LINE / Slack
+```
+
+## Discovery Requirement
+Before implementation, inspect the existing project and review at minimum:
+- AGENTS.md
+- authentication layer / RBAC
+- audit logging
+- storage abstraction
+- document assembly
+- document library
+- CRM approval flow
+- existing email utilities, if any
+- existing queue / background job infrastructure
+- existing scheduler / automation support
+
+Do not assume notification infrastructure already exists. Produce a discovery summary before implementation.
+
+## Design Principles
+The notification engine must be:
+- event-driven
+- channel-agnostic
+- template-driven
+- retryable
+- auditable
+- extensible
+
+Do not hardcode quotation logic inside the notification engine.
+
+## Core Architecture
+Design around:
+
+```text
+Business Event
+  -> Notification Event
+  -> Notification Dispatcher
+     -> Email
+     -> Teams
+     -> LINE OA
+     -> Slack
+     -> Future Providers
+```
+
+Business modules only publish events. They must not directly call SMTP or a provider SDK.
+
+## Notification Events
+Support generic events. Initial CRM events:
+- `quotation.created`
+- `quotation.submitted`
+- `quotation.approved`
+- `quotation.rejected`
+- `quotation.sent`
+- `quotation.cancelled`
+- `lead.assigned`
+- `opportunity.assigned`
+
+Future events:
+- `po.received`
+- `service.completed`
+- `maintenance.due`
+- `inventory.low`
+- `asset.expired`
+
+Events should carry payload only.
+
+## Notification Template
+Support reusable notification templates with fields:
+- `code`
+- `name`
+- `channel`
+- `subject`
+- `body`
+- `language`
+- `variables`
+- `active`
+- `version`
+
+Support placeholder replacement.
+
+Example:
+
+```text
+Dear {{customerName}}
+Your quotation {{quotationCode}} has been approved.
+
+Attached:
+- Quotation
+- SLA
+
+Thank you.
+```
+
+## Notification Channels
+Create a provider abstraction:
+
+```ts
+NotificationProvider
+```
+
+Methods:
+- `send()`
+- `validate()`
+- `healthCheck()`
+
+Implement `EmailProvider` only in this phase. Other providers remain placeholders.
+
+## Email Foundation
+Support:
+- SMTP
+- provider abstraction
+- HTML body
+- plain text fallback
+- multiple recipients
+- CC
+- BCC
+- Reply-To
+- attachments
+
+No provider lock-in.
+
+## Attachment Support
+Notification must support attachments such as:
+- approved PDF
+- final assembled PDF
+- SLA
+- warranty
+
+Attachments must come from the storage abstraction. Do not regenerate PDFs during sending.
+
+## Notification Queue
+Create a notification queue abstraction. Even if processed synchronously now, the architecture must allow future background processing.
+
+States:
+- `pending`
+- `sending`
+- `sent`
+- `failed`
+- `retry`
+
+## Notification Log
+Create notification history that tracks:
+- event
+- recipient
+- channel
+- template
+- subject
+- attachment list
+- status
+- error
+- retry count
+- createdAt
+- sentAt
+
+This becomes permanent delivery audit history.
+
+## Document Package Integration
+Integrate P.7 output.
+
+```text
+Quotation -> Approved PDF -> Assembly -> Document Package -> Notification
+```
+
+Notification must never rebuild PDFs. It must use stored artifacts only.
+
+## API Requirements
+Create APIs for:
+- send notification
+- resend notification
+- preview notification
+- list notifications
+- notification history
+- notification detail
+
+Notification sending should support:
+- recipient override
+- template override
+- attachment selection
+- dry-run preview
+
+## CRM Integration
+Do not automatically send emails yet. Instead provide service methods that CRM modules can call.
+
+Example:
+
+```text
+Quotation Approved -> Notification Service -> Email Provider
+```
+
+Future phases decide when automatic sending occurs.
+
+## RBAC
+Add permissions:
+- `notificationRead`
+- `notificationSend`
+- `notificationResend`
+- `notificationManageTemplate`
+- `notificationViewHistory`
+
+## Audit Logging
+Record:
+- notification requested
+- provider selected
+- send started
+- send succeeded
+- send failed
+- resend
+- template changed
+
+## Validation
+Validate:
+- recipient exists
+- valid email
+- template exists
+- attachment exists
+- storage object exists
+- provider available
+
+Return business-readable errors only.
+
+## Testing Requirements
+Add tests for:
+- template rendering
+- placeholder replacement
+- attachment resolution
+- provider abstraction
+- notification queue
+- failed send
+- retry
+- audit logging
+
+Run:
+
+```bash
+npm run typecheck
+npm run build
+npm run audit:pdf
+```
+
+## Acceptance Criteria
+- Generic Notification Engine exists.
+- Business modules publish notification events instead of calling providers directly.
+- Email provider abstraction is implemented.
+- Notification templates support placeholders.
+- Attachments resolve from stored artifacts.
+- Notification history is persisted.
+- Retry architecture exists.
+- Queue abstraction exists.
+- Notification service is reusable across ALLA OS.
+- No CRM module is tightly coupled to SMTP or a provider SDK.
+
+## Out of Scope
+
+### P.7.2
+- SMTP provider configuration UI
+- provider secrets management
+- SendGrid / Microsoft Graph / Resend implementation
+- email branding
+- DKIM / SPF guidance
+
+### P.7.3
+- automatic approval notifications
+- automatic quotation emails
+- customer email workflow
+- manager notifications
+
+### P.8
+- user notification preferences
+- subscription management
+- channel selection UI
+- notification scheduling
+
+## Final Success Condition
+Task P.7.1 is complete when ALLA OS has a reusable, event-driven Notification Foundation capable of rendering templates, resolving stored document artifacts, dispatching notifications through a provider abstraction (initially Email), persisting delivery history, and serving as the foundation for future notification channels without coupling business modules to specific delivery mechanisms.
+
+---
+
+## Implementation Status - 2026-06-30
+
+Current round completed:
+- reviewed existing notification, approval automation, storage, document artifact, and document assembly foundations before implementation
+- extended notification schema/contracts for generic dispatch history, richer templates, provider abstraction, and retry state
+- added SMTP-based `EmailNotificationProvider`
+- added reusable preview/send/resend/history/detail APIs under `/api/notifications/**`
+- added attachment resolution from stored artifacts and document-library files only
+- added tests for template rendering and retry queue execution
+- verified `npm run typecheck`, targeted notification tests, `npm run build`, and `npm run audit:pdf`
+
+Implementation notes:
+- [docs/implementation/task-p.7.1-implementation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7.1-implementation.md)
+- [docs/implementation/task-p.7.1-verification-report.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7.1-verification-report.md)
+
+Open follow-ups:
+- add dedicated seeded email templates for all initial CRM events instead of relying on fallback behavior
+- add template management UI and provider configuration UX
+- move dispatch processing to a background worker when scheduler / worker runtime is introduced