dsh-personal-ledger 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-personal-ledger contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# 分期记账（Installment Ledger）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> npm 包名：`dsh-personal-ledger` · 版本 `1.3.0`
+
+DeepSeek Harness Web UI 插件：在左侧栏提供「分期记账」入口，打开一个记账面板，用来记录 / 编辑**分期账单**和**不分期（一次性）账单**，从**京东白条 / 信用卡 / 支付宝备用金 / 支付宝花呗**等平台**导入账单**，按**还款月份**统计应还金额并**一键还清当月**，还可将账单**导出为文本 / 表格（CSV）/ 图片（PNG）**。
+
+## 功能
+
+- **添加账单**：对话框顶部选择「分期 / 不分期」。
+  - 分期账单：名称、总金额、期数（3/6/12/24 快捷或 1–120）、首期还款日期、备注；自动生成每期计划。
+  - 不分期账单：名称、总金额、还款日期、备注；只有一笔到期记录。
+- **编辑账单（本次新增）**：每张卡片都有「编辑」按钮，可修改类型、名称、总额、期数、首期还款日期与备注。保存时按「期号顺序」保留已还状态：仍存在的期保留原已还时间；改期数 / 改类型时，能对应上的期保留已还，新增的期从未还开始。
+- **按月份分类与一键还款（本次新增）**：工具栏可切换「账单列表 / 按月份」。
+  - 按到期月份分组，显示每月应还 / 已还 / 待还金额与逾期笔数；当前月份高亮。
+  - 每个月份卡片可展开逐笔查看（账单名、第几期、到期日、金额、状态），也可单独「标记已还」。
+  - 点「一键还清本月」会把该月份内所有未还款项一次性标记为已还，并提示笔数与金额。
+- **导出账单（本次新增）**：页面右上角「导出」。
+  - 格式：**文本（.txt）**、**表格（.csv，Excel 可直接打开，带 BOM）**、**图片（.png，按当前主题绘制的账单汇总图）**。
+  - 可勾选是否包含已还清账单；导出内容包含账单明细（类型、名称、总额、期数、已还、剩余、到期日、来源、备注）与按月份汇总。
+- **账单导入**：右上角「导入账单」，平台预设 京东白条 / 信用卡 / 支付宝备用金 / 支付宝花呗 / 通用 CSV；粘贴文本或读取 `.csv` / `.tsv` / `.txt`（UTF-8，自动尝试 GBK）；点「解析账单」后逐条勾选，点「导入 N 笔」批量导入，自动去重并标记来源平台。**本插件导出的 CSV 可直接回灌**（见下）。
+- **逐期 / 逐笔标记已还**：分期账单展开「还款计划」逐期操作；不分期账单直接在卡片上操作；逾期用警示色提示。
+- **汇总与筛选**：剩余待还、本月已还、最近一期；全部 / 进行中 / 已还清筛选；有逾期或待还的账单排在前面。
+- **删除**：行内二次确认。**本地持久化**：`localStorage` 键 `dsh.installment-ledger.v1`，多标签页通过 `storage` 事件同步。
+- 中英文文案跟随 Harness 语言；颜色、边框、弹层使用 Harness 主题 token，浅色 / 深色 / 第三方皮肤下均可读。
+
+## 导入格式说明
+
+| 平台 | 识别方式 |
+| --- | --- |
+| 京东白条 / 支付宝花呗 | 标签文字：商品名称 / 分期总额（或总金额）/ 分期期数 / 每期应还 / 下期还款日；有「每期金额 + 期数」时生成分期账单，否则按「本期应还 + 还款日」生成一次性账单；也支持多行分期明细（`名称 12期 每期 100.00`）与 CSV。 |
+| 信用卡 | 逐行交易明细：`2026-01-10 京东商城 123.45`（日期 商户 金额），或带表头的 CSV（日期 / 商户 / 金额…），每行生成一笔一次性账单；也识别「本期应还 + 到期还款日」汇总。 |
+| 支付宝备用金 | 标签文字：取用金额 / 借款金额 / 还款金额、到期日（或应还日期），生成一次性账单。 |
+| 通用 / CSV | 表头列名支持：名称 / 描述 / 商户、金额 / 总金额、日期 / 到期日、期数 / 分期期数、类型（分期 / 不分期）、备注；分隔符支持 `,` / `\t` / `;` / `|` / 全角逗号，也支持 `日期 商户 金额` 文本明细。 |
+
+示例（通用 / CSV，可直接粘贴到「通用 / CSV」平台解析）：
+
+```csv
+名称,金额,日期,期数,类型
+手机分期,12000,2026-11-10,12,分期
+年度保险,3600,2026-12-01,1,不分期
+```
+
+- 文件读取支持 `.csv` / `.tsv` / `.txt` 文件，UTF-8 编码；检测到乱码时自动尝试 GBK。
+- 导入前会按「类型 + 名称 + 总额 + 首期/到期日」去重，重复候选会被跳过并提示数量。
+
+### 导出后回灌（导出 CSV 再导入）
+
+「导出」得到的账单 CSV 可以直接粘回「导入账单 → 通用 / CSV」恢复数据，支持的表头为：
+
+```csv
+类型,名称,总额(元),期数,已还期数,剩余(元),首期/到期日,下次到期日,来源,备注
+```
+
+- 名称按原样保留（带英文逗号的名称会自动按 CSV 引号规则处理）；
+- **已还期数**会还原为对应期数的已还状态（已还时间记为导入时刻）；「剩余(元)」「下次到期日」是导出时的派生列，导入时按总额与期数重新计算，不参与导入；
+- **来源**列的中英文平台名会映射回平台标记（空值表示无来源）；
+- 文件末尾的「还款月份 / 应还 / 已还 / 待还」汇总表会被自动忽略，不会被当成账单导入；
+- 缺少可识别表头的多列表格会提示「缺少可识别表头」而不会猜测金额、生成错误账单。
+
+## 导出格式说明
+
+| 格式 | 文件 | 内容 |
+| --- | --- | --- |
+| 文本 | `installment-ledger-YYYY-MM-DD.txt` | 标题、生成时间、账单总数与剩余待还、逐笔账单明细、按月份应还 / 已还 / 待还汇总。 |
+| 表格 | `installment-ledger-YYYY-MM-DD.csv` | 第一段：类型 / 名称 / 总额(元) / 期数 / 已还期数 / 剩余(元) / 首期或到期日 / 下次到期日 / 来源 / 备注；第二段：还款月份 / 应还(元) / 已还(元) / 待还(元)。UTF-8 BOM，逗号分隔，含引号转义。 |
+| 图片 | `installment-ledger-YYYY-MM-DD.png` | 按当前主题配色绘制的账单汇总图：标题、汇总、账单明细表、按月份汇总，2 倍像素密度。 |
+
+三种格式均在浏览器本地生成并触发下载，不上传任何数据。
+
+## 界面位置
+
+- 左侧栏新增账本图标（`sidebar.panellist`，id 为 `installment-ledger`）；点击后在中栏打开记账页（`main` 槽位），无需选中会话。
+- 右上角按钮：**导出**、**导入账单**、**添加账单**。
+- 工具栏：**账单列表 / 按月份**视图切换；列表中另有 全部 / 进行中 / 已还清 筛选。
+- 添加 / 编辑 / 导入 / 导出均为页面内对话框：Esc 关闭、点击遮罩关闭、Tab 焦点循环，关闭后焦点回到触发按钮。
+
+## 数据格式
+
+```json
+{
+  "version": 2,
+  "bills": [
+    {
+      "id": "bill-…",
+      "kind": "installment",
+      "name": "手机分期",
+      "totalCents": 1200000,
+      "periods": 12,
+      "firstDue": "2026-11-10",
+      "note": "免息",
+      "source": "generic",
+      "createdAt": "2026-11-03T13:00:00.000Z",
+      "payments": [
+        { "index": 0, "dueDate": "2026-11-10", "amountCents": 100000, "paidAt": null }
+      ]
+    },
+    {
+      "id": "bill-…",
+      "kind": "single",
+      "name": "年度保险",
+      "totalCents": 360000,
+      "periods": 1,
+      "firstDue": "2026-12-01",
+      "note": "",
+      "source": "",
+      "createdAt": "2026-11-03T13:05:00.000Z",
+      "payments": [
+        { "index": 0, "dueDate": "2026-12-01", "amountCents": 360000, "paidAt": null }
+      ]
+    }
+  ]
+}
+```
+
+- `kind` 为 `"installment"`（分期）或 `"single"`（不分期）；旧版本数据没有 `kind` 时按「分期」读取，兼容已有账本。
+- `source` 为可选来源平台 id：`jd-baitiao` / `credit-card` / `alipay-reserve` / `huabei` / `generic`；手动添加的账单为空。
+- 两种类型共用 `payments` 结构：不分期就是只有 1 期的账单；编辑账单时按 `index` 保留已还时间戳。
+- 金额一律以「分」为整数存储；读取时做防御性归一化（非法账单丢弃、缺失的期数 / 金额 / 到期日重新推导，已还时间戳保留）。
+
+## 文件结构
+
+- `package.json`：bundle 清单（`dsh.bundle.patch` + `dsh.client`）。
+- `cordis.patch.yml`：向当前 profile 插入 `installment-ledger` 行。
+- `index.js`：Host 半边（无 Host 逻辑，UI 与数据均在浏览器端）。
+- `client.js`：面板页面、添加 / 编辑 / 导入 / 导出对话框、月度统计与还款、localStorage 存取与槽位注册。
+- `locale/en.json`、`locale/zh.json`：插件管理器中显示的标题与描述。
+- `icon.svg`：原创图标（账本 + 金币）。
+- `LICENSE`：MIT 许可证。
+
+## 安装与验证
+
+- 从 npm 安装：在 Harness 左侧栏「插件 / Plugins」页点「Add plugin」，输入包名 `dsh-personal-ledger`（可带版本号，如 `dsh-personal-ledger@1.3.0`）。
+
+- `node --check index.js`、`node --check client.js` 通过；`package.json`、`locale/*.json` 为合法 JSON；`icon.svg` 为合法 SVG。
+- 安装后经 `cordis_inspect_query` 的 Client `Slots.listSubTree` 确认：`sidebar.panellist` 出现 `installment-ledger` 占用项，`main` 出现 `installment-ledger` 键。
+- 逻辑与渲染测试覆盖：金额 / 日期 / 分期拆分、类型切换、旧数据兼容、五种导入解析、账单编辑（已还状态保留）、按月分组与一键还款、文本 / CSV / 图片导出、导出 CSV 回灌导入。
+
+## 已知限制
+
+- 不包含分类统计、多币种、按平台筛选；编辑只维护「当前计划」，不会还原历史已还时间（已还状态按期号保留）。
+- 图片导出是绘制好的静态 PNG（不可再编辑文本）；文本 / 表格 / 图片均在浏览器生成并触发下载，若运行环境禁止下载只提示不支持。
+- 导入解析基于常见文案 / 表头的启发式规则：不同银行或平台的导出格式可能不同，请先在「识别结果」里核对候选账单再导入。
+- 数据存于当前浏览器，不跨浏览器 / 设备同步，也不写入 Session 日志或 Host 存储；清除站点数据会清空账本。
+- 本插件未注册模型可调用的工具，模型无法直接读写账本。
+- 当前安装环境无浏览器自动化控制，视觉与交互主要依靠独立渲染冒烟测试 + 槽位注册验证；像素级外观需在 Web UI 中人工确认。