perf: 优化页面
This commit is contained in:
richarjiang
244
CARD_TYPES_INDEX.md
Normal file
244
CARD_TYPES_INDEX.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# 卡种管理 (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**:
|
||||
1. Project structure
|
||||
2. Database schema (Prisma)
|
||||
3. Shared types & DTOs
|
||||
4. Server-side implementation
|
||||
5. Frontend admin page
|
||||
6. Admin store (Pinia)
|
||||
7. Workflow flows
|
||||
8. API communication
|
||||
9. Price handling
|
||||
10. Card type categories
|
||||
11. **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"
|
||||
1. Start with **EXPLORATION_SUMMARY.md** (overview)
|
||||
2. Look at **CARD_TYPES_FLOW_DIAGRAM.txt** (visual)
|
||||
3. Dive into **CARD_TYPES_ANALYSIS.md** (details)
|
||||
|
||||
### Scenario 2: "I need to find something specific"
|
||||
→ Use **CARD_TYPES_QUICK_REFERENCE.md** (index & lookup)
|
||||
|
||||
### Scenario 3: "I need to fix the edit modal bug"
|
||||
→ 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:
|
||||
1. EXPLORATION_SUMMARY.md
|
||||
2. CARD_TYPES_FLOW_DIAGRAM.txt
|
||||
3. CARD_TYPES_QUICK_REFERENCE.md (bookmark for later)
|
||||
4. 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
|
||||
|
||||
1. **次卡 (TIMES)**: Class count-based (e.g., 10 classes) - Dark blue
|
||||
2. **月卡 (DURATION)**: Time period-based (e.g., 30 days) - Purple
|
||||
3. **体验卡 (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
|
||||
|
||||
1. **Quick start**: Read EXPLORATION_SUMMARY.md (15 min)
|
||||
2. **Deep dive**: Read CARD_TYPES_ANALYSIS.md (30 min)
|
||||
3. **Reference**: Bookmark CARD_TYPES_QUICK_REFERENCE.md
|
||||
4. **Implement bug fix** (5 min)
|
||||
5. **Test thoroughly** (15 min)
|
||||
|
||||
---
|
||||
|
||||
## 💡 Price Handling
|
||||
|
||||
**Critical**: Prices are stored as integers (cents)
|
||||
- ¥980 = 98000 cents
|
||||
- Display: formatPrice(98000) = "980.00"
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- `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
|
||||
|
||||
Reference in New Issue
Block a user