# 个人工作台

**Repository Path**: womeiqian/my-work-code

## Basic Information

- **Project Name**: 个人工作台
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人工作台（my-work-code）

面向**个人 + 教学双场景**的单用户工作台：仪表盘聚合日期时间（农历/节日/节气）、天气、今日课程、待办、时间进度、重要节点与热榜；并提供任务管理、课程表、课程与学生管理、作业收集与跟踪、知识库、免登录作业提交与文件分享能力。PC 与手机访问同一地址，数据实时一致。

> 项目已开发完成并通过全量自动化回归（226 项断言全部通过）。采用**极简产品取向**：单用户、免登录、无 Token 认证、打开即用；删除即物理删除（前端两次确认），无备份、无回收站。

## 项目简介

- **后端**：Python Flask + SQLite（WAL 模式、外键开启），RESTful API，路由 → service → orm 三层分层，11 张表。
- **前端**：Vue 3 + Vite + Element Plus，7 个页面，一套代码响应式适配 PC 与手机；PC 侧边导航 / 移动端底部 Tab。
- **部署**：家用服务器裸机 + frp 内网穿透，Windows 一键启动脚本（`start-all.bat`）。

## 功能总览

| 模块 | 能力 |
| --- | --- |
| 仪表盘 | 7 张卡片：日期时间（农历/法定节假日/节气）、天气（定位 + 手动城市 + 3/7 天预报）、今日课程、今日待办、时间进度条（日/周/月/年）、重要时间节点（CRUD + 分页）、热榜（5 平台切换，在线 API） |
| 任务管理 | 增删改查、状态流转（未开始/进行中/已完成）、优先级、标题搜索、分页、快速添加 |
| 课程表 | 按周查询、上一周/下一周与指定周切换、JSON 全量导入（覆盖式，格式校验定位到字段行号）、学期第一周开始日期设置、表头日期与今天高亮、学期状态提示 |
| 课程管理 | 课程增删改查、分页、名称模糊搜索、学生名单 / 作业入口 |
| 学生名单 | 增删改查、批量删除、Excel 模板下载、名单导入（失败明细弹窗） |
| 作业管理 | 作业 CRUD、发布状态机（0 未发布 / 1 已发布 / 2 已停止）、提交链接 + 二维码、提交情况（已交/未交/名单外）、打包下载全班作业（统一重命名 `学号-姓名-班级.zip`） |
| 学生提交 | 免登录提交：姓名/学号/班级 + 文件（≤100MB），学号 + 姓名与课程名单匹配校验，学号查重（确认后保留多次记录） |
| 知识库 | 层级文件夹树（收起/展开）、任意类型文件上传（同文件夹同名禁止）、多格式在线预览（md / 代码高亮 / 图片 / 视频 / PDF）、单个与批量下载、标题搜索、文件分享 |
| 文件分享 | 分享链接 + 二维码、有效期设置（秒级）、分享记录管理（分页 / 筛选 / 删除）、落地页按类型在线查看 + 下载 |

## 技术栈与版本

| 端 | 技术 | 版本（实测） |
| --- | --- | --- |
| 后端 | Python | 3.13 |
| 后端 | Flask | 3.1.3 |
| 后端 | SQLite | 内置（WAL 模式 + 外键开启） |
| 后端 | python-dotenv | 1.2.3（配置管理） |
| 后端 | openpyxl | 3.1.5（学生名单 Excel 读写） |
| 后端 | qrcode / Pillow | 8.2 / 12.3.0（二维码本地生成） |
| 后端 | zhdate / chinese-calendar | 0.1 / 1.11.0（农历 / 法定节假日） |
| 后端 | lunar-python | 1.x（节气计算） |
| 后端 | PyYAML | 6.0.3（OpenAPI 规范解析） |
| 后端 | flask-swagger-ui | 5.32.14（Swagger 文档页面） |
| 前端 | Vue | 3.5 |
| 前端 | Vite | 6.0 |
| 前端 | Element Plus | 2.9 |
| 前端 | vue-router | 4.5 |
| 前端 | axios | 1.7 |
| 前端 | dayjs | 1.11 |
| 前端 | marked / dompurify | 15.0 / 3.2（Markdown 渲染与 XSS 清洗） |
| 前端 | highlight.js | 11.12（代码预览高亮 + 行号） |

## 环境要求

| 依赖 | 最低版本 | 开发实测 |
| --- | --- | --- |
| Python | 3.10+ | 3.13 |
| Node.js | 18+ | 22 |
| npm | 9+ | 10 |

- 支持 Windows / macOS / Linux；`start-all.bat` 一键脚本仅限 Windows。
- 首次运行需联网安装依赖；天气、热榜等第三方接口为免费在线 API，无需注册 Key。

## 快速开始

### 方式一：一键启动（Windows）

```bat
双击 代码\start-all.bat
```

脚本自动完成环境自检（缺失 venv 自动创建、缺失依赖自动安装），随后并行弹出后端与前端两个服务窗口；主窗口按任意键可一键关闭全部服务。停止服务可双击 `代码\stop-all.bat`。

### 方式二：手动启动

**后端**

```bash
cd 代码/my-work
python -m venv venv
venv/Scripts/activate        # Windows；macOS/Linux 为 source venv/bin/activate
pip install -r requirements.txt

python scripts/init_db.py    # 初始化数据库（生成 db/workbench.db 与 db/init.db）
python scripts/check_db.py   # 表结构完整性检查（应全部通过）

python run.py                # 启动，访问 http://localhost:5000/api/health
```

**前端**

```bash
cd 代码/my-work-vue
npm install
npm run dev                  # 启动，访问 http://localhost:5173
```

前端开发环境已配置 `/api` 代理，页面内请求 `/api/*` 自动转发到后端 5000 端口。

## 目录结构

```
代码/
├── .gitignore                    # 仓库忽略规则
├── LICENSE                       # MIT 开源许可
├── README.md                     # 本文件
├── start-all.bat / stop-all.bat  # Windows 一键启动 / 停止
├── db/
│   ├── init.db                   # 建表 SQL 脚本（入库，与 models.py 同源生成）
│   └── workbench.db              # SQLite 数据库文件（运行时生成，已忽略）
├── my-work/                      # Flask 后端
│   ├── app/
│   │   ├── __init__.py           # 应用工厂（注册配置 / 数据库 / 蓝图 / 健康检查）
│   │   ├── config.py             # 配置模块（全部读取自 .env，不硬编码）
│   │   ├── db.py                 # SQLite 连接层（WAL + 外键开启，请求级）
│   │   ├── models.py             # 11 张表 DDL 与期望结构元数据（唯一数据源）
│   │   ├── routes/               # 10 个模块蓝图（dashboard / tasks / schedules / semester /
│   │   │                         #   courses / students / assignments / submit / knowledge / shares）
│   │   ├── services/             # 业务逻辑层（16 个：datetime / weather / hotlist / semester ...）
│   │   ├── orm/                  # 数据访问层（9 个：task / schedule / setting / milestone ...）
│   │   ├── swagger.py            # Swagger 文档蓝图（/api/docs/ UI + /api/swagger.json）
│   │   ├── openapi.yaml          # OpenAPI 3.0 规范（覆盖全部接口，随代码同步维护）
│   │   └── utils/                # 校验器 / IP 限频 / 统一响应 / 时间处理（UTC 存储·本地展示）
│   ├── scripts/
│   │   ├── init_db.py            # 初始化：生成 db/workbench.db 与 db/init.db（幂等）
│   │   ├── check_db.py           # 数据库与表结构完整性检查
│   │   ├── seed_demo.py          # 演示数据填充
│   │   └── test_api.py           # 接口全量回归（226 项断言，覆盖 10 个模块）
│   ├── data/                     # 运行时数据（uploads / temp，已忽略）
│   ├── .env / .env.example       # 后端环境变量（模板见 .env.example）
│   ├── requirements.txt
│   └── run.py                    # 后端启动入口
└── my-work-vue/                  # Vue3 前端
    ├── public/favicon.ico        # 站点图标（浏览器标题 logo）
    ├── dist/                     # 构建产物（可静态部署）
    ├── src/
    │   ├── api/                  # axios 封装（request.js）+ 全部 49 个接口封装（index.js）
    │   ├── router/index.js       # 7 条路由（/、/tasks、/schedule、/courses、/knowledge、/submit/:token、/share/:token）
    │   ├── layout/Layout.vue     # 全局布局（PC 侧边导航 + 移动端底部 Tab）
    │   ├── views/                # 7 个页面视图（Dashboard / Tasks / Schedule / Courses / Knowledge / Submit / Share）
    │   ├── components/           # ScheduleGrid（课表网格）、StudentDialog（学生名单弹窗）
    │   ├── styles/index.css      # 设计令牌（墨蓝 + 暖金学者风）+ Element Plus 主题覆盖
    │   ├── App.vue / main.js     # 根组件 / 入口
    │   └── utils/download.js     # blob 下载辅助
    ├── .env / .env.example       # 前端环境变量
    ├── package.json
    ├── vite.config.js            # Vite 配置（/api 代理、allowedHosts 放行、缓存目录）
    └── index.html
```

## 数据库设计

共 **11 张表**：`task`（任务）、`schedule`（课表）、`course`（课程）、`student`（学生）、`assignment`（作业，含发布状态 status 0/1/2）、`submission`（作业提交）、`folder`（知识库文件夹，自关联层级）、`file`（知识库文件）、`share`（分享）、`milestone`（重要节点）、`setting`（键值设置，如学期第一周开始日期）。

关键约定：

- 时间字段统一存 UTC（`YYYY-MM-DDTHH:MM:SSZ`），展示统一转本地时区 `yyyy-MM-dd HH:mm:ss`；日期字段存 `YYYY-MM-DD`。
- 主键统一 `INTEGER PRIMARY KEY AUTOINCREMENT`；无用户体系字段、无软删除。
- 外键仅声明关联，级联删除由应用层事务实现（课程删除级联学生/作业/提交文件；文件夹删除递归级联；文件删除级联分享记录）。
- 建表 SQL 幂等可重复执行；`scripts/check_db.py` 可校验表结构完整性。

## API 接口

- 统一响应结构：成功 `{ "code": 0, "message": "ok", "data": ... }`；失败返回非 0 code + HTTP 状态码（400 / 404 / 409 / 410 过期 / 413 超限 / 415 类型 / 429 限频 / 500 / 503）。
- 全部接口无认证、开放访问；上传类接口带 IP 频率限制（默认 10 次/分）。
- 10 个模块：仪表盘（含天气 / 热榜 / 时间节点）、任务、课程表、学期设置、课程、学生名单、作业（含发布/停止/提交情况/打包下载）、学生提交（token 定位）、知识库（文件夹/文件/预览/批量下载/搜索）、分享（创建/列表/信息/预览/下载/删除）。
- Swagger 交互式文档：`/api/docs/`（UI）+ `/api/swagger.json`（规范），随代码同步维护。

## 配置说明

所有环境相关配置均通过 `.env` 文件管理，不硬编码。首次使用请复制 `.env.example` 为 `.env` 后按需修改。

### 后端（my-work/.env）

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| DATABASE_PATH | SQLite 数据库路径 | `../db/workbench.db` |
| UPLOAD_DIR / TEMP_DIR | 上传目录 / 打包临时目录 | `data/uploads` / `data/temp` |
| MAX_CONTENT_LENGTH_ASSIGNMENT | 作业提交单文件上限 | `104857600`（100MB） |
| MAX_CONTENT_LENGTH_KNOWLEDGE | 知识库单文件上限 | `524288000`（500MB） |
| RATE_LIMIT_PER_MINUTE | 上传接口 IP 限频（次/分钟） | `10` |
| OPEN_METEO_BASE_URL / GEOCODING_URL | 天气主源 Open-Meteo | 官方地址，无需 Key |
| IP_API_URL | IP 定位兜底 | `http://ip-api.com/json` |
| HOTLIST_API_URL | 热榜主源 | `https://api.uapis.cn/hotlist` |
| HOTLIST_FALLBACK_API_URL | 热榜备选 | `https://60s.viki.moe/v2/60s` |
| HOTLIST_CACHE_SECONDS | 热榜进程内缓存时长（秒） | `300` |
| SWAGGER_ENABLED | 是否启用 Swagger 文档 | `true` |
| HOST / PORT / FLASK_DEBUG | 服务器监听配置 | `0.0.0.0` / `5000` / `false` |

### 前端（my-work-vue/.env）

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| VITE_API_BASE_URL | 后端 API 基础地址 | `/api`（开发环境走 Vite 代理） |

> `.env` 含密钥与路径信息，已被 `.gitignore` 忽略；仅 `.env.example` 模板入库。

## 自动化测试

后端 `scripts/test_api.py` 提供接口全量回归：**226 项断言全部通过**，覆盖仪表盘（真实数据校验）、任务、课程表、学期设置、课程、学生名单（导入/模板）、作业（发布/停止/提交情况/打包）、提交（查重/名单校验/过期）、知识库（文件夹层级/上传/预览/批量下载/级联删除）、分享（创建/404/410/分页/删除）等全部分组。

```bash
cd 代码/my-work
venv/Scripts/python.exe scripts/test_api.py
```

## 构建与部署

### 前端构建

```bash
cd 代码/my-work-vue
npm run build          # 产物输出到 dist/
```

构建产物 `dist/` 为纯静态文件（含 favicon.ico），可交给任意静态服务器托管；API 请求需指向后端地址。

### 部署拓扑

- 后端：家用电脑常开，`python run.py` 监听 `0.0.0.0:5000`。
- 前端：开发态 `npm run dev`（5173）；生产态托管 `dist/`。
- 外网：frp 内网穿透将公网域名/端口映射到本机；浏览器访问穿透地址即达前端页面，`/api` 经代理或反向代理转发到 5000。
- 开发态经穿透域名访问 5173 时，Vite 已配置 `server.allowedHosts: true` 放行任意 Host，不会被拦截。

## 常见问题

- **Vite dev server 报 "Blocked request"**：Vite 5+ 默认只放行 localhost，穿透域名访问需在 `vite.config.js` 配置 `server.allowedHosts`（本项目已设为 `true` 放行所有 Host；注意 Vite 6 只认布尔 `true`，`'all'`/`'*'` 字符串不生效）。
- **项目位于 OneDrive 目录时的构建问题**：Vite 构建清理旧产物（emptyOutDir）与删除数据库临时文件可能被安全删除机制拦截而失败。处理方式：`vite.config.js` 中 `emptyOutDir: false` + `cacheDir` 指向当前用户可写的非同步目录（`${process.env.LOCALAPPDATA}/vite-mywork-cache`，也可用 `VITE_CACHE_DIR` 环境变量覆盖）；清理 `dist/` 用 PowerShell 自底向上删除。
- **favicon 不显示**：Vite 只服务 `public/` 目录下的静态文件，favicon 需放在 `public/favicon.ico` 并在 `index.html` 声明 `<link rel="icon" href="/favicon.ico">`。
- **上传大文件失败**：检查后端 `.env` 中 `MAX_CONTENT_LENGTH_*` 上限与 frp/反向代理的超时与体积配置。
- **热榜 / 天气不显示**：第三方在线 API 免费层可能按 IP 限流，卡片会优雅降级（显示获取失败占位），不影响其他功能。

## 开源许可

本项目采用 **MIT License** 开源，详见 [LICENSE](./LICENSE)。

```
MIT License
Copyright (c) 2026 tangdou0310
```

允许自由使用、修改、分发与商用，需保留原始版权声明与许可文本；项目按「现状」提供，作者不对使用后果承担责任。