OpenVerein

面向注册协会（e.V.）的开源协会管理系统：会员、团体、会费和发票、SEPA 直接借记、会计、日程、邮件、文档和会员门户。你可以自行托管、导出每条记录，也可以通过 REST API 执行所有操作。

许可证：AGPL-3.0。状态：处于早期开发阶段，逐步构建中（参见 openspec/）。

为什么选择 OpenVerein？

• 你的数据由你掌控。 可自托管，支持完整导出，没有订阅陷阱。
• 为德国协会法量身打造。 EÜR、GoBD、SEPA、XRechnung、符合 BMF 模板的捐赠证明、DATEV 导出。
• 所有操作都可通过 API 完成。 界面只使用公开的 /api/v1，并提供 OpenAPI 文档、Webhook 和面向 AI Agent 的 MCP 接入。
• 自由开放。 采用 AGPL-3.0 许可，开放开发，欢迎贡献。

目录

• OpenVerein 的功能
• 试用演示
• 本地启动
• 面向协会
• 连接 Claude Code
• 在服务端运行
• 测试
• 项目结构
• 参与贡献

OpenVerein 的功能

领域	亮点
会员	带日期的分组会员资格、带付款人的家庭和家庭折扣、自定义字段、重复项、保存的视图、批量操作、按年龄自动更换分组、向州体育协会提交会员名册、表彰登记和祝贺邮件、联系记录、数据质量提示、工作时长、会员证明、PDF 和 vCard 格式的名单
财务	带生效日期和年龄分档的会费、每次收取会费前必须预览，并可选择自动生成每月预览、可转为发票的报价、带标准文本和净价或含税价的发票、催款管理及信函、SEPA 直接扣款（用途说明模板）和转账、CAMT 导入及匹配、发出和接收 XRechnung（ZUGFeRD/UBL/CII）、商品目录、将信函合并为一个双面 PDF
账簿	基于收支平衡、仅允许追加的日记账编制收支盈余表（EÜR）（GoBD 固化记录、冲销）、凭证和现金簿、收集并记账银行交易、自定义税率、DATEV 导出、PDF 格式的现金报告、预算与实际对比、志愿者津贴、根据 BMF 模板制作的捐赠和捐赠证明（现金和实物捐赠），可通过邮件或信函发送
协会生活	带接受和拒绝选项的活动、候补名单和用于申请资助的出勤名单、ICS 订阅源和导入、公开日历小组件、带模板和发送记录的邮件、带文件夹权限的文档、库存和借用、投票、任务、会员大会和理事会会议及会议记录
门户	会员自助服务：修改数据、带 GiroCode 的发票、文档、投票、费用报销、为付款人提供家庭代理功能，可按协会和分组启用功能
平台	与分部关联并限制字段访问的角色、财务功能的 TOTP、API 令牌和 OpenAPI、签名 Webhook、后台任务、完整导出、DSGVO 工具、用于安装、备份、恢复和更新的 ovctl

试用演示

无需安装： 公开演示版运行于 **https://klub2.ki-klub-werder.de**。演示版会定期重置，不会发送真实邮件，且只包含虚构数据。

在本地按如下方式载入演示协会：

npm run seed:demo    # lädt den „SV Lindenhof 1921 e.V.“ mit 150 erfundenen Mitgliedern in eine leere Instanz
npm run dev

使用 [email protected] / verein-demo-2026 登录。npm run seed:demo -- --reset 会清空演示实例并重新载入；如果实例中有真实协会，此命令不会对其进行任何操作。

设置 DEMO_MODE=true 后，服务器会自行载入演示数据，并每隔 DEMO_RESET_HOURS（默认值为 24）重置一次。此时服务器不会发送真实邮件，会显示演示横幅，为每个 PDF 添加水印，并锁定账户、角色、API 密钥、上传和导入功能，以便所有人都能使用公开演示版。访问者可以在下次重置前编辑协会设置、文本和会员。会员门户会在屏幕上显示登录码，而不是通过邮件发送。在包含真实协会的实例上，设置 DEMO_MODE=true 的服务器不会启动：

DEMO_MODE=true docker compose --profile app up --build

本地启动

前提条件：Node 24、Docker。

cp .env.example .env
npm install
npm run dev

npm run dev 会在 Docker 中启动 Postgres 和 Mailpit，运行数据库迁移，并在 http://localhost:3300 启动 API、在 http://localhost:5173 启动 Web 应用。首次访问时，请设置你的协会。应用发送的邮件会出现在 Mailpit 中，可通过 http://localhost:18025 查看。

API 参考文档：http://localhost:3300/api/docs（OpenAPI 文档位于 /api/v1/openapi.json）。

在 Docker 中运行完整应用

docker compose --profile app up --build

然后打开 http://localhost:3300。

面向协会

• 财务手册：介绍一个协会年度的各项工作，从会费到税务咨询。
• 理事会与行政管理手册：会员、入会、活动安排、邮件、门户和数据保护。
• 流程文档（模板）：用于填写 GoBD 流程文档的模板。

连接 Claude Code

该插件通过 <club>/mcp 下的远程 MCP 服务，将 Claude Code 连接到协会。你的 Agent 看到和执行的内容，与你在协会管理系统或会员门户中看到和执行的完全一致，不会更多。

1. 在 Claude Code 中安装该插件：

   /plugin marketplace add KI-Klub-Werder-e-V/openverein
   /plugin install openverein@openverein
   

   从 Claude Code 2.1.275 起，也可以一步完成：/plugin install openverein --marketplace KI-Klub-Werder-e-V/openverein。

2. 按提示输入协会地址，例如 https://verein.example.org。若要使用公开演示版，请输入 https://klub2.ki-klub-werder.de。之后可以使用 /plugin configure openverein@openverein 更改地址；更改后请重新登录。在 Shell 中，可以在安装时直接指定地址：claude plugin install openverein@openverein --config club_url=https://verein.example.org。

3. 登录：运行 /mcp，选择 openverein 并完成身份验证。在浏览器中：

   • 会员使用门户中的电子邮件验证码登录
   • 协会管理人员使用常规登录方式和第二因素登录

   登录前，请确认浏览器显示的是协会地址。然后选择“仅阅读”或“阅读和写入”，并授权访问。过程中不会有任何令牌写入文件。

4. 例如，可以询问：“我有哪些发票尚未结清？”或“谁报名参加了周二的训练？”

你可以在设置 → Agent（或门户 → Agent）下查看 Agent 的调用记录，也可以在那里撤销其访问权限。脚本和命令行工具 ov 使用同一页面上的令牌，而非 OAuth。claude.ai 和 ChatGPT 可通过同一地址 <club>/mcp 作为自定义连接器接入。

在服务器上运行

./ovctl install 会使用 Docker Compose 配置 Caddy（HTTPS）、应用和 Postgres；./ovctl backup、restore、update 和 doctor 可确保一切正常运行。详情请见 docs/operations.md。

测试

npm run typecheck && npm run lint
npm test            # Unit- und Integrationstests (braucht den Postgres-Container)
npm run test:e2e    # End-to-End-Tests mit Playwright
npm run validate:xrechnung  # Beispiel-E-Rechnungen durch den offiziellen KoSIT-Validator (braucht Java 17+ oder Docker)

项目结构

• openspec/specs/ 是行为的权威说明，每项能力对应一份规范。每项内容都通过 openspec/changes/ 中的 OpenSpec 变更创建，并在合并后归档。
• src/server/ 是 Fastify API，src/web/ 是 React 应用，src/shared/ 是两者共用的 Schema，migrations/ 是仅向前执行的 SQL 迁移。
• docs/adr/ 存放架构决策，docs/decisions.md 记录较小的决策。
• PRODUCT.md 和 DESIGN.md 描述产品和设计系统。
• android/、ios/、capacitor.config.ts、codemagic.yaml：移动应用会打包 Web 构建版本，详见 docs/mobile.md。

参与贡献

欢迎贡献，包括报告错误、提出功能需求、改进文档或提交代码。

• CONTRIBUTING.md：环境搭建、使用 OpenSpec 的工作方式、规则和 PR 检查清单。
• SECURITY.md：请保密报告安全漏洞，不要将其作为公开 Issue 提交。
• CODE_OF_CONDUCT.md：我们的行为准则。
• Issues：报告错误或提出功能建议。