feat: 添加关系时支持拼音模糊匹配（企业成员搜索增强）

[Clawiee]

📋 需求背景

当前在 Clawith 中添加关系时，企业成员搜索仅支持中文/英文的 LIKE 模糊匹配，不支持拼音搜索。这导致以下用户体验问题：

• 输入 "zhangsan" 搜不到 "张三"
• 输入 "zs"（首字母）搜不到 "张三"
• 用户需要记住同事的准确中文姓名才能搜索

🎯 需求目标

在 /api/enterprise/org/members 接口中增加拼音模糊匹配能力，支持：

1. 拼音全拼匹配：输入 "zhangsan" → 匹配 "张三"
2. 拼音首字母匹配：输入 "zs" → 匹配 "张三"
3. 保持向后兼容：不影响现有中文搜索功能

💡 技术方案

推荐方案：数据库拼音字段

-- 在 org_members 表增加拼音索引字段
ALTER TABLE org_members 
ADD COLUMN pinyin_full VARCHAR(255),      -- 完整拼音：zhangsan
ADD COLUMN pinyin_initial VARCHAR(50);    -- 拼音首字母：zs

-- 创建索引加速查询
CREATE INDEX idx_org_members_pinyin_full ON org_members(pinyin_full);
CREATE INDEX idx_org_members_pinyin_initial ON org_members(pinyin_initial);

后端修改点

文件: backend/app/api/enterprise.py

from pypinyin import pinyin, Style

@router.get("/org/members")
async def list_org_members(
    search: str | None = None,
    ...
):
    if search:
        # 生成搜索词的拼音和首字母
        search_pinyin = ''.join([i[0] for i in pinyin(search, style=Style.NORMAL)]).lower()
        search_initial = ''.join([i[0] for i in pinyin(search, style=Style.FIRST_LETTER)]).lower()
        
        # 多条件 OR 匹配
        query = query.where(
            or_(
                OrgMember.name.ilike(f"%{search}%"),
                OrgMember.pinyin_full.ilike(f"%{search_pinyin}%"),
                OrgMember.pinyin_initial.ilike(f"%{search_initial}%"),
            )
        )

文件: backend/app/services/org_sync_service.py

在同步企业成员时自动转换拼音：

def _convert_pinyin(self, name: str) -> dict:
    return {
        'pinyin_full': ''.join([i[0] for i in pinyin(name, style=Style.NORMAL)]).lower(),
        'pinyin_initial': ''.join([i[0] for i in pinyin(name, style=Style.FIRST_LETTER)]).lower(),
    }

依赖安装

pypinyin>=0.50.0

📊 用户体验提升

搜索输入	当前结果	增强后结果
张三	✅ 张三	✅ 张三
zhangsan	❌ 无结果	✅ 张三
zs	❌ 无结果	✅ 张三
wang	❌ 无结果	✅ 王五、王六

🚀 实施计划

阶段	工作内容	预计时间
Phase 1	数据库迁移：添加拼音字段 + 索引	0.5 天
Phase 2	后端修改：搜索逻辑 + 同步服务	1 天
Phase 3	历史数据回填（批量转换拼音）	0.5 天
Phase 4	前端测试 + 用户体验验证	0.5 天
总计		2.5 天

⚠️ 注意事项

1. 多音字处理：pypinyin 支持自定义词典，需处理常见多音字
2. 性能影响：拼音字段增加约 300 字节/记录，对 10 万成员规模影响可忽略
3. 同步触发：每次 Feishu 组织架构同步时自动更新拼音
4. 兼容性：搜索逻辑向后兼容，不影响现有中文搜索

📝 验收标准

• 数据库迁移完成，拼音字段和索引创建成功
• 新成员同步时自动填充拼音字段
• 历史成员数据批量回填拼音
• 搜索 "zhangsan" 能匹配到 "张三"
• 搜索 "zs" 能匹配到 "张三"
• 现有中文搜索功能不受影响
• 前端添加关系界面测试通过

🔗 相关文件

• backend/app/api/enterprise.py
• backend/app/services/org_sync_service.py
• backend/app/models/org.py (OrgMember 模型)

---

优先级: P1 - 用户体验增强

[Clawiee]

Hi @Clawiee,

Thank you for submitting this feature request! This is a well-documented enhancement for pinyin fuzzy matching in enterprise member search.

📌 Friendly Reminder: For better collaboration with international contributors, please consider submitting future issues in English. The detailed structure and technical proposal you provided are excellent!

✅ Issue Analysis:

• Feature: Pinyin fuzzy matching for enterprise member search
• Priority: P1 - User Experience Enhancement
• Estimated Effort: 2.5 days
• Key Files: backend/app/api/enterprise.py, backend/app/services/org_sync_service.py

The technical approach using pypinyin library with database indexing looks solid. The backward compatibility consideration is also well thought out.

Next Steps:

1. Team will review the implementation plan
2. Assign developer for Phase 1 (Database migration)
3. Schedule for upcoming sprint

Thanks for the detailed proposal! 🚀

---

Note: This issue has been logged and the team has been notified.

[wisdomqin]

We have just implemented this feature! Thank you for the excellent suggestion! To better support internationalization (such as English usernames, Japanese Romaji, Russian transliteration, etc.), we have introduced generic name_translit_full and name_translit_initial fields on the OrgMember model instead of hardcoding pinyin. The platform now automatically generates these fields using pypinyin during the background sync process and executes an OR search across the name and transliteration fields. The problem of full ASCII names falsely triggering pin-yin matches is now naturally avoided since the frontend search query remains identical, and the backend searches across all variations natively. Closing this issue as it is now fully supported. Thanks again!