# 顾信家居 IT · WorkBuddy 项目开发全过程纪要（总索引）

> 本辑收录 **8 个已归档到云效 codeup（代码组 `guxin-it`）** 的项目，从最初规划、功能迭代、构建归档的全过程回顾。
> 素材全部来自各项目仓库实证：README、`docs/` 文档、完整 git 提交历史、codeup 远端状态（`git ls-remote` 逐仓核验）。凡资料未记载处均标注「资料未记录」，**未虚构任何对话内容**。

---

## 一、为什么有这本文档

2026-09 至 10 月这批项目的真实迭代过程，散落在三个地方：git 提交信息、项目 `docs/` 文档、以及与 WorkBuddy 的日常对话里。前两者能长期留存，对话却会随会话消失。

这本文档的作用是**把"决策链条"固定下来**：为什么当初这么选、中途撞了什么坑、怎么修的、沉淀了什么经验。以后接手维护、或者做下一个项目时，可以直接复用这些判断，而不用重新踩一遍。

写作原则：
- **只写有据可查的事实**，查不到就写「资料未记录」
- **弯路和失败照样写**（如 netServer 历史提交里残留明文口令、ERPMcp 自测清空真实配置事故、RouterMonitor 生产修复未上 main 的风险窗口）
- **不吹嘘**，成就是结果不是宣传

---

## 二、协作架构总览

8 个项目不是各干各的，而是共用同一套「本地开发 → codeup 双分支 → 生产环境」的协作链路：

<div class="archwrap">
<img src="协作架构图.svg" alt="项目协作架构图" style="min-width:1180px">
</div>

> 窄屏可横向滚动查看完整图。源文件 `协作架构图.svg`（矢量，可无损缩放/放进汇报材料）· `协作架构图.png`（1780×1420）· 生成脚本 `make_arch_diagram.py`
> 图中所有事实（路径、脚本、端口、分支状态）均来自仓库与服务器实测，非示意图。

三条关键链路：

| 环节 | 通道 | 纪律 |
|---|---|---|
| 本地 → codeup | `git push origin dev` | **随时可推**，本地测试通过即可，无需等通知 |
| codeup → 生产 | 服务器上 `git pull origin main` | **必须等用户明确说「发布」**才合并 main + 打 tag |
| 凭据管理 | `backend/.env`（不入库） | `config.json` / `*.env` / `state.json` / 日志一律 gitignore |

远程运维统一走 `srv-cli`（`~/.workbuddy/tools/srv-cli/config.json`，`ai.iut8.cn` + `id_ed25519` 免密），**不允许把本机开发环境直接传到服务器**。

---

## 三、8 个项目一览

| 序号 | 项目 | 台账编号 | 一句话定位 | 周期 | 提交 | 最新 tag | 归档状态 |
|---|---|---|---|---|---|---|---|
| 1 | [netServer](./netServer-开发全过程纪要.md) | P004 | 内网网络监测与设备管理平台（FastAPI + MySQL，宝塔部署） | 09-02 → 10-12 | 13 | v1.1 | 待发布 1 提交 |
| 2 | [RouterMonitor](./RouterMonitor-开发全过程纪要.md) | P007 | 路由器每 2 分钟采集 + 连接数峰值告警邮件 | 09-11 → 10-12 | 6 | v2.0 | 待发布 3 提交 ⚠️ 生产在跑 |
| 3 | [WinUIMap](./WinUIMap-开发全过程纪要.md) | — | Windows UI 自动化框架（控件树扫描 + UI Map 缓存） | 09-11 → 10-12 | 2 | v0.1 | 待发布 1 提交 |
| 4 | [WorkBuddySign](./WorkBuddySign-开发全过程纪要.md) | P003 | WorkBuddy 每日签到领积分自动化（UIA 驱动） | 09-11 → 10-12 | 3 | v3.0 | 待发布 1 提交 + 6 项未提交 |
| 5 | [LabelStudio](./LabelStudio-开发全过程纪要.md) | P008 | 通用标签打印工具（Excel + JSON 模板，ZPL/TSPL/PDF） | 09-15 → 10-12 | 22 | v1.6.5 | 待发布 3 提交 ⚠️ 修复未进 exe |
| 6 | [GuxinTools](./GuxinTools-开发全过程纪要.md) | P013 | IT 小工具集（修 ERP / 升 FMS / 修打印机） | 09-14 → 10-12 | 5 | v0.4 | 待发布 1 提交 |
| 7 | [IT-AssetManage](./IT-AssetManage-开发全过程纪要.md) | P011 | IT 固定资产管理系统（企微智能表 + Python 工具） | 09-17 → 09-18 | 10 | v1.0 | ✅ 完全同步 |
| 8 | [ERPMcp](./ERPMcp-开发全过程纪要.md) | P012 | ERP MCP 服务（关杰 ERP 接成 WorkBuddy 连接器） | 09-18 → 10-12 | 9 | v0.5.0 | 待发布 6 提交 ⚠️ 3 版本无 tag |

合计 **80 个提交、32 个 tag、7220 行纪要**。

### 技术栈分布

| 技术 | 项目 |
|---|---|
| Python + FastAPI | netServer |
| Python + tkinter | LabelStudio、WorkBuddySign |
| Python + pywinauto/UIA | WinUIMap、WorkBuddySign |
| Python + 企微智能表 | IT-AssetManage |
| Python + MCP SDK | ERPMcp |
| bat / PowerShell | GuxinTools |
| 标准库 + HTTP 抓取 | RouterMonitor |

### 生命周期阶段覆盖度

所有 8 篇均按统一八章结构撰写：

| 阶段 | 对应章节 |
|---|---|
| 需求缘起与边界 | 一、项目缘起与初始规划 |
| 方案选型与架构 | 二、技术选型与架构设计 |
| 功能迭代编年史 | 三、迭代编年史 |
| 关键技术攻坚 | 四、关键攻坚与踩坑复盘 |
| 测试与验证 | 五、质量保障与验证机制 |
| 构建部署归档 | 六、构建、部署与归档 |
| 遗留与后续 | 七、遗留问题与后续计划 |
| 人机协作复盘 | 八、协作方式复盘 |
| 附录 | A 完整提交清单 / B 文件与模块说明 |

---

## 四、跨项目共性观察

从 8 个项目横向对照，沉淀出 5 条可复用的经验：

### 1. 「实机取证」是这些项目的通用工作方式

LabelStudio 打错标签 → 拍照 → 量墨迹 → 改渲染层 → 再打；IT-AssetManage 标签从「改 80×40」到「六轮」每轮都配验证脚本；WorkBuddySign 目录里留下 13 个探针脚本和几十张截图。**验收标准不是"代码写完"，而是"实物对上且有断言兜底"。**

### 2. 提交历史普遍不反映真实迭代量

WinUIMap 只有 2 个提交，但目录里有 14 张跨 3 小时的调试截图和两版框架日志 —— v0.1 之前框架已重写过至少一轮。早期工作在「单仓多目录归档模式」下被整理型提交（`a3bd48b 整理项目产物`）压缩，真实过程已无法从 git 完全还原。**这正是写这份文档的原因。**

### 3. 待发布积压是当前最大风险

按 v2.1 分支模型，`main` + tag 需用户明确通知才能动，导致：
- **RouterMonitor** ⚠️ 10-12 的告警静默丢失修复**已在生产运行但不在 main** —— 任何人重新 clone 会把 bug 恢复回去
- **LabelStudio** ⚠️ v1.6.5 的 TSPL 修复已验证，但 `dist/` 里的 exe 打包时间早于修复提交 —— **修复没进实际分发程序**
- **ERPMcp** ⚠️ v0.5.1/v0.5.2/v0.5.3 有提交无 tag，写能力三次关键修复全在 dev

### 4. 用户数据保护必须写进脚本，不能靠自觉

两起真实事故：
- **2026-09-16**：GUI 冒烟测试未隔离，覆盖用户草稿（不可逆，靠日志字段重建才救回）
- **2026-09-18**：MCP 自测未隔离 `ERP_MCP_HOME`，清空了真实 `config.json` 的账号密码

教训固化：**未设环境变量就自动指到临时目录、指向真实目录直接 ABORT、收尾断言真实文件字节快照未变**。ERPMcp 的自测日志里已有 `[PASS] ★真实配置文件字节未变（防覆盖）` 这条断言。

### 5. 凭据外置是最后一道防线

netServer 2026-09-11 把硬编码的数据库口令迁到 `backend/.env`，配套 `env_file` 改绝对路径（否则 pydantic 按 cwd 找，换启动目录就读不到）、加 `.env.example` 模板、`deploy_p1.sh` 加前置检查。**但历史 11 个提交里的明文口令仍在**，按用户决定接受残留（开发库口令随时会改），轮换口令是唯一闭环。

---

## 五、怎么读这些文档

| 你的目的 | 建议读法 |
|---|---|
| 接手维护某个项目 | 直接看该项目的「三、迭代编年史」+「六、构建部署归档」+「七、遗留问题」 |
| 做下一个类似项目 | 看「二、技术选型」+「四、关键攻坚」，重点是 LabelStudio 的 TSPL 案例和 IT-AssetManage 的标签六轮 |
| 了解协作模式 | 看每篇的「八、协作方式复盘」，再对照本文档第四节 |
| 决定发布动作 | 看每篇的「关键信息速览」表 + 本文档第二节表格的「归档状态」列 |
| 排查历史决策 | 看「一、项目缘起」的「如果现在重做会怎么定」小节 |

---

## 六、素材来源与核验方式

| 核验项 | 方法 | 结果 |
|---|---|---|
| 仓库真实性 | 逐仓 `git ls-remote` 云效远端 | ✅ 8 仓全部存在，ref 与本地一致 |
| 提交完整性 | `git log --all` 全量遍历 | ✅ 80 个提交全部纳入附录 A |
| tag 完整性 | `git tag` + 远端 `refs/tags` 比对 | ✅ 32 个 tag，其中 ERPMcp 缺 3 个（v0.5.1~3） |
| 分支状态 | `main..dev` 差异 + `git status` | ✅ 逐仓记录，WorkBuddySign 6 项未提交已标出 |
| 文档一致性 | README / `docs/` 与代码交叉核对 | ⚠️ 发现 20+ 处不一致，均已写入对应纪要 |

**已知局限**：历史对话检索仅覆盖最近 7 天，2026-09 的原始对话无法取回。因此本文档的「协作方式复盘」章节基于提交记录、文档内容与目录痕迹**客观归纳**，不含具体对话原文引用。