cbdc-central

Central 是央行管理服务与 React Web Console，HTTP 8000、内部 gRPC 8001。它不运行 FSC / Panurus，也不持有 BizHub 业务表。

职责

• 用户、角色、权限与 session；
• 密码策略、OTP 与 WebAuthn；
• 审批实例、任务、事件与执行命令；
• 管理操作审计与敏感字段脱敏；
• 站内通知与可选邮件发送；
• 通过 BizHub management RPC 管机构、节点、规则、费用、标记、标签和拒绝日志；
• 通过 Auditor client 获取审计数据；
• 提供 React / Vite 管理前端。

数据边界

Central 当前连接 cbdc_central，14 个 Ent entity 为：

approval_definition          approval_instance
approval_task                approval_task_assignee
approval_event               approval_executor_command
notification                 sys_audit_log
sys_role                     sys_role_permission
sys_session                  sys_user
sys_user_role                sys_webauthn_credential

BizHub 业务数据位于独立 cbdc_biz，Central 只能经 gRPC 访问。旧的“Central 与 BizHub 共库、Central 是所有 schema 权威”说明已经过时。

API 面

HTTP 8000 注册 Central Web 使用的全量服务，包括：

• CentralService、UserMgrService、AuditLogService；
• Approval instance / task / event；
• Transaction、Block Explorer、Statistics；
• Institution、Wallet、Wallet Lifecycle；
• Rule Groups、Auditor Ruleset、Fee、Marks、Tags；
• Settlement、Audit Rejection、Auditor Query；
• Notification。

内部 gRPC 8001 只暴露 Notification 与三个 Approval 服务。

到 BizHub 的调用

Central 配置显式指定 BizHub client cert/key，因为它没有 fsc.identity 可复用。BizHub management handlers 再用 mtls.RequireRoles(ctx, RoleCentral) 授权。

RBAC 与审计

权限码为 <resource>:<read|write>。新增 API 路径需要同步资源映射，否则只有登录校验而没有资源权限校验。

写操作在 internal/server/audit_filter.go 声明 route metadata；业务语义记录通过 audit.Record。sys_audit_log 只追加，敏感字段由 internal/audit/redact.go 集中脱敏。

审批与后台任务

审批流把“审批决定”与“业务执行”解耦：通过后产生 executor command，再由 ApprovalExecutorWorker 认领。邮件通知由 NotificationEmailWorker 发送。两者默认关闭，需要在配置中显式启用。

业务执行涉及机构、规则等 BizHub 数据时，handler 调 BizHub management client，而不是直接操作 BizHub 表。

Web Console

web/ 使用 React 19、Vite、React Router、Tailwind、shadcn/Radix、TanStack Query/Table、React Hook Form/Zod 与 Recharts。生产构建可嵌入 Central 二进制；host debug 时 controller 先构建 web/dist 并通过 CENTRAL_WEB_DIST 提供。

配置

server:
  http: { address: 0.0.0.0:8000 }
  grpc: { address: 0.0.0.0:8001 }
data:
  database:
    source: ... dbname=cbdc_central ...
upstreams:
  bizhub:
    address: ...:9000
    tls:
      enabled: true
      clientCert: /data/keys/node.crt
      clientKey: /data/keys/node.key
  auditor:
    address: ...:9750
    tls: { enabled: false }

server.security.adminDefaultPassword 首次启动必须通过配置或 CENTRAL_ADMIN_PASSWORD 提供。启用 OTP 前需要 32-byte hex encryption key；WebAuthn 需要正确的 RP ID 与浏览器 origin。

迁移与构建

cd cbdc-central
make migrate-diff name=<short_name>
make migrate-verify
make ent
make test
make build

数据库 DDL 由 central migrate one-shot 任务应用；普通服务启动不自动迁移。