# surreal_vbcd

**Repository Path**: vibe-coding-2026-3/surreal_vbcd

## Basic Information

- **Project Name**: surreal_vbcd
- **Description**: surreal's repository for zhongguancun academy vibe coding 2026 course
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# surreal_vbcd

🌟 **中关村学院 (Zhongguancun Academy) Vibe Coding 2026** 课程学习仓库。

> User: Surreal

## 📁 项目目录

### 1. Coursework 4.2: 🥬 zgc (诸葛菜) 个人效能系统

**“从菜鸟 (Noob) 到人生诸葛 (Master Strategist)”**

一款融合了 **中国传统智慧（诸葛亮谋略）** 与 **现代极客精神（赛博中关村）** 的极简任务管理工具。采用企业级 **Vue 3 + FastAPI** 前后端分离架构。

#### ⚔️ 核心特性
- **架构大迁徙 (Frontend-Backend Decoupling)**：[v2.0 新增] 彻底抛弃 Streamlit，重构为 **Vue 3 (基于 Vite + Tailwind CSS v4)** 与 **FastAPI** 的现代化前后端分离架构，响应速度与丝滑度大幅提升。
- **辕门核验 (User Authentication & Security)**：完整的独立用户 JWT 注册与登录体系。使用 PBKDF2 HMAC 加盐算法进行高强度密码哈希，并支持“静默哈希升级”平滑过渡历史老数据。
- **兵权绑定 (Multi-tenant Isolation)**：数据库实现彻底的多租户数据隔离，所有的日常军务均与专属主公 (`user_id`) 强绑定，配合前端路由守卫保障数据绝对私密。
- **架构加固 (Architecture & DB Context)**：全面采用 Python 上下文管理器 (`@contextmanager db_transaction`) 闭环数据库事务，自动处理 Commit/Rollback/Close，彻底杜绝连接泄漏。拥有多达 36 项严格的 Pytest 单元测试集背书。
- **剑阁粮仓 (SQLite 持久化)**：使用纯正 SQLite 数据库实现数据长久留存，抛弃一切临时跨域存储会话。
- **搜寻与编排 (Search & Sort)**：支持关键字模糊检索（搜寻锦囊）与按时间排序（编排阵型）的高级管理功能。
- **中军帐 (Core Logic)**：核心业务逻辑与 RESTful API 路由解耦，运筹帷幄之中，决胜千里之外。
- **沙盘推演 (Unit Tests)**：基于 TestClient 和 Pytest 的完整接口与单元测试覆盖，针对 SQLite 内存数据库专门优化，确保军令如山，万无一失。
- **军情总览 (Stats Dashboard)**：通过动态加载 Echarts 图表数据，实时呈现千军万马的新建及变更态势，并精准聚合统计不同兵种（自定义分类）上的兵力比重折线。
- **运筹帷幄 (Edit & Update)**：支持对已有任务的名称、分类、优先级随时进行修改、更新，与极致炫酷的 Neon 编辑模态框交互。
- **神机大观 (View System Hub)**: [全新重构] 核心战术视图大升级！引入龙骧矩阵 (Matrix View，支持四象限拖拽)、列阵视图 (List View，支持高效阅览) 与天时历书 (Calendar View，基于 FullCalendar 实现全局排兵布阵) 的无缝切换。同时将原本孤立的“锦囊录入”收拢合并为弹窗，打造了极致流畅的 Single Page Hub 体验。
- **军令审查 (Validation)**：严谨的军令状机制。拒绝空谈（空标题拦截），规避语焉不详（过短警告）与冗长繁琐（过长警告）。
- **草船借箭 (Quick Add)**：高效丝滑的任务录入体验。
- **兵种校阅 (Category CRUD)**：将分类功能实体化，告别旧有的固定选项，新增无限量自定义分类管理。支持直接通过前端进行分类名称与色彩（十六进制 Vibe Color）的创建和编辑，并且实现了底层级联引用保护机制。
- **隆中对策 (Eisenhower Matrix)**：支持**动态拖拽交互**的四象限优先级矩阵看板（破釜沉舟、隆中对策、权宜之计、食之无味）。配合最近新增的“状态视图隔离（Pending/Completed/All）”，提供极具战术针对性的面板总览。
- **天时系统 (Time & Schedule)**：引入任务截止日期 (`due_date`) 和多级烽火提醒 (`reminders`)。内置“自动督军”机制（任务自动升级），在临界时间前自动提升紧急度。
- **多维度沙盘纵览 (Dashboard & Overviews)**：前端集成 `dayjs` 库，在锦囊矩阵支持“今日战况”、“本周演武”、“全军全景”以及“错失战机（逾期）”等多维度动态日程概览。
- **军情周报 (Weekly Report)**：[全新特性] 自动统计并生成上周的综合战报，涵盖新增兵力（新建任务）、歼敌数量（完成任务）、武侯时计专注回数及总时长，并按兵种（分类）精准剖析各营战力分布，供主公全方位复盘上周得失。
- **武侯时计 (Zhuge Pomodoro Timer)**：[全新特性] 内置沉浸式番茄钟模块。支持“研兵 (Focus)”与“休整 (Break)”双相态智能流转与时长自定义。具备完善的时差断点续传（鸣金收兵与重振旗鼓），页面刷新不丢失倒计时状态，并自动统计主公的专注回数（`focus_count`），结合右侧动态优先级环形编队（图表）带来绝佳的效能管理体验。

#### 🛠️ 技术栈
- **前端 Frontend**: Vue 3, Vite, Tailwind CSS v4, Pinia, Vue Router, VueDraggable, Echarts, dayjs, FullCalendar
- **后端 Backend**: Python 3.13, FastAPI, Pydantic, PyJWT
- **数据库 Database**: SQLite 3
- **测试 Testing**: Pytest, FastAPI TestClient (已覆盖 42 项核心测试集, 100% passed)
- **视觉 Vibe**: Dark Mode + Neon Accents (Cyber Zhongguancun)

#### 🚀 快速开始

```bash
# 1. 克隆代码并在终端进入项目目录
git clone <your-repo>
cd surreal_vbcd

# 2. 配置后端环境 (需安装 Miniconda/Anaconda)
conda create -n coursework_env python=3.13 -y
conda activate coursework_env
pip install fastapi uvicorn pydantic pyjwt pytest httpx

# 3. 启动后端 API 服务
cd zgc_app/backend
uvicorn main:app --reload --port 8002
# 后端 API 默认运行在 http://localhost:8002

# 4. 配置并启动前端环境 (需打开新终端，且已安装 Node.js)
cd zgc_app/frontend
npm install
# 安装时间处理与日历视图依赖 dayjs & fullcalendar
npm install dayjs @fullcalendar/vue3 @fullcalendar/daygrid @fullcalendar/timegrid @fullcalendar/interaction
npm run dev
# 前端默认运行在 http://localhost:5173

# 5. 执行演练 (Run API and DB Tests)
# 确保在 coursework_env 环境与项目根目录下
conda run -n coursework_env pytest zgc_app/tests
```

## 📜 许可证

MIT License