铆钉台账（Maker Space Ledger）

一个零第三方依赖、本地优先的创客空间工具借还台账。它把“工具在哪、谁在用、何时归还、是否逾期”集中在一张维修台式工作板上，并为关键操作保留只读审计记录。

项目定位：适合个人工作室、校园社团、临时工坊和可信局域网内的流程演示。它不包含生产级身份认证、权限隔离或互联网部署防护，不应直接暴露到公网。

为什么做这个项目

小型创客空间通常不需要一套昂贵的资产平台，却经常需要回答几个现实问题：充电钻被谁拿走了？归还期限到了吗？某次借还是谁登记的？电子表格能记录数据，但很难把“库存状态”和“借还动作”约束为一致的流程。

铆钉台账提供一个可读、可运行的最小实现，也适合作为以下内容的教学样例：

Python 标准库 WSGI 应用的组织方式；
SQLite 事务、约束、部分唯一索引与追加式审计；
无框架前端如何消费 JSON API；
本地优先 Demo 如何明确安全边界。

功能

登记工具：资产编号、名称、分类和备注；
签发借用：借用人、联系方式、用途和归还期限；
确认归还：借用记录与工具状态在同一事务中更新；
自动逾期识别和库存概览；
只增不改的审计记录，数据库触发器阻止更新或删除；
资产编号、名称或分类即时筛选；
移动端可用的工业工牌式响应式界面；
数据默认只写入本机 var/ledger.sqlite3。

技术边界

Python 3.10+
wsgiref.simple_server
sqlite3
原生 HTML、CSS、JavaScript
无 pip、npm、CDN 或外部字体依赖

快速开始

Windows PowerShell

cd maker-space-ledger
.\scripts\run.ps1

macOS / Linux

cd maker-space-ledger
sh scripts/run.sh

也可以直接执行：

python -m app.server

浏览器打开 http://127.0.0.1:8787。首次写入时会自动创建 var/ledger.sqlite3。

配置

应用直接读取进程环境变量，不会自动加载 .env 文件。

变量	默认值	说明
`LEDGER_HOST`	`127.0.0.1`	监听地址；仅在可信网络中才应修改
`LEDGER_PORT`	`8787`	HTTP 端口，范围为 1–65535
`LEDGER_DB_PATH`	`var/ledger.sqlite3`	SQLite 文件位置

示例值见 .env.example。

测试

测试只使用标准库，测试数据写入临时目录：

python -m unittest discover -s tests -v

启动真实 HTTP 子进程并走完核心借还流程：

python scripts/smoke_test.py

覆盖范围包括：

工具创建、编号唯一性和输入长度限制；
借出与归还的状态一致性；
过去的归还期限被拒绝；
审计表不可更新/删除；
首页、健康检查和完整 WSGI 借还流程；
非 JSON 请求和静态目录穿越拦截；
基础安全响应头。

API 概览

方法	路径	用途
`GET`	`/api/health`	健康检查
`GET`	`/api/dashboard`	概览、工具、未归还借用单和审计记录
`POST`	`/api/tools`	登记工具
`POST`	`/api/loans/checkout`	签发借用
`POST`	`/api/loans/{id}/return`	确认归还

写接口只接受 Content-Type: application/json，请求体上限为 64 KiB。字段限制以 app/db.py 中的领域校验为准。

项目结构

maker-space-ledger/
├── app/                 # WSGI 路由与 SQLite 数据层
├── static/              # 无构建步骤的前端资源
├── tests/               # unittest 数据层与 API 测试
├── docs/architecture.md # 架构、事务与安全边界
├── scripts/             # Windows / POSIX 启动入口
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

更完整的设计说明见 docs/architecture.md。

安全说明

项目有参数化 SQL、输入长度/状态校验、静态路径边界检查和基础安全响应头，但没有用户身份、授权、CSRF 防护、TLS、限流或多租户隔离。默认绑定 127.0.0.1 是有意为之。

如果需要跨设备演示，应只在可信局域网短期运行，并由外部反向代理承担 TLS 和访问控制。发现漏洞请参考 SECURITY.md，不要在公开 Issue 中披露可利用细节。

贡献

欢迎改进可访问性、数据迁移、测试和文档。提交前请运行完整测试，并阅读 CONTRIBUTING.md。

许可证

本项目采用 MIT License。