Add comprehensive tests and documentation for historical area code validation
This PR addresses concerns about historical area code validation by adding comprehensive test coverage and documentation to clarify how the system handles area code transitions.
Background
The issue reported that area code 370284 (胶南市) was changed to 370211 (黄岛区), causing concerns about identity validation failures for historical IDs. Upon investigation, the system already handles this correctly through its timeline-based validation.
Key Findings
The validation system properly supports historical area codes:
// Historical ID from 2000 (within valid period 1995-2011)
idvalidator.IsValid("370284200001010015", true) // ✅ true (strict mode)
idvalidator.IsValid("370284200001010015", false) // ✅ true (loose mode)
// Returns correct historical address information
info, _ := idvalidator.GetInfo("370284200001010015", false)
// info.Address = "山东省青岛市胶南市"
// info.Abandoned = 1 (indicates historical area code)
Changes Made
Test Coverage:
- Added
TestHistoricalAreaCodeswith comprehensive scenarios covering birth years before, during, and after valid periods - Added
TestAreaCodeTransitionspecifically testing the 370284 → 370211 transition - Added
TestCurrentAreaCodeverifying current area code validation - All tests verify both strict and loose validation modes
Documentation:
- Added "Historical Address Code Support" section to both Chinese and English READMEs
- Explained the difference between strict mode (validates birth date within area code period) and loose mode (allows historical codes regardless)
- Provided clear examples of the 370284 → 370211 transition handling
- Documented the meaning of the
Abandonedfield in results
Validation Modes
- Strict Mode: Only validates when birth date falls within the area code's valid period
- Loose Mode: Accepts historical area codes without strict temporal validation
For maximum compatibility with historical IDs, users should use loose mode (strict=false).
Fixes #60.
💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.
@guanguans 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.
I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.