diff --git a/docs/superpowers/plans/2026-07-21-interface-wms-field-expansion.md b/docs/superpowers/plans/2026-07-21-interface-wms-field-expansion.md new file mode 100644 index 0000000..6a042f2 --- /dev/null +++ b/docs/superpowers/plans/2026-07-21-interface-wms-field-expansion.md @@ -0,0 +1,80 @@ +# Interface and WMS Field Expansion 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:** Persist and display the requested delivery, completion, and sales-shipment fields across FT363-INTERFACE and FT363-WMS. + +**Architecture:** Extend the existing port DTOs and service-to-domain mappings in FT363-INTERFACE, add nullable SQL Server columns and MyBatis mappings, then extend the existing WMS domain/query/table definitions. `requiredTm` reuses the existing `require_time` column for backward compatibility. + +**Tech Stack:** Java 8, Spring Boot 2.5, MyBatis XML, SQL Server, Thymeleaf, Bootstrap Table, JUnit. + +## Global Constraints + +- Preserve unrelated dirty-worktree changes. +- New database columns are nullable and migrations are idempotent. +- Keep existing endpoint response codes and transaction boundaries unchanged. +- Use exact API property names: `requiredTm`, `isExpedited`, `effectiveDate`, `expirationDate`, `oaProductShipNum`. + +### Task 1: Add failing contract and mapping tests + +**Files:** +- Create: `FT363-INTERFACE/ruoyi-admin/src/test/java/com/ruoyi/web/port/FieldExpansionContractTest.java` + +**Interfaces:** +- Consumes the three request DTOs and their detail DTO. +- Produces executable assertions for JSON binding and mapping source expectations. + +- [ ] **Step 1: Write failing tests** for JSON binding of all five exact names and for the new persistence properties. +- [ ] **Step 2: Run `mvn -pl ruoyi-admin -Dtest=FieldExpansionContractTest test`** and confirm failure because the properties do not yet exist. + +### Task 2: Extend FT363-INTERFACE DTOs and persistence mapping + +**Files:** +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/port/domain/DeliveryApplicationMsg.java` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/port/domain/CompletionRecordDetailMsg.java` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/port/domain/GoodsSaleSendMsg.java` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/out/outStock/domain/OutStockout.java` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/in/stockindetail/domain/StockinDetail.java` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/out/outStockDetail/domain/OutStockoutDetail.java` +- Modify: `ruoyi-admin/src/main/resources/mapper/out/OutStockoutMapper.xml` +- Modify: `ruoyi-admin/src/main/resources/mapper/in/StockinDetailMapper.xml` +- Modify: `ruoyi-admin/src/main/resources/mapper/out/OutStockoutDetailMapper.xml` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/port/service/impl/PortServiceImpl.java` + +- [ ] **Step 1:** Add DTO getters/setters using exact JSON names, retaining `requireTime` compatibility through an alias or equivalent setter. +- [ ] **Step 2:** Add nullable persistence properties and MyBatis result/select/insert mappings for `is_expedited`, `effective_date`, `expiration_date`, and `oa_product_ship_num`; map `requiredTm` to `requireTime`. +- [ ] **Step 3:** Map values in the three existing service methods without changing transaction or response behavior. +- [ ] **Step 4:** Run the focused contract tests and confirm they pass. + +### Task 3: Add idempotent SQL migration scripts + +**Files:** +- Create: `FT363-INTERFACE/sql/20260721_add_mes_field_expansion.sql` +- Create: `FT363-WMS/sql/20260721_add_mes_field_expansion.sql` + +- [ ] **Step 1:** Add `COL_LENGTH` guarded `ALTER TABLE` statements for `out_stockout.is_expedited`, `in_stockin_detail.effective_date`, `in_stockin_detail.expiration_date`, and `out_stockout_detail.oa_product_ship_num`. +- [ ] **Step 2:** Verify each statement is valid SQL Server syntax and can run repeatedly without attempting a duplicate column. + +### Task 4: Display fields in FT363-WMS + +**Files:** +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/out/outStock/domain/OutStockout.java` +- Modify: `ruoyi-admin/src/main/resources/mapper/out/OutStockoutMapper.xml` +- Modify: `ruoyi-admin/src/main/resources/templates/out/stockout.html` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/in/stockindetail/domain/StockinDetail.java` +- Modify: `ruoyi-admin/src/main/resources/mapper/in/StockinDetailMapper.xml` +- Modify: `ruoyi-admin/src/main/resources/templates/in/stockin/stockinManage.html` +- Modify: `ruoyi-admin/src/main/java/com/ruoyi/project/out/outStockDetail/domain/OutStockoutDetail.java` +- Modify: `ruoyi-admin/src/main/resources/mapper/out/OutStockoutDetailMapper.xml` +- Modify: `ruoyi-admin/src/main/resources/templates/out/stockout.html` + +- [ ] **Step 1:** Add the new result/select mappings and domain getters/setters in WMS. +- [ ] **Step 2:** Add visible Bootstrap Table columns with Chinese labels and a `0`/`1` formatter for expedited status. +- [ ] **Step 3:** Run static field/column checks and compile WMS. + +### Task 5: Full verification + +- [ ] **Step 1:** Run `mvn -pl ruoyi-admin -DskipTests compile` in FT363-INTERFACE. +- [ ] **Step 2:** Run focused and existing tests that do not require unavailable external databases. +- [ ] **Step 3:** Run `mvn -pl ruoyi-admin -DskipTests compile` in FT363-WMS. +- [ ] **Step 4:** Review `git diff` and `git status` in both repositories to ensure only scoped files changed. diff --git a/docs/superpowers/specs/2026-07-21-interface-wms-field-expansion-design.md b/docs/superpowers/specs/2026-07-21-interface-wms-field-expansion-design.md new file mode 100644 index 0000000..93b92a2 --- /dev/null +++ b/docs/superpowers/specs/2026-07-21-interface-wms-field-expansion-design.md @@ -0,0 +1,41 @@ +# Interface and WMS Field Expansion Design + +## Scope + +Extend three MES-to-WMS contracts without changing their existing business flow: + +- `getDeliveryApplicationMsg`: accept `requiredTm` and `isExpedited`. +- `getCompletionRecordMsg`: accept `effectiveDate` and `expirationDate` on each detail. +- `getGoodsSaleSendMsg`: accept `oaProductShipNum`. + +The existing `out_stockout.require_time` column is retained as the persistence target for the new API property `requiredTm`; the legacy API property `requireTime` remains accepted for compatibility where practical. + +## Data Flow + +`PortController` deserializes the request DTOs. `PortServiceImpl` maps DTO values into the existing WMS domain objects and MyBatis insert statements. WMS list/detail queries map the new columns into domain properties and Thymeleaf Bootstrap Table definitions display them. + +Field ownership: + +| API field | Domain/table | Physical column | WMS view | +| --- | --- | --- | --- | +| `requiredTm` | `OutStockout` / `out_stockout` | existing `require_time` | 出库主表需求时间 | +| `isExpedited` | `OutStockout` / `out_stockout` | new `is_expedited` | 出库主表是否加急 | +| `effectiveDate` | `StockinDetail` / `in_stockin_detail` | new `effective_date` | 入库明细生效日期 | +| `expirationDate` | `StockinDetail` / `in_stockin_detail` | new `expiration_date` | 入库明细失效日期 | +| `oaProductShipNum` | `OutStockoutDetail` / `out_stockout_detail` | new `oa_product_ship_num` | 出库明细 OA 产品发货流水号 | + +## Database Migration + +Provide an idempotent SQL Server script under `sql/` which uses `COL_LENGTH` checks before adding the four missing runtime columns and their `_finish` archive-table counterparts. The existing `require_time` column is not duplicated. New columns are nullable so older interface payloads and existing rows remain valid; matching archive columns preserve the existing `select *` archive procedures. + +## Compatibility and Errors + +Missing new fields are accepted as `null`/empty values and do not change existing insert behavior. `isExpedited` uses integer values `0` and `1` when supplied. Existing transaction and response handling remain unchanged. + +## Verification + +- DTO JSON binding tests assert the exact camel-case API names. +- Mapper XML checks assert every new property is present in result, select, insert, and value mappings where applicable. +- Service tests assert the three mapping paths copy values into persistence objects. +- Maven tests/compilation run for both projects where the local environment permits. +- Static checks verify WMS table columns use the exact new property names and Chinese labels.