# 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:

```java
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:

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

- [ ] **Step 2: Compile and run the existing exchange/payment tests**

Run:

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

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

- [ ] **Step 3: Commit the boundary-only refactor**

```bash
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:

```java
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:

```sql
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:

```java
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`.

```java
@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:

```bash
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**

```java
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:

```sql
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:

```sql
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:

```bash
mvn "-Dtest=WalletPrerequisiteProjectionServiceTest" test
```

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

- [ ] **Step 8: Commit the shared projection**

```bash
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:

```java
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:

```java
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:

```bash
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:

```java
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:

```bash
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**

```bash
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:

```java
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:

```java
@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:

```bash
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:

```java
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:

```java
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:

```java
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:

```bash
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**

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.