"""提醒服务模块 负责系统中各类业务提醒的查询、标记已读、以及自动生成提醒记录。 支持三类提醒场景： - 欠款逾期提醒（arrears） - 沉默客户提醒（inactive_customer） - 物流超时提醒（logistics_timeout） 被调用方：reminders 路由、salesman 路由（仪表盘提醒列表）、定时任务入口。 """ from datetime import datetime, timedelta from sqlalchemy.exc import SQLAlchemyError from sqlalchemy.orm import Session from backend.app.core.cache import cache_delete_pattern, cache_get, cache_set, make_cache_key from backend.app.core.error_codes import ErrorCode from backend.app.core.exceptions import AppException from backend.app.repositories.config_repository import ConfigRepository from backend.app.repositories.reminder_repository import ReminderRepository from backend.app.services.audit_service import audit_service class ReminderService: """提醒业务服务。 依赖： - ReminderRepository：提醒数据的增删查改 - ConfigRepository：读取系统配置（沉默天数阈值、物流超时小时数等） - AuditService：操作审计日志 """ def __init__(self) -> None: self.repository = ReminderRepository() self.config_repository = ConfigRepository() def list_reminders(self, session: Session | None = None, filters: dict | None = None) -> dict: """分页查询提醒列表。 参数： session: 数据库会话，不可为 None。 filters: 可选的筛选条件，支持 page_no、page_size、receiver_user_id 等。 返回： 包含 total、page_no、page_size、list 的分页结果字典。 被调用方：reminders 路由（列表接口）、salesman 路由（仪表盘提醒数）。 """ if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) filters = filters or {} cache_key = make_cache_key("reminder:list", **filters) cached = cache_get(cache_key) if cached is not None: return cached try: reminders = self.repository.list_reminders(session, filters) page_no = filters.get("page_no", 1) page_size = filters.get("page_size", 20) start = max(page_no - 1, 0) * page_size page_list = reminders[start : start + page_size] result = { "total": len(reminders), "page_no": page_no, "page_size": page_size, "list": [self._map_reminder(item) for item in page_list], } cache_set(cache_key, result, ttl=30) return result except SQLAlchemyError as exc: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc def read_reminder(self, reminder_id: int, session: Session | None = None, current_user: dict | None = None) -> dict: """将指定提醒标记为已读。 参数： reminder_id: 提醒记录 ID。 session: 数据库会话，不可为 None。 current_user: 当前登录用户信息；销售角色只能标记自己的提醒。 返回： 包含 reminder_id 和 status 的字典。 被调用方：reminders 路由（标记已读接口）。 """ if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) try: reminder = self.repository.get_reminder(session, reminder_id) if reminder is None: raise AppException(code=ErrorCode.NOT_FOUND, message="提醒不存在", status_code=404) if current_user and current_user.get("role_code") == "salesman": if reminder.receiver_user_id != current_user.get("user_id"): raise AppException(code=ErrorCode.FORBIDDEN, message="无权操作他人提醒", status_code=403) before_status = reminder.status reminder.status = "read" session.add(reminder) audit_service.write_log( session, { "operate_type": "reminder_read", "biz_type": reminder.biz_type, "biz_id": reminder.biz_id, "before_value": {"status": before_status}, "after_value": {"status": reminder.status}, "remark": f"提醒 {reminder_id} 标记已读", }, ) session.commit() cache_delete_pattern("reminder:*") cache_delete_pattern("dashboard:*") return {"reminder_id": reminder.id, "status": reminder.status} except AppException: session.rollback() raise except SQLAlchemyError as exc: session.rollback() raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc def check_arrears(self, session: Session | None = None) -> dict: """检查逾期欠款并自动生成提醒。 遍历所有逾期且未提醒的欠款记录，为对应销售人员创建提醒。 参数： session: 数据库会话，不可为 None。 返回： 包含 checked 和 created_count 的结果字典。 被调用方：reminders 路由（check-arrears 接口）、check_all 方法。 """ if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) try: rows = self.repository.list_overdue_arrears(session) created_count = 0 for arrears, customer, order in rows: if arrears.due_date is None or arrears.due_date >= datetime.now().date(): continue receiver_user_id = (customer.salesman_id if customer and customer.salesman_id else 0) or 0 if receiver_user_id <= 0: continue existed = self.repository.find_active_reminder( session, "arrears", "customer_arrears", arrears.id, receiver_user_id, ) if existed is not None: continue title = f"客户欠款逾期提醒 - {customer.customer_name if customer else '未知客户'}" content = ( f"客户存在逾期欠款，欠款金额 {float(arrears.arrears_amount or 0):.2f} 元，" f"订单编号 {order.order_no if order else '-'}，请及时跟进。" ) self.repository.create_reminder( session, { "reminder_type": "arrears", "biz_type": "customer_arrears", "biz_id": arrears.id, "receiver_user_id": receiver_user_id, "reminder_title": title, "reminder_content": content, "status": "pending", "sent_at": datetime.now(), }, ) arrears.reminded_at = datetime.now() arrears.status = "overdue" session.add(arrears) created_count += 1 session.commit() cache_delete_pattern("reminder:*") cache_delete_pattern("dashboard:*") return {"checked": True, "created_count": created_count} except AppException: session.rollback() raise except SQLAlchemyError as exc: session.rollback() raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc def check_inactive_customers(self, session: Session | None = None) -> dict: """检查沉默客户并自动生成提醒。 根据系统配置的天数阈值和金额阈值，查找超期未下单的客户， 为对应销售人员创建沉默客户提醒。 参数： session: 数据库会话，不可为 None。 返回： 包含 checked 和 created_count 的结果字典。 被调用方：reminders 路由（check-inactive-customers 接口）、check_all 方法。 """ if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) try: inactive_days = int(self._get_config_value(session, "inactive_customer_days", "90")) amount_threshold = float(self._get_config_value(session, "inactive_customer_amount_threshold", "1000")) inactive_before = datetime.now() - timedelta(days=inactive_days) rows = self.repository.list_inactive_customers(session, inactive_before) created_count = 0 for customer, latest_order, total_amount in rows: if total_amount < amount_threshold: continue receiver_user_id = (customer.salesman_id or 0) if receiver_user_id <= 0: continue existed = self.repository.find_active_reminder( session, "inactive_customer", "customer", customer.id, receiver_user_id, ) if existed is not None: continue last_order_time = ( latest_order.created_at.strftime("%Y-%m-%d %H:%M:%S") if latest_order and latest_order.created_at else "暂无订单" ) self.repository.create_reminder( session, { "reminder_type": "inactive_customer", "biz_type": "customer", "biz_id": customer.id, "receiver_user_id": receiver_user_id, "reminder_title": f"沉默客户提醒 - {customer.customer_name}", "reminder_content": f"客户超过 {inactive_days} 天未下单，最近订单时间：{last_order_time}。", "status": "pending", "sent_at": datetime.now(), }, ) created_count += 1 session.commit() cache_delete_pattern("reminder:*") cache_delete_pattern("dashboard:*") return {"checked": True, "created_count": created_count} except AppException: session.rollback() raise except SQLAlchemyError as exc: session.rollback() raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc def check_logistics_timeout(self, session: Session | None = None) -> dict: """检查物流超时并自动生成提醒。 根据系统配置的超时小时数，查找超时未完成物流流转的订单， 为对应销售人员创建物流超时提醒。 参数： session: 数据库会话，不可为 None。 返回： 包含 checked 和 created_count 的结果字典。 被调用方：reminders 路由（check-logistics-timeout 接口）、check_all 方法。 """ if session is None: raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库连接不可用", status_code=500) try: timeout_hours = int(self._get_config_value(session, "logistics_timeout_hours", "48")) timeout_before = datetime.now() - timedelta(hours=timeout_hours) orders = self.repository.list_logistics_timeout_candidates(session, timeout_before) created_count = 0 for order in orders: receiver_user_id = (order.salesman_id or 0) if receiver_user_id <= 0: continue existed = self.repository.find_active_reminder( session, "logistics_timeout", "sales_order", order.id, receiver_user_id, ) if existed is not None: continue self.repository.create_reminder( session, { "reminder_type": "logistics_timeout", "biz_type": "sales_order", "biz_id": order.id, "receiver_user_id": receiver_user_id, "reminder_title": f"物流超时提醒 - {order.order_no}", "reminder_content": f"订单 {order.order_no} 超过 {timeout_hours} 小时未完成物流流转，请及时跟进。", "status": "pending", "sent_at": datetime.now(), }, ) created_count += 1 session.commit() cache_delete_pattern("reminder:*") cache_delete_pattern("dashboard:*") return {"checked": True, "created_count": created_count} except AppException: session.rollback() raise except SQLAlchemyError as exc: session.rollback() raise AppException(code=ErrorCode.INTERNAL_ERROR, message="数据库异常", status_code=500) from exc def check_all(self, session: Session | None = None) -> dict: """统一触发入口，一次性执行全部三类提醒检查。 便于管理端定时任务或手动补跑，依次调用欠款、沉默客户、物流超时检查。 参数： session: 数据库会话，为 None 时返回零计数结果。 返回： 包含各类提醒创建数量和 total_created_count 的汇总字典。 被调用方：reminders 路由（check-all 接口）。 """ if session is None: return { "checked": True, "arrears_created_count": 0, "inactive_customer_created_count": 0, "logistics_timeout_created_count": 0, "total_created_count": 0, } # 统一触发入口直接串起三类提醒，便于管理端定时任务或手动补跑。 arrears_result = self.check_arrears(session) inactive_result = self.check_inactive_customers(session) logistics_result = self.check_logistics_timeout(session) total_created_count = ( int(arrears_result.get("created_count", 0)) + int(inactive_result.get("created_count", 0)) + int(logistics_result.get("created_count", 0)) ) return { "checked": True, "arrears_created_count": arrears_result.get("created_count", 0), "inactive_customer_created_count": inactive_result.get("created_count", 0), "logistics_timeout_created_count": logistics_result.get("created_count", 0), "total_created_count": total_created_count, } def _get_config_value(self, session: Session, config_key: str, default: str) -> str: """从系统配置表读取配置值，不存在时返回默认值。 参数： session: 数据库会话。 config_key: 配置键名。 default: 当配置不存在或为空时的默认值。 返回： 配置值字符串。 """ config = self.config_repository.get_by_key(session, config_key) return config.config_value if config is not None and config.config_value else default def _map_reminder(self, reminder) -> dict: """将数据库提醒对象转换为 API 返回用的字典格式。 参数： reminder: SQLAlchemy 的提醒模型对象。 返回： 包含提醒各字段的字典，日期格式化为 'YYYY-MM-DD HH:MM:SS'。 """ return { "reminder_id": reminder.id, "title": reminder.reminder_title, "content": reminder.reminder_content, "type": reminder.reminder_type, "biz_type": reminder.biz_type, "biz_id": reminder.biz_id, "receiver_user_id": reminder.receiver_user_id, "status": reminder.status, "sent_at": reminder.sent_at.strftime("%Y-%m-%d %H:%M:%S") if reminder.sent_at else "", "created_at": reminder.created_at.strftime("%Y-%m-%d %H:%M:%S") if reminder.created_at else "", } reminder_service = ReminderService()