feat: 接入协作框架

- 创建 ai/contracts.yaml 定义服务契约 - 创建 ai/CHANGELOG_AI.md 记录项目变更 - 定义数据接口格式（年度数据、排名数据、季度进度） - 定义技术栈（React 18 + Vite 5 / Vue 3 + Vite 5 / 原生 HTML） - 更新 CHANGES.md 记录项目加入 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-12 15:57:34 +08:00
parent f9f23ace09
commit 4917f2e01e
2 changed files with 261 additions and 0 deletions
@@ -0,0 +1,72 @@
+# sales_data_dashboard 变更日志
+
+> 记录销售数据仪表盘项目的所有重要变更。
+
+---
+
+## [Unreleased]
+
+### Added
+- 项目接入协作框架
+- 创建 `ai/contracts.yaml` 定义服务契约
+- 定义数据接口格式（年度数据、排名数据、季度进度）
+- 定义技术栈（React 18 + Vite 5 / Vue 3 + Vite 5 / 原生 HTML）
+
+---
+
+## [1.0.0] - 2026-02-12
+
+### Added
+- 初始化销售数据仪表盘项目
+- 实现三个版本：原生 HTML、React、Vue
+- 实现年度销售目标和实际销售额展示
+- 实现销售完成率进度条
+- 实现年度季度进度显示（Q1-Q4）
+- 实现小组销售排名（列表 + 柱状图）
+- 实现个人销售排名（列表 + 柱状图）
+- 支持响应式设计（PC 端等比例缩放，移动端自适应）
+- 集成 ECharts 5.4 进行数据可视化
+
+### Features (React 版本)
+- React Hooks (useState, useEffect, useRef)
+- 组件化开发（TopData、GroupRanking、PersonRanking）
+- 防抖处理窗口 resize
+- 图表自动销毁重建
+
+### Features (Vue 版本)
+- Vue 3 Composition API
+- Setup script 语法
+- 响应式数据绑定
+- 生命周期钩子（onMounted、onUnmounted）
+
+### Features (原生 HTML 版本)
+- 原生 JavaScript 实现
+- DOM 操作
+- Fetch API 数据获取
+
+### Technical Details
+- **技术栈**：React 18 / Vue 3 / Vite 5 / ECharts 5.4
+- **开发端口**：React (3001)、Vue (3002)
+- **构建工具**：Vite 5
+- **样式**：原生 CSS3
+- **浏览器支持**：Chrome、Firefox、Safari、Edge
+
+---
+
+## 变更类型说明
+
+- **Added**: 新增功能
+- **Changed**: 功能变更
+- **Deprecated**: 即将废弃的功能
+- **Removed**: 已删除的功能
+- **Fixed**: 问题修复
+- **Security**: 安全性改进
+
+---
+
+## 发布流程
+
+1. 更新 CHANGELOG_AI.md
+2. 更新版本号（package.json）
+3. 创建 Git tag
+4. 推送到远程仓库
@@ -0,0 +1,189 @@
+# 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: "当前季度总周数"