opt-web — Hướng dẫn đọc source code

00 Dự án này là gì?

opt-web là PoC (Proof of Concept) chứng minh chiến lược migrate ~256 màn hình VB.NET của Optage sang Spring. Hiện đã hiện thực 4 màn hình mẫu (PoC scope), phần còn lại mới chỉ có khung điều hướng (nav shell).

Mục tiêu thiết kế của codebase: (1) dev VB cũ của Optage navigate được new↔old trong 1 bước, (2) dev Java mới hiểu được Clean Architecture, (3) mọi hành vi reproduce 1:1 so với VB (新旧比較 / so sánh cũ–mới).

01 Bản đồ nhanh — "Cái X nằm ở đâu?"

Bảng tra cứu thần tốc. Mỗi câu hỏi onboarding thường gặp → vị trí chính xác trong source. Các mục sẽ được đào sâu ở phần 7.

02 Tech stack & vì sao chọn

Đọc pom.xml là biết ngay bộ công cụ. Đây là stack "enterprise Java cổ điển nhưng bản mới" — chọn JSP thay vì SPA là chủ ý: bám sát mô hình form-render của VB WinForms để migrate cho an toàn.

03 Cây thư mục — nhìn 1 phát hiểu cả repo

Quy tắc vàng: mỗi màn hình legacy = 1 "bounded context" = 1 package con, bên trong chia thành 4 lớp (ring) y hệt nhau. Học thuộc 1 module là đọc được cả 4.

04 Clean Architecture — 4 vòng & "luật phụ thuộc"

Cốt lõi cần khắc cốt ghi tâm: phụ thuộc luôn hướng vào trong. Lớp ngoài biết lớp trong; lớp trong không bao giờ biết lớp ngoài. domain ở tâm — không import gì của Spring/MyBatis.

05 Giải phẫu 1 màn hình — CM06010 từ A→Z

Theo dấu nghiệp vụ "tìm kiếm đơn đăng ký" (検索) chạy xuyên qua cả 4 vòng. Đọc xong cái này, 3 màn hình kia bạn đọc trong 5 phút.

presentation Controller — cửa vào HTTP

Nhận request, validate, đổ Model, trả tên JSP. Lưu ý method shell() — "middleware thủ công" gắn nav + combo cho mọi screen.

@Controller
@RequestMapping("/api/cm06movirus/cm06010")   // route = registry legacy-map.yaml
@LegacyOrigin(module="CM06MoVirus", screen="CM06010", source="FrmCM06010.vb")
public class Cm06010MovirusController {
  private final Cm06010MovirusService service;   // gọi thẳng Service (không inbound port)
  private final NavCatalog nav;

  @PostMapping("/search")        // btnSearch_Click (FrmCM06010.vb L256)
  public String search(@Valid @ModelAttribute("form") Cm06010SearchForm form,
                       BindingResult binding, Model model) {
    shell(model);                       // ← gắn nav + combo (convention)
    if (form.isAllBlank())              // Chk_Form_Pvt: tất cả trống → M99043
      binding.reject("M99043", "すべての項目が入力/選択されていません。");
    if (binding.hasErrors()) { … return VIEW; }   // XỬ LÝ LỖI tại đây
    model.addAttribute("results", service.search(form.toCriteria()));
    return VIEW;                         // "cm06movirus/cm06010" → JSP
  }
}

application Service + Port — nghiệp vụ thuần

Service chỉ điều phối, gọi qua interface Port. Không một dòng MyBatis nào lọt vào đây.

@Service
public class Cm06010MovirusService {
  private final Cm06010SearchPort port;   // ← interface, KHÔNG phải Repository cụ thể
  public List<MoushiInfo> search(MoushiSearchCriteria c) {
    return port.searchMoushiInfo(c);        // ủy thác xuống infra qua port
  }
}

// application/port/Cm06010SearchPort.java — "hợp đồng" ra-DB
public interface Cm06010SearchPort {
  List<CodeName> findMenuKbnList();
  List<MoushiInfo> searchMoushiInfo(MoushiSearchCriteria criteria);
}

domain Entity / Criteria — không framework

@Data @NoArgsConstructor @AllArgsConstructor          // Lombok — OK trong domain
@LegacyOrigin(module="CM06MoVirus", screen="CM06010", source="FrmCM06010.vb:L332")
public class MoushiInfo {
  private String ukeNo;     // 受付番号 — CN.UKENO (cột grid 0)
  private String custName;  // お客さま名 — CASE cá nhân/pháp nhân
  private String kyakuNo;   // 顧客番号 — cột ẩn, dùng khi double-click
}

infrastructure Repository → Mapper → XML (DAO thật sự)

@Repository
public class Cm06010MovirusRepository implements Cm06010SearchPort {  // ← DIP
  private final Cm06010MovirusMapper mapper;
  @Override public List<MoushiInfo> searchMoushiInfo(MoushiSearchCriteria c){
    return mapper.searchMoushiInfo(c);   // ủy thác mỏng sang MyBatis
  }
}

@Mapper  public interface Cm06010MovirusMapper {  // SQL ở file .xml cùng tên
  List<MoushiInfo> searchMoushiInfo(MoushiSearchCriteria criteria);
}

SQL nằm trong resources/com/company/opt/optweb/cm06movirus/infrastructure/persistence/Cm06010MovirusMapper.xml — viết bằng MyBatis dynamic SQL (<if>, <choose>), reproduce 1:1 chuỗi SQL mà VB nối tay. Macro VB (F_LCOMMON, F_LKYAKU…) được giải thích trong comment đầu file XML.

procedure Stored-proc gateway — gọi Oracle nguyên xi

Khi legacy gọi Oracle package/proc, tuyệt đối không viết lại logic bằng Java. Gateway gọi CALL thẳng.

@Component
@LegacyOrigin(…, procedure="CCS_COMMON_PAC.SP_GET_VBUSERID")
public class Cm06010MovirusProcedureGateway {
  public String getVbUserId() {
    return jdbcTemplate.execute(
      con -> con.prepareCall("{ call CCS_COMMON_PAC.SP_GET_VBUSERID(?) }"),
      cs -> { cs.registerOutParameter(1, Types.VARCHAR); cs.execute();
              return cs.getString(1); });
  }
}

Lưu ý: chỉ cm06movirus hiện có procedure gateway. 3 màn hình kia chưa cần.

06 Vòng đời 1 request — "検索" đi qua những đâu

Từ lúc user bấm nút đến lúc bảng kết quả hiện ra. Mỗi mũi tên là 1 ranh giới vòng.

07 Tra cứu chi tiết — đúng các câu hỏi onboarding

Phần này trả lời sâu từng câu trong checklist. Mỗi thẻ: ở đâu · làm gì · ví dụ thật.

08 Quy định bắt buộc — đây là phần khác biệt nhất

Codebase này có một "luật neo về legacy" mà CI sẽ fail build nếu vi phạm. Hiểu nó trước khi commit dòng đầu tiên.

① @LegacyOrigin — mỗi class neo về 1 màn hình VB

Mọi class trong package bounded-context (controller, service, entity, mapper/repository, gateway) bắt buộc có @LegacyOrigin(module, screen, source). Đây là sợi dây để dev Optage trace new↔old trong 1 bước.

@LegacyOrigin(module="CM06MoVirus", screen="CM06010", source="FrmCM06010.vb")

② SoT = .nexa/legacy-map.yaml

File registry này map context ↔ legacyModule ↔ screen ↔ route ↔ label. Nó là chân lý; giá trị trong @LegacyOrigin và route được kiểm ngược lại registry, không phải chiều ngược.

③ Bảng đặt tên (neo = Anchored, idiom = Idiomatic)

④ Gác cổng tự động (sẽ fail CI nếu sai)

09 Quy trình thêm 1 màn hình mới

Khi được giao port màn hình CMxxxxx, đi đúng 5 bước này (rút từ legacy-origin-mapping.md §6).

1. Đăng ký vào registryĐảm bảo screen có trong .nexa/legacy-map.yaml với scope: poc.
2. Tạo package context + 4 ringTạo <ctx>/{presentation,application,application/port,domain,infrastructure/persistence}. Procedure gateway chỉ tạo khi có stored-proc.
3. Viết ControllerĐặt tên Cm<nnnnn><Ctx>Controller, gắn @LegacyOrigin + @RequestMapping = route trong registry. Đừng quên shell(model).
4. Domain + DAOEntity = Pascal(Table) có @LegacyOrigin; Port ở application/port; Repository implements Port; Mapper.xml co-located trong resources/…/persistence/.
5. JSP + chạy validatorView ở WEB-INF/views/<ctx>/cm<nnnnn>.jsp. Chạy python3 coding-rules/legacy-map-check.py → phải 0 hard-fail trước khi commit.

10 Gotchas khi migrate (đọc kẻo mất ngày)

Tổng hợp từ coding-rules/CODING-TIPS.md — những cái bẫy đã có người dẫm.