添加注释

src/lib/pricingMethodTotals.ts

@@ -614,6 +614,8 @@ const resolveScaleRows = (
   return buildDefaultScaleRows(serviceId, consultCategoryFactorMap, majorFactorMap)
 }
 
+// 统一生成某合同下某个咨询服务四种计费方式的存储键。
+// 优先复用 Pinia store 当前约定的 key，避免与旧版 fallback key 脱节。
 export const getPricingMethodDetailDbKeys = (
   contractId: string,
   serviceId: string | number
@@ -697,6 +699,8 @@ const buildDefaultPricingMethodDetailRows = (
   }
 }
 
+// 强制为一组服务重建并落库默认明细行。
+// 这个方法会同时写入 Pinia 内存态和底层 KV 存储，适合“重置为默认值”场景。
 export const persistDefaultPricingMethodDetailRowsForServices = async (params: {
   contractId: string
   serviceIds: Array<string | number>
@@ -729,6 +733,8 @@ export const persistDefaultPricingMethodDetailRowsForServices = async (params: {
   )
 }
 
+// 汇总单个服务的四类计费方式金额。
+// 数据读取顺序是：优先读当前 Pinia 中已加载的计费页数据，缺失时再回退到 KV 存储和合同段默认信息。
 export const getPricingMethodTotalsForService = async (params: {
   contractId: string
   serviceId: string | number
@@ -830,6 +836,8 @@ export const getPricingMethodTotalsForService = async (params: {
   }
 }
 
+// 为一组服务补齐缺失的计费明细行，但不会覆盖已有用户数据。
+// 适合在首次进入计费页或新增服务后做“按需初始化”。
 export const ensurePricingMethodDetailRowsForServices = async (params: {
   contractId: string
   serviceIds: Array<string | number>
@@ -918,6 +926,7 @@ export const ensurePricingMethodDetailRowsForServices = async (params: {
   )
 }
 
+// 并行汇总多个服务的计费结果，返回以 serviceId 为 key 的 Map。
 export const getPricingMethodTotalsForServices = async (params: {
   contractId: string
   serviceIds: Array<string | number>

src/pinia/zxFwPricing.ts

@@ -303,6 +303,8 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return (servicePricingStates.value[contractId]?.[serviceId]?.[method] as ServicePricingMethodState<TRow> | undefined) || null
   }
 
+  // 写入某合同某服务某种计费方式的明细状态。
+  // 默认会同步更新 keysStore，从而触发持久化；syncKeyState=false 时只回填内存态。
   const setServicePricingMethodState = <TRow = unknown>(
     contractIdRaw: string | number,
     serviceIdRaw: string | number,
@@ -337,6 +339,8 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return true
   }
 
+  // 按需加载某个服务的计费方式明细。
+  // 若内存中已有且未强制刷新，直接返回；否则从 keysStore/KV 读取后回填到内存。
   const loadServicePricingMethodState = async <TRow = unknown>(
     contractIdRaw: string | number,
     serviceIdRaw: string | number,
@@ -362,6 +366,7 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return getServicePricingMethodState<TRow>(contractId, serviceId, method)
   }
 
+  // 删除单个服务某种计费方式的状态，并同步清理对应持久化 key。
   const removeServicePricingMethodState = (
     contractIdRaw: string | number,
     serviceIdRaw: string | number,
@@ -377,6 +382,7 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return had
   }
 
+  // 暴露给外部使用的单个计费方式存储键，便于兼容旧逻辑直接读写底层数据。
   const getServicePricingStorageKey = (
     contractIdRaw: string | number,
     serviceIdRaw: string | number,
@@ -388,6 +394,7 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return serviceMethodDbKeyOf(contractId, serviceId, method)
   }
 
+  // 返回某个服务全部计费方式对应的存储键集合，常用于批量清理或导出。
   const getServicePricingStorageKeys = (contractIdRaw: string | number, serviceIdRaw: string | number) => {
     const contractId = toKey(contractIdRaw)
     const serviceId = toServiceKey(serviceIdRaw)
@@ -547,6 +554,7 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
 
   const getKeyVersion = (keyRaw: string | number) => keysStore.getKeyVersion(keyRaw)
 
+  // 对外返回合同咨询服务状态的深拷贝，避免组件直接改写 store 内部引用。
   const getContractState = (contractIdRaw: string | number) => {
     const contractId = toKey(contractIdRaw)
     if (!contractId) return null
@@ -554,6 +562,8 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return data ? cloneState(data) : null
   }
 
+  // 加载合同维度的咨询服务汇总状态。
+  // 同一合同在并发场景下会复用同一个加载任务，避免重复读取 KV。
   const loadContract = async (contractIdRaw: string | number, force = false) => {
     const contractId = toKey(contractIdRaw)
     if (!contractId) return null
@@ -589,6 +599,8 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     }
   }
 
+  // 整体替换某个合同的咨询服务状态。
+  // 入口会先标准化数据并做快照比较，只有真实变化时才递增版本号。
   const setContractState = async (contractIdRaw: string | number, state: ZxFwState) => {
     const contractId = toKey(contractIdRaw)
     if (!contractId) return false
@@ -601,6 +613,8 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return true
   }
 
+  // 只更新某个服务行上的单个汇总字段，适合计费页回写 investScale/landScale/workload/hourly。
+  // 这里不会额外重算其它派生字段，调用方需要自行决定是否联动更新 subtotal/finalFee。
   const updatePricingField = async (params: {
     contractId: string
     serviceId: string | number
@@ -661,6 +675,7 @@ export const useZxFwPricingStore = defineStore('zxFwPricing', () => {
     return hasValid ? round3(sum) : null
   }
 
+  // 清理合同维度的内存态、版本号以及该合同下所有相关持久化键。
   const removeContractData = (contractIdRaw: string | number) => {
     const contractId = toKey(contractIdRaw)
     if (!contractId) return false