【征文】用 WorkBuddy 从一句话需求做到可交付的固定资产管理系统：v3.4 实战全记录

本文记录一个真实项目的完整落地过程：从"我要一套固定资产管理系统"这一句话开始，到产出一个 48MB 的 Windows 安装包、一份 40 页的用户手册和一个在线下载页。所有内容均为实际操作记录，包含可直接复用的提示词模板与 10 条踩坑清单。

一、先说结论

系统首页看板

图 1：系统首页看板，资产总量、分类分布、近期动态一屏可见

二、输入材料：我到底给了 WorkBuddy 什么

这是很多人忽略的一点——AI 交付质量的上限，取决于你喂给它多少"业务约束"，而不是你的提示词写得多花哨。

我全程没有给过一份正式的需求文档，输入材料只有三类：

1. 一句话原始需求

开发一个资产管理系统，对标市面主流资产管理系统，搭建一套功能完善、可本地服务器部署的网页版固定资产管理系统。主要围绕固定资产全生命周期管理（资产入库、管理、周转、处置等），要有组织架构管理、存放地点管理、保管人管理；代码简单，数据库容易部署；兼容多设备访问；要有批量导入/导出/修改功能。

2. 技术约束（一开始就钉死，避免后期返工）

• 前端 Vite + React + MUI + Tailwind
• 后端 Node.js + Express
• 数据库 SQLite（零配置，单文件）
• 部署在本地服务器，不依赖任何云服务
• 响应式，PC / 平板 / 手机都能用

3. 逐轮追加的业务细节

这是最关键的部分。系统不是一次做成的，而是我在使用过程中不断追加的，每一轮都是一句大白话：

• "资产标签打印能否关联资产信息？我要包含资产名称、存放位置、管理部门、资产编号、财务编号、入库日期、保管人"
• "盘点功能太简单了，要能批量修改每条资产的盘点结果，最后能生成盘点表格和报告"
• "打印机驱动加入佳博 GT-1124T，10×4cm 尺寸会被裁剪内容"
• "加入数据库管理功能，备份内容要按数据种类分类，恢复后要注意数据关联防止数据出 bug"
• "操作日志要明确用户操作了什么，加入管理员撤销选项并恢复操作前的数据"

经验：把技术选型写死在第一轮，把业务细节拆成多轮追加。前者防架构摇摆，后者符合真实认知节奏——你不可能在没用过的系统面前想清楚所有细节。

三、WorkBuddy 配置：我怎么搭的工作流

模式：全程代码模式（Craft），没有用过 Ask / Plan。

专家团队：组建了一个四人团队分工，这是本项目效率的核心。

为什么这步值得做：架构文档一旦落盘，后续十几轮迭代里 WorkBuddy 每次都能读到同一份 Schema 和 API 约定，不会出现"这轮把 asset_records 的字段写成 type、下轮又写成 operation_type"这类漂移。这是长周期项目能保持一致的根基。

目录约定：把 PRD 和架构文档固定放在项目根的 docs/ 下，后续每个新会话都能被稳定检索到。

四、操作步骤：四个阶段与真实提示词

阶段 1：需求 → PRD（约 15 分钟）

提示词就是上面那句原始需求，追加了一句约束：

请输出简单 PRD，包含：产品目标（一句话定位 + 核心价值）、用户角色（系统管理员 / 资产管理员 / 普通用户）、功能需求按模块列出（基础数据管理、资产全生命周期、人员管理、报表统计、系统功能）。

产出 docs/PRD.md。这一步的价值不在于文档本身，而在于逼你把模块边界想清楚。

阶段 2：PRD → 架构设计（约 20 分钟）

请基于 PRD 进行完整系统设计，输出到 docs/ARCHITECTURE.md：技术选型确认、目录结构、12 张表的完整建表 SQL、50+ 后端 API 设计、22 个前端路由、共享约定（API 响应格式 / 错误码 / 分页 / JWT）、依赖包版本。

这一步千万别跳过。 我后来 v3.0 到 v3.4 的每一次迭代，都因为这份文档的存在而省掉了大量重新对齐的成本。

阶段 3：编码实施（分 5 个串行任务）

按依赖关系严格排序：基础设施 → 数据库与迁移 → 后端 API → 前端页面 → 批量导入导出。每个任务单独一轮对话，避免上下文污染。

阶段 4：迭代打磨（十几轮，最有价值的部分）

举三个真实案例，展示 WorkBuddy 如何处理"不精确的需求"：

案例 A：标签打印被裁剪

我的原始反馈是"10×4cm 尺寸会被裁剪内容"。WorkBuddy 定位到根因是缩放系数只看了宽度：

// 旧：只看宽度 → 100×40mm 这类"宽而矮"的标签必然溢出
const k = clamp(w / 95, 0.6, 1);

// 新：宽高联合降档，取更严格的那个
const k = clamp(Math.min(h / 55, w / 95), 0.6, 1);
// 列数：够宽够高才分两列
const cols = (w >= 80 && h >= 22) ? 2 : 1;

标签打印，支持 7 大品牌 20+ 款机型、18 种标签尺寸

图 2：标签打印模块，内置 7 大品牌 20+ 款打印机驱动、18 种标签尺寸，自动生成二维码

案例 B：数据库管理要"分类备份 + 恢复不出 bug"

这句话拆出了 9 个数据分类、10 个后端接口和一套带回滚的恢复逻辑：

• 备份格式 { format: 'asset-mgmt-backup', version: 1, categories, tables: { name: { columns, rows } } }
• 恢复提供两种模式：replace（按原 ID 重建）/ merge（ID 冲突跳过，绝不重分配 ID，这是保证关联不出错的关键）
• 失败回滚不落盘——任何一步出错，整个库回到操作前状态
• 备份文件入库 db_backup_files 表，全程留痕

案例 C：操作日志 + 管理员撤销

需求是"能撤销用户操作并恢复操作前数据"。实现要点：

• 中间件层捕获变更前快照（captureBefore()），敏感字段不入快照
• 撤销前做"数据已被后续修改"校验——比对当前行与快照中的 after，不一致则拒绝撤销（返回 409），避免覆盖他人在其后的合法修改
• 撤销必须填 ≥5 字说明，否则 400
• 撤销后写一条 action='undo' 日志，并通知原操作人

操作日志与撤销

图 3：操作日志显示字段级变更明细，管理员可撤销并恢复操作前数据

五、产出物：最终交付了什么

1. 功能全景

资产台账

图 4：资产台账，支持自定义列、多条件筛选与批量操作

资产详情

图 5：资产详情，实物照片 + 全生命周期履历（领用、调拨、维修、盘点记录）

自动折旧

图 6：三种折旧方法（年限平均法 / 双倍余额递减法 / 年数总和法），按月自动计提

手机扫码盘点

图 7：手机浏览器直接扫码盘点，无需安装 App

盘点报告

图 8：盘点盈亏汇总，一键导出 Excel

RFID 标签管理

图 9：RFID 标签管理，支持 UHF / HF / NFC，绑定解绑一目了然

权限管理

图 10：40+ 项权限点按角色精细分配，支持数据范围（全部 / 本部门 / 本存放地点 / 本人保管）

2. 工程化交付

打包链路是三段式：compile_csharp.py（编译安装器）→ build_exe.py（打包 zip）→ append_zip.py（拼成 exe）。

3. 合规底座

跑了全量依赖审计：MIT 346 / ISC 29 / Apache-2.0 14 / BSD-3 7 / BSD-2 1 / CC-BY-4.0 1，GPL / AGPL / LGPL / SSPL / BUSL 数量 = 0，可闭源商用。

这里有个必须提醒的边界：AI 生成的代码在现行规则下无法申请软件著作权（须手抄"未使用 AI"承诺并签名），商业化应走"卖服务不卖代码"的授权模式，合同加 as-is 与责任上限条款。

六、10 条踩坑清单（这部分最值钱）

这些都是真实踩过、且不是通用知识的坑：

另外一条工程纪律：打包模式下启动服务会切换数据目录到 %APPDATA%，本地联调时必须显式指定 DB_PATH，否则你会对着一堆种子数据怀疑人生。

七、可复用的提示词模板

把这几条存起来，下次做类似系统直接套：

① 立项

我要做一个 系统类型，对标 竞品/标准。要求：核心业务链路。技术约束：前端 X，后端 Y，数据库 Z，部署方式 W。请先输出 PRD，包含产品目标、用户角色、按模块划分的功能需求。

② 架构

基于 PRD 输出完整设计文档到 docs/ARCHITECTURE.md：目录结构、完整建表 SQL、API 端点清单、前端路由、统一响应格式与错误码、依赖版本。这份文档后续所有迭代都要遵守，不得擅自偏离。

③ 迭代反馈（关键：说现象，不说方案）

页面/功能 有问题：描述你看到的异常现象。我期望：描述期望结果。

比如"10×4cm 尺寸会被裁剪内容"——说现象就够了，不要自己猜"应该是缩放系数写错了"，把根因定位交给它。

④ 交付

测试所有功能的关联性与前端访问，做最终测试后打包为安装包，同步更新 PDF 用户手册。

八、一点体会

1. 架构文档是长周期项目的命根子。 十几轮迭代下来没跑偏，全靠第一版 ARCHITECTURE.md 一直在上下文里。
2. 反馈说现象，别下诊断。 我绝大多数轮次只描述了"点了没反应""内容被裁剪""数量不对"这类现象，根因定位的准确率远高于我自己先下判断再指挥它改。
3. AI 写得了代码，写不了业务。 资产分类怎么分、折旧从哪个月开始提、盘点结果有哪几种状态——这些必须你来定，或者至少你来确认。
4. 合规要提前想。 依赖许可证、AI 生成代码的著作权边界、架构能否支撑 SaaS，这些在写完代码之后再改成本极高。

如果你也在用 WorkBuddy 做企业级系统，欢迎评论区交流踩坑经验。

#WorkBuddy #AI办公