#{quotation_number}
+{customer_name}
+{customer_company}
+{customer_country}
+Date: {date}
+Valid Until: {valid_until}
+Currency: {currency}
+| Item | +Description | +Qty | +Unit | +Unit Price | +Total | +
|---|
| Subtotal: | {subtotal} | ||||
| Discount: | -{discount} | ||||
| Shipping: | {shipping} | ||||
| TOTAL: | {total} | ||||
Payment Terms: {payment_terms}
+Delivery Terms: {delivery_terms}
+Lead Time: {lead_time}
+ {notes_html} +Notes: {data['notes']}
" + + html = QUOTATION_TEMPLATE.format( + quotation_number=data.get("quotation_number", "N/A"), + customer_name=data.get("customer_name", ""), + customer_company=data.get("customer_company", "") or "", + customer_country=data.get("customer_country", "") or "", + date=data.get("date", datetime.utcnow().strftime("%Y-%m-%d")), + valid_until=data.get("valid_until", "N/A"), + currency=cur, + items_rows=items_rows, + subtotal=subtotal, + discount=discount, + shipping=shipping, + total=total, + payment_terms=data.get("payment_terms", "N/A"), + delivery_terms=data.get("delivery_terms", "N/A"), + lead_time=data.get("lead_time", "N/A"), + notes_html=notes_html, + generated_at=datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"), + ) + + pdf = HTML(string=html).write_pdf() + return pdf + + +pdf_generator = PDFGenerator() diff --git a/backend/app/services/preference.py b/backend/app/services/preference.py new file mode 100644 index 0000000..07bc7b0 --- /dev/null +++ b/backend/app/services/preference.py @@ -0,0 +1,217 @@ +from typing import Dict, Any, Optional, List +from datetime import datetime +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy import select, func, and_, desc +from app.models.customer import Message, Conversation +from app.models.user import User +from app.models.preference import PreferenceAnalysis +import logging + +logger = logging.getLogger(__name__) + + +class UserPreferenceService: + def __init__(self, db: AsyncSession): + self.db = db + + async def record_selection(self, user_id: str, message_id: str, selected_index: int) -> bool: + result = await self.db.execute( + select(Message).where(Message.id == message_id) + ) + msg = result.scalar_one_or_none() + if not msg: + return False + msg.selected_suggestion = selected_index + await self.db.flush() + return True + + async def record_edit(self, user_id: str, message_id: str, edited_text: str) -> bool: + result = await self.db.execute( + select(Message).where(Message.id == message_id) + ) + msg = result.scalar_one_or_none() + if not msg: + return False + msg.user_edited = edited_text + await self.db.flush() + return True + + async def analyze_preferences(self, user_id: str) -> Dict[str, Any]: + user_conv_subq = select(Conversation.id).where( + Conversation.user_id == user_id + ).subquery() + + count_result = await self.db.execute( + select(func.count(Message.id)).where( + and_( + Message.conversation_id.in_(select(user_conv_subq)), + Message.selected_suggestion.isnot(None), + ) + ) + ) + total = count_result.scalar() or 0 + + if total < 3: + return {"needs_more_data": True, "interaction_count": total} + + result = await self.db.execute( + select(Message) + .where( + and_( + Message.conversation_id.in_(select(user_conv_subq)), + Message.selected_suggestion.isnot(None), + ) + ) + .order_by(desc(Message.created_at)) + .limit(100) + ) + messages = result.scalars().all() + + tone_counts = {} + edit_count = 0 + total_chars_saved = 0 + greeting_patterns = [] + signoff_patterns = [] + + for m in messages: + suggestions = m.ai_suggestions or [] + selected = m.selected_suggestion + if suggestions and selected is not None and selected < len(suggestions): + tone = suggestions[selected].get("tone", "unknown") + tone_counts[tone] = tone_counts.get(tone, 0) + 1 + + if m.user_edited: + edit_count += 1 + if suggestions and selected is not None and selected < len(suggestions): + original = suggestions[selected].get("reply", "") + total_chars_saved += abs(len(original) - len(m.user_edited)) + + preferred_tone = max(tone_counts, key=tone_counts.get) if tone_counts else "professional" + edit_ratio = edit_count / len(messages) if messages else 0 + avg_edit_size = total_chars_saved / edit_count if edit_count > 0 else 0 + + greeting_style = self._extract_greeting_style(messages) + sign_off_style = self._extract_sign_off_style(messages) + + preferences = { + "preferred_tone": preferred_tone, + "edit_ratio": edit_ratio, + "avg_edit_size": avg_edit_size, + "greeting_style": greeting_style, + "sign_off_style": sign_off_style, + "tone_distribution": tone_counts, + "interaction_count": len(messages), + "confidence": min(1.0, len(messages) / 20), + } + + existing = await self.db.execute( + select(PreferenceAnalysis).where(PreferenceAnalysis.user_id == user_id) + ) + analysis = existing.scalar_one_or_none() + + if analysis: + analysis.preferred_tone = preferred_tone + analysis.greeting_style = greeting_style + analysis.sign_off_style = sign_off_style + analysis.analysis_data = preferences + analysis.interaction_count = len(messages) + analysis.confidence = preferences["confidence"] + analysis.last_analysis_at = datetime.utcnow() + else: + analysis = PreferenceAnalysis( + user_id=user_id, + task_type="reply", + preferred_tone=preferred_tone, + greeting_style=greeting_style, + sign_off_style=sign_off_style, + analysis_data=preferences, + interaction_count=len(messages), + confidence=preferences["confidence"], + last_analysis_at=datetime.utcnow(), + ) + self.db.add(analysis) + + await self.db.flush() + + await self._update_user_settings(user_id, preferences) + return preferences + + async def get_preference_context(self, user_id: str, task_type: str = "reply") -> Optional[str]: + result = await self.db.execute( + select(PreferenceAnalysis).where( + and_( + PreferenceAnalysis.user_id == user_id, + PreferenceAnalysis.task_type == task_type, + ) + ) + ) + analysis = result.scalar_one_or_none() + if not analysis or analysis.confidence < 0.3: + return None + + parts = [] + if analysis.preferred_tone: + parts.append(f"user's preferred tone: {analysis.preferred_tone}") + if analysis.greeting_style: + parts.append(f"user's typical greeting: {analysis.greeting_style}") + if analysis.sign_off_style: + parts.append(f"user's typical sign-off: {analysis.sign_off_style}") + + if parts: + return "This user prefers: " + "; ".join(parts) + "." + return None + + async def get_analysis(self, user_id: str) -> Dict[str, Any]: + result = await self.db.execute( + select(PreferenceAnalysis).where(PreferenceAnalysis.user_id == user_id) + ) + analysis = result.scalar_one_or_none() + if not analysis: + return {"analyzed": False, "interaction_count": 0, "confidence": 0} + + return { + "analyzed": True, + "preferred_tone": analysis.preferred_tone, + "greeting_style": analysis.greeting_style, + "sign_off_style": analysis.sign_off_style, + "interaction_count": analysis.interaction_count, + "confidence": analysis.confidence, + "last_analysis_at": analysis.last_analysis_at.isoformat() if analysis.last_analysis_at else None, + } + + async def _update_user_settings(self, user_id: str, preferences: Dict[str, Any]): + result = await self.db.execute(select(User).where(User.id == user_id)) + user = result.scalar_one_or_none() + if user: + settings = dict(user.settings or {}) + settings["preferred_tone"] = preferences.get("preferred_tone", settings.get("reply_tone", "professional")) + settings["ai_learning"] = { + "analyzed": True, + "confidence": preferences.get("confidence", 0), + "edit_ratio": preferences.get("edit_ratio", 0), + "greeting_style": preferences.get("greeting_style", ""), + "sign_off_style": preferences.get("sign_off_style", ""), + } + user.settings = settings + await self.db.flush() + + def _extract_greeting_style(self, messages: List[Message]) -> str: + for m in messages: + text = m.user_edited or (m.ai_suggestions[m.selected_suggestion].get("reply", "") if m.selected_suggestion is not None and m.ai_suggestions and m.selected_suggestion < len(m.ai_suggestions) else "") + if text: + first_word = text.strip().split()[0] if text.strip() else "" + if first_word in ["Dear", "Hi", "Hello", "Hey", "To"]: + return first_word + return "" + + def _extract_sign_off_style(self, messages: List[Message]) -> str: + for m in messages: + text = m.user_edited or (m.ai_suggestions[m.selected_suggestion].get("reply", "") if m.selected_suggestion is not None and m.ai_suggestions and m.selected_suggestion < len(m.ai_suggestions) else "") + if text: + words = text.strip().split() + if len(words) >= 3: + last_three = " ".join(words[-3:]) + for signoff in ["Best regards", "Best wishes", "Sincerely", "Cheers", "Regards", "Yours"]: + if signoff in last_three: + return signoff + return "" diff --git a/backend/app/services/push.py b/backend/app/services/push.py new file mode 100644 index 0000000..454867b --- /dev/null +++ b/backend/app/services/push.py @@ -0,0 +1,156 @@ +from typing import Optional, Dict, Any, List +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy import select, and_ +from app.config import settings +from app.models.device import Device +import httpx +import logging + +logger = logging.getLogger(__name__) + + +class PushService: + def __init__(self, db: Optional[AsyncSession] = None): + self.db = db + + @staticmethod + def send_notification(user_id: str, title: str, content: str, payload: Optional[Dict[str, Any]] = None) -> bool: + logger.info(f"[PUSH] user={user_id} title={title} content={content}") + try: + import asyncio + loop = asyncio.new_event_loop() + asyncio.set_event_loop(loop) + result = loop.run_until_complete( + PushService._send_via_wechat(user_id, title, content, payload) + ) + loop.close() + return result + except Exception as e: + logger.warning(f"Push send failed (logged only): {e}") + return True + + @staticmethod + def send_bulk(user_ids: List[str], title: str, content: str, payload: Optional[Dict[str, Any]] = None) -> int: + sent = 0 + for uid in user_ids: + if PushService.send_notification(uid, title, content, payload): + sent += 1 + return sent + + async def send_async(self, user_id: str, title: str, content: str, payload: Optional[Dict[str, Any]] = None) -> bool: + logger.info(f"[PUSH_ASYNC] user={user_id} title={title}") + + result = await self._send_via_wechat(user_id, title, content, payload) + + await self._save_in_app_notification(user_id, title, content, payload) + + return result + + async def register_device(self, user_id: str, client_id: str, platform: str = "weapp", push_token: Optional[str] = None, device_info: Optional[Dict] = None) -> Device: + result = await self.db.execute( + select(Device).where( + and_(Device.user_id == user_id, Device.client_id == client_id) + ) + ) + existing = result.scalar_one_or_none() + if existing: + existing.platform = platform + existing.push_token = push_token + existing.device_info = device_info or {} + existing.is_active = True + await self.db.flush() + return existing + + device = Device( + user_id=user_id, + platform=platform, + push_token=push_token, + client_id=client_id, + device_info=device_info or {}, + ) + self.db.add(device) + await self.db.flush() + return device + + async def get_user_devices(self, user_id: str) -> List[Dict]: + result = await self.db.execute( + select(Device).where( + and_(Device.user_id == user_id, Device.is_active == True) + ) + ) + devices = result.scalars().all() + return [ + { + "id": str(d.id), + "platform": d.platform, + "client_id": d.client_id, + "device_info": d.device_info, + "created_at": d.created_at.isoformat() if d.created_at else None, + } + for d in devices + ] + + async def unregister_device(self, user_id: str, client_id: str) -> bool: + result = await self.db.execute( + select(Device).where( + and_(Device.user_id == user_id, Device.client_id == client_id) + ) + ) + device = result.scalar_one_or_none() + if not device: + return False + device.is_active = False + await self.db.flush() + return True + + @staticmethod + async def _send_via_wechat(user_id: str, title: str, content: str, payload: Optional[Dict] = None) -> bool: + if not settings.WECHAT_APP_ID or not settings.WECHAT_APP_SECRET: + logger.debug("WeChat push not configured, falling back to log") + return True + + try: + from app.services.wechat import wechat_service + access_token = await wechat_service._get_access_token() + if not access_token: + logger.warning("Cannot get WeChat access token for push") + return False + + async with httpx.AsyncClient() as client: + resp = await client.post( + "https://api.weixin.qq.com/cgi-bin/message/subscribe/send", + params={"access_token": access_token}, + json={ + "touser": user_id, + "template_id": settings.WECHAT_PUSH_TEMPLATE_ID or "", + "data": { + "thing1": {"value": title[:20]}, + "thing2": {"value": content[:20]}, + }, + "miniprogram_state": "formal", + }, + timeout=10, + ) + data = resp.json() + if data.get("errcode", 0) != 0: + logger.warning(f"WeChat push failed: {data}") + return False + logger.info(f"WeChat push sent to user {user_id}") + return True + except Exception as e: + logger.warning(f"WeChat push error: {e}") + return False + + async def _save_in_app_notification(self, user_id: str, title: str, content: str, payload: Optional[Dict] = None): + if not self.db: + return + try: + from app.services.notification import NotificationService + await NotificationService.create_notification( + self.db, user_id, title, content, + notification_type="push", + reference_type=(payload or {}).get("reference_type"), + reference_id=(payload or {}).get("reference_id"), + ) + except Exception as e: + logger.warning(f"Failed to save in-app notification: {e}") diff --git a/backend/app/services/quotation.py b/backend/app/services/quotation.py index f8c60e9..5b77c65 100644 --- a/backend/app/services/quotation.py +++ b/backend/app/services/quotation.py @@ -1,11 +1,13 @@ from typing import Dict, Any, Optional, List from sqlalchemy.ext.asyncio import AsyncSession -from sqlalchemy import select, and_ +from sqlalchemy import select, and_, or_ from app.models.quotation import Quotation, QuotationItem from app.models.customer import Customer from app.models.user import Product +from app.ai.router import get_ai_router from datetime import datetime import logging +import json logger = logging.getLogger(__name__) @@ -90,6 +92,135 @@ class QuotationService: await self.db.flush() return await self._to_dict(q) + async def generate_from_inquiry( + self, user_id: str, inquiry_text: str, customer_id: Optional[str] = None, + ) -> Dict[str, Any]: + ai = get_ai_router() + + schema = { + "type": "object", + "properties": { + "product_requests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "product_name": {"type": "string"}, + "quantity": {"type": "integer"}, + "unit": {"type": "string"}, + "specifications": {"type": "string"}, + "target_price": {"type": "string"}, + }, + }, + }, + "payment_terms": {"type": "string"}, + "delivery_terms": {"type": "string"}, + "urgency": {"type": "string"}, + }, + } + + extract_result = await ai.extract(inquiry_text, schema) + extracted = extract_result.get("data", {}) + product_requests = extracted.get("product_requests", []) + + if not product_requests: + schema_simple = { + "type": "object", + "properties": { + "product_name": {"type": "string"}, + "quantity": {"type": "integer"}, + "specifications": {"type": "string"}, + }, + } + extract_result = await ai.extract(inquiry_text, schema_simple) + extracted = extract_result.get("data", {}) + if extracted.get("product_name"): + product_requests = [{ + "product_name": extracted["product_name"], + "quantity": extracted.get("quantity", 1), + "unit": "pcs", + "specifications": extracted.get("specifications", ""), + }] + + product_result = await self.db.execute( + select(Product).where( + and_( + Product.user_id == user_id, + Product.is_active == True, + ) + ) + ) + user_products = product_result.scalars().all() + + matched_products = [] + for req in product_requests: + req_name = req.get("product_name", "").lower() + best_match = None + best_score = 0 + + for p in user_products: + score = 0 + p_name = (p.name or "").lower() + p_name_en = (p.name_en or "").lower() + + if req_name in p_name or p_name in req_name: + score += 3 + if req_name in p_name_en or p_name_en in req_name: + score += 2 + + keywords = p.keywords or [] + for kw in keywords: + if isinstance(kw, str) and kw.lower() in req_name: + score += 1 + + if score > best_score: + best_score = score + best_match = p + + if best_match and best_score > 0: + unit_price = float(best_match.price) if best_match.price else 0 + quantity = req.get("quantity", 1) + matched_products.append({ + "product_id": str(best_match.id), + "product_name": best_match.name, + "description": best_match.description_en or best_match.description, + "quantity": quantity, + "unit_price": unit_price, + "total_price": unit_price * quantity, + "unit": req.get("unit", "pcs"), + "match_score": best_score, + }) + else: + matched_products.append({ + "product_id": None, + "product_name": req.get("product_name", "Unknown"), + "description": req.get("specifications", ""), + "quantity": req.get("quantity", 1), + "unit_price": 0, + "total_price": 0, + "unit": req.get("unit", "pcs"), + "match_score": 0, + }) + + subtotal = sum(p["total_price"] for p in matched_products) + total = subtotal + + suggested_quotation = { + "title": f"Quotation - {', '.join(p['product_name'] for p in matched_products[:3])}", + "items": matched_products, + "subtotal": subtotal, + "total": total, + "payment_terms": extracted.get("payment_terms", "T/T"), + "delivery_terms": extracted.get("delivery_terms", "FOB"), + "lead_time": "15-20 days" if extracted.get("urgency") != "urgent" else "7-10 days", + "notes": f"Generated from customer inquiry: {inquiry_text[:100]}..." if len(inquiry_text) > 100 else f"Generated from customer inquiry: {inquiry_text}", + "extracted_data": extracted, + "matched_count": len([p for p in matched_products if p["product_id"]]), + "unmatched_count": len([p for p in matched_products if not p["product_id"]]), + } + + return suggested_quotation + async def generate_quotation_text(self, q: Quotation) -> str: items_result = await self.db.execute( select(QuotationItem).where(QuotationItem.quotation_id == q.id) diff --git a/backend/app/services/silent_pattern.py b/backend/app/services/silent_pattern.py new file mode 100644 index 0000000..0cf0f44 --- /dev/null +++ b/backend/app/services/silent_pattern.py @@ -0,0 +1,168 @@ +from typing import Dict, Any, Optional, List +from datetime import datetime, timedelta +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy import select, func, and_ +from app.models.customer import Customer, Conversation, Message +import logging + +logger = logging.getLogger(__name__) + + +class SilentPatternService: + def __init__(self, db: AsyncSession): + self.db = db + + async def analyze_silent_risk(self, user_id: str) -> List[Dict[str, Any]]: + cutoff_3d = datetime.utcnow() - timedelta(days=3) + cutoff_7d = datetime.utcnow() - timedelta(days=7) + + result = await self.db.execute( + select(Customer).where( + and_( + Customer.user_id == user_id, + Customer.status.in_(["lead", "negotiating"]), + ) + ) + ) + customers = result.scalars().all() + + risk_scores = [] + for c in customers: + score, reasons = await self._calculate_risk_score(c, cutoff_3d, cutoff_7d) + if score > 0: + risk_scores.append({ + "customer_id": str(c.id), + "name": c.name, + "company": c.company, + "country": c.country, + "status": c.status, + "estimated_value": c.estimated_value, + "last_contact_at": c.last_contact_at.isoformat() if c.last_contact_at else None, + "silence_days": (datetime.utcnow() - c.last_contact_at).days if c.last_contact_at else 0, + "risk_score": score, + "risk_level": self._risk_level(score), + "reasons": reasons, + }) + + risk_scores.sort(key=lambda x: x["risk_score"], reverse=True) + return risk_scores + + async def _calculate_risk_score( + self, customer: Customer, cutoff_3d: datetime, cutoff_7d: datetime + ) -> tuple: + score = 0 + reasons = [] + + if not customer.last_contact_at: + return (0, []) + + silence_days = (datetime.utcnow() - customer.last_contact_at).days + + if silence_days >= 7: + score += 40 + reasons.append(f"沉默超过7天") + elif silence_days >= 3: + score += 20 + reasons.append(f"沉默超过3天") + + conv_query = await self.db.execute( + select(Conversation).where( + and_( + Conversation.customer_id == customer.id, + Conversation.user_id == customer.user_id, + ) + ).order_by(Conversation.created_at.desc()).limit(1) + ) + conv = conv_query.scalar_one_or_none() + if not conv: + return (score, reasons) + + msg_count_query = await self.db.execute( + select(func.count(Message.id)).where( + and_( + Message.conversation_id == conv.id, + Message.direction == "inbound", + ) + ) + ) + inbound_count = msg_count_query.scalar() or 0 + + if inbound_count >= 5 and silence_days >= 3: + score += 20 + reasons.append(f"前期沟通频繁({inbound_count}条)后突然沉默") + + if customer.status == "lead" and silence_days >= 3: + score += 15 + reasons.append("潜在客户阶段需及时跟进") + + if customer.status == "negotiating" and silence_days >= 2: + score += 25 + reasons.append("谈判阶段客户需保持热度") + + recent_query = await self.db.execute( + select(Message).where( + and_( + Message.conversation_id == conv.id, + Message.created_at >= cutoff_7d, + ) + ).order_by(Message.created_at.desc()).limit(3) + ) + recent_msgs = recent_query.scalars().all() + + if recent_msgs: + last_inbound = None + for m in recent_msgs: + if m.direction == "inbound": + last_inbound = m + break + if last_inbound and silence_days >= 1: + content_lower = last_inbound.content.lower() + closing_signals = ["i'll think", "let me check", "too expensive", "high price", "not now", "maybe later", "considering"] + for signal in closing_signals: + if signal in content_lower: + score += 15 + reasons.append(f"客户回复含消极信号: \"{signal}\"") + break + + return (min(score, 100), reasons) + + def _risk_level(self, score: int) -> str: + if score >= 70: + return "high" + elif score >= 40: + return "medium" + elif score >= 20: + return "low" + return "minimal" + + async def get_suggestions(self, user_id: str, customer_id: str) -> List[str]: + score_result = await self.analyze_silent_risk(user_id) + customer_scores = [s for s in score_result if s["customer_id"] == customer_id] + if not customer_scores: + return [] + + score = customer_scores[0] + suggestions = [] + silence_days = score["silence_days"] + + if silence_days >= 7: + suggestions.extend([ + f"客户{score['name']}已沉默{silence_days}天，建议发送产品更新或行业资讯重新激活", + "考虑提供限时优惠或样品折扣打动客户", + ]) + elif silence_days >= 3: + suggestions.extend([ + f"客户{score['name']}沉默{silence_days}天，建议发送跟进消息询问是否有进一步需求", + "可分享相关案例或成功故事保持客户兴趣", + ]) + + if "negotiating" in score.get("status", ""): + suggestions.append("谈判阶段客户，建议主动提供更多产品细节或定制方案") + + if "消极信号" in str(score.get("reasons", [])): + suggestions.append("客户曾表达价格顾虑，建议重新审视报价或提供增值服务") + + if not suggestions: + suggestions.append("客户状态良好，建议保持定期跟进节奏") + + return suggestions diff --git a/backend/app/services/team.py b/backend/app/services/team.py new file mode 100644 index 0000000..a3ac3e6 --- /dev/null +++ b/backend/app/services/team.py @@ -0,0 +1,201 @@ +from typing import Dict, Any, Optional, List +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy import select, func, and_, or_ +from app.models.team import Team, TeamMember +from app.models.user import User +from datetime import datetime +import logging + +logger = logging.getLogger(__name__) + + +class TeamService: + def __init__(self, db: AsyncSession): + self.db = db + + async def create_team(self, owner_id: str, name: str, description: str = None) -> Dict[str, Any]: + existing = await self.db.execute( + select(Team).where(and_(Team.owner_id == owner_id, Team.is_active == True)) + ) + if existing.scalar_one_or_none(): + raise ValueError("You already own an active team") + + user_result = await self.db.execute(select(User).where(User.id == owner_id)) + user = user_result.scalar_one_or_none() + if not user: + raise ValueError("User not found") + + max_members = 20 if user.tier == "enterprise" else (10 if user.tier == "pro" else 5) + + team = Team( + name=name, + owner_id=owner_id, + description=description, + max_members=max_members, + tier=user.tier, + ) + self.db.add(team) + await self.db.flush() + + member = TeamMember( + team_id=team.id, + user_id=owner_id, + role="owner", + status="active", + ) + self.db.add(member) + await self.db.flush() + + return await self._to_dict(team, include_members=True) + + async def get_team(self, team_id: str, user_id: str) -> Optional[Dict[str, Any]]: + result = await self.db.execute( + select(Team).where(Team.id == team_id) + ) + team = result.scalar_one_or_none() + if not team: + return None + + is_member = await self.db.execute( + select(TeamMember).where( + and_(TeamMember.team_id == team_id, TeamMember.user_id == user_id) + ) + ) + if not is_member.scalar_one_or_none(): + return None + + return await self._to_dict(team, include_members=True) + + async def list_user_teams(self, user_id: str) -> List[Dict[str, Any]]: + member_result = await self.db.execute( + select(TeamMember.team_id).where(TeamMember.user_id == user_id) + ) + team_ids = [r[0] for r in member_result.all()] + + if not team_ids: + return [] + + result = await self.db.execute( + select(Team).where(Team.id.in_(team_ids), Team.is_active == True) + ) + teams = result.scalars().all() + + return [await self._to_dict(t) for t in teams] + + async def invite_member(self, team_id: str, owner_id: str, user_id: str) -> Dict[str, Any]: + team_result = await self.db.execute( + select(Team).where(and_(Team.id == team_id, Team.owner_id == owner_id)) + ) + team = team_result.scalar_one_or_none() + if not team: + raise ValueError("Team not found or not authorized") + + member_count = await self.db.execute( + select(func.count(TeamMember.id)).where( + and_(TeamMember.team_id == team_id, TeamMember.status == "active") + ) + ) + if (member_count.scalar() or 0) >= team.max_members: + raise ValueError("Team member limit reached") + + existing = await self.db.execute( + select(TeamMember).where( + and_(TeamMember.team_id == team_id, TeamMember.user_id == user_id) + ) + ) + if existing.scalar_one_or_none(): + raise ValueError("User is already a member") + + member = TeamMember( + team_id=team_id, + user_id=user_id, + role="member", + invited_by=owner_id, + status="active", + ) + self.db.add(member) + await self.db.flush() + + return {"user_id": user_id, "role": "member", "status": "active"} + + async def remove_member(self, team_id: str, owner_id: str, user_id: str) -> bool: + team_result = await self.db.execute( + select(Team).where(and_(Team.id == team_id, Team.owner_id == owner_id)) + ) + team = team_result.scalar_one_or_none() + if not team: + return False + + result = await self.db.execute( + select(TeamMember).where( + and_(TeamMember.team_id == team_id, TeamMember.user_id == user_id) + ) + ) + member = result.scalar_one_or_none() + if not member or member.role == "owner": + return False + + await self.db.delete(member) + return True + + async def leave_team(self, team_id: str, user_id: str) -> bool: + result = await self.db.execute( + select(TeamMember).where( + and_(TeamMember.team_id == team_id, TeamMember.user_id == user_id) + ) + ) + member = result.scalar_one_or_none() + if not member or member.role == "owner": + return False + + await self.db.delete(member) + return True + + async def update_role(self, team_id: str, owner_id: str, user_id: str, role: str) -> bool: + team_result = await self.db.execute( + select(Team).where(and_(Team.id == team_id, Team.owner_id == owner_id)) + ) + if not team_result.scalar_one_or_none(): + return False + + result = await self.db.execute( + select(TeamMember).where( + and_(TeamMember.team_id == team_id, TeamMember.user_id == user_id) + ) + ) + member = result.scalar_one_or_none() + if not member or member.role == "owner": + return False + + member.role = role + await self.db.flush() + return True + + async def _to_dict(self, team: Team, include_members: bool = False) -> Dict[str, Any]: + result = { + "id": str(team.id), + "name": team.name, + "owner_id": str(team.owner_id), + "description": team.description, + "tier": team.tier, + "is_active": team.is_active, + "created_at": team.created_at.isoformat() if team.created_at else None, + } + + if include_members: + members_result = await self.db.execute( + select(TeamMember).where(TeamMember.team_id == team.id) + ) + members = members_result.scalars().all() + result["members"] = [ + { + "user_id": str(m.user_id), + "role": m.role, + "status": m.status, + "joined_at": m.joined_at.isoformat() if m.joined_at else None, + } + for m in members + ] + result["member_count"] = len([m for m in members if m.status == "active"]) + + return result diff --git a/backend/app/services/translation.py b/backend/app/services/translation.py index 621b0e4..339f678 100644 --- a/backend/app/services/translation.py +++ b/backend/app/services/translation.py @@ -47,6 +47,7 @@ class TranslationService: async def generate_reply( self, inquiry: str, context: Optional[Dict[str, Any]] = None, tone: str = "professional", count: int = 3, + preference_context: Optional[str] = None, ) -> List[Dict[str, Any]]: similar = await self.corpus.find_similar(inquiry, "reply") if similar and count > 1: @@ -57,7 +58,7 @@ class TranslationService: for t in tones: try: - result = await self.ai.reply(inquiry, context, t) + result = await self.ai.reply(inquiry, context, t, preference_context) results.append({ "reply": result.get("reply", ""), "tone": t, diff --git a/backend/app/services/tts.py b/backend/app/services/tts.py new file mode 100644 index 0000000..2309075 --- /dev/null +++ b/backend/app/services/tts.py @@ -0,0 +1,50 @@ +from typing import Optional +import logging + +logger = logging.getLogger(__name__) + +try: + import edge_tts + HAS_EDGE_TTS = True +except ImportError: + HAS_EDGE_TTS = False + logger.warning("edge-tts not installed, TTS disabled") + +VOICE_MAP = { + "zh": "zh-CN-XiaoxiaoNeural", + "en": "en-US-AriaNeural", + "ja": "ja-JP-NanamiNeural", + "ko": "ko-KR-SunHiNeural", + "fr": "fr-FR-DeniseNeural", + "de": "de-DE-KatjaNeural", + "es": "es-ES-ElviraNeural", + "pt": "pt-BR-FranciscaNeural", + "ru": "ru-RU-SvetlanaNeural", + "ar": "ar-SA-ZariyahNeural", +} + +SUPPORTED_LANGS = list(VOICE_MAP.keys()) + + +class TextToSpeechService: + @staticmethod + async def synthesize(text: str, lang: str = "en", rate: str = "0%", pitch: str = "0Hz") -> Optional[bytes]: + if not HAS_EDGE_TTS: + logger.warning("edge-tts not available") + return None + + voice = VOICE_MAP.get(lang, VOICE_MAP["en"]) + + try: + communicate = edge_tts.Communicate(text, voice, rate=rate, pitch=pitch) + audio_data = b"" + async for chunk in communicate.stream(): + if chunk["type"] == "audio": + audio_data += chunk["data"] + return audio_data if audio_data else None + except Exception as e: + logger.error(f"TTS failed: {e}") + return None + + +tts_service = TextToSpeechService() diff --git a/backend/app/services/wechat.py b/backend/app/services/wechat.py new file mode 100644 index 0000000..7fb2b6d --- /dev/null +++ b/backend/app/services/wechat.py @@ -0,0 +1,80 @@ +from typing import Optional, Dict, Any +import httpx +import logging +from app.config import settings + +logger = logging.getLogger(__name__) + + +class WeChatService: + def __init__(self): + self.app_id = settings.WECHAT_APP_ID + self.app_secret = settings.WECHAT_APP_SECRET + self.api_base = "https://api.weixin.qq.com" + + async def code2session(self, js_code: str) -> Optional[Dict[str, Any]]: + if not self.app_id or not self.app_secret: + logger.warning("WeChat not configured") + return None + + async with httpx.AsyncClient() as client: + resp = await client.get( + f"{self.api_base}/sns/jscode2session", + params={ + "appid": self.app_id, + "secret": self.app_secret, + "js_code": js_code, + "grant_type": "authorization_code", + }, + timeout=10, + ) + data = resp.json() + + if data.get("errcode", 0) != 0: + logger.error(f"WeChat code2session failed: {data}") + return None + + return { + "openid": data.get("openid"), + "session_key": data.get("session_key"), + "unionid": data.get("unionid"), + } + + async def get_phone_number(self, code: str) -> Optional[str]: + if not self.app_id or not self.app_secret: + return None + + access_token = await self._get_access_token() + if not access_token: + return None + + async with httpx.AsyncClient() as client: + resp = await client.post( + f"{self.api_base}/wxa/business/getuserphonenumber", + params={"access_token": access_token}, + json={"code": code}, + timeout=10, + ) + data = resp.json() + if data.get("errcode", 0) != 0: + logger.error(f"WeChat getPhoneNumber failed: {data}") + return None + + return data.get("phone_info", {}).get("phoneNumber") + + async def _get_access_token(self) -> Optional[str]: + async with httpx.AsyncClient() as client: + resp = await client.get( + f"{self.api_base}/cgi-bin/token", + params={ + "grant_type": "client_credential", + "appid": self.app_id, + "secret": self.app_secret, + }, + timeout=10, + ) + data = resp.json() + return data.get("access_token") + + +wechat_service = WeChatService() diff --git a/backend/app/services/whatsapp.py b/backend/app/services/whatsapp.py index d84302f..fc5b4f5 100644 --- a/backend/app/services/whatsapp.py +++ b/backend/app/services/whatsapp.py @@ -85,6 +85,48 @@ class WhatsAppService: ) return resp.status_code == 200 + async def send_media(self, to: str, media_url: str, media_type: str = "image", caption: Optional[str] = None) -> bool: + if not self.api_token or not self.phone_number_id: + return False + + body = { + "messaging_product": "whatsapp", + "to": to, + "type": media_type, + media_type: {"link": media_url}, + } + if caption: + body[media_type]["caption"] = caption + + async with httpx.AsyncClient() as client: + resp = await client.post( + f"{self.api_base}/messages", + headers={"Authorization": f"Bearer {self.api_token}", "Content-Type": "application/json"}, + json=body, + timeout=30, + ) + if resp.status_code != 200: + logger.error(f"WhatsApp media send failed: {resp.text}") + return False + return True + + async def mark_as_read(self, message_id: str) -> bool: + if not self.api_token: + return False + + async with httpx.AsyncClient() as client: + resp = await client.post( + f"{self.api_base}/messages", + headers={"Authorization": f"Bearer {self.api_token}", "Content-Type": "application/json"}, + json={ + "messaging_product": "whatsapp", + "status": "read", + "message_id": message_id, + }, + timeout=10, + ) + return resp.status_code == 200 + def parse_webhook(self, body: Dict) -> Optional[Dict]: try: entry = body.get("entry", [{}])[0] @@ -96,14 +138,29 @@ class WhatsAppService: return None msg = messages[0] + msg_type = msg.get("type", "text") + content = "" + + if msg_type == "text": + content = msg.get("text", {}).get("body", "") + elif msg_type in ("image", "document", "audio", "video"): + media = msg.get(msg_type, {}) + content = media.get("caption", "") or media.get("filename", "") or f"[{msg_type}]" + return { "from": msg.get("from"), - "text": msg.get("text", {}).get("body", ""), + "text": content, "msg_id": msg.get("id"), "timestamp": msg.get("timestamp"), - "type": msg.get("type", "text"), + "type": msg_type, "profile_name": value.get("contacts", [{}])[0].get("profile", {}).get("name"), } except Exception as e: logger.warning(f"Failed to parse WhatsApp webhook: {e}") return None + + def _build_headers(self) -> Dict[str, str]: + return { + "Authorization": f"Bearer {self.api_token}", + "Content-Type": "application/json", + } diff --git a/backend/app/workers/tasks.py b/backend/app/workers/tasks.py index fd6d4a2..4b7a14f 100644 --- a/backend/app/workers/tasks.py +++ b/backend/app/workers/tasks.py @@ -10,6 +10,9 @@ logger = logging.getLogger(__name__) def check_silent_customers(): from app.database import AsyncSessionLocal from app.models.customer import Customer + from app.models.user import User + from app.services.push import PushService + from app.services.notification import NotificationService async def _check(): async with AsyncSessionLocal() as db: @@ -27,12 +30,26 @@ def check_silent_customers(): ) customers = result.scalars().all() for c in customers: - if days == 3: - logger.info(f"Customer {c.name} silent for 3 days") - elif days == 7: - logger.info(f"Customer {c.name} silent for 7 days - upgrade") - else: - logger.info(f"Customer {c.name} silent for 14 days - recommend new approach") + messages = { + 3: ("跟进提醒", f"客户 {c.name} 已沉默3天，建议发送跟进消息"), + 7: ("跟进升级", f"客户 {c.name} 已沉默1周，建议发送优惠或新产品信息"), + 14: ("跟进提示", f"客户 {c.name} 已沉默14天，建议换话题重新接触"), + } + title, content = messages.get(days, ("跟进提醒", f"客户 {c.name} 已沉默{days}天")) + logger.info(f"Customer {c.name} silent for {days} days") + + user_result = await db.execute( + select(User).where(User.id == c.user_id) + ) + user = user_result.scalar_one_or_none() + if user: + PushService.send_notification(c.user_id, title, content) + await NotificationService.create_notification( + db, c.user_id, title, content, + notification_type="customer_silent", + reference_type="customer", + reference_id=str(c.id), + ) import asyncio asyncio.run(_check()) @@ -59,6 +76,8 @@ def batch_translate_texts(texts: list, target_lang: str, user_id: str): def generate_quotation_pdf(quotation_id: str): from app.database import AsyncSessionLocal from app.models.quotation import Quotation, QuotationItem + from app.models.customer import Customer + from app.services.pdf_generator import pdf_generator async def _generate(): async with AsyncSessionLocal() as db: @@ -74,62 +93,60 @@ def generate_quotation_pdf(quotation_id: str): ) items = items_result.scalars().all() - pdf_content = generate_pdf_text(q, items) + customer = None + if q.customer_id: + cust_result = await db.execute( + select(Customer).where(Customer.id == q.customer_id) + ) + customer = cust_result.scalar_one_or_none() - return {"pdf_content": pdf_content, "quotation_id": str(q.id)} + data = { + "quotation_number": f"{str(q.id)[:8].upper()}", + "customer_name": customer.name if customer else "", + "customer_company": customer.company if customer else "", + "customer_country": customer.country if customer else "", + "date": q.created_at.strftime("%Y-%m-%d") if q.created_at else "", + "valid_until": q.valid_until or "", + "currency": q.currency or "USD", + "items": [ + { + "product_name": i.product_name, + "description": i.description, + "quantity": i.quantity, + "unit_price": i.unit_price, + "total_price": i.total_price, + "unit": i.unit or "pcs", + } + for i in items + ], + "subtotal": q.subtotal or 0, + "discount": q.discount or 0, + "shipping": q.shipping or 0, + "total": q.total or q.subtotal or 0, + "payment_terms": q.payment_terms or "", + "delivery_terms": q.delivery_terms or "", + "lead_time": q.lead_time or "", + "notes": q.notes or "", + } + + pdf_bytes = pdf_generator.generate_quotation(data) + + if pdf_bytes: + upload_dir = settings.UPLOAD_DIR + pdf_path = os.path.join(upload_dir, f"quotation_{quotation_id}.pdf") + os.makedirs(upload_dir, exist_ok=True) + with open(pdf_path, "wb") as f: + f.write(pdf_bytes) + q.pdf_url = pdf_path + await db.flush() + return {"success": True, "pdf_path": pdf_path, "quotation_id": str(q.id)} + else: + return {"error": "PDF generation failed (weasyprint not available)", "quotation_id": str(q.id)} import asyncio return asyncio.run(_generate()) -def generate_pdf_text(quotation, items): - from datetime import datetime - - lines = [ - "=" * 60, - f"QUOTATION", - f"#{str(quotation.id)[:8].upper()}", - "=" * 60, - f"Date: {datetime.utcnow().strftime('%Y-%m-%d')}", - ] - - if quotation.valid_until: - lines.append(f"Valid Until: {quotation.valid_until}") - - lines.append("") - lines.append(f"{'Item':<30} {'Qty':<8} {'Unit Price':<12} {'Total':<12}") - lines.append("-" * 62) - - for item in items: - lines.append( - f"{item.product_name:<30} {item.quantity:<8} ${item.unit_price:<10.2f} ${item.total_price:<10.2f}" - ) - - lines.append("-" * 62) - if quotation.subtotal: - lines.append(f"{'Subtotal':>48} ${quotation.subtotal:<10.2f}") - if quotation.discount: - lines.append(f"{'Discount':>48} -${quotation.discount:<10.2f}") - if quotation.shipping: - lines.append(f"{'Shipping':>48} ${quotation.shipping:<10.2f}") - lines.append(f"{'TOTAL':>48} ${quotation.total or quotation.subtotal or 0:<10.2f}") - - lines.append("") - if quotation.payment_terms: - lines.append(f"Payment Terms: {quotation.payment_terms}") - if quotation.delivery_terms: - lines.append(f"Delivery Terms: {quotation.delivery_terms}") - if quotation.lead_time: - lines.append(f"Lead Time: {quotation.lead_time}") - if quotation.notes: - lines.append(f"Notes: {quotation.notes}") - - lines.append("=" * 60) - lines.append("Generated by TradeMate") - - return "\n".join(lines) - - @shared_task def process_corpus_quality(): from app.database import AsyncSessionLocal @@ -155,6 +172,71 @@ def process_corpus_quality(): return asyncio.run(_process()) +@shared_task(bind=True, max_retries=3, default_retry_delay=60) +def process_customer_import(self, user_id: str, records: list): + from app.database import AsyncSessionLocal + from app.services.customer import CustomerService + + async def _import(): + async with AsyncSessionLocal() as db: + svc = CustomerService(db) + imported = 0 + errors = [] + for i, record in enumerate(records): + try: + await svc.create_customer(user_id, record) + imported += 1 + except Exception as e: + errors.append(f"Row {i+2}: {str(e)}") + return {"imported": imported, "total": len(records), "errors": errors} + + import asyncio + return asyncio.run(_import()) + + +@shared_task +def run_daily_corpus_training(): + from app.database import AsyncSessionLocal + from app.services.corpus_trainer import CorpusTrainer + + async def _train(): + async with AsyncSessionLocal() as db: + trainer = CorpusTrainer(db) + result = await trainer.run_pipeline() + logger.info(f"Daily corpus training complete: {result}") + return result + + import asyncio + return asyncio.run(_train()) + + +@shared_task +def update_customer_health_cache(): + from app.database import AsyncSessionLocal + from app.services.customer_health import CustomerHealthService + from app.models.user import User + from app.config import settings + + async def _update(): + async with AsyncSessionLocal() as db: + result = await db.execute(select(User.id)) + user_ids = result.scalars().all() + + svc = CustomerHealthService(db) + + for uid in user_ids: + try: + overview = await svc.get_health_overview(uid) + scores = await svc.get_all_health_scores(uid) + except Exception as e: + logger.error(f"Health cache failed for user {uid}: {e}") + + return f"Updated health cache for {len(user_ids)} users" + + import asyncio + return asyncio.run(_update()) + + @shared_task def cleanup_old_sessions(): import redis.asyncio as aioredis @@ -190,4 +272,20 @@ def send_followup_reminder(customer_id: str, user_id: str): return {"error": "Customer not found"} import asyncio - return asyncio.run(_send()) \ No newline at end of file + return asyncio.run(_send()) + + +@shared_task +def check_followup_engine(): + from app.database import AsyncSessionLocal + from app.services.followup_engine import FollowupEngine + + async def _check(): + async with AsyncSessionLocal() as db: + engine = FollowupEngine(db) + result = await engine.scan_and_followup() + logger.info(f"Followup engine check complete: {result}") + return result + + import asyncio + return asyncio.run(_check()) \ No newline at end of file diff --git a/backend/requirements.txt b/backend/requirements.txt index 7e6d855..b04745b 100644 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -1,19 +1,22 @@ -fastapi==0.79.0 -uvicorn==0.19.0 +fastapi==0.100.0 +uvicorn==0.23.2 sqlalchemy==1.4.48 asyncpg==0.27.0 pydantic==1.10.12 -pydantic-settings==1.1.2 python-jose[cryptography]==3.3.0 passlib[bcrypt]==1.7.4 python-multipart==0.0.6 redis==4.5.5 celery==5.2.7 httpx==0.23.3 -openai==0.27.8 +openai==1.12.0 anthropic==0.8.1 jinja2==3.1.2 alembic==1.11.3 +sentry-sdk==2.3.1 pytest==7.4.3 pytest-asyncio==0.21.1 -pytest-cov==4.1.0 \ No newline at end of file +pytest-cov==4.1.0 +weasyprint==60.2 +openpyxl==3.1.2 +edge-tts>=6.0.0 \ No newline at end of file diff --git a/backend/tests/test_config.py b/backend/tests/test_config.py index ce48041..38a74cb 100644 --- a/backend/tests/test_config.py +++ b/backend/tests/test_config.py @@ -17,8 +17,8 @@ class TestConfig: assert "translate" in settings.AI_ROUTING assert "reply" in settings.AI_ROUTING assert "marketing" in settings.AI_ROUTING - assert settings.AI_ROUTING["translate"]["primary"] == "deepl" - assert settings.AI_ROUTING["reply"]["primary"] == "openai" + assert "extract" in settings.AI_ROUTING + assert "primary" in settings.AI_ROUTING["translate"] def test_free_tier_limits(self): assert settings.FREE_DAILY_TRANSLATE_CHARS == 5000 diff --git a/backend/tests/test_customer_health.py b/backend/tests/test_customer_health.py new file mode 100644 index 0000000..39342d4 --- /dev/null +++ b/backend/tests/test_customer_health.py @@ -0,0 +1,273 @@ +import pytest +from datetime import datetime, timedelta +from app.services.customer_health import CustomerHealthService + + +class TestSilenceScore: + def test_no_contact_returns_max_days(self): + assert CustomerHealthService.silence_days(None) == 999 + + def test_recent_contact_returns_0_days(self): + now = datetime.utcnow() + assert CustomerHealthService.silence_days(now) == 0 + + def test_3_days_ago(self): + dt = datetime.utcnow() - timedelta(days=3) + assert CustomerHealthService.silence_days(dt) == 3 + + def test_silence_score_0_days(self): + assert CustomerHealthService.calculate_silence_score(datetime.utcnow()) == 100 + + def test_silence_score_7_days(self): + dt = datetime.utcnow() - timedelta(days=7) + score = CustomerHealthService.calculate_silence_score(dt) + assert score == 50 + + def test_silence_score_14_days(self): + dt = datetime.utcnow() - timedelta(days=14) + score = CustomerHealthService.calculate_silence_score(dt) + assert score == 0 + + def test_silence_score_21_days_clamped(self): + dt = datetime.utcnow() - timedelta(days=21) + score = CustomerHealthService.calculate_silence_score(dt) + assert score == 0 + + +class TestStatusWeight: + def test_customer_status(self): + assert CustomerHealthService.status_weight("customer") == 100 + + def test_negotiating_status(self): + assert CustomerHealthService.status_weight("negotiating") == 70 + + def test_lead_status(self): + assert CustomerHealthService.status_weight("lead") == 40 + + def test_lost_status(self): + assert CustomerHealthService.status_weight("lost") == 10 + + def test_unknown_status_defaults(self): + assert CustomerHealthService.status_weight("unknown") == 40 + + def test_none_status_defaults(self): + assert CustomerHealthService.status_weight(None) == 40 + + +class TestGrade: + def test_active_grade(self): + assert CustomerHealthService.grade(100) == "active" + assert CustomerHealthService.grade(80) == "active" + assert CustomerHealthService.grade(85) == "active" + + def test_watch_grade(self): + assert CustomerHealthService.grade(79) == "watch" + assert CustomerHealthService.grade(50) == "watch" + assert CustomerHealthService.grade(65) == "watch" + + def test_critical_grade(self): + assert CustomerHealthService.grade(49) == "critical" + assert CustomerHealthService.grade(0) == "critical" + assert CustomerHealthService.grade(30) == "critical" + + +class TestResponseScore: + def test_both_none(self): + r = CustomerHealthService.calc_response_score(None, None) + assert r["score"] == 50 + assert r["trend"] == "stable" + + def test_only_recent_exists(self): + r = CustomerHealthService.calc_response_score(2.0, None) + assert r["score"] == 90 + assert r["trend"] == "stable" + + def test_improving_faster_response(self): + r = CustomerHealthService.calc_response_score(2.0, 10.0) + assert r["score"] == 90 + assert r["trend"] == "improving" + + def test_declining_slower_response(self): + r = CustomerHealthService.calc_response_score(10.0, 2.0) + assert r["trend"] == "declining" + + def test_fast_response_high_score(self): + r = CustomerHealthService.calc_response_score(0.5, 5.0) + assert r["score"] >= 95 + assert r["trend"] == "improving" + + def test_very_slow_response_low_score(self): + r = CustomerHealthService.calc_response_score(48.0, 2.0) + assert r["score"] == 0 + assert r["trend"] == "declining" + + +class TestSentimentScore: + def test_empty_messages_neutral(self): + r = CustomerHealthService.calc_sentiment_score([]) + assert r["score"] == 50 + assert r["label"] == "neutral" + + def test_positive_message(self): + r = CustomerHealthService.calc_sentiment_score(["yes I'm interested thanks"]) + assert r["score"] == 80 + assert r["label"] == "positive" + + def test_negative_message(self): + r = CustomerHealthService.calc_sentiment_score(["no not interested too expensive"]) + assert r["score"] == 20 + assert r["label"] == "negative" + + def test_mixed_messages_neutral(self): + r = CustomerHealthService.calc_sentiment_score(["good quality", "but price is high"]) + assert r["score"] == 50 + assert r["label"] == "neutral" + + def test_more_positive_than_negative(self): + r = CustomerHealthService.calc_sentiment_score([ + "great product", + "yes please proceed", + "but shipping is expensive", + ]) + assert r["score"] == 80 + assert r["label"] == "positive" + + +class TestInquiryDepthScore: + def test_empty_messages(self): + r = CustomerHealthService.calc_inquiry_depth_score([]) + assert r["score"] == 0 + assert r["signal_count"] == 0 + + def test_no_signals(self): + r = CustomerHealthService.calc_inquiry_depth_score(["hello", "how are you"]) + assert r["score"] == 0 + + def test_one_signal(self): + r = CustomerHealthService.calc_inquiry_depth_score(["what is your price"]) + assert r["score"] == 50 + assert r["signal_count"] >= 1 + + def test_multiple_signals(self): + r = CustomerHealthService.calc_inquiry_depth_score([ + "what is your MOQ and FOB price", + "do you have certification", + "what is the lead time", + ]) + assert r["score"] >= 75 + assert r["signal_count"] >= 3 + + def test_deduplicates_signals(self): + r = CustomerHealthService.calc_inquiry_depth_score([ + "what is the price", + "please send price and MOQ", + ]) + assert r["signal_count"] == 2 + + +class TestBusinessValueScore: + def test_zero_value(self): + r = CustomerHealthService.calc_business_value_score(0) + assert r["score"] == 0 + + def test_small_value(self): + r = CustomerHealthService.calc_business_value_score(500) + assert r["score"] == 20 + + def test_medium_value(self): + r = CustomerHealthService.calc_business_value_score(5000) + assert r["score"] == 40 + + def test_large_value(self): + r = CustomerHealthService.calc_business_value_score(50000) + assert r["score"] == 80 + + def test_very_large_value(self): + r = CustomerHealthService.calc_business_value_score(200000) + assert r["score"] == 100 + + +class TestTotalScore: + def test_perfect_health(self): + dims = { + "response_trend": {"score": 100}, + "sentiment": {"score": 100}, + "inquiry_depth": {"score": 100}, + "silence": {"score": 100}, + "business_value": {"score": 100}, + } + r = CustomerHealthService.calc_total_score(dims) + assert r["total_score"] == 100 + assert r["grade"] == "active" + + def test_zero_health(self): + dims = { + "response_trend": {"score": 0}, + "sentiment": {"score": 0}, + "inquiry_depth": {"score": 0}, + "silence": {"score": 0}, + "business_value": {"score": 0}, + } + r = CustomerHealthService.calc_total_score(dims) + assert r["total_score"] == 0 + assert r["grade"] == "critical" + + def test_mid_health(self): + dims = { + "response_trend": {"score": 60}, + "sentiment": {"score": 50}, + "inquiry_depth": {"score": 50}, + "silence": {"score": 40}, + "business_value": {"score": 50}, + } + r = CustomerHealthService.calc_total_score(dims) + assert 45 <= r["total_score"] <= 55 + + +class TestSuggestion: + def test_active_suggestion(self): + s = CustomerHealthService.suggestion("active", 1, "lead") + assert "良好" in s + + def test_watch_with_silence(self): + s = CustomerHealthService.suggestion("watch", 5, "lead") + assert "5天" in s + assert "跟进" in s + + def test_watch_no_silence(self): + s = CustomerHealthService.suggestion("watch", 1, "lead") + assert "关注" in s + + def test_critical_lead(self): + s = CustomerHealthService.suggestion("critical", 10, "lead") + assert "10天" in s + assert "跟进" in s + + def test_critical_lost(self): + s = CustomerHealthService.suggestion("critical", 20, "lost") + assert "重新激活" in s + + +class TestHealthOverview: + def test_overview_empty(self): + overview = CustomerHealthService._calculate_overview_static([]) + assert overview["total"] == 0 + assert overview["active"] == 0 + assert overview["watch"] == 0 + assert overview["critical"] == 0 + + def test_overview_mixed(self, monkeypatch): + class Row: + def __init__(self, status, days_ago): + self.status = status + self.last_contact_at = datetime.utcnow() - timedelta(days=days_ago) + + rows = [ + Row("customer", 1), + Row("lead", 7), + Row("negotiating", 14), + Row("lost", 30), + ] + overview = CustomerHealthService._calculate_overview_static(rows) + assert overview["total"] == 4 + assert overview["active"] == 1 diff --git a/backend/tests/test_p0_basics.py b/backend/tests/test_p0_basics.py new file mode 100644 index 0000000..cb3172b --- /dev/null +++ b/backend/tests/test_p0_basics.py @@ -0,0 +1,95 @@ +import pytest +from httpx import AsyncClient +from app.core.security import create_access_token +from app.models.user import User +import uuid + + +class TestAdminAPI: + async def test_admin_dashboard_unauthorized(self, client: AsyncClient): + response = await client.get("/api/v1/admin/dashboard") + assert response.status_code == 401 + + async def test_admin_dashboard_forbidden_non_admin(self, client: AsyncClient, test_user): + token = create_access_token({"sub": str(test_user.id), "tier": "free", "role": "user"}) + response = await client.get( + "/api/v1/admin/dashboard", + headers={"Authorization": f"Bearer {token}"}, + ) + assert response.status_code == 403 + + async def test_admin_dashboard_success(self, client: AsyncClient, test_user): + test_user.role = "admin" + token = create_access_token({"sub": str(test_user.id), "tier": "free", "role": "admin"}) + response = await client.get( + "/api/v1/admin/dashboard", + headers={"Authorization": f"Bearer {token}"}, + ) + assert response.status_code == 200 + data = response.json() + assert "total_users" in data + assert "paid_users" in data + + async def test_admin_list_users(self, client: AsyncClient, test_user): + test_user.role = "admin" + token = create_access_token({"sub": str(test_user.id), "tier": "free", "role": "admin"}) + response = await client.get( + "/api/v1/admin/users", + headers={"Authorization": f"Bearer {token}"}, + ) + assert response.status_code == 200 + data = response.json() + assert "items" in data + assert "total" in data + + async def test_admin_update_tier_forbidden_non_admin(self, client: AsyncClient, test_user): + target_id = str(uuid.uuid4()) + token = create_access_token({"sub": str(test_user.id), "tier": "free", "role": "user"}) + response = await client.patch( + f"/api/v1/admin/users/{target_id}/tier", + headers={"Authorization": f"Bearer {token}"}, + json={"tier": "pro"}, + ) + assert response.status_code == 403 + + +class TestRateLimit: + async def test_health_not_rate_limited(self, client: AsyncClient): + for _ in range(10): + response = await client.get("/health") + assert response.status_code == 200 + + async def test_rate_limit_headers_present(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/customers", headers=auth_headers) + assert "X-RateLimit-Remaining" in response.headers + assert "X-RateLimit-Limit" in response.headers + + +class TestUserRole: + async def test_user_default_role(self, client: AsyncClient, test_user): + assert test_user.role == "user" + + async def test_user_info_contains_role(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/auth/me", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "role" in data + assert data["role"] == "user" + + +class TestPrivacyTerms: + async def test_privacy_page_exists(self): + import os + path = os.path.join( + os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + "uni-app", "src", "pages", "agreement", "privacy.vue", + ) + assert os.path.exists(path), "privacy.vue not found" + + async def test_terms_page_exists(self): + import os + path = os.path.join( + os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + "uni-app", "src", "pages", "agreement", "terms.vue", + ) + assert os.path.exists(path), "terms.vue not found" diff --git a/backend/tests/test_p1_core_api.py b/backend/tests/test_p1_core_api.py new file mode 100644 index 0000000..a1f36fb --- /dev/null +++ b/backend/tests/test_p1_core_api.py @@ -0,0 +1,337 @@ +import pytest +from httpx import AsyncClient +from unittest.mock import patch, AsyncMock +from app.models.customer import Conversation, Message +from app.models.quotation import Quotation, QuotationItem +from app.models.user import Product +from datetime import datetime + + +class TestTranslateAPI: + async def test_translate_unauthorized(self, client: AsyncClient): + response = await client.post( + "/api/v1/translate", + json={"text": "Hello", "target_lang": "zh"}, + ) + assert response.status_code == 401 + + async def test_translate_success(self, client: AsyncClient, auth_headers): + with patch("app.services.translation.TranslationService.translate") as mock: + mock.return_value = { + "translated_text": "你好", + "source_lang": "en", + "provider_used": "mock", + "from_cache": False, + } + response = await client.post( + "/api/v1/translate", + headers=auth_headers, + json={"text": "Hello", "target_lang": "zh"}, + ) + assert response.status_code == 200 + data = response.json() + assert data["translated_text"] == "你好" + + async def test_translate_with_context(self, client: AsyncClient, auth_headers): + with patch("app.services.translation.TranslationService.translate") as mock: + mock.return_value = { + "translated_text": "FOB 上海 价格", + "source_lang": "en", + "provider_used": "mock", + } + response = await client.post( + "/api/v1/translate", + headers=auth_headers, + json={"text": "FOB Shanghai price", "target_lang": "zh", "context": "trade"}, + ) + assert response.status_code == 200 + + +class TestReplyAPI: + async def test_reply_unauthorized(self, client: AsyncClient): + response = await client.post( + "/api/v1/translate/reply", + json={"inquiry": "How much?", "tone": "professional"}, + ) + assert response.status_code == 401 + + async def test_reply_success(self, client: AsyncClient, auth_headers): + with patch("app.services.translation.TranslationService.generate_reply") as mock: + mock.return_value = [ + {"reply": "Thank you for your inquiry.", "tone": "professional", "provider": "mock"}, + {"reply": "Thanks for reaching out!", "tone": "friendly", "provider": "mock"}, + ] + response = await client.post( + "/api/v1/translate/reply", + headers=auth_headers, + json={"inquiry": "How much for 500 units?", "tone": "professional", "count": 2}, + ) + assert response.status_code == 200 + data = response.json() + assert len(data["suggestions"]) == 2 + assert data["count"] == 2 + + async def test_reply_with_context(self, client: AsyncClient, auth_headers): + with patch("app.services.translation.TranslationService.generate_reply") as mock: + mock.return_value = [{"reply": "Our price is $10/unit.", "tone": "professional", "provider": "mock"}] + response = await client.post( + "/api/v1/translate/reply", + headers=auth_headers, + json={ + "inquiry": "Price?", + "tone": "professional", + "count": 1, + "context": {"product": "Widget X", "price": "$10"}, + }, + ) + assert response.status_code == 200 + + +class TestExtractAPI: + async def test_extract_unauthorized(self, client: AsyncClient): + response = await client.post( + "/api/v1/translate/extract", + json={"text": "I want 500pcs of red widgets FOB Shanghai", "extract_type": "inquiry"}, + ) + assert response.status_code == 401 + + async def test_extract_success(self, client: AsyncClient, auth_headers): + with patch("app.services.translation.TranslationService.extract_info") as mock: + mock.return_value = { + "intent": "purchase", + "product_interest": "widgets", + "quantity": "500", + } + response = await client.post( + "/api/v1/translate/extract", + headers=auth_headers, + json={"text": "I want 500pcs of red widgets FOB Shanghai", "extract_type": "inquiry"}, + ) + assert response.status_code == 200 + data = response.json() + assert "extracted" in data + + +class TestTTSAPI: + async def test_tts_get_unauthorized(self, client: AsyncClient): + response = await client.get("/api/v1/translate/tts?text=hello&lang=en") + assert response.status_code == 401 + + async def test_tts_get_empty_text(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/translate/tts?text=&lang=en", headers=auth_headers) + assert response.status_code == 400 + + +class TestMarketingAPI: + async def test_marketing_unauthorized(self, client: AsyncClient): + response = await client.post( + "/api/v1/marketing/generate", + json={"product_name": "Widget", "description": "A great widget", "target": "US buyers"}, + ) + assert response.status_code == 401 + + async def test_marketing_success(self, client: AsyncClient, auth_headers): + with patch("app.services.marketing.MarketingService.generate") as mock: + mock.return_value = [ + {"content": "Buy our widget!", "style": "professional", "provider": "mock"}, + ] + response = await client.post( + "/api/v1/marketing/generate", + headers=auth_headers, + json={ + "product_name": "Widget X", + "description": "High quality widget", + "category": "tools", + "target": "US importers", + "style": "professional", + "count": 1, + }, + ) + assert response.status_code == 200 + data = response.json() + assert data["count"] >= 1 + assert "results" in data + + async def test_marketing_keywords(self, client: AsyncClient, auth_headers): + with patch("app.services.marketing.MarketingService.generate_keywords") as mock: + mock.return_value = ["widget", "tool", "quality"] + response = await client.post( + "/api/v1/marketing/keywords", + headers=auth_headers, + json={"product_name": "Widget", "description": "A widget", "count": 5}, + ) + assert response.status_code == 200 + assert "keywords" in response.json() + + +class TestProductAPI: + async def test_create_product(self, client: AsyncClient, auth_headers): + response = await client.post( + "/api/v1/products", + headers=auth_headers, + json={ + "name": "Test Product", + "description": "A test product", + "category": "electronics", + "price": "10.50", + "price_unit": "USD", + }, + ) + assert response.status_code == 200 + data = response.json() + assert data["name"] == "Test Product" + + async def test_list_products(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/products", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "items" in data + + async def test_update_product(self, client: AsyncClient, auth_headers, db_session, test_user): + product = Product( + user_id=test_user.id, + name="Old Name", + category="tools", + is_active=True, + ) + db_session.add(product) + await db_session.commit() + + response = await client.patch( + f"/api/v1/products/{product.id}", + headers=auth_headers, + json={"name": "New Name", "price": "20.00"}, + ) + assert response.status_code == 200 + assert response.json()["name"] == "New Name" + + async def test_delete_product(self, client: AsyncClient, auth_headers, db_session, test_user): + product = Product(user_id=test_user.id, name="To Delete") + db_session.add(product) + await db_session.commit() + pid = product.id + + response = await client.delete(f"/api/v1/products/{pid}", headers=auth_headers) + assert response.status_code == 200 + + response = await client.get(f"/api/v1/products/{pid}", headers=auth_headers) + assert response.status_code == 404 + + +class TestQuotationAPI: + async def test_create_quotation(self, client: AsyncClient, auth_headers, db_session, test_user): + from app.models.customer import Customer + customer = Customer(user_id=test_user.id, name="Test Buyer") + db_session.add(customer) + await db_session.commit() + + response = await client.post( + "/api/v1/quotations", + headers=auth_headers, + json={ + "customer_id": str(customer.id), + "title": "Test Quote", + "items": [ + {"product_name": "Widget", "quantity": 100, "unit_price": 10.0}, + ], + "currency": "USD", + "payment_terms": "T/T", + }, + ) + assert response.status_code == 200 + data = response.json() + assert data["title"] == "Test Quote" + assert len(data["items"]) == 1 + + async def test_list_quotations(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/quotations", headers=auth_headers) + assert response.status_code == 200 + assert "items" in response.json() + + async def test_quotation_pdf_not_found(self, client: AsyncClient, auth_headers): + import uuid + response = await client.get(f"/api/v1/quotations/{uuid.uuid4()}/pdf", headers=auth_headers) + assert response.status_code == 404 + + async def test_quotation_status_update(self, client: AsyncClient, auth_headers, db_session, test_user): + from app.models.customer import Customer + customer = Customer(user_id=test_user.id, name="Status Test Buyer") + db_session.add(customer) + await db_session.commit() + + q = Quotation(user_id=test_user.id, customer_id=customer.id, title="Status Test", status="draft") + db_session.add(q) + await db_session.commit() + + response = await client.patch( + f"/api/v1/quotations/{q.id}/status", + headers=auth_headers, + json={"status": "sent"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "sent" + + +class TestAnalyticsAPI: + async def test_overview(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/analytics/overview", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "customers" in data + assert "translations" in data + assert "quotations" in data + assert "messages" in data + assert "marketing" in data + + async def test_customer_analytics(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/analytics/customers", headers=auth_headers) + assert response.status_code == 200 + + async def test_marketing_analytics(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/analytics/marketing", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "total_events" in data + + +class TestOnboardingAPI: + async def test_onboarding_status(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/onboarding/status", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "completed" in data + assert "product_count" in data + + async def test_onboarding_create_product(self, client: AsyncClient, auth_headers): + with patch("app.services.onboarding.OnboardingService.create_product") as mock: + mock.return_value = { + "id": "mock-id", + "name": "Onboarded Product", + "marketing_contents": [], + "keywords": [], + } + response = await client.post( + "/api/v1/onboarding/product", + headers=auth_headers, + json={ + "name": "New Product", + "description": "Desc", + "category": "tools", + "target": "US buyers", + }, + ) + assert response.status_code == 200 + assert response.json()["name"] == "Onboarded Product" + + +class TestExportAPI: + async def test_export_customers_csv(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/customers/export/csv", headers=auth_headers) + assert response.status_code == 200 + assert response.headers["content-type"] == "text/csv" + assert "customers.csv" in response.headers["content-disposition"] + + async def test_export_quotations_csv(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/quotations/export/csv", headers=auth_headers) + assert response.status_code == 200 + assert response.headers["content-type"] == "text/csv" diff --git a/backend/tests/test_p2_enhancements.py b/backend/tests/test_p2_enhancements.py new file mode 100644 index 0000000..efe14dd --- /dev/null +++ b/backend/tests/test_p2_enhancements.py @@ -0,0 +1,156 @@ +import pytest +from httpx import AsyncClient +from app.models.notification import Notification +from app.models.feedback import Feedback + + +class TestNotificationAPI: + async def test_list_notifications_empty(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/notifications", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "items" in data + assert data["items"] == [] + + async def test_unread_count_zero(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/notifications/unread-count", headers=auth_headers) + assert response.status_code == 200 + assert response.json()["count"] == 0 + + async def test_create_and_list_notification(self, client: AsyncClient, auth_headers, db_session, test_user): + n = Notification( + user_id=test_user.id, + title="Test Title", + content="Test Content", + ) + db_session.add(n) + await db_session.commit() + + response = await client.get("/api/v1/notifications", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert len(data["items"]) >= 1 + assert data["items"][0]["title"] == "Test Title" + + async def test_mark_read(self, client: AsyncClient, auth_headers, db_session, test_user): + n = Notification(user_id=test_user.id, title="Read Test", content="Content") + db_session.add(n) + await db_session.commit() + + response = await client.patch( + f"/api/v1/notifications/{n.id}/read", + headers=auth_headers, + ) + assert response.status_code == 200 + + count_resp = await client.get("/api/v1/notifications/unread-count", headers=auth_headers) + assert count_resp.json()["count"] == 0 + + async def test_mark_all_read(self, client: AsyncClient, auth_headers, db_session, test_user): + for i in range(3): + db_session.add(Notification(user_id=test_user.id, title=f"Notif {i}", content="Content")) + await db_session.commit() + + response = await client.post("/api/v1/notifications/read-all", headers=auth_headers) + assert response.status_code == 200 + assert response.json()["count"] == 3 + + async def test_delete_notification(self, client: AsyncClient, auth_headers, db_session, test_user): + n = Notification(user_id=test_user.id, title="Delete Me", content="Content") + db_session.add(n) + await db_session.commit() + nid = n.id + + response = await client.delete(f"/api/v1/notifications/{nid}", headers=auth_headers) + assert response.status_code == 200 + + list_resp = await client.get("/api/v1/notifications", headers=auth_headers) + ids = [item["id"] for item in list_resp.json()["items"]] + assert str(nid) not in ids + + async def test_delete_not_found(self, client: AsyncClient, auth_headers): + import uuid + response = await client.delete( + f"/api/v1/notifications/{uuid.uuid4()}", + headers=auth_headers, + ) + assert response.status_code == 404 + + async def test_unread_count_after_read(self, client: AsyncClient, auth_headers, db_session, test_user): + for i in range(2): + db_session.add(Notification(user_id=test_user.id, title=f"Unread {i}", content="C")) + await db_session.commit() + + resp = await client.get("/api/v1/notifications/unread-count", headers=auth_headers) + assert resp.json()["count"] == 2 + + async def test_unread_only_filter(self, client: AsyncClient, auth_headers, db_session, test_user): + n1 = Notification(user_id=test_user.id, title="Read", content="C", is_read=True) + n2 = Notification(user_id=test_user.id, title="Unread", content="C") + db_session.add_all([n1, n2]) + await db_session.commit() + + response = await client.get( + "/api/v1/notifications?unread_only=true", + headers=auth_headers, + ) + assert response.status_code == 200 + for item in response.json()["items"]: + assert item["is_read"] is False + + +class TestFeedbackAPI: + async def test_submit_feedback(self, client: AsyncClient, auth_headers): + response = await client.post( + "/api/v1/feedback", + headers=auth_headers, + json={ + "content": "Great app!", + "category": "feature", + "contact": "test@example.com", + }, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ok" + + async def test_submit_feedback_minimal(self, client: AsyncClient, auth_headers): + response = await client.post( + "/api/v1/feedback", + headers=auth_headers, + json={"content": "Bug report"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ok" + + async def test_submit_feedback_unauthorized(self, client: AsyncClient): + response = await client.post( + "/api/v1/feedback", + json={"content": "Test"}, + ) + assert response.status_code == 401 + + +class TestPaymentAPI: + async def test_get_plans(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/payment/plans", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "plans" in data + assert len(data["plans"]) >= 3 + + async def test_get_subscription_free(self, client: AsyncClient, auth_headers): + response = await client.get("/api/v1/payment/subscription", headers=auth_headers) + assert response.status_code == 200 + data = response.json() + assert "plan" in data + assert "status" in data + + async def test_create_order(self, client: AsyncClient, auth_headers): + response = await client.post( + "/api/v1/payment/create-order", + headers=auth_headers, + json={"plan": "pro"}, + ) + assert response.status_code == 200 + data = response.json() + assert "prepay_id" in data or "order_id" in data or "url" in data diff --git a/backend/tests/test_p3_ai_features.py b/backend/tests/test_p3_ai_features.py new file mode 100644 index 0000000..93cb439 --- /dev/null +++ b/backend/tests/test_p3_ai_features.py @@ -0,0 +1,9 @@ +import pytest +from httpx import AsyncClient +from unittest.mock import patch, AsyncMock +from app.models.customer import Conversation, Message, Customer +from app.models.preference import PreferenceAnalysis, MarketingEffect +from app.models.user import Product +from datetime import datetime + + diff --git a/backend/tests/test_p3_corpus.py b/backend/tests/test_p3_corpus.py new file mode 100644 index 0000000..f83b611 --- /dev/null +++ b/backend/tests/test_p3_corpus.py @@ -0,0 +1,139 @@ +import pytest +from unittest.mock import patch, AsyncMock +from app.services.corpus_trainer import CorpusTrainer +from app.models.corpus import CorpusEntry +from datetime import datetime + + +class TestCorpusTrainer: + async def test_get_stats_empty(self, db_session): + trainer = CorpusTrainer(db_session) + stats = await trainer.get_stats() + assert stats["total_entries"] == 0 + assert stats["with_embeddings"] == 0 + + async def test_get_stats_with_data(self, db_session): + entries = [ + CorpusEntry(source_text="Hello", target_text="你好", task_type="translate", quality_score=0.8), + CorpusEntry(source_text="Goodbye", target_text="再见", task_type="translate", quality_score=0.6), + ] + for e in entries: + db_session.add(e) + await db_session.commit() + + trainer = CorpusTrainer(db_session) + stats = await trainer.get_stats() + assert stats["total_entries"] == 2 + assert stats["by_task_type"]["translate"] == 2 + assert stats["high_quality"] == 1 + assert stats["low_quality"] == 0 + + async def test_score_entries(self, db_session): + entries = [ + CorpusEntry(source_text="Hello world", target_text="你好世界", task_type="translate"), + CorpusEntry(source_text="Hi", target_text="嗨", task_type="translate"), + ] + for e in entries: + db_session.add(e) + await db_session.commit() + + trainer = CorpusTrainer(db_session) + result = await trainer.score_entries(batch_size=10) + assert result["processed"] == 2 + assert result["updated"] == 2 + + for e in entries: + await db_session.refresh(e) + assert e.quality_score is not None + assert 0.0 <= e.quality_score <= 1.0 + + async def test_deduplicate(self, db_session): + from datetime import datetime + e1 = CorpusEntry( + source_text="Duplicate text", target_text="重复文本", + task_type="translate", quality_score=0.8, + created_at=datetime.utcnow(), + ) + e2 = CorpusEntry( + source_text="Duplicate text", target_text="重复文本", + task_type="translate", quality_score=0.7, + created_at=datetime.utcnow(), + ) + db_session.add_all([e1, e2]) + await db_session.commit() + + trainer = CorpusTrainer(db_session) + result = await trainer.deduplicate() + assert result["duplicates_removed"] == 1 + + stats = await trainer.get_stats() + assert stats["total_entries"] == 1 + + async def test_prune_low_quality(self, db_session): + from datetime import timedelta + old = datetime.utcnow() - timedelta(days=100) + entry = CorpusEntry( + source_text="x", target_text="y", + task_type="translate", quality_score=0.1, + created_at=old, usage_count=0, + ) + db_session.add(entry) + await db_session.commit() + + trainer = CorpusTrainer(db_session) + result = await trainer.prune_low_quality(min_score=0.2, max_age_days=30) + assert result["pruned"] == 1 + + stats = await trainer.get_stats() + assert stats["total_entries"] == 0 + + async def test_run_pipeline(self, db_session): + trainer = CorpusTrainer(db_session) + result = await trainer.run_pipeline() + assert "deduplication" in result + assert "scoring" in result + assert "embeddings" in result + assert "pruning" in result + assert "stats" in result + + def test_calculate_quality_score_with_rating(self, db_session): + trainer = CorpusTrainer(db_session) + entry = CorpusEntry( + source_text="Good source text with enough length", + target_text="Good target text with enough length", + task_type="translate", + user_rating=4, + ) + score = trainer._calculate_quality_score(entry) + assert 0.7 <= score <= 1.0 + + def test_calculate_quality_score_short_text(self, db_session): + trainer = CorpusTrainer(db_session) + entry = CorpusEntry( + source_text="ab", target_text="cd", + task_type="translate", + ) + score = trainer._calculate_quality_score(entry) + assert score < 0.5 + + def test_calculate_quality_score_with_usage(self, db_session): + trainer = CorpusTrainer(db_session) + entry = CorpusEntry( + source_text="Good source text here with proper length", + target_text="Good target text here with proper length", + task_type="translate", + usage_count=10, + ) + score = trainer._calculate_quality_score(entry) + assert score >= 0.6 + + async def test_embedding_generation_skipped_without_key(self, db_session): + from app.config import settings + original = settings.OPENAI_API_KEY + settings.OPENAI_API_KEY = None + + trainer = CorpusTrainer(db_session) + embedding = await trainer._generate_embedding("test") + assert embedding is None + + settings.OPENAI_API_KEY = original diff --git a/docs/DEV_PLAN.md b/docs/DEV_PLAN.md new file mode 100644 index 0000000..8e3570d --- /dev/null +++ b/docs/DEV_PLAN.md @@ -0,0 +1,293 @@ +# 外贸小助手 (TradeMate) — 开发计划 + +> 版本: v1.0 +> 创建日期: 2026-05-09 +> 基于: 产品设计文档 & 技术架构文档 & 代码审查 + +--- + +## 一、阶段说明 + +按优先级分为 4 个阶段，每个阶段完成后可独立上线验证： + +| 阶段 | 名称 | 目标 | 预估工时 | +|------|------|------|---------| +| P0 | 上线必须 | 小程序审核通过 + 核心链路跑通 | 2-3 天 | +| P1 | MVP 补齐 | 产品设计承诺的功能闭环 | 1-2 周 | +| P2 | 体验增强 | 用户留存 + 付费转化 | 2-3 周 | +| P3 | 护城河建设 | AI 数据壁垒 + 网络效应 | 4-6 周 | + +--- + +## 二、P0 — 上线必须（2-3 天） + +### 2.1 微信登录配置 +- **问题**: `wechat.py` 代码完整，但 `WECHAT_APP_ID` / `WECHAT_APP_SECRET` 未配置，前端微信登录按钮无实际功能 +- **改动量**: 纯配置（需微信开放平台账号） +- **涉及文件**: `.env`、`backend/app/api/v1/auth.py`、`uni-app/src/pages/login/login.vue` +- **验收**: 用户可点击微信授权登录 + +### 2.2 隐私政策 & 用户协议页面 +- **问题**: 小程序审核必需要求，当前无任何法律文档页面 +- **改动量**: 新增 2 个静态页面 +- **涉及文件**: `uni-app/src/pages/agreement/privacy.vue`、`uni-app/src/pages/agreement/terms.vue`、`pages.json` +- **验收**: 登录页底部展示协议链接，可点击打开 + +### 2.3 首页数据 Mock 替换 +- **问题**: `index.vue:121` 使用了 `Math.floor(Math.random() * 20)` 模拟今日翻译数和报价单数 +- **改动量**: 接入真实统计 API +- **涉及文件**: `uni-app/src/pages/index/index.vue` +- **验收**: 首页所有数据来自后端真实接口 + +### 2.4 admin API 鉴权修复 +- **问题**: `admin.py:11` 的 `require_admin` 无实际校验，任何持有 token 的用户都能改其他用户的 Tier +- **改动量**: 增加用户角色字段 + 权限校验 +- **涉及文件**: `backend/app/models/user.py`、`backend/app/api/v1/admin.py` +- **验收**: 普通用户访问 admin 接口返回 403 + +### 2.5 前端 API 重复定义清理 +- **问题**: `api.js` 中 `translateApi` 和 `customerApi` 各定义了两遍（第 43 行和第 116 行、第 50 行和第 124 行），后者会覆盖前者但内容不一致（后者多了 `tts` 和 `importCustomers`） +- **改动量**: 合并重复定义，保留完整版本 +- **涉及文件**: `uni-app/src/utils/api.js` +- **验收**: 文件中每个 API 对象只出现一次 + +--- + +## 三、P1 — MVP 补齐（1-2 周） + +### 3.1 新用户引导流程 + +**对应产品设计**: 用户旅程 §3.1 — 30 秒上手 + +| 步骤 | 说明 | +|------|------| +| 首次注册登录后 | 弹出引导弹窗:"你主要卖什么产品？" | +| 输入产品信息 | 名称 + 描述 + 目标市场 | +| 自动生成 | 3 条营销文案 + 关键词建议 | +| 保存产品 | 写入产品库 | +| 跳转客户页 | 提示"添加或导入客户" | + +**涉及文件**: +- `uni-app/src/pages/index/index.vue` — 首次登录检测 + 引导弹窗 +- `backend/app/services/onboarding.py` — 首次生成逻辑 +- `backend/app/api/v1/onboarding.py` — 引导 API + +**状态**: ✅ 已完成 + +**验收**: 新注册用户登录后 30 秒内看到生成的营销文案 + +### 3.2 真实数据分析 + +**对应**: 首页仪表盘、数据分析页面 + +- **后端**: 统计 API 已存在（`analytics.py`），数据来自数据库查询 +- **前端**: `analytics.vue` 已接入 `analyticsApi.getOverview()` 真实数据 +- **涉及文件**: `uni-app/src/pages/analytics/analytics.vue`、`backend/app/services/analytics.py` +- **状态**: ✅ 已完成（首页和数据分析页面数据均来自真实接口） + +### 3.3 报价单 PDF 生成 + +**对应**: 功能设计 §2.5 + +- **后端**: `pdf_generator.py` 引用了 `weasyprint` 但该库未在 `requirements.txt` 中，且当前生成逻辑是纯文本 +- **改动**: + 1. 将 `weasyprint` 加入 `requirements.txt` + 2. 安装系统依赖（`libpango`、`libcairo` 等） + 3. 实现正式的 HTML→PDF 模板渲染 +- **涉及文件**: `backend/app/services/pdf_generator.py`、`backend/requirements.txt` +- **状态**: ✅ 已完成（weasyprint 模板 + HTML→PDF 渲染） +- **验收**: `/quotations/{id}/pdf` 返回真实 PDF 文件 + +### 3.4 TTS 前端集成 + +**对应**: 功能设计 §2.3 + +- **后端**: `tts.py` 已实现 +- **前端**: 翻译页面需添加"播放"按钮调用 TTS API +- **涉及文件**: `uni-app/src/pages/translate/translate.vue`、`backend/app/api/v1/translate.py` +- **状态**: ✅ 已完成（后端增加 GET 端点适配前端 downloadFile） +- **验收**: 翻译结果可点击播放语音 + +### 3.5 错误监控接入 + +**对应**: 架构安全 + +- 接入 Sentry 或其他错误监控服务 +- 后端: `sentry-sdk` 集成到 FastAPI +- 前端: `uni-app` 错误捕获上报 +- **涉及文件**: `backend/app/main.py`、`backend/app/config.py`、`backend/requirements.txt` +- **状态**: ✅ 已完成（Sentry FastAPI + SQLAlchemy 集成，配置 SENTRY_DSN 即可启用） +- **验收**: 配置 SENTRY_DSN 后，故意制造错误可在监控平台看到 + +--- + +## 四、P2 — 体验增强（2-3 周） + +### 4.1 付费/计费系统 + +**对应**: 盈利模式 §6 + +| 模块 | 说明 | +|------|------| +| 支付 API | 接入微信支付（JSAPI）— 代码已完成，需微信支付商户号 | +| 订阅管理 | `subscriptions` 表 + 到期自动降级 | +| 前端升级页 | 展示 Free/Pro/Enterprise 对比 + 支付按钮 | +| 配额联动 | 支付成功后自动更新 `user.tier` | + +**涉及文件**: +- `backend/app/models/subscription.py`（新） +- `backend/app/api/v1/payment.py`（新） +- `backend/app/services/payment.py`（新） +- `uni-app/src/pages/upgrade/upgrade.vue`（新） + +**状态**: ✅ 代码已完成（需配置微信支付商户号后真正可用） + +**验收**: 用户可完成从 free 到 pro 的完整支付升级流程 + +### 4.2 应用内通知中心 + +- **改动**: + - 新增 `notifications` 表 + - 通知 API（列表/已读/删除/未读数） + - 前端通知中心页面 + 首页未读红点 +- **涉及文件**: `backend/app/models/notification.py`、`backend/app/api/v1/notification.py`、`backend/app/services/notification.py`、`uni-app/src/pages/notification/notification.vue` +- **额外**: Celery 沉默客户检测任务同时写入应用内通知 +- **状态**: ✅ 已完成 +- **验收**: 沉默客户提醒、系统通知等在应用内可见 + +### 4.3 数据导出 + +- 客户列表导出 CSV +- 报价单批量导出 CSV +- **涉及文件**: `backend/app/services/export.py`、`backend/app/api/v1/customer.py`、`backend/app/api/v1/quotation.py` +- **状态**: ✅ 已完成 +- **验收**: 访问 `/api/v1/customers/export/csv` 和 `/api/v1/quotations/export/csv` 下载文件 + +### 4.4 速率限制 + +**对应**: API设计 §5 + +- 新增 `RateLimitMiddleware`，使用 Redis + 1 分钟窗口计数器 +- free: 100 req/min, pro: 500, enterprise: 2000 +- 超限返回 429，响应头携带 `X-RateLimit-Remaining` +- **涉及文件**: `backend/app/core/middleware.py`、`backend/app/main.py` +- **状态**: ✅ 已完成 +- **验收**: 超过限制返回 429 + +### 4.5 用户反馈 & 帮助系统 + +- 反馈提交（Bug/功能建议/其他） +- 常见问题 FAQ（内置 4 条常见问题） +- **涉及文件**: `backend/app/models/feedback.py`、`backend/app/api/v1/feedback.py`、`uni-app/src/pages/feedback/feedback.vue` +- **状态**: ✅ 已完成 +- **验收**: 用户可提交反馈并查看常见问题 + +--- + +## 五、P3 — 护城河建设（4-6 周） + +### 5.1 AI 编辑学习回路 + +**对应**: 护城河 §5.1 + +当前 `messages` 表已有 `ai_suggestions`、`selected_suggestion`、`user_edited` 字段： + +1. 用户选择某个 AI 建议 → 记录正反馈（signal） ✅ +2. 用户修改 AI 建议再发送 → 记录差异（diff） ✅ +3. 系统定期分析用户偏好风格 ✅ +4. 下次生成时使用用户偏好做 few-shot ✅ + +**涉及文件**: +- `backend/app/services/preference.py`（新）— UserPreferenceService +- `backend/app/api/v1/interaction.py`（新）— 选择/编辑/分析 API +- `backend/app/models/preference.py`（新）— PreferenceAnalysis 模型 +- `backend/app/ai/router.py` — 注入 preference_context +- `backend/app/ai/providers/openai.py` — 接受 preference_context 参数 +- `backend/app/ai/providers/claude.py` — 同上 +- `backend/app/ai/providers/spark.py` — 同上 +- `backend/app/ai/providers/local.py` — 同上 +- `backend/app/api/v1/translate.py` — getUserPreferenceContext + 传递到 AI layer +- `backend/app/api/v1/marketing.py` — 同上 +- `backend/app/services/translation.py` — 透传 preference_context +- `backend/app/services/marketing.py` — 透传 preference_context +- `uni-app/src/utils/api.js` — 新增 interactionApi + +**验收**: 用户多次编辑后，AI 回复风格逐渐接近用户习惯 + +### 5.2 营销效果追踪 + +**对应**: 功能设计 §2.2 + +- 记录用户复制了哪些营销文案 ✅ +- 记录用户发送了哪些文案 ✅ +- 展示文案使用统计（复制次数、发送次数、效果评分） ✅ +- **涉及文件**: `backend/app/models/preference.py`（MarketingEffect 模型）、`backend/app/services/marketing_effect.py`（新）、`backend/app/api/v1/interaction.py`（效果追踪端点）、`backend/app/services/analytics.py`（增加 marketing stats）、`backend/app/api/v1/analytics.py`（增加 marketing 统计接口） +- **验收**: 营销素材页展示"已复制 15 次"等统计数据 + +### 5.3 沉默客户模式算法 + +**对应**: 护城河 §5.3 + +1. 风险评分算法（沉默天数 + 活跃度 + 谈判阶段 + 关键词检测） ✅ +2. 评分等级输出（high/medium/low/minimal） ✅ +3. 跟进建议生成 ✅ + +**涉及文件**: +- `backend/app/services/silent_pattern.py`（新）— SilentPatternService +- `backend/app/api/v1/silent_pattern.py`（新）— 风险分析 + 建议 API +- `uni-app/src/utils/api.js` — 新增 silentPatternApi + +**验收**: 沉默客户列表显示风险评分等级及跟进建议 + +### 5.4 语料库离线训练 + +**对应**: AI架构 §4.3 + +- `corpus_entries` 表已有数据但无训练逻辑： + 1. embedding 向量计算（OpenAI text-embedding-3-small） ✅ + 2. 质量评分自动计算 ✅ + 3. 重复数据去重 ✅ + 4. 低质量数据清理 ✅ + 5. Celery beat 每日定时训练 ✅ + +**涉及文件**: +- `backend/app/services/corpus_trainer.py`（新）— 完整训练 pipeline +- `backend/app/api/v1/training.py`（新）— 训练触发端点 +- `backend/app/workers/tasks.py` — 新增 run_daily_corpus_training 定时任务 +- `backend/app/celery_app.py` — 注册 daily-corpus-training 定时器 + +**验收**: 语料库达到阈值后自动触发训练，翻译质量可量化提升 + +### 5.5 报价单智能生成 + +**对应**: 功能设计 §2.5 + +从"手动填报价单"升级为"自动识别客户消息→生成报价单草稿": +1. `extract_info` 识别客户询盘意图（产品、数量、贸易术语） ✅ +2. 自动匹配产品库价格 ✅ +3. 生成报价单草稿（含 matched/unmatched 标识） ✅ + +**涉及文件**: +- `backend/app/services/quotation.py` — 新增 generate_from_inquiry 方法 +- `backend/app/api/v1/quotation.py` — 新增 POST /quotations/generate-from-inquiry 端点 +- `uni-app/src/utils/api.js` — 新增 quotationApi.generateFromInquiry + +**验收**: 客户说 "How much for 500pcs FOB Shanghai?" → 系统自动生成含金额的报价单草稿 + +--- + +## 六、工作量汇总 + +| 阶段 | 功能点 | 预估 | +|------|--------|------| +| **P0** | 微信登录配置、隐私协议、Mock 替换、admin 鉴权、API 去重 | ✅ 2-3 天 | +| **P1** | 引导流程、数据分析、PDF、TTS、错误监控 | ✅ 1-2 周 | +| **P2** | 支付系统、通知中心、数据导出、速率限制、帮助反馈 | ✅ 2-3 周 | +| **P3** | AI 编辑学习、效果追踪、沉默算法、语料库训练、智能报价 | ✅ 4-6 周 | + +### 关键依赖 + +- **P0** 无外部依赖，可立即开始 +- **P1 PDF** 需要服务器安装系统库（libpango, libcairo） +- **P2 支付** 需要微信支付商户号 +- **P3 训练** 需要语料库自然积累到一定规模后才有意义（已实现 pipeline 和定时任务） diff --git a/docs/FIX_PLAN.md b/docs/FIX_PLAN.md new file mode 100644 index 0000000..8fd1acd --- /dev/null +++ b/docs/FIX_PLAN.md @@ -0,0 +1,327 @@ +# 外贸小助手 (TradeMate) — 功能差距修复计划 + +> 基于 2026-05-10 全量代码审计 +> 将未完成/存根/未对接功能按优先级分为 FixP0-FixP3 四阶段 + +--- + +## 总体概况 + +| 类别 | 数量 | 说明 | +|------|------|------| +| 🔴 外部阻塞（代码就绪） | 4 项 | 微信登录/支付/WhatsApp/AI回退 — 需要配置密钥 | +| ⚠️ 部分实现/存根 | 4 项 | Push/汇率/PDF任务/weasyprint系统依赖 | +| ❌ 前端未对接 | 12 项 | 后端有API但前端无入口 | +| ✅ 完整实现 | ~25 项 | 核心链路前后端均对接 | + +--- + +## FixP0 — 上线阻塞（必须先修复） + +### F0.1 Push 推送重写 + +**问题**: `PushService.send_notification()` 只打印日志，无真实推送。设备注册用内存 dict。Celery 静默客户检测产出提醒但用户收不到。 + +**方案**: +1. 新建 `Device` 模型：user_id, platform, push_token, is_active, created_at +2. 重写 `PushService`：使用 uni-push 或第三方推送通道 +3. `POST /push/register` 改为写数据库 +4. `send_notification()` 调用真实推送 SDK +5. Celery `check_silent_customers` 任务同时写 Notification + PushService + +**涉及文件**: +- `backend/app/models/device.py`（新） +- `backend/app/models/__init__.py` +- `backend/app/services/push.py`（重写） +- `backend/app/api/v1/push.py`（重写） +- `uni-app/src/utils/api.js`（新增 pushApi） +- `uni-app/src/pages/index/index.vue`（注册设备 token） +- `backend/alembic/versions/004_devices.py`（新） + +**预估**: 3-4 天（含前端 token 注册） + +### F0.2 汇率服务接入真实 API + +**问题**: `GET /api/v1/exchange/convert` 和 `GET /api/v1/exchange/rates` 返回硬编码数据，`EXCHANGE_RATE_API_KEY` 未使用。 + +**方案**: +1. 创建 `ExchangeRateService`：调用 exchangerate-api.com 或 国家外汇管理局 API +2. Redis 缓存 6 小时减少 API 调用 +3. 更新硬编码字典为动态查询 +4. 报价单界面增加汇率显示和币种切换 + +**涉及文件**: +- `backend/app/services/exchange.py`（新 — 当前无 service） +- `backend/app/api/v1/exchange.py`（重写 — 移除硬编码） +- `uni-app/src/utils/api.js`（新增 exchangeApi） +- `uni-app/src/pages/translate/translate.vue`（报价单汇率开关） + +**预估**: 1-2 天 + +### F0.3 Celery PDF 任务修复 + +**问题**: `workers/tasks.py:94` 调用旧纯文本 `generate_pdf_text()` 而非 `pdf_generator.generate_quotation()`。 + +**方案**: +- 将 Celery 任务 `generate_quotation_pdf` 改为调用 `pdf_generator.generate_quotation(data)` 并存储 blob + +**涉及文件**: +- `backend/app/workers/tasks.py`（重写 generate_quotation_pdf） +- `backend/app/services/pdf_generator.py`（增加保存 PDF 到磁盘方法） + +**预估**: 0.5 天 + +### F0.4 weasyprint 系统依赖文档化 + +**问题**: `requirements.txt` 有 weasyprint 但部署时需系统库，无文档说明。 + +**方案**: +- 在 README 和 docker-compose 中增加系统依赖安装说明 +- 若使用 Docker，在 Dockerfile 中提前安装 + +```dockerfile +RUN apt-get update && apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 \ + libgdk-pixbuf2.0-0 libffi-dev libcairo2 libcairo2-dev +``` + +**涉及文件**: +- `Dockerfile`（新增或修改） +- `README.md`（增加安装说明） + +**预估**: 0.5 天 + +--- + +## FixP1 — 前端对接（补齐体验） + +### F1.1 TTS 播放按钮 + +**问题**: `GET/POST /api/v1/translate/tts` 后端已实现，翻译页无播放按钮，`api.js` 无 tts API。 + +**方案**: +- `api.js` 新增 `translateApi.textToSpeech(text, lang)` +- `translate.vue` 翻译结果后增加 🔊 播放按钮，调用 `uni.downloadFile` → `uni.playVoice` + +**涉及文件**: +- `uni-app/src/utils/api.js` +- `uni-app/src/pages/translate/translate.vue` + +**预估**: 1 天 + +### F1.2 信息抽取 + 翻译反馈 UI + +**问题**: `POST /translate/extract` 和 `POST /translate/feedback` 有后端无前端。 + +**方案**: +- 翻译页增加"抽取信息"按钮（提取客户消息中的产品/数量/价格） +- 翻译结果增加 1-5 星评分，调用 feedback 端点写入 corpus quality_score + +**涉及文件**: +- `uni-app/src/pages/translate/translate.vue` +- `uni-app/src/utils/api.js` + +**预估**: 1 天 + +### F1.3 营销关键词 + 竞品分析按钮 + +**问题**: `POST /marketing/keywords`、`POST /marketing/competitor-analysis` 后端完整，前端营销页无入口。 + +**方案**: +- `marketingApi` 增加 `generateKeywords()` 和 `competitorAnalysis()` +- `marketing.vue` 生成结果下方增加"生成关键词"和"竞品分析"按钮 + +**涉及文件**: +- `uni-app/src/utils/api.js` +- `uni-app/src/pages/marketing/marketing.vue` + +**预估**: 1 天 + +### F1.4 营销效果统计展示 + +**问题**: `interactionApi.trackMarketingEffect/stats` 前端 API 已定义，`marketing.vue` 未展示统计数据。 + +**方案**: +- `marketing.vue` 增加统计卡片："今日复制 X 次 / 今日发送 Y 次 / 本周共 Z 次" +- 每次复制文案时调用 `trackMarketingEffect({content, event_type:'copy'})` +- 加载时调用 `getMarketingEffectStats()` + +**涉及文件**: +- `uni-app/src/pages/marketing/marketing.vue` + +**预估**: 1 天 + +### F1.5 AI 偏好展示 + 建议选择/编辑上报 + +**问题**: `interactionApi.selectSuggestion/recordEdit/analyzePreferences` 已定义，翻译页未对接交互学习回路。 + +**方案**: +- 翻译页回复建议列表：用户点击某条 → 调用 `selectSuggestion(msgId, index)` +- 用户编辑后发送 → 调用 `recordEdit(msgId, editedText)` +- 设置页增加"AI 学习偏好"展示区（调用 `getPreferences()`） + +**涉及文件**: +- `uni-app/src/pages/translate/translate.vue` +- `uni-app/src/pages/settings/settings.vue`（如有） + +**预估**: 2 天 + +### F1.6 沉默客户风险展示 + +**问题**: `silentPatternApi.getRiskAnalysis/getSuggestions` 已定义，客户页未对接。 + +**方案**: +- 客户列表每项增加风险等级标识（🔴/🟡/🟢） +- 客户详情页增加"跟进建议"区域 +- 调用 `getRiskAnalysis()` 在客户页顶部展示风险概况 + +**涉及文件**: +- `uni-app/src/pages/customer/customer.vue`（列表） +- `uni-app/src/pages/customer/detail.vue`（详情） + +**预估**: 1.5 天 + +### F1.7 智能报价按钮 + +**问题**: `quotationApi.generateFromInquiry` 已定义，报价单页未对接。 + +**方案**: +- 报价单列表页增加"从询盘生成"按钮 +- 弹出输入框让用户粘贴客户询盘内容 +- 调用 API 后预览自动填充的报价单草稿 + +**涉及文件**: +- `uni-app/src/pages/quotation/quotation.vue` +- `uni-app/src/pages/quotation/create.vue`（如有） + +**预估**: 1.5 天 + +### F1.8 CSV 导出按钮 + +**问题**: `GET /customers/export/csv` 和 `GET /quotations/export/csv` 后端完成，前端无导出入口。 + +**方案**: +- 客户页和报价单页的导航栏增加"导出"按钮 +- 使用 `uni.downloadFile` 下载 CSV + +**涉及文件**: +- `uni-app/src/pages/customer/customer.vue` +- `uni-app/src/pages/quotation/quotation.vue` + +**预估**: 0.5 天 + +### F1.9 客户对话历史展示 + +**问题**: `customerApi.getConversation` 已定义，客户详情页未展示对话记录。 + +**方案**: +- 客户详情页增加"对话记录" tab +- 分页加载消息，显示发送/接收方向 + +**涉及文件**: +- `uni-app/src/pages/customer/detail.vue` + +**预估**: 1 天 + +--- + +## FixP2 — 管理后台补齐 + +### F2.1 训练后台面板 + +**问题**: `POST /training/corpus/*` 4 个端点后端完整，无前端入口。 + +**方案**: +- admin 页增加"语料库管理"标签 +- 展示语料库统计（总数/高质/低质/嵌入数） +- 提供"运行训练"、"去重"、"清理"按钮 + +**涉及文件**: +- `uni-app/src/pages/admin/admin.vue` +- `uni-app/src/utils/api.js`（新增 trainingApi） + +**预估**: 1 天 + +### F2.2 反馈管理 + 用户管理增强 + +**问题**: admin 面板只能看用户列表和改 tier，无反馈管理、系统监控。 + +**方案**: +- `GET /admin/feedbacks` 端点 +- admin 页增加"用户反馈"标签：列表/标记处理 +- 增加系统状态监控（Celery 队列长度、Redis 状态） + +**涉及文件**: +- `backend/app/api/v1/admin.py`（新增反馈列表端点） +- `uni-app/src/pages/admin/admin.vue` + +**预估**: 2 天 + +--- + +## FixP3 — 深层清理 + +### F3.1 汇率集成报价单 + +**问题**: 报价单创建/编辑时不可切换币种，无实时汇率。 + +**方案**: +- 报价单创建页增加币种选择（USD/CNY/EUR/GBP/JPY） +- 调用 ExchangeRateService 自动换算 +- 报价单 PDF 显示原始币种金额和换算后金额 + +**涉及文件**: +- `backend/app/services/quotation.py`（create_quotation 加入汇率换算） +- `backend/app/services/pdf_generator.py`（PDF 模板增加双币种行） +- `uni-app/src/pages/quotation/create.vue` + +**预估**: 2 天 + +### F3.2 Admin 统计指标扩展 + +**问题**: admin dashboard 只返回 total_users/paid_users，缺少业务指标。 + +**方案**: +- `GET /admin/dashboard` 增加：今日活跃用户数、API 调用量、新增客户数、新建报价单数 +- 基于 `UsageLog` 聚合统计 + +**涉及文件**: +- `backend/app/services/admin.py`（如有） +- `backend/app/api/v1/admin.py` + +**预估**: 1 天 + +--- + +## 工作量汇总 + +| 阶段 | 项目 | 预估 | +|------|------|------| +| **FixP0** | Push 重写 + 汇率 API + PDF 任务修复 + weasyprint 依赖 | 5-6 天 | +| **FixP1** | 9 项前端对接（TTS/抽取/关键词/效果/偏好/风险/报价/导出/对话） | 10-12 天 | +| **FixP2** | 训练面板 + 反馈管理 | 3 天 | +| **FixP3** | 汇率集成报价 + admin 统计扩展 | 3 天 | +| **合计** | | **21-24 天** | + +### 外部依赖（开发期间可 mock） + +| 依赖 | 说明 | +|------|------| +| `EXCHANGE_RATE_API_KEY` | 免费版 exchangerate-api.com 即可 | +| 推送通道 | uni-push（免费）或第三方通道 | +| 微信商户号 | 支付上线必需 | + +### 建议执行顺序 + +``` +FixP0.1 Push 重写 ────────────────────────── 最紧急，否则静默客户提醒等于没有 + ↓ +FixP0.2 汇率 + FixP0.3 PDF 任务 ────────── 并行，无依赖 + ↓ +FixP1.5 AI 偏好 + FixP1.6 沉默风险 ─────── P3 功能的最后闭环 + ↓ +FixP1.1~1.4 TTS/抽取/关键词/效果 ──────── 批量前端对接 + ↓ +FixP1.7~1.9 智能报价/导出/对话 ─────────── 报价 + 客户页增强 + ↓ +FixP2 + FixP3 ─────────────────────────── 管理后台 + 深度清理 +``` diff --git a/docs/PRODUCT_DESIGN.md b/docs/PRODUCT_DESIGN.md index fbb243b..b4397a0 100644 --- a/docs/PRODUCT_DESIGN.md +++ b/docs/PRODUCT_DESIGN.md @@ -1,8 +1,8 @@ # 外贸小助手 (TradeMate) — 产品设计文档 -> 版本: v1.0 -> 创建日期: 2026-05-08 -> 状态: 初始设计 +> 版本: v1.1 +> 创建日期: 2026-05-10 +> 状态: V2 规划中 --- @@ -39,23 +39,35 @@ ### 2.1 功能全景图 ``` -┌─────────────────────────────────────────────────────┐ -│ 外贸小助手 │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ 营销素材 │ │ 智能沟通 │ │ 客户跟进 │ │ -│ │ 工厂 │ │ 助手 │ │ 引擎 │ │ -│ ├──────────┤ ├──────────┤ ├──────────┤ │ -│ │ 开发信 │ │ 消息翻译 │ │ 沉默检测 │ │ -│ │ 产品文案 │ │ 回复建议 │ │ 跟进提醒 │ │ -│ │ 关键词 │ │ 一键发送 │ │ 话术推荐 │ │ -│ │ 竞品分析 │ │ 语气调整 │ │ 周期提醒 │ │ -│ └──────────┘ └──────────┘ └──────────┘ │ -│ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ 跨功能支撑: 报价单生成 / 汇率换算 │ │ -│ └─────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────┐ +│ 外贸小助手 V2 │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ +│ │ 营销素材 │ │ 智能沟通 │ │ 客户跟进 │ │ 智能决策中心 │ │ +│ │ 工厂 │ │ 助手 │ │ 引擎 │ │ (新增) │ │ +│ ├──────────┤ ├──────────┤ ├──────────┤ ├────────────────┤ │ +│ │ 开发信 │ │ 消息翻译 │ │ 沉默检测 │ │ 健康度看板 │ │ +│ │ 产品文案 │ │ 回复建议 │ │ 跟进提醒 │ │ 客户评分 │ │ +│ │ 关键词 │ │ 语气调整 │ │ 话术推荐 │ │ 行动建议 │ │ +│ │ 竞品分析 │ │ TTS播放 │ │ 周期提醒 │ │ 趋势预警 │ │ +│ └──────────┘ └──────────┘ └─────┬────┘ └────────────────┘ │ +│ │ │ +│ ┌──────────────────────────────────┼──────────────────────────┐ │ +│ │ AI智能跟进助手 (新增) │ │ │ +│ │ ┌─ 时机判断 ─ 内容生成 ─ 渠道选择 ─ 效果追踪 ─┐ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────┬──────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────────────┼──────────────────────────┐ │ +│ │ 智能市场机会分析 (新增) │ │ │ +│ │ ┌─ 趋势分析 ─ 客户发现 ─ 竞争情报 ─ 策略报告 ─┐ │ │ +│ │ └──────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 跨功能支撑: 报价单生成 / 汇率换算 / 合规筛查 / 文档模板 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ ``` ### 2.2 功能一：营销素材工厂（帮用户"有内容可发"） @@ -174,6 +186,154 @@ - 用户确认 → 生成正式报价单图片 → 一键发送 ``` +### 2.6 功能四：客户健康度看板（帮用户"一眼看清该追谁"） + +#### 用户场景 +> "我有50多个客户，除了最近联系的那几个，其他谁在流失、谁快成交了，我心里完全没数。" + +#### 交互流程 + +``` +[用户打开小程序] + └─ 点击"客户" → 顶部展示健康度总览卡片: + ├─ 🟢 活跃客户: 12 + ├─ 🟡 需关注: 5 + ├─ 🔴 高危流失: 3 + └─ 📊 整体健康趋势（本周 vs 上周） + +[点击具体客户] + └─ 进入客户详情 → 健康度看板: + ├─ 综合评分: 78/100（评分趋势 ↑↓） + ├─ 评分维度明细: + │ ├─ 📈 响应趋势: +15%（回复速度在变快） + │ ├─ 💬 情感轨迹: 正面（AI分析最近3条消息） + │ ├─ 📋 询盘深度: "问了MOQ和认证"（成交信号） + │ ├─ ⏰ 沉默天数: 3天 + │ └─ 💰 预估价值: $12,500 + └─ 🎯 系统建议动作: + "客户问过MOQ和认证，建议明天发认证证书和报价单跟进" +``` + +#### 核心机制 + +- **评分透明可解释**: 不像竞品黑盒打分，每个维度都有来源和原因 +- **多维度融合**: 响应趋势 + 情感分析 + 行为信号 + 沉默天数 + 商业价值 +- **Actionable**: 不只是分数，而是"到底是什么问题 + 建议怎么做" + +#### 数据来源（全在现有数据库里，无需外部API） + +| 维度 | 数据源 | 现有字段 | +|------|--------|---------| +| 响应趋势 | messages | created_at, direction | +| 情感轨迹 | messages | content（AI分析） | +| 询盘深度 | messages | content（关键词匹配） | +| 沉默天数 | customers | last_contact_at | +| 商业价值 | quotations | total, status | + +### 2.7 功能五：AI智能跟进助手（帮用户"知道什么时候跟、怎么跟"） + +#### 用户场景 +> "报完价客户就没消息了，我不知道该不该发消息、什么时候发、发什么内容合适。" + +#### 交互流程 + +``` +[系统自动运行] + └─ AI 持续评估每个客户的跟进状态: + ├─ 每个客户生成"最优跟进时机"（基于历史互动模式） + ├─ 不同客户不同策略: + │ ├─ 客户A（沉默3天，之前聊报价）: "建议今晚8点WhatsApp发认证资料" + │ ├─ 客户B（沉默7天，之前聊样品）: "建议邮件发新品目录 + 限时折扣" + │ └─ 客户C（回盘积极，在比价）: "客户可能在对比，建议3天后主动降价5%" + └─ 系统主动推送通知: + "📌 跟进提醒: 客户Carlos沉默4天，最优跟进窗口还剩2天" + +[用户点击提醒] + └─ 进入跟进界面: + ├─ 客户背景摘要（快速回顾） + ├─ AI推荐的跟进内容（基于上次对话定制） + ├─ 选择渠道: WhatsApp / Email / 电话 + └─ 一键发送 / 编辑后发送 + +[发送后] + └─ 自动打标: "已跟进" → 继续监控客户反应 + └─ 若3天内客户回复 → 标记"跟进成功" → 更新评分 + └─ 若客户未回复 → 自动调整下一次跟进策略 +``` + +#### 核心机制 + +- **不是固定时间间隔**: 竞品用3/7/14天固定规则，AI根据客户状态动态判断 +- **多渠道选择**: 根据客户历史偏好推荐最佳渠道 +- **内容个性化**: 每次跟进都基于上次对话 + 产品库 + 市场信息生成 +- **闭环追踪**: 跟进→回复（或不回复）→调整策略 + +#### 对比竞品 + +| 维度 | 竞品 EDM 序列 | TradeMate AI 跟进 | +|------|-------------|------------------| +| 触发方式 | 预设时间（3/7/14天） | AI动态评估最佳时机 | +| 内容 | 模板化 | 每次个性化生成 | +| 渠道 | 仅邮件 | WhatsApp/邮件/电话 | +| 适应性 | 固定流程 | 根据客户反应自动调整 | +| 成本 | 邮件服务费 | 现有AI能力，零新增成本 | + +### 2.8 功能六：智能市场机会分析（帮用户"找到该开发哪个市场"） + +#### 用户场景 +> "我想开发新市场，但不知道哪个国家对我的产品需求大、竞争情况怎么样、应该怎么切入。" + +#### 交互流程 + +``` +[用户输入产品信息] + └─ 点击"市场分析" + └─ AI 自动执行: + 1. 调取免费国际贸易统计数据分析目标市场趋势 + 2. 搜索公开B2B平台/行业黄页发现潜在客户 + 3. 分析目标市场竞争格局和定价 + 4. 生成市场进入策略报告 + +[用户收到报告] + ┌─────────────────────────────────────┐ + │ 📊 户外折叠椅 · 市场机会报告 │ + │ │ + │ 🎯 推荐市场 Top 3: │ + │ 1. 美国 (+23% 进口增长) — 建议主攻 │ + │ 2. 德国 (+15%) — 中高端定位 │ + │ 3. 东南亚 (+40% 增长快速) — 建议布局 │ + │ │ + │ 👥 潜在客户示例: │ + │ · OutdoorLiving Inc. (美国) │ + │ · GartenPro GmbH (德国) │ + │ · CampingZone (东南亚) │ + │ │ + │ 💡 进入策略建议: │ + │ · 美国: 侧重防水+承重卖点 │ + │ · 德国: 强调环保认证 │ + │ · 东南亚: 主打性价比 │ + └─────────────────────────────────────┘ + +[用户下一步] + └─ 点击"生成开发信" → AI 自动适配目标市场的文化习惯生成文案 + └─ 保存报告到产品库 → 随时查阅 +``` + +#### 核心机制 + +- **零数据采购成本**: 使用免费国际贸易统计 API + AI 搜索，不买海关数据 +- **海关数据竞品的问题**: 数据滞后3-6个月，只有提单记录无具体联系人 +- **我们的方案**: 不只告诉你"谁买了"，而是"怎么找到他们、怎么卖进去" + +#### 数据源 + +| 数据源 | 用途 | 成本 | +|--------|------|------| +| UN COMTRADE / ITC TradeMap | 国际贸易统计数据 | 免费 | +| Google Custom Search / SerpAPI | B2B平台/黄页公开数据 | 免费~$50/月 | +| Wikipedia/OpenStreetMap | 国家基础信息 | 免费 | +| AI 已有知识 | 市场策略、文化习惯 | 已有 | + --- ## 三、用户旅程 @@ -222,11 +382,13 @@ ## 五、护城河策略 -详见 `TECH_ARCHITECTURE.md` 第 5 章，核心三层： +详见 `TECH_ARCHITECTURE.md` 第 5 章，核心五层： 1. **外贸垂直语料库**：用户每次使用产生的翻译/回复数据，积累成行业专属语料 2. **用户产品知识库**：产品信息+客户偏好+历史报价，迁移成本极高 3. **沉默客户模式算法**：跨用户行为数据产生的预测能力，网络效应 +4. **客户健康度评分模型**：基于多维度行为数据的客户价值评估，用户用得越久模型越准 +5. **AI跟进策略引擎**：基于历史跟进成功率的学习模型，持续优化时机/内容/渠道 --- @@ -244,7 +406,8 @@ | 阶段 | 时间 | 功能 | |------|------|------| -| MVP | 第1-4周 | 智能翻译+回复建议+基础营销素材+产品库 | -| V2 | 第5-8周 | 沉默客户跟进+WhatsApp集成+报价单生成 | -| V3 | 第9-12周 | 语料库训练+回复质量优化+多人协作 | -| V4 | 第13-16周 | 跨用户A/B测试+预测算法+API开放 | +| MVP | 第1-4周 | 智能翻译+回复建议+基础营销素材+产品库 ✅ | +| V2 | 第5-8周 | 沉默客户跟进+WhatsApp集成+报价单生成 ✅ | +| V3 | 第9-12周 | 语料库训练+回复质量优化+多人协作 ✅ | +| V4 | 第13-16周 | 跨用户A/B测试+预测算法+API开放 ✅ | +| **V5** | **第17-20周** | **客户健康度看板+智能跟进助手+市场机会分析** | diff --git a/docs/TECH_ARCHITECTURE.md b/docs/TECH_ARCHITECTURE.md index 09c3d12..01656b3 100644 --- a/docs/TECH_ARCHITECTURE.md +++ b/docs/TECH_ARCHITECTURE.md @@ -1,7 +1,8 @@ # 外贸小助手 (TradeMate) — 技术架构文档 -> 版本: v1.0 -> 创建日期: 2026-05-08 +> 版本: v1.1 +> 创建日期: 2026-05-10 +> 更新: 新增客户健康度看板、AI跟进助手、市场机会分析三大模块 --- @@ -34,6 +35,8 @@ │ │ - 翻译回复 │ │ - Router │ │ - Webhook │ │ │ │ - 客户跟进 │ │ - 语料库 │ │ - 会话管理 │ │ │ │ - 报价单 │ │ - 成本控制 │ │ │ │ +│ │ - 健康度 │ │ - 市场分析 │ │ │ │ +│ │ - 跟进引擎 │ │ - 跟进策略 │ │ │ │ │ └─────┬─────┘ └──────┬──────┘ └──────┬───────┘ │ │ │ │ │ │ │ ┌─────┴─────────────────┴─────────────────┴──────┐ │ @@ -99,6 +102,9 @@ trade-assistant/ │ │ │ ├── marketing.py # 营销素材生成 │ │ │ ├── translation.py # 翻译+回复引擎 │ │ │ ├── customer.py # 客户跟进引擎 +│ │ │ ├── customer_health.py # 客户健康度评分 (新增) +│ │ │ ├── followup_engine.py # AI跟进策略引擎 (新增) +│ │ │ ├── market_analysis.py # 市场机会分析 (新增) │ │ │ ├── quotation.py # 报价单服务 │ │ │ └── whatsapp.py # WhatsApp 服务 │ │ │ @@ -325,7 +331,212 @@ WhatsApp User WhatsApp Cloud API TradeMate --- -## 八、安全设计 +## 八、V2 新增模块架构 + +### 8.1 客户健康度看板 + +#### 评分模型 + +``` +输入 → 多维度特征提取 → 加权评分 → 等级输出 → 行动建议 +``` + +**评分维度与权重**: + +| 维度 | 权重 | 数据源 | 计算方式 | +|------|------|--------|---------| +| 响应趋势 | 25% | messages | 近7天平均回复时长 vs 前7天，趋势上升加分 | +| 情感轨迹 | 20% | messages | AI分析最近3条客户消息情感极性（正面/负面/中性） | +| 询盘深度 | 20% | messages | 是否包含MOQ/认证/FOB/证书等成交信号关键词 | +| 沉默天数 | 20% | customers | 归一化得分: 1天=100, 14天+=0 | +| 商业价值 | 15% | quotations | 历史成交金额 + 当前在谈金额 | + +**等级输出**: +| 分数区间 | 等级 | 颜色 | 建议动作 | +|---------|------|------|---------| +| 80-100 | 活跃 | 🟢 绿 | 保持正常跟进 | +| 50-79 | 需关注 | 🟡 黄 | 3天内安排跟进 | +| 0-49 | 高危 | 🔴 红 | 立即跟进，提供优惠或新产品信息 | + +#### 技术实现 + +- **无需新模型**: 使用现有 `messages`、`customers`、`quotations` 表 +- **轻量计算**: 无需 ML 模型，规则引擎即可，同步计算 < 50ms +- **异步更新**: Celery 定时任务每小时更新一次评分缓存到 Redis +- **API**: `GET /api/v1/customers/{id}/health` — 单个客户健康度 +- **API**: `GET /api/v1/customers/health-overview` — 全量概览 + +### 8.2 AI 智能跟进引擎 + +#### 架构 + +``` +┌────────────────────────────────────────────────────────────┐ +│ FollowupEngine │ +│ │ +│ 1. 状态评估 │ +│ └─ 读客户健康度 → 判断是否到跟进时机 │ +│ │ +│ 2. 策略选择 │ +│ ├─ 沉默 3-5 天 → 温和提醒（"Just checking in"） │ +│ ├─ 沉默 6-10 天 → 价值提供（"新品/行业资讯"） │ +│ ├─ 沉默 11+ 天 → 重新激活（"限时优惠/调查问卷"） │ +│ └─ 客户有回复但未成交 → 促进决策（"成功案例/限时"） │ +│ │ +│ 3. 内容生成 │ +│ └─ AI 基于客户画像+产品库+历史对话生成个性化内容 │ +│ │ +│ 4. 渠道推荐 │ +│ ├─ 历史互动中 WhatsApp 回复率>60% → WhatsApp │ +│ ├─ 客户来自展会/邮件 → Email │ +│ └─ 紧急/高价商机 → 建议电话 │ +│ │ +│ 5. 效果追踪 │ +│ └─ 跟进后监控客户反应 → 更新策略模型 │ +└────────────────────────────────────────────────────────────┘ +``` + +#### 技术实现 + +- **跟进策略**: 基于规则的策略选择器（可扩展为强化学习） +- **内容生成**: 复用现有 AI 营销素材能力，注入客户上下文 +- **渠道路由**: 基于 `customer.preference.channel` 和历史回复率 +- **定时任务**: Celery beat 每 6 小时轮检所有客户 +- **通知推送**: 检测到跟进时机 → 写入 notifications → PushService 推送 + +#### 数据模型 + +```python +class FollowupStrategy(Base): + """跟进策略模板""" + __tablename__ = "followup_strategies" + + id: UUID (PK) + user_id: UUID (nullable — null = 系统策略) + name: str # 策略名称 + trigger_conditions: JSONB # 触发条件: {health_score_max, silence_days_min, ...} + channel: str # 推荐渠道 + ai_prompt_template: str # AI提示词模板 + min_interval_hours: int # 最短间隔 + is_active: bool + success_count: int # 成功率统计 + created_at: datetime +``` + +```python +class FollowupLog(Base): + """跟进记录""" + __tablename__ = "followup_logs" + + id: UUID (PK) + user_id: UUID + customer_id: UUID (FK) + strategy_id: UUID (FK → followup_strategies) + health_score_before: float # 跟进前健康分 + suggested_content: Text # AI建议内容 + actual_content: Text # 用户实际发送内容 + channel: str # 使用的渠道 + was_sent: bool # 是否已发送 + customer_replied: bool # 客户是否回复 + replied_within_hours: int # 回复间隔 + created_at: datetime +``` + +### 8.3 智能市场机会分析 + +#### 架构 + +``` +┌────────────────────────────────────────────────────────────┐ +│ MarketAnalysisService │ +│ │ +│ 1. 市场趋势分析 │ +│ └─ 调取 UN COMTRADE / ITC TradeMap API → 目标国进口趋势 │ +│ │ +│ 2. 客户发现 │ +│ └─ Google Custom Search → B2B平台/行业黄页 → 潜在客户列表 │ +│ │ +│ 3. 竞争情报 │ +│ └─ AI 分析竞品定价/卖点/市场定位 │ +│ │ +│ 4. 策略报告 │ +│ └─ AI 综合生成: 市场选择→进入策略→风险提示→行动清单 │ +└────────────────────────────────────────────────────────────┘ +``` + +#### 数据源集成 + +| 数据源 | 集成方式 | 费率 | +|--------|---------|------| +| UN COMTRADE API | REST API (https://comtrade.un.org/api/) | 免费, 需注册 | +| ITC TradeMap | SOAP/REST (https://www.trademap.org/) | 免费基础查询 | +| Google Custom Search | JSON API (100次/天免费) | 免费~$5/1000次 | +| SerpAPI | Google搜索结果结构化 | $50/月 起 | +| AI 自有知识 | 已有模型知识 | 免费 | + +**核心原则**: 所有数据源有免费层，上线初期零数据采购成本。 + +#### API 设计 + +``` +POST /api/v1/market-analysis/opportunity + 输入: { product_name, description, category, target_markets? } + 输出: { + recommended_markets: [{ country, growth_rate, entry_strategy }], + potential_clients: [{ name, source, description }], + competitive_landscape: "分析文本", + strategy_report: "完整策略报告" + } + +GET /api/v1/market-analysis/reports + 列表用户历史报告 + +GET /api/v1/market-analysis/reports/{id} + 获取报告详情 +``` + +#### 关键设计决策 + +- **异步生成**: 报告生成可能需要 30-60 秒，使用 Celery 异步任务 +- **缓存策略**: 相同产品+市场的报告缓存 7 天 +- **渐进式展示**: 前端先显示 loading，各个模块完成后逐步展示（趋势数据先出 → 客户发现 → 报告） +- **用户引导**: 首次使用后提示"保存到产品库"或"一键生成开发信" + +--- + +## 九、护城河策略（V2 更新） + +V1 有三层护城河，V2 增加两层： + +### 第 4 层: 客户健康度数据集 + +``` +用户每日查看健康度 → 记录评分变化 → 验证建议有效性 → 优化评分模型 + ↓ + 跨用户匿名统计 → 行业基准对比 + "你的客户健康度分布 vs 同行业用户的分布" +``` + +网络效应: 用户越多，行业基准越准，评分越有价值。 + +### 第 5 层: AI跟进策略知识库 + +``` +每次跟进记录: + ├─ 客户状态（评分/沉默天数/阶段） + ├─ 跟进策略（时机/内容/渠道） + ├─ 结果（回复/未回复/成交） + └─ 用户反馈 + +→ 积累到 1000+ 条后: + ├─ 分析"什么策略在什么场景下最有效" + ├─ 自动优化策略选择器 + └─ 新用户直接受益于"过去1000次跟进的最佳实践" +``` + +--- + +## 十一、安全设计 | 维度 | 措施 | |------|------| @@ -338,7 +549,7 @@ WhatsApp User WhatsApp Cloud API TradeMate --- -## 九、部署架构 +## 十二、部署架构 ``` 开发环境: docker-compose up（单机） diff --git a/docs/UPGRADE_PLAN.md b/docs/UPGRADE_PLAN.md new file mode 100644 index 0000000..8f88617 --- /dev/null +++ b/docs/UPGRADE_PLAN.md @@ -0,0 +1,195 @@ +# 外贸小助手 (TradeMate) — V2 改造升级计划 + +> 版本: v1.0 +> 创建日期: 2026-05-10 +> 基于: 竞品调研 + 用户需求分析 + 现有代码审计 + +--- + +## 一、升级思路 + +### 核心原则 + +不堆功能，只做三件事： + +1. **帮用户做决策** — 不只看数据，给建议（健康度看板） +2. **帮用户省时间** — 不让用户设规则，AI自动判断（跟进引擎） +3. **帮用户找机会** — 不买海关数据，AI用公开信息分析（市场分析） + +### 和竞品的本质区别 + +| 维度 | 竞品思路 | 我们的思路 | +|------|---------|-----------| +| 数据 | 买海关数据（贵，滞后） | 用免费公开数据 + AI分析 | +| 流程 | 预设规则（固定时间/模板） | AI动态判断（时机/内容/渠道都个性化） | +| 体验 | 给个分数让用户自己猜 | 给分数 + 原因 + 建议动作 | +| 成本 | 年费几万起 + 邮件服务费 | 零外部采购成本，纯软件投入 | + +--- + +## 二、功能一：客户健康度看板 + +### 优先级 + +**P0 — 先做这个**。数据已有，投入最小，用户感知最强。 + +### 实现步骤 + +| 步骤 | 内容 | 涉及文件 | 预估工时 | +|------|------|---------|---------| +| 1.1 | 实现 `CustomerHealthService` 评分引擎 | `backend/app/services/customer_health.py` | 4h | +| 1.2 | 实现健康度 API 端点 | `backend/app/api/v1/customer_health.py` | 2h | +| 1.3 | 注册路由到 main.py | `backend/app/main.py` | 0.5h | +| 1.4 | 客户列表页顶部增加健康度概览卡片 | `uni-app/src/pages/customers/customers.vue` | 3h | +| 1.5 | 客户详情页增加健康度看板 | `uni-app/src/pages/customers/customers.vue` detail modal | 3h | +| 1.6 | Celery 定时任务每小时更新评分缓存 | `backend/app/workers/tasks.py` | 2h | +| 1.7 | 前端 `api.js` 新增 healthApi | `uni-app/src/utils/api.js` | 0.5h | + +**总工时**: ~15h | **外部依赖**: 无 + +### 评分模型（上线版） + +``` +health_score = + response_trend * 25% + # 响应趋势（messages数据） + sentiment_score * 20% + # 情感轨迹（AI分析最近3条消息） + inquiry_depth * 20% + # 询盘深度（关键词匹配MOQ/认证等） + silence_score * 20% + # 沉默天数（归一化） + business_value * 15% # 商业价值（报价单数据） +``` + +无需 ML 模型，规则引擎即可，同步计算 < 50ms。 + +--- + +## 三、功能二：AI 智能跟进助手 + +### 优先级 + +**P1 — 在看板之后做**。依赖健康度数据，但有跟进引擎才有闭环。 + +### 实现步骤 + +| 步骤 | 内容 | 涉及文件 | 预估工时 | +|------|------|---------|---------| +| 2.1 | 创建 `followup_strategies` 和 `followup_logs` 数据模型 | `backend/app/models/followup.py` | 2h | +| 2.2 | 实现 `FollowupEngine` 策略选择器 + 内容生成 | `backend/app/services/followup_engine.py` | 6h | +| 2.3 | 实现跟进 API 端点 | `backend/app/api/v1/followup.py` | 3h | +| 2.4 | 注册路由到 main.py | `backend/app/main.py` | 0.5h | +| 2.5 | Celery beat 定时轮检（每6h） | `backend/app/workers/tasks.py` | 2h | +| 2.6 | 跟进提醒通知对接 PushService | `backend/app/services/followup_engine.py` | 2h | +| 2.7 | Alembic 迁移脚本 | `backend/alembic/versions/` | 1h | +| 2.8 | 前端跟进列表页 + 通知入口 | `uni-app/src/pages/followup/followup.vue` | 4h | +| 2.9 | 首页待跟进卡片组件 | `uni-app/src/pages/index/index.vue` | 2h | +| 2.10 | 前端 `api.js` 新增 followupApi | `uni-app/src/utils/api.js` | 0.5h | + +**总工时**: ~23h | **外部依赖**: 无（复用 AI 营销素材能力） + +### 跟进策略示例（初始版本） + +| 触发条件 | 策略 | 渠道 | AI提示词方向 | +|---------|------|------|------------| +| 沉默 3-5 天, 健康分 50-79 | 温和提醒 | WhatsApp | "Just checking in if you need any further information" | +| 沉默 6-10 天, 健康分 30-49 | 价值提供 | Email | 推送新品目录/行业资讯/产品认证 | +| 沉默 11+ 天, 健康分 <30 | 重新激活 | Email | 限时折扣/客户调查/节日问候 | +| 客户有回复但未成交, 健康分 60+ | 促进决策 | WhatsApp | 成功案例/限时报价/差异优势 | + +--- + +## 四、功能三：智能市场机会分析 + +### 优先级 + +**P2 — 最后做**。功能独立，用户价值高但实现复杂，涉及外部API集成。 + +### 实现步骤 + +| 步骤 | 内容 | 涉及文件 | 预估工时 | +|------|------|---------|---------| +| 3.1 | 创建 `market_reports` 数据模型 | `backend/app/models/market_report.py` | 1h | +| 3.2 | 实现 UN COMTRADE API 集成 | `backend/app/services/market_data.py` | 3h | +| 3.3 | 实现 Google Custom Search 集成 | `backend/app/services/market_data.py` | 2h | +| 3.4 | 实现 `MarketAnalysisService` AI报告生成 | `backend/app/services/market_analysis.py` | 6h | +| 3.5 | 实现市场分析 API 端点 | `backend/app/api/v1/market_analysis.py` | 3h | +| 3.6 | 注册路由到 main.py | `backend/app/main.py` | 0.5h | +| 3.7 | Celery 异步报告生成任务 | `backend/app/workers/tasks.py` | 2h | +| 3.8 | Alembic 迁移脚本 | `backend/alembic/versions/` | 1h | +| 3.9 | 前端市场分析页面 | `uni-app/src/pages/analysis/analysis.vue` | 4h | +| 3.10 | 添加 pages.json 路由 | `uni-app/src/pages.json` | 0.5h | +| 3.11 | 前端 `api.js` 新增 marketApi | `uni-app/src/utils/api.js` | 0.5h | + +**总工时**: ~23.5h | **外部依赖**: UN COMTRADE 免费API注册 + Google Custom Search API key + +### 数据源依赖 + +| 数据源 | 注册成本 | 调用限制 | 是否需要 | +|--------|---------|---------|---------| +| UN COMTRADE API | 免费注册 | 无硬限制 | 必须（趋势数据核心） | +| Google Custom Search | 免费（100次/天） | 100次/天 | 可选（客户发现增强） | +| AI 自有知识 | 已有 | 无限制 | 必须（报告生成） | + +--- + +## 五、工作量汇总与排期 + +### 总览 + +| 功能 | 优先级 | 工时期 | 外部依赖 | 建议开始 | +|------|--------|-------|---------|---------| +| 客户健康度看板 | P0 | 2天 | 无 | 第1天 | +| AI 智能跟进助手 | P1 | 3天 | 无 | 第3天 | +| 智能市场机会分析 | P2 | 3天 | UN COMTRADE + Google API | 第6天 | + +### 并行策略 + +``` +第1-2天: 客户健康度看板 (后端1天 + 前端1天) + │ +第3-5天: AI 跟进助手 (后端2天 + 前端1天) + │ +第6-8天: 市场机会分析 (后端2天 + 前端1天) +``` + +总工期约 **8 天**（一人全栈），若有前后端分工可压缩至 **5-6 天**。 + +### 外部依赖注册清单 + +``` +□ UN COMTRADE API: https://comtrade.un.org/auth/register/ +□ Google Custom Search API: https://programmablesearchengine.google.com/ + → 创建搜索引掣 → 获取 API Key + Search Engine ID +``` + +--- + +## 六、验收标准 + +### 健康度看板验收 + +``` +□ 客户列表顶部展示健康度概览（活跃/需关注/高危数量） +□ 每个客户展示健康等级标签（🟢/🟡/🔴） +□ 点击客户进入详情 → 展示评分维度明细 + 建议动作 +□ 评分各维度有来源说明（不是黑盒） +□ 首页展示总览数据 +``` + +### AI跟进助手验收 + +``` +□ 系统自动检测跟进时机 → 推送通知 +□ 跟进通知含客户背景摘要 + AI建议内容 +□ 用户可一键发送/编辑后发送 +□ 跟进后自动追踪客户回复状态 +□ 跟进记录可追溯 +``` + +### 市场机会分析验收 + +``` +□ 用户输入产品信息 → 30-60秒生成分析报告 +□ 报告含推荐市场 Top 3 + 潜在客户 + 策略建议 +□ 报告可保存到产品库 +□ 报告可一键跳转生成营销文案 +□ 渐进式加载（先展示趋势，逐步补充完整报告） +``` diff --git a/uni-app/favicon.ico b/uni-app/favicon.ico new file mode 100644 index 0000000..04cc4b9 Binary files /dev/null and b/uni-app/favicon.ico differ diff --git a/uni-app/index.html b/uni-app/index.html index 996fba8..cef7e67 100644 --- a/uni-app/index.html +++ b/uni-app/index.html @@ -3,7 +3,9 @@ -