opensource-loyalty

# 忠诚度交换协议（LIP） 👋 [](https://www.npmjs.com/org/loyalty-interchange) [](LICENSE)      **LIP 是一个开放、厂商中立的忠诚度协议和开发者参考平台，用于构建餐厅、快餐、咖啡、便利店和特许经营等订购系统。** 它提供了从零到忠诚度集成的所有必要组件：规范协议规格、确定性参考引擎、HTTP API、TypeScript SDK、本地管理仪表盘、SQLite 沙盒、Docker 运行时、可运行的示例和黑盒一致性测试。 > [!IMPORTANT] > 客户身份验证故意不在 LIP 交易边界内。应用程序 BFF 集成 Clerk、Auth0 或其他身份提供商，保留商家 API 密钥在服务器端，并将身份验证的客户映射到不透明的 LIP `member_id` 值。LIP 成员不自动成为平台客户。例如，试点应用程序的演示访客可以在该应用程序的 BFF/客户数据层中存在，而无需在托管客户身份平台中进行配置。 📖 **文档： [loyalty-interchange.mintlify.app](https://loyalty-interchange.mintlify.app)** （指南在 [`docs/`](docs/README.md) 中是源代码）。使用 AI 编码代理构建？从 **[使用 AI 入门](#getting-started-with-ai-)** 开始。 ## LIP 的关键功能 ⭐ - 🚀 **轻松设置**：一条命令即可启动本地沙盒（`npm start`），或使用 Docker Compose 自主托管。启动屏幕打印您的管理 URL 和 API 密钥。 - 🔁 **完整的忠诚度生命周期**：会员查找、注册、余额和账本历史。在结账前评估订单，在支付后累积积分，并运行兑换预留、捕获、反向和退款安全调整流程。 - 🍔 **食品服务优先的订单模型**：具有商品、修改器、折扣、费用、税款、小费、付款方式和总金额的餐厅订单。针对柜台、车道、终端、网络、移动设备、取货、送货和餐饮的渠道感知规则。 - 🏪 **特许经营感知范围**：品牌、商家、地点和特许经营者标识，以及产品、类别、标签和行类型赚取排除。 - 🎯 **多种计划模型**：可执行的 **积分**、**访问/印章**、**钱包积分**、**付费会员** 和具有独立赚取、余额、过期、奖励成本和预留的混合多账户计划。 - 📣 **参与平台**：持久化静态或动态细分、计划的奖励活动、幂等钱包发行、奖励草稿 CRUD 和管理中的会员生命周期控制。账本分析、同意过滤的 CRM 导出和签名消息连接器作业包括重试和审计。 - 🛡️ **设计时重试安全**：幂等键、请求上下文、RFC 9457 问题详细信息和部分退款、无效、反转、重复检查和结算语义。 - 🧰 **TypeScript SDK**：具有请求 ID、时间戳、幂等键、精确货币帮助器、食品服务订单构建器和生成的低级 OpenAPI 客户端的惯用领域客户端。 - 🖥️ **本地管理仪表盘**：在 `http://127.0.0.1:3210/admin/` 进行身份验证的仪表盘，用于检查会员和账本活动，以及版本化的计划草稿、验证、实时发布和回滚。 - 🗄️ **持久存储**：默认情况下基于 SQLite 的本地状态，以及规范化、租户范围的 Postgres 表、迁移、乐观修订、咨询事务锁和多实例协议服务的调度器租约。 - ☁️ **云控制平面**：用于组织、项目、区域环境、计划、订阅、配置作业、幂等使用计量和配额的单独 Postgres 支持的管理服务。开放协议和自主托管运行时与此非规范服务保持独立。 - 🔐 **外部身份桥**：在您的 BFF 中验证 Clerk、Auth0 或通用 OIDC 访问令牌，并将提供商身份映射到稳定的客户和 LIP 会员 ID，而无需将凭证或会话移动到忠诚度平台。 - 🧪 **规格和一致性**：OpenAPI 3.1 合同、JSON Schema Draft 2020-12 有效载荷模式、规范生命周期、账户、Webhook 和食品服务配置文件文档，以及您可以针对任何实现运行的黑盒 HTTP 一致性测试。 - 🔧 **包含电池的 CLI**：验证、诊断（`doctor`）、本地服务、模式列出、基准一致性检查和用于云迁移的校验和全状态导出/导入。 - 🤖 **AI 就绪**：可安装的代理技能、官方 MCP 服务器、[`llms.txt`](llms.txt) 和精选提示，以便 Cursor、Claude Code、Codex 等工具正确实现 LIP。 想要了解全貌？查看 [开发者文档](docs/README.md) 以获取全面概述。 ## 如何安装 🚀 ### 使用 AI 入门 🤖 LIP 为 AI 编码代理设置与 Clerk 等平台相同：用于专业知识的技能、用于准确查找的 MCP 服务器和用于代理上下文的紧凑索引。 ```bash # 克隆并安装后（参见下文） npx skills add . ``` 这在您的代理环境中安装了七种技能（`lip`、`lip-cli`、`lip-sdk`、`lip-checkout`、`lip-webhooks`、`lip-bff`、`lip-conformance`）。 然后启用 MCP 服务器。Cursor 可以使用存储库根目录 [`mcp.json`](mcp.json)（设置 → MCP），或直接运行： ```bash npm run mcp ``` | 资源 | 它是什么 | | --- | --- | | [在 AI 中使用 LIP](docs/using-lip-with-ai.md) | 完整的 AI 入门指南 | | [AI 提示](docs/ai-prompts.md) | 用于结账、Webhook、退款等的复制/粘贴提示 | | [`llms.txt`](llms.txt) | 紧凑的存储库索引 - 您的代理首先指向此处 | | [`skills/`](skills/README.md) | 可安装的代理技能 | | [`packages/mcp/`](packages/mcp/) | 官方 MCP 服务器（规范查找、验证、SDK 代码片段） | ### 快速入门 Docker 🐳 要求：Git 和 Docker。 ```bash git clone https://github.com/alvinjchoi/opensource-loyalty.git cd opensource-loyalty docker compose up --build ``` 启动日志打印管理 URL 和管理/API 密钥。在默认的 Compose 环境中，密钥是： ```text lip-dev-key ``` 在 [http://127.0.0.1:3210/admin/](http://127.0.0.1:3210/admin/) 打开管理仪表盘并使用该密钥登录。 > [!TIP] > 如果终端不再可见，请使用 `docker compose logs lip` 从 Docker 日志中读取相同的密钥。 然后在第二个终端中验证 API： ```bash curl http://127.0.0.1:3210/health curl http://127.0.0.1:3210/lip/v1/capabilities \ -H 'Authorization: Bearer lip-dev-key' ``` ### 从源代码安装 🛠️ 要求：Git、Node.js 20.19 或更高版本和 npm。 > [!NOTE] > 该存储库使用具有 `package-lock.json` 的 npm 工作区。pnpm 不是受支持的安装路径。对于干净的锁定文件安装，请使用 `npm ci` 代替 `npm install`。 ```bash git clone https://github.com/alvinjchoi/opensource-loyalty.git cd opensource-loyalty npm install npm start ``` CLI 打印： ```text 管理：http://127.0.0.1:3210/admin/ 管理/API 密钥：lip-dev-key ``` 在第二个终端中，检查服务器并运行基准一致性套件： ```bash npm run lip -- doctor http://127.0.0.1:3210 --api-key lip-dev-key npm run lip -- test http://127.0.0.1:3210 --api-key lip-dev-key ``` 运行完整的 SDK 生命周期 - 注册会员、评估订单、累积积分、预留和捕获奖励、反转它并调整退款订单： ```bash npm run example:sdk ``` ### 您应该看到的内容 ✅ 本地服务器公开： - 管理仪表盘：`http://127.0.0.1:3210/admin/` - 协议 API：`http://127.0.0.1:3210/lip/v1` - 健康检查：`http://127.0.0.1:3210/health` - Prometheus 指标：`http://127.0.0.1:3210/metrics`（需要 Bearer 身份验证） - 发现：`http://127.0.0.1:3210/.well-known/lip` ### 单独运行 API 在您只需要参考 API 和管理应用程序时使用： ```bash npm run lip -- serve ``` 有用选项： ```bash npm run lip -- serve --reset npm run lip -- serve --reset --no-seed npm run lip -- serve --database .lip/another.db npm run lip -- serve --port 4010 --api-key local-dev-key npm run lip -- serve --program ./my-program.json npm run lip -- serve --rate-limit 300 --rate-window-ms 60000 npm run lip -- serve --no-structured-logs ``` `--program` 使用您的 JSON 程序定义（与 `packages/reference/src/config.ts` 中的 `ProgramDefinition` 相同）启动一个空数据库。之后，使用管理配置视图编辑、验证、发布或回滚持久修订而无需重启。演示会员种子在加载自定义程序时被跳过。 ### 自主托管配置 ⚙️ 默认的 Compose 服务在端口 `3210` 上运行参考服务器和管理仪表盘，并将 SQLite 状态存储在命名的 `lip-data` 卷中。使用环境变量配置运行时值： ```bash LIP_API_KEY="replace-with-a-long-local-key" LIP_PORT=3210 LIP_SEED_DEMO=true LIP_RATE_LIMIT_REQUESTS=120 LIP_RATE_LIMIT_WINDOW_MS=60000 LIP_STRUCTURED_LOGS=true docker compose up --build ``` 对于基于 Postgres 的配置文件，请运行 `docker compose --profile postgres up --build`；其 API 默认端口为 `3211`。参见 [PostgreSQL 生产存储](docs/postgres.md)。 要运行端口 `3220` 上的托管服务控制平面基础，请设置至少 16 个字符的 `LIP_CLOUD_API_KEY` 并运行 `docker compose --profile cloud up --build`。参见 [云控制平面](docs/cloud.md)。 将自主托管的程序迁移到另一个 LIP 主机？遵循 [MIGRATION.md](MIGRATION.md)。迁移存档保留会员、余额、不可变的账本历史、开放预留和幂等记录。 身份验证的协议请求根据远程客户端的限制。响应包括 `RateLimit-*` 头部，并在用尽时返回具有 HTTP 429 的 RFC 9457 问题详细信息。CLI 和容器在每个响应时发出一个 JSON `http_request` 记录，而不记录 API 密钥或请求正文。身份验证的 `/metrics` 端点以 Prometheus 文本格式导出请求计数和持续时间摘要。 > [!WARNING] > Postgres 协议运行时在实例之间协调引擎突变。完整的管理服务套件仍然使用基于 SQLite 的扩展存储；生产管理部署必须移植这些存储并添加位置范围。 ### 从 npm 安装 📦 所有软件包都使用 [`@loyalty-interchange`](https://www.npmjs.com/org/loyalty-interchange) 范围发布到 npm 以确保来源。无需克隆即可运行沙盒： ```bash npx @loyalty-interchange/cli serve ``` 或将 SDK 添加到您的应用程序： ```bash npm install @loyalty-interchange/sdk ``` 参见 [发布指南](docs/releasing.md) 以了解如何进行发布和验证。 ## 项目结构 🗂️ ```text |-- apps/ | |-- admin/ # 浏览器管理仪表盘 | `-- cloud/ # 托管云控制平面和管理 API |-- docs/ # 开发者指南和 API 文档 |-- examples/ | `-- typescript/ # 可运行的 SDK 生命周期示例 |-- packages/ | |-- cli/ # CLI：服务、快速启动、验证、医生、一致性 | |-- identity/ # 外部 OIDC 验证和客户/会员映射 | |-- protocol/ # TypeScript 类型、模式、验证、协议合同 | |-- reference/ # 确定性忠诚度引擎和管理快照模型 | |-- sdk/ # 领域 SDK 和生成的低级 OpenAPI 客户端 | |-- server/ # 参考 HTTP 服务器和非规范管理 API | |-- storage/ # 存储适配器接口 | |-- storage-postgres/ # 规范化 Postgres 适配器、迁移、锁、租约 | `-- storage-sqlite/ # 用于本地和单节点的持久 SQLite 适配器 |-- scripts/ # 规范、SDK、示例和软件包验证脚本 |-- spec/ # 规范性散文、OpenAPI、生成的模式和示例 `-- tests/ # 单元、集成和黑盒一致性测试 ``` ## 技术栈 🧱 - **语言：** Node.js 20.19+ 上的 TypeScript - **前端：** React、Vite、Tailwind CSS、lucide-react - **API：** 具有 OpenAPI 3.1 合同的 Node HTTP 服务器 - **云：** 具有 PostgreSQL 控制平面状态的单独 Node 管理 API - **验证：** 通过 TypeBox 的 JSON Schema Draft 2020-12 - **SDK：** 手写的领域客户端加上生成的低级 OpenAPI 客户端 - **存储：** SQLite 沙盒或规范化、租户范围的 PostgreSQL - **测试：** Vitest 和黑盒 HTTP 一致性测试 - **打包：** npm (`@loyalty-interchange/*`，发布时带有来源）和 Docker ## 常用命令 🧑‍💻 ```bash npm start # 启动本地沙盒和管理仪表盘 npm run serve # 相同的沙盒路径，公共命令名称 npm run lip -- doctor # 检查发现、健康状况、身份验证和功能 npm run lip -- test # 运行基准 HTTP 一致性检查 npm run lip -- schemas # 列出支持的 JSON 模式 npm run lip -- validate spec/examples/paid-order.json --schema FoodserviceOrder npm run example:sdk # 运行完整的 TypeScript SDK 生命周期 npm run typecheck # 类型检查所有软件包和管理应用程序 npm test # 运行完整的测试套件 npm run build # 构建 TypeScript 软件包和管理资产 npm run generate # 重新生成模式、OpenAPI 和 SDK 客户端 npm run verify # 完整的本地验证管道 ``` ## 文档 📚 完整文档站点：**[loyalty-interchange.mintlify.app](https://loyalty-interchange.mintlify.app)** 开发者指南： - [入门](docs/getting-started.md) — 从克隆到工作请求的 shortest 路径 - [五分钟快速入门](docs/quickstart.md) — 验证、Docker、重置、种子和一致性详细信息 - [API 端点](docs/api-endpoints.md) — 路由、身份验证、示例、错误、重试和 Webhook - [TypeScript SDK](docs/typescript-sdk.md) — SDK 操作、错误、货币帮助器和订单构建器 - [参考平台](docs/reference-platform.md) — 服务器、管理、存储和实现边界 - [Punchh 兼容性](docs/punchh-compatibility.md) — 迁移覆盖和适配器差距 规范性规格（当文档和生成的工件不一致时为准）： - [规格概述](spec/README.md) - [核心协议](spec/core.md) - [生命周期规则](spec/lifecycle.md) - [账户体验](spec/account-experience.md) - [食品服务配置文件](spec/profiles/foodservice.md) - [Webhook](spec/webhooks.md) - [OpenAPI](spec/openapi.yaml) - [生成的 JSON 模式](spec/schemas) ## 下一步？ 🌟 当前优先级在 [PLAN.md](PLAN.md) 中跟踪。近期关注点： - 尽量减少开发者 onboarding - 基于代码的程序配置草案，带有验证、预览、发布和回滚 - 奖励钱包和奖励管理 API - Webhook 订阅管理 - 异步 Postgres 存储，用于剩余的管理扩展服务 - 云配置工作器、直接 OIDC 验证和 Stripe 计费适配器 - 更多 SDK 示例和机器可读文档 ## 贡献 🤝 欢迎贡献！首先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，在打开拉取请求之前运行 `npm run verify`，并保持协议变更由模式、示例和一致性测试支持。 ## 安全 🛡️ 如果您认为您发现了安全漏洞，请遵循 [SECURITY.md](SECURITY.md) 中的责任披露流程，而不是公开问题。 ## 许可证 📜 该项目根据 [Apache-2.0](LICENSE) 许可。 ## 支持 💬 如果您有任何问题、建议或需要帮助，请 [打开问题](https://github.com/alvinjchoi/opensource-loyalty/issues) — 让我们一起构建开放的忠诚度基础设施！ 💪