城市尾气排放数据可视化分析系统 — 技术文档

1. 项目概述

1.1 项目简介

本系统是一个基于 Python Django 框架的城市尾气排放数据可视化分析平台，面向全国 36 个主要城市的机动车尾气排放数据，提供多维度的数据展示、智能分析和趋势预测能力。系统采用 B/S 架构，前端通过 ECharts 实现丰富的交互式图表，后端通过 Django + Pandas + NumPy 进行数据处理与统计分析，数据持久层使用 MySQL。

1.2 核心功能

功能模块	说明
态势总览	KPI 卡片、智能分析结论、风险预警城市排名、低碳效率标杆、工作日排放对比、区域排放结构对比
地域分布	3D 中国地图（省份下钻至城市）、桑基流图、漏斗图、极坐标柱状图、矩形树图
排放趋势	月度/年度趋势折线图、AQI 南丁格尔玫瑰图、月-周热力矩阵、污染物相关性矩阵、区域 CO2 箱线图、污染物堆叠面积图
车辆结构	能源类型饼图、绿色治理度仪表盘、多维雷达图、GDP-CO2 散点图、新能源占比排行
预测分析	基于线性回归的 CO2 排放预测、Top 城市排放排行、年度 CO2/AQI 对比柱状图
数据管理	分页查询、多条件筛选、CRUD 操作、CSV 导出
用户管理	注册/登录/登出、个人资料编辑、密码修改、管理员用户管理（启用/禁用/删除）

1.3 数据规模

• 覆盖城市：36 个（北京、上海、广州、深圳、天津、重庆、成都、杭州等）
• 覆盖省份：30 个省/直辖市/自治区
• 数据字段：22 个维度（时间、地理、车辆、排放、气象、经济）
• 原始数据量：约 4.16 MB CSV 文件

---

2. 技术栈

2.1 后端

组件	版本	用途
Python	3.8+	运行时环境
Django	4.2.8	Web 框架（路由、视图、模板、ORM、认证）
pandas	2.2.3	数据加载、聚合、透视、相关性计算
NumPy	1.26.2	数值计算（百分位数、线性回归、归一化）
scikit-learn	1.3.2	LinearRegression 预测模型
PyMySQL	1.4.6	MySQL 数据库驱动

2.2 前端

组件	版本	用途
Bootstrap	5.x	响应式布局、表单组件、导航
Bootstrap Icons	—	图标库
ECharts	5.x	图表渲染引擎（折线、柱状、饼图、散点、热力图、桑基、漏斗、雷达、仪表盘、箱线图、地图）
ECharts-GL	—	3D 地图渲染（map3D）
china.js	—	中国地图 GeoJSON 数据

2.3 数据库

组件	说明
MySQL	8.0+，字符集 utf8mb4，排序规则 utf8mb4_unicode_ci
数据库名	design_129_emission
存储引擎	InnoDB（Django 默认）

---

3. 系统架构

3.1 整体架构

┌──────────────────────────────────────────────────────────┐
│                     浏览器 (Client)                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌────────────┐  │
│  │ Bootstrap│  │ ECharts │  │ ECharts │  │ dashboard  │  │
│  │  CSS/JS  │  │  Core   │  │  -GL    │  │    .js     │  │
│  └─────────┘  └─────────┘  └─────────┘  └────────────┘  │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTP (JSON API / HTML)
┌──────────────────────▼───────────────────────────────────┐
│                  Django 应用层                             │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐  │
│  │   urls.py   │→ │  views.py   │→ │   templates/     │  │
│  │  (路由分发)  │  │ (视图逻辑)   │  │  (模板渲染)      │  │
│  └─────────────┘  └──────┬──────┘  └──────────────────┘  │
│                          │                                │
│  ┌─────────────┐  ┌──────▼──────┐  ┌──────────────────┐  │
│  │  forms.py   │  │  models.py  │  │   admin.py       │  │
│  │ (表单验证)   │  │  (数据模型)  │  │  (后台管理)      │  │
│  └─────────────┘  └──────┬──────┘  └──────────────────┘  │
└──────────────────────────┼───────────────────────────────┘
                           │ Django ORM
┌──────────────────────────▼───────────────────────────────┐
│                    MySQL 数据库                            │
│              design_129_emission.emission_records          │
└──────────────────────────────────────────────────────────┘

3.2 数据流

CSV 文件 ──(import_emissions 命令)──→ MySQL ──(ORM Query)──→ Django View
                                                                  │
                                                    ┌─────────────┼─────────────┐
                                                    ▼             ▼             ▼
                                              pandas DataFrame  JSON API    Template
                                              (聚合/统计/分析)  (前端渲染)   (HTML页面)
                                                    │             │
                                                    └──────┬──────┘
                                                           ▼
                                                    ECharts 图表

3.3 项目目录结构

city/
├── manage.py                          # Django 管理入口
├── requirements.txt                   # Python 依赖
├── city_emission_data.csv             # 原始数据集 (4.16 MB)
├── database_init.sql                  # 数据库初始化脚本
├── design_129_emission.sql            # 完整数据库导出
│
├── emission_system/                   # Django 项目配置
│   ├── __init__.py
│   ├── settings.py                    # 全局配置（数据库、中间件、模板、静态文件）
│   ├── urls.py                        # 根路由
│   └── wsgi.py                        # WSGI 入口
│
├── dashboard/                         # 核心应用
│   ├── __init__.py
│   ├── apps.py                        # 应用配置
│   ├── models.py                      # 数据模型 (EmissionRecord)
│   ├── views.py                       # 视图函数 (1731 行，含 15 个 API)
│   ├── urls.py                        # 应用路由 (34 条)
│   ├── forms.py                       # 表单类 (5 个)
│   ├── admin.py                       # Admin 后台配置
│   ├── management/
│   │   └── commands/
│   │       ├── import_emissions.py    # CSV 数据导入命令
│   │       └── seed_admin.py          # 管理员账号初始化
│   └── migrations/
│       └── 0001_initial.py            # 初始迁移
│
├── static/dashboard/
│   ├── css/dashboard.css              # 自定义样式 (2339 行)
│   ├── js/dashboard.js                # 前端逻辑 (1239 行)
│   ├── img/                           # 城市 SVG 插图
│   └── vendor/                        # 第三方库
│       ├── bootstrap/                 # Bootstrap 5 CSS/JS
│       ├── bootstrap-icons/           # 图标字体
│       ├── echarts/                   # ECharts 核心 + china.js
│       └── echarts-gl/                # ECharts 3D 扩展
│
├── templates/
│   ├── base.html                      # 认证页面基础模板
│   └── dashboard/
│       ├── layout.html                # 仪表盘布局（侧边栏 + 顶栏 + 内容区）
│       ├── login.html                 # 登录页
│       ├── register.html              # 注册页
│       ├── overview.html              # 态势总览
│       ├── geo.html                   # 地域分布
│       ├── emission.html              # 排放趋势
│       ├── vehicle.html               # 车辆结构
│       ├── forecast.html              # 预测分析
│       ├── data_management.html       # 数据管理
│       ├── user_management.html       # 用户管理
│       ├── profile.html               # 个人资料
│       ├── password_change.html       # 修改密码
│       ├── record_form.html           # 记录新增/编辑
│       ├── record_confirm_delete.html # 记录删除确认
│       └── partials/
│           └── filter_dock.html       # 筛选器组件
│
└── docs/
    ├── city_drilldown_technical_doc.md
    └── technical_document.md          # 本文档

---

4. 数据模型

4.1 EmissionRecord 模型

系统核心数据模型，存储每条城市尾气排放记录。

class EmissionRecord(models.Model):
    # ── 地理维度 ──
    city = CharField(max_length=50)          # 城市名称
    province = CharField(max_length=50)      # 省份名称
    region = CharField(max_length=30)        # 区域（华东、华南等）

    # ── 时间维度 ──
    date = DateField()                       # 具体日期
    year = PositiveSmallIntegerField()       # 年份（冗余字段，加速查询）
    month = PositiveSmallIntegerField()      # 月份（冗余字段）
    weekday = PositiveSmallIntegerField()    # 星期几（1=周一，7=周日）
    is_workday = BooleanField()              # 是否工作日

    # ── 车辆维度 ──
    vehicle_stock_10k = FloatField()         # 机动车保有量（万辆）
    new_energy_ratio = FloatField()          # 新能源车占比（0-1）
    gasoline_ratio = FloatField()            # 汽油车占比（0-1）
    diesel_ratio = FloatField()              # 柴油车占比（0-1）
    avg_vehicle_age = FloatField()           # 平均车龄（年）

    # ── 排放维度 ──
    co2_emission = FloatField()              # CO2 排放量（吨/日）
    co_emission = FloatField()               # CO 排放量（吨/日）
    nox_emission = FloatField()              # NOx 排放量（吨/日）
    pm25_contribution = FloatField()         # PM2.5 贡献（微克/立方米）
    aqi_index = PositiveSmallIntegerField()  # AQI 指数

    # ── 气象维度 ──
    avg_temperature = FloatField()           # 月均气温（摄氏度）
    humidity = FloatField()                  # 相对湿度（%）
    wind_speed = FloatField()                # 平均风速（米/秒）

    # ── 经济维度 ──
    population_10k = PositiveIntegerField()  # 人口（万人）
    gdp_100m = PositiveIntegerField()        # GDP（亿元）

    # ── 系统字段 ──
    created_at = DateTimeField(auto_now_add=True)  # 创建时间

4.2 数据库索引

索引名	字段	用途
主键索引	id (BigAutoField)	记录唯一标识
单字段索引	city, province, region, date, year, month	筛选查询加速
idx_emission_place	(province, city)	按省市联合查询
idx_emission_ym	(year, month)	按年月联合查询
idx_emission_region	(region, province)	按区域省份联合查询

4.3 数据库初始化

CREATE DATABASE IF NOT EXISTS design_129_emission
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_unicode_ci;

---

5. API 接口文档

所有 API 均需登录认证（@login_required），返回 JSON 格式，支持筛选参数。

5.1 公共筛选参数

参数	类型	说明
province	string	省份筛选
city	string	城市筛选
year	string	年份筛选
q	string	关键词搜索（城市/省份/区域模糊匹配）

5.2 API 列表

5.2.1 GET /api/options/

功能：获取筛选器选项数据

返回：

{
  "ok": true,
  "data": {
    "provinces": ["上海市", "云南省", ...],
    "cities_by_province": {
      "上海市": ["上海"],
      "云南省": ["昆明"],
      ...
    },
    "years": [2019, 2020, 2021, 2022, 2023]
  }
}

5.2.2 GET /api/summary/

功能：态势总览 KPI 数据与区域排放对比

返回：

{
  "ok": true,
  "empty": false,
  "data": {
    "cards": [
      {
        "key": "co2",
        "label": "CO2日排放总量",
        "value": 123.45,
        "unit": "万吨",
        "trend": -2.3
      }
    ],
    "meta": {
      "records": 5000,
      "cities": 36,
      "provinces": 30,
      "regions": 7,
      "year_range": [2019, 2023]
    },
    "region_mix": [
      {
        "region": "华东",
        "co2": 50000.00,
        "aqi": 85.3,
        "nox": 3000.00,
        "city_count": 8
      }
    ]
  }
}

5.2.3 GET /api/trends/

功能：时间趋势数据（月度、年度、星期维度）

返回：

{
  "data": {
    "monthly": [
      { "label": "2023-01", "co2": 50000, "co": 3000, "nox": 2000, "pm25": 45.2, "aqi": 85.3, "new_energy": 15.2 }
    ],
    "yearly": [
      { "year": 2023, "co2": 600000, "nox": 24000, "aqi": 82.1, "vehicle": 350.5, "new_energy": 18.3 }
    ],
    "weekday": [
      { "weekday": 1, "is_workday": true, "co2": 450.5, "aqi": 85.3 }
    ]
  }
}

5.2.4 GET /api/geo/

功能：地理分布数据（省份和城市级 CO2 排放、AQI 等）

返回：

{
  "data": {
    "provinces": [
      {
        "name": "广东省",
        "geo_name": "广东",
        "region": "华南",
        "co2": 80000.00,
        "aqi": 78.5,
        "coord": [113.2669, 23.1333]
      }
    ],
    "cities": [
      {
        "name": "广州",
        "province": "广东省",
        "co2": 25000.00,
        "aqi": 75.2,
        "coord": [113.2644, 23.1291]
      }
    ]
  }
}

5.2.5 GET /api/geo-province/?province=广东省

功能：省份下钻，获取指定省份内城市级数据

参数：province（必填）

返回：与 /api/geo/ 结构类似，但仅包含指定省份的城市数据，另含 funnel、treemap、sankey 图表数据。

5.2.6 GET /api/charts/

功能：综合图表数据（车辆混合、污染物混合、AQI 南丁格尔、省份漏斗、桑基、雷达、仪表盘、散点、热力图、相关性矩阵、矩形树图、箱线图、Top 城市）

5.2.7 GET /api/geo-charts/

功能：地域分布页专用图表数据（漏斗、桑基、极坐标、矩形树图）

5.2.8 GET /api/emission-charts/

功能：排放趋势页专用图表数据（AQI 南丁格尔、热力矩阵、相关性矩阵、箱线图）

5.2.9 GET /api/vehicle-charts/

功能：车辆结构页专用图表数据（能源饼图、仪表盘、雷达、散点）

5.2.10 GET /api/forecast-detail/

功能：预测页 Top 城市排行数据

5.2.11 GET /api/insights/

功能：智能分析结论

返回：

{
  "data": {
    "narrative": [
      "华东区域累计 CO2 排放最高，占当前筛选范围的 32.5%。",
      "广东省广州是排放压力最高城市，CO2 累计 12.50 万吨。"
    ],
    "risk_rank": [
      { "city": "广州", "province": "广东省", "score": 85.3, "co2": 25000, "aqi": 75.2, "new_energy": 18.5 }
    ],
    "efficiency_rank": [...],
    "pressure_rank": [...],
    "region_profile": [...],
    "workday_compare": [...]
  }
}

5.2.12 GET /api/prediction/?horizon=6

功能：CO2 排放趋势预测（线性回归）

参数：horizon（预测月数，3-12，默认 6）

返回：

{
  "data": {
    "history": [{ "label": "2023-01", "value": 50000 }],
    "forecast": [{ "label": "2024-01", "value": 52000 }],
    "method": "LinearRegression + monthly aggregate",
    "generated_at": "2024-01-15 10:30:00"
  }
}

5.2.13 GET /api/export/

功能：CSV 数据导出（带 BOM 头，支持 Excel 直接打开）

返回：text/csv 文件下载

---

6. 核心业务逻辑

6.1 数据导入流程

# 1. 创建数据库
mysql -u root -p < database_init.sql

# 2. 执行迁移
python manage.py migrate

# 3. 导入 CSV 数据
python manage.py import_emissions --path city_emission_data.csv --truncate

# 4. 创建管理员
python manage.py seed_admin --username admin --password 123456

import_emissions 命令流程：

1. 读取 CSV 文件（pandas）
2. 校验必需列是否存在
3. 中文列名映射为英文字段名
4. 类型转换（日期、布尔值）
5. 事务内批量插入（bulk_create，默认 batch_size=1000）
6. 可选 --truncate 清空旧数据

6.2 数据分析流程

视图函数中的数据分析遵循统一模式：

请求 → _filtered_queryset() → _frame() → pandas 聚合 → JSON 序列化 → 响应

1. 筛选：_filtered_queryset(request) 根据 GET 参数构建 Django QuerySet
2. 加载：_frame(request, fields) 将 QuerySet 转为 pandas DataFrame
3. 分析：使用 pandas groupby/agg/corr 等进行多维聚合
4. 序列化：_num() / _int() 辅助函数处理 NaN/Inf 安全转换
5. 返回：_json() 封装 JsonResponse（ensure_ascii=False）

6.3 智能分析算法

6.3.1 风险评分模型

risk_score = (
    minmax(co2) * 34        # CO2 权重 34%
    + minmax(nox) * 22      # NOx 权重 22%
    + minmax(aqi) * 24      # AQI 权重 24%
    + minmax(pm25) * 14     # PM2.5 权重 14%
    + (1 - minmax(new_energy)) * 6  # 新能源占比反向权重 6%
)

其中 minmax() 为 Min-Max 归一化函数，将各指标映射到 [0, 1] 区间。

6.3.2 绿色治理度评分

green_score = clamp(
    100
    - avg_aqi / 3
    - avg_co2 / max_co2 * 35
    + avg_new_energy * 20,
    0, 100
)

6.3.3 CO2 预测模型

使用 scikit-learn 的 LinearRegression，以月度聚合的 CO2 总量为因变量，时间序列为自变量进行线性回归预测。若 scikit-learn 不可用，回退到 NumPy 的 polyfit 一次多项式拟合。

6.4 地图下钻机制

全国地图 (3D map3D)
    │
    │ 点击省份
    ▼
省份下钻 (2D effectScatter)
    │
    │ 点击面包屑"全国"
    ▼
返回全国地图

• 前端维护 drilldown 状态对象（active, province, nationalData）
• 点击省份时调用 /api/geo-province/ 获取城市级数据
• 地图从 3D map3D 切换为 2D effectScatter（涟漪散点）
• 漏斗图、桑基图、矩形树图同步更新为城市级数据
• 面包屑导航支持返回全国视图

---

7. 前端架构

7.1 页面结构

所有仪表盘页面继承 dashboard/layout.html，包含：

• 侧边栏 (dimension-rail)：品牌标识 + 分析维度导航 + 数据量统计
• 顶栏 (workspace-topbar)：页面标题 + 紧凑模式/回到顶部/个人中心/退出
• 内容区 (dashboard-shell)：各页面具体内容
• Toast 容器：操作反馈通知

7.2 JavaScript 模块结构

dashboard.js 采用 IIFE 封装，主要模块：

┌─ 状态管理 ──────────────────────────┐
│  charts{}      ECharts 实例缓存     │
│  state{}       全局状态（选项、模态） │
│  drilldown{}   下钻状态             │
└────────────────────────────────────┘

┌─ 工具函数 ──────────────────────────┐
│  queryString()     构建筛选参数      │
│  getJson()         API 请求封装      │
│  _num()/_int()     数值安全转换      │
│  escapeHtml()      XSS 防护         │
│  showToast()       通知系统          │
└────────────────────────────────────┘

┌─ 图表渲染 ──────────────────────────┐
│  renderMap()         3D/2D 地图     │
│  renderTrend()       趋势折线图      │
│  renderNightingale() 南丁格尔玫瑰图  │
│  renderHeatmap()     热力矩阵       │
│  renderCorrelation() 相关性矩阵     │
│  renderSankey()      桑基流图       │
│  renderFunnel()      漏斗图         │
│  renderRadar()       雷达图         │
│  renderGauge()       仪表盘         │
│  renderScatter()     散点图         │
│  renderBoxplot()     箱线图         │
│  renderTreemap()     矩形树图       │
│  renderPrediction()  预测折线图     │
│  ...                               │
└────────────────────────────────────┘

┌─ 页面加载器 ────────────────────────┐
│  loadOverviewPage()   态势总览      │
│  loadGeoPage()        地域分布      │
│  loadEmissionPage()   排放趋势      │
│  loadVehiclePage()    车辆结构      │
│  loadForecastPage()   预测分析      │
└────────────────────────────────────┘

┌─ 交互功能 ──────────────────────────┐
│  initChartTools()     图表工具栏    │
│  focusChart()         图表聚焦模态  │
│  downloadChart()      图表导出PNG   │
│  enterDrilldown()     省份下钻      │
│  exitDrilldown()      返回全国      │
│  applyCompactMode()   紧凑模式      │
└────────────────────────────────────┘

7.3 图表类型汇总

页面	图表	ECharts 类型	数据 API
态势总览	KPI 卡片	DOM 渲染	/api/summary/
态势总览	智能结论	DOM 渲染	/api/insights/
态势总览	区域柱状图	bar	/api/summary/
态势总览	区域饼图	pie	/api/summary/
地域分布	3D 中国地图	map3D	/api/geo/
地域分布	省份下钻散点	effectScatter	/api/geo-province/
地域分布	桑基流图	sankey	/api/geo-charts/
地域分布	漏斗图	funnel	/api/geo-charts/
地域分布	极坐标柱状图	bar (polar)	/api/geo-charts/
地域分布	矩形树图	treemap	/api/geo-charts/
排放趋势	趋势折线图	line	/api/trends/
排放趋势	污染物堆叠图	line (stack)	/api/trends/
排放趋势	AQI 南丁格尔	pie (roseType)	/api/emission-charts/
排放趋势	月-周热力图	heatmap	/api/emission-charts/
排放趋势	相关性矩阵	heatmap	/api/emission-charts/
排放趋势	箱线图	boxplot	/api/emission-charts/
车辆结构	能源饼图	pie	/api/vehicle-charts/
车辆结构	绿色治理度	gauge	/api/vehicle-charts/
车辆结构	多维雷达	radar	/api/vehicle-charts/
车辆结构	GDP-CO2 散点	scatter	/api/vehicle-charts/
车辆结构	新能源排行	bar (horizontal)	/api/vehicle-charts/
预测分析	CO2 预测折线	line	/api/prediction/
预测分析	年度对比柱状	bar + line	/api/trends/
预测分析	Top 城市表格	DOM 渲染	/api/forecast-detail/

---

8. 用户认证与权限

8.1 认证机制

• 基于 Django 内置认证框架（django.contrib.auth）
• Session 认证，Cookie 存储 Session ID
• 所有仪表盘页面和 API 均需 @login_required 装饰器
• 未登录用户自动跳转至 /login/

8.2 权限模型

角色	权限
普通用户	查看仪表盘、筛选数据、导出 CSV、编辑个人资料
管理员 (is_staff)	普通用户权限 + 用户管理 + Django Admin 后台
超级管理员 (is_superuser)	全部权限

8.3 表单类

表单	用途	字段
BootstrapAuthenticationForm	登录	username, password
BootstrapUserCreationForm	注册	username, email, password1, password2
BootstrapPasswordChangeForm	改密	old_password, new_password1, new_password2
ProfileForm	个人资料	username(只读), email, first_name, last_name
EmissionRecordForm	排放记录 CRUD	除 year/month/weekday/created_at 外全部字段

---

9. 部署与运维

9.1 环境要求

• Python 3.8+
• MySQL 8.0+
• pip (Python 包管理)

9.2 安装步骤

# 1. 克隆项目
cd city/

# 2. 安装依赖
pip install -r requirements.txt

# 3. 创建数据库
mysql -u root -p < database_init.sql

# 4. 配置数据库连接（环境变量或修改 settings.py）
export MYSQL_DATABASE=design_129_emission
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_HOST=localhost
export MYSQL_PORT=3306

# 5. 执行数据库迁移
python manage.py migrate

# 6. 导入数据
python manage.py import_emissions --path city_emission_data.csv --truncate

# 7. 创建管理员
python manage.py seed_admin --username admin --password your_password

# 8. 启动服务
python manage.py runserver 0.0.0.0:8000

9.3 环境变量

变量	默认值	说明
DJANGO_SECRET_KEY	design-129-emission-local-development-key	Django 密钥
DJANGO_DEBUG	1	调试模式（1=开，0=关）
MYSQL_DATABASE	design_129_emission	数据库名
MYSQL_USER	root	数据库用户
MYSQL_PASSWORD	123456	数据库密码
MYSQL_HOST	localhost	数据库主机
MYSQL_PORT	3306	数据库端口

9.4 生产环境建议

1. 安全配置：

   • 设置 DJANGO_DEBUG=0
   • 使用强随机 DJANGO_SECRET_KEY
   • 配置 ALLOWED_HOSTS 为具体域名
   • 数据库用户使用最小权限原则

2. 性能优化：

   • 使用 Gunicorn + Nginx 部署
   • 开启 Django 缓存框架（Redis/Memcached）
   • 对 API 响应启用分页或增量加载
   • 静态文件使用 CDN 或 Nginx 直接服务

3. 数据备份：

   • 定期备份 MySQL 数据库
   • CSV 原始数据归档保存

---

10. 代码质量与规范

10.1 后端规范

• 视图函数使用 @login_required 和 @require_GET 装饰器进行访问控制
• 数据处理使用 pandas DataFrame，避免在 Python 层面手动循环
• 数值输出统一通过 _num() / _int() 处理 NaN/Inf 安全转换
• JSON 响应使用 ensure_ascii=False 支持中文直接输出
• 数据库操作使用 @transaction.atomic 保证事务一致性

10.2 前端规范

• 图表渲染使用 safeRender() 包装，捕获异常并显示错误状态
• XSS 防护：所有动态内容通过 escapeHtml() 转义
• 响应式设计：CSS Grid + Flexbox 布局
• 无障碍：使用 aria-label、aria-live、role 等属性
• 性能：ECharts 实例缓存在 charts{} 对象中，避免重复初始化

10.3 数据安全

• 所有 API 需要登录认证
• CSRF 中间件保护表单提交
• 用户密码使用 Django 内置哈希算法存储
• 管理员操作使用 @user_passes_test 权限检查

---

11. 数据字典

11.1 排放指标

字段	单位	范围	说明
co2_emission	吨/日	>0	城市日均 CO2 排放量
co_emission	吨/日	>0	城市日均 CO 排放量
nox_emission	吨/日	>0	城市日均 NOx 排放量
pm25_contribution	微克/立方米	>0	尾气对 PM2.5 的贡献浓度
aqi_index	无量纲	0-500	空气质量指数

11.2 AQI 等级划分

等级	AQI 范围	颜色
优	0-50	绿色
良	51-100	黄绿
轻度污染	101-150	橙色
中度污染	151-200	红色
重度污染	201-300	紫色
严重污染	>300	褐红

11.3 车辆结构指标

字段	单位	说明
vehicle_stock_10k	万辆	机动车保有量
new_energy_ratio	0-1	新能源车占比
gasoline_ratio	0-1	汽油车占比
diesel_ratio	0-1	柴油车占比
avg_vehicle_age	平均车龄	年

---

12. 扩展与维护指南

12.1 新增城市数据

1. 在 views.py 的 CITY_COORDS 和 PROVINCE_COORDS 字典中添加坐标
2. 准备 CSV 数据，确保列名与 COLUMN_MAP 一致
3. 运行 python manage.py import_emissions 导入

12.2 新增图表

1. 在 views.py 中添加 API 视图函数
2. 在 dashboard/urls.py 中注册路由
3. 在对应模板中添加图表容器 DOM
4. 在 dashboard.js 中添加渲染函数和页面加载逻辑

12.3 新增分析维度

1. 在 EmissionRecord 模型中添加字段
2. 执行 python manage.py makemigrations && python manage.py migrate
3. 更新 VALUE_FIELDS 列表
4. 更新 import_emissions.py 的 COLUMN_MAP
5. 在 API 和前端中使用新字段

12.4 预测模型升级

当前使用简单线性回归，可扩展为：

• ARIMA / SARIMA（时间序列专用）
• Prophet（Facebook 时间序列预测）
• LSTM（深度学习序列预测）
• XGBoost / LightGBM（多特征回归）

扩展位置：views.py 的 api_prediction() 函数。