251117:2200 rebase .md
This commit is contained in:
@@ -1,192 +1,192 @@
|
||||
# FullStackJS Development Guidelines
|
||||
|
||||
## 🧠 General Philosophy
|
||||
|
||||
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
|
||||
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ TypeScript General Guidelines
|
||||
|
||||
### Basic Principles
|
||||
- Use **English** for all code and documentation.
|
||||
- Explicitly type all variables, parameters, and return values.
|
||||
- Avoid `any`; create custom types or interfaces.
|
||||
- Use **JSDoc** for public classes and methods.
|
||||
- Export only **one main symbol** per file.
|
||||
- Avoid blank lines within functions.
|
||||
|
||||
### Naming Conventions
|
||||
| Entity | Convention | Example |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Functions
|
||||
|
||||
- Write short, single-purpose functions (<20 lines).
|
||||
- Use **early returns** to reduce nesting.
|
||||
- Use **map**, **filter**, **reduce** instead of loops when suitable.
|
||||
- Prefer **arrow functions** for short logic, **named functions** otherwise.
|
||||
- Use **default parameters** over null checks.
|
||||
- Group multiple parameters into a single object (RO-RO pattern).
|
||||
- Return typed objects, not primitives.
|
||||
- Maintain a single abstraction level per function.
|
||||
|
||||
---
|
||||
|
||||
## 🧱 Data Handling
|
||||
|
||||
- Encapsulate data in composite types.
|
||||
- Use **immutability** with `readonly` and `as const`.
|
||||
- Perform validations in classes or DTOs, not within business functions.
|
||||
- Always validate data using typed DTOs.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Classes
|
||||
|
||||
- Follow **SOLID** principles.
|
||||
- Prefer **composition over inheritance**.
|
||||
- Define **interfaces** for contracts.
|
||||
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
- Use exceptions for unexpected errors.
|
||||
- Catch only to fix or add context; otherwise, use global error handlers.
|
||||
- Always provide meaningful error messages.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing (General)
|
||||
|
||||
- Use the **Arrange–Act–Assert** pattern.
|
||||
- Use descriptive test variable names (`inputData`, `expectedOutput`).
|
||||
- Write **unit tests** for all public methods.
|
||||
- Mock external dependencies.
|
||||
- Add **acceptance tests** per module using Given–When–Then.
|
||||
|
||||
---
|
||||
|
||||
# 🏗️ Backend (NestJS)
|
||||
|
||||
### Principles
|
||||
- **Modular architecture**:
|
||||
- One module per domain.
|
||||
- Controller → Service → Model structure.
|
||||
- DTOs validated with **class-validator**.
|
||||
- Use **MikroORM** or equivalent for persistence.
|
||||
- Encapsulate reusable code in a **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
|
||||
|
||||
### Core Functionalities
|
||||
- Global **filters** for exception handling.
|
||||
- **Middlewares** for request handling.
|
||||
- **Guards** for permissions and RBAC.
|
||||
- **Interceptors** for response transformation and logging.
|
||||
|
||||
### Testing
|
||||
- Use **Jest** for testing.
|
||||
- Test each controller and service.
|
||||
- Add `admin/test` endpoint as a smoke test.
|
||||
|
||||
---
|
||||
|
||||
# 🖥️ Frontend (NextJS / React)
|
||||
|
||||
### Developer Profile
|
||||
Senior-level TypeScript + React/NextJS engineer.
|
||||
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
|
||||
|
||||
### Code Implementation Guidelines
|
||||
- Use **early returns** for clarity.
|
||||
- Always style with **TailwindCSS** classes.
|
||||
- Prefer `class:` conditional syntax over ternary operators.
|
||||
- Use **const arrow functions** for components and handlers.
|
||||
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
|
||||
- Include accessibility attributes:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
|
||||
- Ensure all code is **complete**, **tested**, and **DRY**.
|
||||
- Always import required modules explicitly.
|
||||
|
||||
### UI/UX with React
|
||||
- Use **semantic HTML**.
|
||||
- Apply **responsive Tailwind** classes.
|
||||
- Maintain visual hierarchy with typography and spacing.
|
||||
- Use **Shadcn** components for consistent UI.
|
||||
- Keep components small and focused.
|
||||
|
||||
---
|
||||
|
||||
# 🎨 UI/UX (Bootstrap Integration)
|
||||
|
||||
### Key Principles
|
||||
- Use **Bootstrap 5+** for responsive design and consistent UI.
|
||||
- Focus on **maintainability**, **readability**, and **accessibility**.
|
||||
- Use clear and descriptive class names.
|
||||
|
||||
### Bootstrap Usage
|
||||
- Structure layout with **container**, **row**, **col**.
|
||||
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
|
||||
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
|
||||
- Ensure **ARIA compliance** and semantic markup.
|
||||
|
||||
### Form Validation & Errors
|
||||
- Use Bootstrap’s built-in validation states.
|
||||
- Show errors with **alert components**.
|
||||
- Include labels, placeholders, and feedback messages.
|
||||
|
||||
### Dependencies
|
||||
- Bootstrap (latest CSS + JS)
|
||||
- Optionally jQuery (for legacy interactive components)
|
||||
|
||||
### Bootstrap-Specific Guidelines
|
||||
- Customize Bootstrap via **Sass variables** and **mixins**.
|
||||
- Use responsive visibility utilities.
|
||||
- Avoid overriding Bootstrap; extend it.
|
||||
- Follow official documentation for examples.
|
||||
|
||||
### Performance Optimization
|
||||
- Include only necessary Bootstrap modules.
|
||||
- Use CDN for assets and caching.
|
||||
- Optimize images and assets for mobile.
|
||||
|
||||
### Key Conventions
|
||||
1. Follow Bootstrap’s naming and structure.
|
||||
2. Prioritize **responsiveness** and **accessibility**.
|
||||
3. Keep the file structure organized and modular.
|
||||
|
||||
---
|
||||
|
||||
# 🔗 Full Stack Integration Guidelines
|
||||
|
||||
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
|
||||
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
|
||||
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
|
||||
| Errors | Global filters | Toasts / modals | Alerts / feedback |
|
||||
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
|
||||
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
---
|
||||
|
||||
# ✅ Final Notes
|
||||
|
||||
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
|
||||
- Document your modules and APIs.
|
||||
- Run lint, type-check, and tests before commit.
|
||||
- Use **Prettier + ESLint** for consistent formatting.
|
||||
- Prefer **clarity over cleverness** — readable code wins.
|
||||
# FullStackJS Development Guidelines
|
||||
|
||||
## 🧠 General Philosophy
|
||||
|
||||
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
|
||||
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ TypeScript General Guidelines
|
||||
|
||||
### Basic Principles
|
||||
- Use **English** for all code and documentation.
|
||||
- Explicitly type all variables, parameters, and return values.
|
||||
- Avoid `any`; create custom types or interfaces.
|
||||
- Use **JSDoc** for public classes and methods.
|
||||
- Export only **one main symbol** per file.
|
||||
- Avoid blank lines within functions.
|
||||
|
||||
### Naming Conventions
|
||||
| Entity | Convention | Example |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Functions
|
||||
|
||||
- Write short, single-purpose functions (<20 lines).
|
||||
- Use **early returns** to reduce nesting.
|
||||
- Use **map**, **filter**, **reduce** instead of loops when suitable.
|
||||
- Prefer **arrow functions** for short logic, **named functions** otherwise.
|
||||
- Use **default parameters** over null checks.
|
||||
- Group multiple parameters into a single object (RO-RO pattern).
|
||||
- Return typed objects, not primitives.
|
||||
- Maintain a single abstraction level per function.
|
||||
|
||||
---
|
||||
|
||||
## 🧱 Data Handling
|
||||
|
||||
- Encapsulate data in composite types.
|
||||
- Use **immutability** with `readonly` and `as const`.
|
||||
- Perform validations in classes or DTOs, not within business functions.
|
||||
- Always validate data using typed DTOs.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Classes
|
||||
|
||||
- Follow **SOLID** principles.
|
||||
- Prefer **composition over inheritance**.
|
||||
- Define **interfaces** for contracts.
|
||||
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
- Use exceptions for unexpected errors.
|
||||
- Catch only to fix or add context; otherwise, use global error handlers.
|
||||
- Always provide meaningful error messages.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing (General)
|
||||
|
||||
- Use the **Arrange–Act–Assert** pattern.
|
||||
- Use descriptive test variable names (`inputData`, `expectedOutput`).
|
||||
- Write **unit tests** for all public methods.
|
||||
- Mock external dependencies.
|
||||
- Add **acceptance tests** per module using Given–When–Then.
|
||||
|
||||
---
|
||||
|
||||
# 🏗️ Backend (NestJS)
|
||||
|
||||
### Principles
|
||||
- **Modular architecture**:
|
||||
- One module per domain.
|
||||
- Controller → Service → Model structure.
|
||||
- DTOs validated with **class-validator**.
|
||||
- Use **MikroORM** or equivalent for persistence.
|
||||
- Encapsulate reusable code in a **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
|
||||
|
||||
### Core Functionalities
|
||||
- Global **filters** for exception handling.
|
||||
- **Middlewares** for request handling.
|
||||
- **Guards** for permissions and RBAC.
|
||||
- **Interceptors** for response transformation and logging.
|
||||
|
||||
### Testing
|
||||
- Use **Jest** for testing.
|
||||
- Test each controller and service.
|
||||
- Add `admin/test` endpoint as a smoke test.
|
||||
|
||||
---
|
||||
|
||||
# 🖥️ Frontend (NextJS / React)
|
||||
|
||||
### Developer Profile
|
||||
Senior-level TypeScript + React/NextJS engineer.
|
||||
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
|
||||
|
||||
### Code Implementation Guidelines
|
||||
- Use **early returns** for clarity.
|
||||
- Always style with **TailwindCSS** classes.
|
||||
- Prefer `class:` conditional syntax over ternary operators.
|
||||
- Use **const arrow functions** for components and handlers.
|
||||
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
|
||||
- Include accessibility attributes:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
|
||||
- Ensure all code is **complete**, **tested**, and **DRY**.
|
||||
- Always import required modules explicitly.
|
||||
|
||||
### UI/UX with React
|
||||
- Use **semantic HTML**.
|
||||
- Apply **responsive Tailwind** classes.
|
||||
- Maintain visual hierarchy with typography and spacing.
|
||||
- Use **Shadcn** components for consistent UI.
|
||||
- Keep components small and focused.
|
||||
|
||||
---
|
||||
|
||||
# 🎨 UI/UX (Bootstrap Integration)
|
||||
|
||||
### Key Principles
|
||||
- Use **Bootstrap 5+** for responsive design and consistent UI.
|
||||
- Focus on **maintainability**, **readability**, and **accessibility**.
|
||||
- Use clear and descriptive class names.
|
||||
|
||||
### Bootstrap Usage
|
||||
- Structure layout with **container**, **row**, **col**.
|
||||
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
|
||||
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
|
||||
- Ensure **ARIA compliance** and semantic markup.
|
||||
|
||||
### Form Validation & Errors
|
||||
- Use Bootstrap’s built-in validation states.
|
||||
- Show errors with **alert components**.
|
||||
- Include labels, placeholders, and feedback messages.
|
||||
|
||||
### Dependencies
|
||||
- Bootstrap (latest CSS + JS)
|
||||
- Optionally jQuery (for legacy interactive components)
|
||||
|
||||
### Bootstrap-Specific Guidelines
|
||||
- Customize Bootstrap via **Sass variables** and **mixins**.
|
||||
- Use responsive visibility utilities.
|
||||
- Avoid overriding Bootstrap; extend it.
|
||||
- Follow official documentation for examples.
|
||||
|
||||
### Performance Optimization
|
||||
- Include only necessary Bootstrap modules.
|
||||
- Use CDN for assets and caching.
|
||||
- Optimize images and assets for mobile.
|
||||
|
||||
### Key Conventions
|
||||
1. Follow Bootstrap’s naming and structure.
|
||||
2. Prioritize **responsiveness** and **accessibility**.
|
||||
3. Keep the file structure organized and modular.
|
||||
|
||||
---
|
||||
|
||||
# 🔗 Full Stack Integration Guidelines
|
||||
|
||||
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
|
||||
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
|
||||
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
|
||||
| Errors | Global filters | Toasts / modals | Alerts / feedback |
|
||||
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
|
||||
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
---
|
||||
|
||||
# ✅ Final Notes
|
||||
|
||||
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
|
||||
- Document your modules and APIs.
|
||||
- Run lint, type-check, and tests before commit.
|
||||
- Use **Prettier + ESLint** for consistent formatting.
|
||||
- Prefer **clarity over cleverness** — readable code wins.
|
||||
|
||||
@@ -1,364 +1,364 @@
|
||||
# FullStackJS Development Guidelines
|
||||
|
||||
## 🧠 General Philosophy
|
||||
|
||||
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
|
||||
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ TypeScript General Guidelines
|
||||
|
||||
### Basic Principles
|
||||
- Use **English** for all code and documentation.
|
||||
- Explicitly type all variables, parameters, and return values.
|
||||
- Avoid `any`; create custom types or interfaces.
|
||||
- Use **JSDoc** for public classes and methods.
|
||||
- Export only **one main symbol** per file.
|
||||
- Avoid blank lines within functions.
|
||||
|
||||
### Naming Conventions
|
||||
| Entity | Convention | Example |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Functions
|
||||
|
||||
- Write short, single-purpose functions (<20 lines).
|
||||
- Use **early returns** to reduce nesting.
|
||||
- Use **map**, **filter**, **reduce** instead of loops when suitable.
|
||||
- Prefer **arrow functions** for short logic, **named functions** otherwise.
|
||||
- Use **default parameters** over null checks.
|
||||
- Group multiple parameters into a single object (RO-RO pattern).
|
||||
- Return typed objects, not primitives.
|
||||
- Maintain a single abstraction level per function.
|
||||
|
||||
---
|
||||
|
||||
## 🧱 Data Handling
|
||||
|
||||
- Encapsulate data in composite types.
|
||||
- Use **immutability** with `readonly` and `as const`.
|
||||
- Perform validations in classes or DTOs, not within business functions.
|
||||
- Always validate data using typed DTOs.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Classes
|
||||
|
||||
- Follow **SOLID** principles.
|
||||
- Prefer **composition over inheritance**.
|
||||
- Define **interfaces** for contracts.
|
||||
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
- Use exceptions for unexpected errors.
|
||||
- Catch only to fix or add context; otherwise, use global error handlers.
|
||||
- Always provide meaningful error messages.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing (General)
|
||||
|
||||
- Use the **Arrange–Act–Assert** pattern.
|
||||
- Use descriptive test variable names (`inputData`, `expectedOutput`).
|
||||
- Write **unit tests** for all public methods.
|
||||
- Mock external dependencies.
|
||||
- Add **acceptance tests** per module using Given–When–Then.
|
||||
|
||||
---
|
||||
|
||||
# 🏗️ Backend (NestJS)
|
||||
|
||||
### Principles
|
||||
- **Modular architecture**:
|
||||
- One module per domain.
|
||||
- Controller → Service → Model structure.
|
||||
- DTOs validated with **class-validator**.
|
||||
- Use **MikroORM** or equivalent for persistence.
|
||||
- Encapsulate reusable code in a **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
|
||||
|
||||
### Core Functionalities
|
||||
- Global **filters** for exception handling.
|
||||
- **Middlewares** for request handling.
|
||||
- **Guards** for permissions and RBAC.
|
||||
- **Interceptors** for response transformation and logging.
|
||||
|
||||
### Testing
|
||||
- Use **Jest** for testing.
|
||||
- Test each controller and service.
|
||||
- Add `admin/test` endpoint as a smoke test.
|
||||
|
||||
---
|
||||
|
||||
# 🖥️ Frontend (NextJS / React)
|
||||
|
||||
### Developer Profile
|
||||
Senior-level TypeScript + React/NextJS engineer.
|
||||
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
|
||||
|
||||
### Code Implementation Guidelines
|
||||
- Use **early returns** for clarity.
|
||||
- Always style with **TailwindCSS** classes.
|
||||
- Prefer `class:` conditional syntax over ternary operators.
|
||||
- Use **const arrow functions** for components and handlers.
|
||||
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
|
||||
- Include accessibility attributes:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
|
||||
- Ensure all code is **complete**, **tested**, and **DRY**.
|
||||
- Always import required modules explicitly.
|
||||
|
||||
### UI/UX with React
|
||||
- Use **semantic HTML**.
|
||||
- Apply **responsive Tailwind** classes.
|
||||
- Maintain visual hierarchy with typography and spacing.
|
||||
- Use **Shadcn** components for consistent UI.
|
||||
- Keep components small and focused.
|
||||
|
||||
---
|
||||
|
||||
# 🎨 UI/UX (Bootstrap Integration)
|
||||
|
||||
### Key Principles
|
||||
- Use **Bootstrap 5+** for responsive design and consistent UI.
|
||||
- Focus on **maintainability**, **readability**, and **accessibility**.
|
||||
- Use clear and descriptive class names.
|
||||
|
||||
### Bootstrap Usage
|
||||
- Structure layout with **container**, **row**, **col**.
|
||||
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
|
||||
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
|
||||
- Ensure **ARIA compliance** and semantic markup.
|
||||
|
||||
### Form Validation & Errors
|
||||
- Use Bootstrap’s built-in validation states.
|
||||
- Show errors with **alert components**.
|
||||
- Include labels, placeholders, and feedback messages.
|
||||
|
||||
### Dependencies
|
||||
- Bootstrap (latest CSS + JS)
|
||||
- Optionally jQuery (for legacy interactive components)
|
||||
|
||||
### Bootstrap-Specific Guidelines
|
||||
- Customize Bootstrap via **Sass variables** and **mixins**.
|
||||
- Use responsive visibility utilities.
|
||||
- Avoid overriding Bootstrap; extend it.
|
||||
- Follow official documentation for examples.
|
||||
|
||||
### Performance Optimization
|
||||
- Include only necessary Bootstrap modules.
|
||||
- Use CDN for assets and caching.
|
||||
- Optimize images and assets for mobile.
|
||||
|
||||
### Key Conventions
|
||||
1. Follow Bootstrap’s naming and structure.
|
||||
2. Prioritize **responsiveness** and **accessibility**.
|
||||
3. Keep the file structure organized and modular.
|
||||
|
||||
---
|
||||
|
||||
# 🔗 Full Stack Integration Guidelines
|
||||
|
||||
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
|
||||
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
|
||||
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
|
||||
| Errors | Global filters | Toasts / modals | Alerts / feedback |
|
||||
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
|
||||
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
---
|
||||
|
||||
# ✅ Final Notes
|
||||
|
||||
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
|
||||
- Document your modules and APIs.
|
||||
- Run lint, type-check, and tests before commit.
|
||||
- Use **Prettier + ESLint** for consistent formatting.
|
||||
- Prefer **clarity over cleverness** — readable code wins.
|
||||
|
||||
|
||||
---
|
||||
|
||||
# 🗂️ DMS-Specific Conventions (Document Management System)
|
||||
|
||||
This section extends the general FullStackJS guidelines for projects similar to **np‑dms.work**, focusing on document approval workflows (RFA, Drawing, Contract, Revision, Transmittal, Report).
|
||||
|
||||
## 🧱 Backend Domain Modules
|
||||
|
||||
Use modular domain structure per document type:
|
||||
|
||||
```
|
||||
src/
|
||||
├─ modules/
|
||||
│ ├─ rfas/
|
||||
│ ├─ drawings/
|
||||
│ ├─ contracts/
|
||||
│ ├─ transmittals/
|
||||
│ ├─ audit-log/
|
||||
│ ├─ users/
|
||||
│ └─ common/
|
||||
```
|
||||
|
||||
### Naming Convention
|
||||
| Entity | Example |
|
||||
|:--|:--|
|
||||
| Table | `rfa_revisions`, `drawing_contracts` |
|
||||
| DTO | `CreateRfaDto`, `UpdateContractDto` |
|
||||
| Controller | `rfas.controller.ts` |
|
||||
| Service | `rfas.service.ts` |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 RBAC & Permission Control
|
||||
|
||||
Use decorators to enforce access rights:
|
||||
|
||||
```ts
|
||||
@RequirePermission('rfa.update')
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
```
|
||||
|
||||
### Roles
|
||||
- **Admin**: Full access to all modules.
|
||||
- **Editor**: Modify data within assigned modules.
|
||||
- **Viewer**: Read‑only access.
|
||||
|
||||
### Permissions
|
||||
- `rfa.create`, `rfa.update`, `rfa.delete`, `rfa.view`
|
||||
- `drawing.upload`, `drawing.map`, `drawing.view`
|
||||
- `contract.assign`, `contract.view`
|
||||
|
||||
Seed mapping between roles and permissions via seeder scripts.
|
||||
|
||||
---
|
||||
|
||||
## 🧾 AuditLog Standard
|
||||
|
||||
Log all CRUD and mapping operations:
|
||||
|
||||
| Field | Description |
|
||||
|:--|:--|
|
||||
| `actor_id` | user performing the action |
|
||||
| `module_name` | e.g. `rfa`, `drawing` |
|
||||
| `action` | `create`, `update`, `delete`, `map` |
|
||||
| `target_id` | primary id of the record |
|
||||
| `timestamp` | UTC timestamp |
|
||||
| `description` | contextual note |
|
||||
|
||||
Example implementation:
|
||||
|
||||
```ts
|
||||
await this.auditLogService.log({
|
||||
actorId: user.id,
|
||||
moduleName: 'rfa',
|
||||
action: 'update',
|
||||
targetId: rfa.id,
|
||||
description: `Updated revision ${rev}`,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 File Handling
|
||||
|
||||
### File Upload Standard
|
||||
- Upload path: `/storage/{year}/{month}/`
|
||||
- File naming: `{drawing_code}_{revision}_{timestamp}.pdf`
|
||||
- Allowed types: `pdf, dwg, docx, xlsx, zip`
|
||||
- Max size: **50 MB**
|
||||
- Store outside webroot.
|
||||
- Serve via secure endpoint `/files/:id/download`.
|
||||
|
||||
### Access Control
|
||||
Each file download must verify user permission (`hasPermission('drawing.view')`).
|
||||
|
||||
---
|
||||
|
||||
## 📊 Reporting & Exports
|
||||
|
||||
| Report | Description |
|
||||
|:--|:--|
|
||||
| **Report A** | RFA → Drawings → All Drawing Revisions |
|
||||
| **Report B** | RFA Revision Timeline vs Drawing Revision |
|
||||
| **Dashboard KPI** | RFAs, Drawings, Revisions, Transmittals summary |
|
||||
|
||||
### Export Rules
|
||||
- Export formats: CSV, Excel, PDF.
|
||||
- Provide print view.
|
||||
- Include source entity link (e.g., `/rfas/:id`).
|
||||
|
||||
---
|
||||
|
||||
## 🧮 Frontend: DataTable & Form Patterns
|
||||
|
||||
### DataTable (Server‑Side)
|
||||
- Endpoint: `/api/{module}?page=1&pageSize=20`
|
||||
- Must support: pagination, sorting, search, filters.
|
||||
- Always display latest revision inline (for RFA/Drawing).
|
||||
|
||||
### Form Standards
|
||||
- Dependent dropdowns:
|
||||
- Contract → Subcategory
|
||||
- RFA → Related Drawing
|
||||
- File upload: preview + validation.
|
||||
- Submit via API with toast feedback.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Dashboard & Activity Feed
|
||||
|
||||
### Dashboard Cards
|
||||
- Show latest RFA, Drawing, Transmittal, KPI summary.
|
||||
- Include quick links to modules.
|
||||
|
||||
### Activity Feed
|
||||
- Display recent AuditLog actions (10 latest).
|
||||
|
||||
```ts
|
||||
// Example response
|
||||
[
|
||||
{ user: 'admin', action: 'Updated RFA 023-Rev02', time: '2025‑11‑04T09:30Z' }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Integration Summary
|
||||
|
||||
| Aspect | Backend | Frontend | Description |
|
||||
|:--|:--|:--|
|
||||
| **File Handling** | Secure storage, token check | Upload/Preview UI | Consistent standard path |
|
||||
| **RBAC** | `RequirePermission` guard | Hide/disable UI actions | Unified permission logic |
|
||||
| **AuditLog** | Persist actions | Show in dashboard | Traceable user activity |
|
||||
| **Reports** | Aggregation queries | Export + Print | Consistent data pipeline |
|
||||
| **DataTables** | Server‑side paging | Filter/Search UI | Scalable dataset management |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Recommended Enhancements
|
||||
|
||||
- ✅ Add `deleted_at` for soft delete + restore.
|
||||
- ✅ Fulltext search + date filters.
|
||||
- ✅ Background job for RFA deadline reminders.
|
||||
- ✅ Optimize DB with indexes on `rfa_id`, `drawing_id`, `contract_id`.
|
||||
- ✅ Periodic cleanup for unused file uploads.
|
||||
|
||||
---
|
||||
# FullStackJS Development Guidelines
|
||||
|
||||
## 🧠 General Philosophy
|
||||
|
||||
Unified best practices for **NestJS Backend**, **NextJS Frontend**, and **Bootstrap-based UI/UX** development in TypeScript environments.
|
||||
Focus on **clarity**, **maintainability**, **consistency**, and **accessibility** across the entire stack.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ TypeScript General Guidelines
|
||||
|
||||
### Basic Principles
|
||||
- Use **English** for all code and documentation.
|
||||
- Explicitly type all variables, parameters, and return values.
|
||||
- Avoid `any`; create custom types or interfaces.
|
||||
- Use **JSDoc** for public classes and methods.
|
||||
- Export only **one main symbol** per file.
|
||||
- Avoid blank lines within functions.
|
||||
|
||||
### Naming Conventions
|
||||
| Entity | Convention | Example |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
Use full words — no abbreviations — except for standard ones (`API`, `URL`, `req`, `res`, `err`, `ctx`).
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Functions
|
||||
|
||||
- Write short, single-purpose functions (<20 lines).
|
||||
- Use **early returns** to reduce nesting.
|
||||
- Use **map**, **filter**, **reduce** instead of loops when suitable.
|
||||
- Prefer **arrow functions** for short logic, **named functions** otherwise.
|
||||
- Use **default parameters** over null checks.
|
||||
- Group multiple parameters into a single object (RO-RO pattern).
|
||||
- Return typed objects, not primitives.
|
||||
- Maintain a single abstraction level per function.
|
||||
|
||||
---
|
||||
|
||||
## 🧱 Data Handling
|
||||
|
||||
- Encapsulate data in composite types.
|
||||
- Use **immutability** with `readonly` and `as const`.
|
||||
- Perform validations in classes or DTOs, not within business functions.
|
||||
- Always validate data using typed DTOs.
|
||||
|
||||
---
|
||||
|
||||
## 🧰 Classes
|
||||
|
||||
- Follow **SOLID** principles.
|
||||
- Prefer **composition over inheritance**.
|
||||
- Define **interfaces** for contracts.
|
||||
- Keep classes focused and small (<200 lines, <10 methods, <10 properties).
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
- Use exceptions for unexpected errors.
|
||||
- Catch only to fix or add context; otherwise, use global error handlers.
|
||||
- Always provide meaningful error messages.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing (General)
|
||||
|
||||
- Use the **Arrange–Act–Assert** pattern.
|
||||
- Use descriptive test variable names (`inputData`, `expectedOutput`).
|
||||
- Write **unit tests** for all public methods.
|
||||
- Mock external dependencies.
|
||||
- Add **acceptance tests** per module using Given–When–Then.
|
||||
|
||||
---
|
||||
|
||||
# 🏗️ Backend (NestJS)
|
||||
|
||||
### Principles
|
||||
- **Modular architecture**:
|
||||
- One module per domain.
|
||||
- Controller → Service → Model structure.
|
||||
- DTOs validated with **class-validator**.
|
||||
- Use **MikroORM** or equivalent for persistence.
|
||||
- Encapsulate reusable code in a **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators.
|
||||
|
||||
### Core Functionalities
|
||||
- Global **filters** for exception handling.
|
||||
- **Middlewares** for request handling.
|
||||
- **Guards** for permissions and RBAC.
|
||||
- **Interceptors** for response transformation and logging.
|
||||
|
||||
### Testing
|
||||
- Use **Jest** for testing.
|
||||
- Test each controller and service.
|
||||
- Add `admin/test` endpoint as a smoke test.
|
||||
|
||||
---
|
||||
|
||||
# 🖥️ Frontend (NextJS / React)
|
||||
|
||||
### Developer Profile
|
||||
Senior-level TypeScript + React/NextJS engineer.
|
||||
Expert in **TailwindCSS**, **Shadcn/UI**, and **Radix** for UI development.
|
||||
|
||||
### Code Implementation Guidelines
|
||||
- Use **early returns** for clarity.
|
||||
- Always style with **TailwindCSS** classes.
|
||||
- Prefer `class:` conditional syntax over ternary operators.
|
||||
- Use **const arrow functions** for components and handlers.
|
||||
- Event handlers start with `handle...` (e.g., `handleClick`, `handleSubmit`).
|
||||
- Include accessibility attributes:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, etc.
|
||||
- Ensure all code is **complete**, **tested**, and **DRY**.
|
||||
- Always import required modules explicitly.
|
||||
|
||||
### UI/UX with React
|
||||
- Use **semantic HTML**.
|
||||
- Apply **responsive Tailwind** classes.
|
||||
- Maintain visual hierarchy with typography and spacing.
|
||||
- Use **Shadcn** components for consistent UI.
|
||||
- Keep components small and focused.
|
||||
|
||||
---
|
||||
|
||||
# 🎨 UI/UX (Bootstrap Integration)
|
||||
|
||||
### Key Principles
|
||||
- Use **Bootstrap 5+** for responsive design and consistent UI.
|
||||
- Focus on **maintainability**, **readability**, and **accessibility**.
|
||||
- Use clear and descriptive class names.
|
||||
|
||||
### Bootstrap Usage
|
||||
- Structure layout with **container**, **row**, **col**.
|
||||
- Use built-in **components** (buttons, modals, alerts, etc.) instead of custom CSS.
|
||||
- Apply **utility classes** for quick styling (spacing, colors, text, etc.).
|
||||
- Ensure **ARIA compliance** and semantic markup.
|
||||
|
||||
### Form Validation & Errors
|
||||
- Use Bootstrap’s built-in validation states.
|
||||
- Show errors with **alert components**.
|
||||
- Include labels, placeholders, and feedback messages.
|
||||
|
||||
### Dependencies
|
||||
- Bootstrap (latest CSS + JS)
|
||||
- Optionally jQuery (for legacy interactive components)
|
||||
|
||||
### Bootstrap-Specific Guidelines
|
||||
- Customize Bootstrap via **Sass variables** and **mixins**.
|
||||
- Use responsive visibility utilities.
|
||||
- Avoid overriding Bootstrap; extend it.
|
||||
- Follow official documentation for examples.
|
||||
|
||||
### Performance Optimization
|
||||
- Include only necessary Bootstrap modules.
|
||||
- Use CDN for assets and caching.
|
||||
- Optimize images and assets for mobile.
|
||||
|
||||
### Key Conventions
|
||||
1. Follow Bootstrap’s naming and structure.
|
||||
2. Prioritize **responsiveness** and **accessibility**.
|
||||
3. Keep the file structure organized and modular.
|
||||
|
||||
---
|
||||
|
||||
# 🔗 Full Stack Integration Guidelines
|
||||
|
||||
| Aspect | Backend (NestJS) | Frontend (NextJS) | UI Layer (Bootstrap/Tailwind) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks via fetch/axios | Components consuming data |
|
||||
| Validation | `class-validator` DTOs | `zod` / form-level validation | Bootstrap validation feedback |
|
||||
| Auth | Guards, JWT | NextAuth / cookies | Auth UI states |
|
||||
| Errors | Global filters | Toasts / modals | Alerts / feedback |
|
||||
| Testing | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles | Scoped modules | Tailwind / Shadcn | Bootstrap utilities |
|
||||
| Accessibility | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
---
|
||||
|
||||
# ✅ Final Notes
|
||||
|
||||
- Use a **shared types package** (`@types/shared`) for consistent interfaces.
|
||||
- Document your modules and APIs.
|
||||
- Run lint, type-check, and tests before commit.
|
||||
- Use **Prettier + ESLint** for consistent formatting.
|
||||
- Prefer **clarity over cleverness** — readable code wins.
|
||||
|
||||
|
||||
---
|
||||
|
||||
# 🗂️ DMS-Specific Conventions (Document Management System)
|
||||
|
||||
This section extends the general FullStackJS guidelines for projects similar to **np‑dms.work**, focusing on document approval workflows (RFA, Drawing, Contract, Revision, Transmittal, Report).
|
||||
|
||||
## 🧱 Backend Domain Modules
|
||||
|
||||
Use modular domain structure per document type:
|
||||
|
||||
```
|
||||
src/
|
||||
├─ modules/
|
||||
│ ├─ rfas/
|
||||
│ ├─ drawings/
|
||||
│ ├─ contracts/
|
||||
│ ├─ transmittals/
|
||||
│ ├─ audit-log/
|
||||
│ ├─ users/
|
||||
│ └─ common/
|
||||
```
|
||||
|
||||
### Naming Convention
|
||||
| Entity | Example |
|
||||
|:--|:--|
|
||||
| Table | `rfa_revisions`, `drawing_contracts` |
|
||||
| DTO | `CreateRfaDto`, `UpdateContractDto` |
|
||||
| Controller | `rfas.controller.ts` |
|
||||
| Service | `rfas.service.ts` |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 RBAC & Permission Control
|
||||
|
||||
Use decorators to enforce access rights:
|
||||
|
||||
```ts
|
||||
@RequirePermission('rfa.update')
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
```
|
||||
|
||||
### Roles
|
||||
- **Admin**: Full access to all modules.
|
||||
- **Editor**: Modify data within assigned modules.
|
||||
- **Viewer**: Read‑only access.
|
||||
|
||||
### Permissions
|
||||
- `rfa.create`, `rfa.update`, `rfa.delete`, `rfa.view`
|
||||
- `drawing.upload`, `drawing.map`, `drawing.view`
|
||||
- `contract.assign`, `contract.view`
|
||||
|
||||
Seed mapping between roles and permissions via seeder scripts.
|
||||
|
||||
---
|
||||
|
||||
## 🧾 AuditLog Standard
|
||||
|
||||
Log all CRUD and mapping operations:
|
||||
|
||||
| Field | Description |
|
||||
|:--|:--|
|
||||
| `actor_id` | user performing the action |
|
||||
| `module_name` | e.g. `rfa`, `drawing` |
|
||||
| `action` | `create`, `update`, `delete`, `map` |
|
||||
| `target_id` | primary id of the record |
|
||||
| `timestamp` | UTC timestamp |
|
||||
| `description` | contextual note |
|
||||
|
||||
Example implementation:
|
||||
|
||||
```ts
|
||||
await this.auditLogService.log({
|
||||
actorId: user.id,
|
||||
moduleName: 'rfa',
|
||||
action: 'update',
|
||||
targetId: rfa.id,
|
||||
description: `Updated revision ${rev}`,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 File Handling
|
||||
|
||||
### File Upload Standard
|
||||
- Upload path: `/storage/{year}/{month}/`
|
||||
- File naming: `{drawing_code}_{revision}_{timestamp}.pdf`
|
||||
- Allowed types: `pdf, dwg, docx, xlsx, zip`
|
||||
- Max size: **50 MB**
|
||||
- Store outside webroot.
|
||||
- Serve via secure endpoint `/files/:id/download`.
|
||||
|
||||
### Access Control
|
||||
Each file download must verify user permission (`hasPermission('drawing.view')`).
|
||||
|
||||
---
|
||||
|
||||
## 📊 Reporting & Exports
|
||||
|
||||
| Report | Description |
|
||||
|:--|:--|
|
||||
| **Report A** | RFA → Drawings → All Drawing Revisions |
|
||||
| **Report B** | RFA Revision Timeline vs Drawing Revision |
|
||||
| **Dashboard KPI** | RFAs, Drawings, Revisions, Transmittals summary |
|
||||
|
||||
### Export Rules
|
||||
- Export formats: CSV, Excel, PDF.
|
||||
- Provide print view.
|
||||
- Include source entity link (e.g., `/rfas/:id`).
|
||||
|
||||
---
|
||||
|
||||
## 🧮 Frontend: DataTable & Form Patterns
|
||||
|
||||
### DataTable (Server‑Side)
|
||||
- Endpoint: `/api/{module}?page=1&pageSize=20`
|
||||
- Must support: pagination, sorting, search, filters.
|
||||
- Always display latest revision inline (for RFA/Drawing).
|
||||
|
||||
### Form Standards
|
||||
- Dependent dropdowns:
|
||||
- Contract → Subcategory
|
||||
- RFA → Related Drawing
|
||||
- File upload: preview + validation.
|
||||
- Submit via API with toast feedback.
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Dashboard & Activity Feed
|
||||
|
||||
### Dashboard Cards
|
||||
- Show latest RFA, Drawing, Transmittal, KPI summary.
|
||||
- Include quick links to modules.
|
||||
|
||||
### Activity Feed
|
||||
- Display recent AuditLog actions (10 latest).
|
||||
|
||||
```ts
|
||||
// Example response
|
||||
[
|
||||
{ user: 'admin', action: 'Updated RFA 023-Rev02', time: '2025‑11‑04T09:30Z' }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Integration Summary
|
||||
|
||||
| Aspect | Backend | Frontend | Description |
|
||||
|:--|:--|:--|
|
||||
| **File Handling** | Secure storage, token check | Upload/Preview UI | Consistent standard path |
|
||||
| **RBAC** | `RequirePermission` guard | Hide/disable UI actions | Unified permission logic |
|
||||
| **AuditLog** | Persist actions | Show in dashboard | Traceable user activity |
|
||||
| **Reports** | Aggregation queries | Export + Print | Consistent data pipeline |
|
||||
| **DataTables** | Server‑side paging | Filter/Search UI | Scalable dataset management |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Recommended Enhancements
|
||||
|
||||
- ✅ Add `deleted_at` for soft delete + restore.
|
||||
- ✅ Fulltext search + date filters.
|
||||
- ✅ Background job for RFA deadline reminders.
|
||||
- ✅ Optimize DB with indexes on `rfa_id`, `drawing_id`, `contract_id`.
|
||||
- ✅ Periodic cleanup for unused file uploads.
|
||||
|
||||
---
|
||||
|
||||
@@ -1,136 +1,136 @@
|
||||
# LCBP3-DMS: Requirements Specification
|
||||
|
||||
เอกสารนี้สรุปข้อกำหนดของโปรเจ็ค LCBP3-DMS (Document Management System), สถาปัตยกรรมทางเทคนิค, และรายละเอียดการนำไปใช้ (Implementation) สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)
|
||||
|
||||
## 1. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ระบบใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา
|
||||
|
||||
- 1.1 Infrastructure & Environment:
|
||||
Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration, debug
|
||||
Development Environment: VS Code on Windows 11
|
||||
Domain: np-dms.work, www.np-dms.work (มี Fixed IP)
|
||||
Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
Data Storage: /share/dms-data บน QNAP
|
||||
ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
- 1.2 Code Hosting:
|
||||
Service: Gitea (Self-hosted on QNAP)
|
||||
Service name: gitea
|
||||
Domain: git.np-dms.work
|
||||
หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
- 1.3 Backend / Data Platform:
|
||||
Service: NestJS
|
||||
Service name: backend
|
||||
Domain: backend.np-dms.work
|
||||
Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
- 1.4 Database:
|
||||
Service: mariadb:10.11
|
||||
Service name: mariadb
|
||||
Domain: db.np-dms.work
|
||||
หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
- 1.5 Database management:
|
||||
Service: phpmyadmin:5-apache
|
||||
Service name: pma
|
||||
Domain: pma.np-dms.work
|
||||
หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
- 1.6 Frontend:
|
||||
Service: next.js
|
||||
Service name: frontend
|
||||
Domain: lcbp3.np-dms.work
|
||||
Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
Styling: Tailwind CSS + PostCSS
|
||||
Component Library: shadcn/ui
|
||||
หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
- 1.7 Workflow automation:
|
||||
Service: n8nio/n8n:latest
|
||||
Service name: n8n
|
||||
Domain: n8n.np-dms.work
|
||||
หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
- 1.8 Reverse Proxy:
|
||||
Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
Service name: npm
|
||||
Domain: npm.np-dms.work
|
||||
หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
## 2. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
- 2.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
- 2.1.1 โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 2.1.2 สัญญา (Contracts): ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 2.1.3 องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ บางองค์กรเช่น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
- 2.2. การจัดการเอกสาร (Correspondence Management)
|
||||
- 2.2.1 ประเภทเอกสาร: ระบบต้องรองรับเอกสารหลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 2.2.2 การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ "ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 2.2.3 การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 2.2.4 ประวัติการแก้ไข (Revisions): เอกสารสามารถมีได้หลาย Revision โดยระบบจะเก็บประวัติการแก้ไขทั้งหมด
|
||||
- 2.2.5 การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ออกเอกสาร (Issue Date) ได้
|
||||
- 2.3. การจัดการเอกสารนำส่ง (Transmittals)
|
||||
- 2.3.1 วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Technical Documents (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 2.3.2 การอ้างอิง: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence และสามารถมี Technical Documents (RFAS) หลายฉบับ
|
||||
- 2.4 ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
- 2.4.1 วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 2.4.2 การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 2.4.3 การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว
|
||||
- 2.5. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow)
|
||||
- 2.5.1 ประเภท: Technical Documents (RFAS) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA_DWG)
|
||||
- Request for Document Approval (RFA_DOC)
|
||||
- Request for Method statement Approval (RFA_MES)
|
||||
- Request for Material Approval (RFA_MAT)
|
||||
- 2.5.2 Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Org1 -> Org2 -> Org3 แล้วส่งผลกลับตามลำดับเดิม
|
||||
- 2.5.3 การจัดการ Drawing (RFA_DWG):
|
||||
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
|
||||
## 3. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
- 3.1 ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
- 3.2 ระดับของสิทธิ์:
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- 3.3 บทบาท (Roles) พื้นฐาน:
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้
|
||||
- Document Control / Editor: สามารถ เพิ่ม/แก้ไข เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin Panel
|
||||
- 3.4 การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 4. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
- 4.1 Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
- 4.2 หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
- 4.3 หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
- 4.4 การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
- 4.5 การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
- 4.6 การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 5. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
- 5.1 การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
- 5.2 การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
- 5.3 การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
- 5.4 ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
- 5.5 ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
# LCBP3-DMS: Requirements Specification
|
||||
|
||||
เอกสารนี้สรุปข้อกำหนดของโปรเจ็ค LCBP3-DMS (Document Management System), สถาปัตยกรรมทางเทคนิค, และรายละเอียดการนำไปใช้ (Implementation) สำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)
|
||||
|
||||
## 1. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ระบบใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา
|
||||
|
||||
- 1.1 Infrastructure & Environment:
|
||||
Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration, debug
|
||||
Development Environment: VS Code on Windows 11
|
||||
Domain: np-dms.work, www.np-dms.work (มี Fixed IP)
|
||||
Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
Data Storage: /share/dms-data บน QNAP
|
||||
ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
- 1.2 Code Hosting:
|
||||
Service: Gitea (Self-hosted on QNAP)
|
||||
Service name: gitea
|
||||
Domain: git.np-dms.work
|
||||
หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
- 1.3 Backend / Data Platform:
|
||||
Service: NestJS
|
||||
Service name: backend
|
||||
Domain: backend.np-dms.work
|
||||
Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
- 1.4 Database:
|
||||
Service: mariadb:10.11
|
||||
Service name: mariadb
|
||||
Domain: db.np-dms.work
|
||||
หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
- 1.5 Database management:
|
||||
Service: phpmyadmin:5-apache
|
||||
Service name: pma
|
||||
Domain: pma.np-dms.work
|
||||
หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
- 1.6 Frontend:
|
||||
Service: next.js
|
||||
Service name: frontend
|
||||
Domain: lcbp3.np-dms.work
|
||||
Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
Styling: Tailwind CSS + PostCSS
|
||||
Component Library: shadcn/ui
|
||||
หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
- 1.7 Workflow automation:
|
||||
Service: n8nio/n8n:latest
|
||||
Service name: n8n
|
||||
Domain: n8n.np-dms.work
|
||||
หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
- 1.8 Reverse Proxy:
|
||||
Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
Service name: npm
|
||||
Domain: npm.np-dms.work
|
||||
หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
## 2. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
- 2.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
- 2.1.1 โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 2.1.2 สัญญา (Contracts): ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 2.1.3 องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ บางองค์กรเช่น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
- 2.2. การจัดการเอกสาร (Correspondence Management)
|
||||
- 2.2.1 ประเภทเอกสาร: ระบบต้องรองรับเอกสารหลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 2.2.2 การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ "ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 2.2.3 การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 2.2.4 ประวัติการแก้ไข (Revisions): เอกสารสามารถมีได้หลาย Revision โดยระบบจะเก็บประวัติการแก้ไขทั้งหมด
|
||||
- 2.2.5 การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ออกเอกสาร (Issue Date) ได้
|
||||
- 2.3. การจัดการเอกสารนำส่ง (Transmittals)
|
||||
- 2.3.1 วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Technical Documents (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 2.3.2 การอ้างอิง: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence และสามารถมี Technical Documents (RFAS) หลายฉบับ
|
||||
- 2.4 ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
- 2.4.1 วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 2.4.2 การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 2.4.3 การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว
|
||||
- 2.5. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow)
|
||||
- 2.5.1 ประเภท: Technical Documents (RFAS) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA_DWG)
|
||||
- Request for Document Approval (RFA_DOC)
|
||||
- Request for Method statement Approval (RFA_MES)
|
||||
- Request for Material Approval (RFA_MAT)
|
||||
- 2.5.2 Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น ส่งจาก Originator -> Org1 -> Org2 -> Org3 แล้วส่งผลกลับตามลำดับเดิม
|
||||
- 2.5.3 การจัดการ Drawing (RFA_DWG):
|
||||
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
|
||||
## 3. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
- 3.1 ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
- 3.2 ระดับของสิทธิ์:
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- 3.3 บทบาท (Roles) พื้นฐาน:
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้
|
||||
- Document Control / Editor: สามารถ เพิ่ม/แก้ไข เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin Panel
|
||||
- 3.4 การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 4. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
- 4.1 Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
- 4.2 หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
- 4.3 หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
- 4.4 การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
- 4.5 การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
- 4.6 การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 5. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
- 5.1 การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
- 5.2 การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
- 5.3 การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
- 5.4 ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
- 5.5 ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
|
||||
@@ -1,197 +1,197 @@
|
||||
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
|
||||
## 📌 1. วัตถุประสงค์
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
- Application name: git
|
||||
- Service: Gitea (Self-hosted on QNAP)
|
||||
- Service name: gitea
|
||||
- Domain: git.np-dms.work
|
||||
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
- Application name: lcbp3-backend
|
||||
- Service: NestJS
|
||||
- Service name: backend
|
||||
- Domain: backend.np-dms.work
|
||||
- Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
- Application name: lcbp3-db
|
||||
- Service: mariadb:10.11
|
||||
- Service name: mariadb
|
||||
- Domain: db.np-dms.work
|
||||
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
- Application name: lcbp3-db
|
||||
- Service: phpmyadmin:5-apache
|
||||
- Service name: pma
|
||||
- Domain: pma.np-dms.work
|
||||
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
- Application name: lcbp3-frontend
|
||||
- Service: next.js
|
||||
- Service name: frontend
|
||||
- Domain: lcbp3.np-dms.work
|
||||
- Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
- Styling: Tailwind CSS + PostCSS
|
||||
- Component Library: shadcn/ui
|
||||
- หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
- Application name: lcbp3-n8n
|
||||
- Service: n8nio/n8n:latest
|
||||
- Service name: n8n
|
||||
- Domain: n8n.np-dms.work
|
||||
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
- Application name: lcbp3-npm
|
||||
- Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
- Service name: npm
|
||||
- Domain: npm.np-dms.work
|
||||
- หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
|
||||
## 📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 3.1.3. องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
- 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects)
|
||||
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA_DWG)
|
||||
- Request for Document Approval (RFA_DOC)
|
||||
- Request for Method statement Approval (RFA_MES)
|
||||
- Request for Material Approval (RFA_MAT)
|
||||
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 3.7.5. การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
|
||||
* 3.9. การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ในเอกสาร (Document Date) ได้ ตัวอย่างเช่น
|
||||
- Correspondence จัดเก็บใน /share/dms-data/correspondences/YYMMDD/ชื่อไฟล์.pdf
|
||||
- Request for Approval จัดเก็บใน /share/dms-data/rfas/YYMMDD/ชื่อไฟล์.pdf
|
||||
- Shop Drawings จัดเก็บใน /share/dms-data/shop_drawings/YYMMDD/ชื่อไฟล์.pdf
|
||||
|
||||
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
|
||||
## 📈 7.
|
||||
|
||||
## 🧩 8.
|
||||
🎯
|
||||
📤
|
||||
📊
|
||||
✅
|
||||
🔄
|
||||
|
||||
|
||||
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
|
||||
## 📌 1. วัตถุประสงค์
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
- Application name: git
|
||||
- Service: Gitea (Self-hosted on QNAP)
|
||||
- Service name: gitea
|
||||
- Domain: git.np-dms.work
|
||||
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
- Application name: lcbp3-backend
|
||||
- Service: NestJS
|
||||
- Service name: backend
|
||||
- Domain: backend.np-dms.work
|
||||
- Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
- Application name: lcbp3-db
|
||||
- Service: mariadb:10.11
|
||||
- Service name: mariadb
|
||||
- Domain: db.np-dms.work
|
||||
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
- Application name: lcbp3-db
|
||||
- Service: phpmyadmin:5-apache
|
||||
- Service name: pma
|
||||
- Domain: pma.np-dms.work
|
||||
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
- Application name: lcbp3-frontend
|
||||
- Service: next.js
|
||||
- Service name: frontend
|
||||
- Domain: lcbp3.np-dms.work
|
||||
- Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
- Styling: Tailwind CSS + PostCSS
|
||||
- Component Library: shadcn/ui
|
||||
- หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
- Application name: lcbp3-n8n
|
||||
- Service: n8nio/n8n:latest
|
||||
- Service name: n8n
|
||||
- Domain: n8n.np-dms.work
|
||||
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
- Application name: lcbp3-npm
|
||||
- Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
- Service name: npm
|
||||
- Domain: npm.np-dms.work
|
||||
- หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
|
||||
## 📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 3.1.3. องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
- 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects)
|
||||
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA_DWG)
|
||||
- Request for Document Approval (RFA_DOC)
|
||||
- Request for Method statement Approval (RFA_MES)
|
||||
- Request for Material Approval (RFA_MAT)
|
||||
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
- เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
- ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
0 - สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 3.7.5. การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
|
||||
* 3.9. การจัดเก็บ: เอกสารและไฟล์แนบจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) โดยมีการอ้างอิงข้อมูล (Metadata) ในฐานข้อมูล และสามารถจัดเรียงตามวันที่ในเอกสาร (Document Date) ได้ ตัวอย่างเช่น
|
||||
- Correspondence จัดเก็บใน /share/dms-data/correspondences/YYMMDD/ชื่อไฟล์.pdf
|
||||
- Request for Approval จัดเก็บใน /share/dms-data/rfas/YYMMDD/ชื่อไฟล์.pdf
|
||||
- Shop Drawings จัดเก็บใน /share/dms-data/shop_drawings/YYMMDD/ชื่อไฟล์.pdf
|
||||
|
||||
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
|
||||
## 📈 7.
|
||||
|
||||
## 🧩 8.
|
||||
🎯
|
||||
📤
|
||||
📊
|
||||
✅
|
||||
🔄
|
||||
|
||||
|
||||
|
||||
@@ -1,456 +1,456 @@
|
||||
# แนวทางการพัฒนา FullStackJS
|
||||
|
||||
## 🧠 ปรัชญาทั่วไป
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา **NestJS Backend**, **NextJS Frontend** และ **Tailwind-based UI/UX** ในสภาพแวดล้อม TypeScript
|
||||
มุ่งเน้นที่ **ความชัดเจน (clarity)**, **ความง่ายในการบำรุงรักษา (maintainability)**, **ความสอดคล้องกัน (consistency)** และ **การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก
|
||||
|
||||
-----
|
||||
|
||||
## ⚙️ แนวทางทั่วไปสำหรับ TypeScript
|
||||
|
||||
### หลักการพื้นฐาน
|
||||
|
||||
- ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
|
||||
- กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
- หลีกเลี่ยงการใช้ `any`; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
- ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
- ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
- หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
|
||||
### ข้อตกลงในการตั้งชื่อ (Naming Conventions)
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น `API`, `URL`, `req`, `res`, `err`, `ctx`)
|
||||
|
||||
-----
|
||||
|
||||
## 🧩 ฟังก์ชัน (Functions)
|
||||
|
||||
- เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
- ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
- ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
- ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
- ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
- จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
- ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
- รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
-----
|
||||
|
||||
## 🧱 การจัดการข้อมูล (Data Handling)
|
||||
|
||||
- ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
- ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย `readonly` และ `as const`
|
||||
- ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
- ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
-----
|
||||
|
||||
## 🧰 คลาส (Classes)
|
||||
|
||||
- ปฏิบัติตามหลักการ **SOLID**
|
||||
- ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
- กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
- ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
-----
|
||||
|
||||
## 🚨 การจัดการข้อผิดพลาด (Error Handling)
|
||||
|
||||
- ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
- ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
- ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
-----
|
||||
|
||||
## 🧪 การทดสอบ (ทั่วไป) (Testing (General))
|
||||
|
||||
- ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
- ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (`inputData`, `expectedOutput`)
|
||||
- เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
- จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
- เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When–Then
|
||||
|
||||
-----
|
||||
|
||||
# 🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))
|
||||
|
||||
### หลักการ
|
||||
|
||||
- **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
- หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
- โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
- DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
- ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
- ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### ฟังก์ชันหลัก (Core Functionalities)
|
||||
|
||||
- Global **filters** สำหรับการจัดการ exception
|
||||
- **Middlewares** สำหรับการจัดการ request
|
||||
- **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
- **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### ข้อจำกัดในการ Deploy (QNAP Container Station)
|
||||
|
||||
- **ห้ามใช้ไฟล์ `.env`** ในการตั้งค่า Environment Variables
|
||||
- การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน `docker-compose.yml` โดยตรง** ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station
|
||||
|
||||
### โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CoreModule / CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น `DatabaseModule`, `FileStorageService` (จัดการไฟล์ใน QNAP), `AuditLogService`, และ `NotificationService`
|
||||
2. **AuthModule / UserModule:**
|
||||
* จัดการ `users`, `roles`, `permissions` และการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ**: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ Admin เพื่อ **สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก** (ไม่ใช่แค่ seed ข้อมูลเริ่มต้น)
|
||||
3. **ProjectModule:**
|
||||
* จัดการ `projects`, `organizations`, `contracts`, `project_parties`, `contract_parties`
|
||||
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ `correspondences`, `correspondence_revisions`
|
||||
* จัดการ `correspondence_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (`correspondence_routings`) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
5. **RfaModule:**
|
||||
* จัดการ `rfas`, `rfa_revisions`, `rfa_items`
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (`rfa_workflows`) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
6. **DrawingModule:**
|
||||
* จัดการ `shop_drawings`, `shop_drawing_revisions`, `contract_drawings` และหมวดหมู่ต่างๆ
|
||||
* จัดการ `shop_drawing_revision_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
7. **CirculationModule:**
|
||||
* จัดการ `circulations`, `circulation_templates`, `circulation_assignees`
|
||||
* จัดการ `circulation_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลGว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
8. **TransmittalModule:**
|
||||
* จัดการ `transmittals` และ `transmittal_items`
|
||||
9. **SearchModule:**
|
||||
* **(สำหรับ V1)** ให้บริการค้นหาขั้นสูง (Advanced Search) โดยต้องรองรับการกรองจาก ชื่อเรื่อง (LIKE), ประเภท, วันที่, และ **Tags** (ผ่านการ Join ตาราง) โดยค้นหาผ่าน Views (`v_current_rfas`, `v_current_correspondences`)
|
||||
|
||||
### เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)
|
||||
|
||||
🔐 **Authentication & Authorization**
|
||||
|
||||
* `@nestjs/passport`
|
||||
* `@nestjs/jwt`
|
||||
* `casl` – สำหรับ RBAC (Role-Based Access Control)
|
||||
|
||||
🗃️ **Database & ORM**
|
||||
|
||||
* `@nestjs/typeorm` – ORM สำหรับ SQL (หรือ `Prisma` เป็นทางเลือก)
|
||||
* `typeorm-seeding` – สำหรับสร้างข้อมูลจำลอง (seeding)
|
||||
|
||||
📦 **Validation & Transformation**
|
||||
|
||||
* `class-validator`
|
||||
* `class-transformer`
|
||||
|
||||
📁 **File Upload & Storage**
|
||||
|
||||
* `@nestjs/platform-express`
|
||||
* `multer` – สำหรับจัดการไฟล์
|
||||
|
||||
🔍 **Search**
|
||||
|
||||
* **(สำหรับ V1)** เน้นการค้นหาขั้นสูงตาม Requirement 6.2 (Full-text search/Elasticsearch จะพิจารณาใน V2)
|
||||
|
||||
📬 **Notification**
|
||||
|
||||
* `nodemailer` – สำหรับส่งอีเมล
|
||||
* `@nestjs/schedule` – สำหรับ cron job หรือแจ้งเตือนตามเวลา
|
||||
|
||||
📊 **Logging & Monitoring**
|
||||
|
||||
* `winston` หรือ `nestjs-pino` – ระบบ log ที่ยืดหยุ่น
|
||||
* `@nestjs/terminus` – สำหรับ health check
|
||||
|
||||
🧪 **Testing**
|
||||
|
||||
* `@nestjs/testing`
|
||||
* `jest` – สำหรับ unit/integration test
|
||||
|
||||
🌐 **API Documentation**
|
||||
|
||||
* `@nestjs/swagger` – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
|
||||
|
||||
🛡️ **Security**
|
||||
|
||||
* `helmet` – ป้องกันช่องโหว่ HTTP
|
||||
* `rate-limiter-flexible` – ป้องกัน brute force
|
||||
|
||||
### การทดสอบ (Testing)
|
||||
|
||||
- ใช้ **Jest** สำหรับการทดสอบ
|
||||
- ทดสอบทุก controller และ service
|
||||
- เพิ่ม endpoint `admin/test` เพื่อใช้เป็น smoke test
|
||||
|
||||
-----
|
||||
|
||||
# 🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))
|
||||
|
||||
### โปรไฟล์นักพัฒนา (Developer Profile)
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ **TailwindCSS**, **Shadcn/UI**, และ **Radix** สำหรับการพัฒนา UI
|
||||
|
||||
### แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)
|
||||
|
||||
- ใช้ **early returns** เพื่อความชัดเจน
|
||||
- ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
- ควรใช้ `class:` syntax แบบมีเงื่อนไข (หรือ utility `clsx`) มากกว่าการใช้ ternary operators ใน class strings
|
||||
- ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
- Event handlers ให้ขึ้นต้นด้วย `handle...` (เช่น `handleClick`, `handleSubmit`)
|
||||
- รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, ฯลฯ
|
||||
- ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
- ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### UI/UX ด้วย React
|
||||
|
||||
- ใช้ **semantic HTML**
|
||||
- ใช้คลาสของ **Tailwind** ที่รองรับ responsive (`sm:`, `md:`, `lg:`)
|
||||
- รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
- ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
- ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
- ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
- ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)
|
||||
|
||||
- ใช้ไลบรารีฝั่ง client เช่น `zod` และ `react-hook-form`
|
||||
- แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
- ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
-----
|
||||
|
||||
# 🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | `class-validator` DTOs | `zod` / `react-hook-form` | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
-----
|
||||
|
||||
# 🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
## 🧱 โมดูลโดเมนฝั่งแบ็กเอนด์ (Backend Domain Modules)
|
||||
|
||||
ใช้โครงสร้างโดเมนแบบโมดูลาร์ที่สะท้อนสคีมา SQL โดย `correspondences` จะทำหน้าที่เป็นศูนย์กลาง (โครงสร้างนี้จะอยู่ภายใต้ "Functional Modules" ที่กล่าวถึงข้างต้น)
|
||||
|
||||
```
|
||||
src/
|
||||
├─ modules/
|
||||
│ ├─ correspondences/ (Core: Master documents, Revisions, correspondence_attachments)
|
||||
│ ├─ rfas/ (RFA logic, Revisions, Workflows, Items)
|
||||
│ ├─ drawings/ (ShopDrawings, Revisions, shop_drawing_revision_attachments)
|
||||
│ ├─ circulations/ (Internal circulation, Templates, circulation_attachments)
|
||||
│ ├─ transmittals/ (Transmittal logic, Items)
|
||||
│ ├─ projects-contracts/ (Projects, Contracts, Organizations, Parties)
|
||||
│ ├─ users-auth/ (Users, Roles, Permissions, Auth)
|
||||
│ ├─ audit-log/
|
||||
│ └─ common/
|
||||
```
|
||||
|
||||
### ข้อตกลงการตั้งชื่อ (Naming Convention)
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Example (ตัวอย่างจาก SQL) |
|
||||
|:--|:--|
|
||||
| Table | `correspondences`, `rfa_revisions`, `contract_parties` |
|
||||
| Column | `correspondence_id`, `created_by`, `is_current` |
|
||||
| DTO | `CreateRfaDto`, `UpdateCorrespondenceDto` |
|
||||
| Controller | `rfas.controller.ts` |
|
||||
| Service | `correspondences.service.ts` |
|
||||
|
||||
-----
|
||||
|
||||
## 🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง `permissions`
|
||||
|
||||
```ts
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
```
|
||||
|
||||
### Roles (บทบาท)
|
||||
|
||||
- **Superadmin**: ไม่มีข้อจำกัดใดๆ
|
||||
- **Admin**: มีสิทธิ์เต็มที่ในองค์กร
|
||||
- **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร
|
||||
- **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด
|
||||
- **Viewer**: สามารถดู เอกสาร
|
||||
|
||||
### ตัวอย่าง Permissions (จากตาราง `permissions`)
|
||||
|
||||
- `rfas.view`, `rfas.create`, `rfas.respond`, `rfas.delete`
|
||||
- `drawings.view`, `drawings.upload`, `drawings.delete`
|
||||
- `corr.view`, `corr.manage`
|
||||
- `transmittals.manage`
|
||||
- `cirs.manage`
|
||||
- `project_parties.manage`
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL) **อย่างไรก็ตาม `AuthModule`/`UserModule` ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง**
|
||||
|
||||
-----
|
||||
|
||||
## 🧾 มาตรฐาน AuditLog (AuditLog Standard)
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง `audit_logs`
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
|:--|:--|:--|
|
||||
| `audit_id` | `BIGINT` | Primary Key |
|
||||
| `user_id` | `INT` | ผู้ใช้ที่ดำเนินการ (FK -\> users) |
|
||||
| `action` | `VARCHAR(100)` | `rfa.create`, `correspondence.update`, `login.success` |
|
||||
| `entity_type`| `VARCHAR(50)` | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| `entity_id` | `VARCHAR(50)` | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| `details_json`| `JSON` | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| `ip_address` | `VARCHAR(45)` | IP address ของผู้ดำเนินการ |
|
||||
| `user_agent` | `VARCHAR(255)`| User Agent ของผู้ดำเนินการ |
|
||||
| `created_at` | `TIMESTAMP` | Timestamp (UTC) |
|
||||
|
||||
ตัวอย่างการใช้งาน:
|
||||
|
||||
```ts
|
||||
await this.auditLogService.log({
|
||||
userId: user.id,
|
||||
action: 'rfa.update_status',
|
||||
entityType: 'rfa_revisions',
|
||||
entityId: rfaRevision.id,
|
||||
detailsJson: { from: 'DFT', to: 'FAP' },
|
||||
ipAddress: req.ip,
|
||||
});
|
||||
```
|
||||
|
||||
-----
|
||||
|
||||
## 📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)
|
||||
|
||||
### มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)
|
||||
|
||||
- **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย `FileStorageService` และบันทึกข้อมูลไฟล์ลงในตาราง `attachments` (ตารางกลาง)
|
||||
- ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
- `correspondence_attachments` (เชื่อม Correspondence กับ Attachments)
|
||||
- `circulation_attachments` (เชื่อม Circulation กับ Attachments)
|
||||
- `shop_drawing_revision_attachments` (เชื่อม Drawing Revision กับ Attachments)
|
||||
- **(สำคัญ)** คอลัมน์ `file_path` ถูกลบออกจาก `shop_drawing_revisions` แล้ว ต้องใช้ระบบตารางเชื่อมใหม่นี้เท่านั้น
|
||||
- เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ `/share/dms-data` โดย `FileStorageService` จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น `/share/dms-data/uploads/{YYYY}/{MM}/[stored_filename]`)
|
||||
- **(หมายเหตุ)**: โครงสร้างนี้ *แทนที่* โครงสร้างแบบแยกโมดูลที่ระบุใน Requirement 3.9 เนื่องจากการออกแบบใหม่ได้รวมศูนย์ไฟล์ไว้ที่ตาราง `attachments` กลางแล้ว
|
||||
- ประเภทไฟล์ที่อนุญาต: `pdf, dwg, docx, xlsx, zip`
|
||||
- ขนาดสูงสุด: **50 MB**
|
||||
- จัดเก็บนอก webroot
|
||||
- ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย `/files/:attachment_id/download`
|
||||
|
||||
### การควบคุมการเข้าถึง (Access Control)
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint `/files/:attachment_id/download` จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน `attachment`
|
||||
2. ตรวจสอบว่า `attachment_id` นี้ เชื่อมโยงกับ Entity ใด (เช่น `correspondence`, `circulation`, `shop_drawing_revision`) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
-----
|
||||
|
||||
## 📊 การรายงานและการส่งออก (Reporting & Exports)
|
||||
|
||||
### วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
- `v_current_correspondences`: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
- `v_current_rfas`: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
- `v_contract_parties_all`: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### กฎการส่งออก (Export Rules)
|
||||
|
||||
- Export formats: CSV, Excel, PDF.
|
||||
- จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
- รวมลิงก์ไปยังต้นทาง (เช่น `/rfas/:id`).
|
||||
|
||||
-----
|
||||
|
||||
## 🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)
|
||||
|
||||
### DataTable (Server‑Side)
|
||||
|
||||
- Endpoint: `/api/{module}?page=1&pageSize=20&sort=...&filter=...`
|
||||
- ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
- แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### มาตรฐานฟอร์ม (Form Standards)
|
||||
|
||||
- ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
- Project → Contract Drawing Volumes
|
||||
- Contract Drawing Category → Sub-Category
|
||||
- RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
- การอัปโหลดไฟล์: ต้องมี preview + validation (ผ่านตรรกะของ `attachments` และตารางเชื่อมใหม่)
|
||||
- ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### ข้อกำหนด Component เฉพาะ (Specific UI Requirements)
|
||||
|
||||
- **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks) ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จากโมดูล `Circulations`
|
||||
- **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA) ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น `disabled` ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้
|
||||
|
||||
-----
|
||||
|
||||
## 🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)
|
||||
|
||||
### การ์ดบนแดชบอร์ด (Dashboard Cards)
|
||||
|
||||
- แสดง Correspondences, RFAs, Circulations ล่าสุด
|
||||
- รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ")
|
||||
- รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### ฟีดกิจกรรม (Activity Feed)
|
||||
|
||||
- แสดงรายการ `audit_logs` ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
```ts
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
```
|
||||
|
||||
-----
|
||||
|
||||
## ✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
- ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ `deleted_at` ในตารางสำคัญ (เช่น `correspondences`, `rfas`, `project_parties`) ตรรกะการดึงข้อมูลต้องกรอง `deleted_at IS NULL`
|
||||
- ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น `idx_rr_rfa`, `idx_cor_project`, `idx_cr_is_current`) เพื่อประสิทธิภาพ
|
||||
- ✅ **โครงสร้าง RBAC:** มีระบบ `users`, `roles`, `permissions`, `user_roles`, และ `user_project_roles` ที่ครอบคลุมอยู่แล้ว
|
||||
- ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization\_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## 🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))
|
||||
|
||||
- ✅ **(V2)** นำ Fulltext search หรือ Elasticsearch มาใช้กับฟิลด์เช่น `correspondence_revisions.title` หรือ `details`
|
||||
- ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด `due_date`)
|
||||
- ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ `attachments` ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
|
||||
|
||||
# แนวทางการพัฒนา FullStackJS
|
||||
|
||||
## 🧠 ปรัชญาทั่วไป
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา **NestJS Backend**, **NextJS Frontend** และ **Tailwind-based UI/UX** ในสภาพแวดล้อม TypeScript
|
||||
มุ่งเน้นที่ **ความชัดเจน (clarity)**, **ความง่ายในการบำรุงรักษา (maintainability)**, **ความสอดคล้องกัน (consistency)** และ **การเข้าถึงได้ (accessibility)** ตลอดทั้งสแต็ก
|
||||
|
||||
-----
|
||||
|
||||
## ⚙️ แนวทางทั่วไปสำหรับ TypeScript
|
||||
|
||||
### หลักการพื้นฐาน
|
||||
|
||||
- ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
|
||||
- กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
- หลีกเลี่ยงการใช้ `any`; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
- ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
- ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
- หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
|
||||
### ข้อตกลงในการตั้งชื่อ (Naming Conventions)
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
|:--|:--|:--|
|
||||
| Classes | PascalCase | `UserService` |
|
||||
| Variables & Functions | camelCase | `getUserInfo` |
|
||||
| Files & Folders | kebab-case | `user-service.ts` |
|
||||
| Environment Variables | UPPERCASE | `DATABASE_URL` |
|
||||
| Booleans | Verb + Noun | `isActive`, `canDelete`, `hasPermission` |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น `API`, `URL`, `req`, `res`, `err`, `ctx`)
|
||||
|
||||
-----
|
||||
|
||||
## 🧩 ฟังก์ชัน (Functions)
|
||||
|
||||
- เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
- ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
- ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
- ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
- ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
- จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
- ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
- รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
-----
|
||||
|
||||
## 🧱 การจัดการข้อมูล (Data Handling)
|
||||
|
||||
- ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
- ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย `readonly` และ `as const`
|
||||
- ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
- ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
-----
|
||||
|
||||
## 🧰 คลาส (Classes)
|
||||
|
||||
- ปฏิบัติตามหลักการ **SOLID**
|
||||
- ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
- กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
- ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
-----
|
||||
|
||||
## 🚨 การจัดการข้อผิดพลาด (Error Handling)
|
||||
|
||||
- ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
- ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
- ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
-----
|
||||
|
||||
## 🧪 การทดสอบ (ทั่วไป) (Testing (General))
|
||||
|
||||
- ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
- ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (`inputData`, `expectedOutput`)
|
||||
- เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
- จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
- เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When–Then
|
||||
|
||||
-----
|
||||
|
||||
# 🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))
|
||||
|
||||
### หลักการ
|
||||
|
||||
- **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
- หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
- โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
- DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
- ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
- ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (`@app/common`):
|
||||
- Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### ฟังก์ชันหลัก (Core Functionalities)
|
||||
|
||||
- Global **filters** สำหรับการจัดการ exception
|
||||
- **Middlewares** สำหรับการจัดการ request
|
||||
- **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
- **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### ข้อจำกัดในการ Deploy (QNAP Container Station)
|
||||
|
||||
- **ห้ามใช้ไฟล์ `.env`** ในการตั้งค่า Environment Variables
|
||||
- การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน `docker-compose.yml` โดยตรง** ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station
|
||||
|
||||
### โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CoreModule / CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น `DatabaseModule`, `FileStorageService` (จัดการไฟล์ใน QNAP), `AuditLogService`, และ `NotificationService`
|
||||
2. **AuthModule / UserModule:**
|
||||
* จัดการ `users`, `roles`, `permissions` และการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ**: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ Admin เพื่อ **สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก** (ไม่ใช่แค่ seed ข้อมูลเริ่มต้น)
|
||||
3. **ProjectModule:**
|
||||
* จัดการ `projects`, `organizations`, `contracts`, `project_parties`, `contract_parties`
|
||||
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ `correspondences`, `correspondence_revisions`
|
||||
* จัดการ `correspondence_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (`correspondence_routings`) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
5. **RfaModule:**
|
||||
* จัดการ `rfas`, `rfa_revisions`, `rfa_items`
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (`rfa_workflows`) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
6. **DrawingModule:**
|
||||
* จัดการ `shop_drawings`, `shop_drawing_revisions`, `contract_drawings` และหมวดหมู่ต่างๆ
|
||||
* จัดการ `shop_drawing_revision_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
7. **CirculationModule:**
|
||||
* จัดการ `circulations`, `circulation_templates`, `circulation_assignees`
|
||||
* จัดการ `circulation_attachments` (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลGว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
8. **TransmittalModule:**
|
||||
* จัดการ `transmittals` และ `transmittal_items`
|
||||
9. **SearchModule:**
|
||||
* **(สำหรับ V1)** ให้บริการค้นหาขั้นสูง (Advanced Search) โดยต้องรองรับการกรองจาก ชื่อเรื่อง (LIKE), ประเภท, วันที่, และ **Tags** (ผ่านการ Join ตาราง) โดยค้นหาผ่าน Views (`v_current_rfas`, `v_current_correspondences`)
|
||||
|
||||
### เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)
|
||||
|
||||
🔐 **Authentication & Authorization**
|
||||
|
||||
* `@nestjs/passport`
|
||||
* `@nestjs/jwt`
|
||||
* `casl` – สำหรับ RBAC (Role-Based Access Control)
|
||||
|
||||
🗃️ **Database & ORM**
|
||||
|
||||
* `@nestjs/typeorm` – ORM สำหรับ SQL (หรือ `Prisma` เป็นทางเลือก)
|
||||
* `typeorm-seeding` – สำหรับสร้างข้อมูลจำลอง (seeding)
|
||||
|
||||
📦 **Validation & Transformation**
|
||||
|
||||
* `class-validator`
|
||||
* `class-transformer`
|
||||
|
||||
📁 **File Upload & Storage**
|
||||
|
||||
* `@nestjs/platform-express`
|
||||
* `multer` – สำหรับจัดการไฟล์
|
||||
|
||||
🔍 **Search**
|
||||
|
||||
* **(สำหรับ V1)** เน้นการค้นหาขั้นสูงตาม Requirement 6.2 (Full-text search/Elasticsearch จะพิจารณาใน V2)
|
||||
|
||||
📬 **Notification**
|
||||
|
||||
* `nodemailer` – สำหรับส่งอีเมล
|
||||
* `@nestjs/schedule` – สำหรับ cron job หรือแจ้งเตือนตามเวลา
|
||||
|
||||
📊 **Logging & Monitoring**
|
||||
|
||||
* `winston` หรือ `nestjs-pino` – ระบบ log ที่ยืดหยุ่น
|
||||
* `@nestjs/terminus` – สำหรับ health check
|
||||
|
||||
🧪 **Testing**
|
||||
|
||||
* `@nestjs/testing`
|
||||
* `jest` – สำหรับ unit/integration test
|
||||
|
||||
🌐 **API Documentation**
|
||||
|
||||
* `@nestjs/swagger` – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
|
||||
|
||||
🛡️ **Security**
|
||||
|
||||
* `helmet` – ป้องกันช่องโหว่ HTTP
|
||||
* `rate-limiter-flexible` – ป้องกัน brute force
|
||||
|
||||
### การทดสอบ (Testing)
|
||||
|
||||
- ใช้ **Jest** สำหรับการทดสอบ
|
||||
- ทดสอบทุก controller และ service
|
||||
- เพิ่ม endpoint `admin/test` เพื่อใช้เป็น smoke test
|
||||
|
||||
-----
|
||||
|
||||
# 🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))
|
||||
|
||||
### โปรไฟล์นักพัฒนา (Developer Profile)
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ **TailwindCSS**, **Shadcn/UI**, และ **Radix** สำหรับการพัฒนา UI
|
||||
|
||||
### แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)
|
||||
|
||||
- ใช้ **early returns** เพื่อความชัดเจน
|
||||
- ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
- ควรใช้ `class:` syntax แบบมีเงื่อนไข (หรือ utility `clsx`) มากกว่าการใช้ ternary operators ใน class strings
|
||||
- ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
- Event handlers ให้ขึ้นต้นด้วย `handle...` (เช่น `handleClick`, `handleSubmit`)
|
||||
- รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
`tabIndex="0"`, `aria-label`, `onKeyDown`, ฯลฯ
|
||||
- ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
- ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### UI/UX ด้วย React
|
||||
|
||||
- ใช้ **semantic HTML**
|
||||
- ใช้คลาสของ **Tailwind** ที่รองรับ responsive (`sm:`, `md:`, `lg:`)
|
||||
- รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
- ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
- ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
- ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
- ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)
|
||||
|
||||
- ใช้ไลบรารีฝั่ง client เช่น `zod` และ `react-hook-form`
|
||||
- แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
- ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
-----
|
||||
|
||||
# 🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
|:--|:--|:--|:--|
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | `class-validator` DTOs | `zod` / `react-hook-form` | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
-----
|
||||
|
||||
# 🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
## 🧱 โมดูลโดเมนฝั่งแบ็กเอนด์ (Backend Domain Modules)
|
||||
|
||||
ใช้โครงสร้างโดเมนแบบโมดูลาร์ที่สะท้อนสคีมา SQL โดย `correspondences` จะทำหน้าที่เป็นศูนย์กลาง (โครงสร้างนี้จะอยู่ภายใต้ "Functional Modules" ที่กล่าวถึงข้างต้น)
|
||||
|
||||
```
|
||||
src/
|
||||
├─ modules/
|
||||
│ ├─ correspondences/ (Core: Master documents, Revisions, correspondence_attachments)
|
||||
│ ├─ rfas/ (RFA logic, Revisions, Workflows, Items)
|
||||
│ ├─ drawings/ (ShopDrawings, Revisions, shop_drawing_revision_attachments)
|
||||
│ ├─ circulations/ (Internal circulation, Templates, circulation_attachments)
|
||||
│ ├─ transmittals/ (Transmittal logic, Items)
|
||||
│ ├─ projects-contracts/ (Projects, Contracts, Organizations, Parties)
|
||||
│ ├─ users-auth/ (Users, Roles, Permissions, Auth)
|
||||
│ ├─ audit-log/
|
||||
│ └─ common/
|
||||
```
|
||||
|
||||
### ข้อตกลงการตั้งชื่อ (Naming Convention)
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Example (ตัวอย่างจาก SQL) |
|
||||
|:--|:--|
|
||||
| Table | `correspondences`, `rfa_revisions`, `contract_parties` |
|
||||
| Column | `correspondence_id`, `created_by`, `is_current` |
|
||||
| DTO | `CreateRfaDto`, `UpdateCorrespondenceDto` |
|
||||
| Controller | `rfas.controller.ts` |
|
||||
| Service | `correspondences.service.ts` |
|
||||
|
||||
-----
|
||||
|
||||
## 🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง `permissions`
|
||||
|
||||
```ts
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission_code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
```
|
||||
|
||||
### Roles (บทบาท)
|
||||
|
||||
- **Superadmin**: ไม่มีข้อจำกัดใดๆ
|
||||
- **Admin**: มีสิทธิ์เต็มที่ในองค์กร
|
||||
- **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร
|
||||
- **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด
|
||||
- **Viewer**: สามารถดู เอกสาร
|
||||
|
||||
### ตัวอย่าง Permissions (จากตาราง `permissions`)
|
||||
|
||||
- `rfas.view`, `rfas.create`, `rfas.respond`, `rfas.delete`
|
||||
- `drawings.view`, `drawings.upload`, `drawings.delete`
|
||||
- `corr.view`, `corr.manage`
|
||||
- `transmittals.manage`
|
||||
- `cirs.manage`
|
||||
- `project_parties.manage`
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL) **อย่างไรก็ตาม `AuthModule`/`UserModule` ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง**
|
||||
|
||||
-----
|
||||
|
||||
## 🧾 มาตรฐาน AuditLog (AuditLog Standard)
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง `audit_logs`
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
|:--|:--|:--|
|
||||
| `audit_id` | `BIGINT` | Primary Key |
|
||||
| `user_id` | `INT` | ผู้ใช้ที่ดำเนินการ (FK -\> users) |
|
||||
| `action` | `VARCHAR(100)` | `rfa.create`, `correspondence.update`, `login.success` |
|
||||
| `entity_type`| `VARCHAR(50)` | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| `entity_id` | `VARCHAR(50)` | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| `details_json`| `JSON` | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| `ip_address` | `VARCHAR(45)` | IP address ของผู้ดำเนินการ |
|
||||
| `user_agent` | `VARCHAR(255)`| User Agent ของผู้ดำเนินการ |
|
||||
| `created_at` | `TIMESTAMP` | Timestamp (UTC) |
|
||||
|
||||
ตัวอย่างการใช้งาน:
|
||||
|
||||
```ts
|
||||
await this.auditLogService.log({
|
||||
userId: user.id,
|
||||
action: 'rfa.update_status',
|
||||
entityType: 'rfa_revisions',
|
||||
entityId: rfaRevision.id,
|
||||
detailsJson: { from: 'DFT', to: 'FAP' },
|
||||
ipAddress: req.ip,
|
||||
});
|
||||
```
|
||||
|
||||
-----
|
||||
|
||||
## 📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)
|
||||
|
||||
### มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)
|
||||
|
||||
- **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย `FileStorageService` และบันทึกข้อมูลไฟล์ลงในตาราง `attachments` (ตารางกลาง)
|
||||
- ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
- `correspondence_attachments` (เชื่อม Correspondence กับ Attachments)
|
||||
- `circulation_attachments` (เชื่อม Circulation กับ Attachments)
|
||||
- `shop_drawing_revision_attachments` (เชื่อม Drawing Revision กับ Attachments)
|
||||
- **(สำคัญ)** คอลัมน์ `file_path` ถูกลบออกจาก `shop_drawing_revisions` แล้ว ต้องใช้ระบบตารางเชื่อมใหม่นี้เท่านั้น
|
||||
- เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ `/share/dms-data` โดย `FileStorageService` จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น `/share/dms-data/uploads/{YYYY}/{MM}/[stored_filename]`)
|
||||
- **(หมายเหตุ)**: โครงสร้างนี้ *แทนที่* โครงสร้างแบบแยกโมดูลที่ระบุใน Requirement 3.9 เนื่องจากการออกแบบใหม่ได้รวมศูนย์ไฟล์ไว้ที่ตาราง `attachments` กลางแล้ว
|
||||
- ประเภทไฟล์ที่อนุญาต: `pdf, dwg, docx, xlsx, zip`
|
||||
- ขนาดสูงสุด: **50 MB**
|
||||
- จัดเก็บนอก webroot
|
||||
- ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย `/files/:attachment_id/download`
|
||||
|
||||
### การควบคุมการเข้าถึง (Access Control)
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint `/files/:attachment_id/download` จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน `attachment`
|
||||
2. ตรวจสอบว่า `attachment_id` นี้ เชื่อมโยงกับ Entity ใด (เช่น `correspondence`, `circulation`, `shop_drawing_revision`) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
-----
|
||||
|
||||
## 📊 การรายงานและการส่งออก (Reporting & Exports)
|
||||
|
||||
### วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
- `v_current_correspondences`: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
- `v_current_rfas`: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
- `v_contract_parties_all`: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### กฎการส่งออก (Export Rules)
|
||||
|
||||
- Export formats: CSV, Excel, PDF.
|
||||
- จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
- รวมลิงก์ไปยังต้นทาง (เช่น `/rfas/:id`).
|
||||
|
||||
-----
|
||||
|
||||
## 🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)
|
||||
|
||||
### DataTable (Server‑Side)
|
||||
|
||||
- Endpoint: `/api/{module}?page=1&pageSize=20&sort=...&filter=...`
|
||||
- ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
- แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### มาตรฐานฟอร์ม (Form Standards)
|
||||
|
||||
- ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
- Project → Contract Drawing Volumes
|
||||
- Contract Drawing Category → Sub-Category
|
||||
- RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
- การอัปโหลดไฟล์: ต้องมี preview + validation (ผ่านตรรกะของ `attachments` และตารางเชื่อมใหม่)
|
||||
- ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### ข้อกำหนด Component เฉพาะ (Specific UI Requirements)
|
||||
|
||||
- **Dashboard - My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks) ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จากโมดูล `Circulations`
|
||||
- **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA) ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น `disabled` ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้
|
||||
|
||||
-----
|
||||
|
||||
## 🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)
|
||||
|
||||
### การ์ดบนแดชบอร์ด (Dashboard Cards)
|
||||
|
||||
- แสดง Correspondences, RFAs, Circulations ล่าสุด
|
||||
- รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ")
|
||||
- รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### ฟีดกิจกรรม (Activity Feed)
|
||||
|
||||
- แสดงรายการ `audit_logs` ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
<!-- end list -->
|
||||
|
||||
```ts
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
```
|
||||
|
||||
-----
|
||||
|
||||
## ✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
- ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ `deleted_at` ในตารางสำคัญ (เช่น `correspondences`, `rfas`, `project_parties`) ตรรกะการดึงข้อมูลต้องกรอง `deleted_at IS NULL`
|
||||
- ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น `idx_rr_rfa`, `idx_cor_project`, `idx_cr_is_current`) เพื่อประสิทธิภาพ
|
||||
- ✅ **โครงสร้าง RBAC:** มีระบบ `users`, `roles`, `permissions`, `user_roles`, และ `user_project_roles` ที่ครอบคลุมอยู่แล้ว
|
||||
- ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization\_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## 🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))
|
||||
|
||||
- ✅ **(V2)** นำ Fulltext search หรือ Elasticsearch มาใช้กับฟิลด์เช่น `correspondence_revisions.title` หรือ `details`
|
||||
- ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด `due_date`)
|
||||
- ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ `attachments` ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
|
||||
|
||||
-----
|
||||
@@ -1,201 +1,201 @@
|
||||
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
|
||||
|
||||
## 📌 1. วัตถุประสงค์
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
- Application name: git
|
||||
- Service: Gitea (Self-hosted on QNAP)
|
||||
- Service name: gitea
|
||||
- Domain: git.np-dms.work
|
||||
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
- Application name: lcbp3-backend
|
||||
- Service: NestJS
|
||||
- Service name: backend
|
||||
- Domain: backend.np-dms.work
|
||||
- Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
- Application name: lcbp3-db
|
||||
- Service: mariadb:10.11
|
||||
- Service name: mariadb
|
||||
- Domain: db.np-dms.work
|
||||
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
- Application name: lcbp3-db
|
||||
- Service: phpmyadmin:5-apache
|
||||
- Service name: pma
|
||||
- Domain: pma.np-dms.work
|
||||
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
- Application name: lcbp3-frontend
|
||||
- Service: next.js
|
||||
- Service name: frontend
|
||||
- Domain: lcbp3.np-dms.work
|
||||
- Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
- Styling: Tailwind CSS + PostCSS
|
||||
- Component Library: shadcn/ui
|
||||
- หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
- Application name: lcbp3-n8n
|
||||
- Service: n8nio/n8n:latest
|
||||
- Service name: n8n
|
||||
- Domain: n8n.np-dms.work
|
||||
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
- Application name: lcbp3-npm
|
||||
- Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
- Service name: npm
|
||||
- Domain: npm.np-dms.work
|
||||
- หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
## 📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
|
||||
- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 3.1.3. องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
|
||||
- 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects)
|
||||
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
|
||||
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
|
||||
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
|
||||
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA\_DWG)
|
||||
- Request for Document Approval (RFA\_DOC)
|
||||
- Request for Method statement Approval (RFA\_MES)
|
||||
- Request for Material Approval (RFA\_MAT)
|
||||
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA\_DWG):
|
||||
- เอกสาร RFA\_DWG จะประกอบไปด้วย Shop Drawing (shop\_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract\_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
- ส่งจาก Originator -\> Organization 1 -\> Organization 2 -\> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
|
||||
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
|
||||
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 3.7.5. การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
|
||||
* **3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)**
|
||||
|
||||
- เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (`/share/dms-data/`)
|
||||
- ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง `attachments` (ตารางกลาง)
|
||||
- ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น `correspondence_attachments`, `circulation_attachments`, และ `shop_drawing_revision_attachments`
|
||||
- สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
|
||||
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
|
||||
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 6\. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน `audit_logs` เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
# 📝 Documents Management Sytem Version 1.1.0: Application Requirements Specification
|
||||
|
||||
## 📌 1. วัตถุประสงค์
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System) ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## 🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
- Application name: git
|
||||
- Service: Gitea (Self-hosted on QNAP)
|
||||
- Service name: gitea
|
||||
- Domain: git.np-dms.work
|
||||
- หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
- Application name: lcbp3-backend
|
||||
- Service: NestJS
|
||||
- Service name: backend
|
||||
- Domain: backend.np-dms.work
|
||||
- Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
- หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
- Application name: lcbp3-db
|
||||
- Service: mariadb:10.11
|
||||
- Service name: mariadb
|
||||
- Domain: db.np-dms.work
|
||||
- หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
- Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
- Application name: lcbp3-db
|
||||
- Service: phpmyadmin:5-apache
|
||||
- Service name: pma
|
||||
- Domain: pma.np-dms.work
|
||||
- หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
- Application name: lcbp3-frontend
|
||||
- Service: next.js
|
||||
- Service name: frontend
|
||||
- Domain: lcbp3.np-dms.work
|
||||
- Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
- Styling: Tailwind CSS + PostCSS
|
||||
- Component Library: shadcn/ui
|
||||
- หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
- Application name: lcbp3-n8n
|
||||
- Service: n8nio/n8n:latest
|
||||
- Service name: n8n
|
||||
- Domain: n8n.np-dms.work
|
||||
- หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
- Application name: lcbp3-npm
|
||||
- Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
- Service name: npm
|
||||
- Domain: npm.np-dms.work
|
||||
- หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
|
||||
## 📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
|
||||
- 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
- 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
- 3.1.3. องค์กร (Organizations):
|
||||
- มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
- Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
|
||||
- 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects)
|
||||
- 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
- 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
- ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
- เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
- 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
- เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
- สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
- 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อเป็นผู้รับ ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
|
||||
- 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
- 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
|
||||
- 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
- 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
|
||||
- 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
- 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
- Request for Drawing Approval (RFA\_DWG)
|
||||
- Request for Document Approval (RFA\_DOC)
|
||||
- Request for Method statement Approval (RFA\_MES)
|
||||
- Request for Material Approval (RFA\_MAT)
|
||||
- 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA\_DWG):
|
||||
- เอกสาร RFA\_DWG จะประกอบไปด้วย Shop Drawing (shop\_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
- Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract\_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
- ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
- 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
- ส่งจาก Originator -\> Organization 1 -\> Organization 2 -\> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
- 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
- มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
|
||||
- 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
- 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
- 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
|
||||
- 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
- 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
- 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
- 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
- ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
- ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
- ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
- 3.7.5. การติดตามงาน:
|
||||
- สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
- มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
- สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
|
||||
* **3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)**
|
||||
|
||||
- เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (`/share/dms-data/`)
|
||||
- ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง `attachments` (ตารางกลาง)
|
||||
- ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น `correspondence_attachments`, `circulation_attachments`, และ `shop_drawing_revision_attachments`
|
||||
- สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
|
||||
## 🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
|
||||
- Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
- Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
- Contract-Specific Roles: สิทธิ์ที่ถูกกำหนดให้โครงการสำหรับสัญญานั้นๆ (เช่น เป็น Admin ในสัญญา 1 จะเป็น Admin ใน โครงการ A และ ฺB ที่อยู่ในสัญญา 1)
|
||||
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
|
||||
- Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กร
|
||||
- Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
- Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
- Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
- Viewer: สามารถดู เอกสาร เฉพาะในองค์กรที่ตัวเองสังกัด
|
||||
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
|
||||
## 👥 5. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
- Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
- Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
- Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
- การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
- ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
|
||||
## 6\. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน `audit_logs` เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสารจากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
- มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
- การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
@@ -1,55 +1,55 @@
|
||||
# Documents Management Sytem Version 1.1.0: Application Databases Specification
|
||||
## 1. วัตถุประสงค์
|
||||
|
||||
|
||||
## 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
correspondences ตารางเอกสารโต้ตอบ
|
||||
-- 2.7.5 : n.n.5 for shop_drawing
|
||||
shop_drawings;
|
||||
-- 2.6.6 : n.n.6 for contract_drawing
|
||||
contract_drawings;
|
||||
-- 2.5.2 : n.n.2 for rfa
|
||||
rfas;
|
||||
-- 2.4.4 : n.n.4 for transmittal
|
||||
transmittals;
|
||||
-- 2.3.3: n.n.3 for circulation
|
||||
circulations;
|
||||
|
||||
|
||||
users;
|
||||
-- 4.7
|
||||
projects ตารางโครงการ
|
||||
-- 4.6
|
||||
contracts ตารางสัญญา
|
||||
-- 4.2
|
||||
permissions;
|
||||
-- 4.1
|
||||
roles;
|
||||
|
||||
-- Level 5: ตารางที่เป็นรากฐานที่สุด
|
||||
-- 5.2
|
||||
organizations ตารางองกรณ์;
|
||||
-- 5.1
|
||||
organization_roles;
|
||||
|
||||
-- 1.2
|
||||
attachments;
|
||||
|
||||
-- 1.1
|
||||
global_default_roles;
|
||||
|
||||
audit_logs;
|
||||
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
# Documents Management Sytem Version 1.1.0: Application Databases Specification
|
||||
## 1. วัตถุประสงค์
|
||||
|
||||
|
||||
## 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)
|
||||
correspondences ตารางเอกสารโต้ตอบ
|
||||
-- 2.7.5 : n.n.5 for shop_drawing
|
||||
shop_drawings;
|
||||
-- 2.6.6 : n.n.6 for contract_drawing
|
||||
contract_drawings;
|
||||
-- 2.5.2 : n.n.2 for rfa
|
||||
rfas;
|
||||
-- 2.4.4 : n.n.4 for transmittal
|
||||
transmittals;
|
||||
-- 2.3.3: n.n.3 for circulation
|
||||
circulations;
|
||||
|
||||
|
||||
users;
|
||||
-- 4.7
|
||||
projects ตารางโครงการ
|
||||
-- 4.6
|
||||
contracts ตารางสัญญา
|
||||
-- 4.2
|
||||
permissions;
|
||||
-- 4.1
|
||||
roles;
|
||||
|
||||
-- Level 5: ตารางที่เป็นรากฐานที่สุด
|
||||
-- 5.2
|
||||
organizations ตารางองกรณ์;
|
||||
-- 5.1
|
||||
organization_roles;
|
||||
|
||||
-- 1.2
|
||||
attachments;
|
||||
|
||||
-- 1.1
|
||||
global_default_roles;
|
||||
|
||||
audit_logs;
|
||||
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
- Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
- Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
- Development Environment: VS Code on Windows 11
|
||||
- Domain: np-dms.work, www.np-dms.work
|
||||
- ip: 159.192.126.103
|
||||
- Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
- Data Storage: /share/dms-data บน QNAP
|
||||
- ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
*
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,459 +1,459 @@
|
||||
# **Documents Management Sytem Version 1.2.1: แนวทางการพัฒนา FullStackJS**
|
||||
|
||||
## **🧠 ปรัชญาทั่วไป**
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
|
||||
|
||||
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
|
||||
|
||||
### **หลักการพื้นฐาน**
|
||||
|
||||
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
|
||||
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
|
||||
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
| :---- | :---- | :---- |
|
||||
| Classes | PascalCase | UserService |
|
||||
| Variables & Functions | camelCase | getUserInfo |
|
||||
| Files & Folders | kebab-case | user-service.ts |
|
||||
| Environment Variables | UPPERCASE | DATABASE\URL |
|
||||
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
|
||||
|
||||
## **🧩 ฟังก์ชัน (Functions)**
|
||||
|
||||
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
* ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
## **🧱 การจัดการข้อมูล (Data Handling)**
|
||||
|
||||
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
|
||||
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
## **🧰 คลาส (Classes)**
|
||||
|
||||
* ปฏิบัติตามหลักการ **SOLID**
|
||||
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
* กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
|
||||
|
||||
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
|
||||
|
||||
* ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
|
||||
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
|
||||
|
||||
# **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
|
||||
|
||||
### **หลักการ**
|
||||
|
||||
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
* หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
* โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
|
||||
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### **ฟังก์ชันหลัก (Core Functionalities)**
|
||||
|
||||
* Global **filters** สำหรับการจัดการ exception
|
||||
* **Middlewares** สำหรับการจัดการ request
|
||||
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
|
||||
|
||||
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
|
||||
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
|
||||
|
||||
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CoreModule / CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
|
||||
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
|
||||
2. **AuthModule / UserModule:**
|
||||
* จัดการ users, roles, permissions และการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
* จัดการ Master Data (เช่น correspondence_types, tags) [cite: 4.5]
|
||||
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
|
||||
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร) [cite: 3.10]
|
||||
3. **ProjectModule:**
|
||||
* จัดการ projects, organizations, contracts, project_parties, contract_parties
|
||||
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ correspondences, correspondence\revisions
|
||||
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
|
||||
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
|
||||
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence\routings) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
5. **RfaModule:**
|
||||
* จัดการ rfas, rfa_revisions, rfa_items
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
6. **DrawingModule:**
|
||||
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings และหมวดหมู่ต่างๆ
|
||||
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
|
||||
7. **CirculationModule:**
|
||||
* จัดการ circulations, circulation_templates, circulation_assignees
|
||||
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
8. **TransmittalModule:**
|
||||
* จัดการ transmittals และ transmittal_items
|
||||
9. **SearchModule:**
|
||||
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
|
||||
10. **DocumentNumberingModule:**
|
||||
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
|
||||
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
|
||||
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
|
||||
|
||||
### **เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)**
|
||||
|
||||
🔐 **Authentication & Authorization**
|
||||
|
||||
* @nestjs/passport
|
||||
* @nestjs/jwt
|
||||
* casl – สำหรับ RBAC (Role-Based Access Control)
|
||||
|
||||
🗃️ **Database & ORM**
|
||||
|
||||
* @nestjs/typeorm – ORM สำหรับ SQL (หรือ Prisma เป็นทางเลือก)
|
||||
* typeorm-seeding – สำหรับสร้างข้อมูลจำลอง (seeding)
|
||||
|
||||
📦 **Validation & Transformation**
|
||||
|
||||
* class-validator
|
||||
* class-transformer
|
||||
|
||||
📁 **File Upload & Storage**
|
||||
|
||||
* @nestjs/platform-express
|
||||
* multer – สำหรับจัดการไฟล์
|
||||
|
||||
🔍 **Search**
|
||||
|
||||
* @nestjs/elasticsearch – สำหรับ Full-text search [cite: 6.2]
|
||||
|
||||
📬 **Notification**
|
||||
|
||||
* nodemailer – สำหรับส่งอีเมล
|
||||
* @nestjs/schedule – สำหรับ cron job หรือแจ้งเตือนตามเวลา
|
||||
|
||||
📊 **Logging & Monitoring**
|
||||
|
||||
* winston หรือ nestjs-pino – ระบบ log ที่ยืดหยุ่น
|
||||
* @nestjs/terminus – สำหรับ health check
|
||||
|
||||
🧪 **Testing**
|
||||
|
||||
* @nestjs/testing
|
||||
* jest – สำหรับ unit/integration test
|
||||
|
||||
🌐 **API Documentation**
|
||||
|
||||
* @nestjs/swagger – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
|
||||
|
||||
🛡️ **Security**
|
||||
|
||||
* helmet – ป้องกันช่องโหว่ HTTP
|
||||
* rate-limiter-flexible – ป้องกัน brute force
|
||||
|
||||
### **🧪 Backend Testing**
|
||||
|
||||
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
|
||||
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
|
||||
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
|
||||
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
|
||||
|
||||
### **🗄️ Backend State Management**
|
||||
|
||||
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
|
||||
|
||||
* **Request-Scoped State (สถานะภายใน Request เดียว):**
|
||||
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
|
||||
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
|
||||
* **Application-Scoped State (การ Caching):**
|
||||
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
|
||||
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
|
||||
|
||||
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
|
||||
|
||||
### **โปรไฟล์นักพัฒนา (Developer Profile)**
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
|
||||
|
||||
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
|
||||
|
||||
* ใช้ **early returns** เพื่อความชัดเจน
|
||||
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
|
||||
* ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
|
||||
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
tabIndex="0", aria-label, onKeyDown, ฯลฯ
|
||||
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### **UI/UX ด้วย React**
|
||||
|
||||
* ใช้ **semantic HTML**
|
||||
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
|
||||
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
|
||||
|
||||
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
|
||||
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
* ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
### **🧪 Frontend Testing**
|
||||
|
||||
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เครื่องมือ:** Vitest + RTL
|
||||
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
|
||||
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
|
||||
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เครื่องมือ:** **Playwright**
|
||||
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
|
||||
|
||||
### **🗄️ Frontend State Management**
|
||||
|
||||
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
|
||||
|
||||
1. **Local UI State (สถานะ UI ชั่วคราว):**
|
||||
* **เครื่องมือ:** useState, useReducer
|
||||
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
|
||||
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
|
||||
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
|
||||
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
|
||||
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
|
||||
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
|
||||
4. **Form State (สถานะของฟอร์ม):**
|
||||
* **เครื่องมือ:** **React Hook Form** + **Zod**
|
||||
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
|
||||
|
||||
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
# **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
## **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
|
||||
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
|
||||
### **Roles (บทบาท)**
|
||||
|
||||
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
|
||||
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
|
||||
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
|
||||
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
|
||||
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
|
||||
|
||||
### **ตัวอย่าง Permissions (จากตาราง permissions)**
|
||||
|
||||
* rfas.view, rfas.create, rfas.respond, rfas.delete
|
||||
* drawings.view, drawings.upload, drawings.delete
|
||||
* corr.view, corr.manage
|
||||
* transmittals.manage
|
||||
* cirs.manage
|
||||
* project\parties.manage
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
|
||||
|
||||
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
| :---- | :---- | :---- |
|
||||
| audit_id | BIGINT | Primary Key |
|
||||
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
|
||||
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
|
||||
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
|
||||
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
|
||||
| created_at | TIMESTAMP | Timestamp (UTC) |
|
||||
|
||||
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
|
||||
|
||||
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
|
||||
|
||||
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
|
||||
* circulation_attachments (เชื่อม Circulation กับ Attachments)
|
||||
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
|
||||
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
|
||||
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
|
||||
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
|
||||
* ขนาดสูงสุด: **50 MB**
|
||||
* จัดเก็บนอก webroot
|
||||
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
|
||||
|
||||
### **การควบคุมการเข้าถึง (Access Control)**
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน attachment
|
||||
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
|
||||
|
||||
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
|
||||
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
|
||||
* **ตาราง SQL:**
|
||||
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
|
||||
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
|
||||
* **การทำงาน (Backend):**
|
||||
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
|
||||
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
|
||||
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
|
||||
|
||||
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
|
||||
|
||||
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
|
||||
* v_audit_log_details: สำหรับ Activity Feed
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### **กฎการส่งออก (Export Rules)**
|
||||
|
||||
* Export formats: CSV, Excel, PDF.
|
||||
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
|
||||
|
||||
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
|
||||
|
||||
### **DataTable (Server‑Side)**
|
||||
|
||||
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
|
||||
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### **มาตรฐานฟอร์ม (Form Standards)**
|
||||
|
||||
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
* Project → Contract Drawing Volumes
|
||||
* Contract Drawing Category → Sub-Category
|
||||
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
|
||||
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
|
||||
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
|
||||
|
||||
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
|
||||
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
|
||||
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
|
||||
|
||||
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
|
||||
|
||||
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
|
||||
|
||||
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
|
||||
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
|
||||
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### **ฟีดกิจกรรม (Activity Feed)**
|
||||
|
||||
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
|
||||
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
|
||||
|
||||
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
|
||||
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
|
||||
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
|
||||
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
|
||||
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
|
||||
|
||||
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
|
||||
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
|
||||
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
|
||||
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
|
||||
|
||||
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
|
||||
# **Documents Management Sytem Version 1.2.1: แนวทางการพัฒนา FullStackJS**
|
||||
|
||||
## **🧠 ปรัชญาทั่วไป**
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
|
||||
|
||||
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
|
||||
|
||||
### **หลักการพื้นฐาน**
|
||||
|
||||
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ดและเอกสารทั้งหมด
|
||||
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
|
||||
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
| :---- | :---- | :---- |
|
||||
| Classes | PascalCase | UserService |
|
||||
| Variables & Functions | camelCase | getUserInfo |
|
||||
| Files & Folders | kebab-case | user-service.ts |
|
||||
| Environment Variables | UPPERCASE | DATABASE\URL |
|
||||
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
|
||||
|
||||
## **🧩 ฟังก์ชัน (Functions)**
|
||||
|
||||
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
* ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
## **🧱 การจัดการข้อมูล (Data Handling)**
|
||||
|
||||
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
|
||||
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
## **🧰 คลาส (Classes)**
|
||||
|
||||
* ปฏิบัติตามหลักการ **SOLID**
|
||||
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
* กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
|
||||
|
||||
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
|
||||
|
||||
* ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
|
||||
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
|
||||
|
||||
# **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
|
||||
|
||||
### **หลักการ**
|
||||
|
||||
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
* หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
* โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
|
||||
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### **ฟังก์ชันหลัก (Core Functionalities)**
|
||||
|
||||
* Global **filters** สำหรับการจัดการ exception
|
||||
* **Middlewares** สำหรับการจัดการ request
|
||||
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
|
||||
|
||||
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
|
||||
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
|
||||
|
||||
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CoreModule / CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
|
||||
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
|
||||
2. **AuthModule / UserModule:**
|
||||
* จัดการ users, roles, permissions และการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
* จัดการ Master Data (เช่น correspondence_types, tags) [cite: 4.5]
|
||||
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
|
||||
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร) [cite: 3.10]
|
||||
3. **ProjectModule:**
|
||||
* จัดการ projects, organizations, contracts, project_parties, contract_parties
|
||||
4. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ correspondences, correspondence\revisions
|
||||
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
|
||||
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
|
||||
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence\routings) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
5. **RfaModule:**
|
||||
* จัดการ rfas, rfa_revisions, rfa_items
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
6. **DrawingModule:**
|
||||
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings และหมวดหมู่ต่างๆ
|
||||
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
|
||||
7. **CirculationModule:**
|
||||
* จัดการ circulations, circulation_templates, circulation_assignees
|
||||
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
8. **TransmittalModule:**
|
||||
* จัดการ transmittals และ transmittal_items
|
||||
9. **SearchModule:**
|
||||
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
|
||||
10. **DocumentNumberingModule:**
|
||||
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
|
||||
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
|
||||
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
|
||||
|
||||
### **เครื่องมือและไลบรารีที่แนะนำ (Recommended Tools & Libraries)**
|
||||
|
||||
🔐 **Authentication & Authorization**
|
||||
|
||||
* @nestjs/passport
|
||||
* @nestjs/jwt
|
||||
* casl – สำหรับ RBAC (Role-Based Access Control)
|
||||
|
||||
🗃️ **Database & ORM**
|
||||
|
||||
* @nestjs/typeorm – ORM สำหรับ SQL (หรือ Prisma เป็นทางเลือก)
|
||||
* typeorm-seeding – สำหรับสร้างข้อมูลจำลอง (seeding)
|
||||
|
||||
📦 **Validation & Transformation**
|
||||
|
||||
* class-validator
|
||||
* class-transformer
|
||||
|
||||
📁 **File Upload & Storage**
|
||||
|
||||
* @nestjs/platform-express
|
||||
* multer – สำหรับจัดการไฟล์
|
||||
|
||||
🔍 **Search**
|
||||
|
||||
* @nestjs/elasticsearch – สำหรับ Full-text search [cite: 6.2]
|
||||
|
||||
📬 **Notification**
|
||||
|
||||
* nodemailer – สำหรับส่งอีเมล
|
||||
* @nestjs/schedule – สำหรับ cron job หรือแจ้งเตือนตามเวลา
|
||||
|
||||
📊 **Logging & Monitoring**
|
||||
|
||||
* winston หรือ nestjs-pino – ระบบ log ที่ยืดหยุ่น
|
||||
* @nestjs/terminus – สำหรับ health check
|
||||
|
||||
🧪 **Testing**
|
||||
|
||||
* @nestjs/testing
|
||||
* jest – สำหรับ unit/integration test
|
||||
|
||||
🌐 **API Documentation**
|
||||
|
||||
* @nestjs/swagger – **(สำคัญมาก)** สร้าง Swagger UI อัตโนมัติ ต้องใช้ DTOs อย่างเคร่งครัดเพื่อความชัดเจนของ API สำหรับทีม Frontend
|
||||
|
||||
🛡️ **Security**
|
||||
|
||||
* helmet – ป้องกันช่องโหว่ HTTP
|
||||
* rate-limiter-flexible – ป้องกัน brute force
|
||||
|
||||
### **🧪 Backend Testing**
|
||||
|
||||
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
|
||||
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
|
||||
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
|
||||
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
|
||||
|
||||
### **🗄️ Backend State Management**
|
||||
|
||||
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
|
||||
|
||||
* **Request-Scoped State (สถานะภายใน Request เดียว):**
|
||||
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
|
||||
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
|
||||
* **Application-Scoped State (การ Caching):**
|
||||
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
|
||||
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
|
||||
|
||||
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
|
||||
|
||||
### **โปรไฟล์นักพัฒนา (Developer Profile)**
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
|
||||
|
||||
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
|
||||
|
||||
* ใช้ **early returns** เพื่อความชัดเจน
|
||||
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
|
||||
* ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
|
||||
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
tabIndex="0", aria-label, onKeyDown, ฯลฯ
|
||||
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### **UI/UX ด้วย React**
|
||||
|
||||
* ใช้ **semantic HTML**
|
||||
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
|
||||
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
|
||||
|
||||
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
|
||||
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
* ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
### **🧪 Frontend Testing**
|
||||
|
||||
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เครื่องมือ:** Vitest + RTL
|
||||
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
|
||||
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
|
||||
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เครื่องมือ:** **Playwright**
|
||||
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
|
||||
|
||||
### **🗄️ Frontend State Management**
|
||||
|
||||
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
|
||||
|
||||
1. **Local UI State (สถานะ UI ชั่วคราว):**
|
||||
* **เครื่องมือ:** useState, useReducer
|
||||
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
|
||||
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
|
||||
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
|
||||
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
|
||||
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
|
||||
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
|
||||
4. **Form State (สถานะของฟอร์ม):**
|
||||
* **เครื่องมือ:** **React Hook Form** + **Zod**
|
||||
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
|
||||
|
||||
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
# **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
## **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
|
||||
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
|
||||
### **Roles (บทบาท)**
|
||||
|
||||
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
|
||||
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
|
||||
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
|
||||
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
|
||||
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
|
||||
|
||||
### **ตัวอย่าง Permissions (จากตาราง permissions)**
|
||||
|
||||
* rfas.view, rfas.create, rfas.respond, rfas.delete
|
||||
* drawings.view, drawings.upload, drawings.delete
|
||||
* corr.view, corr.manage
|
||||
* transmittals.manage
|
||||
* cirs.manage
|
||||
* project\parties.manage
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
|
||||
|
||||
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
| :---- | :---- | :---- |
|
||||
| audit_id | BIGINT | Primary Key |
|
||||
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
|
||||
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
|
||||
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
|
||||
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
|
||||
| created_at | TIMESTAMP | Timestamp (UTC) |
|
||||
|
||||
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
|
||||
|
||||
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
|
||||
|
||||
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
|
||||
* circulation_attachments (เชื่อม Circulation กับ Attachments)
|
||||
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
|
||||
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
|
||||
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
|
||||
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
|
||||
* ขนาดสูงสุด: **50 MB**
|
||||
* จัดเก็บนอก webroot
|
||||
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
|
||||
|
||||
### **การควบคุมการเข้าถึง (Access Control)**
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน attachment
|
||||
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
|
||||
|
||||
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
|
||||
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
|
||||
* **ตาราง SQL:**
|
||||
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
|
||||
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
|
||||
* **การทำงาน (Backend):**
|
||||
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
|
||||
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
|
||||
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
|
||||
|
||||
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
|
||||
|
||||
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
|
||||
* v_audit_log_details: สำหรับ Activity Feed
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### **กฎการส่งออก (Export Rules)**
|
||||
|
||||
* Export formats: CSV, Excel, PDF.
|
||||
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
|
||||
|
||||
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
|
||||
|
||||
### **DataTable (Server‑Side)**
|
||||
|
||||
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
|
||||
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### **มาตรฐานฟอร์ม (Form Standards)**
|
||||
|
||||
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
* Project → Contract Drawing Volumes
|
||||
* Contract Drawing Category → Sub-Category
|
||||
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
|
||||
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
|
||||
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
|
||||
|
||||
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
|
||||
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
|
||||
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
|
||||
|
||||
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
|
||||
|
||||
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
|
||||
|
||||
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
|
||||
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
|
||||
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### **ฟีดกิจกรรม (Activity Feed)**
|
||||
|
||||
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
|
||||
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
|
||||
|
||||
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
|
||||
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
|
||||
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
|
||||
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
|
||||
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
|
||||
|
||||
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
|
||||
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
|
||||
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
|
||||
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
|
||||
|
||||
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
|
||||
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
|
||||
@@ -1,210 +1,210 @@
|
||||
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
|
||||
|
||||
## **📌 1. วัตถุประสงค์**
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
* Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
* Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
* Development Environment: VS Code on Windows 11
|
||||
* Domain: np-dms.work, www.np-dms.work
|
||||
* ip: 159.192.126.103
|
||||
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
* Data Storage: /share/dms-data บน QNAP
|
||||
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
* Application name: git
|
||||
* Service: Gitea (Self-hosted on QNAP)
|
||||
* Service name: gitea
|
||||
* Domain: git.np-dms.work
|
||||
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
* Application name: lcbp3-backend
|
||||
* Service: NestJS
|
||||
* Service name: backend
|
||||
* Domain: backend.np-dms.work
|
||||
* Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
* Application name: lcbp3-db
|
||||
* Service: mariadb:10.11
|
||||
* Service name: mariadb
|
||||
* Domain: db.np-dms.work
|
||||
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
* Application name: lcbp3-db
|
||||
* Service: phpmyadmin:5-apache
|
||||
* Service name: pma
|
||||
* Domain: pma.np-dms.work
|
||||
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
* Application name: lcbp3-frontend
|
||||
* Service: next.js
|
||||
* Service name: frontend
|
||||
* Domain: lcbp3.np-dms.work
|
||||
* Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
* Styling: Tailwind CSS + PostCSS
|
||||
* Component Library: shadcn/ui
|
||||
* หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
* Application name: lcbp3-n8n
|
||||
* Service: n8nio/n8n:latest
|
||||
* Service name: n8n
|
||||
* Domain: n8n.np-dms.work
|
||||
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
* Application name: lcbp3-npm
|
||||
* Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
* Service name: npm
|
||||
* Domain: npm.np-dms.work
|
||||
* หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
|
||||
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
|
||||
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
|
||||
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
|
||||
|
||||
## **📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
* 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
* 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
* 3.1.3. องค์กร (Organizations):
|
||||
* มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
* Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
* 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กร
|
||||
* 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
* 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
* Request for Drawing Approval (RFA_DWG)
|
||||
* Request for Document Approval (RFA_DOC)
|
||||
* Request for Method statement Approval (RFA_MES)
|
||||
* Request for Material Approval (RFA_MAT)
|
||||
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
* 3.7.5. การติดตามงาน:
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
|
||||
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
|
||||
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
|
||||
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
|
||||
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
|
||||
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
|
||||
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
|
||||
|
||||
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
* Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
|
||||
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
|
||||
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
|
||||
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
|
||||
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
|
||||
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
|
||||
* Tags ที่ใช้ในระบบ
|
||||
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
|
||||
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
|
||||
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
|
||||
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
|
||||
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
|
||||
|
||||
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
* Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
* Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
* การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
* ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
|
||||
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
|
||||
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
|
||||
|
||||
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
|
||||
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
|
||||
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
|
||||
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (Notification Strategy):
|
||||
* ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ ดังนี้:
|
||||
1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
|
||||
2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
|
||||
3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
|
||||
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
|
||||
|
||||
## **📌 1. วัตถุประสงค์**
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
* Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
* Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
* Development Environment: VS Code on Windows 11
|
||||
* Domain: np-dms.work, www.np-dms.work
|
||||
* ip: 159.192.126.103
|
||||
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
* Data Storage: /share/dms-data บน QNAP
|
||||
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
* Application name: git
|
||||
* Service: Gitea (Self-hosted on QNAP)
|
||||
* Service name: gitea
|
||||
* Domain: git.np-dms.work
|
||||
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
* Application name: lcbp3-backend
|
||||
* Service: NestJS
|
||||
* Service name: backend
|
||||
* Domain: backend.np-dms.work
|
||||
* Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
* Application name: lcbp3-db
|
||||
* Service: mariadb:10.11
|
||||
* Service name: mariadb
|
||||
* Domain: db.np-dms.work
|
||||
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
* Application name: lcbp3-db
|
||||
* Service: phpmyadmin:5-apache
|
||||
* Service name: pma
|
||||
* Domain: pma.np-dms.work
|
||||
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
* Application name: lcbp3-frontend
|
||||
* Service: next.js
|
||||
* Service name: frontend
|
||||
* Domain: lcbp3.np-dms.work
|
||||
* Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
* Styling: Tailwind CSS + PostCSS
|
||||
* Component Library: shadcn/ui
|
||||
* หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
* Application name: lcbp3-n8n
|
||||
* Service: n8nio/n8n:latest
|
||||
* Service name: n8n
|
||||
* Domain: n8n.np-dms.work
|
||||
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
* Application name: lcbp3-npm
|
||||
* Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
* Service name: npm
|
||||
* Domain: npm.np-dms.work
|
||||
* หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
|
||||
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
|
||||
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
|
||||
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
|
||||
|
||||
## **📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
* 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
* 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
* 3.1.3. องค์กร (Organizations):
|
||||
* มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
* Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
* 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กร
|
||||
* 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
* 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
* Request for Drawing Approval (RFA_DWG)
|
||||
* Request for Document Approval (RFA_DOC)
|
||||
* Request for Method statement Approval (RFA_MES)
|
||||
* Request for Material Approval (RFA_MAT)
|
||||
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
* 3.7.5. การติดตามงาน:
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
|
||||
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
|
||||
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
|
||||
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
|
||||
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
|
||||
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
|
||||
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
|
||||
|
||||
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
* Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
|
||||
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
|
||||
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
|
||||
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
|
||||
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
|
||||
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
|
||||
* Tags ที่ใช้ในระบบ
|
||||
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
|
||||
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
|
||||
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
|
||||
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
|
||||
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
|
||||
|
||||
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
* Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
* Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
* การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
* ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
|
||||
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
|
||||
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
|
||||
|
||||
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
|
||||
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
|
||||
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
|
||||
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (Notification Strategy):
|
||||
* ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ ดังนี้:
|
||||
1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
|
||||
2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
|
||||
3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
|
||||
4. (ทางเลือก) เมื่อใกล้ถึงวันครบกำหนด (Deadline) [cite: 3.2.5, 3.6.6, 3.7.5]
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,478 +1,478 @@
|
||||
# **Documents Management Sytem Version 1.3.0: แนวทางการพัฒนา FullStackJS**
|
||||
|
||||
## **🧠 ปรัชญาทั่วไป**
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
|
||||
|
||||
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
|
||||
|
||||
### **หลักการพื้นฐาน**
|
||||
|
||||
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
|
||||
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
|
||||
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
|
||||
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
|
||||
|
||||
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
| :---- | :---- | :---- |
|
||||
| Classes | PascalCase | UserService |
|
||||
| Property | snake_sase | user_id |
|
||||
| Variables & Functions | camelCase | getUserInfo |
|
||||
| Files & Folders | kebab-case | user-service.ts |
|
||||
| Environment Variables | UPPERCASE | DATABASE\URL |
|
||||
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
|
||||
|
||||
## **🧩 ฟังก์ชัน (Functions)**
|
||||
|
||||
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
* ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
## **🧱 การจัดการข้อมูล (Data Handling)**
|
||||
|
||||
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
|
||||
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
## **🧰 คลาส (Classes)**
|
||||
|
||||
* ปฏิบัติตามหลักการ **SOLID**
|
||||
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
* กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
|
||||
|
||||
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
|
||||
|
||||
* ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
|
||||
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
|
||||
|
||||
## **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
|
||||
|
||||
### **หลักการ**
|
||||
|
||||
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
* หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
* โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
|
||||
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
|
||||
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### **ฟังก์ชันหลัก (Core Functionalities)**
|
||||
|
||||
* Global **filters** สำหรับการจัดการ exception
|
||||
* **Middlewares** สำหรับการจัดการ request
|
||||
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
|
||||
|
||||
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
|
||||
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
|
||||
|
||||
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
|
||||
* จัดการ audit_logs
|
||||
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
|
||||
2. **AuthModule:**
|
||||
* จัดการะการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
|
||||
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
|
||||
3. **UserModule:**
|
||||
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
4. **ProjectModule:**
|
||||
* จัดการ projects, organizations, contracts, project_parties, contract_parties
|
||||
5. **MasterModule:**
|
||||
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
|
||||
6. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ correspondences, correspondence_revisions, correspondence_tags
|
||||
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
|
||||
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
|
||||
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence_routings, correspondence_routing_templates) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
7. **RfaModule:**
|
||||
* จัดการ rfas, rfa_revisions, rfa_items
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
8. **DrawingModule:**
|
||||
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
|
||||
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
|
||||
9. **CirculationModule:**
|
||||
* จัดการ circulations, circulation_templates, circulation_assignees
|
||||
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
10. **TransmittalModule:**
|
||||
* จัดการ transmittals และ transmittal_items
|
||||
11. **SearchModule:**
|
||||
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
|
||||
12. **DocumentNumberingModule:**
|
||||
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
|
||||
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
|
||||
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
|
||||
|
||||
### **สถาปัตยกรรมระบบ (System Architecture)**
|
||||
|
||||
โครงสร้างโมดูล (Module Structure)
|
||||
|
||||
```bash
|
||||
📁 src
|
||||
├── 📄 app.module.ts
|
||||
├── 📄 main.ts
|
||||
├── 📁 common # @app/common (โมดูลส่วนกลาง)
|
||||
│ ├── 📁 auth # AuthModule (JWT, Guards)
|
||||
│ ├── 📁 config # Configuration
|
||||
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
|
||||
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
|
||||
│ ├── 📁 exceptions # Global Exception Filters
|
||||
│ ├── 📁 file-storage # FileStorageService
|
||||
│ ├── 📁 guards # Custom Guards (RBAC Guard)
|
||||
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform)
|
||||
│ └── 📁 services # Shared Services (NotificationService)
|
||||
├── 📁 modules
|
||||
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
|
||||
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
|
||||
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
|
||||
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
|
||||
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
|
||||
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
|
||||
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
|
||||
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
|
||||
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
|
||||
└── 📁 database # Database Migration & Seeding Scripts
|
||||
```
|
||||
|
||||
### **เเทคโนโลยีที่ใช้ (Technology Stack)**
|
||||
|
||||
| ส่วน | Library/Tool | หมายเหตุ |
|
||||
|---|---|---|
|
||||
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
|
||||
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
|
||||
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
|
||||
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
|
||||
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
|
||||
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
|
||||
|**Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
|
||||
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
|
||||
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
|
||||
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
|
||||
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
|
||||
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
|
||||
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
|
||||
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
|
||||
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
|
||||
|
||||
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
|
||||
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
|
||||
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
|
||||
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
|
||||
|
||||
### **🗄️ Backend State Management**
|
||||
|
||||
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
|
||||
|
||||
* **Request-Scoped State (สถานะภายใน Request เดียว):**
|
||||
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
|
||||
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
|
||||
* **Application-Scoped State (การ Caching):**
|
||||
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
|
||||
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
|
||||
|
||||
### **การไหลของข้อมูล (Data Flow)**
|
||||
|
||||
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
|
||||
2. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
|
||||
3. Authorization: RBAC Guard (ใช้ CASL) ตรวจสอบสิทธิ์จาก Decorators (@RequirePermission)
|
||||
4. Validation: Validation Pipe (ใช้ class-validator) ตรวจสอบ DTO
|
||||
5. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
|
||||
6. Data Access: Repository Layer (ใช้ TypeORM) ติดต่อกับฐานข้อมูล MariaDB
|
||||
7. Response: ส่งกลับไปยัง Frontend พร้อมสถานะและข้อมูลที่เหมาะสม
|
||||
|
||||
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
|
||||
|
||||
### **โปรไฟล์นักพัฒนา (Developer Profile)**
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
|
||||
|
||||
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
|
||||
|
||||
* ใช้ **early returns** เพื่อความชัดเจน
|
||||
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
|
||||
* ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
|
||||
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
tabIndex="0", aria-label, onKeyDown, ฯลฯ
|
||||
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### **UI/UX ด้วย React**
|
||||
|
||||
* ใช้ **semantic HTML**
|
||||
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
|
||||
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
|
||||
|
||||
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
|
||||
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
* ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
### **🧪 Frontend Testing**
|
||||
|
||||
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เครื่องมือ:** Vitest + RTL
|
||||
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
|
||||
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
|
||||
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เครื่องมือ:** **Playwright**
|
||||
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
|
||||
|
||||
### **🗄️ Frontend State Management**
|
||||
|
||||
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
|
||||
|
||||
1. **Local UI State (สถานะ UI ชั่วคราว):**
|
||||
* **เครื่องมือ:** useState, useReducer
|
||||
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
|
||||
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
|
||||
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
|
||||
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
|
||||
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
|
||||
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
|
||||
4. **Form State (สถานะของฟอร์ม):**
|
||||
* **เครื่องมือ:** **React Hook Form** + **Zod**
|
||||
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
|
||||
|
||||
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
## **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
### **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
|
||||
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
|
||||
### **Roles (บทบาท)**
|
||||
|
||||
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
|
||||
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
|
||||
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
|
||||
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
|
||||
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
|
||||
|
||||
### **ตัวอย่าง Permissions (จากตาราง permissions)**
|
||||
|
||||
* rfas.view, rfas.create, rfas.respond, rfas.delete
|
||||
* drawings.view, drawings.upload, drawings.delete
|
||||
* corr.view, corr.manage
|
||||
* transmittals.manage
|
||||
* cirs.manage
|
||||
* project\parties.manage
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
|
||||
|
||||
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
| :---- | :---- | :---- |
|
||||
| audit_id | BIGINT | Primary Key |
|
||||
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
|
||||
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
|
||||
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
|
||||
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
|
||||
| created_at | TIMESTAMP | Timestamp (UTC) |
|
||||
|
||||
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
|
||||
|
||||
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
|
||||
|
||||
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
|
||||
* circulation_attachments (เชื่อม Circulation กับ Attachments)
|
||||
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
|
||||
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
|
||||
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
|
||||
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
|
||||
* ขนาดสูงสุด: **50 MB**
|
||||
* จัดเก็บนอก webroot
|
||||
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
|
||||
|
||||
### **การควบคุมการเข้าถึง (Access Control)**
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน attachment
|
||||
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
|
||||
|
||||
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
|
||||
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
|
||||
* **ตาราง SQL:**
|
||||
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
|
||||
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
|
||||
* **การทำงาน (Backend):**
|
||||
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
|
||||
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
|
||||
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
|
||||
|
||||
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
|
||||
|
||||
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
|
||||
* v_audit_log_details: สำหรับ Activity Feed
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### **กฎการส่งออก (Export Rules)**
|
||||
|
||||
* Export formats: CSV, Excel, PDF.
|
||||
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
|
||||
|
||||
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
|
||||
|
||||
### **DataTable (Server‑Side)**
|
||||
|
||||
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
|
||||
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### **มาตรฐานฟอร์ม (Form Standards)**
|
||||
|
||||
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
* Project → Contract Drawing Volumes
|
||||
* Contract Drawing Category → Sub-Category
|
||||
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
|
||||
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
|
||||
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
|
||||
|
||||
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
|
||||
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
|
||||
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
|
||||
|
||||
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
|
||||
|
||||
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
|
||||
|
||||
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
|
||||
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
|
||||
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### **ฟีดกิจกรรม (Activity Feed)**
|
||||
|
||||
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
|
||||
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
|
||||
|
||||
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
|
||||
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
|
||||
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
|
||||
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
|
||||
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
|
||||
|
||||
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
|
||||
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
|
||||
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
|
||||
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
|
||||
|
||||
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
|
||||
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
|
||||
# **Documents Management Sytem Version 1.3.0: แนวทางการพัฒนา FullStackJS**
|
||||
|
||||
## **🧠 ปรัชญาทั่วไป**
|
||||
|
||||
แนวทางปฏิบัติที่ดีที่สุดแบบครบวงจรสำหรับการพัฒนา NestJS Backend, NextJS Frontend และ Tailwind-based UI/UX ในสภาพแวดล้อม TypeScript มุ่งเน้นที่ ความชัดเจน (clarity), ความง่ายในการบำรุงรักษา (maintainability), ความสอดคล้องกัน (consistency) และ การเข้าถึงได้ (accessibility) ตลอดทั้งสแต็ก
|
||||
|
||||
## **⚙️ แนวทางทั่วไปสำหรับ TypeScript**
|
||||
|
||||
### **หลักการพื้นฐาน**
|
||||
|
||||
* ใช้ **ภาษาอังกฤษ** สำหรับโค้ด
|
||||
* ใช้ **ภาษาไทย** สำหรับ comment และเอกสารทั้งหมด
|
||||
* กำหนดไทป์ (type) อย่างชัดเจนสำหรับตัวแปร, พารามิเตอร์ และค่าที่ส่งกลับ (return values) ทั้งหมด
|
||||
* หลีกเลี่ยงการใช้ any; ให้สร้างไทป์ (types) หรืออินเทอร์เฟซ (interfaces) ที่กำหนดเอง
|
||||
* ใช้ **JSDoc** สำหรับคลาส (classes) และเมธอด (methods) ที่เป็น public
|
||||
* ส่งออก (Export) **สัญลักษณ์หลัก (main symbol) เพียงหนึ่งเดียว** ต่อไฟล์
|
||||
* หลีกเลี่ยงบรรทัดว่างภายในฟังก์ชัน
|
||||
* ระบุ // File: path/filename ในบรรทัดแรกของทุกไฟล์
|
||||
* ระบุ // บันทึกการแก้ไข, หากมีการแก้ไขเพิ่มในอนาคต ให้เพิ่มบันทึก
|
||||
|
||||
### **ข้อตกลงในการตั้งชื่อ (Naming Conventions)**
|
||||
|
||||
| Entity (สิ่งที่ตั้งชื่อ) | Convention (รูปแบบ) | Example (ตัวอย่าง) |
|
||||
| :---- | :---- | :---- |
|
||||
| Classes | PascalCase | UserService |
|
||||
| Property | snake_sase | user_id |
|
||||
| Variables & Functions | camelCase | getUserInfo |
|
||||
| Files & Folders | kebab-case | user-service.ts |
|
||||
| Environment Variables | UPPERCASE | DATABASE\URL |
|
||||
| Booleans | Verb \+ Noun | isActive, canDelete, hasPermission |
|
||||
|
||||
ใช้คำเต็ม — ไม่ใช้อักษรย่อ — ยกเว้นคำมาตรฐาน (เช่น API, URL, req, res, err, ctx)
|
||||
|
||||
## **🧩 ฟังก์ชัน (Functions)**
|
||||
|
||||
* เขียนฟังก์ชันให้สั้น และทำ **หน้าที่เพียงอย่างเดียว** (single-purpose) (\< 20 บรรทัด)
|
||||
* ใช้ **early returns** เพื่อลดการซ้อน (nesting) ของโค้ด
|
||||
* ใช้ **map**, **filter**, **reduce** แทนการใช้ loops เมื่อเหมาะสม
|
||||
* ควรใช้ **arrow functions** สำหรับตรรกะสั้นๆ, และใช้ **named functions** ในกรณีอื่น
|
||||
* ใช้ **default parameters** แทนการตรวจสอบค่า null
|
||||
* จัดกลุ่มพารามิเตอร์หลายตัวให้เป็นอ็อบเจกต์เดียว (RO-RO pattern)
|
||||
* ส่งค่ากลับ (Return) เป็นอ็อบเจกต์ที่มีไทป์กำหนด (typed objects) ไม่ใช่ค่าพื้นฐาน (primitives)
|
||||
* รักษาระดับของสิ่งที่เป็นนามธรรม (abstraction level) ให้เป็นระดับเดียวในแต่ละฟังก์ชัน
|
||||
|
||||
## **🧱 การจัดการข้อมูล (Data Handling)**
|
||||
|
||||
* ห่อหุ้มข้อมูล (Encapsulate) ในไทป์แบบผสม (composite types)
|
||||
* ใช้ **immutability** (การไม่เปลี่ยนแปลงค่า) ด้วย readonly และ as const
|
||||
* ทำการตรวจสอบความถูกต้องของข้อมูล (Validations) ในคลาสหรือ DTOs ไม่ใช่ภายในฟังก์ชันทางธุรกิจ
|
||||
* ตรวจสอบความถูกต้องของข้อมูลโดยใช้ DTOs ที่มีไทป์กำหนดเสมอ
|
||||
|
||||
## **🧰 คลาส (Classes)**
|
||||
|
||||
* ปฏิบัติตามหลักการ **SOLID**
|
||||
* ควรใช้ **composition มากกว่า inheritance** (Prefer composition over inheritance)
|
||||
* กำหนด **interfaces** สำหรับสัญญา (contracts)
|
||||
* ให้คลาสมุ่งเน้นการทำงานเฉพาะอย่างและมีขนาดเล็ก (\< 200 บรรทัด, \< 10 เมธอด, \< 10 properties)
|
||||
|
||||
## **🚨 การจัดการข้อผิดพลาด (Error Handling)**
|
||||
|
||||
* ใช้ Exceptions สำหรับข้อผิดพลาดที่ไม่คาดคิด
|
||||
* ดักจับ (Catch) ข้อผิดพลาดเพื่อแก้ไขหรือเพิ่มบริบท (context) เท่านั้น; หากไม่เช่นนั้น ให้ใช้ global error handlers
|
||||
* ระบุข้อความข้อผิดพลาด (error messages) ที่มีความหมายเสมอ
|
||||
|
||||
## **🧪 การทดสอบ (ทั่วไป) (Testing (General))**
|
||||
|
||||
* ใช้รูปแบบ **Arrange–Act–Assert**
|
||||
* ใช้ชื่อตัวแปรในการทดสอบที่สื่อความหมาย (inputData, expectedOutput)
|
||||
* เขียน **unit tests** สำหรับ public methods ทั้งหมด
|
||||
* จำลอง (Mock) การพึ่งพาภายนอก (external dependencies)
|
||||
* เพิ่ม **acceptance tests** ต่อโมดูลโดยใช้รูปแบบ Given–When-Then
|
||||
|
||||
## **🏗️ แบ็กเอนด์ (NestJS) (Backend (NestJS))**
|
||||
|
||||
### **หลักการ**
|
||||
|
||||
* **สถาปัตยกรรมแบบโมดูลาร์ (Modular architecture)**:
|
||||
* หนึ่งโมดูลต่อหนึ่งโดเมน
|
||||
* โครงสร้างแบบ Controller → Service → Repository (Model)
|
||||
* API-First: มุ่งเน้นการสร้าง API ที่มีคุณภาพสูง มีเอกสารประกอบ (Swagger) ที่ชัดเจนสำหรับ Frontend Team
|
||||
* DTOs ที่ตรวจสอบความถูกต้องด้วย **class-validator**
|
||||
* ใช้ **MikroORM** (หรือ TypeORM/Prisma) สำหรับการคงอยู่ของข้อมูล (persistence) ซึ่งสอดคล้องกับสคีมา MariaDB
|
||||
* ห่อหุ้มโค้ดที่ใช้ซ้ำได้ไว้ใน **common module** (@app/common):
|
||||
* Configs, decorators, DTOs, guards, interceptors, notifications, shared services, types, validators
|
||||
|
||||
### **ฟังก์ชันหลัก (Core Functionalities)**
|
||||
|
||||
* Global **filters** สำหรับการจัดการ exception
|
||||
* **Middlewares** สำหรับการจัดการ request
|
||||
* **Guards** สำหรับการอนุญาต (permissions) และ RBAC
|
||||
* **Interceptors** สำหรับการแปลงข้อมูล response และการบันทึก log
|
||||
|
||||
### **ข้อจำกัดในการ Deploy (QNAP Container Station)**
|
||||
|
||||
* **ห้ามใช้ไฟล์ .env** ในการตั้งค่า Environment Variables [cite: 2.1]
|
||||
* การตั้งค่าทั้งหมด (เช่น Database connection string, JWT secret) **จะต้องถูกกำหนดผ่าน Environment Variable ใน docker-compose.yml โดยตรง** [cite: 6.5] ซึ่งจะจัดการผ่าน UI ของ QNAP Container Station [cite: 2.1]
|
||||
|
||||
### **โครงสร้างโมดูลตามโดเมน (Domain-Driven Module Structure)**
|
||||
|
||||
เพื่อให้สอดคล้องกับสคีมา SQL (LCBP3-DMS) เราจะใช้โครงสร้างโมดูลแบบ **Domain-Driven (แบ่งตามขอบเขตธุรกิจ)** แทนการแบ่งตามฟังก์ชัน:
|
||||
|
||||
1. **CommonModule:**
|
||||
* เก็บ Services ที่ใช้ร่วมกัน เช่น DatabaseModule, FileStorageService (จัดการไฟล์ใน QNAP), AuditLogService, NotificationService
|
||||
* จัดการ audit_logs
|
||||
* NotificationService ต้องรองรับ Triggers ที่ระบุใน Requirement 6.7 [cite: 6.7]
|
||||
2. **AuthModule:**
|
||||
* จัดการะการยืนยันตัวตน (JWT, Guards)
|
||||
* **(สำคัญ)** ต้องรับผิดชอบการตรวจสอบสิทธิ์ **3 ระดับ** [cite: 4.2]: สิทธิ์ระดับระบบ (Global Role), สิทธิ์ระดับโปรเจกต์ (Project Role), และ **สิทธิ์ระดับสัญญา (Contract Role)**
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
* ให้ Superadmin สร้าง Organizations และกำหนด Org Admin ได้ [cite: 4.6]
|
||||
* ให้ Superadmin/Admin จัดการ document_number_formats (รูปแบบเลขที่เอกสาร), document_number_counters (Running Number) [cite: 3.10]
|
||||
3. **UserModule:**
|
||||
* จัดการ users, roles, permissions, global_default_roles, role_permissions, user_roles, user_project_roles
|
||||
* **(สำคัญ)** ต้องมี API สำหรับ **Admin Panel** เพื่อ:
|
||||
* สร้างและจัดการ Role และการจับคู่ Permission แบบไดนามิก [cite: 4.3]
|
||||
4. **ProjectModule:**
|
||||
* จัดการ projects, organizations, contracts, project_parties, contract_parties
|
||||
5. **MasterModule:**
|
||||
* จัดการ master data (correspondence_types, rfa_types, rfa_status_codes, rfa_approve_codes, circulation_status_codes, correspondence_types, correspondence_status, tags) [cite: 4.5]
|
||||
6. **CorrespondenceModule (โมดูลศูนย์กลาง):**
|
||||
* จัดการ correspondences, correspondence_revisions, correspondence_tags
|
||||
* **(สำคัญ)** Service นี้ต้อง Inject DocumentNumberingService เพื่อขอเลขที่เอกสารใหม่ก่อนการสร้าง
|
||||
* **(สำคัญ)** ตรรกะการสร้าง/อัปเดต Revision จะอยู่ใน Service นี้
|
||||
* จัดการ correspondence_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Correspondence Routings"** (correspondence_routings, correspondence_routing_templates) สำหรับการส่งต่อเอกสารทั่วไประหว่างองค์กร
|
||||
7. **RfaModule:**
|
||||
* จัดการ rfas, rfa_revisions, rfa_items
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"RFA Workflows"** (rfa_workflows, rfa_workflow_templates, rfa_workflow_template_steps, rfa_status_transitions) สำหรับการอนุมัติเอกสารทางเทคนิค
|
||||
8. **DrawingModule:**
|
||||
* จัดการ shop_drawings, shop_drawing_revisions, contract_drawings, contract_drawing_volumes, contract_drawing_cats, contract_drawing_sub_cats, shop_drawing_main_categories, shop_drawing_sub_categories, contract_drawing_subcat_cat_maps, shop_drawing_revision_contract_refs
|
||||
* จัดการ shop_drawing_revision_attachments และ contract_drawing_attachments(ตารางเชื่อมไฟล์แนบ)
|
||||
9. **CirculationModule:**
|
||||
* จัดการ circulations, circulation_templates, circulation_assignees
|
||||
* จัดการ circulation_attachments (ตารางเชื่อมไฟล์แนบ)
|
||||
* รับผิดชอบเวิร์กโฟลว์ **"Circulations"** (circulation_status_transitions, circulation_template_assignees, circulation_assignees, circulation_recipients, circulation_actions, circulation_action_documents)สำหรับการเวียนเอกสาร **ภายในองค์กร**
|
||||
10. **TransmittalModule:**
|
||||
* จัดการ transmittals และ transmittal_items
|
||||
11. **SearchModule:**
|
||||
* ให้บริการค้นหาขั้นสูง (Advanced Search) [cite: 6.2] โดยใช้ **Elasticsearch** เพื่อรองรับการค้นหาแบบ Full-text จากชื่อเรื่อง, รายละเอียด, เลขที่เอกสาร, ประเภท, วันที่, และ Tags
|
||||
12. **DocumentNumberingModule:**
|
||||
* **สถานะ:** เป็น Module ภายใน (Internal Module) ไม่เปิด API สู่ภายนอก
|
||||
* **หน้าที่:** ให้บริการ DocumentNumberingService ที่ Module อื่น (เช่น CorrespondenceModule) จะ Inject ไปใช้งาน
|
||||
* **ตรรกะ:** รับผิดชอบการสร้างเลขที่เอกสาร โดยการเรียกใช้ Stored Procedure *sp_get_next_document_number** เพื่อป้องกัน Race Condition
|
||||
|
||||
### **สถาปัตยกรรมระบบ (System Architecture)**
|
||||
|
||||
โครงสร้างโมดูล (Module Structure)
|
||||
|
||||
```bash
|
||||
📁 src
|
||||
├── 📄 app.module.ts
|
||||
├── 📄 main.ts
|
||||
├── 📁 common # @app/common (โมดูลส่วนกลาง)
|
||||
│ ├── 📁 auth # AuthModule (JWT, Guards)
|
||||
│ ├── 📁 config # Configuration
|
||||
│ ├── 📁 decorators # Custom Decorators (เช่น @RequirePermission)
|
||||
│ ├── 📁 entities # Shared Entities (User, Role, Permission)
|
||||
│ ├── 📁 exceptions # Global Exception Filters
|
||||
│ ├── 📁 file-storage # FileStorageService
|
||||
│ ├── 📁 guards # Custom Guards (RBAC Guard)
|
||||
│ ├── 📁 interceptors # Interceptors (Audit Log, Transform)
|
||||
│ └── 📁 services # Shared Services (NotificationService)
|
||||
├── 📁 modules
|
||||
│ ├── 📁 user # UserModule (จัดการ Users, Roles, Permissions)
|
||||
│ ├── 📁 project # ProjectModule (จัดการ Projects, Organizations, Contracts)
|
||||
│ ├── 📁 correspondence # CorrespondenceModule (จัดการเอกสารโต้ตอบ)
|
||||
│ ├── 📁 rfa # RfaModule (จัดการเอกสารขออนุมัติ)
|
||||
│ ├── 📁 drawing # DrawingModule (จัดการแบบแปลน)
|
||||
│ ├── 📁 circulation # CirculationModule (จัดการใบเวียน)
|
||||
│ ├── 📁 transmittal # TransmittalModule (จัดการเอกสารนำส่ง)
|
||||
│ ├── 📁 search # SearchModule (ค้นหาขั้นสูงด้วย Elasticsearch)
|
||||
│ └── 📁 document-numbering # DocumentNumberingModule (Internal Module)
|
||||
└── 📁 database # Database Migration & Seeding Scripts
|
||||
```
|
||||
|
||||
### **เเทคโนโลยีที่ใช้ (Technology Stack)**
|
||||
|
||||
| ส่วน | Library/Tool | หมายเหตุ |
|
||||
|---|---|---|
|
||||
| **Framework** | `@nestjs/core`, `@nestjs/common` | Core Framework |
|
||||
| **Language** | `TypeScript` | ใช้ TypeScript ทั้งระบบ |
|
||||
| **Database** | `MariaDB 10.11` | ฐานข้อมูลหลัก |
|
||||
| **ORM** | `@nestjs/typeorm`, `typeorm` | 🗃️จัดการการเชื่อมต่อและ Query ฐานข้อมูล |
|
||||
| **Validation** | `class-validator`, `class-transformer` | 📦ตรวจสอบและแปลงข้อมูลใน DTO |
|
||||
| **Auth** | `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt` | 🔐การยืนยันตัวตนด้วย JWT |
|
||||
|**Authorization** | `casl` | 🔐จัดการสิทธิ์แบบ RBAC |
|
||||
| **File Upload** | `multer` | 📁จัดการการอัปโหลดไฟล์ |
|
||||
| **Search** | `@nestjs/elasticsearch` | 🔍สำหรับการค้นหาขั้นสูง |
|
||||
| **Notification** | `nodemailer` | 📬ส่งอีเมลแจ้งเตือน |
|
||||
| **Scheduling** | `@nestjs/schedule` | 📬สำหรับ Cron Jobs (เช่น แจ้งเตือน Deadline) |
|
||||
| **Logging** | `winston` | 📊บันทึก Log ที่มีประสิทธิภาพ |
|
||||
| **Testing** | `@nestjs/testing`, `jest`, `supertest` | 🧪ทดสอบ Unit, Integration และ E2E |
|
||||
| **Documentation** | `@nestjs/swagger` | 🌐สร้าง API Documentation อัตโนมัติ |
|
||||
| **Security** | `helmet`, `rate-limiter-flexible` | 🛡️เพิ่มความปลอดภัยให้ API |
|
||||
|
||||
เราจะแบ่งการทดสอบเป็น 3 ระดับ โดยใช้ **Jest** และ @nestjs/testing:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เป้าหมาย:** ทดสอบ Logic ภายใน Service, Guard, หรือ Pipe โดยจำลอง (Mock) Dependencies ทั้งหมด
|
||||
* **สิ่งที่ต้องทดสอบ:** Business Logic (เช่น การเปลี่ยนสถานะ Workflow, การตรวจสอบ Deadline) [cite: 2.9.1], ตรรกะการตรวจสอบสิทธิ์ (Auth Guard) ทั้ง 3 ระดับ
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เป้าหมาย:** ทดสอบการทำงานร่วมกันของ Controller -> Service -> Repository (Database)
|
||||
* **เทคนิค:** ใช้ **Test Database แยกต่างหาก** (ห้ามใช้ Dev DB) และใช้ supertest เพื่อยิง HTTP Request จริงไปยัง App
|
||||
* **สิ่งที่ต้องทดสอบ:** การเรียก sp\get\next\document\number [cite: 2.9.3] และการทำงานของ Views (เช่น v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เป้าหมาย:** ทดสอบ API Contract ว่า Response Body Shape ตรงตามเอกสาร Swagger เพื่อรับประกันทีม Frontend
|
||||
|
||||
### **🗄️ Backend State Management**
|
||||
|
||||
Backend (NestJS) ควรเป็น **Stateless** (ไม่เก็บสถานะ) "State" ทั้งหมดจะถูกจัดเก็บใน MariaDB
|
||||
|
||||
* **Request-Scoped State (สถานะภายใน Request เดียว):**
|
||||
* **ปัญหา:** จะส่งต่อข้อมูล (เช่น User ที่ล็อกอิน) ระหว่าง Guard และ Service ใน Request เดียวกันได้อย่างไร?
|
||||
* **วิธีแก้:** ใช้ **Request-Scoped Providers** ของ NestJS (เช่น AuthContextService) เพื่อเก็บข้อมูล User ปัจจุบันที่ได้จาก AuthGuard และให้ Service อื่น Inject ไปใช้
|
||||
* **Application-Scoped State (การ Caching):**
|
||||
* **ปัญหา:** ข้อมูล Master (เช่น roles, permissions, organizations) ถูกเรียกใช้บ่อย
|
||||
* **วิธีแก้:** ใช้ **Caching** (เช่น @nestjs/cache-manager) เพื่อ Caching ข้อมูลเหล่านี้ และลดภาระ Database
|
||||
|
||||
### **การไหลของข้อมูล (Data Flow)**
|
||||
|
||||
1. Request: ผ่าน Nginx Proxy Manager -> NestJS Controller
|
||||
2. Authentication: JWT Guard ตรวจสอบ Token และดึงข้อมูล User
|
||||
3. Authorization: RBAC Guard (ใช้ CASL) ตรวจสอบสิทธิ์จาก Decorators (@RequirePermission)
|
||||
4. Validation: Validation Pipe (ใช้ class-validator) ตรวจสอบ DTO
|
||||
5. Business Logic: Service Layer ประมวลผลตรรกะทางธุรกิจ
|
||||
6. Data Access: Repository Layer (ใช้ TypeORM) ติดต่อกับฐานข้อมูล MariaDB
|
||||
7. Response: ส่งกลับไปยัง Frontend พร้อมสถานะและข้อมูลที่เหมาะสม
|
||||
|
||||
# **🖥️ ฟรอนต์เอนด์ (NextJS / React / UI) (Frontend (NextJS / React / UI))**
|
||||
|
||||
### **โปรไฟล์นักพัฒนา (Developer Profile)**
|
||||
|
||||
วิศวกร TypeScript + React/NextJS ระดับ Senior
|
||||
เชี่ยวชาญ TailwindCSS, Shadcn/UI, และ Radix สำหรับการพัฒนา UI
|
||||
|
||||
### **แนวทางการพัฒนาโค้ด (Code Implementation Guidelines)**
|
||||
|
||||
* ใช้ **early returns** เพื่อความชัดเจน
|
||||
* ใช้คลาสของ **TailwindCSS** ในการกำหนดสไตล์เสมอ
|
||||
* ควรใช้ class: syntax แบบมีเงื่อนไข (หรือ utility clsx) มากกว่าการใช้ ternary operators ใน class strings
|
||||
* ใช้ **const arrow functions** สำหรับ components และ handlers
|
||||
* Event handlers ให้ขึ้นต้นด้วย handle... (เช่น handleClick, handleSubmit)
|
||||
* รวมแอตทริบิวต์สำหรับการเข้าถึง (accessibility) ด้วย:
|
||||
tabIndex="0", aria-label, onKeyDown, ฯลฯ
|
||||
* ตรวจสอบให้แน่ใจว่าโค้ดทั้งหมด **สมบูรณ์**, **ผ่านการทดสอบ**, และ **ไม่ซ้ำซ้อน (DRY)**
|
||||
* ต้อง import โมดูลที่จำเป็นต้องใช้อย่างชัดเจนเสมอ
|
||||
|
||||
### **UI/UX ด้วย React**
|
||||
|
||||
* ใช้ **semantic HTML**
|
||||
* ใช้คลาสของ **Tailwind** ที่รองรับ responsive (sm:, md:, lg:)
|
||||
* รักษาลำดับชั้นของการมองเห็น (visual hierarchy) ด้วยการใช้ typography และ spacing
|
||||
* ใช้ **Shadcn** components (Button, Input, Card, ฯลฯ) เพื่อ UI ที่สอดคล้องกัน
|
||||
* ทำให้ components มีขนาดเล็กและมุ่งเน้นการทำงานเฉพาะอย่าง
|
||||
* ใช้ utility classes สำหรับการจัดสไตล์อย่างรวดเร็ว (spacing, colors, text, ฯลฯ)
|
||||
* ตรวจสอบให้แน่ใจว่าสอดคล้องกับ **ARIA** และใช้ semantic markup
|
||||
|
||||
### **การตรวจสอบฟอร์มและข้อผิดพลาด (Form Validation & Errors)**
|
||||
|
||||
* ใช้ไลบรารีฝั่ง client เช่น zod และ react-hook-form
|
||||
* แสดงข้อผิดพลาดด้วย **alert components** หรือข้อความ inline
|
||||
* ต้องมี labels, placeholders, และข้อความ feedback
|
||||
|
||||
### **🧪 Frontend Testing**
|
||||
|
||||
เราจะใช้ **React Testing Library (RTL)** สำหรับการทดสอบ Component และ **Playwright** สำหรับ E2E:
|
||||
|
||||
* **Unit Tests (การทดสอบหน่วยย่อย):**
|
||||
* **เครื่องมือ:** Vitest + RTL
|
||||
* **เป้าหมาย:** ทดสอบ Component ขนาดเล็ก (เช่น Buttons, Inputs) หรือ Utility functions
|
||||
* **Integration Tests (การทดสอบการบูรณาการ):**
|
||||
* **เครื่องมือ:** RTL + **Mock Service Worker (MSW)**
|
||||
* **เป้าหมาย:** ทดสอบว่า Component หรือ Page ทำงานกับ API (ที่จำลองขึ้น) ได้ถูกต้อง
|
||||
* **เทคนิค:** ใช้ MSW เพื่อจำลอง NestJS API และทดสอบว่า Component แสดงผลข้อมูลจำลองได้ถูกต้องหรือไม่ (เช่น ทดสอบหน้า Dashboard [cite: 5.3] ที่ดึงข้อมูลจาก v_user_tasks)
|
||||
* **E2E (End-to-End) Tests:**
|
||||
* **เครื่องมือ:** **Playwright**
|
||||
* **เป้าหมาย:** ทดสอบ User Flow ทั้งระบบโดยอัตโนมัติ (เช่น ล็อกอิน -> สร้าง RFA -> ตรวจสอบ Workflow Visualization [cite: 5.6])
|
||||
|
||||
### **🗄️ Frontend State Management**
|
||||
|
||||
สำหรับ Next.js App Router เราจะแบ่ง State เป็น 4 ระดับ:
|
||||
|
||||
1. **Local UI State (สถานะ UI ชั่วคราว):**
|
||||
* **เครื่องมือ:** useState, useReducer
|
||||
* **ใช้เมื่อ:** จัดการสถานะเล็กๆ ที่จบใน Component เดียว (เช่น Modal เปิด/ปิด, ค่าใน Input)
|
||||
2. **Server State (สถานะข้อมูลจากเซิร์ฟเวอร์):**
|
||||
* **เครื่องมือ:** **React Query (TanStack Query)** หรือ SWR
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ดึงมาจาก NestJS API (เช่น รายการ correspondences, rfas, drawings)
|
||||
* **ทำไม:** React Query เป็น "Cache" ที่จัดการ Caching, Re-fetching, และ Invalidation ให้โดยอัตโนมัติ
|
||||
3. **Global Client State (สถานะส่วนกลางฝั่ง Client):**
|
||||
* **เครื่องมือ:** **Zustand** (แนะนำ) หรือ Context API
|
||||
* **ใช้เมื่อ:** จัดการข้อมูลที่ต้องใช้ร่วมกันทั่วทั้งแอป และ *ไม่ใช่* ข้อมูลจากเซิร์ฟเวอร์ (เช่น ข้อมูล User ที่ล็อกอิน, สิทธิ์ Permissions)
|
||||
4. **Form State (สถานะของฟอร์ม):**
|
||||
* **เครื่องมือ:** **React Hook Form** + **Zod**
|
||||
* **ใช้เมื่อ:** จัดการฟอร์มที่ซับซ้อน (เช่น ฟอร์มสร้าง RFA, ฟอร์ม Circulation [cite: 3.7])
|
||||
|
||||
# **🔗 แนวทางการบูรณาการ Full Stack (Full Stack Integration Guidelines)**
|
||||
|
||||
| Aspect (แง่มุม) | Backend (NestJS) | Frontend (NextJS) | UI Layer (Tailwind/Shadcn) |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| API | REST / GraphQL Controllers | API hooks ผ่าน fetch/axios/SWR | Components ที่รับข้อมูล |
|
||||
| Validation (การตรวจสอบ) | class-validator DTOs | zod / react-hook-form | สถานะของฟอร์ม/input ใน Shadcn |
|
||||
| Auth (การยืนยันตัวตน) | Guards, JWT | NextAuth / cookies | สถานะ UI ของ Auth (loading, signed in) |
|
||||
| Errors (ข้อผิดพลาด) | Global filters | Toasts / modals | Alerts / ข้อความ feedback |
|
||||
| Testing (การทดสอบ) | Jest (unit/e2e) | Vitest / Playwright | Visual regression |
|
||||
| Styles (สไตล์) | Scoped modules (ถ้าจำเป็น) | Tailwind / Shadcn | Tailwind utilities |
|
||||
| Accessibility (การเข้าถึง) | Guards + filters | ARIA attributes | Semantic HTML |
|
||||
|
||||
## **🗂️ ข้อตกลงเฉพาะสำหรับ DMS (LCBP3-DMS)**
|
||||
|
||||
ส่วนนี้ขยายแนวทาง FullStackJS ทั่วไปสำหรับโปรเจกต์ **LCBP3-DMS** โดยมุ่งเน้นไปที่เวิร์กโฟลว์การอนุมัติเอกสาร (Correspondence, RFA, Drawing, Contract, Transmittal, Circulation)
|
||||
|
||||
### **🧩 RBAC และการควบคุมสิทธิ์ (RBAC & Permission Control)**
|
||||
|
||||
ใช้ Decorators เพื่อบังคับใช้สิทธิ์การเข้าถึง โดยอ้างอิงสิทธิ์จากตาราง permissions
|
||||
|
||||
@RequirePermission('rfas.respond') // ต้องตรงกับ 'permission\code'
|
||||
@Put(':id')
|
||||
updateRFA(@Param('id') id: string) {
|
||||
return this.rfaService.update(id);
|
||||
}
|
||||
|
||||
### **Roles (บทบาท)**
|
||||
|
||||
* **Superadmin**: ไม่มีข้อจำกัดใดๆ [cite: 4.3]
|
||||
* **Admin**: มีสิทธิ์เต็มที่ในองค์กร [cite: 4.3]
|
||||
* **Document Control**: เพิ่ม/แก้ไข/ลบ เอกสารในองค์กร [cite: 4.3]
|
||||
* **Editor**: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนด [cite: 4.3]
|
||||
* **Viewer**: สามารถดู เอกสาร [cite: 4.3]
|
||||
|
||||
### **ตัวอย่าง Permissions (จากตาราง permissions)**
|
||||
|
||||
* rfas.view, rfas.create, rfas.respond, rfas.delete
|
||||
* drawings.view, drawings.upload, drawings.delete
|
||||
* corr.view, corr.manage
|
||||
* transmittals.manage
|
||||
* cirs.manage
|
||||
* project\parties.manage
|
||||
|
||||
การจับคู่ระหว่าง roles และ permissions **เริ่มต้น** จะถูก seed ผ่านสคริปต์ (ดังที่เห็นในไฟล์ SQL)**อย่างไรก็ตาม AuthModule/UserModule ต้องมี API สำหรับ Admin เพื่อสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลัง** [cite: 4.3]
|
||||
|
||||
## **🧾 มาตรฐาน AuditLog (AuditLog Standard)**
|
||||
|
||||
บันทึกการดำเนินการ CRUD และการจับคู่ทั้งหมดลงในตาราง audit_logs
|
||||
|
||||
| Field (ฟิลด์) | Type (จาก SQL) | Description (คำอธิบาย) |
|
||||
| :---- | :---- | :---- |
|
||||
| audit_id | BIGINT | Primary Key |
|
||||
| user_id | INT | ผู้ใช้ที่ดำเนินการ (FK -> users) |
|
||||
| action | VARCHAR(100) | rfa.create, correspondence.update, login.success |
|
||||
| entity_type | VARCHAR(50) | ชื่อตาราง/โมดูล เช่น 'rfa', 'correspondence' |
|
||||
| entity_id | VARCHAR(50) | Primary ID ของระเบียนที่ได้รับผลกระทบ |
|
||||
| details_json | JSON | ข้อมูลบริบท (เช่น ฟิลด์ที่มีการเปลี่ยนแปลง) |
|
||||
| ip_address | VARCHAR(45) | IP address ของผู้ดำเนินการ |
|
||||
| user_agent | VARCHAR(255) | User Agent ของผู้ดำเนินการ |
|
||||
| created_at | TIMESTAMP | Timestamp (UTC) |
|
||||
|
||||
## **📂 การจัดการไฟล์ (File Handling) (ปรับปรุงใหม่)**
|
||||
|
||||
### **มาตรฐานการอัปโหลดไฟล์ (File Upload Standard)**
|
||||
|
||||
* **ตรรกะใหม่:** การอัปโหลดไฟล์ทั้งหมดจะถูกจัดการโดย FileStorageService และบันทึกข้อมูลไฟล์ลงในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงไปยัง Entity ที่ถูกต้องผ่าน **ตารางเชื่อม (Junction Tables)** เท่านั้น:
|
||||
* correspondence_attachments (เชื่อม Correspondence กับ Attachments)
|
||||
* circulation_attachments (เชื่อม Circulation กับ Attachments)
|
||||
* shop_drawing_revision_attachments (เชื่อม Shop Drawing Revision กับ Attachments)
|
||||
* contract_drawing_attachments (เชื่อม Contract Drawing กับ Attachments)
|
||||
* เส้นทางจัดเก็บไฟล์ (Upload path): อ้างอิงจาก Requirement 2.1 คือ /share/dms-data [cite: 2.1] โดย FileStorageService จะสร้างโฟลเดอร์ย่อยแบบรวมศูนย์ (เช่น /share/dms-data/uploads/{YYYY}/{MM}/[stored\filename])
|
||||
* ประเภทไฟล์ที่อนุญาต: pdf, dwg, docx, xlsx, zip
|
||||
* ขนาดสูงสุด: **50 MB**
|
||||
* จัดเก็บนอก webroot
|
||||
* ให้บริการไฟล์ผ่าน endpoint ที่ปลอดภัย /files/:attachment_id/download
|
||||
|
||||
### **การควบคุมการเข้าถึง (Access Control)**
|
||||
|
||||
การเข้าถึงไฟล์ไม่ใช่การเข้าถึงโดยตรง endpoint /files/:attachment_id/download จะต้อง:
|
||||
|
||||
1. ค้นหาระเบียน attachment
|
||||
2. ตรวจสอบว่า attachment_id นี้ เชื่อมโยงกับ Entity ใด (เช่น correspondence, circulation, shop_drawing_revision, contract_drawing) ผ่านตารางเชื่อม
|
||||
3. ตรวจสอบว่าผู้ใช้มีสิทธิ์ (permission) ในการดู Entity ต้นทางนั้นๆ หรือไม่
|
||||
|
||||
## **🔟 การจัดการเลขที่เอกสาร (Document Numbering) [cite: 3.10]**
|
||||
|
||||
* **เป้าหมาย:** สร้างเลขที่เอกสาร (เช่น correspondence\number) โดยอัตโนมัติ ตามรูปแบบที่กำหนด
|
||||
* **ตรรกะการนับ:** การนับ Running number (SEQ) จะนับแยกตาม Key: **Project + Originator Organization + Document Type + Year**
|
||||
* **ตาราง SQL:**
|
||||
* document_number_formats: Admin ใช้กำหนด "รูปแบบ" (Template) ของเลขที่ (เช่น {ORG\CODE}-{TYPE\CODE}-{YEAR\SHORT}-{SEQ:4}) โดยกำหนดตาม **Project** และ **Document Type** [cite: 4.5]
|
||||
* document_number_counters: ระบบใช้เก็บ "ตัวนับ" ล่าสุดของ Key (Project+Org+Type+Year)
|
||||
* **การทำงาน (Backend):**
|
||||
* DocumentNumberingModule จะให้บริการ DocumentNumberingService
|
||||
* เมื่อ CorrespondenceModule ต้องการสร้างเอกสารใหม่, มันจะเรียก documentNumberingService.generateNextNumber(...)
|
||||
* Service นี้จะเรียกใช้ Stored Procedure **sp_get_next_document_number** [cite: 2.9.3] ซึ่ง Procedure นี้จะจัดการ Database Transaction และ Row Lock (FOR UPDATE) ภายใน DB เพื่อรับประกันการป้องกัน Race Condition
|
||||
|
||||
## **📊 การรายงานและการส่งออก (Reporting & Exports)**
|
||||
|
||||
### **วิวสำหรับการรายงาน (Reporting Views) (จาก SQL)**
|
||||
|
||||
การรายงานควรสร้างขึ้นจาก Views ที่กำหนดไว้ล่วงหน้าในฐานข้อมูลเป็นหลัก:
|
||||
|
||||
* v_current_correspondences: สำหรับ revision ปัจจุบันทั้งหมดของเอกสารที่ไม่ใช่ RFA
|
||||
* v_current_rfas: สำหรับ revision ปัจจุบันทั้งหมดของ RFA และข้อมูล master
|
||||
* v_contract_parties_all: สำหรับการตรวจสอบความสัมพันธ์ของ project/contract/organization
|
||||
* v_user_tasks: สำหรับ Dashboard "งานของฉัน"
|
||||
* v_audit_log_details: สำหรับ Activity Feed
|
||||
|
||||
Views เหล่านี้ทำหน้าที่เป็นแหล่งข้อมูลหลักสำหรับการรายงานฝั่งเซิร์ฟเวอร์และการส่งออกข้อมูล
|
||||
|
||||
### **กฎการส่งออก (Export Rules)**
|
||||
|
||||
* Export formats: CSV, Excel, PDF.
|
||||
* จัดเตรียมมุมมองสำหรับพิมพ์ (Print view).
|
||||
* รวมลิงก์ไปยังต้นทาง (เช่น /rfas/:id).
|
||||
|
||||
## **🧮 ฟรอนต์เอนด์: รูปแบบ DataTable และฟอร์ม (Frontend: DataTable & Form Patterns)**
|
||||
|
||||
### **DataTable (Server‑Side)**
|
||||
|
||||
* Endpoint: /api/{module}?page=1\&pageSize=20\&sort=...\&filter=...
|
||||
* ต้องรองรับ: การแบ่งหน้า (pagination), การเรียงลำดับ (sorting), การค้นหา (search), การกรอง (filters)
|
||||
* แสดง revision ล่าสุดแบบ inline เสมอ (สำหรับ RFA/Drawing)
|
||||
|
||||
### **มาตรฐานฟอร์ม (Form Standards)**
|
||||
|
||||
* ต้องมีการใช้งาน Dropdowns แบบขึ้นต่อกัน (Dependent dropdowns) (ตามที่สคีมารองรับ):
|
||||
* Project → Contract Drawing Volumes
|
||||
* Contract Drawing Category → Sub-Category
|
||||
* RFA (ประเภท Shop Drawing) → Shop Drawing Revisions ที่เชื่อมโยงได้
|
||||
* **(ใหม่)** การอัปโหลดไฟล์: ต้องรองรับ **Multi-file upload (Drag-and-Drop)** [cite: 5.7]
|
||||
* **(ใหม่)** UI ต้องอนุญาตให้ผู้ใช้กำหนดว่าไฟล์ใดเป็น **"เอกสารหลัก"** หรือ "เอกสารแนบประกอบ" [cite: 5.7]
|
||||
* ส่ง (Submit) ผ่าน API พร้อม feedback แบบ toast
|
||||
|
||||
### **ข้อกำหนด Component เฉพาะ (Specific UI Requirements)**
|
||||
|
||||
* **Dashboard \- My Tasks:** ต้องพัฒนา Component ตาราง "งานของฉัน" (My Tasks)ซึ่งดึงข้อมูลงานที่ผู้ใช้ล็อกอินอยู่ต้องรับผิดชอบ (Main/Action) จาก v\user\tasks [cite: 5.3]
|
||||
* **Workflow Visualization:** ต้องพัฒนา Component สำหรับแสดงผล Workflow (โดยเฉพาะ RFA)ที่แสดงขั้นตอนทั้งหมดเป็นลำดับ โดยขั้นตอนปัจจุบัน (active) เท่านั้นที่ดำเนินการได้ และขั้นตอนอื่นเป็น disabled [cite: 5.6] ต้องมีตรรกะสำหรับ Admin ในการ override หรือย้อนกลับขั้นตอนได้ [cite: 5.6]
|
||||
* ** Admin Panel:** ต้องมีหน้า UI สำหรับ Superadmin/Admin เพื่อจัดการข้อมูลหลัก (Master Data [cite: 4.5]), การเริ่มต้นใช้งาน (Onboarding [cite: 4.6]), และ **รูปแบบเลขที่เอกสาร (Numbering Formats [cite: 3.10])**
|
||||
|
||||
## **🧭 แดชบอร์ดและฟีดกิจกรรม (Dashboard & Activity Feed)**
|
||||
|
||||
### **การ์ดบนแดชบอร์ด (Dashboard Cards)**
|
||||
|
||||
* แสดง Correspondences, RFAs, Circulations, Shop Drawing Revision ล่าสุด
|
||||
* รวมสรุป KPI (เช่น "RFAs ที่รอการอนุมัติ", "Shop Drawing ที่รอการอนุมัติ") [cite: 5.3]
|
||||
* รวมลิงก์ด่วนไปยังโมดูลต่างๆ
|
||||
|
||||
### **ฟีดกิจกรรม (Activity Feed)**
|
||||
|
||||
* แสดงรายการ v\audit\log\details ล่าสุด (10 รายการ) ที่เกี่ยวข้องกับผู้ใช้
|
||||
|
||||
// ตัวอย่าง API response
|
||||
[
|
||||
{ user: 'editor01', action: 'Updated RFA (LCBP3-RFA-001)', time: '2025-11-04T09:30Z' }
|
||||
]
|
||||
|
||||
## **🛡️ ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
ส่วนนี้สรุปข้อกำหนด Non-Functional จาก requirements.md เพื่อให้ทีมพัฒนาทราบ
|
||||
|
||||
* **Audit Log [cite: 6.1]:** ทุกการกระทำที่สำคัญ (C/U/D) ต้องถูกบันทึกใน audit_logs
|
||||
* **Performance [cite: 6.4]:** ต้องใช้ Caching สำหรับข้อมูลที่เรียกบ่อย และใช้ Pagination
|
||||
* **Security [cite: 6.5]:** ต้องมี Rate Limiting และจัดการ Secret ผ่าน docker-compose.yml (ไม่ใช่ .env)
|
||||
* **(ใหม่) Backup & Recovery [cite: 6.6]:** ต้องมีแผนสำรองข้อมูลทั้ง Database (MariaDB) และ File Storage (/share/dms-data) อย่างน้อยวันละ 1 ครั้ง
|
||||
* **(ใหม่) Notification Strategy [cite: 6.7]:** ระบบแจ้งเตือน (Email/Line) ต้องถูก Trigger เมื่อมีเอกสารใหม่ส่งถึง, มีการมอบหมายงานใหม่ (Circulation), หรือ (ทางเลือก) เมื่องานเสร็จ/ใกล้ถึงกำหนด
|
||||
|
||||
## **✅ มาตรฐานที่นำไปใช้แล้ว (จาก SQL v1.1.0) (Implemented Standards (from SQL v1.1.0))**
|
||||
|
||||
ส่วนนี้ยืนยันว่าแนวทางปฏิบัติที่ดีที่สุดต่อไปนี้เป็นส่วนหนึ่งของการออกแบบฐานข้อมูลอยู่แล้ว และควรถูกนำไปใช้ประโยชน์ ไม่ใช่สร้างขึ้นใหม่
|
||||
|
||||
* ✅ **Soft Delete:** นำไปใช้แล้วผ่านคอลัมน์ deleted_at ในตารางสำคัญ (เช่น correspondences, rfas, project_parties) ตรรกะการดึงข้อมูลต้องกรอง deleted_at IS NULL
|
||||
* ✅ **Database Indexes:** สคีมาได้มีการทำ index ไว้อย่างหนักหน่วงบน foreign keys และคอลัมน์ที่ใช้ค้นหาบ่อย (เช่น idx_rr_rfa, idx_cor_project, idx_cr_is_current) เพื่อประสิทธิภาพ
|
||||
* ✅ **โครงสร้าง RBAC:** มีระบบ users, roles, permissions, user_roles, และ user_project_roles ที่ครอบคลุมอยู่แล้ว
|
||||
* ✅ **Data Seeding:** ข้อมูล Master (roles, permissions, organization_roles, initial users, project parties) ถูกรวมอยู่ในสคริปต์สคีมาแล้ว
|
||||
|
||||
## **🧩 การปรับปรุงที่แนะนำ (สำหรับอนาคต) (Recommended Enhancements (Future))**
|
||||
|
||||
* ✅ สร้าง Background job (โดยใช้ **n8n** เพื่อเชื่อมต่อกับ **Line** [cite: 2.7] และ/หรือใช้สำหรับการแจ้งเตือน RFA ที่ใกล้ถึงกำหนด due_date [cite: 6.7])
|
||||
* ✅ เพิ่ม job ล้างข้อมูลเป็นระยะสำหรับ attachments ที่ไม่ถูกเชื่อมโยงกับ Entity ใดๆ เลย (ไฟล์กำพร้า)
|
||||
|
||||
@@ -1,79 +1,79 @@
|
||||
# **🧪 แผนการทดสอบระบบ (Test Plan) \- DMS v1.3.0 Backend**
|
||||
|
||||
เอกสารนี้สรุปแผนการทดสอบ, ขั้นตอน, และเครื่องมือที่ใช้ในการตรวจสอบความถูกต้องของ NestJS Backend API (DMS v1.3.0) ก่อนการ Deploy ใช้งานจริงร่วมกับ Frontend
|
||||
|
||||
## **1\. วัตถุประสงค์ (Objectives)**
|
||||
|
||||
* เพื่อให้มั่นใจว่า API ทั้งหมดทำงานตรงตาม requirements.md
|
||||
* เพื่อตรวจสอบว่าระบบรักษาความปลอดภัย (RBAC และ Security) ทำงานได้ถูกต้อง 100%
|
||||
* เพื่อค้นหาและแก้ไขข้อบกพร่อง (Bugs) ที่เกี่ยวข้องกับการเชื่อมต่อฐานข้อมูลและ Business Logic
|
||||
* เพื่อยืนยันว่าระบบทนทานต่อการใช้งานพร้อมกัน (Concurrency) และมีประสิทธิภาพ (Performance)
|
||||
* เพื่อส่งมอบ API ที่เสถียรและมีเอกสาร (Swagger) ครบถ้วนให้แก่ทีม Frontend
|
||||
|
||||
## **2\. ขอบเขตการทดสอบ (Scope)**
|
||||
|
||||
### **สิ่งที่อยู่ในขอบเขต (In-Scope)**
|
||||
|
||||
* **API Functionality:** การทดสอบ Endpoints ทั้งหมด (CRUD, Search, Upload)
|
||||
* **Business Logic:** ตรรกะการสร้างเอกสาร (RFA, Correspondence), การสร้างเลขที่, และ Workflow
|
||||
* **Security:** การยืนยันตัวตน (JWT), การจัดการสิทธิ์ (RBAC Guard), การป้องกัน (Helmet, Rate Limiter)
|
||||
* **Data Integrity:** การตรวจสอบความถูกต้องของข้อมูลที่บันทึกลง MariaDB
|
||||
* **Performance:** การทดสอบ Concurrency (การสร้างเลขที่) และการตอบสนองของ API
|
||||
* **Error Handling:** การตรวจสอบว่า Global Exception Filter ทำงานได้ถูกต้อง
|
||||
|
||||
### **สิ่งที่อยู่นอกขอบเขต (Out-of-Scope)**
|
||||
|
||||
* การทดสอบ Next.js Frontend (UI/UX)
|
||||
* การทดสอบตรรกะภายในของ N8N (เราทดสอบแค่ว่า Backend *ยิง* Webhook ไปหรือไม่)
|
||||
* การทดสอบ Penetration Test ขั้นสูง (เน้น Functional & Security พื้นฐาน)
|
||||
|
||||
## **3\. สภาพแวดล้อมและเครื่องมือ (Environment & Tools)**
|
||||
|
||||
| ประเภท | เครื่องมือ/สภาพแวดล้อม | วัตถุประสงค์ |
|
||||
| :---- | :---- | :---- |
|
||||
| **สภาพแวดล้อม** | **Staging (QNAP)** | สภาพแวดล้อมจำลอง (บน Docker) ที่เหมือน Production ที่สุด ประกอบด้วย backend, mariadb, elasticsearch, n8n (Mock Receiver) |
|
||||
| **ฐานข้อมูล** | **DBeaver** | ใช้สำหรับเชื่อมต่อ MariaDB (Staging) เพื่อตรวจสอบผลลัพธ์ (Data Verification) |
|
||||
| **API (Manual)** | **Postman / Insomnia** | ใช้สำหรับการทดสอบ API ด้วยตนเอง, สำรวจ Endpoints, และสร้าง Test Case |
|
||||
| **API (Automation)** | **Postman (Newman) / Supertest** | (E2E) ใช้รัน Test Case อัตโนมัติเพื่อตรวจสอบ API Contract |
|
||||
| **Unit/Integration** | **Jest / @nestjs/testing** | (Developer) ใช้สำหรับทดสอบ Logic ภายใน Service และ Guard (ตามตัวอย่าง spec.ts ที่สร้างไว้) |
|
||||
| **Concurrency** | **k6 (แนะนำ) / Node.js Script** | ใช้สำหรับทดสอบ Stress Test และ Concurrency (โดยเฉพาะ TC-CON-01) |
|
||||
| **Webhook** | **N8N (Webhook Node)** | ใช้ N8N จริง (Staging) ตั้งค่า Webhook Node เพื่อรับ Event จาก NotificationService |
|
||||
|
||||
## **4\. รายละเอียดสถานการณ์ทดสอบ (Detailed Test Scenarios)**
|
||||
|
||||
นี่คือ Test Case ที่สำคัญที่สุด โดยแบ่งตามความเสี่ยงและ Function
|
||||
|
||||
### **T1: การรักษาความปลอดภัย (Security & RBAC) \- (ความเสี่ยงสูงมาก)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-SEC-01** | **(RBAC) ห้าม Viewer สร้างเอกสาร** | 1\. (Postman) เรียก POST /api/v1/auth/login ด้วย User "Viewer" 2\. คัดลอก access\_token 3\. เรียก POST /api/v1/correspondence (ใน Auth Header) พร้อม Body ที่ถูกต้อง | 403 Forbidden (RBACGuard ทำงาน) | Postman |
|
||||
| **TC-SEC-02** | **(RBAC) Editor ข้าม Project** | 1\. (Postman) Login User "Editor" ที่มีสิทธิ์เฉพาะ Project A 2\. (DBeaver) หา ID เอกสาร (เช่น corr\_id: 99\) ที่อยู่ใน Project B 3\. (Postman) เรียก GET /api/v1/correspondence/99 ด้วย Token ของ Editor | 403 Forbidden หรือ 404 Not Found | Postman, DBeaver |
|
||||
| **TC-SEC-03** | **(RBAC) Super Admin** | 1\. (Postman) Login User "Super Admin" 2\. เรียก Endpoint ที่จำกัดสิทธิ์สูง (เช่น POST /api/v1/admin/users) | 201 Created (Super Admin ต้องผ่านทุกการตรวจสอบ) | Postman |
|
||||
| **TC-SEC-04** | **(Rate Limit) Brute-force** | 1\. (Postman Runner หรือ k6) ตั้งค่าให้เรียก POST /api/v1/auth/login (ด้วยรหัสผ่านผิด) 110 ครั้ง (Limit คือ 100\) 2\. สังเกตผลลัพธ์ | Request ที่ 1-100: 401 Unauthorized Request ที่ 101+: 429 Too Many Requests | k6, Postman |
|
||||
| **TC-SEC-05** | **(Security) Helmet** | 1\. (Postman) เรียก Endpoint ใดก็ได้ (เช่น GET /api/v1/health) 2\. ตรวจสอบ Response Headers | ต้องมี Headers เช่น X-Content-Type-Options: nosniff, Strict-Transport-Security, X-Frame-Options: SAMEORIGIN | Postman |
|
||||
|
||||
### **T2: ตรรกะหลัก (Core Logic & Concurrency) \- (ความเสี่ยงสูง)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-CON-01** | **(Concurrency) สร้างเลขที่เอกสาร** | 1\. (k6/Script) สร้าง Script ที่เรียก POST /api/v1/correspondence (สร้างเอกสารใหม่) 50 ครั้ง *พร้อมกัน* (Simultaneously) 2\. (Postman) Login Admin 3\. (DBeaver) ตรวจสอบตาราง correspondences และ document\_number\_counters | 1\. Script ทั้ง 50 ครั้งสำเร็จ (201 Created) 2\. (DBeaver) document\_number\_counters มี last\_number: 50 3\. correspondences มีเอกสาร 50 ฉบับ โดย *ไม่มี* correspondence\_number ซ้ำกันเลย | k6, DBeaver |
|
||||
| **TC-FUNC-01** | **(Data) สร้าง RFA (Complex)** | 1\. (Postman) Login User (เช่น "Editor") 2\. เรียก POST /api/v1/rfa พร้อม DTO ที่ซับซ้อน (มี rfa\_type\_id, title, attachments, shop\_drawings) | 1\. 201 Created 2\. (DBeaver) ตรวจสอบว่ามีข้อมูลถูกสร้างขึ้นใน 3 ตารางหลัก: \- correspondences (ตารางแม่) \- rfas (ตารางแม่ RFA) \- rfa\_revisions (ตารางลูก Revision 0\) | Postman, DBeaver |
|
||||
|
||||
### **T3: การทำงานของโมดูล (Module Functionality)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-FUNC-02** | **(File) อัปโหลดไฟล์** | 1\. (Postman) Login User 2\. เรียก POST /api/v1/files/upload (ประเภท form-data, key file) 3\. (DBeaver) ตรวจสอบตาราง attachments | 1\. 201 Created คืนค่าข้อมูล Attachment (เช่น ID, stored\_filename) 2\. (DBeaver) มีแถวใหม่ในตาราง attachments 3\. (ถ้าทำได้) ตรวจสอบ QNAP /share/dms-data/... ว่ามีไฟล์จริง | Postman, DBeaver |
|
||||
| **TC-FUNC-03** | **(File) ดาวน์โหลด (ผ่าน Auth)** | 1\. (Postman) ทำ TC-FUNC-02 เพื่ออัปโหลดไฟล์ (สมมติได้ attachment\_id: 123\) 2\. เรียก GET /api/v1/files/download/123 (ต้องใส่ Auth Header) | 200 OK และได้ข้อมูลไฟล์กลับมา | Postman |
|
||||
| **TC-FUNC-04** | **(Search) Elasticsearch** | 1\. (Postman) สร้างเอกสารใหม่ POST /api/v1/correspondence (จดจำ Title ไว้) 2\. (รอ 10 วินาที ให้ Elastic Index) 3\. เรียก GET /api/v1/search?query=\[Title ที่จดไว้\] | 200 OK และผลลัพธ์การค้นหาต้องมีเอกสารที่เพิ่งสร้าง | Postman |
|
||||
| **TC-FUNC-05** | **(Notification) N8N Webhook** | 1\. (N8N) สร้าง Workflow ใหม่, ใช้ "Webhook" Node (เปิด Test Mode) 2\. (Postman) Login User 3\. เรียก POST /api/v1/circulation (สร้างใบเวียนใหม่) | 1\. (Postman) 201 Created 2\. (N8N) Webhook Node ได้รับข้อมูล Payload ({ event: 'NEW\_CIRCULATION\_TASK', ... }) | Postman, N8N |
|
||||
| **TC-FUNC-06** | **(Audit) Audit Log** | 1\. (Postman) Login Admin 2\. เรียก DELETE /api/v1/admin/roles/10 (ลบ Role สมมติ) 3\. (DBeaver) ตรวจสอบ audit\_logs | 1\. (DBeaver) มีแถวใหม่ใน audit\_logs 2\. ข้อมูลถูกต้อง: action: 'role.delete', entity\_type: 'role', entity\_id: '10', user\_id: \[Admin ID\] | Postman, DBeaver |
|
||||
|
||||
### **T4: การ Deploy (NFR)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-NFR-01** | **(Health) Health Check** | 1\. (Browser/Postman) เรียก GET /api/v1/health (จาก Staging URL) | 200 OK และ JSON Response แสดง status: "ok" และสถานะ DB | Postman, Browser |
|
||||
| **TC-NFR-02** | **(Error) Global Filter** | 1\. (Postman) เรียก Endpoint ที่ไม่มีอยู่จริง (เช่น GET /api/v1/invalid\_path) | 404 Not Found Response Body ต้องมีโครงสร้าง JSON ที่กำหนดไว้ (เช่น { "statusCode": 404, "message": "Cannot GET /api/v1/invalid\_path", ... }) | Postman |
|
||||
|
||||
# **🧪 แผนการทดสอบระบบ (Test Plan) \- DMS v1.3.0 Backend**
|
||||
|
||||
เอกสารนี้สรุปแผนการทดสอบ, ขั้นตอน, และเครื่องมือที่ใช้ในการตรวจสอบความถูกต้องของ NestJS Backend API (DMS v1.3.0) ก่อนการ Deploy ใช้งานจริงร่วมกับ Frontend
|
||||
|
||||
## **1\. วัตถุประสงค์ (Objectives)**
|
||||
|
||||
* เพื่อให้มั่นใจว่า API ทั้งหมดทำงานตรงตาม requirements.md
|
||||
* เพื่อตรวจสอบว่าระบบรักษาความปลอดภัย (RBAC และ Security) ทำงานได้ถูกต้อง 100%
|
||||
* เพื่อค้นหาและแก้ไขข้อบกพร่อง (Bugs) ที่เกี่ยวข้องกับการเชื่อมต่อฐานข้อมูลและ Business Logic
|
||||
* เพื่อยืนยันว่าระบบทนทานต่อการใช้งานพร้อมกัน (Concurrency) และมีประสิทธิภาพ (Performance)
|
||||
* เพื่อส่งมอบ API ที่เสถียรและมีเอกสาร (Swagger) ครบถ้วนให้แก่ทีม Frontend
|
||||
|
||||
## **2\. ขอบเขตการทดสอบ (Scope)**
|
||||
|
||||
### **สิ่งที่อยู่ในขอบเขต (In-Scope)**
|
||||
|
||||
* **API Functionality:** การทดสอบ Endpoints ทั้งหมด (CRUD, Search, Upload)
|
||||
* **Business Logic:** ตรรกะการสร้างเอกสาร (RFA, Correspondence), การสร้างเลขที่, และ Workflow
|
||||
* **Security:** การยืนยันตัวตน (JWT), การจัดการสิทธิ์ (RBAC Guard), การป้องกัน (Helmet, Rate Limiter)
|
||||
* **Data Integrity:** การตรวจสอบความถูกต้องของข้อมูลที่บันทึกลง MariaDB
|
||||
* **Performance:** การทดสอบ Concurrency (การสร้างเลขที่) และการตอบสนองของ API
|
||||
* **Error Handling:** การตรวจสอบว่า Global Exception Filter ทำงานได้ถูกต้อง
|
||||
|
||||
### **สิ่งที่อยู่นอกขอบเขต (Out-of-Scope)**
|
||||
|
||||
* การทดสอบ Next.js Frontend (UI/UX)
|
||||
* การทดสอบตรรกะภายในของ N8N (เราทดสอบแค่ว่า Backend *ยิง* Webhook ไปหรือไม่)
|
||||
* การทดสอบ Penetration Test ขั้นสูง (เน้น Functional & Security พื้นฐาน)
|
||||
|
||||
## **3\. สภาพแวดล้อมและเครื่องมือ (Environment & Tools)**
|
||||
|
||||
| ประเภท | เครื่องมือ/สภาพแวดล้อม | วัตถุประสงค์ |
|
||||
| :---- | :---- | :---- |
|
||||
| **สภาพแวดล้อม** | **Staging (QNAP)** | สภาพแวดล้อมจำลอง (บน Docker) ที่เหมือน Production ที่สุด ประกอบด้วย backend, mariadb, elasticsearch, n8n (Mock Receiver) |
|
||||
| **ฐานข้อมูล** | **DBeaver** | ใช้สำหรับเชื่อมต่อ MariaDB (Staging) เพื่อตรวจสอบผลลัพธ์ (Data Verification) |
|
||||
| **API (Manual)** | **Postman / Insomnia** | ใช้สำหรับการทดสอบ API ด้วยตนเอง, สำรวจ Endpoints, และสร้าง Test Case |
|
||||
| **API (Automation)** | **Postman (Newman) / Supertest** | (E2E) ใช้รัน Test Case อัตโนมัติเพื่อตรวจสอบ API Contract |
|
||||
| **Unit/Integration** | **Jest / @nestjs/testing** | (Developer) ใช้สำหรับทดสอบ Logic ภายใน Service และ Guard (ตามตัวอย่าง spec.ts ที่สร้างไว้) |
|
||||
| **Concurrency** | **k6 (แนะนำ) / Node.js Script** | ใช้สำหรับทดสอบ Stress Test และ Concurrency (โดยเฉพาะ TC-CON-01) |
|
||||
| **Webhook** | **N8N (Webhook Node)** | ใช้ N8N จริง (Staging) ตั้งค่า Webhook Node เพื่อรับ Event จาก NotificationService |
|
||||
|
||||
## **4\. รายละเอียดสถานการณ์ทดสอบ (Detailed Test Scenarios)**
|
||||
|
||||
นี่คือ Test Case ที่สำคัญที่สุด โดยแบ่งตามความเสี่ยงและ Function
|
||||
|
||||
### **T1: การรักษาความปลอดภัย (Security & RBAC) \- (ความเสี่ยงสูงมาก)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-SEC-01** | **(RBAC) ห้าม Viewer สร้างเอกสาร** | 1\. (Postman) เรียก POST /api/v1/auth/login ด้วย User "Viewer" 2\. คัดลอก access\_token 3\. เรียก POST /api/v1/correspondence (ใน Auth Header) พร้อม Body ที่ถูกต้อง | 403 Forbidden (RBACGuard ทำงาน) | Postman |
|
||||
| **TC-SEC-02** | **(RBAC) Editor ข้าม Project** | 1\. (Postman) Login User "Editor" ที่มีสิทธิ์เฉพาะ Project A 2\. (DBeaver) หา ID เอกสาร (เช่น corr\_id: 99\) ที่อยู่ใน Project B 3\. (Postman) เรียก GET /api/v1/correspondence/99 ด้วย Token ของ Editor | 403 Forbidden หรือ 404 Not Found | Postman, DBeaver |
|
||||
| **TC-SEC-03** | **(RBAC) Super Admin** | 1\. (Postman) Login User "Super Admin" 2\. เรียก Endpoint ที่จำกัดสิทธิ์สูง (เช่น POST /api/v1/admin/users) | 201 Created (Super Admin ต้องผ่านทุกการตรวจสอบ) | Postman |
|
||||
| **TC-SEC-04** | **(Rate Limit) Brute-force** | 1\. (Postman Runner หรือ k6) ตั้งค่าให้เรียก POST /api/v1/auth/login (ด้วยรหัสผ่านผิด) 110 ครั้ง (Limit คือ 100\) 2\. สังเกตผลลัพธ์ | Request ที่ 1-100: 401 Unauthorized Request ที่ 101+: 429 Too Many Requests | k6, Postman |
|
||||
| **TC-SEC-05** | **(Security) Helmet** | 1\. (Postman) เรียก Endpoint ใดก็ได้ (เช่น GET /api/v1/health) 2\. ตรวจสอบ Response Headers | ต้องมี Headers เช่น X-Content-Type-Options: nosniff, Strict-Transport-Security, X-Frame-Options: SAMEORIGIN | Postman |
|
||||
|
||||
### **T2: ตรรกะหลัก (Core Logic & Concurrency) \- (ความเสี่ยงสูง)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-CON-01** | **(Concurrency) สร้างเลขที่เอกสาร** | 1\. (k6/Script) สร้าง Script ที่เรียก POST /api/v1/correspondence (สร้างเอกสารใหม่) 50 ครั้ง *พร้อมกัน* (Simultaneously) 2\. (Postman) Login Admin 3\. (DBeaver) ตรวจสอบตาราง correspondences และ document\_number\_counters | 1\. Script ทั้ง 50 ครั้งสำเร็จ (201 Created) 2\. (DBeaver) document\_number\_counters มี last\_number: 50 3\. correspondences มีเอกสาร 50 ฉบับ โดย *ไม่มี* correspondence\_number ซ้ำกันเลย | k6, DBeaver |
|
||||
| **TC-FUNC-01** | **(Data) สร้าง RFA (Complex)** | 1\. (Postman) Login User (เช่น "Editor") 2\. เรียก POST /api/v1/rfa พร้อม DTO ที่ซับซ้อน (มี rfa\_type\_id, title, attachments, shop\_drawings) | 1\. 201 Created 2\. (DBeaver) ตรวจสอบว่ามีข้อมูลถูกสร้างขึ้นใน 3 ตารางหลัก: \- correspondences (ตารางแม่) \- rfas (ตารางแม่ RFA) \- rfa\_revisions (ตารางลูก Revision 0\) | Postman, DBeaver |
|
||||
|
||||
### **T3: การทำงานของโมดูล (Module Functionality)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-FUNC-02** | **(File) อัปโหลดไฟล์** | 1\. (Postman) Login User 2\. เรียก POST /api/v1/files/upload (ประเภท form-data, key file) 3\. (DBeaver) ตรวจสอบตาราง attachments | 1\. 201 Created คืนค่าข้อมูล Attachment (เช่น ID, stored\_filename) 2\. (DBeaver) มีแถวใหม่ในตาราง attachments 3\. (ถ้าทำได้) ตรวจสอบ QNAP /share/dms-data/... ว่ามีไฟล์จริง | Postman, DBeaver |
|
||||
| **TC-FUNC-03** | **(File) ดาวน์โหลด (ผ่าน Auth)** | 1\. (Postman) ทำ TC-FUNC-02 เพื่ออัปโหลดไฟล์ (สมมติได้ attachment\_id: 123\) 2\. เรียก GET /api/v1/files/download/123 (ต้องใส่ Auth Header) | 200 OK และได้ข้อมูลไฟล์กลับมา | Postman |
|
||||
| **TC-FUNC-04** | **(Search) Elasticsearch** | 1\. (Postman) สร้างเอกสารใหม่ POST /api/v1/correspondence (จดจำ Title ไว้) 2\. (รอ 10 วินาที ให้ Elastic Index) 3\. เรียก GET /api/v1/search?query=\[Title ที่จดไว้\] | 200 OK และผลลัพธ์การค้นหาต้องมีเอกสารที่เพิ่งสร้าง | Postman |
|
||||
| **TC-FUNC-05** | **(Notification) N8N Webhook** | 1\. (N8N) สร้าง Workflow ใหม่, ใช้ "Webhook" Node (เปิด Test Mode) 2\. (Postman) Login User 3\. เรียก POST /api/v1/circulation (สร้างใบเวียนใหม่) | 1\. (Postman) 201 Created 2\. (N8N) Webhook Node ได้รับข้อมูล Payload ({ event: 'NEW\_CIRCULATION\_TASK', ... }) | Postman, N8N |
|
||||
| **TC-FUNC-06** | **(Audit) Audit Log** | 1\. (Postman) Login Admin 2\. เรียก DELETE /api/v1/admin/roles/10 (ลบ Role สมมติ) 3\. (DBeaver) ตรวจสอบ audit\_logs | 1\. (DBeaver) มีแถวใหม่ใน audit\_logs 2\. ข้อมูลถูกต้อง: action: 'role.delete', entity\_type: 'role', entity\_id: '10', user\_id: \[Admin ID\] | Postman, DBeaver |
|
||||
|
||||
### **T4: การ Deploy (NFR)**
|
||||
|
||||
| ID | สถานการณ์ | ขั้นตอนการทดสอบ (Steps) | ผลลัพธ์ที่คาดหวัง (Expected) | เครื่องมือ |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| **TC-NFR-01** | **(Health) Health Check** | 1\. (Browser/Postman) เรียก GET /api/v1/health (จาก Staging URL) | 200 OK และ JSON Response แสดง status: "ok" และสถานะ DB | Postman, Browser |
|
||||
| **TC-NFR-02** | **(Error) Global Filter** | 1\. (Postman) เรียก Endpoint ที่ไม่มีอยู่จริง (เช่น GET /api/v1/invalid\_path) | 404 Not Found Response Body ต้องมีโครงสร้าง JSON ที่กำหนดไว้ (เช่น { "statusCode": 404, "message": "Cannot GET /api/v1/invalid\_path", ... }) | Postman |
|
||||
|
||||
|
||||
@@ -1,117 +1,117 @@
|
||||
|
||||
# แผนการพัฒนา Backend NestJS สำหรับ DMS v1.3.0
|
||||
|
||||
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
|
||||
|
||||
- [ ] สร้าง NestJS Project ใหม่ (backend/src)
|
||||
- [✅] ติดตั้ง Dependencies หลักๆ ตาม Technology Stack
|
||||
- [✅] `@nestjs/core`, `@nestjs/common`
|
||||
- [✅] `@nestjs/typeorm`, `typeorm`
|
||||
- [✅] `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt`
|
||||
- [✅] `casl`
|
||||
- [✅] `class-validator`, `class-transformer`
|
||||
- [✅] `@nestjs/swagger`
|
||||
- [✅] `winston`, `helmet`, `rate-limiter-flexible`
|
||||
- [✅] ตั้งค่า `tsconfig.json`, `nest-cli.json` และไฟล์ config อื่นๆ
|
||||
- [ ] ตั้งค่าการเชื่อมต่อ MariaDB ผ่าน TypeORM
|
||||
- [ ] **(สำคัญ)** กำหนดค่าตัวแปรสภาพแวดล้อม (DATABASE_URL, JWT_SECRET) ผ่าน `docker-compose.yml`
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: การสร้างรากฐาน (Foundation) - สัปดาห์ที่ 1-2
|
||||
|
||||
- [ ] พัฒนา Core Auth Module (`AuthModule`)
|
||||
- [✅] สร้าง Entities: `Users`, `Roles`, `Permissions`
|
||||
- [✅] สร้าง `AuthService` สำหรับ Login, Register, JWT Generation
|
||||
- [✅] สร้าง `JwtStrategy` สำหรับ Passport
|
||||
- [✅] สร้าง `RBACGuard` โดยใช้ CASL
|
||||
- [✅] สร้าง API Endpoints: `/auth/login`, `/auth/me`
|
||||
- [✅] พัฒนา Common Module (`@app/common`)
|
||||
- [✅] สร้าง `FileStorageService` สำหรับจัดการไฟล์ (อัปโหลด/ดาวน์โหลด)
|
||||
- [✅] สร้าง `AuditLogInterceptor` สำหรับบันทึกการกระทำโดยอัตโนมัติ
|
||||
- [✅] สร้าง Global Exception Filter
|
||||
- [✅] สร้าง DTOs และ Interfaces พื้นฐาน
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: พัฒนาเอนทิตีหลัก (Core Entities) - สัปดาห์ที่ 3-4
|
||||
|
||||
- [✅] พัฒนา Project Module (`ProjectModule`)
|
||||
- [✅] สร้าง Entities: `Project`, `Organization`, `Contract`, `ProjectParty`
|
||||
- [✅] สร้าง Services สำหรับ CRUD และจัดการความสัมพันธ์
|
||||
- [✅] สร้าง Controller พร้อม Swagger Decorators
|
||||
- [ ] พัฒนา Correspondence Module (`CorrespondenceModule`)
|
||||
- [ ] สร้าง Entities: `Correspondence`, `CorrespondenceRevision`, `CorrespondenceAttachment`
|
||||
- [ ] สร้าง Services สำหรับจัดการเอกสาร การสร้าง Revision
|
||||
- [ ] เชื่อมโยงกับ `FileStorageService` และ `DocumentNumberingService`
|
||||
- [ ] พัฒนา Attachment Management
|
||||
- [ ] พัฒนา API อัปโหลดไฟล์ (`POST /correspondences/:id/attachments`)
|
||||
- [ ] พัฒนา API ดาวน์โหลดไฟล์ (`GET /attachments/:id/download`)
|
||||
- [ ] ใช้ Junction Tables (`correspondence_attachments`) ในการเชื่อมโยง
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: พัฒนาเวิร์กโฟลว์เฉพาะทาง (Specialized Workflows) - สัปดาห์ที่ 5-7
|
||||
|
||||
- [ ] พัฒนา RFA Module (`RfaModule`)
|
||||
- [ ] สร้าง Entities: `Rfa`, `RfaRevision`, `RfaWorkflow`, `RfaItem`
|
||||
- [ ] สร้าง Service สำหรับจัดการ Workflow การอนุมัติ (ส่ง -> อนุมัติ/ปฏิเสธ -> ส่งกลับ)
|
||||
- [ ] จัดการ State Transitions ตาม `rfa_status_transitions`
|
||||
- [ ] พัฒนา Drawing Module (`DrawingModule`)
|
||||
- [ ] สร้าง Entities: `ShopDrawing`, `ShopDrawingRevision`, `ContractDrawing`
|
||||
- [ ] สร้าง Services สำหรับจัดการแบบแปลนและการอ้างอิงระหว่าง Shop และ Contract Drawing
|
||||
- [ ] พัฒนา Circulation Module (`CirculationModule`)
|
||||
- [ ] สร้าง Entities: `Circulation`, `CirculationAssignee`
|
||||
- [ ] สร้าง Service สำหรับการสร้างใบเวียน มอบหมายงาน และติดตามสถานะ
|
||||
- [ ] พัฒนา Transmittal Module (`TransmittalModule`)
|
||||
- [ ] สร้าง Entities: `Transmittal`, `TransmittalItem`
|
||||
- [ ] สร้าง Service สำหรับการสร้างเอกสารนำส่ง
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: คุณสมบัติขั้นสูงและการเชื่อมโยง (Advanced Features) - สัปดาห์ที่ 8-9
|
||||
|
||||
- [ ] พัฒนา Document Numbering Module (`DocumentNumberingModule`)
|
||||
- [ ] สร้าง `DocumentNumberingService` (Internal Module)
|
||||
- [ ] Implement การเรียกใช้ Stored Procedure `sp_get_next_document_number`
|
||||
- [ ] ให้บริการแก่ `CorrespondenceModule` และโมดูลอื่นๆ
|
||||
- [ ] พัฒนา Search Module (`SearchModule`)
|
||||
- [ ] ตั้งค่า Elasticsearch
|
||||
- [ ] สร้าง Service สำหรับ Index ข้อมูลจาก Views (`v_current_correspondences`, `v_current_rfas`)
|
||||
- [ ] สร้าง API ค้นหาขั้นสูง (`/search`)
|
||||
- [ ] พัฒนา Notification Service
|
||||
- [ ] สร้าง `NotificationService` ใน `CommonModule`
|
||||
- [ ] Implement การส่ง Email ผ่าน `nodemailer`
|
||||
- [ ] สร้าง Trigger สำหรับส่งการแจ้งเตือน (เอกสารใหม่, เปลี่ยนสถานะ, ใกล้ถึง Deadline)
|
||||
- [ ] เตรียมพร้อมสำหรับการเชื่อมต่อกับ N8N สำหรับ Line Notification
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: การทดสอบและเพิ่มประสิทธิภาพ (Testing & Optimization) - สัปดาห์ที่ 10
|
||||
|
||||
- [ ] ดำเนินการทดสอบ (Testing)
|
||||
- [ ] เขียน Unit Tests สำหรับ Business Logic ใน Services และ Guards
|
||||
- [ ] เขียน Integration Tests สำหรับ Controller -> Service -> Repository (โดยใช้ Test Database)
|
||||
- [ ] เขียน E2E Tests สำหรับตรวจสอบ API Contract ว่าตรงตาม Swagger
|
||||
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
|
||||
- [ ] ใช้ Caching (`@nestjs/cache-manager`) สำหรับข้อมูลที่ถูกเรียกบ่อย (Roles, Permissions)
|
||||
- [ ] ตรวจสอบ Query และใช้ Database Indexes ให้เป็นประโยชน์ (มีอยู่แล้วใน SQL)
|
||||
- [ ] ใช้ Pagination สำหรับข้อมูลจำนวนมาก
|
||||
- [ ] เพิ่มความปลอดภัย (Security)
|
||||
- [ ] ติดตั้ง `helmet` สำหรับตั้งค่า HTTP Headers
|
||||
- [ ] ติดตั้ง `rate-limiter-flexible` สำหรับป้องกัน Brute-force
|
||||
- [ ] จัดเตรียมเอกสาร (Documentation)
|
||||
- [ ] ตรวจสอบความสมบูรณ์ของ Swagger Documentation
|
||||
- [ ] เพิ่ม JSDoc Comments สำหรับ Methods และ Classes ที่สำคัญ
|
||||
|
||||
---
|
||||
|
||||
## การ Deploy บน QNAP Container Station
|
||||
|
||||
- [ ] เตรียมการ Deploy บน QNAP Container Station
|
||||
- [ ] สร้าง `Dockerfile` สำหรับ NestJS App
|
||||
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `backend` service
|
||||
- [ ] กำหนด `environment` สำหรับ `DATABASE_HOST`, `DATABASE_USER`, `DATABASE_PASSWORD`, `JWT_SECRET`
|
||||
- [ ] เชื่อมต่อกับ `lcbp3` network
|
||||
- [ ] ทดสอบ Build และ Run บน Container Station UI
|
||||
- [ ] ตั้งค่า Health Check endpoint (`/health`) โดยใช้ `@nestjs/terminus`
|
||||
|
||||
# แผนการพัฒนา Backend NestJS สำหรับ DMS v1.3.0
|
||||
|
||||
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
|
||||
|
||||
- [ ] สร้าง NestJS Project ใหม่ (backend/src)
|
||||
- [✅] ติดตั้ง Dependencies หลักๆ ตาม Technology Stack
|
||||
- [✅] `@nestjs/core`, `@nestjs/common`
|
||||
- [✅] `@nestjs/typeorm`, `typeorm`
|
||||
- [✅] `@nestjs/jwt`, `@nestjs/passport`, `passport-jwt`
|
||||
- [✅] `casl`
|
||||
- [✅] `class-validator`, `class-transformer`
|
||||
- [✅] `@nestjs/swagger`
|
||||
- [✅] `winston`, `helmet`, `rate-limiter-flexible`
|
||||
- [✅] ตั้งค่า `tsconfig.json`, `nest-cli.json` และไฟล์ config อื่นๆ
|
||||
- [ ] ตั้งค่าการเชื่อมต่อ MariaDB ผ่าน TypeORM
|
||||
- [ ] **(สำคัญ)** กำหนดค่าตัวแปรสภาพแวดล้อม (DATABASE_URL, JWT_SECRET) ผ่าน `docker-compose.yml`
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: การสร้างรากฐาน (Foundation) - สัปดาห์ที่ 1-2
|
||||
|
||||
- [ ] พัฒนา Core Auth Module (`AuthModule`)
|
||||
- [✅] สร้าง Entities: `Users`, `Roles`, `Permissions`
|
||||
- [✅] สร้าง `AuthService` สำหรับ Login, Register, JWT Generation
|
||||
- [✅] สร้าง `JwtStrategy` สำหรับ Passport
|
||||
- [✅] สร้าง `RBACGuard` โดยใช้ CASL
|
||||
- [✅] สร้าง API Endpoints: `/auth/login`, `/auth/me`
|
||||
- [✅] พัฒนา Common Module (`@app/common`)
|
||||
- [✅] สร้าง `FileStorageService` สำหรับจัดการไฟล์ (อัปโหลด/ดาวน์โหลด)
|
||||
- [✅] สร้าง `AuditLogInterceptor` สำหรับบันทึกการกระทำโดยอัตโนมัติ
|
||||
- [✅] สร้าง Global Exception Filter
|
||||
- [✅] สร้าง DTOs และ Interfaces พื้นฐาน
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: พัฒนาเอนทิตีหลัก (Core Entities) - สัปดาห์ที่ 3-4
|
||||
|
||||
- [✅] พัฒนา Project Module (`ProjectModule`)
|
||||
- [✅] สร้าง Entities: `Project`, `Organization`, `Contract`, `ProjectParty`
|
||||
- [✅] สร้าง Services สำหรับ CRUD และจัดการความสัมพันธ์
|
||||
- [✅] สร้าง Controller พร้อม Swagger Decorators
|
||||
- [ ] พัฒนา Correspondence Module (`CorrespondenceModule`)
|
||||
- [ ] สร้าง Entities: `Correspondence`, `CorrespondenceRevision`, `CorrespondenceAttachment`
|
||||
- [ ] สร้าง Services สำหรับจัดการเอกสาร การสร้าง Revision
|
||||
- [ ] เชื่อมโยงกับ `FileStorageService` และ `DocumentNumberingService`
|
||||
- [ ] พัฒนา Attachment Management
|
||||
- [ ] พัฒนา API อัปโหลดไฟล์ (`POST /correspondences/:id/attachments`)
|
||||
- [ ] พัฒนา API ดาวน์โหลดไฟล์ (`GET /attachments/:id/download`)
|
||||
- [ ] ใช้ Junction Tables (`correspondence_attachments`) ในการเชื่อมโยง
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: พัฒนาเวิร์กโฟลว์เฉพาะทาง (Specialized Workflows) - สัปดาห์ที่ 5-7
|
||||
|
||||
- [ ] พัฒนา RFA Module (`RfaModule`)
|
||||
- [ ] สร้าง Entities: `Rfa`, `RfaRevision`, `RfaWorkflow`, `RfaItem`
|
||||
- [ ] สร้าง Service สำหรับจัดการ Workflow การอนุมัติ (ส่ง -> อนุมัติ/ปฏิเสธ -> ส่งกลับ)
|
||||
- [ ] จัดการ State Transitions ตาม `rfa_status_transitions`
|
||||
- [ ] พัฒนา Drawing Module (`DrawingModule`)
|
||||
- [ ] สร้าง Entities: `ShopDrawing`, `ShopDrawingRevision`, `ContractDrawing`
|
||||
- [ ] สร้าง Services สำหรับจัดการแบบแปลนและการอ้างอิงระหว่าง Shop และ Contract Drawing
|
||||
- [ ] พัฒนา Circulation Module (`CirculationModule`)
|
||||
- [ ] สร้าง Entities: `Circulation`, `CirculationAssignee`
|
||||
- [ ] สร้าง Service สำหรับการสร้างใบเวียน มอบหมายงาน และติดตามสถานะ
|
||||
- [ ] พัฒนา Transmittal Module (`TransmittalModule`)
|
||||
- [ ] สร้าง Entities: `Transmittal`, `TransmittalItem`
|
||||
- [ ] สร้าง Service สำหรับการสร้างเอกสารนำส่ง
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: คุณสมบัติขั้นสูงและการเชื่อมโยง (Advanced Features) - สัปดาห์ที่ 8-9
|
||||
|
||||
- [ ] พัฒนา Document Numbering Module (`DocumentNumberingModule`)
|
||||
- [ ] สร้าง `DocumentNumberingService` (Internal Module)
|
||||
- [ ] Implement การเรียกใช้ Stored Procedure `sp_get_next_document_number`
|
||||
- [ ] ให้บริการแก่ `CorrespondenceModule` และโมดูลอื่นๆ
|
||||
- [ ] พัฒนา Search Module (`SearchModule`)
|
||||
- [ ] ตั้งค่า Elasticsearch
|
||||
- [ ] สร้าง Service สำหรับ Index ข้อมูลจาก Views (`v_current_correspondences`, `v_current_rfas`)
|
||||
- [ ] สร้าง API ค้นหาขั้นสูง (`/search`)
|
||||
- [ ] พัฒนา Notification Service
|
||||
- [ ] สร้าง `NotificationService` ใน `CommonModule`
|
||||
- [ ] Implement การส่ง Email ผ่าน `nodemailer`
|
||||
- [ ] สร้าง Trigger สำหรับส่งการแจ้งเตือน (เอกสารใหม่, เปลี่ยนสถานะ, ใกล้ถึง Deadline)
|
||||
- [ ] เตรียมพร้อมสำหรับการเชื่อมต่อกับ N8N สำหรับ Line Notification
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: การทดสอบและเพิ่มประสิทธิภาพ (Testing & Optimization) - สัปดาห์ที่ 10
|
||||
|
||||
- [ ] ดำเนินการทดสอบ (Testing)
|
||||
- [ ] เขียน Unit Tests สำหรับ Business Logic ใน Services และ Guards
|
||||
- [ ] เขียน Integration Tests สำหรับ Controller -> Service -> Repository (โดยใช้ Test Database)
|
||||
- [ ] เขียน E2E Tests สำหรับตรวจสอบ API Contract ว่าตรงตาม Swagger
|
||||
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
|
||||
- [ ] ใช้ Caching (`@nestjs/cache-manager`) สำหรับข้อมูลที่ถูกเรียกบ่อย (Roles, Permissions)
|
||||
- [ ] ตรวจสอบ Query และใช้ Database Indexes ให้เป็นประโยชน์ (มีอยู่แล้วใน SQL)
|
||||
- [ ] ใช้ Pagination สำหรับข้อมูลจำนวนมาก
|
||||
- [ ] เพิ่มความปลอดภัย (Security)
|
||||
- [ ] ติดตั้ง `helmet` สำหรับตั้งค่า HTTP Headers
|
||||
- [ ] ติดตั้ง `rate-limiter-flexible` สำหรับป้องกัน Brute-force
|
||||
- [ ] จัดเตรียมเอกสาร (Documentation)
|
||||
- [ ] ตรวจสอบความสมบูรณ์ของ Swagger Documentation
|
||||
- [ ] เพิ่ม JSDoc Comments สำหรับ Methods และ Classes ที่สำคัญ
|
||||
|
||||
---
|
||||
|
||||
## การ Deploy บน QNAP Container Station
|
||||
|
||||
- [ ] เตรียมการ Deploy บน QNAP Container Station
|
||||
- [ ] สร้าง `Dockerfile` สำหรับ NestJS App
|
||||
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `backend` service
|
||||
- [ ] กำหนด `environment` สำหรับ `DATABASE_HOST`, `DATABASE_USER`, `DATABASE_PASSWORD`, `JWT_SECRET`
|
||||
- [ ] เชื่อมต่อกับ `lcbp3` network
|
||||
- [ ] ทดสอบ Build และ Run บน Container Station UI
|
||||
- [ ] ตั้งค่า Health Check endpoint (`/health`) โดยใช้ `@nestjs/terminus`
|
||||
|
||||
@@ -1,169 +1,169 @@
|
||||
|
||||
# แผนการพัฒนา Frontend Next.js สำหรับ DMS v1.3.0
|
||||
|
||||
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
|
||||
|
||||
- [ ] สร้าง Next.js Project ใหม่ (App Router)
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest frontend --typescript --tailwind --eslint --app
|
||||
```
|
||||
|
||||
- [ ] ติดตั้ง Dependencies หลักๆ ตามเอกสาร FullStackJS
|
||||
- [ ] UI Library: `@shadcn/ui` และ dependencies ที่เกี่ยวข้อง
|
||||
- [ ] State Management: `zustand`
|
||||
- [ ] Server State: `@tanstack/react-query`
|
||||
- [ ] Form Handling: `react-hook-form`, `zod`, `@hookform/resolvers`
|
||||
- [ ] File Upload: `react-dropzone`
|
||||
- [ ] Icons: `lucide-react`
|
||||
- [ ] Testing: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@playwright/test`
|
||||
- [ ] ตั้งค่าโครงสร้างโปรเจกต์
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # App Router
|
||||
│ ├── (dashboard)/ # Route Groups
|
||||
│ ├── api/ # API Routes (ถ้าจำเป็น)
|
||||
│ ├── globals.css
|
||||
│ ├── layout.tsx
|
||||
│ └── page.tsx
|
||||
├── components/ # Reusable UI Components
|
||||
│ ├── ui/ # shadcn/ui components
|
||||
│ ├── forms/ # Form Components
|
||||
│ └── features/ # Feature-specific Components
|
||||
├── lib/ # Utility functions
|
||||
│ ├── api.ts # Axios/Fetch wrapper
|
||||
│ ├── auth.ts # Auth helpers
|
||||
│ └── utils.ts
|
||||
├── hooks/ # Custom React Hooks
|
||||
├── store/ # Zustand stores
|
||||
└── types/ # TypeScript type definitions
|
||||
```
|
||||
|
||||
- [ ] ตั้งค่า Tailwind CSS และ shadcn/ui
|
||||
- [ ] ตั้งค่า React Query ใน `app/providers.tsx` และครอบใน `layout.tsx`
|
||||
- [ ] ตั้งค่า Zustand store สำหรับ Global State (เช่น User, Auth)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: การสร้างรากฐานและการยืนยันตัวตน (Foundation & Authentication) - สัปดาห์ที่ 1-2
|
||||
|
||||
- [ ] พัฒนา Layout หลัก (App Shell - Req 5.1)
|
||||
- [ ] สร้าง `Navbar` Component (ชื่อระบบ, เมนูผู้ใช้, ปุ่ม Logout)
|
||||
- [ ] สร้าง `Sidebar` Component (เมนูการนำทางหลัก)
|
||||
- [ ] สร้าง `MainContent` Component สำหรับแสดงผลหน้าต่างๆ
|
||||
- [ ] ประกอบ Component ทั้งหมดใน `layout.tsx`
|
||||
- [ ] พัฒนาระบบ Authentication
|
||||
- [ ] สร้าง `LoginPage` Component (ใช้ `react-hook-form` + `zod`)
|
||||
- [ ] สร้าง Auth Store ด้วย Zustand (เก็บ User, Token, สถานะการล็อกอิน)
|
||||
- [ ] สร้าง `useAuth` Hook สำหรับเข้าถึง Auth State
|
||||
- [ ] สร้าง API functions สำหรับ Login, Logout, Get Profile
|
||||
- [ ] สร้าง Middleware สำหรับป้องกัน Route ที่ต้องการ Login
|
||||
- [ ] สร้าง `ProfilePage` (Req 5.5)
|
||||
- [ ] แสดงข้อมูลผู้ใช้
|
||||
- [ ] ฟอร์มแก้ไขข้อมูลส่วนตัว
|
||||
- [ ] ฟอร์มเปลี่ยนรหัสผ่าน
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: พัฒนาคอมโพเนนต์หลักและหน้า Dashboard (Core Components & Dashboard) - สัปดาห์ที่ 3-4
|
||||
|
||||
- [ ] พัฒนา Reusable Components พื้นฐาน
|
||||
- [ ] `DataTable` Component (รองรับ Server-side Pagination, Sorting, Filtering)
|
||||
- [ ] `FormSelect`, `FormInput`, `FormTextarea` (ครอบด้วย `react-hook-form`)
|
||||
- [ ] `LoadingSpinner`, `ErrorAlert` Components
|
||||
- [ ] `ConfirmDialog` Component
|
||||
- [ ] พัฒนา `FileUpload` Component (Req 5.7)
|
||||
- [ ] ใช้ `react-dropzone` สำหรับ Drag-and-Drop
|
||||
- [ ] รองรับการอัปโหลดหลายไฟล์
|
||||
- [ ] มี Checkbox ให้เลือก "เอกสารหลัก" (Main Document)
|
||||
- [ ] แสดงรายการไฟล์ที่เลือกพร้อมตัวเลือกลบ
|
||||
- [ ] พัฒนา `AttachmentList` Component
|
||||
- [ ] แสดงรายการไฟล์แนบที่เชื่อมโยงกับเอกสาร
|
||||
- [ ] แสดง Badge "เอกสารหลัก"
|
||||
- [ ] ปุ่มดาวน์โหลดแต่ละไฟล์
|
||||
- [ ] พัฒนา `DashboardPage` (Req 5.3)
|
||||
- [ ] สร้าง `KpiCard` Component สำหรับแสดงข้อมูลสรุป
|
||||
- [ ] สร้าง `MyTasksTable` Component
|
||||
- [ ] ดึงข้อมูลจาก API endpoint ที่เชื่อมต่อกับ View `v_user_tasks`
|
||||
- [ ] แสดงคอลัมน์: ชื่อเอกสาร, ประเภท, วันครบกำหนด, สถานะ
|
||||
- [ ] ปุ่ม "ดำเนินการ" ที่นำไปยังหน้าที่เกี่ยวข้อง
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: พัฒนาโมดูลเอกสารโต้ตอบและเวิร์กโฟลว์ (Correspondence & Workflow Modules) - สัปดาห์ที่ 5-7
|
||||
|
||||
- [ ] พัฒนา `CorrespondenceModule` (Req 3.2)
|
||||
- [ ] หน้ารายการเอกสาร (`/correspondences`)
|
||||
- [ ] `DataTable` พร้อม Filter: โครงการ, ประเภทเอกสาร, ช่วงวันที่, ผู้ส่ง/ผู้รับ
|
||||
- [ ] ปุ่ม "สร้างใหม่", "ดู", "แก้ไข" (ตามสิทธิ์)
|
||||
- [ ] หน้าสร้าง/แก้ไขเอกสาร (`/correspondences/new`, `/correspondences/[id]/edit`)
|
||||
- [ ] ฟอร์มสร้างเอกสาร (ใช้ `react-hook-form`)
|
||||
- [ ] Dropdowns ที่เชื่อมโยงกัน (Project -> Contract)
|
||||
- [ ] การเลือกผู้รับ (To/CC) หลายองค์กร
|
||||
- [ ] การใส่ Tag
|
||||
- [ ] การเชื่อมโยงเอกสารอ้างอิง
|
||||
- [ ] ใช้ `FileUpload` และ `AttachmentList` Components
|
||||
- [ ] หน้ารายละเอียดเอกสาร (`/correspondences/[id]`)
|
||||
- [ ] แสดงข้อมูลทั้งหมดของเอกสาร
|
||||
- [ ] แสดงประวัติการแก้ไข (Revisions)
|
||||
- [ ] แสดงสถานะการส่งต่อ (Routings)
|
||||
- [ ] พัฒนา `RfaModule` (Req 3.5, 5.6)
|
||||
- [ ] ฟังก์ชันพื้นฐานคล้ายกับ CorrespondenceModule
|
||||
- [ ] พัฒนา `WorkflowVisualization` Component **(สำคัญ)**
|
||||
- [ ] ดึงข้อมูลจาก `rfa_workflows` table
|
||||
- [ ] แสดงขั้นตอนทั้งหมดเป็นลำดับ (เช่น การ์ดหรือไลน์)
|
||||
- [ ] ขั้นตอนปัจจุบัน (Active) สามารถดำเนินการได้
|
||||
- [ ] ขั้นตอนอื่นๆ แสดงเป็น Disabled
|
||||
- [ ] มีปุ่มสำหรับ Action: "อนุมัติ", "ปฏิเสธ", "ขอแก้ไข"
|
||||
- [ ] สำหรับ Admin: ปุ่ม "บังคับไปขั้นตอนถัดไป", "ย้อนกลับ"
|
||||
- [ ] แสดงความคิดเห็นในแต่ละขั้นตอน
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: พัฒนาโมดูลแบบแปลนและคุณสมบัติขั้นสูง (Drawings & Advanced Features) - สัปดาห์ที่ 8-9
|
||||
|
||||
- [ ] พัฒนา `DrawingModule` (Req 3.3, 3.4)
|
||||
- [ ] แยกระหว่าง `ContractDrawingPage` และ `ShopDrawingPage`
|
||||
- [ ] ฟอร์มสร้าง/แก้ไขแบบแปลน
|
||||
- [ ] การจัดการ Revision (เช่น การสร้าง Revision ใหม่จาก Revision ปัจจุบัน)
|
||||
- [ ] การเชื่อมโยง Shop Drawing Revision กับ Contract Drawing
|
||||
- [ ] พัฒนา `CirculationModule` (Req 3.7)
|
||||
- [ ] หน้ารายการใบเวียนภายใน
|
||||
- [ ] ฟอร์มสร้างใบเวียน
|
||||
- [ ] การมอบหมายงานให้ผู้รับผิดชอบ (Main, Action, Info)
|
||||
- [ ] หน้ารายละเอียดสำหรับผู้รับผิดชอบกระทำ (แสดงความคิดเห็น, ปุ่มปิดงาน)
|
||||
- [ ] พัฒนา `AdminPanel` (Req 4.5, 4.6)
|
||||
- [ ] หน้าจัดการผู้ใช้ (Create/Edit/Delete Users ในองค์กร)
|
||||
- [ ] หน้าจัดการ Roles และ Permissions
|
||||
- [ ] หน้าจัดการ Master Data (Tags, Document Types, Categories)
|
||||
- [ ] หน้าจัดการรูปแบบเลขที่เอกสาร (Document Numbering Formats)
|
||||
- [ ] พัฒนา `AdvancedSearchPage` (Req 6.2)
|
||||
- [ ] ฟอร์มค้นหาขั้นสูงพร้อมฟิลด์ต่างๆ
|
||||
- [ ] ส่งคำขอไปยัง Search API (Elasticsearch)
|
||||
- [ ] แสดงผลลัพธ์ใน `DataTable`
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: การทดสอบ ปรับปรุงประสิทธิภาพ และเตรียม Deploy (Testing, Optimization & Deployment) - สัปดาห์ที่ 10
|
||||
|
||||
- [ ] ดำเนินการทดสอบ (Testing)
|
||||
- [ ] **Unit/Integration Tests:**
|
||||
- [ ] เขียนทดสอบสำหรับ `FileUpload` Component (Vitest + RTL)
|
||||
- [ ] เขียนทดสอบสำหรับ `DataTable` Component
|
||||
- [ ] เขียนทดสอบสำหรับ Custom Hooks (เช่น `useAuth`)
|
||||
- [ ] **E2E Tests:**
|
||||
- [ ] เขียนทดสอบ User Flow: Login -> สร้าง RFA -> อนุมัติ (Playwright)
|
||||
- [ ] เขียนทดสอบ User Flow: สร้างใบเวียน -> มอบหมายงาน -> ตอบกลับ
|
||||
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
|
||||
- [ ] ใช้ `next/dynamic` สำหรับ lazy loading ของ Components ที่ใหญ่
|
||||
- [ ] ตรวจสอบการใช้ React Query เพื่อให้แน่ใจว่ามีการ Caching และ Re-fetching ที่เหมาะสม
|
||||
- [ ] ใช้ Image Optimization ของ Next.js
|
||||
- [ ] การเตรียม Deploy
|
||||
- [ ] สร้าง `Dockerfile` สำหรับ Frontend (Multi-stage build)
|
||||
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `frontend` service
|
||||
- [ ] กำหนด `build` จาก `Dockerfile`
|
||||
- [ ] กำหนด `environment` สำหรับ `NEXT_PUBLIC_API_URL`
|
||||
- [ ] เชื่อมต่อกับ `lcbp3` network
|
||||
- [ ] ทดสอบ Build และ Run บน Container Station UI
|
||||
- [ ] ตั้งค่า Nginx Proxy Manager ให้ชี้ `lcbp3.np-dms.work` มายัง Frontend Container
|
||||
|
||||
# แผนการพัฒนา Frontend Next.js สำหรับ DMS v1.3.0
|
||||
|
||||
## การเตรียมความพร้อมและการติดตั้ง (Prerequisites & Setup)
|
||||
|
||||
- [ ] สร้าง Next.js Project ใหม่ (App Router)
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest frontend --typescript --tailwind --eslint --app
|
||||
```
|
||||
|
||||
- [ ] ติดตั้ง Dependencies หลักๆ ตามเอกสาร FullStackJS
|
||||
- [ ] UI Library: `@shadcn/ui` และ dependencies ที่เกี่ยวข้อง
|
||||
- [ ] State Management: `zustand`
|
||||
- [ ] Server State: `@tanstack/react-query`
|
||||
- [ ] Form Handling: `react-hook-form`, `zod`, `@hookform/resolvers`
|
||||
- [ ] File Upload: `react-dropzone`
|
||||
- [ ] Icons: `lucide-react`
|
||||
- [ ] Testing: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@playwright/test`
|
||||
- [ ] ตั้งค่าโครงสร้างโปรเจกต์
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # App Router
|
||||
│ ├── (dashboard)/ # Route Groups
|
||||
│ ├── api/ # API Routes (ถ้าจำเป็น)
|
||||
│ ├── globals.css
|
||||
│ ├── layout.tsx
|
||||
│ └── page.tsx
|
||||
├── components/ # Reusable UI Components
|
||||
│ ├── ui/ # shadcn/ui components
|
||||
│ ├── forms/ # Form Components
|
||||
│ └── features/ # Feature-specific Components
|
||||
├── lib/ # Utility functions
|
||||
│ ├── api.ts # Axios/Fetch wrapper
|
||||
│ ├── auth.ts # Auth helpers
|
||||
│ └── utils.ts
|
||||
├── hooks/ # Custom React Hooks
|
||||
├── store/ # Zustand stores
|
||||
└── types/ # TypeScript type definitions
|
||||
```
|
||||
|
||||
- [ ] ตั้งค่า Tailwind CSS และ shadcn/ui
|
||||
- [ ] ตั้งค่า React Query ใน `app/providers.tsx` และครอบใน `layout.tsx`
|
||||
- [ ] ตั้งค่า Zustand store สำหรับ Global State (เช่น User, Auth)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: การสร้างรากฐานและการยืนยันตัวตน (Foundation & Authentication) - สัปดาห์ที่ 1-2
|
||||
|
||||
- [ ] พัฒนา Layout หลัก (App Shell - Req 5.1)
|
||||
- [ ] สร้าง `Navbar` Component (ชื่อระบบ, เมนูผู้ใช้, ปุ่ม Logout)
|
||||
- [ ] สร้าง `Sidebar` Component (เมนูการนำทางหลัก)
|
||||
- [ ] สร้าง `MainContent` Component สำหรับแสดงผลหน้าต่างๆ
|
||||
- [ ] ประกอบ Component ทั้งหมดใน `layout.tsx`
|
||||
- [ ] พัฒนาระบบ Authentication
|
||||
- [ ] สร้าง `LoginPage` Component (ใช้ `react-hook-form` + `zod`)
|
||||
- [ ] สร้าง Auth Store ด้วย Zustand (เก็บ User, Token, สถานะการล็อกอิน)
|
||||
- [ ] สร้าง `useAuth` Hook สำหรับเข้าถึง Auth State
|
||||
- [ ] สร้าง API functions สำหรับ Login, Logout, Get Profile
|
||||
- [ ] สร้าง Middleware สำหรับป้องกัน Route ที่ต้องการ Login
|
||||
- [ ] สร้าง `ProfilePage` (Req 5.5)
|
||||
- [ ] แสดงข้อมูลผู้ใช้
|
||||
- [ ] ฟอร์มแก้ไขข้อมูลส่วนตัว
|
||||
- [ ] ฟอร์มเปลี่ยนรหัสผ่าน
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: พัฒนาคอมโพเนนต์หลักและหน้า Dashboard (Core Components & Dashboard) - สัปดาห์ที่ 3-4
|
||||
|
||||
- [ ] พัฒนา Reusable Components พื้นฐาน
|
||||
- [ ] `DataTable` Component (รองรับ Server-side Pagination, Sorting, Filtering)
|
||||
- [ ] `FormSelect`, `FormInput`, `FormTextarea` (ครอบด้วย `react-hook-form`)
|
||||
- [ ] `LoadingSpinner`, `ErrorAlert` Components
|
||||
- [ ] `ConfirmDialog` Component
|
||||
- [ ] พัฒนา `FileUpload` Component (Req 5.7)
|
||||
- [ ] ใช้ `react-dropzone` สำหรับ Drag-and-Drop
|
||||
- [ ] รองรับการอัปโหลดหลายไฟล์
|
||||
- [ ] มี Checkbox ให้เลือก "เอกสารหลัก" (Main Document)
|
||||
- [ ] แสดงรายการไฟล์ที่เลือกพร้อมตัวเลือกลบ
|
||||
- [ ] พัฒนา `AttachmentList` Component
|
||||
- [ ] แสดงรายการไฟล์แนบที่เชื่อมโยงกับเอกสาร
|
||||
- [ ] แสดง Badge "เอกสารหลัก"
|
||||
- [ ] ปุ่มดาวน์โหลดแต่ละไฟล์
|
||||
- [ ] พัฒนา `DashboardPage` (Req 5.3)
|
||||
- [ ] สร้าง `KpiCard` Component สำหรับแสดงข้อมูลสรุป
|
||||
- [ ] สร้าง `MyTasksTable` Component
|
||||
- [ ] ดึงข้อมูลจาก API endpoint ที่เชื่อมต่อกับ View `v_user_tasks`
|
||||
- [ ] แสดงคอลัมน์: ชื่อเอกสาร, ประเภท, วันครบกำหนด, สถานะ
|
||||
- [ ] ปุ่ม "ดำเนินการ" ที่นำไปยังหน้าที่เกี่ยวข้อง
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: พัฒนาโมดูลเอกสารโต้ตอบและเวิร์กโฟลว์ (Correspondence & Workflow Modules) - สัปดาห์ที่ 5-7
|
||||
|
||||
- [ ] พัฒนา `CorrespondenceModule` (Req 3.2)
|
||||
- [ ] หน้ารายการเอกสาร (`/correspondences`)
|
||||
- [ ] `DataTable` พร้อม Filter: โครงการ, ประเภทเอกสาร, ช่วงวันที่, ผู้ส่ง/ผู้รับ
|
||||
- [ ] ปุ่ม "สร้างใหม่", "ดู", "แก้ไข" (ตามสิทธิ์)
|
||||
- [ ] หน้าสร้าง/แก้ไขเอกสาร (`/correspondences/new`, `/correspondences/[id]/edit`)
|
||||
- [ ] ฟอร์มสร้างเอกสาร (ใช้ `react-hook-form`)
|
||||
- [ ] Dropdowns ที่เชื่อมโยงกัน (Project -> Contract)
|
||||
- [ ] การเลือกผู้รับ (To/CC) หลายองค์กร
|
||||
- [ ] การใส่ Tag
|
||||
- [ ] การเชื่อมโยงเอกสารอ้างอิง
|
||||
- [ ] ใช้ `FileUpload` และ `AttachmentList` Components
|
||||
- [ ] หน้ารายละเอียดเอกสาร (`/correspondences/[id]`)
|
||||
- [ ] แสดงข้อมูลทั้งหมดของเอกสาร
|
||||
- [ ] แสดงประวัติการแก้ไข (Revisions)
|
||||
- [ ] แสดงสถานะการส่งต่อ (Routings)
|
||||
- [ ] พัฒนา `RfaModule` (Req 3.5, 5.6)
|
||||
- [ ] ฟังก์ชันพื้นฐานคล้ายกับ CorrespondenceModule
|
||||
- [ ] พัฒนา `WorkflowVisualization` Component **(สำคัญ)**
|
||||
- [ ] ดึงข้อมูลจาก `rfa_workflows` table
|
||||
- [ ] แสดงขั้นตอนทั้งหมดเป็นลำดับ (เช่น การ์ดหรือไลน์)
|
||||
- [ ] ขั้นตอนปัจจุบัน (Active) สามารถดำเนินการได้
|
||||
- [ ] ขั้นตอนอื่นๆ แสดงเป็น Disabled
|
||||
- [ ] มีปุ่มสำหรับ Action: "อนุมัติ", "ปฏิเสธ", "ขอแก้ไข"
|
||||
- [ ] สำหรับ Admin: ปุ่ม "บังคับไปขั้นตอนถัดไป", "ย้อนกลับ"
|
||||
- [ ] แสดงความคิดเห็นในแต่ละขั้นตอน
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: พัฒนาโมดูลแบบแปลนและคุณสมบัติขั้นสูง (Drawings & Advanced Features) - สัปดาห์ที่ 8-9
|
||||
|
||||
- [ ] พัฒนา `DrawingModule` (Req 3.3, 3.4)
|
||||
- [ ] แยกระหว่าง `ContractDrawingPage` และ `ShopDrawingPage`
|
||||
- [ ] ฟอร์มสร้าง/แก้ไขแบบแปลน
|
||||
- [ ] การจัดการ Revision (เช่น การสร้าง Revision ใหม่จาก Revision ปัจจุบัน)
|
||||
- [ ] การเชื่อมโยง Shop Drawing Revision กับ Contract Drawing
|
||||
- [ ] พัฒนา `CirculationModule` (Req 3.7)
|
||||
- [ ] หน้ารายการใบเวียนภายใน
|
||||
- [ ] ฟอร์มสร้างใบเวียน
|
||||
- [ ] การมอบหมายงานให้ผู้รับผิดชอบ (Main, Action, Info)
|
||||
- [ ] หน้ารายละเอียดสำหรับผู้รับผิดชอบกระทำ (แสดงความคิดเห็น, ปุ่มปิดงาน)
|
||||
- [ ] พัฒนา `AdminPanel` (Req 4.5, 4.6)
|
||||
- [ ] หน้าจัดการผู้ใช้ (Create/Edit/Delete Users ในองค์กร)
|
||||
- [ ] หน้าจัดการ Roles และ Permissions
|
||||
- [ ] หน้าจัดการ Master Data (Tags, Document Types, Categories)
|
||||
- [ ] หน้าจัดการรูปแบบเลขที่เอกสาร (Document Numbering Formats)
|
||||
- [ ] พัฒนา `AdvancedSearchPage` (Req 6.2)
|
||||
- [ ] ฟอร์มค้นหาขั้นสูงพร้อมฟิลด์ต่างๆ
|
||||
- [ ] ส่งคำขอไปยัง Search API (Elasticsearch)
|
||||
- [ ] แสดงผลลัพธ์ใน `DataTable`
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: การทดสอบ ปรับปรุงประสิทธิภาพ และเตรียม Deploy (Testing, Optimization & Deployment) - สัปดาห์ที่ 10
|
||||
|
||||
- [ ] ดำเนินการทดสอบ (Testing)
|
||||
- [ ] **Unit/Integration Tests:**
|
||||
- [ ] เขียนทดสอบสำหรับ `FileUpload` Component (Vitest + RTL)
|
||||
- [ ] เขียนทดสอบสำหรับ `DataTable` Component
|
||||
- [ ] เขียนทดสอบสำหรับ Custom Hooks (เช่น `useAuth`)
|
||||
- [ ] **E2E Tests:**
|
||||
- [ ] เขียนทดสอบ User Flow: Login -> สร้าง RFA -> อนุมัติ (Playwright)
|
||||
- [ ] เขียนทดสอบ User Flow: สร้างใบเวียน -> มอบหมายงาน -> ตอบกลับ
|
||||
- [ ] ปรับปรุงประสิทธิภาพ (Performance)
|
||||
- [ ] ใช้ `next/dynamic` สำหรับ lazy loading ของ Components ที่ใหญ่
|
||||
- [ ] ตรวจสอบการใช้ React Query เพื่อให้แน่ใจว่ามีการ Caching และ Re-fetching ที่เหมาะสม
|
||||
- [ ] ใช้ Image Optimization ของ Next.js
|
||||
- [ ] การเตรียม Deploy
|
||||
- [ ] สร้าง `Dockerfile` สำหรับ Frontend (Multi-stage build)
|
||||
- [ ] สร้างไฟล์ `docker-compose.yml` สำหรับ `frontend` service
|
||||
- [ ] กำหนด `build` จาก `Dockerfile`
|
||||
- [ ] กำหนด `environment` สำหรับ `NEXT_PUBLIC_API_URL`
|
||||
- [ ] เชื่อมต่อกับ `lcbp3` network
|
||||
- [ ] ทดสอบ Build และ Run บน Container Station UI
|
||||
- [ ] ตั้งค่า Nginx Proxy Manager ให้ชี้ `lcbp3.np-dms.work` มายัง Frontend Container
|
||||
|
||||
@@ -1,210 +1,210 @@
|
||||
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
|
||||
|
||||
## **📌 1. วัตถุประสงค์**
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
* Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
* Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
* Development Environment: VS Code on Windows 11
|
||||
* Domain: np-dms.work, www.np-dms.work
|
||||
* ip: 159.192.126.103
|
||||
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
* Data Storage: /share/dms-data บน QNAP
|
||||
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
* Application name: git
|
||||
* Service: Gitea (Self-hosted on QNAP)
|
||||
* Service name: gitea
|
||||
* Domain: git.np-dms.work
|
||||
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
* Application name: lcbp3-backend
|
||||
* Service: NestJS
|
||||
* Service name: backend
|
||||
* Domain: backend.np-dms.work
|
||||
* Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
* Application name: lcbp3-db
|
||||
* Service: mariadb:10.11
|
||||
* Service name: mariadb
|
||||
* Domain: db.np-dms.work
|
||||
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
* Application name: lcbp3-db
|
||||
* Service: phpmyadmin:5-apache
|
||||
* Service name: pma
|
||||
* Domain: pma.np-dms.work
|
||||
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
* Application name: lcbp3-frontend
|
||||
* Service: next.js
|
||||
* Service name: frontend
|
||||
* Domain: lcbp3.np-dms.work
|
||||
* Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
* Styling: Tailwind CSS + PostCSS
|
||||
* Component Library: shadcn/ui
|
||||
* หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
* Application name: lcbp3-n8n
|
||||
* Service: n8nio/n8n:latest
|
||||
* Service name: n8n
|
||||
* Domain: n8n.np-dms.work
|
||||
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
* Application name: lcbp3-npm
|
||||
* Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
* Service name: npm
|
||||
* Domain: npm.np-dms.work
|
||||
* หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
|
||||
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
|
||||
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
|
||||
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
|
||||
|
||||
## **📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
* 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
* 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
* 3.1.3. องค์กร (Organizations):
|
||||
* มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
* Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
* 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กร
|
||||
* 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
* 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
* Request for Drawing Approval (RFA_DWG)
|
||||
* Request for Document Approval (RFA_DOC)
|
||||
* Request for Method statement Approval (RFA_MES)
|
||||
* Request for Material Approval (RFA_MAT)
|
||||
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
* 3.7.5. การติดตามงาน:
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
|
||||
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
|
||||
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
|
||||
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
|
||||
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
|
||||
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
|
||||
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
|
||||
|
||||
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
* Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
|
||||
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
|
||||
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
|
||||
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
|
||||
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
|
||||
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
|
||||
* Tags ที่ใช้ในระบบ
|
||||
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
|
||||
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
|
||||
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
|
||||
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
|
||||
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
|
||||
|
||||
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
* Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
* Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
* การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
* ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
|
||||
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
|
||||
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
|
||||
|
||||
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
|
||||
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
|
||||
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
|
||||
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (Notification Strategy):
|
||||
* ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ ดังนี้:
|
||||
1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
|
||||
2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
|
||||
3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
|
||||
4. (ทางเลือก) เมื่อใกล้ถึงวันครบกำหนด (Deadline) [cite: 3.2.5, 3.6.6, 3.7.5]
|
||||
# **📝 Documents Management Sytem Version 1.2.1: Application Requirements Specification**
|
||||
|
||||
## **📌 1. วัตถุประสงค์**
|
||||
|
||||
สร้างเว็บแอปพลิเคชั่นสำหรับระบบบริหารจัดการเอกสารโครงการ (Document Management System)ที่สามารถจัดการและควบคุม การสื่อสารด้วยเอกสารที่ซับซ้อน อย่างมีประสิทธิภาพ
|
||||
|
||||
* มีฟังก์ชันหลักในการอัปโหลด จัดเก็บ ค้นหา แชร์ และควบคุมสิทธิ์การเข้าถึงเอกสาร
|
||||
* ช่วยลดการใช้เอกสารกระดาษ เพิ่มความปลอดภัยในการจัดเก็บข้อมูล
|
||||
* เพิ่มความสะดวกในการทำงานร่วมกันระหว่างองกรณ์
|
||||
|
||||
## **🛠️ 2. สถาปัตยกรรมและเทคโนโลยี (System Architecture & Technology Stack)**
|
||||
|
||||
ใช้สถาปัตยกรรมแบบ Headless/API-First ที่ทันสมัย ทำงานทั้งหมดบน QNAP Server ผ่าน Container Station เพื่อความสะดวกในการจัดการและบำรุงรักษา, Domain: np-dms.work, มี fix ip, รัน docker command ใน application ของ Container Station ได้โดยตรง, ประกอบด้วย
|
||||
|
||||
* 2.1. Infrastructure & Environment:
|
||||
* Server: QNAP (Model: TS-473A, RAM: 32GB, CPU: AMD Ryzen V1500B)
|
||||
* Containerization: Container Station (Docker & Docker Compose) ใช้ UI ของ Container Station เป็นหลัก ในการ configuration และการรัน docker command
|
||||
* Development Environment: VS Code on Windows 11
|
||||
* Domain: np-dms.work, www.np-dms.work
|
||||
* ip: 159.192.126.103
|
||||
* Docker Network: ทุก Service จะเชื่อมต่อผ่านเครือข่ายกลางชื่อ lcbp3 เพื่อให้สามารถสื่อสารกันได้
|
||||
* Data Storage: /share/dms-data บน QNAP
|
||||
* ข้อจำกัด: ไม่สามารถใช้ .env ในการกำหนดตัวแปรภายนอกได้ ต้องกำหนดใน docker-compose.yml เท่านั้น
|
||||
* 2.2. Code Hosting:
|
||||
* Application name: git
|
||||
* Service: Gitea (Self-hosted on QNAP)
|
||||
* Service name: gitea
|
||||
* Domain: git.np-dms.work
|
||||
* หน้าที่: เป็นศูนย์กลางในการเก็บและจัดการเวอร์ชันของโค้ด (Source Code) สำหรับทุกส่วน
|
||||
* 2.3. Backend / Data Platform:
|
||||
* Application name: lcbp3-backend
|
||||
* Service: NestJS
|
||||
* Service name: backend
|
||||
* Domain: backend.np-dms.work
|
||||
* Framework: NestJS (Node.js, TypeScript, ESM)
|
||||
* หน้าที่: จัดการโครงสร้างข้อมูล (Data Models), สร้าง API, จัดการสิทธิ์ผู้ใช้ (Roles & Permissions), และสร้าง Workflow ทั้งหมดของระบบ
|
||||
* 2.4. Database:
|
||||
* Application name: lcbp3-db
|
||||
* Service: mariadb:10.11
|
||||
* Service name: mariadb
|
||||
* Domain: db.np-dms.work
|
||||
* หน้าที่: ฐานข้อมูลหลักสำหรับเก็บข้อมูลทั้งหมด
|
||||
* Tooling: DBeaver (Community Edition), phpmyadmin สำหรับการออกแบบและจัดการฐานข้อมูล
|
||||
* 2.5. Database management:
|
||||
* Application name: lcbp3-db
|
||||
* Service: phpmyadmin:5-apache
|
||||
* Service name: pma
|
||||
* Domain: pma.np-dms.work
|
||||
* หน้าที่: จัดการฐานข้อมูล mariadb ผ่าน Web UI
|
||||
* 2.6. Frontend:
|
||||
* Application name: lcbp3-frontend
|
||||
* Service: next.js
|
||||
* Service name: frontend
|
||||
* Domain: lcbp3.np-dms.work
|
||||
* Framework: Next.js (App Router, React, TypeScript, ESM)
|
||||
* Styling: Tailwind CSS + PostCSS
|
||||
* Component Library: shadcn/ui
|
||||
* หน้าที่: สร้างหน้าตาเว็บแอปพลิเคชันสำหรับให้ผู้ใช้งานเข้ามาดู Dashboard, จัดการเอกสาร, และติดตามงาน โดยจะสื่อสารกับ Backend ผ่าน API
|
||||
* 2.7. Workflow automation:
|
||||
* Application name: lcbp3-n8n
|
||||
* Service: n8nio/n8n:latest
|
||||
* Service name: n8n
|
||||
* Domain: n8n.np-dms.work
|
||||
* หน้าที่: จัดการ workflow ระหว่าง Backend และ Line
|
||||
* 2.8. Reverse Proxy:
|
||||
* Application name: lcbp3-npm
|
||||
* Service: Nginx Proxy Manager (nginx-proxy-manage: latest)
|
||||
* Service name: npm
|
||||
* Domain: npm.np-dms.work
|
||||
* หน้าที่: เป็นด่านหน้าในการรับ-ส่งข้อมูล จัดการโดเมนทั้งหมด, ทำหน้าที่เป็น Proxy ชี้ไปยัง Service ที่ถูกต้อง, และจัดการ SSL Certificate (HTTPS) ให้อัตโนมัติ
|
||||
* **2.9. การจัดการตรรกะทางธุรกิจ (Business Logic Implementation):**
|
||||
* 2.9.1. ตรรกะทางธุรกิจที่ซับซ้อนทั้งหมด (เช่น การเปลี่ยนสถานะ Workflow [cite: 3.5.4, 3.6.5], การบังคับใช้สิทธิ์ [cite: 4.4], การตรวจสอบ Deadline [cite: 3.2.5]) **จะถูกจัดการในฝั่ง Backend (NestJS)** [cite: 2.3] เพื่อให้สามารถบำรุงรักษาและทดสอบได้ง่าย (Testability)
|
||||
* 2.9.2. **จะไม่มีการใช้ SQL Triggers** เพื่อป้องกันตรรกะซ่อนเร้น (Hidden Logic) และความซับซ้อนในการดีบัก
|
||||
* 2.9.3. **ข้อยกเว้น:** ตรรกะเดียวที่จะอยู่ในฐานข้อมูลคือ **Stored Procedure** สำหรับการสร้างเลขที่เอกสาร (Document Numbering) [cite: 3.10] เพื่อป้องกันการซ้ำซ้อนของข้อมูล (Race Condition)
|
||||
|
||||
## **📦 3. ข้อกำหนดด้านฟังก์ชันการทำงาน (Functional Requirements)**
|
||||
|
||||
* 3.1. การจัดการโครงสร้างโครงการและองค์กร
|
||||
* 3.1.1. โครงการ (Projects): ระบบต้องสามารถจัดการเอกสารภายในหลายโครงการได้ (ปัจจุบันมี 4 โครงการ และจะเพิ่มขึ้นในอนาคต)
|
||||
* 3.1.2. สัญญา (Contracts): ระบบต้องสามารถจัดการเอกสารภายในแต่ละสัญญาได้ ในแต่ละโครงการ มีได้หลายสัญญา หรืออย่างน้อย 1 สัญญา
|
||||
* 3.1.3. องค์กร (Organizations):
|
||||
* มีหลายองค์กรในโครงการ องค์กรณ์ที่เป็น Owner, Designer และ Consultant สามารถอยู่ในหลายโครงการและหลายสัญญาได้
|
||||
* Contractor จะถือ 1 สัญญา และอยู่ใน 1 โครงการเท่านั้น
|
||||
* 3.2. การจัดการเอกสารโต้ตอบ (Correspondence Management)
|
||||
* 3.2.1. วัตถุประสงค์: เอกสารโต้ตอบ (correspondences) ระหว่างองกรณื-องกรณ์ ภายใน โครงการ (Projects) และระหว่าง องค์กร-องค์กร ภายนอก โครงการ (Projects), รองรับ To (ผู้รับหลัก) และ CC (ผู้รับสำเนา) หลายองค์กร
|
||||
* 3.2.2. ประเภทเอกสาร: ระบบต้องรองรับเอกสารรูปแบบ ไฟล์ PDF หลายประเภท (Types) เช่น จดหมาย (Letter), อีเมล์ (Email), Request for Information (RFI), และสามารถเพิ่มประเภทใหม่ได้ในภายหลัง
|
||||
* 3.2.3. การสร้างเอกสาร (Correspondence):
|
||||
* ผู้ใช้ที่มีสิทธิ์ (เช่น Document Control) สามารถสร้างเอกสารรอไว้ในสถานะ ฉบับร่าง" (Draft) ได้ ซึ่งผู้ใช้งานต่างองค์กรจะมองไม่เห็น
|
||||
* เมื่อกด "Submitted" แล้ว การแก้ไข, ถอนเอกสารกลับไปสถานะ Draft, หรือยกเลิก (Cancel) จะต้องทำโดยผู้ใช้ระดับ Admin ขึ้นไป พร้อมระบุเหตุผล
|
||||
* 3.2.4. การอ้างอิงและจัดกลุ่ม:
|
||||
* เอกสารสามารถอ้างถึง (Reference) เอกสารฉบับก่อนหน้าได้หลายฉบับ
|
||||
* สามารถกำหนด Tag ได้หลาย Tag เพื่อจัดกลุ่มและใช้ในการค้นหาขั้นสูง
|
||||
* 3.2.5. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่เป็นผู้รับได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบขององกรณ์ที่เป็น ผู้รับ/ผู้ส่ง ทราบ เมื่อมีเอกสารใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.3. การจัดกาแบบคู่สัญญา (Contract Drawing)
|
||||
* 3.3.1. วัตถุประสงค์: แบบคู่สัญญา (Contract Drawing) ใช้เพื่ออ้างอิงและใช้ในการตรวจสอบ
|
||||
* 3.3.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.3.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.3.4. การอ้างอิงและจัดกลุ่ม: ใช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Contract Drawing
|
||||
* 3.4. การจัดกาแบบก่อสร้าง (Shop Drawing)
|
||||
* 3.4.1. วัตถุประสงค์: แบบก่อสร้าง (Shop Drawing) ใช้เในการตรวจสอบ โดยจัดส่งด้วย Request for Approval (RFA)
|
||||
* 3.4.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.4.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.4.4. การอ้างอิงและจัดกลุ่ม: ช้สำหรับอ้างอิง ใน Shop Drawings, มีการจัดหมวดหมู่ของ Shop Drawings
|
||||
* 3.5. การจัดการเอกสารขออนุมัติ (Request for Approval & Workflow)
|
||||
* 3.5.1. วัตถุประสงค์: เอกสารขออนุมัติ (Request for Approval) ใช้ในการส่งเอกสารเพิอขออนุมัติ
|
||||
* 3.5.2. ประเภทเอกสาร: Request for Approval (RFA) เป็นชนิดหนึ่งของ Correspondence ที่มีลักษณะเฉพาะที่ต้องได้รับการอนุมัติ มีประเภทดังนี้:
|
||||
* Request for Drawing Approval (RFA_DWG)
|
||||
* Request for Document Approval (RFA_DOC)
|
||||
* Request for Method statement Approval (RFA_MES)
|
||||
* Request for Material Approval (RFA_MAT)
|
||||
* 3.5.2. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.5.4. การอ้างอิงและจัดกลุ่ม: การจัดการ Drawing (RFA_DWG):
|
||||
* เอกสาร RFA_DWG จะประกอบไปด้วย Shop Drawing (shop_drawings) หลายแผ่น ซึ่งแต่ละแผ่นมี Revision ของตัวเอง
|
||||
* Shop Drawing แต่ละ Revision สามารถอ้างอิงถึง Contract Drawing (Ccontract_drawings) หลายแผ่น หรือไม่อ้างถึงก็ได้
|
||||
* ระบบต้องมีส่วนสำหรับจัดการข้อมูล Master Data ของทั้ง Shop Drawing และ Contract Drawing แยกจากกัน
|
||||
* 3.6.5. Workflow การอนุมัติ: ต้องรองรับกระบวนการอนุมัติที่ซับซ้อนและเป็นลำดับ เช่น
|
||||
* ส่งจาก Originator -> Organization 1 -> Organization 2 -> Organization 3 แล้วส่งผลกลับตามลำดับเดิม (โดยถ้า องกรณ์ใดใน Workflow ให้ส่งกลับ ก็สามารถส่งผลกลับตามลำดับเดิมโดยไม่ต้องรอให้ถึง องกรณืในลำดับถัดไป)
|
||||
* 3.6.6. การจัดการ: มีการจัดการอย่างน้อยดังนี้
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ได้
|
||||
* มีระบบแจ้งเตือน ให้ผู้รับผิดชอบของ องกรณ์ ที่อยู่ใน Workflow ทราบ เมื่อมี RFA ใหม่ หรือมีการเปลี่ยนสถานะ
|
||||
* 3.6.การจัดการเอกสารนำส่ง (Transmittals)
|
||||
* 3.6.1. วัตถุประสงค์: เอกสารนำส่ง ใช้สำหรับ นำส่ง Request for Approval (RFAS) หลายฉบับ ไปยังองค์กรอื่น
|
||||
* 3.6.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.6.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ สามารถสร้างและแก้ไขได้
|
||||
* 3.6.4. การอ้างอิงและจัดกลุ่ม: เอกสารนำส่ง เป็นส่วนหนึ่งใน Correspondence
|
||||
* 3.7. ใบเวียนเอกสารภายใน (Internal Circulation Sheet)
|
||||
* 3.7.1. วัตถุประสงค์: การสื่อสาร เอกสาร (Correspondence) ทุกฉบับ จะมีใบเวียนเอกสารเพื่อควบคุมและมอบหมายงานภายในองค์กร (สามารถดูและแก้ไขได้เฉพาะคนในองค์กร)
|
||||
* 3.7.2. ประเภทเอกสาร: ไฟล์ PDF
|
||||
* 3.7.3. การสร้างเอกสาร: ผู้ใช้ที่มีสิทธิ์ในองค์กรนั้น สามารถสร้างและแก้ไขได้
|
||||
* 3.7.4. การอ้างอิงและจัดกลุ่ม: การระบุผู้รับผิดชอบ:
|
||||
* ผู้รับผิดชอบหลัก (Main): มีได้หลายคน
|
||||
* ผู้ร่วมปฏิบัติงาน (Action): มีได้หลายคน
|
||||
* ผู้ที่ต้องรับทราบ (Information): มีได้หลายคน
|
||||
* 3.7.5. การติดตามงาน:
|
||||
* สามารถกำหนดวันแล้วเสร็จ (Deadline) สำหรับผู้รับผิดชอบประเภท Main และ Action ได้
|
||||
* มีระบบแจ้งเตือนเมื่อมี Circulation ใหม่ และแจ้งเตือนล่วงหน้าก่อนถึงวันแล้วเสร็จ
|
||||
* สามารถปิด Circulation ได้เมื่อดำเนินการตอบกลับไปยังองค์กรผู้ส่ง (Originator) แล้ว หรือ รับทราบแล้ว (For Information)
|
||||
* 3.8. ประวัติการแก้ไข (Revisions): ระบบจะเก็บประวัติการสร้างและแก้ไข เอกสารทั้งหมด
|
||||
* 3.9. การจัดเก็บ: (ปรับปรุงตามสถาปัตยกรรมใหม่)
|
||||
* เอกสารและไฟล์แนบทั้งหมดจะถูกจัดเก็บในโฟลเดอร์บน Server (/share/dms-data/) [cite: 2.1]
|
||||
* ข้อมูล Metadata ของไฟล์ (เช่น ชื่อไฟล์, ขนาด, path) จะถูกเก็บในตาราง attachments (ตารางกลาง)
|
||||
* ไฟล์จะถูกเชื่อมโยงกับเอกสารประเภทต่างๆ ผ่านตารางเชื่อม (Junction tables) เช่น correspondence_attachments, circulation_attachments, shop_drawing_revision_attachments ,และ contracy_drawing_attachments
|
||||
* สถาปัตยกรรมแบบรวมศูนย์นี้ *แทนที่* แนวคิดเดิมที่จะแยกโฟลเดอร์ตามประเภทเอกสาร เพื่อรองรับการขยายระบบที่ดีกว่า
|
||||
* 3.10. การจัดการเลขที่เอกสาร (Document Numbering):
|
||||
* 3.10.1. ระบบต้องสามารถสร้างเลขที่เอกสาร (เช่น correspondence_number) ได้โดยอัตโนมัติ
|
||||
* 3.10.2. การนับเลข Running Number (SEQ) จะต้องนับแยกตาม Key ดังนี้: **โครงการ (Project)**, **องค์กรผู้ส่ง (Originator Organization)**, **ประเภทเอกสาร (Document Type)** และ **ปีปัจจุบัน (Year)**
|
||||
* 3.10.3. ผู้ดูแลระบบ (Admin) ต้องสามารถกำหนด "รูปแบบ" (Format Template) ของเลขที่เอกสารได้ (เช่น {ORG_CODE}-{TYPE_CODE}-{YEAR_SHORT}-{SEQ:4}) โดยกำหนดแยกตามโครงการและประเภทเอกสาร
|
||||
|
||||
## **🔐 4. ข้อกำหนดด้านสิทธิ์และการเข้าถึง (Access Control Requirements)**
|
||||
|
||||
* 4.1. ภาพรวม: ผู้ใช้และองค์กรสามารถดูและแก้ไขเอกสารได้ตามสิทธิ์ที่ได้รับ โดยระบบสิทธิ์จะเป็นแบบ Role-Based Access Control (RBAC)
|
||||
* 4.2. ระดับของสิทธิ์:
|
||||
* Global Roles: สิทธิ์ในภาพรวมของระบบ
|
||||
* Project-Specific Roles: สิทธิ์ที่ถูกกำหนดให้ผู้ใช้สำหรับโครงการนั้นๆ โดยเฉพาะ (เช่น เป็น Editor ในโครงการ A แต่เป็น Viewer ในโครงการ B)
|
||||
* 4.3. บทบาท (Roles) พื้นฐาน:
|
||||
* Superadmin: ไม่มีข้อจำกัดใดๆ สามารถจัดการได้ทุกอย่างข้ามองค์กรณ์
|
||||
* Admin: มีสิทธิ์เต็มที่ แต่จำกัดเฉพาะในองค์กรที่ตัวเองสังกัด สามารถจัดการผู้ใช้ในองค์กรณ์ได้ สามารถสร้าง Role ใหม่และกำหนดสิทธิ์ (Permissions) เพิ่มเติมได้ในภายหลังผ่านหน้า Admin
|
||||
* Document Control สามารถ เพิ่ม/แก้ไข/ลบ เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด ไม่สามารถจัดการผู้ใช้ได้
|
||||
* Editor: สามารถ เพิ่ม/แก้ไข เอกสารที่กำหนดไว้ เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* Viewer: สามารถดู เอกสาร เฉพาะในองค์กรณ์ที่ตัวเองสังกัด
|
||||
* 4.4. การบังคับใช้สิทธิ์: สิทธิ์ขององค์กรจะครอบคลุมสิทธิ์ของผู้ใช้ และการเข้าถึงข้อมูลที่เกี่ยวข้องกับโครงการ (เช่น การแก้ไขเอกสาร) จะถูกตรวจสอบเทียบกับสิทธิ์ที่ผู้ใช้มีในโครงการนั้นๆ โดยเฉพาะ
|
||||
* 4.5. (ใหม่) การจัดการข้อมูลหลัก (Master Data Management):
|
||||
* ระบบจะต้องมีส่วน "Admin Panel" (สำหรับ Superadmin และ Admin) เพื่อใช้จัดการข้อมูลหลัก (Master Data) ของระบบ
|
||||
* ข้อมูลหลักที่ต้องจัดการได้เป็นอย่างน้อย:
|
||||
* ประเภทเอกสาร (เช่น correspondence_types, rfa_types)
|
||||
* หมวดหมู่แบบ (เช่น shop_drawing_categories)
|
||||
* Tags ที่ใช้ในระบบ
|
||||
* สถานะเอกสาร (หากจำเป็นต้องเพิ่มในอนาคต)
|
||||
* 4.6. (ใหม่) การเริ่มต้นใช้งาน (User & Organization Onboarding):
|
||||
* การเพิ่มองค์กรณ์ใหม่ (Organizations) เข้าสู่ระบบ จะต้องดำเนินการโดย Superadmin เท่านั้น
|
||||
* เมื่อ Superadmin สร้างองค์กรณ์ใหม่ จะต้องสามารถกำหนดผู้ใช้ (User) อย่างน้อย 1 คน ให้เป็น "Admin" ประจำองค์กรณ์นั้นๆ
|
||||
* Admin ประจำองค์กณ์รจึงจะสามารถเพิ่มผู้ใช้ (Editor, Viewer, Document Control) คนอื่นๆ เข้าสู่องค์กรของตนเองได้
|
||||
|
||||
## **👥 5\. ข้อกำหนดด้านผู้ใช้งาน (User Interface & Experience)**
|
||||
|
||||
* 5.1. Layout หลัก: หน้าเว็บใช้รูปแบบ App Shell ที่ประกอบด้วย:
|
||||
* Navbar (ส่วนบน): แสดงชื่อระบบ, เมนูผู้ใช้ (Profile), เมนูสำหรับ Admin/Superadmin (จัดการผู้ใช้, จัดการสิทธิ์), และปุ่ม Login/Logout
|
||||
* Sidebar (ด้านข้าง): เป็นเมนูหลักสำหรับเข้าถึงส่วนที่เกี่ยวกับเอกสารทั้งหมด เช่น Dashboard, Correspondences, RFA, Drawings
|
||||
* Main Content Area: พื้นที่สำหรับแสดงเนื้อหาหลักของหน้าที่เลือก
|
||||
* 5.2. หน้า Landing Page: เป็นหน้าแรกที่แสดงข้อมูลบางส่วนของโครงการสำหรับผู้ใช้ที่ยังไม่ได้ล็อกอิน
|
||||
* 5.3. หน้า Dashboard: เป็นหน้าแรกหลังจากล็อกอิน ประกอบด้วย:
|
||||
* การ์ดสรุปภาพรวม (KPI Cards): แสดงข้อมูลสรุปที่สำคัญขององค์กร เช่น จำนวนเอกสาร, งานที่เกินกำหนด
|
||||
* ตาราง "งานของฉัน" (My Tasks Table): แสดงรายการงานทั้งหมดจาก Circulation ที่ผู้ใช้ต้องดำเนินการ
|
||||
* 5.4. การติดตามสถานะ: องค์กรสามารถติดตามสถานะเอกสารทั้งของตนเอง (Originator) และสถานะเอกสารที่ส่งมาถึงตนเอง (Recipient)
|
||||
* 5.5. การจัดการข้อมูลส่วนตัว (Profile Page): ผู้ใช้สามารถจัดการข้อมูลส่วนตัวและเปลี่ยนรหัสผ่านของตนเองได้
|
||||
* 5.6. การจัดการเอกสารทางเทคนิค (Technical Documents & Workflow): ผู้ใช้สามารถดู Technical Document ในรูปแบบ Workflow ทั้งหมดได้ในหน้าเดียว, ขั้นตอนที่ยังไม่ถึงหรือผ่านไปแล้วจะเป็นรูปแบบ diable, สามารถดำเนินการได้เฉพาะในขั้นตอนที่ได้รับมอบหมายงาน (active) เช่น ตรวจสอบแล้ว เพื่อไปยังขั้นตอนต่อไป, สิทธิ์ admin ขึ้นไป สามรถกด ไปยังขั้นตอนต่อไป ได้ทุกขั้นตอน, การย้อนกลับ ไปขั้นตอนก่อนหน้า สามารถทำได้โดย สิทธิ์ admin ขึ้นไป
|
||||
* 5.7. ข้อกำหนด UI/UX การแนบไฟล์ (File Attachment UX):
|
||||
* ระบบต้องรองรับการอัปโหลดไฟล์หลายไฟล์พร้อมกัน (Multi-file upload) เช่น การลากและวาง (Drag-and-Drop)
|
||||
* ในหน้าอัปโหลด (เช่น สร้าง RFA หรือ Correspondence) ผู้ใช้ต้องสามารถกำหนดได้ว่าไฟล์ใดเป็น "เอกสารหลัก" (Main Document เช่น PDF) และไฟล์ใดเป็น "เอกสารแนบประกอบ" (Supporting Attachments เช่น .dwg, .docx, .zip)
|
||||
|
||||
## **6. ข้อกำหนดที่ไม่ใช่ฟังก์ชันการทำงาน (Non-Functional Requirements)**
|
||||
|
||||
* 6.1. การบันทึกการกระทำ (Audit Log): ทุกการกระทำที่สำคัญของผู้ใช้ (สร้าง, แก้ไข, ลบ, ส่ง) จะถูกบันทึกไว้ใน audit_logs เพื่อการตรวจสอบย้อนหลัง
|
||||
* 6.2. การค้นหา (Search): ระบบต้องมีฟังก์ชันการค้นหาขั้นสูง ที่สามารถค้นหาเอกสาร **correspondence**, **rfa**, **shop_drawing**, **contract-drawing**, **transmittal** และ **ใบเวียน (Circulations)** จากหลายเงื่อนไขพร้อมกันได้ เช่น ค้นหาจากชื่อเรื่อง, ประเภท, วันที่, และ Tag
|
||||
* 6.3. การทำรายงาน (Reporting): สามารถจัดทำรายงานสรุปแยกประเภทของ Correspondence ประจำวัน, สัปดาห์, เดือน, และปีได้
|
||||
* 6.4. ประสิทธิภาพ (Performance): มีการใช้ Caching กับข้อมูลที่เรียกใช้บ่อย และใช้ Pagination ในตารางข้อมูลเพื่อจัดการข้อมูลจำนวนมาก
|
||||
* 6.5. ความปลอดภัย (Security):
|
||||
* มีระบบ Rate Limiting เพื่อป้องกันการโจมตีแบบ Brute-force
|
||||
* การจัดการ Secret (เช่น รหัสผ่าน DB, JWT Secret) จะต้องทำผ่าน Environment Variable ของ Docker เพื่อความปลอดภัยสูงสุด
|
||||
* 6.6. (ใหม่) การสำรองข้อมูลและการกู้คืน (Backup & Recovery):
|
||||
* ระบบจะต้องมีกลไกการสำรองข้อมูลอัตโนมัติสำหรับฐานข้อมูล MariaDB [cite: 2.4] และไฟล์เอกสารทั้งหมดใน /share/dms-data [cite: 2.1] (เช่น ใช้ HBS 3 ของ QNAP หรือสคริปต์สำรองข้อมูล) อย่างน้อยวันละ 1 ครั้ง
|
||||
* ต้องมีแผนการกู้คืนระบบ (Disaster Recovery Plan) ในกรณีที่ Server หลัก (QNAP) ใช้งานไม่ได้
|
||||
* 6.7. (ใหม่) กลยุทธ์การแจ้งเตือน (Notification Strategy):
|
||||
* ระบบจะส่งการแจ้งเตือน (ผ่าน Email หรือ Line [cite: 2.7]) เมื่อมีการกระทำที่สำคัญ ดังนี้:
|
||||
1. เมื่อมีเอกสารใหม่ (Correspondence, RFA) ถูกส่งมาถึงองค์กรณ์ของเรา
|
||||
2. เมื่อมีใบเวียน (Circulation) ใหม่ มอบหมายงานมาที่เรา
|
||||
3. (ทางเลือก) เมื่อเอกสารที่เราส่งไป ถูกดำเนินการ (เช่น อนุมัติ/ปฏิเสธ)
|
||||
4. (ทางเลือก) เมื่อใกล้ถึงวันครบกำหนด (Deadline) [cite: 3.2.5, 3.6.6, 3.7.5]
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,110 +1,110 @@
|
||||
```Icon
|
||||
📂
|
||||
🔐
|
||||
⚙️
|
||||
✨
|
||||
📦
|
||||
🐞
|
||||
🖥️
|
||||
📊
|
||||
💡
|
||||
📄
|
||||
💬
|
||||
|
||||
# 🎯 Icon Showcase for Documentation & Presentations
|
||||
|
||||
This document presents a curated set of emoji and image-based icons across multiple categories for use in Markdown files, presentations, and documentation.
|
||||
|
||||
---
|
||||
## 📌 UI Icons
|
||||
|
||||
**Description:** Icons used for user interface elements such as settings, navigation, and interaction.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| ⚙️ | Settings |
|
||||
| 🖱️ | Mouse Click |
|
||||
| 📁 | Folder Navigation |
|
||||
| 🔍 | Search |
|
||||
| 📂 | Open Folder |
|
||||
|
||||
---
|
||||
## 📌 Communication Icons
|
||||
|
||||
**Description:** Icons representing communication methods and tools.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 📞 | Phone Call |
|
||||
| ✉️ | Email |
|
||||
| 💬 | Chat |
|
||||
| 📢 | Announcement |
|
||||
| 📡 | Signal |
|
||||
|
||||
---
|
||||
## 📌 Technology Icons
|
||||
|
||||
**Description:** Icons related to devices, cloud services, and digital infrastructure.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 💻 | Laptop |
|
||||
| 🖥️ | Desktop |
|
||||
| ☁️ | Cloud |
|
||||
| 🔌 | Plug |
|
||||
| 🧠 | AI / Intelligence |
|
||||
|
||||
---
|
||||
## 📌 Productivity Icons
|
||||
|
||||
**Description:** Icons used to represent tasks, schedules, and progress.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 📅 | Calendar |
|
||||
| ✅ | Completed Task |
|
||||
| ⏰ | Alarm / Reminder |
|
||||
| 📊 | Statistics |
|
||||
| 📝 | Notes |
|
||||
|
||||
---
|
||||
## 📌 Creative Icons
|
||||
|
||||
**Description:** Icons representing artistic and creative activities.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 🎨 | Art / Design |
|
||||
| 🎬 | Video / Film |
|
||||
| 🎵 | Music |
|
||||
| ✏️ | Drawing / Writing |
|
||||
| 📸 | Photography |
|
||||
|
||||
---
|
||||
## 📌 Business Icons
|
||||
|
||||
**Description:** Icons used in business contexts such as finance, strategy, and management.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 💼 | Briefcase |
|
||||
| 📈 | Growth Chart |
|
||||
| 📉 | Decline Chart |
|
||||
| 🧾 | Invoice |
|
||||
| 🏢 | Office Building |
|
||||
|
||||
---
|
||||
## 📌 Education Icons
|
||||
|
||||
**Description:** Icons representing learning, teaching, and academic activities.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 🎓 | Graduation |
|
||||
| 📚 | Books |
|
||||
| 🧑🏫 | Teacher |
|
||||
| 📝 | Exam / Assignment |
|
||||
| 🏫 | School |
|
||||
|
||||
---
|
||||
```Icon
|
||||
📂
|
||||
🔐
|
||||
⚙️
|
||||
✨
|
||||
📦
|
||||
🐞
|
||||
🖥️
|
||||
📊
|
||||
💡
|
||||
📄
|
||||
💬
|
||||
|
||||
# 🎯 Icon Showcase for Documentation & Presentations
|
||||
|
||||
This document presents a curated set of emoji and image-based icons across multiple categories for use in Markdown files, presentations, and documentation.
|
||||
|
||||
---
|
||||
## 📌 UI Icons
|
||||
|
||||
**Description:** Icons used for user interface elements such as settings, navigation, and interaction.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| ⚙️ | Settings |
|
||||
| 🖱️ | Mouse Click |
|
||||
| 📁 | Folder Navigation |
|
||||
| 🔍 | Search |
|
||||
| 📂 | Open Folder |
|
||||
|
||||
---
|
||||
## 📌 Communication Icons
|
||||
|
||||
**Description:** Icons representing communication methods and tools.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 📞 | Phone Call |
|
||||
| ✉️ | Email |
|
||||
| 💬 | Chat |
|
||||
| 📢 | Announcement |
|
||||
| 📡 | Signal |
|
||||
|
||||
---
|
||||
## 📌 Technology Icons
|
||||
|
||||
**Description:** Icons related to devices, cloud services, and digital infrastructure.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 💻 | Laptop |
|
||||
| 🖥️ | Desktop |
|
||||
| ☁️ | Cloud |
|
||||
| 🔌 | Plug |
|
||||
| 🧠 | AI / Intelligence |
|
||||
|
||||
---
|
||||
## 📌 Productivity Icons
|
||||
|
||||
**Description:** Icons used to represent tasks, schedules, and progress.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 📅 | Calendar |
|
||||
| ✅ | Completed Task |
|
||||
| ⏰ | Alarm / Reminder |
|
||||
| 📊 | Statistics |
|
||||
| 📝 | Notes |
|
||||
|
||||
---
|
||||
## 📌 Creative Icons
|
||||
|
||||
**Description:** Icons representing artistic and creative activities.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 🎨 | Art / Design |
|
||||
| 🎬 | Video / Film |
|
||||
| 🎵 | Music |
|
||||
| ✏️ | Drawing / Writing |
|
||||
| 📸 | Photography |
|
||||
|
||||
---
|
||||
## 📌 Business Icons
|
||||
|
||||
**Description:** Icons used in business contexts such as finance, strategy, and management.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 💼 | Briefcase |
|
||||
| 📈 | Growth Chart |
|
||||
| 📉 | Decline Chart |
|
||||
| 🧾 | Invoice |
|
||||
| 🏢 | Office Building |
|
||||
|
||||
---
|
||||
## 📌 Education Icons
|
||||
|
||||
**Description:** Icons representing learning, teaching, and academic activities.
|
||||
|
||||
| Icon | Meaning |
|
||||
|------|---------|
|
||||
| 🎓 | Graduation |
|
||||
| 📚 | Books |
|
||||
| 🧑🏫 | Teacher |
|
||||
| 📝 | Exam / Assignment |
|
||||
| 🏫 | School |
|
||||
|
||||
---
|
||||
```
|
||||
Reference in New Issue
Block a user