cbdc-biz/app/auditor

审计节点。本仓库 submodule cbdc-chain/，本页所有路径相对该 submodule 根。

基本事实

项	值	出处
路径	cbdc-biz/app/auditor/	—
独立 go.mod	无（目录内无 go.mod，共用 cbdc-biz/go.mod）	—
Go 文件数	19 非测试 + 4 测试	—
README	[未核] 目录内无
子文档	internal/worker/INTEGRATION.md（78 行，Capture Worker 集成说明）	—

目录：

cbdc-biz/app/auditor/
├── cmd/auditor/{main.go,wire.go,wire_gen.go,indexer.go,indexer_test.go}
├── internal/
│   ├── biz/      biz.go + auditor.go(297行) + auditlog_biz.go(52行)
│   ├── conf/     conf.proto + conf.pb.go
│   ├── data/     data.go（空 stub，TODO 标记）
│   ├── server/   server.go + grpc.go
│   ├── service/  service.go + auditor.go(248行)
│   ├── sidecar/  sidecar.go + sidecar_test.go
│   └── worker/   types.go + finality_capture_worker.go + lookup_ttx.go + source_deliver.go + INTEGRATION.md + 2 个 test
├── pkg/auditlog/ auditlog.go (121行)
└── Makefile

入口启动（main.go）

来源：cbdc-biz/app/auditor/cmd/auditor/main.go。

-conf flag 默认 ../../configs（main.go:50-52）；版本号由 -X main.Version 注入（main.go:38）。

Wire DI

来源：cmd/auditor/wire.go:1-23、wire_gen.go:26-33。

wireApp(*conf.Server, log.Logger, *node.Node)
  └─ NewAuditorBiz(node)
     └─ NewAuditorService(biz)
        └─ NewGRPCServer(conf.Server, service, logger)
           └─ newApp(logger, gs)

server.ProviderSet (internal/server/server.go:8)；biz.ProviderSet (internal/biz/biz.go:6)；service.ProviderSet (internal/service/service.go:6)。

internal/biz

来源：cbdc-biz/app/auditor/internal/biz/。

AuditorBiz（auditor.go:45-47，构造器 :49-51）

type AuditorBiz struct {
    node *node.Node
}

方法	file:line	职责
NewAuditorBiz	auditor.go:49-51	构造
GetBalance	auditor.go:57-79	钱包余额（按 token 类型）
GetHistory	auditor.go:82-129	钱包完整交易历史
ListTransactions	auditor.go:194-297	分页查询（多维过滤）

返回类型：

• ValueByTokenType = map[string]int64（auditor.go:54）
• TransactionHistoryItem（auditor.go:34-43）：TxID / Sender / Recipient / TokenType / Amount / Status / Timestamp / Message
• TransactionItem（auditor.go:146-156）：含 Amount 字符串（经 wallet_common.FormatBigAmount）
• ListTransactionsParams（auditor.go:132-143）：SenderWallet / RecipientWallet / FromTime / ToTime / ActionTypes / Statuses / Page / PageSize / TxIDs / ExcludeToSelf

错误（auditor.go:26-30）：

var (
    ErrCounterpartyAccountNotFound = errors.New("counterparty account not found")
    ErrInsufficientFunds           = errors.New("insufficient funds")
    ErrConnectionError             = errors.New("could not connect to counterparty")
)

auditlog_biz.go

函数	file:line	职责
InitAuditLog	auditlog_biz.go:13-15	初始化审计日志，注入 bizhub rejection 发送器
CloseAuditLog	auditlog_biz.go:18-20	关闭并刷新
LogRejection	auditlog_biz.go:23-25	异步入队一条拒绝记录
bizhubRejectionSender.SendRejectionLogs	auditlog_biz.go:30-52	批量发到 bizhub gRPC

internal/data

[未核 / 故意空]

internal/data/data.go:9-22 仅为空 stub（TODO）。无 ORM / 无 SQL；持久化由 Fabric Token SDK 的 ttxdb / auditdb 承担。

internal/service

来源：cbdc-biz/app/auditor/internal/service/auditor.go:17-26。

type AuditorService struct {
    v1.UnimplementedAuditorServiceServer
    biz *biz.AuditorBiz
}

RPC	file:line	业务层调用
GetBalance	auditor.go:28-40	biz.GetBalance(wallet, tokenSymbol)
GetHistory	auditor.go:42-63	biz.GetHistory(wallet)
ManualRulesetSync	auditor.go:65-102	auditor.UpdateRulesets()（GetSDK() 仅作 nil 守卫）
ManualRuleGroupSync	auditor.go:104-163	tx_selector.UpdateRuleGroups()
ManualMarkSync	auditor.go:165-209	marked.UpdateAssetMarks()
ListTransactions	auditor.go:211-247	biz.ListTransactions(ctx, params)

对应 proto：api/cbdc-biz/v1/auditor.proto:9-22。

internal/sidecar / internal/worker / cmd/auditor/indexer

Sidecar 连接

internal/sidecar/sidecar.go（181 行）含 FSC config 解析、TLS 凭证构建与 gRPC 拨号（ResolveSidecarConfig / DialSidecar / buildSidecarCredentials）；测试 sidecar_test.go（39 行）覆盖 ResolveSidecarConfig。

Worker

文件	用途
types.go (75 行)	类型定义（含 pkg/common/indexer 类型再导出）
finality_capture_worker.go	账本索引主 Worker（测试覆盖 547 行）
lookup_ttx.go	TTXLookup.LookupTxBatch 批量交易查询（82 行测试覆盖 convertTransactionRecord / actionTypeToInt 转换辅助函数）
source_deliver.go	Deliver 流处理
INTEGRATION.md	78 行集成说明（设计要点、接线、启用、故障场景、监控、测试）

Indexer 启动（startIndexerCapture，cmd/auditor/indexer.go:86-184）

• resolveIndexerEndpoints 读 fabric.default.channels 取 channel_id（indexer.go:50，由 L110 调用）
• sidecar.ResolveSidecarConfig(c) 解析 sidecar 端点（indexer.go:124，实际读 fabric.default.notificationService.endpoints 见 sidecar.go:66）
• bizclient.NewIndexerClient(bizhubConn) 构造 bizhub indexer 客户端（indexer.go:161）；cursor 的 GetCursor / AppendBatch 在 Worker 内（worker/finality_capture_worker.go:150,500）

测试覆盖：resolveIndexerEndpoints / nextBackoff（indexer_test.go 159 行）。

internal/conf

来源：cbdc-biz/app/auditor/internal/conf/conf.proto。

message Bootstrap {
  Biz biz = 1;
}

message Biz {
  Server server = 1;
  string bizhub_addr = 2;
  Observability observability = 3;
  WorkerPool audit_worker_pool = 4;
  Indexer indexer = 5;
  TLS bizhub_tls = 6;
}

message Indexer {
  bool   enabled         = 1;
  string shard           = 2;   // Phase 1: auditor-0
  int32  batch_size      = 3;   // 0 → 200
  Duration flush_interval = 4;  // 0 → 1s
  int32  queue_depth     = 5;   // 0 → 10000
  Duration append_timeout = 6;  // 0 → 5s
  Duration retry_initial  = 7;  // 0 → 100ms
  Duration retry_max      = 8;  // 0 → 30s
  Duration restart_backoff = 9; // 0 → 5s
}

message WorkerPool {
  int32 size = 1;             // 0 → runtime.GOMAXPROCS
  Duration submit_timeout = 2; // 0 → fail-fast
}

行号见 conf.proto:1-80（节选）。Tracing sample_rate 见 :73，Logging level 见 :78。

configs

[未核]

auditor app 内无 configs/ 目录；配置由上级 cbdc-biz/ 集中提供，-conf flag 默认 ../../configs。

与其他 app / pkg 的关系

出站：→ bizhub（gRPC）

来源：main.go:118-132、service/auditor.go、biz/auditlog_biz.go。

用途	出处
Rulesets	service/auditor.go:82 bizhubc.GetAuditorRulesets()
Rule groups	service/auditor.go:121 GetRuleGroupsByCategory("compliance")
Asset marks	service/auditor.go:182 GetAssetMarks()
优先级	service/auditor.go:138 FetchGroupPriorities()
拒绝日志	biz/auditlog_biz.go:50 InsertRejectionLogs()
Indexer cursor	internal/worker/finality_capture_worker.go:150 GetCursor() / :500 AppendBatch()

入站：← endorser（FSC View）

来源：main.go:202-209。

reg.RegisterResponder(&views.AuditView{...}, &views.RequestAuditView{})

Endorser 调 RequestAuditView → Auditor 跑 AuditView 验证并签名（pkg/views/audit.go）。

与 cbdc-biz/pkg/

pkg	用途	出处
pkg/common/auditor	Ruleset SDK	main.go:12, 141-148、service:7, 66
pkg/common/marked	资产标签 SDK	main.go:14, 150-157、service:9, 166-209
pkg/common/biz-client	bizhub gRPC 客户端 + TLS	main.go:13, 118-132、indexer.go:12, 131, 161
pkg/common/tx_selector	合规规则选择器	main.go:18, 159-167、service:10, 105-162
pkg/common/nodesdk	FSC 启动	main.go:15, 171-174
pkg/common/revocation	撤销列表（30s 刷新）	main.go:16, 186-192
pkg/common/syncutil	默认同步间隔	main.go:17, 143, 152, 162
pkg/common/indexer	共享 indexer 类型	worker/types.go:7（在 worker 内再导出供 finality_capture_worker 使用）
pkg/constants	TokenSymbol	main.go:19, 102、service:11, 33
pkg/signet	OTel	main.go:21, 111-114、server/grpc.go:7, 18
pkg/views	Audit / endorsement View	main.go:22, 204-209
pkg/workerpool	有界线程池	main.go:23, 198、pkg/views/audit.go:23, 139-146
pkg/auditor/rejection	拒绝日志类型	biz/auditlog_biz.go:8、pkg/auditlog/auditlog.go:10, 22

端口

实测自 cbdc-biz/conf/auditor/core.yaml：

用途	值	出处
gRPC（Server.addr）	0.0.0.0:9750	cbdc-biz/conf/auditor/core.yaml:16
FSC P2P（fsc.p2p.listenAddress）	/ip4/0.0.0.0/tcp/9751	cbdc-biz/conf/auditor/core.yaml:67
配置 schema	Server.addr 字段	internal/conf/conf.proto:57
监听代码	读 c.Addr	internal/server/grpc.go:25-26

测试

文件	行数	覆盖
cmd/auditor/indexer_test.go	159	resolveIndexerEndpoints / nextBackoff
internal/sidecar/sidecar_test.go	39	ResolveSidecarConfig（通知端点 + TLS 字段）
internal/worker/finality_capture_worker_test.go	547	capture/flush/cursor、批量 lookup、重试、分片
internal/worker/lookup_ttx_test.go	82	convertTransactionRecord / actionTypeToInt（转换辅助函数）

看代码推荐路径

1. cmd/auditor/main.go:67-228 → 启动全貌。
2. internal/biz/auditor.go:45-297 → 业务核心。
3. internal/service/auditor.go:17-247 → gRPC 翻译层 + 三个 ManualSync RPC。
4. internal/worker/finality_capture_worker.go + INTEGRATION.md → 索引器机制。
5. pkg/views/audit.go:48-147 → 与 Endorser 的 View 协作。

[未核]

• auditor app 主 README（无）。
• 关系型数据库（无 — 全部走 Token SDK）。
• 与 Issuer / Institution 的直接调用记录。
• configs/ 默认值（由上级目录提供）。
• 审计拒绝规则的具体定义（来自 auditor SDK 缓存，非本 app 源）。