From 4917f2e01eba49a100a5f68c75ca1afad2c4f4bb Mon Sep 17 00:00:00 2001 From: mzl92 Date: Thu, 12 Feb 2026 15:57:34 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8E=A5=E5=85=A5=E5=8D=8F=E4=BD=9C?= =?UTF-8?q?=E6=A1=86=E6=9E=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建 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 --- ai/CHANGELOG_AI.md | 72 +++++++++++++++++ ai/contracts.yaml | 189 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 ai/CHANGELOG_AI.md create mode 100644 ai/contracts.yaml diff --git a/ai/CHANGELOG_AI.md b/ai/CHANGELOG_AI.md new file mode 100644 index 0000000..3fda4d0 --- /dev/null +++ b/ai/CHANGELOG_AI.md @@ -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. 推送到远程仓库 diff --git a/ai/contracts.yaml b/ai/contracts.yaml new file mode 100644 index 0000000..df2eea2 --- /dev/null +++ b/ai/contracts.yaml @@ -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: "当前季度总周数"