mp-pilates/SCHEDULING_DOCUMENTATION_INDEX.md

WeChat Mini-Program Admin Scheduling - Documentation Index

Created: 2026-04-05
Project: mp-pilates (Pilates Studio Booking System)

---

📚 Documentation Files

This exploration contains 3 comprehensive documents about the admin scheduling/排课设置 system:

1. ADMIN_SCHEDULING_EXPLORATION.md (24 KB, 803 lines)

Purpose: Complete deep-dive into the scheduling system

Sections:

• Executive Summary
• File Structure (frontend, backend, shared)
• 4 Key Components (Admin Dashboard, Week Templates, Slot Adjustment, Admin Store)
• Backend Architecture (Controllers, Services, Slot Generator)
• Data Flow & User Journey
• Constants & Utilities
• Permission Model
• Implementation Status
• Edge Cases
• UI Design Patterns
• Deployment & Configuration

Best for: Understanding the complete architecture and how everything connects

---

2. SCHEDULING_FLOW_DIAGRAM.md (13 KB, 271 lines)

Purpose: Visual flowcharts and architecture diagrams

Sections:

• Component Architecture (visual tree)
• Data Flow: Template → Slots (visual flowchart)
• State Management breakdown
• API Endpoints Summary
• Entity Relationships (ER diagram)
• Weekday Mapping (ISO vs JS conversion)
• Timeline Example (realistic scenario)

Best for: Quick visual understanding of the flow and architecture

---

3. SCHEDULING_QUICK_REFERENCE.md (7.9 KB, 296 lines)

Purpose: Quick lookup guide for developers

Sections:

• Quick Links to Key Files (with line numbers)
• The Flow in 30 Seconds
• Core Entities (WeekTemplate, TimeSlot)
• API Endpoints (with JSON examples)
• UI State Management
• Permissions & Auth
• Important Constants
• Common Gotchas (5 key points)
• Usage Example (step-by-step)
• Related Components
• Scalability Notes

Best for: Developers jumping into the code for the first time

---

🎯 Choose Your Path

If you want to...

Understand the big picture
→ Read: SCHEDULING_FLOW_DIAGRAM.md
→ Then: ADMIN_SCHEDULING_EXPLORATION.md (section 2)

Start coding immediately
→ Read: SCHEDULING_QUICK_REFERENCE.md
→ Then: Jump to specific file links

Debug a specific issue
→ Read: SCHEDULING_QUICK_REFERENCE.md (Common Gotchas)
→ Then: Search in ADMIN_SCHEDULING_EXPLORATION.md

Understand data flow
→ Read: SCHEDULING_FLOW_DIAGRAM.md (Data Flow section)
→ Then: ADMIN_SCHEDULING_EXPLORATION.md (section 7: Data Flow)

---

🔑 Key Files by Role

Frontend Developer

Must Read:

• SCHEDULING_QUICK_REFERENCE.md → UI State Management
• packages/app/src/pages/admin/week-template.vue (500 lines)
• packages/app/src/pages/admin/slot-adjust.vue (428 lines)
• packages/app/src/stores/admin.ts (171 lines)

Backend Developer

Must Read:

• SCHEDULING_QUICK_REFERENCE.md → API Endpoints
• packages/server/src/time-slot/time-slot.controller.ts
• packages/server/src/time-slot/slot-generator.service.ts
• packages/server/src/time-slot/time-slot.service.ts

Full-Stack Developer

Must Read: All documentation files in order:

1. SCHEDULING_QUICK_REFERENCE.md (5 min)
2. SCHEDULING_FLOW_DIAGRAM.md (10 min)
3. ADMIN_SCHEDULING_EXPLORATION.md (20 min)

---

🎓 Learning Timeline

Day 1: Orientation (30 minutes)

• Read: SCHEDULING_QUICK_REFERENCE.md section "The Flow: In 30 Seconds"
• Skim: SCHEDULING_FLOW_DIAGRAM.md

Day 2: Deep Dive (1-2 hours)

• Read: SCHEDULING_FLOW_DIAGRAM.md (entire)
• Read: ADMIN_SCHEDULING_EXPLORATION.md (sections 1-3)

Day 3: Implementation (ongoing)

• Refer to: SCHEDULING_QUICK_REFERENCE.md as needed
• Cross-reference: ADMIN_SCHEDULING_EXPLORATION.md sections 4-8
• Check: Backend/Frontend specific sections

---

🔗 File Paths: Quick Lookup

Component	Path	Lines
Admin Dashboard	packages/app/src/pages/admin/index.vue	177
Week Templates	packages/app/src/pages/admin/week-template.vue	500 ⭐
Slot Adjustment	packages/app/src/pages/admin/slot-adjust.vue	428
Admin Store	packages/app/src/stores/admin.ts	171
API Controller	packages/server/src/time-slot/time-slot.controller.ts	92
API Service	packages/server/src/time-slot/time-slot.service.ts	142
Slot Generator	packages/server/src/time-slot/slot-generator.service.ts	172
Types: Templates	packages/shared/src/types/week-template.ts	19
Types: Slots	packages/shared/src/types/time-slot.ts	30
Constants	packages/shared/src/constants.ts	22
Utilities	packages/app/src/utils/format.ts	47

⭐ = Main scheduling component (排课设置)

---

📊 System Overview

┌─────────────────────────────────────────────────────────┐
│              ADMIN SCHEDULING SYSTEM                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Frontend (Vue 3 + TypeScript)                          │
│  ├─ week-template.vue (templates CRUD)                 │
│  ├─ slot-adjust.vue (manual operations)                │
│  └─ admin.ts (Pinia store)                             │
│                                                          │
│  Backend (NestJS + Prisma)                             │
│  ├─ time-slot.controller.ts (API routes)              │
│  ├─ time-slot.service.ts (business logic)             │
│  └─ slot-generator.service.ts (auto-generation)       │
│                                                          │
│  Database (PostgreSQL/MySQL)                           │
│  ├─ WeekTemplate (recurring schedule rules)            │
│  ├─ TimeSlot (actual bookable slots)                   │
│  └─ Booking (user reservations)                        │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

🚀 Quick Start Checklist

• Read SCHEDULING_QUICK_REFERENCE.md (5 min)
• Skim SCHEDULING_FLOW_DIAGRAM.md (5 min)
• Open packages/app/src/pages/admin/week-template.vue
• Open packages/server/src/time-slot/slot-generator.service.ts
• Bookmark this index file for reference
• Ask questions about specific sections in the docs

---

📝 Terms & Definitions

Term	Definition
WeekTemplate	Recurring schedule rule (e.g., "every Monday 9-10 AM")
TimeSlot	Actual bookable time (e.g., "Monday, April 6, 9-10 AM")
排课设置	Schedule setup (admin template management)
临时调整	Temporary adjustments (manual slot operations)
isDirty	Flag indicating unsaved changes
Atomic	All-or-nothing database transaction
skipDuplicates	Prisma option to ignore duplicate records on batch insert
ISO Weekday	1=Monday, 2=Tuesday, ..., 7=Sunday

---

🆘 Getting Help

Question Type → Documentation

"How does admin add a new class?"
→ SCHEDULING_QUICK_REFERENCE.md → Usage Example

"What API endpoints exist?"
→ SCHEDULING_QUICK_REFERENCE.md → API Endpoints
→ OR ADMIN_SCHEDULING_EXPLORATION.md → Backend Architecture

"How do templates become slots?"
→ SCHEDULING_FLOW_DIAGRAM.md → Data Flow section

"What database schema?"
→ SCHEDULING_QUICK_REFERENCE.md → Core Entities
→ OR SCHEDULING_FLOW_DIAGRAM.md → Entity Relationships

"Where does X file?"
→ SCHEDULING_QUICK_REFERENCE.md → File Paths lookup table

---

✅ Verification Checklist

• All 3 documentation files created
• 803 + 271 + 296 = 1,370 lines of documentation
• Complete file paths documented
• API endpoints listed with examples
• Data flow diagrams included
• Common gotchas documented
• Usage examples provided
• Scalability notes included
• Permission model explained
• Timezone handling noted

---

Last Updated: 2026-04-05
Status: Complete and ready for reference