feat(player): implement unified player entity feature with core CRUD and authorization

[andrewck24]

Summary

Completes the unified Player entity refactoring as specified in specs/001-unify-player/spec.md. This PR implements the foundational infrastructure and three priority-1 user stories (US1-US3) with complete test coverage, API routes, and React components.

Completed Components

Phase 1-2: Foundational Infrastructure ✅

• Domain: Player entity with three statuses (JOINED, INVITED, PURE_PLAYER)
• Application: 6 core use cases + validation layer
• Infrastructure: Mongoose schema, repository pattern, authorization service optimization
• DI: Dependency injection container configuration

Phase 3-5: User Stories 1-3 Implementation ✅

• US1: Team manager invite members via email (CreateInvitationUseCase)
• US2: Invited users accept/reject invitations (AcceptInvitationUseCase, RejectInvitationUseCase)
• US3: View team members list (GetTeamPlayersUseCase, GetUserPlayersUseCase, GetPlayerUseCase)

API Routes ✅

GET    /api/players/{playerId}                  - Get single player info
GET    /api/players/{playerId}/status           - Get invitation status
POST   /api/players/{playerId}/status           - Accept/reject invitation
GET    /api/teams/{teamId}/players              - List team players
GET    /api/users/{userId}/players              - List user's teams

React Components ✅

• PlayerCard: Display individual player info with actions
• PlayerList: List of team players with filtering
• InvitationList: Display pending invitations
• InviteAccordion: Invite new members interface
• RoleSelect: Role selection dropdown

Key Technical Improvements

Query Optimization

• Replaced N+1 query pattern in AuthorizationService
• Direct findByTeamIdAndUserId() instead of fetch-all-then-filter

Type Safety

• Improved Mongoose schema with Schema<PlayerDocument>() type parameters
• Proper Types.ObjectId usage instead of any
• jest.Mocked<T> for test mocks

Architecture

• Clean Architecture: Domain → Application → Infrastructure → Interface → Presentation
• Repository Pattern for data access abstraction
• Dependency Injection with InversifyJS
• Use Case pattern for business logic isolation

Test Coverage

• ✅ 412 unit tests passing
• ✅ API route integration tests
• ✅ React component unit tests
• ✅ Use case tests with full mock coverage
• ✅ Entity and validation tests

Code Quality

• ✅ ESLint: No errors in invite/player/authorization scope
• ✅ TypeScript: No type errors for player files
• ✅ Build: Successful without warnings
• ✅ All imports using @/ absolute paths

Tasks Completed

• Phase 1: 3/3 setup tasks ✅
• Phase 2: 13/13 foundational tasks ✅
• Phase 3 (US1): 8/8 tasks ✅
• Phase 4 (US2): 9/9 tasks ✅
• Phase 5 (US3): 10/10 tasks ✅
• Bug fixes & optimization: 2/2 tasks ✅

Total: 57/128 tasks completed (44.5%)

Remaining tasks (71) are for US4-US7 which are not in scope for this MVP.

Breaking Changes

• Removed dependency on Team.members[] array (now queries Player entity directly)
• Removed dependency on Profile.teams array (now queries Player entity directly)
• API routes completely redesigned for new Player entity structure

Migration Path

• No data migration required in this PR (data model is additive)
• Legacy endpoints removed as per version 0.x.x guidelines (no backwards compatibility required)
• Future migration script (FR-016) will be in separate spec if needed

---

摘要

實現統一 Player 實體功能，完成 MVP 三個優先級 P1 使用者故事 (US1-US3)。

核心功能

1. 隊伍管理者邀請成員 (US1) - 透過 email 邀請使用者加入隊伍並指定角色
2. 接受/拒絕邀請 (US2) - 被邀請者可接受或拒絕邀請
3. 查看隊伍成員 (US3) - 成員列表顯示所有球員、邀請和相關資訊

技術亮點

• 查詢最佳化：移除 N+1 查詢模式
• 型別安全：完全使用 Types.ObjectId，無 any 型別
• 清潔架構：完整的分層設計和依賴注入
• 測試覆蓋：412 個單元測試全部通過

進度

• 57/128 任務完成 (44.5%)
• MVP 三個優先級 P1 故事全部實現
• 剩餘 71 個任務是 US4-US7 (P2-P3)，不在本次 MVP 範圍內

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
volleybro	Ready	Preview, Comment	Dec 20, 2025 7:52pm

[claude]

Claude finished @andrewck24's task —— View job

---

PR Review: Unified Player Entity Implementation

Comprehensive review of this large-scale Player entity refactoring implementing Clean Architecture with 3 priority user stories.

Review Checklist

• Analyze domain layer implementation
• Review application layer (use cases and repositories)
• Check infrastructure layer (database and services)
• Evaluate API routes and controllers
• Review React components and UI
• Assess test coverage and quality
• Check for security and performance issues
• Provide final recommendations

✅ Strengths & Excellent Implementation

1. Clean Architecture Excellence

• Perfect Layer Separation: Domain → Application → Infrastructure → Interface → Presentation
• SOLID Principles: Each use case has single responsibility, interfaces properly abstracted
• Dependency Injection: Excellent InversifyJS integration for testability
• Repository Pattern: Clean abstraction of data access with proper type safety

2. Type Safety & Validation

• Zod Integration: Runtime validation with compile-time type inference
• Mongoose Schema: Proper Schema<PlayerDocument>() typing eliminates any types
• Discriminated Unions: Smart status validation pattern in UpdatePlayerStatusSchema
• ObjectId Handling: Consistent string conversion in repository layer

3. State Machine Design (src/entities/player.ts)

// Clean state transitions with business logic
INVITED (email ✓, userId ✗) → JOINED (userId ✓) → PURE_PLAYER (email ✗, userId ✗)

4. Query Optimization

• Direct Lookups: findByTeamIdAndUserId() replaces N+1 patterns
• Targeted Queries: Efficient MongoDB operations avoid full collection scans
• Authorization Performance: AuthorizationService.verifyIsTeamAdmin() uses single query

5. Test Coverage Excellence

• 412 Tests Passing: Comprehensive unit test coverage
• Proper Mocking: jest.Mocked<T> for type-safe test doubles
• Use Case Testing: All business logic paths covered
• Component Testing: React Testing Library with user interactions

⚠️ Issues Requiring Attention

Critical Security Issues

1. Email Validation Insufficient (src/applications/usecases/player/create-invitation.usecase.ts:36)

// 🚨 CRITICAL: Basic email validation is insufficient
if (!email || !email.includes('@')) {
  throw new Error('Invalid email format');
}

Risk: Email injection, invalid invitations
Fix: Use proper email validation (already available in Zod schema)

2. Role Validation Gap (src/applications/usecases/player/create-invitation.usecase.ts:41)

// 🚨 CRITICAL: Missing OWNER role protection
if (!Object.values(PlayerRole).includes(role as PlayerRole)) {
  throw new Error(`Invalid role: ${role}`);
}

Risk: Team OWNER role assignment by non-owners
Fix: Add owner-only validation for OWNER role assignment

3. Database Injection Risk (src/infrastructure/db/repositories/player.repository.ts:78)

// ⚠️ MEDIUM: Direct string in MongoDB query
role: "OWNER",  // Should use enum

Performance Concerns

1. Inefficient Queries (src/infrastructure/db/repositories/player.repository.ts:94)

// 🚨 Expensive query on every invitation check
const count = await PlayerModel.countDocuments({
  teamId,
  email,
  userId: { $exists: false },
}).exec();

Impact: Unnecessary database roundtrips
Fix: Use findInvitedByTeamIdAndEmail() which already exists

2. Missing Database Indexes

• teamId + userId: Required for authorization queries
• teamId + email: Required for invitation lookups
• teamId + role: Required for admin/owner lookups

Code Quality Issues

1. Inconsistent Error Handling (src/app/api/teams/[teamId]/players/route.ts:69-84)

// 🔄 INCONSISTENT: String matching for error classification
if (error.message.includes('not admin')) {
  return NextResponse.json({ error: error.message }, { status: 403 });
}

Fix: Use custom error classes with proper status codes

2. Magic Numbers (src/lib/validations/player.ts:18)

number: z.number().int().min(0).max(99).optional(),  // Why 99?

3. Mixed Languages

• Good: Consistent Traditional Chinese in UI components
• Issue: Some comments mix English/Chinese
• API Routes: English (correct for API)

🎯 Recommendations

High Priority Fixes

1. Security: Replace basic email validation with Zod schema validation
2. Security: Add owner-only protection for OWNER role assignment
3. Performance: Add database indexes for frequent query patterns
4. Error Handling: Implement custom error classes with proper HTTP status mapping

Medium Priority Improvements

5. Performance: Remove duplicate existsInvitation() method, use existing method
6. Type Safety: Replace string literals with enum constants in repository
7. Validation: Add business rule validation (e.g., max players per team)
8. Logging: Add structured logging for audit trails

Low Priority Enhancements

9. Documentation: Add JSDoc for public methods
10. Testing: Add integration tests for API routes
11. Constants: Extract magic numbers to configuration

📊 Overall Assessment

Category	Score	Notes
Architecture	🟢 9/10	Excellent Clean Architecture implementation
Type Safety	🟢 9/10	Outstanding Zod + TypeScript integration
Performance	🟡 7/10	Good queries, needs indexes
Security	🟡 6/10	Basic validation needs improvement
Test Coverage	🟢 9/10	Comprehensive 412 tests
Code Quality	🟢 8/10	Clean, well-structured code

✅ Approval Recommendation

APPROVE WITH CONDITIONS: This is an excellent implementation of Clean Architecture with strong type safety and comprehensive testing. The identified security and performance issues should be addressed before merging to production, but they don't block the architectural foundation this PR establishes.

Critical fixes required: Email validation and role authorization security improvements.

[claude]

Claude finished @andrewck24's task —— View job

---

PR Review: Unified Player Entity Implementation

Comprehensive review of this large-scale Player entity refactoring implementing Clean Architecture with 3 priority user stories.

Review Checklist

• Analyze domain layer implementation
• Review application layer (use cases and repositories)
• Check infrastructure layer (database and services)
• Evaluate API routes and controllers
• Review React components and UI
• Assess test coverage and quality
• Check for security and performance issues
• Provide final recommendations

✅ Strengths & Excellent Implementation

1. Clean Architecture Excellence

• Perfect Layer Separation: Domain → Application → Infrastructure → Interface → Presentation
• SOLID Principles: Each use case has single responsibility, interfaces properly abstracted
• Dependency Injection: Excellent InversifyJS integration for testability
• Repository Pattern: Clean abstraction of data access with proper type safety

2. Type Safety & Validation

• Zod Integration: Runtime validation with compile-time type inference
• Mongoose Schema: Proper Schema<PlayerDocument>() typing eliminates any types
• Discriminated Unions: Smart status validation pattern in UpdatePlayerStatusSchema
• ObjectId Handling: Consistent string conversion in repository layer

3. State Machine Design (src/entities/player.ts)

// Clean state transitions with business logic
INVITED (email ✓, userId ✗) → JOINED (userId ✓) → PURE_PLAYER (email ✗, userId ✗)

4. Query Optimization

• Direct Lookups: findByTeamIdAndUserId() replaces N+1 patterns
• Targeted Queries: Efficient MongoDB operations avoid full collection scans
• Authorization Performance: AuthorizationService.verifyIsTeamAdmin() uses single query

5. Test Coverage Excellence

• 412 Tests Passing: Comprehensive unit test coverage
• Proper Mocking: jest.Mocked<T> for type-safe test doubles
• Use Case Testing: All business logic paths covered
• Component Testing: React Testing Library with user interactions

⚠️ Issues Requiring Attention

Critical Security Issues

1. Email Validation Insufficient (src/applications/usecases/player/create-invitation.usecase.ts:36)

// 🚨 CRITICAL: Basic email validation is insufficient
if (!email || !email.includes('@')) {
  throw new Error('Invalid email format');
}

Risk: Email injection, invalid invitations
Fix: Use proper email validation (already available in Zod schema)

2. Role Validation Gap (src/applications/usecases/player/create-invitation.usecase.ts:41)

// 🚨 CRITICAL: Missing OWNER role protection
if (!Object.values(PlayerRole).includes(role as PlayerRole)) {
  throw new Error(`Invalid role: ${role}`);
}

Risk: Team OWNER role assignment by non-owners
Fix: Add owner-only validation for OWNER role assignment

3. Database Injection Risk (src/infrastructure/db/repositories/player.repository.ts:78)

// ⚠️ MEDIUM: Direct string in MongoDB query
role: "OWNER",  // Should use enum

Performance Concerns

1. Inefficient Queries (src/infrastructure/db/repositories/player.repository.ts:94)

// 🚨 Expensive query on every invitation check
const count = await PlayerModel.countDocuments({
  teamId,
  email,
  userId: { $exists: false },
}).exec();

Impact: Unnecessary database roundtrips
Fix: Use findInvitedByTeamIdAndEmail() which already exists

2. Missing Database Indexes

• teamId + userId: Required for authorization queries
• teamId + email: Required for invitation lookups
• teamId + role: Required for admin/owner lookups

Code Quality Issues

1. Inconsistent Error Handling (src/app/api/teams/[teamId]/players/route.ts:69-84)

// 🔄 INCONSISTENT: String matching for error classification
if (error.message.includes('not admin')) {
  return NextResponse.json({ error: error.message }, { status: 403 });
}

Fix: Use custom error classes with proper status codes

2. Magic Numbers (src/lib/validations/player.ts:18)

number: z.number().int().min(0).max(99).optional(),  // Why 99?

3. Mixed Languages

• Good: Consistent Traditional Chinese in UI components
• Issue: Some comments mix English/Chinese
• API Routes: English (correct for API)

🎯 Recommendations

High Priority Fixes

1. Security: Replace basic email validation with Zod schema validation
2. Security: Add owner-only protection for OWNER role assignment
3. Performance: Add database indexes for frequent query patterns
4. Error Handling: Implement custom error classes with proper HTTP status mapping

Medium Priority Improvements

5. Performance: Remove duplicate existsInvitation() method, use existing method
6. Type Safety: Replace string literals with enum constants in repository
7. Validation: Add business rule validation (e.g., max players per team)
8. Logging: Add structured logging for audit trails

Low Priority Enhancements

9. Documentation: Add JSDoc for public methods
10. Testing: Add integration tests for API routes
11. Constants: Extract magic numbers to configuration

📊 Overall Assessment

Category	Score	Notes
Architecture	🟢 9/10	Excellent Clean Architecture implementation
Type Safety	🟢 9/10	Outstanding Zod + TypeScript integration
Performance	🟡 7/10	Good queries, needs indexes
Security	🟡 6/10	Basic validation needs improvement
Test Coverage	🟢 9/10	Comprehensive 412 tests
Code Quality	🟢 8/10	Clean, well-structured code

✅ Approval Recommendation

APPROVE WITH CONDITIONS: This is an excellent implementation of Clean Architecture with strong type safety and comprehensive testing. The identified security and performance issues should be addressed before merging to production, but they don't block the architectural foundation this PR establishes.

Critical fixes required: Email validation and role authorization security improvements.

---

View job