拼好团

FAIRJOIN 是面向固定费用活动的动态同价分摊工具。 组织者提前锁定总预算、成团人数和截止时间；参与者陆续加入后，合约重新计算每人的应摊，原成员自行领取多付的差价，组织者只能按规则收取固定本金。它不需要用发币、积分或补贴制造参与动机。新增成员带来的经济变化，就是产品的反馈：人多了，固定成本没有变，先付款的人也应该少付。当前版本：真实 Monad 测试网产品。 主活动为「GPT Pro 20x 拼车」费用分摊演示。FJUSD 是项目发行的无价值测试代币，不是美元或 Circle USDC。FAIRJOIN 不提供会员、账号、密码或使用额度；20x 不是 20 个席位。产品当前没有平台服务费，网络费另计。从这里开始产品与差异 · 核心机制 · 完整功能 · 技术栈 · 架构与可靠性 · 真实证据 · 市场价值 · 商业前景 · 快速启动 · 安全边界01 / 我们解决的不是除法，而是退差价的执行问题设想一个固定预算 200 的团。最初四人各付 50，后来第五人加入，每人只需要承担 40。算出这个答案很容易。难的是：谁重新核对名单？谁通知前四个人？差价何时退？组织者能否把后续收到的钱直接留下？群聊里的承诺、付款截图和表格，是否始终指向同一本账？FAIRJOIN 把这个变化落实为三项可检查的规则：对谁产品承诺实现方式先加入的成员后来有人加入，我也享受更低应摊按当前人数计算应摊，差额成为原钱包的可领取余额后加入的成员我支付加入时确认的报价，而不是先多付再追退款带人数版本、条款哈希、最高支付额和有效期的链上报价活动组织者可以收取事先约定的总预算，但不能把成员差价算成收入合约限制本金提取时机、金额、收款地址和次数它与常见方案的关注点不同下表比较的是产品类别的设计重心，不是对每一个具体竞品的功能断言。方案类别主要回答的问题FAIRJOIN 的不同切入点普通转账 / 收款链接钱怎样从 A 到 B？新成员付款后，旧成员的应摊和领取权如何变化？AA 记账 / 费用台账谁最终欠谁多少钱？不只记录应退额，也提供按规则提取资金的执行路径达标众筹是否筹齐目标金额？达标不是结束；截止前继续加入的人，还会降低已有成员的应摊优惠券 / 邀请返利怎样用营销预算拉新？差价来自固定费用被更多人分摊，不依赖额外奖励池通用托管资金先放在哪里？托管之外，定义人数变化、退款归属和固定本金的具体规则FAIRJOIN 的核心不是「付款后播放一个动画」，而是一次真实付款改变多人的资金权利。02 / 一次加入，让整团的账一起变化主案例：GPT Pro 20x 拼车这个案例使用 200 FJUSD 的固定预算解释机制。OpenAI 的 Pro 档位说明可作为费用场景背景，但费用分摊本身不构成供应商对共享账号或转售权益的许可。¹时刻人数本次付款当前每人应摊原成员新增可领取组织者本金上限前四人完成报名4每人 50500200第五人加入5新人支付 4040原四人各 10200一位原成员领取5无新增报名付款40该成员领取 10200所有金额单位均为无价值 FJUSD。可领取不等于已经到账；成员需要使用原付款钱包主动调用 claim。新人支付的 40，恰好对应前四人各 10 的差价。不是新人替平台支付营销费，不是协议凭空铸造奖励，也不是组织者多赚 40。精确到最小单位的分摊规则合约只处理整数。令 C 为总预算的最小单位整数、n 为当前有效人数、i 为成员在有效名单中的零起始位置：基础份额 q = floor(C / n) 余数 r = C mod n 成员应摊 = q + (i < r ? 1 : 0) 已成团成员可领取差价 = 累计已付 − 累计已退 − 当前应摊 取消或未成团失败后的可领取退款 = 累计已付 − 累计已退 余数按有效成员顺序分配，每人最多相差一个最小单位，即 0.000001 个六位精度代币。这样所有人的应摊加起来恰好等于总预算，而不是把浮点误差留给最后一个人。成团前，每位预报名成员支付 ceil(C / minimum)；达到最低人数后进入动态分摊。成团后新加入者位于名单末尾，其报价为 floor(C / (n + 1))。规则见 _share、_quote 与 _claimable。为什么成团后不能单独退出？在成团前，个人可以退出并拿回尚未退回的预报名款。成团后则锁定个人退出：否则一人退出会提高剩余成员的应摊，迫使其他人补款，也可能破坏已经领取的差价。这是一个明确的产品取舍：用成团后的承诺稳定性，换取先加入者的应摊不会因他人退出而反弹。 组织者在截止前仍可以取消整团，成员按剩余净付款领取退款。03 / 不只有成功按钮：完整的活动资金生命周期上图是用户旅程。链上实际状态为 OPEN / CANCELLED / FAILED / SETTLED，成团与否由独立的 funded 字段表示；退款完成和本金到账由账本字段表示，不是额外伪造的状态枚举。结算后尚未领取的成员差价仍可领取。能力当前实现关键边界创建活动固定费用、最低人数、上限、截止时间、开始时间、收款地址和公开描述创建后没有修改条款的接口条款确认termsHash 把网络、合约、活动身份与规则绑定换链、换合约或换规则，不能沿用旧确认精确授权授权本次所需额度；授权后重新报价和确认报名授权成功不等于报名成功预报名与成团达到最低人数后自动标记为已成团成团前不允许组织者提取本金动态加入人数变化后计算新应摊和原成员差价满员、过期、重复成员、旧报价均会被拒绝主动领取差价和退款回到调用者的原付款钱包不提供由前端指定任意收款人的接口成团前退出退出并退回净付款，名单压缩重新加入保留累计支付与退款历史整团取消截止前由组织者取消已领过差价的人只领取剩余退款，不重复退款未成团失败截止未成团，成员可领取净付款claim 可同时触发失败状态确认，不必等组织者处理截止结算任何人可调用 finalize 确认到期状态页面倒计时结束不等于链上已写入结算固定本金提取已成团且到期后，组织者提取一次固定本金转入创建时锁定的收款地址，不侵占成员差价公开收据无钱包查看、刷新重开、JSON 导出与打印资金信息来自链上读取，不依赖付款页面缓存多活动展示搜索、分类，以及不同筹款和退款状态当前目录是八个测试示例，不是商家供给或用户增长数据中英文界面语言切换和持久化偏好用户提交的活动描述不冒充自动翻译交易恢复拒签、超时、丢失哈希、替换交易和旧记录恢复结果未知时不自动再次付款04 / 技术栈：把复杂性留在边界，把主路径做短版本对应本仓库的依赖声明与锁文件，不表示这些依赖是当前最新版本。层次技术在项目中的实际职责消费者界面React 19.1.1活动、发团管理、交易确认与公开收据类型系统TypeScript 5.9.2严格模式；部署身份、报价、成员账本和恢复状态的类型边界构建Vite 7.1.7本地开发、生产打包与静态客户端输出钱包连接RainbowKit 2.2.8 + wagmi 2.17.0钱包选择、账户连接、网络切换和钱包写入链交互viem 2.37.9ABI 编码、合约读取、交易回执、日志与 RPC 传输查询基础TanStack Query 5.90.2钱包集成的查询上下文；关键资金快照另行绑定区块合约Solidity，solc 0.8.30资金分摊、参与权限、条款锁定、退款和本金结算合约基础库OpenZeppelin Contracts 5.4.0SafeERC20、ReentrancyGuard 与测试 ERC-20链上环境Monad Testnet · 10143实际部署、付款、领取和可公开核查的交易边缘交付Cloudflare Workers + Wrangler 4.129.0静态应用、健康接口和可选演示媒体流服务回归测试Node.js assert + esbuild + Ganache 7.9.2真实合约本地执行、实际控制器隔离测试与流式响应测试持续集成GitHub Actions干净安装、仓库内容检查、测试、构建和 ABI 一致性检查没有把 AI 模型塞进退款决策，也没有让一个中心化服务替用户签名。这里的规则是确定性的，应该由可检查的代码执行。05 / 架构：轻客户端，确定性资金规则5.1 一个业务合约，不是一套多余的服务体系Pinhaotuan.sol 承担核心资金规则。DemoUSD.sol 是公开测试网水龙头代币，TestUSDC.sol 是用于模拟转账失败和手续费行为的本地测试夹具，不是三个需要相互协调的业务系统。主路径不依赖中心化业务数据库、运营方私钥、机器人代签、后台退款队列或私有价格计算 API。资金在合约中按规则保管，而不是一直留在用户钱包，也不是没有任何托管或技术风险。5.2 同一区块快照，不拼接「看起来差不多」的数字src/lib/chain.ts 对活动、成员和报价指定相同的 blockNumber。否则，高频出块时可能出现人数来自前一区块、报价来自后一区块、收据又展示旧余额的混合状态。历史日志采用增量扫描、重叠区间、去重和并发任务合并；RPC 限制查询区间时可拆分读取。历史没有追完时，界面报告同步范围，不把缺失日志解释成「从未发生」。可见资金和名额以合约快照为准，不靠日志追赶速度决定能否正确显示。5.3 读可以切换 RPC，付款不能盲目重试配置中的 RPC 会先验证网络身份，不符合当前链的节点不能混入读池。客户端同时检查业务合约代码、固定 token 地址和六位精度。备用 RPC 用于只读故障切换。写入交给用户钱包；收到超时、连接中断或未知结果时，恢复原交易，而不是把同一笔付款再发送一次。5.4 报价是一个有边界的承诺join 验证四个用户确认条件：join( uint256 id, uint64 expectedRosterVersion, uint256 maxAmount, uint64 quoteExpiry, bytes32 expectedTermsHash )人数版本解决并发名额竞争；最高付款额约束支出；过期时间拒绝陈旧报价；条款哈希确保确认的仍是同一个活动。合约也会再次检查活动状态、截止时间、人数上限和重复报名。5.5 恢复是产品的一部分，不是异常日志useAppController.ts、pending.ts 和 receiptVerification.ts 共同处理交易恢复：先匹配网络、发送者、nonce、目标合约、calldata、原生币金额和回执，再判断业务结果。手工输入但暂时查不到的哈希会被保留；缺少 nonce 的旧记录不能直接当成「未广播」解除等待；同 nonce 的取消交易不会被当成报名成功。已经成功上链、但区块末状态核对异常的交易会进入明确的人工复核提示，不显示正常业务成功，也不永久锁住应用。测试币领取按本笔交易的铸币事件核验，避免同一区块其他资金流动干扰余额差判断。5.6 小规模限制是显式设计，而不是隐藏假设当前合约的约束如下：参数约束总预算1–1,000 个六位精度资产单位最低成团人数至少 2 人，且不高于人数上限人数上限最多 12 人报名截止创建时至少在当前区块时间之后 10 分钟活动开始至少在报名截止之后 30 分钟公开描述UTF-8 字节长度 1–2,048固定资产构造时验证代码与 6 位精度，部署后不可更换升级 / 管理员提款核心合约没有代理升级或全局任意提款接口单成员份额和领取额使用常数次算术；成团前退出需要压缩名单，工作量随人数线性增长，但人数被限制在 12 以内。更大规模、更多资产和可升级策略属于未来版本设计，不能把当前限制写成已经支持无限扩展。06 / 不止有界面：已经发生过的链上结果以下为 2026 年 9 月 5 日保存的真实测试网演示记录，不代表后来所有时刻的实时余额。完整证据索引见 public/proof/settlement.json。项目值网络Monad Testnet，Chain ID 10143核心业务合约0xf6ac320e7c4e865a72c588c89be23ff12ca543c3FJUSD 测试代币0xa9df142d14218cc99f3068cbadc1d1965f7623b7主案例Group 11 · GPT Pro 20x 拼车第五人实际付款40.000000 FJUSD一位原成员实际领取10.000000 FJUSD该原钱包记录余额690.000000 → 700.000000 FJUSD该笔活动净承担50 − 10 = 40 FJUSD加入交易0x1be1efb349173d80e4c36ca387ff83e4c01b914bcd0095e38cebe7b583f387ef 领取交易0x6feae5199f7f80fdcf21a95308689f49fe603be4d0a236e23f4c130aa3fc1925 打开实际领取交易 · 无钱包查看公开收据这组结果使用受控测试账户，验证的是资金机制，不是用户采用、营业收入或独立安全审计。测试网可能重置；重新核查时以网络身份、合约代码和实际可查询状态为准。²07 / 市场价值：把组织成本和信任成本一起降下来我们更关心谁已经在反复付这笔钱，而不是先画一张巨大的市场规模图。目标场景同时具备三个条件：总费用相对固定；参与人数逐步确定；组织者反复开展类似活动。在这里，人数变化不仅影响报名表，还影响每个人实际应该承担的费用。第一批用户：已经有活动、有社群、有固定支出的组织者切入场景可分摊的固定成本参与者获得的价值组织者获得的价值AI 共创小班明确约定的活动与工具预算后续新增成员后，不必再次催差价用统一规则解释预算、报名和退款摄影棚 / 排练室 / 小型场地固定时段的场地费用知道人数变化如何影响自己承担的金额减少重复核账和逐人返款的操作工作坊 / 小型训练营场地、讲师或固定材料预算在报名时看到完整条件和退款路径把资金规则与活动说明一起固定社群线下活动固定组织预算公开收据降低信息不对称下一场活动复用相同的协作模式这是目标用户与价值假设，而不是已经签约的商家清单。按人头增加的餐食、门票或授权席位不能直接套进固定成本模型；混合成本需要先明确哪些部分能够分摊。对参与者：先支持，不必承担「先付的人更亏」的心理负担用户不只需要知道当前价格，还需要知道后面人数增加时自己会怎样被对待。FAIRJOIN 让这种待遇在付款前可见，并在合约里有明确执行路径。对组织者：从反复解释规则，转向把活动办好潜在价值不是「少做一次除法」，而是减少名单变化后的重复核账、返款操作、询问和争议。可量化的验证应比较组织者每场的管理时间、退款处理次数和重复使用意愿，而不是把功能数量当成商业价值。对产品增长：新增参与者可以让已有参与者直接受益组织者发起固定费用活动 ↓ 第一批成员报名 ↓ 成员邀请更多人加入 ↓ 已有成员应摊降低，差价可领取 ↓ 资金结果可核对，组织者更容易解释下一场活动 这是待验证的增长机制，不是已经证明的病毒传播。它的吸引力在于：邀请带来的好处与真实费用变化一致，不需要持续发放平台补贴。它的限制也很明确：人数上限、活动容量和服务质量不能为了低价被忽略。08 / 商业前景：从一次拼团，走向组织者的结算基础工具定位：用户使用简单，组织者获得持续价值FAIRJOIN 的消费者入口是一场具体活动，而更可能持续产生需求的主体，是反复组织活动的人。我们的商业化思路因此不是向退款金额偷偷抽成，而是验证组织者是否愿意为长期的协作与管理能力付费。路径未来可提供的付费价值当前状态必须先验证什么组织者专业版活动模板、团队管理、跨活动汇总、预算与对账工作流商业化假设，未上线收费同一组织者是否持续重复使用，节省时间是否足够明显嵌入式分摊组件让社群、活动或场地平台接入同一结算规则产品方向，未发布 SDK / 商用 API是否存在愿意集成、愿意付费且要求清晰的合作方品牌化 / 白标交付专属活动入口、组织流程配置和技术支持产品方向，未签约客户的个性化需求是否可复用，而不是每单重做当前平台服务费为零。 上表不是已实现功能清单，也不是收入预测。我们希望建立的壁垒，不是「别人不会写这个除法」单纯的分摊公式很容易复制。值得长期投入的是：完整生命周期的正确性、失败后的可靠恢复、组织者反复使用的流程、参与者对规则的理解，以及外部平台的集成成本。公开合约和可复现测试有利于别人检查规则；它们并不自动形成商业壁垒。真正的竞争力要通过真实活动证明：在不增加过多钱包门槛的前提下，用户是否更愿意先报名，组织者是否更愿意下次再用。商业验证应看哪些指标？假设应观察的指标为什么重要解决了重复问题组织者下一场活动复用率、每月重复发团数区分一次性新鲜感与持续工作流减少了协调成本每场管理时间、人工退款次数、退款咨询量衡量是否真正替组织者省事不妨碍付款连接钱包到实际报名的完成率、拒签和未知交易比例防止技术方案本身制造更大阻力成员理解机制首次差价领取完成率、误解与争议原因公平必须被理解，不能只存在于代码里存在商业模式愿意付费的组织者数量、试用转化和留存防止把交易笔数直接当成收入能力目前没有这些指标的真实经营结果，不能用受控钱包代替用户样本。仓库包含默认关闭、本地可选的交互记录模块，没有建成中心化增长分析平台。扩展顺序先验证窄场景里的重复使用，再考虑专业工具和嵌入式分发；先完成安全评估与资产适配，再讨论主网。多资产、Gas 代付、账户抽象和外部履约集成都值得研究，但它们不是当前版本已经交付的能力。09 / 为什么是 Monad，而不是「任意转账页面加钱包」？Monad 的 EVM 与 Ethereum RPC 兼容性，使项目能够使用 Solidity、OpenZeppelin、viem 和现有钱包工具来实现真实结算，而不是额外创造一套用户必须理解的支付技术。³FAIRJOIN 需要的不是链上存一张付款截图，而是让参与顺序、应摊变化、成员领取权和组织者本金在同一套可执行状态中协调。网络确认体验对消费者操作很重要，但本项目没有把底层链公布的吞吐量当成自己的应用性能测试，也不保证每次钱包确认都在固定秒数内完成。产品的主要创新是分摊规则和用户体验，Monad 是本版实际使用的执行基础；我们不宣称这套机制在其他 EVM 环境中技术上不可实现。10 / 从一个干净仓库启动环境要求Node.js 22.12 或更高版本，以及 npm。仓库提供 .nvmrc；依赖版本由 package-lock.json 固定。运行已有测试网客户端不需要私钥、数据库、TTS Key 或视频文件。git clone https://github.com/veithly/fairjoin.git cd fairjoin npm ci npm run dev打开 http://localhost:5173。默认使用已提交的 public/deployment.json 连接现有 Monad 测试网部署。只读浏览无需连接钱包。写入需要自己的测试钱包、支付网络费的测试 MON，以及 FJUSD。FJUSD 水龙头每个钱包每 24 小时可领取一次 1,000 测试币；这是代币夹具规则，不代表任何财务价值。测试 MON 获取方式以 Monad 官方测试网说明 为准。可选钱包连接配置cp .env.example .env配置 VITE_WALLETCONNECT_PROJECT_ID 可启用 WalletConnect；留空时仍可使用支持的注入式钱包。VITE_ 开头的变量会用于前端构建，任何私钥都不能放进这类变量。构建与检查npm run check:repo # 检查Git提交内容，拦截媒体、内部文件和常见凭据 npm test # 合约、恢复工具、实际控制器和Worker单元测试 npm run build # TypeScript检查 + Vite生产构建 npm run preview # 预览生产客户端可以分别运行：npm run contracts:compile npm run test:contracts npm run test:recovery npm run test:worker完全本地的合约与客户端# 终端一：启动仅监听本机的开发链 npm run chain # 终端二：编译、部署本地夹具并启动界面 npm run deploy:local npm run dev本地链使用 31337，与 Monad 测试网明确区分。deploy:local 只接受本机开发链，使用该链的解锁测试账户；它不读取测试网私钥，也不访问真实资产。该命令会修改本地 public/deployment.json。恢复仓库默认配置可以执行 git restore public/deployment.json，但先确认没有需要保留的自定义部署修改。本地目录里的链上示例编号不能当成测试网编号。部署自己的静态客户端npm run build npx wrangler login npx wrangler deploy --name your-fairjoin-demo部署使用你的 Cloudflare 账号与实际服务配额；请选择自己的 Worker 名称，不要覆盖不相关项目。Workers 支持静态资源与可选 Worker 逻辑组合托管。⁴新部署默认仍连接配置中的现有测试网合约，不会自动部署新合约。换用自己的合约必须同时更新网络、业务合约、固定 token、部署区块以及示例目录的对应身份。不要只替换一个地址。本仓库不包含录屏、PPT、音轨或视频分片。README 的演示链接指向独立托管的成品；worker/media.ts 保留的是通用流式服务代码与单元测试，没有媒体时不影响核心客户端，直接请求未配置的媒体流会明确失败。11 / 可复现验证：按风险分层，而不是报一个神奇通过率检查层已有验证内容运行方式Solidity 行为11 组行为测试，覆盖退款、截止、竞争、权限、舍入和回滚npm run test:contracts随机账本序列16 个种子的资金守恒与应摊单调性检查，包含在合约测试中npm run test:contracts恢复工具28 项记录校验与有界扫描检查npm run test:recovery实际控制器10 项隔离回归；直接加载实际控制器，不是重新写一套影子实现npm run test:recoveryWorker 媒体流19 项完整流、范围请求、ETag、坏清单与截断流检查npm run test:worker类型与生产构建严格 TypeScript 检查及生产打包npm run build仓库卫生白名单、文件类型、体积和常见凭据模式检查npm run check:repo控制器隔离测试使用明确的 React、RPC 和钱包替身，不对外广播交易。Solidity 测试执行编译后的合约，但运行于本地 EVM；只有证据章节中的交易属于真实外部测试网行为。这里的检查不等同于完整形式化证明、跨浏览器认证或独立安全审计。CI 使用与本地一致的 npm 命令，并校验重新编译后的 ABI 没有意外漂移。安装采用锁文件驱动的 npm ci。⁵12 / 仓库结构：只放产品和工程必需品fairjoin/ ├── contracts/ # 核心业务合约与两个明确命名的测试代币 ├── src/ │ ├── components/ # 活动、发团、收据、交易确认等界面 │ ├── hooks/ # 实际交易控制器 │ ├── lib/ # 链上快照、恢复、校验、语言与可选本地记录 │ ├── generated/abi.ts # 客户端必需ABI，可从合约重新生成 │ └── i18n/ # 英文语言资源 ├── public/ │ ├── deployment.json # 非敏感的测试网部署身份 │ ├── catalog.json # 示例目录；资金值仍从合约读取 │ └── proof/settlement.json # 精简的公开交易证据，不含录屏日志 ├── worker/ # 边缘入口和可选媒体流逻辑 ├── scripts/ # 仅编译、本地启动、测试和仓库检查 ├── .github/workflows/ci.yml # 自动检查，不自动签名或部署 ├── SECURITY.md # 资产风险与漏洞反馈边界 ├── CONTRIBUTING.md # 开发和提交约定 ├── .env.example # 空值配置示例，不含秘密 └── README.md 录屏、截图、音轨、PPT、私钥、代理会话、研究过程、浏览器夹具、缓存和构建目录不进入 Git。必要测试代码不依赖这些私有文件。检查由 .gitignore 白名单和 CI 双重执行，但任何自动扫描都不能替代提交前人工核对。13 / 信任边界：哪些由代码保证，哪些仍由现实世界决定资金规则可检查，活动履约不会因为上链而自动可靠。 当前合约在已成团且报名截止后允许组织者提取本金，并不等到活动举办完毕或用户验收。startsAt 是公开条款，不是交付证明。项目不提供争议仲裁、服务质量担保、法币结算、税务处理或供应商授权。参与地址、活动描述与交易是公开数据；不要把密码、联系方式等不应公开的信息写入链上描述。前端仅做本地可选交互记录，并不意味着 RPC、钱包服务或托管服务无法观察网络请求。SafeERC20、重入保护、转账前后余额核验和资金守恒测试是防护措施，不是无漏洞承诺。核心合约使用固定资产；带转账手续费等非标准行为会被余额核验拒绝，不能据此宣称兼容任意 ERC-20。尚未开展：独立安全审计、真实组织者经营试点、主网发布。 使用无价值测试资产验证流程；不要把真实资金转入测试合约，也不要通过直接转币代替 join。误转资产不会自动获得名额或退款权利。