# CSDN博主-后台数据分析系统完整代码

**Repository Path**: javy21/javy21_case01_csdn_data_analysis

## Basic Information

- **Project Name**: CSDN博主-后台数据分析系统完整代码
- **Description**: WorkBuddy实战：CSDN博主-后台数据分析系统完整代码（离线H5看板·双击即用）

作者从 CSDN 后台下载三类核心数据（趋势图、数据列表、单篇文章分析），系统将其导入本地 Excel 主库做增量合并与历史归档，最终通过纯前端 H5 看板离线展示阅读趋势、粉丝增长、文章排名、单篇深度画像等分析结果。

- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSDN 作品数据本地分析系统

> 本地 Excel 持久化存储 + 定期增量导入 + 纯前端 H5 离线看板
> 全程本地运行，**不依赖任何在线 API / 云服务 / 网络**。

> 代码已按 **《制造数据与AI践行者老蒋的专栏代码规范与工程化实践标准 V1.2》** 编写：统一文件头模板、Python 3.10+ 类型注解、结构化函数注释（含设计推演）、`logging` 分级日志、结构化异常处理、black（`--line-length 100`）、`config.py` 统一配置入口。案例溯源统一映射到虚拟工厂 **智联工坊**（技术内容运营分析看板，数据已脱敏）。

---

## 一、项目简介

本系统用于对个人 CSDN 技术博客后台的**作品数据板块**进行**本地化、可持续**的分析与可视化。

作者从 CSDN 后台下载三类核心数据（趋势图、数据列表、单篇文章分析），系统将其导入本地 Excel 主库做**增量合并与历史归档**，最终通过**纯前端 H5 看板**离线展示阅读趋势、粉丝增长、文章排名、单篇深度画像等分析结果。

设计目标：
- **数据不出本地**：所有处理与展示在用户电脑完成，不调用任何在线 API 或云服务。
- **可持续使用**：支持定期导入新数据，历史快照可回溯，导入可重复执行（幂等）。
- **零运维**：看板双击即开，无需后端、无需数据库服务。

---

## 二、功能特性

| 类别 | 特性 |
|---|---|
| 数据存储 | 三类数据源归一为本地 Excel 主库（多 Sheet），字段与口径统一 |
| 数据导入 | 自动识别文件类型、增量合并（Upsert）、原始文件带时间戳归档、导入审计日志 |
| 趋势分析 | 日阅读量、7 日移动平均、爆发日识别；评论/收藏趋势叠加 |
| 粉丝分析 | 累计粉丝与每日净增（数据源含粉丝列时生效） |
| 文章排名 | 按阅读/展现/收藏/评论多指标排 Top N |
| 转化分析 | 曝光→阅读转化率（阅读量 / 展现量）衡量标题封面吸引力 |
| 单篇画像 | 单篇文章展现/阅读/评论/收藏/关注雷达图 |
| 离线看板 | 纯前端 HTML + 本地 ECharts/SheetJS，支持时间范围、指标开关、搜索排序 |
| 技术合规 | 运行时零外部网络请求，库已本地化；符合 V1.2 代码规范 |

---

## 三、目录结构

```
csdn_analytics/
├── data/
│   ├── inbox/          # ① 把 CSDN 后台下载的 Excel 丢进这里
│   ├── master/
│   │   └── csdn_master.xlsx   # ② 持久化主库 (多 Sheet)
│   └── archive/        # ③ 每次导入的原始文件带时间戳快照
├── logs/               # 运行期日志 (import.log / 控制台分级输出)
├── scripts/
│   ├── config.py            # 统一配置入口 (路径/字段/Sheet/运行参数, .env 注入)
│   ├── import_data.py       # 数据导入 / 增量合并 / 归档 / 生成看板数据
│   └── start_dashboard.py   # (可选) 一键启动本地看板静态服务
├── dashboard/
│   ├── index.html      # H5 离线看板 (双击即可打开)
│   ├── data.js         # 由脚本自动生成的看板数据 (window.CSDN_DATA)
│   └── lib/            # 本地化的 ECharts + SheetJS (离线依赖, 零网络)
├── README.md           # 项目说明
└── debug.md            # 开发排坑记录 (问题/分析/解决, 编号检索)
```

---

## 四、安装步骤

```bash
# 1) 准备 Python 3.10+ 环境 (推荐用独立 venv)
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

# 2) 安装依赖 (仅首次)
pip install pandas openpyxl xlrd python-dotenv
```

> 图表库（ECharts）与读表库（SheetJS）已随项目下载到 `dashboard/lib/`，**无需联网安装**。
> 如需自定义端口或日志级别，在项目根目录新建 `.env` 写入：
> `CSDN_DASHBOARD_PORT=8777`、`CSDN_LOG_LEVEL=INFO`。

---

## 五、使用说明

### 5.1 数据导入（首次 / 定期）

```bash
# 1) 从 CSDN 后台下载「全部文章分析.xlsx」「单篇文章分析.xls」，放入 data/inbox/
# 2) 执行导入
python scripts/import_data.py
```

执行后会自动：识别文件类型 → 增量合并进主库 → 原始文件归档到 `data/archive/` → 重新生成 `dashboard/data.js` → 写入 `import_log` 审计。

日常更新时，重复上述两步即可；同一批数据重复导入为**幂等更新**（不会新增重复行）。

### 5.2 查看看板

```
方式 A：直接双击 dashboard/index.html        # 读本地 data.js，完全离线
方式 B：python scripts/start_dashboard.py    # 若浏览器拦截 file://，起本机静态服务兜底
```

看板交互：
- **时间范围**：起止日期 + 近 7/14/30 天/全部 快捷键，联动所有时间序列图表与 KPI。
- **趋势指标开关**：阅读 / 评论 / 收藏 / 7 日均线，支持图内缩放。
- **排名**：切换指标与 Top N。
- **单篇画像**：下拉选择文章查看雷达图。
- **明细表**：搜索 + 点击表头排序。
- **手动导入**：点击「📂 手动导入 master.xlsx」可用 SheetJS 直接读取任意主库 Excel。

> 颜色约定遵循国内习惯：增长/环比上行用**红色**，下行用**绿色**。

---

## 六、数据存储设计

系统识别 **两类数据模型**（对应 CSDN 三个下载入口）：

| 数据源 | 对应文件 | 落库 Sheet | 主键 | 字段 |
|---|---|---|---|---|
| 趋势图 / 数据列表 | `全部文章分析.xlsx` | `daily_trend` | `日期` | 日期, 阅读量, 评论数, 粉丝数, 收藏数 |
| 单篇文章分析 | `单篇文章分析.xls` | `article_stats` | `文章标题 + 创建日期` | 文章标题, 创建日期, 展现量, 阅读量, 评论数, 收藏数, 关注数 |
| 导入审计 | — | `import_log` | 自增 | 时间, 文件, 类型, 新增, 更新, 状态, 归档 |

> CSDN 的「趋势图」与「数据列表」是同一份每日指标数据的图/表两种形态，故合并为 `daily_trend` 一张表（详见 `debug.md` P2）。

**数据关系映射**：
- `daily_trend`（时间维度，站点每日汇总）与 `article_stats`（文章维度）通过 **日期** 关联——文章 `创建日期` 落在某天，可与当天站点趋势对照。
- 主库统一日期格式为 `YYYY-MM-DD`；所有指标转为整数，缺失补 0。

---

## 七、分析模块

| # | 模块 | 维度 | 核心指标 |
|---|---|---|---|
| ① | 阅读量趋势分析 | 时间序列 | 日阅读量、7 日移动平均、爆发日识别；可叠加评论/收藏 |
| ② | 互动指标趋势 | 时间序列 | 每日评论数、收藏数 |
| ③ | 粉丝增长分析 | 时间序列 | 累计粉丝、每日净增 |
| ④ | 文章表现排名 | 文章维度 | 按 阅读量/展现量/收藏数/评论数 排 Top N |
| ⑤ | 曝光→阅读转化 | 文章维度 | 阅读量 / 展现量 = 点击转化率 |
| ⑥ | 单篇文章深度分析 | 单篇多维 | 展现/阅读/评论/收藏/关注 雷达画像 |
| ⑦ | 文章数据明细 | 明细表 | 全字段表格，搜索 + 表头排序 |

顶部 **KPI 概览**：总阅读量（含环比）、总评论、总收藏、峰值粉丝、文章篇数、篇均阅读。

---

## 八、技术约束与合规

- 数据处理（Python + pandas/openpyxl/xlrd）与展示（HTML + 本地 ECharts/SheetJS）**全部本地完成**。
- 图表库、读表库均已下载到 `dashboard/lib/`，**运行时零外部请求**。
- 不使用任何在线 API、云服务或远程 CDN。
- 存储介质为本地 Excel 文件，天然支持版本备份与离线迁移。
- 代码严格遵循 V1.2 规范（文件头、类型注解、结构化注释、logging 分级、black 100、config.py）；业务场景映射「智联工坊」，无真实企业信息。

---

## 九、排坑记录

开发过程中的问题与解决方案已结构化整理至 **[debug.md](./debug.md)**，每条按「问题发生 / 问题分析 / 问题解决」三段编号（P1–P7），便于检索与博客汇编。