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

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`
+- keeps the field names `family_id` and `person_id`
-- links by employee `id_card`, not `staff_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`
+- `selectByFamilyId`
-- `replaceByPersonId`
+- `replaceByFamilyId`
-- `deleteByPersonId`
+- `deleteByFamilyId`
-- `deleteByPersonIds`
+- `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 one `family_id`
-- delete by multiple `person_id` values
+- 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 `family_id`
-- delete by `person_id` list
+- delete by `family_id` list
 - batch insert
 - employee existence lookup
+- employee family-relation lookup
 
 **Step 4: Run the mapper test**
 

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

@@ -6,8 +6,14 @@
 本次设计基于 `2026-03-12` 确认了以下业务约束：
 
 - 资产表保留字段名 `person_id`
-- `person_id` 存员工身份证号，关联 `ccdi_base_staff.id_card`
+- 资产表新增 `family_id`
+- `family_id` 存归属员工身份证号
+- `person_id` 存资产实际持有人身份证号
+- 员工本人资产：`family_id = person_id = 员工身份证号`
+- 员工亲属资产：`family_id = 员工身份证号`，`person_id = 亲属身份证号`
 - `asset_id` 改为数据库自增主键，不出现在导入模板中
+- 资产导入模板不要求填写 `family_id`
+- 导入员工资产信息时，系统根据 `person_id` 自动填充归属员工的 `id_card` 到 `family_id`
 - 资产导入失败记录入口需与员工导入失败记录入口明确区分，按钮文案为“查看员工资产导入失败记录”
 
 ## 目标
@@ -80,12 +86,14 @@
 新增 `ccdi_asset_info` 表，字段来源于 `assets/资产信息表.csv`，并做以下调整：
 
 - `asset_id`：`BIGINT` 自增主键
-- `person_id`：`VARCHAR(18)`，保存员工身份证号，关联 `ccdi_base_staff.id_card`
+- `family_id`：`VARCHAR(18)`，保存归属员工身份证号，关联 `ccdi_base_staff.id_card`
+- `person_id`：`VARCHAR(18)`，保存资产实际持有人身份证号
 - 审计字段沿用当前项目规范，由后端自动填充
 
 建议字段如下：
 
 - `asset_id`
+- `family_id`
 - `person_id`
 - `asset_main_type`
 - `asset_sub_type`
@@ -104,6 +112,7 @@
 
 建议索引：
 
+- `idx_family_id(family_id)`
 - `idx_person_id(person_id)`
 - `idx_asset_main_type(asset_main_type)`
 
@@ -134,19 +143,20 @@
 
 后端聚合规则：
 
-- 查询员工详情时，按员工 `id_card` 查询全部资产并组装到 `assetInfoList`
+- 查询员工详情时，按员工 `id_card` 查询 `family_id = 员工身份证号` 的全部资产并组装到 `assetInfoList`
-- 新增员工时，先保存员工，再以员工 `id_card` 回填并保存资产列表
+- 新增员工时，先保存员工，再以员工 `id_card` 回填资产列表中的 `family_id`
-- 编辑员工时，更新员工主信息，再按员工身份证号重建资产列表
+- 编辑员工时，更新员工主信息，再按员工身份证号重建以 `family_id` 归户的资产列表
-- 删除员工时，先删资产再删员工，整个过程置于同一事务内
+- 删除员工时，先按 `family_id` 删除资产再删员工，整个过程置于同一事务内
 
 ### 编辑时的资产处理策略
 编辑员工时不要求前端传递资产行状态，直接按“当前完整列表”覆盖：
 
 - 获取编辑前员工旧身份证号
 - 更新员工主信息
-- 如果身份证号变更，按旧身份证号删除旧资产
+- 如果身份证号变更，按旧身份证号删除 `family_id = 旧身份证号` 的旧资产
-- 按当前最新身份证号删除对应资产
+- 按当前最新身份证号删除 `family_id = 当前身份证号` 的对应资产
-- 将前端提交的资产列表统一设置 `person_id = 当前员工身份证号`
+- 当前员工本人资产设置 `family_id = person_id = 当前员工身份证号`
+- 当前员工亲属资产设置 `family_id = 当前员工身份证号`，`person_id = 资产实际持有人身份证号`
 - 批量插入最新资产列表
 
 该策略实现简单，能直接覆盖资产新增、编辑、删除三种变化。
@@ -171,12 +181,18 @@
 #### 员工保存时
 - 员工基础信息仍沿用现有校验规则
 - `assetInfoList` 中空行自动过滤
-- 资产必填项：`assetMainType`、`assetSubType`、`assetName`、`currentValue`、`assetStatus`
+- 资产必填项：`personId`、`assetMainType`、`assetSubType`、`assetName`、`currentValue`、`assetStatus`
 - 数值和日期格式必须合法
-- 后端强制回填 `person_id = 员工 id_card`
+- 后端强制回填 `family_id = 员工 id_card`
+- 当 `personId = 员工 id_card` 时，视为员工本人资产
+- 当 `personId != 员工 id_card` 时，视为员工亲属资产
 
 #### 资产导入时
-- `person_id` 必填，且必须能匹配到员工 `id_card`
+- 模板中仅要求填写 `person_id`，不要求填写 `family_id`
+- 若 `person_id` 能匹配员工 `id_card`，视为员工本人资产，自动填充 `family_id = 该员工 id_card`
+- 若 `person_id` 不能匹配员工 `id_card`，则继续匹配员工亲属关系中的亲属身份证号，匹配成功后自动填充对应员工的 `id_card` 到 `family_id`
+- 若 `person_id` 同时匹配到多个员工家庭，则导入失败，原因标记为“资产归属员工不唯一”
+- 若 `person_id` 在员工和员工亲属关系中均无法匹配，则导入失败
 - 模板中不包含 `asset_id`
 - 允许同一员工导入多条资产
 - 失败记录仅返回失败数据，不返回成功数据
@@ -202,6 +218,7 @@
 
 子表字段：
 
+- 资产实际持有人身份证号
 - 资产大类
 - 资产小类
 - 资产名称
@@ -219,32 +236,40 @@
 - 分区右侧提供“新增资产”按钮
 - 每行支持删除
 - 编辑时回显 `assetInfoList`
-- 前端不展示 `asset_id`、`person_id`
+- 前端不展示 `asset_id`、`family_id`
+- 前端允许填写 `personId`，用于表示资产实际持有人身份证号
+- 当 `personId` 与当前员工身份证号一致时，视为本人资产；不一致时，视为亲属资产
 
 ### 详情弹窗
 在“员工详情”弹窗中新增“资产信息”区域，使用只读表格展示全部资产。
 
 若无资产数据，显示“暂无资产信息”空状态。
 
+详情表格建议增加：
+
+- `personId`：资产实际持有人身份证号
+- `ownerType`：本人 / 亲属
+
 ## 数据流
 
 ### 员工新增
-前端提交员工基础信息和 `assetInfoList`，后端保存员工后按 `id_card` 批量保存资产。
+前端提交员工基础信息和 `assetInfoList`，后端保存员工后按员工 `id_card` 为每条资产回填 `family_id`，再批量保存资产。
 
 ### 员工编辑
-前端拉取员工详情回显基础信息和资产列表，用户修改后提交完整列表，后端按最新员工身份证号重建资产明细。
+前端拉取员工详情回显基础信息和资产列表，用户修改后提交完整列表，后端按最新员工身份证号重建 `family_id = 员工身份证号` 的资产明细。
 
 ### 员工详情
-后端查询员工主信息，再按 `id_card` 查询资产列表并一并返回。
+后端查询员工主信息，再按 `family_id = 员工身份证号` 查询资产列表并一并返回。
 
 ### 员工删除
-后端先按员工身份证号删除资产，再删除员工主记录。
+后端先按 `family_id = 员工身份证号` 删除资产，再删除员工主记录。
 
 ### 资产导入
-前端上传资产 Excel，后端异步校验并批量插入资产数据，失败记录通过独立入口查看。
+前端上传资产 Excel，后端根据 `person_id` 自动识别归属员工并回填 `family_id`，异步校验并批量插入资产数据，失败记录通过独立入口查看。
 
 ## 异常处理
-- 资产导入时，若 `person_id` 无法匹配员工，记录失败原因
+- 资产导入时，若 `person_id` 无法匹配员工本人或员工亲属，记录失败原因
+- 资产导入时，若 `person_id` 对应多个员工家庭，记录归属不唯一失败原因
 - 员工编辑时若身份证号变更，必须同步处理旧资产清理和新资产重建
 - 员工删除和员工编辑资产重建均使用事务，防止主从数据不一致
 - 前端提示文案中明确区分“员工导入”和“员工资产导入”
@@ -256,4 +281,5 @@
 - 员工详情弹窗中可查看该员工全部资产信息
 - 删除员工后，该员工资产信息同步删除
 - 资产导入模板不包含 `asset_id`
-- 资产导入使用 `person_id` 关联员工身份证号
+- 资产导入模板不填写 `family_id`
+- 资产导入使用 `person_id` 识别资产实际持有人，并自动回填归属员工的 `family_id`

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

@@ -2,9 +2,9 @@
 
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
-**Goal:** Extend the employee maintenance page so users can maintain employee assets inside the add/edit dialog, view all assets in the detail dialog, and import asset data with a dedicated failure-record entry.
+**Goal:** Extend the employee maintenance page so users can maintain employee and family-member assets inside the add/edit dialog, view all assets in the detail dialog, and import asset data with automatic employee-family ownership resolution and a dedicated failure-record entry.
 
-**Architecture:** Keep the existing employee page and API module in place, and add a nested asset-table editing experience within `ccdiBaseStaff/index.vue`. Reuse the existing async import interaction model, but isolate all asset-import state, storage keys, dialogs, and button copy from the original employee-import flow.
+**Architecture:** Keep the existing employee page and API module in place, and add a nested asset-table editing experience within `ccdiBaseStaff/index.vue`. Frontend users edit the actual holder ID card as `personId`, while the backend derives `family_id` from the current employee during form save and from import resolution during Excel import. Reuse the existing async import interaction model, but isolate all asset-import state, storage keys, dialogs, and button copy from the original employee-import flow.
 
 **Tech Stack:** Vue 2, Element UI 2, RuoYi request wrapper, scoped SFC styles, Node-based source assertions or existing frontend unit checks
 
@@ -71,6 +71,7 @@ Assert the employee page contains:
 - an “资产信息” section inside the add/edit dialog
 - an add-asset action
 - a detail-table section for assets
+- a holder-ID-card input for asset rows
 
 **Step 2: Run test to verify it fails**
 
@@ -105,6 +106,7 @@ Add methods for:
 
 Render a section below basic employee info with columns for:
 
+- `personId`
 - `assetMainType`
 - `assetSubType`
 - `assetName`
@@ -182,6 +184,8 @@ Update:
 
 so they all preserve `assetInfoList`.
 
+Ensure `submitForm` filters empty asset rows but keeps valid `personId` values intact instead of overwriting them on the frontend.
+
 **Step 4: Run the submit-flow test**
 
 Run:
@@ -227,6 +231,8 @@ Add:
 - asset-specific upload methods
 - independent polling and completion handlers
 
+Keep the asset import copy clear that the system will auto-match the employee family and auto-fill ownership based on the holder ID card.
+
 **Step 4: Distinguish failure record copy**
 
 Ensure the failure entry text is exactly `查看员工资产导入失败记录`.
@@ -255,6 +261,7 @@ The dialog title must be `员工资产导入失败记录`.
 
 Show:
 
+- `familyId`
 - `personId`
 - `assetMainType`
 - `assetSubType`
@@ -288,6 +295,12 @@ Style:
 
 Ensure basic info layout remains readable on desktop and mobile widths.
 
+Also add clear inline hints so users understand:
+
+- `personId` is the actual holder ID card
+- if it equals the employee ID card, the asset belongs to the employee
+- if it differs, the asset is treated as a family-member asset
+
 ### Task 9: Verify the frontend changes end to end
 
 **Files:**