# 卡种管理 (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