Skip to content

PINYIN_FEATURE_README.md

Latest commit

 

History

History
175 lines (136 loc) · 5.17 KB

PINYIN_FEATURE_README.md

File metadata and controls

175 lines (136 loc) · 5.17 KB

Auto-Generate Pinyin for Acupoint Chinese Characters

This feature automatically generates Pinyin (Chinese phonetic notation) from Chinese characters for acupoint entries, making it easier to input and manage acupoint data.

🚀 Features

  • Automatic Pinyin Generation: When you enter Chinese characters for an acupoint, Pinyin is automatically generated
  • Real-time Conversion: Pinyin updates as you type Chinese characters
  • Manual Override: You can still manually edit the Pinyin field if needed
  • Multiple Pinyin Formats: Supports tone marks, numeric tones, and normal Pinyin
  • Batch Migration: Script to generate Pinyin for existing acupoints
  • API Endpoint: Dedicated endpoint for Pinyin conversion

📋 How It Works

Frontend (Client)

  1. When you enter Chinese characters in the "Chữ Hán" field, the system automatically detects Chinese characters
  2. A request is sent to the server to generate Pinyin
  3. The generated Pinyin appears in the "Pinyin" field
  4. You can manually edit the Pinyin if needed
  5. A refresh button allows manual regeneration

Backend (Server)

  1. Uses the pinyin npm library for accurate Chinese-to-Pinyin conversion
  2. Automatically generates Pinyin when creating or updating acupoints
  3. Provides a dedicated API endpoint for real-time conversion
  4. Handles edge cases and error scenarios gracefully

🛠️ Technical Implementation

New Files Added:

  • server/src/services/pinyinService.ts - Core Pinyin conversion service
  • server/src/scripts/generatePinyinForExistingAcupoints.ts - Migration script
  • server/src/scripts/testPinyinService.ts - Test script

Modified Files:

  • server/src/routes/admin.ts - Added auto-generation logic and API endpoint
  • client/src/components/qigong/AcupointManagement.tsx - Added real-time Pinyin generation
  • server/package.json - Added new npm scripts

Dependencies Added:

  • pinyin - Chinese to Pinyin conversion library

📖 Usage Examples

Common Acupoint Names:

  • 合谷 → hégǔ (Hegu, LI4)
  • 足三里 → zúsānlǐ (Zusanli, ST36)
  • 百会 → bǎihuì (Baihui, GV20)
  • 神门 → shénmén (Shenmen, HE7)
  • 太冲 → tàichōng (Taichong, LR3)

API Usage:

# Convert Chinese characters to Pinyin
POST /api/admin/convert-pinyin?access_code=YOUR_ACCESS_CODE
Content-Type: application/json

{
  "chinese_characters": "合谷"
}

# Response:
{
  "success": true,
  "data": {
    "chinese_characters": "合谷",
    "pinyin": "hé gǔ",
    "pinyin_normal": "he gu",
    "pinyin_numeric": "he2 gu3",
    "acupoint_pinyin": "hégǔ",
    "message": "Pinyin conversion successful"
  }
}

🔧 Available Scripts

Test Pinyin Service:

cd server
npm run test:pinyin

Generate Pinyin for Existing Acupoints:

cd server
# Preview what would be updated (safe, no changes made)
npm run generate-pinyin:preview

# Actually perform the update
npm run generate-pinyin

🎯 Pinyin Formats Supported

  1. Tone Marks (Default): hégǔ
  2. Normal (No tones): he gu
  3. Numeric Tones: he2 gu3
  4. Acupoint Format (Compact with tones): hégǔ

🔍 Features in Detail

Auto-Generation Logic:

  • Triggers when Chinese characters are entered
  • Only generates if Pinyin field is empty
  • Preserves manual edits
  • Handles mixed Chinese/English text
  • Ignores non-Chinese characters

Error Handling:

  • Graceful fallback if conversion fails
  • Validates input before processing
  • Logs errors for debugging
  • Continues operation even if Pinyin generation fails

Performance:

  • Efficient conversion using proven library
  • Minimal impact on form performance
  • Caching for repeated conversions
  • Async processing to avoid UI blocking

🚨 Important Notes

  1. Manual Override: You can always manually edit the Pinyin field
  2. Existing Data: Use the migration script to update existing acupoints
  3. Access Control: Pinyin conversion requires valid access code
  4. Language Support: Primarily designed for Simplified Chinese characters
  5. Backup: Always backup your database before running migration scripts

🐛 Troubleshooting

Common Issues:

Pinyin not generating automatically:

  • Check that Chinese characters are properly entered
  • Ensure access code is valid
  • Check browser console for errors

Migration script not working:

  • Ensure server is built: npm run build
  • Check database permissions
  • Verify acupoint data exists

API endpoint not responding:

  • Verify server is running
  • Check access code parameter
  • Ensure Content-Type is application/json

📊 Testing

The implementation includes comprehensive testing:

  • Unit tests for Pinyin service
  • Integration tests for API endpoints
  • Edge case handling
  • Performance validation

Run tests with:

cd server
npm run test:pinyin

🔮 Future Enhancements

Potential improvements for future versions:

  • Support for Traditional Chinese characters
  • Multiple pronunciation options for polyphones
  • Batch conversion interface
  • Pinyin pronunciation audio
  • Integration with other Chinese text fields

This feature significantly improves the user experience for managing acupoint data by automating the tedious task of manually entering Pinyin for Chinese acupoint names.