# grain_ledger

**Repository Path**: ydbso/grain_ledger

## Basic Information

- **Project Name**: grain_ledger
- **Description**: 粮食台账管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 粮食台账管理系统

粮食购销企业 desktop 管理软件，涵盖主体档案、进销台账、库存管理、结算管理、单据附件等功能，适用于粮食仓储、过磅站和贸易型企业在单机或小办公网络环境下使用。

## 技术栈

| 层 | 技术 |
|---|---|
| 桌面壳 | Electron 39 + electron-builder (NSIS 安装包) |
| 前端 | React 19 + TypeScript 5.9 + Vite 7 |
| 后端 | Express 5 + TypeScript + esbuild |
| 数据库 | SQLite (better-sqlite3) |
| 校验 | Zod 4 |
| 图标 | Lucide React |

## 功能模块

- **仪表盘** — 按粮食品种汇总当日购销数据、当前库存、最近台账记录
- **主体档案** — 企业和农户档案管理，支持供销双重角色，身份证/营业执照附件，高拍仪 OCR 识别
- **粮食品种** — 品种字典维护
- **仓号管理** — 仓库/货位字典维护
- **购销台账** — 核心进销单据，含质检子表、附件上传
- **库存管理** — 实时库存余额与变动流水审计
- **结算管理** — 按主体对账结算，草稿→确认→作废生命周期
- **高拍仪集成** — 良田/Eloam 高拍仪 WebSocket 取图与身份证读取
- **系统设置** — 企业名称、单据编号前缀可配
- **操作日志** — 敏感操作审计

## 项目结构

```
grain_ledger/
├── index.html                    # Vite HTML 入口
├── package.json                  # 依赖与脚本
├── vite.config.ts                # Vite 配置
├── tsconfig.json                 # TypeScript 配置
├── electron/
│   └── main.cjs                  # Electron 主进程
├── src/
│   ├── server/
│   │   ├── index.ts              # Express API 服务
│   │   └── db.ts                 # 数据库初始化与辅助函数
│   └── client/
│       ├── main.tsx              # React SPA 前端
│       └── styles.css            # 全局样式
├── database/
│   └── schema.sql                # 完整建表语句 + 种子数据 + 触发器
├── docs/                         # 设计文档
│   ├── requirements.md
│   ├── architecture.md
│   ├── api-design.md
│   └── ui-and-menu.md
├── data/                         # 运行时数据 (gitignore)
│   ├── grain-ledger.db
│   └── attachments/
├── dist/                         # 前端构建产物
├── dist-server/                  # 后端构建产物
└── release/                      # electron-builder 安装包输出 (gitignore)
```

## 快速开始

### 开发环境

```bash
# 安装依赖
npm install

# 启动开发模式 (API + Vite + Electron 并行启动)
npm run dev
```

- API 服务：`http://127.0.0.1:3800`
- Vite 前端：`http://127.0.0.1:5173`

也可单独启动各模块：

```bash
npm run api          # 仅 API 服务
npm run dev:web      # 仅 Vite 前端
npm run dev:electron # 仅 Electron (需先启动 API 和 Vite)
```

### 生产构建

```bash
npm run build        # tsc 检查 + Vite 构建 + esbuild 打包后端
npm run dist:win     # 构建 + Windows NSIS 安装包
```

默认管理员账号：`admin` / `admin123`

## 数据库

应用使用 SQLite 文件数据库（`data/grain-ledger.db`），启动时自动执行 `database/schema.sql` 建表（幂等）。核心表包括：

- `subjects` — 往来主体
- `ledger_transactions` — 购销台账
- `quality_records` — 质检记录
- `settlement_records` / `settlement_items` — 结算单
- `inventory_balances` / `inventory_movements` — 库存余额与流水
- `operation_logs` — 操作审计日志

台账记录禁止物理删除（数据库触发器保护），只允许"作废"操作，确保审计追溯。

## API 概览

所有接口返回 `{ success, message, data }` 格式。

| 模块 | 端点 | 说明 |
|---|---|---|
| 认证 | `POST /api/auth/login` | 登录 |
| 仪表盘 | `GET /api/dashboard` | 仪表盘数据 |
| 主体 | `CRUD /api/subjects` | 主体档案管理 |
| 品种 | `CRUD /api/grain-varieties` | 粮食品种字典 |
| 仓号 | `CRUD /api/warehouses` | 仓号字典 |
| 台账 | `CRUD /api/ledger-transactions` | 购销台账，作废接口 |
| 库存 | `GET /api/inventory-balances` | 库存余额 |
| 库存 | `GET /api/inventory-movements` | 库存流水 |
| 结算 | `CRUD /api/settlements` | 结算单，确认/作废 |
| 附件 | `POST /api/subjects/:id/attachments` | 上传附件 (base64) |
| 附件 | `POST /api/ledger-transactions/:id/attachments` | 上传附件 (base64) |
| 日志 | `GET /api/operation-logs` | 操作日志 |
| 系统 | `GET /api/settings` | 系统设置 |

## 架构决策

- **Electron + 本地 API 服务**：前端 SPA 通过 REST API 与本地 Express 服务通信，兼顾 Web 开发效率与桌面应用体验
- **库存同步策略**：修改台账时先冲销旧库存变动再生成新变动，作废时仅冲销，确保库存可追溯
- **结算状态机**：draft → confirmed → voided，已确认不可删除，已作废不可修改
- **单据编号**：数据库序列表 + 日期键原子自增，防止编号重复