lcbp3/docs/temp.md

🚀 GitHub Spec Kit: การใช้งานร่วมกับ Requirements & FullStackJS v1.4.5

ðŸ"‹ ภาพรวม

GitHub Spec Kit เป็นเครื่องมือที่ช่วยให้คุณสร้าง Issue Specifications ที่มีโครงสร้างชัดเจนและครบถ้วนสำหรับโปรเจค LCBP3-DMS โดยอ้างอิง Requirements v1.4.5 และ FullStackJS v1.4.5

---

🎯 วัตถุประสงค์หลัก

1. แปลง Requirements เป็น Actionable Tasks - แบ่งความต้องการขนาดใหญ่เป็น issues ขนาดเล็กที่ทำได้จริง
2. รักษา Standards - ทุก issue ต้องสอดคล้องกับ FullStackJS Guidelines
3. Traceability - อ้างอิงกลับไปยัง Requirements ได้ทุกครั้ง
4. Consistency - ใช้ template และรูปแบบเดียวกันทั้งโปรเจค

---

ðŸ"š โครงสร้าง Spec Kit

1. Issue Title Format

[<Module>] <FeatureType>: <ShortDescription>

ตัวอย่าง:

• [RFA] Feature: Implement RFA Creation Workflow
• [Auth] Security: Add Rate Limiting to Login Endpoint
• [File] Refactor: Implement Two-Phase Storage Strategy

2. Issue Labels

• Type: feature, bug, refactor, security, performance
• Priority: critical, high, medium, low
• Module: backend, frontend, database, infrastructure
• Status: blocked, in-progress, review-needed

3. Issue Template Structure

## 📋 Overview

[Brief description of what needs to be done]

## 🎯 Requirements Reference

- **Section:** [Requirements v1.4.5 - Section X.X]
- **Related:** [Link to specific requirement]

## ðŸ'» Technical Specifications

### Backend (NestJS)

- Module: `<ModuleName>`
- Files to modify:
  - [ ] `src/modules/<module>/<file>.ts`
- Dependencies: `<npm packages>`

### Frontend (Next.js)

- Pages/Components:
  - [ ] `app/<page>/page.tsx`
- Dependencies: `<npm packages>`

### Database

- Tables affected: `<table_names>`
- Migrations needed: [ ] Yes / [ ] No

## ✅ Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Security checks passed
- [ ] Tests written and passing
- [ ] Documentation updated

## 🧪 Testing Requirements

- [ ] Unit tests (70% coverage minimum)
- [ ] Integration tests
- [ ] E2E tests (if applicable)

## 🔒 Security Checklist

- [ ] Input validation implemented
- [ ] RBAC permissions checked
- [ ] Audit logging added
- [ ] No sensitive data in logs

## ðŸ"— Related Issues

- Blocks: #<issue_number>
- Depends on: #<issue_number>
- Related to: #<issue_number>

## ðŸ"Œ Notes

[Any additional context, decisions, or constraints]

---

ðŸ› ï¸ วิธีการใช้งาน

Step 1: ระบุ Feature จาก Requirements

อ้างอิง: 0_Requirements_V1_4_5.md

ตัวอย่าง:

Section 3.3: การจัดการเอกสารขออนุมัติ (RFA)

Step 2: สร้าง Issue Specification

Title:

[RFA] Feature: Implement RFA Creation with Workflow Engine

Overview:

## 📋 Overview

Implement the RFA (Request for Approval) creation workflow that allows
Document Control users to create RFAs with multiple revisions and trigger
the unified workflow engine.

## 🎯 Requirements Reference

- **Section:** Requirements v1.4.5 - Section 3.3
- **Page Reference:** Lines 250-275
- **Key Requirements:**
  - Support PDF file uploads only [3.3.2]
  - Multiple revisions support [3.3.2]
  - Draft/Submitted state management [3.3.3]
  - Integration with Unified Workflow Engine [3.3.5]

Step 3: กำหนด Technical Specs ตาม FullStackJS

อ้างอิง: 1_FullStackJS_V1_4_5.md

## ðŸ'» Technical Specifications

### Backend (NestJS)

- **Module:** `RfaModule` [Section 3.9.7]
- **Files to modify:**

  - [ ] `src/modules/rfa/rfa.controller.ts`
  - [ ] `src/modules/rfa/rfa.service.ts`
  - [ ] `src/modules/rfa/dto/create-rfa.dto.ts`
  - [ ] `src/modules/workflow/workflow-engine.service.ts`

- **Dependencies:**
  ```json
  {
    "@nestjs/typeorm": "^10.0.0",
    "class-validator": "^0.14.0",
    "class-transformer": "^0.5.1"
  }
  ```

• Implementation Guidelines:
  • Use Two-Phase Storage for file uploads [Section 3.3]
  • Apply Optimistic Locking for race conditions [Section 3.2.1]
  • Integrate with DocumentNumberingService [Section 3.9.12]
  • Follow RBAC permissions [Section 5.4]

Frontend (Next.js)

• Pages/Components:

  • app/rfas/new/page.tsx
  • components/rfa/rfa-form.tsx
  • components/rfa/revision-manager.tsx

• Dependencies:

  {
    "react-hook-form": "^7.50.0",
    "zod": "^3.22.0",
    "@tanstack/react-query": "^5.20.0"
  }
  

• State Management: [Section 4.10]

  • Use React Query for server state
  • Use React Hook Form for form state
  • Implement auto-save drafts to localStorage [Section 4.1.1]

Database

• Tables affected:

  • rfas - main table
  • rfa_revisions - revision history
  • rfa_items - related items
  • workflow_instances - workflow state

• Migrations needed: [ ✓ ] Yes

  • Create migration for virtual columns if using JSON [Section 3.2.2]

### **Step 4: กำหนด Acceptance Criteria**

```markdown
## ✅ Acceptance Criteria

### Functional Requirements
- [ ] Document Control users can create new RFAs
- [ ] Support PDF file upload (max 50MB) [Section 3.10.1]
- [ ] RFA can have multiple revisions [Section 3.3.2]
- [ ] RFA number auto-generated using format template [Section 3.11]
- [ ] Draft state allows editing, Submitted state is read-only [Section 3.3.3]
- [ ] Triggers workflow engine on submission [Section 3.3.5]

### Non-Functional Requirements
- [ ] API response time < 200ms (excluding file processing) [Section 6.4]
- [ ] Virus scanning implemented for all uploads [Section 3.10.2]
- [ ] File integrity checks (checksum) performed [Section 3.10.3]
- [ ] Audit log entry created for all actions [Section 6.1]
- [ ] RBAC permissions enforced (rfas.create) [Section 5.4.2]

### Security Requirements
- [ ] Input validation using class-validator [Section 2.1]
- [ ] Rate limiting applied (1000 req/hour for Editor) [Section 6.5.1]
- [ ] No sensitive data in error messages [Section 6.5.4]
- [ ] Download links expire after 24 hours [Section 3.10.2]

Step 5: กำหนด Testing Requirements

## 🧪 Testing Requirements

### Unit Tests (Jest) [Section 3.14]

- [ ] RfaService.create() - success case
- [ ] RfaService.create() - validation failures
- [ ] RfaService.create() - file upload failures
- [ ] RfaService.create() - race condition handling
- [ ] DocumentNumberingService integration
- **Target Coverage:** 70% minimum [Section 7.1]

### Integration Tests (Supertest) [Section 7.2]

- [ ] POST /api/rfas - with valid file upload
- [ ] POST /api/rfas - with invalid file type
- [ ] POST /api/rfas - with virus-infected file
- [ ] POST /api/rfas - without required permissions
- [ ] Workflow engine integration test

### E2E Tests (Playwright) [Section 7.3]

- [ ] Complete RFA creation flow
- [ ] File upload with drag-and-drop
- [ ] Form auto-save and recovery
- [ ] Error handling and user feedback

### Security Tests [Section 7.4]

- [ ] SQL injection attempts blocked
- [ ] XSS attacks prevented
- [ ] File upload security bypass attempts
- [ ] Rate limiting enforcement

Step 6: Security Checklist

## 🔒 Security Checklist [Section 6.5]

### Input Validation

- [ ] All DTOs use class-validator [Section 3.1]
- [ ] File type white-list enforced (PDF only) [Section 3.10.1]
- [ ] File size limit checked (50MB max) [Section 3.10.1]
- [ ] JSON schema validation for details field [Section 3.12]

### Authentication & Authorization

- [ ] JWT token validation [Section 5.1]
- [ ] RBAC permission check (rfas.create) [Section 5.4]
- [ ] Organization scope validation [Section 4.2]
- [ ] Session tracking implemented [Section 6.5.4]

### Data Protection

- [ ] Audit log entry created [Section 8.1]
- [ ] Sensitive data not logged [Section 6.5.4]
- [ ] File integrity checksum stored [Section 3.10.3]
- [ ] Virus scanning completed [Section 3.10.2]

### Rate Limiting [Section 6.5.1]

- [ ] Editor: 1000 req/hour
- [ ] File Upload: 50 req/hour
- [ ] Fallback for rate limiter failures

---

ðŸ"Š ตัวอย่าง Issue ที่สมบูรณ์

Issue #1: [RFA] Feature: Implement RFA Creation with Workflow Engine

## 📋 Overview

Implement the RFA (Request for Approval) creation workflow that allows
Document Control users to create RFAs with multiple revisions and trigger
the unified workflow engine.

## 🎯 Requirements Reference

- **Section:** Requirements v1.4.5 - Section 3.3
- **Lines:** 250-275
- **Key Requirements:**
  - วัตถุประสงค์: เอกสารขออนุมัติ (RFA) ภายใน โครงการ [3.3.1]
  - ประเภทเอกสาร: รองรับเอกสารรูปแบบ ไฟล์ PDF [3.3.2]
  - รองรับ Multiple Revisions [3.3.2]
  - Draft/Submitted State Management [3.3.3]
  - Unified Workflow Integration [3.3.5]

## ðŸ'» Technical Specifications

### Backend (NestJS)

**Module:** `RfaModule` [FullStackJS Section 3.9.7]

**Files to create/modify:**

- [ ] `src/modules/rfa/rfa.controller.ts`
- [ ] `src/modules/rfa/rfa.service.ts`
- [ ] `src/modules/rfa/dto/create-rfa.dto.ts`
- [ ] `src/modules/rfa/entities/rfa.entity.ts`
- [ ] `src/modules/rfa/entities/rfa-revision.entity.ts`
- [ ] `src/modules/workflow/workflow-engine.service.ts`

**Dependencies:**

```json
{
  "@nestjs/typeorm": "^10.0.0",
  "class-validator": "^0.14.0",
  "class-transformer": "^0.5.1",
  "uuid": "^9.0.0"
}
```

Implementation Guidelines:

1. File Storage: Use Two-Phase Storage Strategy [FullStackJS 3.3]

   • Phase 1: Upload to temp/ with virus scan
   • Phase 2: Move to permanent/{YYYY}/{MM}/ on commit

2. Concurrency: Apply Optimistic Locking [FullStackJS 3.2.1]

   @VersionColumn()
   version: number;
   

3. Document Numbering: [FullStackJS 3.9.12]

   • Inject DocumentNumberingService
   • Use Redis distributed lock for counter
   • Format: {ORG}-RFA-{DISCIPLINE}-{SEQ:4}-{REV}

4. Workflow Integration: [FullStackJS 3.9.14]

   • Call WorkflowEngineService.createInstance()
   • Set initial state to 'DRAFT'
   • Transition to workflow on submission

Frontend (Next.js)

Pages/Components:

• app/rfas/new/page.tsx - Main creation page
• components/rfa/rfa-form.tsx - Form component
• components/rfa/revision-manager.tsx - Revision UI
• components/file-upload/multi-file-upload.tsx - File upload

Dependencies:

{
  "react-hook-form": "^7.50.0",
  "zod": "^3.22.0",
  "@tanstack/react-query": "^5.20.0",
  "react-dropzone": "^14.2.3"
}

State Management: [FullStackJS 4.10]

• Server State: React Query for RFA data
• Form State: React Hook Form + Zod validation
• Auto-save: LocalStorage for drafts [FullStackJS 4.1.1]

File Upload UX: [FullStackJS 5.7]

// Multi-file drag-and-drop
// Distinguish between "Main Document" and "Supporting Attachments"
// Show virus scan progress
// Display file type icons and security warnings

Database

Tables affected:

• rfas - Main RFA table
• rfa_revisions - Revision history
• rfa_items - Related items
• workflow_instances - Workflow state
• attachments - File metadata
• rfa_attachments - Junction table

Migrations needed: [ ✓ ] Yes

-- Example migration structure
CREATE TABLE rfas (
  rfa_id INT PRIMARY KEY AUTO_INCREMENT,
  project_id INT NOT NULL,
  rfa_number VARCHAR(100) UNIQUE NOT NULL,
  current_state VARCHAR(50),
  version INT DEFAULT 1,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  deleted_at TIMESTAMP NULL,
  FOREIGN KEY (project_id) REFERENCES projects(project_id)
);

✅ Acceptance Criteria

Functional Requirements

• Document Control users can create new RFAs
• Support PDF file upload (max 50MB) [Req 3.10.1]
• RFA can have multiple revisions [Req 3.3.2]
• RFA number auto-generated: {ORG}-RFA-{DISCIPLINE}-{SEQ:4}-{REV} [Req 3.11]
• Draft state allows editing, Submitted state is read-only [Req 3.3.3]
• Admin can cancel/revert submitted RFAs [Req 3.3.3]
• Triggers unified workflow engine on submission [Req 3.3.5]
• Can reference Shop Drawings in RFA [Req 3.3.4]

Non-Functional Requirements

• API response time < 200ms (excluding file processing) [Req 6.4]
• File upload completes < 30 seconds for 50MB [Req 6.4]
• Virus scanning implemented (ClamAV) [Req 3.10.2]
• File integrity checks (checksum) performed [Req 3.10.3]
• Audit log entry created for all actions [Req 6.1]
• RBAC permissions enforced (rfas.create, rfas.respond) [Req 5.4.2]

UI/UX Requirements [FullStackJS 5.7]

• Form uses React Hook Form + Zod validation
• Multi-file drag-and-drop interface
• Clear distinction between main document and attachments
• Real-time virus scan feedback
• File type indicators and security warnings
• Auto-save draft to localStorage every 30 seconds
• Mobile-responsive (Card View on small screens)

Security Requirements [Req 6.5]

• Input validation using class-validator
• Rate limiting: Editor 1000 req/hour, File Upload 50 req/hour
• No sensitive data in error messages
• Download links expire after 24 hours
• Files stored outside web root
• Access control checks before file download

🧪 Testing Requirements

Unit Tests (Jest) [FullStackJS 3.14]

describe('RfaService', () => {
  describe('create', () => {
    it('should create RFA with valid data');
    it('should reject invalid file types');
    it('should handle race conditions with optimistic locking');
    it('should generate correct RFA number');
    it('should trigger workflow on submission');
  });
});

• Target Coverage: 70% minimum [Req 7.1]

Integration Tests (Supertest) [FullStackJS 3.14]

describe('POST /api/rfas', () => {
  it('should create RFA with file upload');
  it('should reject virus-infected files');
  it('should enforce RBAC permissions');
  it('should create workflow instance');
});

E2E Tests (Playwright) [FullStackJS 4.9]

test('Complete RFA creation flow', async ({ page }) => {
  // Login as Document Control user
  // Navigate to RFA creation page
  // Fill form with test data
  // Upload main document (PDF)
  // Upload supporting attachment
  // Verify auto-save works
  // Submit RFA
  // Verify workflow starts
});

Security Tests [Req 7.4]

• SQL injection attempts blocked
• XSS attacks prevented
• File upload security bypass attempts
• Rate limiting enforcement
• Unauthorized access attempts blocked

🔒 Security Checklist [Req 6.5]

Input Validation

• All DTOs use class-validator decorators
• File type white-list enforced (PDF only)
• File size limit checked (50MB max)
• JSON schema validation for details field
• Sanitize all user inputs

Authentication & Authorization

• JWT token validation on all endpoints
• RBAC permission check (rfas.create, rfas.respond)
• Organization scope validation
• Project membership validation
• Session tracking and concurrent session limits

Data Protection

• Audit log entry for: create, update, submit, cancel
• Sensitive data not logged (file contents, user emails)
• File integrity checksum stored in database
• Virus scanning before file is accessible
• Encrypted storage for sensitive metadata

Rate Limiting [Req 6.5.1]

• Document Control: 2000 req/hour
• File Upload: 50 req/hour per user
• Graceful degradation if Redis unavailable
• Alert on rate limit violations

ðŸ"— Related Issues

• Depends on:

  • # FileStorageService implementation
  • # WorkflowEngine implementation
  • # DocumentNumberingService implementation

• Blocks:

  • # RFA Response/Approval workflow
  • # RFA Reports and Analytics

• Related to:

  • # Shop Drawing reference system
  • # Unified Workflow Engine

ðŸ"Œ Notes

Design Decisions

1. Why Two-Phase Storage?

   • Prevents orphan files if transaction fails
   • Allows virus scanning before commitment
   • Reference: FullStackJS Section 3.3

2. Why Application-level Locking?

   • More portable than database stored procedures
   • Better observability with Redis
   • Reference: FullStackJS Section 3.9.12

3. Why Optimistic Locking?

   • Better performance than pessimistic locks
   • Handles concurrent updates gracefully
   • Reference: FullStackJS Section 3.2.1

Implementation Order

1. Backend: Entity, DTO, Service (with tests)
2. Backend: Controller, Guards, Interceptors
3. Database: Migration scripts
4. Frontend: Form component (with validation)
5. Frontend: File upload component
6. Frontend: Integration with API
7. E2E: Complete user flow test

Risk Mitigation

• File Upload Failures: Implement retry with exponential backoff
• Virus Scan Downtime: Queue files for later scanning, block download
• Database Contention: Redis lock + Optimistic lock dual protection
• Large Files: Stream uploads, show progress indicator

---

ðŸ"Œ Labels

feature backend frontend database high-priority requires-testing

👤 Assignment

• Backend: @backend-team
• Frontend: @frontend-team
• QA: @qa-team

⏱ï¸ Estimated Effort

• Backend: 5 days
• Frontend: 3 days
• Testing: 2 days
• Total: 10 days

---

## ðŸ"§ Best Practices

### 1. **ความละเอียดที่เหมาะสม**
- ✅ **DO:** แบ่ง issue ให้ทำเสร็จภายใน 1-2 สัปดาห์
- ❌ **DON'T:** สร้าง issue ขนาดใหญ่ที่ใช้เวลาเป็นเดือน

### 2. **การอ้างอิง**
- ✅ **DO:** อ้างอิง section และ line numbers จาก Requirements
- ✅ **DO:** อ้างอิง section จาก FullStackJS Guidelines
- ❌ **DON'T:** Copy-paste ข้อความยาวๆ ทั้งหมด

### 3. **Acceptance Criteria**
- ✅ **DO:** เขียนเป็นข้อๆ ที่ตรวจสอบได้ (testable)
- ✅ **DO:** แยก functional และ non-functional requirements
- ❌ **DON'T:** เขียนคลุมเครือ เช่น "ระบบต้องเร็ว"

### 4. **Testing**
- ✅ **DO:** ระบุ test cases ที่ต้องเขียนชัดเจน
- ✅ **DO:** ระบุ coverage target (70% minimum)
- ❌ **DON'T:** ปล่อยให้ "เขียน test ภายหลัง"

### 5. **Security**
- ✅ **DO:** มี Security Checklist ทุก issue ที่เกี่ยวกับ user input
- ✅ **DO:** ระบุ permission ที่ต้องใช้ชัดเจน
- ❌ **DON'T:** คิดว่า "จะเพิ่ม security ทีหลัง"

---

## ðŸ"Š Issue Workflow

```mermaid
graph LR
    A[Create Issue from Req] --> B[Add Technical Specs]
    B --> C[Define Acceptance Criteria]
    C --> D[Add Testing Requirements]
    D --> E[Security Checklist]
    E --> F[Link Related Issues]
    F --> G[Assign & Estimate]
    G --> H[Ready for Development]

---

✅ สรุป: ขั้นตอนการสร้าง Issue ที่สมบูรณ์

1. ระบุ Requirement - เลือก section จาก Requirements v1.4.5
2. สร้าง Title - ใช้รูปแบบ [Module] Type: Description
3. เขียน Overview - สรุปสั้นๆ ว่าต้องทำอะไร
4. อ้างอิง Requirements - ระบุ section และ line numbers
5. กำหนด Technical Specs - แยกเป็น Backend, Frontend, Database
6. ใช้ FullStackJS Guidelines - อ้างอิง section ที่เกี่ยวข้อง
7. เขียน Acceptance Criteria - แยก functional/non-functional
8. ระบุ Testing Requirements - Unit, Integration, E2E
9. Security Checklist - ครอบคลุม OWASP Top 10
10. Link Related Issues - ระบุ dependencies และ blockers
11. เพิ่ม Labels & Assignment - ใส่ label และมอบหมายงาน
12. Estimate Effort - ประมาณการเวลาที่ใช้

---

เอกสารนี้เป็น Living Document และจะถูกปรับปรุงตามความต้องการของทีมพัฒนา