# 🚀 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**

```markdown
## 📋 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:**

```markdown
## 📋 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`

````markdown
## ðŸ'» 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:**

  ```json
  {
    "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**

```markdown
## 🧪 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**

```markdown
## 🔒 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

````markdown
## 📋 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]

   ```typescript
   @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:**

```json
{
  "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]

```typescript
// 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

```sql
-- 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]

```typescript
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]

```typescript
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]

```typescript
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:**

  - #<issue> FileStorageService implementation
  - #<issue> WorkflowEngine implementation
  - #<issue> DocumentNumberingService implementation

- **Blocks:**

  - #<issue> RFA Response/Approval workflow
  - #<issue> RFA Reports and Analytics

- **Related to:**
  - #<issue> Shop Drawing reference system
  - #<issue> 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 และจะถูกปรับปรุงตามความต้องการของทีมพัฒนา**