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

{
  "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

-- 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

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

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

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