chiban-org/chiban-oss

项目介绍

Chiban 面向美国小镇的土地利用办公室——通常只有一名书记员、兼职建筑检查员和两个志愿委员会。它把每个地块的记录集中在一处：申请、通知、听证、决定、许可、检查和投诉。居民无需账号即可查看地块历史中的公开部分。

州级规则以「state pack」形式提供：每项期限都带对应的法条，另有通知与决定措辞、上诉路径、建筑规范版本、信息公开豁免和档案保留期限。表单、费用、条件和模板由工作人员在应用内自行修改。数据可按 格式说明 导出为纯文本加原始文件、电子表格和 PDF/A 副本，避免被工具锁定。

先看演示

在线演示运行虚构的 Alder Pond 镇（新罕布什尔州），提供书记员、建筑检查员、委员会成员、申请人、承包商和管理员等角色账号。数据每晚重置且不发邮件，是安装前评估流程最快的方式。

本地运行

前置条件：Node.js 24+、pnpm 9、带 Compose 的 Docker，以及 PATH 中的 Ghostscript 10。OCRmyPDF 和英文 Tesseract 数据只在迁移扫描件时需要。

pnpm install
cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

把生成的密钥填入 .env 中 CHIBAN_SECRET_KEYS 的 k1，然后启动依赖服务、迁移、灌入演示数据并运行应用：

docker compose -f docker-compose.dev.yml up -d --wait
pnpm db:migrate
pnpm storage:init
pnpm db:seed:demo
pnpm dev

另开一个终端运行 pnpm worker；缺少它时邮件会排队、导出不会启动、定时任务不会执行。应用运行在 http://localhost:3000，Mailpit 在 http://localhost:8025 查看外发邮件。设置 ENABLE_DEV_SIGN_IN=true 且 NODE_ENV 非 production 时，http://localhost:3000/dev/sign-in 会列出演示用户，可直接以任意角色登录。

生产部署

自托管指南说明如何在单台 Linux 主机上用 Docker Compose 部署 Caddy、应用、后台 worker、PostgreSQL 加 PostGIS 以及 Garage 对象存储，镜像按 digest 固定。备份、恢复检查、升级、外发邮件和刷卡支付各有单独文档。

使用约束

• 目前只有一个州包：新罕布什尔州（packs/nh）。新增一个州需要实际工作量，州包指南说明了具体内容。
• 支付：仓库不含任何真实支付处理器密钥。Stripe 对接的是无状态 mock，不发 webhook；Clover 适配器尚未在真实商户账户上验证。开发时可启用模拟支付。
• USPS 地址校验是可选的；不配置凭据时地址字段退化为纯文本。每位登录用户每分钟最多 30 次查询，重复地址缓存一天。
• pnpm db:reset:demo 会删除 DATABASE_URL 指向库中的全部表，只能对可丢弃的数据库使用。
• 采用 AGPL-3.0 许可证，若修改后对外提供网络服务需要注意相应义务。

技术栈

Next.js 16 / React 19、tRPC、基于 PostgreSQL 16 和 PostGIS 的 Drizzle ORM、MapLibre 与 PostGIS 提供的矢量瓦片、S3 兼容存储，以及 pg-boss 后台任务。测试使用 Vitest（含针对真实 PostGIS 的集成测试）和 Playwright。

HotRepo 点评

该项目在 2026-11-14 进入 TypeScript 新项目榜，当时 126 星，约一小时窗口内新增 6 星，Fork 数仍为 0。这只是单次快照，不能说明持续热度，也没有讨论记录可供参考。更有价值的观察是适用范围：README 明确说明尚不支持其他州，因此评估重点应放在新罕布什尔州小镇的流程是否与随附州包吻合，而不是总体宣传是否吸引人。