89-基于Django的加利福尼亚州各县死亡概况分析系统

加利福尼亚州各县死亡概况分析系统技术文档

1. 文档目的

本文档基于当前项目真实实现编写，目标是完整说明本系统的：

数据库表设计
功能 PRD
对应的设计思路与实现方式

本文档不是抽象的需求草案，而是面向当前代码版本的实现说明书。文档中提到的模型、页面、接口、后台、表单、服务函数和管理命令，均来自当前实际代码。

2. 项目概览

2.1 项目名称

加利福尼亚州各县死亡概况分析系统

California County Mortality Analytics System

2.2 项目定位

该项目是一个以死亡统计数据为核心的数据分析与管理系统，既包含面向用户的前台分析页面，也包含面向管理员的数据治理后台。

系统主要承载三类能力：

数据展示能力

通过 Dashboard、县域专题、死因专题、图表工坊等模块展示加州各县死亡概况。
数据分析能力

通过筛选、对比、热力图、矩形树图、明细分页和导出，对死亡数据进行多维分析。
数据治理能力

通过 Django Admin、管理首页、用户管理、用户资料管理和死亡数据管理，对系统账号与业务数据进行治理。

2.3 典型用户

匿名访问用户

可直接访问前台公开分析页面。
登录用户

可进入个人中心修改资料、上传头像和修改密码。
管理员

可进入后台总览页和 Django Admin，对用户与死亡数据进行管理。

3. 技术栈与工程结构

3.1 技术栈

后端

Python 3.x
Django 4.2.8
Django ORM
MySQL
Django Admin
SimpleUI

前端

Django Template
Bootstrap 5.3.3
Bootstrap Icons 1.11.3
ECharts 5.5.0
原生 JavaScript

3.2 工程目录

text 复制代码

项目根目录
├─ code/
│  ├─ apps/
│  │  ├─ dashboard/
│  │  └─ records/
│  ├─ config/
│  ├─ templates/
│  ├─ static/
│  ├─ data/
│  └─ manage.py
├─ 系统技术文档.md
└─ 技术文档.md

3.3 主要模块职责

`apps.records`

负责业务主数据，即死亡记录模型、导入命令、后台数据管理。

`apps.dashboard`

负责前台页面、接口、个人中心、标签映射、图表数据聚合与用户资料模型。

`config`

负责全局配置、URL 注册、后台管理首页视图。

`templates`

负责前台页面、后台总览页模板。

`static`

负责 CSS、地图数据、县域坐标等静态资源。

4. 系统实现架构

4.1 总体架构

系统采用 Django 单体架构，但前端图表的数据获取采用页面模板 + 异步接口的混合方式。

整体链路如下：

text 复制代码

CSV 原始数据
  ↓
导入命令 import_death_csv
  ↓
MySQL 数据表 death_records
  ↓
dashboard/services.py 聚合分析
  ↓
dashboard/views.py 页面和 API
  ↓
Django Template + ECharts + JS
  ↓
前台页面 / 个人中心 / 后台管理

4.2 架构分层

数据层

真实数据保存在 MySQL 中，核心业务表为 death_records 与 dashboard_user_profiles。

服务层

code/apps/dashboard/services.py 负责所有统计聚合逻辑，例如：

时间趋势
县域排行
死因排行
分层结构
地图数据
热力图数据
对比图数据
明细摘要

视图层

code/apps/dashboard/views.py 负责：

页面渲染
JSON API 输出
登录/退出
个人中心提交逻辑
导出 CSV

模板层

模板层负责页面结构和交互入口，图表由页面内脚本通过 fetch 调用 API 后渲染。

管理层

后台采用 Django Admin + SimpleUI，并增加了独立管理首页 /admin/overview/。

5. 数据库表设计

本节按真实代码中的模型说明数据库表。

5.1 业务表一：`death_records`

对应模型：code/apps/records/models.py 中的 DeathRecord

5.1.1 表名

python 复制代码

db_table = "death_records"

5.1.2 表用途

用于保存每一条死亡记录，是整个系统的核心业务表。

这张表承载以下分析维度：

年份
月份
县
地理类型
分层类型
分层值
死因编码
死因描述
ICD 版本
死亡数
抑制注释
数据提取时间
数据修订时间

5.1.3 字段结构

字段名	类型	含义
`year`	`PositiveSmallIntegerField`	年份
`month`	`CharField(max_length=2)`	月份，补零后如 `01`、`02`
`county`	`CharField(max_length=100)`	县名
`geography_type`	`CharField(max_length=50)`	地理类型
`strata`	`CharField(max_length=50)`	分层类型，如 Gender、Age
`strata_name`	`CharField(max_length=120)`	分层值，如 Female、65-74 years
`cause_code`	`CharField(max_length=30)`	死因编码
`cause_desc`	`CharField(max_length=255)`	死因文本描述
`icd_revision`	`CharField(max_length=30, blank=True)`	ICD 修订版本
`count`	`IntegerField(null=True, blank=True)`	死亡数，可为空
`annotation_code`	`CharField(max_length=20, blank=True)`	注释代码
`annotation_desc`	`CharField(max_length=255, blank=True)`	注释说明
`data_extract_date`	`DateField(null=True, blank=True)`	数据提取日期
`data_revision_date`	`DateField(null=True, blank=True)`	数据修订日期
`created_at`	`DateTimeField(auto_now_add=True)`	创建时间
`updated_at`	`DateTimeField(auto_now=True)`	更新时间

5.1.4 业务设计思路

使用 year + month 替代完整日期

原始数据以月份统计为主，因此系统直接使用 year 和 month 作为时间维度，便于聚合与导入。
使用 count = null 表达抑制值

原始数据中有一类记录因为样本过小被抑制，不适合强行写成 0，因此保留 null 更符合业务语义。
同时保留 cause_code 和 cause_desc
cause_code 便于标准化识别，cause_desc 便于直接展示和搜索。
strata 和 strata_name 拆分存储
strata 表示维度名称，strata_name 表示该维度具体值，适合做多维分层分析。

5.1.5 索引设计

索引名	字段	设计目的
`death_ym_county_idx`	`year, month, county`	服务首页筛选和县域查询
`death_strata_name_idx`	`strata, strata_name`	服务分层聚合和排序
`death_cause_code_idx`	`cause_code`	按死因过滤
`death_county_cause_idx`	`county, cause_code, strata`	支持县域+死因+分层的组合查询

5.2 业务表二：`dashboard_user_profiles`

对应模型：code/apps/dashboard/models.py 中的 UserProfile

5.2.1 表名

python 复制代码

db_table = "dashboard_user_profiles"

5.2.2 表用途

该表是对 Django 默认用户表的扩展，用于存储个人中心展示和维护所需的信息。

5.2.3 字段结构

字段名	类型	含义
`user`	`OneToOneField`	与 Django 用户一对一关联
`display_name`	`CharField(max_length=80, blank=True)`	显示名称
`avatar`	`FileField(blank=True)`	头像文件
`bio`	`TextField(max_length=240, blank=True)`	个人简介
`created_at`	`DateTimeField(auto_now_add=True)`	创建时间
`updated_at`	`DateTimeField(auto_now=True)`	更新时间

5.2.4 业务设计思路

与 auth_user 拆表

Django 自带用户表负责认证与权限，扩展资料单独放在 UserProfile 中，职责清晰。
头像文件托管在媒体目录
avatar 使用 FileField，上传路径为 avatars/%Y/%m，便于按时间归档。
页面统一通过 preferred_name 获取展示名

优先取 display_name，若为空则回退到 user.get_full_name() 或 username。

5.3 Django 内建表

虽然这些表不是本项目手写模型，但它们在真实代码里被直接使用，因此需要纳入说明。

5.3.1 `auth_user`

职责：

登录认证
后台身份识别
权限控制
个人中心登录态

使用位置：

dashboard/views.py
dashboard/forms.py
config/admin_views.py
Django Admin

5.3.2 `auth_group`

职责：

在后台中进行权限分组管理

使用位置：

Admin 管理首页中的"查看权限分组"入口

5.3.3 `django_admin_log`、`django_session` 等系统表

这些表由 Django 框架自动维护，不是本项目业务主表，但支撑：

后台操作日志
会话保持
权限判断

6. 业务数据导入设计

6.1 导入命令

代码位置：code/apps/records/management/commands/import_death_csv.py

6.2 功能说明

该命令负责将 CSV 中的死亡数据导入数据库。

支持参数：

--path：指定 CSV 路径
--replace：删除旧数据后重新导入
--batch-size：控制批量写入数量

6.3 实现思路

先读取 CSV 文件
将每行转换为 DeathRecord
按批次 bulk_create
支持选择是否先清空旧数据
对数字和日期做安全解析

6.4 设计原因

使用 bulk_create 提高大数据量导入性能
使用 transaction.atomic() 保证导入过程一致性
对 Count 字段允许为空，以保留抑制值语义

7. 功能 PRD

以下 PRD 不是抽象产品描述，而是和当前页面、接口、表单、管理逻辑逐一对应。

7.1 模块总览

系统当前模块包括：

Dashboard 首页
县域洞察
死因专题
图表工坊
明细分析
个人中心登录
个人中心设置
管理首页
Django Admin 后台管理

7.2 PRD：Dashboard 首页

7.2.1 产品目标

作为全系统总入口，面向用户展示全州死亡概览、趋势、地图、排行、分层和质量信息。

7.2.2 功能需求

显示全州死亡概况
支持按年份、月份、县域、分层进行筛选
支持县域滚动排行
支持主要死因排行
支持分层结构展示
支持地图展示
支持重点县对比
支持抑制记录分布

7.2.3 实现代码

页面：code/templates/dashboard/home.html
视图：home
API：
- api_overview
- api_monthly_trend
- api_county_ranking
- api_cause_ranking
- api_live_ranking
- api_county_map
- api_county_compare
- api_suppression_summary
- api_strata_breakdown

7.2.4 设计思路

页面只负责结构和图表容器

数据全部通过 API 获取，避免模板层写复杂聚合逻辑。
首页四个筛选器通过统一查询条件联动多个模块

通过 JS 里的 buildQuery() 拼接参数，保证多个图表使用同一组筛选上下文。
原生 select 替换为自定义主题下拉

为解决 Windows 和浏览器默认控件对下拉菜单白底覆盖的问题，使用"自定义下拉壳 + 隐藏原生 select 同步"模式。
首页强调总览与高频分析

不展示明细表，明细查询交给 analysis 页处理。

7.3 PRD：县域洞察

7.3.1 产品目标

以单个县为中心，查看该县的死亡趋势、主要死因和分层结构。

7.3.2 功能需求

选择县
选择分层
查看县画像指标
查看时间趋势
查看死因构成
查看分层结构

7.3.3 实现代码

页面：code/templates/dashboard/counties.html
视图：county_insights
API：
- api_county_profile
- api_county_trend
- api_county_cause_mix
- api_county_strata_profile

7.3.4 设计思路

将县域场景从首页抽离，避免首页承载过多单县细节
默认县由服务层根据排行自动选择，避免空页面
分层分析复用通用聚合函数 strata_breakdown_data

7.4 PRD：死因专题

7.4.1 产品目标

从某一死因出发，观察它在各县、各月份和各分层人群中的分布。

7.4.2 功能需求

选择死因
选择分层
查看该死因全州趋势
查看重点县域负担
查看死因分层结构

7.4.3 实现代码

页面：code/templates/dashboard/causes.html
视图：cause_explorer
API：
- api_cause_summary
- api_cause_trend
- api_cause_county_burden
- api_cause_strata_profile

7.4.4 设计思路

通过 cause 作为主过滤条件建立专题分析闭环
将死因县域负担和死因分层结构分开展示，保证专题逻辑清晰
通过默认死因值提升页面首屏可用性

7.5 PRD：图表工坊

7.5.1 产品目标

把部分高复用图表做成独立页面，便于展示、比对和扩展。

7.5.2 功能需求

热力矩阵
多县对比折线
死因矩形树图
数据质量图

7.5.3 实现代码

页面：code/templates/dashboard/charts.html
视图：charts_studio
API：
- api_monthly_heatmap
- api_county_compare
- api_cause_treemap
- api_suppression_summary

7.5.4 设计思路

将复用型图表与总览页解耦
避免首页过长，保证总览页面保持节奏
将适合独立讲解的数据视图集中管理

7.6 PRD：明细分析

7.6.1 产品目标

面向需要查看原始记录和导出结果的场景，提供服务端分页与多条件筛选。

7.6.2 功能需求

多条件筛选：年份、月份、县、死因、分层
原始记录分页
图表快照展示
CSV 导出

7.6.3 实现代码

页面：code/templates/dashboard/analysis.html
视图：analysis
导出接口：analysis_export

7.6.4 设计思路

使用服务端分页，避免一次性加载全部明细
导出逻辑复用同一查询条件，保证所见即所得
导出文件增加 County_ZH、Cause_ZH 等对照字段，便于中文环境使用

7.7 PRD：个人中心登录

7.7.1 产品目标

提供进入个人中心的登录入口，区分前台账号入口与后台管理入口。

7.7.2 功能需求

输入用户名和密码登录
登录成功后跳转个人中心
支持管理员直接进入后台

7.7.3 实现代码

页面：code/templates/dashboard/login.html
表单：SignInForm
视图：account_login

7.7.4 设计思路

登录页视觉风格与系统主题统一
登录和后台入口放在同一页面，但职责明确区分
使用 Django 内建认证机制，不重复造用户体系

7.8 PRD：个人中心

7.8.1 产品目标

让用户在前台即可维护自己的资料和密码，而不是被迫进入后台。

7.8.2 功能需求

修改显示名称
修改邮箱
上传头像
修改简介
修改密码
退出账号

7.8.3 实现代码

页面：code/templates/dashboard/profile.html
表单：
- ProfileUpdateForm
- StyledPasswordChangeForm
视图：
- account_center
- account_logout

7.8.4 设计思路

资料更新与密码修改分为两套表单，各自独立提交
密码修改后通过 update_session_auth_hash 保持当前会话
头像文件大小限制在 2MB 内，避免媒体滥用

7.9 PRD：管理首页

7.9.1 产品目标

让后台具有真正的总览首页，而不是直接把 Django Admin 裸暴露给用户。

7.9.2 功能需求

展示后台管理范围
展示账号和数据状态
提供用户管理、用户资料管理、死亡数据管理的入口
展示操作流程和治理规则

7.9.3 实现代码

路由：/admin/overview/
视图：code/config/admin_views.py
模板：code/templates/admin/overview.html

7.9.4 设计思路

将后台首页从 Admin 框架页中单独抽出来
只展示治理相关内容，不混入前台大屏
用状态卡片和模块卡片降低后台使用门槛

7.10 PRD：后台管理

7.10.1 产品目标

后台应聚焦"治理"，包括：

用户管理
用户资料管理
死亡数据管理

7.10.2 功能需求

账号增删改查与权限治理
用户资料查看与维护
死亡记录新增、编辑、删除、搜索、筛选

7.10.3 实现代码

用户资料管理：code/apps/dashboard/admin.py
死亡数据管理：code/apps/records/admin.py

7.10.4 设计思路

用户认证和权限使用 Django 原生机制
用户资料和死亡数据采用自定义 ModelAdmin
死亡记录管理页直接暴露编辑/删除入口，降低操作成本

8. 设计思路与实现策略

8.1 为什么采用 Django 单体架构

当前系统功能覆盖展示、分析、后台和个人中心，但复杂度仍适合单体架构。

采用 Django 单体架构的理由：

开发效率高
模板、ORM、Admin 一体化
页面和后台在一个工程中维护成本低
不需要引入前后端完全分离的额外复杂度

8.2 为什么前端图表采用"模板 + API"模式

如果全部服务端渲染，图表交互会很弱；如果全部前后端分离，工程会变重。

当前做法是折中方案：

页面结构由 Django Template 输出
图表数据由 JS 异步调用接口获取
统计逻辑集中在 Python 服务层

这种方式的优点是：

页面首屏开发简单
图表仍能动态刷新
后端统计逻辑集中，便于维护

8.3 为什么服务函数集中在 `services.py`

dashboard/services.py 是本系统的统计核心。

原因如下：

避免在视图函数中写大量 ORM 聚合逻辑
保证页面视图和 API 视图复用同一套统计规则
后续便于加缓存和性能优化

8.4 为什么做标签映射

原始数据为英文，而系统面向中文环境。

如果直接显示英文，会造成：

页面阅读负担大
图表标签不友好
中英文混排失控

因此系统在 labels.py 中维护：

县域映射
死因映射
分层映射
分层值映射

前端图表通过 dashboardI18n 工具函数做中文优先展示。

8.5 为什么首页四个下拉不用原生白色控件

原生 select 的展开菜单在 Windows / 浏览器下非常容易被系统控件接管，出现：

白底
白字不清晰
展开菜单被卡片遮挡
样式不一致

所以首页最终改成：

隐藏原生 select
保留原生值和 change 事件
使用自定义主题化菜单做视觉展示
通过层级控制解决遮挡问题

8.6 为什么把用户资料从 `auth_user` 拆出来

原因如下：

认证字段和展示字段职责不同
头像、简介等不属于认证核心字段
拆分后更适合个人中心和后台资料管理

8.7 为什么后台只保留治理能力

前台大屏是"看"，后台 Admin 是"管"。

如果把前台可视化页面直接塞进后台，会导致：

后台导航混乱
管理边界不清晰
管理首页不专业

因此现在后台聚焦：

用户
用户资料
死亡数据

9. 关键代码实现映射

9.1 模型

code/apps/records/models.py
code/apps/dashboard/models.py

9.2 视图

code/apps/dashboard/views.py

主要负责：

前台页面渲染
个人中心逻辑
JSON API
CSV 导出

9.3 服务函数

集中在 code/apps/dashboard/services.py。

真实存在的关键函数包括：

dataset_filters
available_filter_options
overview_data
monthly_trend_data
county_ranking_data
cause_ranking_data
strata_breakdown_data
county_map_data
live_ranking_data
county_profile_data
county_trend_data
county_cause_mix_data
county_strata_profile_data
cause_summary_data
cause_trend_data
cause_county_burden_data
cause_strata_profile_data
monthly_heatmap_data
county_compare_data
cause_treemap_data
suppression_summary_data

9.4 表单

位于 code/apps/dashboard/forms.py

SignInForm
ProfileUpdateForm
StyledPasswordChangeForm

9.5 后台管理

code/apps/records/admin.py
code/apps/dashboard/admin.py
code/config/admin_views.py

9.6 模板

code/templates/base.html
code/templates/dashboard/home.html
code/templates/dashboard/counties.html
code/templates/dashboard/causes.html
code/templates/dashboard/charts.html
code/templates/dashboard/analysis.html
code/templates/dashboard/login.html
code/templates/dashboard/profile.html
code/templates/admin/overview.html

10. 测试与质量保证

10.1 测试文件

code/apps/dashboard/tests.py
code/apps/records/tests.py

10.2 当前测试覆盖范围

页面可访问性
概览 API 正确性
县域和死因 API
图表工坊 API
明细导出
登录、资料更新、密码修改
后台管理首页
用户资料后台页
死亡数据后台增改删入口
首页主题下拉结构

10.3 常用验证命令

bash 复制代码

python manage.py check
python manage.py test apps.dashboard apps.records

11. 部署与运行方式

11.1 数据库配置

当前配置位于 code/config/settings.py，数据库使用 MySQL：

数据库名：design_89_death
用户名：root
端口：3306

11.2 初始化流程