refactor: 移除不再使用的配置文件与代码，优化用户界面

- 删除 config.json 和 requirements.txt 文件，移除 Python 版相关代码，简化项目结构。 - 更新 README.md，调整工具说明，强调仅保留 C# WinForms 版本。 - 在 MainForm.cs 中添加输入框的占位提示，提升用户体验。 - 更新 .gitignore，添加 debug.log 文件以记录运行时日志。 - 移除与 Python 版相关的示例 CSV 文件，确保数据源一致性。
2026-11-01 21:44:31 +08:00
parent d055b415fa
commit 8a6f9d55bc
14 changed files with 297 additions and 670 deletions
@@ -12,33 +12,25 @@ TFS 2013 工作项批量导入工具集，用于把 Excel/CSV 里的工时台账
 | 迭代 | `2026年Sprint\2026年Sprint10` |
 | 认证 | 域账号 NTLM（内网直连，不走代理） |

-## 两套工具，先用哪个
+## 工具一览

-| | [TfsExcelImporter](TfsExcelImporter)（C# WinForms） | [tfs_import.py](tfs_import.py)（Python CLI） |
-| --- | --- | --- |
-| 通信协议 | TFS Client OM（VS/Team Explorer 同款内部 SOAP） | REST `/_apis/wit/*` |
-| 适用 | **本环境可用**。该 TFS 2013 实例只有 `/_apis/projects` 通，`wit/fields`、`wit/classificationnodes`、`wit/wiql` 全部 404 | 服务器开放了 wit REST 路由时使用 |
-| 数据源 | `.xlsx`（默认模板随程序发布） | `data/work_items.csv`（GBK/UTF-8 均可，需自备） |
-| 界面 | 图形界面，预览后导入 | 命令行，`--dry-run` 先校验 |
+仓库只有一套工具：[TfsExcelImporter](TfsExcelImporter)（C# WinForms 桌面版），数据源为 `.xlsx`（默认模板随程序发布），图形界面预览后导入。

-Python 版在本环境会因 REST 路由 404 而失败，保留用于其它 TFS 实例或接口可用时的批量脚本化导入。
+通信走 TFS Client OM（VS/Team Explorer 同款内部 SOAP）：该 TFS 2013 实例只有 `/_apis/projects` 通，`wit/fields`、`wit/classificationnodes`、`wit/wiql` 全部 404，REST 路线走不通。原先另有一套 Python CLI（REST `/_apis/wit/*`）实现，因上述限制无法在本环境工作，已移除。

 ## 目录结构

 ```
 TFSImport/
-├── tfs_import.py                  # Python 命令行导入器（REST）
-├── config.json                    # Python 版配置
-├── requirements.txt               # requests / requests-ntlm
 ├── data/
-│   └── work_items.example.csv     # 列结构与示例行（UTF-8 BOM）；真实台账不入库
+│   └── work_items.csv             # 本地工时台账（含人员/项目，不入库）
 ├── templates/
 │   └── TFS导入模板.xlsx            # 默认模板：构建时嵌入 exe，「导出Excel模板」原样导出
 ├── tools/
 │   ├── make_icon.py               # 生成 app.ico（9 个尺寸帧，纯标准库 SDF 栅格化 + 手写 PNG/ICO）
 │   ├── pe_icon.py                 # 解析 exe 的 PE 图标资源，导出某帧 PNG（换图标后核对用）
 │   └── win_screenshot.py          # 冒烟截图：拉起 exe、PrintWindow 抓窗、导出标题栏图标（ctypes）
-└── TfsExcelImporter/              # C# WinForms 桌面版（主用）
+└── TfsExcelImporter/              # C# WinForms 桌面版
    ├── TfsExcelImporter.csproj    # net48 + ClosedXML + TFS ExtendedClient 14.*
    ├── FodyWeavers.xml            # Costura 单文件打包配置（便携版）
    ├── NativeLibraryLoader.cs     # 释放并预加载内嵌的 TFS native DLL
@@ -56,7 +48,7 @@ TFSImport/

 ## 快速开始

-### C# 桌面版（主用）
+### 桌面版

 ```powershell
 dotnet build TfsExcelImporter.sln -c Release
@@ -75,8 +67,8 @@ python tools/win_screenshot.py TfsExcelImporter\bin\Release\net48\TfsExcelImport

 界面按 4 步排：顶部状态条常驻显示服务器/项目/类型与连接状态，四张卡片一次只展开一张（展开一张会把其它收成一行摘要），预览表格永远占满剩余高度。

-1. **步骤 1 连接**：填 URL、项目、工作项类型、认证方式与域账号，点「测试连接」——右上状态灯变绿即连通；内网保持「使用系统代理」**不勾选**。
-2. **步骤 2 选数据**：点「加载迭代列表」选目标迭代（也可手填完整路径）；点「导出 Excel 模板」拿默认模板，或「浏览...」选已有 `.xlsx`。需要挂父项时填「父 PBI Id」（默认全部挂同一个；Excel 里加 `PBI Id` 列可逐行指定不同父项）。
+1. **步骤 1 连接**：填 URL、项目、工作项类型与账号密码（认证固定 NTLM，用户名可写 `user` 或 `DOMAIN\user`），点「测试连接」——右上状态灯变绿即连通。
+2. **步骤 2 选数据**：点「加载迭代列表」选目标迭代（也可手填完整路径）；点「导出 Excel 模板」拿默认模板，或「浏览...」选已有 `.xlsx`。需要挂父项时填「父 PBI Id」（默认全部挂同一个；Excel 里加 `PBI Id` 列可逐行指定不同父项）；勾「跳过已存在标题」按「项目/类型/迭代 + 标题」去重。字段校验**不可绕过**，不合法时日志会直接告诉你改哪一列。
 3. **步骤 3 预览核对**：选完文件自动读表，表格里逐行核对；缺迭代/文件路径无效时红字直接标在对应输入框下方，不再弹框。
 4. **步骤 4 导入**：底部操作条点「开始导入 TFS」，进度条 + `n/m` + 成功/跳过/失败三个计数实时更新，日志抽屉逐行输出 `OK/SKIP/FAIL` 与工作项 ID；跑完点「打开报告 CSV」看逐行结果。
 5. 历史数据 Area 不对、或漏挂父项时，展开底部「高级工具」用「按迭代修 Area」「补挂父项」批量纠正；Area 路径也在这一栏里填（以前只能手改 config.json）。
@@ -105,39 +97,27 @@ copy TfsExcelImporter\bin\Release\net48\TfsExcelImporter.exe dist\

 前提：目标机需有 .NET Framework 4.8（Win10 1903+ / Win11 系统自带，一般无需额外安装）。`FodyWeavers.xml` 是 Costura 的打包配置，删掉它或用 `-p:FodyDisable=true` 构建即回到「exe + 一堆 DLL」的普通输出。

-### Python 版
-
-```powershell
-pip install -r requirements.txt
-python tfs_import.py --dry-run               # 只校验数据与字段映射，不写入
-python tfs_import.py --list-fields           # 列出服务器全部字段（显示名/引用名）
-python tfs_import.py                         # 正式导入
-python tfs_import.py --link-existing         # 已导入的项补挂父链接（不新建）
-python tfs_import.py --skip-existing-titles  # 跳过服务器已有的同标题项
-python tfs_import.py --input other.csv --limit 5
-```
-
-每次运行在 `data/import_report_<时间戳>.csv` 生成逐行结果报告（行号 / Title / 结果 / WorkItemId / 错误）。
-
 ## 配置说明

 桌面版的配置落在 exe 同目录的 `config.json`（界面改动后自动写回）；exe 目录不可写时回退到 `%AppData%\TfsExcelImporter\config.json`。

-配置的语义、留空字段如何解析见 [tfs_import.py:49](tfs_import.py#L49) 与 [Config.cs](TfsExcelImporter/Config.cs)，关键字段：
+配置的语义、留空字段如何解析见 [Config.cs](TfsExcelImporter/Config.cs)，关键字段：

 | 键 | 说明 |
 | --- | --- |
-| `tfs_url` / `project` / `work_item_type` | 目标集合、项目、工作项类型（`Task` 或 `Product Backlog Item`） |
-| `iteration_path` | 可只写 `2026年Sprint\2026年Sprint10`，程序自动补项目名前缀 |
-| `auth.mode` | `ntlm`（域账号，典型）/ `basic` / `default`（当前 Windows 凭据，仅桌面版） |
-| `field_refs` | 语义名 → 字段引用名；自定义字段留空时按 `resolve_fields_by_display_name` 的显示名在服务器字段表里查（支持前缀模糊匹配，如 `Completed` → `Completed Work`） |
-| `parent_title` / `parent_id` | 父工作项，二选一；按标题匹配不到会直接报错并提示改用 `parent_id` |
-| `bypass_rules` | 是否请求绕过字段校验规则；桌面版走 Client OM（14.x 无 `SaveFlags.BypassRules`），实际由服务器规则决定 |
-| `skip_existing_titles` | 同项目/同类型/同迭代下按标题去重 |
+| `TfsUrl` / `Project` / `WorkItemType` | 目标集合、项目、工作项类型（`Task` 或 `Product Backlog Item`） |
+| `IterationPath` | 可只写 `2026年Sprint\2026年Sprint10`，程序自动补项目名前缀 |
+| `AreaPath` | 区域路径；界面「高级工具」栏也可改 |
+| `Username` / `Password` | 认证固定 NTLM，用户名可写 `user` 或 `DOMAIN\user` |
+| `FinancialProjectRef` / `CompletedRef` / `LogDateRef` / `OriginalEstimateRef` | 自定义字段引用名；留空则按显示名在服务器字段表里查（支持前缀模糊匹配，如 `Completed` → `Completed Work`） |
+| `ParentPbiId` | 所有 Task 默认挂接的父 PBI Id；Excel 每行 `PBI Id` 列可覆盖 |
+| `SkipExistingTitles` | 同项目/同类型/同迭代下按标题去重 |
+| `DefaultState` | Excel `State` 列留空时的默认值 |
+| `LastExcelPath` | 上次选中的数据文件，界面回填用 |

 > 配置里含明文密码，请勿提交到共享仓库；`config.json` 保持空值，凭据本地填写。

-## Excel / CSV 列
+## Excel 列

 桌面版 Excel 模板 = 仓库里的 `templates\TFS导入模板.xlsx`，界面「导出Excel模板」直接复制它：

@@ -153,37 +133,24 @@ python tfs_import.py --input other.csv --limit 5

 系统日期列（`Created Date` / `Closed Date`）已从模板移除：`System.CreatedDate` 由服务器按导入时间填写，`Microsoft.VSTS.Common.ClosedDate` 不再写入、保持为空。

-Python 版仍读 `data/work_items.example.csv` 的旧列（含 `CreatedDate`、`ClosedDate`、`Notes`），未随模板调整。
-
-真实台账含人员与项目信息，不入库；本地准备数据文件：
-
-```powershell
-copy data\work_items.example.csv data\work_items.csv   # Python 版默认读这个路径，已在 .gitignore 里
-```
+真实台账含人员与项目信息，不入库，放在 `data\work_items.csv`（已在 `.gitignore` 里）。

 - 表头按名匹配，顺序不限，`AssignedTo` / `Assigned To` 等价；缺列按模板顺序兜底，但该列已被别的表头占用时不套用位置（旧版模板文件不会串列）。
- 空 `Title` 的行直接跳过；`State` 为空时用 `default_state`；未识别的列（如 `Group`）忽略。
+- 空 `Title` 的行直接跳过；`State` 为空时用 `DefaultState`；未识别的列（如 `Group`）忽略。
 - 日期支持 `yyyy-MM-dd[ / ][ HH:mm[:ss]]` 等格式，Excel 日期序列号（如 `46300`）会被还原成日期。
- CSV 从 Excel 另存时注意编码，脚本按 `utf-8-sig` → `gbk` 依次尝试。

 ## 环境坑点

 这些是实测结论，改代码前先看：

 - **wit REST 路由全 404**：TFS 2013 RTM/低 Update 不带 `/_apis/wit/*`，`Classification.asmx?WSDL` 也被禁 → 桌面版整体走 Client OM（NuGet `Microsoft.TeamFoundationServer.ExtendedClient` 钉 `14.*`，对应 VS2015 客户端代际；15.x 不兼容 TFS 2013）。
- **502 Bad Gateway**：TFS OM 内部用 `HttpWebRequest`，默认跟随 IE 系统代理，代理会拦内网 TFS。桌面版默认把 `WebRequest.DefaultWebProxy` 置空直连；确实要走代理时勾「使用系统代理」并带上 Windows 凭据过代理认证。
+- **502 Bad Gateway**：TFS OM 内部用 `HttpWebRequest`，默认跟随 IE 系统代理，代理会拦内网 TFS。桌面版固定把 `WebRequest.DefaultWebProxy` 置空强制直连，界面不提供代理开关（本机若只能经代理上网，程序会直连失败）。
 - **TF400276 / 关闭状态只读**：改已关闭工作项的 Area 会被拒；`FixAreaAsync` 走「重新打开 → 改 Area → 还原状态」的状态循环，中途失败回滚状态。
 - **`System.CreatedDate` 写不进去**：OM 14.x 没有 `SaveFlags.BypassRules`（15.x 才加），该字段服务器托管；`Microsoft.VSTS.Common.ClosedDate` 在 `State=Done` 时按普通字段可尝试写入。模板已去掉日期列，所以导入不再走这条路——若某模板要求 `Done` 必填 Closed Date，需另加列或改回写日期。
- **孤立 Task 在积压工作页不可见**：TFS 2013 的 backlog/任务板按「父项 → 子任务」组织，没挂父链接的 Task 只能在查询里看到，所以导入必须带 `parent_title`/`parent_id`。
+- **字段校验不可绕过**：OM 14.x 没有 `SaveFlags.BypassRules`，旧界面上那个 `bypassRules` 勾选从未真正生效，已移除。校验失败时日志与 report CSV 直接给出「字段(原因) → 怎么改」，列表字段还会列出允许值，按提示改 Excel 对应列后重跑即可。
+- **孤立 Task 在积压工作页不可见**：TFS 2013 的 backlog/任务板按「父项 → 子任务」组织，没挂父链接的 Task 只能在查询里看到，所以导入必须带父项（界面填父 PBI Id，或 Excel 里加 `PBI Id` 列）。
 - **DNS 解析失败 / 超时**：多为 VPN 或网络断开，不是代码问题；桌面版会对这类异常附加排查提示。

 ## 验证

-改动 Python 版后至少跑：
-
-```powershell
-python -m py_compile tfs_import.py
-python tfs_import.py --dry-run
-```
-
-桌面版改完跑一次 `--limit` 级别的小批量导入（先删服务器已有同标题项或开启跳过），并在积压工作页展开父项确认子任务可见。
+桌面版改完，先用只含几行的 Excel 跑一次小批量导入（先删服务器已有同标题项或勾「跳过已存在标题」），再在积压工作页展开父项确认子任务可见；改动涉及界面布局或图标时，跑 `python tools/win_screenshot.py` 抓图核对。确认无误后再跑全量。