Odo-i Addons

Enterprise Infrastructure & Business Building Blocks for Crystal
开箱即用、无框架绑定、安全合规的企业级 Crystal 基础设施与业务构件单仓

---

💡 为什么选择 Odo Addons？

在构建现代 CRM、全渠道分销、医疗健康等复杂业务系统时，Crystal 生态通常缺乏经过真实生产环境与资金安全检验的标准化构件。Odo Addons 采用 Monorepo 统一研发与演进，提供 60 个相互解耦的高内聚 Shards。

• 🚀 零框架绑定（Zero Framework Lock-in）：所有 Shard 纯标准库实现，不绑定 Kemal、Amber 或 Lucky，可无缝嵌入任何 Crystal 架构。
• 🔒 Fail-Closed 安全哲学：核心敏感数据天然脱敏、异常杜绝泄露 raw body/PII、HMAC 恒定时间比对、防重放与严格签名。
• ⚡ 原子并发与幂等保障：核心资金/异步回调统一接入 CallbackDedup 与分布式租约；延迟队列与预约锁采用原子 Lua 状态机。
• 🎯 强类型与严格精度：金额全局整数（分）计算，规则引擎 AST 保持 64 位大整数不降级，除零/模零严格防御。

---

📦 模块全景图 (Shard Matrix)

每个子目录均为独立可引用的 Shard。状态遵循 稳定 与 可用。

💳 支付与交易结算

🔐 身份、权限与认证

☁️ 通讯、消息与企业协作

🏥 医疗与健康中台

⚙️ 引擎、算法与调度

🛡️ 数据安全、媒体与工具

---

🚀 快速上手 (Quick Start)

1. 在业务项目的 shard.yml 中按需声明依赖

name: my_crm_service
version: 0.1.0

dependencies:
  core:
    path: ../addons/core
  wechat_pay:
    path: ../addons/wechat_pay
  pbac:
    path: ../addons/pbac
  delay_queue:
    path: ../addons/delay_queue

2. 编写业务逻辑

require "wechat_pay"
require "pbac"
require "delay_queue"

# 1. 权限引擎策略判定
policy = Odo::Pbac::Policy.new(
  name: "order_access",
  effect: Odo::Pbac::Effect::Allow,
  actions: ["orders:refund"],
  resources: ["order:*"]
)
ctx = Odo::Pbac::Context.new(action: "orders:refund", resource: "order:1001")
puts "Permission granted: #{policy.evaluate(ctx).allow?}"

# 2. 延迟任务队列
backend = Odo::DelayQueue::MemoryBackend.new
job = Odo::DelayQueue.push(
  topic: "order_timeout",
  payload: %({"order_id": "ORD-2026-999"}),
  delay: 15.minutes,
  backend: backend
)
puts "Enqueued delay job: #{job.id}"

---

🛠️ 本地开发与测试

运行全量测试套件（覆盖全部 60 个 Shards + 消费者跨模块集成测试）：

# 全量测试门禁
bash test/run.sh

# 运行特定 Shard 测试
cd wechat_pay && crystal spec

# 代码格式化
crystal tool format

---

📄 许可证与贡献

• 仓库采用 GNU AGPL v3.0 or later 许可证。
• 开发指南与提交约定参见 AGENT.md。