部门事项周报管理系统

一个基于 Vue 3 + Ant Design Vue + FastAPI + SQLite 的部门事项管理系统，覆盖事项全生命周期、组织结构管理、周报与问题台账、可视化看板与甘特图。

---

1. 项目特性

• 前后端一体化：前端使用 Vite + Vue3，后端使用 FastAPI，本地开发开箱即用。
• 组织结构管理：支持 部门 -> 中心 -> 小组 多级结构维护。
• 事项闭环管理：事项增删改查、详情编辑、里程碑维护、甘特图区间展示。
• 里程碑双日期模型：支持 机会开始日期(startDate) + 计划结束日期(planEndDate)，并兼容旧 date 字段。
• 多业务模块：分类、周报、重点事项、问题台账、人员、系统设置等完整页面。
• 本地持久化：SQLite 存储，适合小规模团队/内部管理场景。

---

2. 功能模块

2.1 登录与门户

• 登录页（演示模式：账号存在即可登录，密码未做真实校验）
• 大屏看板 Board
• 概览报表 Dashboard

2.2 事项管理

• 事项列表筛选、创建、编辑、删除
• 事项详情页（独立路由 /items/:id）
• 里程碑维护（支持多条）
• 甘特图区间可视化（事项与里程碑都支持开始/结束日期）

2.3 组织与人员

• 组织结构管理：部门、中心、小组
• 部门角色字段：总经理、副总（可多个）、助理（可多个）
• 中心角色字段：主管
• 小组角色字段：组长
• 人员管理：部门/中心/小组/角色联动

2.4 业务台账

• 事项分类管理
• 周报管理
• 重点跟踪事项
• 生产问题台账
• 系统设置（系统标题与 Logo）

---

3. 技术栈

前端

• Vue 3.4
• Vue Router 4.2
• Pinia 2.1
• Ant Design Vue 4.2
• ECharts 5.4
• Axios 1.6
• Day.js 1.11
• Vite 5

后端

• Python
• FastAPI 0.109
• SQLAlchemy 2.0
• SQLite
• Uvicorn 0.27
• Pydantic 2

---

4. 目录结构

.
├── src
│   ├── api                 # 前端 API 封装
│   ├── layout              # 布局组件
│   ├── router              # 路由配置
│   ├── stores              # Pinia 状态
│   └── views               # 页面视图
│       ├── Login.vue
│       ├── Board.vue
│       ├── Dashboard.vue
│       ├── Items.vue
│       ├── ItemDetail.vue
│       ├── Categories.vue
│       ├── Weekly.vue
│       ├── KeyItems.vue
│       ├── IssueLog.vue
│       ├── Users.vue
│       ├── OrgStructure.vue
│       ├── Permissions.vue
│       └── Settings.vue
├── backend
│   ├── run.py              # 启动后端服务
│   ├── requirements.txt
│   ├── data.db             # SQLite 数据库（运行后生成）
│   └── app
│       ├── main.py         # FastAPI 入口
│       ├── config.py       # 配置（DB/CORS）
│       ├── database.py
│       ├── models.py
│       ├── schemas.py
│       ├── crud.py
│       ├── init_db.py      # 建表/迁移/种子数据
│       └── routers         # 各模块 API
└── vite.config.js

---

5. 环境要求

• Node.js >= 18
• npm >= 9
• Python >= 3.10（建议 3.11/3.12）

---

6. 快速开始

建议开两个终端：一个前端、一个后端。

6.0 复制环境变量模板

Windows PowerShell：

Copy-Item ".env.example" ".env"
Copy-Item "backend/.env.example" "backend/.env"

macOS / Linux：

cp .env.example .env
cp backend/.env.example backend/.env

6.1 启动后端

cd backend
pip install -r requirements.txt
python app/init_db.py
python run.py

后端默认地址：http://127.0.0.1:8000
在线文档：http://127.0.0.1:8000/docs

6.2 启动前端

npm install
npm run dev

前端默认地址：http://localhost:5173

6.3 容器部署（Docker Compose）

适用于本地一键拉起前后端生产镜像（前端 Nginx 静态站点 + 后端 FastAPI）。

1. 复制容器环境变量：

Windows PowerShell：

Copy-Item ".env.docker.example" ".env"

macOS / Linux：

cp .env.docker.example .env

2. 构建并启动：

docker compose up -d --build

3. 查看状态：

docker compose ps

4. 停止并删除容器：

docker compose down

默认访问地址：

• 前端：http://localhost:5173
• 后端文档：http://localhost:8000/docs

6.4 容器目录与持久化

• 前端镜像：根目录 Dockerfile（Node 构建 + Nginx 运行）
• 后端镜像：backend/Dockerfile
• Nginx 反向代理配置：deploy/nginx/default.conf
• 编排文件：docker-compose.yml
• SQLite 数据卷：backend_data（挂载到容器 /data）

---

7. 配置说明

7.1 前端 API 地址

前端请求基于 src/api/index.js：

• 默认走相对路径（如 /api/items）
• 开发环境通过 vite.config.js 代理到后端（由 VITE_API_PROXY_TARGET 控制）
• 也可通过环境变量设置：

VITE_API_URL=http://127.0.0.1:8000

前端端口可配置：

VITE_PORT=5173

代理目标可配置：

VITE_API_PROXY_TARGET=http://127.0.0.1:8000

7.2 后端配置

backend/app/config.py 支持通过 .env 覆盖：

• DATABASE_URL：SQLite 连接（默认指向 backend/data.db）
• CORS_ORIGINS：允许的前端地址
• SECRET_KEY：开发密钥（生产请务必替换）
• BACKEND_HOST：后端监听地址（run.py 读取）
• BACKEND_PORT：后端监听端口（run.py 读取）
• FRONTEND_PORT：默认 CORS 端口（未显式配置 CORS_ORIGINS 时生效）

推荐配置示例：

BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
FRONTEND_PORT=5173
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

7.3 改端口示例

如果你要改成前端 3000、后端 9000：

根目录 .env：

VITE_PORT=3000
VITE_API_PROXY_TARGET=http://127.0.0.1:9000

backend/.env：

BACKEND_PORT=9000
FRONTEND_PORT=3000
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

改完后请重启前后端服务。

7.4 容器环境变量（.env.docker.example）

• FRONTEND_PUBLIC_PORT：宿主机映射到前端容器 80 端口（默认 5173）
• BACKEND_PUBLIC_PORT：宿主机映射到后端容器 8000 端口（默认 8000）
• DATABASE_URL：容器内数据库地址（默认 sqlite:////data/data.db）
• CORS_ORIGINS：后端允许的来源（按你映射后的前端端口调整）

---

8. 数据库初始化与迁移说明

项目使用 backend/app/init_db.py 统一做以下工作：

• Base.metadata.create_all 创建表
• 自动补齐老库字段（例如：
  • users.center
  • users.role
  • milestones.start_date
  • milestones.plan_end_date）
• 自动写入基础种子数据（分类、组织结构、示例事项等）

当你更新了模型字段后，优先执行：

cd backend
python app/init_db.py

---

9. 常用接口（节选）

统一前缀：/api

• POST /login
• GET/POST/PUT/DELETE /categories
• GET/POST/PUT/DELETE /items
• GET /dashboard/items
• GET/POST/PUT/DELETE /users
• GET /org/tree
• GET/POST/PUT/DELETE /departments
• GET/POST/PUT/DELETE /centers
• GET/POST/PUT/DELETE /groups
• GET/POST/PUT /weekly-reports
• GET/POST/PUT/DELETE /key-items
• GET/POST/PUT/DELETE /issues
• GET/PUT /settings

---

10. 里程碑字段约定

里程碑对象建议字段：

{
  "name": "接口设计",
  "startDate": "2026-03-06",
  "planEndDate": "2026-03-15",
  "status": "进行中",
  "description": ""
}

兼容逻辑：

• 后端读取时会兼容旧 date 字段
• 新增/编辑建议统一使用 startDate + planEndDate

---

11. 常见问题

Q1：页面刷新提示 Request failed with status code 500

常见原因：数据库字段未迁移（例如缺少 milestones.start_date）。
解决：

cd backend
python app/init_db.py

然后刷新页面。

Q2：前端能打开但没有数据

请确认：

1. 后端已启动（http://127.0.0.1:8000/docs 可访问）
2. 前端代理指向正确（vite.config.js 中 /api 代理）
3. 数据库已初始化（已执行 python app/init_db.py）

Q3：登录失败“用户不存在”

登录逻辑会按 username 查用户，请先确认数据库中存在该用户（初始化脚本会写入示例用户）。

---

12. 生产部署建议

• 使用 gunicorn/uvicorn workers 部署后端
• 将 SQLite 替换为 MySQL/PostgreSQL（中大型场景）
• 接入正式鉴权（JWT + 密码哈希校验 + 权限控制）
• 配置 Nginx 反向代理与静态资源缓存
• 增加日志、监控、备份与迁移机制（Alembic）

---

13. License

仅用于学习与内部演示，请根据团队规范补充正式 License。