Ver Fonte

feat: update

jerry há 1 mês atrás
pai
commit
09cf110e05
42 ficheiros alterados com 2663 adições e 205 exclusões
  1. 12 3
      .env
  2. 122 14
      app/api/endpoints/common.py
  3. 3 3
      app/api/endpoints/node_configuration.py
  4. 6 3
      app/api/endpoints/order.py
  5. 8 3
      app/api/endpoints/payment.py
  6. 2 2
      app/api/endpoints/product.py
  7. 3 1
      app/api/endpoints/ticket.py
  8. 22 8
      app/api/endpoints/vas_task.py
  9. 14 2
      app/core/config.py
  10. 9 6
      app/schemas/settlement.py
  11. 10 0
      app/schemas/vas_task.py
  12. 2 2
      app/services/agency_service.py
  13. 15 1
      app/services/agent/tools/builtin/__init__.py
  14. 105 0
      app/services/agent/tools/builtin/account_pool_tools.py
  15. 11 11
      app/services/agent/tools/builtin/node_config_tools.py
  16. 108 8
      app/services/agent/tools/builtin/order_tools.py
  17. 62 0
      app/services/agent/tools/builtin/payment_tools.py
  18. 10 10
      app/services/agent/tools/builtin/plugin_tools.py
  19. 117 1
      app/services/agent/tools/builtin/product_tools.py
  20. 7 7
      app/services/agent/tools/builtin/proxy_pool_tools.py
  21. 110 0
      app/services/agent/tools/builtin/settlement_tools.py
  22. 125 0
      app/services/agent/tools/builtin/system_config_tools.py
  23. 137 0
      app/services/agent/tools/builtin/task_queue_tools.py
  24. 204 0
      app/services/agent/tools/builtin/ticket_tools.py
  25. 149 0
      app/services/agent/tools/builtin/user_tools.py
  26. 3 3
      app/services/auth_service.py
  27. 3 3
      app/services/node_configuration_service.py
  28. 18 5
      app/services/order_service.py
  29. 34 8
      app/services/payment_service.py
  30. 20 2
      app/services/product_service.py
  31. 230 0
      app/services/r2_storage_service.py
  32. 21 1
      app/services/seaweedfs_service.py
  33. 93 49
      app/services/settlement_service.py
  34. 70 9
      app/services/ticket_service.py
  35. 158 24
      app/services/vas_task_service.py
  36. 2 1
      requirements.txt
  37. 113 11
      scripts/notification_templates.py
  38. 4 4
      tests/test_agent.py
  39. 47 0
      tests/test_r2_storage.py
  40. 215 0
      tests/test_rbac_idor_guards.py
  41. 82 0
      tests/test_settlement_tech_attribution.py
  42. 177 0
      tests/test_ticket_duplicate_guard.py

+ 12 - 3
.env

@@ -1,8 +1,7 @@
 ENV=DEV
 DATABASE_URL=mysql+asyncmy://root:GqLLL7Bofj0WaaOpp.0@text.skin:3306/book_user_info?charset=utf8mb4
 REDIS_URL=redis://:STEs2x6ML0U1HlpE9SojM6YU7QPhqzY8@text.skin:6379/0
-OPENAI_API_KEY=sk-893e895724c6403d81374e515ffaf427
-LLM_API_KEY=sk-3eea553bb7844623a7da401c8323ce8c
+LLM_API_KEY=sk-7c48e820b0354188b0af4e5168c6d264
 LLM_BASE_URL=https://api.deepseek.com
 LLM_MODEL=deepseek-v4-flash
 STRIPE_API_KEY=sk_live_xxxx
@@ -15,4 +14,14 @@ TELEGRAM_API_TOKEN=xxxxx
 WECHAT_API_TOKEN=a28233ef-80b6-4131-96c0-4cda1d06cefb
 WHATSAPP_API_BASE_URL=https://waha.text.skin
 WHATSAPP_API_KEY=339bdfab10cd43c685438adaa66f47c3
-WHATSAPP_SESSION=default
+WHATSAPP_SESSION=default
+
+# -----------------------
+# Cloudflare R2 Storage
+# -----------------------
+R2_ACCOUNT_ID=f97ce2711cc348200b0de273e48f2230
+R2_ACCESS_KEY_ID=990d57a8f67a6cb024e6660dd2465b91
+R2_SECRET_ACCESS_KEY=9d7be7336c84d412a8eb57f624f71d1f40b316713dec0af290545d23ae73d380
+R2_ENDPOINT_URL=https://f97ce2711cc348200b0de273e48f2230.r2.cloudflarestorage.com
+R2_BUCKET_NAME=starta
+R2_PUBLIC_DOMAIN=

+ 122 - 14
app/api/endpoints/common.py

@@ -1,5 +1,5 @@
 from app.core.logger import logger
-from fastapi import APIRouter, Response, Query, Depends, UploadFile, File
+from fastapi import APIRouter, Response, Query, Depends, UploadFile, File, Request
 from fastapi.responses import RedirectResponse
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.database import get_db
@@ -9,12 +9,18 @@ from app.schemas.http_session import HttpSessionCreate, HttpSessionOut
 from app.schemas.llm import ParseUserInputsOut, ParseUserInputsPayload
 from app.schemas.resource import FileUploadOut
 from app.schemas.short_url import ShortUrlCreate, ShortUrlOut
-from app.schemas.statistics import VasStatisticsOverviewOut
 from app.services.http_session_service import HttpSessionService
 from app.services.llm_service import LlmService
+from typing import Optional
+from redis.asyncio import Redis
+from app.core.redis import get_redis_client
+from app.core.auth import get_current_user
+from app.models.user import VasUser
+from app.core.biz_exception import BizLogicError
+from app.services.r2_storage_service import R2StorageService
 from app.services.seaweedfs_service import SeaweedFSService
 from app.services.short_url_service import ShortUrlService
-from app.services.statistics_service import StatisticsService
+
 
 public_router = APIRouter()
 protected_router = APIRouter()
@@ -46,21 +52,130 @@ async def http_session_get_by_sid(
     return success(data=obj)
 
 
-@public_router.post("/resource/upload_file", summary="上传文件", tags=["文件管理"], response_model=ApiResponse[FileUploadOut])
-async def resource_upload_file(file: UploadFile = File(...)):
+@protected_router.post("/resource/upload_file", summary="上传文件(需登录鉴权)", tags=["文件管理"], response_model=ApiResponse[FileUploadOut])
+async def resource_upload_file(
+    request: Request,
+    file: UploadFile = File(...),
+    current_user: VasUser = Depends(get_current_user),
+    redis_client: Redis = Depends(get_redis_client),
+):
+    # 提取真实客户端 IP
+    client_ip = (
+        request.headers.get("cf-connecting-ip")
+        or (request.headers.get("x-forwarded-for", "").split(",")[0].strip() or None)
+        or (request.client.host if request.client else "unknown")
+    )
+
+    # 防刷机制 1:单 IP 频次限制(单个 IP 每分钟最多允许 3 次上传)
+    ip_rate_key = f"rate:seaweedfs_upload:ip:{client_ip}"
+    ip_count = await redis_client.incr(ip_rate_key)
+    if ip_count == 1:
+        await redis_client.expire(ip_rate_key, 60)
+    elif ip_count > 3:
+        raise BizLogicError("Too many upload requests from this IP address. Please try again later.")
+
+    # 防刷机制 2:单用户频次限制(单个账号每分钟最多允许 3 次上传)
+    user_rate_key = f"rate:seaweedfs_upload:user:{current_user.id}"
+    user_count = await redis_client.incr(user_rate_key)
+    if user_count == 1:
+        await redis_client.expire(user_rate_key, 60)
+    elif user_count > 3:
+        raise BizLogicError("Too many upload requests for this account. Please try again later.")
+
     result = await SeaweedFSService.upload(file)
     return success(data=result)
 
 
 @public_router.get("/resource/download_file", summary="下载文件", tags=["文件管理"])
-async def resource_get_file(fid: str):
+async def resource_get_file(
+    request: Request,
+    fid: str = Query(...),
+    redis_client: Redis = Depends(get_redis_client),
+):
+    # 下载防刷限制:单 IP 每分钟最多 60 次下载请求,防止高频消耗服务器下行带宽
+    client_ip = (
+        request.headers.get("cf-connecting-ip")
+        or (request.headers.get("x-forwarded-for", "").split(",")[0].strip() or None)
+        or (request.client.host if request.client else "unknown")
+    )
+    dl_rate_key = f"rate:seaweedfs_download:ip:{client_ip}"
+    dl_count = await redis_client.incr(dl_rate_key)
+    if dl_count == 1:
+        await redis_client.expire(dl_rate_key, 60)
+    elif dl_count > 60:
+        raise BizLogicError("Download frequency limit exceeded. Please try again later.")
+
     data = await SeaweedFSService.get(fid)
     if not data:
         return Response(content=b"File not found", status_code=404, media_type="text/plain")
     content, mime = data
     return Response(content=content, media_type=mime)
 
-
+@protected_router.post("/r2/upload", summary="上传文件至 Cloudflare R2(需登录鉴权)", tags=["R2 对象存储"], response_model=ApiResponse[FileUploadOut])
+async def r2_upload_file(
+    request: Request,
+    file: UploadFile = File(...),
+    bucket: Optional[str] = Query(None, description="目标存储桶名称(可选,留空使用环境变量默认配置)"),
+    prefix: str = Query("uploads", description="存储目录前缀"),
+    current_user: VasUser = Depends(get_current_user),
+    redis_client: Redis = Depends(get_redis_client),
+):
+    # 提取真实客户端 IP(优先 Cloudflare CDN 提供的 cf-connecting-ip,其次 x-forwarded-for)
+    client_ip = (
+        request.headers.get("cf-connecting-ip")
+        or (request.headers.get("x-forwarded-for", "").split(",")[0].strip() or None)
+        or (request.client.host if request.client else "unknown")
+    )
+
+    # 防刷机制 1:单 IP 频次限制(单个 IP 每分钟最多允许 15 次上传,防止多账号集中在同个 IP 恶意刷量)
+    ip_rate_key = f"rate:r2_upload:ip:{client_ip}"
+    ip_count = await redis_client.incr(ip_rate_key)
+    if ip_count == 1:
+        await redis_client.expire(ip_rate_key, 60)
+    elif ip_count > 3:
+        raise BizLogicError("Too many upload requests from this IP address. Please try again later.")
+
+    # 防刷机制 2:单用户频次限制(单个账号每分钟最多允许 10 次上传)
+    user_rate_key = f"rate:r2_upload:user:{current_user.id}"
+    user_count = await redis_client.incr(user_rate_key)
+    if user_count == 1:
+        await redis_client.expire(user_rate_key, 60)
+    elif user_count > 3:
+        raise BizLogicError("Too many upload requests for this account. Please try again later.")
+
+    result = await R2StorageService.upload(file=file, bucket=bucket, prefix=prefix)
+    return success(data=FileUploadOut(fid=result["fid"], url=result["url"]))
+
+
+@public_router.get("/r2/file", summary="从 Cloudflare R2 下载/预览文件", tags=["R2 对象存储"])
+async def r2_get_file(
+    request: Request,
+    key: str = Query(..., description="文件存储 key"),
+    bucket: Optional[str] = Query(None, description="存储桶名称(可选)"),
+    redis_client: Redis = Depends(get_redis_client),
+):
+    # 下载防刷限制:单 IP 每分钟最多 60 次下载请求,防止黑客对文件下载进行放大攻击
+    client_ip = (
+        request.headers.get("cf-connecting-ip")
+        or (request.headers.get("x-forwarded-for", "").split(",")[0].strip() or None)
+        or (request.client.host if request.client else "unknown")
+    )
+    dl_rate_key = f"rate:r2_download:ip:{client_ip}"
+    dl_count = await redis_client.incr(dl_rate_key)
+    if dl_count == 1:
+        await redis_client.expire(dl_rate_key, 60)
+    elif dl_count > 60:
+        raise BizLogicError("Download frequency limit exceeded. Please try again later.")
+
+    data = await R2StorageService.get_file(key=key, bucket=bucket)
+    if not data:
+        return Response(content=b"File not found", status_code=404, media_type="text/plain")
+    content, mime = data
+    return Response(
+        content=content,
+        media_type=mime,
+        headers={"Cache-Control": "public, max-age=86400"}
+    )
 
 @admin_required_router.post("/s/generate", summary="生成短链接地址<压缩地址长度>", tags=["Short URL"], response_model=ApiResponse[ShortUrlOut])
 async def short_url_generate(
@@ -79,13 +194,6 @@ async def short_url_request(short_key: str, db: AsyncSession = Depends(get_db)):
     return RedirectResponse(url=long_url, status_code=302)
 
 
-@admin_required_router.get("/vas/statistics/overview", summary="系统概览", tags=["textskin"], response_model=ApiResponse[VasStatisticsOverviewOut])
-async def vas_statistics_overview(
-    db: AsyncSession = Depends(get_db)
-):
-    overview = await StatisticsService.overview(db)
-    return success(data=overview)
-
 
 @admin_required_router.post("/vas/llm/data_parsing", summary="llm数据解析", tags=["textskin"], response_model=ApiResponse[ParseUserInputsOut])
 async def vas_llm_data_parsing(

+ 3 - 3
app/api/endpoints/node_configuration.py

@@ -103,7 +103,7 @@ async def create_cluster_node(
     current_user: VasUser = Depends(get_current_user),
 ):
     node = await NodeConfigurationService.create_cluster_node(db=db, data=payload)
-    return success(data=node, message="节点档案登记成功")
+    return success(data=node, message="Node registered successfully")
 
 
 @admin_required_router.post(
@@ -120,7 +120,7 @@ async def update_cluster_node(
     node = await NodeConfigurationService.update_cluster_node(
         db=db, node_id=node_id, data=payload
     )
-    return success(data=node, message="节点档案更新成功")
+    return success(data=node, message="Node updated successfully")
 
 
 @admin_required_router.post(
@@ -134,7 +134,7 @@ async def delete_cluster_node(
     current_user: VasUser = Depends(get_current_user),
 ):
     result = await NodeConfigurationService.delete_cluster_node(db=db, node_id=node_id)
-    return success(data=result, message="节点注销成功")
+    return success(data=result, message="Node deleted successfully")
 
 
 @admin_required_router.get(

+ 6 - 3
app/api/endpoints/order.py

@@ -87,12 +87,13 @@ async def vas_order_adjust_price(
     return success(data=order)
 
 
-@admin_required_router.get("/vas/order/detail", summary="查询订单", tags=["textskin"], response_model=ApiResponse[VasOrderOut])
+@protected_router.get("/vas/order/detail", summary="查询订单", tags=["textskin"], response_model=ApiResponse[VasOrderOut])
 async def vas_order_get_detail(
     order_id: str,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
-    order = await OrderService.get(db, order_id)
+    order = await OrderService.get_authorized_order(db, order_id, current_user)
     return success(data=order)
 
 
@@ -129,7 +130,7 @@ async def vas_order_list_by_user(
     return success(data=orders)
 
 
-@protected_router.get("/vas/order/list_all", summary="查看所有订单(支持渠道/对接人/结算状态筛选)", tags=["textskin"], response_model=ApiResponse[PageResponse[VasOrderOut]])
+@admin_required_router.get("/vas/order/list_all", summary="查看所有订单(支持渠道/对接人/结算状态筛选)", tags=["textskin"], response_model=ApiResponse[PageResponse[VasOrderOut]])
 async def vas_order_list_all(
     page: int = Query(0, description="第几页"),
     size: int = Query(10, description="分页大小"),
@@ -166,7 +167,9 @@ async def vas_order_event_create(
 @protected_router.get("/vas/order-event/list", summary="获取订单的所有事件", tags=["textskin"], response_model=ApiResponse[List[VasOrderEventOut]])
 async def vas_list_order_events_by_order(
     order_id: str,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
+    await OrderService.get_authorized_order(db, order_id, current_user)
     events = await OrderEventService.get_by_order_id(db, order_id)
     return success(data=events)

+ 8 - 3
app/api/endpoints/payment.py

@@ -15,6 +15,7 @@ from app.schemas.payment_qr import VasPaymentQrCreate, VasPaymentQrOut, VasPayme
 from app.services.payment_provider_service import PaymentProviderService
 from app.services.payment_qr_service import PaymentQrService
 from app.services.payment_service import PaymentService
+from app.services.order_service import OrderService
 
 public_router = APIRouter()
 protected_router = APIRouter()
@@ -68,19 +69,21 @@ async def vas_payment_provider_delete(
 @protected_router.post("/vas/payment/create", summary="创建支付", tags=["textskin"], response_model=ApiResponse[VasPaymentOut])
 async def vas_payment_create(
     payload: VasPaymentCreate,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
     redis_client: Redis = Depends(get_redis_client)
 ):
-    res = await PaymentService.create_payment(db, payload, redis_client)
+    res = await PaymentService.create_payment(db, payload, redis_client, current_user=current_user)
     return success(data=res)
 
 
 @protected_router.get("/vas/payment/detail", summary="获取支付详情", tags=["textskin"], response_model=ApiResponse[VasPaymentOut])
-async def vas_payment_create(
+async def vas_payment_get_detail(
     payment_id: int,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
-    res = await PaymentService.get_by_id(db, payment_id)
+    res = await PaymentService.get_authorized_payment(db, payment_id, current_user)
     return success(data=res)
 
 
@@ -129,8 +132,10 @@ async def vas_payment_confirm_list(
 @protected_router.get("/vas/payment/list_by_order", summary="获取某个订单下的所有payment记录", tags=["textskin"], response_model=ApiResponse[List[VasPaymentOut]])
 async def vas_payment_list_by_order(
     order_id: str,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
+    await OrderService.get_authorized_order(db, order_id, current_user)
     payments = await PaymentService.list_by_order(db, order_id)
     return success(data=payments)
 

+ 2 - 2
app/api/endpoints/product.py

@@ -35,7 +35,7 @@ async def vas_product_update(
 ):
     target_id = id if id is not None else product_id
     if target_id is None:
-        raise BizException(code=40001, message="商品ID不能为空")
+        raise BizException(code=40001, message="Product ID cannot be empty")
     product = await ProductService.update(db, target_id, payload)
     return success(data=product)
 
@@ -48,7 +48,7 @@ async def vas_product_delete(
 ):
     target_id = id if id is not None else product_id
     if target_id is None:
-        raise BizException(code=40001, message="商品ID不能为空")
+        raise BizException(code=40001, message="Product ID cannot be empty")
     await ProductService.delete(db, target_id)
     return success()
 

+ 3 - 1
app/api/endpoints/ticket.py

@@ -89,13 +89,15 @@ async def get_ticket_messages(
     ticket_id: int,
     page: int = 1,
     size: int = 20,
+    current_user: VasUser = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
     msgs = await TicketService.list_messages(
         db=db,
         ticket_id=ticket_id,
         page=page,
-        size=size
+        size=size,
+        current_user=current_user
     )
     return success(data=msgs)
 

+ 22 - 8
app/api/endpoints/vas_task.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import List, Optional
 from fastapi import APIRouter, Query, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.redis import get_redis_client
@@ -16,15 +16,29 @@ admin_required_router = APIRouter()
 
 @admin_required_router.get("/vas/task/list", summary="获取待执行的任务", tags=["textskin"], response_model=ApiResponse[PageResponse[VasTaskOut]])
 async def vas_task_list(
-    page: int = Query(0, description="第几页"),
-    size: int = Query(10, description="分页大小"),
-    keyword: str = Query("", description="查询条件"),
-    status: str = Query("", description="task 自定义索引"),
-    routing_key: str = Query("", description="task 自定义索引"),
-    script_version: str = Query("", description="脚本版本, 用来向后兼容"),
+    page: int = Query(1, description="第几页"),
+    size: int = Query(20, description="分页大小"),
+    keyword: str = Query("", description="查询条件 (可搜任务ID/订单号/路由/商品/客户)"),
+    status: str = Query("", description="task 状态索引"),
+    routing_key: str = Query("", description="路由键"),
+    script_version: str = Query("", description="脚本版本"),
+    product_id: Optional[int] = Query(None, description="所属商品ID"),
+    sort_by: str = Query("created_at", description="排序字段: created_at, priority, updated_at, id, order_id"),
+    sort_order: str = Query("desc", description="排序顺序: desc, asc"),
     db: AsyncSession = Depends(get_db)
 ):
-    tasks = await VasTaskService.list_task(db, status, routing_key, script_version, keyword, page, size)
+    tasks = await VasTaskService.list_task(
+        db=db,
+        status=status,
+        routing_key=routing_key,
+        script_version=script_version,
+        keyword=keyword,
+        product_id=product_id,
+        sort_by=sort_by,
+        sort_order=sort_order,
+        page=page,
+        size=size,
+    )
     return success(data=tasks)
 
 

+ 14 - 2
app/core/config.py

@@ -33,16 +33,28 @@ class Settings(BaseSettings):
     whatsapp_session: str = Field("default", description="Whatsapp session")
 
     # -----------------------
-    # Storage (SeaweedFS) & Network
+    # Storage (SeaweedFS / R2) & Network
     # -----------------------
     api_base_url: str = Field("https://api.text.skin", description="Public API base URL for resource links")
     seaweedfs_master_url: str = Field("http://seaweedfs-master:9333", description="SeaweedFS Master URL")
     seaweedfs_volume_override_host: str = Field("", description="Optional host/IP to override SeaweedFS Volume address for cross-network access")
 
+    # Cloudflare R2
+    r2_account_id: str = Field("f97ce2711cc348200b0de273e48f2230", description="Cloudflare Account ID")
+    r2_access_key_id: str = Field("", description="Cloudflare R2 Access Key ID")
+    r2_secret_access_key: str = Field("", description="Cloudflare R2 Secret Access Key")
+    r2_endpoint_url: str = Field(
+        "https://f97ce2711cc348200b0de273e48f2230.r2.cloudflarestorage.com",
+        description="Cloudflare R2 S3 Endpoint URL",
+    )
+    r2_bucket_name: str = Field("", description="Default Cloudflare R2 Bucket Name")
+    r2_public_domain: str = Field("", description="R2 Public Domain for accessing files (e.g. https://pub-xxx.r2.dev or custom domain)")
+
+
     # -----------------------
     # LLM Configuration (OpenAI-compatible)
     # -----------------------
-    llm_api_key: str = Field("", description="LLM API Key (defaults to openai_api_key)")
+    llm_api_key: str = Field("", description="LLM API Key")
     llm_base_url: str = Field("https://api.deepseek.com", description="OpenAI-compatible Base URL")
     llm_model: str = Field("deepseek-v4-flash", description="Default model name, e.g., deepseek-v4-flash, deepseek-v4-pro")
     llm_temperature: float = Field(0.0, description="LLM sampling temperature")

+ 9 - 6
app/schemas/settlement.py

@@ -7,9 +7,9 @@ from pydantic import BaseModel, Field
 class SettlementPreviewRequest(BaseModel):
     start_date: datetime = Field(..., description="统计账期起始时间")
     end_date: datetime = Field(..., description="统计账期结束时间")
-    partner_a_id: Optional[str] = Field("partner_a", description="合伙人甲方用户ID")
-    partner_b_id: Optional[str] = Field("partner_b", description="合伙人乙方用户ID")
-    default_developer_id: Optional[str] = Field(None, description="已废弃:技术分成已改为根据订单关联商品对应的插件开发管理者自动归属,无需手动指定")
+    partner_a_id: str = Field(..., description="合伙人甲方用户ID (必须指定系统真实用户)")
+    partner_b_id: str = Field(..., description="合伙人乙方用户ID (必须指定系统真实用户)")
+    default_developer_id: Optional[str] = Field(None, description="已废弃:技术分成按订单商品绑定的插件开发管理者自动归属")
 
 
 class SettlementConfirmRequest(SettlementPreviewRequest):
@@ -20,6 +20,7 @@ class SettlementConfirmRequest(SettlementPreviewRequest):
 
 class SettlementPayoutItem(BaseModel):
     user_id: str
+    user_name: Optional[str] = None # 真实姓名/昵称
     role_description: str # 如: 合伙人分红 / 社交直客提成 / 中介渠道提成 / 技术版权费
     gross_amount: int     # 应得分润(分)
     fault_penalty: int    # 过错赔偿冲销扣减(分)
@@ -29,9 +30,11 @@ class SettlementPayoutItem(BaseModel):
 class SettlementOrderDetailOut(BaseModel):
     order_id: str
     channel_type: str
-    agency_id: Optional[str]
-    handler_id: Optional[str]
-    developer_id: Optional[str]
+    agency_id: Optional[str] = None
+    handler_id: Optional[str] = None
+    handler_name: Optional[str] = None
+    developer_id: Optional[str] = None
+    developer_name: Optional[str] = None
     order_amount: int
     avg_cost: int
     net_profit: int

+ 10 - 0
app/schemas/vas_task.py

@@ -45,6 +45,16 @@ class VasTaskOut(VasTaskBase):
     created_at: datetime
     updated_at: datetime
     expire_at: datetime
+
+    # 关联商品与主订单扩展属性 (从 VasOrder 关联映射)
+    product_id: Optional[int] = None
+    product_name: Optional[str] = None
+    order_user_name: Optional[str] = None
+    order_status: Optional[str] = None
+    order_final_amount: Optional[int] = None
+    order_base_currency: Optional[str] = None
+    order_created_at: Optional[datetime] = None
+
     model_config = {
         "from_attributes": True
     }

+ 2 - 2
app/services/agency_service.py

@@ -17,7 +17,7 @@ class AgencyService:
         stmt = select(VasAgency).where(VasAgency.name == data.name)
         existing = (await db.execute(stmt)).scalar_one_or_none()
         if existing:
-            raise BizLogicError(f"中介名称 '{data.name}' 已存在")
+            raise BizLogicError(f"Agency name '{data.name}' already exists")
 
         agency_id = data.id or f"AG-{uuid.uuid4().hex[:8].upper()}"
         agency = VasAgency(
@@ -43,7 +43,7 @@ class AgencyService:
     async def update(db: AsyncSession, agency_id: str, data: VasAgencyUpdate) -> VasAgency:
         agency = await AgencyService.get(db, agency_id)
         if not agency:
-            raise NotFoundError("合作中介机构不存在")
+            raise NotFoundError("Agency not found")
 
         update_dict = data.dict(exclude_unset=True)
         for key, value in update_dict.items():

+ 15 - 1
app/services/agent/tools/builtin/__init__.py

@@ -1,11 +1,18 @@
 # app/services/agent/tools/builtin/__init__.py
-# 导入内置工具以触发 @agent_tool 自动注册
+# 导入内置工具以触发 @agent_tool 自动注册全站管理能力
 from app.services.agent.tools.builtin import (
     order_tools,
     product_tools,
     node_config_tools,
     plugin_tools,
     proxy_pool_tools,
+    ticket_tools,
+    user_tools,
+    system_config_tools,
+    task_queue_tools,
+    account_pool_tools,
+    settlement_tools,
+    payment_tools,
 )
 
 __all__ = [
@@ -14,4 +21,11 @@ __all__ = [
     "node_config_tools",
     "plugin_tools",
     "proxy_pool_tools",
+    "ticket_tools",
+    "user_tools",
+    "system_config_tools",
+    "task_queue_tools",
+    "account_pool_tools",
+    "settlement_tools",
+    "payment_tools",
 ]

+ 105 - 0
app/services/agent/tools/builtin/account_pool_tools.py

@@ -0,0 +1,105 @@
+# app/services/agent/tools/builtin/account_pool_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.models.user import VasUser
+from app.models.account import Account
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="list_embassy_accounts",
+    description="查询使领馆代预约账号池列表,支持按服务商/机构(如 VFS, TLS, TROOV)、国家、账号状态(0-未激活/无效, 1-正常可用, 2-风控锁定/冷却)及关键词筛选",
+)
+async def list_embassy_accounts(
+    provider: Optional[str] = None,
+    country: Optional[str] = None,
+    status: Optional[int] = None,
+    keyword: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询使馆预约账号池"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(Account)
+    if provider and provider.strip():
+        stmt = stmt.where(Account.provider.ilike(f"%{provider.strip()}%"))
+    if country and country.strip():
+        stmt = stmt.where(Account.country.ilike(f"%{country.strip()}%"))
+    if status is not None:
+        stmt = stmt.where(Account.status == status)
+    if keyword and keyword.strip():
+        kw = f"%{keyword.strip()}%"
+        stmt = stmt.where(Account.username.ilike(kw))
+
+    stmt = stmt.order_by(desc(Account.id)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    accounts = res.scalars().all()
+
+    items = []
+    for a in accounts:
+        items.append({
+            "account_id": a.id,
+            "username": a.username,
+            "provider": a.provider,
+            "country": a.country,
+            "status": a.status,
+            "status_cn": "正常就绪" if a.status == 1 else ("锁定/冷却" if a.status == 2 else "已停用"),
+            "used_count": getattr(a, "used_count", 0),
+            "last_used_at": a.last_used_at.strftime("%Y-%m-%d %H:%M:%S") if getattr(a, "last_used_at", None) else None,
+        })
+
+    return {
+        "count": len(items),
+        "accounts": items,
+    }
+
+
+@agent_tool(
+    name="update_embassy_account_status",
+    description="更新使馆账号池中指定账号的状态(1-设为正常, 2-设为冷却锁定, 0-设为停用)",
+    is_dangerous=True,
+)
+async def update_embassy_account_status(
+    account_id: int,
+    status: int,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """修改使馆账号状态"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    if status not in (0, 1, 2):
+        return {"error": "Invalid status. Allowed values: 1 (active), 2 (locked), 0 (disabled)"}
+
+    a = await db.get(Account, account_id)
+    if not a:
+        return {"error": f"Account #{account_id} not found"}
+
+    old_status = a.status
+    a.status = status
+    await db.commit()
+    await db.refresh(a)
+
+    logger.info(f"👤 [AI_AGENT] Updated embassy account #{account_id}: status {old_status} -> {status} by admin={current_user.id}")
+
+    return {
+        "success": True,
+        "account_id": a.id,
+        "username": a.username,
+        "previous_status": old_status,
+        "new_status": a.status,
+    }

+ 11 - 11
app/services/agent/tools/builtin/node_config_tools.py

@@ -6,7 +6,7 @@ from app.services.node_configuration_service import NodeConfigurationService
 from app.services.agent.tools.registry import agent_tool
 
 
-ADMIN_CHECK_MSG = "权限不足:该运维操作仅系统管理员(admin)可执行"
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
 
 
 @agent_tool(
@@ -62,7 +62,7 @@ async def list_node_configurations(
             "items": items,
         }
     except Exception as e:
-        return {"error": f"查询节点配置失败: {str(e)}"}
+        return {"error": f"Failed to query node configurations: {str(e)}"}
 
 
 @agent_tool(
@@ -89,7 +89,7 @@ async def get_node_configuration_detail(
             "configuration": snapshot,
         }
     except Exception as e:
-        return {"error": f"获取节点配置详情失败: {str(e)}"}
+        return {"error": f"Failed to get node configuration details: {str(e)}"}
 
 
 @agent_tool(
@@ -125,10 +125,10 @@ async def toggle_node_configuration(
             "identifier": updated.identifier,
             "enable": bool(updated.enable),
             "version": updated.version,
-            "message": f"节点 {updated.identifier} 已成功{'启用' if enable else '禁用'}",
+            "message": f"Node {updated.identifier} has been successfully {'enabled' if enable else 'disabled'}",
         }
     except Exception as e:
-        return {"error": f"启停节点配置失败: {str(e)}"}
+        return {"error": f"Failed to toggle node configuration: {str(e)}"}
 
 
 @agent_tool(
@@ -159,7 +159,7 @@ async def update_node_configuration_settings(
         set_data["debug"] = 1 if debug else 0
 
     if not set_data:
-        return {"message": "未传入需要更新的参数"}
+        return {"message": "No parameters provided to update"}
 
     operator = current_user.email or current_user.nickname or current_user.id
     try:
@@ -177,10 +177,10 @@ async def update_node_configuration_settings(
             "identifier": updated.identifier,
             "updated_fields": set_data,
             "version": updated.version,
-            "message": f"节点 {updated.identifier} 配置更新成功",
+            "message": f"Node {updated.identifier} configuration updated successfully",
         }
     except Exception as e:
-        return {"error": f"更新节点配置参数失败: {str(e)}"}
+        return {"error": f"Failed to update node configuration: {str(e)}"}
 
 
 @agent_tool(
@@ -220,7 +220,7 @@ async def list_node_configuration_revisions(
             "revisions": items,
         }
     except Exception as e:
-        return {"error": f"查询版本记录失败: {str(e)}"}
+        return {"error": f"Failed to query revisions: {str(e)}"}
 
 
 @agent_tool(
@@ -255,7 +255,7 @@ async def rollback_node_configuration(
             "entry_id": entry_id,
             "identifier": rolled.identifier,
             "current_version": rolled.version,
-            "message": f"节点 {rolled.identifier} 已成功回滚至历史版本 #{revision_id}",
+            "message": f"Node {rolled.identifier} successfully rolled back to revision #{revision_id}",
         }
     except Exception as e:
-        return {"error": f"回滚节点配置失败: {str(e)}"}
+        return {"error": f"Failed to rollback node configuration: {str(e)}"}

+ 108 - 8
app/services/agent/tools/builtin/order_tools.py

@@ -66,11 +66,11 @@ async def get_order_detail(
     order = res.scalar_one_or_none()
 
     if not order:
-        return {"error": f"订单 {order_id} 不存在"}
+        return {"error": f"Order {order_id} does not exist"}
 
     # 数据权限校验:非管理员只能查看自己的订单
     if order.user_id != current_user.id and current_user.role != "admin":
-        return {"error": f"无权查看该订单 {order_id}"}
+        return {"error": f"Permission denied: You cannot view order {order_id}"}
 
     return {
         "order_id": order.id,
@@ -105,16 +105,16 @@ async def cancel_user_order(
     order = res.scalar_one_or_none()
 
     if not order:
-        return {"error": f"订单 {order_id_clean} 不存在"}
+        return {"error": f"Order {order_id_clean} does not exist"}
 
     if order.user_id != current_user.id and current_user.role != "admin":
-        return {"error": f"无权取消订单 {order_id_clean}"}
+        return {"error": f"Permission denied: You cannot cancel order {order_id_clean}"}
 
     if order.status == "closed":
-        return {"message": f"订单 {order_id_clean} 已经处于已关闭状态,无需重复取消"}
+        return {"message": f"Order {order_id_clean} is already closed, no need to cancel again"}
 
     if order.status == "completed":
-        return {"error": f"订单 {order_id_clean} 已履约完成,无法取消"}
+        return {"error": f"Order {order_id_clean} has already been fulfilled and cannot be cancelled"}
 
     try:
         cancelled = await OrderService.cancel(db, order_id_clean)
@@ -123,7 +123,107 @@ async def cancel_user_order(
             "success": True,
             "order_id": cancelled.id,
             "status": cancelled.status,
-            "message": f"订单 {order_id_clean} 已成功取消",
+            "message": f"Order {order_id_clean} was successfully cancelled",
         }
     except Exception as e:
-        return {"error": f"取消订单失败: {str(e)}"}
+        return {"error": f"Failed to cancel order: {str(e)}"}
+
+
+@agent_tool(
+    name="admin_list_all_orders",
+    description="管理员全景查询全站订单列表,支持按订单状态(pending-待支付, paid-已支付, completed-已完成, closed-已关闭)、特定用户ID、产品名称关键词或订单号筛选",
+)
+async def admin_list_all_orders(
+    status: Optional[str] = None,
+    user_id: Optional[str] = None,
+    keyword: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员全景查询全站订单列表"""
+    if current_user.role != "admin":
+        return {"error": "Permission denied: This operation is restricted to system administrators (admin)"}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(VasOrder)
+    if status and status.strip():
+        stmt = stmt.where(VasOrder.status == status.strip().lower())
+    if user_id and user_id.strip():
+        stmt = stmt.where(VasOrder.user_id == user_id.strip())
+    if keyword and keyword.strip():
+        kw = f"%{keyword.strip()}%"
+        stmt = stmt.where(
+            or_(
+                VasOrder.id.ilike(kw),
+                VasOrder.product_name.ilike(kw),
+            )
+        )
+
+    stmt = stmt.order_by(desc(VasOrder.created_at)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    orders = res.scalars().all()
+
+    items = []
+    for o in orders:
+        items.append({
+            "order_id": o.id,
+            "user_id": o.user_id,
+            "product_name": o.product_name,
+            "final_amount": o.final_amount,
+            "currency": o.base_currency,
+            "status": o.status,
+            "created_at": o.created_at.strftime("%Y-%m-%d %H:%M:%S") if o.created_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "orders": items,
+    }
+
+
+@agent_tool(
+    name="admin_update_order_status",
+    description="管理员手动调整订单状态(支持改为 paid-已支付, completed-已履约完成, closed-已关闭, pending-待支付)",
+    is_dangerous=True,
+)
+async def admin_update_order_status(
+    order_id: str,
+    status: str,
+    note: Optional[str] = None,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员更新订单状态"""
+    if current_user.role != "admin":
+        return {"error": "Permission denied: This operation is restricted to system administrators (admin)"}
+
+    clean_status = status.strip().lower()
+    valid_statuses = {"pending", "paid", "completed", "closed"}
+    if clean_status not in valid_statuses:
+        return {"error": f"Invalid status '{clean_status}'. Valid statuses: {sorted(list(valid_statuses))}"}
+
+    stmt = select(VasOrder).where(VasOrder.id == order_id.strip())
+    res = await db.execute(stmt)
+    order = res.scalar_one_or_none()
+    if not order:
+        return {"error": f"Order {order_id} does not exist"}
+
+    old_status = order.status
+    order.status = clean_status
+    await db.commit()
+    await db.refresh(order)
+
+    logger.info(f"📦 [AI_AGENT] Updated order status: order={order.id} ({old_status} -> {clean_status}) by admin={current_user.id}, note={note}")
+
+    return {
+        "success": True,
+        "order_id": order.id,
+        "previous_status": old_status,
+        "new_status": order.status,
+    }

+ 62 - 0
app/services/agent/tools/builtin/payment_tools.py

@@ -0,0 +1,62 @@
+# app/services/agent/tools/builtin/payment_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.models.user import VasUser
+from app.models.payment import VasPayment
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="list_payments",
+    description="管理员查询支付流水记录,支持按支付状态(pending-待支付, succeeded-支付成功, failed-失败, refunded-已退款)、订单号、支付通道provider(creem, stripe, wechat等)筛选",
+)
+async def list_payments(
+    status: Optional[str] = None,
+    order_id: Optional[str] = None,
+    provider: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询支付流水列表"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(VasPayment)
+    if status and status.strip():
+        stmt = stmt.where(VasPayment.status == status.strip().lower())
+    if order_id and order_id.strip():
+        stmt = stmt.where(VasPayment.order_id == order_id.strip())
+    if provider and provider.strip():
+        stmt = stmt.where(VasPayment.provider.ilike(f"%{provider.strip()}%"))
+
+    stmt = stmt.order_by(desc(VasPayment.created_at)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    payments = res.scalars().all()
+
+    items = []
+    for p in payments:
+        items.append({
+            "payment_id": p.id,
+            "order_id": p.order_id,
+            "provider": p.provider,
+            "amount": p.amount,
+            "currency": p.currency,
+            "status": p.status,
+            "created_at": p.created_at.strftime("%Y-%m-%d %H:%M:%S") if p.created_at else None,
+            "paid_at": p.paid_at.strftime("%Y-%m-%d %H:%M:%S") if getattr(p, "paid_at", None) else None,
+        })
+
+    return {
+        "count": len(items),
+        "payments": items,
+    }

+ 10 - 10
app/services/agent/tools/builtin/plugin_tools.py

@@ -9,7 +9,7 @@ from app.schemas.plugin import PluginUpdate
 from app.services.plugin_service import PluginService
 from app.services.agent.tools.registry import agent_tool
 
-ADMIN_CHECK_MSG = "权限不足:该运维操作仅系统管理员(admin)可执行"
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
 
 
 @agent_tool(
@@ -54,7 +54,7 @@ async def list_plugins(
             "plugins": items,
         }
     except Exception as e:
-        return {"error": f"查询插件列表失败: {str(e)}"}
+        return {"error": f"Failed to query plugin list: {str(e)}"}
 
 
 @agent_tool(
@@ -79,7 +79,7 @@ async def get_plugin_detail(
             target_id = (await db.execute(stmt)).scalar_one_or_none()
 
         if not target_id:
-            return {"error": f"未找到插件: id={plugin_id}, name={plugin_name}"}
+            return {"error": f"Plugin not found: id={plugin_id}, name={plugin_name}"}
 
         detail = await PluginService.get_plugin_detail(db, target_id)
         versions_info = []
@@ -103,7 +103,7 @@ async def get_plugin_detail(
             "versions": versions_info,
         }
     except Exception as e:
-        return {"error": f"获取插件详情失败: {str(e)}"}
+        return {"error": f"Failed to get plugin details: {str(e)}"}
 
 
 @agent_tool(
@@ -130,7 +130,7 @@ async def toggle_plugin_status(
             target_id = (await db.execute(stmt)).scalar_one_or_none()
 
         if not target_id:
-            return {"error": f"未找到插件: id={plugin_id}, name={plugin_name}"}
+            return {"error": f"Plugin not found: id={plugin_id}, name={plugin_name}"}
 
         clean_status = 1 if status == 1 else 0
         updated = await PluginService.update_plugin(
@@ -143,10 +143,10 @@ async def toggle_plugin_status(
             "plugin_id": updated.id,
             "name": updated.name,
             "status": updated.status,
-            "message": f"插件 {updated.name} 已成功{'启用' if clean_status == 1 else '停用'}",
+            "message": f"Plugin {updated.name} has been successfully {'enabled' if clean_status == 1 else 'disabled'}",
         }
     except Exception as e:
-        return {"error": f"操作插件状态失败: {str(e)}"}
+        return {"error": f"Failed to toggle plugin status: {str(e)}"}
 
 
 @agent_tool(
@@ -173,7 +173,7 @@ async def switch_plugin_version(
             target_id = (await db.execute(stmt)).scalar_one_or_none()
 
         if not target_id:
-            return {"error": f"未找到插件: id={plugin_id}, name={plugin_name}"}
+            return {"error": f"Plugin not found: id={plugin_id}, name={plugin_name}"}
 
         plugin = await PluginService.switch_version(db, target_id, version.strip())
         return {
@@ -181,7 +181,7 @@ async def switch_plugin_version(
             "plugin_id": plugin.id,
             "name": plugin.name,
             "current_version": plugin.latest_version,
-            "message": f"插件 {plugin.name} 生效版本已成功切换为 {version}",
+            "message": f"Plugin {plugin.name} active version switched to {version}",
         }
     except Exception as e:
-        return {"error": f"切换插件版本失败: {str(e)}"}
+        return {"error": f"Failed to switch plugin version: {str(e)}"}

+ 117 - 1
app/services/agent/tools/builtin/product_tools.py

@@ -70,7 +70,7 @@ async def get_product_detail(
     p = res.scalar_one_or_none()
 
     if not p:
-        return {"error": f"商品 ID {product_id} 不存在"}
+        return {"error": f"Product ID {product_id} does not exist"}
 
     return {
         "product_id": p.id,
@@ -86,3 +86,119 @@ async def get_product_detail(
         "extra_fields": p.extra_fields,
         "schema_id": p.schema_id,
     }
+
+
+@agent_tool(
+    name="admin_list_all_products",
+    description="管理员查看系统所有签证商品(包含已启用与已下架的商品),支持按国家、服务商筛选",
+)
+async def admin_list_all_products(
+    country: Optional[str] = None,
+    provider: Optional[str] = None,
+    enabled: Optional[bool] = None,
+    limit: int = 20,
+    *,
+    db: AsyncSession,
+) -> Dict[str, Any]:
+    """管理员全景查询商品列表"""
+    stmt = select(VasProduct)
+    if enabled is not None:
+        stmt = stmt.where(VasProduct.enabled == (1 if enabled else 0))
+    if country and country.strip():
+        stmt = stmt.where(VasProduct.country.ilike(f"%{country.strip()}%"))
+    if provider and provider.strip():
+        stmt = stmt.where(VasProduct.provider.ilike(f"%{provider.strip()}%"))
+
+    stmt = stmt.order_by(desc(VasProduct.id)).limit(max(1, min(limit, 50)))
+    res = await db.execute(stmt)
+    products = res.scalars().all()
+
+    items = []
+    for p in products:
+        items.append({
+            "product_id": p.id,
+            "title": p.title,
+            "country": p.country,
+            "city": p.city,
+            "visa_type": p.visa_type,
+            "provider": p.provider,
+            "price_amount": p.price_amount,
+            "currency": p.price_currency,
+            "enabled": bool(p.enabled),
+            "recommend_score": p.recommend_score,
+        })
+
+    return {
+        "count": len(items),
+        "products": items,
+    }
+
+
+@agent_tool(
+    name="admin_toggle_product_status",
+    description="上架或下架指定商品(enabled: true-上架启用, false-下架停用)",
+    is_dangerous=True,
+)
+async def admin_toggle_product_status(
+    product_id: int,
+    enabled: bool,
+    *,
+    db: AsyncSession,
+) -> Dict[str, Any]:
+    """更新商品上下架状态"""
+    stmt = select(VasProduct).where(VasProduct.id == product_id)
+    res = await db.execute(stmt)
+    p = res.scalar_one_or_none()
+
+    if not p:
+        return {"error": f"Product ID {product_id} does not exist"}
+
+    old_status = bool(p.enabled)
+    p.enabled = 1 if enabled else 0
+    await db.commit()
+    await db.refresh(p)
+
+    return {
+        "success": True,
+        "product_id": p.id,
+        "title": p.title,
+        "previous_status": "enabled" if old_status else "disabled",
+        "new_status": "enabled" if enabled else "disabled",
+    }
+
+
+@agent_tool(
+    name="admin_update_product_price",
+    description="修改指定商品的服务费用单价(price_amount 单位为分,如 35000 代表 350 元)",
+    is_dangerous=True,
+)
+async def admin_update_product_price(
+    product_id: int,
+    price_amount: int,
+    *,
+    db: AsyncSession,
+) -> Dict[str, Any]:
+    """修改商品单价"""
+    if price_amount <= 0:
+        return {"error": "Price amount must be greater than 0"}
+
+    stmt = select(VasProduct).where(VasProduct.id == product_id)
+    res = await db.execute(stmt)
+    p = res.scalar_one_or_none()
+
+    if not p:
+        return {"error": f"Product ID {product_id} does not exist"}
+
+    old_price = p.price_amount
+    p.price_amount = price_amount
+    await db.commit()
+    await db.refresh(p)
+
+    return {
+        "success": True,
+        "product_id": p.id,
+        "title": p.title,
+        "previous_price": old_price,
+        "new_price": p.price_amount,
+        "currency": p.price_currency,
+    }

+ 7 - 7
app/services/agent/tools/builtin/proxy_pool_tools.py

@@ -7,7 +7,7 @@ from app.models.user import VasUser
 from app.models.proxy_pool import ProxyPool
 from app.services.agent.tools.registry import agent_tool
 
-ADMIN_CHECK_MSG = "权限不足:该运维操作仅系统管理员(admin)可执行"
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
 
 
 @agent_tool(
@@ -56,7 +56,7 @@ async def get_proxy_pool_stats(
             "pools": pools_summary,
         }
     except Exception as e:
-        return {"error": f"统计代理池失败: {str(e)}"}
+        return {"error": f"Failed to get proxy pool statistics: {str(e)}"}
 
 
 @agent_tool(
@@ -113,7 +113,7 @@ async def list_proxies(
             "proxies": items,
         }
     except Exception as e:
-        return {"error": f"获取代理列表失败: {str(e)}"}
+        return {"error": f"Failed to list proxies: {str(e)}"}
 
 
 @agent_tool(
@@ -134,13 +134,13 @@ async def toggle_proxy_status(
 
     clean_status = status.strip().lower()
     if clean_status not in ("active", "disable"):
-        return {"error": f"无效状态: '{status}',仅支持 'active' 或 'disable'"}
+        return {"error": f"Invalid status: '{status}', only 'active' or 'disable' are supported"}
 
     try:
         stmt = select(ProxyPool).where(ProxyPool.id == proxy_id)
         proxy = (await db.execute(stmt)).scalar_one_or_none()
         if not proxy:
-            return {"error": f"代理 ID #{proxy_id} 不存在"}
+            return {"error": f"Proxy ID #{proxy_id} does not exist"}
 
         proxy.status = clean_status
         await db.commit()
@@ -151,7 +151,7 @@ async def toggle_proxy_status(
             "proxy_id": proxy.id,
             "pool_name": proxy.pool_name,
             "new_status": proxy.status,
-            "message": f"代理 #{proxy_id} 状态已更新为 {clean_status}",
+            "message": f"Proxy #{proxy_id} status updated to {clean_status}",
         }
     except Exception as e:
-        return {"error": f"更新代理状态失败: {str(e)}"}
+        return {"error": f"Failed to update proxy status: {str(e)}"}

+ 110 - 0
app/services/agent/tools/builtin/settlement_tools.py

@@ -0,0 +1,110 @@
+# app/services/agent/tools/builtin/settlement_tools.py
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, desc
+from app.models.user import VasUser
+from app.models.order import VasOrder
+from app.models.payment import VasPayment
+from app.models.settlement import VasSettlementPeriod
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="get_financial_overview",
+    description="获取全站财务与营收宏观概览(包含总订单成交额、总成功支付笔数、待分润金额及近30天营收统计)",
+)
+async def get_financial_overview(
+    days: int = 30,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """获取全站财务统计概览"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    now = datetime.utcnow()
+    since_date = now - timedelta(days=max(1, min(days, 365)))
+
+    # 总支付成功金额与笔数
+    pay_stmt = select(
+        func.count(VasPayment.id).label("total_payments"),
+        func.coalesce(func.sum(VasPayment.amount), 0).label("total_revenue"),
+    ).where(VasPayment.status.in_(["succeeded", "late_paid"]))
+    pay_res = await db.execute(pay_stmt)
+    total_payments, total_revenue = pay_res.one()
+
+    # 近期区间支付金额
+    recent_stmt = select(
+        func.count(VasPayment.id).label("recent_payments"),
+        func.coalesce(func.sum(VasPayment.amount), 0).label("recent_revenue"),
+    ).where(
+        VasPayment.status.in_(["succeeded", "late_paid"]),
+        VasPayment.created_at >= since_date,
+    )
+    recent_res = await db.execute(recent_stmt)
+    recent_payments, recent_revenue = recent_res.one()
+
+    # 订单总数与完成数
+    order_stmt = select(
+        func.count(VasOrder.id).label("total_orders"),
+        func.sum(func.case((VasOrder.status == 'completed', 1), else_=0)).label("completed_orders"),
+        func.sum(func.case((VasOrder.status == 'pending', 1), else_=0)).label("pending_orders"),
+    )
+    order_res = await db.execute(order_stmt)
+    total_orders, completed_orders, pending_orders = order_res.one()
+
+    return {
+        "period_days": days,
+        "total_revenue_cny": round(float(total_revenue) / 100, 2),
+        "total_successful_payments": total_payments,
+        "recent_revenue_cny": round(float(recent_revenue) / 100, 2),
+        "recent_successful_payments": recent_payments,
+        "total_orders": total_orders or 0,
+        "completed_orders": completed_orders or 0,
+        "pending_orders": pending_orders or 0,
+    }
+
+
+@agent_tool(
+    name="list_settlement_periods",
+    description="查询开发者结算账期列表与状态(已确认、待结算、已打款)",
+)
+async def list_settlement_periods(
+    limit: int = 10,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询结算账期"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 30))
+    offset = max(0, offset)
+
+    stmt = select(VasSettlementPeriod).order_by(desc(VasSettlementPeriod.id)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    periods = res.scalars().all()
+
+    items = []
+    for p in periods:
+        items.append({
+            "period_id": p.id,
+            "period_name": p.period_name,
+            "start_date": p.start_date.strftime("%Y-%m-%d") if p.start_date else None,
+            "end_date": p.end_date.strftime("%Y-%m-%d") if p.end_date else None,
+            "status": p.status,
+            "total_payout_amount": p.total_payout_amount,
+            "created_at": p.created_at.strftime("%Y-%m-%d %H:%M:%S") if p.created_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "settlement_periods": items,
+    }

+ 125 - 0
app/services/agent/tools/builtin/system_config_tools.py

@@ -0,0 +1,125 @@
+# app/services/agent/tools/builtin/system_config_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.models.user import VasUser
+from app.models.configuration import Configuration
+from app.services.configuration_service import ConfigurationService
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="list_system_configurations",
+    description="查询全站全局动态环境变量与系统运行配置参数列表(包含配置项 Key、说明、更新时间)",
+)
+async def list_system_configurations(
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询全站配置列表"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    configs = await ConfigurationService.get_all(db)
+    items = []
+    for c in configs:
+        items.append({
+            "id": c.id,
+            "config_key": c.config_key,
+            "description": c.description,
+            "config_value": c.config_value[:100] + "..." if c.config_value and len(c.config_value) > 100 else c.config_value,
+            "created_at": c.created_at.strftime("%Y-%m-%d %H:%M:%S") if c.created_at else None,
+            "updated_at": c.updated_at.strftime("%Y-%m-%d %H:%M:%S") if c.updated_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "configurations": items,
+    }
+
+
+@agent_tool(
+    name="get_system_configuration",
+    description="获取指定配置 Key 的完整内容与参数定义",
+)
+async def get_system_configuration(
+    config_key: str,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """获取单个全局配置"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_key = config_key.strip()
+    try:
+        c = await ConfigurationService.get_by_key(db, clean_key)
+        return {
+            "id": c.id,
+            "config_key": c.config_key,
+            "description": c.description,
+            "config_value": c.config_value,
+            "created_at": c.created_at.strftime("%Y-%m-%d %H:%M:%S") if c.created_at else None,
+            "updated_at": c.updated_at.strftime("%Y-%m-%d %H:%M:%S") if c.updated_at else None,
+        }
+    except Exception as e:
+        return {"error": f"Config key '{clean_key}' not found or error: {str(e)}"}
+
+
+@agent_tool(
+    name="set_system_configuration",
+    description="设置或修改全局动态环境变量/系统配置(支持更新已有值或创建新键值配置)",
+    is_dangerous=True,
+)
+async def set_system_configuration(
+    config_key: str,
+    config_value: str,
+    description: Optional[str] = None,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """更新或创建全局动态配置"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_key = config_key.strip()
+    if not clean_key:
+        return {"error": "Config key cannot be empty"}
+
+    stmt = select(Configuration).where(Configuration.config_key == clean_key)
+    res = await db.execute(stmt)
+    c = res.scalar_one_or_none()
+
+    if c:
+        c.config_value = config_value
+        if description is not None:
+            c.description = description
+        await db.commit()
+        await db.refresh(c)
+        action = "updated"
+    else:
+        c = Configuration(
+            config_key=clean_key,
+            config_value=config_value,
+            description=description or "",
+        )
+        db.add(c)
+        await db.commit()
+        await db.refresh(c)
+        action = "created"
+
+    logger.info(f"⚙️ [AI_AGENT] Config {action}: key={clean_key} by admin={current_user.id}")
+
+    return {
+        "success": True,
+        "action": action,
+        "config_key": c.config_key,
+        "config_value": c.config_value,
+        "updated_at": c.updated_at.strftime("%Y-%m-%d %H:%M:%S") if c.updated_at else None,
+    }

+ 137 - 0
app/services/agent/tools/builtin/task_queue_tools.py

@@ -0,0 +1,137 @@
+# app/services/agent/tools/builtin/task_queue_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.models.user import VasUser
+from app.models.vas_task import VasTask
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="list_automation_tasks",
+    description="查询后台自动化任务执行队列(vas_tasks),支持按任务状态(pending-待执行, running-执行中, grabbed-已抢位, completed-已完成, pause-已暂停, cancelled-已取消)、关联订单号、routing_key 筛选",
+)
+async def list_automation_tasks(
+    status: Optional[str] = None,
+    order_id: Optional[str] = None,
+    routing_key: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询自动化任务队列"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(VasTask)
+    if status and status.strip():
+        stmt = stmt.where(VasTask.status == status.strip().lower())
+    if order_id and order_id.strip():
+        stmt = stmt.where(VasTask.order_id == order_id.strip())
+    if routing_key and routing_key.strip():
+        stmt = stmt.where(VasTask.routing_key.ilike(f"%{routing_key.strip()}%"))
+
+    stmt = stmt.order_by(desc(VasTask.created_at)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    tasks = res.scalars().all()
+
+    items = []
+    for t in tasks:
+        items.append({
+            "task_id": t.id,
+            "order_id": t.order_id,
+            "routing_key": t.routing_key,
+            "status": t.status,
+            "priority": t.priority,
+            "attempt_count": t.attempt_count,
+            "created_at": t.created_at.strftime("%Y-%m-%d %H:%M:%S") if t.created_at else None,
+            "updated_at": t.updated_at.strftime("%Y-%m-%d %H:%M:%S") if t.updated_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "tasks": items,
+    }
+
+
+@agent_tool(
+    name="get_automation_task_detail",
+    description="获取指定自动化任务ID的完整执行状态、重试次数、抢位结果与上下文参数",
+)
+async def get_automation_task_detail(
+    task_id: int,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询自动化任务详情"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    t = await db.get(VasTask, task_id)
+    if not t:
+        return {"error": f"Automation task #{task_id} does not exist"}
+
+    return {
+        "task_id": t.id,
+        "order_id": t.order_id,
+        "routing_key": t.routing_key,
+        "status": t.status,
+        "priority": t.priority,
+        "attempt_count": t.attempt_count,
+        "grabbed_history": t.grabbed_history,
+        "meta": t.meta,
+        "created_at": t.created_at.strftime("%Y-%m-%d %H:%M:%S") if t.created_at else None,
+        "updated_at": t.updated_at.strftime("%Y-%m-%d %H:%M:%S") if t.updated_at else None,
+    }
+
+
+@agent_tool(
+    name="admin_update_task_status",
+    description="修改自动化任务状态(如将任务重置为 pending 进行重试,或设为 pause / cancelled 终止执行)",
+    is_dangerous=True,
+)
+async def admin_update_task_status(
+    task_id: int,
+    new_status: str,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员更新自动化任务状态"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_status = new_status.strip().lower()
+    valid_statuses = {"pending", "running", "grabbed", "completed", "pause", "cancelled"}
+    if clean_status not in valid_statuses:
+        return {"error": f"Invalid task status '{clean_status}'. Valid: {sorted(list(valid_statuses))}"}
+
+    t = await db.get(VasTask, task_id)
+    if not t:
+        return {"error": f"Automation task #{task_id} does not exist"}
+
+    old_status = t.status
+    t.status = clean_status
+    if clean_status == "pending":
+        t.attempt_count = 0  # 重置重试次数
+
+    await db.commit()
+    await db.refresh(t)
+
+    logger.info(f"🔄 [AI_AGENT] Updated task #{task_id}: {old_status} -> {clean_status} by admin={current_user.id}")
+
+    return {
+        "success": True,
+        "task_id": t.id,
+        "previous_status": old_status,
+        "new_status": t.status,
+    }

+ 204 - 0
app/services/agent/tools/builtin/ticket_tools.py

@@ -0,0 +1,204 @@
+# app/services/agent/tools/builtin/ticket_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, desc
+from app.models.user import VasUser
+from app.models.ticket import VasTicket
+from app.models.ticket_message import VasTicketMessage
+from app.services.ticket_service import TicketService
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="admin_list_tickets",
+    description="管理员查询工单列表,支持按工单状态(pending-待处理, info_required-需补充, in_progress-处理中, resolved-已解决, rejected-已拒绝, closed-已关闭)、关联订单号、用户ID或关键词筛选",
+)
+async def admin_list_tickets(
+    status: Optional[str] = None,
+    order_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    keyword: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员分页检索工单列表"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(VasTicket)
+    if status and status.strip():
+        stmt = stmt.where(VasTicket.status == status.strip().lower())
+    if order_id and order_id.strip():
+        stmt = stmt.where(VasTicket.order_id == order_id.strip())
+    if user_id and user_id.strip():
+        stmt = stmt.where(VasTicket.user_id == user_id.strip())
+    if keyword and keyword.strip():
+        stmt = stmt.where(VasTicket.reason.ilike(f"%{keyword.strip()}%"))
+
+    stmt = stmt.order_by(desc(VasTicket.created_at)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    tickets = res.scalars().all()
+
+    items = []
+    for t in tickets:
+        items.append({
+            "ticket_id": t.id,
+            "order_id": t.order_id,
+            "user_id": t.user_id,
+            "type": t.type,
+            "reason": t.reason,
+            "status": t.status,
+            "created_at": t.created_at.strftime("%Y-%m-%d %H:%M:%S") if t.created_at else None,
+            "updated_at": t.updated_at.strftime("%Y-%m-%d %H:%M:%S") if t.updated_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "tickets": items,
+    }
+
+
+@agent_tool(
+    name="get_ticket_detail",
+    description="获取指定工单ID的完整详细信息及往来沟通对话记录(包含用户描述、客服回复、时间线)",
+)
+async def get_ticket_detail(
+    ticket_id: int,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """获取指定工单详情与对话记录"""
+    t = await db.get(VasTicket, ticket_id)
+    if not t:
+        return {"error": f"Ticket #{ticket_id} does not exist"}
+
+    if current_user.role != "admin" and str(t.user_id) != str(current_user.id):
+        return {"error": "Permission denied: You cannot view this ticket"}
+
+    # 查往来对话消息
+    msg_stmt = (
+        select(VasTicketMessage)
+        .where(VasTicketMessage.ticket_id == ticket_id)
+        .order_by(VasTicketMessage.created_at.asc())
+    )
+    msg_res = await db.execute(msg_stmt)
+    messages = msg_res.scalars().all()
+
+    msg_items = []
+    for m in messages:
+        msg_items.append({
+            "id": m.id,
+            "sender_type": m.sender_type,
+            "sender_id": m.sender_id,
+            "content": m.content,
+            "created_at": m.created_at.strftime("%Y-%m-%d %H:%M:%S") if m.created_at else None,
+        })
+
+    return {
+        "ticket_id": t.id,
+        "order_id": t.order_id,
+        "user_id": t.user_id,
+        "type": t.type,
+        "reason": t.reason,
+        "status": t.status,
+        "created_at": t.created_at.strftime("%Y-%m-%d %H:%M:%S") if t.created_at else None,
+        "updated_at": t.updated_at.strftime("%Y-%m-%d %H:%M:%S") if t.updated_at else None,
+        "messages_count": len(msg_items),
+        "messages": msg_items,
+    }
+
+
+@agent_tool(
+    name="admin_reply_ticket",
+    description="以官方管理员/客服身份在指定工单中回复用户消息,支持解答疑问或通知补件",
+    is_dangerous=True,
+)
+async def admin_reply_ticket(
+    ticket_id: int,
+    content: str,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员回复工单"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_content = content.strip()
+    if not clean_content:
+        return {"error": "Reply content cannot be empty"}
+
+    try:
+        msg = await TicketService.add_message(
+            db=db,
+            ticket_id=ticket_id,
+            sender_type="admin",
+            sender_id=str(current_user.id),
+            content=clean_content,
+        )
+        return {
+            "success": True,
+            "ticket_id": ticket_id,
+            "message_id": msg.id,
+            "content": msg.content,
+            "created_at": msg.created_at.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+    except Exception as e:
+        return {"error": f"Failed to reply ticket #{ticket_id}: {str(e)}"}
+
+
+@agent_tool(
+    name="admin_update_ticket_status",
+    description="更新工单处理状态(pending-待处理, info_required-需补充, in_progress-处理中, resolved-已解决, rejected-已拒绝, closed-已关闭)",
+    is_dangerous=True,
+)
+async def admin_update_ticket_status(
+    ticket_id: int,
+    status: str,
+    note: Optional[str] = None,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员更改工单状态"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_status = status.strip().lower()
+    valid_statuses = {"pending", "info_required", "in_progress", "resolved", "rejected", "closed"}
+    if clean_status not in valid_statuses:
+        return {"error": f"Invalid ticket status '{clean_status}'. Valid statuses: {sorted(list(valid_statuses))}"}
+
+    try:
+        ticket = await TicketService.update_status(
+            db=db,
+            ticket_id=ticket_id,
+            status=clean_status,
+            comment=note or "",
+            admin_id=str(current_user.id),
+        )
+        if note and note.strip():
+            await TicketService.add_message(
+                db=db,
+                ticket_id=ticket_id,
+                sender_type="system",
+                content=f"系统状态变更为 [{clean_status}]: {note.strip()}",
+            )
+        return {
+            "success": True,
+            "ticket_id": ticket.id,
+            "new_status": ticket.status,
+            "updated_at": ticket.updated_at.strftime("%Y-%m-%d %H:%M:%S") if ticket.updated_at else None,
+        }
+    except Exception as e:
+        return {"error": f"Failed to update status for ticket #{ticket_id}: {str(e)}"}

+ 149 - 0
app/services/agent/tools/builtin/user_tools.py

@@ -0,0 +1,149 @@
+# app/services/agent/tools/builtin/user_tools.py
+from typing import Optional, Dict, Any, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, or_, desc
+from app.models.user import VasUser
+from app.models.order import VasOrder
+from app.services.agent.tools.registry import agent_tool
+from app.core.logger import logger
+
+ADMIN_CHECK_MSG = "Permission denied: This operation is restricted to system administrators (admin)"
+
+
+@agent_tool(
+    name="admin_list_users",
+    description="管理员查询全站用户列表,支持按手机号、昵称、用户ID关键词检索,可按角色(admin/user)筛选",
+)
+async def admin_list_users(
+    keyword: Optional[str] = None,
+    role: Optional[str] = None,
+    limit: int = 15,
+    offset: int = 0,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员分页查询用户列表"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    limit = max(1, min(limit, 50))
+    offset = max(0, offset)
+
+    stmt = select(VasUser)
+    if role and role.strip():
+        stmt = stmt.where(VasUser.role == role.strip().lower())
+    if keyword and keyword.strip():
+        kw = f"%{keyword.strip()}%"
+        stmt = stmt.where(
+            or_(
+                VasUser.id.ilike(kw),
+                VasUser.phone.ilike(kw),
+                VasUser.nickname.ilike(kw),
+            )
+        )
+
+    stmt = stmt.order_by(desc(VasUser.created_at)).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    users = res.scalars().all()
+
+    items = []
+    for u in users:
+        items.append({
+            "user_id": u.id,
+            "nickname": u.nickname,
+            "phone": u.phone,
+            "role": u.role,
+            "preferred_language": u.preferred_language,
+            "created_at": u.created_at.strftime("%Y-%m-%d %H:%M:%S") if u.created_at else None,
+        })
+
+    return {
+        "count": len(items),
+        "users": items,
+    }
+
+
+@agent_tool(
+    name="admin_get_user_detail",
+    description="获取指定用户的完整档案信息及历史订单总数统计",
+)
+async def admin_get_user_detail(
+    user_id: str,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """查询指定用户详细信息与业务画像"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    stmt = select(VasUser).where(VasUser.id == user_id.strip())
+    res = await db.execute(stmt)
+    user = res.scalar_one_or_none()
+    if not user:
+        return {"error": f"User '{user_id}' does not exist"}
+
+    # 统计历史订单总数
+    order_stmt = select(VasOrder).where(VasOrder.user_id == user.id)
+    order_res = await db.execute(order_stmt)
+    user_orders = order_res.scalars().all()
+
+    status_counts: Dict[str, int] = {}
+    for o in user_orders:
+        st = o.status or "unknown"
+        status_counts[st] = status_counts.get(st, 0) + 1
+
+    return {
+        "user_id": user.id,
+        "nickname": user.nickname,
+        "phone": user.phone,
+        "role": user.role,
+        "avatar_url": user.avatar_url,
+        "timezone": user.timezone,
+        "preferred_language": user.preferred_language,
+        "created_at": user.created_at.strftime("%Y-%m-%d %H:%M:%S") if user.created_at else None,
+        "total_orders": len(user_orders),
+        "order_status_summary": status_counts,
+    }
+
+
+@agent_tool(
+    name="admin_update_user_role",
+    description="修改指定用户的系统权限角色(user-普通用户, admin-超级管理员)",
+    is_dangerous=True,
+)
+async def admin_update_user_role(
+    user_id: str,
+    new_role: str,
+    *,
+    db: AsyncSession,
+    current_user: VasUser,
+) -> Dict[str, Any]:
+    """管理员修改用户角色权限"""
+    if current_user.role != "admin":
+        return {"error": ADMIN_CHECK_MSG}
+
+    clean_role = new_role.strip().lower()
+    if clean_role not in ("admin", "user"):
+        return {"error": "Invalid role. Supported roles: 'admin', 'user'"}
+
+    stmt = select(VasUser).where(VasUser.id == user_id.strip())
+    res = await db.execute(stmt)
+    user = res.scalar_one_or_none()
+    if not user:
+        return {"error": f"User '{user_id}' does not exist"}
+
+    old_role = user.role
+    user.role = clean_role
+    await db.commit()
+    await db.refresh(user)
+
+    logger.info(f"👑 [AI_AGENT] Updated user role: user={user.id} ({old_role} -> {clean_role}) by admin={current_user.id}")
+
+    return {
+        "success": True,
+        "user_id": user.id,
+        "previous_role": old_role,
+        "new_role": user.role,
+    }

+ 3 - 3
app/services/auth_service.py

@@ -124,7 +124,7 @@ class AuthService:
                 "template_id": "email_verification_for_bind",
                 "receiver": payload.email,
                 "payload": {
-                    "app_name": "TextSkin",
+                    "app_name": "STRATA",
                     "code": token,
                     "expiration_time":  "10 minutes"
                 },
@@ -167,7 +167,7 @@ class AuthService:
                 "template_id": "email_verification_for_reset",
                 "receiver": payload.email,
                 "payload": {
-                    "app_name": "TextSkin",
+                    "app_name": "STRATA",
                     "code": token,
                     "expiration_time": "10 minutes"
                 },
@@ -244,7 +244,7 @@ class AuthService:
                 "template_id": "login_credentials",
                 "receiver": payload.email,
                 "payload": {
-                    "app_name": "TextSkin",
+                    "app_name": "STRATA",
                     "username": payload.email,
                     "password": plain_pwd,
                     "login_url": "https://text.skin/login"

+ 3 - 3
app/services/node_configuration_service.py

@@ -446,7 +446,7 @@ class NodeConfigurationService:
         if existing:
             raise BizException(
                 code=40001,
-                message=f"节点标识 '{data.node_id.strip()}' 已存在,请勿重复注册",
+                message=f"Node ID '{data.node_id.strip()}' already exists",
                 http_status=400,
             )
         node = ClusterNodeEntry(
@@ -473,7 +473,7 @@ class NodeConfigurationService:
         if not node:
             raise BizException(
                 code=40401,
-                message=f"未找到节点: '{node_id}'",
+                message=f"Node not found: '{node_id}'",
                 http_status=404,
             )
         if data.name is not None:
@@ -501,7 +501,7 @@ class NodeConfigurationService:
         if not node:
             raise BizException(
                 code=40401,
-                message=f"未找到节点: '{node_id}'",
+                message=f"Node not found: '{node_id}'",
                 http_status=404,
             )
         await db.delete(node)

+ 18 - 5
app/services/order_service.py

@@ -11,7 +11,7 @@ from sqlalchemy import select
 from app.core.logger import logger
 from app.utils.search import apply_keyword_search_stmt
 from app.utils.pagination import paginate
-from app.core.biz_exception import NotFoundError, BizLogicError
+from app.core.biz_exception import NotFoundError, BizLogicError, PermissionDeniedError
 from app.models.user import VasUser
 from app.models.order import VasOrder
 from app.models.vas_task import VasTask
@@ -84,12 +84,12 @@ class OrderService:
         # 渠道判定与底价拦截
         if channel_type == "agency":
             if not agency_id:
-                raise BizLogicError("中介渠道单必须指定合作中介 agency_id")
+                raise BizLogicError("Agency channel orders must specify agency_id")
             agency = await AgencyService.get(db, agency_id)
             if not agency:
-                raise BizLogicError(f"未找到中介机构: {agency_id}")
+                raise BizLogicError(f"Agency not found: {agency_id}")
             if agency.status != 1:
-                raise BizLogicError(f"中介机构 '{agency.name}' 已暂停合作")
+                raise BizLogicError(f"Agency '{agency.name}' is currently suspended")
             
             # 专属对接人绑定 (中介拓展人独享40%提成)
             handler_id = agency.owner_id
@@ -97,7 +97,7 @@ class OrderService:
             # 底价校验
             effective_floor = agency.min_floor_price if agency.min_floor_price > 0 else (getattr(product, 'min_floor_price', 0) or 0)
             if effective_floor > 0 and final_amount < effective_floor:
-                raise BizLogicError(f"中介下单金额({final_amount/100:.2f}元)不得低于内部最低协议底价({effective_floor/100:.2f}元)")
+                raise BizLogicError(f"Agency order amount ({final_amount/100:.2f}) cannot be lower than the minimum floor price ({effective_floor/100:.2f})")
         else:
             # 社交账号自收直客单 (小红书/微信私域): 默认录单人自己,亦可指定团队接单人
             handler_id = data.handler_id or auth_user.id
@@ -240,6 +240,19 @@ class OrderService:
         stmt = select(VasOrder).where(VasOrder.id == order_id)
         return (await db.execute(stmt)).scalar_one_or_none()
 
+    @staticmethod
+    async def get_authorized_order(
+        db: AsyncSession,
+        order_id: str,
+        current_user: VasUser
+    ) -> VasOrder:
+        order = await OrderService.get(db, order_id)
+        if not order:
+            raise NotFoundError("Order not found")
+        if current_user.role != "admin" and str(order.user_id) != str(current_user.id):
+            raise PermissionDeniedError("Permission denied: You do not have access to this order")
+        return order
+
     @staticmethod
     async def list_by_user(
         db: AsyncSession,

+ 34 - 8
app/services/payment_service.py

@@ -18,7 +18,7 @@ from app.core.config import settings
 from app.core.creem import CreemClient
 from app.utils.search import apply_keyword_search_stmt
 from app.utils.pagination import paginate
-from app.core.biz_exception import NotFoundError, BizLogicError
+from app.core.biz_exception import NotFoundError, BizLogicError, PermissionDeniedError
 from app.models.user import VasUser
 from app.models.order import VasOrder
 from app.models.payment import VasPayment
@@ -103,7 +103,8 @@ class PaymentService:
     async def create_payment(
         db: AsyncSession,
         payload: VasPaymentCreate,
-        redis_client: Redis
+        redis_client: Redis,
+        current_user: Optional[VasUser] = None,
     ) -> VasPayment:
         """
         创建支付单的主入口
@@ -119,6 +120,9 @@ class PaymentService:
         if not order:
             raise NotFoundError("Order not found")
 
+        if current_user and current_user.role != "admin" and str(order.user_id) != str(current_user.id):
+            raise PermissionDeniedError("Permission denied: You do not have access to this order")
+
         # ② 是否已有 pending payment(幂等)
         stmt = select(VasPayment).where(
             VasPayment.order_id == order.id,
@@ -175,6 +179,20 @@ class PaymentService:
         """
         用户点击“我已支付”
         """
+        stmt = select(VasPayment).where(
+            VasPayment.id == payload.payment_id
+        )
+        payment = (await db.execute(stmt)).scalar_one_or_none()
+        if not payment:
+            raise NotFoundError("Payment not found")
+
+        order_stmt = select(VasOrder).where(VasOrder.id == payment.order_id)
+        order = (await db.execute(order_stmt)).scalar_one_or_none()
+        if not order:
+            raise NotFoundError("Order not found")
+        if current_user.role != "admin" and str(order.user_id) != str(current_user.id):
+            raise PermissionDeniedError("Permission denied: You do not have access to this payment")
+
         # 1️⃣ 查询是否存在对应 payment 确认记录
         result = await db.execute(
             select(VasPaymentConfirmation)
@@ -197,12 +215,6 @@ class PaymentService:
             db.add(record)
             await db.commit()
             await db.refresh(record)
-            
-        
-        stmt = select(VasPayment).where(
-            VasPayment.id == payload.payment_id
-        )
-        payment = (await db.execute(stmt)).scalar_one_or_none()
 
         formatted_time = payload.confirmed_at.strftime('%Y-%m-%d %H:%M') + " (UTC)"
         logger.info(f"💳 [PAYMENT] User confirmed payment: payment_id={payload.payment_id} user={current_user.id} amount={payload.amount} {payload.currency}")
@@ -754,3 +766,17 @@ class PaymentService:
         if not obj:
             raise NotFoundError(message="Payment not found")
         return obj
+
+    @staticmethod
+    async def get_authorized_payment(
+        db: AsyncSession,
+        id: int,
+        current_user: VasUser,
+    ) -> VasPayment:
+        payment = await PaymentService.get_by_id(db, id)
+        if current_user.role != "admin":
+            order_stmt = select(VasOrder).where(VasOrder.id == payment.order_id)
+            order = (await db.execute(order_stmt)).scalar_one_or_none()
+            if not order or str(order.user_id) != str(current_user.id):
+                raise PermissionDeniedError("Permission denied: You do not have access to this payment")
+        return payment

+ 20 - 2
app/services/product_service.py

@@ -8,6 +8,7 @@ from app.utils.search import apply_keyword_search_stmt
 from app.utils.pagination import paginate
 from app.core.biz_exception import NotFoundError
 from app.models.product import VasProduct
+from app.models.plugin import Plugin
 from app.schemas.product import VasProductCreate, VasProductUpdate
 
 
@@ -18,7 +19,15 @@ class ProductService:
         db: AsyncSession,
         data: VasProductCreate,
     ) -> VasProduct:
-        rec = VasProduct(**data.dict())
+        d = data.dict()
+        if d.get("plugin_id") and (not d.get("plugin_name") or not d.get("developer_id")):
+            pl = (await db.execute(select(Plugin).where(Plugin.id == d["plugin_id"]))).scalar_one_or_none()
+            if pl:
+                if not d.get("plugin_name"):
+                    d["plugin_name"] = pl.name
+                if not d.get("developer_id") and pl.developer_id:
+                    d["developer_id"] = pl.developer_id
+        rec = VasProduct(**d)
         db.add(rec)
         await db.commit()
         await db.refresh(rec)
@@ -46,7 +55,16 @@ class ProductService:
         if not rec:
             raise NotFoundError("Product not exist")
 
-        for k, v in data.dict(exclude_unset=True).items():
+        fields = data.dict(exclude_unset=True)
+        if "plugin_id" in fields and fields["plugin_id"]:
+            pl = (await db.execute(select(Plugin).where(Plugin.id == fields["plugin_id"]))).scalar_one_or_none()
+            if pl:
+                if "plugin_name" not in fields or not fields["plugin_name"]:
+                    fields["plugin_name"] = pl.name
+                if ("developer_id" not in fields or not fields["developer_id"]) and pl.developer_id:
+                    fields["developer_id"] = pl.developer_id
+
+        for k, v in fields.items():
             setattr(rec, k, v)
 
         await db.commit()

+ 230 - 0
app/services/r2_storage_service.py

@@ -0,0 +1,230 @@
+import asyncio
+import mimetypes
+import os
+import uuid
+from datetime import datetime
+from typing import Optional, Tuple, Dict, Any
+
+import boto3
+from botocore.config import Config
+from botocore.exceptions import ClientError
+from fastapi import UploadFile
+
+from app.core.config import settings
+from app.core.biz_exception import BizLogicError
+from app.core.logger import logger
+
+
+class R2StorageService:
+    """
+    Cloudflare R2 对象存储服务(S3 兼容)
+    提供文件上传、公网 URL 拼接、流式下载、预签名临时链接与删除能力。
+    针对 FastAPI 异步特性,所有阻塞的 boto3 调用均在异步工作线程中执行。
+    """
+
+    _client = None
+
+    @classmethod
+    def get_client(cls):
+        """懒加载获取 S3 客户端"""
+        if cls._client is None:
+            if not settings.r2_access_key_id or not settings.r2_secret_access_key:
+                raise BizLogicError("Cloudflare R2 credentials not configured. Please check R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.")
+            
+            cls._client = boto3.client(
+                service_name="s3",
+                endpoint_url=settings.r2_endpoint_url,
+                aws_access_key_id=settings.r2_access_key_id,
+                aws_secret_access_key=settings.r2_secret_access_key,
+                region_name="auto",
+                config=Config(
+                    signature_version="s3v4",
+                    retries={"max_attempts": 3, "mode": "standard"},
+                ),
+            )
+        return cls._client
+
+    @classmethod
+    def get_bucket_name(cls, bucket: Optional[str] = None) -> str:
+        """获取目标 Bucket 名称"""
+        target = bucket or settings.r2_bucket_name
+        if not target:
+            raise BizLogicError("R2 bucket name not specified. Please specify bucket or configure R2_BUCKET_NAME.")
+        return target.strip()
+
+    @classmethod
+    def get_public_url(cls, key: str, bucket: Optional[str] = None) -> str:
+        """
+        根据配置的公共域名生成下载/浏览 URL。
+        若未配置自定义公网域名,则默认生成自身 API 代理访问地址,严格防止泄漏 R2 Endpoint、存储桶名称及 AccessKey 凭证。
+        """
+        clean_key = key.lstrip("/")
+        public_domain = (settings.r2_public_domain or "").strip().rstrip("/")
+        if public_domain:
+            return f"{public_domain}/{clean_key}"
+
+        # 默认返回自身后端脱敏代理地址,如 https://api.text.skin/api/r2/file?key=...
+        api_base = (settings.api_base_url or os.getenv("API_BASE_URL", "")).strip().rstrip("/")
+        if api_base:
+            return f"{api_base}/api/r2/file?key={clean_key}"
+        return f"/api/r2/file?key={clean_key}"
+
+
+    @classmethod
+    def generate_presigned_url(cls, key: str, expires_in: int = 3600, bucket: Optional[str] = None) -> str:
+        """生成带有效期的 S3 预签名下载 URL"""
+        b_name = cls.get_bucket_name(bucket)
+        client = cls.get_client()
+        try:
+            return client.generate_presigned_url(
+                ClientMethod="get_object",
+                Params={"Bucket": b_name, "Key": key},
+                ExpiresIn=expires_in,
+            )
+        except Exception as e:
+            logger.error(f"[R2] Failed to generate presigned url for {key}: {e}")
+            raise BizLogicError(f"Failed to generate presigned download URL: {e}")
+
+    @classmethod
+    def _generate_key(cls, filename: str, prefix: str = "uploads") -> str:
+        """生成按年月日划分的唯一文件存储 key"""
+        now = datetime.now()
+        date_path = now.strftime("%Y/%m/%d")
+        ext = os.path.splitext(filename)[1].lower()
+        unique_name = f"{uuid.uuid4().hex[:12]}{ext}"
+        return f"{prefix.strip('/')}/{date_path}/{unique_name}"
+
+    @classmethod
+    async def upload(
+        cls,
+        file: UploadFile,
+        custom_key: Optional[str] = None,
+        bucket: Optional[str] = None,
+        prefix: str = "uploads",
+    ) -> Dict[str, Any]:
+        """
+        上传 FastAPI UploadFile 到 R2 存储桶
+        """
+        content = await file.read()
+        await file.seek(0)
+        filename = file.filename or "file.bin"
+        content_type = file.content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+        return await cls.upload_bytes(
+            content=content,
+            filename=filename,
+            content_type=content_type,
+            custom_key=custom_key,
+            bucket=bucket,
+            prefix=prefix,
+        )
+
+    # 防刷安全配置:单文件最大 1MB,拒绝超大文件刷爆存储
+    MAX_FILE_SIZE: int = 1 * 1024 * 1024
+
+    # 允许上传的安全扩展名白名单(阻断可执行文件、脚本文件)
+    ALLOWED_EXTENSIONS = {
+        ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".bmp", ".ico",
+        ".pdf", ".txt", ".csv", ".json", ".zip", ".tar", ".gz"
+    }
+
+    @classmethod
+    async def upload_bytes(
+        cls,
+        content: bytes,
+        filename: str,
+        content_type: Optional[str] = None,
+        custom_key: Optional[str] = None,
+        bucket: Optional[str] = None,
+        prefix: str = "uploads",
+    ) -> Dict[str, Any]:
+        """
+        上传二进制字节数据到 R2(带安全校验:大小拦截、类型拦截)
+        """
+        # 1. 拦截超大文件
+        if len(content) > cls.MAX_FILE_SIZE:
+            max_mb = cls.MAX_FILE_SIZE // (1024 * 1024)
+            raise BizLogicError(f"File size exceeds the allowed limit (max {max_mb}MB)")
+
+        # 2. 拦截危险文件类型
+        ext = os.path.splitext(filename)[1].lower()
+        if ext not in cls.ALLOWED_EXTENSIONS:
+            raise BizLogicError(f"File extension '{ext}' is not supported. Only safe media and document formats are allowed.")
+
+        b_name = cls.get_bucket_name(bucket)
+        key = custom_key or cls._generate_key(filename, prefix=prefix)
+        mime = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+
+        client = cls.get_client()
+
+        def _do_put():
+            client.put_object(
+                Bucket=b_name,
+                Key=key,
+                Body=content,
+                ContentType=mime,
+            )
+
+        try:
+            await asyncio.to_thread(_do_put)
+            url = cls.get_public_url(key, bucket=b_name)
+            logger.info(f"[R2] Upload success: key={key}, bucket={b_name}, size={len(content)} bytes")
+            return {
+                "key": key,
+                "fid": key,  # 兼容现有前端对 fid 字段的使用习惯
+                "url": url,
+                "filename": filename,
+                "size": len(content),
+                "content_type": mime,
+            }
+        except ClientError as ce:
+            logger.error(f"[R2] ClientError during upload: {ce}")
+            raise BizLogicError(f"R2 upload failed: {ce.response.get('Error', {}).get('Message', str(ce))}")
+        except Exception as e:
+            logger.exception(f"[R2] Unexpected upload error: {e}")
+            raise BizLogicError(f"R2 upload failed with error: {e}")
+
+    @classmethod
+    async def get_file(cls, key: str, bucket: Optional[str] = None) -> Optional[Tuple[bytes, str]]:
+        """
+        获取文件内容及 MIME 类型
+        """
+        b_name = cls.get_bucket_name(bucket)
+        client = cls.get_client()
+
+        def _do_get():
+            try:
+                resp = client.get_object(Bucket=b_name, Key=key)
+                content = resp["Body"].read()
+                content_type = resp.get("ContentType", "application/octet-stream")
+                return content, content_type
+            except ClientError as ce:
+                if ce.response.get("Error", {}).get("Code") in ["NoSuchKey", "404"]:
+                    return None
+                raise
+
+        try:
+            return await asyncio.to_thread(_do_get)
+        except Exception as e:
+            logger.error(f"[R2] Get file error for {key}: {e}")
+            return None
+
+    @classmethod
+    async def delete_file(cls, key: str, bucket: Optional[str] = None) -> bool:
+        """
+        删除 R2 中的文件对象
+        """
+        b_name = cls.get_bucket_name(bucket)
+        client = cls.get_client()
+
+        def _do_delete():
+            client.delete_object(Bucket=b_name, Key=key)
+
+        try:
+            await asyncio.to_thread(_do_delete)
+            logger.info(f"[R2] Delete success: key={key}, bucket={b_name}")
+            return True
+        except Exception as e:
+            logger.error(f"[R2] Delete failed for {key}: {e}")
+            return False

+ 21 - 1
app/services/seaweedfs_service.py

@@ -65,18 +65,38 @@ class SeaweedFSService:
         base_volume = f"{scheme}://{netloc}".rstrip("/")
         return f"{base_volume}/{fid}"
 
+    # 防刷安全配置:单文件最大 1MB,拒绝超大文件刷爆存储
+    MAX_FILE_SIZE: int = 1 * 1024 * 1024
+
+    # 允许上传的安全扩展名白名单(包含插件所需的 .py)
+    ALLOWED_EXTENSIONS = {
+        ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".bmp", ".ico",
+        ".pdf", ".txt", ".csv", ".json", ".zip", ".tar", ".gz", ".py"
+    }
+
     @classmethod
     async def upload(cls, file: UploadFile, max_retries: int = 2) -> Dict[str, Any]:
         """
-        上传文件到 SeaweedFS(带自动重试与 Volume 地址自适应)
+        上传文件到 SeaweedFS(带安全校验:大小与扩展名拦截,带自动重试与 Volume 地址自适应)
         """
         file_content = await file.read()
         filename = file.filename or "file.bin"
         content_type = file.content_type or "application/octet-stream"
 
+        # 1. 拦截超大文件
+        if len(file_content) > cls.MAX_FILE_SIZE:
+            max_mb = cls.MAX_FILE_SIZE // (1024 * 1024)
+            raise BizLogicError(f"File size exceeds the allowed limit (max {max_mb}MB)")
+
+        # 2. 拦截危险文件类型
+        ext = os.path.splitext(filename)[1].lower()
+        if ext and ext not in cls.ALLOWED_EXTENSIONS:
+            raise BizLogicError(f"File extension '{ext}' is not supported. Only safe media and document formats are allowed.")
+
         master_url = cls.get_master_url()
         timeout = aiohttp.ClientTimeout(total=15.0)
 
+
         for attempt in range(max_retries + 1):
             try:
                 async with aiohttp.ClientSession(timeout=timeout) as client:

+ 93 - 49
app/services/settlement_service.py

@@ -6,6 +6,7 @@ from sqlalchemy import select, update, and_, or_, func
 from app.models.order import VasOrder
 from app.models.product import VasProduct
 from app.models.plugin import Plugin
+from app.models.user import VasUser
 from app.models.cost import VasCostRecord
 from app.models.fault import VasFaultCompensation
 from app.models.settlement import VasSettlementPeriod, VasSettlementDetail
@@ -66,8 +67,24 @@ class SettlementService:
         avg_cost = (total_cost // total_orders) if total_orders > 0 else 0
         net_profit = total_revenue - total_cost
 
-        partner_a = req.partner_a_id or "partner_a"
-        partner_b = req.partner_b_id or "partner_b"
+        # 加载所有系统用户,用于真实自然人账号对账与显示
+        u_stmt = select(VasUser)
+        all_users = (await db.execute(u_stmt)).scalars().all()
+        users_map: Dict[str, VasUser] = {u.id: u for u in all_users}
+
+        partner_a = (req.partner_a_id or "").strip()
+        partner_b = (req.partner_b_id or "").strip()
+
+        if not partner_a:
+            raise BizLogicError("请提供合伙人甲方的系统用户ID (partner_a_id),结算系统不使用任何预设值!")
+        if not partner_b:
+            raise BizLogicError("请提供合伙人乙方的系统用户ID (partner_b_id),结算系统不使用任何预设值!")
+        if partner_a not in users_map:
+            raise BizLogicError(f"指定的合伙人甲方用户ID【{partner_a}】在系统用户表中不存在!")
+        if partner_b not in users_map:
+            raise BizLogicError(f"指定的合伙人乙方用户ID【{partner_b}】在系统用户表中不存在!")
+        if partner_a == partner_b:
+            raise BizLogicError("合伙人甲方与乙方不能为同一用户!")
 
         # 预加载当前账期涉及的所有商品与插件,技术分成按订单绑定的商品及处理插件开发管理者自动归属
         product_ids = {o.product_id for o in orders if o.product_id}
@@ -78,55 +95,69 @@ class SettlementService:
             for prod in p_res.scalars().all():
                 products_map[prod.id] = prod
 
-        # 收集商品关联的处理插件
-        plugin_ids = {prod.plugin_id for prod in products_map.values() if getattr(prod, 'plugin_id', None)}
-        plugin_names = set()
-        for prod in products_map.values():
-            if getattr(prod, 'plugin_name', None) and prod.plugin_name.strip():
-                plugin_names.add(prod.plugin_name.strip())
-            if getattr(prod, 'provider', None) and prod.provider.strip():
-                plugin_names.add(prod.provider.strip())
-
-        plugins_map: Dict[str, Plugin] = {}
-        if plugin_ids or plugin_names:
-            conditions = []
-            if plugin_ids:
-                conditions.append(Plugin.id.in_(plugin_ids))
-            if plugin_names:
-                conditions.append(Plugin.name.in_(plugin_names))
-            pl_stmt = select(Plugin).where(or_(*conditions))
-            pl_res = await db.execute(pl_stmt)
-            for pl in pl_res.scalars().all():
-                plugins_map[str(pl.id)] = pl
-                plugins_map[pl.name.lower()] = pl
+        # 加载所有可用插件库
+        pl_stmt = select(Plugin)
+        pl_res = await db.execute(pl_stmt)
+        all_plugins = pl_res.scalars().all()
+        plugins_by_id: Dict[int, Plugin] = {pl.id: pl for pl in all_plugins}
+        plugins_by_name: Dict[str, Plugin] = {pl.name.lower(): pl for pl in all_plugins}
 
         def resolve_order_developer(o: VasOrder) -> str:
-            # 1. 订单本身若已记录明确的 developer_id
+            # 1. 订单本身若已记录明确的 developer_id,且属于系统真实用户
             if o.developer_id and o.developer_id.strip():
-                return o.developer_id.strip()
-            # 2. 从订单绑定的商品推断
-            prod = products_map.get(o.product_id)
-            if prod:
-                # 2.1 商品直接指定了底层开发者
-                if getattr(prod, 'developer_id', None) and prod.developer_id.strip():
-                    return prod.developer_id.strip()
-                # 2.2 商品绑定了处理插件 -> 由插件开发管理者 (Plugin.developer_id) 获得技术分成
-                pl = None
-                if getattr(prod, 'plugin_id', None):
-                    pl = plugins_map.get(str(prod.plugin_id))
-                if not pl and getattr(prod, 'plugin_name', None):
-                    pl = plugins_map.get(prod.plugin_name.strip().lower())
-                if not pl and getattr(prod, 'provider', None):
-                    pl = plugins_map.get(prod.provider.strip().lower())
-
-                if pl and getattr(pl, 'developer_id', None) and pl.developer_id.strip():
-                    return pl.developer_id.strip()
-                if pl:
-                    return f"plugin_{pl.name}_dev"
-                if getattr(prod, 'provider', None):
-                    return f"{prod.provider.lower()}_dev"
-            # 3. 兜底
-            return req.default_developer_id or "unassigned_tech"
+                dev_candidate = o.developer_id.strip()
+                if dev_candidate in users_map:
+                    return dev_candidate
+                # 尝试匹配昵称
+                for u in all_users:
+                    if u.nickname and u.nickname.strip().lower() == dev_candidate.lower():
+                        return u.id
+
+            # 2. 从订单绑定的商品中解析
+            if not o.product_id or o.product_id not in products_map:
+                raise BizLogicError(
+                    f"订单 #{o.id} 未关联有效商品 (product_id={o.product_id}),无法核算技术分成,请先完善订单商品关联!"
+                )
+
+            prod = products_map[o.product_id]
+
+            # 2.1 若商品表显式指定了技术开发者ID且为真实用户
+            if getattr(prod, 'developer_id', None) and prod.developer_id.strip():
+                dev_candidate = prod.developer_id.strip()
+                if dev_candidate in users_map:
+                    return dev_candidate
+                for u in all_users:
+                    if u.nickname and u.nickname.strip().lower() == dev_candidate.lower():
+                        return u.id
+
+            # 2.2 严格检查商品是否显式绑定了处理插件(不进行任何模糊推导,未绑定直接报错)
+            pl = None
+            if getattr(prod, 'plugin_id', None) and prod.plugin_id in plugins_by_id:
+                pl = plugins_by_id[prod.plugin_id]
+            elif getattr(prod, 'plugin_name', None) and prod.plugin_name.strip():
+                pl = plugins_by_name.get(prod.plugin_name.strip().lower())
+
+            if not pl:
+                raise BizLogicError(
+                    f"订单 #{o.id} 所属商品【{prod.title}】(商品ID: {prod.id}) 尚未绑定履约处理插件,无法计算技术分成!请先在「商品管理」编辑弹窗中绑定对应插件后再进行结算。"
+                )
+
+            # 2.3 从绑定的插件中提取 developer_id,且必须为系统真实用户
+            if not getattr(pl, 'developer_id', None) or not pl.developer_id.strip():
+                raise BizLogicError(
+                    f"商品【{prod.title}】绑定的插件【{pl.name} ({pl.display_name})】尚未配置技术开发管理者 (developer_id),无法计算技术分成!请先在「插件管理」中完善开发者配置。"
+                )
+
+            dev_candidate = pl.developer_id.strip()
+            if dev_candidate in users_map:
+                return dev_candidate
+            for u in all_users:
+                if u.nickname and u.nickname.strip().lower() == dev_candidate.lower():
+                    return u.id
+
+            raise BizLogicError(
+                f"商品【{prod.title}】绑定的插件【{pl.name}】所配置的开发者ID【{dev_candidate}】在系统用户表中不存在,无法结算技术分成!"
+            )
 
         # 临时聚合各人的毛利润
         user_gross_map: Dict[str, Dict[str, int]] = {
@@ -139,6 +170,11 @@ class SettlementService:
         for o in orders:
             order_profit = o.final_amount - avg_cost
             dev_id = resolve_order_developer(o)
+            dev_user = users_map.get(dev_id)
+            dev_name = dev_user.nickname if (dev_user and dev_user.nickname) else dev_id
+
+            h_user = users_map.get(o.handler_id) if o.handler_id else None
+            h_name = h_user.nickname if (h_user and h_user.nickname) else o.handler_id
 
             if order_profit <= 0:
                 # 亏损或保本单
@@ -147,7 +183,9 @@ class SettlementService:
                     channel_type=o.channel_type or "direct",
                     agency_id=o.agency_id,
                     handler_id=o.handler_id,
+                    handler_name=h_name,
                     developer_id=dev_id,
+                    developer_name=dev_name,
                     order_amount=o.final_amount,
                     avg_cost=avg_cost,
                     net_profit=order_profit,
@@ -190,7 +228,9 @@ class SettlementService:
                 channel_type=o.channel_type or "direct",
                 agency_id=o.agency_id,
                 handler_id=o.handler_id,
+                handler_name=h_name,
                 developer_id=dev_id,
+                developer_name=dev_name,
                 order_amount=o.final_amount,
                 avg_cost=avg_cost,
                 net_profit=order_profit,
@@ -223,9 +263,13 @@ class SettlementService:
             if breakdown["tech"] > 0:
                 roles.append(f"技术版权:{breakdown['tech']/100:.2f}元")
 
+            user_obj = users_map.get(uid)
+            user_display_name = user_obj.nickname if (user_obj and user_obj.nickname) else uid
+
             net_payout = max(0, total_user_gross - fault_penalty)
             payout_summary.append(SettlementPayoutItem(
                 user_id=uid,
+                user_name=user_display_name,
                 role_description=" | ".join(roles),
                 gross_amount=total_user_gross,
                 fault_penalty=fault_penalty,
@@ -256,7 +300,7 @@ class SettlementService:
         # 1. 检查账期ID是否已存在
         stmt = select(VasSettlementPeriod).where(VasSettlementPeriod.id == req.period_id)
         if (await db.execute(stmt)).scalar_one_or_none():
-            raise BizLogicError(f"账期ID '{req.period_id}' 已存在,不可重复生成")
+            raise BizLogicError(f"Settlement period ID '{req.period_id}' already exists")
 
         # 2. 试算结果
         preview = await SettlementService.preview_settlement(

+ 70 - 9
app/services/ticket_service.py

@@ -8,6 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.utils.search import apply_keyword_search_stmt
 from app.utils.pagination import paginate
 from app.core.biz_exception import NotFoundError, PermissionDeniedError, BizLogicError
+from app.core.logger import logger
 from app.models.user import VasUser
 from app.models.order import VasOrder
 from app.models.vas_task import VasTask
@@ -27,6 +28,28 @@ class TicketService:
         current_user: VasUser,
         redis_client: Redis
     ):
+        # 1. 验证订单存在性及访问权限
+        order_res = await db.execute(
+            select(VasOrder).where(VasOrder.id == data.order_id)
+        )
+        order = order_res.scalar_one_or_none()
+        if not order:
+            raise NotFoundError("Associated order not found")
+
+        if current_user.role != "admin" and str(order.user_id) != str(current_user.id):
+            raise PermissionDeniedError("Permission denied: You do not have permission to create a ticket for this order")
+
+        # 2. 一个订单只能有一个处于打开状态的工单 (pending, info_required)
+        existing_ticket = (await db.execute(
+            select(VasTicket).where(
+                VasTicket.order_id == data.order_id,
+                VasTicket.status.in_(["pending", "info_required"])
+            )
+        )).scalars().first()
+
+        if existing_ticket:
+            raise BizLogicError(f"An open ticket (#{existing_ticket.id}) already exists for this order. Duplicate submissions are not allowed.")
+
         ticket = VasTicket(
             **data.dict(),
             user_id=current_user.id,
@@ -47,7 +70,7 @@ class TicketService:
                 "template_id": "ticket_created",
                 "receiver": current_user.email,
                 "payload": {
-                    "app_name": "TextSkin",
+                    "app_name": "STRATA",
                     "username": current_user.email,
                     "ticket_id": ticket.id,
                     "ticket_type": ticket.type,
@@ -64,8 +87,9 @@ class TicketService:
         db: AsyncSession,
         ticket_id: int,
         status: str,
-        comment: str,
-        admin_id: str,
+        comment: str = "",
+        admin_id: Optional[str] = None,
+        user: Optional[VasUser] = None,
     ) -> VasTicket:
 
         result = await db.execute(
@@ -78,6 +102,8 @@ class TicketService:
         if not ticket:
             raise NotFoundError("Ticket not exist")
 
+        effective_admin_id = admin_id or (str(user.id) if user else "system")
+
         ticket.status = status
         ticket.admin_comment = comment
         ticket.updated_at = datetime.utcnow()
@@ -86,7 +112,7 @@ class TicketService:
             VasTicketMessage(
                 ticket_id=ticket.id,
                 sender_type="admin",
-                sender_id=str(admin_id),
+                sender_id=str(effective_admin_id),
                 content=comment,
                 created_at=datetime.utcnow(),
             )
@@ -100,6 +126,36 @@ class TicketService:
 
         await db.commit()
         await db.refresh(ticket)
+
+        # 标记解决时,自动给工单提出者发送提醒邮件
+        if status == "resolved":
+            try:
+                user_stmt = select(VasUser).where(VasUser.id == ticket.user_id)
+                ticket_user = (await db.execute(user_stmt)).scalar_one_or_none()
+                if ticket_user and ticket_user.email:
+                    formatted_time = ticket.updated_at.strftime('%Y-%m-%d %H:%M') + " (UTC)"
+                    await NotificationService.post_message(
+                        db=db,
+                        channel="email",
+                        payload={
+                            "template_id": "ticket_resolved",
+                            "receiver": ticket_user.email,
+                            "payload": {
+                                "app_name": "STRATA",
+                                "username": ticket_user.nickname or ticket_user.email,
+                                "ticket_id": ticket.id,
+                                "order_id": ticket.order_id or "N/A",
+                                "ticket_type": ticket.type,
+                                "status": "Resolved",
+                                "resolution_comment": comment or "Your ticket has been marked as resolved by customer service.",
+                                "ticket_url": "https://text.skin/dashboard",
+                                "resolved_at": formatted_time,
+                            },
+                        },
+                    )
+            except Exception as e:
+                logger.error(f"Failed to post ticket resolved notification: {e}")
+
         return ticket
 
     # =========================
@@ -185,6 +241,9 @@ class TicketService:
         if not ticket:
             raise NotFoundError("Ticket not exist")
 
+        if sender_type != "admin" and sender_id and str(ticket.user_id) != str(sender_id):
+            raise PermissionDeniedError("Permission denied: You do not have access to this ticket")
+
         message = VasTicketMessage(
             ticket_id=ticket_id,
             sender_type=sender_type,
@@ -207,14 +266,16 @@ class TicketService:
         ticket_id: int,
         page: int = 1,
         size: int = 20,
+        current_user: Optional[VasUser] = None,
     ):
-        # 校验 ticket 是否存在
-        exists = await db.scalar(
-            select(VasTicket.id).where(VasTicket.id == ticket_id)
-        )
-        if not exists:
+        # 校验 ticket 是否存在及权限
+        ticket = await db.get(VasTicket, ticket_id)
+        if not ticket:
             raise NotFoundError("Ticket not exist")
 
+        if current_user and current_user.role != "admin" and str(ticket.user_id) != str(current_user.id):
+            raise PermissionDeniedError("Permission denied: You do not have access to this ticket")
+
         stmt = (
             select(VasTicketMessage)
             .where(VasTicketMessage.ticket_id == ticket_id)

+ 158 - 24
app/services/vas_task_service.py

@@ -4,7 +4,7 @@ from datetime import datetime, date, timedelta
 from typing import List, Optional
 
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import func, text, select, or_, and_
+from sqlalchemy import func, text, select, or_, and_, cast, String
 from redis.asyncio import Redis
 
 from app.core.logger import logger
@@ -68,11 +68,34 @@ class VasTaskService:
         db: AsyncSession,
         order_id: str,
     ) -> List[VasTask]:
-        stmt = select(VasTask).where(
-            VasTask.order_id == order_id
+        stmt = (
+            select(
+                VasTask,
+                VasOrder.product_id.label("order_product_id"),
+                VasOrder.product_name.label("order_product_name"),
+                VasOrder.user_name.label("order_user_name"),
+                VasOrder.status.label("order_status"),
+                VasOrder.final_amount.label("order_final_amount"),
+                VasOrder.base_currency.label("order_base_currency"),
+                VasOrder.created_at.label("order_created_at"),
+            )
+            .outerjoin(VasOrder, VasTask.order_id == VasOrder.id)
+            .where(VasTask.order_id == order_id)
+            .order_by(VasTask.created_at.asc(), VasTask.id.asc())
         )
-        result = await db.execute(stmt)
-        return result.scalars().all()
+        rows = (await db.execute(stmt)).all()
+        items = []
+        for row in rows:
+            task = row[0]
+            task.product_id = row[1]
+            task.product_name = row[2]
+            task.order_user_name = row[3]
+            task.order_status = row[4]
+            task.order_final_amount = row[5]
+            task.order_base_currency = row[6]
+            task.order_created_at = row[7]
+            items.append(task)
+        return items
 
     @staticmethod
     async def list_task(
@@ -81,23 +104,116 @@ class VasTaskService:
         routing_key: Optional[str] = None,
         script_version: Optional[str] = None,
         keyword: Optional[str] = None,
-        page: int = 0,
-        size: int = 10,
+        product_id: Optional[int] = None,
+        sort_by: str = "created_at",
+        sort_order: str = "desc",
+        page: int = 1,
+        size: int = 20,
     ):
-        stmt = select(VasTask)
-        if status:
+        stmt = (
+            select(
+                VasTask,
+                VasOrder.product_id.label("order_product_id"),
+                VasOrder.product_name.label("order_product_name"),
+                VasOrder.user_name.label("order_user_name"),
+                VasOrder.status.label("order_status"),
+                VasOrder.final_amount.label("order_final_amount"),
+                VasOrder.base_currency.label("order_base_currency"),
+                VasOrder.created_at.label("order_created_at"),
+            )
+            .outerjoin(VasOrder, VasTask.order_id == VasOrder.id)
+        )
+
+        count_stmt = select(func.count(VasTask.id)).outerjoin(VasOrder, VasTask.order_id == VasOrder.id)
+
+        if status and status != "all":
             stmt = stmt.where(VasTask.status == status)
-        if routing_key:
+            count_stmt = count_stmt.where(VasTask.status == status)
+
+        if routing_key and routing_key != "all":
             stmt = stmt.where(VasTask.routing_key == routing_key)
-        if script_version:
+            count_stmt = count_stmt.where(VasTask.routing_key == routing_key)
+
+        if script_version and script_version != "all":
             stmt = stmt.where(VasTask.script_version == script_version)
-        stmt = apply_keyword_search_stmt(
-            stmt=stmt,
-            model=VasTask,
-            keyword=keyword,
-            fields=["id", "order_id", "routing_key", "user_inputs", "config", "meta", "grabbed_history"],
-        ).order_by(VasTask.created_at.desc())
-        return await paginate(db, stmt, page, size)
+            count_stmt = count_stmt.where(VasTask.script_version == script_version)
+
+        if product_id:
+            stmt = stmt.where(VasOrder.product_id == product_id)
+            count_stmt = count_stmt.where(VasOrder.product_id == product_id)
+
+        if keyword and keyword.strip():
+            kw = f"%{keyword.strip()}%"
+            filter_cond = or_(
+                cast(VasTask.id, String).ilike(kw),
+                VasTask.order_id.ilike(kw),
+                VasTask.routing_key.ilike(kw),
+                VasOrder.product_name.ilike(kw),
+                VasOrder.user_name.ilike(kw),
+            )
+            stmt = stmt.where(filter_cond)
+            count_stmt = count_stmt.where(filter_cond)
+
+        total = await db.scalar(count_stmt) or 0
+
+        # 排序逻辑优化:
+        # - created_at: 最新入队/创建时间优先 (默认)
+        # - priority: 优先级最高优先 (紧急任务靠前,同优先级按最早创建时间先进先出 FIFO)
+        # - updated_at: 最近活跃/更新时间优先
+        # - id: 任务序列号排序
+        # - order_id: 关联订单号聚合排序
+        is_asc = str(sort_order).lower() == "asc"
+        if sort_by == "priority":
+            if is_asc:
+                stmt = stmt.order_by(VasTask.priority.asc(), VasTask.created_at.asc(), VasTask.id.asc())
+            else:
+                stmt = stmt.order_by(VasTask.priority.desc(), VasTask.created_at.asc(), VasTask.id.asc())
+        elif sort_by == "updated_at":
+            stmt = stmt.order_by(
+                VasTask.updated_at.asc() if is_asc else VasTask.updated_at.desc(),
+                VasTask.id.desc()
+            )
+        elif sort_by == "id":
+            stmt = stmt.order_by(
+                VasTask.id.asc() if is_asc else VasTask.id.desc()
+            )
+        elif sort_by == "order_id":
+            stmt = stmt.order_by(
+                VasTask.order_id.asc() if is_asc else VasTask.order_id.desc(),
+                VasTask.id.asc()
+            )
+        else: # 默认 created_at
+            stmt = stmt.order_by(
+                VasTask.created_at.asc() if is_asc else VasTask.created_at.desc(),
+                VasTask.id.desc()
+            )
+
+        if page < 1:
+            page = 1
+        if size < 1:
+            size = 20
+
+        stmt = stmt.offset((page - 1) * size).limit(size)
+        rows = (await db.execute(stmt)).all()
+
+        items = []
+        for row in rows:
+            task = row[0]
+            task.product_id = row[1]
+            task.product_name = row[2]
+            task.order_user_name = row[3]
+            task.order_status = row[4]
+            task.order_final_amount = row[5]
+            task.order_base_currency = row[6]
+            task.order_created_at = row[7]
+            items.append(task)
+
+        return {
+            "items": items,
+            "total": total,
+            "page": page,
+            "size": size,
+        }
 
     @staticmethod
     async def get_expiring_tasks(
@@ -175,14 +291,32 @@ class VasTaskService:
         db: AsyncSession,
         task_id: int,
     ) -> VasTask:
-        stmt = select(VasTask).where(
-            VasTask.id == task_id,
+        stmt = (
+            select(
+                VasTask,
+                VasOrder.product_id.label("order_product_id"),
+                VasOrder.product_name.label("order_product_name"),
+                VasOrder.user_name.label("order_user_name"),
+                VasOrder.status.label("order_status"),
+                VasOrder.final_amount.label("order_final_amount"),
+                VasOrder.base_currency.label("order_base_currency"),
+                VasOrder.created_at.label("order_created_at"),
+            )
+            .outerjoin(VasOrder, VasTask.order_id == VasOrder.id)
+            .where(VasTask.id == task_id)
         )
-        result = await db.execute(stmt)
-        rec = result.scalar_one_or_none()
-        if not rec:
+        row = (await db.execute(stmt)).first()
+        if not row:
             raise NotFoundError("Task not exist")
-        return rec
+        task = row[0]
+        task.product_id = row[1]
+        task.product_name = row[2]
+        task.order_user_name = row[3]
+        task.order_status = row[4]
+        task.order_final_amount = row[5]
+        task.order_base_currency = row[6]
+        task.order_created_at = row[7]
+        return task
 
     @staticmethod
     async def return_to_queue(db: AsyncSession, id: int) -> VasTask:

+ 2 - 1
requirements.txt

@@ -21,4 +21,5 @@ httpx
 alembic
 APScheduler
 python-dotenv
-paramiko
+paramiko
+boto3

+ 113 - 11
scripts/notification_templates.py

@@ -58,12 +58,12 @@ def _get_status_meta(status: Any, has_earliest_date: bool = False) -> Tuple[str,
 # 1. EMAIL TEMPLATES (Anti-Spam Optimized)
 # ==========================================
 
-def _email_base(content_html: str, app_name: str = "TextSkin") -> str:
+def _email_base(content_html: str, app_name: str = "STRATA") -> str:
     """
     Ultra-clean HTML structure. 
     Uses standard fonts and minimal CSS to pass through ESP filters.
     """
-    safe_app_name = html.escape(str(app_name or "TextSkin"))
+    safe_app_name = html.escape(str(app_name or "STRATA"))
     return f"""
     <!DOCTYPE html>
     <html lang="en">
@@ -106,7 +106,7 @@ def _email_base(content_html: str, app_name: str = "TextSkin") -> str:
 
 
 def template_email_verification_bind(payload: Dict) -> str:
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     code = payload.get('code') or ''
     expiration_time = payload.get('expiration_time') or '10 minutes'
 
@@ -122,7 +122,7 @@ def template_email_verification_bind(payload: Dict) -> str:
 
 
 def template_email_password_reset(payload: Dict) -> str:
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     code = payload.get('code') or ''
     expiration_time = payload.get('expiration_time') or '10 minutes'
 
@@ -136,7 +136,7 @@ def template_email_password_reset(payload: Dict) -> str:
 
 
 def template_email_login_credentials(payload: Dict) -> str:
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     username = payload.get('username') or ''
     password = payload.get('password') or ''
     login_url = payload.get('login_url') or 'https://text.skin/login'
@@ -154,7 +154,7 @@ def template_email_login_credentials(payload: Dict) -> str:
 
 
 def template_email_slot_subscription(payload: Dict) -> str:
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     country = payload.get('country') or ''
     city = payload.get('city') or ''
     location = f"{country}, {city}".strip(", ") or "Specified Location"
@@ -177,7 +177,7 @@ def template_email_slot_subscription(payload: Dict) -> str:
 
 def template_email_appointment_confirmation(payload: Dict) -> str:
     """预约成功确认邮件 (Anti-Spam Optimized)"""
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     username = payload.get('username') or 'Customer'
     order_id = payload.get('order_id') or 'N/A'
     country = payload.get('country') or ''
@@ -222,7 +222,7 @@ def template_email_appointment_confirmation(payload: Dict) -> str:
 
 def template_email_order_event_update(payload: Dict) -> str:
     """订单事件进度更新邮件"""
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     order_no = payload.get('order_no') or 'N/A'
     summary = payload.get('summary') or 'No summary available.'
     dashboard_url = payload.get('dashboard_url') or 'https://text.skin/dashboard'
@@ -247,7 +247,7 @@ def template_email_order_event_update(payload: Dict) -> str:
 
 def template_email_ticket_created(payload: Dict) -> str:
     """用户工单创建确认邮件"""
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     username = payload.get('username') or 'Customer'
     ticket_id = payload.get('ticket_id') or 'N/A'
     ticket_type = payload.get('ticket_type') or 'Support'
@@ -282,9 +282,55 @@ def template_email_ticket_created(payload: Dict) -> str:
     return _email_base(html_content, app_name)
 
 
+def template_email_ticket_resolved(payload: Dict) -> str:
+    """用户工单处理完成提醒邮件"""
+    app_name = payload.get('app_name') or 'STRATA'
+    username = payload.get('username') or 'Customer'
+    ticket_id = payload.get('ticket_id') or 'N/A'
+    ticket_type = payload.get('ticket_type') or 'Support'
+    resolution_comment = payload.get('resolution_comment') or payload.get('comment') or 'Your ticket has been marked as resolved by our customer support team.'
+    ticket_url = payload.get('ticket_url') or 'https://text.skin/dashboard'
+    resolved_at = payload.get('resolved_at') or 'N/A'
+
+    html_content = f"""
+        <h2 style="font-size: 20px; color: #111;">Support Ticket Resolved</h2>
+        <p>Dear {html.escape(str(username))},</p>
+        <p>Your support request <strong>Ticket #{html.escape(str(ticket_id))}</strong> has been marked as <strong>Resolved</strong> by our support team.</p>
+        
+        <table style="width: 100%; background: #f9f9f9; padding: 15px; border-radius: 4px; border-collapse: separate; border-spacing: 0 10px; text-align: left;">
+            <tr>
+                <td style="width: 35%; color: #555;"><strong>Ticket ID:</strong></td>
+                <td><code>#{html.escape(str(ticket_id))}</code></td>
+            </tr>
+            <tr>
+                <td style="color: #555;"><strong>Type:</strong></td>
+                <td>{html.escape(str(ticket_type))}</td>
+            </tr>
+            <tr>
+                <td style="color: #555;"><strong>Status:</strong></td>
+                <td><span style="color: #10b981; font-weight: bold;">Resolved</span></td>
+            </tr>
+            <tr>
+                <td style="color: #555;"><strong>Resolution / Notes:</strong></td>
+                <td>{html.escape(str(resolution_comment))}</td>
+            </tr>
+            <tr>
+                <td style="color: #555;"><strong>Resolved At:</strong></td>
+                <td>{html.escape(str(resolved_at))}</td>
+            </tr>
+        </table>
+        
+        <p>If you have any further questions or need additional assistance, you can view the full details or reply directly via the dashboard.</p>
+        <p style="margin-top: 25px;">
+            <a href="{html.escape(str(ticket_url))}" class="button">View Ticket Details</a>
+        </p>
+    """
+    return _email_base(html_content, app_name)
+
+
 def template_email_payment_confirmed(payload: Dict) -> str:
     """支付成功通知邮件"""
-    app_name = payload.get('app_name') or 'TextSkin'
+    app_name = payload.get('app_name') or 'STRATA'
     amount_decimal = _format_currency(payload.get('amount'))
     currency = payload.get('currency') or 'USD'
     order_id = payload.get('order_id') or 'N/A'
@@ -400,6 +446,26 @@ def template_wechat_ticket_created(payload: Dict) -> str:
     )
 
 
+def template_wechat_ticket_resolved(payload: Dict) -> str:
+    """工单解决微信通知 (Markdown)"""
+    ticket_id = payload.get('ticket_id') or 'N/A'
+    username = payload.get('username') or 'Customer'
+    ticket_type = payload.get('ticket_type') or 'Support'
+    resolution_comment = payload.get('resolution_comment') or payload.get('comment') or 'Resolved'
+    resolved_at = payload.get('resolved_at') or 'N/A'
+
+    return (
+        f"# ✅ Support Ticket Resolved\n"
+        f"--- \n"
+        f"🆔 **Ticket ID:** `#{ticket_id}`\n"
+        f"👤 **User:** {username}\n"
+        f"🏷️ **Type:** {ticket_type}\n"
+        f"📝 **Resolution:** {resolution_comment}\n"
+        f"🕒 **Resolved At:** {resolved_at}\n\n"
+        f"🔗 [View Ticket]({payload.get('ticket_url') or 'https://text.skin/dashboard'})"
+    )
+
+
 def template_telegram_slot_snapshot(payload: Dict) -> str:
     """Slot 快照 TG 通知 (HTML)"""
     has_date = bool(payload.get("earliest_date"))
@@ -494,6 +560,24 @@ def template_telegram_ticket_created(payload: Dict) -> str:
     )
 
 
+def template_telegram_ticket_resolved(payload: Dict) -> str:
+    """工单解决 TG 通知 (HTML)"""
+    ticket_id = html.escape(str(payload.get('ticket_id') or 'N/A'))
+    ticket_type = html.escape(str(payload.get('ticket_type') or 'Support'))
+    username = html.escape(str(payload.get('username') or 'Customer'))
+    comment = html.escape(str(payload.get('resolution_comment') or payload.get('comment') or 'Resolved'))
+
+    return (
+        f"✅ <b>Support Ticket #{ticket_id} Resolved</b>\n"
+        f"──────────────────\n"
+        f"👤 <b>User:</b> {username}\n"
+        f"🏷️ <b>Type:</b> {ticket_type}\n"
+        f"📝 <b>Note:</b> {comment}\n"
+        f"──────────────────\n"
+        f"🔗 <a href='{html.escape(payload.get('ticket_url') or 'https://text.skin/dashboard')}'><b>View Details ➜</b></a>"
+    )
+
+
 def template_whatsapp_slot_snapshot(payload: Dict) -> str:
     """Slot 快照 WhatsApp 通知 (Clean Text)"""
     has_date = bool(payload.get("earliest_date"))
@@ -532,7 +616,7 @@ def template_whatsapp_appointment_confirmation(payload: Dict) -> str:
         f"🛂 *Visa Type:* {visa_type}\n"
         f"📅 *Date:* {appointment_date}\n"
         f"🆔 *Order ID:* {order_id}\n\n"
-        f"Please ensure all required documents are prepared. Thank you for choosing TextSkin."
+        f"Please ensure all required documents are prepared. Thank you for choosing STRATA."
     )
 
 
@@ -577,6 +661,20 @@ def template_whatsapp_ticket_created(payload: Dict) -> str:
     )
 
 
+def template_whatsapp_ticket_resolved(payload: Dict) -> str:
+    """工单解决 WhatsApp 通知"""
+    ticket_id = payload.get('ticket_id') or 'N/A'
+    ticket_type = payload.get('ticket_type') or 'Support'
+    comment = payload.get('resolution_comment') or payload.get('comment') or 'Resolved'
+    return (
+        f"✅ *SUPPORT TICKET RESOLVED*\n\n"
+        f"Ticket ID: #{ticket_id}\n"
+        f"Type: {ticket_type}\n"
+        f"Note: {comment}\n\n"
+        f"Thank you for contacting support."
+    )
+
+
 # ==========================================
 # 3. Dispatchers & Maps
 # ==========================================
@@ -589,6 +687,7 @@ EMAIL_MAP = {
     "appointment_confirmation": (template_email_appointment_confirmation, "Your Visa Appointment Confirmation"),
     "order_event_update": (template_email_order_event_update, "Notification: Visa Appointment Update"),
     "ticket_created": (template_email_ticket_created, "Support Ticket Received"),
+    "ticket_resolved": (template_email_ticket_resolved, "Support Ticket Resolved"),
     "payment_user_confirmed": (template_email_payment_confirmed, "Payment Confirmation Receipt"),
     "payment_confirmed": (template_email_payment_confirmed, "Payment Confirmation Receipt"),
 }
@@ -601,6 +700,7 @@ WECHAT_MAP = {
     "appointment_confirmation": template_wechat_appointment_confirmation,
     "order_event_update": template_wechat_order_event_update,
     "ticket_created": template_wechat_ticket_created,
+    "ticket_resolved": template_wechat_ticket_resolved,
 }
 
 WHATSAPP_MAP = {
@@ -609,6 +709,7 @@ WHATSAPP_MAP = {
     "appointment_confirmation": template_whatsapp_appointment_confirmation,
     "order_event_update": template_whatsapp_order_event_update,
     "ticket_created": template_whatsapp_ticket_created,
+    "ticket_resolved": template_whatsapp_ticket_resolved,
     "payment_user_confirmed": template_whatsapp_payment_confirmed,
     "payment_confirmed": template_whatsapp_payment_confirmed,
 }
@@ -619,6 +720,7 @@ TELEGRAM_MAP = {
     "appointment_confirmation": template_telegram_appointment_confirmation,
     "order_event_update": template_telegram_order_event_update,
     "ticket_created": template_telegram_ticket_created,
+    "ticket_resolved": template_telegram_ticket_resolved,
     "payment_user_confirmed": template_telegram_payment_confirmed,
     "payment_confirmed": template_telegram_payment_confirmed,
 }

+ 4 - 4
tests/test_agent.py

@@ -265,11 +265,11 @@ class TestOpsToolsPermissions(unittest.IsolatedAsyncioTestCase):
 
         res1 = await list_node_configurations(db=mock_db, current_user=normal_user)
         self.assertIn("error", res1)
-        self.assertIn("权限不足", res1["error"])
+        self.assertIn("Permission denied", res1["error"])
 
         res2 = await toggle_node_configuration(entry_type="booker", entry_id=1, enable=True, db=mock_db, current_user=normal_user)
         self.assertIn("error", res2)
-        self.assertIn("权限不足", res2["error"])
+        self.assertIn("Permission denied", res2["error"])
 
     async def test_non_admin_blocked_from_plugins_and_proxies(self):
         from app.services.agent.tools.builtin.plugin_tools import list_plugins
@@ -280,11 +280,11 @@ class TestOpsToolsPermissions(unittest.IsolatedAsyncioTestCase):
 
         p_res = await list_plugins(db=mock_db, current_user=normal_user)
         self.assertIn("error", p_res)
-        self.assertIn("权限不足", p_res["error"])
+        self.assertIn("Permission denied", p_res["error"])
 
         prx_res = await get_proxy_pool_stats(db=mock_db, current_user=normal_user)
         self.assertIn("error", prx_res)
-        self.assertIn("权限不足", prx_res["error"])
+        self.assertIn("Permission denied", prx_res["error"])
 
     @patch("app.services.node_configuration_service.NodeConfigurationService.list_entries")
     async def test_admin_allowed_for_node_configs(self, mock_list_entries):

+ 47 - 0
tests/test_r2_storage.py

@@ -0,0 +1,47 @@
+import pytest
+from unittest.mock import MagicMock, patch
+from app.services.r2_storage_service import R2StorageService
+from app.core.config import settings
+from app.core.biz_exception import BizLogicError
+
+
+def test_r2_settings_loaded():
+    assert settings.r2_account_id == "f97ce2711cc348200b0de273e48f2230"
+    assert settings.r2_access_key_id == "990d57a8f67a6cb024e6660dd2465b91"
+    assert settings.r2_secret_access_key == "9d7be7336c84d412a8eb57f624f71d1f40b316713dec0af290545d23ae73d380"
+    assert "r2.cloudflarestorage.com" in settings.r2_endpoint_url
+
+
+def test_generate_key():
+    key = R2StorageService._generate_key("my_avatar.png", prefix="avatars")
+    assert key.startswith("avatars/")
+    assert key.endswith(".png")
+
+
+@pytest.mark.anyio
+async def test_r2_upload_without_bucket_raises_error():
+    # 当既没有设置环境变量 R2_BUCKET_NAME 也没有传 bucket 时,应抛出 BizLogicError 明确提示
+    original_bucket = settings.r2_bucket_name
+    try:
+        settings.r2_bucket_name = ""
+        with pytest.raises(BizLogicError, match="R2 bucket name not specified"):
+            await R2StorageService.upload_bytes(b"hello", "test.txt", bucket=None)
+    finally:
+        settings.r2_bucket_name = original_bucket
+
+
+@pytest.mark.anyio
+async def test_r2_upload_mocked_success():
+    mock_s3 = MagicMock()
+    with patch.object(R2StorageService, "get_client", return_value=mock_s3):
+        res = await R2StorageService.upload_bytes(
+            content=b"image-binary-data",
+            filename="sample.jpg",
+            content_type="image/jpeg",
+            bucket="test-bucket",
+            custom_key="test/sample.jpg",
+        )
+        assert res["key"] == "test/sample.jpg"
+        assert res["size"] == len(b"image-binary-data")
+        assert res["content_type"] == "image/jpeg"
+        mock_s3.put_object.assert_called_once()

+ 215 - 0
tests/test_rbac_idor_guards.py

@@ -0,0 +1,215 @@
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+from datetime import datetime
+
+from app.models.order import VasOrder
+from app.models.payment import VasPayment
+from app.models.ticket import VasTicket
+from app.models.ticket_message import VasTicketMessage
+from app.models.user import VasUser
+from app.schemas.payment import VasPaymentCreate
+from app.schemas.payment_confirmation import VasPaymentConfirmationCreate
+from app.core.biz_exception import PermissionDeniedError, NotFoundError
+from app.services.order_service import OrderService
+from app.services.payment_service import PaymentService
+from app.services.ticket_service import TicketService
+from app.api.endpoints import order as order_endpoints
+
+
+class TestRbacIdorGuards(unittest.IsolatedAsyncioTestCase):
+
+    def setUp(self):
+        self.owner = VasUser(id="user_owner", email="owner@example.com", role="user")
+        self.stranger = VasUser(id="user_stranger", email="stranger@example.com", role="user")
+        self.admin = VasUser(id="admin_1", email="admin@example.com", role="admin")
+
+        self.order = VasOrder(
+            id="ORD-TEST-123",
+            user_id="user_owner",
+            product_id=1,
+            base_amount=5000,
+            final_amount=5000,
+            base_currency="CNY",
+            status="pending"
+        )
+
+        self.payment = VasPayment(
+            id=99,
+            order_id="ORD-TEST-123",
+            provider="creem",
+            amount=5000,
+            currency="USD",
+            status="pending"
+        )
+
+        self.ticket = VasTicket(
+            id=10,
+            order_id="ORD-TEST-123",
+            user_id="user_owner",
+            type="consult",
+            status="pending"
+        )
+
+    # ---------------- OrderService.get_authorized_order ----------------
+    async def test_get_authorized_order_owner_success(self):
+        db = AsyncMock()
+        mock_res = MagicMock()
+        mock_res.scalar_one_or_none.return_value = self.order
+        db.execute.return_value = mock_res
+
+        res = await OrderService.get_authorized_order(db, "ORD-TEST-123", self.owner)
+        self.assertEqual(res.id, "ORD-TEST-123")
+
+    async def test_get_authorized_order_admin_success(self):
+        db = AsyncMock()
+        mock_res = MagicMock()
+        mock_res.scalar_one_or_none.return_value = self.order
+        db.execute.return_value = mock_res
+
+        res = await OrderService.get_authorized_order(db, "ORD-TEST-123", self.admin)
+        self.assertEqual(res.id, "ORD-TEST-123")
+
+    async def test_get_authorized_order_stranger_denied(self):
+        db = AsyncMock()
+        mock_res = MagicMock()
+        mock_res.scalar_one_or_none.return_value = self.order
+        db.execute.return_value = mock_res
+
+        with self.assertRaises(PermissionDeniedError):
+            await OrderService.get_authorized_order(db, "ORD-TEST-123", self.stranger)
+
+    async def test_get_authorized_order_not_found(self):
+        db = AsyncMock()
+        mock_res = MagicMock()
+        mock_res.scalar_one_or_none.return_value = None
+        db.execute.return_value = mock_res
+
+        with self.assertRaises(NotFoundError):
+            await OrderService.get_authorized_order(db, "ORD-NONEXIST", self.owner)
+
+    # ---------------- PaymentService.create_payment ----------------
+    async def test_create_payment_stranger_denied(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        mock_res = MagicMock()
+        mock_res.scalar_one_or_none.return_value = self.order
+        db.execute.return_value = mock_res
+
+        payload = VasPaymentCreate(order_id="ORD-TEST-123", provider="stripe")
+
+        with self.assertRaises(PermissionDeniedError):
+            await PaymentService.create_payment(db, payload, redis_client, current_user=self.stranger)
+
+    async def test_create_payment_owner_allowed(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        mock_res_order = MagicMock()
+        mock_res_order.scalar_one_or_none.return_value = self.order
+
+        mock_res_pay = MagicMock()
+        mock_res_pay.scalar_one_or_none.return_value = None
+
+        db.execute.side_effect = [mock_res_order, mock_res_pay]
+
+        payload = VasPaymentCreate(order_id="ORD-TEST-123", provider="stripe")
+
+        with patch.object(PaymentService, "_get_exchange_config", return_value={"rates": {"CNY": 1.0, "USD": 0.14}}), \
+             patch.object(PaymentService, "create_stripe_payment", return_value=self.payment):
+            pay = await PaymentService.create_payment(db, payload, redis_client, current_user=self.owner)
+            self.assertEqual(pay.id, 99)
+
+    # ---------------- PaymentService.get_authorized_payment ----------------
+    async def test_get_authorized_payment_stranger_denied(self):
+        db = AsyncMock()
+        mock_res_pay = MagicMock()
+        mock_res_pay.scalar_one_or_none.return_value = self.payment
+
+        mock_res_order = MagicMock()
+        mock_res_order.scalar_one_or_none.return_value = self.order
+
+        db.execute.side_effect = [mock_res_pay, mock_res_order]
+
+        with self.assertRaises(PermissionDeniedError):
+            await PaymentService.get_authorized_payment(db, 99, self.stranger)
+
+    async def test_get_authorized_payment_owner_success(self):
+        db = AsyncMock()
+        mock_res_pay = MagicMock()
+        mock_res_pay.scalar_one_or_none.return_value = self.payment
+
+        mock_res_order = MagicMock()
+        mock_res_order.scalar_one_or_none.return_value = self.order
+
+        db.execute.side_effect = [mock_res_pay, mock_res_order]
+
+        pay = await PaymentService.get_authorized_payment(db, 99, self.owner)
+        self.assertEqual(pay.id, 99)
+
+    async def test_get_authorized_payment_admin_success(self):
+        db = AsyncMock()
+        mock_res_pay = MagicMock()
+        mock_res_pay.scalar_one_or_none.return_value = self.payment
+        db.execute.return_value = mock_res_pay
+
+        pay = await PaymentService.get_authorized_payment(db, 99, self.admin)
+        self.assertEqual(pay.id, 99)
+
+    # ---------------- PaymentService.confirm_by_user ----------------
+    async def test_confirm_by_user_stranger_denied(self):
+        db = AsyncMock()
+        mock_res_pay = MagicMock()
+        mock_res_pay.scalar_one_or_none.return_value = self.payment
+
+        mock_res_order = MagicMock()
+        mock_res_order.scalar_one_or_none.return_value = self.order
+
+        db.execute.side_effect = [mock_res_pay, mock_res_order]
+
+        payload = VasPaymentConfirmationCreate(
+            payment_id=99,
+            amount=5000,
+            currency="USD",
+            random_offset=0,
+            confirmed_at=datetime.utcnow()
+        )
+
+        with self.assertRaises(PermissionDeniedError):
+            await PaymentService.confirm_by_user(db, payload, self.stranger)
+
+    # ---------------- TicketService message authorization ----------------
+    async def test_add_ticket_message_stranger_denied(self):
+        db = AsyncMock()
+        db.get.return_value = self.ticket
+
+        with self.assertRaises(PermissionDeniedError):
+            await TicketService.add_message(
+                db=db,
+                ticket_id=10,
+                sender_type="user",
+                sender_id=self.stranger.id,
+                content="Hello"
+            )
+
+    async def test_list_ticket_messages_stranger_denied(self):
+        db = AsyncMock()
+        db.get.return_value = self.ticket
+
+        with self.assertRaises(PermissionDeniedError):
+            await TicketService.list_messages(
+                db=db,
+                ticket_id=10,
+                current_user=self.stranger
+            )
+
+    # ---------------- Router Declarations ----------------
+    def test_order_endpoints_routing(self):
+        admin_routes = [r.path for r in order_endpoints.admin_required_router.routes]
+        protected_routes = [r.path for r in order_endpoints.protected_router.routes]
+
+        # /vas/order/list_all must be admin only
+        self.assertIn("/vas/order/list_all", admin_routes)
+        self.assertNotIn("/vas/order/list_all", protected_routes)
+
+        # /vas/order/detail must be on protected_router
+        self.assertIn("/vas/order/detail", protected_routes)
+        self.assertNotIn("/vas/order/detail", admin_routes)

+ 82 - 0
tests/test_settlement_tech_attribution.py

@@ -0,0 +1,82 @@
+# tests/test_settlement_tech_attribution.py
+import pytest
+from datetime import datetime
+from sqlalchemy import select, update
+from app.core.database import AsyncSessionLocal
+from app.services.settlement_service import SettlementService
+from app.schemas.settlement import SettlementPreviewRequest
+from app.models.product import VasProduct
+from app.models.user import VasUser
+from app.core.biz_exception import BizLogicError
+
+
+@pytest.mark.anyio
+async def test_settlement_tech_attribution_and_strict_unbound_guard():
+    async with AsyncSessionLocal() as db:
+        # 1. 正常分润试算(明确指定合伙人真实用户ID,所有商品均已绑定插件)
+        res = await SettlementService.preview_settlement(
+            db,
+            SettlementPreviewRequest(
+                start_date=datetime(2026, 9, 1),
+                end_date=datetime(2026, 10, 31),
+                partner_a_id="usr-c1f46c54",
+                partner_b_id="usr-df718001",
+            )
+        )
+
+        assert res.total_orders > 0
+
+        # 验证所有分润归属人必须为系统真实存在的自然人(VasUser),绝不能是 vfs_dev 等虚拟标识
+        all_users = (await db.execute(select(VasUser))).scalars().all()
+        valid_user_ids = {u.id for u in all_users}
+
+        for payout in res.payout_summary:
+            assert payout.user_id in valid_user_ids, f"Invalid user_id in payout: {payout.user_id}"
+            assert not payout.user_id.endswith("_dev"), f"Virtual dev string found: {payout.user_id}"
+            assert payout.user_name is not None
+            assert len(payout.user_name) > 0
+
+        # 验证订单明细中的开发者与对接人均有真实姓名
+        for d in res.details:
+            if d.developer_id:
+                assert d.developer_id in valid_user_ids
+                assert not d.developer_id.endswith("_dev")
+                assert d.developer_name is not None
+
+        # 2. 严格模式测试:商品未绑定插件直接报错,不进行任何模糊推导
+        await db.execute(
+            update(VasProduct).where(VasProduct.id == 36).values(plugin_id=None, plugin_name=None, developer_id=None)
+        )
+        await db.commit()
+
+        try:
+            with pytest.raises(BizLogicError) as exc_info:
+                await SettlementService.preview_settlement(
+                    db,
+                    SettlementPreviewRequest(
+                        start_date=datetime(2026, 9, 1),
+                        end_date=datetime(2026, 10, 31),
+                        partner_a_id="usr-c1f46c54",
+                        partner_b_id="usr-df718001",
+                    )
+                )
+            assert "尚未绑定履约处理插件" in str(exc_info.value)
+        finally:
+            # 恢复商品 36 的插件绑定
+            await db.execute(
+                update(VasProduct).where(VasProduct.id == 36).values(plugin_id=3, plugin_name="vfs_plugin", developer_id="usr-c1f46c54")
+            )
+            await db.commit()
+
+        # 3. 严格模式测试:合伙人未指定直接报错,无任何默认预设
+        with pytest.raises(BizLogicError) as p_exc:
+            await SettlementService.preview_settlement(
+                db,
+                SettlementPreviewRequest(
+                    start_date=datetime(2026, 9, 1),
+                    end_date=datetime(2026, 10, 31),
+                    partner_a_id="",
+                    partner_b_id="usr-df718001",
+                )
+            )
+        assert "请提供合伙人甲方的系统用户ID" in str(p_exc.value)

+ 177 - 0
tests/test_ticket_duplicate_guard.py

@@ -0,0 +1,177 @@
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+from datetime import datetime
+
+from app.models.order import VasOrder
+from app.models.ticket import VasTicket
+from app.models.user import VasUser
+from app.schemas.ticket import VasTicketCreate
+from app.core.biz_exception import BizLogicError, NotFoundError, PermissionDeniedError
+from app.services.ticket_service import TicketService
+
+
+class TestTicketDuplicateGuard(unittest.IsolatedAsyncioTestCase):
+
+    async def test_create_ticket_fails_if_open_ticket_exists(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        user = VasUser(id="user_123", email="user@example.com", role="user")
+
+        order = VasOrder(
+            id="ORD-100",
+            user_id="user_123",
+            product_id=1,
+            base_amount=1000,
+            final_amount=1000,
+            base_currency="CNY",
+            status="paid"
+        )
+        existing_ticket = VasTicket(
+            id=1,
+            order_id="ORD-100",
+            user_id="user_123",
+            type="refund",
+            status="pending"
+        )
+
+        order_res_mock = MagicMock()
+        order_res_mock.scalar_one_or_none.return_value = order
+
+        existing_ticket_mock = MagicMock()
+        existing_ticket_mock.scalars.return_value.first.return_value = existing_ticket
+
+        db.execute.side_effect = [order_res_mock, existing_ticket_mock]
+
+        payload = VasTicketCreate(
+            order_id="ORD-100",
+            type="refund",
+            reason="Repeated refund request"
+        )
+
+        with self.assertRaises(BizLogicError) as ctx:
+            await TicketService.create(db, payload, user, redis_client)
+
+        self.assertIn("already exists", str(ctx.exception))
+
+    async def test_create_ticket_succeeds_if_previous_ticket_resolved(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        user = VasUser(id="user_123", email="user@example.com", role="user")
+
+        order = VasOrder(
+            id="ORD-100",
+            user_id="user_123",
+            product_id=1,
+            base_amount=1000,
+            final_amount=1000,
+            base_currency="CNY",
+            status="paid"
+        )
+
+        order_res_mock = MagicMock()
+        order_res_mock.scalar_one_or_none.return_value = order
+
+        existing_ticket_mock = MagicMock()
+        existing_ticket_mock.scalars.return_value.first.return_value = None
+
+        db.execute.side_effect = [order_res_mock, existing_ticket_mock]
+
+        payload = VasTicketCreate(
+            order_id="ORD-100",
+            type="refund",
+            reason="First ticket request"
+        )
+
+        with patch("app.services.notification_service.NotificationService.post_message", new_callable=AsyncMock):
+            ticket = await TicketService.create(db, payload, user, redis_client)
+            self.assertEqual(ticket.order_id, "ORD-100")
+            self.assertEqual(ticket.status, "pending")
+            db.add.assert_called_once()
+            db.commit.assert_awaited_once()
+
+    async def test_create_ticket_fails_for_nonexistent_order(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        user = VasUser(id="user_123", email="user@example.com", role="user")
+
+        order_res_mock = MagicMock()
+        order_res_mock.scalar_one_or_none.return_value = None
+        db.execute.return_value = order_res_mock
+
+        payload = VasTicketCreate(
+            order_id="NONEXISTENT",
+            type="refund",
+            reason="Invalid order"
+        )
+
+        with self.assertRaises(NotFoundError):
+            await TicketService.create(db, payload, user, redis_client)
+
+    async def test_create_ticket_fails_for_unauthorized_user(self):
+        db = AsyncMock()
+        redis_client = AsyncMock()
+        user = VasUser(id="user_456", email="other@example.com", role="user")
+
+        order = VasOrder(
+            id="ORD-100",
+            user_id="user_123",
+            product_id=1,
+            base_amount=1000,
+            final_amount=1000,
+            base_currency="CNY",
+            status="paid"
+        )
+
+        order_res_mock = MagicMock()
+        order_res_mock.scalar_one_or_none.return_value = order
+        db.execute.return_value = order_res_mock
+
+        payload = VasTicketCreate(
+            order_id="ORD-100",
+            type="refund",
+            reason="Not my order"
+        )
+
+        with self.assertRaises(PermissionDeniedError):
+            await TicketService.create(db, payload, user, redis_client)
+
+    async def test_update_status_resolved_sends_notification_email(self):
+        db = AsyncMock()
+        ticket = VasTicket(
+            id=101,
+            order_id="ORD-100",
+            user_id="user_123",
+            type="refund",
+            status="pending",
+        )
+        user = VasUser(id="user_123", email="customer@example.com", nickname="Alice")
+
+        ticket_res_mock = MagicMock()
+        ticket_res_mock.scalar_one_or_none.return_value = ticket
+
+        # In _handle_resolution: order query
+        order_res_mock = MagicMock()
+        order_res_mock.scalar_one_or_none.return_value = None
+
+        # User query for notification
+        user_res_mock = MagicMock()
+        user_res_mock.scalar_one_or_none.return_value = user
+
+        db.execute.side_effect = [ticket_res_mock, order_res_mock, user_res_mock]
+
+        with patch("app.services.notification_service.NotificationService.post_message", new_callable=AsyncMock) as post_mock:
+            updated = await TicketService.update_status(
+                db=db,
+                ticket_id=101,
+                status="resolved",
+                comment="Issue resolved and refunded.",
+                admin_id="admin_1",
+            )
+            self.assertEqual(updated.status, "resolved")
+            post_mock.assert_awaited_once()
+            call_kwargs = post_mock.call_args.kwargs
+            self.assertEqual(call_kwargs["channel"], "email")
+            self.assertEqual(call_kwargs["payload"]["template_id"], "ticket_resolved")
+            self.assertEqual(call_kwargs["payload"]["receiver"], "customer@example.com")
+            self.assertEqual(call_kwargs["payload"]["payload"]["ticket_id"], 101)
+            self.assertEqual(call_kwargs["payload"]["payload"]["resolution_comment"], "Issue resolved and refunded.")