sales_data_dashboard/ai/contracts.yaml

# sales_data_dashboard 服务契约
# 销售数据统计仪表盘 - 数据可视化大屏

# API 规范（遵循中控服务定义的规范）
api_spec: ../../_coordination/API_SPEC.md

# 服务描述
description: >
  销售数据统计仪表盘，用于展示年度销售目标完成情况、小组排名和个人排名。
  提供三个版本实现：原生 HTML、React 18 + Vite 5、Vue 3 + Vite 5。
  支持响应式设计，适配 PC 端和移动端，使用 ECharts 5 进行数据可视化。

# 职责
# - 展示年度销售目标和实际销售额对比
# - 展示销售完成率进度条
# - 展示年度季度进度（Q1-Q4）
# - 展示小组销售排名（列表 + 柱状图）
# - 展示个人销售排名（列表 + 柱状图）
# - 支持数据动态加载和实时更新

# 自己拥有的（owns）
owns:
  # API 接口（无后端 API，纯前端展示）
  apis: []

  # 数据存储（无数据库，使用 API 获取数据）
  tables: []

  # 领域事件（无事件发布）
  events: []

  # 枚举类型
  enums:
    - name: "RankingType"
      description: "排名类型"
      values: ["group", "person"]
      module: "ranking"

    - name: "ChartType"
      description: "图表类型"
      values: ["bar", "line", "pie"]
      module: "chart"

  # 业务流程
  process:
    - name: "数据加载流程"
      description: "从后端 API 获取销售数据（年度目标、实际销售额、排名数据）"
      module: "data"

    - name: "数据可视化流程"
      description: "使用 ECharts 渲染图表（柱状图、折线图、饼图）"
      module: "chart"

    - name: "响应式适配流程"
      description: "根据屏幕尺寸自动调整布局和图表大小"
      module: "ui"

# 依赖的外部服务（depends_on）
depends_on:
  # 后端 API（需要对接）
  apis:
    - name: "GET /api/sales/year-data"
      description: "获取年度销售数据（目标、实际）"
      provider: "backend"
      critical: true

    - name: "GET /api/sales/group-ranking"
      description: "获取小组销售排名"
      provider: "backend"
      critical: true

    - name: "GET /api/sales/person-ranking"
      description: "获取个人销售排名"
      provider: "backend"
      critical: true

    - name: "GET /api/sales/quarter-progress"
      description: "获取季度进度数据"
      provider: "backend"
      critical: false

  # 外部事件
  events: []

# 技术栈（React 版本）
tech_stack:
  type: "web-app"
  framework: "Vite 5"
  language: "React 18 + JavaScript"
  ui_library: "无（原生 CSS）"
  styling: "CSS3"
  build_tool: "Vite 5"
  state_management: "React Hooks"
  deployment: "Static Site"
  api_client: "Fetch API"
  chart_library: "ECharts 5.4"

# 技术栈（Vue 版本）
tech_stack_vue:
  type: "web-app"
  framework: "Vite 5"
  language: "Vue 3 + JavaScript"
  ui_library: "无（原生 CSS）"
  styling: "CSS3（scoped）"
  build_tool: "Vite 5"
  state_management: "Vue 3 Composition API"
  deployment: "Static Site"
  api_client: "Fetch API"
  chart_library: "ECharts 5.4"

# 技术栈（原生 HTML 版本）
tech_stack_vanilla:
  type: "web-app"
  framework: "无（原生 HTML/CSS/JS）"
  language: "JavaScript ES6+"
  ui_library: "无"
  styling: "CSS3"
  build_tool: "无"
  state_management: "无（直接 DOM 操作）"
  deployment: "Static Site"
  api_client: "Fetch API"
  chart_library: "ECharts 5.4"

# 部署配置
deployment:
  type: "Static Site"
  react_app_command: "cd react-app && npm run dev"
  vue_app_command: "cd vue-app && npm run dev"
  vanilla_command: "使用静态服务器（如 nginx）"
  build_command: "cd react-app && npm run build"
  output_dir: "react-app/dist"
  dev_port_react: 3001
  dev_port_vue: 3002

# 环境变量
env:
  - name: "VITE_API_BASE_URL"
    description: "后端 API 地址"
    default: "http://localhost:8000/api"
    required: true

# 数据接口格式（待对接）
data_formats:
  # 年度数据格式
  year_data:
    target:
      type: "number"
      description: "年度销售目标"
      example: 3500
    actual:
      type: "number"
      description: "年度实际销售额"
      example: 2750

  # 排名数据格式
  ranking_data:
    type: "array"
    items:
      name:
        type: "string"
        description: "名称（小组名或个人姓名）"
      target:
        type: "number"
        description: "销售目标"
      actual:
        type: "number"
        description: "实际销售额"
    example:
      - name: "华东一组"
        target: 500
        actual: 450
      - name: "华东二组"
        target: 500
        actual: 380

  # 季度进度数据格式
  quarter_progress:
    type: "object"
    description: "季度进度信息（可选，前端也可自动计算）"
    properties:
      current_quarter:
        type: "number"
        description: "当前季度（1-4）"
      current_week:
        type: "number"
        description: "当前季度第几周"
      total_weeks:
        type: "number"
        description: "当前季度总周数"