# winform-plan-list

**Repository Path**: xianyouhu/winform-plan-list

## Basic Information

- **Project Name**: winform-plan-list
- **Description**: winform-plan-list
单机版
日常工作计划清单：建立计划、修改计划、导出计划等。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WinformDemos · 计划清单

基于 **.NET Framework 4.8 + WinForms + SQLite** 的本地计划清单演示项目，支持企业级状态流转、时间字段管理、列表状态着色，以及按时间段导出工作总结（TXT / Excel）。

---

## 功能概览

| 能力 | 说明 |
|------|------|
| 计划 CRUD | 新增、修改、删除、标记完成 |
| 企业级状态 | 草稿 → 待办 → 进行中 → 挂起 → 待审核 → 已完成 / 已驳回 / 已取消 |
| 时间字段 | 创建时间、修改时间、计划完成时间、已完成时间 |
| 列表着色 | 不同状态行使用不同背景色，便于一眼识别 |
| 状态筛选 | 顶部可按状态过滤列表 |
| 工作总结导出 | 自选时间段；格式可选 **TXT（默认）** 或 **Excel（状态着色 + 自动列宽）** |

### 状态与颜色

| 状态 | 含义 | 列表/Excel 背景色倾向 |
|------|------|------------------------|
| 草稿 | 已录入，未正式发布 | 浅灰 |
| 待办 | 已立项，未开始 | 浅蓝 |
| 进行中 | 执行中 | 浅黄 |
| 挂起 | 暂停，可恢复 | 浅橙 |
| 待审核 | 待验收/审批 | 浅紫 |
| 已完成 | 关闭（终态） | 浅绿 |
| 已驳回 | 审核未通过 | 浅红 |
| 已取消 | 终止（终态） | 深灰 |

新建计划默认状态为 **草稿**。状态变为「已完成」时自动写入 **已完成时间**。

---

## 技术栈

- 语言 / UI：C#、Windows Forms
- 运行时：.NET Framework 4.8
- 数据库：SQLite（`System.Data.SQLite.Core 1.0.118`）
- 数据文件：程序运行目录下的 `plans.db`（首次启动自动建库建表，旧库自动补列）

---

## 程序运行所需环境

### 最终用户（只运行 exe）

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 10 / Windows 11（x86 或 x64） |
| 运行时 | **.NET Framework 4.8**（多数 Win10/11 已自带；未安装可到微软官网下载 Runtime） |
| Office | 非必须；导出 Excel（`.xls`）建议用 Microsoft Excel / WPS 打开 |
| 权限 | 对程序所在目录有读写权限（用于生成 `plans.db` 与导出文件） |
| 网络 | 不需要（纯本地单机） |

> 说明：本程序是 **.NET Framework** 桌面应用，不是 .NET Core / .NET 6+ 的 self-contained 发布，因此目标机器需要已安装 .NET Framework 4.8。

### 开发者（编译 / 调试）

| 项目 | 要求 |
|------|------|
| IDE | Visual Studio 2019 / 2022（推荐安装「.NET 桌面开发」工作负载） |
| SDK / 工具 | MSBuild（随 VS 安装）、NuGet |
| 目标框架 | .NET Framework 4.8 Developer Pack（若 VS 未带齐） |

---

## 从 Gitee 克隆后必做（重要）

仓库**故意不上传** `packages/`、`bin/`、`obj/`（见 `.gitignore`），因此克隆后必须先还原 NuGet，再编译，否则会出现：

> 无法加载 DLL“SQLite.Interop.dll”: 找不到指定的模块

这不是源码没传全，而是 **SQLite 原生库需通过 NuGet 还原后，编译时复制到 `bin\Debug\x86` 与 `bin\Debug\x64`**。

### 一键还原

在项目根目录（含 `WinformDemos.csproj`）执行：

```powershell
.\restore-packages.ps1
```

然后用 Visual Studio **重新生成**，或：

```powershell
msbuild WinformDemos.csproj /p:Configuration=Debug /t:Rebuild
.\bin\Debug\WinformDemos.exe
```

确认下列文件存在后再运行：

- `bin\Debug\System.Data.SQLite.dll`
- `bin\Debug\x86\SQLite.Interop.dll`
- `bin\Debug\x64\SQLite.Interop.dll`

---

## 启动方式（开发调试）

### 方式一：Visual Studio（推荐）

1. 先执行上一节的 `.\restore-packages.ps1`（仅首次或 packages 缺失时）
2. 打开解决方案 `WinformDemos.sln`
3. 确认启动项目为 `WinformDemos`
4. 配置选 **Debug**，按 **F5**（调试）或 **Ctrl+F5**（无调试运行）

### 方式二：命令行 MSBuild

在项目根目录（含 `WinformDemos.csproj`）执行：

```powershell
# 还原依赖（推荐用脚本）
.\restore-packages.ps1

# 或手动：
# .\nuget.exe install System.Data.SQLite.Core -Version 1.0.118 -OutputDirectory packages -Framework net48

# 编译 Debug
msbuild WinformDemos.csproj /p:Configuration=Debug /t:Rebuild

# 启动
.\bin\Debug\WinformDemos.exe
```

> 若系统找不到 `msbuild`，可使用「Developer PowerShell for VS」或 VS 安装目录下的 `MSBuild.exe` 全路径。

### 主界面操作简述

1. 右侧填写标题、说明、优先级、状态、计划完成时间  
2. **新增计划** / **保存修改** / **删除** / **标记完成**  
3. 顶部按状态筛选，或点击 **刷新**  
4. **导出工作总结**：选择时间段与格式（TXT / Excel）后保存  

---

## 打包 exe（发布给他人使用）

本项目为经典 WinForms（非 SDK 风格），**发布 = Release 编译 + 拷贝输出目录必要文件**。

### 1. 编译 Release

```powershell
msbuild WinformDemos.csproj /p:Configuration=Release /t:Rebuild
```

或在 Visual Studio：**生成 → 配置管理器** 选 Release，再 **生成 → 重新生成解决方案**。

输出目录：

```text
bin\Release\
```

### 2. 需要一起分发的文件（最小运行包）

请将整个 `bin\Release\` 中下列内容打成 zip / 拷贝到目标机同一文件夹：

| 文件 / 目录 | 是否必须 | 说明 |
|-------------|----------|------|
| `WinformDemos.exe` | 必须 | 主程序 |
| `WinformDemos.exe.config` | 必须 | 运行时配置（.NET 4.8） |
| `System.Data.SQLite.dll` | 必须 | SQLite 托管程序集 |
| `x86\SQLite.Interop.dll` | 必须 | 32 位原生互操作库 |
| `x64\SQLite.Interop.dll` | 必须 | 64 位原生互操作库 |
| `System.Data.SQLite.xml` | 可选 | 文档，可删 |
| `*.pdb` | 可选 | 调试符号，发布可删 |

**不要**把开发机上的 `plans.db` 一并发给用户（除非有意带演示数据）。用户首次运行会在 exe 同目录自动创建空库。

### 3. 简易打包示例（PowerShell）

```powershell
msbuild WinformDemos.csproj /p:Configuration=Release /t:Rebuild

$out = ".\dist\PlanList"
Remove-Item -Recurse -Force $out -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force -Path $out | Out-Null

Copy-Item ".\bin\Release\WinformDemos.exe" $out
Copy-Item ".\bin\Release\WinformDemos.exe.config" $out
Copy-Item ".\bin\Release\System.Data.SQLite.dll" $out
Copy-Item -Recurse ".\bin\Release\x86" $out
Copy-Item -Recurse ".\bin\Release\x64" $out

Compress-Archive -Path "$out\*" -DestinationPath ".\dist\PlanList_Release.zip" -Force
```

用户解压后双击 `WinformDemos.exe` 即可（目标机需已安装 .NET Framework 4.8）。

### 4. 常见运行问题

| 现象 | 处理 |
|------|------|
| 提示缺少 .NET Framework 4.8 | 安装 [.NET Framework 4.8 Runtime](https://dotnet.microsoft.com/download/dotnet-framework/net48) |
| 启动报 SQLite / DllNotFound | 确认 `x86`、`x64` 文件夹与 exe 同级，勿只拷贝 exe |
| 无法写库 / 闪退 | 勿放在无写权限目录；或对目录授予当前用户写入权限 |
| Excel 打开提示格式不符 | 选「是」继续打开即可（导出为 Excel 可识别的 HTML `.xls`） |

---

## 工作总结导出

- **统计规则**：创建时间、修改时间、已完成时间 **任一** 落入所选区间的计划都会纳入  
- **TXT**：纯文本总结（概况 + 分状态明细）  
- **Excel**：单工作表，含三块内容：  
  1. 概况统计（各状态数量、完成率，行着色）  
  2. 计划明细（完整字段，行着色，列宽按内容自动估算）  
  3. 颜色图例  

默认导出格式为 **TXT**。

---

## 项目结构

```
WinformDemos/
├── Program.cs                 # 程序入口，启动计划清单窗体
├── Forms/
│   ├── PlanListForm.*         # 主界面：列表、编辑、筛选、导出入口
│   └── WorkSummaryExportForm.*# 工作总结导出（时间段 + 格式）
├── Models/
│   ├── PlanItemDto.cs         # 计划 DTO（字段均有备注）
│   ├── PlanStatus.cs          # 状态枚举
│   ├── PlanStatusHelper.cs    # 状态显示名、筛选项、行颜色
│   └── WorkSummaryExportFormat.cs  # 导出格式：TXT / Excel
├── Data/
│   ├── SqliteDbHelper.cs      # 连接串、建库建表、列迁移
│   └── PlanRepository.cs      # 增删改查、按状态/时间段查询
├── Services/
│   └── WorkSummaryExporter.cs # TXT / Excel 总结生成
├── Resources/
│   └── app.ico                # 应用图标
├── packages.config            # NuGet 依赖
├── .gitignore                 # Git 上传忽略规则
└── .cursor/rules/
    └── code-comments.mdc      # 代码注释规范（Cursor 规则）
```

---

## 数据模型（PlanItems）

| 字段 | 说明 |
|------|------|
| Id | 主键，自增 |
| Title | 标题（必填） |
| Description | 说明（可空） |
| Priority | 优先级：1 低 / 2 中 / 3 高 |
| Status | 状态枚举整型值 |
| CreatedAt | 创建时间 |
| UpdatedAt | 最后修改时间 |
| PlannedFinishAt | 计划完成时间（可空） |
| CompletedAt | 实际完成时间（可空） |

数据库路径示例：`bin\Debug\plans.db` 或发布目录下的 `plans.db`。

---

## Git 上传说明

仓库已提供 `.gitignore`（WinForms / .NET Framework 常用忽略项），主要忽略：

- `bin/`、`obj/`、`.vs/` 等编译与 IDE 缓存  
- `packages/`（克隆后可用 nuget 还原）  
- 本地 `plans.db` 等运行数据  

上传前建议确认未误提交用户数据库与个人配置。

依赖还原：

```powershell
.\nuget.exe install System.Data.SQLite.Core -Version 1.0.118 -OutputDirectory packages -Framework net48
```

---

## 编码规范

项目约定：**类、方法、属性/字段、DTO、关键业务分支均需中文注释**，见 `.cursor/rules/code-comments.mdc`。

---

## 说明与限制

- 本项目为本地单机演示，无登录、无多用户协作  
- Excel 导出为 HTML 表格格式的 `.xls`，用 Excel 打开即可；列宽与状态色已内置，一般无需再手动「最适合的列宽」  
- `Form1` 为模板窗体，主程序已切换为 `PlanListForm`  

---

## 后续可扩展方向

- 状态流转校验（如已取消不可改回进行中）  
- 状态变更日志 / 操作人  
- 责任人、分类、附件  
- 真正的 `.xlsx`（如 ClosedXML / EPPlus）与打印模板  
- 安装包（如 Inno Setup / MSIX）一键安装运行时检测  

---

## 应用图标

- 资源文件：`Resources/app.ico`（由清单/勾选风格图标生成）
- 已配置为 **ApplicationIcon**：影响 exe 文件图标与任务栏图标
- 主窗体 / 导出窗体启动时从 exe 提取同一图标，用于窗口左上角

更换图标时：替换 `Resources/app.ico` 后重新编译即可。

---

## License

仅供学习与演示使用。