# 服务端需求

版本：IB-1.1。适用Node权威业务服务、后台worker及若依管理接入。规则全文见[产品需求](../../docs/product.html)，逐表字段见[数据字典](../../docs/database-dictionary.html)。

## 服务职责和写入边界

Node.js / TypeScript模块化单体拥有玩家、俱乐部、邀请、房间、牌局、钱包、账本及结算核心写入权。REST处理身份、查询和业务提交，WSS处理牌桌动作和推送；两种入口共用业务用例。若依负责独立后台认证、权限与运营流程，通过受认证管理API调用Node，不另建游戏规则或资金事实源。

每桌单写；首期不得在缺乏所有权协议时横向多实例写同桌。关键状态和账务在同一PostgreSQL事务内提交，提交后广播；通知失败重发通知，不重复业务。

## 按领域实施

| 领域 | 服务端必须负责 | 重点拒绝/恢复场景 |
| --- | --- | --- |
| 身份 | 稳定player_id、LOCAL身份、现代口令哈希、登录审计、锁定限流、会话与设备接管 | 伪造user_id、旧generation、客户端角色/余额、重复登录名；昵称允许重复 |
| 组织邀请 | 默认俱乐部、归属历史、ROOM/CLUB四组合邀请、审核和迁移 | 撤销与批准竞争、目标冻结、范围不足、手后迁移、普通玩家自退 |
| 模板房间 | 发布/退役不可变版本、授权白名单、独立规则快照、排期与DRAINING | 未发布或越权开房、开放瞬间权限变化、已关闭桌重入 |
| 座位资产 | 锁统一占用行、15秒预约、买入、补码冻结/应用/释放、换座和离桌 | 抢座、余额竞争、重复买入、补码与清算竞态、孤立冻结 |
| 牌局 | 服务端随机、长短牌规则、发牌烧牌、行动顺序、合法加注、边池、尾分及超时 | 截止时间竞争、动作重放、非本人/非当前回合、他人私牌泄露 |
| 费用结算 | CSV_STANDARD_V2、逐池抽水分配、离座费与豁免、不可变结算 | 同手重复派奖、广播失败重结、重复离座费、重启后状态未知 |
| 钱包账本 | 整数最小单位、有符号零和分录、余额非负约束、幂等、冲正及对账 | 同键异参、跨币平衡、并发负余额、覆盖原单和手改余额 |
| 代理 | 不可变协议、GENERAL默认0%、高精度计提、业务日汇总、迟到重算 | 跨范围查看、重复计提、把应计伪装真实付款、离座费计佣 |
| 统计记录 | 全量保留/归档策略、游标查询、投影截止与完整性、同玩法样本 | 3000手截断、缺数据当零、跨币求和、进行中与已结束混算 |
| 聊天客服 | 消息权限、旁观只读、禁言/屏蔽、ASR草稿、举报证据与公开结果 | 内部备注泄露、私牌直查、原音频超期留存、禁言屏蔽举报 |
| 管理安全 | 动作+对象范围、服务间认证、独立后台账号/TOTP、敏感授权消费及审计 | 伪造来源、跨俱乐部访问、授权过期/撤销、参数变化、重放 |
| worker与运维 | 事务Outbox、可重试投影/导出/过期任务、指标和发布排空 | worker抢桌写权、导出后撤权仍可下载、重试重复记账 |

## 数据库实施约束

应用角色默认无表写权限；通过受限函数执行领域变更，函数必须固定search_path、验证对象范围并最小授权。迁移账号独立，应用账号不能拥有对象或迁移权限。若依不能凭管理身份直接写核心表。

现有V001～V015包含92表、强约束、安全视图、最小种子、post_ledger_transaction及Outbox/代际存储保护；尚未在真实PG16验证。下列业务写入口仍需实现并测试，新增Outbox生产投递、会话代际与TOTP认证消费也属于待实现入口：

- 本地注册/凭据更新/会话创建与接管、失败计数及锁定。
- 座位预约、买入、补码、换座、离桌及房间生命周期。
- submit_hand_action及结算提交、恢复处置和冲正编排。
- 俱乐部/代理迁移、邀请签发审核撤销、模板发布。
- post_commission_attribution、apply_admin_grant及敏感授权消费。
- 私牌工单批准与受限读取、玩家密码重置凭据/消费及BP-32种子。

不得以空函数、ORM直写或临时GRANT绕过。真实环境登记checksum后仅新增更高迁移；对尚未执行的评审基线也应记录变更来源。

## 身份与认证

核心业务只依赖稳定player_id。认证提供者分离LOCAL与后续TELEGRAM；Telegram绑定不得复制玩家、钱包、归属或战绩。口令采用Argon2id等现代实现，库参数和资源成本在工程配置中锁定并验证。凭据、摘要、initData与原始重置令牌不能进入普通日志和导出。

玩家会话最长24h；过期阻止新动作但保留在桌权益。后台空闲15分钟、绝对8小时，轮询不续期。后台密码与玩家密码独立。TOTP按产品规定6位/30秒/前后1步，成功时间步不可跨授权重放。

## 资金和结果不确定性

request_id用于请求幂等，operation_id绑定持久业务结果；同号同参返回原结果，同号异参拒绝。UNKNOWN是结果尚未取得，不是业务失败。按账户UUID排序加锁、同资产分录零和、非负账户不透支。结算后广播失败仅重投Outbox。

房间恢复加载所有权、可信检查点、持久事件及已过期计时。已结算返回原结果；可信未结算继续原手；可信手前快照可按规则作废冲回；无法判断是否提交则冻结核查，不自动退款或再结算。

## 管理功能完整范围

59项BKR均属于后端权限、查询、动作和审计实现要求，见[后台需求目录](../../docs/ops-catalog.html)、[流程状态](../../docs/ops-workflows.html)及[展示字段](../../docs/ops-fields.html)。其中标“建议读模型”的字段仍需查询设计，不表示视图已存在。数据字典中的敏感表不能因为前端有展示字段就开放直接读取。

## API契约交付要求

开发前补齐可校验OpenAPI 3.1与WSS消息契约：认证、对象ID、请求号、金额、版本、错误、限流、恢复、过期与服务认证。接口路径以独立工程契约为准，旧好友房WebSocket消息不自动成为新API。提供正常、权限拒绝、幂等冲突、并发和恢复测试。

## 服务端完成标准

真实PG16迁移和SQL门禁、并发与权限测试通过；固定牌序规则向量与独立守恒检查通过；两真人Web对局、结算、离桌和重启恢复通过。500连接/50桌×8席及性能、安全、备份恢复属于M5发布证据，未测不宣称达标。完整要求见[技术架构](../../docs/architecture.html)及[交付与门禁](../../docs/delivery.html)。

## IB-1.1接缝约束

后台唯一认证与权限事实为 Node/poker.admin_*，若依原生 sys_* 登录在生产禁用；采用架构6.6及数据字典12.10的统一判定。买入必须携带有效reservation_id，过期返回RESERVATION_EXPIRED；重试先返回同request_id原结果，不从VACANT直接买入。WSS代际来自player_session及app_user持久字段，每次动作在事务中复查。TOTP使用严格递增高水位的条件更新，与授权签发同事务。手间处理按架构9.3.1，不凭SETTLED直接启动下一手。
