From 762bf2e95c5c10bd53d4778b7323eb530bdead99 Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Thu, 17 Sep 2026 15:56:26 +0800
Subject: [PATCH] =?UTF-8?q?docs(07-12):=20=E8=AE=B0=E5=BD=95=E8=A3=85?=
 =?UTF-8?q?=E5=A4=87=E5=8A=A0=E6=88=90=E4=BA=8B=E5=AE=9E=E6=BA=90=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6=EF=BC=88WR-04=20=E8=AE=BE=E8=AE=A1=E5=A6=82=E6=AD=A4?=
 =?UTF-8?q?=EF=BC=8C=E9=9B=B6=E8=A1=8C=E4=B8=BA=E5=8F=98=E6=9B=B4=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- types.ts 的 IEquipmentStateSave / IEquipmentState 补充契约注释
- 装备自身数值与百分比加成是事实源，存档持久化这两个表并由其重建装备修饰器
- 跨读档不保留旧修饰器引用属预期；运行时改加成须经装备自身而非改其修饰器
---
 packages-user/data-base/src/hero/types.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages-user/data-base/src/hero/types.ts b/packages-user/data-base/src/hero/types.ts
index 77a2b75..bfc7355 100644
--- a/packages-user/data-base/src/hero/types.ts
+++ b/packages-user/data-base/src/hero/types.ts
@@ -633,6 +633,12 @@ export interface IHeroItems<THero>
 
 //#region 勇士装备
 
+/**
+ * 装备实例的存档。装备自身的数值与百分比加成是加成的唯一事实源，
+ * 存档持久化的正是这两个表：无压缩档全量存储、压缩档只存与原始定义的差异；
+ * 读档也由它们重建装备修饰器。故运行时要改变装备加成，必须改装备自身属性，
+ * 而不是修改它的修饰器
+ */
 export interface IEquipmentStateSave<THero> {
     /** 装备实例 uid */
     readonly uid: number;
@@ -649,6 +655,10 @@ export interface IHeroEquipsStoreSave<THero> {
     readonly equipments: readonly IEquipmentStateSave<THero>[];
 }
 
+/**
+ * 装备实例。其修饰器由装备自身加成重建而来，是派生视图：
+ * 跨读档不保留旧的修饰器对象引用属预期行为，读档后它们会被重新创建
+ */
 export interface IEquipmentState<THero> extends ISaveableContent<
     IEquipmentStateSave<THero>
 > {