@yorha2b-lab/autodev 2.1.22 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yorha2b-lab/autodev",
-  "version": "2.1.22",
+  "version": "2.2.1",
   "description": "基于视觉大模型的前端(react+Antd)全自动 CRUD 代码生成器",
   "bin": {
     "autodev": "bin/autodev.js"

package/templates/react/components/EditableCell.js

@@ -1,12 +1,29 @@
 import { Form, Input, InputNumber, Select, Checkbox } from 'antd'
 import React, { useRef, useState, useEffect, useContext } from 'react'
 
+/**
+ * @constant EditableContext
+ * @description [地堡跨组件通信协议] 用于在行（Row）与单元格（Cell）之间共享 Form 传感器的物理句柄。
+ */
 const EditableContext = React.createContext(null)
 
+/**
+ * @component EditableRow
+ * @description [地堡战术行容器] 每一行都是一个独立的逻辑闭环。
+ * 负责初始化 Form 实例并执行“行级数据同步”与“变动传感监听”。
+ *
+ * @param {Object} props - 组件属性
+ * @param {number} props.index - 行物理索引
+ * @param {Object} props.record - 初始物资包（当前行数据）
+ * @param {Function} [props.onValuesChange] - 联动传感：监听行内任何零部件的值变动
+ */
 export const EditableRow = ({ index, record, ...props }) => {
 
     const [form] = Form.useForm()
 
+    /**
+     * @description [数据热更协议] 当外部记录发生变化时，物理同步至内部表单传感器。
+     */
     useEffect(() => {
         if (record) {
             form.setFieldsValue(record)
@@ -22,6 +39,24 @@ export const EditableRow = ({ index, record, ...props }) => {
     )
 }
 
+/**
+ * @component EditableCell
+ * @description [地堡精密编辑单元] 最小物理作战单位。
+ * 支持多种装配模式（text/number/select/checkbox），并具备“自动对焦”与“失焦自愈（自动保存）”功能。
+ *
+ * @param {Object} props - 构筑参数
+ * @param {string} props.title - 零部件视觉标题，兼作占位符使用
+ * @param {Object} props.record - 当前行原始物资数据
+ * @param {boolean} props.editable - 权限协议：是否允许开启编辑模式
+ * @param {boolean} props.disabled - 物理锁定：是否禁止修改
+ * @param {string} props.dataIndex - 逻辑寻址地址：对应后端数据的字段名
+ * @param {Function} props.handleSave - 物理封存协议：数据校验通过后的保存回调
+ * @param {boolean} [props.defaultEdit] - 持久化模式：是否默认始终开启编辑状态
+ * @param {Array} [props.rules=[]] - 逻辑校验准则
+ * @param {Array} [props.options=[]] - 数据字典（仅用于 select/checkbox）
+ * @param {string} [props.editType='text'] - 零部件型号（text/number/select/checkbox）
+ * @param {React.ReactNode} props.children - 默认展示的视觉节点
+ */
 export const EditableCell = ({ title, record, editable, disabled, children, dataIndex, placeholder, handleSave, defaultEdit, rules = [], options = [], editType = 'text', ...restProps }) => {
 
     const inputRef = useRef(null)
@@ -29,6 +64,9 @@ export const EditableCell = ({ title, record, editable, disabled, children, data
 
     const [editing, setEditing] = useState(false)
 
+    /**
+     * @description [自动对焦协议] 当单元格进入“骇入模式”时，光标自动锁定，提升作战效率。
+     */
     useEffect(() => {
         if (editing) {
             if (inputRef.current && typeof inputRef.current.focus === 'function') {
@@ -37,11 +75,20 @@ export const EditableCell = ({ title, record, editable, disabled, children, data
         }
     }, [editing])
 
+    /**
+     * @function toggleEdit
+     * @description 切换“观察/骇入”模式，并执行初始信号同步。
+     */
     const toggleEdit = () => {
         setEditing(!editing)
         form.setFieldsValue({ [dataIndex]: record[dataIndex] })
     }
 
+    /**
+     * @async
+     * @function save
+     * @description 执行“物理封存协议”：触发表单校验，通过后自动关闭编辑状态并向中枢发送保存请求。
+     */
     const save = async () => {
         try {
             const values = await form.validateFields()
@@ -78,7 +125,10 @@ export const EditableCell = ({ title, record, editable, disabled, children, data
         case 'checkbox':
             inputNode = (
                 <div tabIndex={-1} onBlur={e => {
-                    // 确保失去焦点时，新的焦点不在当前 checkbox 组内部
+                    /**
+                     * 💡 [地堡特有防御逻辑]：解决 Checkbox.Group 内部焦点切换导致误触发 save 的问题。
+                     * 通过 contains 判定焦点是否真正离开了当前作战区域。
+                     */
                     if (!e.currentTarget.contains(e.relatedTarget)) {
                         save()
                     }
@@ -97,10 +147,12 @@ export const EditableCell = ({ title, record, editable, disabled, children, data
         <td {...restProps}>
             {editable ? (
                 editing || defaultEdit ? (
+                    // 骇入模式：渲染输入零件
                     <Form.Item {...(['checkbox'].includes(editType) ? { style: formProps.style } : formProps)}>
                         {inputNode}
                     </Form.Item>
                 ) : (
+                    // 观察模式：渲染静态内容，点击开启骇入
                     <div onClick={toggleEdit} className='editable-cell-value-wrap' style={{ paddingRight: 24, minHeight: 32, cursor: 'pointer' }}>
                         {children}
                     </div>

package/templates/react/components/MyBaseForm.js

@@ -3,6 +3,13 @@ import { formNode } from './index'
 import { Form, Button } from 'antd'
 import { PlusOutlined } from '@ant-design/icons'
 
+/**
+ * @function getValueFromEvent
+ * @description [数据拦截协议] 专门针对上传类组件的物理补丁。
+ * 修正 Antd 默认将 Event 对象存入 Form 的行为，强制提取物理文件列表 (fileList)。
+ * @param {Object|Array} e - 原始触发事件或文件数组
+ * @returns {Array} 归一化后的文件列表
+ */
 const getValueFromEvent = e => {
     if (Array.isArray(e)) {
         return e
@@ -10,12 +17,24 @@ const getValueFromEvent = e => {
     return e?.fileList
 }
 
+/**
+ * @function renderFormContent
+ * @description [中枢渲染逻辑] 负责装配 Form.Item 的内核。
+ * 具备“路径递归”与“单位挂件”两大核心功能。
+ *
+ * @param {Object} params - 渲染参数
+ * @param {Object} params.item - 零部件配置对象
+ * @param {Array} [params.prefixName=[]] - 物理路径前缀，用于支持 Form.List 的深层嵌套
+ * @returns {React.ReactNode} 装配完成的输入单元
+ */
 const renderFormContent = ({ item, prefixName = [] }) => {
 
+    // 💡 物理占位逻辑：若无 name 属性，则直接输出原始 value 文本
     if (!item.name) {
         return item.value
     }
 
+    // 💡 路径自动对齐：支持字符串或数组格式的 name，自动合并前缀实现“逻辑寻址”
     const namePath = Array.isArray(prefixName) ? [...prefixName, ...(Array.isArray(item.name) ? item.name : [item.name])] : item.name
 
     const inputNode = (
@@ -24,6 +43,7 @@ const renderFormContent = ({ item, prefixName = [] }) => {
         </Form.Item>
     )
 
+    // 💡 视觉单位挂件逻辑：实现类似“金额(元)”的自动横向排版
     if (item.unit) {
         return (
             <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
@@ -36,22 +56,43 @@ const renderFormContent = ({ item, prefixName = [] }) => {
     return inputNode
 }
 
-
+/**
+ * @component MyBaseForm
+ * @description [地堡通用零部件单元] 表单系统的物理外壳。
+ * 具备“单兵作战（Item）”与“集群协同（List）”两种模式切换能力。
+ *
+ * @param {Object} props - 组件属性
+ * @param {Object} props.item - 构筑协议对象
+ * @param {boolean} [props.item.isList] - 模式切换：是否开启动态增减列表模式
+ * @param {Function} [props.item.render] - 逻辑劫持：支持自定义渲染函数，可完全改写渲染行为
+ * @param {Object} props.form - Antd Form 实例，用于实现复杂的跨组件联动
+ *
+ * @example
+ * // 模式 A：标准表单项
+ * <MyBaseForm item={{ label: '姓名', name: 'name' }} />
+ *
+ * // 模式 B：动态列表项
+ * <MyBaseForm item={{ isList: true, name: 'users', render: (field) => <Input {...field} /> }} />
+ */
 export const MyBaseForm = ({ item, form }) => {
     return (
         item.isList ?
+            // 💡 集群模式：处理动态数组类型的表单构筑
             <Form.List name={item.name} initialValue={item.value}>
                 {(fields, { add, remove }) => (
                     <div style={{ display: 'flex', flexDirection: 'column' }}>
                         {fields.map((field, index) => (
                             <Fragment key={field.key}>
+                                {/* 物理映射：将 field 控制器回传给指挥官自定义的 render 逻辑 */}
                                 {item.render(field, index, { add, remove }, form, renderFormContent)}
                             </Fragment>
                         ))}
+                        {/* 零信号兜底：若列表为空，显示添加按钮 */}
                         {fields.length === 0 && <Button type='dashed' onClick={() => add()} block icon={<PlusOutlined />}>添加{item.label || '项'}</Button>}
                     </div>
                 )}
             </Form.List> :
+            // 💡 单兵模式：标准 Form.Item 构筑
             <Form.Item
                 label={item.label}
                 extra={item.extra}
@@ -61,6 +102,11 @@ export const MyBaseForm = ({ item, form }) => {
                 required={item.required ?? !!item.rules}
                 style={{ marginBottom: !item.name ? 0 : undefined, ...item.style }}
             >
+                {/*
+                  逻辑优先级：
+                  1. 优先使用 item.render 执行语义劫持
+                  2. 否则使用 renderFormContent 进行标准构筑
+                */}
                 {item.render ? (typeof item.render === 'function' ? item.render(item, form) : item.render) : renderFormContent({ item })}
             </Form.Item>
     )

package/templates/react/components/MyModalForm.js

@@ -3,11 +3,40 @@ import { MyBaseForm } from './MyBaseForm'
 import { useState, useEffect } from 'react'
 import { Row, Col, Form, Modal, } from 'antd'
 
+/**
+ * @component MyModalForm
+ * @description [地堡核心构筑舱] 通用弹窗表单组件。
+ * 集成了“语义回显自愈”、“自动时间戳转换”及“原子级提交锁定”三大核心协议。
+ *
+ * @param {Object} props - 构筑参数
+ * @param {string|number} [props.width] - 舱体物理宽度
+ * @param {string} [props.title] - 舱体视觉标题
+ * @param {Function} props.submit - 数据发射协议：提交表单后的核心回调函数
+ * @param {Object} [props.record] - 初始物资包：用于编辑模式的数据回显
+ * @param {boolean} props.visible - 激活信号：控制弹窗的物理显示状态
+ * @param {Function} props.setModal - 指令中心：用于更新弹窗状态（开启/关闭）
+ * @param {Array} props.formItems - 零部件清单：定义表单内部的输入单元
+ * @param {Object} [props.labelCol] - 标签布局校准
+ * @param {Object} [props.wrapperCol] - 控件布局校准
+ * @param {Function} [props.onValuesChange] - 联动传感：捕获表单内部的信号波动
+ *
+ * @example
+ * <MyModalForm
+ *   title="构筑新模块"
+ *   visible={visible}
+ *   formItems={[{ label: '截止日期', name: 'deadline', type: 'date' }]}
+ *   submit={async (vals) => await save(vals)}
+ * />
+ */
 export const MyModalForm = ({ width, title, submit, record, visible, setModal, labelCol, formItems, wrapperCol, onValuesChange }) => {
 
     const [form] = Form.useForm()
     const [pending, setPending] = useState(false)
 
+    /**
+     * @description [数据回显协议] 当构筑舱开启时，自动对初始物资进行“语义格式化”。
+     * 将后端传输的字符串/数字时间戳重新转化为地堡可读的 `dayjs` 对象。
+     */
     useEffect(() => {
         if (visible) {
             form.resetFields()
@@ -16,12 +45,16 @@ export const MyModalForm = ({ width, title, submit, record, visible, setModal, l
                 const initialData = {}
                 Object.entries(record).forEach(([key, value]) => {
                     const config = itemMap.get(key)
+                    // 💡 语义识别：若零部件类型为日期且数值存在，执行物理转化
                     if (config?.type?.includes('date') && value) {
                         if (Array.isArray(value)) {
+                            // 处理范围日期
                             initialData[key] = value.map(v => dayjs(v))
                         } else if (typeof value === 'string' && value.includes(',')) {
+                            // 处理逗号分隔的字符串日期
                             initialData[key] = value.split(',').map(v => dayjs(v))
                         } else {
+                            // 处理单日期
                             initialData[key] = dayjs(value)
                         }
                     } else {
@@ -33,12 +66,31 @@ export const MyModalForm = ({ width, title, submit, record, visible, setModal, l
         }
     }, [visible, record, form, formItems])
 
+    /**
+     * @async
+     * @function handleOk
+     * @description [物理加压提交] 执行表单校验，并自动启动“时间戳转换协议”。
+     * 确保发射至后端的数据包符合标准 Unix 时间戳（毫秒）规范。
+     */
     const handleOk = async () => {
         try {
             const values = await form.validateFields()
+            const formattedValues = { ...values }
+            formItems.forEach(item => {
+                const val = formattedValues[item.name]
+                if (item.type?.includes('date') && val) {
+                    if (Array.isArray(val)) {
+                        // 物理压实：将范围日期转化为逗号分隔的时间戳字符串
+                        formattedValues[item.name] = val.map(v => v.valueOf()).join(',')
+                    } else {
+                        // 物理转化：将 dayjs 对象还原为原始数值（毫秒）
+                        formattedValues[item.name] = val.valueOf()
+                    }
+                }
+            })
             if (submit) {
                 setPending(true)
-                await submit({ ...record, ...values })
+                await submit({ ...record, ...formattedValues })
                 setPending(false)
             }
         } catch (error) {
@@ -46,6 +98,10 @@ export const MyModalForm = ({ width, title, submit, record, visible, setModal, l
         }
     }
 
+    /**
+     * @function handleCancel
+     * @description 执行“撤退协议”：关闭构筑舱并清除当前逻辑残留。
+     */
     const handleCancel = () => {
         setModal({ visible: false })
         form.resetFields()

package/templates/react/components/MyModalTable.js

@@ -1,20 +1,60 @@
-import { useState } from 'react'
 import { MyTable } from './MyTable'
+import { useMemo, useState } from 'react'
 import { Modal, Space, Button } from 'antd'
 import { MySearchForm } from './MySearchForm'
 import { useTableQuery } from '../hooks/useTableQuery'
 
-
+/**
+ * @component MyModalTable
+ * @description [地堡支援型作战单元] 弹窗数据选择平台。
+ * 专门用于执行“关联选择”、“子数据审计”或“二级逻辑骇入”任务。
+ * 具备独立的数据获取链路、可选的搜索过滤系统以及与主构筑舱（setModalForm）的跨维协同能力。
+ *
+ * @param {Object} props - 支援参数
+ * @param {Function} props.api - 弹窗内独立的数据源指令
+ * @param {Function} [props.onOk] - 战果物理确认：按下确认按钮后的异步回调协议
+ * @param {string} [props.title] - 舱体视觉标题
+ * @param {string|number} [props.width] - 舱体物理宽度
+ * @param {React.ReactNode} [props.footer] - 底座指令区：支持完全自定义操作按钮
+ * @param {boolean} props.visible - 激活信号：控制支援单元的显示状态
+ * @param {Function} props.operate - 动态火力配置：生成操作列的函数，接收 { refresh, setModalForm } 句柄
+ * @param {Function} props.setModal - 单元注销中心：用于关闭当前弹窗
+ * @param {Array} [props.formItems] - 局部搜索零部件：用于在弹窗内执行精准情报过滤
+ * @param {Function} [props.setModalForm] - [重要] 跨维调用：由主页面注入的表单控制句柄，实现“弹窗开弹窗”的非耦合交互
+ * @param {Object} [props.rowSelection] - 战术勾选：用于多选物资
+ * @param {Function} props.formatResponse - 数据清洗协议：对 API 吐出的原始物资进行格式化
+ * @param {Array} [props.functionButtons] - 功能挂件组：位于表格上方的操作按钮，可直接操控表格状态
+ * @param {Array} props.columns - 零部件初始清单 (别名: modalColumns)
+ * @param {Object} [props.initialParams={}] - 初始战备物资：定义的初始搜索参数
+ * @param {boolean|Object} [props.modalPagination=true] - 局部后勤协议：弹窗内是否开启分页
+ *
+ * @example
+ * <MyModalTable
+ *   title="关联用户片段"
+ *   api={async params=>await fetchUsers(params)}
+ *   setModalForm={setModal} // 💡 借用主页面的表单构筑舱
+ *   operate={({ refresh, setModalForm }) => ({ label: '详情', onClick: (rec) => setModalForm(...) })}
+ * />
+ */
 export const MyModalTable = ({ api, onOk, title, width, footer, visible, operate, setModal, formItems, setModalForm, rowSelection, formatResponse, functionButtons, columns: modalColumns, initialParams = {}, modalPagination = true }) => {
 
     const [pending, setPending] = useState(false)
 
+    /**
+     * @description [独立信号链路]
+     * 在弹窗内部启动专属的 useTableQuery，实现了与主页面逻辑的“物理隔绝”。
+     */
     const { total, loading, columns, dataSource, search, refresh, setLoading, setSearch, setDataSource } = useTableQuery({ api, cols: modalColumns, initialParams, formatResponse })
 
     const handleSearch = values => setSearch({ ...search, ...values, pageNo: 1 })
 
     const handleTableChange = (pagination, filters, sorter) => setSearch({ ...search, pageNo: pagination.current, pageSize: pagination.pageSize, orderBy: sorter.column ? sorter.field : undefined })
 
+    /**
+     * @async
+     * @function handleOk
+     * @description [确认指令闭环] 执行确认操作并启动原子级锁定（Pending），防止重复指令干扰。
+     */
     const handleOk = async () => {
         if (onOk) {
             try {
@@ -28,21 +68,37 @@ export const MyModalTable = ({ api, onOk, title, width, footer, visible, operate
         }
     }
 
+    /**
+     * @constant finalColumns
+     * @description [火力全开] 将 Hook 生成的动态列与指挥官注入的 operate 操作列进行物理合并。
+     */
+    const finalColumns = useMemo(() => {
+        return operate ? columns.concat(operate({ refresh, setModalForm })) : columns
+    }, [columns, operate])
+
     return (
         <Modal centered destroyOnClose title={title} width={width} open={visible} onOk={handleOk} footer={footer} onCancel={() => setModal({ visible: false })} confirmLoading={pending}>
+            {/*
+                💡 [地堡战术细节]
+                syncUrlParams={false}：确保弹窗内的搜索行为不会干扰全局 URL 信号。
+            */}
             {formItems?.length > 0 && <MySearchForm search={search} formItems={formItems} setSearch={handleSearch} syncUrlParams={false} />}
+            {/*
+                💡 [高阶赋能逻辑]
+                functionButtons 能够获得对当前表格状态 (refresh, setLoading...) 的完全控制权。
+            */}
             {functionButtons?.length > 0 && <Space>{functionButtons.map(item => <Button key={item.name} type={item.type} onClick={() => item.onClick({ refresh, setLoading, setSearch, setDataSource })}>{item.name}</Button>)}</Space>}
             <MyTable
                 total={total}
                 search={search}
                 loading={loading}
                 scroll={{ y: 400 }}
+                columns={finalColumns}
                 dataSource={dataSource}
                 rowSelection={rowSelection}
                 pagination={modalPagination}
                 onChange={handleTableChange}
                 setDataSource={setDataSource}
-                columns={operate ? columns.concat(operate({ refresh, setModalForm })) : columns}
             />
         </Modal>
     )

package/templates/react/components/MySearchForm.js

@@ -3,38 +3,81 @@ import { MyBaseForm } from './MyBaseForm'
 import { useState, useEffect } from 'react'
 import { Row, Col, Form, Button, Space } from 'antd'
 
+/**
+ * @component MySearchForm
+ * @description [地堡战术搜索中心] 高级搜索表单组件。
+ * 集成了“URL 状态同步（持久化）”、“日期范围物理拆解”以及“动态伸缩布局”三大核心能力。
+ *
+ * @param {Object} props - 指挥官指令包
+ * @param {Object} props.form - Antd Form 实例，表单的主控舵盘
+ * @param {Object} props.search - 当前的全局搜索状态（包含 pageNo, pageSize 及各过滤项）
+ * @param {boolean} props.loading - 战场负载状态：请求中时锁定按钮，防止由于重复指令导致的逻辑冲突
+ * @param {Function} props.setSearch - 状态分发器：用于更新全局搜索参数并触发重新构筑
+ * @param {Array} props.formItems - 零部件清单：定义所有的搜索输入单元
+ * @param {number} [props.showLimit=7] - 初始可见能级：默认展示的零部件数量
+ * @param {Object} props.initialValues - 初始信号：从 URL 或缓存中解析出的初始参数
+ * @param {Function} [props.customReset] - 逻辑劫持：自定义重置协议
+ * @param {Function} [props.customFinish] - 逻辑劫持：自定义提交协议
+ * @param {React.ReactNode} [props.extraOperate] - 额外挂件：在按钮区域注入自定义战术单元
+ * @param {Function} [props.onValuesChange] - 联动传感：当表单值变动时的即时反馈
+ * @param {boolean} [props.syncUrlParams=true] - 物理同步开关：是否将搜索状态实时镜像至 URL 链接中
+ * @param {number} [props.defaultPageSize=10] - 默认吞吐量：重置时的初始每页条数
+ *
+ * @example
+ * <MySearchForm
+ *   form={form}
+ *   search={search}
+ *   formItems={[{ label: '状态', name: 'status', type: 'select', options: [...] }]}
+ *   setSearch={setSearch}
+ * />
+ */
 export const MySearchForm = ({ form, search, loading, labelCol, setSearch, formItems, showLimit = 7, initialValues, customReset, extraOperate, customFinish, onValuesChange, syncUrlParams = true, defaultPageSize = 10 }) => {
 
     const [limit, setLimit] = useState(showLimit)
 
+    /**
+     * @function handleReset
+     * @description 执行“归零协议”：清除当前所有搜索信号，并可选择性擦除 URL 中的物理记录。
+     */
     const handleReset = () => {
         if (syncUrlParams) {
+            // 物理清除：重置浏览器历史记录，保持 URL 纯净
             window.history.replaceState(null, '', window.location.pathname)
         }
         if (customReset) {
             customReset()
         } else {
+            // 逻辑重置：强制返回第一页，并恢复默认吞吐量
             setSearch({ pageNo: 1, pageSize: search.pageSize ?? defaultPageSize })
         }
     }
 
+    /**
+     * @function handleFinish
+     * @description 执行“数据发射协议”：对原始表单数据进行脱水和转换，尤其处理复杂的日期范围协议。
+     * @param {Object} values - 原始表单数据包
+     */
     const handleFinish = values => {
         const formattedValues = { ...values }
         if (syncUrlParams) {
             Object.keys(formattedValues).forEach(key => {
                 const val = formattedValues[key]
                 const isDateType = formItems.find(item => item.name === key)?.type?.includes('date')
+                // 💡 [黑科技 1] 日期自动转换与拆解
                 if (isDateType && val) {
                     if (Array.isArray(val) && val.length > 0) {
+                        // 物理拆分：当 name 为 'start,end' 格式时，自动拆解为两个独立的后端参数
                         const [startKey, endKey] = key.split(',')
-                        formattedValues[startKey] = val[0].startOf('day').valueOf()
-                        formattedValues[endKey] = val[1].endOf('day').valueOf()
+                        formattedValues[startKey] = val[0].startOf('day').valueOf()// 修正为当日 00:00:00
+                        formattedValues[endKey] = val[1].endOf('day').valueOf()// 修正为当日 23:59:59
                         delete formattedValues[key]
                     } else {
+                        // 单日转换：转化为毫秒级数字
                         formattedValues[key] = val.valueOf()
                     }
                 }
             })
+            // 💡 [黑科技 2] 镜像至 URL
             const params = new URLSearchParams(Object.fromEntries(Object.entries(formattedValues).filter(([key, value]) => !['', null, undefined].includes(value))))
             window.history.replaceState(null, '', `${window.location.pathname}?${params.toString()}`)
         }
@@ -45,14 +88,20 @@ export const MySearchForm = ({ form, search, loading, labelCol, setSearch, formI
         }
     }
 
+    /**
+     * @description [信号自愈] 初始化逻辑：
+     * 将来自 URL 的字符串信号重新转化为地堡可读的 `dayjs` 对象。
+     */
     useEffect(() => {
         if (Object.values(initialValues).length > 0 && formItems.length > 0) {
             const newValues = {}
             formItems.forEach(item => {
+                // 处理单字段回显
                 if (initialValues[item.name] !== undefined) {
                     const value = initialValues[item.name]
                     newValues[item.name] = item.type?.includes('date') ? dayjs(Number(value)) : value
                 }
+                // 处理双字段（日期范围）回显：执行物理重组
                 if (item.name.includes(',') && item.type?.includes('date')) {
                     const [startKey, endKey] = item.name.split(',')
                     if (initialValues[startKey] && initialValues[endKey]) {
@@ -69,15 +118,22 @@ export const MySearchForm = ({ form, search, loading, labelCol, setSearch, formI
             <Row gutter={24}>
                 {formItems.slice(0, limit)?.map((item, ind) => (
                     <Col key={ind} span={item.span ?? 6}>
+                        {/* 物理装配：利用底层 MyBaseForm 单元进行渲染 */}
                         <MyBaseForm item={item} form={form} />
                     </Col>
                 ))}
+                {/*
+                  战术控制区：
+                  1. 'flex=auto' 确保按钮组始终靠右对齐。
+                  2. 'showLimit' 控制页面纵向熵值，防止过多搜索项挤占战场视野。
+                */}
                 <Col flex='auto' style={{ textAlign: 'right' }}>
                     <Form.Item>
                         <Space>
                             <Button type='primary' loading={loading} htmlType='submit'>查询</Button>
                             <Button onClick={handleReset} loading={loading} htmlType='reset'>重置</Button>
                             {extraOperate}
+                            {/* 动态伸缩协议：根据当前零部件数量决定是否显示展开/收起按钮 */}
                             {formItems.length > showLimit && (<a onClick={() => setLimit(formItems.length > limit ? formItems.length : showLimit)}>{formItems.length > limit ? '展开' : '收起'}</a>)}
                         </Space>
                     </Form.Item>

package/templates/react/components/MyTable.js

@@ -2,13 +2,56 @@ import { Table } from 'antd'
 import { EditableRow, EditableCell } from './EditableCell'
 import { useRef, useMemo, useEffect, useCallback } from 'react'
 
+/**
+ * @component MyTable
+ * @description [地堡核心战术平台] 高级数据表格组件。
+ * 它是地堡系统的“火力中心”，集成了行内编辑、自动滚动定位、动态分页协议及 Optimistic UI (乐观更新) 等工业级特性。
+ *
+ * @param {Object} props - 平台配置参数
+ * @param {string} [props.size='middle'] - 视觉能级：表格的物理尺寸 (small/middle/large)
+ * @param {Object} [props.query] - 侦察参数：包含 rowIndex 用于执行物理追踪定位
+ * @param {number} props.total - 物资总量：用于构筑分页器的刻度
+ * @param {Object} props.search - 当前物流状态：包含 pageNo 和 pageSize
+ * @param {boolean} [props.autoScroll] - 视觉引导开关：是否开启自动滚动至目标行逻辑
+ * @param {Function} props.onChange - 战位协同回调：分页、排序、筛选变动时的通信协议
+ * @param {boolean|Object} [props.pagination] - 分页配置：支持布尔开关或物理对象覆盖
+ * @param {string|Function} [props.rowClassName] - 行视觉涂装：支持静态字符串或基于逻辑的动态类名
+ * @param {Function} [props.customSave] - 物理封存协议：行内编辑保存后的外部持久化回调
+ * @param {Function} props.setDataSource - 状态设置器：直接操作地堡的原始数据流（支持函数式更新）
+ * @param {Function} [props.lineFormChange] - 行级信号监听：捕获行内表单的实时变动
+ * @param {Array} props.columns - 零部件清单：定义列的构筑协议，支持 editType 等扩展属性
+ * @param {Object} [props.rowSelection] - 战术勾选：配置行选择逻辑
+ * @param {string} [props.rowKey='id'] - 唯一标识：每一行物资的数字指纹
+ * @param {boolean} [props.loading=false] - 战场负载状态：显示加载动画
+ * @param {Array} [props.dataSource=[]] - 物理物资包：表格展示的原始数据
+ * @param {Object} [props.scroll={x:'max-content'}] - 滚动配置：默认开启横向物理溢出防护
+ *
+ * @example
+ * <MyTable
+ *   columns={columns}
+ *   dataSource={data}
+ *   total={100}
+ *   setDataSource={setData}
+ *   customSave={(row) => saveApi(row)}
+ * />
+ */
 export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagination, rowClassName, customSave, setDataSource, lineFormChange, columns = [], rowSelection, rowKey = 'id', loading = false, dataSource = [], scroll = { x: 'max-content' }, ...restProps }) => {
 
     const tableRef = useRef(null)
     const hasScrolledRef = useRef(false)
 
+    /**
+     * @description [权限侦察] 自动扫描列配置。若存在 editType 型号，则激活“骇入模式（编辑模式）”。
+     */
     const isEditable = useMemo(() => columns.some(col => col.editType), [columns])
 
+    /**
+     * @function handleSave
+     * @description [原子级物理封存] 执行数据更新协议。
+     * 采用函数式状态更新（prev => ...）以彻底消除闭航陷阱（Stale Closure），确保数据高频修改时的绝对准确。
+     *
+     * @param {Object} row - 修改后的行片段
+     */
     const handleSave = useCallback((row) => {
         setDataSource(prev => {
             const newData = [...prev]
@@ -20,6 +63,10 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
         })
     }, [rowKey, customSave, setDataSource])
 
+    /**
+     * @constant components
+     * @description [零部件注册] 注入地堡特有的可编辑 Row 和 Cell 单元。
+     */
     const components = useMemo(() => ({
         body: {
             row: EditableRow,
@@ -27,6 +74,11 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
         }
     }), [])
 
+    /**
+     * @constant mergedColumns
+     * @description [元数据重组] 将指挥官的静态列定义转化为带逻辑注入的“动态作战列”。
+     * 自动处理 Cell 级的 disabled 状态和 editable 权限。
+     */
     const mergedColumns = useMemo(() => {
         return columns.map(col => {
             if (!col.editType) {
@@ -44,6 +96,7 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
                     dataIndex: col.dataIndex,
                     placeholder: col.placeholder,
                     defaultEdit: col.defaultEdit,
+                    // 💡 条件防御逻辑：支持针对单行的物理锁定
                     disabled: col.specialDisabled ? record.disabled : col.disabled,
                     editable: col.specialEditType ? record.needEdit && !!col.editType : !!col.editType,
                 }),
@@ -51,6 +104,11 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
         })
     }, [columns, handleSave])
 
+    /**
+     * @constant paginationConfig
+     * @description [后勤对齐协议] 自动将地堡的 search 状态映射为 Antd 分页模型。
+     * 具备类型自适应能力：支持 boolean 开关或 Object 属性覆盖。
+     */
     const paginationConfig = useMemo(() => {
 
         if (!pagination) return false
@@ -65,15 +123,21 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
         }
     }, [total, search, pagination])
 
+    /**
+     * @description [视觉追踪协议] 当检测到 query.rowIndex 信号时，执行“物理重定向”。
+     * 表格将自动平滑滚动至目标行并注入高亮背景（#e6f4ff）。
+     */
     useEffect(() => {
         if (!autoScroll || !dataSource?.length || query?.rowIndex === undefined) return
         if (hasScrolledRef.current === query.rowIndex) return
         const timer = setTimeout(() => {
             const tableElement = tableRef.current
             if (!tableElement) return
+            // 物理侦察：查找底层 Antd 生成的行节点
             const trList = tableElement.getElementsByClassName('ant-table-row')
             const tr = trList[Number(query.rowIndex)]
             if (tr) {
+                // 物理定位：平滑引导视觉中心
                 tr.scrollIntoView({ behavior: 'smooth', block: 'center' })
                 tr.style.backgroundColor = '#e6f4ff'
                 hasScrolledRef.current = query.rowIndex
@@ -96,6 +160,7 @@ export const MyTable = ({ size, query, total, search, autoScroll, onChange, pagi
                 rowSelection={rowSelection}
                 pagination={paginationConfig}
                 components={isEditable ? components : undefined}
+                // 💡 信号注入：将行监听协议绑定至底层 tr
                 onRow={(record, index) => ({ record, index, onValuesChange: lineFormChange })}
                 rowClassName={(record, index) => {
                     const externalClass = typeof rowClassName === 'function' ? rowClassName(record, index) : rowClassName

package/templates/react/components/index.js

@@ -3,12 +3,39 @@ import { useState, useEffect } from 'react'
 import { UploadOutlined } from '@ant-design/icons'
 import { Button, Tree, Radio, Input, Upload, Select, Cascader, Checkbox, DatePicker, InputNumber, TreeSelect, AutoComplete } from 'antd'
 
+/**
+ * @component AliyunOSSUpload
+ * @description [地堡核心传输单元] 阿里云 OSS 高级上传组件。
+ * 集成了“物理路径自动重组”、“STS 令牌自动续期”以及“ Antd 属性无损透传”三大核心协议。
+ *
+ * @param {Object} props - 构筑参数
+ * @param {Array} props.value - 传感器当前封存的文件列表 (符合 Antd fileList 规范)
+ * @param {Function} props.onChange - 状态反馈协议：当物理文件状态变更时同步至地堡中枢
+ * @param {Object} [props.oss] - 外部空投的初始凭证包。若缺失，组件将启动自主初始化流程。
+ * @param {string} [props.url] - 司令部通信地址：用于申请最新的物理传输令牌 (STS)
+ * @param {string} [props.path] - 默认存储扇区：定义文件在云端的物理根路径
+ * @param {Object} [props.options] - 通信加密/配置参数：在申请令牌时透传给 request 的额外负载
+ * @param {Object} [props.originUploadProps] - [重要] 无损透传：支持 Antd Upload 的所有原生属性（如 multiple, accept 等）
+ *
+ * @example
+ * // 基本构筑
+ * <AliyunOSSUpload path="project/data" url="/api/oss/token" />
+ *
+ * // 高级装配（限制文件类型并开启多选）
+ * <AliyunOSSUpload accept=".pdf" multiple={true} path="docs" url="/api/oss/token" />
+ */
 const AliyunOSSUpload = ({ value, onChange, ...restProps }) => {
 
+    // 💡 物理剥离：将地堡专用参数与 Antd 原生属性分离
     const { oss, url, path, options, ...originUploadProps } = restProps
 
     const [OSSData, setOSSData] = useState(oss)
 
+    /**
+     * @async
+     * @function init
+     * @description [信号握手] 执行令牌获取协议，从司令部申请最新的物理上传授权
+     */
     const init = async () => {
         try {
             const result = await initOSS(url, options)
@@ -19,6 +46,7 @@ const AliyunOSSUpload = ({ value, onChange, ...restProps }) => {
     }
 
     useEffect(() => {
+        // 💡 自愈逻辑：如果发现能源包 (OSSData) 为空，则自动触发初始化
         if (!OSSData) {
             init()
         }
@@ -31,6 +59,11 @@ const AliyunOSSUpload = ({ value, onChange, ...restProps }) => {
         onChange?.(files)
     }
 
+    /**
+     * @function getExtraData
+     * @description [数据封装] 将动态生成的物理凭证与目标文件路径压入传输负载
+     * @param {Object} file - 待传输的文件对象
+     */
     const getExtraData = file => ({
         key: file.url,
         policy: OSSData?.policy,
@@ -39,15 +72,27 @@ const AliyunOSSUpload = ({ value, onChange, ...restProps }) => {
         'x-oss-security-token': OSSData?.stsToken,
     })
 
+    /**
+     * @async
+     * @function beforeUpload
+     * @description [生存期侦察] 在传输启动前执行 TTL 检测。
+     * 若令牌已失效（过期），则强行拦截并执行同步刷新协议，同时执行物理路径归一化。
+     */
     const beforeUpload = async file => {
         const expire = Number(OSSData.expire) * 1000
         if (expire < Date.now()) {
             await init()
         }
+        // 💡 物理路径重组：通过正则清除多余的路径分隔符，确保存储节点坐标唯一
         file.url = `${OSSData?.dir ?? path}/${file.uid}_${file.name}`.replace(/\/\//g, '/')
         return file
     }
 
+    /**
+     * @constant uploadProps
+     * @description [物理合并] 最终生成的 Antd Upload 指令集：
+     * 自动优先应用 originUploadProps 中的自定义设置。
+     */
     const uploadProps = {
         onRemove,
         name: 'file',
@@ -66,6 +111,21 @@ const AliyunOSSUpload = ({ value, onChange, ...restProps }) => {
     )
 }
 
+/**
+ * @function formNode
+ * @description 智能零部件装配器：根据构筑协议（item.type）动态产出对应的 Ant Design 交互单元。
+ *
+ * @param {Object} params - 装配参数
+ * @param {Object} params.item - 零部件配置对象
+ * @param {string} params.item.type - 构筑类型（date/number/ossUpload/select/daterange 等）
+ * @param {boolean} [params.item.readOnly] - 物理锁定开关
+ * @param {string|number} [params.item.width] - 宽度校准
+ * @param {string} [params.item.placeholder] - 视觉占位提示
+ * @param {Array} [params.item.options] - 数据字典（用于 select/radio/tree 等）
+ * @param {Object} [params.item.props] - 透传给底层组件的原始控制参数
+ *
+ * @returns {React.ReactNode} 物理装配完成的 UI 单元
+ */
 export const formNode = ({ item }) => {
 
     const commonProps = {

package/templates/react/handlebars/MyTable.hbs

@@ -1,4 +1,7 @@
 <MyTable
+    {{#if hasPagination}}
+    pagination
+    {{/if}}
     query={query}
     total={total}
     rowKey={rowKey}

package/templates/react/handlebars/handleBlock.hbs

@@ -1,3 +1,7 @@
+{{!--
+   📡 [地堡战术响应模组]
+   负责物理封存所有交互事件：包含行级操作、全局按钮、页签切换及弹窗构筑提交。
+--}}
 {{#each operations}}
 const {{this.action}} = async record => {
     const response = await request('/api')

package/templates/react/handlebars/hookBlock.hbs

@@ -1,11 +1,17 @@
+{{!--
+   📡 [地堡核心驱动引擎]：逻辑链路全自动构筑
+   1. 执行“传感器对齐”：从 URL 中提取历史信号，实现状态持久化
+   2. 激活“useTableQuery”：物理封存分页、搜索、及动态列加载逻辑
+--}}
+
 const initParams = {{#if hasTabs}}{ type: tabs[0].key }{{else}}{}{{/if}}
 
 const query = formatQuery(Object.fromEntries(new URLSearchParams(location.search).entries()),  {{formItems}})
 
 const { total, columns, loading, dataSource, search, setSearch, setDataSource, refresh } = useTableQuery({
         api: async params => await request('/api/{{fileName}}', { method: 'POST', body: params }),
-        initialParams: { pageNo: 1, pageSize: 10, ...query },
-        cols:tableColumns,//前端指定列数组
+        initialParams: { pageNo: 1, pageSize: 10, ...initParams, ...query },
+        cols:tableColumns,
         formatResponse: response => {
             return {
                 data: response?.data ?? [],

package/templates/react/handlebars/stateBlock.hbs

@@ -1,7 +1,8 @@
 
+{{!-- 📡 [地堡状态模组] 物理信号初始化：驱动弹窗、页签及数据勾选等核心交互单元 --}}
 const rowKey = 'id'
 const [form] = Form.useForm()
-const [modal, setModal] = useState({ visible:false, title:'', formItems:[] })
+const [modal, setModal] = useState({ visible:false, title:'', formItems:modalItems })
 {{#if hasRowSelection}}
 const [selectedRows, setSelectedRows] = useState([])
 {{/if}}

package/templates/react/hooks/useTableQuery.js

@@ -1,5 +1,34 @@
 import { useRef, useState, useEffect, useCallback } from 'react'
 
+/**
+ * @hook useTableQuery
+ * @description [地堡核心逻辑引擎] 高级异步数据驱动钩子。
+ * 负责全自动管理表格的生命周期，包括数据抓取、状态同步、动态列指纹识别及“竞态病毒”物理免疫。
+ *
+ * @param {Object} params - 引擎配置包
+ * @param {Function} params.api - 任务指令：必须返回 Promise 的数据抓取函数
+ * @param {Array} [params.cols] - 初始战备物资：前端预设的静态列配置
+ * @param {Object} [params.initialParams={}] - 初始导航坐标：包含 pageNo, pageSize 及默认过滤参数
+ * @param {Function} params.formatResponse - 数据解码协议：将 API 原始信号转化为 { data, total, columns } 结构
+ *
+ * @returns {Object} 物理操作句柄包
+ * @returns {number} .total - 仓库物资总量
+ * @returns {Array} .columns - 当前生效的动态列配置（已通过指纹协议校验）
+ * @returns {boolean} .loading - 引擎负载状态
+ * @returns {Array} .dataSource - 已解压的物理物资列表
+ * @returns {Object} .search - 当前导航参数（pageNo, pageSize 等）
+ * @returns {Function} .setSearch - 坐标修改器
+ * @returns {Function} .setLoading - 负载状态手动干预句柄
+ * @returns {Function} .setDataSource - 物资流手动修改句柄（用于行内编辑等乐观更新）
+ * @returns {Function} .refresh - 强制重启协议：立即执行一次数据抓取
+ *
+ * @example
+ * const { dataSource, loading, refresh } = useTableQuery({
+ *   api:async params=>await fetchUsers(params),
+ *   initialParams: { pageNo: 1, pageSize: 10 },
+ *   formatResponse: (res) => ({ data: res.list, total: res.total })
+ * });
+ */
 export const useTableQuery = ({ api, cols, initialParams = {}, formatResponse }) => {
 
     const [total, setTotal] = useState(0)
@@ -8,23 +37,41 @@ export const useTableQuery = ({ api, cols, initialParams = {}, formatResponse })
     const [dataSource, setDataSource] = useState([])
     const [search, setSearch] = useState(initialParams)
 
+    // 💡 引用锁定协议：确保异步回调中永远能指向最新的指令地址
     const apiRef = useRef(api)
+    // 💡 [核心防御] 信号 ID 计数器：用于物理拦截由于网络时延导致的“竞态病毒（Race Condition）”
     const fetchIdRef = useRef(0)
 
     useEffect(() => {
         apiRef.current = api
     }, [api])
 
+    /**
+     * @function getColumnSchema
+     * @description [指纹识别协议] 对列配置执行“结构化脱水”。
+     * 通过提取标题、字段和排序状态生成物理指纹，用于判定列结构是否发生“基因变异”。
+     * @param {Array} cols - 待扫描的列配置
+     * @returns {string} 物理指纹字符串
+     */
     const getColumnSchema = cols => cols.map(col => `${col.title}-${col.dataIndex}-${col.sortOrder}`).join('|')
 
+    /**
+     * @async
+     * @function fetchData
+     * @description [数据装配任务] 执行核心的数据抓取与物理封存逻辑。
+     * 具备信号溯源能力，确保只有最后一次发出的指令能修改地堡状态。
+     */
     const fetchData = useCallback(async () => {
         if (!apiRef.current) return
         setLoading(true)
+        // 💡 信号加标：为本次请求分配唯一的物理 ID
         const currentFetchId = ++fetchIdRef.current
         try {
             const response = await apiRef.current(search)
+            // 💡 [物理拦截] 信号校准：若当前 ID 不是最新 ID，说明该信号已过期，执行丢弃协议
             if (currentFetchId !== fetchIdRef.current) return
             const { data, total, columns: newCols } = formatResponse(response ?? {})
+            // 💡 [性能装甲] 只有当列指纹发生变化时，才触发 React 的重绘逻辑
             if (newCols && getColumnSchema(newCols) !== getColumnSchema(columns)) {
                 setColumns(newCols)
             }
@@ -33,6 +80,7 @@ export const useTableQuery = ({ api, cols, initialParams = {}, formatResponse })
         } catch (error) {
             console.error('查询失败', error)
         } finally {
+            // 💡 状态闭环：确保只有最新的信号能解除 Loading 锁定
             if (currentFetchId === fetchIdRef.current) {
                 setLoading(false)
             }

package/templates/react/utils/utils.js

@@ -1,8 +1,19 @@
 import dayjs from 'dayjs'
 import { request } from './request'
 
-//常用工具函数，使用前确保已安装对应模块
-
+/**
+ * @namespace BunkerUtils
+ * @description 地堡核心工具集：包含文件处理、数据脱水、视觉渲染及后勤传输协议；使用前确保已安装对应模块（如：xlsx、ali-oss、crypto-js）
+ * */
+
+
+/**
+ * @async
+ * @function parseExcel
+ * @description [后勤部] 本地 Excel 解析协议：将二进制表格物资转化为地堡可读的 JSON 序列。
+ * @param {File|Blob} file - 待解析的原始文件对象
+ * @returns {Promise<Array[]>} 解析后的二维数组数据
+ */
 export const parseExcel = async file => {
     /* const arrayBuffer = await file.arrayBuffer()
     const XLSX = require('xlsx')
@@ -13,6 +24,14 @@ export const parseExcel = async file => {
     return excelData.filter(item => item.length > 0) */
 }
 
+/**
+ * @async
+ * @function initOSS
+ * @description [出口协议] 阿里云 OSS 凭证初始化：从司令部申请 STS 令牌并计算物理传输签名。
+ * @param {string} url - 令牌申请地址
+ * @param {Object} options - 请求配置参数
+ * @returns {Promise<Object>} 包含 OSS 客户端实例、上传策略及 Host 节点的配置包
+ */
 export const initOSS = async (url, options) => {
     /* const OSS = require('ali-oss')
     const crypto = require('crypto-js')
@@ -29,6 +48,13 @@ export const initOSS = async (url, options) => {
     return { client, policy, signature,host: `https://${bucket}.${endpoint.split('//')[1]}`, ...response?.data } */
 }
 
+/**
+ * @function formatQuery
+ * @description [数据脱水] 搜索参数校准协议：根据零部件类型（如日期）自动执行类型转换（String -> Number）。
+ * @param {Object} params - 原始表单/URL 传感器数据
+ * @param {Array} formItems - 对应的零部件配置清单
+ * @returns {Object} 经过物理清洗、可直接用于 API 请求的参数包
+ */
 export const formatQuery = (params, formItems) => {
     const cleanParams = {}
     Object.keys(params).forEach(key => {
@@ -41,6 +67,15 @@ export const formatQuery = (params, formItems) => {
     return cleanParams
 }
 
+/**
+ * @function timeRender
+ * @description [视觉渲染] 时间戳格式化：将冷冰冰的数字转化为人类可读的时间字符串。
+ * @param {Object} params - 渲染参数
+ * @param {number|string} params.time - 原始时间戳
+ * @param {boolean} [params.date] - 是否仅保留日期（YYYY-MM-DD）
+ * @param {boolean} [params.minute] - 是否精确到分钟（YYYY-MM-DD HH:mm）
+ * @returns {string} 格式化后的时间字符串
+ */
 export const timeRender = ({ time, date, minute }) => {
     if (!time) {
         return ''
@@ -55,6 +90,16 @@ export const timeRender = ({ time, date, minute }) => {
     }
 }
 
+/**
+ * @async
+ * @function exportDataToExcel
+ * @description [物资外运] 数据表格导出协议：支持复杂的渲染逻辑回溯，将页面数据封存为 .xlsx 格式。
+ * @param {string} url - 数据源地址
+ * @param {Object} options - 请求参数
+ * @param {Array} columns - 表格列配置，支持 exportRender 优先级
+ * @param {string} fileName - 导出的文件名
+ * @param {Function} [formatter] - 数据预处理回调
+ */
 export const exportDataToExcel = async (url, options, columns, fileName, formatter) => {
     /* const response = await request(url, options)
     const result = formatter ? formatter(response) : (response?.data ?? [])
@@ -80,6 +125,16 @@ export const exportDataToExcel = async (url, options, columns, fileName, formatt
     } */
 }
 
+/**
+ * @async
+ * @function streamDownload
+ * @description [后勤传输] 智能流式下载协议：具备“语义侦察”能力，能自动识别被伪装成二进制流的 JSON 报错信息。
+ * @param {Object} params - 传输配置
+ * @param {string} params.url - 物资下载地址
+ * @param {Object} [params.options] - Fetch 配置
+ * @param {Object} [params.headers] - 自定义请求头
+ * @param {string} [fileName='下载'] - 预设文件名（支持从 Content-Disposition 自动对齐）
+ */
 export const streamDownload = async ({ url, options, headers = {} }, fileName = '下载') => {
 
     const response = await fetch(url, { ...options, headers })
@@ -96,6 +151,7 @@ export const streamDownload = async ({ url, options, headers = {} }, fileName =
         return
     }
 
+    // 💡 语义侦察逻辑：检查前 10 个字节，判断是否为 JSON 报错信息
     const slice = blob.slice(0, 10)
     const text = (await slice.text()).trim()
 
@@ -110,6 +166,7 @@ export const streamDownload = async ({ url, options, headers = {} }, fileName =
         return
     }
 
+    // 物理解析 Content-Disposition 头部，获取指挥官预设的文件名
     const disposition = response.headers.get('content-disposition')
     let name = fileName
 
@@ -133,6 +190,17 @@ export const streamDownload = async ({ url, options, headers = {} }, fileName =
     setTimeout(() => URL.revokeObjectURL(urlObj), 1000)
 }
 
+/**
+ * @function moneyRender
+ * @description [视觉渲染] 金额校准渲染：支持多国语境、货币符号及精度控制。
+ * @param {number|string} value - 原始金额数值
+ * @param {Object} [options] - 配置参数
+ * @param {number} [options.decimals=2] - 小数位数
+ * @param {string} [options.currency='CNY'] - 货币代号
+ * @param {string} [options.language='zh-CN'] - 语言环境
+ * @param {boolean} [options.showSymbol=true] - 是否显示货币符号
+ * @returns {string} 格式化后的金额文本
+ */
 export const moneyRender = (value, { decimals = 2, currency = 'CNY', language = 'zh-CN', showSymbol = true } = {}) => {
     if (value === null || value === undefined || value === '') return '-'
     const number = Number(value)
@@ -143,6 +211,16 @@ export const moneyRender = (value, { decimals = 2, currency = 'CNY', language =
     return new Intl.NumberFormat(language, options).format(number)
 }
 
+/**
+ * @function formatUnit
+ * @description [视觉渲染] 单位自动进阶协议：实现 B/KB/MB... 等数据的物理量级自动折算。
+ * @param {number} value - 原始字节数值
+ * @param {Object} [options] - 配置参数
+ * @param {number} [options.k=1024] - 进位系数
+ * @param {Array} [options.units] - 单位阶梯
+ * @param {number} [options.decimals=2] - 保留小数位
+ * @returns {string} 带单位的物理量级文本
+ */
 export const formatUnit = (value, { k = 1024, units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'], decimals = 2 } = {}) => {
     if (value === null || value === undefined || isNaN(value) || value === 0) {
         return `0 ${units[0] ?? ''}`