datav---Cattle-Industry/README.md

# 全国牛产业数据中心（website 子项目）

本仓库为“官网展示系统（website）”子项目，作为整个项目的入口页面与数据大屏，遵循中文文档与目录规范。其余文档请放置于 `docs/` 目录。

## 项目简介

全国牛产业大数据中心面向全国牛产业上下游（养殖、交易、监管、保险等）数据，提供统一的采集、治理与可视化能力。官网子项目承担门户与数据大屏展示，支持价格行情、预警监测、3D 地图态势与多维指标对比，面向领导查看与公众科普两类场景。

核心目标：
- 打通多源数据（国统局、行业报送、地方平台）并统一口径展示；
- 以可视化与可交互分析为主，强调直观、准确与性能；
- 保持 Windows 开发友好与 CentOS 生产部署稳定。

## 项目概述

- 基于 Vue 3 + Vite 构建的可视化大屏，整合 3D 地图、图表与业务面板。
- 使用 Three.js 渲染 3D 地球与地图，ECharts 绘制数据图表。
- 面向 Windows 开发环境与 CentOS 10（64位）部署环境。

## 技术栈

前端与可视化：
- `vue@3` 组合式 API + 单文件组件。
- `vite@7` 开发与构建，快速热更新。
- `vue-router@4` 页面路由与导航。
- `pinia@3` 轻量状态管理（如需全局状态时使用）。
- `echarts@5` + `vue-echarts@7` 图表组件封装（柱状、折线、饼图、环形进度等）。
- `three@0.179` 3D 场景渲染（地球、地图、光效）。
- `@jiaminghi/data-view` 大屏装饰与框架组件。
- 静态资源与纹理：`public/texture` 与 `public/data/map`。

工程工具：
- `eslint` + `eslint-plugin-vue` 代码规范校验；`oxlint` 性能更优的静态检查。
- `vite-plugin-vue-devtools` 调试与组件检查。
- `npm-run-all2` 脚本编排；`axios` 数据请求。

地图与空间：
- 项目包含 `three` 地球/地图渲染能力；同时预置 `cesium` 与 `mapbox-gl` 以便后续扩展（当前未强依赖，可选接入）。

后续扩展：
- 管理后台（`admin-system`）、小程序（`mini-program`）、后端服务（`backend`）、官网（`website`）与脚本（`scripts`）模块协同，详见 `docs/` 架构与需求文档。

## 目录结构（关键）

```
├── README.md                # 项目入口文档（当前文件）
├── DASHBOARD_COLOR_UPDATE.md# 大屏调色与配色记录
├── docs/                    # 项目文档目录（见下方文档索引）
├── public/                  # 静态资源（地图数据、纹理等）
├── src/
│   ├── App.vue              # 顶部导航与页面切换
│   ├── components/
│   │   ├── Home.vue         # 首页数据大屏
│   │   ├── Map3D.vue        # 3D 地图
│   │   ├── Price.vue        # 价格行情页
│   │   └── Alert.vue        # 预警监测页
│   ├── hooks/               # 组合式 API 工具
│   ├── assets/              # 静态资源
│   ├── utils/               # 工具函数
│   └── main.js              # 应用入口
├── index.html
├── package.json
└── vite.config.js
```

## 环境要求

- Node.js ≥ 20.19.0（或 ≥ 22.12.0）
- npm（或 yarn / pnpm）

## 本地开发（Windows）

```bash
npm install
npm run dev
```

- 终端会显示本地预览地址，例如：`http://localhost:5174/`（端口以实际输出为准）。
- 若端口占用，Vite 会自动切换到可用端口。

## 构建与预览

```bash
npm run build   # 生产构建，输出到 dist/
npm run preview # 本地预览 dist/
```

## 部署（CentOS 10 64位）

1. 上传 `dist/` 到服务器目录（例如：`/var/www/cattle-datav`）。
2. Nginx 配置示例：

```nginx
server {
    listen 80;
    server_name your-domain.com;  # 修改为你的域名或IP
    root /var/www/cattle-datav;   # 指向 dist 目录
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

3. 重新加载 Nginx：`sudo nginx -s reload`。

## 文档索引（docs/）

文档均使用 Markdown 编写，并统一放置在 `docs/` 目录。建议按以下文件名组织：

- 需求文档：
  - `整个项目需求文档.md`
  - `官网需求文档.md`
  - `后端管理需求文档.md`
  - `管理后台需求文档.md`
  - `小程序app需求文档.md`
- 架构文档：
  - `整个项目的架构文档.md`
  - `后端架构文档.md`
  - `小程序架构文档.md`
  - `管理后台架构文档.md`
- 详细设计文档：
  - `数据库设计文档.md`
  - `管理后台接口设计文档.md`
  - `小程序app接口设计文档.md`
- 开发文档（细分到每个子任务的开发计划）：
  - `后端开发文档.md`
  - `小程序app开发文档.md`
  - `管理后台开发文档.md`
  - `后端管理开发文档.md`
- 其他：`测试文档.md`、`部署文档.md`、`运维文档.md`、`安全文档.md`、`用户手册文档.md`

> 说明：本 README 作为项目入口文档；如需新增或更新详细说明，请在 `docs/` 中对应文件维护。

## 项目总结（阶段性）

本阶段完成内容：
- 首页大屏改版：新增“全国牛存栏量”与“全国牛出栏率”年度图表（含折线样式与统一主题配色）。
- 价格行情入口默认跳转至内蒙古数据页；地图 Top5 来源省份更新为“内蒙古/四川/河北”。
- 浏览器标签图标（favicon）替换为牛产业主题图标，统一品牌风格。

后续计划：
- 完成官网子项目与管理后台、后端、小程序的数据接口联调；
- 按 `docs/` 需求与架构文档迭代细分功能与测试用例；
- 强化安全与运维文档，完善监控与日志采集方案。

## 常见问题（FAQ）

- 预览地址端口与 README 不一致？以终端输出为准，Vite 会根据占用情况动态选择端口。
- 图表配色如何统一？参考 `DASHBOARD_COLOR_UPDATE.md`，并在 `Home.vue` 中的各图表 `option` 与数据源颜色字段进行维护。
- 地图数据加载失败？检查 `public/data/map` 路径与资源权限，确保部署路径与 Nginx `root` 对应。

## 许可证

本项目采用 MIT 许可证。

## 变更记录

- 2025-01-18：初始化版本与大屏展示。
- 2025-01-XX：图表与配色优化、首页标题对齐与功能调整。