Web3 交易系统
原始验证资料

coverage.html

原始资料 · reports/evidence-v0.5/coverage.html · 以可阅读文本展示,HTML 与脚本不会在页面中执行。

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>backend: Go Coverage Report</title>
    <style>
      body {
        background: black;
        color: rgb(80, 80, 80);
      }
      body, pre, #legend span {
        font-family: Menlo, monospace;
        font-weight: bold;
      }
      #topbar {
        background: black;
        position: fixed;
        top: 0; left: 0; right: 0;
        height: 42px;
        border-bottom: 1px solid rgb(80, 80, 80);
      }
      #content {
        margin-top: 50px;
      }
      #nav, #legend {
        float: left;
        margin-left: 10px;
      }
      #legend {
        margin-top: 12px;
      }
      #nav {
        margin-top: 10px;
      }
      #legend span {
        margin: 0 5px;
      }
      .cov0 { color: rgb(192, 0, 0) }
.cov1 { color: rgb(128, 128, 128) }
.cov2 { color: rgb(116, 140, 131) }
.cov3 { color: rgb(104, 152, 134) }
.cov4 { color: rgb(92, 164, 137) }
.cov5 { color: rgb(80, 176, 140) }
.cov6 { color: rgb(68, 188, 143) }
.cov7 { color: rgb(56, 200, 146) }
.cov8 { color: rgb(44, 212, 149) }
.cov9 { color: rgb(32, 224, 152) }
.cov10 { color: rgb(20, 236, 155) }

    </style>
  </head>
  <body>
    <div id="topbar">
      <div id="nav">
        <select id="files">
        
        <option value="file0">web3exchange/backend/admin_query.go (84.4%)</option>
        
        <option value="file1">web3exchange/backend/auth.go (83.2%)</option>
        
        <option value="file2">web3exchange/backend/engine.go (97.9%)</option>
        
        <option value="file3">web3exchange/backend/http.go (78.2%)</option>
        
        <option value="file4">web3exchange/backend/maintenance.go (74.9%)</option>
        
        <option value="file5">web3exchange/backend/market_query.go (81.9%)</option>
        
        <option value="file6">web3exchange/backend/observability.go (100.0%)</option>
        
        <option value="file7">web3exchange/backend/query.go (85.3%)</option>
        
        <option value="file8">web3exchange/backend/runtime.go (84.9%)</option>
        
        <option value="file9">web3exchange/backend/store.go (73.7%)</option>
        
        <option value="file10">web3exchange/backend/types.go (100.0%)</option>
        
        <option value="file11">web3exchange/chaintrade/chain.go (1.0%)</option>
        
        <option value="file12">web3exchange/chaintrade/engine.go (85.6%)</option>
        
        <option value="file13">web3exchange/chaintrade/history.go (77.8%)</option>
        
        <option value="file14">web3exchange/chaintrade/http.go (61.2%)</option>
        
        <option value="file15">web3exchange/chaintrade/index.go (70.8%)</option>
        
        <option value="file16">web3exchange/chaintrade/middleware.go (30.6%)</option>
        
        <option value="file17">web3exchange/chaintrade/observability.go (36.4%)</option>
        
        <option value="file18">web3exchange/chaintrade/reconcile.go (64.8%)</option>
        
        <option value="file19">web3exchange/chaintrade/store.go (74.6%)</option>
        
        <option value="file20">web3exchange/chaintrade/tasks.go (56.5%)</option>
        
        <option value="file21">web3exchange/chaintrade/types.go (76.3%)</option>
        
        <option value="file22">web3exchange/cmd/exchangectl/main.go (73.7%)</option>
        
        <option value="file23">web3exchange/cmd/loadcheck/main.go (17.8%)</option>
        
        <option value="file24">web3exchange/cmd/server/main.go (41.9%)</option>
        
        <option value="file25">web3exchange/cmd/web3server/main.go (0.0%)</option>
        
        </select>
      </div>
      <div id="legend">
        <span>not tracked</span>
      
        <span class="cov0">not covered</span>
        <span class="cov8">covered</span>
      
      </div>
    </div>
    <div id="content">
    
    <pre class="file" id="file0" style="display: none">package backend

// 管理查询在认证/投影外围分页,不读取核心状态。两个审计来源各有稳定水位,不能冒充跨库事务。
import (
        "bytes"
        "context"
        "encoding/base64"
        "encoding/json"
        "fmt"
        "io"
)

// UserPage 使用 SQLite rowid 创建顺序,不以秒级 created_at 排序导致同秒用户遗漏。
// 用户不可删除,rowid 是内部分页位置;API 身份仍用安全随机 ID。
type UserPage struct {
        DatasetID  string `json:"dataset_id"`
        Items      []User `json:"items"`
        NextCursor string `json:"next_cursor,omitempty"`
}

// Audit 是管理动作视图;资金来源显示首次业务结果和重复状态,避免把请求日志都画成注资成功。
type Audit struct {
        ActorID   string `json:"actor_id"`
        TargetID  string `json:"target_id"`
        Action    string `json:"action"`
        Timestamp string `json:"timestamp"`
        Source    string `json:"source"`
        Seq       string `json:"seq,omitempty"`
        Asset     string `json:"asset,omitempty"`
        Amount    string `json:"amount,omitempty"`
        Reason    string `json:"reason,omitempty"`
        Code      string `json:"code,omitempty"`
        Replayed  bool   `json:"replayed"`
}

// AuditPage 保留来源各自水位,分页按 AUTH 前缀、CREDIT 后缀分组遍历,不宣称全局时间排序。
type AuditPage struct {
        DatasetID  string  `json:"dataset_id"`
        AppliedSeq string  `json:"applied_seq"`
        Items      []Audit `json:"items"`
        NextCursor string  `json:"next_cursor,omitempty"`
}

// adminCursor 固定管理员身份、数据集和来源上界;不是权限凭证。
// phase=0 遍历认证审计,phase=1 遍历资金投影,两者各自 seek。
// Actor 绑定该管理员,但 Base64 无签名/加密;授权始终靠 HTTP 会话,游标不是 token。
type adminCursor struct {
        Version     int    `json:"v"`
        Dataset     string `json:"dataset"`
        Actor       string `json:"actor"`
        Kind        string `json:"kind"`
        Upper       int64  `json:"upper"`
        CreditUpper int64  `json:"credit_upper"`
        Before      int64  `json:"before"`
        Phase       int    `json:"phase"`
}

// readAdminCursor 限制长度、未知字段、尾随值、身份及非负边界;授权仍由 protected(true) 强制执行。
func readAdminCursor(raw, dataset, actor, kind string) (adminCursor, error) <span class="cov8" title="1">{
        c := adminCursor{Version: 1, Dataset: dataset, Actor: actor, Kind: kind}
        if raw == "" </span><span class="cov8" title="1">{
                return c, nil
        }</span>
        <span class="cov8" title="1">if len(raw) &gt; 1024 </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">b, err := base64.RawURLEncoding.DecodeString(raw)
        if err != nil </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">d := json.NewDecoder(bytes.NewReader(b))
        d.DisallowUnknownFields()
        if d.Decode(&amp;c) != nil || d.Decode(new(any)) != io.EOF || c.Version != 1 || c.Dataset != dataset || c.Actor != actor || c.Kind != kind || c.Upper &lt; 0 || c.CreditUpper &lt; 0 || c.Before &lt; 0 || c.Phase &lt; 0 || c.Phase &gt; 1 </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">if kind == "users" &amp;&amp; (c.Phase != 0 || c.CreditUpper != 0) </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">boundary := c.Upper
        if c.Phase == 1 </span><span class="cov8" title="1">{
                boundary = c.CreditUpper
        }</span>
        <span class="cov8" title="1">if c.Before &gt; boundary &amp;&amp; c.Before-boundary &gt; 1 </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">return c, nil</span>
}

// adminCursorString 只序列化固定字符串/整数,不包含凭证或 SQL 指令。
func adminCursorString(c adminCursor) string <span class="cov8" title="1">{
        raw, _ := json.Marshal(c)
        return base64.RawURLEncoding.EncodeToString(raw)
}</span>

// UsersPage 首屏固定 rowid 上界,新增用户不混入继续翻页;状态仍为该页当前版本。
// 用户无删除接口,rowid 可作创建顺序;不要改成秒级 created_at 或把随机身份 ID 当顺序。
func (s *Store) UsersPage(ctx context.Context, actor string, limit int, raw string) (UserPage, error) <span class="cov8" title="1">{
        p := UserPage{DatasetID: s.DatasetID, Items: []User{}}
        if limit &lt; 1 || limit &gt; 100 </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">c, err := readAdminCursor(raw, s.DatasetID, actor, "users")
        if err != nil </span><span class="cov8" title="1">{
                return p, err
        }</span>
        <span class="cov8" title="1">tx, err := s.Auth.BeginTx(ctx, nil)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var upper int64
        if err = tx.QueryRow("SELECT COALESCE(MAX(rowid),0) FROM users").Scan(&amp;upper); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">if raw == "" </span><span class="cov8" title="1">{
                c.Upper = upper
                c.Before = upper + 1
        }</span> else<span class="cov8" title="1"> if c.Upper &gt; upper </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">rows, err := tx.Query("SELECT rowid,id,email,role,disabled,created_at FROM users WHERE rowid&lt;=? AND rowid&lt;? ORDER BY rowid DESC LIMIT ?", c.Upper, c.Before, limit+1)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">var last int64
        more := false
        for rows.Next() </span><span class="cov8" title="1">{
                var row int64
                var u User
                if err = rows.Scan(&amp;row, &amp;u.ID, &amp;u.Email, &amp;u.Role, &amp;u.Disabled, &amp;u.CreatedAt); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if len(p.Items) == limit </span><span class="cov8" title="1">{
                        more = true
                        break</span>
                }
                <span class="cov8" title="1">p.Items = append(p.Items, u)
                last = row</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">if more </span><span class="cov8" title="1">{
                c.Before = last
                p.NextCursor = adminCursorString(c)
        }</span>
        <span class="cov8" title="1">return p, tx.Commit()</span>
}

// AuditPageFor 先遍历认证审计,再遍历投影中的管理员 CREDIT。
// 首屏分别获取 auth ID 上界和投影水位;不读取 writer 正在使用的 journal 连接。
// 资金结果来自同一投影事务,故每条 CREDIT 都有确定执行结论,不误把未执行日志当成功。
func (s *Store) AuditPageFor(ctx context.Context, actor string, limit int, raw string) (AuditPage, error) <span class="cov8" title="1">{
        p := AuditPage{DatasetID: s.DatasetID, Items: []Audit{}}
        if limit &lt; 1 || limit &gt; 100 </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">c, err := readAdminCursor(raw, s.DatasetID, actor, "audit")
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">authTx, err := s.Auth.BeginTx(ctx, nil)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer authTx.Rollback()
        var upper int64
        if err = authTx.QueryRow("SELECT COALESCE(MAX(id),0) FROM auth_audit").Scan(&amp;upper); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">views, seq, err := s.projectionRead(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer views.Rollback()
        p.AppliedSeq = seqString(seq)
        if raw == "" </span><span class="cov8" title="1">{
                c.Upper = upper
                c.CreditUpper = seq
                c.Before = upper + 1
        }</span> else<span class="cov8" title="1"> if c.Upper &gt; upper || c.CreditUpper &gt; seq </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">remaining := limit + 1
        if c.Phase == 0 </span><span class="cov8" title="1">{
                rows, err := authTx.Query("SELECT id,actor_id,target_id,action,timestamp FROM auth_audit WHERE id&lt;=? AND id&lt;? ORDER BY id DESC LIMIT ?", c.Upper, c.Before, remaining)
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                        var id int64
                        var a Audit
                        a.Source = "AUTH"
                        if err = rows.Scan(&amp;id, &amp;a.ActorID, &amp;a.TargetID, &amp;a.Action, &amp;a.Timestamp); err != nil </span><span class="cov0" title="0">{
                                break</span>
                        }
                        <span class="cov8" title="1">a.Seq = seqString(id)
                        p.Items = append(p.Items, a)</span>
                }
                <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                        err = rows.Err()
                }</span>
                <span class="cov8" title="1">rows.Close()
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">if len(p.Items) &lt; remaining </span><span class="cov8" title="1">{
                        c.Phase = 1
                        c.Before = c.CreditUpper + 1
                }</span>
        }
        <span class="cov8" title="1">if c.Phase == 1 &amp;&amp; len(p.Items) &lt; remaining </span><span class="cov8" title="1">{
                rows, err := views.Query("SELECT seq,payload FROM credit_audit WHERE seq&lt;=? AND seq&lt;? ORDER BY seq DESC LIMIT ?", c.CreditUpper, c.Before, remaining-len(p.Items))
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                        var seq int64
                        var raw string
                        var a Audit
                        if err = rows.Scan(&amp;seq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                                break</span>
                        }
                        <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;a); err != nil </span><span class="cov0" title="0">{
                                break</span>
                        }
                        <span class="cov8" title="1">p.Items = append(p.Items, a)</span>
                }
                <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                        err = rows.Err()
                }</span>
                <span class="cov8" title="1">rows.Close()
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
        }
        <span class="cov8" title="1">if len(p.Items) &gt; limit </span><span class="cov8" title="1">{
                p.Items = p.Items[:limit]
                last := p.Items[limit-1]
                if last.Source == "AUTH" </span><span class="cov8" title="1">{
                        c.Phase = 0
                }</span> else<span class="cov8" title="1"> {
                        c.Phase = 1
                }</span>
                <span class="cov8" title="1">var before int64
                if _, err = fmt.Sscan(last.Seq, &amp;before); err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">c.Before = before
                p.NextCursor = adminCursorString(c)</span>
        }
        <span class="cov8" title="1">if err = authTx.Commit(); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">return p, views.Commit()</span>
}
</pre>
    
    <pre class="file" id="file1" style="display: none">package backend

// 认证与角色属于外围身份域:密码慢哈希、随机凭证、绝对时间和 SQL 不进入撮合核心。
// 注册身份提交与初始化 CREDIT 不跨库原子;登录可用保留幂等键补齐资金。见 docs/auth-design.md。

import (
        "context"
        "crypto/rand"
        "crypto/sha256"
        "database/sql"
        "encoding/hex"
        "errors"
        "fmt"
        "net/mail"
        "strings"
        "time"

        "golang.org/x/crypto/bcrypt"
)

// ErrCredentials 合并邮箱不存在、密码错误和停用等登录拒绝,避免直接透露账户状态。
var ErrCredentials = errors.New("credentials invalid")

// ErrEmailTaken 表示注册邮箱冲突,交由 HTTP 映射为 409。
var ErrEmailTaken = errors.New("email already registered")

// randomToken 使用密码学随机源生成 256 位凭证,也用于不可预测用户 ID。
// 随机源失败返回 error,不降级为 math/rand;随机数只在认证外围生成。
func randomToken() (string, error) <span class="cov8" title="1">{
        b := make([]byte, 32)
        if _, err := rand.Read(b); err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">return hex.EncodeToString(b), nil</span>
}

// tokenHash 仅持久化会话 token 的 SHA256 摘要,原 token 只进入 HttpOnly Cookie。
// 高熵随机 token 可直接摘要;用户密码必须用带盐的慢哈希,不能采用此函数。
func tokenHash(token string) string <span class="cov8" title="1">{
        x := sha256.Sum256([]byte(token))
        return hex.EncodeToString(x[:])
}</span>

// normalizeEmail 采用本项目约定的去空格/小写规范化,并拒绝带展示名称的地址。
// 数据库 UNIQUE 保证规范邮箱唯一;这只是格式校验,尚无邮箱所有权验证。
func normalizeEmail(s string) (string, error) <span class="cov8" title="1">{
        s = strings.ToLower(strings.TrimSpace(s))
        if len(s) &gt; 254 </span><span class="cov0" title="0">{
                return "", ErrCredentials
        }</span>
        <span class="cov8" title="1">a, err := mail.ParseAddress(s)
        if err != nil || a.Address != s || !strings.Contains(s, "@") </span><span class="cov8" title="1">{
                return "", ErrCredentials
        }</span>
        <span class="cov8" title="1">return s, nil</span>
}

// validPassword 按 UTF-8 字节数限制 12–72;bcrypt 上限是字节而非字符,避免截断。
func validPassword(p string) bool <span class="cov8" title="1">{ return len(p) &gt;= 12 &amp;&amp; len(p) &lt;= 72 }</span>

// UserByEmail 仅供认证内部读取身份及密码摘要;公开 User 不包含 hash。
func (s *Store) UserByEmail(ctx context.Context, email string) (User, string, error) <span class="cov8" title="1">{
        var u User
        var hash string
        err := s.Auth.QueryRowContext(ctx, "SELECT id,email,role,disabled,created_at,password_hash FROM users WHERE email=?", email).Scan(&amp;u.ID, &amp;u.Email, &amp;u.Role, &amp;u.Disabled, &amp;u.CreatedAt, &amp;hash)
        return u, hash, err
}</span>

// CreateUser 校验并 bcrypt 加盐哈希,再写入规范邮箱与随机用户 ID。
// role 来自可信调用者:公开注册固定 USER,启动 bootstrap 固定 ADMIN。
// 唯一约束处理并发注册冲突;认证提交与模拟资金初始化属于不同数据域。
func (s *Store) CreateUser(ctx context.Context, email, password, role string) (User, error) <span class="cov8" title="1">{
        return s.createUser(ctx, email, password, role, 12)
}</span>

// createUser 共享身份持久化与 bcrypt 流程;密码下限只由可信初始化入口选择。
// 公开注册与常规管理员固定 12,本地演示管理员允许 8;72 字节上限始终保留。
func (s *Store) createUser(ctx context.Context, email, password, role string, minimum int) (User, error) <span class="cov8" title="1">{
        var u User
        email, err := normalizeEmail(email)
        if err != nil || len(password) &lt; minimum || len(password) &gt; 72 </span><span class="cov8" title="1">{
                return u, fmt.Errorf("邮箱或密码无效,密码需 %d–72 字节", minimum)
        }</span>
        <span class="cov8" title="1">hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
        if err != nil </span><span class="cov0" title="0">{
                return u, err
        }</span>
        <span class="cov8" title="1">id, err := randomToken()
        if err != nil </span><span class="cov0" title="0">{
                return u, err
        }</span>
        <span class="cov8" title="1">u = User{ID: id, Email: email, Role: role, CreatedAt: time.Now().UTC().Format(time.RFC3339)}
        _, err = s.Auth.ExecContext(ctx, "INSERT INTO users(id,email,password_hash,role,created_at) VALUES(?,?,?,?,?)", id, email, string(hash), role, u.CreatedAt)
        if err != nil </span><span class="cov8" title="1">{
                var exists int
                if s.Auth.QueryRowContext(ctx, "SELECT 1 FROM users WHERE email=?", email).Scan(&amp;exists) == nil </span><span class="cov8" title="1">{
                        return User{}, ErrEmailTaken
                }</span>
                <span class="cov0" title="0">return User{}, err</span>
        }
        <span class="cov8" title="1">return u, nil</span>
}

// BootstrapAdmin 只在启动配置中初始化管理员;无内置密码或公开创建管理员接口。
// 已有 ADMIN 原样返回,不重置密码;已有 USER 直接拒绝,防止配置导致意外提权。
// 该分支也不验证传入密码是否匹配;环境变量改密码不是密码重置接口。
func (s *Store) BootstrapAdmin(ctx context.Context, email, password string) (User, error) <span class="cov8" title="1">{
        return s.bootstrapAdmin(ctx, email, password, 12)
}</span>

// LocalAdminEmail 将本地账号映射为内部邮箱身份,保持 User/API/数据库邮箱契约。
// 仅允许 3–32 位 ASCII 字母数字/下划线/横线,不能把任意字符串变成管理员邮箱。
func LocalAdminEmail(name string) (string, error) <span class="cov8" title="1">{
        if len(name) &lt; 3 || len(name) &gt; 32 </span><span class="cov8" title="1">{
                return "", fmt.Errorf("local admin name must contain 3–32 ASCII characters")
        }</span>
        <span class="cov8" title="1">for _, c := range name </span><span class="cov8" title="1">{
                if !(c &gt;= 'a' &amp;&amp; c &lt;= 'z' || c &gt;= 'A' &amp;&amp; c &lt;= 'Z' || c &gt;= '0' &amp;&amp; c &lt;= '9' || c == '_' || c == '-') </span><span class="cov8" title="1">{
                        return "", fmt.Errorf("invalid local admin name")
                }</span>
        }
        <span class="cov8" title="1">return strings.ToLower(name) + "@localhost", nil</span>
}

// BootstrapLocalAdmin 仅供明确启用的本机演示入口使用,支持指定的 8–72 字节密码。
// 服务装配必须先验证回环监听;HTTP 注册和常规 BootstrapAdmin 不调用此方法。
// 同样拒绝将已存在 USER 提权,保留已存在 ADMIN 的密码与身份。
func (s *Store) BootstrapLocalAdmin(ctx context.Context, name, password string) (User, error) <span class="cov8" title="1">{
        email, err := LocalAdminEmail(name)
        if err != nil </span><span class="cov0" title="0">{
                return User{}, err
        }</span>
        <span class="cov8" title="1">return s.bootstrapAdmin(ctx, email, password, 8)</span>
}

// bootstrapAdmin 保持“只首次创建”的语义;最低密码长度不会重置已有身份。
func (s *Store) bootstrapAdmin(ctx context.Context, email, password string, minimum int) (User, error) <span class="cov8" title="1">{
        email, err := normalizeEmail(email)
        if err != nil </span><span class="cov0" title="0">{
                return User{}, err
        }</span>
        <span class="cov8" title="1">u, _, err := s.UserByEmail(ctx, email)
        if err == nil </span><span class="cov8" title="1">{
                if u.Role != "ADMIN" </span><span class="cov8" title="1">{
                        return User{}, fmt.Errorf("bootstrap email belongs to a regular user")
                }</span>
                <span class="cov8" title="1">return u, nil</span>
        }
        <span class="cov8" title="1">if err != sql.ErrNoRows </span><span class="cov0" title="0">{
                return User{}, err
        }</span>
        <span class="cov8" title="1">return s.createUser(ctx, email, password, "ADMIN", minimum)</span>
}

// Login 对存在用户执行 bcrypt 校验,不存在用户也执行同 cost 的占位哈希比较。
// 占位计算减轻简单的不存在用户计时差异,不保证严格常数时间登录。
// 停用用户即使密码正确仍拒绝;昂贵计算由 HTTP authSlots 限制并发。
func (s *Store) Login(ctx context.Context, email, password string) (User, error) <span class="cov8" title="1">{
        email, err := normalizeEmail(email)
        if err != nil </span><span class="cov8" title="1">{
                return User{}, ErrCredentials
        }</span>
        <span class="cov8" title="1">u, hash, err := s.UserByEmail(ctx, email)
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                hash = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
        }</span> else<span class="cov8" title="1"> if err != nil </span><span class="cov0" title="0">{
                return User{}, err
        }</span>
        <span class="cov8" title="1">compare := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
        if err != nil || compare != nil || u.Disabled </span><span class="cov8" title="1">{
                return User{}, ErrCredentials
        }</span>
        <span class="cov8" title="1">return u, nil</span>
}

// NewSession 生成独立 session/CSRF 凭证,事务清理过期会话并写入 24h 会话。
// 仅返回一次原始 token;数据库存 tokenHash。身份 Cookie 与 CSRF token 分工不同。
// CSRF 原值在认证库保存供比较;24h 是绝对期限,Session 查询不更新 expires_at。
// 过期凭证立即不再有效,物理记录由后续 NewSession 清理,不需定时器进入核心。
func (s *Store) NewSession(ctx context.Context, userID string) (string, string, error) <span class="cov8" title="1">{
        token, err := randomToken()
        if err != nil </span><span class="cov0" title="0">{
                return "", "", err
        }</span>
        <span class="cov8" title="1">csrf, err := randomToken()
        if err != nil </span><span class="cov0" title="0">{
                return "", "", err
        }</span>
        <span class="cov8" title="1">tx, err := s.Auth.BeginTx(ctx, nil)
        if err != nil </span><span class="cov0" title="0">{
                return "", "", err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        if _, err = tx.Exec("DELETE FROM sessions WHERE expires_at&lt;=?", time.Now().Unix()); err != nil </span><span class="cov0" title="0">{
                return "", "", err
        }</span>
        <span class="cov8" title="1">if _, err = tx.Exec("INSERT INTO sessions VALUES(?,?,?,?)", tokenHash(token), userID, csrf, time.Now().Add(24*time.Hour).Unix()); err != nil </span><span class="cov0" title="0">{
                return "", "", err
        }</span>
        <span class="cov8" title="1">return token, csrf, tx.Commit()</span>
}

// Session 每次校验有效期并 JOIN 最新角色/停用状态,不信任客户端声称的角色。
// 停用后删会话并在查询中要求 disabled=0,恢复启用也不会复活旧会话。
func (s *Store) Session(ctx context.Context, token string) (User, string, error) <span class="cov8" title="1">{
        var u User
        var csrf string
        err := s.Auth.QueryRowContext(ctx, "SELECT u.id,u.email,u.role,u.disabled,u.created_at,s.csrf FROM sessions s JOIN users u ON u.id=s.user_id WHERE s.token_hash=? AND s.expires_at&gt;? AND u.disabled=0", tokenHash(token), time.Now().Unix()).Scan(&amp;u.ID, &amp;u.Email, &amp;u.Role, &amp;u.Disabled, &amp;u.CreatedAt, &amp;csrf)
        return u, csrf, err
}</span>

// SetDisabled 将 USER 状态变更、停用时撤销会话、操作审计放在同一认证事务。
// 管理员不能通过此接口停用;actor 来自已鉴权会话。
// 这是访问控制,已受理业务和已有挂单不会自动撤销,不能当作原子资金冻结。
func (s *Store) SetDisabled(ctx context.Context, actor, id string, disabled bool) error <span class="cov8" title="1">{
        tx, err := s.Auth.BeginTx(ctx, nil)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var role string
        if err = tx.QueryRow("SELECT role FROM users WHERE id=?", id).Scan(&amp;role); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if role == "ADMIN" </span><span class="cov8" title="1">{
                return fmt.Errorf("管理员账号不能通过该接口停用")
        }</span>
        <span class="cov8" title="1">if _, err = tx.Exec("UPDATE users SET disabled=? WHERE id=?", disabled, id); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if disabled </span><span class="cov8" title="1">{
                if _, err = tx.Exec("DELETE FROM sessions WHERE user_id=?", id); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">if _, err = tx.Exec("INSERT INTO auth_audit(actor_id,target_id,action,timestamp) VALUES(?,?,?,?)", actor, id, fmt.Sprintf("DISABLED=%t", disabled), time.Now().UTC().Format(time.RFC3339)); err != nil </span><span class="cov8" title="1">{
                return err
        }</span>
        <span class="cov8" title="1">return tx.Commit()</span>
}
</pre>
    
    <pre class="file" id="file2" style="display: none">package backend

// 本文件只做内存领域运算;并发/持久化协议见 runtime.go 与 docs/architecture.md。
import (
        "container/list"
        "fmt"
        "sort"

        "github.com/emirpasic/gods/trees/redblacktree"
        "github.com/shopspring/decimal"
)

// priceLevel 是一个价格档:树定位价格,双向链表维护同价 FIFO。
// 字段和链表只由核心修改;档内数量由订单余量表达。
type priceLevel struct {
        price  decimal.Decimal
        orders *list.List
}

// orderRef 反向定位挂单及其链表节点,撤单不必遍历整档。
// 链表删除为 O(1),删除空价档还需 O(log P) 树操作,P 为价档数。
type orderRef struct {
        order *Order
        level *priceLevel
        node  *list.Element
}

// remembered 保存首次请求的摘要及结果快照,支持同键同内容重放。
// 当前去重记录不淘汰,长期运行的内存增长是明确的后续治理项。
type remembered struct {
        hash   string
        result Result
}

// Engine 独占树、链表、全部订单、余额、去重表及业务序号。
// 禁止外围读取这些可变对象;仅允许启动重放或唯一核心 goroutine 调用 Apply。
// 最优买/卖档缓存使 bestOpposite 为 O(1),空档删除时再从树更新缓存。
// 本实现采用 LMAX 单写者思想和有界 Go channel,并非移植 Disruptor 环形缓冲实现。
type Engine struct {
        bids, asks       *redblacktree.Tree
        active           map[string]*orderRef  // 仅活动单;节点用于 O(1) 同档删除,终态从这里移除。
        orders           map[string]*Order     // 保留全部历史订单,活动预算不限制该表长期增长。
        balances         map[string]*Balance   // account:asset 到核心可变原件;返回前必须值复制。
        dedupe           map[string]remembered // account:key;首次成功或拒绝均记录,不按 TTL 淘汰。
        seq              int64                 // 最后 Apply 的日志位置;拒绝/重试也推进,不能只按成交递增。
        bestBid, bestAsk *priceLevel
}

// NewEngine 创建空核心;初始化资金也必须以 CREDIT 命令进入日志。
// 树键为价格 × 100 的整数 ticks,受价格两位小数和上限约束,可安全放入 int64。
func NewEngine() *Engine <span class="cov8" title="1">{
        cmp := func(a, b interface{}) int </span><span class="cov8" title="1">{
                x, y := a.(int64), b.(int64)
                if x &lt; y </span><span class="cov8" title="1">{
                        return -1
                }</span>
                <span class="cov8" title="1">if x &gt; y </span><span class="cov8" title="1">{
                        return 1
                }</span>
                <span class="cov8" title="1">return 0</span>
        }
        <span class="cov8" title="1">return &amp;Engine{bids: redblacktree.NewWith(cmp), asks: redblacktree.NewWith(cmp), active: map[string]*orderRef{}, orders: map[string]*Order{}, balances: map[string]*Balance{}, dedupe: map[string]remembered{}}</span>
}

// balance 懒创建账户资产余额;返回值属于核心,不得逃逸到外围共享。
func (e *Engine) balance(account, asset string) *Balance <span class="cov8" title="1">{
        k := account + ":" + asset
        b := e.balances[k]
        if b == nil </span><span class="cov8" title="1">{
                b = &amp;Balance{AccountID: account, Asset: asset, Available: "0", Frozen: "0"}
                e.balances[k] = b
        }</span>
        <span class="cov8" title="1">return b</span>
}

// move 使用 decimal 更新余额并追加同样的分录,保证投影与审计可解释。
// 调用者必须事先完成余额/订单校验;资金计算阶段不再接受可恢复的部分失败。
func (e *Engine) move(r *Result, account, asset string, available, frozen decimal.Decimal, reason string) <span class="cov8" title="1">{
        b := e.balance(account, asset)
        b.Available = dec(b.Available).Add(available).String()
        b.Frozen = dec(b.Frozen).Add(frozen).String()
        r.Entries = append(r.Entries, Entry{account, asset, available.String(), frozen.String(), reason})
}</span>

// Apply 消费连续的已持久化命令,返回业务结果及独立投影副本。
// 普通余额不足、撤他人单、非法参数均通过 Code 返回;序号断裂是系统错误。
// 同账户同键同摘要只取首次结果,不重复冻结、成交或注资;不同摘要拒绝。
// 包括业务拒绝在内的首次结果都会记入去重表,重试不能改变首次结论。
func (e *Engine) Apply(c Command) Result <span class="cov8" title="1">{
        // 即使是业务拒绝或幂等重试,也消费一个日志位置;不能跳过已提交输入。
        if c.Seq != e.seq+1 </span><span class="cov0" title="0">{
                panic("non-contiguous command sequence")</span>
        }
        <span class="cov8" title="1">e.seq = c.Seq
        r := Result{ProcessedSeq: seqString(c.Seq), ResultSeq: seqString(c.Seq), Orders: []Order{}, Balances: []Balance{}, Trades: []Trade{}, Entries: []Entry{}}
        k := c.AccountID + ":" + c.Key
        hash := c.PayloadHash
        if prev, ok := e.dedupe[k]; ok </span><span class="cov8" title="1">{
                if prev.hash != hash </span><span class="cov8" title="1">{
                        r.Code = "IDEMPOTENCY_CONFLICT"
                        r.Message = "幂等键对应不同请求"
                        return r
                }</span>
                <span class="cov8" title="1">r.ResultSeq = prev.result.ResultSeq
                r.Code = prev.result.Code
                r.Message = prev.result.Message
                r.Replayed = true
                if prev.result.Order != nil </span><span class="cov8" title="1">{
                        copy := *prev.result.Order
                        r.Order = &amp;copy
                }</span>
                <span class="cov8" title="1">return r</span>
        }
        <span class="cov8" title="1">changed := map[string]*Order{}
        switch c.Kind </span>{
        case "CREDIT":<span class="cov8" title="1">
                amount, ok := parseAmount(c.Amount, 6, "1000000000000", true)
                if c.Asset == "ETH" </span><span class="cov8" title="1">{
                        amount, ok = parseAmount(c.Amount, 4, "1000000", true)
                }</span>
                <span class="cov8" title="1">if !ok || (c.Asset != "ETH" &amp;&amp; c.Asset != "USDT") </span><span class="cov8" title="1">{
                        r.Code = "INVALID_AMOUNT"
                        r.Message = "资金参数无效"
                        break</span>
                }
                <span class="cov8" title="1">e.move(&amp;r, c.AccountID, c.Asset, amount, decimal.Zero, "CREDIT")</span>
        case "CANCEL":<span class="cov8" title="1">
                o := e.orders[c.OrderID]
                if o == nil </span><span class="cov8" title="1">{
                        r.Code = "ORDER_NOT_FOUND"
                        r.Message = "订单不存在"
                        break</span>
                }
                <span class="cov8" title="1">if o.AccountID != c.AccountID </span><span class="cov8" title="1">{
                        r.Code = "FORBIDDEN"
                        r.Message = "只能撤销自己的订单"
                        break</span>
                }
                <span class="cov8" title="1">ref := e.active[o.ID]
                if ref == nil </span><span class="cov8" title="1">{
                        r.Code = "ORDER_TERMINAL"
                        r.Message = "订单已结束"
                        break</span>
                }
                <span class="cov8" title="1">e.release(&amp;r, o, dec(o.Remaining), "CANCEL")
                o.Canceled = dec(o.Canceled).Add(dec(o.Remaining)).String()
                o.Remaining = "0"
                o.Status = "CANCELED"
                o.Reason = "USER_CANCELED"
                e.remove(ref)
                changed[o.ID] = o
                r.Order = o</span>
        case "PLACE":<span class="cov8" title="1">
                e.place(c, &amp;r, changed)</span>
        default:<span class="cov8" title="1">
                r.Code = "INVALID_COMMAND"
                r.Message = "无效命令"</span>
        }
        <span class="cov8" title="1">for _, o := range changed </span><span class="cov8" title="1">{
                r.Orders = append(r.Orders, *o)
        }</span>
        // 只排序本命令改变的订单,消除 map 遍历随机顺序;不对整个订单簿排序。
        <span class="cov8" title="1">sort.Slice(r.Orders, func(i, j int) bool </span><span class="cov8" title="1">{ return r.Orders[i].Seq &lt; r.Orders[j].Seq }</span>)
        <span class="cov8" title="1">seen := map[string]bool{}
        for _, v := range r.Entries </span><span class="cov8" title="1">{
                bk := v.AccountID + ":" + v.Asset
                if !seen[bk] </span><span class="cov8" title="1">{
                        r.Balances = append(r.Balances, *e.balances[bk])
                        seen[bk] = true
                }</span>
        }
        <span class="cov8" title="1">if r.Order != nil </span><span class="cov8" title="1">{
                // 摘离核心可变指针:后续成交/撤单不能改变已返回或已记忆的首次响应。
                copy := *r.Order
                r.Order = &amp;copy
        }</span>
        <span class="cov8" title="1">saved := Result{ResultSeq: r.ResultSeq, Code: r.Code, Message: r.Message, Order: r.Order}
        // 首次结果归核心去重表所有,不能与外围拿到的 r.Order 共用指针。
        // 即使外围修改响应快照,也不能改变后续原键确认的业务结论。
        if r.Order != nil </span><span class="cov8" title="1">{
                copy := *r.Order
                saved.Order = &amp;copy
        }</span>
        <span class="cov8" title="1">e.dedupe[k] = remembered{hash, saved}
        return r</span>
}

// opposite 返回待成交的对手方向价树,仅用于有序预扫描。
func (e *Engine) opposite(side string) *redblacktree.Tree <span class="cov8" title="1">{
        if side == "BUY" </span><span class="cov8" title="1">{
                return e.asks
        }</span>
        <span class="cov8" title="1">return e.bids</span>
}

// bestOpposite 直接读取最优对手价缓存;不扫描全簿或在查询时重新排序。
func (e *Engine) bestOpposite(side string) *priceLevel <span class="cov8" title="1">{
        if side == "BUY" </span><span class="cov8" title="1">{
                return e.bestAsk
        }</span>
        <span class="cov8" title="1">return e.bestBid</span>
}

// crosses 判断对手价格是否符合限价/保护价:买价不能高于上限,卖价不能低于下限。
func crosses(side string, p, limit decimal.Decimal) bool <span class="cov8" title="1">{
        if side == "BUY" </span><span class="cov8" title="1">{
                return p.LessThanOrEqual(limit)
        }</span>
        <span class="cov8" title="1">return p.GreaterThanOrEqual(limit)</span>
}

// place 先校验参数、资金和最大成交工作量,再冻结并按价格时间优先撮合。
// MARKET 也必须提供保护价且使用 IOC,资金预留因此有明确上限。
// 遇到同账户 maker 使用 cancel_taker:保留 maker,取消当前 taker 的剩余量。
// LIMIT GTC 未成交余量挂簿;IOC/受保护市价单余量释放,无流动性可返回零成交 CANCELED。
func (e *Engine) place(c Command, r *Result, changed map[string]*Order) <span class="cov8" title="1">{
        p, pok := parseAmount(c.Price, 2, "1000000000000", true)
        q, qok := parseAmount(c.Quantity, 4, "1000000", true)
        if !pok || !qok || (c.Side != "BUY" &amp;&amp; c.Side != "SELL") || (c.Type != "LIMIT" &amp;&amp; c.Type != "MARKET") || (c.TIF != "GTC" &amp;&amp; c.TIF != "IOC") || (c.Type == "MARKET" &amp;&amp; c.TIF != "IOC") </span><span class="cov8" title="1">{
                r.Code = "INVALID_ORDER"
                r.Message = "订单参数无效"
                return
        }</span>
        <span class="cov8" title="1">if len(e.active) &gt;= 100000 </span><span class="cov0" title="0">{
                r.Code = "ORDER_LIMIT"
                r.Message = "活动订单达到上限"
                return
        }</span>
        <span class="cov8" title="1">asset := "ETH"
        reserve := q
        if c.Side == "BUY" </span><span class="cov8" title="1">{
                asset = "USDT"
                reserve = p.Mul(q)
        }</span>
        <span class="cov8" title="1">if dec(e.balance(c.AccountID, asset).Available).LessThan(reserve) </span><span class="cov8" title="1">{
                r.Code = "INSUFFICIENT_BALANCE"
                r.Message = asset + " 可用余额不足"
                return
        }</span>
        // 在冻结/撮合之前预扫描实际可能成交的 maker,超过 1024 笔整体拒绝。
        // 避免先成交一部分才发现超限而需要回滚;预扫描与真正撮合采用相同停止规则。
        // 预扫描会再次遍历有限成交范围,换取每个输入有明确的工作量上限。
        <span class="cov8" title="1">left := q
        matches := 0
        tree := e.opposite(c.Side)
        it := tree.Iterator()
        if c.Side == "SELL" </span><span class="cov8" title="1">{
                it.End()
        }</span>
        <span class="cov8" title="1">for </span><span class="cov8" title="1">{
                var next bool
                if c.Side == "BUY" </span><span class="cov8" title="1">{
                        next = it.Next()
                }</span> else<span class="cov8" title="1"> {
                        next = it.Prev()
                }</span>
                <span class="cov8" title="1">if !next || left.IsZero() </span><span class="cov8" title="1">{
                        break</span>
                }
                <span class="cov8" title="1">l := it.Value().(*priceLevel)
                if !crosses(c.Side, l.price, p) </span><span class="cov8" title="1">{
                        break</span>
                }
                <span class="cov8" title="1">stop := false
                for n := l.orders.Front(); n != nil &amp;&amp; !left.IsZero(); n = n.Next() </span><span class="cov8" title="1">{
                        o := n.Value.(*Order)
                        if o.AccountID == c.AccountID </span><span class="cov8" title="1">{
                                stop = true
                                break</span>
                        }
                        <span class="cov8" title="1">matches++
                        if matches &gt; 1024 </span><span class="cov8" title="1">{
                                r.Code = "MATCH_LIMIT_EXCEEDED"
                                r.Message = "单笔成交数量过多"
                                return
                        }</span>
                        <span class="cov8" title="1">left = left.Sub(decimal.Min(left, dec(o.Remaining)))</span>
                }
                <span class="cov8" title="1">if stop </span><span class="cov8" title="1">{
                        break</span>
                }
        }
        <span class="cov8" title="1">o := &amp;Order{ID: seqString(c.Seq), AccountID: c.AccountID, Side: c.Side, Type: c.Type, TIF: c.TIF, Price: p.String(), Quantity: q.String(), Remaining: q.String(), Filled: "0", Canceled: "0", Status: "OPEN", CreatedAt: c.Timestamp, Seq: c.Seq}
        e.orders[o.ID] = o
        changed[o.ID] = o
        r.Order = o
        e.move(r, c.AccountID, asset, reserve.Neg(), reserve, "RESERVE")
        reason := ""
        for !dec(o.Remaining).IsZero() </span><span class="cov8" title="1">{
                l := e.bestOpposite(c.Side)
                if l == nil </span><span class="cov8" title="1">{
                        reason = "NO_LIQUIDITY"
                        break</span>
                }
                <span class="cov8" title="1">if !crosses(c.Side, l.price, p) </span><span class="cov8" title="1">{
                        reason = "PRICE_PROTECTION"
                        break</span>
                }
                <span class="cov8" title="1">maker := l.orders.Front().Value.(*Order)
                // 档位最优价决定价格优先;Front 是最早入队的挂单,保证同价时间优先。
                if maker.AccountID == o.AccountID </span><span class="cov8" title="1">{
                        reason = "SELF_TRADE_PREVENTED"
                        break</span>
                }
                <span class="cov8" title="1">fill := decimal.Min(dec(o.Remaining), dec(maker.Remaining))
                buy, sell := o, maker
                if c.Side == "SELL" </span><span class="cov8" title="1">{
                        buy, sell = maker, o
                }</span>
                <span class="cov8" title="1">cost := l.price.Mul(fill)
                locked := dec(buy.Price).Mul(fill)
                // 成交以 maker 档位定价,买方按原限价冻结额扣减,并把价差立即退回可用额。
                // 例如买 3 ETH @105 冻结 315,在卖价 100 成交 2:
                // 扣冻结 210、付卖方 200、返买方 10,余量 1 仍冻结 105。
                // ETH 由卖方冻结转到买方可用;USDT 在双方间转移,总量不变。
                e.move(r, buy.AccountID, "USDT", locked.Sub(cost), locked.Neg(), "TRADE")
                e.move(r, buy.AccountID, "ETH", fill, decimal.Zero, "TRADE")
                e.move(r, sell.AccountID, "ETH", decimal.Zero, fill.Neg(), "TRADE")
                e.move(r, sell.AccountID, "USDT", cost, decimal.Zero, "TRADE")
                for _, v := range []*Order{o, maker} </span><span class="cov8" title="1">{
                        v.Remaining = dec(v.Remaining).Sub(fill).String()
                        v.Filled = dec(v.Filled).Add(fill).String()
                        v.Status = "PARTIALLY_FILLED"
                        if dec(v.Remaining).IsZero() </span><span class="cov8" title="1">{
                                v.Status = "FILLED"
                        }</span>
                        <span class="cov8" title="1">changed[v.ID] = v</span>
                }
                <span class="cov8" title="1">r.Trades = append(r.Trades, Trade{fmt.Sprintf("%d-%d", c.Seq, len(r.Trades)), maker.ID, o.ID, l.price.String(), fill.String(), o.Side, c.Timestamp})
                if maker.Status == "FILLED" </span><span class="cov8" title="1">{
                        e.remove(e.active[maker.ID])
                }</span>
        }
        <span class="cov8" title="1">remaining := dec(o.Remaining)
        // FILLED 无余量;自成交余量总是取消;GTC 才能把其余未成交数量留在簿上。
        if !remaining.IsZero() </span><span class="cov8" title="1">{
                if c.Type == "LIMIT" &amp;&amp; c.TIF == "GTC" &amp;&amp; reason != "SELF_TRADE_PREVENTED" </span><span class="cov8" title="1">{
                        e.add(o)
                }</span> else<span class="cov8" title="1"> {
                        e.release(r, o, remaining, "RELEASE")
                        o.Canceled = remaining.String()
                        o.Remaining = "0"
                        o.Status = "CANCELED"
                        o.Reason = reason
                        if o.Reason == "" </span><span class="cov0" title="0">{
                                o.Reason = "IOC_REMAINDER"
                        }</span>
                }
        }
}

// release 按原买单限价 × 余量释放 USDT;卖单按余量释放 ETH。
// 不是按当前市场价解冻,确保活动挂单资金与 Frozen 精确对应。
func (e *Engine) release(r *Result, o *Order, q decimal.Decimal, reason string) <span class="cov8" title="1">{
        asset := "ETH"
        amount := q
        if o.Side == "BUY" </span><span class="cov8" title="1">{
                asset = "USDT"
                amount = dec(o.Price).Mul(q)
        }</span>
        <span class="cov8" title="1">e.move(r, o.AccountID, asset, amount, amount.Neg(), reason)</span>
}

// add 将订单追加在同价链表尾部,并更新反向索引和最优价缓存。
// 创建/定位价档 O(log P),链表入队 O(1);创建顺序已由命令序号确定。
func (e *Engine) add(o *Order) <span class="cov8" title="1">{
        tree := e.bids
        if o.Side == "SELL" </span><span class="cov8" title="1">{
                tree = e.asks
        }</span>
        <span class="cov8" title="1">p := dec(o.Price)
        ticks := p.Shift(2).IntPart()
        v, ok := tree.Get(ticks)
        var l *priceLevel
        if ok </span><span class="cov8" title="1">{
                l = v.(*priceLevel)
        }</span> else<span class="cov8" title="1"> {
                l = &amp;priceLevel{p, list.New()}
                tree.Put(ticks, l)
        }</span>
        <span class="cov8" title="1">e.active[o.ID] = &amp;orderRef{o, l, l.orders.PushBack(o)}
        if o.Side == "BUY" &amp;&amp; (e.bestBid == nil || p.GreaterThan(e.bestBid.price)) </span><span class="cov8" title="1">{
                e.bestBid = l
        }</span>
        <span class="cov8" title="1">if o.Side == "SELL" &amp;&amp; (e.bestAsk == nil || p.LessThan(e.bestAsk.price)) </span><span class="cov8" title="1">{
                e.bestAsk = l
        }</span>
}

// remove 删除已索引的活动订单;调用者保证 ref 存在。
// 档内其他单仍在时保留价档与缓存;最后一单离开时删除价档。
// 若被删的是最优档,再取买树最大或卖树最小节点;空簿缓存归 nil。
func (e *Engine) remove(ref *orderRef) <span class="cov8" title="1">{
        ref.level.orders.Remove(ref.node)
        delete(e.active, ref.order.ID)
        if ref.level.orders.Len() == 0 </span><span class="cov8" title="1">{
                tree := e.bids
                if ref.order.Side == "SELL" </span><span class="cov8" title="1">{
                        tree = e.asks
                }</span>
                <span class="cov8" title="1">tree.Remove(ref.level.price.Shift(2).IntPart())
                if ref.order.Side == "BUY" &amp;&amp; e.bestBid == ref.level </span><span class="cov8" title="1">{
                        e.bestBid = nil
                        if n := tree.Right(); n != nil </span><span class="cov8" title="1">{
                                e.bestBid = n.Value.(*priceLevel)
                        }</span>
                }
                <span class="cov8" title="1">if ref.order.Side == "SELL" &amp;&amp; e.bestAsk == ref.level </span><span class="cov8" title="1">{
                        e.bestAsk = nil
                        if n := tree.Left(); n != nil </span><span class="cov8" title="1">{
                                e.bestAsk = n.Value.(*priceLevel)
                        }</span>
                }
        }
}
</pre>
    
    <pre class="file" id="file3" style="display: none">package backend

// 并发接入层仅解析/鉴权/映射结果及读取投影,不能绕过 runtime 直接改核心或查询余额。
// 客户端使用顺序与错误语义见 docs/api-guide.md;响应写失败不回滚已受理命令。

import (
        "context"
        "crypto/subtle"
        "database/sql"
        "encoding/json"
        "errors"
        "io"
        "net"
        "net/http"
        "net/url"
        "os"
        "path/filepath"
        "strconv"
        "strings"
        "sync"
        "time"

        "web3exchange/api"

        "github.com/coder/websocket"
        "github.com/coder/websocket/wsjson"
)

// Config 控制 Cookie 传输要求、静态目录及允许的浏览器 Origin。
// 生产 HTTPS 配 Secure=true 并显式设置外部 Origin;本地 HTTP 使用 false。
type Config struct {
        CookieSecure  bool
        FrontendDir   string
        AllowedOrigin string
        // LocalAdminName 仅由回环本地启动配置启用;别名登录映射为 name@localhost。
        // 空值保持邮箱登录。注册永远不应用别名,不能通过公开注册创建管理员。
        LocalAdminName string
}

// sessionContext 存放服务端验证得到的用户及 CSRF,仅由 protected 写入请求 context。
type sessionContext struct {
        user User
        csrf string
}

// Server 是并发 HTTP 外围:持有持久化/运行时引用及认证、行情资源上限。
// limitMu 和 snapshot 的锁只协调外围共享数据,不进入 Engine。
type Server struct {
        Store         *Store
        Runtime       *Runtime
        Config        Config
        authSlots     chan struct{}
        limitMu       sync.Mutex
        attempts      map[string][]time.Time
        snapshot      atomicSnapshot
        wsSlots       chan struct{}
        streamContext context.Context
        stopStreams   context.CancelFunc
}

// atomicSnapshot 用外围 RWMutex 发布完整快照与查询错误。
// 发布后快照切片不再修改,WS 只读取;名称表示整体替换,并非 sync/atomic 类型。
type atomicSnapshot struct {
        mu    sync.RWMutex
        value Snapshot
        err   error
}

// NewServer 限制 bcrypt 并发为 4、公共 WS 连接为 200,避免接入无限消耗资源。
func NewServer(s *Store, r *Runtime, c Config) *Server <span class="cov8" title="1">{
        streamContext, stopStreams := context.WithCancel(context.Background())
        return &amp;Server{streamContext: streamContext, stopStreams: stopStreams, Store: s, Runtime: r, Config: c, authSlots: make(chan struct{}, 4), attempts: map[string][]time.Time{}, wsSlots: make(chan struct{}, 200)}
}</span>

// CloseStreams 停止已有 WS 生命周期,不依赖 http.Server.Shutdown(它不关闭 hijacked 连接)。
// 可重复调用;连接 goroutine 自行回收 wsSlots,采样器仍由外部 ctx 管理。
func (s *Server) CloseStreams() <span class="cov8" title="1">{ s.stopStreams() }</span>

// writeJSON 在接入层编码响应;核心不编码 JSON。
// 编码或网络写失败不会撤销已执行业务,客户端须按结果未知处理写请求。
func writeJSON(w http.ResponseWriter, status int, v any) <span class="cov8" title="1">{
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(status)
        json.NewEncoder(w).Encode(v)
}</span>

// apiError 统一接入错误 envelope,错误码供客户端处理,message 用于简短展示。
func apiError(w http.ResponseWriter, status int, code, message string) <span class="cov8" title="1">{
        writeJSON(w, status, map[string]any{"error": map[string]string{"code": code, "message": message}})
}</span>

// decode 限制请求体 16KiB、拒绝未知字段和多个 JSON 值。
// 注册不能塞 role、下单不能塞 account_id;兼容性变更需明确调整契约。
// JSON null 对结构体可解码成零值,字段必填/业务组合仍由具体 handler 校验,不能只靠 decode。
func decode(w http.ResponseWriter, r *http.Request, v any) bool <span class="cov8" title="1">{
        r.Body = http.MaxBytesReader(w, r.Body, 16&lt;&lt;10)
        d := json.NewDecoder(r.Body)
        d.DisallowUnknownFields()
        if err := d.Decode(v); err != nil </span><span class="cov8" title="1">{
                apiError(w, 400, "INVALID_REQUEST", "请求参数无效")
                return false
        }</span>
        <span class="cov8" title="1">var extra any
        if d.Decode(&amp;extra) != io.EOF </span><span class="cov8" title="1">{
                apiError(w, 400, "INVALID_REQUEST", "请求只能包含一个 JSON 对象")
                return false
        }</span>
        <span class="cov8" title="1">return true</span>
}

// Handler 定义公开行情、会话业务及 ADMIN 路由,并统一执行安全头和写请求 Origin 校验。
// live 只表示进程可响应;ready 额外要求 runtime 仍可受理工作。
// API 禁缓存,避免敏感余额/身份被浏览器或代理共享缓存。
func (s *Server) Handler() http.Handler <span class="cov8" title="1">{
        m := http.NewServeMux()
        // 契约与运行二进制同版本发布;静态文档公开,但不暴露用户/会话。
        m.HandleFunc("GET /api/v1/openapi.json", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                w.Header().Set("Content-Type", "application/json")
                w.Write(api.Spec)
        }</span>)
        <span class="cov8" title="1">m.HandleFunc("POST /api/v1/auth/register", s.authAction(true))
        m.HandleFunc("POST /api/v1/auth/login", s.authAction(false))
        m.HandleFunc("GET /api/v1/auth/me", s.protected(false, s.me))
        m.HandleFunc("POST /api/v1/auth/logout", s.protected(false, s.logout))
        m.HandleFunc("GET /api/v1/markets", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                writeJSON(w, 200, []any{map[string]string{"symbol": "ETH-USDT", "tick_size": "0.01", "step_size": "0.0001"}})
        }</span>)
        <span class="cov8" title="1">m.HandleFunc("POST /api/v1/orders", s.protected(false, s.place))
        m.HandleFunc("POST /api/v1/orders/{id}/cancel", s.protected(false, s.cancelOrder))
        m.HandleFunc("GET /api/v1/orders", s.protected(false, s.orders))
        m.HandleFunc("GET /api/v1/orders/{id}", s.protected(false, s.orderByID))
        m.HandleFunc("GET /api/v1/commands/by-key", s.protected(false, s.commandByKey))
        m.HandleFunc("GET /api/v1/balances", s.protected(false, s.balances))
        m.HandleFunc("GET /api/v1/snapshot", s.market)
        m.HandleFunc("GET /api/v1/stream", s.stream)
        m.HandleFunc("GET /api/v1/markets/{symbol}/book", s.marketBook)
        m.HandleFunc("GET /api/v1/markets/{symbol}/trades", s.marketTrades)
        m.HandleFunc("GET /api/v1/admin/users", s.protected(true, s.users))
        m.HandleFunc("PATCH /api/v1/admin/users/{id}", s.protected(true, s.updateUser))
        m.HandleFunc("POST /api/v1/admin/credits", s.protected(true, s.credit))
        m.HandleFunc("GET /api/v1/admin/audit", s.protected(true, s.audit))
        m.HandleFunc("GET /api/v1/admin/orders", s.protected(true, s.allOrders))
        m.HandleFunc("GET /health/live", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{ writeJSON(w, 200, map[string]string{"status": "alive"}) }</span>)
        <span class="cov8" title="1">m.HandleFunc("GET /health/ready", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                if !s.Runtime.Healthy() </span><span class="cov0" title="0">{
                        apiError(w, 503, "NOT_READY", "服务暂不可用")
                        return
                }</span>
                <span class="cov8" title="1">writeJSON(w, 200, map[string]string{"status": "ready"})</span>
        })
        <span class="cov8" title="1">m.HandleFunc("/metrics", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{ http.NotFound(w, r) }</span>)
        <span class="cov8" title="1">m.HandleFunc("/debug/", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{ http.NotFound(w, r) }</span>)
        <span class="cov8" title="1">m.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) </span><span class="cov0" title="0">{ apiError(w, 404, "NOT_FOUND", "接口不存在") }</span>)
        <span class="cov8" title="1">m.HandleFunc("/", s.static)
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                w.Header().Set("X-Dataset-ID", s.Store.DatasetID)
                w.Header().Set("X-Content-Type-Options", "nosniff")
                w.Header().Set("Referrer-Policy", "same-origin")
                w.Header().Set("X-Frame-Options", "DENY")
                if strings.HasPrefix(r.URL.Path, "/api/") </span><span class="cov8" title="1">{
                        w.Header().Set("Cache-Control", "no-store")
                }</span>
                <span class="cov8" title="1">if r.Method != "GET" &amp;&amp; r.Method != "HEAD" &amp;&amp; !s.originOK(r) </span><span class="cov8" title="1">{
                        apiError(w, 403, "ORIGIN_REJECTED", "请求来源不允许")
                        return
                }</span>
                // 浏览器恢复请求带数据集标识;旧卷/重置前的请求不可自动进入新日志。
                // 兼容既有脚本客户端不带此头;新前端已登录的业务写请求都显式发送。
                <span class="cov8" title="1">if dataset := r.Header.Get("X-Dataset-ID"); r.Method != "GET" &amp;&amp; r.Method != "HEAD" &amp;&amp; dataset != "" &amp;&amp; dataset != s.Store.DatasetID </span><span class="cov8" title="1">{
                        apiError(w, 409, "DATASET_CHANGED", "数据集已变更,请刷新后重新确认")
                        return
                }</span>
                <span class="cov8" title="1">m.ServeHTTP(w, r)</span>
        })
}

// originOK 检查浏览器 Origin 或无 Origin 时的 Sec-Fetch-Site。
// 显式 AllowedOrigin 适合 TLS 反向代理;默认校验 Host,未启用宽泛跨域 CORS。
// 无这些浏览器头的脚本客户端仍须通过会话/CSRF,而不能把 Origin 当身份认证。
func (s *Server) originOK(r *http.Request) bool <span class="cov8" title="1">{
        origin := r.Header.Get("Origin")
        if origin == "" </span><span class="cov8" title="1">{
                return r.Header.Get("Sec-Fetch-Site") != "cross-site"
        }</span>
        <span class="cov8" title="1">u, err := url.Parse(origin)
        if err != nil || (u.Scheme != "http" &amp;&amp; u.Scheme != "https") || u.Path != "" || u.RawQuery != "" || u.User != nil </span><span class="cov8" title="1">{
                return false
        }</span>
        <span class="cov8" title="1">if s.Config.AllowedOrigin != "" </span><span class="cov8" title="1">{
                return origin == s.Config.AllowedOrigin
        }</span>
        <span class="cov8" title="1">return u.Host == r.Host</span>
}

// protected 从 HttpOnly Cookie 查数据库会话,校验 RBAC 及写操作 CSRF 后调用 handler。
// 常数时间比较 CSRF,身份/角色均来自数据库;前端隐藏按钮不构成权限控制。
// 认证库故障返回 503,过期或停用返回 401,两者不混为合法访客。
func (s *Server) protected(admin bool, next http.HandlerFunc) http.HandlerFunc <span class="cov8" title="1">{
        return func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                cookie, err := r.Cookie("exchange_session")
                if err != nil </span><span class="cov8" title="1">{
                        apiError(w, 401, "UNAUTHENTICATED", "请先登录")
                        return
                }</span>
                <span class="cov8" title="1">u, csrf, err := s.Store.Session(r.Context(), cookie.Value)
                if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                        apiError(w, 401, "UNAUTHENTICATED", "登录已失效")
                        return
                }</span>
                <span class="cov8" title="1">if err != nil </span><span class="cov8" title="1">{
                        apiError(w, 503, "AUTH_UNAVAILABLE", "认证服务暂不可用")
                        return
                }</span>
                <span class="cov8" title="1">if admin &amp;&amp; u.Role != "ADMIN" </span><span class="cov8" title="1">{
                        apiError(w, 403, "FORBIDDEN", "需要管理员权限")
                        return
                }</span>
                <span class="cov8" title="1">if r.Method != "GET" &amp;&amp; r.Method != "HEAD" &amp;&amp; subtle.ConstantTimeCompare([]byte(csrf), []byte(r.Header.Get("X-CSRF-Token"))) != 1 </span><span class="cov8" title="1">{
                        apiError(w, 403, "CSRF_REJECTED", "请刷新后重试")
                        return
                }</span>
                <span class="cov8" title="1">next(w, r.WithContext(context.WithValue(r.Context(), authContextKey{}, sessionContext{u, csrf})))</span>
        }
}

// authContextKey 使用私有类型避免不同中间件 context key 字符串冲突。
type authContextKey struct{}

// session 仅在 protected 包装的 handler 中调用;类型断言依赖该调用约束。
func session(r *http.Request) sessionContext <span class="cov8" title="1">{
        return r.Context().Value(authContextKey{}).(sessionContext)
}</span>

// allowAuth 按 RemoteAddr 限制每分钟 10 次尝试,并清理过期 IP,表大小上限 10000。
// 不信任 X-Forwarded-For;代理部署时 RemoteAddr 是代理地址,可后续配置可信代理/共享限流。
func (s *Server) allowAuth(r *http.Request) bool <span class="cov8" title="1">{
        ip, _, err := net.SplitHostPort(r.RemoteAddr)
        if err != nil </span><span class="cov0" title="0">{
                ip = r.RemoteAddr
        }</span>
        <span class="cov8" title="1">now := time.Now()
        s.limitMu.Lock()
        defer s.limitMu.Unlock()
        for k, times := range s.attempts </span><span class="cov8" title="1">{
                if len(times) == 0 || now.Sub(times[len(times)-1]) &gt; time.Minute </span><span class="cov8" title="1">{
                        delete(s.attempts, k)
                }</span>
        }
        <span class="cov8" title="1">a := s.attempts[ip]
        fresh := a[:0]
        for _, t := range a </span><span class="cov8" title="1">{
                if now.Sub(t) &lt; time.Minute </span><span class="cov8" title="1">{
                        fresh = append(fresh, t)
                }</span>
        }
        <span class="cov8" title="1">if len(fresh) &gt;= 10 || len(s.attempts) &gt;= 10000 </span><span class="cov8" title="1">{
                return false
        }</span>
        <span class="cov8" title="1">s.attempts[ip] = append(fresh, now)
        return true</span>
}

// authAction 统一注册和登录流程:限流/并发额度 → 严格解析 → 密码认证 → 幂等初始资金 → 会话。
// 公开注册固定 USER;初始化中断时下次登录重试,账户不会重复得到模拟资金。
// Cookie HttpOnly/SameSiteStrict;CSRF 返回 JSON 供本次页面内存使用。
func (s *Server) authAction(register bool) http.HandlerFunc <span class="cov8" title="1">{
        return func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                if !s.allowAuth(r) </span><span class="cov0" title="0">{
                        apiError(w, 429, "RATE_LIMITED", "操作频繁,请稍后重试")
                        return
                }</span>
                <span class="cov8" title="1">select </span>{
                case s.authSlots &lt;- struct{}{}:<span class="cov8" title="1">
                        defer func() </span><span class="cov8" title="1">{ &lt;-s.authSlots }</span>()
                default:<span class="cov8" title="1">
                        apiError(w, 429, "RATE_LIMITED", "请求繁忙,请稍后重试")
                        return</span>
                }
                <span class="cov8" title="1">var body struct {
                        Email    string `json:"email"`
                        Password string `json:"password"`
                }
                if !decode(w, r, &amp;body) </span><span class="cov8" title="1">{
                        return
                }</span>
                <span class="cov8" title="1">if len(body.Password) &gt; 72 </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_PASSWORD", "密码过长")
                        return
                }</span>
                <span class="cov8" title="1">var u User
                var err error
                if register </span><span class="cov8" title="1">{
                        u, err = s.Store.CreateUser(r.Context(), body.Email, body.Password, "USER")
                }</span> else<span class="cov8" title="1"> {
                        // 仅映射启动配置指定的一个别名,其他无 @ 的输入仍按普通邮箱校验拒绝。
                        // 身份/角色仍从认证库读取,别名不是授权凭证或密码绕过。
                        if s.Config.LocalAdminName != "" &amp;&amp; strings.EqualFold(strings.TrimSpace(body.Email), s.Config.LocalAdminName) </span><span class="cov8" title="1">{
                                body.Email, err = LocalAdminEmail(s.Config.LocalAdminName)
                                if err != nil </span><span class="cov0" title="0">{
                                        apiError(w, 503, "AUTH_UNAVAILABLE", "本地账号配置无效")
                                        return
                                }</span>
                        }
                        <span class="cov8" title="1">u, err = s.Store.Login(r.Context(), body.Email, body.Password)</span>
                }
                <span class="cov8" title="1">if err != nil </span><span class="cov8" title="1">{
                        if errors.Is(err, ErrEmailTaken) </span><span class="cov0" title="0">{
                                apiError(w, 409, "EMAIL_TAKEN", "邮箱已注册")
                        }</span> else<span class="cov8" title="1"> if errors.Is(err, ErrCredentials) </span><span class="cov8" title="1">{
                                apiError(w, 401, "INVALID_CREDENTIALS", "邮箱或密码错误")
                        }</span> else<span class="cov8" title="1"> if register </span><span class="cov8" title="1">{
                                apiError(w, 400, "REGISTRATION_FAILED", err.Error())
                        }</span> else<span class="cov0" title="0"> {
                                apiError(w, 503, "AUTH_UNAVAILABLE", "登录暂不可用")
                        }</span>
                        <span class="cov8" title="1">return</span>
                }
                <span class="cov8" title="1">if err = s.EnsureFunding(r.Context(), u.ID); err != nil </span><span class="cov0" title="0">{
                        apiError(w, 503, "ACCOUNT_INITIALIZING", "账户初始化中,请稍后登录")
                        return
                }</span>
                <span class="cov8" title="1">token, csrf, err := s.Store.NewSession(r.Context(), u.ID)
                if err != nil </span><span class="cov0" title="0">{
                        apiError(w, 503, "AUTH_UNAVAILABLE", "登录暂不可用")
                        return
                }</span>
                <span class="cov8" title="1">http.SetCookie(w, &amp;http.Cookie{Name: "exchange_session", Value: token, Path: "/", HttpOnly: true, Secure: s.Config.CookieSecure, SameSite: http.SameSiteStrictMode, MaxAge: 86400})
                status := 200
                if register </span><span class="cov8" title="1">{
                        status = 201
                }</span>
                <span class="cov8" title="1">writeJSON(w, status, map[string]any{"user": u, "csrf_token": csrf, "dataset_id": s.Store.DatasetID})</span>
        }
}

// EnsureFunding 将 10 ETH 与 100000 USDT 分别写成正常 CREDIT 命令。
// 固定 system.initial.&lt;asset&gt; 键允许重试修复部分初始化;客户端不能占用 system. 命名空间。
// 两个资产不是跨库原子注册事务,登录响应会等待两项初始化结果。
func (s *Server) EnsureFunding(ctx context.Context, id string) error <span class="cov8" title="1">{
        for _, v := range []struct{ asset, amount string }{{"ETH", "10"}, {"USDT", "100000"}} </span><span class="cov8" title="1">{
                result, err := s.Runtime.Submit(ctx, Command{Kind: "CREDIT", AccountID: id, Key: "system.initial." + v.asset, Asset: v.asset, Amount: v.amount, ActorID: "SYSTEM", Reason: "注册模拟资金"})
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if result.Code != "" </span><span class="cov0" title="0">{
                        return errors.New(result.Code)
                }</span>
        }
        <span class="cov8" title="1">return nil</span>
}

// me 返回当前会话身份与 CSRF,支持刷新页面后恢复登录,不返回会话 token。
func (s *Server) me(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        x := session(r)
        writeJSON(w, 200, map[string]any{"user": x.user, "csrf_token": x.csrf, "dataset_id": s.Store.DatasetID})
}</span>

// logout 先删除服务端当前会话再清 Cookie;其他设备会话不受此操作影响。
func (s *Server) logout(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        cookie, _ := r.Cookie("exchange_session")
        if _, err := s.Store.Auth.ExecContext(r.Context(), "DELETE FROM sessions WHERE token_hash=?", tokenHash(cookie.Value)); err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "AUTH_UNAVAILABLE", "退出暂不可用")
                return
        }</span>
        <span class="cov8" title="1">http.SetCookie(w, &amp;http.Cookie{Name: "exchange_session", Value: "", Path: "/", HttpOnly: true, Secure: s.Config.CookieSecure, SameSite: http.SameSiteStrictMode, MaxAge: -1})
        writeJSON(w, 200, map[string]bool{"ok": true})</span>
}

// idempotency 校验客户端幂等键长度/字符集,保留 system. 给可信初始化。
// 业务摘要在外围规范化后计算;键与当前账户共同确定去重范围。
func idempotency(w http.ResponseWriter, r *http.Request) string <span class="cov8" title="1">{
        k := r.Header.Get("Idempotency-Key")
        if len(k) &lt; 8 || len(k) &gt; 128 || strings.HasPrefix(k, "system.") </span><span class="cov8" title="1">{
                apiError(w, 400, "INVALID_IDEMPOTENCY_KEY", "需要 8–128 字符的幂等键")
                return ""
        }</span>
        <span class="cov8" title="1">for _, c := range k </span><span class="cov8" title="1">{
                if !(c &gt;= 'a' &amp;&amp; c &lt;= 'z' || c &gt;= 'A' &amp;&amp; c &lt;= 'Z' || c &gt;= '0' &amp;&amp; c &lt;= '9' || c == '-' || c == '_' || c == '.') </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_IDEMPOTENCY_KEY", "幂等键字符无效")
                        return ""
                }</span>
        }
        <span class="cov8" title="1">return k</span>
}

// submit 映射业务冲突、权限及系统故障为 HTTP 状态,保留处理/首次结果两个水位。
// 网络等待超时映射 RESULT_UNKNOWN,客户端只能用原内容/原键确认结果。
// 映射 OVERLOADED 也不能证明更早的同键请求没成功;错误响应不撤销历史业务效果。
// 201 表示新订单业务已处理,不表示必定成交;IOC 可创建并立即取消余量。
func (s *Server) submit(w http.ResponseWriter, r *http.Request, c Command) <span class="cov8" title="1">{
        result, err := s.Runtime.Submit(r.Context(), c)
        if err != nil </span><span class="cov0" title="0">{
                status, code := 503, "OVERLOADED"
                if strings.Contains(err.Error(), "result unknown") </span><span class="cov0" title="0">{
                        status, code = 504, "RESULT_UNKNOWN"
                }</span>
                <span class="cov0" title="0">apiError(w, status, code, "请求暂未取得结果,请使用原幂等键重试")
                return</span>
        }
        <span class="cov8" title="1">status := 200
        if c.Kind == "PLACE" &amp;&amp; !result.Replayed </span><span class="cov8" title="1">{
                status = 201
        }</span>
        <span class="cov8" title="1">if result.Code != "" </span><span class="cov8" title="1">{
                result.Error = &amp;PublicError{result.Code, result.Message}
                status = 422
                switch result.Code </span>{
                case "IDEMPOTENCY_CONFLICT", "ORDER_TERMINAL":<span class="cov8" title="1">
                        status = 409</span>
                case "ORDER_NOT_FOUND":<span class="cov0" title="0">
                        status = 404</span>
                case "FORBIDDEN":<span class="cov8" title="1">
                        status = 403</span>
                }
        }
        <span class="cov8" title="1">writeJSON(w, status, result)</span>
}

// place 解析 ETH-USDT 订单并规范化金额,再从会话注入 AccountID。
// 接入层与核心都校验业务字段,防止内部调用绕过参数约束;外部不能选择交易账户。
func (s *Server) place(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        k := idempotency(w, r)
        if k == "" </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">var b struct {
                Market   string `json:"market"`
                Side     string `json:"side"`
                Type     string `json:"type"`
                TIF      string `json:"time_in_force"`
                Price    string `json:"price"`
                Quantity string `json:"quantity"`
        }
        if !decode(w, r, &amp;b) </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">p, pok := parseAmount(b.Price, 2, "1000000000000", true)
        q, qok := parseAmount(b.Quantity, 4, "1000000", true)
        if b.Market != "ETH-USDT" || !pok || !qok || (b.Side != "BUY" &amp;&amp; b.Side != "SELL") || (b.Type != "LIMIT" &amp;&amp; b.Type != "MARKET") || (b.TIF != "GTC" &amp;&amp; b.TIF != "IOC") || (b.Type == "MARKET" &amp;&amp; b.TIF != "IOC") </span><span class="cov0" title="0">{
                apiError(w, 400, "INVALID_ORDER", "价格、数量或订单类型无效")
                return
        }</span>
        <span class="cov8" title="1">s.submit(w, r, Command{AccountID: session(r).user.ID, Kind: "PLACE", Key: k, Side: b.Side, Type: b.Type, TIF: b.TIF, Price: p.String(), Quantity: q.String()})</span>
}

// cancelOrder 用 ParseInt 检查 int64 格式,核心再次核验订单归属和终态,避免跨账户撤单。
// 这里不规范化正号/前导零/非正值,原文本继续匹配 ID;客户端应使用服务器返回的原 ID。
func (s *Server) cancelOrder(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        k := idempotency(w, r)
        if k == "" </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">if _, err := strconv.ParseInt(r.PathValue("id"), 10, 64); err != nil </span><span class="cov0" title="0">{
                apiError(w, 400, "INVALID_ORDER_ID", "订单 ID 无效")
                return
        }</span>
        <span class="cov8" title="1">s.submit(w, r, Command{Kind: "CANCEL", AccountID: session(r).user.ID, Key: k, OrderID: r.PathValue("id")})</span>
}

// waitProjection 支持 min_seq 读自己的写:最多等待 2s,投影未追上返回 PROJECTION_LAG。
// 只等待查询水位,不同步阻塞核心;HTTP context 取消后停止查询等待。
// Views 连接仍与 projector 争用;目标是至少达到 min_seq,并不读取恰好该历史时刻。
func (s *Server) waitProjection(w http.ResponseWriter, r *http.Request) bool <span class="cov8" title="1">{
        value := r.URL.Query().Get("min_seq")
        if value == "" </span><span class="cov8" title="1">{
                return true
        }</span>
        <span class="cov8" title="1">target, err := strconv.ParseInt(value, 10, 64)
        if err != nil || target &lt; 0 </span><span class="cov8" title="1">{
                apiError(w, 400, "INVALID_SEQUENCE", "序号无效")
                return false
        }</span>
        <span class="cov8" title="1">deadline := time.NewTimer(2 * time.Second)
        defer deadline.Stop()
        ticker := time.NewTicker(10 * time.Millisecond)
        defer ticker.Stop()
        for </span><span class="cov8" title="1">{
                var seq int64
                if err = s.Store.Views.QueryRowContext(r.Context(), "SELECT seq FROM progress WHERE id=1").Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                        apiError(w, 503, "PROJECTION_UNAVAILABLE", "查询暂不可用")
                        return false
                }</span>
                <span class="cov8" title="1">if seq &gt;= target </span><span class="cov8" title="1">{
                        return true
                }</span>
                <span class="cov0" title="0">select </span>{
                case &lt;-deadline.C:<span class="cov0" title="0">
                        apiError(w, 503, "PROJECTION_LAG", "更新中,请稍后重试")
                        return false</span>
                case &lt;-r.Context().Done():<span class="cov0" title="0">
                        return false</span>
                case &lt;-ticker.C:<span class="cov0" title="0"></span>
                }
        }
}

// orders 返回当前账户订单页,支持 min_seq/limit/cursor;不直接读取核心 map。
func (s *Server) orders(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">limit := 100
        if raw := r.URL.Query().Get("limit"); raw != "" </span><span class="cov8" title="1">{
                parsed, err := strconv.Atoi(raw)
                if err != nil || parsed &lt; 1 || parsed &gt; 100 </span><span class="cov8" title="1">{
                        apiError(w, 400, "INVALID_LIMIT", "limit 需为 1–100")
                        return
                }</span>
                <span class="cov8" title="1">limit = parsed</span>
        }
        <span class="cov8" title="1">out, err := s.Store.OrdersPage(r.Context(), session(r).user.ID, false, limit, r.URL.Query().Get("cursor"))
        if err != nil </span><span class="cov8" title="1">{
                if errors.Is(err, ErrCursor) </span><span class="cov8" title="1">{
                        apiError(w, 400, "INVALID_CURSOR", "订单游标无效或已过期")
                        return
                }</span>
                <span class="cov0" title="0">apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                return</span>
        }
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// orderByID 读取当前用户的单笔投影;服务端按会话账户过滤,不能靠 URL 访问他人订单。
func (s *Server) orderByID(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">out, err := s.Store.OrderByID(r.Context(), session(r).user.ID, r.PathValue("id"))
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                apiError(w, 404, "ORDER_NOT_FOUND", "订单不存在")
                return
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                return
        }</span>
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// commandByKey 供写请求超时后确认首次结果。键空间仍绑定当前账户,不能查询其他账户的命令。
func (s *Server) commandByKey(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        key := r.URL.Query().Get("key")
        if len(key) &lt; 8 || len(key) &gt; 128 </span><span class="cov0" title="0">{
                apiError(w, 400, "INVALID_IDEMPOTENCY_KEY", "幂等键无效")
                return
        }</span>
        <span class="cov8" title="1">if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">out, err := s.Store.LookupCommand(r.Context(), session(r).user.ID, key)
        if err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                return
        }</span>
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// balances 返回当前账户可用/冻结资产,支持 min_seq 防止紧随写入读到旧余额。
func (s *Server) balances(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">out, err := s.Store.Balances(r.Context(), session(r).user.ID)
        if err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                return
        }</span>
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// market 返回公共一致行情快照,支持 min_seq;失败不伪造空行情为成功。
func (s *Server) market(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">x, err := s.Store.Snapshot(r.Context())
        if err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "QUERY_FAILED", "行情暂不可用")
                return
        }</span>
        <span class="cov8" title="1">writeJSON(w, 200, x)</span>
}

// users 是 ADMIN 用户查询入口,仅返回公开身份字段。
func (s *Server) users(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        limit, ok := queryLimit(w, r)
        if !ok </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">out, err := s.Store.UsersPage(r.Context(), session(r).user.ID, limit, r.URL.Query().Get("cursor"))
        if err != nil </span><span class="cov0" title="0">{
                if errors.Is(err, ErrCursor) </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_CURSOR", "用户游标无效")
                }</span> else<span class="cov0" title="0"> {
                        apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                }</span>
                <span class="cov0" title="0">return</span>
        }
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// updateUser 只接受明确的 disabled 布尔值,不提供角色任意变更接口。
// 状态与审计在认证库事务中完成;停用与业务订单生命周期分离。
func (s *Server) updateUser(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        var b struct {
                Disabled *bool `json:"disabled"`
        }
        if !decode(w, r, &amp;b) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">if b.Disabled == nil </span><span class="cov0" title="0">{
                apiError(w, 400, "INVALID_REQUEST", "需要 disabled 字段")
                return
        }</span>
        <span class="cov8" title="1">if err := s.Store.SetDisabled(r.Context(), session(r).user.ID, r.PathValue("id"), *b.Disabled); err != nil </span><span class="cov8" title="1">{
                apiError(w, 409, "USER_UPDATE_REJECTED", "用户不存在或不能停用")
                return
        }</span>
        <span class="cov8" title="1">writeJSON(w, 200, map[string]bool{"ok": true})</span>
}

// credit 是 ADMIN 模拟资产注资入口,检查目标账户存在并要求审计原因。
// 目标账户可以不同于操作者;键包含管理员 ID 隔离不同管理员的同名请求。
// 实际资金变更走 CREDIT 日志和单写者核心,不在此直接 UPDATE 余额。
func (s *Server) credit(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        k := idempotency(w, r)
        if k == "" </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">var b struct {
                AccountID string `json:"account_id"`
                Asset     string `json:"asset"`
                Amount    string `json:"amount"`
                Reason    string `json:"reason"`
        }
        if !decode(w, r, &amp;b) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">scale := int32(6)
        max := "1000000000000"
        if b.Asset == "ETH" </span><span class="cov0" title="0">{
                scale = 4
                max = "1000000"
        }</span>
        <span class="cov8" title="1">amount, ok := parseAmount(b.Amount, scale, max, true)
        if !ok || (b.Asset != "ETH" &amp;&amp; b.Asset != "USDT") || len(strings.TrimSpace(b.Reason)) &lt; 2 || len(b.Reason) &gt; 200 </span><span class="cov0" title="0">{
                apiError(w, 400, "INVALID_CREDIT", "资金参数或原因无效")
                return
        }</span>
        <span class="cov8" title="1">var exists int
        if err := s.Store.Auth.QueryRowContext(r.Context(), "SELECT 1 FROM users WHERE id=?", b.AccountID).Scan(&amp;exists); err != nil </span><span class="cov0" title="0">{
                apiError(w, 404, "USER_NOT_FOUND", "用户不存在")
                return
        }</span>
        <span class="cov8" title="1">s.submit(w, r, Command{Kind: "CREDIT", AccountID: b.AccountID, Key: "admin." + session(r).user.ID + "." + k, Asset: b.Asset, Amount: amount.String(), ActorID: session(r).user.ID, Reason: b.Reason})</span>
}

// allOrders 返回管理员可见的全账户订单页;每页最多 100,all 权限只由 protected(true, ...) 授予。
func (s *Server) allOrders(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">limit := 100
        if raw := r.URL.Query().Get("limit"); raw != "" </span><span class="cov0" title="0">{
                parsed, err := strconv.Atoi(raw)
                if err != nil || parsed &lt; 1 || parsed &gt; 100 </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_LIMIT", "limit 需为 1–100")
                        return
                }</span>
                <span class="cov0" title="0">limit = parsed</span>
        }
        <span class="cov8" title="1">out, err := s.Store.OrdersPage(r.Context(), "", true, limit, r.URL.Query().Get("cursor"))
        if err != nil </span><span class="cov0" title="0">{
                if errors.Is(err, ErrCursor) </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_CURSOR", "订单游标无效或已过期")
                        return
                }</span>
                <span class="cov0" title="0">apiError(w, 503, "QUERY_FAILED", "查询暂不可用")
                return</span>
        }
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// queryLimit 统一有界列表参数,默认 100;非法数值在数据库查询前拒绝。
func queryLimit(w http.ResponseWriter, r *http.Request) (int, bool) <span class="cov8" title="1">{
        limit := 100
        if raw := r.URL.Query().Get("limit"); raw != "" </span><span class="cov8" title="1">{
                n, err := strconv.Atoi(raw)
                if err != nil || n &lt; 1 || n &gt; 100 </span><span class="cov8" title="1">{
                        apiError(w, 400, "INVALID_LIMIT", "limit 需为 1–100")
                        return 0, false
                }</span>
                <span class="cov8" title="1">limit = n</span>
        }
        <span class="cov8" title="1">return limit, true</span>
}

// audit 返回认证/资金两个来源的完整 seek 分页;资金含确定业务结果,不占用日志写者连接。
func (s *Server) audit(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">limit, ok := queryLimit(w, r)
        if !ok </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">out, err := s.Store.AuditPageFor(r.Context(), session(r).user.ID, limit, r.URL.Query().Get("cursor"))
        if err != nil </span><span class="cov0" title="0">{
                if errors.Is(err, ErrCursor) </span><span class="cov0" title="0">{
                        apiError(w, 400, "INVALID_CURSOR", "审计游标无效")
                }</span> else<span class="cov0" title="0"> {
                        apiError(w, 503, "QUERY_FAILED", "审计暂不可用")
                }</span>
                <span class="cov0" title="0">return</span>
        }
        <span class="cov8" title="1">writeJSON(w, 200, out)</span>
}

// RunSampler 每 100ms 从投影读取一次完整行情,所有 WS 复用该值。
// 查询超时 2s;快照发布整体替换而不修改已发布切片,避免每连接重复 SQL。
// ctx 决定生命周期,退出必须在 Store.Close 前完成。
func (s *Server) RunSampler(ctx context.Context) <span class="cov8" title="1">{
        ticker := time.NewTicker(100 * time.Millisecond)
        defer ticker.Stop()
        for </span><span class="cov8" title="1">{
                queryCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
                x, err := s.Store.Snapshot(queryCtx)
                cancel()
                s.snapshot.mu.Lock()
                s.snapshot.value = x
                s.snapshot.err = err
                s.snapshot.mu.Unlock()
                select </span>{
                case &lt;-ctx.Done():<span class="cov8" title="1">
                        return</span>
                case &lt;-ticker.C:<span class="cov8" title="1"></span>
                }
        }
}

// stream 是只读公共行情 WS,先独立验证 Origin 再升级,不暴露账户私有数据。
// 每连接 100ms 看最新水位,相同水位不重复发送;慢客户端发送超时 2s 就断开。
// WS 仅发送最新完整快照,可跳过中间水位,不宣称逐笔可靠事件订阅。
func (s *Server) stream(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if !s.originOK(r) </span><span class="cov0" title="0">{
                apiError(w, 403, "ORIGIN_REJECTED", "请求来源不允许")
                return
        }</span>
        <span class="cov8" title="1">select </span>{
        case s.wsSlots &lt;- struct{}{}:<span class="cov8" title="1">
                defer func() </span><span class="cov8" title="1">{ &lt;-s.wsSlots }</span>()
        default:<span class="cov8" title="1">
                apiError(w, 503, "OVERLOADED", "行情连接达到上限")
                return</span>
        }
        // 已用 originOK 按部署的外部 Origin 验证来源;跳过库内默认 Host 策略以兼容反向代理。
        <span class="cov8" title="1">conn, err := websocket.Accept(w, r, &amp;websocket.AcceptOptions{InsecureSkipVerify: true})
        if err != nil </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">defer conn.CloseNow()
        ctx := conn.CloseRead(r.Context())
        ticker := time.NewTicker(100 * time.Millisecond)
        defer ticker.Stop()
        last := ""
        for </span><span class="cov8" title="1">{
                select </span>{
                case &lt;-s.streamContext.Done():<span class="cov8" title="1">
                        return</span>
                case &lt;-ctx.Done():<span class="cov0" title="0">
                        return</span>
                case &lt;-ticker.C:<span class="cov8" title="1">
                        s.snapshot.mu.RLock()
                        x, err := s.snapshot.value, s.snapshot.err
                        s.snapshot.mu.RUnlock()
                        if err != nil || x.AppliedSeq == "" || x.AppliedSeq == last </span><span class="cov0" title="0">{
                                continue</span>
                        }
                        <span class="cov8" title="1">sendCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
                        err = wsjson.Write(sendCtx, conn, x)
                        cancel()
                        if err != nil </span><span class="cov0" title="0">{
                                return
                        }</span>
                        <span class="cov8" title="1">last = x.AppliedSeq</span>
                }
        }
}

// static 提供构建好的前端和 SPA 路由回退,仅接受 GET/HEAD。
// 规范化路径限制 ../;带扩展名且不存在的资源返回 404,避免把 HTML 当 JS 响应。
func (s *Server) static(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if r.Method != "GET" &amp;&amp; r.Method != "HEAD" </span><span class="cov8" title="1">{
                http.NotFound(w, r)
                return
        }</span>
        <span class="cov8" title="1">clean := filepath.Clean("/" + r.URL.Path)
        path := filepath.Join(s.Config.FrontendDir, clean)
        if info, err := os.Stat(path); err == nil &amp;&amp; !info.IsDir() </span><span class="cov8" title="1">{
                http.ServeFile(w, r, path)
                return
        }</span>
        <span class="cov8" title="1">if strings.Contains(filepath.Base(clean), ".") </span><span class="cov8" title="1">{
                http.NotFound(w, r)
                return
        }</span>
        <span class="cov8" title="1">http.ServeFile(w, r, filepath.Join(s.Config.FrontendDir, "index.html"))</span>
}
</pre>
    
    <pre class="file" id="file4" style="display: none">package backend

// 离线运维复用 SQLite FULL/目录写者锁和业务重放,而非复制正在写入的数据库。
// 检查/备份/恢复不开放 HTTP;显式停服务取得同一锁,避免 auth 与 journal 跨库不一致。
import (
        "context"
        "crypto/sha256"
        "database/sql"
        "encoding/hex"
        "encoding/json"
        "fmt"
        "github.com/gofrs/flock"
        "io"
        "os"
        "path/filepath"
        "time"
)

// CheckReport 给出离线重放、投影对账和恢复所依赖的权威身份/水位。
// 余额/订单内容用规范表摘要比较,SQL 不计算金融金额。
type CheckReport struct {
        DatasetID     string            `json:"dataset_id"`
        EngineVersion string            `json:"engine_version"`
        JournalSeq    string            `json:"journal_seq"`
        ProjectionSeq string            `json:"projection_seq"`
        Users         int               `json:"users"`
        Orders        int               `json:"orders"`
        Checksums     map[string]string `json:"projection_checksums"`
}

// BackupManifest 绑定数据库字节摘要与离线重放结果;不是防恶意修改的签名。
// 备份包含身份/会话摘要,目录与文件使用 0700/0600,不能发布到公开下载服务。
type BackupManifest struct {
        Version   int               `json:"version"`
        CreatedAt string            `json:"created_at"`
        Report    CheckReport       `json:"report"`
        Files     map[string]string `json:"files"`
}

// databaseFiles 固定文件白名单,不从 manifest 的任意路径执行复制。
var databaseFiles = []string{"journal.db", "auth.db", "views.db"}

// OpenExistingStore 拒绝缺文件/符号链接,避免错输路径变成自动初始化空库。
// OpenStore 继续执行版本/完整性/目录锁检查,失败返回原错误。
func OpenExistingStore(dir string) (*Store, error) <span class="cov8" title="1">{
        for _, name := range databaseFiles </span><span class="cov8" title="1">{
                info, err := os.Lstat(filepath.Join(dir, name))
                if err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">if !info.Mode().IsRegular() </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("database must be a regular file: %s", name)
                }</span>
        }
        <span class="cov8" title="1">return OpenStore(dir)</span>
}

// InspectStore 在离线锁持有期间重放并补齐未完成投影,再用干净投影逐表对账。
// 这会修复正常崩溃后的落后水位;不能修复已应用前缀被人工篡改的投影。
// 临时数据库在 Linux 临时目录,由函数清理;历史命令、身份与资金不被删改。
// 操作包含两次核心重放与临时查询库,按全历史预算时间/内存/磁盘,不是轻量只读检查。
// 比较固定派生表;fresh 的新 dataset 与认证库不在业务投影摘要中,身份仍来自原 auth。
func InspectStore(s *Store) (CheckReport, error) <span class="cov8" title="1">{
        report := CheckReport{DatasetID: s.DatasetID, EngineVersion: "1", Checksums: map[string]string{}}
        r, err := NewRuntime(s)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if err = r.Close(context.Background()); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">temp, err := os.MkdirTemp("", "exchange-reconcile-")
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">defer os.RemoveAll(temp)
        fresh, err := OpenStore(temp)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">defer fresh.Close()
        // 复制的是命令值,不是 SQLite 文件;参数绑定且在一个事务中准备重放依据。
        rows, err := s.Journal.Query("SELECT seq,payload FROM commands ORDER BY seq")
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">tx, err := fresh.Journal.Begin()
        if err != nil </span><span class="cov0" title="0">{
                rows.Close()
                return report, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        for rows.Next() </span><span class="cov8" title="1">{
                var seq int64
                var raw string
                if err = rows.Scan(&amp;seq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if _, err = tx.Exec("INSERT INTO commands VALUES(?,?)", seq, raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if err = tx.Commit(); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">replay, err := NewRuntime(fresh)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if err = replay.Close(context.Background()); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">for _, table := range []struct{ name, query string }{
                {"orders", "SELECT id,account_id,status,seq,payload FROM orders ORDER BY id"},
                {"balances", "SELECT account_id,asset,available,frozen FROM balances ORDER BY account_id,asset"},
                {"levels", "SELECT side,ticks,price,quantity FROM levels ORDER BY side,ticks"},
                {"trades", "SELECT id,seq,payload FROM trades ORDER BY id"},
                {"ledger", "SELECT seq,idx,payload FROM ledger ORDER BY seq,idx"},
                {"results", "SELECT seq,account_id,key,payload FROM results ORDER BY seq"},
                {"credit_audit", "SELECT seq,payload FROM credit_audit ORDER BY seq"},
                {"progress", "SELECT id,seq FROM progress ORDER BY id"},
        } </span><span class="cov8" title="1">{
                actual, err := tableChecksum(s.Views, table.query)
                if err != nil </span><span class="cov0" title="0">{
                        return report, err
                }</span>
                <span class="cov8" title="1">expected, err := tableChecksum(fresh.Views, table.query)
                if err != nil </span><span class="cov0" title="0">{
                        return report, err
                }</span>
                <span class="cov8" title="1">if actual != expected </span><span class="cov8" title="1">{
                        return report, fmt.Errorf("projection reconciliation failed: %s; preserve original and rebuild views", table.name)
                }</span>
                <span class="cov8" title="1">report.Checksums[table.name] = actual</span>
        }
        <span class="cov8" title="1">var seq, projected int64
        if err = s.Journal.QueryRow("SELECT COALESCE(MAX(seq),0) FROM commands").Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if err = s.Views.QueryRow("SELECT seq FROM progress WHERE id=1").Scan(&amp;projected); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">report.JournalSeq = seqString(seq)
        report.ProjectionSeq = seqString(projected)
        if err = s.Auth.QueryRow("SELECT COUNT(*) FROM users").Scan(&amp;report.Users); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">err = s.Views.QueryRow("SELECT COUNT(*) FROM orders").Scan(&amp;report.Orders)
        return report, err</span>
}

// tableChecksum 用按主键排序的逐行 JSON framing 求摘要,不拼接易歧义的字段文本。
// query 只来自上面的固定常量;金额 TEXT 原样比较,不使用 SUM/REAL。
func tableChecksum(db *sql.DB, query string) (string, error) <span class="cov8" title="1">{
        rows, err := db.Query(query)
        if err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        cols, err := rows.Columns()
        if err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">hash := sha256.New()
        enc := json.NewEncoder(hash)
        for rows.Next() </span><span class="cov8" title="1">{
                values := make([]any, len(cols))
                pointers := make([]any, len(cols))
                for i := range values </span><span class="cov8" title="1">{
                        pointers[i] = &amp;values[i]
                }</span>
                <span class="cov8" title="1">if err = rows.Scan(pointers...); err != nil </span><span class="cov0" title="0">{
                        return "", err
                }</span>
                <span class="cov8" title="1">if err = enc.Encode(values); err != nil </span><span class="cov0" title="0">{
                        return "", err
                }</span>
        }
        <span class="cov8" title="1">return hex.EncodeToString(hash.Sum(nil)), rows.Err()</span>
}

// fileChecksum 对备份字节流计算 SHA256,及时关闭 FD,内存与数据库大小无关。
func fileChecksum(path string) (string, error) <span class="cov8" title="1">{
        f, err := os.Open(path)
        if err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">defer f.Close()
        h := sha256.New()
        if _, err = io.Copy(h, f); err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">return hex.EncodeToString(h.Sum(nil)), nil</span>
}

// copySynced 使用排他创建和 fsync;失败由调用者清理本次新建的目标目录,不覆盖原文件。
func copySynced(src, dst string) error <span class="cov8" title="1">{
        from, err := os.Open(src)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer from.Close()
        to, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">_, copyErr := io.Copy(to, from)
        if copyErr == nil </span><span class="cov8" title="1">{
                copyErr = to.Sync()
        }</span>
        <span class="cov8" title="1">closeErr := to.Close()
        if copyErr != nil </span><span class="cov0" title="0">{
                return copyErr
        }</span>
        <span class="cov8" title="1">return closeErr</span>
}

// syncDirectory 让目录项持久化;此项目的部署/验证目标为 Linux 本地文件系统。
func syncDirectory(path string) error <span class="cov8" title="1">{
        f, err := os.Open(path)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer f.Close()
        return f.Sync()</span>
}

// BackupStore 只复制完整 checkpoint 后的三个数据库,并最后发布 manifest。
// dst 必须不存在;不会覆盖旧备份。中断留下无 manifest 的目录,不能被 RestoreBackup 接受。
func BackupStore(s *Store, dir, dst string) (manifest BackupManifest, err error) <span class="cov8" title="1">{
        report, err := InspectStore(s)
        if err != nil </span><span class="cov0" title="0">{
                return manifest, err
        }</span>
        <span class="cov8" title="1">for _, db := range []*sql.DB{s.Journal, s.Auth, s.Views} </span><span class="cov8" title="1">{
                var busy, log, done int
                if err = db.QueryRow("PRAGMA wal_checkpoint(TRUNCATE)").Scan(&amp;busy, &amp;log, &amp;done); err != nil </span><span class="cov0" title="0">{
                        return manifest, err
                }</span>
                <span class="cov8" title="1">if busy != 0 || log != done </span><span class="cov0" title="0">{
                        return manifest, fmt.Errorf("checkpoint incomplete")
                }</span>
        }
        <span class="cov8" title="1">if err = os.Mkdir(dst, 0700); err != nil </span><span class="cov8" title="1">{
                return manifest, err
        }</span>
        // 只有此函数创建成功的目标目录才可清理,永远不删除已有目录。
        <span class="cov8" title="1">defer func() </span><span class="cov8" title="1">{
                if err != nil </span><span class="cov0" title="0">{
                        os.RemoveAll(dst)
                }</span>
        }()
        <span class="cov8" title="1">manifest = BackupManifest{Version: 1, CreatedAt: time.Now().UTC().Format(time.RFC3339Nano), Report: report, Files: map[string]string{}}
        for _, name := range databaseFiles </span><span class="cov8" title="1">{
                path := filepath.Join(dst, name)
                if err = copySynced(filepath.Join(dir, name), path); err != nil </span><span class="cov0" title="0">{
                        return manifest, err
                }</span>
                <span class="cov8" title="1">if manifest.Files[name], err = fileChecksum(path); err != nil </span><span class="cov0" title="0">{
                        return manifest, err
                }</span>
        }
        <span class="cov8" title="1">raw, err := json.MarshalIndent(manifest, "", "  ")
        if err != nil </span><span class="cov0" title="0">{
                return manifest, err
        }</span>
        <span class="cov8" title="1">f, err := os.OpenFile(filepath.Join(dst, "manifest.json"), os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
        if err != nil </span><span class="cov0" title="0">{
                return manifest, err
        }</span>
        <span class="cov8" title="1">if _, err = f.Write(append(raw, '\n')); err == nil </span><span class="cov8" title="1">{
                err = f.Sync()
        }</span>
        <span class="cov8" title="1">closeErr := f.Close()
        if err != nil </span><span class="cov0" title="0">{
                return manifest, err
        }</span>
        <span class="cov8" title="1">if closeErr != nil </span><span class="cov0" title="0">{
                return manifest, closeErr
        }</span>
        <span class="cov8" title="1">if err = syncDirectory(dst); err != nil </span><span class="cov0" title="0">{
                return manifest, err
        }</span>
        <span class="cov8" title="1">err = syncDirectory(filepath.Dir(dst))
        return manifest, err</span>
}

// RestoreBackup 先验证白名单/字节摘要,再复制到新目录,重放对账并匹配 manifest。
// 只接收不存在的目标,已有服务目录一律拒绝;数据集 ID 保持备份身份。
func RestoreBackup(src, dst string) (report CheckReport, err error) <span class="cov8" title="1">{
        f, err := os.Open(filepath.Join(src, "manifest.json"))
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">var manifest BackupManifest
        d := json.NewDecoder(io.LimitReader(f, 1&lt;&lt;20))
        d.DisallowUnknownFields()
        err = d.Decode(&amp;manifest)
        if err == nil &amp;&amp; d.Decode(new(any)) != io.EOF </span><span class="cov8" title="1">{
                err = fmt.Errorf("trailing manifest JSON")
        }</span>
        <span class="cov8" title="1">f.Close()
        if err != nil || manifest.Version != 1 || len(manifest.Files) != 3 </span><span class="cov8" title="1">{
                return report, fmt.Errorf("invalid backup manifest: %v", err)
        }</span>
        <span class="cov8" title="1">for _, name := range databaseFiles </span><span class="cov8" title="1">{
                info, e := os.Lstat(filepath.Join(src, name))
                if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">if !info.Mode().IsRegular() </span><span class="cov8" title="1">{
                        return report, fmt.Errorf("invalid backup file %s", name)
                }</span>
                <span class="cov8" title="1">sum, e := fileChecksum(filepath.Join(src, name))
                if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">if sum != manifest.Files[name] </span><span class="cov8" title="1">{
                        return report, fmt.Errorf("backup checksum mismatch: %s", name)
                }</span>
        }
        <span class="cov8" title="1">if err = os.Mkdir(dst, 0700); err != nil </span><span class="cov8" title="1">{
                return report, err
        }</span>
        <span class="cov8" title="1">defer func() </span><span class="cov8" title="1">{
                if err != nil </span><span class="cov8" title="1">{
                        os.RemoveAll(dst)
                }</span>
        }()
        <span class="cov8" title="1">for _, name := range databaseFiles </span><span class="cov8" title="1">{
                if err = copySynced(filepath.Join(src, name), filepath.Join(dst, name)); err != nil </span><span class="cov0" title="0">{
                        return report, err
                }</span>
        }
        <span class="cov8" title="1">s, err := OpenExistingStore(dst)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">report, err = InspectStore(s)
        s.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">actual, _ := json.Marshal(report)
        expected, _ := json.Marshal(manifest.Report)
        if string(actual) != string(expected) </span><span class="cov8" title="1">{
                return report, fmt.Errorf("restored data differs from manifest")
        }</span>
        <span class="cov8" title="1">if err = syncDirectory(dst); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">err = syncDirectory(filepath.Dir(dst))
        return report, err</span>
}

// RebuildViews 重建可派生库,保留原投影文件用于排错;不修改/删除权威业务记录。
// journal/auth 的 checkpoint 会改变文件/WAL 物理布局,不保证文件字节保持不变。
// 全程持有原目录锁,重放在独立 staging 中验证成功后才进入替换。
// 多个 rename 不是一个原子事务,失败时旧投影可能已部分移动;preserved 保留排错证据。
// 恢复步骤见 docs/data-lifecycle.md,不能把旧 WAL/SHM 随意附到新主库。
func RebuildViews(dir string) (report CheckReport, err error) <span class="cov8" title="1">{
        abs, err := filepath.Abs(dir)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">lock := flock.New(filepath.Join(abs, "exchange.lock"))
        ok, err := lock.TryLock()
        if err != nil || !ok </span><span class="cov0" title="0">{
                return report, fmt.Errorf("data directory already in use")
        }</span>
        <span class="cov8" title="1">defer lock.Unlock()
        // staging 放在原目录内,最终 rename 才能留在同一文件系统;需要额外数据盘空间。
        staging, err := os.MkdirTemp(abs, "rebuild-")
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">defer os.RemoveAll(staging)
        for _, name := range []string{"journal.db", "auth.db"} </span><span class="cov8" title="1">{
                path := filepath.Join(abs, name)
                info, e := os.Lstat(path)
                if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">if !info.Mode().IsRegular() </span><span class="cov0" title="0">{
                        return report, fmt.Errorf("invalid authority file")
                }</span>
                <span class="cov8" title="1">db, e := openDB(path)
                if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">var busy, log, done int
                e = db.QueryRow("PRAGMA wal_checkpoint(TRUNCATE)").Scan(&amp;busy, &amp;log, &amp;done)
                db.Close()
                if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">if busy != 0 || log != done </span><span class="cov0" title="0">{
                        return report, fmt.Errorf("checkpoint incomplete")
                }</span>
                <span class="cov8" title="1">if err = copySynced(path, filepath.Join(staging, name)); err != nil </span><span class="cov0" title="0">{
                        return report, err
                }</span>
        }
        <span class="cov8" title="1">s, err := OpenStore(staging)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">report, err = InspectStore(s)
        if err == nil </span><span class="cov8" title="1">{
                var busy, log, done int
                err = s.Views.QueryRow("PRAGMA wal_checkpoint(TRUNCATE)").Scan(&amp;busy, &amp;log, &amp;done)
                if err == nil &amp;&amp; (busy != 0 || log != done) </span><span class="cov0" title="0">{
                        err = fmt.Errorf("checkpoint incomplete")
                }</span>
        }
        <span class="cov8" title="1">s.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">preserved := filepath.Join(abs, "views-preserved-"+time.Now().UTC().Format("20060102T150405.000000000"))
        if err = os.Mkdir(preserved, 0700); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">for _, suffix := range []string{"", "-wal", "-shm"} </span><span class="cov8" title="1">{
                path := filepath.Join(abs, "views.db"+suffix)
                if _, e := os.Lstat(path); os.IsNotExist(e) </span><span class="cov8" title="1">{
                        continue</span>
                } else<span class="cov8" title="1"> if e != nil </span><span class="cov0" title="0">{
                        return report, e
                }</span>
                <span class="cov8" title="1">if err = os.Rename(path, filepath.Join(preserved, "views.db"+suffix)); err != nil </span><span class="cov0" title="0">{
                        return report, err
                }</span>
        }
        // 崩溃在此窗口时原投影仍在 preserved;服务可从 journal 创建缺失 views 继续恢复。
        <span class="cov8" title="1">if err = os.Rename(filepath.Join(staging, "views.db"), filepath.Join(abs, "views.db")); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if err = syncDirectory(preserved); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">err = syncDirectory(abs)
        return report, err</span>
}
</pre>
    
    <pre class="file" id="file5" style="display: none">package backend

// 公共市场历史通过投影只读事务访问,不与日志写者竞争连接。
import (
        "context"
        "encoding/json"
        "net/http"
        "strconv"
)

// TradePage 按唯一投影 rowid seek,避免同一个命令多笔成交只按 seq 翻页遗漏。
// rowid 仅是游标位置;业务 Trade.ID 仍由命令序号/成交下标确定。
type TradePage struct {
        DatasetID  string  `json:"dataset_id"`
        AppliedSeq string  `json:"applied_seq"`
        Items      []Trade `json:"items"`
        NextCursor string  `json:"next_cursor,omitempty"`
}

// TradesPage 首屏固定已提交成交上界;投影重建按原日志/成交顺序插入,rowid 仍稳定。
// 每命令可输出多笔成交,seq 单独 seek 会漏掉同命令其他成交;limit+1 仅探测,不消费下一页。
func (s *Store) TradesPage(ctx context.Context, limit int, raw string) (TradePage, error) <span class="cov8" title="1">{
        p := TradePage{DatasetID: s.DatasetID, Items: []Trade{}}
        if limit &lt; 1 || limit &gt; 100 </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">c, err := readAdminCursor(raw, s.DatasetID, "", "trades")
        if err != nil </span><span class="cov8" title="1">{
                return p, err
        }</span>
        <span class="cov8" title="1">if c.Phase != 0 || c.CreditUpper != 0 </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">tx, seq, err := s.projectionRead(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        p.AppliedSeq = seqString(seq)
        var upper int64
        if err = tx.QueryRow("SELECT COALESCE(MAX(rowid),0) FROM trades").Scan(&amp;upper); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">if raw == "" </span><span class="cov8" title="1">{
                c.Upper = upper
                c.Before = upper + 1
        }</span> else<span class="cov8" title="1"> if c.Upper &gt; upper </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">rows, err := tx.Query("SELECT rowid,payload FROM trades WHERE rowid&lt;=? AND rowid&lt;? ORDER BY rowid DESC LIMIT ?", c.Upper, c.Before, limit+1)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">var last int64
        more := false
        for rows.Next() </span><span class="cov8" title="1">{
                var row int64
                var raw string
                var trade Trade
                if err = rows.Scan(&amp;row, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if len(p.Items) == limit </span><span class="cov8" title="1">{
                        more = true
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;trade); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">p.Items = append(p.Items, trade)
                last = row</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">if more </span><span class="cov8" title="1">{
                c.Before = last
                p.NextCursor = adminCursorString(c)
        }</span>
        <span class="cov8" title="1">return p, tx.Commit()</span>
}

// marketBook 只支持实际已实现的 ETH-USDT,depth 有界;复用同一完整行情事务再裁剪。
func (s *Server) marketBook(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if r.PathValue("symbol") != "ETH-USDT" </span><span class="cov8" title="1">{
                apiError(w, 404, "MARKET_NOT_FOUND", "市场不存在")
                return
        }</span>
        <span class="cov8" title="1">depth := 20
        if raw := r.URL.Query().Get("depth"); raw != "" </span><span class="cov8" title="1">{
                n, err := strconv.Atoi(raw)
                if err != nil || n &lt; 1 || n &gt; 20 </span><span class="cov8" title="1">{
                        apiError(w, 400, "INVALID_DEPTH", "depth 需为 1–20")
                        return
                }</span>
                <span class="cov8" title="1">depth = n</span>
        }
        <span class="cov8" title="1">if !s.waitProjection(w, r) </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov8" title="1">snapshot, err := s.Store.Snapshot(r.Context())
        if err != nil </span><span class="cov0" title="0">{
                apiError(w, 503, "QUERY_FAILED", "行情暂不可用")
                return
        }</span>
        <span class="cov8" title="1">if len(snapshot.Bids) &gt; depth </span><span class="cov0" title="0">{
                snapshot.Bids = snapshot.Bids[:depth]
        }</span>
        <span class="cov8" title="1">if len(snapshot.Asks) &gt; depth </span><span class="cov0" title="0">{
                snapshot.Asks = snapshot.Asks[:depth]
        }</span>
        <span class="cov8" title="1">snapshot.Trades = []Trade{}
        writeJSON(w, 200, snapshot)</span>
}

// marketTrades 是公开历史成交入口;响应内水位与成交来自同一个读事务。
func (s *Server) marketTrades(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        if r.PathValue("symbol") != "ETH-USDT" </span><span class="cov8" title="1">{
                apiError(w, 404, "MARKET_NOT_FOUND", "市场不存在")
                return
        }</span>
        <span class="cov8" title="1">limit, ok := queryLimit(w, r)
        if !ok || !s.waitProjection(w, r) </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">page, err := s.Store.TradesPage(r.Context(), limit, r.URL.Query().Get("cursor"))
        if err != nil </span><span class="cov8" title="1">{
                if err == ErrCursor </span><span class="cov8" title="1">{
                        apiError(w, 400, "INVALID_CURSOR", "成交游标无效")
                }</span> else<span class="cov0" title="0"> {
                        apiError(w, 503, "QUERY_FAILED", "成交暂不可用")
                }</span>
                <span class="cov8" title="1">return</span>
        }
        <span class="cov8" title="1">writeJSON(w, 200, page)</span>
}
</pre>
    
    <pre class="file" id="file6" style="display: none">package backend

// 外围可观测性只读取原子计数器,不读取 Engine 的树/账户指针。
// 使用 Prometheus 文本格式固定输出,无业务身份/幂等键标签,避免高基数和信息泄露。
import (
        "fmt"
        "net/http"
        "net/http/pprof"
        "runtime"
        "sync/atomic"
        "time"
)

// stageTimer 记录固定阶段的累计次数、纳秒及最大耗时;最大值不是 p99。
// 计时放在 Apply 调用者中,核心仍不读取时钟;计数允许采样时略有时间差。
// journal/projection 每批 observe 一次,core 每命令一次;平均值不能混成每订单端到端延迟。
type stageTimer struct{ count, nanos, max atomic.Uint64 }

// observe 更新外围计时;CAS 只发生在指标发布,不能视为核心业务锁。
func (s *stageTimer) observe(start time.Time) <span class="cov8" title="1">{
        n := uint64(time.Since(start))
        s.nanos.Add(n)
        s.count.Add(1)
        for old := s.max.Load(); n &gt; old; old = s.max.Load() </span><span class="cov8" title="1">{
                if s.max.CompareAndSwap(old, n) </span><span class="cov8" title="1">{
                        break</span>
                }
        }
}

// runtimeMetrics 区分受理、容量拒绝、已提交、已执行与已投影,恢复前缀也初始化水位。
type runtimeMetrics struct {
        accepted, overloaded, failed          atomic.Uint64
        durable, applied, projected           atomic.Int64
        activeOrders, totalOrders, dedupeKeys atomic.Int64
        journal, core, projection             stageTimer
        recoverySeconds                       float64 // HTTP 开放前固定,只读。
}

// DiagnosticsHandler 供独立本机监听器使用,不挂到公网业务路由。
// pprof 使用标准库;生产入口强制独立 loopback IP,远程通过受控转发访问,不能借代理公开。
func (r *Runtime) DiagnosticsHandler() http.Handler <span class="cov8" title="1">{
        mux := http.NewServeMux()
        mux.HandleFunc("GET /metrics", r.metricsHTTP)
        mux.HandleFunc("/debug/pprof/", pprof.Index)
        mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
        mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
        mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
        mux.HandleFunc("/debug/pprof/trace", pprof.Trace)
        return mux
}</span>

// metricsHTTP 输出进程/队列/水位与阶段计时;无 SQL,因此慢存储时仍可观测背压。
// 三个水位独立采样,并非一个事务快照;lag 下界取零以容忍采样瞬间进度推进。
func (r *Runtime) metricsHTTP(w http.ResponseWriter, req *http.Request) <span class="cov8" title="1">{
        w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
        w.Header().Set("Cache-Control", "no-store")
        gauge := func(name string, value any) </span><span class="cov8" title="1">{
                fmt.Fprintf(w, "# TYPE exchange_%s gauge\nexchange_%s %v\n", name, name, value)
        }</span>
        <span class="cov8" title="1">counter := func(name string, value uint64) </span><span class="cov8" title="1">{
                fmt.Fprintf(w, "# TYPE exchange_%s counter\nexchange_%s %d\n", name, name, value)
        }</span>
        <span class="cov8" title="1">healthy := 0
        if r.Healthy() </span><span class="cov8" title="1">{
                healthy = 1
        }</span>
        <span class="cov8" title="1">gauge("ready", healthy)
        counter("accepted_total", r.metrics.accepted.Load())
        counter("overloaded_total", r.metrics.overloaded.Load())
        counter("failures_total", r.metrics.failed.Load())
        j, a, p := r.metrics.durable.Load(), r.metrics.applied.Load(), r.metrics.projected.Load()
        gauge("active_orders", r.metrics.activeOrders.Load())
        gauge("orders_retained", r.metrics.totalOrders.Load())
        gauge("dedupe_keys", r.metrics.dedupeKeys.Load())
        gauge("journal_seq", j)
        gauge("core_seq", a)
        gauge("projection_seq", p)
        lag := j - p
        if lag &lt; 0 </span><span class="cov8" title="1">{
                lag = 0
        }</span>
        <span class="cov8" title="1">gauge("projection_lag", lag)
        for _, q := range []struct {
                name            string
                depth, capacity int
        }{{"input", len(r.input), cap(r.input)}, {"durable", len(r.durable), cap(r.durable)}, {"results", len(r.results), cap(r.results)}, {"inflight", len(r.slots), cap(r.slots)}} </span><span class="cov8" title="1">{
                fmt.Fprintf(w, "exchange_queue_depth{stage=%q} %d\nexchange_queue_capacity{stage=%q} %d\n", q.name, q.depth, q.name, q.capacity)
        }</span>
        <span class="cov8" title="1">for _, s := range []struct {
                name  string
                timer *stageTimer
        }{{"journal", &amp;r.metrics.journal}, {"core", &amp;r.metrics.core}, {"projection", &amp;r.metrics.projection}} </span><span class="cov8" title="1">{
                fmt.Fprintf(w, "exchange_stage_seconds_sum{stage=%q} %.9f\nexchange_stage_seconds_count{stage=%q} %d\nexchange_stage_seconds_max{stage=%q} %.9f\n", s.name, float64(s.timer.nanos.Load())/1e9, s.name, s.timer.count.Load(), s.name, float64(s.timer.max.Load())/1e9)
        }</span>
        <span class="cov8" title="1">gauge("recovery_seconds", r.metrics.recoverySeconds)
        var mem runtime.MemStats
        runtime.ReadMemStats(&amp;mem)
        gauge("heap_bytes", mem.HeapAlloc)
        gauge("goroutines", runtime.NumGoroutine())
        counter("gc_cycles_total", uint64(mem.NumGC))</span>
}
</pre>
    
    <pre class="file" id="file7" style="display: none">package backend

// 本文件只访问查询投影,不触碰 Engine。协议见 docs/v0.2-design.md。
// 分页按唯一创建序号倒序 seek,避免 OFFSET 随页数增长且新增订单推移页边界。
import (
        "bytes"
        "context"
        "database/sql"
        "encoding/base64"
        "encoding/json"
        "errors"
        "fmt"
        "io"
)

// ErrCursor 表示客户端游标与当前数据集/身份/顺序不符,HTTP 应返回 400 而非存储故障。
var ErrCursor = errors.New("invalid order cursor")

// OrderPage 返回一个读取事务中的订单和水位。NextCursor 为空表示当前遍历结束。
// 游标的 Upper 固定首屏可见的创建序号上限,后续新增不混入;本页 DTO 没有 Upper 字段。
// 原订单状态仍是每页查询时的最新状态,整段遍历不是冻结所有状态的历史快照。
type OrderPage struct {
        DatasetID  string  `json:"dataset_id"`
        AppliedSeq string  `json:"applied_seq"`
        Items      []Order `json:"items"`
        NextCursor string  `json:"next_cursor,omitempty"`
}

// OrderView 是一个订单的当前投影状态,不同于 CommandLookup 中保存的首次结果快照。
type OrderView struct {
        DatasetID  string `json:"dataset_id"`
        AppliedSeq string `json:"applied_seq"`
        Order      Order  `json:"order"`
}

// CommandLookup 返回首次已投影的幂等结果。Found=false 只表示本次投影尚不可见。
// 查不到不能证明没受理;客户端仍须保留原 key/body,不能换键盲重下。
type CommandLookup struct {
        DatasetID  string  `json:"dataset_id"`
        AppliedSeq string  `json:"applied_seq"`
        Found      bool    `json:"found"`
        Result     *Result `json:"result,omitempty"`
}

// orderCursor 是分页定位信息,不是授权凭证;SQL 始终从服务端会话限定 account。
// Base64 只隐藏内部表示、不加密/签名;修改有效页边界最多改变本账户的浏览范围。
type orderCursor struct {
        Version int    `json:"v"`
        Dataset string `json:"dataset"`
        Account string `json:"account"`
        All     bool   `json:"all"`
        Upper   int64  `json:"upper"`
        Before  int64  `json:"before"`
}

// decodeCursor 严格限制长度/字段/数据集/身份以及正序号范围,不信任客户端解码后的值。
func decodeCursor(raw, dataset, account string, all bool) (orderCursor, error) <span class="cov8" title="1">{
        var c orderCursor
        if len(raw) &gt; 1024 </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">data, err := base64.RawURLEncoding.DecodeString(raw)
        if err != nil </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">d := json.NewDecoder(bytes.NewReader(data))
        d.DisallowUnknownFields()
        if err = d.Decode(&amp;c); err != nil </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">var extra any
        if d.Decode(&amp;extra) != io.EOF || c.Version != 1 || c.Dataset != dataset || c.Account != account || c.All != all || c.Upper &lt; 1 || c.Before &lt; 1 || c.Before &gt; c.Upper </span><span class="cov8" title="1">{
                return c, ErrCursor
        }</span>
        <span class="cov8" title="1">return c, nil</span>
}

// projectionRead 打开只读事务并首先读取水位,从此该事务所有查询看到同一投影版本。
// 调用者负责 Commit/Rollback;读失败立即回滚,避免占住唯一 Views 连接。
func (s *Store) projectionRead(ctx context.Context) (*sql.Tx, int64, error) <span class="cov8" title="1">{
        tx, err := s.Views.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
        if err != nil </span><span class="cov0" title="0">{
                return nil, 0, err
        }</span>
        <span class="cov8" title="1">var seq int64
        if err = tx.QueryRowContext(ctx, "SELECT seq FROM progress WHERE id=1").Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                tx.Rollback()
                return nil, 0, err
        }</span>
        <span class="cov8" title="1">return tx, seq, nil</span>
}

// OrdersPage 每页最多 100,查询 limit+1 判断是否有下一页,不做全表 COUNT/OFFSET。
// 额外一行只作探测,游标取最后已返回行;下一页重新读取探测行,不吞掉它。
// all 由受保护管理员入口设置;即使客户端伪造 all 字段,也不能改变 SQL 的权限域。
// 游标跨账户/数据集不可复用;后续页上限不能高于当前水位,避免误用旧恢复数据的游标。
func (s *Store) OrdersPage(ctx context.Context, account string, all bool, limit int, cursor string) (OrderPage, error) <span class="cov8" title="1">{
        p := OrderPage{DatasetID: s.DatasetID, Items: []Order{}}
        if limit &lt; 1 || limit &gt; 100 </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">var c orderCursor
        var err error
        if cursor != "" </span><span class="cov8" title="1">{
                if c, err = decodeCursor(cursor, s.DatasetID, account, all); err != nil </span><span class="cov8" title="1">{
                        return p, err
                }</span>
        }
        <span class="cov8" title="1">tx, seq, err := s.projectionRead(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        p.AppliedSeq = seqString(seq)
        if cursor == "" </span><span class="cov8" title="1">{
                c = orderCursor{Version: 1, Dataset: s.DatasetID, Account: account, All: all, Upper: seq}
        }</span> else<span class="cov8" title="1"> if c.Upper &gt; seq </span><span class="cov0" title="0">{
                return p, ErrCursor
        }</span>
        <span class="cov8" title="1">query := "SELECT seq,payload FROM orders WHERE seq&lt;=?"
        args := []any{c.Upper}
        if !all </span><span class="cov8" title="1">{
                query += " AND account_id=?"
                args = append(args, account)
        }</span>
        <span class="cov8" title="1">if cursor != "" </span><span class="cov8" title="1">{
                query += " AND seq&lt;?"
                args = append(args, c.Before)
        }</span>
        <span class="cov8" title="1">query += " ORDER BY seq DESC LIMIT ?"
        args = append(args, limit+1)
        rows, err := tx.QueryContext(ctx, query, args...)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">var last int64
        more := false
        for rows.Next() </span><span class="cov8" title="1">{
                var seq int64
                var raw string
                var o Order
                if err = rows.Scan(&amp;seq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if len(p.Items) == limit </span><span class="cov8" title="1">{
                        more = true
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;o); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">p.Items = append(p.Items, o)
                last = seq</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">if more </span><span class="cov8" title="1">{
                c.Before = last
                raw, err := json.Marshal(c)
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">p.NextCursor = base64.RawURLEncoding.EncodeToString(raw)</span>
        }
        <span class="cov8" title="1">return p, tx.Commit()</span>
}

// OrderByID 同事务读取当前水位及本账户订单;他人订单与不存在统一为 sql.ErrNoRows。
// ID 参数始终绑定,不拼 SQL,不提供管理员替他人下单或撤单能力。
func (s *Store) OrderByID(ctx context.Context, account, id string) (OrderView, error) <span class="cov8" title="1">{
        v := OrderView{DatasetID: s.DatasetID}
        tx, seq, err := s.projectionRead(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return v, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        v.AppliedSeq = seqString(seq)
        var raw string
        if err = tx.QueryRowContext(ctx, "SELECT payload FROM orders WHERE id=? AND account_id=?", id, account).Scan(&amp;raw); err != nil </span><span class="cov8" title="1">{
                return v, err
        }</span>
        <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;v.Order); err != nil </span><span class="cov0" title="0">{
                return v, err
        }</span>
        <span class="cov8" title="1">return v, tx.Commit()</span>
}

// LookupCommand 利用 account/key/seq 索引读取最早结果,后续冲突和重试不能覆盖首次结论。
// 查询失败不是 Found=false;拒绝首次结果也算 Found=true,保持资金变化后的稳定幂等语义。
func (s *Store) LookupCommand(ctx context.Context, account, key string) (CommandLookup, error) <span class="cov8" title="1">{
        v := CommandLookup{DatasetID: s.DatasetID}
        tx, seq, err := s.projectionRead(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return v, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        v.AppliedSeq = seqString(seq)
        var raw string
        err = tx.QueryRowContext(ctx, "SELECT payload FROM results WHERE account_id=? AND key=? ORDER BY seq LIMIT 1", account, key).Scan(&amp;raw)
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                return v, tx.Commit()
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                return v, err
        }</span>
        <span class="cov8" title="1">var result Result
        if err = json.Unmarshal([]byte(raw), &amp;result); err != nil </span><span class="cov0" title="0">{
                return v, fmt.Errorf("decode result: %w", err)
        }</span>
        <span class="cov8" title="1">v.Found = true
        v.Result = &amp;result
        return v, tx.Commit()</span>
}
</pre>
    
    <pre class="file" id="file8" style="display: none">package backend

// 本文件是外围定序/生命周期层,不把磁盘、时钟、序列化或接入锁放入 Engine。
// 每段队列只有一个工作者消费;恢复完毕后才启动它们。详见 docs/data-lifecycle.md。

import (
        "context"
        "crypto/sha256"
        "database/sql"
        "encoding/hex"
        "encoding/json"
        "fmt"
        "math"
        "sync"
        "sync/atomic"
        "time"
)

// request 在 HTTP/日志/核心之间转移命令值及单次响应通道。
// response 容量为 1:即使客户端已经离开,回包也不会阻塞后台流水线。
type request struct {
        command  Command
        response chan Result
}

// output 把已执行命令与不可再修改的结果交给投影 goroutine。
type output struct {
        request request
        result  Result
}

// Runtime 管理有界流水线:write 独占输入序号,run 独占 Engine,project 独占投影写入。
// input: Submit → write;durable: write → run;results: run → project。
// slots 从接入占用到投影提交后释放,约束全部在途工作而不只是一段队列。
// accept 只保护外围接入/关闭竞态;failure 原子发布首个失败,核心没有业务锁。
type Runtime struct {
        store          *Store
        input, durable chan request
        results        chan output
        slots          chan struct{}
        // ctx 用于流水线致命故障/超时停机;与 HTTP 请求 context 分离。
        ctx    context.Context
        cancel context.CancelFunc
        // wg 跟踪三个工作者;所有生产者关闭其下游,正常排空不提前 cancel。
        wg      sync.WaitGroup
        accept  sync.RWMutex
        closed  bool                   // 只在 accept 锁下读写,关闭 input 与 Submit 入队互斥。
        failure atomic.Pointer[string] // 首个失败原因只发布一次,后续不覆盖根因。
        seq     int64                  // 恢复时初始化,运行中仅 writer 修改;抓指标改读原子副本。
        config  RuntimeConfig          // 启动前固定,运行中不热改 channel 容量/批预算。
        metrics runtimeMetrics         // 外围发布计时/规模副本,诊断不读取 Engine 可变状态。
        hooks   runtimeHooks
}

// RuntimeConfig 是外围资源预算;FULL 耐久策略不能通过配置关闭。
// Queue 约束每段队列,Inflight 约束直到投影完成的所有工作;值不是吞吐承诺。
type RuntimeConfig struct {
        // Queue 是每段元素数,Inflight 是全流程额度,Batch 同时限制日志和投影最大条数。
        Queue, Inflight, Batch int
        BatchWait              time.Duration // 仅 writer 等待聚批;projector 不人为等待。
}

// DefaultRuntimeConfig 保留已有默认行为,部署可按实测调整。
func DefaultRuntimeConfig() RuntimeConfig <span class="cov8" title="1">{ return RuntimeConfig{1024, 2048, 64, time.Millisecond} }</span>

// runtimeHooks 只供同包测试注入故障窗口,生产 CLI/HTTP 不暴露暂停或崩溃开关。
type runtimeHooks struct {
        beforeCommit, afterCommit func(int64)
        afterApply, beforeProject func(Command)
}

// NewRuntimeWithConfig 在重放前校验预算,防止负容量 panic 或无限队列/聚批等待。
func NewRuntimeWithConfig(s *Store, c RuntimeConfig) (*Runtime, error) <span class="cov8" title="1">{
        return newRuntime(s, c, runtimeHooks{})
}</span>

// NewRuntime 在开放 HTTP 前,按日志序号恢复核心并补齐查询投影。
// 即使 views 已存在,也须从头恢复内存订单簿及去重;跳过已完成投影前缀,仅对落后部分/旧库审计迁移批写。
// 投影超前或存在缺口时拒绝启动;权威日志损坏不能用空状态继续营业。
// 当前没有持久化核心快照,恢复时间随历史增长,计时位于外围。
func NewRuntime(s *Store) (*Runtime, error) <span class="cov8" title="1">{ return NewRuntimeWithConfig(s, DefaultRuntimeConfig()) }</span>

// newRuntime 的 hooks 在工作者启动前固定,测试不能在运行中改写它们。
func newRuntime(s *Store, config RuntimeConfig, hooks runtimeHooks) (runtime *Runtime, err error) <span class="cov8" title="1">{
        // 输入损坏导致连续序号不变量失败时拒绝启动,不能让进程以半恢复核心继续服务。
        defer func() </span><span class="cov8" title="1">{
                if v := recover(); v != nil </span><span class="cov0" title="0">{
                        runtime = nil
                        err = fmt.Errorf("journal replay failed: %v", v)
                }</span>
        }()
        <span class="cov8" title="1">if config.Queue &lt; 1 || config.Queue &gt; 65536 || config.Inflight &lt; 1 || config.Inflight &gt; 131072 || config.Batch &lt; 1 || config.Batch &gt; 4096 || config.BatchWait &lt; 0 || config.BatchWait &gt; time.Second </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("invalid runtime budget")
        }</span>
        <span class="cov8" title="1">recoveryStart := time.Now()
        e := NewEngine()
        var existingProjection int64
        if err = s.Views.QueryRow("SELECT seq FROM progress WHERE id=1").Scan(&amp;existingProjection); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">var auditMigrated int
        // 无标识的旧投影需补审计,逐批执行与正常投影同一逻辑;成功后才写迁移标志。
        migrationErr := s.Views.QueryRow("SELECT 1 FROM projection_metadata WHERE key='credit_audit_v1'").Scan(&amp;auditMigrated)
        if migrationErr != nil &amp;&amp; migrationErr != sql.ErrNoRows </span><span class="cov0" title="0">{
                return nil, migrationErr
        }</span>
        <span class="cov8" title="1">commands := make([]Command, 0, 64)
        results := make([]Result, 0, 64)
        flush := func() error </span><span class="cov8" title="1">{
                if len(commands) == 0 </span><span class="cov8" title="1">{
                        return nil
                }</span>
                <span class="cov8" title="1">err := s.ProjectBatch(commands, results)
                commands = commands[:0]
                results = results[:0]
                return err</span>
        }
        <span class="cov8" title="1">rows, err := s.Journal.Query("SELECT seq,payload FROM commands ORDER BY seq")
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        for rows.Next() </span><span class="cov8" title="1">{
                var raw string
                var c Command
                var storedSeq int64
                if err = rows.Scan(&amp;storedSeq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return nil, err
                }</span>
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;c); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return nil, err
                }</span>
                <span class="cov8" title="1">if c.SchemaVersion &lt; 0 || c.SchemaVersion &gt; 1 </span><span class="cov8" title="1">{
                        rows.Close()
                        return nil, fmt.Errorf("unsupported command schema %d", c.SchemaVersion)
                }</span>
                <span class="cov8" title="1">if c.Seq != storedSeq || (c.PayloadHash != "" &amp;&amp; c.PayloadHash != payloadHash(c)) </span><span class="cov8" title="1">{
                        rows.Close()
                        return nil, fmt.Errorf("journal sequence or payload hash invalid at %d", storedSeq)
                }</span>
                <span class="cov8" title="1">if c.PayloadHash == "" </span><span class="cov0" title="0">{
                        // 兼容早期缺摘要的日志;补齐动作仍在外围,Apply 不做 JSON 或哈希计算。
                        c.PayloadHash = payloadHash(c)
                }</span>
                // 已投影前缀仍必须 Apply;否则恢复后的树/账户/去重会缺失历史。
                // 固定恢复批 64 条只影响 SQL 补后缀,不由在线 Batch 配置控制。
                <span class="cov8" title="1">r := e.Apply(c)
                if c.Seq &gt; existingProjection || (auditMigrated == 0 &amp;&amp; c.Kind == "CREDIT" &amp;&amp; c.ActorID != "" &amp;&amp; c.ActorID != "SYSTEM") </span><span class="cov8" title="1">{
                        commands = append(commands, c)
                        results = append(results, r)
                        if len(commands) == 64 </span><span class="cov0" title="0">{
                                if err = flush(); err != nil </span><span class="cov0" title="0">{
                                        rows.Close()
                                        return nil, err
                                }</span>
                        }
                }
        }
        <span class="cov8" title="1">err = rows.Err()
        rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if err = flush(); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if auditMigrated == 0 </span><span class="cov8" title="1">{
                if _, err = s.Views.Exec("INSERT OR IGNORE INTO projection_metadata VALUES('credit_audit_v1','1')"); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
        }
        <span class="cov8" title="1">var projected int64
        if err = s.Views.QueryRow("SELECT seq FROM progress WHERE id=1").Scan(&amp;projected); err != nil || projected != e.seq </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("projection ahead of journal or invalid: %d/%d", projected, e.seq)
        }</span>
        <span class="cov8" title="1">ctx, cancel := context.WithCancel(context.Background())
        r := &amp;Runtime{store: s, input: make(chan request, config.Queue), durable: make(chan request, config.Queue), results: make(chan output, config.Queue), slots: make(chan struct{}, config.Inflight), ctx: ctx, cancel: cancel, seq: e.seq, config: config, hooks: hooks}
        r.metrics.activeOrders.Store(int64(len(e.active)))
        r.metrics.totalOrders.Store(int64(len(e.orders)))
        r.metrics.dedupeKeys.Store(int64(len(e.dedupe)))
        r.metrics.durable.Store(e.seq)
        r.metrics.applied.Store(e.seq)
        r.metrics.projected.Store(e.seq)
        r.metrics.recoverySeconds = time.Since(recoveryStart).Seconds()
        r.wg.Add(3)
        go r.write()
        go r.run(e)
        go r.project()
        return r, nil</span>
}

// fail 只保存首次错误并取消流水线,交由 main 监督退出。
// 写入/投影不确定时不可跳过失败命令继续分配序号;下次启动从已提交前缀恢复。
func (r *Runtime) fail(err error) <span class="cov8" title="1">{
        message := err.Error()
        if r.failure.CompareAndSwap(nil, &amp;message) </span><span class="cov8" title="1">{
                r.metrics.failed.Add(1)
        }</span>
        <span class="cov8" title="1">r.cancel()</span>
}

// Healthy 用于就绪探针和外围监督;关闭接入或阶段失败时为 false。
func (r *Runtime) Healthy() bool <span class="cov8" title="1">{ return r.failure.Load() == nil &amp;&amp; !r.closedState() }</span>

// closedState 在外围读锁下查询接入关闭标记。
func (r *Runtime) closedState() bool <span class="cov8" title="1">{ r.accept.RLock(); defer r.accept.RUnlock(); return r.closed }</span>

// Submit 在容量允许时受理一个命令,然后等待核心结果。
// 摘要和 UTC 时间固定在外围;日志 writer 随后分配唯一序号。
// HTTP context 取消仅停止等待:已进入 input 的命令仍可能提交并执行。
// 结果未知必须用原幂等键和原内容重试,不能当作确定失败再次创建业务。
func (r *Runtime) Submit(ctx context.Context, c Command) (Result, error) <span class="cov8" title="1">{
        r.accept.RLock()
        if r.closed || r.failure.Load() != nil </span><span class="cov0" title="0">{
                r.accept.RUnlock()
                return Result{}, fmt.Errorf("service unavailable")
        }</span>
        <span class="cov8" title="1">select </span>{
        case r.slots &lt;- struct{}{}:<span class="cov8" title="1"></span>
        default:<span class="cov8" title="1">
                r.accept.RUnlock()
                r.metrics.overloaded.Add(1)
                return Result{}, fmt.Errorf("overloaded")</span>
        }
        <span class="cov8" title="1">c.SchemaVersion = 1
        c.PayloadHash = payloadHash(c)
        c.Timestamp = time.Now().UTC().Format(time.RFC3339Nano)
        q := request{c, make(chan Result, 1)}
        // 非阻塞入队失败时立即归还额度;入队成功后只有 projector 在提交后归还。
        select </span>{
        case r.input &lt;- q:<span class="cov8" title="1">
                r.metrics.accepted.Add(1)
                r.accept.RUnlock()</span>
        default:<span class="cov0" title="0">
                &lt;-r.slots
                r.accept.RUnlock()
                r.metrics.overloaded.Add(1)
                return Result{}, fmt.Errorf("overloaded")</span>
        }
        <span class="cov8" title="1">select </span>{
        case res := &lt;-q.response:<span class="cov8" title="1">
                return res, nil</span>
        case &lt;-ctx.Done():<span class="cov8" title="1">
                return Result{}, fmt.Errorf("result unknown: %w", ctx.Err())</span>
        case &lt;-r.ctx.Done():<span class="cov8" title="1">
                return Result{}, fmt.Errorf("service unavailable; result unknown")</span>
        }
}

// write 是输入日志唯一写者,按资源配置聚批(默认最多 64 条、等待 1ms)。
// SQLite synchronous=FULL 的事务提交成功是进入 durable 的必要屏障。
// 批内失败全部回滚并停机;虽然内存 seq 已前进,失败进程不会继续使用它。
// 关闭 input 后仍排空已受理请求,结束时由本生产者关闭 durable。
func (r *Runtime) write() <span class="cov8" title="1">{
        defer r.wg.Done()
        defer close(r.durable)
        for </span><span class="cov8" title="1">{
                var first request
                var ok bool
                select </span>{
                case &lt;-r.ctx.Done():<span class="cov8" title="1">
                        return</span>
                case first, ok = &lt;-r.input:<span class="cov8" title="1">
                        if !ok </span><span class="cov8" title="1">{
                                return
                        }</span>
                }
                <span class="cov8" title="1">batch := []request{first}
                timer := time.NewTimer(r.config.BatchWait)
        gather:
                for len(batch) &lt; r.config.Batch </span><span class="cov8" title="1">{
                        select </span>{
                        case q, more := &lt;-r.input:<span class="cov8" title="1">
                                if !more </span><span class="cov0" title="0">{
                                        break gather</span>
                                }
                                <span class="cov8" title="1">batch = append(batch, q)</span>
                        case &lt;-timer.C:<span class="cov8" title="1">
                                break gather</span>
                        case &lt;-r.ctx.Done():<span class="cov0" title="0">
                                timer.Stop()
                                return</span>
                        }
                }
                <span class="cov8" title="1">timer.Stop()
                commitStart := time.Now()
                tx, err := r.store.Journal.Begin()
                if err != nil </span><span class="cov8" title="1">{
                        r.fail(err)
                        return
                }</span>
                <span class="cov8" title="1">for i := range batch </span><span class="cov8" title="1">{
                        if r.seq == math.MaxInt64 </span><span class="cov8" title="1">{
                                err = fmt.Errorf("command sequence exhausted")
                                break</span>
                        }
                        <span class="cov8" title="1">r.seq++
                        batch[i].command.Seq = r.seq
                        raw, _ := json.Marshal(batch[i].command)
                        _, err = tx.Exec("INSERT INTO commands VALUES(?,?)", r.seq, string(raw))
                        if err != nil </span><span class="cov0" title="0">{
                                break</span>
                        }
                }
                <span class="cov8" title="1">if err != nil </span><span class="cov8" title="1">{
                        tx.Rollback()
                        r.fail(err)
                        return
                }</span>
                <span class="cov8" title="1">if r.hooks.beforeCommit != nil </span><span class="cov0" title="0">{
                        r.hooks.beforeCommit(r.seq)
                }</span>
                <span class="cov8" title="1">if err = tx.Commit(); err != nil </span><span class="cov0" title="0">{
                        r.fail(err)
                        return
                }</span>
                <span class="cov8" title="1">r.metrics.journal.observe(commitStart)
                r.metrics.durable.Store(r.seq)
                if r.hooks.afterCommit != nil </span><span class="cov0" title="0">{
                        r.hooks.afterCommit(r.seq)
                }</span>
                // Commit 返回成功后才发布批内请求;durable 的任何元素都已有持久化依据。
                <span class="cov8" title="1">for _, q := range batch </span><span class="cov8" title="1">{
                        select </span>{
                        case r.durable &lt;- q:<span class="cov8" title="1"></span>
                        case &lt;-r.ctx.Done():<span class="cov0" title="0">
                                return</span>
                        }
                }
        }
}

// run 是启动恢复后的唯一业务写者,只执行已经过提交屏障的命令。
// Apply 输出副本进入 results,不在此阶段编码 JSON、访问数据库或网络。
// recover 仅把内部异常转成失败停机信号,不会在受损核心上继续撮合。
func (r *Runtime) run(e *Engine) <span class="cov8" title="1">{
        defer r.wg.Done()
        defer close(r.results)
        defer func() </span><span class="cov8" title="1">{
                if v := recover(); v != nil </span><span class="cov0" title="0">{
                        r.fail(fmt.Errorf("core failure: %v", v))
                }</span>
        }()
        <span class="cov8" title="1">for </span><span class="cov8" title="1">{
                select </span>{
                case &lt;-r.ctx.Done():<span class="cov8" title="1">
                        return</span>
                case q, ok := &lt;-r.durable:<span class="cov8" title="1">
                        if !ok </span><span class="cov8" title="1">{
                                return
                        }</span>
                        <span class="cov8" title="1">applyStart := time.Now()
                        result := e.Apply(q.command)
                        r.metrics.core.observe(applyStart)
                        r.metrics.applied.Store(q.command.Seq)
                        r.metrics.activeOrders.Store(int64(len(e.active)))
                        r.metrics.totalOrders.Store(int64(len(e.orders)))
                        r.metrics.dedupeKeys.Store(int64(len(e.dedupe)))
                        if r.hooks.afterApply != nil </span><span class="cov0" title="0">{
                                r.hooks.afterApply(q.command)
                        }</span>
                        <span class="cov8" title="1">select </span>{
                        case r.results &lt;- output{q, result}:<span class="cov8" title="1"></span>
                        case &lt;-r.ctx.Done():<span class="cov0" title="0">
                                return</span>
                        }
                }
        }
}

// project 先回传已持久化且已执行的结果,再以事务更新查询投影。
// 因此写成功与立即读可见不是同一时刻,读自己的写应带 min_seq。
// 只有投影事务成功才释放 slot;慢存储将背压到接入,防止积压无限增长。
// 投影失败后先前回包仍有日志可恢复,但进程停止继续服务。
func (r *Runtime) project() <span class="cov8" title="1">{
        defer r.wg.Done()
        for </span><span class="cov8" title="1">{
                var first output
                var ok bool
                select </span>{
                case &lt;-r.ctx.Done():<span class="cov8" title="1">
                        return</span>
                case first, ok = &lt;-r.results:<span class="cov8" title="1">
                        if !ok </span><span class="cov8" title="1">{
                                return
                        }</span>
                }
                // 只取已经就绪的连续结果,不复用日志的 1ms 聚批等待;减少低流量查询可见延迟。
                <span class="cov8" title="1">batch := []output{first}
        gather:
                for len(batch) &lt; r.config.Batch </span><span class="cov8" title="1">{
                        select </span>{
                        case out, more := &lt;-r.results:<span class="cov8" title="1">
                                if !more </span><span class="cov0" title="0">{
                                        break gather</span>
                                }
                                <span class="cov8" title="1">batch = append(batch, out)</span>
                        default:<span class="cov8" title="1">
                                break gather</span>
                        }
                }
                <span class="cov8" title="1">commands := make([]Command, len(batch))
                results := make([]Result, len(batch))
                for i, out := range batch </span><span class="cov8" title="1">{
                        if r.hooks.beforeProject != nil </span><span class="cov8" title="1">{
                                r.hooks.beforeProject(out.request.command)
                        }</span>
                        // 调用者和投影异步执行,响应必须拥有独立指针/切片。
                        // 只复制 Result 结构会共用底层数组,使 Go 调用者能改写尚未落库的数据。
                        <span class="cov8" title="1">out.request.response &lt;- copyResult(out.result)
                        commands[i] = out.request.command
                        results[i] = out.result</span>
                }
                <span class="cov8" title="1">start := time.Now()
                if err := r.store.ProjectBatch(commands, results); err != nil </span><span class="cov8" title="1">{
                        r.fail(err)
                        return
                }</span>
                <span class="cov8" title="1">r.metrics.projection.observe(start)
                r.metrics.projected.Store(commands[len(commands)-1].Seq)
                // 回包/HTTP 断开不会释放额度;本批 SQL Commit 成功才算可靠工作完成。
                for range batch </span><span class="cov8" title="1">{
                        &lt;-r.slots
                }</span>
        }
}

// copyResult 在外围划分调用者与投影的数据所有权;字符串字段是不可变值。
// 所有切片元素均为纯值结构,复制切片即可;Order/Error 指针另复制一份。
// 不用 JSON 编解码做深拷贝,避免把投影专用字段丢掉或引入无谓的序列化成本。
// 若以后切片元素新增引用字段,必须递归复制并补所有权测试;当前纯值假设才使切片复制充分。
func copyResult(r Result) Result <span class="cov8" title="1">{
        if r.Order != nil </span><span class="cov8" title="1">{
                order := *r.Order
                r.Order = &amp;order
        }</span>
        <span class="cov8" title="1">if r.Error != nil </span><span class="cov8" title="1">{
                err := *r.Error
                r.Error = &amp;err
        }</span>
        <span class="cov8" title="1">r.Orders = append([]Order(nil), r.Orders...)
        r.Balances = append([]Balance(nil), r.Balances...)
        r.Trades = append([]Trade(nil), r.Trades...)
        r.Entries = append([]Entry(nil), r.Entries...)
        return r</span>
}

// Close 排空顺序:锁住并关闭 input → writer 关闭 durable → core 关闭 results → projector 完成。
// 关闭期间不先 cancel,避免正常退出丢掉已受理工作;超过 deadline 才取消并等待工作者结束。
// Store 必须在此函数之后关闭,防止正在投影/提交时先关闭数据库。
func (r *Runtime) Close(ctx context.Context) error <span class="cov8" title="1">{
        r.accept.Lock()
        if !r.closed </span><span class="cov8" title="1">{
                r.closed = true
                close(r.input)
        }</span>
        <span class="cov8" title="1">r.accept.Unlock()
        done := make(chan struct{})
        go func() </span><span class="cov8" title="1">{ r.wg.Wait(); close(done) }</span>()
        <span class="cov8" title="1">select </span>{
        case &lt;-done:<span class="cov8" title="1">
                r.cancel()
                if p := r.failure.Load(); p != nil </span><span class="cov8" title="1">{
                        return fmt.Errorf("%s", *p)
                }</span>
                <span class="cov8" title="1">return nil</span>
        case &lt;-ctx.Done():<span class="cov0" title="0">
                r.cancel()
                &lt;-done
                return ctx.Err()</span>
        }
}

// payloadHash 在外围编码确定业务字段并计算 SHA256。
// 剔除 seq、时间和摘要自身,使网络重试仍能识别同一内容。
// 接入层先规范化金额,因而 1.00 与 1 不会产生不同摘要;ActorID/Reason 仍纳入语义。
func payloadHash(c Command) string <span class="cov8" title="1">{
        c.Seq = 0
        // 输入格式版本不改变业务内容;旧库同键重试仍应得到首次结果。
        c.SchemaVersion = 0
        c.Timestamp = ""
        c.PayloadHash = ""
        raw, _ := json.Marshal(c)
        hash := sha256.Sum256(raw)
        return hex.EncodeToString(hash[:])
}</span>
</pre>
    
    <pre class="file" id="file9" style="display: none">package backend

// 三库各自事务,不提供跨库原子提交。journal/auth 权威,views 派生。
// 同一进程的读写仍争用每库唯一连接;运维仅停机持有目录锁时执行,见 docs/data-lifecycle.md。

import (
        "context"
        "database/sql"
        "encoding/hex"
        "encoding/json"
        "fmt"
        "net/url"
        "os"
        "path/filepath"
        "strconv"
        "strings"

        "github.com/gofrs/flock"
        _ "modernc.org/sqlite"
)

// Store 分离三个数据库:Journal 是输入权威,Auth 是身份/会话权威,Views 是可重建查询表。
// lock 是整个数据目录的进程独占锁,不是核心撮合锁;它不提供跨主机防双主保证。
type Store struct {
        Journal, Views, Auth *sql.DB
        // DatasetID 在 journal 元数据中持久化,只在旧库首次升级或新建时生成,重启/投影重建不变。
        DatasetID string
        lock      *flock.Flock
        // beforeProjectCommit 仅同包测试注入事务中途崩溃;生产保持 nil。
        beforeProjectCommit func(Command)
}

// openDB 为每条新连接通过 DSN 设置 WAL/FULL/外键及最多 5s busy_timeout。
// 每个数据库最多一条连接,外围读取与该库写入会竞争连接,不宣称无限查询吞吐。
// Ping 提前暴露打开失败;SQL 与驱动仅存在于外围。
func openDB(path string) (*sql.DB, error) <span class="cov8" title="1">{
        dsn := "file:" + url.PathEscape(path) + "?_pragma=journal_mode(WAL)&amp;_pragma=synchronous(FULL)&amp;_pragma=foreign_keys(ON)&amp;_pragma=busy_timeout(5000)"
        db, err := sql.Open("sqlite", dsn)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">db.SetMaxOpenConns(1)
        if err = db.Ping(); err != nil </span><span class="cov8" title="1">{
                db.Close()
                return nil, err
        }</span>
        <span class="cov8" title="1">return db, nil</span>
}

// OpenStore 创建私有目录、独占写者锁并验证 SQLite/完整性/引擎版本,然后建表。
// 不兼容版本或坏库直接拒绝,不自动删除权威数据。
// 金额以 TEXT 存储,避免 SQLite REAL 或 SUM 把精确金额转为浮点。
func OpenStore(dir string) (s *Store, err error) <span class="cov8" title="1">{
        if err = os.MkdirAll(dir, 0700); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">abs, _ := filepath.Abs(dir)
        s = &amp;Store{lock: flock.New(filepath.Join(abs, "exchange.lock"))}
        ok, err := s.lock.TryLock()
        if err != nil || !ok </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("data directory already in use: %v", err)
        }</span>
        // 捕获已分配实例:return nil, err 会把具名返回值 s 改为 nil,不能在 defer 中再读取 s。
        // 即使版本/建表检查失败,也必须释放已打开连接和目录锁。
        <span class="cov8" title="1">opened := s
        defer func() </span><span class="cov8" title="1">{
                if err != nil </span><span class="cov8" title="1">{
                        opened.Close()
                }</span>
        }()
        <span class="cov8" title="1">if s.Journal, err = openDB(filepath.Join(abs, "journal.db")); err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if s.Views, err = openDB(filepath.Join(abs, "views.db")); err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if s.Auth, err = openDB(filepath.Join(abs, "auth.db")); err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">var version string
        if err = s.Journal.QueryRow("SELECT sqlite_version()").Scan(&amp;version); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">parts := strings.Split(version, ".")
        if len(parts) != 3 </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("invalid SQLite version")
        }</span>
        <span class="cov8" title="1">major, _ := strconv.Atoi(parts[0])
        minor, _ := strconv.Atoi(parts[1])
        patch, _ := strconv.Atoi(parts[2])
        if major &lt; 3 || (major == 3 &amp;&amp; (minor &lt; 51 || (minor == 51 &amp;&amp; patch &lt; 3))) </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("SQLite %s lacks required WAL fix", version)
        }</span>
        <span class="cov8" title="1">for _, db := range []*sql.DB{s.Journal, s.Views, s.Auth} </span><span class="cov8" title="1">{
                var check string
                if err = db.QueryRow("PRAGMA quick_check").Scan(&amp;check); err != nil || check != "ok" </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("database integrity check failed: %s %v", check, err)
                }</span>
        }
        <span class="cov8" title="1">_, err = s.Journal.Exec(`CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS commands(seq INTEGER PRIMARY KEY,payload TEXT NOT NULL);
INSERT OR IGNORE INTO metadata VALUES('engine_version','1');`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">var engineVersion string
        if err = s.Journal.QueryRow("SELECT value FROM metadata WHERE key='engine_version'").Scan(&amp;engineVersion); err != nil || engineVersion != "1" </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("unsupported engine version %s", engineVersion)
        }</span>
        <span class="cov8" title="1">if err = s.Journal.QueryRow("SELECT value FROM metadata WHERE key='dataset_id'").Scan(&amp;s.DatasetID); err == sql.ErrNoRows </span><span class="cov8" title="1">{
                // 随机 ID 在外围生成;旧输入日志不改写,当前独占锁保证初始化只有一个进程。
                if s.DatasetID, err = randomToken(); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">_, err = s.Journal.Exec("INSERT INTO metadata VALUES('dataset_id',?)", s.DatasetID)</span>
        }
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if decoded, decodeErr := hex.DecodeString(s.DatasetID); decodeErr != nil || len(decoded) != 32 </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("invalid dataset identity")
        }</span>
        <span class="cov8" title="1">_, err = s.Views.Exec(`CREATE TABLE IF NOT EXISTS orders(id TEXT PRIMARY KEY, account_id TEXT NOT NULL, status TEXT NOT NULL, seq INTEGER NOT NULL,payload TEXT NOT NULL);
CREATE INDEX IF NOT EXISTS orders_account ON orders(account_id,seq);
CREATE TABLE IF NOT EXISTS balances(account_id TEXT,asset TEXT,available TEXT,frozen TEXT,PRIMARY KEY(account_id,asset));
CREATE TABLE IF NOT EXISTS levels(side TEXT,ticks INTEGER,price TEXT,quantity TEXT,PRIMARY KEY(side,ticks));
CREATE TABLE IF NOT EXISTS trades(id TEXT PRIMARY KEY,seq INTEGER,payload TEXT);
CREATE TABLE IF NOT EXISTS ledger(seq INTEGER,idx INTEGER,payload TEXT,PRIMARY KEY(seq,idx));
CREATE TABLE IF NOT EXISTS results(seq INTEGER PRIMARY KEY,account_id TEXT,key TEXT,payload TEXT);
CREATE INDEX IF NOT EXISTS results_account_key ON results(account_id,key,seq);
CREATE INDEX IF NOT EXISTS orders_seq ON orders(seq);
CREATE TABLE IF NOT EXISTS projection_metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS credit_audit(seq INTEGER PRIMARY KEY,payload TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS progress(id INTEGER PRIMARY KEY CHECK(id=1),seq INTEGER);
INSERT OR IGNORE INTO progress VALUES(1,0);`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">_, err = s.Auth.Exec(`CREATE TABLE IF NOT EXISTS users(id TEXT PRIMARY KEY,email TEXT NOT NULL UNIQUE,password_hash TEXT NOT NULL,role TEXT NOT NULL CHECK(role IN ('USER','ADMIN')),disabled INTEGER NOT NULL DEFAULT 0,created_at TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS sessions(token_hash TEXT PRIMARY KEY,user_id TEXT NOT NULL REFERENCES users(id),csrf TEXT NOT NULL,expires_at INTEGER NOT NULL);
CREATE INDEX IF NOT EXISTS session_user ON sessions(user_id);
CREATE TABLE IF NOT EXISTS auth_audit(id INTEGER PRIMARY KEY AUTOINCREMENT,actor_id TEXT,target_id TEXT,action TEXT,timestamp TEXT);`)
        return s, err</span>
}

// Close 在 runtime 和采样器停止后关闭所有 DB,再释放目录独占锁。
func (s *Store) Close() <span class="cov8" title="1">{
        for _, db := range []*sql.DB{s.Journal, s.Views, s.Auth} </span><span class="cov8" title="1">{
                if db != nil </span><span class="cov8" title="1">{
                        db.Close()
                }</span>
        }
        <span class="cov8" title="1">if s.lock != nil </span><span class="cov8" title="1">{
                s.lock.Unlock()
        }</span>
}

// Project 将一个命令的订单、余额、成交、分录、结果及水位原子写入 Views。
// 已应用前缀无副作用跳过;跳跃序号拒绝,不能伪造进度掩盖漏数据。
// 价档先扣旧余量再加新余量,与订单及水位同事务提交;失败由 deferred rollback 撤销。
// 拒绝和幂等重试没有资金增量,但仍推进命令水位,便于 min_seq 查询。
func (s *Store) Project(c Command, r Result) error <span class="cov0" title="0">{ return s.ProjectBatch([]Command{c}, []Result{r}) }</span>

// ProjectBatch 在一个 FULL 事务中提交连续结果及最终水位,失败整批回滚。
// 命令/结果保持配对且不被修改;每条仍执行原先相同的账户/订单/分录逻辑。
func (s *Store) ProjectBatch(commands []Command, results []Result) error <span class="cov8" title="1">{
        if len(commands) != len(results) || len(commands) == 0 </span><span class="cov0" title="0">{
                return fmt.Errorf("invalid projection batch")
        }</span>
        <span class="cov8" title="1">tx, err := s.Views.Begin()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        for i, c := range commands </span><span class="cov8" title="1">{
                if err = s.applyProjected(tx, c, results[i]); err != nil </span><span class="cov8" title="1">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">return tx.Commit()</span>
}

// applyProjected 只由外围投影持有者调用,事务归 ProjectBatch 所有,不能在这里提前提交。
func (s *Store) applyProjected(tx *sql.Tx, c Command, r Result) error <span class="cov8" title="1">{
        var err error
        var current int64
        if err = tx.QueryRow("SELECT seq FROM progress WHERE id=1").Scan(&amp;current); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        // 正常已提交前缀不重做余额/成交/分录;仅旧库迁移补缺失的资金审计。
        <span class="cov8" title="1">if c.Seq &lt;= current </span><span class="cov0" title="0">{
                if c.Kind == "CREDIT" &amp;&amp; c.ActorID != "" &amp;&amp; c.ActorID != "SYSTEM" </span><span class="cov0" title="0">{
                        a := Audit{ActorID: c.ActorID, TargetID: c.AccountID, Action: "CREDIT", Timestamp: c.Timestamp, Source: "CREDIT", Seq: seqString(c.Seq), Asset: c.Asset, Amount: c.Amount, Reason: c.Reason, Code: r.Code, Replayed: r.Replayed}
                        raw, _ := json.Marshal(a)
                        if _, err = tx.Exec("INSERT OR IGNORE INTO credit_audit VALUES(?,?)", c.Seq, string(raw)); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">return nil</span>
                }
                <span class="cov0" title="0">return nil</span>
        }
        <span class="cov8" title="1">if c.Seq != current+1 </span><span class="cov0" title="0">{
                return fmt.Errorf("projection gap: %d -&gt; %d", current, c.Seq)
        }</span>
        // 用旧余量的负数减档、再加新余量;例如旧 3 新 1,该价档净减少 2。
        // 不是每次把新余量直接累加,否则重复订单更新会扩大盘口。
        <span class="cov8" title="1">for _, o := range r.Orders </span><span class="cov8" title="1">{
                var previous string
                err = tx.QueryRow("SELECT payload FROM orders WHERE id=?", o.ID).Scan(&amp;previous)
                if err != nil &amp;&amp; err != sql.ErrNoRows </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                        var old Order
                        if err = json.Unmarshal([]byte(previous), &amp;old); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov8" title="1">if err = adjustLevel(tx, old, dec(old.Remaining).Neg().String()); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
                <span class="cov8" title="1">if err = adjustLevel(tx, o, o.Remaining); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">raw, _ := json.Marshal(o)
                _, err = tx.Exec("INSERT INTO orders VALUES(?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET status=excluded.status,payload=excluded.payload", o.ID, o.AccountID, o.Status, o.Seq, string(raw))
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        // Balances 是变更后完整值,直接覆盖;Entries 才是有符号增量,不能再加一次余额。
        <span class="cov8" title="1">for _, b := range r.Balances </span><span class="cov8" title="1">{
                _, err = tx.Exec("INSERT INTO balances VALUES(?,?,?,?) ON CONFLICT(account_id,asset) DO UPDATE SET available=excluded.available,frozen=excluded.frozen", b.AccountID, b.Asset, b.Available, b.Frozen)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">for _, t := range r.Trades </span><span class="cov8" title="1">{
                raw, _ := json.Marshal(t)
                if _, err = tx.Exec("INSERT INTO trades VALUES(?,?,?)", t.ID, c.Seq, string(raw)); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">for i, v := range r.Entries </span><span class="cov8" title="1">{
                raw, _ := json.Marshal(v)
                if _, err = tx.Exec("INSERT INTO ledger VALUES(?,?,?)", c.Seq, i, string(raw)); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">if c.Kind == "CREDIT" &amp;&amp; c.ActorID != "" &amp;&amp; c.ActorID != "SYSTEM" </span><span class="cov8" title="1">{
                a := Audit{ActorID: c.ActorID, TargetID: c.AccountID, Action: "CREDIT", Timestamp: c.Timestamp, Source: "CREDIT", Seq: seqString(c.Seq), Asset: c.Asset, Amount: c.Amount, Reason: c.Reason, Code: r.Code, Replayed: r.Replayed}
                raw, _ := json.Marshal(a)
                if _, err = tx.Exec("INSERT INTO credit_audit VALUES(?,?)", c.Seq, string(raw)); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        // 每个输入 envelope 都存结果并推进 progress;首次按键结论由查询最早 seq 获取。
        // 同键确认也有本次 processed_seq,但不产生新的成交/资金副作用。
        <span class="cov8" title="1">raw, _ := json.Marshal(r)
        if _, err = tx.Exec("INSERT INTO results VALUES(?,?,?,?)", c.Seq, c.AccountID, c.Key, string(raw)); err != nil </span><span class="cov8" title="1">{
                return err
        }</span>
        <span class="cov8" title="1">if _, err = tx.Exec("UPDATE progress SET seq=? WHERE id=1", c.Seq); err != nil </span><span class="cov8" title="1">{
                return err
        }</span>
        <span class="cov8" title="1">if s.beforeProjectCommit != nil </span><span class="cov0" title="0">{
                s.beforeProjectCommit(c)
        }</span>
        <span class="cov8" title="1">return nil</span>
}

// Balances 只读指定账户的投影余额,字符串原样返回,不在 SQL 中作金额运算。
func (s *Store) Balances(ctx context.Context, account string) ([]Balance, error) <span class="cov8" title="1">{
        rows, err := s.Views.QueryContext(ctx, "SELECT account_id,asset,available,frozen FROM balances WHERE account_id=? ORDER BY asset", account)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        out := []Balance{}
        for rows.Next() </span><span class="cov8" title="1">{
                var b Balance
                if err = rows.Scan(&amp;b.AccountID, &amp;b.Asset, &amp;b.Available, &amp;b.Frozen); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">out = append(out, b)</span>
        }
        <span class="cov8" title="1">return out, rows.Err()</span>
}

// Snapshot 在同一个只读事务中读取水位、前 20 档及最近 50 成交。
// 事务避免水位和数据来自不同瞬间;价档已有增量聚合,不扫描所有活动订单。
// SQL 排序方向只从固定枚举选择,用户输入仅作为参数绑定。
func (s *Store) Snapshot(ctx context.Context) (Snapshot, error) <span class="cov8" title="1">{
        x := Snapshot{DatasetID: s.DatasetID, Bids: []Level{}, Asks: []Level{}, Trades: []Trade{}}
        tx, err := s.Views.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
        if err != nil </span><span class="cov0" title="0">{
                return x, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var seq int64
        if err = tx.QueryRow("SELECT seq FROM progress WHERE id=1").Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return x, err
        }</span>
        <span class="cov8" title="1">x.AppliedSeq = seqString(seq)
        for _, side := range []string{"BUY", "SELL"} </span><span class="cov8" title="1">{
                order := "ASC"
                if side == "BUY" </span><span class="cov8" title="1">{
                        order = "DESC"
                }</span>
                <span class="cov8" title="1">rows, err := tx.Query("SELECT price,quantity FROM levels WHERE side=? ORDER BY ticks "+order+" LIMIT 20", side)
                if err != nil </span><span class="cov0" title="0">{
                        return x, err
                }</span>
                <span class="cov8" title="1">for rows.Next() </span><span class="cov0" title="0">{
                        var l Level
                        if err = rows.Scan(&amp;l.Price, &amp;l.Quantity); err != nil </span><span class="cov0" title="0">{
                                rows.Close()
                                return x, err
                        }</span>
                        <span class="cov0" title="0">if side == "BUY" </span><span class="cov0" title="0">{
                                x.Bids = append(x.Bids, l)
                        }</span> else<span class="cov0" title="0"> {
                                x.Asks = append(x.Asks, l)
                        }</span>
                }
                <span class="cov8" title="1">err = rows.Err()
                rows.Close()
                if err != nil </span><span class="cov0" title="0">{
                        return x, err
                }</span>
        }
        // 同 seq 的 id 是文本排序(如 :9 与 :10),不宣称成交数字下标严格倒序。
        // 完整成交历史用 market_query.go 的 rowid seek 保证分页不漏。
        <span class="cov8" title="1">rows, err := tx.Query("SELECT payload FROM trades ORDER BY seq DESC,id DESC LIMIT 50")
        if err != nil </span><span class="cov0" title="0">{
                return x, err
        }</span>
        <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                var raw string
                var t Trade
                if err = rows.Scan(&amp;raw); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return x, err
                }</span>
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;t); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return x, err
                }</span>
                <span class="cov8" title="1">x.Trades = append(x.Trades, t)</span>
        }
        <span class="cov8" title="1">err = rows.Err()
        rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return x, err
        }</span>
        <span class="cov8" title="1">return x, tx.Commit()</span>
}

// adjustLevel 在投影事务里用 decimal 增减档位数量,零档删除,负档拒绝。
// 例如旧挂单余量 1、新余量 0.6:先 -1 再 +0.6,深度准确减少 0.4。
// ticks 只用于索引;业务 price/quantity 仍存十进制字符串。
func adjustLevel(tx *sql.Tx, o Order, delta string) error <span class="cov8" title="1">{
        if dec(delta).IsZero() </span><span class="cov8" title="1">{
                return nil
        }</span>
        <span class="cov8" title="1">ticks := dec(o.Price).Shift(2).IntPart()
        var current string
        err := tx.QueryRow("SELECT quantity FROM levels WHERE side=? AND ticks=?", o.Side, ticks).Scan(&amp;current)
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                current = "0"
        }</span> else<span class="cov8" title="1"> if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">quantity := dec(current).Add(dec(delta))
        if quantity.IsNegative() </span><span class="cov0" title="0">{
                return fmt.Errorf("negative projection level")
        }</span>
        <span class="cov8" title="1">if quantity.IsZero() </span><span class="cov8" title="1">{
                _, err = tx.Exec("DELETE FROM levels WHERE side=? AND ticks=?", o.Side, ticks)
        }</span> else<span class="cov8" title="1"> {
                _, err = tx.Exec("INSERT INTO levels VALUES(?,?,?,?) ON CONFLICT(side,ticks) DO UPDATE SET quantity=excluded.quantity", o.Side, ticks, o.Price, quantity.String())
        }</span>
        <span class="cov8" title="1">return err</span>
}
</pre>
    
    <pre class="file" id="file10" style="display: none">package backend

import (
        "regexp"
        "strconv"

        "github.com/shopspring/decimal"
)

// User 是可公开的身份信息;密码摘要与会话凭证不进入此 DTO。
// 角色来自 auth.db,客户端不能在注册请求中指定角色。
type User struct {
        ID        string `json:"id"`
        Email     string `json:"email"`
        Role      string `json:"role"`
        Disabled  bool   `json:"disabled"`
        CreatedAt string `json:"created_at"`
}

// Command 是日志中的确定性业务输入,跨队列按值传递。
// Seq、Timestamp、PayloadHash 由外围固定;核心重放时不重新生成。
// AccountID 是受影响资金账户,ActorID 是管理员/系统操作者,二者可能不同。
type Command struct {
        // SchemaVersion=1 为当前输入格式;早期日志省略字段视为兼容版本 0,未知版本拒绝重放。
        SchemaVersion int `json:"schema_version,omitempty"`
        // PayloadHash 不由 HTTP 客户端指定;外围对规范化业务内容计算后随命令持久化。
        PayloadHash string `json:"payload_hash"`
        // Seq 是全局输入顺序,含注资、下单、撤单、拒绝及重试;下单 ID 因此不必连续。
        Seq int64 `json:"seq"`
        // AccountID 由可信会话或管理员目标解析生成,决定资金与幂等范围。
        AccountID string `json:"account_id"`
        Key       string `json:"key"`
        // Kind 为 PLACE/CANCEL/CREDIT;后续增加命令种类必须考虑历史重放兼容。
        Kind string `json:"kind"`
        Side string `json:"side,omitempty"`
        Type string `json:"type,omitempty"`
        TIF  string `json:"time_in_force,omitempty"`
        // Price 是限价或市价保护价(2 位),Quantity 为 ETH 数量(4 位)。
        Price    string `json:"price,omitempty"`
        Quantity string `json:"quantity,omitempty"`
        OrderID  string `json:"order_id,omitempty"`
        // CREDIT 才用 Asset/Amount;USDT 最多 6 位以容纳价格 2 位 × 数量 4 位的成交额。
        Asset  string `json:"asset,omitempty"`
        Amount string `json:"amount,omitempty"`
        // 管理操作保留操作者与原因;系统初始化的 ActorID 为 SYSTEM。
        ActorID string `json:"actor_id,omitempty"`
        Reason  string `json:"reason,omitempty"`
        // Timestamp 是受理时刻,不作为优先级裁决;FIFO 以实际日志顺序为准。
        Timestamp string `json:"timestamp"`
}

// Order 记录订单生命周期,金额/ID 使用字符串避免浮点与 JS 整数精度问题。
// Quantity = Remaining + Filled + Canceled;已结束订单 Remaining 必须为零。
// Seq 是内部创建顺序,JSON 不暴露它;业务 ID 已采用同一序号的字符串。
type Order struct {
        ID        string `json:"id"`
        AccountID string `json:"account_id"`
        Side      string `json:"side"`
        Type      string `json:"type"`
        TIF       string `json:"time_in_force"`
        Price     string `json:"price"`
        Quantity  string `json:"quantity"`
        // Remaining 只有活动挂单可非零;IOC 未成交部分归 Canceled,不继续挂簿。
        Remaining string `json:"remaining_quantity"`
        Filled    string `json:"filled_quantity"`
        Canceled  string `json:"canceled_quantity"`
        Status    string `json:"status"`
        // CANCELED 可同时有 Filled&gt;0;Reason 说明用户撤单/自成交/流动性/保护价原因。
        Reason    string `json:"cancel_reason,omitempty"`
        CreatedAt string `json:"created_at"`
        Seq       int64  `json:"-"`
}

// Balance 区分可用与冻结资产。挂单冻结,成交扣除冻结,撤单释放。
// 核心拥有可变原件,返回给投影的 Balance 是值副本。
type Balance struct {
        AccountID string `json:"account_id"`
        Asset     string `json:"asset"`
        Available string `json:"available"`
        Frozen    string `json:"frozen"`
}

// Trade 是不可变成交事实,按 maker 价格结算。
// ID 由命令序号和该命令内成交下标组成,重放得到相同 ID。
type Trade struct {
        ID        string `json:"id"`
        MakerID   string `json:"maker_order_id"`
        TakerID   string `json:"taker_order_id"`
        Price     string `json:"price"`
        Quantity  string `json:"quantity"`
        Side      string `json:"side"`
        Timestamp string `json:"timestamp"`
}

// Entry 是一笔账户资产分录,记录可用/冻结的有符号增量。
// RESERVE/RELEASE 只在账户内移动资金,TRADE 在买卖双方间转移资产。
// 本演示零手续费;只有 CREDIT 改变系统模拟资产总供给。
type Entry struct {
        AccountID      string `json:"account_id"`
        Asset          string `json:"asset"`
        AvailableDelta string `json:"available_delta"`
        FrozenDelta    string `json:"frozen_delta"`
        Reason         string `json:"reason"`
}

// Result 同时承载对外响应及投影更新副本。json:"-" 字段仅在内存流水线传递。
// ProcessedSeq 是本次命令进度;ResultSeq 是首次业务结果的序号,重试时可能不同。
// Order 指向脱离核心状态的快照;幂等重试不会再次输出成交或分录。
// 结构体值传递仍共享指针与切片;runtime 回包前 copyResult 再隔离 HTTP 与投影所有权。
type Result struct {
        ProcessedSeq string       `json:"processed_seq"`
        ResultSeq    string       `json:"result_seq"`
        Order        *Order       `json:"order,omitempty"`
        Code         string       `json:"code,omitempty"`
        Message      string       `json:"message,omitempty"`
        Replayed     bool         `json:"replayed"`
        Error        *PublicError `json:"error,omitempty"`
        // 以下是本命令的投影变更副本;重复请求不再输出这些副作用。
        Orders   []Order   `json:"-"`
        Balances []Balance `json:"-"`
        Trades   []Trade   `json:"-"`
        Entries  []Entry   `json:"-"`
}

// PublicError 统一 HTTP 错误字段;由接入层根据核心业务错误补充。
type PublicError struct {
        Code    string `json:"code"`
        Message string `json:"message"`
}

// Level 是查询投影聚合的价档深度,数量是该价格全部活动挂单余量之和。
type Level struct {
        Price    string `json:"price"`
        Quantity string `json:"quantity"`
}

// Snapshot 是投影某一水位的完整公共行情快照,不包含用户身份或余额。
// 盘口与成交在同一读取事务中取得;AppliedSeq 为其可见数据的水位。
type Snapshot struct {
        // DatasetID 区分全新数据目录;只有同一数据集的序号才能比较大小。
        DatasetID  string  `json:"dataset_id"`
        AppliedSeq string  `json:"applied_seq"`
        Bids       []Level `json:"bids"`
        Asks       []Level `json:"asks"`
        Trades     []Trade `json:"trades"`
}

var decimalPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)(\.[0-9]+)?$`)

// parseAmount 校验非负普通十进制文本,再用 decimal 精确解析。
// 拒绝指数、符号、前导零、超长及超精度输入,避免大数解析消耗与静默舍入。
// scale 是允许的小数位数,max 是单次输入上限,positive 决定是否允许零。
// 返回 bool 让非法业务输入成为可处理错误,而不是 panic。
func parseAmount(s string, scale int32, max string, positive bool) (decimal.Decimal, bool) <span class="cov8" title="1">{
        if len(s) &gt; 32 || !decimalPattern.MatchString(s) </span><span class="cov8" title="1">{
                return decimal.Zero, false
        }</span>
        <span class="cov8" title="1">x, err := decimal.NewFromString(s)
        if err != nil || x.Exponent() &lt; -scale || (positive &amp;&amp; !x.IsPositive()) || x.GreaterThan(decimal.RequireFromString(max)) </span><span class="cov8" title="1">{
                return decimal.Zero, false
        }</span>
        <span class="cov8" title="1">return x, true</span>
}

// seqString 将受控 int64 序号转为字符串,跨 JSON 边界不损失精度。
func seqString(x int64) string <span class="cov8" title="1">{ return strconv.FormatInt(x, 10) }</span>

// dec 仅用于已验证输入或核心生成的十进制字符串。
// RequireFromString 的 panic 表示内部数据不变量破坏;外部输入必须先走 parseAmount。
func dec(s string) decimal.Decimal <span class="cov8" title="1">{ return decimal.RequireFromString(s) }</span>
</pre>
    
    <pre class="file" id="file11" style="display: none">package chaintrade

import (
        "bytes"
        "context"
        "crypto/ecdsa"
        "database/sql"
        "encoding/hex"
        "encoding/json"
        "errors"
        "fmt"
        "math/big"
        "strings"

        "github.com/ethereum/go-ethereum"
        "github.com/ethereum/go-ethereum/accounts/abi"
        "github.com/ethereum/go-ethereum/common"
        "github.com/ethereum/go-ethereum/core/types"
        "github.com/ethereum/go-ethereum/crypto"
        "github.com/ethereum/go-ethereum/ethclient"
)

// ABI 最小读写集合与Solidity字段一致;完整契约生成物在contracts/artifacts。
const settlementABI = `[
{"type":"function","name":"base","stateMutability":"view","inputs":[],"outputs":[{"type":"address"}]},
{"type":"function","name":"quote","stateMutability":"view","inputs":[],"outputs":[{"type":"address"}]},
{"type":"function","name":"relayer","stateMutability":"view","inputs":[],"outputs":[{"type":"address"}]},
{"type":"function","name":"settle","stateMutability":"nonpayable","inputs":[{"name":"id","type":"bytes32"},{"name":"maker","type":"tuple","components":[{"name":"maker","type":"address"},{"name":"side","type":"uint8"},{"name":"price","type":"uint256"},{"name":"quantity","type":"uint256"},{"name":"nonce","type":"uint256"},{"name":"deadline","type":"uint256"}]},{"name":"makerSig","type":"bytes"},{"name":"taker","type":"tuple","components":[{"name":"maker","type":"address"},{"name":"side","type":"uint8"},{"name":"price","type":"uint256"},{"name":"quantity","type":"uint256"},{"name":"nonce","type":"uint256"},{"name":"deadline","type":"uint256"}]},{"name":"takerSig","type":"bytes"},{"name":"quantity","type":"uint256"}],"outputs":[]},
{"type":"function","name":"cancelled","stateMutability":"view","inputs":[{"type":"bytes32"}],"outputs":[{"type":"bool"}]},
{"type":"function","name":"filled","stateMutability":"view","inputs":[{"type":"bytes32"}],"outputs":[{"type":"uint256"}]},
{"type":"function","name":"settled","stateMutability":"view","inputs":[{"type":"bytes32"}],"outputs":[{"type":"bool"}]}]`
const erc20ABI = `[{"type":"function","name":"balanceOf","stateMutability":"view","inputs":[{"type":"address"}],"outputs":[{"type":"uint256"}]},{"type":"function","name":"allowance","stateMutability":"view","inputs":[{"type":"address"},{"type":"address"}],"outputs":[{"type":"uint256"}]},{"type":"function","name":"decimals","stateMutability":"view","inputs":[],"outputs":[{"type":"uint8"}]}]`

// contractOrder 使用big.Int编码uint256,不能把nonce/链金额转float64。
type contractOrder struct {
        Maker                            common.Address
        Side                             uint8
        Price, Quantity, Nonce, Deadline *big.Int
}

// toContract 输入已由ValidateOrder固定。
func toContract(o Order) contractOrder <span class="cov0" title="0">{
        p, _ := uintText(o.Price)
        q, _ := uintText(o.Quantity)
        n, _ := uintText(o.Nonce)
        d, _ := uintText(o.Deadline)
        return contractOrder{common.HexToAddress(o.Maker), o.Side, p, q, n, d}
}</span>

// Chain 将RPC/签名放外围;key只用于relayer Gas,不控制用户钱包资产。
type Chain struct {
        Client     *ethclient.Client
        Domain     Domain
        key        *ecdsa.PrivateKey
        address    common.Address
        abi, token abi.ABI
}

// OpenChain 核实RPC链ID、合约代码、relayer配置和资产精度后才运行任务。
func OpenChain(ctx context.Context, url, key string, d Domain) (*Chain, error) <span class="cov0" title="0">{
        private, err := crypto.HexToECDSA(strings.TrimPrefix(key, "0x"))
        if err != nil </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("invalid relayer key")
        }</span>
        <span class="cov0" title="0">c := &amp;Chain{Domain: d, key: private, address: crypto.PubkeyToAddress(private.PublicKey)}
        if !strings.EqualFold(c.address.Hex(), d.Relayer) </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("relayer address mismatch")
        }</span>
        <span class="cov0" title="0">c.abi, err = abi.JSON(strings.NewReader(settlementABI))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">c.token, err = abi.JSON(strings.NewReader(erc20ABI))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">c.Client, err = ethclient.DialContext(ctx, url)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">ok := false
        defer func() </span><span class="cov0" title="0">{
                if !ok </span><span class="cov0" title="0">{
                        c.Client.Close()
                }</span>
        }()
        <span class="cov0" title="0">id, err := c.Client.ChainID(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">if id.String() != d.ChainID </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("RPC chain id mismatch")
        }</span>
        <span class="cov0" title="0">for _, address := range []string{d.Contract, d.Base, d.Quote} </span><span class="cov0" title="0">{
                code, e := c.Client.CodeAt(ctx, common.HexToAddress(address), nil)
                if e != nil </span><span class="cov0" title="0">{
                        return nil, e
                }</span>
                <span class="cov0" title="0">if len(code) == 0 </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("missing contract code")
                }</span>
        }
        // 配置与链ID正确仍不充分:核对合约不可变资产/发送者,防止部署指向另一市场。
        <span class="cov0" title="0">for method, address := range map[string]string{"base": d.Base, "quote": d.Quote, "relayer": d.Relayer} </span><span class="cov0" title="0">{
                values, e := c.call(ctx, c.abi, common.HexToAddress(d.Contract), method)
                if e != nil </span><span class="cov0" title="0">{
                        return nil, e
                }</span>
                <span class="cov0" title="0">if values[0].(common.Address) != common.HexToAddress(address) </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("contract %s mismatch", method)
                }</span>
        }
        <span class="cov0" title="0">for idx, address := range []string{d.Base, d.Quote} </span><span class="cov0" title="0">{
                result, e := c.call(ctx, c.token, common.HexToAddress(address), "decimals")
                if e != nil </span><span class="cov0" title="0">{
                        return nil, e
                }</span>
                <span class="cov0" title="0">want := uint8(18)
                if idx == 1 </span><span class="cov0" title="0">{
                        want = 6
                }</span>
                <span class="cov0" title="0">if result[0].(uint8) != want </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("token decimals mismatch")
                }</span>
        }
        <span class="cov0" title="0">ok = true
        return c, nil</span>
}

// call 编码ABI和执行只读RPC;核心重放绝不调用。
func (c *Chain) call(ctx context.Context, a abi.ABI, address common.Address, method string, args ...interface{}) ([]interface{}, error) <span class="cov0" title="0">{
        data, err := a.Pack(method, args...)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">raw, err := c.Client.CallContract(ctx, ethereum.CallMsg{To: &amp;address, Data: data}, nil)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">return a.Unpack(method, raw)</span>
}

// Preflight 余额/授权预检只减少失败,不冻结钱包;返回链上原子单位文本供页面。
func (c *Chain) Preflight(ctx context.Context, o SignedOrder) error <span class="cov0" title="0">{
        price, _ := uintText(o.Price)
        quantity, _ := uintText(o.Quantity)
        asset := c.Domain.Base
        need := new(big.Int).Mul(quantity, big.NewInt(100000000000000))
        if o.Side == 0 </span><span class="cov0" title="0">{
                asset = c.Domain.Quote
                need = new(big.Int).Mul(price, quantity)
        }</span>
        <span class="cov0" title="0">address := common.HexToAddress(asset)
        owner := common.HexToAddress(o.Maker)
        for _, method := range []string{"balanceOf", "allowance"} </span><span class="cov0" title="0">{
                args := []interface{}{owner}
                if method == "allowance" </span><span class="cov0" title="0">{
                        args = append(args, common.HexToAddress(c.Domain.Contract))
                }</span>
                <span class="cov0" title="0">values, err := c.call(ctx, c.token, address, method, args...)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if values[0].(*big.Int).Cmp(need) &lt; 0 </span><span class="cov0" title="0">{
                        return fmt.Errorf("insufficient wallet balance/allowance")
                }</span>
        }
        <span class="cov0" title="0">values, err := c.call(ctx, c.abi, common.HexToAddress(c.Domain.Contract), "cancelled", common.HexToHash(mustHash(c.Domain, o)))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if values[0].(bool) </span><span class="cov0" title="0">{
                return fmt.Errorf("order cancelled on chain")
        }</span>
        <span class="cov0" title="0">values, err = c.call(ctx, c.abi, common.HexToAddress(c.Domain.Contract), "filled", common.HexToHash(mustHash(c.Domain, o)))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if values[0].(*big.Int).Sign() != 0 </span><span class="cov0" title="0">{
                return fmt.Errorf("order already filled on chain; reconcile original dataset")
        }</span>
        <span class="cov0" title="0">return nil</span>
}

// mustHash 只用于已经验签的订单,不接受未验证客户端输入。
func mustHash(d Domain, o SignedOrder) string <span class="cov0" title="0">{ h, _ := OrderHash(d, o); return h.Hex() }</span>

// build 签名后返回raw tx,在广播之前由SQL任务保存;复用同raw避免新nonce双转。
func (c *Chain) build(ctx context.Context, i Intent) (*types.Transaction, error) <span class="cov0" title="0">{
        data, err := c.abi.Pack("settle", common.HexToHash(i.ID), toContract(i.Maker), common.FromHex(i.Maker.Signature), toContract(i.Taker), common.FromHex(i.Taker.Signature), big.NewInt(i.Quantity))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">nonce, err := c.Client.PendingNonceAt(ctx, c.address)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">price, err := c.Client.SuggestGasPrice(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov0" title="0">to := common.HexToAddress(c.Domain.Contract)
        // 固定Gas上限避免EstimateGas把可确定的revert变成永远未发送任务;测试revert由receipt确认。
        tx := types.NewTransaction(nonce, to, big.NewInt(0), 700000, price, data)
        id, _ := uintText(c.Domain.ChainID)
        return types.SignTx(tx, types.LatestSignerForChainID(id), c.key)</span>
}

// finalized Receipt后还检查规范块hash与确认深度,不把RPC成功当结算最终成功。
func (c *Chain) finalized(ctx context.Context, task Task) (string, *types.Receipt, error) <span class="cov0" title="0">{
        receipt, err := c.Client.TransactionReceipt(ctx, common.HexToHash(task.Hash))
        if errors.Is(err, ethereum.NotFound) </span><span class="cov0" title="0">{
                return "WAIT", nil, nil
        }</span>
        <span class="cov0" title="0">if err != nil </span><span class="cov0" title="0">{
                return "", nil, err
        }</span>
        <span class="cov0" title="0">header, err := c.Client.HeaderByNumber(ctx, receipt.BlockNumber)
        if err != nil </span><span class="cov0" title="0">{
                return "", nil, err
        }</span>
        <span class="cov0" title="0">if header.Hash() != receipt.BlockHash </span><span class="cov0" title="0">{
                return "WAIT", nil, nil
        }</span>
        <span class="cov0" title="0">head, err := c.Client.BlockNumber(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return "", nil, err
        }</span>
        <span class="cov0" title="0">if head &lt; receipt.BlockNumber.Uint64()+c.Domain.Confirmations-1 </span><span class="cov0" title="0">{
                return "WAIT", receipt, nil
        }</span>
        <span class="cov0" title="0">if receipt.Status == types.ReceiptStatusFailed </span><span class="cov0" title="0">{
                return "FAILED", receipt, nil
        }</span>
        // 只能接受本合约Matched(id)事件,receipt success并非充分业务确认。
        <span class="cov0" title="0">topic := crypto.Keccak256Hash([]byte("Matched(bytes32,bytes32,bytes32,uint256,uint256)"))
        for _, log := range receipt.Logs </span><span class="cov0" title="0">{
                if log.Address == common.HexToAddress(c.Domain.Contract) &amp;&amp; len(log.Topics) == 4 &amp;&amp; log.Topics[0] == topic &amp;&amp; log.Topics[1] == common.HexToHash(task.Intent.ID) &amp;&amp; log.Topics[2] == common.HexToHash(task.Intent.Maker.ID) &amp;&amp; log.Topics[3] == common.HexToHash(task.Intent.Taker.ID) &amp;&amp; len(log.Data) == 64 </span><span class="cov0" title="0">{
                        price, _ := uintText(task.Intent.Maker.Price)
                        if new(big.Int).SetBytes(log.Data[:32]).Cmp(price) != 0 || new(big.Int).SetBytes(log.Data[32:]).Cmp(big.NewInt(task.Intent.Quantity)) != 0 </span><span class="cov0" title="0">{
                                return "", receipt, fmt.Errorf("settlement event amount mismatch")
                        }</span>
                        <span class="cov0" title="0">return "CONFIRMED", receipt, nil</span>
                }
        }
        <span class="cov0" title="0">return "", receipt, fmt.Errorf("successful receipt missing settlement event")</span>
}

// Worker 是单relayer任务所有者:同钱包nonce顺序发送,未知/未确认会阻止新nonce任务。
type Worker struct {
        Store      *Store
        Runtime    *Runtime
        Tasks      *Tasks
        Middleware *Middleware
        Chain      *Chain
        auditAfter string // 每轮最多100个历史锚点,完整巡检由多轮完成。
}

// Tick 有限扫描100任务;任何链/SQL失败返回错误,调用者保留状态重试。
// 未终结任务阻止后续sender nonce;HTTP本地受理可继续,pending不等于真实链吞吐。
func (w *Worker) Tick(ctx context.Context) error <span class="cov0" title="0">{
        if err := w.Tasks.CheckOwner(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if err := w.Middleware.Dispatch(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">tasks, err := w.Tasks.Pending(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">for _, task := range tasks </span><span class="cov0" title="0">{
                if err := ValidateIntent(w.Store.Domain, task.Intent); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                // 最终链确认锚点保存在每个task,不依赖一次广播响应。
                <span class="cov0" title="0">if task.Raw == "" </span><span class="cov0" title="0">{
                        tx, err := w.Chain.build(ctx, task.Intent)
                        if err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">raw, err := tx.MarshalBinary()
                        if err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">task.Raw = hex.EncodeToString(raw)
                        task.Hash = tx.Hash().Hex()
                        task.Nonce = fmt.Sprint(tx.Nonce())
                        task.Status = "SIGNED"
                        task.Reason = "SIGNED_DURABLE"
                        if err = w.Tasks.Save(ctx, &amp;task); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
                // 不论receipt是否已终结,先核实持久raw;坏hash不能冒用另一笔链交易确认。
                <span class="cov0" title="0">var tx types.Transaction
                raw, err := hex.DecodeString(task.Raw)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if err = tx.UnmarshalBinary(raw); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if err = w.Chain.verifyRaw(task, &amp;tx); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">outcome, receipt, err := w.Chain.finalized(ctx, task)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if outcome == "WAIT" </span><span class="cov0" title="0">{
                        // 广播失败不能释放资金;下次按同txHash查receipt/重发,不另分配nonce。
                        if err = w.Tasks.CheckOwner(ctx); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">sendErr := w.Chain.Client.SendTransaction(ctx, &amp;tx)
                        task.Status = "BROADCAST"
                        task.Reason = "WAIT_CANONICAL_RECEIPT"
                        task.Block = ""
                        task.BlockNumber = 0
                        if receipt != nil </span><span class="cov0" title="0">{
                                task.Status = "INCLUDED"
                                task.Reason = "WAIT_CONFIRMATIONS"
                                task.Block = receipt.BlockHash.Hex()
                                task.BlockNumber = receipt.BlockNumber.Uint64()
                        }</span>
                        <span class="cov0" title="0">if err = w.Tasks.Save(ctx, &amp;task); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">if sendErr != nil &amp;&amp; !strings.Contains(sendErr.Error(), "already known") &amp;&amp; !strings.Contains(sendErr.Error(), "nonce too low") </span><span class="cov0" title="0">{
                                return sendErr
                        }</span>
                        <span class="cov0" title="0">return nil</span>
                }
                <span class="cov0" title="0">result, err := w.Runtime.Submit(ctx, Command{Kind: outcome, IntentID: task.Intent.ID, TxHash: task.Hash, Reason: outcome})
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if result.Code != "" </span><span class="cov0" title="0">{
                        return fmt.Errorf("confirmation rejected: %s", result.Code)
                }</span>
                <span class="cov0" title="0">task.Status = outcome
                task.Reason = "SETTLED"
                if outcome == "FAILED" </span><span class="cov0" title="0">{
                        task.Reason = "RECEIPT_REVERT"
                }</span>
                <span class="cov0" title="0">task.Block = receipt.BlockHash.Hex()
                task.BlockNumber = receipt.BlockNumber.Uint64()
                if err = w.Tasks.Save(ctx, &amp;task); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov0" title="0">return nil</span>
}

// AuditAnchors 深重组/历史receipt丢失停止运行,不能悄悄继续用旧最终事实。
func (w *Worker) AuditAnchors(ctx context.Context) error <span class="cov0" title="0">{
        rows, err := w.Tasks.DB.QueryContext(ctx, `SELECT payload FROM chain_tasks WHERE status IN ('CONFIRMED','FAILED') AND id &gt; `+w.Tasks.query(`? ORDER BY id LIMIT 100`), w.auditAfter)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">raws := []string{}
        for rows.Next() </span><span class="cov0" title="0">{
                var raw string
                if err = rows.Scan(&amp;raw); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return err
                }</span>
                <span class="cov0" title="0">raws = append(raws, raw)</span>
        }
        <span class="cov0" title="0">err = rows.Err()
        rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if len(raws) == 0 </span><span class="cov0" title="0">{
                w.auditAfter = ""
        }</span>
        <span class="cov0" title="0">for _, raw := range raws </span><span class="cov0" title="0">{
                var task Task
                if err = json.Unmarshal([]byte(raw), &amp;task); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">w.auditAfter = task.Intent.ID
                receipt, e := w.Chain.Client.TransactionReceipt(ctx, common.HexToHash(task.Hash))
                if e != nil </span><span class="cov0" title="0">{
                        return fmt.Errorf("final receipt unavailable: %w", e)
                }</span>
                <span class="cov0" title="0">header, e := w.Chain.Client.HeaderByNumber(ctx, receipt.BlockNumber)
                if e != nil </span><span class="cov0" title="0">{
                        return e
                }</span>
                <span class="cov0" title="0">if receipt.BlockHash.Hex() != task.Block || header.Hash() != receipt.BlockHash </span><span class="cov0" title="0">{
                        return fmt.Errorf("finalized chain reorganization: %s", task.Intent.ID)
                }</span>
        }
        <span class="cov0" title="0">return nil</span>
}

// ScanOrders 轮询已确认高度上的活动订单;持久块锚点让重启后的深重组也被识别。
// 这不是完整事件索引器:每轮最多200订单,按seq循环,单轮RPC有界。
func (w *Worker) ScanOrders(ctx context.Context) error <span class="cov0" title="0">{
        if err := w.CheckScanAnchor(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">head, err := w.Chain.Client.BlockNumber(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if head+1 &lt; w.Chain.Domain.Confirmations </span><span class="cov0" title="0">{
                return nil
        }</span>
        <span class="cov0" title="0">block := new(big.Int).SetUint64(head + 1 - w.Chain.Domain.Confirmations)
        header, err := w.Chain.Client.HeaderByNumber(ctx, block)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">var after int64
        _ = w.Store.Journal.QueryRowContext(ctx, `SELECT value FROM metadata WHERE key='scan_after'`).Scan(&amp;after)
        rows, err := w.Store.Views.QueryContext(ctx, `SELECT payload FROM orders WHERE seq&gt;? ORDER BY seq LIMIT 200`, after)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">orders := []Order{}
        for rows.Next() </span><span class="cov0" title="0">{
                var raw string
                var o Order
                if err = rows.Scan(&amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov0" title="0">if err = json.Unmarshal([]byte(raw), &amp;o); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov0" title="0">orders = append(orders, o)</span>
        }
        <span class="cov0" title="0">if err == nil </span><span class="cov0" title="0">{
                err = rows.Err()
        }</span>
        <span class="cov0" title="0">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        // 先落锚点再写任何INVALIDATE;崩溃后会继续扫描,不能无锚点采纳取消事实。
        <span class="cov0" title="0">anchor, _ := json.Marshal(scanAnchor{Number: block.Uint64(), Hash: header.Hash().Hex()})
        if _, err = w.Store.Journal.ExecContext(ctx, `INSERT INTO metadata VALUES('scan_anchor',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`, string(anchor)); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">for _, o := range orders </span><span class="cov0" title="0">{
                after = o.Seq
                if o.Remaining == 0 </span><span class="cov0" title="0">{
                        continue</span>
                }
                <span class="cov0" title="0">data, err := w.Chain.abi.Pack("cancelled", common.HexToHash(o.ID))
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">to := common.HexToAddress(w.Chain.Domain.Contract)
                raw, err := w.Chain.Client.CallContractAtHash(ctx, ethereum.CallMsg{To: &amp;to, Data: data}, header.Hash())
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">values, err := w.Chain.abi.Unpack("cancelled", raw)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">deadline, _ := strconvInt(o.Deadline)
                if values[0].(bool) || uint64(deadline) &lt; header.Time </span><span class="cov0" title="0">{
                        if _, err = w.Runtime.Submit(ctx, Command{Kind: "INVALIDATE", OrderID: o.ID, Reason: "chain cancelled or expired"}); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
        }
        <span class="cov0" title="0">if len(orders) &lt; 200 </span><span class="cov0" title="0">{
                after = 0
        }</span>
        <span class="cov0" title="0">_, err = w.Store.Journal.ExecContext(ctx, `INSERT INTO metadata VALUES('scan_after',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`, fmt.Sprint(after))
        return err</span>
}

// scanAnchor 固定已采用链事实的高度和hash,不是可重建任务的发送记录。
type scanAnchor struct {
        Number uint64 `json:"number"`
        Hash   string `json:"hash"`
}

// CheckScanAnchor 历史链事实消失或hash变化拒绝继续;RPC不可用同样不采用新事实。
func (w *Worker) CheckScanAnchor(ctx context.Context) error <span class="cov0" title="0">{
        var raw string
        err := w.Store.Journal.QueryRowContext(ctx, `SELECT value FROM metadata WHERE key='scan_anchor'`).Scan(&amp;raw)
        if err == sql.ErrNoRows </span><span class="cov0" title="0">{
                return nil
        }</span>
        <span class="cov0" title="0">if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">var a scanAnchor
        if err = json.Unmarshal([]byte(raw), &amp;a); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">header, err := w.Chain.Client.HeaderByNumber(ctx, new(big.Int).SetUint64(a.Number))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if header.Hash().Hex() != a.Hash </span><span class="cov0" title="0">{
                return fmt.Errorf("finalized scan reorganization at %d", a.Number)
        }</span>
        <span class="cov0" title="0">return nil</span>
}

// strconvInt 已验证deadline可放int64,外围转换不进核心时间判断。
func strconvInt(s string) (int64, bool) <span class="cov8" title="1">{
        n, ok := uintText(s)
        if !ok || !n.IsInt64() </span><span class="cov0" title="0">{
                return 0, false
        }</span>
        <span class="cov8" title="1">return n.Int64(), true</span>
}

// verifyRaw 恢复发送前验证SQL中原交易的hash/nonce/sender/目标/调用数据,损坏任务不得广播。
func (c *Chain) verifyRaw(task Task, tx *types.Transaction) error <span class="cov0" title="0">{
        id, _ := uintText(c.Domain.ChainID)
        sender, err := types.Sender(types.LatestSignerForChainID(id), tx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">data, err := c.abi.Pack("settle", common.HexToHash(task.Intent.ID), toContract(task.Intent.Maker), common.FromHex(task.Intent.Maker.Signature), toContract(task.Intent.Taker), common.FromHex(task.Intent.Taker.Signature), big.NewInt(task.Intent.Quantity))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if tx.ChainId().Cmp(id) != 0 || sender != c.address || tx.To() == nil || *tx.To() != common.HexToAddress(c.Domain.Contract) || tx.Value().Sign() != 0 || tx.Hash().Hex() != task.Hash || fmt.Sprint(tx.Nonce()) != task.Nonce || !bytes.Equal(data, tx.Data()) </span><span class="cov0" title="0">{
                return fmt.Errorf("stored raw transaction mismatch")
        }</span>
        <span class="cov0" title="0">return nil</span>
}
</pre>
    
    <pre class="file" id="file12" style="display: none">package chaintrade

import (
        "container/list"
        "fmt"
        "sort"
        "strconv"
        "strings"

        "github.com/emirpasic/gods/trees/redblacktree"
)

// level 单价格FIFO;refs支持直接撤出活动簿,全部只由Engine拥有。
type level struct {
        price  int64
        orders *list.List
}

// reference 由订单ID直达FIFO节点,撤出无需扫描整个档位。
type reference struct {
        level *level
        node  *list.Element
}

// Engine 仅计算订单数量/确定性意图,不把链下匹配视为资产到账。
// 为限制热路径复制,状态发布在外围消费增量;Core不访问SQL/时钟/RPC。
type Engine struct {
        seq        int64
        dataset    string
        orders     map[string]*Order
        intents    map[string]*Intent
        bids, asks *redblacktree.Tree
        refs       map[string]reference
        nonces     map[string]string
}

// NewEngine 创建无余额的新链上簿;身份资金由合约而非模拟CREDIT裁决。
func NewEngine(dataset string) *Engine <span class="cov8" title="1">{
        cmp := func(a, b interface{}) int </span><span class="cov8" title="1">{
                x, y := a.(int64), b.(int64)
                if x &lt; y </span><span class="cov8" title="1">{
                        return -1
                }</span>
                <span class="cov8" title="1">if x &gt; y </span><span class="cov0" title="0">{
                        return 1
                }</span>
                <span class="cov8" title="1">return 0</span>
        }
        <span class="cov8" title="1">return &amp;Engine{dataset: dataset, orders: map[string]*Order{}, intents: map[string]*Intent{}, bids: redblacktree.NewWith(cmp), asks: redblacktree.NewWith(cmp), refs: map[string]reference{}, nonces: map[string]string{}}</span>
}

// add 只挂尚可撮合且没有待结算的订单,一订单最多一个pending任务避免链失败传播。
func (e *Engine) add(o *Order) <span class="cov8" title="1">{
        if o.Remaining == 0 || o.Pending != 0 </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">tree := e.bids
        if o.Side == 1 </span><span class="cov8" title="1">{
                tree = e.asks
        }</span>
        <span class="cov8" title="1">price, _ := strconv.ParseInt(o.Price, 10, 64)
        value, ok := tree.Get(price)
        var l *level
        if ok </span><span class="cov8" title="1">{
                l = value.(*level)
        }</span> else<span class="cov8" title="1"> {
                l = &amp;level{price, list.New()}
                tree.Put(price, l)
        }</span>
        <span class="cov8" title="1">e.refs[o.ID] = reference{l, l.orders.PushBack(o.ID)}</span>
}

// remove 删除引用与空价档;不存在时允许重复调用以简化终态处理。
func (e *Engine) remove(o *Order) <span class="cov8" title="1">{
        ref, ok := e.refs[o.ID]
        if !ok </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">ref.level.orders.Remove(ref.node)
        delete(e.refs, o.ID)
        if ref.level.orders.Len() == 0 </span><span class="cov8" title="1">{
                tree := e.bids
                if o.Side == 1 </span><span class="cov8" title="1">{
                        tree = e.asks
                }</span>
                <span class="cov8" title="1">tree.Remove(ref.level.price)</span>
        }
}

// best 返回对手最优档;价格排序不依赖全簿sort。
func (e *Engine) best(side uint8) *level <span class="cov8" title="1">{
        if side == 0 </span><span class="cov8" title="1">{
                if n := e.asks.Left(); n != nil </span><span class="cov8" title="1">{
                        return n.Value.(*level)
                }</span>
        } else<span class="cov8" title="1"> {
                if n := e.bids.Right(); n != nil </span><span class="cov0" title="0">{
                        return n.Value.(*level)
                }</span>
        }
        <span class="cov8" title="1">return nil</span>
}

// status 数量字段决定展示状态;本地取消量不可使链上已广播意图失效。
func status(o *Order) <span class="cov8" title="1">{
        switch </span>{
        case o.Pending &gt; 0:<span class="cov8" title="1">
                o.Status = "PENDING_SETTLEMENT"</span>
        case o.Remaining &gt; 0 &amp;&amp; o.Filled &gt; 0:<span class="cov8" title="1">
                o.Status = "PARTIALLY_FILLED"</span>
        case o.Remaining &gt; 0:<span class="cov0" title="0">
                o.Status = "OPEN"</span>
        case o.Canceled &gt; 0:<span class="cov8" title="1">
                o.Status = "CANCELED"</span>
        default:<span class="cov8" title="1">
                o.Status = "FILLED"</span>
        }
}

// match 至多生成一项两单任务;pending订单暂出簿,确认后可重新撮合余量。
func (e *Engine) match(taker *Order, changed map[string]bool, newIntents *[]Intent) <span class="cov8" title="1">{
        if taker.Remaining == 0 || taker.Pending != 0 </span><span class="cov8" title="1">{
                return
        }</span>
        <span class="cov8" title="1">l := e.best(taker.Side)
        if l == nil </span><span class="cov8" title="1">{
                e.add(taker)
                return
        }</span>
        <span class="cov8" title="1">price, _ := strconv.ParseInt(taker.Price, 10, 64)
        if taker.Side == 0 &amp;&amp; l.price &gt; price || taker.Side == 1 &amp;&amp; l.price &lt; price </span><span class="cov0" title="0">{
                e.add(taker)
                return
        }</span>
        <span class="cov8" title="1">maker := e.orders[l.orders.Front().Value.(string)]
        if strings.EqualFold(maker.Maker, taker.Maker) </span><span class="cov0" title="0">{
                taker.Canceled += taker.Remaining
                taker.Remaining = 0
                status(taker)
                changed[taker.ID] = true
                return
        }</span>
        <span class="cov8" title="1">q := min(maker.Remaining, taker.Remaining)
        e.remove(maker)
        e.remove(taker)
        maker.Remaining -= q
        maker.Pending += q
        taker.Remaining -= q
        taker.Pending += q
        status(maker)
        status(taker)
        changed[maker.ID] = true
        changed[taker.ID] = true
        id := e.dataset + fmt.Sprintf("%032x", e.seq) // 一命令最多一个新意图,稳定seq映射bytes32。
        intent := Intent{ID: "0x" + id, Maker: *maker, Taker: *taker, Quantity: q, Status: "READY"}
        e.intents[intent.ID] = &amp;intent
        *newIntents = append(*newIntents, intent)</span>
}

// Apply 按持久化顺序处理;返回增量订单和意图的值副本供外围投影。
func (e *Engine) Apply(c Command) (Result, []Order, []Intent) <span class="cov8" title="1">{
        if c.Seq != e.seq+1 </span><span class="cov0" title="0">{
                panic("chain command sequence gap")</span>
        }
        <span class="cov8" title="1">e.seq = c.Seq
        result := Result{Seq: strconv.FormatInt(c.Seq, 10)}
        changed := map[string]bool{}
        updates := []Intent{}
        switch c.Kind </span>{
        case "PLACE":<span class="cov8" title="1">
                result.OrderID = c.OrderID
                if old := e.orders[c.OrderID]; old != nil </span><span class="cov8" title="1">{
                        return result, []Order{}, updates
                }</span>
                <span class="cov8" title="1">key := strings.ToLower(c.Order.Maker) + ":" + c.Order.Nonce
                if e.nonces[key] != "" </span><span class="cov8" title="1">{
                        result.Code = "NONCE_CONFLICT"
                        break</span>
                }
                <span class="cov8" title="1">if len(e.orders) &gt;= 100000 </span><span class="cov0" title="0">{
                        result.Code = "ORDER_BUDGET"
                        break</span>
                }
                <span class="cov8" title="1">q, _ := strconv.ParseInt(c.Order.Quantity, 10, 64)
                if q &lt;= 0 || c.OrderID == "" </span><span class="cov0" title="0">{
                        result.Code = "INVALID_ORDER"
                        break</span>
                }
                <span class="cov8" title="1">o := &amp;Order{ID: c.OrderID, SignedOrder: c.Order, Seq: c.Seq, Remaining: q, Status: "OPEN"}
                e.orders[o.ID] = o
                e.nonces[key] = o.ID
                changed[o.ID] = true
                e.match(o, changed, &amp;updates)</span>
        case "CONFIRMED", "FAILED":<span class="cov8" title="1">
                intent := e.intents[c.IntentID]
                if intent == nil </span><span class="cov0" title="0">{
                        result.Code = "INTENT_NOT_FOUND"
                        break</span>
                }
                <span class="cov8" title="1">if intent.Status != "READY" </span><span class="cov8" title="1">{
                        break</span>
                } // 重复链事件只推进日志,不重复转数量。
                <span class="cov8" title="1">maker, taker := e.orders[intent.Maker.ID], e.orders[intent.Taker.ID]
                for _, o := range []*Order{maker, taker} </span><span class="cov8" title="1">{
                        o.Pending -= intent.Quantity
                        if c.Kind == "CONFIRMED" </span><span class="cov8" title="1">{
                                o.Filled += intent.Quantity
                        }</span> else<span class="cov8" title="1"> {
                                // 失败订单全部本地取消,避免失效签名/余额不足制造无限重试任务。
                                o.Canceled += o.Remaining + intent.Quantity
                                o.Remaining = 0
                        }</span>
                        <span class="cov8" title="1">status(o)
                        changed[o.ID] = true</span>
                }
                <span class="cov8" title="1">intent.Status = c.Kind
                intent.TxHash = c.TxHash
                intent.Reason = c.Reason
                updates = append(updates, *intent)
                if c.Kind == "CONFIRMED" </span><span class="cov8" title="1">{
                        e.add(maker)
                        // 持有原taker角色恢复;maker放回档尾,明确未提供等待期间绝对FIFO保证。
                        e.match(taker, changed, &amp;updates)
                }</span>
        case "INVALIDATE":<span class="cov8" title="1">
                o := e.orders[c.OrderID]
                if o == nil </span><span class="cov0" title="0">{
                        result.Code = "ORDER_NOT_FOUND"
                        break</span>
                }
                <span class="cov8" title="1">e.remove(o)
                o.Canceled += o.Remaining
                o.Remaining = 0
                status(o)
                changed[o.ID] = true</span>
        default:<span class="cov0" title="0">
                result.Code = "INVALID_COMMAND"</span>
        }
        <span class="cov8" title="1">orders := make([]Order, 0, len(changed))
        for id := range changed </span><span class="cov8" title="1">{
                orders = append(orders, *e.orders[id])
        }</span>
        <span class="cov8" title="1">sort.Slice(orders, func(i, j int) bool </span><span class="cov8" title="1">{ return orders[i].Seq &lt; orders[j].Seq }</span>)
        <span class="cov8" title="1">return result, orders, updates</span>
}
</pre>
    
    <pre class="file" id="file13" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/base64"
        "encoding/json"
        "fmt"
        "io"
        "strconv"
        "strings"

        "github.com/ethereum/go-ethereum/common"
)

// HistoryCursor 绑定查询条件和初始插入上界,后续分页不能跨数据集/钱包/类别。
// 游标不是权限令牌;本接口查询公开链数据,仍严格校验长度、字段与排序边界。
type HistoryCursor struct {
        Dataset string `json:"dataset"`
        Kind    string `json:"kind"`
        Wallet  string `json:"wallet"`
        Upper   string `json:"upper"`
        After   string `json:"after"`
}

// TaskView 只公开可解释的进度,不返回 rawTx;详情包含两笔原订单便于定位问题。
type TaskView struct {
        ID          string `json:"id"`
        Status      string `json:"status"`
        Hash        string `json:"tx_hash"`
        Nonce       string `json:"nonce"`
        Block       string `json:"block"`
        BlockNumber string `json:"block_number"`
        CreatedAt   int64  `json:"created_at"`
        UpdatedAt   int64  `json:"updated_at"`
        Version     string `json:"version"`
        Reason      string `json:"reason"`
        Intent      Intent `json:"intent"`
}

func taskView(t Task) TaskView <span class="cov8" title="1">{
        return TaskView{t.Intent.ID, t.Status, t.Hash, t.Nonce, t.Block, fmt.Sprint(t.BlockNumber), t.CreatedAt, t.UpdatedAt, fmt.Sprint(t.Version), t.Reason, t.Intent}
}</span>

// HistoryPage 的 items 始终是数组,空集合不编码为 null。seq 是本地投影水位。
type HistoryPage struct {
        Dataset string        `json:"dataset_id"`
        Seq     string        `json:"seq"`
        Items   []interface{} `json:"items"`
        Next    string        `json:"next_cursor"`
}

// History 只使用固定表模板,用户不能提供 SQL;limit+1 判断下一页,无 OFFSET。
// 订单和意图在同一 SQLite 快照;任务库另有独立状态,不承诺跨库原子快照。
func (s *Store) History(ctx context.Context, t *Tasks, kind, wallet, cursor string, limit int) (HistoryPage, error) <span class="cov8" title="1">{
        p := HistoryPage{Dataset: s.Domain.Dataset, Items: []interface{}{}}
        if limit &lt; 1 || limit &gt; 100 </span><span class="cov0" title="0">{
                return p, fmt.Errorf("invalid limit")
        }</span>
        <span class="cov8" title="1">wallet = strings.ToLower(wallet)
        if wallet != "" &amp;&amp; !common.IsHexAddress(wallet) </span><span class="cov0" title="0">{
                return p, fmt.Errorf("invalid wallet")
        }</span>
        <span class="cov8" title="1">cur := HistoryCursor{Dataset: s.Domain.Dataset, Kind: kind, Wallet: wallet}
        if cursor != "" </span><span class="cov8" title="1">{
                if len(cursor) &gt; 2048 </span><span class="cov0" title="0">{
                        return p, fmt.Errorf("invalid cursor")
                }</span>
                <span class="cov8" title="1">raw, err := base64.RawURLEncoding.DecodeString(cursor)
                if err != nil </span><span class="cov0" title="0">{
                        return p, fmt.Errorf("invalid cursor")
                }</span>
                <span class="cov8" title="1">dec := json.NewDecoder(strings.NewReader(string(raw)))
                dec.DisallowUnknownFields()
                if err = dec.Decode(&amp;cur); err != nil </span><span class="cov8" title="1">{
                        return p, fmt.Errorf("invalid cursor")
                }</span>
                <span class="cov8" title="1">var extra interface{}
                if dec.Decode(&amp;extra) != io.EOF </span><span class="cov0" title="0">{
                        return p, fmt.Errorf("invalid cursor")
                }</span>
                <span class="cov8" title="1">if cur.Dataset != s.Domain.Dataset || cur.Kind != kind || cur.Wallet != wallet || cur.After == "" || cur.Upper == "" || cur.After &gt; cur.Upper </span><span class="cov8" title="1">{
                        return p, fmt.Errorf("cursor mismatch")
                }</span>
        }
        <span class="cov8" title="1">tx, err := s.Views.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var seq int64
        if err = tx.QueryRowContext(ctx, `SELECT seq FROM progress WHERE id=1`).Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">p.Seq = strconv.FormatInt(seq, 10)
        key, table, filter := "", "", "1=1"
        var taskTx *sql.Tx
        queryDB := tx
        switch kind </span>{
        case "orders":<span class="cov8" title="1">
                key = "printf('%020d',seq)"
                table = "orders"
                if wallet != "" </span><span class="cov8" title="1">{
                        filter = "lower(json_extract(payload,'$.maker'))=?"
                }</span>
        case "trades":<span class="cov8" title="1">
                key = "id"
                table = "intents"
                filter = "status='CONFIRMED'"
                if wallet != "" </span><span class="cov0" title="0">{
                        filter += " AND (lower(json_extract(payload,'$.maker.maker'))=? OR lower(json_extract(payload,'$.taker.maker'))=?)"
                }</span>
        case "events":<span class="cov8" title="1">
                key = "printf('%020d',block)||'/'||substr(id,-10)"
                table = "chain_events"
                if wallet != "" </span><span class="cov0" title="0">{
                        filter = "(lower(wallet)=? OR maker_id IN (SELECT id FROM orders WHERE lower(json_extract(payload,'$.maker'))=?) OR taker_id IN (SELECT id FROM orders WHERE lower(json_extract(payload,'$.maker'))=?))"
                }</span>
        case "tasks":<span class="cov8" title="1">
                key = "id"
                table = "chain_tasks"
                if wallet != "" </span><span class="cov0" title="0">{
                        filter = "lower(" + taskWalletExpr(t.pg, "maker") + ")=? OR lower(" + taskWalletExpr(t.pg, "taker") + ")=?"
                }</span>
                <span class="cov8" title="1">taskTx, err = t.DB.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
                if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">defer taskTx.Rollback()
                queryDB = taskTx</span>
        default:<span class="cov0" title="0">
                return p, fmt.Errorf("invalid history kind")</span>
        }
        <span class="cov8" title="1">bind := func(q string) string </span><span class="cov8" title="1">{
                if kind == "tasks" </span><span class="cov8" title="1">{
                        return t.query(q)
                }</span>
                <span class="cov8" title="1">return q</span>
        }
        <span class="cov8" title="1">args := []interface{}{}
        if wallet != "" </span><span class="cov8" title="1">{
                args = append(args, wallet)
                if kind == "trades" || kind == "tasks" || kind == "events" </span><span class="cov0" title="0">{
                        args = append(args, wallet)
                }</span>
                <span class="cov8" title="1">if kind == "events" </span><span class="cov0" title="0">{
                        args = append(args, wallet)
                }</span>
        }
        <span class="cov8" title="1">if cursor == "" </span><span class="cov8" title="1">{
                var upper sql.NullString
                if err = queryDB.QueryRowContext(ctx, bind(`SELECT MAX(`+key+`) FROM `+table+` WHERE (`+filter+`)`), args...).Scan(&amp;upper); err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">if !upper.Valid </span><span class="cov8" title="1">{
                        return p, nil
                }</span>
                <span class="cov8" title="1">cur.Upper = upper.String</span>
        }
        <span class="cov8" title="1">args = append(args, cur.Upper)
        condition := "(" + filter + ") AND " + key + "&lt;=?"
        if cur.After != "" </span><span class="cov8" title="1">{
                condition += " AND " + key + "&lt;?"
                args = append(args, cur.After)
        }</span>
        <span class="cov8" title="1">args = append(args, limit+1)
        rows, err := queryDB.QueryContext(ctx, bind(`SELECT `+key+`,payload FROM `+table+` WHERE `+condition+` ORDER BY `+key+` DESC LIMIT ?`), args...)
        if err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        last := ""
        for rows.Next() </span><span class="cov8" title="1">{
                var k, raw string
                if err = rows.Scan(&amp;k, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">if len(p.Items) == limit </span><span class="cov8" title="1">{
                        cur.After = last
                        b, _ := json.Marshal(cur)
                        p.Next = base64.RawURLEncoding.EncodeToString(b)
                        break</span>
                }
                <span class="cov8" title="1">var value interface{}
                switch kind </span>{
                case "orders":<span class="cov8" title="1">
                        var v Order
                        err = json.Unmarshal([]byte(raw), &amp;v)
                        value = v</span>
                case "trades":<span class="cov0" title="0">
                        var v Intent
                        err = json.Unmarshal([]byte(raw), &amp;v)
                        value = v</span>
                case "events":<span class="cov0" title="0">
                        var v Event
                        err = json.Unmarshal([]byte(raw), &amp;v)
                        value = v</span>
                case "tasks":<span class="cov8" title="1">
                        var v Task
                        err = json.Unmarshal([]byte(raw), &amp;v)
                        value = taskView(v)</span>
                }
                <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                        return p, err
                }</span>
                <span class="cov8" title="1">p.Items = append(p.Items, value)
                last = k</span>
        }
        <span class="cov8" title="1">if err = rows.Err(); err != nil </span><span class="cov0" title="0">{
                return p, err
        }</span>
        <span class="cov8" title="1">return p, nil</span> // 回滚只读事务释放快照,列表没有写入。
}

// taskWalletExpr 仅内部 maker/taker 常量,适配 PG 的 JSON 文本列与 SQLite JSON 函数。
func taskWalletExpr(pg bool, side string) string <span class="cov0" title="0">{
        if pg </span><span class="cov0" title="0">{
                return "(payload::jsonb #&gt;&gt; '{intent," + side + ",maker}')"
        }</span>
        <span class="cov0" title="0">return "json_extract(payload,'$.intent." + side + ".maker')"</span>
}

// Detail 查询不限最近100项,去掉可用于广播的 raw,公开签名仍属于公开链订单。
func (t *Tasks) Detail(ctx context.Context, id string) (TaskView, error) <span class="cov8" title="1">{
        var raw string
        var v Task
        err := t.DB.QueryRowContext(ctx, t.query(`SELECT payload FROM chain_tasks WHERE id=?`), id).Scan(&amp;raw)
        if err == nil </span><span class="cov8" title="1">{
                err = json.Unmarshal([]byte(raw), &amp;v)
        }</span>
        <span class="cov8" title="1">return taskView(v), err</span>
}
</pre>
    
    <pre class="file" id="file14" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/json"
        "io"
        "net"
        "net/http"
        "os"
        "strconv"
        "strings"
        "sync/atomic"
        "time"

        "github.com/ethereum/go-ethereum/common"
        "web3exchange/api"
)

// HTTP 是独立公开签单入口,订单只公开钱包与签名,不共享模拟邮箱/资产。
type HTTP struct {
        Store            *Store
        Runtime          *Runtime
        Middleware       *Middleware
        Chain            *Chain
        Origin           string
        Frontend         string
        slots            chan struct{}
        requests, denied atomic.Uint64
        WorkerError      atomic.Value
        Monitor          Monitoring
}

// NewHTTP 独立并发预算限制验签/RPC,业务拒绝不进入核心网络调用。
func NewHTTP(s *Store, r *Runtime, m *Middleware, c *Chain, origin, frontend string) *HTTP <span class="cov8" title="1">{
        return &amp;HTTP{Store: s, Runtime: r, Middleware: m, Chain: c, Origin: origin, Frontend: frontend, slots: make(chan struct{}, 16)}
}</span>

// jsonReply 接入统一输出;金额/数量整数文本不转Number。
func jsonReply(w http.ResponseWriter, status int, v interface{}) <span class="cov8" title="1">{
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(status)
        _ = json.NewEncoder(w).Encode(v)
}</span>

// reject 状态码与错误码供pending判断,内部密钥/RPC配置不回显给客户端。
func reject(w http.ResponseWriter, status int, code string) <span class="cov8" title="1">{
        jsonReply(w, status, map[string]interface{}{"error": map[string]string{"code": code, "message": code}})
}</span>

// Handler 所有写要求准确Origin(浏览器),签单本身是交易授权,无需模拟CSRF。
func (h *HTTP) Handler() http.Handler <span class="cov8" title="1">{
        mux := http.NewServeMux()
        mux.HandleFunc("GET /api/web3/openapi.json", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                w.Header().Set("Content-Type", "application/json")
                w.Write(api.Web3Spec)
        }</span>)
        <span class="cov8" title="1">mux.HandleFunc("GET /api/web3/orders/{id}", h.order)
        mux.HandleFunc("GET /api/web3/tasks", h.tasks)
        mux.HandleFunc("GET /api/web3/history/{kind}", h.history)
        mux.HandleFunc("GET /api/web3/tasks/{id}", h.taskDetail)
        mux.HandleFunc("GET /api/web3/config", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{ jsonReply(w, 200, h.Store.Domain) }</span>)
        <span class="cov8" title="1">mux.HandleFunc("GET /api/web3/state", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
                defer cancel()
                var s State
                var err error
                if r.URL.Query().Get("fresh") == "1" </span><span class="cov8" title="1">{
                        s, err = h.Store.State(ctx)
                }</span> else<span class="cov8" title="1"> {
                        s, err = h.Middleware.CachedState(ctx)
                }</span>
                <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                        reject(w, 503, "QUERY_FAILED")
                        return
                }</span>
                <span class="cov8" title="1">jsonReply(w, 200, s)</span>
        })
        <span class="cov8" title="1">mux.HandleFunc("POST /api/web3/orders", h.place)
        mux.HandleFunc("POST /api/web3/orders/{id}/sync", h.syncOrder)
        mux.HandleFunc("GET /health/ready", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                if !h.Runtime.Healthy() || h.WorkerError.Load() != nil </span><span class="cov0" title="0">{
                        reject(w, 503, "NOT_READY")
                        return
                }</span>
                <span class="cov8" title="1">jsonReply(w, 200, map[string]string{"status": "ready"})</span>
        })
        <span class="cov8" title="1">mux.HandleFunc("GET /health/live", func(w http.ResponseWriter, r *http.Request) </span><span class="cov0" title="0">{ jsonReply(w, 200, map[string]string{"status": "alive"}) }</span>)
        <span class="cov8" title="1">mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) </span><span class="cov0" title="0">{ reject(w, 404, "NOT_FOUND") }</span>)
        <span class="cov8" title="1">mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) </span><span class="cov0" title="0">{
                if _, err := os.Stat(h.Frontend + "/index.html"); err != nil </span><span class="cov0" title="0">{
                        http.NotFound(w, r)
                        return
                }</span>
                <span class="cov0" title="0">http.ServeFile(w, r, h.Frontend+"/index.html")</span>
        })
        <span class="cov8" title="1">return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                h.requests.Add(1)
                start := time.Now()
                defer h.Monitor.observe(start)
                w.Header().Set("X-Dataset-ID", h.Store.Domain.Dataset)
                w.Header().Set("Cache-Control", "no-store")
                w.Header().Set("X-Content-Type-Options", "nosniff")
                w.Header().Set("X-Frame-Options", "DENY")
                if strings.HasPrefix(r.URL.Path, "/assets/") </span><span class="cov0" title="0">{
                        http.FileServer(http.Dir(h.Frontend)).ServeHTTP(w, r)
                        return
                }</span>
                <span class="cov8" title="1">if r.Method != "GET" &amp;&amp; r.Method != "HEAD" </span><span class="cov8" title="1">{
                        if origin := r.Header.Get("Origin"); origin != "" &amp;&amp; origin != h.Origin </span><span class="cov8" title="1">{
                                reject(w, 403, "ORIGIN_REJECTED")
                                return
                        }</span>
                        <span class="cov8" title="1">if r.Header.Get("X-Dataset-ID") != h.Store.Domain.Dataset </span><span class="cov8" title="1">{
                                reject(w, 409, "DATASET_CHANGED")
                                return
                        }</span>
                }
                <span class="cov8" title="1">ip, _, _ := net.SplitHostPort(r.RemoteAddr)
                ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)
                allowed := h.Middleware.Allow(ctx, ip)
                cancel()
                if !allowed </span><span class="cov0" title="0">{
                        h.denied.Add(1)
                        reject(w, 429, "RATE_LIMITED")
                        return
                }</span>
                <span class="cov8" title="1">mux.ServeHTTP(w, r)</span>
        })
}

// place 签名hash就是不可改内容的订单ID,同签单重试不新建业务。
func (h *HTTP) place(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        select </span>{
        case h.slots &lt;- struct{}{}:<span class="cov8" title="1">
                defer func() </span><span class="cov8" title="1">{ &lt;-h.slots }</span>()
        default:<span class="cov0" title="0">
                reject(w, 429, "ADMISSION_FULL")
                return</span>
        }
        <span class="cov8" title="1">r.Body = http.MaxBytesReader(w, r.Body, 16&lt;&lt;10)
        dec := json.NewDecoder(r.Body)
        dec.DisallowUnknownFields()
        var o SignedOrder
        if err := dec.Decode(&amp;o); err != nil </span><span class="cov8" title="1">{
                reject(w, 400, "INVALID_REQUEST")
                return
        }</span>
        <span class="cov8" title="1">var more interface{}
        if dec.Decode(&amp;more) != io.EOF </span><span class="cov8" title="1">{
                reject(w, 400, "INVALID_REQUEST")
                return
        }</span>
        <span class="cov8" title="1">id, err := ValidateOrder(h.Store.Domain, o, 0)
        if err != nil </span><span class="cov8" title="1">{
                reject(w, 400, "INVALID_SIGNATURE_ORDER")
                return
        }</span>
        // 已日志处理过的签单先取ID确认,余额变化不得改变首次已受理语义。
        <span class="cov8" title="1">var previous string
        err = h.Store.Views.QueryRowContext(r.Context(), `SELECT id FROM orders WHERE id=?`, id).Scan(&amp;previous)
        if err == nil </span><span class="cov8" title="1">{
                jsonReply(w, 200, Result{OrderID: id})
                return
        }</span>
        <span class="cov0" title="0">if err != sql.ErrNoRows </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov0" title="0">if _, err = ValidateOrder(h.Store.Domain, o, time.Now().Unix()); err != nil </span><span class="cov0" title="0">{
                reject(w, 400, "EXPIRED_ORDER")
                return
        }</span>
        <span class="cov0" title="0">ctx, cancel := context.WithTimeout(r.Context(), 8*time.Second)
        defer cancel()
        if err = h.Chain.Preflight(ctx, o); err != nil </span><span class="cov0" title="0">{
                reject(w, 422, "CHAIN_PRECHECK_REJECTED")
                return
        }</span>
        <span class="cov0" title="0">result, err := h.Runtime.Submit(ctx, Command{Kind: "PLACE", OrderID: id, Order: o})
        if err != nil </span><span class="cov0" title="0">{
                reject(w, 503, "RESULT_UNKNOWN")
                return
        }</span>
        <span class="cov0" title="0">if result.Code != "" </span><span class="cov0" title="0">{
                jsonReply(w, 422, result)
                return
        }</span>
        <span class="cov0" title="0">jsonReply(w, 201, result)</span>
}

// syncOrder 不相信前端说已取消;只确认接收到提示,周期扫描由worker独立执行。
// 公开调用不提供本地随意撤别人单的权限,真正cancel由maker钱包上链。
func (h *HTTP) syncOrder(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        id := r.PathValue("id")
        if len(id) != 66 || !strings.HasPrefix(id, "0x") || common.HexToHash(id) == (common.Hash{}) </span><span class="cov8" title="1">{
                reject(w, 400, "INVALID_ORDER_ID")
                return
        }</span>
        <span class="cov0" title="0">jsonReply(w, 202, map[string]string{"order_id": id, "status": "WAIT_CHAIN_SCAN"})</span>
}

// order 对原签单hash强读,供超时/刷新后确认,不依赖最近100项列表。
func (h *HTTP) order(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        var raw string
        err := h.Store.Views.QueryRowContext(r.Context(), `SELECT payload FROM orders WHERE id=?`, r.PathValue("id")).Scan(&amp;raw)
        if err == sql.ErrNoRows </span><span class="cov0" title="0">{
                reject(w, 404, "ORDER_NOT_FOUND")
                return
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov8" title="1">var o Order
        if json.Unmarshal([]byte(raw), &amp;o) != nil </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov8" title="1">jsonReply(w, 200, o)</span>
}

// tasks 仅暴露最近100个任务进度,不把raw交易/私钥传给浏览器。
func (h *HTTP) tasks(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        rows, err := h.Middleware.tasks.DB.QueryContext(r.Context(), `SELECT payload FROM chain_tasks ORDER BY id DESC LIMIT 100`)
        if err != nil </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        out := []TaskView{}
        for rows.Next() </span><span class="cov0" title="0">{
                var raw string
                var task Task
                if err = rows.Scan(&amp;raw); err != nil </span><span class="cov0" title="0">{
                        reject(w, 503, "QUERY_FAILED")
                        return
                }</span>
                <span class="cov0" title="0">if err = json.Unmarshal([]byte(raw), &amp;task); err != nil </span><span class="cov0" title="0">{
                        reject(w, 503, "QUERY_FAILED")
                        return
                }</span>
                <span class="cov0" title="0">out = append(out, taskView(task))</span>
        }
        <span class="cov8" title="1">if rows.Err() != nil </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov8" title="1">jsonReply(w, 200, out)</span>
}

// history 参数错误是明确拒绝;数据库/数据损坏不误报为用户输入问题。
func (h *HTTP) history(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        limit := 25
        if raw := r.URL.Query().Get("limit"); raw != "" </span><span class="cov0" title="0">{
                n, err := strconv.Atoi(raw)
                if err != nil || n &lt; 1 || n &gt; 100 </span><span class="cov0" title="0">{
                        reject(w, 400, "INVALID_HISTORY_QUERY")
                        return
                }</span>
                <span class="cov0" title="0">limit = n</span>
        }
        <span class="cov8" title="1">ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
        defer cancel()
        page, err := h.Store.History(ctx, h.Middleware.tasks, r.PathValue("kind"), r.URL.Query().Get("wallet"), r.URL.Query().Get("cursor"), limit)
        if err != nil </span><span class="cov0" title="0">{
                switch </span>{
                case strings.Contains(err.Error(), "invalid"), strings.Contains(err.Error(), "cursor mismatch"):<span class="cov0" title="0">
                        reject(w, 400, "INVALID_HISTORY_QUERY")</span>
                default:<span class="cov0" title="0">
                        reject(w, 503, "QUERY_FAILED")</span>
                }
                <span class="cov0" title="0">return</span>
        }
        <span class="cov8" title="1">jsonReply(w, 200, page)</span>
}

// taskDetail 按 bytes32 ID 查询公开状态,不披露 signed raw 或维护接口。
func (h *HTTP) taskDetail(w http.ResponseWriter, r *http.Request) <span class="cov8" title="1">{
        ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
        defer cancel()
        v, err := h.Middleware.tasks.Detail(ctx, r.PathValue("id"))
        if err == sql.ErrNoRows </span><span class="cov0" title="0">{
                reject(w, 404, "TASK_NOT_FOUND")
                return
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                reject(w, 503, "QUERY_FAILED")
                return
        }</span>
        <span class="cov8" title="1">jsonReply(w, 200, v)</span>
}
</pre>
    
    <pre class="file" id="file15" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/json"
        "fmt"
        "math/big"

        "github.com/ethereum/go-ethereum"
        "github.com/ethereum/go-ethereum/common"
        "github.com/ethereum/go-ethereum/core/types"
        "github.com/ethereum/go-ethereum/crypto"
)

// Event 是已确认合约事实的可重建投影;金额和高度采用文本,禁止浮点表示资产。
// 唯一 ID = blockHash/logIndex;不同交易中的事件即使内容相同也不能合并。
type Event struct {
        ID          string `json:"id"`
        Kind        string `json:"kind"`
        BlockNumber string `json:"block_number"`
        BlockHash   string `json:"block_hash"`
        TxHash      string `json:"tx_hash"`
        IntentID    string `json:"intent_id,omitempty"`
        MakerID     string `json:"maker_id,omitempty"`
        TakerID     string `json:"taker_id,omitempty"`
        Wallet      string `json:"wallet,omitempty"`
        Price       string `json:"price,omitempty"`
        Quantity    string `json:"quantity,omitempty"`
}

var matchedTopic = crypto.Keccak256Hash([]byte("Matched(bytes32,bytes32,bytes32,uint256,uint256)"))
var cancelledTopic = crypto.Keccak256Hash([]byte("Cancelled(bytes32,address)"))

// IndexRPC 缩小依赖以便注入确定性区块测试;实际生产实现是 ethclient.Client。
type IndexRPC interface {
        BlockNumber(context.Context) (uint64, error)
        HeaderByNumber(context.Context, *big.Int) (*types.Header, error)
        FilterLogs(context.Context, ethereum.FilterQuery) ([]types.Log, error)
}

// Indexer 只接受确认块,用单个事务发布本块事件与游标,崩溃最多重复本块。
// 与 receipt worker 分开负责完整查询,不直接调用 Engine 或发链交易。
type Indexer struct {
        Store *Store
        RPC   IndexRPC
}

// initIndex 所有表都属于可重建投影;显式版本禁止新代码误读未知布局。
func (s *Store) initIndex() error <span class="cov8" title="1">{
        tx, err := s.Views.Begin()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        _, err = tx.Exec(`CREATE TABLE IF NOT EXISTS view_metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
 INSERT OR IGNORE INTO view_metadata VALUES('schema_version','2');
 CREATE TABLE IF NOT EXISTS indexed_blocks(number INTEGER PRIMARY KEY,hash TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS chain_events(id TEXT PRIMARY KEY,block INTEGER NOT NULL,kind TEXT NOT NULL,intent_id TEXT NOT NULL,maker_id TEXT NOT NULL,taker_id TEXT NOT NULL,wallet TEXT NOT NULL,payload TEXT NOT NULL);
 CREATE INDEX IF NOT EXISTS orders_history_key ON orders(printf('%020d',seq));
 CREATE INDEX IF NOT EXISTS intents_history_key ON intents(status,id);
 CREATE INDEX IF NOT EXISTS events_history_key ON chain_events(printf('%020d',block)||'/'||substr(id,-10));
 CREATE INDEX IF NOT EXISTS events_intent ON chain_events(intent_id);
 CREATE INDEX IF NOT EXISTS events_order ON chain_events(maker_id,taker_id);
 CREATE TABLE IF NOT EXISTS index_progress(id INTEGER PRIMARY KEY CHECK(id=1),number INTEGER NOT NULL,hash TEXT NOT NULL);
 INSERT OR IGNORE INTO index_progress VALUES(1,-1,'');`)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">var version string
        if err = tx.QueryRow(`SELECT value FROM view_metadata WHERE key='schema_version'`).Scan(&amp;version); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if version != "2" </span><span class="cov0" title="0">{
                return fmt.Errorf("unsupported chain view schema %s", version)
        }</span>
        <span class="cov8" title="1">return tx.Commit()</span>
}

// decodeEvent 严格核对 topics 长度和金额布局;未知事件允许未来合约扩展,不作为成交。
func decodeEvent(log types.Log) (Event, bool, error) <span class="cov8" title="1">{
        e := Event{ID: fmt.Sprintf("%s/%010d", log.BlockHash.Hex(), log.Index), BlockNumber: fmt.Sprint(log.BlockNumber), BlockHash: log.BlockHash.Hex(), TxHash: log.TxHash.Hex()}
        if log.Removed </span><span class="cov0" title="0">{
                return e, false, fmt.Errorf("removed log in canonical block")
        }</span>
        <span class="cov8" title="1">if len(log.Topics) == 0 </span><span class="cov0" title="0">{
                return e, false, nil
        }</span>
        <span class="cov8" title="1">switch log.Topics[0] </span>{
        case matchedTopic:<span class="cov8" title="1">
                if len(log.Topics) != 4 || len(log.Data) != 64 </span><span class="cov8" title="1">{
                        return e, false, fmt.Errorf("malformed Matched event")
                }</span>
                <span class="cov8" title="1">e.Kind = "MATCHED"
                e.IntentID = log.Topics[1].Hex()
                e.MakerID = log.Topics[2].Hex()
                e.TakerID = log.Topics[3].Hex()
                e.Price = new(big.Int).SetBytes(log.Data[:32]).String()
                e.Quantity = new(big.Int).SetBytes(log.Data[32:]).String()</span>
        case cancelledTopic:<span class="cov0" title="0">
                if len(log.Topics) != 3 || len(log.Data) != 0 </span><span class="cov0" title="0">{
                        return e, false, fmt.Errorf("malformed Cancelled event")
                }</span>
                <span class="cov0" title="0">e.Kind = "CANCELLED"
                e.MakerID = log.Topics[1].Hex()
                e.Wallet = common.BytesToAddress(log.Topics[2].Bytes()).Hex()</span>
        default:<span class="cov0" title="0">
                return e, false, nil</span>
        }
        <span class="cov8" title="1">return e, true, nil</span>
}

// IndexBlock 校验连续性;事件表与块锚点/游标原子提交。仅在外围由索引器调用。
func (s *Store) IndexBlock(ctx context.Context, h *types.Header, logs []types.Log) error <span class="cov8" title="1">{
        tx, err := s.Views.BeginTx(ctx, nil)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var number int64
        var hash string
        if err = tx.QueryRowContext(ctx, `SELECT number,hash FROM index_progress WHERE id=1`).Scan(&amp;number, &amp;hash); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if h.Number == nil || !h.Number.IsInt64() || h.Number.Int64() != number+1 </span><span class="cov8" title="1">{
                return fmt.Errorf("index block gap")
        }</span>
        <span class="cov8" title="1">if number &gt;= 0 &amp;&amp; h.ParentHash.Hex() != hash </span><span class="cov0" title="0">{
                return fmt.Errorf("finalized index reorganization")
        }</span>
        <span class="cov8" title="1">for _, log := range logs </span><span class="cov8" title="1">{
                if log.BlockHash != h.Hash() || log.BlockNumber != h.Number.Uint64() || log.Address != common.HexToAddress(s.Domain.Contract) </span><span class="cov0" title="0">{
                        return fmt.Errorf("log outside indexed block/domain")
                }</span>
                <span class="cov8" title="1">e, known, err := decodeEvent(log)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if !known </span><span class="cov0" title="0">{
                        continue</span>
                }
                <span class="cov8" title="1">raw, err := json.Marshal(e)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if _, err = tx.ExecContext(ctx, `INSERT INTO chain_events VALUES(?,?,?,?,?,?,?,?)`, e.ID, log.BlockNumber, e.Kind, e.IntentID, e.MakerID, e.TakerID, e.Wallet, string(raw)); err != nil </span><span class="cov8" title="1">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">if _, err = tx.ExecContext(ctx, `INSERT INTO indexed_blocks VALUES(?,?)`, h.Number.Int64(), h.Hash().Hex()); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if _, err = tx.ExecContext(ctx, `UPDATE index_progress SET number=?,hash=? WHERE id=1`, h.Number.Int64(), h.Hash().Hex()); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">return tx.Commit()</span>
}

// Cursor 从唯一进度行读取已索引高度;-1 表示尚未完成创世块。
func (s *Store) IndexCursor(ctx context.Context) (int64, string, error) <span class="cov8" title="1">{
        var n int64
        var h string
        err := s.Views.QueryRowContext(ctx, `SELECT number,hash FROM index_progress WHERE id=1`).Scan(&amp;n, &amp;h)
        return n, h, err
}</span>

// CheckAnchor 重启和每轮都核对最后已确认块;深重组必须停止,不能自行覆盖历史。
func (i *Indexer) CheckAnchor(ctx context.Context) error <span class="cov8" title="1">{
        n, hash, err := i.Store.IndexCursor(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if n &lt; 0 </span><span class="cov8" title="1">{
                return nil
        }</span>
        <span class="cov8" title="1">h, err := i.RPC.HeaderByNumber(ctx, big.NewInt(n))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if h.Hash().Hex() != hash </span><span class="cov8" title="1">{
                return fmt.Errorf("finalized index reorganization at %d", n)
        }</span>
        <span class="cov8" title="1">return nil</span>
}

// Tick 最多64块,每块固定 blockHash 查询,二次核验后提交;暂时 RPC 错误可重试。
func (i *Indexer) Tick(ctx context.Context) error <span class="cov8" title="1">{
        if err := i.CheckAnchor(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">head, err := i.RPC.BlockNumber(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if head+1 &lt; i.Store.Domain.Confirmations </span><span class="cov0" title="0">{
                return nil
        }</span>
        <span class="cov8" title="1">target := head + 1 - i.Store.Domain.Confirmations
        n, _, err := i.Store.IndexCursor(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">for step := 0; step &lt; 64 &amp;&amp; uint64(n+1) &lt;= target; step++ </span><span class="cov8" title="1">{
                h, err := i.RPC.HeaderByNumber(ctx, big.NewInt(n+1))
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">hash := h.Hash()
                logs, err := i.RPC.FilterLogs(ctx, ethereum.FilterQuery{BlockHash: &amp;hash, Addresses: []common.Address{common.HexToAddress(i.Store.Domain.Contract)}, Topics: [][]common.Hash{{matchedTopic, cancelledTopic}}})
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">current, err := i.RPC.HeaderByNumber(ctx, h.Number)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if current.Hash() != hash </span><span class="cov0" title="0">{
                        return fmt.Errorf("confirmed block changed while indexing")
                }</span>
                <span class="cov8" title="1">if err = i.Store.IndexBlock(ctx, h, logs); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">n++</span>
        }
        <span class="cov8" title="1">return nil</span>
}

// indexedMatch 为对账提供完整事件,不使用只取100项的 HTTP state。
func indexedMatch(ctx context.Context, tx *sql.Tx, id string) (Event, error) <span class="cov8" title="1">{
        var raw string
        var e Event
        err := tx.QueryRowContext(ctx, `SELECT payload FROM chain_events WHERE kind='MATCHED' AND intent_id=?`, id).Scan(&amp;raw)
        if err == nil </span><span class="cov0" title="0">{
                err = json.Unmarshal([]byte(raw), &amp;e)
        }</span>
        <span class="cov8" title="1">return e, err</span>
}
</pre>
    
    <pre class="file" id="file16" style="display: none">package chaintrade

import (
        "context"
        "encoding/json"
        "fmt"
        "strings"
        "time"

        "github.com/redis/go-redis/v9"
        "github.com/twmb/franz-go/pkg/kgo"
        "github.com/twmb/franz-go/pkg/kmsg"
)

// Middleware 为外围可选Redis/Kafka适配,关闭它们不会改变链资金权威。
type Middleware struct {
        Redis *redis.Client
        Kafka *kgo.Client
        Topic string
        store *Store
        tasks *Tasks
        retry []*kgo.Record // 仅消费goroutine拥有;持久化失败后保留本批,不轮询跨过失败记录。
}

// OpenMiddleware 配置了但不可用时拒绝启动,不默默把分布式演示切成本地。
func OpenMiddleware(ctx context.Context, s *Store, t *Tasks, redisURL, brokers, topic string) (*Middleware, error) <span class="cov8" title="1">{
        m := &amp;Middleware{store: s, tasks: t, Topic: topic}
        if redisURL != "" </span><span class="cov0" title="0">{
                opt, err := redis.ParseURL(redisURL)
                if err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov0" title="0">m.Redis = redis.NewClient(opt)
                if err = m.Redis.Ping(ctx).Err(); err != nil </span><span class="cov0" title="0">{
                        m.Close()
                        return nil, err
                }</span>
        }
        <span class="cov8" title="1">if brokers != "" </span><span class="cov0" title="0">{
                client, err := kgo.NewClient(kgo.SeedBrokers(brokers), kgo.ConsumeTopics(topic), kgo.ConsumerGroup("web3-relayer-"+s.Domain.Dataset), kgo.DisableAutoCommit(), kgo.ConsumeResetOffset(kgo.NewOffset().AtStart()))
                if err != nil </span><span class="cov0" title="0">{
                        m.Close()
                        return nil, err
                }</span>
                <span class="cov0" title="0">m.Kafka = client
                if err = client.Ping(ctx); err != nil </span><span class="cov0" title="0">{
                        m.Close()
                        return nil, err
                }</span>
                // 主动建主题,避免生产/消费首次 metadata 竞态;生产应预建并限制ACL。
                <span class="cov0" title="0">create := kmsg.NewPtrCreateTopicsRequest()
                entry := kmsg.NewCreateTopicsRequestTopic()
                entry.Topic = topic
                entry.NumPartitions = 1
                entry.ReplicationFactor = 1
                create.Topics = []kmsg.CreateTopicsRequestTopic{entry}
                reply, e := create.RequestWith(ctx, client)
                if e != nil </span><span class="cov0" title="0">{
                        m.Close()
                        return nil, e
                }</span>
                <span class="cov0" title="0">for _, v := range reply.Topics </span><span class="cov0" title="0">{
                        if v.ErrorCode != 0 &amp;&amp; v.ErrorCode != 36 </span><span class="cov0" title="0">{
                                m.Close()
                                return nil, fmt.Errorf("topic creation code %d", v.ErrorCode)
                        }</span>
                }

        }
        <span class="cov8" title="1">return m, nil</span>
}

// Close 仅关闭本进程client,不删除Redis键/Kafka主题/SQL任务。
func (m *Middleware) Close() <span class="cov8" title="1">{
        if m.Redis != nil </span><span class="cov0" title="0">{
                m.Redis.Close()
        }</span>
        <span class="cov8" title="1">if m.Kafka != nil </span><span class="cov0" title="0">{
                m.Kafka.Close()
        }</span>
}

// Allow Lua原子窗口限流,Redis故障保守拒绝;本地模式另有HTTP并发预算。
func (m *Middleware) Allow(ctx context.Context, key string) bool <span class="cov8" title="1">{
        if m.Redis == nil </span><span class="cov8" title="1">{
                return true
        }</span>
        <span class="cov0" title="0">n, err := m.Redis.Eval(ctx, `local n=redis.call('INCR',KEYS[1]); if n==1 then redis.call('PEXPIRE',KEYS[1],1000) end; return n`, []string{"web3:limit:" + m.store.Domain.Dataset + ":" + key}).Int64()
        return err == nil &amp;&amp; n &lt;= 50</span>
}

// CachedState Redis仅缓存公共签名订单,不裁定余额;强读需要回源而非min_seq缓存。
func (m *Middleware) CachedState(ctx context.Context) (State, error) <span class="cov8" title="1">{
        key := "web3:state:" + m.store.Domain.Dataset
        if m.Redis != nil </span><span class="cov0" title="0">{
                raw, err := m.Redis.Get(ctx, key).Result()
                if err == nil </span><span class="cov0" title="0">{
                        var s State
                        if json.Unmarshal([]byte(raw), &amp;s) == nil &amp;&amp; s.Dataset == m.store.Domain.Dataset </span><span class="cov0" title="0">{
                                return s, nil
                        }</span>
                }
        }
        <span class="cov8" title="1">s, err := m.store.State(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return s, err
        }</span>
        <span class="cov8" title="1">if m.Redis != nil </span><span class="cov0" title="0">{
                raw, _ := json.Marshal(s)
                // seq不能Lua tonumber比较超过JS安全范围:固定20位补零字典序比较。
                padded := strings.Repeat("0", 20-len(s.Seq)) + s.Seq
                _, _ = m.Redis.Eval(ctx, `local prev=redis.call('GET',KEYS[2]); if not prev or ARGV[1]&gt;=prev then redis.call('SET',KEYS[1],ARGV[2],'PX',250); redis.call('SET',KEYS[2],ARGV[1]); end; return 1`, []string{key, key + ":seq"}, padded, string(raw)).Result()
        }</span>
        <span class="cov8" title="1">return s, nil</span>
}

// Dispatch 先outbox再持久任务;Kafka发布可能重复,稳定ID与SQL唯一约束吸收。
func (m *Middleware) Dispatch(ctx context.Context) error <span class="cov8" title="1">{
        rows, err := m.store.Views.QueryContext(ctx, `SELECT id,payload FROM outbox WHERE published=0 ORDER BY rowid LIMIT 100`)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">type item struct{ id, raw string }
        items := []item{}
        for rows.Next() </span><span class="cov8" title="1">{
                var i item
                if err = rows.Scan(&amp;i.id, &amp;i.raw); err != nil </span><span class="cov0" title="0">{
                        rows.Close()
                        return err
                }</span>
                <span class="cov8" title="1">items = append(items, i)</span>
        }
        <span class="cov8" title="1">err = rows.Err()
        rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">for _, i := range items </span><span class="cov8" title="1">{
                if m.Kafka != nil </span><span class="cov0" title="0">{
                        err = m.Kafka.ProduceSync(ctx, &amp;kgo.Record{Topic: m.Topic, Key: []byte(m.store.Domain.Dataset), Value: []byte(i.raw)}).FirstErr()
                }</span> else<span class="cov8" title="1"> {
                        var intent Intent
                        err = json.Unmarshal([]byte(i.raw), &amp;intent)
                        if err == nil </span><span class="cov8" title="1">{
                                err = m.tasks.PutIntent(ctx, intent)
                        }</span>
                }
                <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if _, err = m.store.Views.ExecContext(ctx, `UPDATE outbox SET published=1 WHERE id=?`, i.id); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">return nil</span>
}

// Consume offset仅在每条任务已SQL持久化后提交;网络错误不覆盖其他任务。
func (m *Middleware) Consume(ctx context.Context) error <span class="cov0" title="0">{
        if m.Kafka == nil </span><span class="cov0" title="0">{
                return nil
        }</span>
        <span class="cov0" title="0">if len(m.retry) == 0 </span><span class="cov0" title="0">{
                fetch := m.Kafka.PollRecords(ctx, 100)
                if err := fetch.Err(); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">m.retry = fetch.Records()</span>
        }
        <span class="cov0" title="0">for len(m.retry) &gt; 0 </span><span class="cov0" title="0">{
                r := m.retry[0]
                var i Intent
                if err := json.Unmarshal(r.Value, &amp;i); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if string(r.Key) == m.store.Domain.Dataset &amp;&amp; strings.HasPrefix(i.ID, "0x"+m.store.Domain.Dataset) </span><span class="cov0" title="0">{
                        if err := ValidateIntent(m.store.Domain, i); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                        <span class="cov0" title="0">if err := m.tasks.PutIntent(ctx, i); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
                <span class="cov0" title="0">if err := m.Kafka.CommitRecords(ctx, r); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">m.retry = m.retry[1:]</span> // SQL+offset均成功后才放下一条,重试不能漏当前消息。
        }

        <span class="cov0" title="0">return nil</span>
}

// RunConsumer 重试外围消费,退出由ctx控制;SQL/Kafka失败可观察但不放行错误资金。
func (m *Middleware) RunConsumer(ctx context.Context, report func(error)) <span class="cov0" title="0">{
        if m.Kafka == nil </span><span class="cov0" title="0">{
                return
        }</span>
        <span class="cov0" title="0">for ctx.Err() == nil </span><span class="cov0" title="0">{
                if err := m.Consume(ctx); err != nil &amp;&amp; ctx.Err() == nil </span><span class="cov0" title="0">{
                        report(err)
                        select </span>{
                        case &lt;-ctx.Done():<span class="cov0" title="0">
                                return</span>
                        case &lt;-time.After(time.Second):<span class="cov0" title="0"></span>
                        }
                }
        }
}
</pre>
    
    <pre class="file" id="file17" style="display: none">package chaintrade

import (
        "context"
        "fmt"
        "net/http"
        "sync/atomic"
        "time"
)

// Monitoring 只属于外围。有限桶/无钱包标签避免高基数;requestTotal 不计诊断自身。
// Atomic 不保护业务对象,核心 Engine 不依赖这些观测值。
type Monitoring struct {
        Completed     atomic.Uint64
        Latency       [6]atomic.Uint64
        LatencyMicros atomic.Uint64
        WorkerErrors  atomic.Uint64
        Samples       atomic.Uint64
        SampleFailed  atomic.Uint64
        IndexHeight   atomic.Int64
        IndexLag      atomic.Int64
        Pending       atomic.Int64
        OldestAge     atomic.Int64
        UnknownAge    atomic.Int64
        Outbox        atomic.Int64
        Differences   atomic.Int64
        Lag           atomic.Int64
        LastSuccess   atomic.Int64
}

var latencyBounds = [6]float64{.005, .025, .1, .5, 2, 10}

// observe 每个请求命中一个桶;输出时累计成 Prometheus histogram 的 le 语义。
func (m *Monitoring) observe(start time.Time) <span class="cov8" title="1">{
        elapsed := time.Since(start)
        m.Completed.Add(1)
        m.LatencyMicros.Add(uint64(elapsed.Microseconds()))
        for n, b := range latencyBounds </span><span class="cov8" title="1">{
                if elapsed.Seconds() &lt;= b </span><span class="cov8" title="1">{
                        m.Latency[n].Add(1)
                        break</span>
                }
        }
}

// Sample SQL/RPC/重放可慢但不阻塞核心;失败时保留上一次 gauge 并显式标失败。
func (h *HTTP) Sample(ctx context.Context) error <span class="cov0" title="0">{
        h.Monitor.Samples.Add(1)
        err := h.sample(ctx)
        if err != nil </span><span class="cov0" title="0">{
                h.Monitor.SampleFailed.Store(1)
        }</span> else<span class="cov0" title="0"> {
                h.Monitor.SampleFailed.Store(0)
                h.Monitor.LastSuccess.Store(time.Now().Unix())
        }</span>
        <span class="cov0" title="0">return err</span>
}
func (h *HTTP) sample(ctx context.Context) error <span class="cov0" title="0">{
        report, err := h.Store.Reconcile(ctx, h.Middleware.tasks)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">height, _, err := h.Store.IndexCursor(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">head, err := h.Chain.Client.BlockNumber(ctx)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">var pending, created, unknown, outbox int64
        t := h.Middleware.tasks
        // 老任务没有时间,只报告 unknown_age 数量,不能编造 SLA 成绩。
        expr := "json_extract(payload,'$.created_at')"
        if t.pg </span><span class="cov0" title="0">{
                expr = "CAST(payload::jsonb-&gt;&gt;'created_at' AS BIGINT)"
        }</span>
        <span class="cov0" title="0">query := `SELECT count(*),COALESCE(MIN(CASE WHEN ` + expr + `&gt;0 THEN ` + expr + ` END),0),COALESCE(SUM(CASE WHEN COALESCE(` + expr + `,0)=0 THEN 1 ELSE 0 END),0) FROM chain_tasks WHERE status NOT IN ('CONFIRMED','FAILED')`
        if err = t.DB.QueryRowContext(ctx, query).Scan(&amp;pending, &amp;created, &amp;unknown); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if err = h.Store.Views.QueryRowContext(ctx, `SELECT count(*) FROM outbox WHERE published=0`).Scan(&amp;outbox); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">target := int64(head) + 1 - int64(h.Store.Domain.Confirmations)
        if target &lt; -1 </span><span class="cov0" title="0">{
                target = -1
        }</span>
        <span class="cov0" title="0">behind := target - height
        if behind &lt; 0 </span><span class="cov0" title="0">{
                behind = 0
        }</span>
        <span class="cov0" title="0">age := int64(0)
        if created &gt; 0 </span><span class="cov0" title="0">{
                age = time.Now().Unix() - created
                if age &lt; 0 </span><span class="cov0" title="0">{
                        age = 0
                }</span>
        }
        <span class="cov0" title="0">m := &amp;h.Monitor
        m.IndexHeight.Store(height)
        m.IndexLag.Store(behind)
        m.Pending.Store(pending)
        m.OldestAge.Store(age)
        m.UnknownAge.Store(unknown)
        m.Outbox.Store(outbox)
        m.Differences.Store(int64(report.Differences))
        m.Lag.Store(int64(report.Lag))
        return nil</span>
}

// Diagnostics 仅由回环 listener 挂载;/check 不修改资产、不重发交易,查询有超时。
func (h *HTTP) Diagnostics() http.Handler <span class="cov8" title="1">{
        mux := http.NewServeMux()
        mux.HandleFunc("GET /check", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
                defer cancel()
                report, err := h.Store.Reconcile(ctx, h.Middleware.tasks)
                if err != nil </span><span class="cov0" title="0">{
                        reject(w, 503, "CHECK_FAILED")
                        return
                }</span>
                <span class="cov8" title="1">jsonReply(w, 200, report)</span>
        })
        <span class="cov8" title="1">mux.HandleFunc("GET /metrics", func(w http.ResponseWriter, r *http.Request) </span><span class="cov8" title="1">{
                w.Header().Set("Content-Type", "text/plain; version=0.0.4")
                m := &amp;h.Monitor
                fmt.Fprintf(w, "web3_http_requests_total %d\nweb3_http_denied_total %d\n", h.requests.Load(), h.denied.Load())
                cumulative := uint64(0)
                fmt.Fprintln(w, "# TYPE web3_http_request_duration_seconds histogram")
                for n, b := range latencyBounds </span><span class="cov8" title="1">{
                        cumulative += m.Latency[n].Load()
                        fmt.Fprintf(w, "web3_http_request_duration_seconds_bucket{le=\"%g\"} %d\n", b, cumulative)
                }</span>
                <span class="cov8" title="1">fmt.Fprintf(w, "web3_http_request_duration_seconds_bucket{le=\"+Inf\"} %d\nweb3_http_request_duration_seconds_count %d\nweb3_http_request_duration_seconds_sum %.6f\n", m.Completed.Load(), m.Completed.Load(), float64(m.LatencyMicros.Load())/1e6)
                for _, v := range []struct {
                        name  string
                        value int64
                }{
                        {"index_height", m.IndexHeight.Load()}, {"index_lag_blocks", m.IndexLag.Load()}, {"settlement_pending", m.Pending.Load()}, {"settlement_oldest_age_seconds", m.OldestAge.Load()}, {"settlement_unknown_age", m.UnknownAge.Load()}, {"outbox_pending", m.Outbox.Load()}, {"reconciliation_differences", m.Differences.Load()}, {"reconciliation_lag", m.Lag.Load()}, {"sample_failed", int64(m.SampleFailed.Load())}, {"sample_last_success_timestamp_seconds", m.LastSuccess.Load()},
                } </span><span class="cov8" title="1">{
                        fmt.Fprintf(w, "web3_%s %d\n", v.name, v.value)
                }</span>
                <span class="cov8" title="1">fmt.Fprintf(w, "web3_worker_errors_total %d\nweb3_samples_total %d\n", m.WorkerErrors.Load(), m.Samples.Load())</span>
        })
        <span class="cov8" title="1">return mux</span>
}
</pre>
    
    <pre class="file" id="file18" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/json"
        "fmt"
        "reflect"
        "strconv"
        "strings"
        "time"
)

// CheckReport 分开列差异和流水线延迟,防止 Kafka/索引尚未追平时被误判成资产丢失。
// Issues 最多100条,计数包含全部;不输出签名、raw、DSN,适合回环运维查询。
type CheckReport struct {
        Dataset     string   `json:"dataset_id"`
        Seq         string   `json:"seq"`
        CheckedAt   int64    `json:"checked_at"`
        Orders      int      `json:"orders"`
        Intents     int      `json:"intents"`
        Differences int      `json:"differences"`
        Lag         int      `json:"lag"`
        Issues      []string `json:"issues"`
}

func (r *CheckReport) issue(lag bool, code, id string) <span class="cov8" title="1">{
        if lag </span><span class="cov8" title="1">{
                r.Lag++
        }</span> else<span class="cov8" title="1"> {
                r.Differences++
        }</span>
        <span class="cov8" title="1">if len(r.Issues) &lt; 100 </span><span class="cov8" title="1">{
                r.Issues = append(r.Issues, code+":"+id)
        }</span>
}

// Reconcile 只读取全量权威日志和独立投影;重放使用新 Engine,不读取运行核心对象。
// 投影读事务固定水位,然后只重放 &lt;= 水位的日志,排除跨库读取时刻引发的假差异。
// 所有链判断基于已验证 receipt/已确认事件,未查询钱包余额,不是资金储备审计。
func (s *Store) Reconcile(ctx context.Context, t *Tasks) (CheckReport, error) <span class="cov8" title="1">{
        report := CheckReport{Dataset: s.Domain.Dataset, CheckedAt: time.Now().Unix(), Issues: []string{}}
        view, err := s.Views.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">defer view.Rollback()
        var seq int64
        if err = view.QueryRowContext(ctx, `SELECT seq FROM progress WHERE id=1`).Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">report.Seq = strconv.FormatInt(seq, 10)
        e := NewEngine(s.Domain.Dataset)
        rows, err := s.Journal.QueryContext(ctx, `SELECT seq,payload FROM commands WHERE seq&lt;=? ORDER BY seq`, seq)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                var n int64
                var raw string
                var c Command
                if err = rows.Scan(&amp;n, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;c); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if n != c.Seq || n != e.seq+1 </span><span class="cov0" title="0">{
                        err = fmt.Errorf("journal sequence gap")
                        break</span>
                }
                <span class="cov8" title="1">if err = validateCommand(s.Domain, c); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">e.Apply(c)</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">if e.seq != seq </span><span class="cov0" title="0">{
                report.issue(false, "JOURNAL_WATERMARK", report.Seq)
        }</span>
        <span class="cov8" title="1">report.Orders = len(e.orders)
        report.Intents = len(e.intents)
        rows, err = view.QueryContext(ctx, `SELECT id,seq,payload FROM orders ORDER BY seq`)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">seenOrders := map[string]bool{}
        for rows.Next() </span><span class="cov8" title="1">{
                var id, raw string
                var rowSeq int64
                var o Order
                if err = rows.Scan(&amp;id, &amp;rowSeq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;o); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">seenOrders[id] = true
                expected := e.orders[id]
                if expected == nil || id != o.ID || rowSeq != o.Seq || !reflect.DeepEqual(*expected, o) </span><span class="cov8" title="1">{
                        report.issue(false, "ORDER_PROJECTION", id)
                }</span>
                <span class="cov8" title="1">q, ok := strconvInt(o.Quantity)
                if !ok || o.Remaining &lt; 0 || o.Pending &lt; 0 || o.Filled &lt; 0 || o.Canceled &lt; 0 || q != o.Remaining+o.Pending+o.Filled+o.Canceled </span><span class="cov8" title="1">{
                        report.issue(false, "QUANTITY_CONSERVATION", id)
                }</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">for id := range e.orders </span><span class="cov8" title="1">{
                if !seenOrders[id] </span><span class="cov0" title="0">{
                        report.issue(false, "ORDER_MISSING", id)
                }</span>
        }
        <span class="cov8" title="1">rows, err = view.QueryContext(ctx, `SELECT id,status,payload FROM intents`)
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">seenIntents := map[string]bool{}
        for rows.Next() </span><span class="cov8" title="1">{
                var id, status, raw string
                var i Intent
                if err = rows.Scan(&amp;id, &amp;status, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;i); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">seenIntents[id] = true
                expected := e.intents[id]
                if expected == nil || id != i.ID || status != i.Status || !reflect.DeepEqual(*expected, i) </span><span class="cov0" title="0">{
                        report.issue(false, "INTENT_PROJECTION", id)
                }</span>
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov0" title="0">{
                return report, err
        }</span>
        <span class="cov8" title="1">for id := range e.intents </span><span class="cov8" title="1">{
                if !seenIntents[id] </span><span class="cov0" title="0">{
                        report.issue(false, "INTENT_MISSING", id)
                }</span>
        }
        // 同一个 task 读快照保证 status 与 payload 一致;与 view 的先后关系只认稳定冲突。
        <span class="cov8" title="1">taskOptions := &amp;sql.TxOptions{ReadOnly: true}
        if t.pg {
</span>                taskOptions.Isolation = sql.LevelRepeatableRead
        }</span>
        <span class="cov8" title="1">taskTx, err := t.DB.BeginTx(ctx, taskOptions)
        if err != nil {
                return report, err
</span>        }
        d</span>efer taskTx.Rollback()
        <span class="cov8" title="1">var domain string
</span>        if err = taskTx.QueryRowContext(ctx, `SELECT value FROM chain_metadata WHERE key='domain'`).Scan(&amp;domain); err != nil {
                </span>return report, err
        <span class="cov8" title="1">}
        if domain != m</span><span class="cov0" title="0">ustJSON(s.Domain) {
                return report, fmt.Errorf("reconciliation task domain mismatch")
        }</span>
        <span class="cov8" title="1">rows, err = taskTx.QueryContext(ctx, `SELECT id,status,payload,version FROM chain_tasks`)
        if err != nil {
</span>                return report, err
        }
        tasks := map[string]Task{}
        for rows.Next() {
</span>                var id</span>, status, raw string
                var version int64
                <span class="cov8" title="1">var task Task
</span>                if err</span> = rows.Scan(&amp;id, &amp;status, &amp;raw, &amp;version); err != nil {
                        break
                <span class="cov8" title="1">}
                if err = json.Unmarshal([]byte(raw), &amp;task); err != nil {
</span>                        break
                }
                t</span>asks[id] = task
                <span class="cov8" title="1">if err = ValidateIntent(s.Domain, task.Intent); err != nil {
</span>                        report.issue(false, "TASK_INTENT_INVALID", id)
                        </span>err = nil
                }
        <span class="cov8" title="1">        if task.Inten</span><span class="cov8" title="1">t.ID != id || task.Status != status || task.Version != version {
                        report.issue(false, "TASK_ROW", id)
                </span>}
        <span class="cov8" title="1">}
        if err == nil </span><span class="cov0" title="0">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil {
</span>                return report, err
        }</span>
        <span class="cov8" title="1">var indexed int64
</span>        if err = view.QueryRowContext(ctx, `SELECT number FROM index_progress WHERE id=1`).Scan(&amp;indexed); err != nil {
                return report, err
        }
</span>        for id, i := range e.intents {
                v</span>ar ou<span class="cov8" title="1">tbox string
</span>                err = view.QueryRowContext(ctx, `SELECT payload FROM outbox WHERE id=?`, id).Scan(&amp;outbox)
                i</span>f err<span class="cov8" title="1"> == sql.ErrNoRows {
                        report.issue(false, "OUTBOX_MISSING", id)
                } else if err != nil {
</span>                        return report, err
                } </span>else {
                        <span class="cov8" title="1">var original Intent
                        if err = json.Unmarshal([]byte(outbox), &amp;original); err != nil {
                                return report, err
                        }
                        expectedOriginal := *i
</span>                        expectedOriginal.Status = "READY"
                        e</span>xpectedOriginal.TxHash = ""
                        expectedOriginal.Reason = ""
                <span class="cov8" title="1">        if !reflect.DeepEqual(original, expectedOriginal) {
                                report.is</span><span class="cov8" title="1">sue(false, "OUTBOX_CONTENT", id)
                        }
                }
</span>                task, exists := tasks[id]
                <span class="cov8" title="1">if !exists {
                        report.issue(true, "HANDOFF_LAG", id)
                        continue
                }
                expectedTask := *i
</span>                expectedTask.Status = "READY"
                e</span>xpectedTask.TxHash = ""
                expectedTask.Reason = ""
                <span class="cov8" title="1">if !reflect.DeepEqual(t</span><span class="cov8" title="1">ask.Intent, expectedTask) {
                        report.issue(false, "TASK_INTENT_CONTENT", id)
</span>                }
                //</span> core READY 与任务最终状态可能是采样间刚完成,下一次快照才可判定。
                if i.S<span class="cov0" title="0">tatus == "READY" {
</span>                        if task.Status == "CONFIRMED" || task.Status == "FAILED" {
                        </span>        repo<span class="cov0" title="0">rt.issue(true, "COMMAND_LAG", id)
</span>                        }
                }</span> else if task.Status != "CONFIRMED" &amp;&amp; task.Status != "FAILED" {
                <span class="cov8" title="1">        report.issue(true, "TASK_SAVE_LAG", id)
                } else if i.Status != task.Status || i.TxH</span><span class="cov0" title="0">ash != task.Hash {
                        report.issue(false, "FINAL_TASK_CONFLICT", id)
                }</span>
                <span class="cov8" title="1">event, evErr := </span><span class="cov0" title="0">indexedMatch(ctx, view, id)
                if evErr != nil &amp;&amp; evErr != sql.ErrNoRows {
                        return report, evErr
</span>                }
                if</span> evErr == nil {
                        <span class="cov0" title="0">price, _ := strconvInt(i</span><span class="cov0" title="0">.Maker.Price)
                        if event.MakerID != i.Maker.ID || event.TakerID != i.Taker.ID || event.Quantity != fmt.Sprint(i.Quantity) || event.Price != fmt.Sprint(price) || (task.Hash != "" &amp;&amp; !strings.EqualFold(task.Hash, event.TxHash)) {
                                </span>repor<span class="cov0" title="0">t.issue(false, "MATCHED_CONT</span><span class="cov0" title="0">ENT", id)
                        }
                        i</span>f i.Status == "FAILED" {
                                repo<span class="cov8" title="1">rt.issue(false, "FAILED_HAS_</span><span class="cov0" title="0">MATCH", id)
                        } else if i.Status != "CONFIRMED" {
</span>                                report.issue(true, "INDEX_COMMAND_LAG", id)
                        }</span>
                } else if i.Status == "CONFIRMED" {
                        i</span>f task.BlockNumber &gt; 0 &amp;&amp; indexed &gt;= int64(task.BlockNumber) {
                                report.issue(false, "MATCHED_MISSING", id)
                        } else {
        <span class="cov8" title="1">                        report.issue(true, "INDEX</span><span class="cov8" title="1">_LAG_OR_LEGACY_HEIGHT", id)
                        }
</span>                }
        }
        for id, task := range tasks {
                if e.intents[id] == nil {
</span>                        // task可能在view快照之后才由consumer创建;seq高于快照只归类延迟。
                        c</span>omman<span class="cov0" title="0">dSeq, parseErr := strconv.ParseUint(strings.TrimPrefix(id, "0x"+s.Domain.Dataset), 16, 64)
                        if parseErr == nil &amp;&amp; commandSeq &gt; uint64(seq) {
                                </span>report.issue(true, "TASK_AHEAD", id)
                        } else {
                                report.issue(false, "TASK_WITHOUT_INTENT", task.Intent.ID)
                        }
                }
        <span class="cov8" title="1">}

</span>        // 本数据集事件没有对应意图是稳定差异;其他数据集的历史链事件不归本实例所有。
        r</span>ows, err = view.QueryContext(ctx, `SELECT intent_id FROM chain_events WHERE kind='MATCHED'`)
        <span class="cov8" title="1">if err != nil {
</span>                return report, err
        }
</span>        for row</span>s.Next() {
                var id string
                <span class="cov0" title="0">if err = rows.Scan(&amp;id); err != nil {
</span>                        break
                }
</span>                if strings.HasPrefix(id, "0x"+s.Domain.Dataset) &amp;&amp; e.intents[id] == nil {
                        n</span>, par<span class="cov0" title="0">seErr := strconv.ParseUint(strings.TrimPrefix(id, "0x"+s.Domain.Dataset), 16, 64)
                        if parseErr != nil || n &lt;= uint64(seq) {
                                </span>report.issue(false, "EVENT_WITHOUT_INTENT", id)
                        } else {
                                report.issue(true, "EVENT_AHEAD", id)
        <span class="cov8" title="1">                }
</span>                }
        }</span>
        <span class="cov8" title="1">if err == nil {
                err = rows.Er</span><span class="cov0" title="0">r()
        }
        r</span>ows.Close()
        if err != nil {
        <span class="cov8" title="1">        return report, err
        }
</span>        // 已索引取消事件但余量仍可匹配表示扫描延迟;不自行更改订单。
        r</span>ows, err = view.QueryContext(ctx, `SELECT maker_id FROM chain_events WHERE kind='CANCELLED'`)
        <span class="cov8" title="1">if err != nil {
</span>                return report, err
        }
</span>        for row</span>s.Next() {
                var id string
                <span class="cov0" title="0">if err = rows.Scan(&amp;id); err != nil {
</span>                        break
                }</span>
                if o := e.orders[id]; o != nil &amp;&amp; o.Remaining &gt; 0 {
        <span class="cov8" title="1">                report.issue</span><span class="cov8" title="1">(true, "CANCEL_SCAN_LAG", id)
                }
        }</span>
        <span class="cov8" title="1">if err == nil {
                err = rows.Er</span><span class="cov0" title="0">r()
        }
        r</span>ows.Close()
        <span class="cov8" title="1">if err != nil {
</span>                return report, err
        }
        return report, nil
}
</pre>
    
    <pre class="file" id="file19" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/json"
        "fmt"
        "github.com/ethereum/go-ethereum/common"
        "os"
        "path/filepath"
        "strconv"
        "strings"
        "sync"

        "github.com/gofrs/flock"
        _ "modernc.org/sqlite"
)

// Store 保持journal与views在独立SQLite文件,tasks由另一权威SQL适配器持有。
type Store struct {
        Journal, Views *sql.DB
        lock           *flock.Flock
        Domain         Domain
}

// sqlite 在每次连接使用DSN设置FULL/WAL,不受连接替换丢PRAGMA影响。
func sqlite(path string) (*sql.DB, error) <span class="cov8" title="1">{
        db, err := sql.Open("sqlite", "file:"+filepath.ToSlash(path)+"?_pragma=journal_mode(WAL)&amp;_pragma=synchronous(FULL)&amp;_pragma=busy_timeout(5000)")
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">db.SetMaxOpenConns(1)
        if err = db.Ping(); err != nil </span><span class="cov0" title="0">{
                db.Close()
                return nil, err
        }</span>
        <span class="cov8" title="1">return db, nil</span>
}

// OpenStore 独占新模式目录并绑定网络;禁止用模拟data或另一合约域重解释日志。
func OpenStore(dir string, d Domain) (*Store, error) <span class="cov8" title="1">{
        if id, ok := uintText(d.ChainID); !ok || id.Sign() == 0 </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("invalid chain id")
        }</span>
        <span class="cov8" title="1">if d.Confirmations &lt; 1 || d.Confirmations &gt; 128 </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("invalid confirmations")
        }</span>
        <span class="cov8" title="1">for _, address := range []string{d.Contract, d.Base, d.Quote, d.Relayer} </span><span class="cov8" title="1">{
                if !common.IsHexAddress(address) || common.HexToAddress(address) == (common.Address{}) </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("invalid domain address")
                }</span>
        }
        <span class="cov8" title="1">if strings.EqualFold(d.Base, d.Quote) </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("identical assets")
        }</span>
        <span class="cov8" title="1">if err := os.MkdirAll(dir, 0700); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if _, err := os.Stat(filepath.Join(dir, "auth.db")); err == nil </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("simulation directory cannot be reused")
        }</span>
        <span class="cov8" title="1">s := &amp;Store{lock: flock.New(filepath.Join(dir, "chain.lock")), Domain: d}
        locked, err := s.lock.TryLock()
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if !locked </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("chain directory already in use")
        }</span>
        <span class="cov8" title="1">ok := false
        defer func() </span><span class="cov8" title="1">{
                if !ok </span><span class="cov8" title="1">{
                        s.Close()
                }</span>
        }()
        <span class="cov8" title="1">s.Journal, err = sqlite(filepath.Join(dir, "chain-journal.db"))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">s.Views, err = sqlite(filepath.Join(dir, "chain-views.db"))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">_, err = s.Journal.Exec(`CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS commands(seq INTEGER PRIMARY KEY,payload TEXT NOT NULL)`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        // 当前日志编码版本不隐式升级;未来迁移需离线工具和测试。
        <span class="cov8" title="1">if _, err = s.Journal.Exec(`INSERT OR IGNORE INTO metadata VALUES('schema_version','1')`); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">var version string
        if err = s.Journal.QueryRow(`SELECT value FROM metadata WHERE key='schema_version'`).Scan(&amp;version); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if version != "1" </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("unsupported chain journal version %s", version)
        }</span>
        <span class="cov8" title="1">d.Dataset = ""
        raw, _ := json.Marshal(d)
        var previous string
        err = s.Journal.QueryRow(`SELECT value FROM metadata WHERE key='domain'`).Scan(&amp;previous)
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                if _, err = s.Journal.Exec(`INSERT INTO metadata VALUES('domain',?)`, string(raw)); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
        } else<span class="cov8" title="1"> if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span> else<span class="cov8" title="1"> if previous != string(raw) </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("chain domain changed; use a new directory")
        }</span>
        <span class="cov8" title="1">if _, err = s.Journal.Exec(`INSERT OR IGNORE INTO metadata VALUES('dataset',lower(hex(randomblob(16))))`); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if err = s.Journal.QueryRow(`SELECT value FROM metadata WHERE key='dataset'`).Scan(&amp;s.Domain.Dataset); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">_, err = s.Views.Exec(`CREATE TABLE IF NOT EXISTS orders(id TEXT PRIMARY KEY,seq INTEGER NOT NULL,payload TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS intents(id TEXT PRIMARY KEY,status TEXT NOT NULL,payload TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS outbox(id TEXT PRIMARY KEY,payload TEXT NOT NULL,published INTEGER NOT NULL DEFAULT 0);
 CREATE TABLE IF NOT EXISTS progress(id INTEGER PRIMARY KEY,seq INTEGER NOT NULL);
 INSERT OR IGNORE INTO progress VALUES(1,0);`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if err = s.initIndex(); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">ok = true
        return s, nil</span>
}

// Close 先关闭数据库,再解目录锁;调用者必须已停止worker与核心。
func (s *Store) Close() <span class="cov8" title="1">{
        if s.Views != nil </span><span class="cov8" title="1">{
                s.Views.Close()
        }</span>
        <span class="cov8" title="1">if s.Journal != nil </span><span class="cov8" title="1">{
                s.Journal.Close()
        }</span>
        <span class="cov8" title="1">if s.lock != nil </span><span class="cov8" title="1">{
                s.lock.Unlock()
        }</span>
}

// project 增量对象/outbox/水位同一事务;重放前缀不重置已发布任务。
func (s *Store) project(c Command, orders []Order, intents []Intent) error <span class="cov8" title="1">{
        tx, err := s.Views.Begin()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var seq int64
        if err = tx.QueryRow(`SELECT seq FROM progress WHERE id=1`).Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if c.Seq &lt;= seq </span><span class="cov8" title="1">{
                return nil
        }</span>
        <span class="cov8" title="1">if c.Seq != seq+1 </span><span class="cov0" title="0">{
                return fmt.Errorf("projection gap")
        }</span>
        <span class="cov8" title="1">for _, o := range orders </span><span class="cov8" title="1">{
                raw, _ := json.Marshal(o)
                if _, err = tx.Exec(`INSERT INTO orders VALUES(?,?,?) ON CONFLICT(id) DO UPDATE SET payload=excluded.payload`, o.ID, o.Seq, string(raw)); err != nil </span><span class="cov8" title="1">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">for _, i := range intents </span><span class="cov8" title="1">{
                raw, _ := json.Marshal(i)
                if _, err = tx.Exec(`INSERT INTO intents VALUES(?,?,?) ON CONFLICT(id) DO UPDATE SET status=excluded.status,payload=excluded.payload`, i.ID, i.Status, string(raw)); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if i.Status == "READY" </span><span class="cov8" title="1">{
                        if _, err = tx.Exec(`INSERT OR IGNORE INTO outbox(id,payload) VALUES(?,?)`, i.ID, string(raw)); err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
        }
        <span class="cov8" title="1">if _, err = tx.Exec(`UPDATE progress SET seq=? WHERE id=1`, c.Seq); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">return tx.Commit()</span>
}

// State 查询最多100项订单/任务,避免历史持续增长造成无限HTTP响应。
func (s *Store) State(ctx context.Context) (State, error) <span class="cov8" title="1">{
        state := State{Dataset: s.Domain.Dataset, Orders: []Order{}, Intents: []Intent{}}
        tx, err := s.Views.BeginTx(ctx, &amp;sql.TxOptions{ReadOnly: true})
        if err != nil </span><span class="cov0" title="0">{
                return state, err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        var seq int64
        if err = tx.QueryRowContext(ctx, `SELECT seq FROM progress WHERE id=1`).Scan(&amp;seq); err != nil </span><span class="cov0" title="0">{
                return state, err
        }</span>
        <span class="cov8" title="1">state.Seq = strconv.FormatInt(seq, 10)
        for _, kind := range []string{"orders", "intents"} </span><span class="cov8" title="1">{
                query := `SELECT payload FROM orders ORDER BY seq DESC LIMIT 100`
                if kind == "intents" </span><span class="cov8" title="1">{
                        query = `SELECT payload FROM intents ORDER BY rowid DESC LIMIT 100`
                }</span>
                <span class="cov8" title="1">rows, e := tx.QueryContext(ctx, query)
                if e != nil </span><span class="cov0" title="0">{
                        return state, e
                }</span>
                <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                        var raw string
                        if e = rows.Scan(&amp;raw); e != nil </span><span class="cov0" title="0">{
                                rows.Close()
                                return state, e
                        }</span>
                        <span class="cov8" title="1">if kind == "orders" </span><span class="cov8" title="1">{
                                var o Order
                                e = json.Unmarshal([]byte(raw), &amp;o)
                                state.Orders = append(state.Orders, o)
                        }</span> else<span class="cov8" title="1"> {
                                var i Intent
                                e = json.Unmarshal([]byte(raw), &amp;i)
                                state.Intents = append(state.Intents, i)
                        }</span>
                        <span class="cov8" title="1">if e != nil </span><span class="cov0" title="0">{
                                rows.Close()
                                return state, e
                        }</span>
                }
                <span class="cov8" title="1">e = rows.Err()
                rows.Close()
                if e != nil </span><span class="cov0" title="0">{
                        return state, e
                }</span>
        }
        <span class="cov8" title="1">return state, tx.Commit()</span>
}

// request 是外围队列消息,response缓冲1防止客户端取消堵塞单写者。
type request struct {
        command Command
        reply   chan response
}

// response 为一次原命令结果;容量1回包通道不因HTTP取消阻塞业务流水线。
type response struct {
        result Result
        err    error
}

// Runtime 接入锁只协调send/close;核心Engine自身完全无业务锁。
type Runtime struct {
        store          *Store
        input, durable chan request
        outputs        chan computed
        done           chan struct{}
        slots          chan struct{}
        mu             sync.RWMutex
        closed         bool
        failure        error
}

// computed 持有核心产生的独立增量,编码/SQL留给projector。
type computed struct {
        request request
        result  Result
        orders  []Order
        intents []Intent
}

// NewRuntime 重放所有日志恢复内存,补投影尾部;启动恢复不广播交易。
func NewRuntime(s *Store) (*Runtime, error) <span class="cov8" title="1">{
        e := NewEngine(s.Domain.Dataset)
        rows, err := s.Journal.Query(`SELECT seq,payload FROM commands ORDER BY seq`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">for rows.Next() </span><span class="cov8" title="1">{
                var seq int64
                var raw string
                var c Command
                if err = rows.Scan(&amp;seq, &amp;raw); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if err = json.Unmarshal([]byte(raw), &amp;c); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
                <span class="cov8" title="1">if seq != c.Seq || seq != e.seq+1 </span><span class="cov8" title="1">{
                        err = fmt.Errorf("corrupt journal sequence")
                        break</span>
                }
                <span class="cov8" title="1">if err = validateCommand(s.Domain, c); err != nil </span><span class="cov8" title="1">{
                        break</span>
                }
                <span class="cov8" title="1">_, orders, intents := e.Apply(c)
                if err = s.project(c, orders, intents); err != nil </span><span class="cov0" title="0">{
                        break</span>
                }
        }
        <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                err = rows.Err()
        }</span>
        <span class="cov8" title="1">rows.Close()
        if err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">var progress int64
        if err = s.Views.QueryRow(`SELECT seq FROM progress WHERE id=1`).Scan(&amp;progress); err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if progress != e.seq </span><span class="cov0" title="0">{
                return nil, fmt.Errorf("projection ahead of journal")
        }</span>
        <span class="cov8" title="1">r := &amp;Runtime{store: s, input: make(chan request, 1024), durable: make(chan request, 1024), outputs: make(chan computed, 1024), slots: make(chan struct{}, 2048), done: make(chan struct{})}
        go r.write(e.seq)
        go r.run(e)
        go r.project()
        return r, nil</span>
}

// Submit 非阻塞入队并等待本地投影成功;发送后取消不撤销已受理业务。
func (r *Runtime) Submit(ctx context.Context, c Command) (Result, error) <span class="cov8" title="1">{
        if err := validateCommand(r.store.Domain, c); err != nil </span><span class="cov0" title="0">{
                return Result{}, err
        }</span>
        <span class="cov8" title="1">r.mu.RLock()
        if r.closed || r.failure != nil </span><span class="cov0" title="0">{
                r.mu.RUnlock()
                return Result{}, fmt.Errorf("runtime unavailable")
        }</span>
        <span class="cov8" title="1">select </span>{
        case r.slots &lt;- struct{}{}:<span class="cov8" title="1"></span>
        default:<span class="cov0" title="0">
                r.mu.RUnlock()
                return Result{}, fmt.Errorf("overloaded")</span>
        }
        <span class="cov8" title="1">q := request{c, make(chan response, 1)}
        select </span>{
        case r.input &lt;- q:<span class="cov8" title="1"></span>
        default:<span class="cov0" title="0">
                &lt;-r.slots
                r.mu.RUnlock()
                return Result{}, fmt.Errorf("overloaded")</span>
        }
        <span class="cov8" title="1">r.mu.RUnlock()
        select </span>{
        case res := &lt;-q.reply:<span class="cov8" title="1">
                return res.result, res.err</span>
        case &lt;-ctx.Done():<span class="cov0" title="0">
                return Result{}, fmt.Errorf("result unknown: %w", ctx.Err())</span>
        }
}

// fail 永久封住本进程接入;已持久化未投影尾部交给下次重放。
func (r *Runtime) fail(err error) <span class="cov8" title="1">{
        r.mu.Lock()
        if r.failure == nil </span><span class="cov8" title="1">{
                r.failure = err
        }</span>
        <span class="cov8" title="1">r.mu.Unlock()</span>
}

// write 是外围唯一日志writer,最多64项同一FULL事务提交,成功才发送durable。
func (r *Runtime) write(seq int64) <span class="cov8" title="1">{
        defer close(r.durable)
        for first := range r.input </span><span class="cov8" title="1">{
                batch := []request{first}
        gather:
                for len(batch) &lt; 64 </span><span class="cov8" title="1">{
                        select </span>{
                        case q, ok := &lt;-r.input:<span class="cov8" title="1">
                                if !ok </span><span class="cov0" title="0">{
                                        break gather</span>
                                }
                                <span class="cov8" title="1">batch = append(batch, q)</span>
                        default:<span class="cov8" title="1">
                                break gather</span>
                        }
                }
                <span class="cov8" title="1">r.mu.RLock()
                err := r.failure
                r.mu.RUnlock()
                if err == nil </span><span class="cov8" title="1">{
                        tx, e := r.store.Journal.Begin()
                        err = e
                        if err == nil </span><span class="cov8" title="1">{
                                for i := range batch </span><span class="cov8" title="1">{
                                        if seq == int64(^uint64(0)&gt;&gt;1) </span><span class="cov0" title="0">{
                                                err = fmt.Errorf("sequence exhausted")
                                                break</span>
                                        }
                                        <span class="cov8" title="1">seq++
                                        batch[i].command.Seq = seq
                                        raw, e := json.Marshal(batch[i].command)
                                        if e != nil </span><span class="cov0" title="0">{
                                                err = e
                                                break</span>
                                        }
                                        <span class="cov8" title="1">if _, err = tx.Exec(`INSERT INTO commands VALUES(?,?)`, seq, string(raw)); err != nil </span><span class="cov0" title="0">{
                                                break</span>
                                        }
                                }
                                <span class="cov8" title="1">if err == nil </span><span class="cov8" title="1">{
                                        err = tx.Commit()
                                }</span> else<span class="cov0" title="0"> {
                                        tx.Rollback()
                                }</span>
                        }
                }
                <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                        r.fail(err)
                        for _, q := range batch </span><span class="cov0" title="0">{
                                q.reply &lt;- response{err: err}
                                &lt;-r.slots
                        }</span>
                        <span class="cov0" title="0">continue</span>
                }
                <span class="cov8" title="1">for _, q := range batch </span><span class="cov8" title="1">{
                        r.durable &lt;- q
                }</span>
        }
}

// run 仅调用确定性Apply和有界结果发送;此goroutine不访问SQL/JSON/RPC/时钟。
func (r *Runtime) run(e *Engine) <span class="cov8" title="1">{
        defer close(r.outputs)
        for q := range r.durable </span><span class="cov8" title="1">{
                result, orders, intents := e.Apply(q.command)
                r.outputs &lt;- computed{q, result, orders, intents}
        }</span>
}

// project 持久增量/outbox成功后回包并释放inflight;新mode没有模拟mode回包早于投影语义。
func (r *Runtime) project() <span class="cov8" title="1">{
        defer close(r.done)
        for out := range r.outputs </span><span class="cov8" title="1">{
                r.mu.RLock()
                err := r.failure
                r.mu.RUnlock()
                if err == nil </span><span class="cov8" title="1">{
                        err = r.store.project(out.request.command, out.orders, out.intents)
                }</span>
                <span class="cov8" title="1">if err != nil </span><span class="cov8" title="1">{
                        r.fail(err)
                }</span>
                <span class="cov8" title="1">out.request.reply &lt;- response{out.result, err}
                &lt;-r.slots</span>
        }
}

// Healthy 与Close使用同一外围生命周期锁,不读取Engine可变状态。
func (r *Runtime) Healthy() bool <span class="cov8" title="1">{
        r.mu.RLock()
        defer r.mu.RUnlock()
        return !r.closed &amp;&amp; r.failure == nil
}</span>

// Close 拒绝新命令并排空已受理队列,重复调用安全;调用者最后再Close Store。
func (r *Runtime) Close() <span class="cov8" title="1">{
        r.mu.Lock()
        if !r.closed </span><span class="cov8" title="1">{
                r.closed = true
                close(r.input)
        }</span>
        <span class="cov8" title="1">r.mu.Unlock()
        &lt;-r.done</span>
}

// validateCommand 外围校验持久输入的域/摘要/签名/预算;历史订单不使用当前时钟判过期。
// 验签不会进入单写者run,未知命令拒绝写日志,防止篡改被无声推进水位。
func validateCommand(d Domain, c Command) error <span class="cov8" title="1">{
        switch c.Kind </span>{
        case "PLACE":<span class="cov8" title="1">
                id, err := ValidateOrder(d, c.Order, 0)
                if err != nil </span><span class="cov8" title="1">{
                        return err
                }</span>
                <span class="cov8" title="1">if id != c.OrderID </span><span class="cov0" title="0">{
                        return fmt.Errorf("order digest mismatch")
                }</span>
        case "CONFIRMED", "FAILED":<span class="cov0" title="0">
                if len(c.IntentID) != 66 || !strings.HasPrefix(c.IntentID, "0x"+d.Dataset) || len(c.TxHash) != 66 || common.HexToHash(c.TxHash) == (common.Hash{}) </span><span class="cov0" title="0">{
                        return fmt.Errorf("invalid settlement confirmation")
                }</span>
        case "INVALIDATE":<span class="cov0" title="0">
                if len(c.OrderID) != 66 || common.HexToHash(c.OrderID) == (common.Hash{}) </span><span class="cov0" title="0">{
                        return fmt.Errorf("invalid invalidation")
                }</span>
        default:<span class="cov8" title="1">
                return fmt.Errorf("unknown chain command %s", c.Kind)</span>
        }
        <span class="cov8" title="1">return nil</span>
}
</pre>
    
    <pre class="file" id="file20" style="display: none">package chaintrade

import (
        "context"
        "database/sql"
        "encoding/json"
        "fmt"
        "path/filepath"
        "strings"
        "time"

        _ "github.com/jackc/pgx/v5/stdlib"
)

// Task 保存不能由投影重建的rawTx/nonce;广播之前必须成功持久化。
type Task struct {
        Intent      Intent `json:"intent"`
        Raw         string `json:"raw,omitempty"`
        Hash        string `json:"tx_hash,omitempty"`
        Nonce       string `json:"nonce,omitempty"`
        Status      string `json:"status"`
        Block       string `json:"block,omitempty"`
        BlockNumber uint64 `json:"block_number"`
        CreatedAt   int64  `json:"created_at"` // Unix 秒;旧版本没有记录时间,保持 0,不能伪造历史。
        UpdatedAt   int64  `json:"updated_at"`
        Version     int64  `json:"version"` // SQL CAS 版本;不同于命令日志序号。
        Reason      string `json:"reason"`
}

// Tasks 在生产连接PG,本地显式使用独立SQLite,两者都使用稳定唯一任务ID。
type Tasks struct {
        DB    *sql.DB
        pg    bool
        owner *sql.Conn // 专用会话锁,不随业务连接池自动重连而失去互斥。
}

// OpenTasks 初始化权威外部任务表,DSN变更不会迁移已发送任务。
func OpenTasks(dir, dsn string) (*Tasks, error) <span class="cov8" title="1">{
        t := &amp;Tasks{}
        var err error
        if dsn != "" </span><span class="cov0" title="0">{
                t.pg = true
                t.DB, err = sql.Open("pgx", dsn)
                if err == nil </span><span class="cov0" title="0">{
                        t.DB.SetMaxOpenConns(1)
                        err = t.DB.Ping()
                }</span>
        } else<span class="cov8" title="1"> {
                t.DB, err = sqlite(filepath.Join(dir, "chain-tasks.db"))
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov0" title="0">{
                if t.DB != nil </span><span class="cov0" title="0">{
                        t.DB.Close()
                }</span>
                <span class="cov0" title="0">return nil, err</span>
        }
        <span class="cov8" title="1">_, err = t.DB.Exec(`CREATE TABLE IF NOT EXISTS chain_tasks(id TEXT PRIMARY KEY,status TEXT NOT NULL,payload TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS chain_metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);`)
        if err != nil </span><span class="cov0" title="0">{
                t.DB.Close()
                return nil, err
        }</span>
        <span class="cov8" title="1">if t.pg </span><span class="cov0" title="0">{
                t.owner, err = t.DB.Conn(context.Background())
                if err != nil </span><span class="cov0" title="0">{
                        t.DB.Close()
                        return nil, err
                }</span>
                <span class="cov0" title="0">t.DB.SetMaxOpenConns(2)
                var locked bool
                if err = t.owner.QueryRowContext(context.Background(), `SELECT pg_try_advisory_lock(574302149)`).Scan(&amp;locked); err != nil || !locked </span><span class="cov0" title="0">{
                        t.owner.Close()
                        t.DB.Close()
                        return nil, fmt.Errorf("relayer SQL already owned: %v", err)
                }</span>
        }
        <span class="cov8" title="1">if err = t.migrate(); err != nil </span><span class="cov8" title="1">{
                if t.owner != nil </span><span class="cov0" title="0">{
                        t.owner.Close()
                }</span>
                <span class="cov8" title="1">t.DB.Close()
                return nil, err</span>
        }
        <span class="cov8" title="1">return t, nil</span>
}

// query 在固定SQL模板把?转换PG参数;不是用户SQL字符串替换。
func (t *Tasks) query(q string) string <span class="cov8" title="1">{
        if !t.pg </span><span class="cov8" title="1">{
                return q
        }</span>
        <span class="cov0" title="0">i := 0
        return qWithParams(q, &amp;i)</span>
}

// qWithParams 按模板占位顺序编号,仅内部固定查询调用。
func qWithParams(q string, i *int) string <span class="cov0" title="0">{
        parts := strings.Split(q, "?")
        out := parts[0]
        for _, p := range parts[1:] </span><span class="cov0" title="0">{
                *i++
                out += fmt.Sprintf("$%d", *i) + p
        }</span>
        <span class="cov0" title="0">return out</span>
}

// PutIntent 同ID重复Kafka消费不覆盖已有签名交易状态。
func (t *Tasks) PutIntent(ctx context.Context, i Intent) error <span class="cov8" title="1">{
        now := time.Now().Unix()
        raw, _ := json.Marshal(Task{Intent: i, Status: "READY", CreatedAt: now, UpdatedAt: now})
        _, err := t.DB.ExecContext(ctx, t.query(`INSERT INTO chain_tasks(id,status,payload) VALUES(?,?,?) ON CONFLICT(id) DO NOTHING`), i.ID, "READY", string(raw))
        return err
}</span>

// Bind 网络/发送者绑定外部权威库,拒绝多个域复用nonce任务。
func (t *Tasks) Bind(ctx context.Context, d Domain) error <span class="cov8" title="1">{
        raw, _ := json.Marshal(d)
        var old string
        err := t.DB.QueryRowContext(ctx, t.query(`SELECT value FROM chain_metadata WHERE key=?`), "domain").Scan(&amp;old)
        if err == sql.ErrNoRows </span><span class="cov8" title="1">{
                _, err = t.DB.ExecContext(ctx, t.query(`INSERT INTO chain_metadata VALUES(?,?)`), "domain", string(raw))
                return err
        }</span>
        <span class="cov0" title="0">if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if old != string(raw) </span><span class="cov0" title="0">{
                return fmt.Errorf("task domain mismatch")
        }</span>
        <span class="cov0" title="0">return nil</span>
}

// Save 更新任务状态与原交易,不允许只记录txHash而丢签名payload。
func (t *Tasks) Save(ctx context.Context, task *Task) error <span class="cov8" title="1">{
        // 先读取同版本旧值,保护不可替换的已签交易与终态;UPDATE 的 CAS 防止读后竞争。
        var previous string
        if err := t.DB.QueryRowContext(ctx, t.query(`SELECT payload FROM chain_tasks WHERE id=? AND version=?`), task.Intent.ID, task.Version).Scan(&amp;previous); err != nil </span><span class="cov8" title="1">{
                return fmt.Errorf("task version conflict: %w", err)
        }</span>
        <span class="cov8" title="1">var old Task
        if err := json.Unmarshal([]byte(previous), &amp;old); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if old.Status == "CONFIRMED" || old.Status == "FAILED" </span><span class="cov8" title="1">{
                return fmt.Errorf("terminal task is immutable")
        }</span>
        <span class="cov8" title="1">allowed := map[string]bool{"READY": true, "SIGNED": true, "BROADCAST": true, "INCLUDED": true, "CONFIRMED": true, "FAILED": true}
        if !allowed[task.Status] || (task.Status == "READY" &amp;&amp; old.Status != "READY") || (task.Status == "SIGNED" &amp;&amp; old.Status != "READY" &amp;&amp; old.Status != "SIGNED") </span><span class="cov0" title="0">{
                return fmt.Errorf("invalid task transition")
        }</span>
        <span class="cov8" title="1">if old.Raw != "" &amp;&amp; (task.Raw != old.Raw || task.Hash != old.Hash || task.Nonce != old.Nonce) </span><span class="cov8" title="1">{
                return fmt.Errorf("signed transaction is immutable")
        }</span>
        // Intent 也不能被更换;raw 校验在广播前继续验证 sender/domain/calldata。
        <span class="cov8" title="1">if a, b := mustJSON(old.Intent), mustJSON(task.Intent); a != b </span><span class="cov0" title="0">{
                return fmt.Errorf("task intent is immutable")
        }</span>
        <span class="cov8" title="1">next := *task
        next.Version++
        next.CreatedAt = old.CreatedAt
        next.UpdatedAt = time.Now().Unix()
        raw, err := json.Marshal(next)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">result, err := t.DB.ExecContext(ctx, t.query(`UPDATE chain_tasks SET status=?,payload=?,version=? WHERE id=? AND version=?`), next.Status, string(raw), next.Version, next.Intent.ID, task.Version)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">n, err := result.RowsAffected()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if n != 1 </span><span class="cov0" title="0">{
                return fmt.Errorf("task version conflict")
        }</span>
        <span class="cov8" title="1">*task = next // 只有成功提交才能更新调用者的期望版本。
        return nil</span>
}

// mustJSON 仅对内部固定结构编码;没有不可编码字段。
func mustJSON(v interface{}) string <span class="cov8" title="1">{ raw, _ := json.Marshal(v); return string(raw) }</span>

// migrate 在事务中升级旧任务表;raw/nonce/payload 不变,未知版本拒绝启动。
func (t *Tasks) migrate() error <span class="cov8" title="1">{
        tx, err := t.DB.Begin()
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer tx.Rollback()
        if _, err = tx.Exec(`INSERT INTO chain_metadata(key,value) VALUES('task_schema','1') ON CONFLICT(key) DO NOTHING`); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">var version string
        if err = tx.QueryRow(`SELECT value FROM chain_metadata WHERE key='task_schema'`).Scan(&amp;version); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">if version == "1" </span><span class="cov8" title="1">{
                if _, err = tx.Exec(`ALTER TABLE chain_tasks ADD COLUMN version BIGINT NOT NULL DEFAULT 0`); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">if _, err = tx.Exec(`UPDATE chain_metadata SET value='2' WHERE key='task_schema'`); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
        } else<span class="cov8" title="1"> if version != "2" </span><span class="cov8" title="1">{
                return fmt.Errorf("unsupported task schema %s", version)
        }</span>
        <span class="cov8" title="1">if _, err = tx.Exec(`CREATE INDEX IF NOT EXISTS chain_tasks_pending ON chain_tasks(status,id)`); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">return tx.Commit()</span>
}

// Pending 仅取有限待处理任务,顺序按stable bytes32序号;首版单sender负责nonce。
func (t *Tasks) Pending(ctx context.Context) ([]Task, error) <span class="cov8" title="1">{
        rows, err := t.DB.QueryContext(ctx, `SELECT payload FROM chain_tasks WHERE status NOT IN ('CONFIRMED','FAILED') ORDER BY id LIMIT 100`)
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">defer rows.Close()
        out := []Task{}
        for rows.Next() </span><span class="cov8" title="1">{
                var raw string
                if err = rows.Scan(&amp;raw); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">var task Task
                if err = json.Unmarshal([]byte(raw), &amp;task); err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">out = append(out, task)</span>
        }
        <span class="cov8" title="1">return out, rows.Err()</span>
}

// CheckOwner 专用锁连接断开后停发送,不自动在新连接重拿锁冒充原所有者。
func (t *Tasks) CheckOwner(ctx context.Context) error <span class="cov0" title="0">{
        if t.owner == nil </span><span class="cov0" title="0">{
                return nil
        }</span>
        <span class="cov0" title="0">var locked bool
        err := t.owner.QueryRowContext(ctx, `SELECT EXISTS(SELECT 1 FROM pg_locks WHERE pid=pg_backend_pid() AND locktype='advisory' AND objid=574302149 AND granted)`).Scan(&amp;locked)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if !locked </span><span class="cov0" title="0">{
                return fmt.Errorf("relayer owner lost")
        }</span>
        <span class="cov0" title="0">return nil</span>
}

// Close 先释放固定锁连接,再关池;数据库/链状态保留供恢复。
func (t *Tasks) Close() <span class="cov8" title="1">{
        if t.owner != nil </span><span class="cov0" title="0">{
                t.owner.Close()
        }</span>
        <span class="cov8" title="1">t.DB.Close()</span>
}
</pre>
    
    <pre class="file" id="file21" style="display: none">// Package chaintrade 实现独立链下撮合/链上结算模式,不共享模拟账户与CREDIT余额。
package chaintrade

import (
        "fmt"
        "math/big"
        "regexp"
        "strconv"
        "strings"

        "github.com/ethereum/go-ethereum/common"
        "github.com/ethereum/go-ethereum/crypto"
        "github.com/ethereum/go-ethereum/signer/core/apitypes"
)

// Domain 固定签单链/合约/资产身份,启动后不可热改;新网络使用新数据目录。
type Domain struct {
        ChainID       string `json:"chain_id"`
        Contract      string `json:"contract"`
        Base          string `json:"base"`
        Quote         string `json:"quote"`
        Relayer       string `json:"relayer"`
        Confirmations uint64 `json:"confirmations"`
        Dataset       string `json:"dataset_id"`
}

// SignedOrder 数值是整数文本:price以0.01USDT为tick,quantity以0.0001WETH为lot。
// 上限price=1e8tick、quantity=1e10lot,投影整数保持JS安全范围,乘积用big.Int/uint256。
// nonce是订单随机标识,deadline为用户签署的链时间上限;signature只在外围验证。
type SignedOrder struct {
        Maker     string `json:"maker"`
        Side      uint8  `json:"side"`
        Price     string `json:"price"`
        Quantity  string `json:"quantity"`
        Nonce     string `json:"nonce"`
        Deadline  string `json:"deadline"`
        Signature string `json:"signature"`
}

// Order 的数量守恒含Pending;核心本地预留不等于冻结钱包代币。
type Order struct {
        ID string `json:"id"`
        SignedOrder
        Seq       int64  `json:"seq"`
        Remaining int64  `json:"remaining"`
        Pending   int64  `json:"pending"`
        Filled    int64  `json:"filled"`
        Canceled  int64  `json:"canceled"`
        Status    string `json:"status"`
}

// Intent 是确定性结算任务,不含发送nonce;任务状态存于外围权威SQL。
type Intent struct {
        ID       string `json:"id"`
        Maker    Order  `json:"maker"`
        Taker    Order  `json:"taker"`
        Quantity int64  `json:"quantity"`
        Status   string `json:"status"`
        TxHash   string `json:"tx_hash,omitempty"`
        Reason   string `json:"reason,omitempty"`
}

// Command 已由外围固定授权/链事实;核心不查看时间、签名、数据库或RPC。
type Command struct {
        Seq      int64       `json:"seq"`
        Kind     string      `json:"kind"`
        OrderID  string      `json:"order_id,omitempty"`
        Order    SignedOrder `json:"order,omitempty"`
        IntentID string      `json:"intent_id,omitempty"`
        TxHash   string      `json:"tx_hash,omitempty"`
        Reason   string      `json:"reason,omitempty"`
}

// State 是脱离核心的公开订单/任务快照,金额单位与seq字符串在API层解释。
type State struct {
        Dataset string   `json:"dataset_id"`
        Seq     string   `json:"applied_seq"`
        Orders  []Order  `json:"orders"`
        Intents []Intent `json:"intents"`
}

// Result 是本次处理结果;重复订单返回原ID而不再次预留。
type Result struct {
        Seq     string `json:"processed_seq"`
        OrderID string `json:"order_id,omitempty"`
        Code    string `json:"code,omitempty"`
}

var integer = regexp.MustCompile(`^(0|[1-9][0-9]*)$`)

// uintText 限制原始长度/整数格式,避免大整数解析DoS或uint256溢出。
func uintText(s string) (*big.Int, bool) <span class="cov8" title="1">{
        if len(s) &gt; 78 || !integer.MatchString(s) </span><span class="cov0" title="0">{
                return nil, false
        }</span>
        <span class="cov8" title="1">n, ok := new(big.Int).SetString(s, 10)
        return n, ok &amp;&amp; n.BitLen() &lt;= 256</span>
}

// TypedData 与Settlement.ORDER_TYPEHASH字段顺序保持一致,EIP712域防跨链/跨合约重放。
func TypedData(d Domain, o SignedOrder) apitypes.TypedData <span class="cov8" title="1">{
        return apitypes.TypedData{Types: apitypes.Types{
                "EIP712Domain": {{Name: "name", Type: "string"}, {Name: "version", Type: "string"}, {Name: "chainId", Type: "uint256"}, {Name: "verifyingContract", Type: "address"}},
                "Order":        {{Name: "maker", Type: "address"}, {Name: "side", Type: "uint8"}, {Name: "price", Type: "uint256"}, {Name: "quantity", Type: "uint256"}, {Name: "nonce", Type: "uint256"}, {Name: "deadline", Type: "uint256"}},
        }, PrimaryType: "Order", Domain: apitypes.TypedDataDomain{Name: "GoExchange", Version: "1", VerifyingContract: d.Contract},
                Message: apitypes.TypedDataMessage{"maker": o.Maker, "side": strconv.Itoa(int(o.Side)), "price": o.Price, "quantity": o.Quantity, "nonce": o.Nonce, "deadline": o.Deadline}}
}</span>

// OrderHash 构造域hash显式使用chainId;不依赖缺失ChainId的默认值。
func OrderHash(d Domain, o SignedOrder) (common.Hash, error) <span class="cov8" title="1">{
        data := TypedData(d, o)
        chain, ok := uintText(d.ChainID)
        if !ok || chain.Sign() == 0 </span><span class="cov0" title="0">{
                return common.Hash{}, fmt.Errorf("invalid chain id")
        }</span>
        <span class="cov8" title="1">domainHash, err := data.HashStruct("EIP712Domain", apitypes.TypedDataMessage{"name": "GoExchange", "version": "1", "chainId": chain.String(), "verifyingContract": d.Contract})
        if err != nil </span><span class="cov0" title="0">{
                return common.Hash{}, err
        }</span>
        <span class="cov8" title="1">orderHash, err := data.HashStruct("Order", data.Message)
        if err != nil </span><span class="cov0" title="0">{
                return common.Hash{}, err
        }</span>
        <span class="cov8" title="1">return crypto.Keccak256Hash([]byte{0x19, 0x01}, domainHash, orderHash), nil</span>
}

// ValidateOrder 在HTTP、日志恢复和Kafka外围运行,校验输入/EOA签名/截止时刻后返回可信摘要。
func ValidateOrder(d Domain, o SignedOrder, now int64) (string, error) <span class="cov8" title="1">{
        if !common.IsHexAddress(o.Maker) || common.HexToAddress(o.Maker) == (common.Address{}) || o.Side &gt; 1 </span><span class="cov8" title="1">{
                return "", fmt.Errorf("invalid maker/side")
        }</span>
        <span class="cov8" title="1">for _, s := range []string{o.Price, o.Quantity, o.Nonce, o.Deadline} </span><span class="cov8" title="1">{
                if _, ok := uintText(s); !ok </span><span class="cov0" title="0">{
                        return "", fmt.Errorf("invalid integer")
                }</span>
        }
        <span class="cov8" title="1">p, _ := strconv.ParseInt(o.Price, 10, 64)
        q, _ := strconv.ParseInt(o.Quantity, 10, 64)
        end, err := strconv.ParseInt(o.Deadline, 10, 64)
        if p &lt; 1 || p &gt; 100000000 || q &lt; 1 || q &gt; 10000000000 || err != nil || end &lt;= 0 || (now &gt; 0 &amp;&amp; (end &lt;= now || end &gt; now+7*86400)) </span><span class="cov0" title="0">{
                return "", fmt.Errorf("price/quantity/deadline outside budget")
        }</span>
        <span class="cov8" title="1">hash, err := OrderHash(d, o)
        if err != nil </span><span class="cov0" title="0">{
                return "", err
        }</span>
        <span class="cov8" title="1">sig := common.FromHex(o.Signature)
        if len(sig) != 65 || (sig[64] != 27 &amp;&amp; sig[64] != 28) </span><span class="cov0" title="0">{
                return "", fmt.Errorf("signature requires 65 bytes and EVM v=27/28")
        }</span>
        <span class="cov8" title="1">if sig[64] &gt;= 27 </span><span class="cov8" title="1">{
                sig[64] -= 27
        }</span>
        <span class="cov8" title="1">if sig[64] &gt; 1 || !crypto.ValidateSignatureValues(sig[64], new(big.Int).SetBytes(sig[:32]), new(big.Int).SetBytes(sig[32:64]), true) </span><span class="cov0" title="0">{
                return "", fmt.Errorf("noncanonical signature")
        }</span>
        <span class="cov8" title="1">pub, err := crypto.SigToPub(hash.Bytes(), sig)
        if err != nil || !strings.EqualFold(crypto.PubkeyToAddress(*pub).Hex(), o.Maker) </span><span class="cov8" title="1">{
                return "", fmt.Errorf("signature mismatch")
        }</span>
        <span class="cov8" title="1">return hash.Hex(), nil</span>
}

// ValidateIntent 在Kafka/恢复外围校验签名和数量预算;坏消息停消费并等待人工核对。
func ValidateIntent(d Domain, i Intent) error <span class="cov8" title="1">{
        if len(i.ID) != 66 || !strings.HasPrefix(i.ID, "0x"+d.Dataset) || common.HexToHash(i.ID) == (common.Hash{}) || i.Quantity &lt;= 0 </span><span class="cov0" title="0">{
                return fmt.Errorf("invalid intent identity/quantity")
        }</span>
        <span class="cov8" title="1">for _, o := range []Order{i.Maker, i.Taker} </span><span class="cov8" title="1">{
                id, err := ValidateOrder(d, o.SignedOrder, 0)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov8" title="1">q, _ := strconv.ParseInt(o.Quantity, 10, 64)
                if id != o.ID || i.Quantity &gt; q </span><span class="cov0" title="0">{
                        return fmt.Errorf("invalid intent order")
                }</span>
        }
        <span class="cov8" title="1">if i.Maker.Side == i.Taker.Side || strings.EqualFold(i.Maker.Maker, i.Taker.Maker) </span><span class="cov0" title="0">{
                return fmt.Errorf("invalid intent counterparties")
        }</span>
        <span class="cov8" title="1">buy, sell := i.Maker, i.Taker
        if buy.Side == 1 </span><span class="cov8" title="1">{
                buy, sell = sell, buy
        }</span>
        <span class="cov8" title="1">bp, _ := strconv.ParseInt(buy.Price, 10, 64)
        sp, _ := strconv.ParseInt(sell.Price, 10, 64)
        if bp &lt; sp </span><span class="cov0" title="0">{
                return fmt.Errorf("noncrossing intent")
        }</span>
        <span class="cov8" title="1">return nil</span>
}
</pre>
    
    <pre class="file" id="file22" style="display: none">// exchangectl 是停服务后使用的离线工具;与服务共享目录锁,不能同时写数据。
package main

import (
        "context"
        "encoding/json"
        "flag"
        "fmt"
        "os"
        "web3exchange/backend"
)

// execute 使用独立 FlagSet 明确每项操作的参数,未知命令返回错误,不悄悄启动 HTTP。
// init-admin 密码只从环境读取,不放命令行参数/历史;无任意账号提权或默认密码。
// check 可补落后投影,backup/restore 还做全历史对账,不是在线只读运维;预算临时磁盘。
// restore 的目标拒绝覆盖;rebuild 单独打开权威库,避免普通 OpenStore 先因坏 views 退出。
func execute(args []string) (any, error) <span class="cov8" title="1">{
        if len(args) == 0 </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("usage: exchangectl check|backup|restore|rebuild-views|init-admin [--data DIR] [--backup DIR] [--email EMAIL]")
        }</span>
        <span class="cov8" title="1">command := args[0]
        fs := flag.NewFlagSet(command, flag.ContinueOnError)
        data := fs.String("data", "data", "停机数据目录;restore 时必须不存在")
        backup := fs.String("backup", "", "备份目录;backup 时必须不存在")
        email := fs.String("email", "", "管理员邮箱;仅 init-admin")
        if err := fs.Parse(args[1:]); err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">if fs.NArg() != 0 </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("unexpected arguments")
        }</span>
        <span class="cov8" title="1">if command == "rebuild-views" </span><span class="cov8" title="1">{
                return backend.RebuildViews(*data)
        }</span>
        <span class="cov8" title="1">if command == "restore" </span><span class="cov8" title="1">{
                if *backup == "" </span><span class="cov8" title="1">{
                        return nil, fmt.Errorf("--backup is required")
                }</span>
                <span class="cov8" title="1">return backend.RestoreBackup(*backup, *data)</span>
        }
        <span class="cov8" title="1">if command != "check" &amp;&amp; command != "backup" &amp;&amp; command != "init-admin" </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("unknown command: %s", command)
        }</span>
        <span class="cov8" title="1">var s *backend.Store
        var err error
        if command == "init-admin" </span><span class="cov8" title="1">{
                s, err = backend.OpenStore(*data)
        }</span> else<span class="cov8" title="1"> {
                s, err = backend.OpenExistingStore(*data)
        }</span>
        <span class="cov8" title="1">if err != nil </span><span class="cov8" title="1">{
                return nil, err
        }</span>
        <span class="cov8" title="1">defer s.Close()
        switch command </span>{
        case "check":<span class="cov8" title="1">
                return backend.InspectStore(s)</span>
        case "backup":<span class="cov8" title="1">
                if *backup == "" </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("--backup is required")
                }</span>
                <span class="cov8" title="1">return backend.BackupStore(s, *data, *backup)</span>
        default:<span class="cov8" title="1">
                if *email == "" </span><span class="cov0" title="0">{
                        return nil, fmt.Errorf("--email is required")
                }</span>
                <span class="cov8" title="1">user, err := s.BootstrapAdmin(context.Background(), *email, os.Getenv("EXCHANGE_ADMIN_PASSWORD"))
                if err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">r, err := backend.NewRuntime(s)
                if err != nil </span><span class="cov0" title="0">{
                        return nil, err
                }</span>
                <span class="cov8" title="1">server := backend.NewServer(s, r, backend.Config{})
                fundErr := server.EnsureFunding(context.Background(), user.ID)
                closeErr := r.Close(context.Background())
                if fundErr != nil </span><span class="cov0" title="0">{
                        return nil, fundErr
                }</span>
                <span class="cov8" title="1">if closeErr != nil </span><span class="cov0" title="0">{
                        return nil, closeErr
                }</span>
                <span class="cov8" title="1">return user, nil</span>
        }
}

// main 输出机器可读 JSON,失败退出非零,便于升级/备份脚本校验。
func main() <span class="cov0" title="0">{
        result, err := execute(os.Args[1:])
        if err != nil </span><span class="cov0" title="0">{
                fmt.Fprintln(os.Stderr, err)
                os.Exit(1)
        }</span>
        <span class="cov0" title="0">encoder := json.NewEncoder(os.Stdout)
        encoder.SetIndent("", "  ")
        if err = encoder.Encode(result); err != nil </span><span class="cov0" title="0">{
                fmt.Fprintln(os.Stderr, err)
                os.Exit(1)
        }</span>
}
</pre>
    
    <pre class="file" id="file23" style="display: none">// loadcheck 是开放到达率实验发生器,仅连接本机独立测试服务;不启动/重置业务数据。
// 固定 128 工作者、最多 256 客户端积压,记录计划时间至完成的延迟及全部错误/丢弃。
package main

import (
        "bytes"
        "encoding/json"
        "flag"
        "fmt"
        "io"
        "math"
        "net"
        "net/http"
        "net/url"
        "os"
        "sort"
        "strconv"
        "strings"
        "sync"
        "time"
)

// job 保存计划到达时刻,排队时间计入延迟,不通过只测网络时间低估拥塞。
type job struct {
        index   int64
        planned time.Time
}

// sample 对成功/拒绝/超时一视同仁;网络失败 status=0,不能当作业务未受理。
// latency 的浮点仅用于时间统计,绝不计算金额;客户端丢弃另统计,无完成延迟样本。
type sample struct {
        status  int
        latency float64
        seq     int64
}

// runReport 每档含计划、客户端丢弃、全部状态、百分位和最后投影赶上时间。
type runReport struct {
        Rate        int                `json:"planned_rate"`
        Planned     int                `json:"planned_requests"`
        Elapsed     float64            `json:"elapsed_seconds"`
        Dropped     int                `json:"client_dropped"`
        Status      map[string]int     `json:"status_counts"`
        SuccessRate float64            `json:"success_per_second"`
        P50         float64            `json:"p50_ms"`
        P95         float64            `json:"p95_ms"`
        P99         float64            `json:"p99_ms"`
        Catchup     float64            `json:"projection_catchup_seconds"`
        Before      map[string]float64 `json:"metrics_before"`
        After       map[string]float64 `json:"metrics_after"`
}

// loopbackURL 拒绝非本机目标,凭证来自独立实验环境,禁止对外发送。
func loopbackURL(raw string) error <span class="cov8" title="1">{
        u, err := url.Parse(raw)
        if err != nil || u.Scheme != "http" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Path != "" </span><span class="cov8" title="1">{
                return fmt.Errorf("expected plain loopback HTTP URL")
        }</span>
        <span class="cov8" title="1">ip := net.ParseIP(u.Hostname())
        if ip == nil || !ip.IsLoopback() </span><span class="cov8" title="1">{
                return fmt.Errorf("target must be loopback")
        }</span>
        <span class="cov8" title="1">return nil</span>
}

// readMetrics 解析固定无标签文本指标;最大读取 1MiB,关闭响应防 FD/连接泄漏。
func readMetrics(client *http.Client, base string) (map[string]float64, error) <span class="cov8" title="1">{
        resp, err := client.Get(base + "/metrics")
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">defer resp.Body.Close()
        if resp.StatusCode != 200 </span><span class="cov8" title="1">{
                return nil, fmt.Errorf("metrics status %d", resp.StatusCode)
        }</span>
        <span class="cov8" title="1">raw, err := io.ReadAll(io.LimitReader(resp.Body, 1&lt;&lt;20))
        if err != nil </span><span class="cov0" title="0">{
                return nil, err
        }</span>
        <span class="cov8" title="1">out := map[string]float64{}
        for _, line := range strings.Split(string(raw), "\n") </span><span class="cov8" title="1">{
                parts := strings.Fields(line)
                if len(parts) != 2 || strings.HasPrefix(line, "#") || strings.Contains(parts[0], "{") </span><span class="cov8" title="1">{
                        continue</span>
                }
                <span class="cov8" title="1">value, err := strconv.ParseFloat(parts[1], 64)
                if err == nil </span><span class="cov8" title="1">{
                        out[parts[0]] = value
                }</span>
        }
        <span class="cov8" title="1">return out, nil</span>
}

// percentile 为 nearest-rank,调用者先排序全部延迟,不只统计 2xx。
func percentile(sorted []float64, p float64) float64 <span class="cov8" title="1">{
        if len(sorted) == 0 </span><span class="cov8" title="1">{
                return 0
        }</span>
        <span class="cov8" title="1">return sorted[max(0, int(math.Ceil(float64(len(sorted))*p))-1)]</span>
}

// execute 以有界 channel 连接计划发送器和固定 HTTP 工作者,不创建每请求 goroutine。
func execute() error <span class="cov0" title="0">{
        base := flag.String("url", "", "本机实验服务")
        diagnostic := flag.String("diagnostic", "", "本机诊断 URL")
        ratesRaw := flag.String("rates", "100,500,1000", "计划请求/秒列表")
        seconds := flag.Float64("seconds", 5, "每档时间,1..60秒")
        output := flag.String("output", "", "JSON 实验结果路径")
        flag.Parse()
        if err := loopbackURL(*base); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if err := loopbackURL(*diagnostic); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if *seconds &lt; 1 || *seconds &gt; 60 || *output == "" </span><span class="cov0" title="0">{
                return fmt.Errorf("invalid duration/output")
        }</span>
        <span class="cov0" title="0">rates := []int{}
        for _, raw := range strings.Split(*ratesRaw, ",") </span><span class="cov0" title="0">{
                n, err := strconv.Atoi(raw)
                if err != nil || n &lt; 1 || n &gt; 20000 </span><span class="cov0" title="0">{
                        return fmt.Errorf("invalid rate")
                }</span>
                <span class="cov0" title="0">rates = append(rates, n)</span>
        }
        <span class="cov0" title="0">cookie, csrf, dataset := os.Getenv("EXCHANGE_LOAD_COOKIE"), os.Getenv("EXCHANGE_LOAD_CSRF"), os.Getenv("EXCHANGE_LOAD_DATASET")
        if cookie == "" || csrf == "" || dataset == "" </span><span class="cov0" title="0">{
                return fmt.Errorf("missing isolated load credentials")
        }</span>
        <span class="cov0" title="0">transport := &amp;http.Transport{MaxIdleConns: 256, MaxIdleConnsPerHost: 128, MaxConnsPerHost: 128, IdleConnTimeout: 30 * time.Second}
        client := &amp;http.Client{Transport: transport, Timeout: 15 * time.Second}
        defer transport.CloseIdleConnections()
        body := []byte(`{"market":"ETH-USDT","side":"BUY","type":"LIMIT","time_in_force":"GTC","price":"0.01","quantity":"0.0001"}`)
        report := struct {
                Workload string      `json:"workload"`
                Seconds  float64     `json:"seconds_per_rate"`
                Workers  int         `json:"client_workers"`
                Pending  int         `json:"max_client_pending"`
                Driver   string      `json:"driver"`
                Runs     []runReport `json:"runs"`
        }{"90% new non-crossing LIMIT GTC, 10% same-key confirmation", *seconds, 128, 256, "Go net/http", nil}
        var index int64
        for _, rate := range rates </span><span class="cov0" title="0">{
                before, err := readMetrics(client, *diagnostic)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">jobs := make(chan job, 256)
                samples := make(chan sample, 384)
                var workers sync.WaitGroup
                for range 128 </span><span class="cov0" title="0">{
                        workers.Go(func() </span><span class="cov0" title="0">{
                                for j := range jobs </span><span class="cov0" title="0">{
                                        key := "load-order-" + strconv.FormatInt(j.index, 10)
                                        if j.index%10 == 0 </span><span class="cov0" title="0">{
                                                key = "load-fixed-key"
                                        }</span>
                                        <span class="cov0" title="0">req, err := http.NewRequest("POST", *base+"/api/v1/orders", bytes.NewReader(body))
                                        if err != nil </span><span class="cov0" title="0">{
                                                samples &lt;- sample{0, time.Since(j.planned).Seconds() * 1000, 0}
                                                continue</span>
                                        }
                                        <span class="cov0" title="0">req.Header.Set("Content-Type", "application/json")
                                        req.Header.Set("Cookie", cookie)
                                        req.Header.Set("X-CSRF-Token", csrf)
                                        req.Header.Set("X-Dataset-ID", dataset)
                                        req.Header.Set("Idempotency-Key", key)
                                        resp, err := client.Do(req)
                                        status := 0
                                        var result struct {
                                                ProcessedSeq string `json:"processed_seq"`
                                        }
                                        if err == nil </span><span class="cov0" title="0">{
                                                status = resp.StatusCode
                                                json.NewDecoder(io.LimitReader(resp.Body, 1&lt;&lt;20)).Decode(&amp;result)
                                                io.Copy(io.Discard, resp.Body)
                                                resp.Body.Close()
                                        }</span>
                                        <span class="cov0" title="0">seq, _ := strconv.ParseInt(result.ProcessedSeq, 10, 64)
                                        samples &lt;- sample{status, time.Since(j.planned).Seconds() * 1000, seq}</span>
                                }
                        })
                }
                <span class="cov0" title="0">collected := make(chan []sample, 1)
                go func() </span><span class="cov0" title="0">{
                        all := []sample{}
                        for s := range samples </span><span class="cov0" title="0">{
                                all = append(all, s)
                        }</span>
                        <span class="cov0" title="0">collected &lt;- all</span>
                }()
                <span class="cov0" title="0">start := time.Now()
                dropped := 0
                total := int(float64(rate) * *seconds)
                for i := 0; i &lt; total; i++ </span><span class="cov0" title="0">{
                        planned := start.Add(time.Duration(float64(i) / float64(rate) * 1e9))
                        if delay := time.Until(planned); delay &gt; 0 </span><span class="cov0" title="0">{
                                time.Sleep(delay)
                        }</span>
                        <span class="cov0" title="0">select </span>{
                        case jobs &lt;- job{index, planned}:<span class="cov0" title="0"></span>
                        default:<span class="cov0" title="0">
                                dropped++</span>
                        }
                        <span class="cov0" title="0">index++</span>
                }
                <span class="cov0" title="0">close(jobs)
                workers.Wait()
                close(samples)
                all := &lt;-collected
                elapsed := time.Since(start).Seconds()
                statuses := map[string]int{}
                latencies := make([]float64, 0, len(all))
                success := 0
                for _, s := range all </span><span class="cov0" title="0">{
                        statuses[strconv.Itoa(s.status)]++
                        latencies = append(latencies, s.latency)
                        if s.status == 200 || s.status == 201 </span><span class="cov0" title="0">{
                                success++
                        }</span>
                }
                <span class="cov0" title="0">sort.Float64s(latencies)
                catchup := time.Now()
                after, err := readMetrics(client, *diagnostic)
                if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">target := after["exchange_journal_seq"]
                for after["exchange_projection_seq"] &lt; target </span><span class="cov0" title="0">{
                        if time.Since(catchup) &gt; 15*time.Second </span><span class="cov0" title="0">{
                                return fmt.Errorf("projection did not catch up")
                        }</span>
                        <span class="cov0" title="0">time.Sleep(10 * time.Millisecond)
                        after, err = readMetrics(client, *diagnostic)
                        if err != nil </span><span class="cov0" title="0">{
                                return err
                        }</span>
                }
                <span class="cov0" title="0">run := runReport{rate, total, elapsed, dropped, statuses, float64(success) / elapsed, percentile(latencies, .5), percentile(latencies, .95), percentile(latencies, .99), time.Since(catchup).Seconds(), before, after}
                report.Runs = append(report.Runs, run)
                raw, _ := json.Marshal(run)
                fmt.Println(string(raw))</span>
        }
        <span class="cov0" title="0">f, err := os.OpenFile(*output, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">encoder := json.NewEncoder(f)
        encoder.SetIndent("", "  ")
        encodeErr := encoder.Encode(report)
        closeErr := f.Close()
        if encodeErr != nil </span><span class="cov0" title="0">{
                return encodeErr
        }</span>
        <span class="cov0" title="0">return closeErr</span>
}

// main 失败退出非零,实验脚本负责停止独立服务并对账,不能因网络错误静默通过。
func main() <span class="cov0" title="0">{
        if err := execute(); err != nil </span><span class="cov0" title="0">{
                fmt.Fprintln(os.Stderr, err)
                os.Exit(1)
        }</span>
}
</pre>
    
    <pre class="file" id="file24" style="display: none">package main

import (
        "context"
        "errors"
        "fmt"
        "log/slog"
        "net"
        "net/http"
        "os"
        "os/signal"
        "strconv"
        "syscall"
        "time"

        "web3exchange/backend"
)

// env 读取非空配置,否则使用本地默认值;生产参数说明见 deploy/exchange.env.example。
func env(name, fallback string) string <span class="cov8" title="1">{
        if x := os.Getenv(name); x != "" </span><span class="cov8" title="1">{
                return x
        }</span>
        <span class="cov8" title="1">return fallback</span>
}

// localAdminConfig 在打开数据库前校验显式本地管理员模式,只允许数值回环 IP 监听。
// localhost/空 host/0.0.0.0 都拒绝,避免固定演示密码被误用于公开监听。
// 两种管理员初始化配置互斥;脚本设置独立数据目录,不自动更改已有管理员密码。
func localAdminConfig(listen string) (string, error) <span class="cov8" title="1">{
        name := os.Getenv("EXCHANGE_LOCAL_ADMIN_NAME")
        if name == "" </span><span class="cov8" title="1">{
                return "", nil
        }</span>
        <span class="cov8" title="1">host, _, err := net.SplitHostPort(listen)
        ip := net.ParseIP(host)
        if err != nil || ip == nil || !ip.IsLoopback() </span><span class="cov8" title="1">{
                return "", fmt.Errorf("local admin requires a loopback IP listener")
        }</span>
        <span class="cov8" title="1">if _, err = backend.LocalAdminEmail(name); err != nil </span><span class="cov8" title="1">{
                return "", err
        }</span>
        <span class="cov8" title="1">if os.Getenv("EXCHANGE_ADMIN_EMAIL") != "" </span><span class="cov8" title="1">{
                return "", fmt.Errorf("local and regular admin configuration cannot be combined")
        }</span>
        <span class="cov8" title="1">return name, nil</span>
}

// main 支持正常服务与无 shell 依赖的 health 子命令,便于 scratch 镜像健康检查。
// 健康请求最多 3s,关闭 response body;启动/运行失败退出非零交给进程监督器。
func main() <span class="cov0" title="0">{
        // 结构化进程日志只在外围输出,不记录密码/完整业务请求。
        slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
        if len(os.Args) &gt; 1 &amp;&amp; os.Args[1] == "health" </span><span class="cov0" title="0">{
                client := &amp;http.Client{Timeout: 3 * time.Second}
                resp, err := client.Get(env("EXCHANGE_HEALTH_URL", "http://127.0.0.1:8080/health/ready"))
                if err != nil </span><span class="cov0" title="0">{
                        os.Exit(1)
                }</span>
                <span class="cov0" title="0">resp.Body.Close()
                if resp.StatusCode != 200 </span><span class="cov0" title="0">{
                        os.Exit(1)
                }</span>
                <span class="cov0" title="0">return</span>
        }
        <span class="cov0" title="0">if err := run(); err != nil </span><span class="cov0" title="0">{
                slog.Error("service stopped", "error", err)
                os.Exit(1)
        }</span>
}

// run 按存储 → 重放/流水线 → 管理员 → 行情采样 → HTTP 的顺序启动。
// defer 逆序保证采样器结束、业务排空,再关存储;无默认管理员密码。
// SIGINT/SIGTERM 取消采样、关闭 WS,再关闭 runtime 接入并排空,之后 Shutdown HTTP。
// 在排空时监听器尚可响应,但 runtime 不接受新业务;最后等待采样结束再关闭数据库。
// runtime 故障会主动关闭 HTTP 并退出;HTTP Shutdown 本身不管理 hijacked WS。
func run() error <span class="cov8" title="1">{
        listen := env("EXCHANGE_LISTEN_ADDR", "127.0.0.1:8080")
        localAdmin, err := localAdminConfig(listen)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">s, err := backend.OpenStore(env("EXCHANGE_DATA_DIR", "data"))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov8" title="1">defer s.Close()
        budget := backend.DefaultRuntimeConfig()
        for _, entry := range []struct {
                name   string
                target *int
        }{{"EXCHANGE_QUEUE_CAPACITY", &amp;budget.Queue}, {"EXCHANGE_INFLIGHT_CAPACITY", &amp;budget.Inflight}, {"EXCHANGE_JOURNAL_BATCH_SIZE", &amp;budget.Batch}} </span><span class="cov8" title="1">{
                if raw := os.Getenv(entry.name); raw != "" </span><span class="cov8" title="1">{
                        value, e := strconv.Atoi(raw)
                        if e != nil </span><span class="cov8" title="1">{
                                return fmt.Errorf("%s: %w", entry.name, e)
                        }</span>
                        <span class="cov8" title="1">*entry.target = value</span>
                }
        }
        <span class="cov8" title="1">if raw := os.Getenv("EXCHANGE_JOURNAL_BATCH_WAIT"); raw != "" </span><span class="cov8" title="1">{
                budget.BatchWait, err = time.ParseDuration(raw)
                if err != nil </span><span class="cov8" title="1">{
                        return err
                }</span>
        }
        <span class="cov8" title="1">shutdownWait := 60 * time.Second
        if raw := os.Getenv("EXCHANGE_SHUTDOWN_TIMEOUT"); raw != "" </span><span class="cov8" title="1">{
                shutdownWait, err = time.ParseDuration(raw)
                if err != nil || shutdownWait &lt; time.Second || shutdownWait &gt; 5*time.Minute </span><span class="cov8" title="1">{
                        return fmt.Errorf("invalid shutdown timeout")
                }</span>
        }
        <span class="cov8" title="1">runtime, err := backend.NewRuntimeWithConfig(s, budget)
        if err != nil </span><span class="cov8" title="1">{
                return err
        }</span>
        <span class="cov8" title="1">defer func() </span><span class="cov8" title="1">{
                ctx, cancel := context.WithTimeout(context.Background(), shutdownWait)
                defer cancel()
                runtime.Close(ctx)
        }</span>()
        // 诊断服务独立监听,强制 IP 为 loopback,避免错误配置把 pprof 暴露公网。
        <span class="cov8" title="1">var diagnostics *http.Server
        if address := os.Getenv("EXCHANGE_DIAGNOSTICS_ADDR"); address != "" </span><span class="cov8" title="1">{
                host, _, e := net.SplitHostPort(address)
                if e != nil || net.ParseIP(host) == nil || !net.ParseIP(host).IsLoopback() </span><span class="cov8" title="1">{
                        return fmt.Errorf("diagnostics address must use loopback IP")
                }</span>
                <span class="cov0" title="0">listener, e := net.Listen("tcp", address)
                if e != nil </span><span class="cov0" title="0">{
                        return e
                }</span>
                <span class="cov0" title="0">diagnostics = &amp;http.Server{Handler: runtime.DiagnosticsHandler(), ReadHeaderTimeout: 5 * time.Second, IdleTimeout: 30 * time.Second}
                go func() </span><span class="cov0" title="0">{
                        if e := diagnostics.Serve(listener); e != nil &amp;&amp; !errors.Is(e, http.ErrServerClosed) </span><span class="cov0" title="0">{
                                slog.Error("diagnostics stopped", "error", e)
                        }</span>
                }()
                <span class="cov0" title="0">defer diagnostics.Close()</span>
        }
        <span class="cov0" title="0">server := backend.NewServer(s, runtime, backend.Config{CookieSecure: env("EXCHANGE_COOKIE_SECURE", "false") == "true", FrontendDir: env("EXCHANGE_FRONTEND_DIR", "frontend/dist"), AllowedOrigin: os.Getenv("EXCHANGE_ALLOWED_ORIGIN"), LocalAdminName: localAdmin})
        defer server.CloseStreams()
        if email := os.Getenv("EXCHANGE_ADMIN_EMAIL"); email != "" || localAdmin != "" </span><span class="cov0" title="0">{
                var u backend.User
                if localAdmin != "" </span><span class="cov0" title="0">{
                        u, err = s.BootstrapLocalAdmin(context.Background(), localAdmin, os.Getenv("EXCHANGE_ADMIN_PASSWORD"))
                }</span> else<span class="cov0" title="0"> {
                        u, err = s.BootstrapAdmin(context.Background(), email, os.Getenv("EXCHANGE_ADMIN_PASSWORD"))
                }</span>
                <span class="cov0" title="0">if err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">if err = server.EnsureFunding(context.Background(), u.ID); err != nil </span><span class="cov0" title="0">{
                        return err
                }</span>
                <span class="cov0" title="0">slog.Info("admin bootstrap complete", "email", u.Email)</span>
        }
        <span class="cov0" title="0">ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
        defer stop()
        samplerDone := make(chan struct{})
        go func() </span><span class="cov0" title="0">{ defer close(samplerDone); server.RunSampler(ctx) }</span>()
        <span class="cov0" title="0">defer func() </span><span class="cov0" title="0">{ stop(); &lt;-samplerDone }</span>()
        <span class="cov0" title="0">httpServer := &amp;http.Server{Addr: listen, Handler: server.Handler(), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 15 * time.Second, IdleTimeout: 60 * time.Second, MaxHeaderBytes: 16 &lt;&lt; 10}
        serveErrors := make(chan error, 1)
        go func() </span><span class="cov0" title="0">{
                slog.Info("exchange listening", "address", httpServer.Addr)
                serveErrors &lt;- httpServer.ListenAndServe()
        }</span>()
        <span class="cov0" title="0">ticker := time.NewTicker(time.Second)
        defer ticker.Stop()
        for </span><span class="cov0" title="0">{
                select </span>{
                case &lt;-ctx.Done():<span class="cov0" title="0">
                        server.CloseStreams()
                        shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownWait)
                        defer cancel()
                        // 先关闭业务受理并排空,再等 HTTP 等待者结束;关闭时 ready 立即转为失败。
                        drainErr := runtime.Close(shutdownCtx)
                        httpErr := httpServer.Shutdown(shutdownCtx)
                        if httpErr != nil </span><span class="cov0" title="0">{
                                httpServer.Close()
                        }</span>
                        <span class="cov0" title="0">return errors.Join(drainErr, httpErr)</span>
                case err := &lt;-serveErrors:<span class="cov0" title="0">
                        return err</span>
                case &lt;-ticker.C:<span class="cov0" title="0">
                        if !runtime.Healthy() </span><span class="cov0" title="0">{
                                server.CloseStreams()
                                shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
                                httpServer.Shutdown(shutdownCtx)
                                cancel()
                                return fmt.Errorf("business runtime failed")
                        }</span>
                }
        }
}
</pre>
    
    <pre class="file" id="file25" style="display: none">// web3server 独立链上模式入口,不调用模拟初始化资金或共用原数据目录。
package main

import (
        "context"
        "encoding/json"
        "fmt"
        "log/slog"
        "net"
        "net/http"
        "os"
        "os/signal"
        "syscall"
        "time"

        "web3exchange/chaintrade"
)

// env 配置只读进程环境,不写全局代理或用户配置。
func env(k, f string) string <span class="cov0" title="0">{
        if v := os.Getenv(k); v != "" </span><span class="cov0" title="0">{
                return v
        }</span>
        <span class="cov0" title="0">return f</span>
}

// run 生命周期:域/任务绑定→重放→链核验→中间件→worker→HTTP,逆序排空。
func run() error <span class="cov0" title="0">{
        raw, err := os.ReadFile(env("WEB3_CONFIG", "bin/web3-dev/config.json"))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">var domain chaintrade.Domain
        if err = json.Unmarshal(raw, &amp;domain); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if domain.Confirmations &lt; 1 || domain.Confirmations &gt; 128 </span><span class="cov0" title="0">{
                return fmt.Errorf("confirmations requires 1..128")
        }</span>
        <span class="cov0" title="0">dir := env("WEB3_DATA_DIR", "data-web3")
        store, err := chaintrade.OpenStore(dir, domain)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer store.Close()
        runtime, err := chaintrade.NewRuntime(store)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer runtime.Close()
        tasks, err := chaintrade.OpenTasks(dir, os.Getenv("WEB3_POSTGRES_DSN"))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer tasks.Close()
        ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
        defer stop()
        if err = tasks.Bind(ctx, store.Domain); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">chain, err := chaintrade.OpenChain(ctx, env("WEB3_RPC_URL", "http://127.0.0.1:8545"), os.Getenv("WEB3_RELAYER_KEY"), store.Domain)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer chain.Client.Close()
        middleware, err := chaintrade.OpenMiddleware(ctx, store, tasks, os.Getenv("WEB3_REDIS_URL"), os.Getenv("WEB3_KAFKA_BROKER"), env("WEB3_KAFKA_TOPIC", "exchange-settlements"))
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer middleware.Close()
        listen := env("WEB3_LISTEN_ADDR", "127.0.0.1:8081")
        handler := chaintrade.NewHTTP(store, runtime, middleware, chain, env("WEB3_ALLOWED_ORIGIN", "http://"+listen), env("WEB3_FRONTEND_DIR", "frontend/dist"))
        indexer := &amp;chaintrade.Indexer{Store: store, RPC: chain.Client}
        if err = indexer.CheckAnchor(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">worker := &amp;chaintrade.Worker{Store: store, Runtime: runtime, Tasks: tasks, Middleware: middleware, Chain: chain}
        // 启动前核实已采纳链事实,避免深重组后短暂宣告ready。
        if err = worker.CheckScanAnchor(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if err = worker.AuditAnchors(ctx); err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">workerDone := make(chan struct{})
        consumerDone := make(chan struct{})
        report := func(err error) </span><span class="cov0" title="0">{ handler.Monitor.WorkerErrors.Add(1); slog.Error("web3 worker", "error", err) }</span>
        <span class="cov0" title="0">go func() </span><span class="cov0" title="0">{ defer close(consumerDone); middleware.RunConsumer(ctx, report) }</span>()
        <span class="cov0" title="0">go func() </span><span class="cov0" title="0">{
                defer close(workerDone)
                ticker := time.NewTicker(500 * time.Millisecond)
                defer ticker.Stop()
                for </span><span class="cov0" title="0">{
                        select </span>{
                        case &lt;-ctx.Done():<span class="cov0" title="0">
                                return</span>
                        case &lt;-ticker.C:<span class="cov0" title="0">
                                work, cancel := context.WithTimeout(ctx, 10*time.Second)
                                if err := tasks.CheckOwner(work); err != nil </span><span class="cov0" title="0">{
                                        handler.WorkerError.Store(err.Error())
                                        report(err)
                                        cancel()
                                        stop()
                                        return
                                }</span>
                                <span class="cov0" title="0">if err := worker.CheckScanAnchor(work); err != nil </span><span class="cov0" title="0">{
                                        handler.WorkerError.Store(err.Error())
                                        report(err)
                                        cancel()
                                        stop()
                                        return
                                }</span>
                                <span class="cov0" title="0">if err := worker.AuditAnchors(work); err != nil </span><span class="cov0" title="0">{
                                        handler.WorkerError.Store(err.Error())
                                        report(err)
                                        cancel()
                                        stop()
                                        return
                                }</span>
                                <span class="cov0" title="0">if err := worker.Tick(work); err != nil </span><span class="cov0" title="0">{
                                        report(err)
                                }</span>
                                <span class="cov0" title="0">if err := worker.ScanOrders(work); err != nil </span><span class="cov0" title="0">{
                                        report(err)
                                }</span>
                                <span class="cov0" title="0">cancel()</span>
                        }
                }
        }()
        // 索引与监控分别调度,RPC补拉/重放不能抢占 relayer 本轮预算。
        <span class="cov0" title="0">indexDone := make(chan struct{})
        sampleDone := make(chan struct{})
        go func() </span><span class="cov0" title="0">{
                defer close(indexDone)
                ticker := time.NewTicker(time.Second)
                defer ticker.Stop()
                for </span><span class="cov0" title="0">{
                        select </span>{
                        case &lt;-ctx.Done():<span class="cov0" title="0">
                                return</span>
                        case &lt;-ticker.C:<span class="cov0" title="0">
                                work, cancel := context.WithTimeout(ctx, 10*time.Second)
                                if err := indexer.CheckAnchor(work); err != nil </span><span class="cov0" title="0">{
                                        handler.WorkerError.Store(err.Error())
                                        report(err)
                                        cancel()
                                        stop()
                                        return
                                }</span>
                                <span class="cov0" title="0">if err := indexer.Tick(work); err != nil </span><span class="cov0" title="0">{
                                        report(err)
                                }</span>
                                <span class="cov0" title="0">cancel()</span>
                        }
                }
        }()
        <span class="cov0" title="0">go func() </span><span class="cov0" title="0">{
                defer close(sampleDone)
                ticker := time.NewTicker(30 * time.Second)
                defer ticker.Stop()
                for </span><span class="cov0" title="0">{
                        work, cancel := context.WithTimeout(ctx, 10*time.Second)
                        if err := handler.Sample(work); err != nil </span><span class="cov0" title="0">{
                                report(err)
                        }</span>
                        <span class="cov0" title="0">cancel()
                        select </span>{
                        case &lt;-ctx.Done():<span class="cov0" title="0">
                                return</span>
                        case &lt;-ticker.C:<span class="cov0" title="0"></span>
                        }
                }
        }()
        <span class="cov0" title="0">defer func() </span><span class="cov0" title="0">{ stop(); &lt;-workerDone; &lt;-consumerDone; &lt;-indexDone; &lt;-sampleDone }</span>()
        <span class="cov0" title="0">server := &amp;http.Server{Addr: listen, Handler: handler.Handler(), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 15 * time.Second}
        diagnosticsAddr := os.Getenv("WEB3_DIAGNOSTICS_ADDR")
        if diagnosticsAddr != "" </span><span class="cov0" title="0">{
                host, _, e := net.SplitHostPort(diagnosticsAddr)
                if e != nil || net.ParseIP(host) == nil || !net.ParseIP(host).IsLoopback() </span><span class="cov0" title="0">{
                        return fmt.Errorf("diagnostics must be loopback")
                }</span>
                <span class="cov0" title="0">diagnostics := &amp;http.Server{Addr: diagnosticsAddr, Handler: handler.Diagnostics(), ReadHeaderTimeout: 5 * time.Second}
                defer diagnostics.Close()
                go func() </span><span class="cov0" title="0">{
                        if e := diagnostics.ListenAndServe(); e != nil &amp;&amp; e != http.ErrServerClosed </span><span class="cov0" title="0">{
                                report(e)
                        }</span>
                }()
        }
        <span class="cov0" title="0">errors := make(chan error, 1)
        go func() </span><span class="cov0" title="0">{
                slog.Info("web3 server ready", "address", listen, "dataset", store.Domain.Dataset)
                errors &lt;- server.ListenAndServe()
        }</span>()
        <span class="cov0" title="0">select </span>{
        case err = &lt;-errors:<span class="cov0" title="0">
                if err != http.ErrServerClosed </span><span class="cov0" title="0">{
                        return err
                }</span>
        case &lt;-ctx.Done():<span class="cov0" title="0"></span>
        }
        <span class="cov0" title="0">shutdown, cancel := context.WithTimeout(context.Background(), 20*time.Second)
        defer cancel()
        return server.Shutdown(shutdown)</span>
}

// health 容器内无需curl,固定超时检查自身ready;0.0.0.0只转换为探针回环地址。
func health() error <span class="cov0" title="0">{
        address := env("WEB3_LISTEN_ADDR", "127.0.0.1:8081")
        host, port, err := net.SplitHostPort(address)
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">if host == "0.0.0.0" || host == "::" || host == "" </span><span class="cov0" title="0">{
                host = "127.0.0.1"
        }</span>
        <span class="cov0" title="0">client := http.Client{Timeout: 2 * time.Second}
        response, err := client.Get("http://" + net.JoinHostPort(host, port) + "/health/ready")
        if err != nil </span><span class="cov0" title="0">{
                return err
        }</span>
        <span class="cov0" title="0">defer response.Body.Close()
        if response.StatusCode != 200 </span><span class="cov0" title="0">{
                return fmt.Errorf("not ready: %d", response.StatusCode)
        }</span>
        <span class="cov0" title="0">return nil</span>
}

// main 失败非零退出供supervisor处理;日志不输出key/DSN或用户签名正文。
func main() <span class="cov0" title="0">{
        if len(os.Args) == 2 &amp;&amp; os.Args[1] == "health" </span><span class="cov0" title="0">{
                if err := health(); err != nil </span><span class="cov0" title="0">{
                        fmt.Fprintln(os.Stderr, err)
                        os.Exit(1)
                }</span>
                <span class="cov0" title="0">return</span>
        }
        <span class="cov0" title="0">slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
        if err := run(); err != nil </span><span class="cov0" title="0">{
                slog.Error("web3 stopped", "error", err)
                os.Exit(1)
        }</span>
}
</pre>
    
    </div>
  </body>
  <script>
  (function() {
    var files = document.getElementById('files');
    var visible;
    files.addEventListener('change', onChange, false);
    function select(part) {
      if (visible)
        visible.style.display = 'none';
      visible = document.getElementById(part);
      if (!visible)
        return;
      files.value = part;
      visible.style.display = 'block';
      location.hash = part;
    }
    function onChange() {
      select(files.value);
      window.scrollTo(0, 0);
    }
    if (location.hash != "") {
      select(location.hash.substr(1));
    }
    if (!visible) {
      select("file0");
    }
  })();
  </script>
</html>

— 本篇阅读完毕 —
来源:Web3 交易系统 / docs / reports/evidence-v0.5/coverage.html 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭