Files

richarjiang 9811c9a13b perf: 优化页面

2026-04-05 13:25:54 +08:00

6.5 KiB

Raw Blame History

卡种管理 (Card Types Management) - Documentation Index

Exploration Date: April 5, 2026
Total Files Analyzed: 13 source files (~1,800 lines)
Documentation Created: 4 comprehensive guides (1,546 lines)

📖 Documentation Files

1. EXPLORATION_SUMMARY.md ⭐ START HERE

Best for: Quick overview of the entire system and key findings

What was explored (13 files, 1,800 lines)
Documentation generated
Key findings summary
File inventory
Complete workflows
Bug identification
Next steps
Statistics

Read time: 15-20 minutes
Size: 12 KB, 428 lines

2. CARD_TYPES_QUICK_REFERENCE.md 📋 FOR LOOKUP

Best for: Quick lookup when working on the code

File quick links with line numbers
Key data model (CardType entity)
API endpoints
DTOs & validation rules
UI components structure
Form fields list
Operations guide (Add, Edit, Toggle, Delete)
React refs & state
Admin store methods
Bug explanation with 3 solutions ⚡
Price handling notes
Testing checklist
Card type categories

Read time: 10 minutes
Size: 10 KB, 342 lines

3. CARD_TYPES_ANALYSIS.md 📚 FOR DEEP DIVE

Best for: Understanding every detail of the system

11 Sections:

Project structure
Database schema (Prisma)
Shared types & DTOs
Server-side implementation
Frontend admin page
Admin store (Pinia)
Workflow flows
API communication
Price handling
Card type categories
Detailed bug analysis with root cause

Read time: 30-40 minutes
Size: 16 KB, 548 lines

4. CARD_TYPES_FLOW_DIAGRAM.txt 🎨 FOR VISUALIZATION

Best for: Understanding data flow and architecture visually

Database tier diagram
API tier diagram
Shared types tier
Frontend tier (page structure, store, state)
Complete operation flows (Add, Edit, Toggle, Delete)
Bug analysis with solutions

Read time: 20 minutes
Size: 24 KB, 228 lines (ASCII art)

🎯 How to Use This Documentation

Scenario 1: "I need to understand the whole system"

Start with EXPLORATION_SUMMARY.md (overview)
Look at CARD_TYPES_FLOW_DIAGRAM.txt (visual)
Dive into CARD_TYPES_ANALYSIS.md (details)

Scenario 2: "I need to find something specific"

→ Use CARD_TYPES_QUICK_REFERENCE.md (index & lookup)

→ Jump to CARD_TYPES_QUICK_REFERENCE.md → Section "THE BUG" or
→ Read CARD_TYPES_ANALYSIS.md → Section 11 "Detailed bug analysis"

Scenario 4: "I need to see how data flows"

→ Check CARD_TYPES_FLOW_DIAGRAM.txt

Scenario 5: "I'm new to this project"

→ Read in order:

EXPLORATION_SUMMARY.md
CARD_TYPES_FLOW_DIAGRAM.txt
CARD_TYPES_QUICK_REFERENCE.md (bookmark for later)
CARD_TYPES_ANALYSIS.md (as needed for details)

🔍 Quick File Locations

Frontend

Admin page: packages/app/src/pages/admin/card-types.vue (607 lines)
Pinia store: packages/app/src/stores/admin.ts (198 lines)

Backend

Controller: packages/server/src/membership/membership.controller.ts (68 lines)
Service: packages/server/src/membership/membership.service.ts (173 lines)
Create DTO: packages/server/src/membership/dto/create-card-type.dto.ts (45 lines)
Update DTO: packages/server/src/membership/dto/update-card-type.dto.ts (49 lines)

Database

Prisma schema: packages/server/prisma/schema.prisma (205 lines)

Shared Types

Card types: packages/shared/src/types/card-type.ts (39 lines)
Enums: packages/shared/src/enums.ts (47 lines)

⚡ The Critical Bug

What: Edit modal closes immediately when user taps [编辑] button

Why: Event propagation issue - tap event bubbles to modal-mask's @tap.self

Where to Fix: Line 67 of packages/app/src/pages/admin/card-types.vue

Simple Fix: Change @tap="openEdit(ct)" to @tap.stop="openEdit(ct)"

See Also:

CARD_TYPES_QUICK_REFERENCE.md → "THE BUG" section
CARD_TYPES_ANALYSIS.md → Section 11
CARD_TYPES_FLOW_DIAGRAM.txt → Bottom (3 solutions shown)

📊 Key Statistics

Aspect	Count
Source files analyzed	13
Total lines of code	~1,800
API endpoints	5
Card type categories	3 (TIMES, DURATION, TRIAL)
Core operations	4 (Create, Read, Update, Delete)
Documentation files	4
Documentation lines	1,546
Bugs identified	1
Bug severity	High (UX-breaking)

🎨 Card Type Categories

次卡 (TIMES): Class count-based (e.g., 10 classes) - Dark blue
月卡 (DURATION): Time period-based (e.g., 30 days) - Purple
体验卡 (TRIAL): Trial cards - Gold/tan

🔐 Auth & Security

Admin endpoints require JWT Bearer token
Admin endpoints require ADMIN role
Public endpoint (GET /membership/card-types) returns only active cards

💾 Database Details

CardType Model:

Soft delete (set isActive=false, not removed from DB)
Relationships: Membership (many), Order (many)
Indexed on: isActive, sortOrder

📝 API Endpoints

Method	Endpoint	Auth	Purpose
GET	/membership/card-types	None	Get active cards (public)
GET	/admin/card-types	JWT+Admin	Get all cards (admin)
POST	/admin/card-types	JWT+Admin	Create card
PUT	/admin/card-types/:id	JWT+Admin	Update card (can toggle isActive)
DELETE	/admin/card-types/:id	JWT+Admin	Soft delete card

🧪 Testing Checklist

Create new card with all types
Edit existing card
Toggle card status (上架/下架)
Delete card (soft delete works)
List updates after each operation
Modal closes after submit
FIX: Edit modal stays open (not closes immediately)

🚀 Next Steps

Quick start: Read EXPLORATION_SUMMARY.md (15 min)
Deep dive: Read CARD_TYPES_ANALYSIS.md (30 min)
Reference: Bookmark CARD_TYPES_QUICK_REFERENCE.md
Implement bug fix (5 min)
Test thoroughly (15 min)

💡 Price Handling

Critical: Prices are stored as integers (cents)

¥980 = 98000 cents
Display: formatPrice(98000) = "980.00"

ADMIN_SCHEDULING_EXPLORATION.md - Scheduling feature
BOOKING_ARCHITECTURE_DIAGRAM.md - Booking system
BOOKING_PAGE_ANALYSIS.md - Booking pages
SCHEDULING_QUICK_REFERENCE.md - Scheduling reference

Generated: 2026-04-05
Ready to: Implement features, fix bugs, deploy updates

6.5 KiB Raw Blame History