digital-rmb-backend/docs/superpowers/plans/2026-08-18-downstream-wallet-prerequisite-projection.md

Downstream Wallet Prerequisite Projection Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make modules 4 and 5 pull completed module 3 wallet-opening results on first access and initialize shared wallet runtime state without module 3 writing downstream process data.

Architecture: A shared transactional WalletPrerequisiteProjectionService reads completed module 3 fact tables with full user/school/class isolation and inserts only missing shared wallet runtime rows. Exchange and payment repositories invoke it before their existing runtime-state queries; existing rows are validated and never overwritten, so real balances and limit counters remain authoritative.

Tech Stack: Java 8-compatible code, Spring Boot 2.7, JdbcTemplate, Spring transactions, JUnit 5, MockMvc, AssertJ, H2/MySQL-compatible SQL.

Spec: docs/superpowers/specs/2026-08-18-downstream-wallet-prerequisite-projection-design.md

Global Constraints

• Module 3 fact tables remain read-only to modules 4 and 5.
• Every module 1 and module 3 lookup is scoped by user_id, school_id, and class_id.
• Projection is pull-based, transactional, idempotent, and insert-only for existing shared runtime rows.
• Entering a context endpoint must not create exchange orders, payment orders, or step logs.
• A module 5 payer needs module 4 wallet-owned currency; a payee only needs a completed module 3 wallet.
• Do not address unrelated full-suite error-code assertion failures.

---

Task 1: Put wallet private-key encryption in the shared boundary

Files:

• Create: src/main/java/com/yau/digitalrmb/shared/wallet/WalletPrivateKeyCipher.java
• Delete: src/main/java/com/yau/digitalrmb/exchange/infrastructure/crypto/WalletPrivateKeyCipher.java
• Modify: src/main/java/com/yau/digitalrmb/exchange/infrastructure/persistence/JdbcExchangeResourceRepository.java
• Modify: src/main/java/com/yau/digitalrmb/payment/infrastructure/persistence/JdbcPaymentResourceRepository.java
• Modify: src/test/java/com/yau/digitalrmb/exchange/interfaces/rest/ExchangeControllerTest.java
• Modify: src/test/java/com/yau/digitalrmb/payment/interfaces/rest/PaymentControllerTest.java

Interfaces:

• Consumes: SecurityProperties.getJwt().getSecret().

• Produces: WalletPrivateKeyCipher.encrypt(String) and WalletPrivateKeyCipher.decrypt(String) in com.yau.digitalrmb.shared.wallet.

• Step 1: Move the component without changing its implementation

Create the class under the shared package with the existing constructor and methods:

package com.yau.digitalrmb.shared.wallet;

import com.yau.digitalrmb.security.config.SecurityProperties;
import org.springframework.stereotype.Component;

import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Base64;

@Component
public class WalletPrivateKeyCipher {
    private static final int IV_LENGTH = 12;
    private final SecretKeySpec key;

    public WalletPrivateKeyCipher(SecurityProperties properties) {
        try {
            byte[] digest = MessageDigest.getInstance("SHA-256")
                    .digest(properties.getJwt().getSecret().getBytes(StandardCharsets.UTF_8));
            this.key = new SecretKeySpec(digest, "AES");
        } catch (Exception exception) {
            throw new IllegalStateException("钱包私钥加密组件初始化失败", exception);
        }
    }

    public String encrypt(String privateKey) {
        try {
            byte[] iv = new byte[IV_LENGTH];
            new SecureRandom().nextBytes(iv);
            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
            cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(128, iv));
            byte[] encrypted = cipher.doFinal(privateKey.getBytes(StandardCharsets.US_ASCII));
            byte[] output = new byte[iv.length + encrypted.length];
            System.arraycopy(iv, 0, output, 0, iv.length);
            System.arraycopy(encrypted, 0, output, iv.length, encrypted.length);
            return Base64.getEncoder().encodeToString(output);
        } catch (Exception exception) {
            throw new IllegalStateException("钱包私钥加密失败", exception);
        }
    }

    public String decrypt(String value) {
        try {
            byte[] input = Base64.getDecoder().decode(value);
            byte[] iv = new byte[IV_LENGTH];
            byte[] encrypted = new byte[input.length - IV_LENGTH];
            System.arraycopy(input, 0, iv, 0, iv.length);
            System.arraycopy(input, iv.length, encrypted, 0, encrypted.length);
            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
            cipher.init(Cipher.DECRYPT_MODE, key, new GCMParameterSpec(128, iv));
            return new String(cipher.doFinal(encrypted), StandardCharsets.US_ASCII);
        } catch (Exception exception) {
            throw new IllegalStateException("钱包私钥解密失败", exception);
        }
    }
}

Delete the old class and replace all four imports with:

import com.yau.digitalrmb.shared.wallet.WalletPrivateKeyCipher;

• Step 2: Compile and run the existing exchange/payment tests

Run:

mvn -DskipTests compile
mvn "-Dtest=ExchangeControllerTest,PaymentControllerTest" test

Expected: compilation succeeds; 3 tests pass with 0 failures.

• Step 3: Commit the boundary-only refactor

git add src/main/java/com/yau/digitalrmb/shared/wallet/WalletPrivateKeyCipher.java src/main/java/com/yau/digitalrmb/exchange/infrastructure/crypto/WalletPrivateKeyCipher.java src/main/java/com/yau/digitalrmb/exchange/infrastructure/persistence/JdbcExchangeResourceRepository.java src/main/java/com/yau/digitalrmb/payment/infrastructure/persistence/JdbcPaymentResourceRepository.java src/test/java/com/yau/digitalrmb/exchange/interfaces/rest/ExchangeControllerTest.java src/test/java/com/yau/digitalrmb/payment/interfaces/rest/PaymentControllerTest.java
git commit -m "refactor: share wallet private key cipher"

---

Task 2: Project completed module 3 facts into shared wallet runtime state

Files:

• Create: src/main/java/com/yau/digitalrmb/shared/wallet/WalletPrerequisiteReference.java
• Create: src/main/java/com/yau/digitalrmb/shared/wallet/WalletPrerequisiteProjectionService.java
• Create: src/test/java/com/yau/digitalrmb/shared/wallet/WalletPrerequisiteProjectionServiceTest.java
• Create: src/test/java/com/yau/digitalrmb/testsupport/WalletOpeningTestData.java
• Modify: src/test/resources/schema.sql

Interfaces:

• Consumes: InstitutionKeySubject, module 3 fact rows, module 1 institution identifier, WalletPrivateKeyCipher.
• Produces:

public final class WalletPrerequisiteReference {
    public String getUserId();
    public long getSchoolId();
    public long getClassId();
    public String getWalletId();
    public String getBankCode();
    public String getOrganizationId();
}

public class WalletPrerequisiteProjectionService {
    public WalletPrerequisiteReference ensureForSubject(InstitutionKeySubject subject);
    public WalletPrerequisiteReference ensureForWallet(String walletId);
}

• Step 1: Add module 3 source tables to the H2 test schema

Append H2-compatible definitions matching the production columns used by the projector. Define all columns below, including audit/scope columns, so production SQL is exercised unchanged:

CREATE TABLE IF NOT EXISTS wallet_application (
  id BIGINT PRIMARY KEY, user_id VARCHAR(36) NOT NULL, school_id BIGINT NOT NULL, class_id BIGINT NOT NULL,
  account_bank VARCHAR(100), bank_card_number VARCHAR(30), account_balance DECIMAL(20,2), selected_bank VARCHAR(100),
  wallet_type VARCHAR(20), application_id VARCHAR(64), status VARCHAR(32) NOT NULL,
  created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL, created_by VARCHAR(64) NOT NULL,
  updated_by VARCHAR(64) NOT NULL, deleted BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE TABLE IF NOT EXISTS wallet_identifier_generation (
  id BIGINT PRIMARY KEY, user_id VARCHAR(36) NOT NULL, school_id BIGINT NOT NULL, class_id BIGINT NOT NULL,
  wallet_identifier VARCHAR(128), cert_private_key VARCHAR(512), cert_public_key VARCHAR(512),
  cert_serial_number VARCHAR(64), cert_issued_time VARCHAR(20), status VARCHAR(32) NOT NULL,
  created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL, created_by VARCHAR(64) NOT NULL,
  updated_by VARCHAR(64) NOT NULL, deleted BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE TABLE IF NOT EXISTS central_wallet_registration (
  id BIGINT PRIMARY KEY, user_id VARCHAR(36) NOT NULL, school_id BIGINT NOT NULL, class_id BIGINT NOT NULL,
  wallet_id VARCHAR(128), cb_root_signature VARCHAR(512), wallet_registered BOOLEAN NOT NULL DEFAULT FALSE,
  sent BOOLEAN NOT NULL DEFAULT FALSE, status VARCHAR(32) NOT NULL,
  created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL, created_by VARCHAR(64) NOT NULL,
  updated_by VARCHAR(64) NOT NULL, deleted BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE TABLE IF NOT EXISTS smart_contract_generation (
  id BIGINT PRIMARY KEY, user_id VARCHAR(36) NOT NULL, school_id BIGINT NOT NULL, class_id BIGINT NOT NULL,
  wallet_id VARCHAR(128), wallet_type VARCHAR(30), single_payment_limit VARCHAR(30), daily_payment_limit VARCHAR(30),
  annual_payment_limit VARCHAR(30), balance_ceiling VARCHAR(30), validity VARCHAR(20), contract_plaintext VARCHAR(1000),
  contract_digest VARCHAR(128), contract_id VARCHAR(64), contract_effective_time VARCHAR(20), sent BOOLEAN NOT NULL DEFAULT FALSE,
  status VARCHAR(32) NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL,
  created_by VARCHAR(64) NOT NULL, updated_by VARCHAR(64) NOT NULL, deleted BOOLEAN NOT NULL DEFAULT FALSE
);
CREATE TABLE IF NOT EXISTS central_wallet_activation (
  id BIGINT PRIMARY KEY, user_id VARCHAR(36) NOT NULL, school_id BIGINT NOT NULL, class_id BIGINT NOT NULL,
  wallet_id VARCHAR(128), wallet_activated BOOLEAN NOT NULL DEFAULT FALSE, wallet_register_status VARCHAR(32),
  cb_final_signature VARCHAR(512), final_time VARCHAR(20), final_sent BOOLEAN NOT NULL DEFAULT FALSE,
  status VARCHAR(32) NOT NULL, created_at TIMESTAMP NOT NULL, updated_at TIMESTAMP NOT NULL,
  created_by VARCHAR(64) NOT NULL, updated_by VARCHAR(64) NOT NULL, deleted BOOLEAN NOT NULL DEFAULT FALSE
);

• Step 2: Write failing integration tests for incomplete, complete, idempotent, and isolated projection

Create a shared test-data utility so all three integration test classes seed the same module 3 completion contract:

public final class WalletOpeningTestData {
    private WalletOpeningTestData() {}

    public static void insertCompletedWallet(JdbcTemplate jdbc, long baseId, String userId,
            long schoolId, long classId, String walletId, String privateKey, String publicKey,
            String bankName, String cardNumber, BigDecimal bankBalance) {
        jdbc.update("INSERT INTO wallet_application (id,user_id,school_id,class_id,account_bank,bank_card_number," +
                "account_balance,selected_bank,wallet_type,application_id,status,created_at,updated_at,created_by,updated_by,deleted) " +
                "VALUES (?,?,?,?,?,?,?,?,? ,?,'SUBMITTED',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
                baseId, userId, schoolId, classId, bankName, cardNumber, bankBalance, bankName, "TYPE_II", "APP_" + baseId);
        jdbc.update("INSERT INTO wallet_identifier_generation (id,user_id,school_id,class_id,wallet_identifier," +
                "cert_private_key,cert_public_key,cert_serial_number,cert_issued_time,status,created_at,updated_at,created_by,updated_by,deleted) " +
                "VALUES (?,?,?,?,?,?,?,?,?,'CERT_ISSUED',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
                baseId + 1, userId, schoolId, classId, walletId, privateKey, publicKey, "CERT_" + baseId, "20260818090000");
        jdbc.update("INSERT INTO central_wallet_registration (id,user_id,school_id,class_id,wallet_id,cb_root_signature," +
                "wallet_registered,sent,status,created_at,updated_at,created_by,updated_by,deleted) " +
                "VALUES (?,?,?,?,?,'CB_ROOT_TEST',TRUE,TRUE,'SENT',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
                baseId + 2, userId, schoolId, classId, walletId);
        jdbc.update("INSERT INTO smart_contract_generation (id,user_id,school_id,class_id,wallet_id,wallet_type," +
                "single_payment_limit,daily_payment_limit,annual_payment_limit,balance_ceiling,validity,contract_plaintext," +
                "contract_digest,contract_id,contract_effective_time,sent,status,created_at,updated_at,created_by,updated_by,deleted) " +
                "VALUES (?,?,?,?,?,'TYPE_II','50000.00','100000.00','500000.00','500000.00','长期有效'," +
                "'CONTRACT_TEXT','0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',?," +
                "'20260818090000',TRUE,'SENT',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
                baseId + 3, userId, schoolId, classId, walletId, "CONTRACT_" + baseId);
        jdbc.update("INSERT INTO central_wallet_activation (id,user_id,school_id,class_id,wallet_id,wallet_activated," +
                "wallet_register_status,cb_final_signature,final_time,final_sent,status,created_at,updated_at,created_by,updated_by,deleted) " +
                "VALUES (?,?,?,?,?,TRUE,'AVAILABLE','CB_FINAL_TEST','20260818090000',TRUE,'FINAL_SENT'," +
                "CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
                baseId + 4, userId, schoolId, classId, walletId);
    }

    public static void deleteWalletFacts(JdbcTemplate jdbc, String userId) {
        jdbc.update("DELETE FROM central_wallet_activation WHERE user_id=?", userId);
        jdbc.update("DELETE FROM smart_contract_generation WHERE user_id=?", userId);
        jdbc.update("DELETE FROM central_wallet_registration WHERE user_id=?", userId);
        jdbc.update("DELETE FROM wallet_identifier_generation WHERE user_id=?", userId);
        jdbc.update("DELETE FROM wallet_application WHERE user_id=?", userId);
    }
}

Create @SpringBootTest tests using real JdbcTemplate and the real cipher. Seed unique IDs and clean them in @AfterEach.

@Test
void incompleteModuleThreeCreatesNoSharedRuntimeRows() {
    jdbc.update("INSERT INTO central_wallet_activation (id,user_id,school_id,class_id,wallet_id,wallet_activated," +
            "final_sent,status,created_at,updated_at,created_by,updated_by,deleted) " +
            "VALUES (?,?,?,?,?,FALSE,FALSE,'PENDING',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP,'test','test',FALSE)",
            ACTIVATION_ID, SUBJECT_USER, SCHOOL_ID, CLASS_ID, WALLET_ID);
    assertThatThrownBy(() -> service.ensureForSubject(subject()))
        .isInstanceOf(BusinessException.class)
        .hasMessageContaining("个人数字钱包开通");
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM digital_wallet WHERE user_id=?", Integer.class, SUBJECT_USER)).isZero();
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM simulated_bank_account WHERE user_id=?", Integer.class, SUBJECT_USER)).isZero();
}

@Test
void completedModuleThreeCreatesAllSharedRuntimeRows() {
    WalletOpeningTestData.insertCompletedWallet(jdbc, 980000L, SUBJECT_USER, SCHOOL_ID, CLASS_ID,
            WALLET_ID, keyPair.getPrivateKey(), keyPair.getPublicKey(), "测试银行", "6216610100001234567", new BigDecimal("50000.00"));
    seedInstitutionIdentifier(SUBJECT_USER, SCHOOL_ID, CLASS_ID, BANK_CODE, "ORG_EXPECTED", true);
    WalletPrerequisiteReference reference = service.ensureForSubject(subject());
    assertThat(reference.getWalletId()).isEqualTo(WALLET_ID);
    assertThat(reference.getOrganizationId()).isEqualTo("ORG_EXPECTED");
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM digital_wallet WHERE wallet_id=?", Integer.class, WALLET_ID)).isEqualTo(1);
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM wallet_certificate WHERE wallet_id=?", Integer.class, WALLET_ID)).isEqualTo(1);
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM wallet_contract WHERE wallet_id=?", Integer.class, WALLET_ID)).isEqualTo(1);
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM wallet_bank_binding WHERE wallet_id=?", Integer.class, WALLET_ID)).isEqualTo(1);
}

@Test
void repeatedProjectionDoesNotOverwriteMutableRuntimeStateOrModuleThreeFacts() {
    WalletOpeningTestData.insertCompletedWallet(jdbc, 980000L, SUBJECT_USER, SCHOOL_ID, CLASS_ID,
            WALLET_ID, keyPair.getPrivateKey(), keyPair.getPublicKey(), "测试银行", "6216610100001234567", new BigDecimal("50000.00"));
    seedInstitutionIdentifier(SUBJECT_USER, SCHOOL_ID, CLASS_ID, BANK_CODE, "ORG_EXPECTED", true);
    service.ensureForSubject(subject());
    jdbc.update("UPDATE digital_wallet SET balance=321.00,frozen_amount=20.00 WHERE wallet_id=?", WALLET_ID);
    jdbc.update("UPDATE wallet_contract SET daily_used_amount=45.00 WHERE wallet_id=?", WALLET_ID);
    String activationUpdatedAt = jdbc.queryForObject("SELECT CAST(updated_at AS VARCHAR) FROM central_wallet_activation WHERE id=?", String.class, ACTIVATION_ID);
    service.ensureForSubject(subject());
    assertThat(jdbc.queryForObject("SELECT balance FROM digital_wallet WHERE wallet_id=?", BigDecimal.class, WALLET_ID)).isEqualByComparingTo("321.00");
    assertThat(jdbc.queryForObject("SELECT daily_used_amount FROM wallet_contract WHERE wallet_id=?", BigDecimal.class, WALLET_ID)).isEqualByComparingTo("45.00");
    assertThat(jdbc.queryForObject("SELECT CAST(updated_at AS VARCHAR) FROM central_wallet_activation WHERE id=?", String.class, ACTIVATION_ID)).isEqualTo(activationUpdatedAt);
}

@Test
void sameBankCodeFromAnotherScopeCannotSupplyOrganizationId() {
    WalletOpeningTestData.insertCompletedWallet(jdbc, 980000L, SUBJECT_USER, SCHOOL_ID, CLASS_ID,
            WALLET_ID, keyPair.getPrivateKey(), keyPair.getPublicKey(), "测试银行", "6216610100001234567", new BigDecimal("50000.00"));
    seedInstitutionIdentifier(SUBJECT_USER, SCHOOL_ID, CLASS_ID, BANK_CODE, "ORG_EXPECTED", true);
    seedInstitutionIdentifier("other-user", SCHOOL_ID + 1, CLASS_ID + 1, BANK_CODE, "ORG_WRONG", true);
    assertThat(service.ensureForWallet(WALLET_ID).getOrganizationId()).isEqualTo("ORG_EXPECTED");
}

• Step 3: Run the new test and verify RED

Run:

mvn "-Dtest=WalletPrerequisiteProjectionServiceTest" test

Expected: test compilation fails because WalletPrerequisiteProjectionService and WalletPrerequisiteReference do not exist. This is the intended RED condition.

• Step 4: Implement the immutable reference

public final class WalletPrerequisiteReference {
    private final String userId;
    private final long schoolId;
    private final long classId;
    private final String walletId;
    private final String bankCode;
    private final String organizationId;

    public WalletPrerequisiteReference(String userId, long schoolId, long classId,
            String walletId, String bankCode, String organizationId) {
        this.userId = userId;
        this.schoolId = schoolId;
        this.classId = classId;
        this.walletId = walletId;
        this.bankCode = bankCode;
        this.organizationId = organizationId;
    }

    public String getUserId() { return userId; }
    public long getSchoolId() { return schoolId; }
    public long getClassId() { return classId; }
    public String getWalletId() { return walletId; }
    public String getBankCode() { return bankCode; }
    public String getOrganizationId() { return organizationId; }
}

• Step 5: Implement transactional source validation and lookup

Annotate both public methods with @Transactional. ensureForSubject must query each module 3 table using the same three scope columns, deleted=FALSE, expected completion state, descending created_at, and LIMIT 1. Link identifier, registration, and contract rows to the activation wallet ID. Query module 1 with all scope columns:

SELECT bank_code,institution_identifier
FROM institution_identifier_application
WHERE user_id=? AND school_id=? AND class_id=?
  AND status IN ('ISSUED','FEEDBACKED') AND deleted=FALSE
  AND bank_code IS NOT NULL AND institution_identifier IS NOT NULL
ORDER BY created_at DESC LIMIT 1

ensureForWallet must locate exactly one completed activation by wallet_id, wallet_activated=TRUE, final_sent=TRUE, non-null final signature, and deleted=FALSE, then delegate with the located subject. Zero matches returns the same prerequisite validation error; more than one scope returns a data-conflict error.

• Step 6: Implement insert-only runtime projection

Use deterministic account ID ACCOUNT_ plus UUID.nameUUIDFromBytes((userId + "|" + bankCode).getBytes(UTF_8)). Parse yyyyMMddHHmmss timestamps when possible, otherwise use CURRENT_TIMESTAMP. Insert in this order:

INSERT INTO simulated_bank_account
(account_id,user_id,bank_code,bank_name,card_number,card_last4,balance,frozen_amount,status,created_at,updated_at)
VALUES (?,?,?,?,?,?,?,0,'ACTIVE',CURRENT_TIMESTAMP,CURRENT_TIMESTAMP)

INSERT INTO digital_wallet
(wallet_id,user_id,wallet_type,status,balance,frozen_amount,central_bank_confirmation_signature,opened_at,created_at,updated_at)
VALUES (?,?,?,'ACTIVE',0,0,?,?,CURRENT_TIMESTAMP,CURRENT_TIMESTAMP)

INSERT INTO wallet_certificate
(certificate_serial,wallet_id,public_key,encrypted_private_key,filing_status,central_bank_root_signature,status,issued_at)
VALUES (?,?,?,?, 'REGISTERED',?,'VALID',?)

INSERT INTO wallet_contract
(contract_id,wallet_id,wallet_type,single_payment_limit,daily_payment_limit,annual_payment_limit,balance_limit,
 valid_until,original_text,digest,status,daily_used_amount,daily_counter_date,annual_used_amount,annual_counter_year,created_at,updated_at)
VALUES (?,?,?,?,?,?,?,NULL,?,?,'ACTIVE',0,NULL,0,NULL,CURRENT_TIMESTAMP,CURRENT_TIMESTAMP)

INSERT INTO wallet_bank_binding (wallet_id,bank_account_id,status,bound_at)
VALUES (?,?,'BOUND',CURRENT_TIMESTAMP)

Before each insert, query by its primary/unique business key. If a row exists, validate immutable ownership fields and skip the insert. Catch DuplicateKeyException, re-read, and run the same validation; never use an updating upsert. Encrypt the module 3 certificate private key with WalletPrivateKeyCipher.encrypt only when inserting a missing certificate.

• Step 7: Run the new test and verify GREEN

Run:

mvn "-Dtest=WalletPrerequisiteProjectionServiceTest" test

Expected: 4 tests pass with 0 failures and 0 errors.

• Step 8: Commit the shared projection

git add src/main/java/com/yau/digitalrmb/shared/wallet src/test/java/com/yau/digitalrmb/shared/wallet/WalletPrerequisiteProjectionServiceTest.java src/test/java/com/yau/digitalrmb/testsupport/WalletOpeningTestData.java src/test/resources/schema.sql
git commit -m "feat: project completed wallet prerequisites on demand"

---

Task 3: Make module 4 pull module 3 prerequisites

Files:

• Modify: src/main/java/com/yau/digitalrmb/exchange/infrastructure/persistence/JdbcExchangeResourceRepository.java
• Modify: src/test/java/com/yau/digitalrmb/exchange/interfaces/rest/ExchangeControllerTest.java

Interfaces:

• Consumes: WalletPrerequisiteProjectionService.ensureForSubject(InstitutionKeySubject).

• Produces: unchanged ExchangeResourceRepository.loadContext(ExchangeActor) API.

• Step 1: Rewrite exchange test setup to seed module 3 facts, not shared runtime rows

Keep module 1 identifiers, keys, module 2 bank currency, and ownership setup. Replace direct inserts into the five shared wallet tables with:

WalletOpeningTestData.insertCompletedWallet(jdbc, 990100L, USER_ID, 1999L, 2999L,
        "WALLET_EXCHANGE_TEST", walletKey.getPrivateKey(), walletKey.getPublicKey(),
        "中国银行北京分行", "6216610100001234567", new BigDecimal("50000.00"));

Add assertions to the successful context test:

assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM currency_exchange_order", Integer.class)).isZero();
assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM exchange_step_log", Integer.class)).isZero();
assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM digital_wallet WHERE user_id=?", Integer.class, USER_ID)).isEqualTo(1);

Change doesNotCreateDemoWalletWhenWalletOpeningOutputIsMissing so it deletes module 3 fact rows as well as shared rows and retains the assertion that no wallet is created.

• Step 2: Run exchange tests and verify RED

Run:

mvn "-Dtest=ExchangeControllerTest" test

Expected: the successful context test returns 400 because the repository still reads shared rows without invoking the projector.

• Step 3: Inject and invoke the projector

Add WalletPrerequisiteProjectionService to the repository constructor and start loadContext with:

InstitutionKeySubject subject = new InstitutionKeySubject(actor.getUserId(), actor.getSchoolId(), actor.getClassId());
walletPrerequisiteProjectionService.ensureForSubject(subject);
Institution institution = loadIssuedInstitution(actor);

Do not invoke the projector from module 3 services or controllers.

• Step 4: Run exchange tests and verify GREEN

Run:

mvn "-Dtest=ExchangeControllerTest" test

Expected: both exchange tests pass. The full five-step exchange still updates shared balances and ownership, while the missing-prerequisite test creates no shared rows.

• Step 5: Commit module 4 integration

git add src/main/java/com/yau/digitalrmb/exchange/infrastructure/persistence/JdbcExchangeResourceRepository.java src/test/java/com/yau/digitalrmb/exchange/interfaces/rest/ExchangeControllerTest.java
git commit -m "feat: load module three wallet data for exchange"

---

Task 4: Make module 5 pull both parties and enforce scoped identifiers

Files:

• Modify: src/main/java/com/yau/digitalrmb/payment/domain/repository/PaymentResourceRepository.java
• Modify: src/main/java/com/yau/digitalrmb/payment/application/service/PaymentApplicationService.java
• Modify: src/main/java/com/yau/digitalrmb/payment/infrastructure/persistence/JdbcPaymentResourceRepository.java
• Modify: src/test/java/com/yau/digitalrmb/payment/interfaces/rest/PaymentControllerTest.java

Interfaces:

• Consumes: ensureForSubject for payer and ensureForWallet for payee.
• Changes repository API to:

PaymentContext loadContext(PaymentActor actor, String payeeWalletId);

• Step 1: Add failing payment association tests

Seed completed module 3 facts for both users. For the payer, retain an already-existing shared wallet with balance 200.00 and module 4 WALLET/AVAILABLE coins; this represents completed module 4. Do not seed payee shared rows. Assert context access projects only the payee and creates no payment order:

@Test
void loadsPayeeFromCompletedModuleThreeWithoutCreatingPaymentOrder() throws Exception {
    jdbc.update("DELETE FROM wallet_bank_binding WHERE wallet_id=?", PAYEE_WALLET);
    jdbc.update("DELETE FROM wallet_certificate WHERE wallet_id=?", PAYEE_WALLET);
    jdbc.update("DELETE FROM simulated_bank_account WHERE user_id=?", PAYEE_USER);
    jdbc.update("DELETE FROM digital_wallet WHERE wallet_id=?", PAYEE_WALLET);

    mockMvc.perform(get("/api/v1/payments/context")
            .param("payeeWalletId", PAYEE_WALLET).with(payer()))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.data.payee.walletId").value(PAYEE_WALLET));

    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM digital_wallet WHERE wallet_id=?", Integer.class, PAYEE_WALLET)).isEqualTo(1);
    assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM payment_order", Integer.class)).isZero();
}

Add a second test with the same bank code in another school/class and assert payer/payee organizationId values come from their own scoped module 1 records. Add a third test where the payer has completed module 3 but has no WALLET/AVAILABLE coins; create and sign the request, then assert /payer-bank-process returns 400 and no ownership transfer is created.

• Step 2: Run payment tests and verify RED

Run:

mvn "-Dtest=PaymentControllerTest" test

Expected: payee context returns 400 because no shared payee row exists, or the scope assertion returns the other user's organization identifier.

• Step 3: Pass the complete actor through the payment repository boundary

Change both service call sites:

return resourceRepository.loadContext(actor, payeeWalletId);
PaymentContext context = resourceRepository.loadContext(actor, command.getPayeeWalletId());

Update the interface and implementation signature to use PaymentActor.

• Step 4: Pull payer and payee prerequisites before participant queries

Implement:

WalletPrerequisiteReference payerRef = projector.ensureForSubject(
    new InstitutionKeySubject(actor.getUserId(), actor.getSchoolId(), actor.getClassId()));
WalletPrerequisiteReference payeeRef = projector.ensureForWallet(payeeWalletId);
PaymentParticipant payer = loadParticipant(payerRef);
PaymentParticipant payee = loadParticipant(payeeRef);

Replace the dynamic where SQL and unscoped organizationId(bankCode) method with a fixed wallet query:

private PaymentParticipant loadParticipant(WalletPrerequisiteReference reference) {
    List<PaymentParticipant> values = jdbc.query(
            "SELECT w.user_id,w.wallet_id,w.wallet_type,cert.certificate_serial,cert.public_key," +
            "a.bank_code,a.bank_name,w.balance,COALESCE(w.frozen_amount,0) frozen_amount " +
            "FROM digital_wallet w JOIN wallet_certificate cert ON cert.wallet_id=w.wallet_id " +
            "AND cert.status='VALID' AND cert.filing_status='REGISTERED' " +
            "JOIN wallet_bank_binding binding ON binding.wallet_id=w.wallet_id AND binding.status='BOUND' " +
            "JOIN simulated_bank_account a ON a.account_id=binding.bank_account_id AND a.status='ACTIVE' " +
            "WHERE w.wallet_id=? AND w.user_id=? AND w.status='ACTIVE' " +
            "AND w.central_bank_confirmation_signature IS NOT NULL",
            (rs, row) -> new PaymentParticipant(rs.getString("user_id"), rs.getString("wallet_id"),
                    rs.getString("wallet_type"), rs.getString("certificate_serial"), rs.getString("public_key"),
                    rs.getString("bank_code"), rs.getString("bank_name"), reference.getOrganizationId(),
                    rs.getBigDecimal("balance"), rs.getBigDecimal("frozen_amount")),
            reference.getWalletId(), reference.getUserId());
    if (values.isEmpty()) throw validation("付款方或收款方钱包运行态不存在或状态异常");
    return values.get(0);
}

Delete the query that selects institution_identifier_application by bank_code only. The scoped organization ID must come from the projection reference.

• Step 5: Run payment tests and verify GREEN

Run:

mvn "-Dtest=PaymentControllerTest" test

Expected: all payment tests pass; payee-only module 3 data is readable, scoped organization IDs are correct, and a payer without module 4 coins cannot proceed through payer-bank processing.

• Step 6: Commit module 5 integration

git add src/main/java/com/yau/digitalrmb/payment/domain/repository/PaymentResourceRepository.java src/main/java/com/yau/digitalrmb/payment/application/service/PaymentApplicationService.java src/main/java/com/yau/digitalrmb/payment/infrastructure/persistence/JdbcPaymentResourceRepository.java src/test/java/com/yau/digitalrmb/payment/interfaces/rest/PaymentControllerTest.java
git commit -m "feat: load scoped wallet prerequisites for payment"

---

Task 5: Verify the complete module chain and document actual failures

Files:

• Modify only if verification exposes a regression caused by Tasks 1-4.

Interfaces:

• Consumes: completed implementation from Tasks 1-4.

• Produces: reproducible compile/test evidence and a clean tracked worktree.

• Step 1: Check formatting, conflicts, and production compilation

Run:

git diff --check
rg -n "^(<<<<<<<|=======|>>>>>>>)" src
mvn -DskipTests compile

Expected: git diff --check and compile exit 0; rg finds no conflict markers.

• Step 2: Run the focused module-chain tests

Run:

mvn "-Dtest=WalletPrerequisiteProjectionServiceTest,DigitalCurrencyGenerationStockIntegrationTest,ExchangeControllerTest,PaymentControllerTest" test

Expected: all focused tests pass with 0 failures and 0 errors.

• Step 3: Run the full suite without hiding existing failures

Run:

mvn test

Expected: report the exact total, failure count, and test names. Fix only failures introduced by Tasks 1-4; retain and explicitly report unrelated existing failures such as string-versus-numeric API error-code assertions.

• Step 4: Verify repository state and module 3 write isolation

Run:

rg -n "UPDATE (wallet_application|bank_received_wallet_application|wallet_verification_record|wallet_identifier_generation|wallet_registration_request|central_wallet_registration|smart_contract_generation|central_wallet_activation)" src/main/java/com/yau/digitalrmb/exchange src/main/java/com/yau/digitalrmb/payment src/main/java/com/yau/digitalrmb/shared/wallet
git status --short --branch
git log --oneline -6

Expected: no downstream update statements target module 3 fact tables. Only user-owned pre-existing untracked documents may remain outside the committed implementation.