# TÀI LIỆU SPEC: ỨNG DỤNG VIẾT TRUYỆN AI

### **StoryForge AI - Technical Specification**

***

### 1. TỔNG QUAN HỆ THỐNG

#### 1.1 Mục tiêu

Xây dựng ứng dụng web cho phép người dùng tải lên file outline truyện (PDF/Word/TXT), AI phân tích và viết thành truyện hoàn chỉnh theo các thể loại tùy chọn.

#### 1.2 Người dùng mục tiêu

* Nhà văn mới cần hỗ trợ viết truyện
* Content creator cần sản xuất nội dung nhanh
* Người có ý tưởng nhưng chưa biết cách triển khai

***

### 2. CHỨC NĂNG CHÍNH

#### 2.1 Module Upload & Phân tích Outline

Table Copy

| Chức năng              | Mô tả                                                   | Input          | Output                |
| ---------------------- | ------------------------------------------------------- | -------------- | --------------------- |
| **File Upload**        | Hỗ trợ PDF, DOCX, TXT                                   | File outline   | Text trích xuất       |
| **Structure Parser**   | Phân tích cấu trúc outline                              | Raw text       | JSON cấu trúc         |
| **Content Classifier** | Phát hiện thể loại, độ tuổi, cảnh báo nội dung nhạy cảm | Parsed content | Tags + Content Rating |

**Cấu trúc JSON sau khi parse:**

JSON Copy

```json
{
  "metadata": {
    "title": "Y tá nhỏ của tôi",
    "tagline": "Em 20, lần đầu biết yêu...",
    "genre_detected": ["romance", "drama", "medical"],
    "content_rating": "R-18",
    "warning_flags": ["explicit_sexual_content", "age_gap_relationship"]
  },
  "characters": [
    {
      "name": "Trinh",
      "age": 20,
      "role": "protagonist",
      "occupation": "y tá",
      "traits": ["ngây thơ", "xinh đẹp", "mới ra trường"],
      "physical_description": "dáng thanh mảnh, da trắng hồng..."
    }
  ],
  "chapters": [
    {
      "chapter_number": 1,
      "title": "Cô gái nhỏ vào khoa Ngoại",
      "setting": "Bệnh viện tỉnh, khoa Ngoại",
      "key_scenes": [
        {
          "scene_id": "1.1",
          "location": "phòng thay đồ",
          "characters": ["Trinh"],
          "action": "Trinh chuẩn bị đi làm ngày đầu tiên",
          "sensory_details": ["đồng phục xanh nhạt", "áo blouse trắng"],
          "emotional_tone": "hồi hộp, tự tin"
        }
      ]
    }
  ],
  "sensory_elements": {
    "visual": ["màu xanh nhạt", "ánh mắt sâu thẳm"],
    "auditory": ["tiếng mưa rơi", "tiếng giường kêu"],
    "tactile": ["da mịn như lụa", "bàn tay khô ráp"],
    "olfactory": ["mùi bạc hà", "mùi thuốc sát trùng"]
  }
}
```

***

#### 2.2 Module AI Writing Engine

**2.2.1 Content Policy Filter**

plain Copy

```
┌─────────────────────────────────────────┐
│         INPUT: Parsed Outline           │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│    CONTENT SAFETY CLASSIFIER            │
│  • Detect sexual content level          │
│  • Detect violence, sensitive themes  │
│  • Assign content rating                │
└─────────────────┬───────────────────────┘
                  ▼
        ┌─────────┴─────────┐
        ▼                   ▼
   [SAFE CONTENT]      [EXPLICIT CONTENT]
        │                   │
        ▼                   ▼
┌───────────────┐    ┌──────────────────┐
│ Direct Writing│    │ Reframe Options  │
│               │    │ • Romance (fade  │
│               │    │   to black)      │
│               │    │ • Drama (focus   │
│               │    │   on emotion)    │
│               │    │ • Skip scene     │
└───────────────┘    └──────────────────┘
```

**2.2.2 Writing Modes**

Table Copy

| Mode               | Mô tả                             | Phù hợp với            |
| ------------------ | --------------------------------- | ---------------------- |
| **Romance-Pure**   | Tình cảm sâu sắc, không cảnh nóng | Người đọc mọi lứa tuổi |
| **Romance-Steamy** | Gợi cảm nhẹ, ngụ ý                | Người trưởng thành     |
| **Drama**          | Xung đột, phát triển nhân vật     | Thích truyện chiều sâu |
| **Rom-Com**        | Hài hước, nhẹ nhàng               | Giải trí               |
| **Thriller**       | Căng thẳng, bí ẩn                 | Truyện trinh thám      |
| **Slice of Life**  | Đời thường, chậm rãi              | Thư giãn               |

**2.2.3 Scene Rewriting Rules (cho nội dung nhạy cảm)**

**Ví dụ chuyển đổi từ outline gốc:**Table Copy

| Gốc (Explicit)                       | Romance-Pure                                                                                                        | Drama                                                                                    |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| "Cảnh nóng trong phòng trực đêm mưa" | "Khoảnh khắc gần gũi đầu tiên - họ trao nhau nụ hôn dưới ánh đèn khẩn cấp, tình cảm vượt qua ranh giới bác sĩ-y tá" | "Xung đột nội tâm của An khi rung động trước đồng nghiệp trẻ, sự cô đơn sau ca trực dài" |
| "Tay chạm vào vòng một"              | "Ánh mắt dừng lại ở nơi anh không nên nhìn, cả hai đều biết điều gì đang thay đổi"                                  | "Sự chạm va vô tình khiến An nhận ra mình đã lâu không gần gũi ai"                       |

***

#### 2.3 Module Output & Export

Table Copy

| Format         | Mô tả                  | Tùy chọn              |
| -------------- | ---------------------- | --------------------- |
| **Web Reader** | Đọc trực tiếp trên app | Font, theme, bookmark |
| **EPUB**       | Ebook chuẩn            | Cover, metadata       |
| **PDF**        | In ấn                  | Layout A4/A5          |
| **DOCX**       | Chỉnh sửa tiếp         | Track changes         |
| **Audio**      | Text-to-speech         | Voice selection       |

***

### 3. KIẾN TRÚC KỸ THUẬT

#### 3.1 Tech Stack

plain Copy

```
┌─────────────────────────────────────────┐
│           FRONTEND (Next.js)            │
│  • React 18 + TypeScript                │
│  • TailwindCSS + shadcn/ui              │
│  • React Query (state management)         │
│  • React Hook Form + Zod (validation)   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           BACKEND (Node.js)             │
│  • Fastify / Express                    │
│  • Prisma ORM + PostgreSQL              │
│  • Redis (caching)                      │
│  • BullMQ (job queue)                   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           AI SERVICES                 │
│  • OpenAI GPT-4 / Claude / Gemini     │
│  • Fine-tuned model for Vietnamese    │
│  • Content moderation API             │
│  • Vector DB (Pinecone) for RAG       │
└─────────────────────────────────────────┘
```

#### 3.2 Database Schema

sql Copy

```sql
-- Users
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE,
    subscription_tier ENUM('free', 'pro', 'enterprise'),
    created_at TIMESTAMP
);

-- Projects
CREATE TABLE projects (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    title VARCHAR(255),
    original_outline TEXT,
    parsed_structure JSONB,
    content_rating VARCHAR(50),
    selected_mode VARCHAR(50),
    status ENUM('parsing', 'writing', 'review', 'completed'),
    created_at TIMESTAMP
);

-- Chapters
CREATE TABLE chapters (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    chapter_number INT,
    title VARCHAR(255),
    outline_summary TEXT,
    generated_content TEXT,
    word_count INT,
    ai_model VARCHAR(50),
    generation_params JSONB
);

-- Content Safety Logs
CREATE TABLE safety_logs (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    detected_flag VARCHAR(100),
    severity ENUM('low', 'medium', 'high', 'critical'),
    original_snippet TEXT,
    rewritten_snippet TEXT,
    user_approved BOOLEAN
);
```

***

### 4. API ENDPOINTS

#### 4.1 Core APIs

Table Copy

| Method | Endpoint                       | Description       | Request                  | Response               |
| ------ | ------------------------------ | ----------------- | ------------------------ | ---------------------- |
| POST   | `/api/projects`                | Tạo project mới   | `{file, title}`          | `{project_id, status}` |
| GET    | `/api/projects/:id/parse`      | Lấy kết quả parse | -                        | Parsed JSON            |
| POST   | `/api/projects/:id/write`      | Bắt đầu viết      | `{mode, options}`        | `{job_id}`             |
| GET    | `/api/jobs/:id/status`         | Check tiến độ     | -                        | `{status, progress}`   |
| GET    | `/api/chapters/:id`            | Lấy chapter       | -                        | Full content           |
| POST   | `/api/chapters/:id/regenerate` | Viết lại scene    | `{scene_id, new_prompt}` | New content            |

#### 4.2 WebSocket Events

JavaScript Copy

```javascript
// Real-time writing progress
socket.emit('subscribe', { project_id: 'xxx' });

socket.on('chapter_progress', (data) => {
  // { chapter: 3, total: 20, status: 'writing', word_count: 1500 }
});

socket.on('content_warning', (data) => {
  // { scene_id: '5.2', flag: 'explicit_content', options: [...] }
});
```

***

### 5. PROMPT ENGINEERING

#### 5.1 System Prompt Template

Python Copy

```python
VIETNAMESE_STORY_WRITER = """
Bạn là nhà văn chuyên nghiệp viết truyện tiếng Việt. Nhiệm vụ: Viết truyện dựa trên outline được cung cấp.

QUY TẮC TUYỆT ĐỐI:
1. KHÔNG viết nội dung khiêu dâm, tình dục rõ ràng, bạo lực cực đoan
2. KHÔNG mô tả chi tiết cơ thể nhạy cảm với mục đích kích thích
3. KHÔNG viết về quan hệ tình dục dù bằng ngôn ngữ ẩn dụ hay trực tiếp
4. Có thể viết về tình yêu, rung động, hôn nhẹ nhàng nếu phù hợp mode

MODE VIẾT: {writing_mode}

HƯỚNG DẪN THEO MODE:
- romance-pure: Tập trung cảm xúc, nội tâm, ngụ ý. Cảnh thân mật = nụ hôn, ôm ấp, lời yêu thương
- drama: Xung đột, phát triển nhân vật, đối thoại sâu sắc
- rom-com: Tình huống hài hước, nhịp điệu nhanh, dialog witty

NGÔN NGỮ: Tiếng Việt phong phú, câu văn uyển chuyển, miêu tả giác quan (thị giác, thính giác, xúc giác, khứu giác) thay vì mô tả cơ thể.

CẤU TRÚC CHAPTER:
1. Mở đầu: Bối cảnh, không khí
2. Diễn biến: Hành động, đối thoại, cảm xúc nhân vật
3. Cao trào: Khoảnh khắc quan trọng (theo mode)
4. Kết: Chuyển tiếp hoặc kết thúc chapter

OUTLINE CHAPTER CẦN VIẾT:
{chapter_outline}

VIẾT {word_count} TỪ CHO CHAPTER NÀY.
"""
```

#### 5.2 Scene Transformation Prompt

Python Copy

```python
TRANSFORM_EXPLICIT_SCENE = """
Cảnh gốc chứa nội dung nhạy cảm. Chuyển đổi sang phiên bản {target_mode}:

NGUYÊN TẮC CHUYỂN ĐỔI:
1. Giữ nguyên ý nghĩa cảm xúc (rung động, gần gũi, xung đột)
2. Thay thế hành động thân mật bằng:
   - Ánh mắt, biểu cảm
   - Lời nói chưa nói hết
   - Không gian im lặng đầy ý nghĩa
   - Hành động tượng trưng (nắm tay, chạm má, ôm nhẹ)
3. Tăng cường nội tâm: suy nghĩ, giằng xé, khao khát nhưng kiềm chế

VÍ DỤ:
- "Tay anh chạm vào..." → "Ánh mắt anh dừng lại nơi không nên, cả hai đều nghe tiếng tim mình"
- "Họ làm tình trong phòng trực" → "Họ trao nhau nụ hôn đầu tiên dưới ánh đèn khẩn cấp, bên ngoài mưa rơi không ngớt"

CẢNH CẦN CHUYỂN ĐỔI:
{original_scene}

VIẾT LẠI:
"""
```

***

### 6. GIAO DIỆN NGƯỜI DÙNG

#### 6.1 Wireframes

plain Copy

```
┌─────────────────────────────────────────────────────────┐
│  [Logo]  Dashboard | My Stories | Templates | Settings   [User] │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────┐  ┌─────────────────────────────┐   │
│  │  UPLOAD OUTLINE │  │      PROJECT SETTINGS       │   │
│  │                 │  │                             │   │
│  │  [Drop zone]    │  │  Title: _________________     │   │
│  │  PDF/DOCX/TXT   │  │                             │   │
│  │                 │  │  Writing Mode:              │   │
│  │  [Upload btn]   │  │  ○ Romance-Pure             │   │
│  │                 │  │  ○ Drama                    │   │
│  │  Preview:       │  │  ○ Rom-Com                  │   │
│  │  ┌─────────┐    │  │  ○ Thriller                 │   │
│  │  │Parsed   │    │  │                             │   │
│  │  │Structure│    │  │  Target Length: [___] words │   │
│  │  └─────────┘    │  │                             │   │
│  │                 │  │  [Start Writing →]            │   │
│  └─────────────────┘  └─────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │              WRITING PROGRESS                     │    │
│  │  ████████████████████░░░░░  Chapter 8/20         │    │
│  │  Current: "Cơn mưa đầu mùa" - 1,850 words       │    │
│  │  ETA: 12 minutes remaining                        │    │
│  │                                                 │    │
│  │  [⚠️ Content Warning] Scene 5.2 requires review   │    │
│  │      [Review & Approve] [Auto-rewrite]          │    │
│  └─────────────────────────────────────────────────┘    │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

#### 6.2 Chapter Editor View

plain Copy

```
┌─────────────────────────────────────────────────────────┐
│  ← Back to Project    Chapter 5: Những rung động...    [✓] │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────────────────────────┐   │
│  │   OUTLINE   │  │      GENERATED CONTENT           │   │
│  │             │  │                                  │   │
│  │ Scene 5.1   │  │  Mưa bất chợt đổ xuống chiều    │   │
│  │ ━━━━━━━━━━  │  │  hôm ấy. Trinh đứng dưới mái    │   │
│  │ Scene 5.2 ⚠️│  │  hiên nhỏ của bệnh viện, nhìn   │   │
│  │ ━━━━━━━━━━  │  │  những hạt mưa bay ngang...     │   │
│  │ Scene 5.3   │  │                                  │   │
│  │             │  │  [Edit with AI]                  │   │
│  │             │  │  [Regenerate] [Change Tone]      │   │
│  │             │  │                                  │   │
│  │             │  │  Word count: 2,340 | Read time:  │   │
│  │             │  │  12 min                          │   │
│  └─────────────┘  └──────────────────────────────────┘   │
│                                                         │
│  [◀ Prev]  [Save Draft]  [Export]  [Next ▶]             │
└─────────────────────────────────────────────────────────┘
```

***

### 7. CONTENT SAFETY SYSTEM

#### 7.1 Detection Categories

Table Copy

| Category            | Description                       | Action                  |
| ------------------- | --------------------------------- | ----------------------- |
| **Explicit Sexual** | Mô tả chi tiết hành vi tình dục   | Block + Suggest rewrite |
| **Suggestive**      | Ngụ ý tình dục rõ ràng            | Flag + User review      |
| **Violence**        | Bạo lực cực đoan, tra tấn         | Block                   |
| **Age Gap**         | Quan hệ chênh lệch tuổi (>10 năm) | Warning label           |
| **Power Imbalance** | Sếp-nhân viên, bác sĩ-bệnh nhân   | Ethical review          |

#### 7.2 User Control Flow

plain Copy

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Upload    │────▶│   Parse     │────▶│   Detect    │
│   Outline   │     │  Structure  │     │   Flags     │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                          ┌────────────────────┼────────────────────┐
                          │                    │                    │
                          ▼                    ▼                    ▼
                    ┌─────────┐          ┌─────────┐           ┌─────────┐
                    │  SAFE   │          │ WARNING │           │ BLOCKED │
                    │         │          │         │           │         │
                    │ Continue│          │ Options:│           │ Must    │
                    │ writing │          │ • Rewrite│          │ modify  │
                    │         │          │ • Skip   │           │ outline │
                    │         │          │ • Manual │           │         │
                    └─────────┘          │   edit   │           └─────────┘
                                         └─────────┘
```

***

### 8. MONETIZATION & LIMITS

Table Copy

| Tier           | Price     | Features                                                          |
| -------------- | --------- | ----------------------------------------------------------------- |
| **Free**       | $0        | 3 projects/month, 5k words/project, basic modes                   |
| **Pro**        | $9.99/mo  | Unlimited projects, 50k words/project, all modes, export EPUB/PDF |
| **Enterprise** | $49.99/mo | API access, custom fine-tuning, white-label, priority support     |

***

### 9. IMPLEMENTATION ROADMAP

Table Copy

| Phase    | Duration | Deliverables                                                        |
| -------- | -------- | ------------------------------------------------------------------- |
| **MVP**  | 6 weeks  | Upload, parse, basic writing (romance-pure, drama), web reader      |
| **v1.0** | +4 weeks | All modes, export formats, payment integration                      |
| **v1.5** | +6 weeks | Collaborative editing, AI image generation for covers, audio export |
| **v2.0** | +8 weeks | Mobile app, community features, publishing to platform              |

***

### 10. RISK MITIGATION

Table Copy

| Risk                                    | Mitigation                                                                |
| --------------------------------------- | ------------------------------------------------------------------------- |
| AI generates inappropriate content      | Multi-layer filtering: model-level + post-processing + human review queue |
| Copyright issues with uploaded outlines | Terms of service: user retains rights, we claim license to process        |
| Vietnamese language quality             | Fine-tune on Vietnamese literature corpus, human-in-the-loop validation   |
| Content policy violations               | Strict safety system, user education, clear guidelines                    |

***

Bạn cần tôi mở rộng phần nào? Ví dụ:

* Chi tiết kỹ thuật AI/ML pipeline
* API documentation đầy đủ
* Database schema chi tiết hơn
* UI/UX mockup chi tiết