outsource/appointment_system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d5a0824f20
appointment_system/.kiro/specs/admin-system-comprehensive-test/design.md
18631081161 7cf63cfad0 1
2025-12-11 22:50:18 +08:00

730 lines
26 KiB
Markdown
Raw Blame History

# Design Document
## Overview
This document outlines the comprehensive testing strategy for the overseas appointment backend admin management system. The testing approach combines automated integration tests, property-based tests, and manual testing procedures to ensure all admin functionalities work correctly and securely.
The admin system consists of multiple modules:
- Authentication and RBAC
- User management
- Appointment management
- Withdrawal review
- Service and category management
- Statistics dashboard
- System configuration
- Home content management
- Translation management
- File upload
- Security and validation
## Architecture
### Testing Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Test Suite │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Integration │ │ Property-Based │ │
│ │ Tests │ │ Tests │ │
│ │ (Jest+Supertest)│ │ (fast-check) │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Test Database │ │
│ │ (MySQL) │ │
│ └─────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Manual Test Procedures │ │
│ │ (Documented test cases) │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### Test Data Management
- Use test database with isolated data
- Create test fixtures for admins with different roles
- Generate random test data using fast-check generators
- Clean up test data after each test suite
## Components and Interfaces
### Test Utilities
**AdminTestHelper**
- Purpose: Helper functions for admin testing
- Methods:
- `createTestAdmin(role, status)`: Create test admin account
- `loginAsAdmin(username, password)`: Login and get token
- `makeAuthenticatedRequest(token, method, path, data)`: Make authenticated API call
- `cleanupTestData()`: Remove test data
**DataGenerators**
- Purpose: Generate random test data using fast-check
- Generators:
- `adminCredentials()`: Generate valid admin credentials
- `userSearchCriteria()`: Generate user search parameters
- `appointmentData()`: Generate appointment test data
- `serviceData()`: Generate service with translations
- `dateRange()`: Generate valid date ranges
**ResponseValidator**
- Purpose: Validate API response formats
- Methods:
- `validateSuccessResponse(response)`: Check success response structure
- `validateErrorResponse(response, expectedCode)`: Check error response
- `validatePaginationResponse(response)`: Check pagination structure
### Test Suites
**Authentication Test Suite**
- Tests admin login flow
- Validates JWT token generation
- Checks login history recording
- Verifies token validation
**RBAC Test Suite**
- Tests role-based access control
- Validates permission boundaries
- Checks role hierarchy
**CRUD Test Suites** (for each resource)
- User management tests
- Appointment management tests
- Withdrawal management tests
- Service management tests
- Category management tests
- Configuration management tests
- Home content management tests
**Integration Test Suites**
- End-to-end workflows
- Cross-module interactions
- Data consistency checks
## Data Models
### Test Admin Model
```javascript
{
id: UUID,
username: string,
password: string (hashed),
email: string,
role: 'super_admin' | 'admin' | 'operator',
status: 'active' | 'inactive',
createdAt: timestamp,
updatedAt: timestamp,
lastLoginAt: timestamp
}
```
### Test Response Format
```javascript
// Success Response
{
success: true,
data: {
// Response data
},
meta: {
// Optional metadata (pagination, etc.)
}
}
// Error Response
{
success: false,
error: {
code: string,
message: string,
details: object (optional)
}
}
```
## Correctness Properties
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
### Authentication Properties
Property 1: Valid login returns token and profile
*For any* valid admin credentials, logging in should return a JWT token and admin profile without the password field
**Validates: Requirements 1.1**
Property 2: Invalid credentials are rejected
*For any* invalid credentials (wrong username, wrong password, or both), login attempts should be rejected with error code INVALID_CREDENTIALS
**Validates: Requirements 1.2**
Property 3: Login creates history record
*For any* successful admin login, a login history record should be created with timestamp, IP address, and user agent
**Validates: Requirements 1.4**
Property 4: Valid tokens grant access
*For any* valid admin JWT token, requests to protected endpoints should be granted access
**Validates: Requirements 1.5**
Property 5: Invalid tokens are rejected
*For any* invalid or malformed JWT token, requests should be rejected with error code INVALID_TOKEN
**Validates: Requirements 1.6**
### RBAC Properties
Property 6: Super admin has full access
*For any* endpoint in the system, a super_admin token should grant access
**Validates: Requirements 2.1**
Property 7: Admin inherits operator permissions
*For any* operator-level endpoint, an admin token should grant access
**Validates: Requirements 2.2**
Property 8: Admin cannot access super admin endpoints
*For any* super_admin-only endpoint, an admin token should be rejected with error code FORBIDDEN
**Validates: Requirements 2.3**
Property 9: Operator has limited access
*For any* operator-level endpoint, an operator token should grant access
**Validates: Requirements 2.4**
Property 10: Operator cannot escalate privileges
*For any* admin or super_admin endpoint, an operator token should be rejected with error code FORBIDDEN
**Validates: Requirements 2.5**
### User Management Properties
Property 11: Pagination returns correct counts
*For any* page number and page size, the user list should return the correct subset of users and accurate total count
**Validates: Requirements 3.1**
Property 12: Search returns only matching users
*For any* search criteria, all returned users should match the search parameters
**Validates: Requirements 3.2**
Property 13: User status updates persist
*For any* user and status value, updating the status then retrieving the user should reflect the new status
**Validates: Requirements 3.3**
Property 14: User details are complete
*For any* user ID, the user details response should include all required fields including appointments and invitations
**Validates: Requirements 3.4**
Property 15: Date filtering is accurate
*For any* date range, all returned users should have creation dates within that range
**Validates: Requirements 3.5**
### Appointment Management Properties
Property 16: Appointments include related data
*For any* appointment list request, all appointments should include user and service details
**Validates: Requirements 4.1**
Property 17: Status filtering works correctly
*For any* appointment status, filtering by that status should return only appointments with that status
**Validates: Requirements 4.2**
Property 18: Appointment status updates persist
*For any* appointment and status value, updating the status then retrieving the appointment should reflect the new status and updated timestamp
**Validates: Requirements 4.3**
Property 19: Appointment search returns matches
*For any* search query (user or service), all returned appointments should match the search criteria
**Validates: Requirements 4.4**
Property 20: Appointment details are complete
*For any* appointment ID, the details response should include all required appointment information
**Validates: Requirements 4.5**
### Withdrawal Management Properties
Property 21: Pending filter returns only pending
*For any* withdrawal list filtered by pending status, all returned withdrawals should have status pending
**Validates: Requirements 5.1**
Property 22: Approval updates status and records admin
*For any* withdrawal, approving it should update status to approved and record the admin ID
**Validates: Requirements 5.2**
Property 23: Rejection updates status and records reason
*For any* withdrawal and rejection reason, rejecting it should update status to rejected and store the reason
**Validates: Requirements 5.3**
Property 24: Withdrawal history includes user data
*For any* withdrawal history request, all withdrawals should include user information
**Validates: Requirements 5.4**
Property 25: Withdrawal date filtering is accurate
*For any* date range, all returned withdrawals should fall within that period
**Validates: Requirements 5.5**
### Service Management Properties
Property 26: Service creation persists all languages
*For any* service data with multi-language fields, creating the service then retrieving it should return all language versions
**Validates: Requirements 6.1**
Property 27: Service updates persist all changes
*For any* service and update data, updating the service then retrieving it should reflect all changes including translations
**Validates: Requirements 6.2**
Property 28: Service deletion removes record
*For any* service, deleting it then attempting to retrieve it should return not found
**Validates: Requirements 6.3**
Property 29: Image upload returns accessible URL
*For any* valid image file, uploading it should return a URL that can be accessed to retrieve the image
**Validates: Requirements 6.4**
Property 30: Service list includes categories
*For any* service list request, all services should include their category information
**Validates: Requirements 6.5**
### Category Management Properties
Property 31: Category creation persists all languages
*For any* category data with multi-language names, creating the category then retrieving it should return all language versions
**Validates: Requirements 7.1**
Property 32: Category translation updates persist
*For any* category and translation updates, updating translations then retrieving the category should reflect all language changes
**Validates: Requirements 7.2**
Property 33: Category deletion respects references
*For any* category with no service references, deleting it should remove the category; for categories with services, deletion should fail
**Validates: Requirements 7.3**
Property 34: Category list includes service counts
*For any* category list request, each category's service count should match the actual number of services in that category
**Validates: Requirements 7.4**
Property 35: Category reordering persists
*For any* new category order, updating the order then retrieving categories should reflect the new sequence
**Validates: Requirements 7.5**
### Statistics Properties
Property 36: Overview statistics are accurate
*For any* time period, overview statistics counts should match actual database records for users, appointments, and revenue
**Validates: Requirements 8.1**
Property 37: User growth aggregation is correct
*For any* date range, user growth data should correctly aggregate user registrations by time period
**Validates: Requirements 8.2**
Property 38: Appointment statistics match reality
*For any* time period, appointment status distribution should match actual appointment records
**Validates: Requirements 8.3**
Property 39: Revenue calculations are accurate
*For any* time period, revenue statistics should match the sum of actual transaction amounts
**Validates: Requirements 8.4**
Property 40: Statistics date filtering works
*For any* date range, statistics should only include data from that period
**Validates: Requirements 8.5**
### Configuration Properties
Property 41: Config retrieval is complete
*For any* config retrieval request, all config key-value pairs should be returned
**Validates: Requirements 9.1**
Property 42: Config updates persist immediately
*For any* config key and value, updating the config then retrieving it should return the new value
**Validates: Requirements 9.2**
Property 43: Batch config updates are atomic
*For any* set of config updates, either all updates should succeed or none should be applied
**Validates: Requirements 9.3**
Property 44: Single config retrieval works
*For any* config key, retrieving by key should return the correct value
**Validates: Requirements 9.4**
Property 45: Config caching is consistent
*For any* config key, multiple reads should return the same value without database queries
**Validates: Requirements 9.5**
### Home Content Properties
Property 46: Banner creation persists data
*For any* banner data, creating the banner then retrieving it should return the same image URL and display order
**Validates: Requirements 10.1**
Property 47: Banner reordering persists
*For any* new banner order, updating the order then retrieving banners should reflect the new sequence
**Validates: Requirements 10.2**
Property 48: Banner deletion removes record
*For any* banner, deleting it then attempting to retrieve it should return not found
**Validates: Requirements 10.3**
Property 49: Hot service addition persists
*For any* service and display order, adding it as a hot service then retrieving hot services should include it
**Validates: Requirements 10.4**
Property 50: Hot service removal works
*For any* hot service, removing it then retrieving hot services should not include it
**Validates: Requirements 10.5**
### Translation Properties
Property 51: Language translations are complete
*For any* supported language, retrieving translations should return all key-value pairs for that language
**Validates: Requirements 11.1**
Property 52: Translation updates persist
*For any* translation key, language, and value, updating the translation then retrieving it should return the new value
**Validates: Requirements 11.2**
Property 53: New keys create all language entries
*For any* new translation key, adding it should create entries for all supported languages (zh, en, pt)
**Validates: Requirements 11.3**
Property 54: Language negotiation works
*For any* Accept-Language header value, the system should return content in the matching language
**Validates: Requirements 11.4**
Property 55: Translation fallback works
*For any* missing translation, the system should return the default language version
**Validates: Requirements 11.5**
### File Upload Properties
Property 56: Valid image upload succeeds
*For any* valid image file (jpg, png, webp), uploading should store the file and return an accessible public URL
**Validates: Requirements 12.1**
Property 57: Invalid file types are rejected
*For any* non-image file type, upload attempts should be rejected with an appropriate error
**Validates: Requirements 12.2**
Property 58: Multiple file upload works
*For any* set of valid image files, uploading them should process all files and return URLs for each
**Validates: Requirements 12.4**
Property 59: File serving has correct headers
*For any* uploaded file URL, accessing it should return the file with correct Content-Type header
**Validates: Requirements 12.5**
### Response Format Properties
Property 60: Success responses are consistent
*For any* successful API endpoint, the response should have success: true and a data object
**Validates: Requirements 13.1**
Property 61: Error responses are consistent
*For any* failed API endpoint, the response should have success: false and an error object with code and message
**Validates: Requirements 13.2**
Property 62: Validation errors have details
*For any* validation failure, the error response should have code VALIDATION_ERROR and include validation details
**Validates: Requirements 13.3**
Property 63: Auth errors have correct codes
*For any* authentication failure, the error response should have an appropriate auth error code (MISSING_TOKEN, INVALID_TOKEN, etc.)
**Validates: Requirements 13.4**
Property 64: Server errors are formatted correctly
*For any* server error, the response should have code INTERNAL_ERROR and an error message
**Validates: Requirements 13.5**
### Logging Properties
Property 65: Operations are logged
*For any* admin operation, a log entry should be created with admin ID and timestamp
**Validates: Requirements 14.1**
Property 66: Sensitive data is redacted
*For any* operation that modifies data, the log should include request body with passwords and secrets redacted
**Validates: Requirements 14.2**
Property 67: Request metadata is logged
*For any* admin request, the log should include IP address and user agent
**Validates: Requirements 14.3**
Property 68: Response status is logged
*For any* completed operation, the log should include the response status code
**Validates: Requirements 14.4**
Property 69: Errors are logged with details
*For any* error that occurs, the log should include error details for debugging
**Validates: Requirements 14.5**
### Security Properties
Property 70: SQL injection is prevented
*For any* input containing SQL injection attempts, the system should sanitize the input and prevent execution
**Validates: Requirements 15.2**
Property 71: XSS payloads are sanitized
*For any* text input containing XSS payloads, the system should sanitize and escape dangerous content
**Validates: Requirements 15.3**
Property 72: CORS policies are enforced
*For any* cross-origin request, the system should enforce proper CORS policies based on configuration
**Validates: Requirements 15.5**
## Error Handling
### Error Response Format
All errors follow the standardized format:
```javascript
{
success: false,
error: {
code: string, // Machine-readable error code
message: string, // Human-readable error message
details: object // Optional additional error details
}
}
```
### Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| MISSING_CREDENTIALS | 400 | Username or password not provided |
| INVALID_CREDENTIALS | 401 | Wrong username or password |
| ACCOUNT_INACTIVE | 403 | Admin account is inactive |
| MISSING_TOKEN | 401 | No authentication token provided |
| INVALID_TOKEN | 401 | Token is invalid or expired |
| INVALID_TOKEN_TYPE | 401 | Wrong token type for endpoint |
| FORBIDDEN | 403 | Insufficient permissions |
| VALIDATION_ERROR | 400 | Input validation failed |
| NOT_FOUND | 404 | Resource not found |
| INTERNAL_ERROR | 500 | Server error occurred |
| INVALID_JSON | 400 | Malformed JSON in request |
### Error Handling Strategy
1. **Validation Errors**: Catch at controller level, return detailed validation errors
2. **Authentication Errors**: Handle in auth middleware, return appropriate auth error codes
3. **Authorization Errors**: Handle in RBAC middleware, return FORBIDDEN
4. **Database Errors**: Catch in service layer, log details, return generic error to client
5. **Unexpected Errors**: Catch in global error handler, log full stack trace, return INTERNAL_ERROR
## Testing Strategy
### Unit Testing
Unit tests focus on individual functions and modules:
- **Authentication utilities**: Token generation, validation, password hashing
- **RBAC logic**: Permission checking, role hierarchy
- **Data validators**: Input validation functions
- **Response formatters**: Success/error response builders
- **Generators**: Test data generation functions
### Property-Based Testing
Property-based tests use fast-check to verify properties across many random inputs:
- **Testing Framework**: Jest with fast-check
- **Iterations**: Minimum 100 iterations per property
- **Generators**: Custom generators for admin data, credentials, search criteria, etc.
- **Shrinking**: Automatic test case minimization on failure
- **Tagging**: Each property test tagged with format: `**Feature: admin-system-comprehensive-test, Property {number}: {property_text}**`
**Property Test Structure**:
```javascript
describe('Property: {property description}', () => {
it('should hold for all valid inputs', () => {
fc.assert(
fc.property(
// Generators
fc.record({
username: fc.string(),
password: fc.string()
}),
// Test function
async (credentials) => {
// Test logic
const response = await loginAdmin(credentials);
// Assertions
expect(response).toMatchProperty();
}
),
{ numRuns: 100 }
);
});
});
```
### Integration Testing
Integration tests verify end-to-end workflows:
- **Test Database**: Isolated MySQL test database
- **Test Data**: Created before each test suite, cleaned after
- **API Testing**: Using supertest to make HTTP requests
- **Authentication**: Login once, reuse token for test suite
- **Assertions**: Verify database state, response format, side effects
**Integration Test Structure**:
```javascript
describe('Admin User Management Integration', () => {
let adminToken;
beforeAll(async () => {
await setupTestDatabase();
adminToken = await loginAsTestAdmin();
});
afterAll(async () => {
await cleanupTestDatabase();
});
test('should list users with pagination', async () => {
const response = await request(app)
.get('/api/v1/admin/users?page=1&limit=10')
.set('Authorization', `Bearer ${adminToken}`);
expect(response.status).toBe(200);
expect(response.body.success).toBe(true);
expect(response.body.data.users).toBeInstanceOf(Array);
expect(response.body.meta.total).toBeGreaterThan(0);
});
});
```
### Manual Testing
Manual test procedures for scenarios that are difficult to automate:
- **UI Testing**: Admin portal interface testing
- **File Upload**: Test various file types and sizes
- **Performance**: Load testing with many concurrent requests
- **Security**: Penetration testing for vulnerabilities
- **Cross-browser**: Test admin portal in different browsers
**Manual Test Documentation**:
- Step-by-step test procedures
- Expected results for each step
- Screenshots for UI tests
- Test data requirements
- Environment setup instructions
### Test Coverage Goals
- **Unit Tests**: 80%+ code coverage
- **Integration Tests**: All API endpoints covered
- **Property Tests**: All correctness properties implemented
- **Manual Tests**: Critical user workflows documented
### Test Execution
```bash
# Run all tests
npm test
# Run specific test suite
npm test -- admin-auth.test.js
# Run with coverage
npm test -- --coverage
# Run property tests only
npm test -- --testNamePattern="Property:"
# Run integration tests only
npm test -- --testNamePattern="Integration"
```
### Continuous Integration
- Run all tests on every commit
- Fail build if any test fails
- Generate coverage reports
- Run security scans
- Performance benchmarks
## Implementation Notes
### Test Data Management
1. **Fixtures**: Pre-defined test data for common scenarios
2. **Factories**: Functions to create test data with defaults
3. **Generators**: fast-check generators for random test data
4. **Cleanup**: Automatic cleanup after each test suite
### Database Isolation
- Use separate test database
- Reset database before each test suite
- Use transactions for test isolation where possible
- Clean up test data after tests complete
### Authentication in Tests
- Create test admin accounts with different roles
- Login once per test suite to get token
- Reuse token for multiple tests
- Test token expiration separately
### Mocking Strategy
- **Avoid mocking** for integration tests - test real implementations
- **Mock external services**: WeChat API, payment gateways, email services
- **Mock time**: For testing time-dependent features
- **Mock file system**: For file upload tests when needed
### Performance Considerations
- Run tests in parallel where possible
- Use database transactions for faster cleanup
- Cache test data that doesn't change
- Skip slow tests in development, run in CI
## Security Considerations
### Test Security
- Never commit real credentials to test files
- Use environment variables for test configuration
- Sanitize test logs to remove sensitive data
- Secure test database access
### Security Testing
- Test SQL injection prevention
- Test XSS prevention
- Test CSRF protection
- Test rate limiting
- Test authentication bypass attempts
- Test authorization escalation attempts
## Monitoring and Reporting
### Test Reports
- Generate HTML test reports
- Track test execution time
- Monitor test flakiness
- Report coverage trends
### Failure Analysis
- Capture screenshots on UI test failures
- Log full request/response on API test failures
- Save database state on integration test failures
- Provide reproduction steps for failures
## Future Enhancements
- Visual regression testing for admin UI
- Performance benchmarking suite
- Chaos engineering tests
- Accessibility testing
- Mobile responsiveness testing
- Internationalization testing
Reference in New Issue View Git Blame Copy Permalink