Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions plugins/project-cost/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
node_modules/
dist/
releases/
.DS_Store
86 changes: 86 additions & 0 deletions plugins/project-cost/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# 更新日志

## 1.0.0 - 2026-10-29

首次上架 ZTools 插件市场。以下为完整功能清单。

**多项目台账**

- 每个项目独立预算 / 品类 / 支付对象 / 支出 / 付款,可重命名、切换、删除,可存为模板复用
- 可为项目填建筑面积,填了才显示单方造价(元/㎡),未填则整项隐藏,绝不显示「¥0/㎡」误导

**明细驱动金额链(唯一真源)**

- 明细金额合计 → 项目总计 → 应付(总计 − 优惠)→ 已付(Σ 付款)→ 待付
- 有明细时总计自动汇总并锁定只读;数量 × 单价齐全时金额自动算并锁定
- 预估与应付分离:派生「确定应付 = 应付 − 预估合计」,预算占用率与超支/临界预警按确定应付算,真源「应付 / 待付」保持不变

**付款跟踪**

- 逐笔流水(支持负数退款),每笔有稳定编号 `P0001`、备注与凭证号,超付软确认
- 作废留痕:作废 ≠ 删除,记录灰显留在流水里、保留编号与凭证号,只是不再计入已付,可随时恢复;真正抹掉才用「彻底删除」。作废款不进环比、趋势、体检与对账单
- 批量登记:勾选多条 → 输入总额按待付比例或均分自动拆行,最后一行吸收分角差(Σ 恒等于总额),面板内逐笔预览后一次落库,整批一次撤销
- 付款日期必填;历史无日期记录允许保留空值并高亮提示,不会被悄悄补成今天

**到期日与逾期提醒**

- 到期日推算可配:按项目设 1–365 天(默认 30),只影响未填到期日的费用项
- 逾期分级:拆成「逾期 1–30 天」与「超 30 天」两档,付款页顶部有「超 30 天 · 优先催收」置顶卡,按逾期天数降序
- 临期提醒(≤7 天);预警可当天忽略、跨天自动恢复,左轨角标仍保留计数

**预算预警**

- 品类预算进度、超支与临界(默认 80%)提示,顶栏横幅按类型收敛,不撑爆窄窗口
- 抽屉内实时预算剩余:选完品类、填好金额即提示「该品类预算剩余 X,本笔后剩 Y / 将超支 Z」

**分析**

- 账龄分桶:按到期日把待付分成 0–30 / 31–60 / 61–90 / 90 天以上四桶(四桶之和恒等于待付合计),点桶可展开下钻,可按收款方筛选
- 材料(明细品名)支出排行 Top10,按品名合并排(忽略空格与大小写),Top 合计 + 其他 = 明细合计,可对账
- 月度环比:本月 vs 上月应付 / 已付 / 新增费用项的增减与百分比,并给出变化最大的品类
- 收款方账目占比、欠款排行、付款月度趋势、费用类型构成

**收款方**

- 对账单:按收款方生成对账单(费用项金额 / 已付 / 待付 + 付款流水 + 三行小计),支持 A4 打印与导出 CSV
- 改名 / 合并:改名与合并前先显示将影响多少条费用项、多少笔付款与合计金额,确认后才执行,预览与实改同一套口径

**录入效率**

- 明细连续录入:「保存并继续」保存后清空品名/数量/单价/金额、保留单位与预估标记、焦点回到品名框
- 批量粘贴:粘贴 TSV/CSV → 解析预览 → 一次落库多条,金额自动算,坏行剔除不入库
- 品名历史单价联想:按历史明细提示「单位 / 最近单价」,采纳后自动填充
- 费用项复制(含明细 / 跨项目),明细一并复制、编号按目标项目顺延,**付款不复制**(避免虚增已付)
- 列表多选(Shift 连选)+ 批量操作(改品类 / 改收款方 / 改到期日 / 删除 / 批量付款)

**导入导出**

- Excel(支出 / 明细 / 付款三表,数值列按数字写入)、CSV、全量 CSV、JSON 备份(可再导入还原)
- 按当前筛选导出:支出表 / 明细表 / 付款表共用同一作用域,三表行数必然一致
- 三表 CSV 回读导入:按表头对齐列,冲突策略(追加 / 按编号覆盖 / 跳过已存在),落库前自动存快照可回滚
- 同名文件自动追加时分与序号,同日多次导出不会互相覆盖

**数据安全**

- 自动快照与一键回滚:每天首次启动自动存快照,保留 7 份日快照 + 3 份操作前快照(上限 1.5MB),快照存独立键、写失败也不影响账目
- 自动备份(默认开)
- 存储占用与配额预警:已用容量 / 约 5MB 进度条,≥80% 变红提示先导出备份,≥100% 明示写入会被拒绝
- 数据体检与一键修复:9 类数据问题可检测、6 类可一键修复,所有修复动作都不改变应付/已付/待付
- 撤销 / 重做:逐条撤销,支持撤销 → 重做 → 再撤销,快捷键 ⌘Z / ⇧⌘Z,栈 20 步并落盘持久化,按钮实时显示「可撤销 N 步 / 可重做 N 步」

**视图与交互**

- 三档显示密度:紧凑(单行 ~36px,首屏 10 条)/ 舒适 / 大字(所有文字 ≥12px,付款页、抽屉、图表同步放大)
- 搜索命中逐条导航、六档排序(日期 / 编号 / 金额 / 待付 / 到期日 / 收款方)、状态与品类与日期筛选
- 左侧 62px 图标轨道常驻,右侧 392px 抽屉就地编辑,⌘K 搜索 / J K 移动 / Enter 打开 / 1–6 分区 / Esc 关闭
- 三个入口直达:主入口 / 记一笔 / 付款跟踪

**数据搬家**

- 网页版导出 JSON → 插件内「导入 JSON」;可从旧版键名自动迁移,无需手动导入
- 首次进入预置一份真实装修台账作为示例(可随时清空),可核对:应付 246,055.97、已付 188,529.11、待付 57,526.86、预算 234,688.00、结余 −11,367.97

**技术说明**

- Vue 3 + Vite,**零第三方运行时依赖**(Excel / ZIP / OOXML 均为自实现),数据仅存本机 localStorage
- 插件窗口固定 800px 窄窗口设计,跟随 ZTools 深/浅色主题
167 changes: 167 additions & 0 deletions plugins/project-cost/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
# 项目费用管理 · ZTools 插件

把原先的单文件网页台账(`renovation-cost-manager.html`)移植为 ZTools 插件,并按启动器窄窗口(`800 × ~620`)重新设计了版式与交互。

> 定位不止住宅装修:**任何按项目记账的费用台账**(门店改造、工程分包、活动搭建等)都适用。插件标识 `project-cost`,命令词保留「装修费用」「装修」等关键词,搜索习惯不变;本地数据从旧键 `ztools_renovation_cost_v1` 自动迁移到 `ztools_project_cost_v1`,无需手动导入。

## 为什么重做版面

原版是 1200px 宽的「管理后台」:六页签 + 12 列宽表格 + 5 个居中弹窗。ZTools 插件窗口宽度固定 800px,直接塞进去会横向溢出、弹窗遮满屏、切页丢上下文。因此按「启动器原生」重排:

| 维度 | 网页版 | 插件版 |
| --- | --- | --- |
| 导航 | 顶部六页签,占两行 | 左侧 62px 图标轨道,一屏常驻 |
| 支出列表 | 12 列宽表格 + 横向滚动 | 两行式条目流(主信息 + 品类/对象/日期),金额右对齐 |
| 详情 | 居中弹窗遮全屏 | 右侧 392px 抽屉,背后列表保留上下文 |
| 明细/付款 | 各自独立弹窗,与支出弹窗割裂 | 同一抽屉内分段就地增删,不用来回开关 |
| 筛选 | 工具栏堆 5 个控件 | 命令条:搜索 + 状态段 + 品类 + 排序 + 日期折叠 |
| 主题 | 固定浅色 | 跟随 ZTools 深/浅色,可手动切换 |
| 键盘 | 全局快捷键 + G 序列 | `⌘K` 搜索、`J/K` 移动、`Enter` 打开、`1–6` 分区、`Esc` 关闭 |
| 入口 | 只能打开页面 | 三个 feature:主入口 / 记一笔 / 付款跟踪,直达动作 |

## 功能

**多项目台账**

- 每个项目独立预算 / 品类 / 支付对象 / 支出 / 付款,可重命名、切换、删除,可存为模板复用
- 可填建筑面积,填了才显示单方造价(元/㎡),未填则整项隐藏,绝不显示「¥0/㎡」误导

**明细驱动金额链(唯一真源)**

- 明细金额合计 → 项目总计 → 应付(总计 − 优惠)→ 已付(Σ 付款)→ 待付
- 有明细时总计自动汇总并锁定只读;数量 × 单价齐全时金额自动算并锁定
- 预估与应付分离:派生「确定应付 = 应付 − 预估合计」,预算占用率与超支/临界预警按确定应付算,真源「应付 / 待付」保持不变

**付款跟踪**

- 逐笔流水(支持负数退款),每笔有稳定编号 `P0001`、备注与凭证号,超付软确认
- **作废留痕**:作废 ≠ 删除,记录灰显留在流水里、保留编号与凭证号,只是不再计入已付,可随时恢复;真正抹掉才用「彻底删除」。作废款不进环比、趋势、体检与对账单
- **批量登记**:勾选多条 → 输入总额按待付比例或均分自动拆行,最后一行吸收分角差(Σ 恒等于总额),面板内逐笔预览后一次落库,整批一次撤销
- 付款日期必填;历史无日期记录允许保留空值并高亮提示,**不会被悄悄补成今天**

**到期日与逾期提醒**

- 到期日推算可配:按项目设 1–365 天(默认 30),只影响未填到期日的费用项
- 逾期分「1–30 天」与「超 30 天」两档,付款页顶部有「超 30 天 · 优先催收」置顶卡,按逾期天数降序
- 临期提醒(≤7 天);预警可当天忽略、跨天自动恢复,左轨角标仍保留计数

**预算预警**

- 品类预算进度、超支与临界(默认 80%)提示,顶栏横幅按类型收敛,不撑爆窄窗口
- 抽屉内实时预算剩余:选完品类、填好金额即提示「该品类预算剩余 X,本笔后剩 Y / 将超支 Z」

**分析**

- 账龄分桶:按到期日把待付分成 0–30 / 31–60 / 61–90 / 90 天以上四桶(四桶之和恒等于待付合计),点桶可展开下钻,可按收款方筛选
- 材料(明细品名)支出排行 Top10,按品名合并(忽略空格与大小写),Top 合计 + 其他 = 明细合计,可对账
- 月度环比:本月 vs 上月应付 / 已付 / 新增费用项的增减与百分比,并给出变化最大的品类
- 收款方账目占比、欠款排行、付款月度趋势、费用类型构成

**收款方**

- 对账单:按收款方生成(费用项金额 / 已付 / 待付 + 付款流水 + 三行小计),支持 A4 打印与导出 CSV
- 改名 / 合并:执行前先显示将影响多少条费用项、多少笔付款与合计金额,确认后才执行,预览与实改同一套口径

**录入效率**

- 明细连续录入:「保存并继续」保存后清空品名/数量/单价/金额、保留单位与预估标记、焦点回到品名框
- 批量粘贴:粘贴 TSV/CSV → 解析预览 → 一次落库多条,金额自动算,坏行剔除不入库
- 品名历史单价联想:按历史明细提示「单位 / 最近单价」,采纳后自动填充
- 费用项复制(含明细 / 跨项目),明细一并复制、编号按目标项目顺延,**付款不复制**(避免虚增已付)
- 列表多选(Shift 连选)+ 批量操作(改品类 / 改收款方 / 改到期日 / 删除 / 批量付款)

**导入导出**

- Excel(支出 / 明细 / 付款三表,数值列按数字写入)、CSV、全量 CSV、JSON 备份(可再导入还原)
- 按当前筛选导出:三表共用同一作用域,行数必然一致
- 三表 CSV 回读导入:按表头对齐列,冲突策略(追加 / 按编号覆盖 / 跳过已存在),落库前自动存快照可回滚
- 同名文件自动追加时分与序号,同日多次导出不会互相覆盖

**数据安全**

- 自动快照与一键回滚:每天首次启动自动存快照,保留 7 份日快照 + 3 份操作前快照(上限 1.5MB),快照存独立键、**写失败也不影响账目**
- 自动备份(默认开)
- 存储占用与配额预警:已用容量 / 约 5MB 进度条,≥80% 变红提示先导出备份,≥100% 明示写入会被拒绝
- 数据体检与一键修复:9 类问题可检测、6 类可一键修复,**所有修复动作都不改变应付/已付/待付**
- 撤销 / 重做:逐条撤销,支持撤销 → 重做 → 再撤销,快捷键 ⌘Z / ⇧⌘Z,栈 20 步并落盘持久化,按钮实时显示「可撤销 N 步 / 可重做 N 步」

**视图与交互**

- 三档显示密度:紧凑(单行 ~36px,首屏 10 条)/ 舒适 / 大字(所有文字 ≥12px,付款页、抽屉、图表同步放大)
- 搜索命中逐条导航、六档排序(日期 / 编号 / 金额 / 待付 / 到期日 / 收款方)、状态与品类与日期筛选
- 三个入口直达:主入口 / 记一笔 / 付款跟踪

## 开发与打包

```bash
npm install # 首次
npm run dev # 浏览器预览(建议窗口 800×620)
npm run build # 产出 dist/(自带 plugin.json / preload.js / logo.png / README.md)
npm run package # 产出 releases/*.zip / *.zpx
python3 generate_logo.py # 重新生成 logo.png
```

安装:ZTools → 插件管理 → 安装本地插件,选择 `releases/project-cost-<version>.zpx`;或把 `dist/` 里的文件放进 `~/.ztools/plugins/project-cost/`。

## 目录

```
src/
lib/core.js 纯逻辑:金额链、汇总、预警、现金流、日期、数据体检 checkup()
lib/store.js 响应式状态 + localStorage 持久化 + 多账套 / 模板 / 撤销重做 / 搬家 / 快照与回滚
lib/snapshot.js 快照读写(独立键,不参与主数据链路)+ 淘汰策略
lib/filters.js 列表筛选与「按筛选导出」的唯一口径
lib/export.js JSON / CSV / XLSX(零依赖 OOXML + store-only ZIP)
lib/seed.js 默认台账(14 品类 / 71 支出 / 384 明细 / 88 付款)
lib/ui.js 分区、抽屉、搜索筛选、Toast
components/ Icon、Donut、MiniBars、Drawer、ItemRow、DensityChip
views/ 概览 / 支出 / 付款 / 预算 / 分析 / 设置
sheets/ 支出抽屉(含明细、付款)、品类、支付对象、项目管理
```

## 默认台账校验

首次进入预置一份真实装修台账作为示例(可随时清空或另建项目),可核对:应付 `246,055.97`、已付 `188,529.11`、待付 `57,526.86`、预算 `234,688.00`、结余 `-11,367.97`。

> 默认台账里有 6 笔历史付款没填日期(合计 `4,142.00`),所以「数据体检」会报 1 类提示、0 类可修复 —— 这是诚实的结果(不改日期以免伪造对账事实),不是缺陷。

## 自验脚本

**一键跑全部(推荐)**:`node scripts/verify-all.mjs`(23 个套件,含 8 套 headless Chrome UI 冒烟,约 2 分钟);也可只跑指定套件,如 `node scripts/verify-all.mjs v16 v16ui`。

编排器会先用本地 `node_modules/.bin/esbuild` 把套件打成单文件再交给 node 执行(`src/lib/*` 的相对导入没有省略扩展名,node 直接跑不通)。

```bash
node scripts/verify-all.mjs # 全部 23 个套件
node scripts/verify-all.mjs k14b k18k23ui # 指定套件
```

UI 套件依赖 `dist/`,跑之前必须先 `npm run build`。三条不可突破的红线由每个套件共同把关:

| 红线 | 判据 |
| --- | --- |
| 金额链 | 应付 246,055.97 / 已付 188,529.11 / 待付 57,526.86 / 预算 234,688.00 / 结余 −11,367.97 |
| 预算 | 预算键 13 个,`sumBudget === 234688` |
| 导入导出 | 导出 → 导入 round-trip 88 行、0 坏行 |

## 发布

网络正常时用官方 CLI:

```bash
npx @ztools-center/plugin-cli@latest # 或本地安装后
ztools publish
```

市场仓库:`ZToolsCenter/ZTools-plugins`,走 fork → 分支 `plugin/project-cost` → PR 的流程。发布前两件硬门槛:

1. `CHANGELOG.md` 必须有 `## <version> - YYYY-MM-DD` 标题(无 v 前缀、日期不晚于今天、正文非空),格式不对直接拒绝发布
2. 工作区必须干净

网络差到 CLI 的 `git fetch` 跑不完时(它要把上游几百个插件的全部分支拉下来),改用仓库内的备用通道 —— 直接走 GitHub Git Data API,不需要下载任何历史树:

```bash
node scripts/publish-via-api.mjs
```

> 注意:官方 CLI 的忽略名单里**没有 `releases/`**,而它是整棵工作树拷贝、不看 git 跟踪状态,本地 `.gitignore` 忽略掉的 `releases/` 照样会被推上去。备用脚本已内置排除,并在收尾自检里按前缀再扫一遍。
83 changes: 83 additions & 0 deletions plugins/project-cost/build.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
// 打包 ZTools 插件:dist/ 构建产物 + plugin.json / preload.js / logo.png / README.md
// 打平后产出 .zip 与 .zpx(内容一致,.zpx 供 ZTools「安装本地插件」),有 asar 时额外产出 .asar。
const fs = require('fs');
const path = require('path');
const os = require('os');
const crypto = require('crypto');
const { execSync } = require('child_process');

const root = process.cwd();
const dist = path.join(root, 'dist');
const rel = path.join(root, 'releases');
const NAME = JSON.parse(fs.readFileSync(path.join(root, 'plugin.json'), 'utf8')).name;

if (!fs.existsSync(dist)) {
console.error('ERROR: dist/ 不存在,请先运行 `npm run build`。');
process.exit(1);
}
fs.mkdirSync(rel, { recursive: true });

const ver = JSON.parse(fs.readFileSync(path.join(root, 'plugin.json'), 'utf8')).version;
const idx = fs.readFileSync(path.join(dist, 'index.html'));
const hash = crypto.createHash('md5').update(idx).digest('hex').slice(0, 8);

const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ztpkg-'));
function copyDir(src, dest) {
fs.mkdirSync(dest, { recursive: true });
for (const e of fs.readdirSync(src, { withFileTypes: true })) {
const s = path.join(src, e.name);
const d = path.join(dest, e.name);
if (e.isDirectory()) copyDir(s, d);
else fs.copyFileSync(s, d);
}
}
copyDir(dist, tmp);
for (const f of ['plugin.json', 'preload.js', 'logo.png', 'README.md']) {
const p = path.join(root, f);
if (fs.existsSync(p)) fs.copyFileSync(p, path.join(tmp, f));
}
// probe/test 探针不应进包
for (const f of ['probe.html', 'test.html']) {
const p = path.join(tmp, f);
if (fs.existsSync(p)) fs.rmSync(p);
}

for (const ext of ['zip', 'zpx']) {
for (const old of fs.readdirSync(rel).filter((n) => n.startsWith(`${NAME}-${ver}.`) && n.endsWith(`.${ext}`))) {
fs.rmSync(path.join(rel, old), { force: true });
}
}

const zip = path.join(rel, `${NAME}-${ver}.zip`);
const zpx = path.join(rel, `${NAME}-${ver}.zpx`);
execSync(`cd "${tmp}" && zip -r -X -q "${zip}" .`);
fs.copyFileSync(zip, zpx);

// asar 在某些沙箱下不可写:失败时只告警,不阻断 zip/zpx 产物
let asarPhase = false;
process.on('uncaughtException', (e) => {
if (!asarPhase) throw e;
console.warn('asar 打包跳过(沙箱限制):', String((e && e.message) || e).split('\n')[0]);
});

const asarBin = path.join(process.env.HOME, '.workbuddy/binaries/node/workspace/node_modules/.bin/asar');
let asarPath = null;
if (fs.existsSync(asarBin)) asarPath = asarBin;
else {
try { asarPath = execSync('command -v asar').toString().trim(); } catch (e) { /* none */ }
}
if (asarPath) {
const asarFile = path.join(rel, `${NAME}-${ver}-${hash}.asar`);
asarPhase = true;
try {
execSync(`"${asarPath}" pack "${tmp}" "${asarFile}"`);
console.log('asar ->', path.basename(asarFile));
} catch (e) {
console.warn('asar 打包跳过:', String(e.message).split('\n')[0]);
}
// 注意:asar 的写入失败可能是异步抛出的,故不复位 asarPhase
}

fs.rmSync(tmp, { recursive: true, force: true });
console.log('=== releases ===');
for (const n of fs.readdirSync(rel)) console.log(' ', n);
Loading
Loading