cbdc-biz/app/institution

商业银行侧应用节点。本仓库 submodule cbdc-chain/，本页所有路径相对该 submodule 根。

基本事实

项	值	出处
路径	`cbdc-biz/app/institution/`	—
独立 go.mod	无（共用 `cbdc-biz/go.mod`）	目录无 `go.mod`
Go 文件数	26（含 `wire_gen.go`，无 `_test.go`）	—
独立 Dockerfile	有	`cbdc-biz/app/institution/Dockerfile`
Wire DI	有	`cbdc-biz/app/institution/cmd/institution/wire.go`
README / 文档	[未核] 目录内无	—

子目录：

cbdc-biz/app/institution/
├── cmd/institution/{main.go,wire.go,wire_gen.go}
├── internal/
│   ├── biz/        6 个文件
│   ├── client/     1 个文件（BizHub gRPC 客户端）
│   ├── conf/       conf.proto + conf.pb.go
│   ├── server/     server.go + grpc.go + http.go + openapi.yaml
│   ├── service/    9 个文件
│   └── worker/     3 个文件（worker.go ProviderSet + 2 个 worker）
├── configs/
├── Dockerfile
└── Makefile

入口启动（main.go）

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

注册的 4 对 FSC View（main.go:210-220）：

Responder	←	Initiator	业务含义
`AcceptTransferView`	←	`TransferView`	跨机构转账
`AcceptIdentityRequestView`	←	`PrepareTransferView`	两步转账·身份步
`AcceptPreparedTransferView`	←	`SubmitSignatureView`	两步转账·签名步
`AcceptCashView`	←	`IssueCashView`	央行发行 → 机构接收

Wire DI 依赖图

来源：cbdc-biz/app/institution/cmd/institution/wire.go:1-25、wire_gen.go:28-42。

wireApp 入参：*conf.Server、log.Logger、*node.Node、*client.BizHubClients、*conf.Biz（wire.go:23）。

internal/biz

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

文件	行数	关键 struct
`biz.go`	127	`InstitutionBiz`（`L38-43`）：基础依赖 + `pendingTxStore`
`wallet_biz.go`	308	`InstitutionWalletBiz`（`L32-43`）
`transfer_biz.go`	325	`InstitutionTransferBiz`（`L27-33`）
`transaction_biz.go`	86	`InstitutionTransactionBiz`（`L15-20`）
`redeem_biz.go`	115	`InstitutionRedeemBiz`（`L18-33`）
`transfer_metrics.go`	113	OTel 转账指标 `cbdc_institution_transfer_outcome_total`（method × outcome）

`InstitutionWalletBiz` 关键方法

方法	file:line	职责
`ListWalletIDs`	`wallet_biz.go:46`	查询 Token SDK 所有钱包 ID
`QueryBalances`	`wallet_biz.go:61`	单钱包余额（金额列表）
`BatchQueryBalances`	`wallet_biz.go:81`	并发批查询（16 并发上限）

`InstitutionTransferBiz` 关键方法

方法	file:line	职责
`PrepareTokenOptimization`	`transfer_biz.go:50`	UTXO 合并 / 分割（无签名）
`PrepareTransfer`	`transfer_biz.go:80`	常规转账准备
`PrepareMarkedTransfer`	`transfer_biz.go:169`	标记 token 转账（含 `useAssetMark` / `attachMetadata`）
`SubmitTransfer`	`transfer_biz.go:239`	提交 X.509 签名并广播
`CancelTransfer`	`transfer_biz.go:285`	取消待处理（释放 token 锁）
`Transfer`	`transfer_biz.go:295`	传统一体化转账（一步完成）

`InstitutionTransactionBiz` 关键方法

方法	file:line	职责
`CountTransactions`	`transaction_biz.go:23`	交易总数
`ListTransactions`	`transaction_biz.go:49`	分页查询（filter：sender / recipient / 时间 / 状态 / 类型）

`InstitutionRedeemBiz` 关键方法

方法	file:line	职责
`PrepareRedeem`	`redeem_biz.go:36`	赎回准备（央行销毁 token）
`SubmitRedeem`	`redeem_biz.go:78`	提交赎回签名

共享方法（`biz.go`）

方法	file:line	职责
`GetInstitutionCode`	`biz.go:61`	返回 3 位机构代码
`releasePendingTx`	`biz.go:76`	释放 token 选择器锁 + FSC 钱包锁
`StorePendingTransaction`	`biz.go:101`	存待处理交易
`GetPendingTransaction`	`biz.go:106`	取待处理交易
`PopPendingTransaction`	`biz.go:116`	原子弹出（防重复执行）

internal/data

[未核]

institution 无 internal/data/ 目录。持久化由 Hyperledger Fabric Token SDK 的 TTX DB 与钱包管理器在 SDK 层处理，本 app 不直接管理 DB。

internal/service

来源：cbdc-biz/app/institution/internal/service/。

聚合 struct InstitutionOpsService（service.go:21-51）：

type InstitutionOpsService struct {
    pb.UnimplementedInstitutionOpsServiceServer
    base, walletBiz, transferBiz, transactionBiz, redeemBiz
    certProvider auth.CertificateProvider
    bizhub       *client.BizHubClients
}

文件	RPC 方法	file:line
`wallet_service.go`	`ListWallets`	`:23`
	`GetWalletBalance`	`:101`
	`RegisterWallet`	`:120`
	`GetWalletCertificate`	`:133`
	`UpdateWalletCertificate`	`:145`
	`CreateWallet`	`:166`
	`GenerateWalletID`	`:282`
	`UpdateWalletStatus`	`:298`
	`ListWalletIDs`	`:381`
	`GetWalletInfo`	`:413`
	`BatchGetWalletInfo`	`:430`
	`BatchGetWalletBalances`	`:553`
	`RenewWalletCert`	`:631`
`transfer_service.go`	`PrepareTransfer`	`:24`
	`SubmitTransfer`	`:101`
	`CancelTransfer`	`:125`
`redeem_service.go`	`PrepareRedeem`	`:14`
	`SubmitRedeem`	`:33`
`transaction_service.go`	`listTransactionsLocal`（内部）	`:28`
	`ListTransactions`	`:148`
	`GetTransaction`	`:210`
`settlement_service.go`	`CreateSettlementRequest`	`:13`
	`QuerySettlementRequest`	`:33`
	`ListSettlementRequests`	`:50`
	`SubmitRedeemSignature`	`:74`
`approval_service.go`	`ListApprovals`	`:13`
	`GetApproval`	`:36`
`mark_service.go`	`ManualMarkSync`	`:17`
	`GetAssetMarks`	`:51`
	`GetWalletMarks`	`:64`

对应 proto：cbdc-biz/api/cbdc-biz/v1/institution.proto（service InstitutionOpsService）。

internal/worker

来源：cbdc-biz/app/institution/internal/worker/。

目录 3 个文件，含 2 个 worker 与 worker.go（Wire ProviderSet，worker.go:13-17）：

Worker	用途
`ApprovalWorker`	轮询 BizHub 审批队列（`PollInterval` 5s，`approval_worker.go:78`），执行 CREATE / CLOSE 钱包（`approval_worker.go:121`/`:123`）
`FinalityWorker`	监听链上交易最终性，`watch` 回调释放 token 锁（`finality_worker.go:68` struct / `:186` watch）

internal/conf

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

proto

message Biz {
  Server server = 1;
  string bizhub_addr = 2;        // 可选；省略则禁用钱包/结算
  string institution_code = 3;   // 必需；3 位机构代码，main.go:127 panic 校验
  TLS bizhub_tls = 4;
  Observability observability = 5;
  TokenSelector token_selector = 6;
}

message TokenSelector {
  string mode = 1;               // "memory" | "distributed"
  repeated uint64 bucket_boundaries = 2;
  RedisConfig redis = 3;
}

message TLS {
  bool enabled = 1;
  string server_name = 2;
  string ca_cert = 3;
  string client_cert = 4;
  string client_key = 5;
  bool insecure_skip_verify = 6;  // DEV ONLY
}

关键配置（来源 main.go:99-129 及 conf.proto）：

key	必需	默认 / 说明
`biz.institution_code`	✅	3 位机构码；缺则 `panic`（`main.go:127`）
`biz.bizhub_addr`	❌	空时跳过 BizHub 客户端初始化
`biz.token_selector.mode`	❌	默认 `memory`；`distributed` 需 Redis
`cbdc.symbol`	❌	默认 `SOM`（`main.go:100`）

configs

app 内 `configs/config.yaml`（Kratos 默认模板，非实际部署用）

yaml

server:
  http:
    addr: 0.0.0.0:8000
  grpc:
    addr: 0.0.0.0:9000

实际部署用配置：`cbdc-biz/conf/institution-001/core.yaml`

用途	值	出处
gRPC（`biz.server.addr`）	`0.0.0.0:9500`	`cbdc-biz/conf/institution-001/core.yaml:8`
FSC P2P（`fsc.p2p.listenAddress`）	`/ip4/0.0.0.0/tcp/9501`	`cbdc-biz/conf/institution-001/core.yaml:46`
HTTP（硬编码，不读 config）	`:9502`	`internal/server/http.go:38`

端口来源差异

cbdc-biz/app/institution/configs/config.yaml 是 Kratos 脚手架默认模板（:8000 / :9000），与 Dockerfile EXPOSE 8000 9000 一致；但 compose-local-run.yml 把 cbdc-biz/conf/institution-001/ 挂载到容器 /conf（docker/compose-local-run.yml:195），gRPC 监听走配置 9500、FSC P2P 9501，HTTP 硬编码在 server/http.go:38 的 9502；该 compose 发布 9500 / 9501 / 9502（docker/compose-local-run.yml:199-202）。

Dockerfile

来源：cbdc-biz/app/institution/Dockerfile。

dockerfile

FROM golang:1.26 AS builder                       # L1
COPY . /src                                       # L3
WORKDIR /src                                       # L4
RUN GOPROXY=https://goproxy.cn make build          # L6

FROM debian:stable-slim                            # L8
RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates netbase \
        && rm -rf /var/lib/apt/lists/ \
        && apt-get autoremove -y && apt-get autoclean -y   # L10-14
COPY --from=builder /src/bin /app                  # L16
WORKDIR /app                                       # L18
EXPOSE 8000                                        # L20
EXPOSE 9000                                        # L21
VOLUME /data/conf                                  # L22
CMD ["./server", "-conf", "/data/conf"]            # L24

特点：

两阶段（golang:1.26 → debian:stable-slim）
国内 GOPROXY=https://goproxy.cn
暴露 8000（HTTP）+ 9000（gRPC）
配置挂载点 /data/conf

与其他 app 的关系

出站

方向	协议	出处
→ BizHub（7 个 gRPC 客户端）	gRPC	`main.go:227-238`、`client/bizhub.go`
→ 其他 Institution（4 对 View）	FSC P2P viewregistry	`main.go:210-220`
→ Hyperledger Fabric Token SDK	in-process	全局 SDK

BizHubClients 含 7 项：CA / Wallet / ClientAuth / Settlement / InstitutionManage / Approval / Manage（struct 字段 internal/client/bizhub.go:43-49；构造调用点 main.go:231）。

入站

方向	协议	出处
← BizHub（审批轮询触发 CREATE/CLOSE 钱包）	gRPC（被动）	`worker/approval_worker.go:78,121`
← 其他 Institution（P2P 接收转账 / 身份 / 签名 / 发行）	FSC P2P	View Responder 注册
← Endorser / Issuer / Auditor 是否直连？	[未核]	—

与 `cbdc-biz/pkg/` 的关系

来源：main.go 与 biz/ / service/ import 段。

pkg	file:line	用途
`pkg/common/auth`	`service/service.go:7`	X.509 证书提供者
`pkg/common/fee`	`main.go:14`	本地手续费引擎
`pkg/common/marked`	`main.go:15`	标记 token SDK
`pkg/common/nodesdk`	`main.go:16`	FSC 节点启动
`pkg/common/syncutil`	`main.go:17`	周期同步
`pkg/common/wallet_common`	`main.go:19`、`biz/biz.go:10`	钱包公共类型 + pending-tx 存储
`pkg/common/biz-client`	`main.go:13`	BizHub HTTP 客户端
`pkg/common/tx_selector`	`main.go:18`	交易 / 手续费选择器
`pkg/constants`	`main.go:20`	`InitToken("SOM")`
`pkg/identity`	`biz/wallet_biz.go:15`	身份解析
`pkg/observability`	`biz/transfer_biz.go:12`	可观测性辅助
`pkg/runtime`	`main.go:21`	启动日志 + pprof
`pkg/scheduler`	`worker/approval_worker.go:14`	定时任务
`pkg/signet`	`main.go:22`、`server/grpc.go:7`	OTel + 中间件
`pkg/token_selector`	`main.go:23`	Token 选择器管理
`pkg/views`	`main.go:24`、`biz/transfer_biz.go:13`	FSC 视图定义 + FinalityRegistry

测试

[未核]

本 app 目录下 0 个 _test.go 文件。

跨 app 测试涉及 institution 行为的，主要在 tests/transfer/ 与 tests/e2e/（具体覆盖范围 [未核]）。

看代码推荐路径

cmd/institution/main.go:70-251 → 启动序列全貌。
cmd/institution/wire_gen.go:28-42 → 依赖注入图。
internal/biz/biz.go:38-127 → pendingTxStore 与 releasePendingTx 机制。
internal/biz/transfer_biz.go:80-285 → 两步转账（prepare → submit）。
internal/service/wallet_service.go → 钱包创建（CreateWallet:166）与关闭审批（UpdateWalletStatus:298 → submitWholesaleCloseApproval:331）工作流。
internal/worker/approval_worker.go:78,121 → BizHub 审批轮询与 CREATE/CLOSE 派发。
pkg/views/（外部）→ 4 对 View 的实现。

[未核] 与已知缺口

transfer_metrics.go（113 行）暴露 cbdc_institution_transfer_outcome_total，按 method（prepare/submit）与 outcome 维度计数；完整指标清单未逐项展开。
与 Endorser / Issuer / Auditor 是否存在直连调用（core.yaml fsc.endpoint.resolvers 列出 auditor/issuer/endorser1/institution-001 的 P2P 端点）。

cbdc-biz/app/institution ​

基本事实 ​

入口启动（main.go） ​

Wire DI 依赖图 ​

internal/biz ​

InstitutionWalletBiz 关键方法 ​

InstitutionTransferBiz 关键方法 ​

InstitutionTransactionBiz 关键方法 ​

InstitutionRedeemBiz 关键方法 ​

共享方法（biz.go） ​

internal/data ​

internal/service ​

internal/worker ​

internal/conf ​

configs ​

app 内 configs/config.yaml（Kratos 默认模板，非实际部署用） ​

实际部署用配置：cbdc-biz/conf/institution-001/core.yaml ​

Dockerfile ​

与其他 app 的关系 ​

出站 ​

入站 ​

与 cbdc-biz/pkg/ 的关系 ​

测试 ​

看代码推荐路径 ​

[未核] 与已知缺口 ​