b6986ba30c
## Features ### Admin Schedule Page (`packages/app/src/pages/admin/schedule.vue`) - Interactive date-based slot editor for managing daily schedules - Real-time slot editing: start/end times, capacity adjustments - Slot deletion with conflict warnings when bookings exist - Add new slots with modal dialog - Live booking status display (booked count, people names) - Publish/Save changes with sync feedback - Revert unsaved changes with confirmation - Skeleton loading states and empty state handling - Responsive design with optimized mobile UX ### Backend Enhancements - **New DTO** (`PublishDaySlotsDto`): Structured slot publishing with validation - Date string validation - Slot array with existing slot IDs for updates - Time and capacity validation per slot - **Schedule Preview API** (`getSchedulePreview`): - Check for existing published slots - Fallback to active WeekTemplates for unpublished dates - Unified response format with isPublished flag - **Publish Slots API** (`publishDaySlots`): - Atomic transaction for consistency - Update existing slots with new times/capacity - Create new slots from template data - Delete unpublished slots or set to CLOSED if bookings exist - Prevent capacity reduction below existing bookings - Returns all published slots for feedback ### State Management - Enhanced admin store with schedule state - Support for pending/unsaved slot changes - Optimistic UI updates with server sync ### Documentation - Comprehensive scheduling system architecture docs - Quick reference for admin workflows - Flow diagrams and state transitions - Implementation guide for future maintenance ## Breaking Changes None ## Testing Recommendations - Create slots for future dates via schedule editor - Verify booking prevention for locked/full slots - Test capacity adjustments with existing bookings - Confirm template-based schedule generation - Verify transaction rollback on publish failures Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
245 lines
8.3 KiB
Markdown
245 lines
8.3 KiB
Markdown
# 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
|
|
|
|
- [x] All 3 documentation files created
|
|
- [x] 803 + 271 + 296 = 1,370 lines of documentation
|
|
- [x] Complete file paths documented
|
|
- [x] API endpoints listed with examples
|
|
- [x] Data flow diagrams included
|
|
- [x] Common gotchas documented
|
|
- [x] Usage examples provided
|
|
- [x] Scalability notes included
|
|
- [x] Permission model explained
|
|
- [x] Timezone handling noted
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-04-05
|
|
**Status**: Complete and ready for reference
|
|
|