# 蓝晒小掌柜

> 面向手作店铺的智能经营驾驶舱：融合自然语言记账、进销存、生产成本核算、往来管理与经营分析。

## 1. 项目概述

蓝晒小掌柜是一款面向小型手作工作室和个人经营者的经营管理 Web 应用。项目围绕“采购—生产—库存—销售—收付款—经营分析”建立完整数据闭环，帮助使用者从分散的备忘录或表格记账，过渡到可追溯、可核对、可分析的结构化经营管理。

本项目为求职作品集性质的单店经营原型，重点展示产品设计、业务建模、前端工程、数据一致性和可视化能力，不作为法定会计核算或纳税申报软件。

## 2. 业务问题

手作店铺通常具有 SKU 多、单量小、生产耗料复杂和渠道分散等特点。仅记录“今天收了多少钱”无法回答以下问题：

- 每件商品实际消耗了多少原材料？
- 销售收入中有多少仍未收回？
- 当前库存还能支持多少次生产？
- 设备购置成本应如何分期计入经营结果？
- 利润变化来自售价、销量、材料成本还是期间费用？

因此，本项目将交易流水、库存数量、移动平均成本、BOM、工单、应收应付和设备分摊统一纳入同一账本。

## 3. 核心业务闭环

```mermaid
flowchart LR
    A["采购入库"] --> B["原材料库存"]
    B --> C["BOM 与生产工单"]
    C --> D["成品库存"]
    D --> E["销售与退货"]
    E --> F["应收、应付与结算"]
    F --> G["利润、现金流与经营分析"]
```

一次业务操作会同步影响交易流水、库存移动、成本、往来款和报表口径，避免不同模块之间的数据脱节。

## 4. 核心模块

| 模块 | 主要能力 |
| --- | --- |
| 智能速记 | 将中文口语解析为销售、采购、费用、结算、退货等结构化业务草稿 |
| 进销存 | 成品与原材料分层管理、库存预警、移动平均成本、盘点调整 |
| 生产管理 | BOM 配方、计划工单、完工入库、耗料与批次成本结转 |
| 往来管理 | 应收、应付、部分结算、到期提醒及交易关联 |
| 设备分摊 | 录入购置金额、开始月份和分摊期，按期间自动停止计提 |
| 经营报表 | 收入、毛利、净利润、现金流、成本结构、趋势及差异桥 |
| 数据治理 | 快照、备份导入导出、健康检查、冲销与撤销 |

## 5. 关键设计决策

### 5.1 移动加权平均成本

采购入库后，系统按以下公式更新材料单位成本：

```text
新平均成本 =（原库存金额 + 本次采购金额）÷（原库存数量 + 本次入库数量）
```

生产完工时，根据 BOM 实际耗料和当时材料成本形成成品批次成本；销售时将对应成本计入销售成本。

### 5.2 原子化过账

一笔业务可能同时更新流水、库存、应收应付和工单。系统先在状态副本上完成校验和影响计算，全部成功后再替换正式状态，从而避免“流水已写入、库存未更新”等半完成状态。

### 5.3 红字冲销与精确恢复

已入账交易通过冲销记录保留审计轨迹。冲销时保存受影响库存、往来款和分摊计划的快照；撤销冲销时恢复原始状态，并检查是否存在后续库存移动，防止破坏成本链路。

### 5.4 设备分摊

设备分摊按“报表月份与购置月份的月份差”判断是否处于有效期，不依赖手工累加计数。超过分摊月数后自动停止，年度汇总也采用相同规则。

### 5.5 报表口径

- 销售收入包含已收和未收部分；未收部分进入应收，而不是从收入中剔除。
- 销售退货以负数冲减收入，并根据是否回库恢复库存及成本。
- 现金流仅统计实际收付金额。
- 税费模块用于经营情景估算，与正式申报口径明确区分。

## 6. 数据一致性与安全

- 用户可见文本进入 `innerHTML` 前统一转义，降低 XSS 风险。
- CSV 导出对 `=`、`+`、`-`、`@` 等公式前缀进行防护。
- 导入时校验数据结构、ID 唯一性、数值、日期、业务引用和 BOM 关联。
- 库存回滚若会导致负库存则拒绝执行。
- 备份包含校验信息；异常导入不会覆盖当前账本。
- 本地快照支持在重大操作前恢复。

## 7. 技术实现

- 前端：原生 HTML、CSS、JavaScript
- 可视化：ECharts；加载失败时使用原生 SVG 降级
- 数据存储：浏览器 LocalStorage
- 交互形态：响应式单页应用，可离线打开
- 工程策略：无后端依赖、单文件可携带、业务规则集中校验

## 8. 运行方式

### 在线体验

打开作品集站点后，点击“进入交互式 Demo”。首次访问会自动载入与当前月份对齐的演示账套。

### 本地运行

直接使用现代浏览器打开 `dist/demo/index.html` 即可。若浏览器限制本地脚本，也可以在项目目录启动任意静态服务器：

```bash
python3 -m http.server 8000 -d dist
```

然后访问 `http://localhost:8000/demo/`。

## 9. 推荐演示路径（约 64 秒）

1. 首页：查看本月利润、现金、库存预警与智能经营建议。
2. 智能速记：输入“今天拼多多卖出 2 把团扇，已收 70 元”并检查结构化草稿。
3. 报表：查看收入、毛利、净利润、现金流趋势和成本结构。
4. 库存：查看成品、原材料、BOM 和生产工单。
5. 往来：查看部分收款形成的应收及月结快递应付。
6. 设备分摊：检查曝光机的 12 个月分摊计划。
7. 流水：展示编辑、冲销、筛选和库存移动追溯。
8. 数据治理：展示健康检查、快照与备份能力。

## 10. 测试范围

| 场景 | 预期结果 |
| --- | --- |
| 设备分摊到期 | 最后一个有效月份计提，之后自动停止 |
| 生产完工 | 原料扣减、成品增加、成本结转和工单状态同步完成 |
| 销售退货 | 收入冲减，符合条件时库存与成本同步恢复 |
| 交易冲销与撤销 | 库存及关联应收、应付、分摊计划精确恢复 |
| 非法导入 | 数据被拒绝，当前账本保持不变 |
| 旧版备份 | 缺失的可选字段获得兼容性默认值 |
| 图表依赖失败 | 自动切换到 SVG 降级视图 |

## 11. 项目边界

- 当前版本使用 LocalStorage，不支持多人协作和跨设备实时同步。
- 税费模块是经营估算工具，不替代会计师意见或税务申报系统。
- 项目暂未实现会计期间锁账、角色权限和后端审计日志。
- 历史交易的成本冻结仍是下一阶段需要完善的核心能力。

## 12. 后续路线

1. 增加期初现金及银行账户余额。
2. 增加月度结账、反结账和权限控制。
3. 为历史销售固化成本快照，避免重算造成历史利润漂移。
4. 拆分模块并引入自动化单元测试与端到端测试。
5. 增加后端同步、账号体系和多设备数据一致性。

## 13. 个人贡献

独立完成需求分析、业务流程梳理、数据模型、财务与库存规则、交互设计、前端实现、可视化、数据安全和回归测试。

## 14. 作品集定位

**蓝晒小掌柜：面向手作店铺的智能经营驾驶舱。**

它不是简单的收支记录器，而是一个能够连接采购、生产、库存、销售、往来款与经营分析的完整业务原型。