更新员工资产信息归户规则设计与计划

docs/plans/2026-03-12-employee-asset-maintenance-backend-implementation.md

@@ -2,9 +2,9 @@
 
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
-**Goal:** Add backend support for employee asset maintenance, including aggregated employee detail/save, employee-asset cascade delete, and asynchronous asset import based on employee ID card linkage.
+**Goal:** Add backend support for employee asset maintenance, including aggregated employee detail/save, employee-asset cascade delete by employee family ID card, and asynchronous asset import that auto-resolves the owning employee from the asset holder ID card.
 
-**Architecture:** Keep employee maintenance on the existing `CcdiBaseStaff` aggregate, and introduce a new `CcdiAssetInfo` resource in `ccdi-info-collection`. Employee add/edit/detail/delete will orchestrate asset persistence inside transactions, while asset import will mirror the existing employee import flow with a dedicated controller, service, Redis task keys, and failure records.
+**Architecture:** Keep employee maintenance on the existing `CcdiBaseStaff` aggregate, and introduce a new `CcdiAssetInfo` resource in `ccdi-info-collection`. Asset rows use `family_id` for the owning employee ID card and `person_id` for the actual holder ID card. Employee add/edit/detail/delete will orchestrate asset persistence by `family_id` inside transactions, while asset import will mirror the existing employee import flow and resolve `family_id` from either the employee table or the employee family-relation table.
 
 **Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, XML mapper SQL, EasyExcel, Redis, Maven
 
@@ -22,18 +22,20 @@
 Create `ccdi_asset_info` with:
 
 - `asset_id BIGINT` auto increment primary key
-- `person_id VARCHAR(18)` storing employee `id_card`
+- `family_id VARCHAR(18)` storing owning employee `id_card`
+- `person_id VARCHAR(18)` storing actual asset holder `id_card`
 - business columns from the approved design
 - audit columns `create_by`, `create_time`, `update_by`, `update_time`
-- indexes `idx_person_id` and `idx_asset_main_type`
+- indexes `idx_family_id`, `idx_person_id`, and `idx_asset_main_type`
 
 **Step 2: Verify the script matches the approved constraints**
 
 Confirm the script:
 
 - does not include `asset_id` in any import-facing note
-- keeps the field name `person_id`
-- links by employee `id_card`, not `staff_id`
+- keeps the field names `family_id` and `person_id`
+- stores owning employee linkage in `family_id`
+- stores actual holder linkage in `person_id`
 
 **Step 3: Commit**
 
@@ -65,15 +67,19 @@ Add one DTO for nested employee-form submission and one VO for employee detail r
 
 `CcdiAssetInfoExcel` must exclude `asset_id` and include `person_id`.
 
+It must not require `family_id` in the import template because `family_id` is resolved automatically during import.
+
 **Step 4: Create mapper methods**
 
 Define methods for:
 
+- query by `family_id`
+- delete by `family_id`
+- delete by `family_id` list
 - query by `person_id`
-- delete by `person_id`
-- delete by `person_id` list
 - batch insert
 - import lookup by employee `id_card`
+- import lookup by employee family-relation ID card
 
 ### Task 3: Extend employee DTO and VO aggregation
 
@@ -123,10 +129,11 @@ Expected: PASS
 
 Cover these behaviors:
 
-- query all assets by `person_id`
+- query all assets by `family_id`
 - replace all assets for one employee
 - delete assets by one or more employee ID cards
 - ignore empty rows when replacing assets
+- preserve `person_id` as the actual holder while forcing `family_id` to the owning employee ID card
 
 **Step 2: Run test to verify it fails**
 
@@ -142,10 +149,10 @@ Expected: FAIL because the asset service does not exist yet.
 
 Implement methods:
 
-- `selectByPersonId`
-- `replaceByPersonId`
-- `deleteByPersonId`
-- `deleteByPersonIds`
+- `selectByFamilyId`
+- `replaceByFamilyId`
+- `deleteByFamilyId`
+- `deleteByFamilyIds`
 
 Use batch delete + batch insert.
 
@@ -176,6 +183,8 @@ Add or extend service tests for:
 - edit employee with changed `id_card`
 - detail query returns `assetInfoList`
 - delete employee cascades asset deletion
+- employee self-owned asset uses `family_id = person_id = employee.idCard`
+- employee family asset uses `family_id = employee.idCard` and `person_id = relative.idCard`
 
 **Step 2: Run test to verify it fails**
 
@@ -192,8 +201,9 @@ Expected: FAIL because employee service does not yet coordinate asset persistenc
 Update `CcdiBaseStaffServiceImpl` to:
 
 - inject `ICcdiAssetInfoService`
-- load assets during detail query
+- load assets during detail query by `family_id = employee.id_card`
 - save employee first, then replace assets by current employee `id_card`
+- for each asset row, set `family_id = employee.id_card` and preserve submitted `person_id`
 - capture old `id_card` during edit and clean old asset records when it changes
 - delete asset rows before deleting employee rows
 
@@ -220,7 +230,11 @@ Expected: PASS
 Cover:
 
 - import template entity excludes `asset_id`
-- import fails when `person_id` does not match an employee `id_card`
+- import template does not require `family_id`
+- import resolves `family_id` when `person_id` matches an employee `id_card`
+- import resolves `family_id` when `person_id` matches an employee family-relation ID card
+- import fails when `person_id` does not match either an employee or an employee family-relation ID card
+- import fails when one `person_id` maps to multiple employees
 - import stores failure records only for bad rows
 - import status and failure list use dedicated asset task keys
 
@@ -242,6 +256,7 @@ Mirror the employee import design with asset-specific names:
 - asynchronous import execution
 - failure record caching for 7 days
 - controller endpoints for template, upload, status, and failures
+- resolve `family_id` automatically from `person_id`
 
 **Step 4: Run the focused test again**
 
@@ -263,11 +278,13 @@ Expected: PASS
 
 Verify:
 
+- select by `family_id`
 - select by `person_id`
 - batch insert multiple assets
-- delete by one `person_id`
-- delete by multiple `person_id` values
+- delete by one `family_id`
+- delete by multiple `family_id` values
 - employee existence lookup by `id_card`
+- employee family-relation existence lookup by relative `id_card`
 
 **Step 2: Run test to verify it fails**
 
@@ -284,11 +301,13 @@ Expected: FAIL because the mapper XML SQL is incomplete.
 Add:
 
 - result map
+- select by `family_id`
 - select by `person_id`
-- delete by `person_id`
-- delete by `person_id` list
+- delete by `family_id`
+- delete by `family_id` list
 - batch insert
 - employee existence lookup
+- employee family-relation lookup
 
 **Step 4: Run the mapper test**