宫论项目开发记录

2025年5月23日
1、通过 xc_cloud_upload 发起云端同步请求时，如果传递的 update['sort'] 值为 local，则表示需要同步本地文件。此时，系统会首先执行 file_exists(update['local']) 来验证本地文件是否存在。如果文件不存在，将立即返回错误信息：“上传失败：本地文件不存在！”。如果文件存在，系统将继续读取 xc_upload_cloud_sort 配置，并根据配置执行相应的 SDK 上传操作。然而，由于此过程并未传递媒体库 ID，因此不会通过 xc_update_sql 执行回调动作。在上传成功后，系统会直接返回上传文件的 URL 地址信息。
2、在通过云端同步脚本进行远程文件上传时，如果update['sort']的值为local，那么成功上传后将执行一系列业务逻辑。首先，会检测delete变量是否存在且不为空。如果满足条件，则会主动发起删除请求，以清理本次上传的本地文件。接着，读取本地文件以获取其大小，然后通过update_redis_sorted_set进行计数统计。该过程会获取当天的时间戳作为成员，更新有序集合，以统计每日文件上传的总大小。注：因为local不会触发回调动作，因此需要再函数内执行一些上传成功的回调业务处理。
3、在上传本地文件到云端同步，除了会统计文件的upload_size的大小到有序集合以及外，还会通过内置方法mime_content_type来获取文件的MIME 类型，并将结果保存的变量mime中，然后调用xc_redis_count计数器，来记录upload_$mime，该计数器会这自动统计平台[图片=image 视频=video voice=声音]等上传成功次数，后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
4、在成功获取到MIME文件类型后，这里会进行一个至关重要的处理。首先，通过xc_is_login方法获取当前登录用户，并将结果保存到user_id中。如果用户已登录，则会进行以下操作：如果MIME类型等于image，则通过xc_user_daily_hook方法发起一个计数统计，增加当前用户的upload_image图片上传次数；如果MIME类型等于video，则同样通过xc_user_daily_hook方法统计用户的upload_video视频上传次数。系统还设置了一个API接口拦截器，负责监控每日用户的视频和图片上传次数。即使用户通过云端发起上传操作，也要进行相应的计数统计，以防止用户超过上传限制。
5、在云端文件同步上传事件中，涉及到的计数器统计回调处理，仅限于非媒体库【ID】的云端请求。在执行时，系统会验证update数组变量是否存在ID字段，如果存在则跳过处理。这是因为在媒体库同步的业务逻辑中，已经有自己的一套标准进行计数处理和缓存更新处理，不需要重复性的计数操作。如果强制执行，可能会导致计数器重复触发，从而引起统计数值不准确的问题。注：local和url两个上传类型才允许触发（必须在文件确定同步成功后执行）
6、后台云端上传类型配置字段：xc_upload_cloud_sort，新增了一个上传场景【SFTP】。系统在同步上传文件到云端时，如果选择了SFTP，则会使用SFTP协议将本地文件上传到远程服务器。之所以采用SFTP，是因为大多数服务器都是Linux类型，使用SFTP进行传输更加安全可靠。相比之下，FTP协议不仅安全性较低，还需要额外安装对应的客户端。注：使用SFTP进行协议同步云端文件同步，本质上就是建立一个存储服务器，专门存储服务器对应文件。所有的本地文件都将通过这台服务器进行分发处理。
7、在后台appkey账户信息配置页，新增了一个名为【xc_appkey_sftp_config】的SFTP账户权限配置列表。该列表包含以下字段：name（账户说明）、key（IP或域名链接，即FTP或SFTP的服务器地址）、user（登录账户，即服务器FTP登录账户名）、pass（登录密码）和port（端口号，即服务器FTP请求端口）。服务器的参数配置通过后台进行管理，如果需要追加服务器或变更服务器参数，只需在后台修改对应数值即可完成。这一改进将大大提高后期维护的便捷性。
8、新增的钩子函数 xc_hook_sftp() 通过 SFTP 协议将本地文件上传到远程服务器。使用该函数时，需要提供三个必要的变量参数。首先是 key，它用于匹配 SFTP 配置的唯一键，这是在后台配置场景中设置的独特值。其次是 local_file，即本地文件的路径。需要注意，此处仅支持服务器上的文件同步功能，不支持远程文件的处理。最后一个参数是 $remote_file，它表示远程保存文件的路径，包括具体目录和文件名。值得特别指出的是，无论是本地文件路径还是远程存储位置，都必须设置为绝对路径，以确保文件能够正确地进行传输和存储。
9、在xc_appkey_sftp_config配置中新增了两个字段。首先是“path”字段，用于指定上传目录。该字段可以为空，根据具体应用场景进行配置。当设置了这个字段后，所有属于该场景的文件必须上传至指定的目录，以确保文件管理的规范性和安全性，避免因文件乱放而引发的混乱和风险。其次是“type”字段，用于指定上传协议类型。该字段的值固定为FTP或SFTP两种协议类型，并且两种协议共用同一份配置。在调用相应场景的上传接口时，系统会检测实际使用的协议是否与配置中的协议一致，如果不一致则会返回协议错误。这一新增配置旨在进一步规范上传流程，提高文件传输的安全性和一致性。
10、xc_hook_sftp上传接口已完成封装，该钩子返回标准的数组结构：code=0代表上传成功，code=1代表上传失败，msg是失败的详细原因。执行流程如下：1、通过require_once引入SDK组件，确保SFTP协议能够被支持。2、使用file_exists检测需要上传的文件是否存在，如果不存在直接返回错误。3、读取key检测是否场景配置是否存在，不存在返回错误。配置存在则检测协议选择是否为sftp，不是也返回对应错误。4、读取场景其他配置，通过new phpseclib3\Net\SFTP构建上传请求，如果构建过程出现异常，返回对应的错误。5、调用$sftp->put执行上传请求，并且监听返回，如果错误返回对应信息。6、完成上传请求，返回code=0。
11、对SFTP上传接口进行了优化：首先，在后台新增了一个名为$config['open']的字段，用于判断当前场景是否被临时弃用。如果该字段被设置为关闭状态，当用户尝试上传文件时，系统将直接返回一个错误信息【上传失败：SFTP应用场景已被管理员关闭】。这一措施有效地防止在不适宜的情况下继续进行上传操作，从而保证系统的稳定性和安全性。其次，在整个上传流程中引入了try-catch机制来捕获异常事件。通过这种方式，如果在执行过程中出现任何异常，系统将立即返回相应的错误信息，从而避免上传过程中出现错误导致整体返回结果的不一致性或失败。

2025年5月22日
1、在成功读取到xc_upload_cloud_sort配置参数后，xc_cloud_upload方法会立即通过require_once加载配置中指定的【xc_get_option('xc_sdk_composer')】文件，以便将宫论项目的所有SDK集成到当前环境中。随后，该方法会根据后台返回的配置参数发起相应的上传请求。目前，该功能主要集成了腾讯云对象存储（COS），因此在加载完相关SDK后，会调用Qcloud\Cos\Client类来发起COS云文件同步请求，并将处理结果存储在cosClient对象中。
2、通过xc_cloud_upload发起宫论媒体库资源上传同步请求时，会对原有的资源进行状态检测，如果state等于delete，则返回错误【上传失败：文件已被删除!】，如果$upload['state']等于ok，则返回上传失败，文件已完成上传。并使用parse_url对本地的链接进行解析处理，如果$parts['scheme']不存在，则说明存在域名节后，此时会提示错误：上传失败：等待上传的文件是远程地址。注：通过上述验证，防止出现重复执行上传，或者已删除的媒体库资源发起上传请求。
3、在成功地处理了本地文件的读取后（通过file_exists函数验证文件是否存在，如果文件不存在，将返回相应的错误信息），接下来需要读取与“宫论”相关的后台云端账户配置信息。这些信息包括但不限于腾讯云账户的SecretId（即xc_tencent_secret_id）、腾讯云秘钥的SecretKey（即xc_tencent_secret_key）、存储桶的地域（即xc_upload_cos_region）、存储桶的名称（即xc_upload_cos_bucket）、以及cos的自定义域名（即xc_upload_cos_domain）等。这些参数的提取和封装是为后续上传SDK的调用做好准备工作，确保上传操作能够顺利进行。
4、通过xc_cloud_upload发起云端同步请求，如果同步的类型为（媒体库ID）并且SDK类型为cos对象存储，那么它的处理逻辑如下：1、使用new Qcloud\Cos\Client构建上传行为，将之前封装好的腾讯云账户信息写入到对应对象中，然后将body对象设置为$upload['local']，请求将该文件进行上传处理，对应的key（存储的路径地址和文件名称）则读取$upload['remote']参数。最后调用$cosClient->upload方法进行上传请求。注：验签过程会在cosClient对象中进行，这里不需要进行任何处理。
5、通过cos发起云端同步请求的时候，为了确保执行的安全可靠性。会采用try-catch来捕获错误和异常，确保上传中出现的任何异常错误都可以被定位到，也是确保返回的结构体使用是标准数组结构，不会因为SDK的返回为对象或者其他参数，造成返回结构不被系统识别。具体的处理方式如下，try负责执行$cosClient->upload上传请求行为，果过程中发生任何错误，如文件损坏、权限不足、接口异常或账户欠费等，catch块则会捕获异常并进行相应的处理，通过catch(\Exceptione)来转发和记录这些错误信息，确保系统能够稳定地处理各种异常情况。
6、通过云端同步接口发起cos上传请求时，如果cos_result执行返回上传成功。会主动检测请求方式是否为ID，如果是ID则表明本次是和宫论数据表xc_upload进行关联的，此时在返回结果前，会进行xc_update_sql回调操作，主要对两个字段进行更新处理。1、remote：远程CDN地址，上传成功后会进行封装【xc_get_option('xc_upload_cos_domain') . '/' . $upload['remote']】结构为CDN域名+KEY键名方式拼接。2、state：将数据表的状态标记为OK。表明该媒体库ID已完成云端同步工作。
7、在完成云端资源的同步操作后，对于使用ID作为主键的同步类型，会触发文件上传成功的回调动作：xc_upload_hook_success。该钩子专门用于处理业务回调操作，任何成功上传到宫论媒体库的资源都会激活此钩子，确保系统内置的方法能够准确监听到上传行为。同样的处理也适用于云端同步。只要确认上传成功，就将ID传递给这个回调动作，由其负责后续的执行。后续的业务逻辑则不在此处进行处理。
8、在云端文件成功同步至COS对象存储桶后，除了触发通用的回调动作事件外，还会通过xc_do_action注册动作钩子，以便进行业务回调操作。在注册过程中，会传递一个固定的参数ID作为身份标识，允许第三方通过注册方法挂载回调方法，从而接收此次回调的通知。完成上述操作后，COS版本的云端上传业务即宣告完成。此时，系统会返回四个字段：code=0表示本次同步成功；msg为“文件云端同步成功”；type指示同步方式为腾讯云对象存储（COS）；url则为封装并拼接好的CDN地址，供直接访问使用。
9、通过cos上传同步远端对象的时候，如果触发catch错误监听，则会触发一个日志报警器。日志的标识为：cloud_upload，日志的记录结构为【[上传时间: - ' . date("Y-m-d H:i:s") . '] [上传用户: - ' . $upload['user_id'] . '] [错误日志: - ' . $e . ']】记录动作是通过调用xc_log_error_warn方法来完成的。需要注意的是，这条日志记录仅用于错误追踪和分析，不会触发任何报警机制。只要上传过程中发生的任何错误，都会触发这个日志写入，具体错误原因为$e变量提供。
10、增加了一个名为“cloud_upload”的Redis计数器，用于记录xc_cloud_upload方法在处理云端文件时的执行成功次数。无论文件是通过何种同步方式上传、使用哪种存储机制，只要通过xc_cloud_upload方法成功上传文件，便会触发xc_redis_count脚本进行计数处理。后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
11、在云端文件同步成功后，系统会对传递的变量upload数组进行检查，以确认是否存在【delete字段】。如果该字段存在且不为空，脚本将执行删除本地文件的操作。通常，delete参数用于标记临时文件，例如远程下载的图片，这些文件会被保存到临时目录中。一旦同步到云端，便需要立即进行清理，因为这些临时文件在后续操作中已不再需要。如果不及时清理，可能会导致服务器磁盘空间的浪费。完成delete字段的检测和处理后，整个cos对象的远程同步工作便告一段落。通过这种机制，确保了服务器资源的高效利用和管理。

2025年5月21日
1、在执行xc_upload_thumbnail_save方法时，如果需要将缩略图上传至云端，该方法会内部调用xc_cos_upload方法。此方法是一个封装好的SDK上传请求，用于处理所有cos文件的同步请求，以便于后期的维护和管理。为了确保上传过程的顺利进行，xc_cos_upload方法需要接收两个变量参数。首先，$url参数可以是本地图片或远程图片，但目前尚未兼容base64格式。其次，#name参数用于指定上传的保存位置，若无需指定则可以留空。通过这种设计，确保了上传过程的灵活性和高效性。
2、对xc_cos_upload作为宫论云端文件同步方法进行了优化升级，以确保其能够适应所有场景，并成功接入宫论的媒体系统。首先，对云同步功能进行了调整，采用标准化的数组结构来返回结果。其中，code=0表示文件上传并同步成功，code=1则表示上传失败。上传失败的原因可能多种多样，需要通过msg字段来获取具体的错误信息。如果上传成功，还会返回一个额外字段：cdn，即远程可直接访问的文件路径地址。
3、考虑到兼容性问题，直接修改 xc_cos_upload 方法的业务逻辑可能会对已经集成的上传场景产生影响。因此，我们决定重新封装一个新的方法来进行适配处理，而原有的 xc_cos_upload 方法将被恢复至其初始状态，不做任何改动。那些已经使用 xc_cos_upload 方法的场景将在后续逐步迁移到新的方法上。新的方法命名为 xc_cloud_upload，其中“cloud”表示云端同步的意思。该方法不仅限于 COS（对象存储服务），未来还将集成更多的同步方案，如存储服务器备份、OSS（对象存储服务）等，以提供更广泛的支持和灵活性。
4、在后台上传配置页面们新增了一个参数字段：xc_upload_cloud_sort【上传类型】。目前，这个上传类型是一个单选项，只有一个选项可供选择，即【cos：腾讯云对象存储】。在同步云端图片数据时，系统将根据这个上传类型读取相应的设置，并调用对应的SDK发起上传请求。这一参数匹配的设计，旨在为未来的扩展性做好准备。随着云端同步方案的不断发展，我们计划提供更灵活的选择，包括【本地、备用服务器、cos、oss】等选项。通过这种适配处理，用户将能够轻松一键切换不同的上传类型，极大地提升了系统的灵活性和适应性。
5、xc_cloud_upload方法现在对url变量的处理不仅支持url图片，还增加了对宫论媒体库ID的支持。如果传入的是url链接资源，将通过xc_local_is方法进行参数验证和解析。如果验证结果显示资源为本地资源，则返回服务器的真实路径，通过内网数据处理并执行上传请求。如果is_numeric函数返回true，则表明传递的参数是数字类型，此时将通过xc_query_upload方法发起订单查询，通过ID检索对应记录的存在性。如果记录不存在，将返回code=1，表示媒体库资源查找失败；如果记录存在，则会将查询结果赋值到upload数组中。
6、对xc_cloud_upload方法的变量参数结构进行了优化，以提升其高扩展性。优化后，该方法不再接受固定的变量参数，而是改为通过数组结构进行传参处理。在调用此方法时，需传递一个名为【upload】的数组。该数组中必备的参数包括：id（对应宫论媒体库的主键ID值）和key（表示文件的路径及名称，例如XXX/xxxx/22.jpg），文件将会以此名称进行云端同步上传。此外，还可以选择性地传递参数type，用于指定上传的类型和来源。通过这种数组方式传递参数，当未来需要对参数进行变动或调整时，将会更加灵活和便捷。
7、upload数组变量新增了三个字段参数：首先是url字段，该字段用于传递远程图片或本地图片的地址，以便在需要进行云端同步时使用。其次是sort字段，该字段的固定值为"url"或"id"，用于区分当前同步的文件是媒体库类型还是链接类型。最后是delete字段，这是一个布尔值，默认为false。当进行本地文件上传时，如果将delete标记为true，则在文件成功同步到云端后会主动删除本地图片。通常情况下不建议开启此功能，以避免误删文件，但对于临时文件的处理可以考虑启用。
8、在通过xc_cloud_upload发起云端参数同步时，系统首先会检查upload数组是否为空。如果该数组为空，则会立即返回错误信息：“同步失败：数组参数不能为空”。如果upload数组不为空，系统会进一步验证【key、type】两个参数是否已提供，这两个参数是必传项。如果其中任何一个缺失，将返回错误信息：“同步失败：必备参数缺失无法上传”。在确保所有必需参数存在后，系统会根据type参数的值进行进一步的验证。如果type的值为id，系统将检查数组中是否包含有效的ID。如果ID缺失或为空，系统会返回错误：“同步失败：媒体库主键不存在”。如果type的值为url，系统则会验证数组中是否包含有效的URL。如果URL缺失或为空，系统会返回错误：“同步失败：URL参数不能为空”。这些步骤确保在上传过程中所有必要的信息都得到正确处理，以避免数据同步失败。
9、如果所需的所有核心参数都存在，则会进行进一步的核验处理：首先，通过is_numeric函数验证ID是否为数字，如果验证失败，则返回错误【同步失败：媒体库资源查找失败】。其次，通过xc_local_is函数验证传递的url参数是否为本地路径，如果验证失败，则返回错误【同步失败：不是有效的link地址】。最后，检测url是否为外部链接，如果是外部链接，则会尝试通过内置的宫论接口去检测文件的可访问性，如果文件不可访问，则返回错误【同步失败：远程图片不可访问】。
10、通过xc_cloud_upload发起云端资源同步，最核心的环节在于确保文件位于服务器本地。在执行函数前会初始化一个变量local_file，其默认值为空。如果通过媒体ID读取文件，则会使用字段【local】，该字段包含本地文件的绝对路径，并通过宫论API接口上传文件，这种情况下本地文件路径必定存在。如果文件通过URL提供，则会使用xc_local_is函数获取其本地绝对路径。如果文件位于远程服务器，则会先将其下载至本地，并返回临时路径。所有这些处理逻辑的最终目的是获取local_file地址，以便进行后续操作。
11、local_file如果不为空，则表明系统已成功获取到本地文件。此时，系统会通过file_exists函数来验证该文件是否确实存在。如果文件不存在，系统将返回错误提示【同步失败：本地文件读取失败】。若文件存在，系统会继续读取xc_upload_cloud_sort配置字段，以确定所需的同步方式。系统具备高度灵活性，支持多种云端同步方式，并根据配置调用相应的SDK接口（每种云端同步方式所使用的SDK各不相同），从而进入文件的云同步上传流程。

2025年5月20日
1、在执行数据表更新的过程中，xc_update_sql_callback会通过Redis触发计数器统计，标识为：update_sql_callback。此计数器记录数据表更新动作的触发次数，后续可通过get_redis_count($key)获取详细统计信息。该功能支持多维度查询统计，包括总数、今日、昨日、本周、上周、本月、上月、今年及去年等时间维度，方便全面了解数据表更新的频率和趋势。此外，计数器具备监听每日SQL更新调用次数的能力，为数据管理提供了精准的监控工具。
2、xc_update_sql_callback方法进一步扩展处理，加入了日志记录功能。当通过该方法执行缓存清理动作时，支持通过日志记录错误返回。具体操作流程如下：首先，通过内置的统一查询方法获取本次更新的数据表记录。如果获取成功，则根据数据表类型执行相应的缓存更新或其他操作。如果执行失败，则记录当前时间日期、执行用户、执行场景、执行主键ID、以及返回的错误信息到【update_sql】日志文件中。这一功能的加入将大大方便后续运维人员进行跟进和查询处理。
3、在缓存更新场景中，不仅需要关注数据表更新时触发的操作，还必须处理数据表行被删除时的情况。因此，为了确保缓存的准确性，在xc_delete_sql事件中也集成了xc_update_sql_callback方法。这样一来，当系统通过这个方法执行SQL操作删除指定行时，相关的SQL回调动作将会被自动触发，从而主动清理对应的缓存。这种机制有效地避免了数据表删除后由于缓存残留导致前后端查询仍返回过时数据的问题，确保数据的一致性和实时性。
4、xc_update_sql_callback进行了升级优化处理，现在支持xc_do_action(FUNCTION, $result, func_get_args())【宫论动态注册钩子】功能。当通过add_action注册回调函数时，系统会在处理缓存结构后，自动调用并触发预设的方法。此次回调将包含两个变量【table_name：数据表名、id：对应的主键ID值】，这些变量会被发送到注册的方法中，允许在该方法内执行相应的业务逻辑。例如，可以主动清理自己挂载的缓存参数，以确保系统的缓存数据始终保持最新状态。
5、针对SQL更新操作，由于可能会被外部第三方事件挂载一些复杂的方法，这些业务逻辑有可能阻塞整个进程的执行。为了解决这一问题，在执行xc_update_sql_callback操作时，现在统一采用Swoole框架进行处理。通过异步方式处理，可以有效地响应缓存的更新以及附属业务的执行。在具体执行方法时，我们使用xc_is_swoole方法来验证当前是否处于异步状态。如果未处于异步状态，则将操作转发到异步进程进行响应处理；如果已经处于异步状态，则跳过验证，直接进行执行。这种策略优化了系统的响应速度和处理效率，确保业务逻辑的顺畅执行，同时避免了可能的阻塞问题。
6、在 xc_update_sql_callback 函数中新增了一个名为 action 的第三个变量，该变量的默认值为 update，可选值为 delete。当 action 的值为 update 时，表示此次触发是由于数据表的更新操作，此时需要做的就是更新相应的缓存，而无需进行复杂的处理逻辑。而当 action 的值为 delete 时，意味着此次操作是由 xc_delete_sql 触发的删除动作，系统要求删除该记录的所有缓存，而不是执行更新操作。在这种情况下，处理逻辑与更新操作存在显著差异，需要根据 action 的值来决定采用何种业务处理方式，以确保系统正确执行相应的操作。
7、通过宫论封装的方法执行SQL操作时，系统会在操作成功后自动触发相应的callback回调动作。这些回调动作通常用于更新缓存、同步缓存或删除缓存，以确保数据的一致性和可靠性。回调挂载的机制采用统一查询接口设计，只要SQL发生变动，系统会主动更新统一查询方法的缓存，从而保证查询结果的实时性和准确性。此外，该回调机制支持第三方挂载，允许外部注册自定义方法以接收和处理更新事件，进一步增强了系统的扩展性。同时，系统集成了日志记录功能，详细记录每次回调的触发情况，便于运维人员实时监控和排查问题，全面提升了系统的可维护性和稳定性。
8、为了确保宫论中的所有SQL操作能够准确有效地触发xc_update_sql_callback事件，不仅在xc_update_sql和xc_delete_sql方法中集成了该事件，还将其整合到了xc_insert_sql方法中。当通过内置方法生成SQL语句时，系统会主动触发回调，并将action标记为insert插入。如此一来，无论是数据库的统一插入函数、统一修改函数还是统一删除函数，都能够在执行过程中准确有效地执行回调功能。这种设计保证了数据库操作的一致性和可靠性，确保在每次操作时都能顺利触发相应的事件处理机制。
9、新增了一个定时任务计划：xc_task_thumbnail_clear()。该方法无需传递任何参数变量。具体执行时，该方法会主动读取位于 $_SERVER['DOCUMENT_ROOT'] . '/cache/image/temporary/' 的缩略图临时目录文件。如果该目录存在且其中包含临时缩略图图片，则会触发清理函数【xc_delete_path】，请求系统对该目录进行清理操作。由于上传操作的原因，在生成缩略图时，系统会在指定目录中创建一个临时缩略图文件。
10、在后台定时计划配置组中新增了一个固定计划任务，旨在每隔三天自动触发一次，以高效清理服务器上的缩略图临时文件。该任务被命名为“清理缩略图临时文件图片”，其核心功能由函数“xc_task_thumbnail_clear”实现。为确保任务的顺利执行并避免对主进程造成阻塞，我们采用了Swoole技术进行请求转发，使其以异步方式运行。一旦计划生效，系统将定期扫描并清理temporary目录中的缩略图临时文件，防止随着时间的推移文件数量不断增加而占用服务器的磁盘空间。需要注意的是，这些临时文件不需要长期保留，定期清理有助于维持服务器的运行效率。
11、在xc_upload_thumbnail_save方法中，新增了一个名为Cloud的变量，默认值设定为false。当该变量被标记为true时，意味着此次生成的缩略图需要上传至云端，并同步至COS对象存储桶。在此情况下，内部方法将调用腾讯云SDK，发起文件上传请求，并确保上传文件的路径与服务器上的缩略图路径保持一致。如果上传操作成功，将额外返回一个名为【cos】的变量，该变量指向缩略图在CDN上的地址。若上传失败，则不会返回该字段，但本地生成的缩略图仍然会正常返回。

2025年5月19日
1、在处理动态缩略图的过程中，系统不仅会验证处理来源是否为图片类型（image），还会检查设置项xc_upload_thumbnail_open是否处于开启状态。如果该设置项被关闭，系统将跳过缩略图生成过程，并返回错误信息【处理失败：后台已关闭生成缩略图】。此设计旨在避免在后台关闭缩略图生成功能时，系统仍然通过xc_upload_thumbnail_save尝试生成缩略图，从而导致不必要的服务器性能消耗和磁盘空间占用。
2、通过xc_upload_thumbnail_save生成缩略图时，首先会读取原数据表的信息，检查其中是否包含【thumbnail】字段。如果该字段存在，系统会使用file_exists函数检测本地是否已有对应的缩略图文件。如果文件不存在，则表示缩略图可能已丢失或不可用，这时才会通过接口请求并生成新的缩略图。引入这个检测机制，旨在避免在数据表中已有缩略图记录的情况下，重复生成缩略图，从而节省系统性能。
3、新增了一个名为xc_query_upload的统一查询方法，专门用于检索宫论媒体库中的记录。此方法已经集成到【统一查询脚本：query.php】中，并且未来所有针对上传数据表的查询请求都将通过这个方法进行。使用该方法时，需要传递一个固定变量【id】，它对应于xc_upload数据表中的主键ID值。通过这个唯一标识，可以获取相应的媒体库信息。在构建查询请求时，系统会首先验证ID是否存在且为数字；如果验证未通过，则会立即返回false，终止后续的查询操作。
4、在构建xc_query_upload方法时，遵循与其他统一查询方法相似的逻辑流程。首先，通过引用全局变量【wpdb】对象，利用它来创建查询语句，以检索数据表中的【xc_upload】ID匹配的记录。为保证安全性，查询语句通过prepare方法进行参数过滤，从而有效防范SQL注入的风险。查询操作使用get_row方法，确保仅返回一条记录，并通过ARRAY_A选项强制结果以数组形式返回。若查询成功并存在结果，则返回对应的数组信息；若无匹配结果，则返回false。这种严谨的处理方式不仅提高了查询的安全性，还确保了数据返回的准确性和一致性。
5、为了提升系统的灵活性，在统一订单查询功能中引入了更为多样化的ID变量查询方式。除了传统的主键ID查询方法外，现在系统还支持通过CDN加速域名路径进行查询。当接收到一个查询请求时，系统会首先利用is_number函数判断传入的ID变量是否为纯数字或数字字符串。如果是数字字符串，系统将采用主键ID的方式构建查询语句进行数据检索。如果ID变量不是数字，系统将进一步检查该字符串是否包含域名信息。若检测到域名，系统会尝试匹配数据表中的【cdn】字段。一旦匹配成功，系统将按照标准处理流程返回相应的数组结构信息；如果匹配失败，系统则会返回false，提示查询未能成功匹配。通过这种多层次的判断与匹配机制，能够更加高效和准确地响应不同类型的查询请求。
6、在xc_query_upload功能中增加了一个用于缓存控制的开关变量uncache，默认值为false，以启用并优先返回Redis缓存的结果。在系统查询上传媒体库信息时，将会构建一个Redis键位："query_query:" . $id。若启用缓存查询，系统会通过get_redis_meta函数进行缓存查询；如果缓存记录存在，则直接返回缓存数据。如果缓存记录不存在，则系统会使用wpdb语句进行数据库查询，并将结果保存到Redis键位中，以便下次查询时能够直接读取缓存数据。此缓存的有效期设定为30天，考虑到上传记录的变动性较低，因此可以适当延长缓存时间，而无需像其他缓存查询那样保持24小时的实时性。
7、xc_query_upload的缓存刷新机制进行调整优化，因为查询变量ID是同时控制两个字段【1、ID主键，唯一值参数值。2、cdn：媒体文件的CDN加速域名路径】，因此在对缓存操作上的处理，需要同时兼顾上述两个查询结果，避免缓存更新的时候，只更新了其中一个，造成了查询到的缓存结果，与实际的数据表结果存在不一致的情况。具体优化方法为，在涉及redis处理更新的时候，会同时构建两个reidis键位，分别对应上，并同时执行操作。
8、完成统一订单查询【宫论上传媒体库】的方法封装，具体流程如下：1、初始化 Redis 缓存键：基于输入参数 $id 创建 Redis 缓存键 query_upload:<id>。2/检查 Redis 缓存： 如果 $uncache 为 false 且缓存存在： 如果缓存值为 'false'，返回 false（表示之前查询未找到数据）。 否则，返回缓存中的查询结果。3、构建 SQL 查询： 根据 $id 的类型： 如果是数字且长度不超过 8 位，使用 id 字段进行查询。 否则，使用 remote 字段进行查询。4、执行数据库查询： 使用 $wpdb->get_row() 执行 SQL 查询，获取结果。5、处理查询结果： 如果查询成功： 将结果缓存到 Redis，使用 id 和 remote 作为缓存键，设置缓存有效期为 86400 秒（1天）。 返回查询结果数组。 如果查询失败，返回 false。
9、对xc_upload_thumbnail_save方法进行了优化处理。由于已经集成了统一订单查询方法【xc_query_upload】，在生成缩略图时，读取媒体库信息不再使用wpdb构建查询语句，而是采用统一的查询方法。查询时，优先启用缓存机制，如果缓存中存在所需数据，则直接返回缓存结果；只有在缓存中找不到数据时，才会通过wpdb方法发起SQL请求进行处理。需要注意的是，后续所有涉及媒体库资源的查询调用请求都将升级为使用统一的【xc_query_upload】方法。
10、在xc_update_sql中新增了一个监听回调机制：此机制旨在统一管理数据表的修改变更操作，所有数据表在进行操作时（除wp系统自带表外）均需通过此方法发起处理请求。该机制允许接受一个回调方法，用于执行缓存清理和刷新操作。具体实施过程是：当xc_update_sql成功更新数据表记录后，会立即触发回调操作，记录此次操作的数据表名称及其主键ID。随后，将调用一个新封装的方法，该方法专门负责处理订单或记录的缓存需求，确保相关缓存能够得到及时更新和维护，从而提升系统的整体性能和响应速度。此改动不仅简化了缓存处理流程，还提升了数据变更的可控性和系统稳定性。
11、新增了一个名为 xc_update_sql_callback 的方法，用于在 SQL 更新后触发缓存刷新的事件处理。该事件会接收两个参数：1. table_name（数据表名），该参数始终包含 wp_ 的数据表前缀。如果缓存处理逻辑需要验证表名，需通过 $wpdb->prefix 检查表名前缀的合法性；2. id（数据表的主键 ID 值），此参数为唯一标识符。该方法通过 id 和 table_name 的组合来定位具体更新的行数据。在方法执行前，会进行必要的参数校验：首先检查 table_name 是否为已存在的合法数据表，若不存在则判定为非法请求；其次检查 id 是否为有效的数字类型，以确保数据的准确性和安全性。这一设计旨在提高缓存刷新操作的精准性和稳定性，同时避免因参数异常导致的潜在安全隐患或数据处理错误。

2025年5月16日
1、宫论上传接口的配置中心新增了一个字段：xc_upload_thumbnail_open，该字段用于设置是否开启上传图片时自动裁剪生成缩略图的功能。此功能为可选项，用户可以根据需求自行决定是否启用。当用户选择开启该功能时，系统将在上传图片时自动触发缩略图处理逻辑。通过内置的接口，系统会对上传的图片进行缩略图处理，并将处理后的缩略图保存至本地，同时同步至云端。这样一来，在后续调用时，系统能够自动检测是否存在对应的缩略图，并根据检测结果执行相应的业务逻辑，优化图片加载速度和用户体验。
2、在后台启用xc_upload_thumbnail_open功能后，页面将新增显示以下字段参数：首先是xc_upload_thumbnail_size，该参数用于设置缩略图尺寸的触发要求，以整数形式表示，单位为MB，并精确到小数点。例如，如果设置为0.1MB，则当图片小于100KB时不会触发缩略图处理，因为图片尺寸过小，无需生成缩略图。其次是xc_upload_thumbnail_directory，该参数指定缩略图的上传目录，所有接口生成的缩略图都会统一上传到这个目录进行存储。这样可以有效管理和存储缩略图，确保资源的合理利用和访问的便捷性。
3、在缩略图的配置方面，除了可以设置尺寸生成条件和目录外，还可以调整以下参数字段，以满足特定需求。首先，参数“xc_upload_thumbnail_mime”用于指定生成缩略图的格式，常见的格式包括jpg和png。建议根据实际需求进行选择，除非有特殊要求，否则尽量避免使用其他格式，以防止兼容性问题的出现。其次，参数“xc_upload_thumbnail_width”用于定义裁剪时的宽度要求。例如，如果设置为500px，缩略图的宽度将固定为500px，而高度则会根据比例进行自动适配。这种灵活的配置方式确保了缩略图在不同平台和设备上的良好显示效果。
4、在生成缩略图的过程中，为了实现更灵活的配置处理，引入了一个新的切换选项卡字段：xc_upload_thumbnail_type。这一字段包含两个选项，分别对应不同的裁剪策略。用户可以根据需求选择通过宽度或高度来适应裁剪，从而生成符合要求的缩略图。具体而言，如果选择“高度”作为裁剪依据，系统将展示xc_upload_thumbnail_height字段，用户可以在此填写所需的缩略图高度，随后宽度将自动调整以适应该高度。同样地，如果选择“宽度”作为裁剪依据，则会展示相应的宽度设置字段，系统将根据填写的宽度进行自适应处理，以确保缩略图的完整性和视觉效果。
5、在宫论数据表【xc_upload】中，我们新增了一个名为“thumbnail”的字段，用于存储缩略图地址。这个字段的类型设置为VARCHAR，最大长度为255字符。当系统生成缩略图后，会自动对其进行裁剪处理，以便在需要调用缩略图时进行展示。调用时，系统会优先检测媒体上传表中的thumbnail字段，若该字段不为空，则直接读取并展示对应的缩略图；若为空，则会通过其他方式进行处理。通常情况下，在发起上传请求时，缩略图会自动生成并保存，确保上传内容的高效处理和展示。
6、宫论通用上传脚本【upload.php】无论是通过H5、APP、网页还是小程序进行上传，均由该脚本负责处理文件上传操作。当前，该脚本具备监听image类型的功能，当图片上传请求完成后，会自动检测配置项xc_upload_thumbnail_open的状态。如果该配置项处于开启状态，脚本将读取此次上传的图片，并根据后台设置的参数，调用xc_imageManage_sdk进行缩略图处理。生成的缩略图会被移动至后台指定的目录，并将其路径保存到xc_upload数据表的thumbnail字段中，以便后续使用。这一流程确保了图片上传的高效管理与处理，提升了系统的灵活性与可扩展性。
7、在进行上传脚本的设计时，意识到直接在上传过程中处理缩略图可能会限制后续的调整和优化。考虑到可能会出现需要重新生成缩略图的场景，例如检测到缩略图缺失时自动生成，因此决定封装一个专门的方法来处理这些需求。我们创建了名为xc_upload_thumbnail_save()的方法，该方法的作用是接收【xc_upload】的主键ID，然后从数据库中读取相关数据，并将其保存到一个thumbnail数组中。这样设计的好处是后续所有与缩略图相关的操作都将集中在这个数组中进行，确保了处理的灵活性和可扩展性。通过这种方式，不仅提高了系统的稳定性，还为未来的功能扩展提供了便利。
8、现在xc_upload_thumbnail_save返回的标准数组结构，以便上级可以知道具体的处理结果。如果返回code=1，则代表处理失败，这个失败是多样的，一般有以下情况：文件读取失败，操作失败，保存失败，权限问题。数据表查找失败，数据表对象不存在，也会造成这个错误。需要根据msg去获取具体的错误原因。code=0则代表处理成功，这个处理成功是值得是，缩略图生成到指定文件，并且对应的数据表主键thumbnail完成了回调写入动作。
9、整个xc_upload_thumbnail_save方法的处理流程如下：首先通过xc_get_sql方法读取上传数据表的信息，如果读取失败则返回错误，目前该方法仅支持宫论媒体库文件来生成缩略图。然后获取到本地图片，并解析绝对路径。读取后台的具体配置参数（生成要求），然后通过xc_imageManage_sdk发起生成缩略图处理，如果发生错误，则将错误继承下来，并进行输出处理。如果生成成功，则读取临时缩略图，将图片移动到后台配置的目录，并将移动后的地址保存到数据表【通过：xc_update_sql进行数据表回调操作】，返回操作成功，结束整个生成动作。
10、通过xc_upload_thumbnail_save生成缩略图成功后，会立即执行两个动作（也可以理解为操作回调处理）1、首先会将xc_imageManage_sdk接口产生的临时图片，进行主动删除处理。2、通过redis发起计数器统计功能，统计标识为：upload_thumbnail，记录系统缩略图的生成次数。后续可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
11、在宫论的上传接口（upload.php）中，当图片成功上传后，将触发xc_upload_hook_success($id)回调钩子，以启动【缩略图生成】的动作。具体操作包括读取上传文件的主键ID，然后利用Swoole发起异步执行请求，以生成该图片的缩略图。异步执行的函数是：xc_upload_thumbnail_save。需要特别注意的是，这里采用异步处理方式是为了避免阻塞进程，确保系统的高效运行。在异步处理缩略图的生成过程中，有效规避了因IO操作可能导致的各种意外情况，提高了整体系统的稳定性和响应速度。

2025年5月15日
1、在nginx配置自动缩略图功能之外，新增了一个内置处理脚本方法：xc_imageManage_sdk()。该方法专门用于对图片进行多种处理操作，考虑到实际应用场景中，图片的处理需求多种多样，比如格式转换、尺寸调整、质量压缩以及裁剪处理等。为了能够灵活应对不同的上传场景，决定将这些功能封装到一个扩展中，使得在后期使用时可以方便地直接调用。该方法默认依赖于imageManage组件进行处理，确保了处理过程的高效性和一致性。通过这种方式，不仅提升了系统的灵活性和可扩展性，也为开发人员提供了更为便捷的工具，以满足不断变化的业务需求。
2、xc_imageManage_sdk方法需要传递两个变量参数来进行图片的处理。第一个参数是image，即图片的地址，也就是需要处理的图片。当前该方法仅支持通过图片链接来传递图片参数，不支持直接传递图片对象。第二个参数是option，用于配置具体的处理操作。目前计划支持以下几种操作：首先，可以调整图像的尺寸，包括宽度和高度的修改，以满足不同的需求。其次，提供图像压缩功能，能够在保持图片原有尺寸规格的情况下进行压缩处理，压缩比可以在30%到100%之间调节。此外，还支持图片格式的转换处理，例如将PNG格式的图片转换为JPG格式。最后，针对某些上传场景中图片会自动横向旋转的问题，增加了旋转图片方向的功能，以便对图片进行复原处理。
3、在使用 xc_imageManage_sdk 对图片进行处理时，系统会对传入的 image 变量参数进行详细的检查和处理。当传递的是宫论域名时，程序会自动调用内置方法，将其转换为本地的绝对路径。例如， 链接 会被自动转换为 /www/wwwroot/www.acocoa.com/1.jpg。此功能仅支持宫论主域名的路径，并且会通过 xc_home 函数来验证域名信息的正确性。这样的处理方式有效地增强了 image 变量的扩展性和灵活性。
4、在调用内部SDK进行图片处理操作时，系统将返回一个标准化的数组结构，以确保后续处理能够及时响应并进行处理。当返回的code为0时，表示图片处理已成功完成。此时，根据传入的option参数，对原始图片进行进一步的扩展操作，后续的处理将由上层方法继续执行。若返回的code为1，则表示处理失败。失败的原因可能多种多样，包括文件不存在、权限不足、内部异常错误或方法调用错误等。具体的错误原因需查看msg参数以便进行准确的诊断和解决。
5、在进行图片操作时，系统会按顺序执行以下检查步骤，以确保文件可以被操作。首先，通过parse_url函数解析当前请求的URL路径，从中提取出文件名和域名等参数信息。如果请求的域名属于宫论域名，则获取对应的本地路径；否则，系统会立即返回，提示文件不支持操作。接着，系统使用file_exists函数检测文件是否存在，如果文件不存在，则返回相应的错误信息。随后，系统通过$manager->make方法尝试读取本地文件，如果在读取过程中出现异常，则返回相应的错误提示。最后，如果文件读取成功，系统会解析文件的MIME类型，以确保其为支持的类型；如果MIME类型不被支持，系统会返回错误信息。
6、宫论内置图片处理SDK现已扩展功能，不仅支持本地服务器图片的处理，还能处理外部图片。由于外部图片涉及下载操作，因此需要特别谨慎对待。具体流程如下：系统首先使用parse_url函数解析图片路径。如果图片来自本地服务器或是宫论域名指向的链接，则按照预设的参数进行处理。如果路径指向外部域名且包含scheme，则视为外部图片，此时系统会使用file_get_contents函数进行读取，读取操作设置了5秒的超时时间，以防止阻塞进程。若读取成功，图片将被暂时存储在临时文件中，随后按照标准流程进行
7、在使用 file_get_contents 发起远程图片下载请求时，为了确保安全性，将采取以下步骤进行处理。首先，会检查下载图片的文件名，确认其格式是否为支持的图片类型，如 jpg、jpeg、png、webp 等。如果文件格式不在支持列表中，将直接跳过此文件，避免下载非图片文件。接着，发起请求时会使用 @ 符号来抑制可能出现的警告，并通过 error_get_last 捕获潜在的错误信息。如果在下载过程中发生任何错误，将立即返回错误信息并中断操作。最后，还会检查图片是否成功保存，因为保存失败可能是由于权限等问题引起的。如果保存不成功，将返回相应的错误提示，以便进行进一步的排查和处理。
8、在使用 xc_imageManage_sdk 进行图片操作时，一旦成功读取图片对象，系统会立即调用并加载 SDK，同时创建一个 ImageManager 实例。接着，选择适合的图像处理库（如 gd）来进行处理，并将结果保存到【manager】中。此后，所有的图片操作都将通过这个对象进行管理。如果 SDK 初始化失败，或在 $manager->make 加载图片信息时遇到问题，系统将返回相应的错误信息，并中断当前任务的执行流程。
9、在使用ImageManager对图片对象进行操作和处理（如扩展、调整、压缩、转换）时，系统会采用try-catch机制来捕获异常。这些异常是在内部SDK进行对象操作时可能出现的。任何错误都会导致执行立即中断，系统将返回code=1，并附带具体的错误信息。与此同时，系统会将错误详细信息写入日志中。日志内容包括【处理时间：Y-m-d H:i:s，处理文件：由传入参数指定的image，处理请求：需要进行JSON转换的option参数，以及通过try-catch捕获的错误原因】。这些信息会被记录在【imageManage_sdk】日志中。需要注意的是，这类错误不会触发报警系统，仅负责错误信息的记录和存档，以便后续分析和改进。
10、在通过xc_imageManage_sdk发起图片处理请求并成功处理后，系统会将处理成功的图片直接保存到【$_SERVER['DOCUMENT_ROOT'] . '/cache/image/temporary'】目录中。如果在保存过程中出现失败，将会触发错误并终止脚本的执行。然而，一旦保存成功，系统将返回一个code=0的响应，同时附带一个额外的字段：link。这个link字段包含了指向已保存文件的路径。需要注意的是，为了防止文件名重复，文件命名采用了时间戳加随机数的方式进行生成，确保每个文件名的唯一性。
11、宫论通用图片处理SDK已完成封装处理，整个执行流程如下：1/输入参数：接受两个参数，image（图片地址）和 option（操作配置）。只支持通过图片链接传递，不支持直接传递图片对象。2、当 image 参数为宫论域名时，通过内置方法转换为本地绝对路径，确保处理的是合法的本地资源。3、对本地图片，检查文件是否存在并验证其MIME类型。4、对外部图片，下载并保存至临时文件夹，设置5秒超时以防止阻塞。5、使用 ImageManager 实例化处理引擎，默认使用 gd 库。如遇初始化或加载错误，立即返回错误信息。6、执行图片操作：根据 option 参数执行图像尺寸调整、压缩、格式转换及旋转等操作。过程中使用 try-catch 捕获异常，确保稳定性。7、处理成功后，图片保存在 /cache/image/temporary 目录中，采用时间戳和随机数生成唯一文件名。返回成功响应 code=0 及图片访问链接。8、任何操作错误均返回 code=1 并记录详细错误日志，包括处理时间、文件、请求参数及错误原因，便于后续分析。

2025年5月14日
1、在xc_delete_path功能中增加了删除错误的报警日志记录：在执行过程中，若遇到以下错误情况，将触发日志写入处理。首先，当realpath解析文件路径失败，即路径不存在或无法解析为有效路径时，将记录日志。其次，当file_exists返回false，意味着文件请求失败且无法找到对应文件时，也会记录。第三，在使用is_file和@unlink尝试删除文件时，如果删除失败，将记录相应的错误信息。此外，使用is_dir和opendir打开并读取目录及其子目录时出现错误，同样会触发日志记录。最后，若在使用rmdir方法删除目录时发生异常错误，日志系统也会进行记录。以上所有场景均会触发相应的日志写入，以便进行后续的错误分析和处理。
2、在xc_delete_path操作中，当触发错误日志写入时，系统将记录详细信息以便于后续排查。具体记录内容包括：操作时间，以"年-月-日 时:分:秒"的格式记录；删除的文件，记录传递的参数，路径或目录的本地路径；删除执行用户，通过xc_is_login方法获取当前用户的UID，若操作由系统执行则记录为0。错误原因将根据具体的删除失败原因进行定义处理。日志的写入通过通用方法xc_log_error_warn执行，并附上唯一标记"delete_path_error"以便识别。需要注意的是，该日志仅用于记录失败原因，不会触发报警，旨在为运维人员提供便利的故障排查依据。
3、为了提高删除文件过程的可靠性，特别是针对可能出现的磁盘IO响应问题，引入了 try-catch 块以捕获和处理任何潜在的异常。当系统检测到错误时，通过 throw new Exception('错误消息') 抛出相应的异常。在 catch 块中，我们能够捕获这些异常，并根据具体的异常信息返回相应的错误响应。特别是在遇到权限不足或路径不存在的情况时，系统将抛出特定的异常，并在 catch 块中返回相应的错误提示。需要注意的是，原有的错误记录方式保持不变，新增的 try-catch 模块仅用于捕获系统级的异常错误，旨在进一步确保执行 xc_delete_path 方法的稳定性和可靠性。
4、本地压缩图脚本【ImageManager】完成封装处理，该脚本的执行顺序为：通过 require 'vendor/autoload.php'; 自动加载 Composer 的依赖包，使用 Intervention\Image\ImageManager 创建一个图像管理器实例，选择使用 gd 作为图像处理库。使用 parse_url() 函数解析当前请求的 URL 路径。通过 basename() 获取请求路径的文件名。组合文档根目录 $_SERVER['DOCUMENT_ROOT'] 和请求的 URI $_SERVER['REQUEST_URI'] 来生成文件的完整路径。使用 urldecode() 解码文件路径以确保任何 URL 编码的字符被正确解析。使用正则表达式 preg_replace() 去除 URL 中的 ?image/* 部分，以获得实际文件路径。定义缓存目录为 $_SERVER['DOCUMENT_ROOT'] . '/cache/image/'。获取当前的年份和月份，构造按年月归档的缓存目录路径 '/cache/image/' . $month . '/'使用 file_exists() 检查缓存目录是否存在，若不存在则使用 mkdir() 创建目录。检查查询字符串中是否包含 image/，以判断是否需要进行图像处理。若请求文件是 GIF 格式，将其转换为 JPG 格式。检查缓存文件是否存在，若存在则直接输出缓存内容，否则进行图像转换并缓存结果。使用正则表达式解析查询字符串中请求的宽度参数。若请求为指定宽度的图像，检查缓存文件是否存在。如果不存在缓存，加载图像并进行宽度调整（保持纵横比）。保存处理后的图像至缓存目录，并输出结果。如果不需要处理或者处理条件不满足，检查文件是否存在。若文件存在，则直接输出原始图像。若文件不存在，则返回 404 错误。每个成功输出（缓存或处理后的图像）都设置适当的 Content-Type 并终止脚本执行以防止继续执行不必要的代码。
5、xc_task_clean_image_cache脚本完成封装处理，该脚本为自动清理非当月的图片缓存文件，执行流程如下：使用 date('m') 获取当前月份，格式为两位数的字符串（如 "05" 表示五月），通过 $_SERVER['DOCUMENT_ROOT'] . '/cache/image/' 获取缓存目录的完整路径。使用 is_dir($cacheRootDir) 检查缓存根目录是否存在。如果不存在，函数直接返回，不执行任何操作。使用 opendir($cacheRootDir) 打开缓存目录，返回一个目录句柄。使用 readdir($handle) 读取目录中的每个条目。通过 while (false !== ($entry = readdir($handle))) 循环遍历目录中的每个文件和子目录。如果读取到的条目是当前目录 . 或父目录 ..，则使用 continue 跳过。构造完整路径 entryPath 为 cacheRootDir . $entry。使用 is_dir($entryPath) 检查条目是否为目录。确保该目录名与当前月份不同 ($entry !== $currentMonth)。如果目录不是当前月份的，则调用 xc_delete_path($entryPath) 函数删除整个目录及其内容。使用 closedir($handle) 关闭已打开的目录句柄，以释放资源。
6、宫论系统计划配置中心：新增了一个【间隔 [7天执行] 任务】，该任务每隔7天会触发一次，任务名称为“定时清理非当月的缓存图片”。触发函数为：xc_task_clean_image_cache。由于目前尚未对异步执行逻辑进行充分的实测，因此暂时不启用异步处理，而采用同步方式触发。这样设计每7天执行一次的任务，是为了防止上次执行时可能出现的异常情况导致清理不完全，每隔一周进行检查更为稳妥。
7、新增nginx配置信息【location ~* \.(jpg|jpeg|png|bmp|gif|GIF)$ 】匹配以 .jpg, .jpeg, .png, .bmp, .gif, 或 .GIF 结尾的 URL。这些通常是图像文件的扩展名。if ($args ~* "image/")：检查 URL 请求参数（即 $args，例如 URL 中的查询字符串 ?key=value）是否包含字符串 "image/"。不区分大小写。rewrite ^ /sdk/ImageManager.php last;：如果条件为真（即 URL 参数中包含 "image/"），则重写请求路径，将其重定向到 /sdk/ImageManager.php。last 表示这是最后一条重写规则，处理完后立即执行新的请求。expires 30d;：为匹配的文件设置缓存头，指示客户端和中间缓存（如代理服务器）缓存这些图像文件 30 天。如果请求的查询字符串中包含 "image/"，则将请求重写到一个 PHP 脚本（/sdk/ImageManager.php）。
8、通过精心配置的Nginx，服务器现已能够高效处理本地图片的请求。当用户请求图片时，若请求URL中附带了类似【?image/width/960】的参数，Nginx会将该请求转发至一个专门的图片压缩缓存脚本中。此脚本首先会自动检查所需的缩略图是否已存在于缓存中：如果存在，则直接返回本地缓存的缩略图；如果不存在，则根据请求的参数调用SDK对原图进行压缩，生成所需尺寸和规格的缩略图，并将其保存到本地缓存。最后，处理完成的图片会被返回给用户。通过这种机制，服务器不仅能够动态生成符合请求参数的缩略图，还提升了图片请求的响应效率。
9、对 sdk/ImageManager.php 脚本进行了逻辑优化，以应对未来巨大的请求量。由于该脚本会被 Nginx 转发，尤其是大量的缩略图请求都会经过此脚本处理，原有方案在处理时，首先加载 SDK 然后进行图片判断处理，这导致即使缓存文件已存在，每个请求仍然需要调用 SDK，增加了不必要的性能开销和服务器资源消耗。为此，对脚本进行了调整：在请求响应阶段，首先生成缓存目录及其对应的路径，然后检查缓存文件是否存在。如果缓存文件存在，则直接输出结果，避免不必要的 SDK 调用；如果缓存文件不存在，才加载 SDK 进行处理。通过这种优化策略，有效减少了不必要的资源浪费，提高了服务器的处理效率。
10、通过ImageManager脚本进行处理图片的时候，现在会触发redis计数器，脚本会通过xc_redis_count('request_image')来进行计数统计处理，记录本地缩略图图片的请求量，注意这里是统计的是所有缩略图处理量，而非SDK调用的次数，调用缓存的时候也会触发。可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。
11、redis现在除了会统计缩略图的请求量外，还会统计本地（文件、目录）的删除次数。当通过xc_delete_path方法成功删除了一个文件的时候，会主动通过通过xc_redis_count('delete_path')来进行计数统计处理，记录服务器文件删除数量，这个删除不仅限于缩略图、任何文件的删除都会触发，而且删除目录的时候，会对遍历删除的每个文件都会重复计数，以确保删除的精准度。可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。

2025年5月13日
1、ImageManager封装一个固定脚本【sdk/ImageManager.php】该脚本通过parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)来处理并解析当前请求地址，如果请求地址包含image目录、并且携带了width、height那么便触发执行请求，在触发执行压缩或者读取缓存文件前，会检测文件是否为image的mime类型，如果不是也会拒绝。同时会检测源文件其高度或者宽度是否大于传递的参数，如果不大于也会跳过处理。
2、在mageManager.php脚本中，我移除了WordPress核心库的加载【require 'wp-load.php';】。这是因为这个脚本的主要任务是自动化处理本地所有图片。如果在每次请求时都加载WordPress核心库，会严重影响性能，导致整个响应速度不够及时，用户在前端的加载速度因此变得非常缓慢，进而带来糟糕的用户体验。mageManager脚本专注于对每张图片进行压缩、缓存、读取等自动化和响应式处理，因此需要确保其运行的高效性和快速响应。
3、由于缓存文件随着时间的推移会不断累积，这不仅导致缓存目录体积逐渐增大，还会造成服务器磁盘空间的过度占用，并且影响IO操作的查询效率。为了解决这个问题，决定在生成缓存目录时，采用按【年月】归档的策略。具体来说，前期将以年来进行归档，后期则改为按月进行归档。在实施过程中，将在缓存目录下新增一个以【Y-m】命名的子目录。当需要写入缓存文件时，如果当前年月目录不存在，则会自动创建并在该目录中进行写入操作。与此同时，将定期通过计划任务清理非当前月的缓存文件，从而实现缓存的自动化管理和清理，避免所有缓存文件永久保留的问题。
4、图片文件压缩脚本的年月归档的处理逻辑如下【包含image.php和ImageManager.php】两个脚本的处理应用，在构建压缩缓存目录的会通过date('Y'）和date('m'）来获取当前的年和月，然后通过$cacheDir = $_SERVER['DOCUMENT_ROOT'] . '/cache/image/' . $year . '/' . $month . '/';
方法来生成生成按年月归档的目录路径。当前因为设计规划问题，因此不需要通过按年归档，因此会移除year目录的处理。后期业务量需求进行恢复即可。
5、新增了一个定时任务脚本：xc_task_clean_image_cache()，该脚本的主要职责是清理宫论项目的本地图片缓存。其业务逻辑相对简单，首先获取当前月份，即$month = date('m');。然后，该脚本会扫描缓存目录，路径为$_SERVER['DOCUMENT_ROOT'] . '/cache/image/'，如果发现任何不属于当前月份的子目录，则会执行清理操作，删除所有相关的缓存文件。缓存的目录结构是$_SERVER['DOCUMENT_ROOT'] . '/cache/image/' . $month . '/'。值得注意的是，如果缓存采用年度归档方式，则可以通过date('Y')获取对应年份，以确定需要清理的对象。这样设置的目的是确保缓存文件得到及时清理，以节省存储空间和提升系统性能。
6、xc_task_clean_image_cache 的处理流程如下：首先，使用 date('m') 获取当前月份，以便确定需要保留的缓存目录。接着，将服务器的文档根目录与 /cache/image/ 路径组合，明确缓存文件的存放位置。如果缓存根目录不存在，系统会输出提示信息并终止执行流程。然后，通过 opendir 打开缓存目录，并逐一遍历其中的每个条目。在遍历过程中，会跳过当前目录 . 和父目录 ..。对于每一个目录条目，如果该目录不属于当前月份，将对其进行删除操作（删除动作后续会进行封装处理）。最后，在遍历完成后，关闭目录句柄以释放资源。
7、在宫论自定义函数库中，新增了一个名为 xc_delete_Directory($dir) 的处理方法。这个函数旨在递归地删除指定目录中的所有文件和子目录，然后再删除该目录本身。函数的设计逻辑如下：首先，使用 opendir 和 readdir 来遍历目录内容，确保能识别并处理每一个文件和子目录。对于每一个子目录，函数会递归调用自身，以便彻底清除所有层级的文件和文件夹。只有在所有内容都被成功删除后，才会尝试删除最初传入的目录。值得注意的是，如果传入的路径并不是一个有效的目录，函数会立即返回，不进行任何操作。这种实现方式是因为 PHP 自带的 rmdir() 函数只能用于删除空目录，因此在处理非空目录时，必须先清空其中的内容，再调用 rmdir() 删除目录本身。这个方法只需要接收一个变量，即 $dir，代表需要删除的目录路径。整体而言，这个方法通过使用 while 循环来遍历并删除所有文件和子目录，从而确保目录被彻底清空后删除。
8、xc_delete_Directory 函数现已优化，能够同时处理单个文件和目录。具体实现中，通过 is_file($path) 判断给定路径是否为文件：如果是文件，则直接执行删除操作；如果不是文件，则进入目录处理逻辑。由于在许多场景下会收到单一文件删除的请求，因此将文件删除与目录删除整合成一个方法更为合理。这种方法不仅简化了代码结构，还提高了功能的复用性。在实现过程中，需要特别注意的是，文件和目录的删除操作必须基于服务器的绝对路径进行。如果未来的删除请求需要通过域名来完成，可能需要进行适配处理以确保功能的正确性。此外，为了保持代码的一致性和易读性，将函数命名规范化为 xc_delete_path。
9、对xc_delete_path的语法进行了进一步的优化，现在处理结果将返回标准化的数组结构。具体来说，code=1表示处理失败，通常有两种原因：一是文件或目录不存在，无法找到目标；二是删除权限不足，无法执行删除操作。对于这些错误，用户可以通过msg获取详细信息。code=0则表示操作成功，msg中会显示“删除成功”。此外，也考虑到在处理大量文件删除请求时可能会耗费较多时间，为避免执行中途被迫退出，在内部脚本中加入了【set_time_limit】，以确保执行时间不会受到限制。
10、在执行缓存文件清理任务时，xc_task_clean_image_cache首先会遍历检查缓存目录【/cache/image/】中的所有子目录，并筛选出不属于当前月份的目录。这些过期目录会被标记为待删除，并通过xc_delete_path方法发起删除请求，从而对非当前月份的缓存目录进行清理。在执行这个清理动作时，并不会对删除结果进行监听或确认，只需确保指令已执行即可。为防止误删重要目录，代码中特别使用了$entry == '.' || $entry == '..'的条件判断来跳过当前目录和父目录，从而避免对根目录的误操作。
11、xc_delete_path进一步优化处理，当递归删除目录中的某个文件或子目录失败时，函数会立即退出并返回错误信息。这意味着一旦某个文件或子目录删除失败，函数不会继续尝试删除其他文件或子目录。中途退出等同于导致整个任务的执行退出，这不符合目前清理需求，因此这里做出调整，中途删除失败不会退出，而是将错误信息记录到$errors[]对应数组中，并进行返回处理。这样仍旧会返回code=0，但是如果存在$errors字段，则说明有文件因为各种原因是删除失败的。删除原因是包含被删除的文件地址+错误原因

2025年5月12日
1、通过ImageManager处理本地缩略图的时候，会进行一个优先级的判断处理 通过【 $cacheDir . md5($file) . '.jpg'】生成一个换成文件名地址，其中cacheDir指向的路径为： $_SERVER['DOCUMENT_ROOT'] . '/cache/image/，该路径为缓存目录，file是文件名称地址，防止过长或者存在中文等敏感参数字符，会使用MD5进行加密处理。生成了缓存文件名称，后在执行访问请求的时候，会优先对其进行file_exist检查处理，如果存在，则说明本地缓存文件存在，需要执行不同的业务处理。
2、在使用Intervention方法构建本地图片缓存时，当系统检测到当前对象已存在缓存文件时，首先会通过PHP内置函数readfile读取对应的文件内容。随后，系统通过header函数设置HTTP头部【Content-Type: image/jpg】，明确告知浏览器当前加载的文件类型为图片。最后，通过调用exit函数终止后续的所有操作。这种处理方式有效地利用缓存文件，直接读取并输出图片，同时通过适当的HTTP头部标记，确保浏览器正确识别并展示图片内容。
3、对缩略图压缩脚本进行了优化，集成了一个动态的width宽度变量参数。在ImageManager执行缩略图生成计划时，系统首先会进行关键检测，检查图片路径中是否包含width参数。如果路径中没有该参数，处理流程将自动跳过，避免不必要的资源浪费。然而，如果路径包含width参数，系统将会提取并解析该参数，将其保存到变量【widtch】中。在生成缓存文件名时，该变量会作为关键参数之一参与命名，这使得系统能够支持生成不同宽度的缩略图，突破了传统的单一压缩模式限制。例如，对于路径"1812_1744421566.jpeg?image/width/960"，其中的960即为指定的图片压缩宽度。这样，用户可以灵活地指定所需的缩略图尺寸，提升了系统的适应性和实用性。
4、通过内置SDK接口生成本地缩略图时，会image manager实例并加载本地要处理的图片，然后将返回的对象赋值到image。随后会进行计算处理，如果图片宽度大于等于请求的宽度，则进行缩放处理。处理计算方式为【$image->width() >= $width】如果图片不符合这一条件，则会跳过此次处理。这种处理方法有效地避免了当原始图片宽度小于请求的压缩宽度时被强制压缩的问题。例如，当加载的图片尺寸为500x500，而压缩请求尺寸为960时，如果不进行条件判断，会导致反向压缩问题，结果是返回的图片不仅不清晰，反而尺寸更大。通过这种方法，确保图片质量的同时也优化了处理效率。
5、如果符合压缩条件，并且缓存文件并未存在的情况。则图片会进行如下的处理。1、通过Intervention Image SDK来调整图片的大小，$width：指定要调整的图片宽度（该参数由传参进行获取，可自定义。默认参数为960）。高度参数为 null，表示高度将自动计算以保持宽高比。2；function ($constraint) { $constraint->aspectRatio(); }：这是一个匿名函数，传递给 resize 方法，用于设置约束条件。3、$constraint->aspectRatio();：确保图片在调整大小时保持其原始的宽高比。4、$image->save($cacheFile, 80)：这行代码将处理后的图片保存到指定的缓存文件路径。80：指定保存图片的质量。
6、在完成图片压缩动作处理后，会通过回调接口检测是否保存成功，如果保存成功的情况下会使用file_exists检测文件是否存在，如果保存成功，并且缓存文件承载的情况下，则会执行header('Content-Type: image/jpg')，设置HTTP头部信息，告知浏览器本次请求是图片，然后通过$image->response()输出对应的图片信息，加载本次压缩成功的图片。整个压缩的动作至此就宣告结束。注：先检测是否有缓存、在检测是否符合条件，然后进行压缩保存，最后返回。
7、在调用SDK对图片进行压缩处理的过程中，可能会出现多种无法继续压缩的情况，例如：图片不符合压缩条件、文件格式不被支持、压缩过程失败等。当遇到这些问题时，系统将会触发一个回源处理机制。首先，通过file_exists函数检测原始文件是否存在。如果文件存在，系统将尝试直接输出原始文件内容，以保证用户能够访问到图片。如果图片地址不存在，则系统会发送一个HTTP 404状态码，以告知用户资源未找到：header("HTTP/1.0 404 Not Found");。无论处理结果如何，脚本都会在最后通过exit;命令终止执行，确保流程的完整性和稳定性。
8、为了更加灵活地调用SDK接口来处理各种缩略图任务，不仅支持通过指定宽度进行高度自适应的压缩图任务，还新增了指定高度、宽度自适应的压缩方法。用户在传递图片地址参数时，只需使用【1812_1744421566.jpeg?image/height/960】格式进行传参，系统会自动检测图片的高度，并在高度超过960的情况下进行压缩处理。整个压缩过程与宽度自适应的处理方式相同，确保不破坏原有的宽高比，同时将压缩后的图像质量设置为70。此外，经过压缩处理的图片会进行本地缓存，优化后续访问速度，提升用户体验。这样不仅增强了系统的灵活性，也提高了图片处理的效率和质量。
9、在处理压缩请求的时候，系统会进行严格的写入权限检查，首先检测缓存目录【$_SERVER['DOCUMENT_ROOT'] . '/cache/image/'】是否存在，如果不存在的情况，则会通过 mkdir($cacheDir, 0755, true)进行目录创建，并将权限设定为0755，如果写入失败，则说明权限分配存在问题，这时候会执行两个动作。1、溯源处理，直接读取原来的图片，并进行加载输出到浏览器。2、触发日志的写入动作，将错误信息写入到【ImageManager】这个日志log中。错误日志包括，时间、权限返回错误信息、原图片地址、操作的用户ip信息。
10、在宫论后台系统，新增了一个名为【ImageManager】的日志报警功能，以便在图片压缩过程中出现问题时能够及时响应。目前，该功能会在以下两种场景下触发：首先，当由于权限问题导致无法写入缓存文件时，系统会主动记录相关错误信息并触发报警；其次，在调用压缩组件进行操作时，如果遇到格式不支持或文件不支持的情况，也会产生错误异常并记录日志。为了确保运维人员能够及时处理这些问题，该报警功能会通过邮件、微信公众号和短信三种方式通知他们。报警机制设计为每日触发两次，当连续出现30次错误时便会触发通知，并在触发后自动重置计数器，以确保问题得到持续监控和及时解决。
11、宫论压缩脚本针对GIF文件的处理进行了优化。新的逻辑不仅仅依赖于文件名的格式，还会检测对象中的MIME类型参数，确保其为【image/gif】才会触发处理，从而修复了之前仅凭文件名检测而导致的不严谨问题。此外，考虑到某些GIF文件可能非常大，例如超过10MB的动画，强制进行压缩处理可能会导致系统性能负担过重，影响其他进程的正常运行。因此，脚本增加了对文件大小的检测机制：如果GIF文件大于8MB，将自动跳过压缩处理。只有在符合所有条件的情况下，才会调用$image->save方法，将GIF文件转换为临时的JPG格式并进行缓存保存。通过这一优化，脚本在保证处理效率的同时，也有效避免了不必要的资源消耗。

2025年5月9日
1、xc_is_status方法进行优化处理，该方法现在需要传递三个变量。1、 $table_name 数据表名称，目前支持 'consignment' 表和 'express_delivery'数据表。这个参数只支持数据表明，不支持其它参数，方法也是检测指定数据表的状态参数返回。2、status：状态的标记名称，比如传递wait，返回某个表这个状态的中文标记，比如：支付订单表，wait代表的就是等待付款中。3、$id 可选参数，订单 ID，用于检索具体订单信息。注：如果需要查询指定订单的状态，则传递ID参数即可。
2、状态返回函数，现在支持redis缓存结果。提升方法的执行效率，减少对sql的请求量。会对【$table_name, $status, $id】三个变量参数封装成一个唯一标识（通过MD5进行处理）然后，在查询成功后，将查询到的结果缓存到redis中，缓存的有效期为24小时，也就是24小时读取过一次，那么后续的请求都是缓存结果的返回。通过redis的部署，可以确保查询的时候，只是从内存中提取结果，而不涉及sql或者磁盘io的处理。尽可能的提升响应速度。
3、通过 xc_is_status 返回的查询结果采用标准数组结构，其中 code=1 表示获取失败。失败的原因可能多种多样，例如传递的数据表不支持、传递的ID查询结果失败、或者传递的status目前尚未兼容适配处理。具体的失败原因需要根据返回的 msg 来判断。如果查询成功，则统一返回 code=0。在查询成功的情况下，系统会返回一个名为 name 的参数，该参数会通过 switch 语句解析成对应的中文状态名称。例如，状态码1解析为“等待揽收”，状态码2解析为“正在运输中”。不同的查询可能会返回不同的内容，因此需要根据具体情况进行处理。
4、在传递了ID参数的情况下，系统将使用内置的统一查询方法来进行订单查询操作。查询结果会返回一个数组，其中包含了订单的详细信息，包括一个用于表示状态的字段。虽然在默认情况下这个字段被命名为status，但在早期版本的数据表中，名称可能有所不同，因此需要根据实际情况灵活读取。接下来，系统会对该状态字段进行switch解析处理，以便做出相应的业务判断和响应。为了确保处理的一致性，如果解析过程中遇到不支持或者未集成的状态类型，系统将统一返回“未知状态('status' )”，其中status是查询到的原始状态标识。此外，当通过ID进行查询时，系统还会额外返回一个data数组，该数组包含了原订单的详细结构参数。
5、寄售审核订单验收页面新增了一个名为order_parameters的容器。该容器将展示以下内容信息：寄售订单编号、申请时间、当前状态、订单类型（区分寄售订单和回收订单）、申请用户（对应的用户昵称信息）、线上审核专家、审核同意的人员。这个容器相当于一个信息汇总，能够直观地展示本次寄售订单的主要信息内容。其中最关键的是订单状态，系统会通过xc_is_status来解析状态，方便工作人员了解当前申请的状态，例如是否完成验收、是否需要进行线下鉴定等。
6、在寄售回收订单验收页面，为了提升后续前端交互的便捷性，在页面中嵌入了多个自定义属性。这些属性包括【consignment_id：关联的寄售回收订单编号，express_deliver_id：关联的快递物流订单编号，time：订单申请的时间戳，staff：负责订单下线审核的员工，author_id：订单申请用户的唯一标识（uid）】。在页面执行各种交互操作时，这些自定义属性将被用作关键参数，以确保数据的准确传递和操作的高效执行。通过这种方式，页面的交互性和响应速度都得到了显著提升，为用户提供更流畅的体验。
7、宫论项目集成了【Intervention Image】SDK，这是一款广泛应用的 PHP 图像处理库。此次集成的主要目的是为了优化本地缩略图的生成和展示。当前端用户上传图片时，系统将计划调用内置的 SDK 接口，对用户上传的图片进行缩略图处理，并将生成的缩略图保存到服务器的指定目录。随后，在读取本地图片时，系统会根据样式解析参数，提取出对应的目录地址，最终在前端进行展示处理。通过这种方式，实现了缩略图的快速展示，显著减少了对原图的直接读取，提升了系统性能和用户体验。
8、在PHP环境中安装以下扩展，以提升图像处理和文件信息识别的能力。首先是GD扩展，这是一个功能强大的图像处理和生成库，通常与Intervention Image SDK结合使用，以实现对图片资源的各种操作。在使用GD扩展时，务必注意管理图像资源，以避免内存泄漏问题。每次创建图像后，确保正确销毁资源。其次是EXIF扩展，它专注于读取图像文件中的EXIF数据。EXIF数据包含丰富的图像元信息，如拍摄时间、相机型号、地理位置等，这些信息对于图像管理和分析至关重要。最后是Fileinfo扩展，该扩展用于识别文件的MIME类型和编码信息，确保文件在处理和传输过程中能够被正确识别。这些扩展主要用于本地图片处理，结合Intervention可实现更复杂的图像操作。
9、新增脚本【sdk/image.php】负责本地缩略图的处理动作，具体执行流程如下：通过require加载【vendor/autoload.php】并引入了 Intervention Image 库的 ImageManager 类，创建一个 ImageManager 实例，并指定使用 gd 驱动来处理本次请求，使用 parse_url 函数解析当前请求的 URL，提取路径部分。使用 basename 函数获取 URL 路径中的文件名。构造文件在服务器上的完整路径，得到类似 /var/www/html/images/pic.jpg?image/resize 的结果。使用 urldecode 函数对 URL 进行解码，处理 URL 中的编码字符。用正则表达式去除 URL 中的查询参数部分，即 ?image/*。如果请求的参数包含该部分数值，则进入缩略图处理流程。
10、image脚本现在已经支持GIF动态图片的压缩处理。首先，通过pathinfo($file, PATHINFO_EXTENSION)方法判断请求的文件扩展名是否为GIF。如果是GIF文件，则使用Intervention Image库加载该文件。接着，使用md5函数生成缓存文件名，并将处理后的图像保存到缓存目录。随后，设置响应头为image/jpg，输出处理后的图像并结束脚本执行。需要注意的是，通过image脚本压缩GIF时，默认返回的是jpg静态格式，不支持对GIF进行直接压缩。
11、Intervention在处理jpge/png/jpg等静态图片的时候，整个流程如下：使用 $file 和请求的 $width 生成一个唯一的缓存文件名，通过 md5() 函数创建哈希值以确保文件名唯一。缓存文件存储在 $cacheDir 目录中。如果缓存文件已经存在，直接输出缓存文件的内容并结束脚本执行。这减少了重复处理相同图像的开销。如果不存在：使用 $manager->make($file) 加载原始图像。检查原图的宽度是否大于或等于请求的宽度。如果是，则使用 $image->resize() 方法调整图像大小，并保持宽高比。将处理后的图像保存到缓存文件，图像质量设为 80（通常是 JPEG 的质量参数）。设置响应头为图像类型，然后输出调整后的图像并结束脚本。

2025年5月8日
1、当xc_express_delivery_completed_hook钩子被触发时，不再采用同步请求的方式执行操作，而是利用Swoole框架实现异步响应和动作处理。这种机制有效避免了业务逻辑执行过程中可能引发的进程阻塞问题，从而大幅缩短用户等待响应的时间，提升系统的响应效率。该钩子主要针对快递签收后的后续处理动作，例如签收完成后系统会自动对订单的确认收货状态进行锁定，或者触发订单款项的结算流程。针对不同的物流单号，系统会根据运单来源进行精准判断，执行相应的业务处理逻辑，保证每笔订单的后续操作准确无误且高效完成。
2、在xc_express_delivery_completed_hook执行场景业务逻辑时，系统会首先进行一系列拦截检测，以确保操作的安全性和可靠性。首先，通过Redis实现上锁保护机制，锁的有效期设定为86400秒（即24小时）。如果获取锁失败，系统将返回相应的错误信息，并终止后续操作。其次，系统会调用xc_query_express_delivery接口，读取主键ID以获取相关运单的数据表信息。如果无法成功获取，则会返回错误提示，指明“运单信息不存在”。最后，系统会检查运单的status状态字段，如果该状态不等于3（即已签收状态），则会返回错误，指出运单状态不符合条件，从而阻止后续业务逻辑的执行。通过以上步骤，系统有效地保障了业务逻辑的执行安全性和数据的完整性。
3、为了确保宫论项目业务的统一性，快递运单系统的签收回调动作现已采用标准的数组结构来返回处理结果。其中，code=0表示业务已成功执行，而code=1则意味着处理失败。失败的原因可能多种多样，包括条件不具备、操作已执行过、上锁保护等。具体的失败原因可以通过msg字段进行详细了解，这样的设计不仅提高了系统的可读性和可维护性，还为开发和运维人员提供了更为清晰的错误诊断信息。注：正常签收回调是只能系统方式触发，但是考虑到业务的扩展性，将会允许手动触发回调。
4、由于签收事件涉及到多个敏感环节，包括消息推送通知、订单结算以及原状态回调处理，因此有必要实施严格的安全回调保障机制。系统将预设一个Redis安全键位：express_delivery_success:$ID，该键位具有永久有效期，不会过期。当签收场景中的所有事件均已成功执行后，系统将进行写入操作以记录该状态。在触发相关事件时，系统会优先检测该Redis键位是否存在，若存在则表明该事件已被处理过，从而主动跳过重复处理，避免出现不可控的重复执行现象。值得注意的是，除了永久键位保护外，还需对订单的状态进行检测，以确保处理过程的可靠性和准确性。
5、除了通过Redis进行保护以防止重复触发外，系统还会读取并判断运单记录的update_time（最后状态更新时间）。如果发现当前运单的状态等于3（已签收），但显示的签收时间超过24小时，则系统将主动跳过对【xc_express_delivery_completed_hook】的处理。通常情况下，在更新时，系统会通过API主动进行关联执行。然而，一旦超过24小时，就可以基本判断该事件已经触发过，因此应跳过处理，以避免由于极端意外情况导致的重复结算等问题。
6、在xc_express_delivery_completed_hook中，增加了对签收动作事件的处理，如果快递单号的类型为【consignment】时。这意味着当前运单涉及寄售回收藏品订单。一旦触发签收动作，便表明用户在申请寄售回收订单后，主动通过物流快递将藏品寄出，而官方工作人员已成功接收到该快递。需要注意的是，这个签收动作的触发并非由工作人员手动操作，而是通过系统与快递接口的自动交互来实现。为了确保后续因快递签收引发的业务流程变化能够准确执行，提供了一个接口示例。这将有助于确保每个业务环节的变化都能得到正确处理和执行。
7、快递签收接口的规范化处理流程：首先，在处理签收动作时，需要通过Redis、最后更新时间以及原订单状态进行参数核验，以确保不会出现重复执行的情况。通常情况下，快递签收动作是由系统自动触发，无需人工干预，但在极端情况下，人工也可以手动触发。快递签收动作的回调采用异步执行模式，并允许通过唯一的任务标识来追踪执行结果是否成功。执行结果将通过数组进行返回处理，确保信息的完整性和准确性。此外，系统业务会进行分离处理，即使不触发签收动作，也能确保核心业务的连续性，避免业务中断问题。值得注意的是，即便用户填写运单错误或接口出现故障，这些问题也不会影响主流程的正常运作。
8、当工作人员进入【consignment_acceptance_details：寄售回收订单线下验收页面】时，系统会调用xc_query_logistics_tracking接口来读取当前快递运单的信息。该接口方法返回的是标准数组结构，数据的传输经过优化，以提升页面的加载性能。运单信息存储在可靠性极高的Redis缓存中，系统通过定时计划自动查询快递信息并更新缓存，以确保数据的实时性和准确性。如果成功查找到运单信息，系统会将返回的数组数据保存到【express_delivery】数组中。在后续页面生成构建时，这些物流动态会在快递box容器中展示，确保用户能够及时查看到最新的物流信息。
9、在寄售回收订单的验收页面中，除了利用快递查询接口获取当前订单的运输信息外，还会通过名为xc_query_express_delivery的接口来获取更为详细的发货信息。返回的参数包括但不限于：发货用户、发货时间、承运快递公司、快递单号以及最后的物流更新时间。这些参数被存储在query_express_delivery数组中，并在构建快递BOX容器时展示于相应的列表中。这种设计方便了工作人员对信息进行核对，确保查询到的运单信息与寄售订单准确关联，提升了物流信息管理的准确性和效率。
10、xc_is_status模块新增了订单状态解析方法，现已支持【express_delivery：快递状态的中文解析处理】。用户只需传递运单表中的status字段，系统将自动进行解析，并返回标准的状态名称。目前系统通过switch语句解析以下状态：0-已发货、1-在途中、2-派送中、3-已签收、4-派送失败、5-揽收、6-退回、7-转单、8-疑难、9-退签、10-待清关、11-清关中、12-已清关、13-清关异常、99-单号不存在。由于物流状态的标识字段可能会发生变化，因此需要一个统一的方法来处理，这样在新增状态或改变状态时，所有相关功能都会自动同步更新。
11、在通过xc_is_status获取运单状态信息时，现已支持传递ID主键编号作为参数。该参数为可选项，用户可以选择是否传递ID。当传递了ID且返回值不为空时，系统会通过xc_query_express_delivery进行快递查询，并使用获取到的status作为条件进行switch解析处理。如果通过ID进行查询时，数据表返回为空，则系统将返回【运单不存在】的结果。如果运单存在，除了返回状态名称外，还会额外返回一个包含数据表所有信息的数组字段【data】。需要注意的是，该数组字段【data】包含敏感信息，不能直接返回给前端，以避免隐私泄露。

2025年5月7日
1、为xc_api_express_delivery接口增加了一项安全验证和拦截机制。该机制首先检查传入的ID是否为数字，如果不是数字，则立即返回异常错误。此验证通过is_numeric函数实现。此外，即便传入的是数字，但如果长度超过8位，也将返回错误。这一方法仅允许传递【xc_epress_delivery】数据表的主键ID值。由于该参数必定是数字且其长度在递增过程中不会过长，这两个拦截条件基本上能够有效防止非法参数传入的问题。
2、在通过xc_query_logistics_tracking发起快递接口响应请求时，系统在完成基础验证处理后，会针对状态为status=0（表示刚发货但尚未产生任何运输状态）的记录直接执行xc_api_express_delivery请求。这类请求将不受$express_delivery['update_time']时间段验证的影响。在原有的函数设计中，所有请求都会检查最后的更新时间，只有当最后更新时间超过6小时，系统才会主动发起API接口请求，否则默认返回缓存的状态字段信息。
3、新增发货HOOK通知回调脚本事件：xc_express_delivery_success_hook。当系统或用户完成快递发货后，将触发对【xc_express_delivery】数据表的写入操作，此时会主动触发该回调HOOK，处理发货成功的相关事件。此类事件包括通知用户其购买的商品已发货、执行相关查询操作等。该脚本触发时需要主动传递一个主键ID，也就是说，只有在数据表写入成功后，才会执行此回调脚本。
4、当触发快递发货事件回调时，系统将通过xc_query_express_delivery方法获取此次发货的数组信息（通过ID主键）来构建查询请求，随后将返回的数组保存到【express_delivery】变量中。所有回调动作的参数提取都将通过该变量进行。同时，该方法会返回标准的数组结构，以便在后续手动执行时，可以清楚地了解执行状态，确保操作的可监听性。若code=0，表示所有预留事件均已执行完毕；若code=1，则表示出现中断错误，msg字段会提供具体的失败原因。需要注意的是，如果express_delivery获取失败，整个执行过程也会被中断。
5、在触发 xc_express_delivery_success_hook 事件时，决定统一采用异步方式进行处理，以减少同步处理可能带来的性能阻塞问题。具体的解决方案是通过 xc_swoole_asyn('xc_express_delivery_success_hook', [$insert]) 来触发回调 HOOK，将执行请求转发至 Swoole 服务器进行处理。我们通过任务的唯一标识来监控此次任务请求的执行情况是否成功。需要特别注意的是，Swoole 作为异步处理进程的脚本服务器，其可用性至关重要，一旦出现问题，可能会对许多业务流程产生负面影响。因此，确保 Swoole 服务器的稳定运行是我们的首要任务，以保障整个系统的流畅和高效运作。
6、快递发货的第一个回调动作事件为：执行 xc_api_express_delivery($id) 接口查询请求，通过调用宫论API接口，获取本次发货快递的运单运输状态信息。在用户进行发货操作时，通常都会生成一个运单号，因此基本可以查询到快递的状态，通常包括待揽收、已揽收和运输中三个状态。为了确保系统能够及时掌握快递的最新状态，需要进行一个初始化动作，主动查询快递的状态并将其同步到宫论系统中。由于这个过程涉及到外部接口的查询，将其放在回调脚本中，并利用Swoole进行处理是非常适合的选择，这样不仅提高了效率，还确保了系统的稳定性和实时性。
7、xc_express_delivery_success_hook 现已支持外部第三方事件的扩展处理。该功能在内部通过hook_after脚本触发【xc_do_action(__FUNCTION__, $id, func_get_args())】动作。用户只需按照标准的action动作进行挂载和注册，当发货事件触发时，系统会自动将物流信息同步到已注册的方法中。这样，外部事件只需监听用户的发货行为，即可实现相应的处理。需要注意的是，传递的id是对应数据表的主键，通过这个id`可以获取到发货场景、发货用户、快递单号等详细信息。
8、宫论swoole异步规范化处理：为了确保业务的统一性和异步环境的健壮性，在使用swoole执行异步操作时需要注意以下几点。首先，禁止在异步环境中再次触发swoole请求，以避免出现死循环和套娃现象。系统会在内部进行环境校验，如果检测到是异步环境，则将请求转换为同步执行处理。其次，任何函数都不应默认通过swoole进行处理，必须手动使用xc_swoole_asyn来触发并响应，以确保明确的控制和管理。第三，首次执行swoole请求时，应进行充分的调试处理，以确保当前环境支持相关函数的语法和功能。最后，当涉及到外部请求，如API接口任务时，如果不需要立即同步返回结果，必须采用异步方式进行处理，以提高系统的响应效率和资源利用率。通过遵循这些规范，可以有效地提升异步操作的可靠性和业务处理的一致性。
9、通过xc_api_express_delivery成功发起快递查询后，如果返回了结果，并且同步更新了运输状态信息到【xc_express_delivery】数据表后，会主动触发缓存刷新机制，将对应的查询缓存结果进行更新处理，以确保后续查询得到的数据都是可靠有效的。更新缓存的方式非常简单，只需要执行【xc_query_express_delivery($id, true)】即可。该方法用于读取数据表中的相关信息，当第二个变量标记为true时，表示读取数据时禁止使用缓存，并将wpdb请求到的结果进行重新缓存。这样能够确保数据的实时性和准确性。
10、因为快递查询接口现在会在获取到结果后会主动更新对应运单数据表的缓存信息，因此以下场景或者方法不在需要强制返回缓存结果，读取对应的数据时，仅返回redis缓存即可，强化整个响应速度，减少sql的请求量。1、xc_query_logistics_tracking：发起快递查询请求方法，这是宫论唯一查询渠道。之前为了确保返回的数据一致性，是禁用缓存来读取，现在可以取消这个设置。2、xc_api_express_delivery该方法是外部API接口调用，在初始化的时候，会禁用缓存来获取运单信息。现在也可以进行移除处理。
11、宫论快递接口的封装处理已经圆满完成，整个系统采用标准HOOK机制对所有事件进行精细化封装，具备强大的异步操作能力，并支持日志写入、任务执行、回调操作以及缓存更新等功能。每个步骤都可以通过HOOK进行灵活接管，从而提高系统的可扩展性和响应速度。具体涉及到的函数包括：1、xc_query_user_address，用于统一查询用户的收货地址，确保信息准确无误；2、xc_query_express_delivery，用于查询指定的运单记录，提供详细的物流信息追踪；3、xc_api_express_delivery，用于处理外部API接口的查询请求，增强系统的开放性和互操作性；4、xc_task_express_delivery，负责系统的定时任务处理，保证自动化运作的高效性；5、xc_express_delivery_success_hook，用于响应用户快递发货事件，确保信息及时反馈；6、xc_express_delivery_completed_hook，负责快递签收通知的回调事件，确保用户实时获知物流状态。这些功能的实现使得宫论快递接口更加完善和智能化，能够为用户提供更加流畅和高效的服务体验。

2025年5月6日
1、设计并实现了一个名为 xc_is_time_range() 的方法，用于检查当前时间是否位于指定的时间范围内。该方法接收两个字符串参数，分别表示开始时间和结束时间，格式为 "H:i"（例如：22:31）。如果结束时间为午夜（"00:00"），则该方法会自动将其调整为次日的00:00，以便正确判断时间范围的跨日情况。通过返回布尔值，该方法可以有效地判断当前时间是否在指定范围内。这个功能在很多场景中非常实用，例如在某些时间段内限制特定操作的执行。通过使用这个方法，可以轻松实现时间段的判断和控制，确保操作在合适的时间窗口内进行。
2、在xc_task_express_delivery任务中新增了时间区域检测功能，以优化任务执行效率。具体而言，如果当前时间处于20:00至次日07:00之间，任务将自动跳过执行。这一调整基于快递物流信息在凌晨时段通常不会发生显著变化的事实，通过接口查询此时段的物流信息，往往意义不大。因此，引入了xc_is_time_range方法来有效地跳过该时段的任务处理。此外，该任务的执行周期已从原来的43200秒调整为每6小时执行一次。这意味着任务仍然每天更新两次，但会避开夜间时段，确保资源的合理利用和任务执行的高效性。
3、xc_is_time_range做出优化调整，原本处理机制并不支持第二天的时间段判断处理。比如：23:00-12:00，即当天23:00到第二天中午12点这个时间段的处理效验。处理逻辑方式为，跨越午夜的逻辑：当开始时间大于结束时间时，表示时间段跨越午夜。在这种情况下，只要当前时间大于等于开始时间或者小于结束时间，就认为当前时间在范围内。时间比较的边界：使用 < 而不是 <= 来比较结束时间，以避免误判在结束时刻整点的情况。
4、在使用xc_query_logistics_tracking方法进行快递单号查询请求时，系统首先会通过xc_query_express_delivery方法获取订单数组信息。如果订单信息读取成功，系统会将返回的信息保存到express_delivery变量中。接下来，系统会对express_delivery数组中的status字段进行检查处理：若status的值为3（表示已签收），系统则返回code为0，msg显示为“快递查询成功”，并将logistics字段的内容作为data返回。这一流程确保在订单已签收的情况下，用户能够顺利获取到相关物流信息。
5、在进行快递单号查询时，如果原表中的状态值为3，系统将直接返回对应的物流字段，因为此时快递已被签收，不需要通过API接口进行进一步查询。然而，当订单状态为99时，系统也不会主动生成查询语句。这是因为状态99表明订单存在异常，经过多次查询仍未获得任何结果，订单可能已被系统标记为不存在或异常。因此，在这种情况下，系统会直接返回一个错误代码code=1，并附带信息msg：单号查询失败。此外，还会返回相应的HTML页面，其中包含通过xc_empty转义的msg参数信息，以便用户能够清楚地了解查询失败的原因和相关细节。
6、在数据表中，如果记录的status状态既不是3也不是99这两个基本固定状态，那么将会通过xc_api_express_delivery接口发起快递查询请求。在此之前，需要通过express_delivery获取主键ID值。由于系统传递的参数变量可能是快递单号，并不一定是ID，因此在发起请求前需要进行转换处理，以确保API接口能够成功响应。此外，在通过xc_query_logistics_tracking构建查询请求时，返回的信息将通过xc_query_express_delivery接口进行处理，并且禁用缓存，以确保状态信息的可靠性和准确性。
7、宫论内置的xc_api_express_delivery快递查询接口新增了一个名为uncache的可选变量，默认设置为false。用户可以选择将其设置为true，从而禁用任何形式的缓存结果。除非快递状态为（status=3）已签收，否则所有其他状态都会强制进行实时API查询，以确保返回结果的可靠性和有效性。这一功能特别适用于某些场景，例如当用户对查询结果不满意或需要最新的快递状态信息时，能够通过强制刷新功能发起实时查询，确保获取到最新、最准确的快递信息。
8、在同样的宫论统一查询接口【xc_query_logistics_tracking】中，新增了一个名为uncache的变量，用于决定是否发起同步实时查询请求。当该变量设置为true时，系统将忽略已有的查询结果，直接调用xc_api_express_delivery方法进行API查询请求，并且在查询过程中不允许使用缓存处理。通过这个变量的设置，可以确保查询结果的实时性和可靠性，满足对最新物流信息的需求。
9、当通过数据表查询到的运单状态不等于3或99，且缓存功能处于禁用状态时，系统会读取该记录的update_time字段，并借助strtotime函数将其转换为时间戳，随后与当前时间time()进行比较。如果发现上次更新时间距当前时间超过6小时（即21600秒），系统便会主动调用xc_api_express_delivery接口对运单状态进行实时查询，获取最新的信息并直接返回给用户。通过这种机制，系统在用户查看运单记录时，能够自动判断是否需要刷新数据缓存，确保展现的信息始终保持最新，提升用户体验和数据准确性。
10、在系统中，如果运单查询结果的status状态既不是3也不是99，并且缓存状态已开启的情况下，当上次更新时间超过6小时，系统会自动调用xc_api_express_delivery方法，发起外部API查询请求。查询得到的结果将被保存到API变量中。接着，系统会对返回结果进行进一步处理：如果返回的code值为1，系统将生成一个新的HTML页面，并通过xc_empty($api['msg'])方法获取具体的错误提示信息，该信息会直接展示在前端页面上。需要注意的是，即使缓存功能被禁用，处理逻辑仍然与上述方法保持一致。
11、通过xc_query_express_delivery方法进行单号查询请求的时候，如果$express_delivery['status'] 不等于3或者99两个固定状态，在发起API请求的时候，会进行一个非常重要的检查。首先通过time()获取当前时间戳、然后使用strtotime($express_delivery['time'])获取该运单的发货的时间戳。如果发货时间距今已经超过了15天，则会直接读取$express_delivery['logistics']运单信息，而不是发起API请求。原则上讲，超过15天的单号查询，是被禁用的。

2025年5月5日
1、在宫论系统中，对任务命名进行了规范化处理。所有任务方法将统一采用“xc_task”作为前缀，其中“xc”代表宫论项目，“task”则指任务方法。后续参数将根据具体任务场景进行定义。这种命名方式不仅提升了代码的可读性和一致性，还方便了任务的分类管理。由于任务通常是定时执行的，无法指派或传递变量，因此大多数任务方法不需要传递任何参数。同时，所有任务必须集中在function/corn/system_task.php脚本中，以便于统一管理和维护。这种设计不仅简化了任务调度流程，也确保了系统任务在定时执行的同时能够支持手动执行，以应对特殊情况或临时需求。
2、为了防止系统在极端情况下重复执行任务，导致问题的发生，在执行 xc_task_express_delivery 方法时，内部设置了一个简单的锁保护机制。锁的名称即为任务函数的名称，锁的有效期为30秒，超过这个时间锁将自动释放。此外，定时任务系统的外部还通过 is_redis_corn 进行执行检查，确保该方法仅在规定的时间内被允许执行。这种双重保护机制有效避免了短时间内的并执行，从而防止接口被滥用的情况发生。
3、在完成上锁保护后，xc_task_express_delivery将通过wpdb构建SQL查询语句，旨在检索xc_express_delivery数据表中所有状态不等于3的记录。状态3表示快递已完成签收，因此查询的目标是找到所有已发货但尚未完成签收的运单记录。接着，系统利用get_results方法将查询结果转换为数组结构，并将其存储在sql_result变量中。在后续执行API接口查询处理动作时，该数组将被用于进一步的处理。这一流程确保了系统能够有效地追踪和管理尚未签收的快递运单，提升运单管理的效率与准确性。
4、由于快递的运输状态繁多，涵盖了诸如【在途、派送、揽收、退回】等多种状态，系统在构建查询时不再仅仅依赖简单的数字标准，而是将【派送中、转单、退签、取消、揽收】等状态纳入查询依据。这种方式确保了查询的全面性，同时有效减少了API接口的请求量。此外，系统在原有功能基础上新增了一项保护措施：在事件检查中引入【发货建立时间】的概念，系统仅检索最近15天内的记录，对于超过15天的状态则自动跳过处理。这一机制旨在避免系统长期检索特殊状态带来的负担，提高查询效率。
5、在通过wpdb成功检索到符合条件的运输记录后，将使用foreach循环进行遍历处理。接下来，将通过调用宫论API接口，向相关服务商发起快递查询请求。这个查询操作是通过xc_api_express_delivery方法来实现的，并且会通过id参数传递相应的主键ID以进行精确查询。需要注意的是，如果查询结果为空，将通过empty函数进行验证。一旦确认结果为空，系统会立即返回false，并中断当前的查询请求，任务将停止，且不再进行任何后续处理，直接退出。
6、为了确保执行效率，针对任务发起的快递查询请求，统一采用xc_swoole_asyn方法进行异步请求的下发。这样做是为了避免同步执行可能导致的进程崩溃现象。由于运输记录中可能会有上百条符合查询条件的记录，如果采用同步方式，通过for循环逐条查询，每秒执行两条记录，整个过程可能需要耗费数分钟才能完成。此外，本次任务接口可能同时处理多个任务请求，如果频繁调用接口而导致进程阻塞，将会引发一些不可控的问题。因此，采用异步执行的方式，可以有效提高系统的响应速度和稳定性，是一种更为理想的解决方案。
7、在使用 xc_api_express_delivery 接口查询快递单号时，如果返回的状态码不为 200 或者返回的数据为空，将启动一个计数器的处理逻辑。该计数器的 Redis 键名为 error_api_express_delivery：$id。首先，通过 get_redis_meta 函数读取缓存，检查是否已有相关记录。如果存在记录，则在原有基础上递增计数器值加1；如果不存在记录，则初始化计数器值为1。接着，使用 update_redis_meta 函数对缓存进行更新，以确保计数器准确统计查询失败的次数。这一流程旨在有效监控快递查询的异常情况，并为后续优化提供数据支持。
8、在执行xc_task_express_delivery任务时，系统会对每一个任务进行缓存检查。如果检测到error_api_express_delivery：$id存在，并且该缓存的键值已超过10次，系统将通过continue语句跳过当前循环任务，继续处理下一个任务。值得注意的是，如果连续10次查询均未找到相关记录或返回其他错误信息，这意味着该运单信息可能存在异常情况，如运单号错误、参数错误或快递公司识别失败等。在这种情况下，必须果断拒绝处理该运单，以避免潜在问题。
9、在使用xc_api_express_delivery接口查询快递单号时，如果遇到接口异常、单号错误或信息不存在等情况，不仅会通过error_api_express_delivery记录查询失败次数，还会对这些失败次数进行监控和处理。如果记录的错误次数超过20次，系统将触发数据表回调操作，自动将订单状态更新为99【运单记录查找失败】，同时标记该运单号为错误并记录查找失败的情况。这一流程考虑到运单号是由用户上传，可能存在错误，因此当系统检测到查询失败次数过多时，应及时标记运单错误信息，以便后续处理和用户通知。
10、在使用xc_api_express_delivery方法执行快递查询时，系统在接收到express_delivery数组参数后，会首先对status状态进行检查。如果状态为3（表示物流单号已签收），系统将自动返回数据表中的logistics字段内容，并将其转换为数组结构，随后返回code=0、msg=“快递查询成功”，以及包含物流详情的数组结构作为data。如果状态返回为99，则系统会返回code=1、msg=“快递单号不存在，或者信息错误”。只有当status不为这两种情况时，系统才会继续进行API查询处理。
11、在宫论后台的定时计划组中，新增了一个【主副锁计划 [周期性执行]】任务，旨在自动查询已发货但未签收的快递状态。该任务绑定了函数：xc_task_express_delivery，设置为每隔43200秒（即12小时）执行一次。此计划的工作流程是，系统会定期检索符合条件的运单记录，并通过API接口查询这些运单的当前状态，然后将最新的信息同步更新至宫论系统。由于内置的for循环已经采用了swoole异步进程逻辑处理，因此在此任务场景中无需再进行额外的异步处理。

2025年5月4日
1、在使用xc_api_express_delivery进行快递查询时，无论返回什么结果，都会包含一个HTML字段。这一设计是为了让前端在接收到参数时，可以直接将内容插入到页面中。HTML信息将通过xc_empty进行转移处理，从而直接生成一个错误提示，其内容为msg对应的信息。如果查询结果中存在运输记录，则会跳过这一处理步骤。由于不同场景生成的HTML结构各不相同，因此不应在查询接口中直接构建HTML结构，而应根据具体调用场景进行构建和处理。
2、在成功查询到运输记录后（返回code=200），系统会对返回结果进行一次详细的检查和处理。如果返回的内容不是有效的JSON结构，或者在通过json_decode解析成数组后发现缺少data字段（该字段不能为空），则说明查询结果无效，没有可供查阅的运输记录。在这种情况下，系统会返回code=1，并提示信息：该运单尚无运输记录可供查询。若data字段存在，系统将继续处理，将运输记录解析为JSON格式，并写入到数据表【xc_express_delivery】中，同时将这些信息同步到logistics字段中，并更新对应记录的updated_at字段，以反映最新的更新时间。
3、在服务端新增一个签收提醒的回调HOOK动作事件：xc_express_delivery_completed_hook($ID)。该钩子触发的场景为，当通过宫论内置API接口发起单号查询时，如果查询到运输状态，并且运输状态为3，则表示本次运单已成功签收，此时将触发该HOOK事件，以便进行后续处理。通常有两个应用场景：首先，通知寄件人和收件人，运单已显示签收，请及时确认处理；其次，系统进行回调操作，比如在运单签收后，自动将订单状态设为已完成，或者启动其他倒计时操作，例如签收后三日自动确认收货。通过这种方式，可以有效提升物流信息的处理效率，确保各方及时获取运单状态更新，并进行相应的后续操作。
4、为防止重复触发签收HOOK事件，增加了一项保护措施。具体而言，通过$express_delivery['status']检测快递状态，确保仅当原数据表中快递状态不等于3（已签收），且本次查询请求返回状态为3（已签收）时，才会触发相应的HOOK事件。这种机制能够保证在API接口调用并首次返回status=3时才触发事件，从而有效避免重复结算通知的情况。
5、在xc_express_delivery_completed_hook($ID)中，为了增强安全性和可靠性，添加了一个基于REDIS的安全锁机制。每当该钩子函数被触发时，系统会自动上锁，锁的名称为express_delivery_completed_hook:$id，并且锁的有效期设置为365天。这意味着在这一年内，钩子函数只能被执行一次，从而有效防止极端情况下的重复执行，避免重复结算和重复通知的问题。由于签收环节涉及到敏感的业务处理，必须谨慎对待，以防止可能的安全和资金风险。因此，除了REDIS锁之外，我们、、还将实施其他多重业务保护机制，以确保系统的一致性和可靠性。上锁只是采取的第一步措施，后续还会有其他辅助方法来加强这一过程。
6、在通过xc_api_express_delivery进行API查询时，由于系统涉及到首次签收的HOOK执行问题，因此在使用xc_query_express_delivery获取运单数据表状态信息时，会禁用缓存处理，将uncache标记为true。这一措施旨在确保查询结果的准确性和可靠性，避免因缓存更新不及时而导致的状态误判问题。具体来说，如果订单状态已标记为签收，但由于缓存未及时更新，系统可能仍会返回订单处于派送中的状态，从而错误地将此次签收事件识别为首次签收，进而触发不必要的签收HOOK事件。因此，通过禁用缓存，可以确保系统在获取运单状态时，能够反映当前的真实情况，避免不必要的错误触发和处理。
7、在触发 xc_express_delivery_completed_hook($ID) 进行快递签收业务处理时，系统会返回一个标准的数组结构，以判断操作是否成功。其中，code=0 表示处理成功，所有相关事件已顺利完成。若 code=1，则意味着此次事件处理失败，具体原因会在 msg 字段中详细说明。常见的失败原因包括：操作被系统拦截、订单不存在、事件已被重复执行、上锁保护等情况。需要特别注意的是，这里的处理逻辑是根据具体业务场景来触发的。例如，如果快递属于退货情境，则会启动相应的退货处理逻辑。
8、因为API接口是外部请求，在执行的时候需要等待接口的响应处理。因此在执行的时候增加一个异步参数字段asyn，默认是false，如果执行任务的时候，需要通过异步处理则可以通过将该参数标记为true，一旦请求异步去执行，系统会通过xc_swoole_asyn($functionName, $params = [])方法去执行，并记录task任务标识到redis缓存中。这样做可以避免阻塞请求，但是结果也不能实时返回。对于系统级的任务可以通过通过swoole来触发异步。
9、在触发 xc_express_delivery_completed_hook 快递首次签收动作回调事件时，使用 Swoole 进行处理。这个过程默认采用 Swoole 的异步处理方式，且不提供其他选项。一旦触发，该事件会通过 xc_swoole_asyn 内部机制自动执行。由于该 HOOK 的性质类似于回调处理，执行过程中无需同步接收返回结果，因此选择异步处理方式，以确保任务能够顺利完成即可。需要注意的是，由于采用 Swoole 进行执行，当该方法发生变更时，例如增加新的执行逻辑场景，必须重启 Swoole 才能使更改生效。
10、在完成首次快递签收的业务回调后，xc_api_express_delivery的执行流程便已结束，此时系统会返回三个字段：code=0，代表本次的查询请求成功。msg：快递查询成功。data：对应的物流数组结构信息，该数组返回返回上一级，如果是前端需要，则会在返回前端的时候对其进行解析，并进行封装处理。整个大致执行流程如下：通过xc_query_express_delivery方法去查询匹配运输记录，如果匹配成功则调用API接口进行查询，查询后将结果回调到对应数据表，如果是首次签收则还会触发对应HOOK，返回标准数组结构响应，同时查询成功会进行API接口计数，查询失败会写入日志并触发报警。
11、新增了一个定时任务：xc_task_express_delivery()，专门负责宫论快递信息的自动更新与同步操作。该任务设计为每隔12小时运行一次，通过内置的方法访问宫论数据表【XC_express_delivery】，筛选出所有已发货但仍处于运输状态的记录。任务将利用API接口查询这些订单的最新状态，直到运单显示已签收或退回处理成功为止。值得注意的是，该方法无需传递任何变量参数，系统会自动通过status状态字段检索符合条件的记录，并构建相应的查询语法进行处理。这一机制确保快递信息的及时更新，提高了系统的效率与准确性。

2025年4月30日
1、在通过xc_api_express_delivery发起API请求时，会封装一个单独的curl请求，具体参数如下：请求头（headers）包含三个核心加密参数：source、X-Date、Authorization，这些参数中包含了请求时间戳和签名信息。请求体（bodyParams）包含三个字段：expressCode（固定值，不指定快递公司）、mobile（收件人手机号，通过查询数据表读取）以及number（快递单号信息）。该请求使用POST方法发送，最大响应等待时间为30秒，超时将自动放弃请求。
2、宫论快递查询接口【xc_api_express_delivery】现已优化至标准数组结构，确保用户在进行查询时能获得明确的反馈信息。在请求失败的情况下，无论是由于请求超时、接口拒绝、查询失败、信息不存在、token非法参数、欠费拒绝、接口维护中或其他错误原因，系统均统一返回code值为1，并通过msg字段详细描述具体的错误信息，以便用户快速识别并采取相应措施。而当查询成功时，系统则返回code值为0，msg字段显示“快递查询成功”，同时将详细的快递物流信息存储于data字段中。这一改进不仅提升了接口的可靠性和用户体验，也为用户提供了更为清晰和结构化的信息反馈。
3、为了提高系统的可靠性和便于故障排查，引入了日志报警模式。在此模式下，当curl请求出现错误（通常是由于服务器拒绝连接或请求超时），系统会通过curl_errno监听器自动捕获错误并触发报错机制。具体操作包括通过xc_log_error_warn函数将错误信息写入日志，日志内容格式为【[时间: ' . date("Y-m-d H:i:s") . '] [查询单号:] [ 错误信息 : ′ . number. ′ ][错误信息: ′ .error_message . ']】。这些日志信息会被保存至文件标识为api_express_delivery的日志文件中。此功能确保每次故障发生时，系统能够立即记录相关信息，为后续的维护和问题排查提供详实的数据支持。同时，在发生错误时，系统会返回code=1以及msg= error_message，以便及时通知相关人员进行处理。
4、后台日志报警配置新增了【api_express_delivery】快递接口报警处理功能。当快递查询接口出现故障时，系统将自动记录错误次数并写入日志。同时，报警提示将通过【手机号、邮箱、公众号】三种途径进行通知。设置的报警上限为20次，即当天若连续发生超过20次请求故障，将自动触发报警，运营人员会收到邮件、短信和公众号的通知，提醒接口故障的发生。每天报警触发上限为三次，超过三次后将不再触发。每次报警触发后，错误计数将被清零，以确保系统能够准确监控故障频率并及时通知相关人员。
5、在处理快递单号API查询请求时，除了使用CURL监听异常情况，系统还会根据返回的状态码来判断请求的结果。若返回的状态码为200，意味着查询成功，本次请求已被接收，可以进行快递单号信息的写入操作。然而，如果返回其他状态码，则会触发相应的错误处理流程。具体而言，若状态码为400，表示查询失败，原因是参数错误；而状态码为500则意味着服务商正在维护，请稍后再试。此外，如果状态码为999，则需要进一步分析和处理。
6、如果返回的code状态为：200则表明本次API请求顺利执行，此时会触发xc_redis_count计数器，将【api_express_delivery】作为计数标识，进行+1计数处理动作。统计API接口的调用次数，便于接口的监听处理的。可以通过get_redis_count($key)来获取详细的统计信息，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】等多维度的数据分析。注：只要返回200则表明扣费成功，基本可以精确通过计数器判断系统资源包的剩余数量。
7、为了更好地区分和管理快递状态，系统将对返回的快递状态进行细致的分类处理。目前，已经归档了以下运输状态：【1、在途中。2、派送中。3、已签收。4、派送失败。5、揽收。6、退回。7、转单。8、疑难。9、退签。10、待清关。11、清关中。12、已清关。13、清关异常】。这些状态涵盖了快递运输过程中可能出现的所有情况，确保能够全面掌握每一个快递的动态。无论是哪家快递公司，其最终的返回状态都将通过上述13个状态来进行记录。这种标准化处理不仅提高了信息透明度，还方便了后续的管理和跟踪。
8、在宫论快递运输表【xc_express_delivery】中，已经对status状态进行了优化处理。现在，该状态字段将自动继承之前归档的运输状态1至13，并在初始化时设置为0。这意味着在构建运输表记录时，状态会默认标记为0。随着运输状态的更新，系统会自动同步为最新的状态，包括【1、在途中；2、派送中；3、已签收；4、派送失败；5、揽收；6、退回；7、转单；8、疑难；9、退签；10、待清关；11、清关中；12、已清关；13、清关异常】。无论后续与哪个快递平台对接，其返回的最终状态都会根据这个运输状态进行统一处理。这一调整不仅提升了状态追踪的准确性，也为管理和维护提供了极大的便利。
9、快递查询成功后，会通过xc_update_sql执行sql写入动作。写入的参数包括：1、status（这里统一化处理，继承之前归档的运输状态1-13）。2、检测data是否为空，如果不为空则将其转为json结构，然后存储到logistics字段中【快递物流详细信息】。3、将created_at的时间进行更新处理，记录物流发生变动的最新事件。执行更新的方式，通过ID主键进行匹配处理。并将更新结果返回到result。如果更新失败，返回code=1，msg：查询失败：数据表写入异常！
10、如果返回的查询状态不为200或者express数组为空的情况下，则不会触发数据表的更新动作，而是直接返回【查询失败：没有运输记录信息】。同时会通过redis写入一个缓存键位【xc_api_express_delivery_error：$id】并进行查询，如果存在记录且数值大于10，则说明该物流单号连续超过10次都没有任何记录，此时会直接将数据表的status状态标记为：99【单号不存在或者异常】。如果小于10则会在原有基础上进行计数+1动作处理。注：该缓存键位是为了避免系统查询，返回查询不存在的单号信息，造成无效执行的保护处理
11、在通过xc_api_express_delivery进行快递单号查询时，首先会通过xc_query_express_delivery读取数据表中的订单信息。如果返回的状态STATUS为3，即表示订单已签收，此时无需再通过API接口进行查询，而是直接将数据表中的物流信息返回给用户。在返回过程中，需要将信息从JSON格式转换为数组，以便进行后续处理。如果状态为99，则表示查询失败，原因可能是单号不存在或填写错误，会直接返回错误提示【查询失败：单号不存在或填写错误】。对于这两种状态，可以直接返回查询结果，避免不必要的API调用。然而，对于其他状态，由于结果不确定，仍需通过API重新进行状态检索，以确保信息的准确性和实时性。

2025年4月29日
1、在执行物流信息API接口查询时，首先使用xc_query_express_delivery方法进行数据查询。如果该方法返回了有效数据，将验证logistics字段是否存在，该字段用于存储物流详细信息（JSON格式）。如果该字段不存在，表明该运单信息之前没有查询记录，此时需要直接调用接口发起新的查询请求。如果该字段存在，则需要进一步验证created_at字段，以确定上次查询的时间，避免在短时间内重复查询，浪费API接口资源。
2、xc_express_delivery数据表状态设计规划：status是固定字段，具体参数如下。0：代表用户已经发货，但运单尚未完成。1：代表运单正在运输中，但尚未完成。2：表示运单查询不到记录，无法找到运单信息。3：运单已完成，可能是派件完成、退回成功、签收成功或代放成功。4：运单异常状态，可能是超长时间未更新状态或其他疑难件情况。通过API接口追踪物流订单时，需要通过status字段来标记订单的处理状态。
3、在构建物流信息查询请求之前，如果返回的status状态为3，则表明物流运输已完成。此时系统会通过json_decode将【logistics】字段转换为数组，并直接返回前端进行处理。同时返回的字段还有user_id：寄件人的用户唯一标识符；recipient：收件人的用户唯一标识符；courier_company：快递公司名称；code：快递单号；express_key：快递标识。注：每次查询快递信息，都会优先读取数据表的信息，只有数据表的信息不存在的，才会通过接口进行查询处理。
4、xc_query_logistics_tracking增加缓存功能，uncache控制是否需要缓存输出。默认值为fasle（不禁用缓存），系统会在执行方法查询前构建redis键名：query_logistics_tracking：$code，然后适用get_redis_meta方法检查缓存是否存在，如果存在缓存并且uncache等于false，则会直接将查询到的缓存结果进行输出，而不是执行复杂的查询处理动作。缓存的返回方式有很多种，不同的场景，执行的方式不一样。
5、物流查询接口的，缓存控制输出方式进行优化，现在需要根据status来决定是否允许进行缓存返回。只有当物流运输状态为【2：订单查询不到记录、3：运单已完成的状况】两种状态下才会读取缓存。因为2表明订单的运单号出现异常，一般是单号录错了，或者不存在的单号才会出现这个问题，基本没有结果。4则代表订单已完成，此时就不需要再进行任何查询，直接返回完成状态的json结构就可以。至于其他状态，则需要进一步确认，不能适用缓存查询。因为缓存有效期内，运输状态可能已发生了变化。
6、新增了一个外部API接口脚本文件【function/api.php】，将所有第三方接口的调用方法整合到该脚本中执行，包括物流快递查询、实名认证查询、地理位置查询、行政区域查询等功能。这些功能均通过外部第三方接口进行查询处理，需特别关注接口的稳定性。之前这些接口调用分散在各个文件中，后期维护非常不便。此次整合后，管理和更新更加方便。如果接口发生变化，只需集中处理API脚本即可。该脚本通过require_once加载到宫论项目核心库中。
7、新增了方法xc_api_express_delivery，用于获取并查询快递单号的物流信息。该方法通过调用第三方API接口发起查询请求。在查询时，需要传递一个固定值ID，对应物流运输数据表中的【主键ID】。系统将通过内置方法检查宫论物流订单表【express_delivery】中是否存在这个主键ID。如果该ID不存在，则直接返回false，阻止后续查询请求的进行；如果该ID存在，则继续处理后续操作。需要注意的是，为了防止接口滥用，快递查询接口仅限内部使用，不支持查询外部单号。
8、在宫论的后台配置中，新增了一个名为xc_api_token的字段，这个字段将作为API接口的令牌标识参数。所有外部API接口请求都必须携带此参数，以确保安全验证的通过。为了保证令牌的安全性和可靠性，该参数需要定期更换。需要注意的是，宫论涉及众多依赖于外部服务的API接口，这些接口通常来自云服务提供商，并且属于付费服务。每次请求都可能会消耗相应的资源包或按使用量计费。由于这些请求是外部调用，可能存在接口暴露的风险，因此引入token机制以确保请求的安全性和可靠性，防止潜在的安全隐患。
9、在通过xc_api_express_delivery发起外部API接口查询请求时，系统会进行两项基础拦截检测。首先，通过xc_is_ip函数获取当前请求端的IP地址，并将其赋值给requestIp变量。接着，通过判断条件(requestIp=='127.0.0.1'∣∣requestIp === '::1')对IP地址进行核验。如果条件不满足，即返回false，则表示此次请求并非来自本地（localhost）。其次，系统会检查token变量是否与后台预设的值保持一致。如果不一致，则视为非法请求，并同样返回false。通过这两项基础拦截措施，可以有效确保请求接口的安全性。
10、后台API接口配置新增了三个字段：xc_api_express_secretId、xc_api_express_secretKey和xc_api_express_link。其中，xc_api_express_secretId为快递查询接口的Secret ID，xc_api_express_secretKey为快递查询接口的秘钥参数，xc_api_express_link为快递查询接口的API请求地址。这三个参数由云厂商提供，用于构建快递查询并进行验签处理。每次请求都需要通过secretId、secretKey和当前时间生成对应的签名值。该接口每次查询的费用不到1分钱，并且支持市面上所有主流的快递查询服务。
11、通过xc_api_express_delivery获取到对应记录信息后，会将结果保存到【express_delivery】驻足，然后从该数组中提取两个参数：1、code：对应的快递单号信息，通过接口查询快递信息必须要提供单号。因为接口封闭性，不允许直接传递单号，而是需要从数据表中提取。2、phone：收件人的手机号码，因为顺丰快递查询单号必须提供手机号，所以这里在构建查询的时候，需要提前将收件人手机号码提取出来。避免顺丰包裹查询失败。

2025年4月28日
1、鉴于除了APP端会出现扫码场景需求外，微信浏览器、微信小程序等平台也具备扫码功能，这些扫码组件并不依赖APP的扫码功能，而是使用平台自带的扫码集成处理。因此，前端需要封装一个全新的扫码调用方法xc_hook_scan。该方法需传递一个唯一参数method，值为扫码场景。其他参数将根据具体场景在内部进行封装处理，不需要通过外部变量方法来传递或指定数值。注：后续集成其它平台小程序，也可以通过xc_hook_scan方法HOOK来调用原生平台的扫一扫扩展需求。
2、在通过xc_hook_scan发起扫一扫动作时，系统会首先使用xc_is_app验证用户环境是否处于APP内。如果验证结果为true，则会执行plus_scan动作，通过plus发起APP通讯请求，随后按照预先设计的流程进行扫一扫操作。整个执行流程与业务钩子保持一致。同样地，对于其他场景，系统会分别通过xc_is_weixin、xc_is_h5等方法验证环境，从而调用对应场景的扫一扫组件来启动扫码动作。需要注意的是，不同场景仅调用方法有所区别，具体的扫码结果由后端进行解析处理，前端页面的响应方法仍然保持不变。
3、目前，系统仅集成了APP端的扫码功能，微信和小程序的扫码操作需要在后续版本中进行接入。因此，除了在APP环境中调用扫码组件能够正常执行并响应外，其他场景会触发错误页面，提示“扫码失败：目前仅支持APP端进行扫码操作”。此外，xc_hook_scan组件增加了一个安全校验检查，对于非默认通用扫码请求（method: default）外的所有扫码发起，用户必须处于登录状态。如果用户未登录，则会触发xc_login，强制用户跳转到登录页面，并提示用户登录后再进行操作。
4、目前主要的几个扫码场景都已适配升级到新方法xc_hook_scan，这些场景包括【默认快递单号查询、通用页面跳转动作、寄售回收订单查询、快递发货页面，扫一扫自动识别快递单号】等。所有这些场景的扫码动作都已从旧方法升级到xc_hook_scan方法，确保在后续集成小程序扫一扫组件时，可以一键集成扩展，无需重写业务逻辑。此外，后续的扫码接入也都需要通过前端新方法进行处理，以确保扫码功能的统一性和一致性。
5、至此，宫论的扫码组件已完全重构完成，全面采用HOOK钩子设计，每个扫码场景都按照标准化进行集成。整个执行流程如下：1、通过xc_hook_scan发起扫码动作，支持环境识别，不同的环境调用不同的扫码组件。2、APP端使用plus_scan发起扫码动作，然后封装data扫码参数组件，包括token令牌、扫码标识method、以及对应扫码参数配置信息。接着使用xc_hook_app_request发起扫码动作，请求APP端进行扫码响应动作。3、APP端收到扫码请求后，会解析请求参数，并进行核验并发起扫码请求。如果请求顺利执行，则通过H5-app通讯组件，将扫码结果返回到SPA页面端。4、页面监听器收到结果后，会通过xc_hook_app_evaljs触发器交互动作，将请求转发到xc_hook_qr_result(data)进行处理。5、二维码解析请求事件收到扫码结果后，会核验token令牌等信息，确保请求的可靠性。然后发起ajax请求到服务端，进行扫码结果识别（出于安全考虑，扫码请求必须通过服务端进行响应解析）。6、服务端在收到扫码解析请求后，会调用xc_qr_result_hook方法进行解析处理，内部会根据不同的场景调用相应的method方法，不同场景处理的业务逻辑各不相同。在处理前会核验token和用户的请求是否可靠，如果不可靠则会进行拦截处理。7、服务端解析完成后，会将处理参数返回到前端xc_hook_qr_result_callback事件，具体页面需要如何交互处理，将通过返回结果进行处理。
6、consignment_acceptance(寄售回收订单工作人员审核页面)，现已在右上角集成了最新版的扫一扫功能，绑定的事件方法为【xc_hook_scan('consignment_acceptance');】。点击后，将按照标准流程加载APP或小程序的扫一扫组件。完成扫码动作后，如果请求可靠且成功解析（获取到关键的link和request），前端会通过ajax监听器进行页面跳转，引导用户进入订单详情页。在订单详情页，用户可以查看寄售回收订单的所有信息，包括藏品的图片和视频、用户的联系方式等详细内容。
7、宫论新增了一个物流追踪更新接口：xc_query_logistics_tracking。该方法主要负责处理物流单号的追踪。具体处理机制如下：用户传递快递单号信息后，系统会首先检索宫论物流表中是否存在该记录。如果记录存在，系统会检查快递状态是否已完成，若已完成则直接返回物流信息；若未完成，则进一步检索上次更新时间。如果上次更新时间小于2小时，系统仍旧读取数据表中的物流信息；如果更新时间超过2小时且快递状态未完成，系统将尝试调用接口进行物流查询，并将查询结果更新至数据表中，同时返回最新结果。此流程设计旨在尽量减少API接口调用次数，因为每次查询都需要等待响应时间，而且使用第三方物流查询接口是需要付费的。
8、在使用 xc_query_logistics_tracking 接口进行快递单号查询时，必须传递一个名为【CODE】的固定值参数。这个参数可以是 xc_express_delivery 数据表中的【ID主键】或者【code：快递单号】，两者都可以用于查询并且互相兼容。通常建议通过ID来发起查询请求，因为ID是唯一的，而快递单号（code）可能会因为不同快递公司生成的规则而出现重复。在极端情况下，可以使用快递单号进行查询。不过，无论选择哪种方式进行查询，都必须严格限制在宫论物流表的记录范围内，任何外部单号都不予处理。这是为了防止接口信息暴露，从而避免被恶意利用。
9、宫论快递单号查询方法采用标注的数组结构进行处理，确保查询结果以固定格式返回。具体来说，返回的结果包含两个主要属性：code和msg。其中，code用于指示查询的状态，若其值为1，则表明查询失败，且无法记录相关信息。失败的原因可能多种多样，用户可以通过msg属性了解具体失败原因。相反，若code值为0，则表示查询成功。在成功查询的情况下，除了code和msg之外，系统还会返回一个名为express_delivery的数组，该数组提供物流订单的详细信息。此信息包括快递公司名称、快递单号、发货时间、发货人信息、物流走向，以及最后更新时间等关键参数。这种结构化的返回方式不仅提高了数据的可读性，也为用户提供了全面且详细的物流信息查询体验。
10、运单查询系统有两个基础拦截机制：1、通过xc_is_login方法获取当前用户的UID，如果用户未登录，则系统会直接返回code=1，msg=请登录后再进行查看。由于物流单号查询仅限登录用户进行，因此未登录用户会被拦截处理。2、快递单号查询通过xc_query_express_delivery方法进行，如果单号不存在，系统会直接返回false，从而减少对wpdb的处理负担。如果单号不存在，系统会直接返回code=1，查询失败：快递单号信息不存在。
11、在使用宫论统一查询方法进行快递单号查询时，为确保物流追踪信息的实时性和准确性，系统会禁用缓存功能，通过将uncache标记为true，避免因缓存导致的运输轨迹信息与实际不符的情况出现。在查询失败时，除了返回常规的code和msg属性字段外，还会额外提供一个经过xc_empty转义处理的HTML字段。该字段包含msg返回的字符串内容，旨在为用户提供清晰的错误提示信息。此HTML提示信息可直接嵌入到快递信息查找组件页面中，以便用户在无需触发额外提示信息的情况下，快速了解查询失败的原因和细节。

2025年4月25日
1、在触发 xc_hook_qr_result 事件时，系统会逐步检查对象信息，以确保请求的执行合理且可靠。首先对传入的 sacn 对象进行解析处理，如果传递的数组参数不存在或不是对象，则直接视为非法请求。接着提取 result 对象，依次检查其 token、method、result 三个属性的完整性和有效性，若缺失或不符合要求，则立即返回相应的错误提示。其中，token 的核验处理尤为关键，因为它是通讯加密的核心。必须确保 token 的有效性和可靠性，并通过时间戳来控制其有效期，以防止过期或无效的请求对系统安全造成威胁。
2、在基础信息核验完成后，系统通过 xc_loading_show 显示加载指示器【扫码结果中】，随后以 AJAX 方式将 scan 对象发送至服务器进行响应和解析处理。宫论API接口在接收到扫码识别和解析请求后，会将请求参数转发至 xc_qr_result_hook 后端钩子进行处理，并将钩子的处理结果原样返回至前端进行响应。在发送至钩子之前，会对POST参数 scan 进行基础核验，以确保传递的参数合法且可靠。
3、xc_qr_result_hook二维码结果解析钩子现已支持hook_before拦截脚本的集成。当解析请求触发时，系统会首先调用【xc_qr_result_hook_before】函数，并在拦截脚本中对所有请求参数和请求来源进行全面核验，确保此次解析合法且可靠。同时，系统会预埋【xc_apply_filters(FUNCTION, func_get_args()】过滤钩子，允许外部注册方法来接管此次解析请求。值得注意的是，在拦截脚本中可以根据不同的method场景执行相应的拦截响应处理。
4、本次对二维码解析HOOK钩子的重构（后端）不再兼容旧版二维码请求处理，传递的scan变量必须为数组结构。若传递的scan变量不是数组结构，或者数组中未包含【token、method、result】三个必需属性，则解析将失败，并返回错误信息：请求未包含所需参数，请联系管理员进行修复处理。需要注意的是，由于响应体结构发生了根本性变化，继续兼容旧版二维码解析请求可能会导致语法错误，因此决定不再进行兼容处理。若遇到扫码场景不支持的情况，需及时进行适配处理，以确保所有场景均可正常使用。
5、通过在hook_before阶段拦截脚本，实现扫码核验检测时，会调用xc_is_login函数获取当前用户的UID。如果扫码操作的场景并非来自登录状态，则必须强制用户进行登录操作。若获取user_id失败，系统会直接返回错误提示“扫码失败：请登录后再进行操作”，并同时返回jump指令为login，前端在收到该信息后会主动触发xc_login功能，弹出一键登录界面或跳转到对应的登录页面。需要特别注意的是，绝大多数扫码操作都涉及用户的交互处理，若未登录状态下允许页面执行交互操作，安全防护不到位时，极有可能导致订单信息泄露等安全风险。因此，在扫码结果返回之前，必须严格做好拦截和验证处理，确保用户登录状态的合法性，有效防止未经授权的访问和数据泄露，保障系统和用户的信息安全。
6、新版本扫码接口接入的第一个事件是【consignment_acceptance】寄售回收藏品验收入库操作。在寄售回收审核列表页面，将集成此项plus扫码动作。用户点击按钮后会触发【plus_scan】扫码动作，其中method场景会标记为consignment_acceptance，表明此次扫码来源于工作人员进行入仓操作处理。服务端在接收到该请求后，会对该场景进行专门识别并响应处理。值得注意的是，重构后的扫码场景中，method必须指定，因此后端在解析扫码结果时无需逐级解析，可以快速返回对应结果。
7、在处理扫码场景为【consignment_acceptance】时，用户必须登录才能进行扫码操作，否则系统会返回相应的错误提示。此外，我们会对扫码结果进行基础验证，确保其合法性。如果扫码结果的长度超过20位，则被视为非法请求，因为快递单号的最大长度不会超过这一数值。此时系统将返回错误信息：“扫码失败：不是有效的快递单号”。如果扫码结果符合规定条件，我们会通过xc_query_express_delivery接口统一查询发货记录，启动快递信息查询流程。该流程将检查数据库中是否存在相应的发货记录。需要注意的是，由于该查询仅需获取运单信息，因此可以直接从缓存中读取数据，以提高响应速度。
8、在使用xc_query_express_delivery功能读取运单记录时，如果未能成功获取相关记录，系统会提示错误信息：“扫码失败：没有找到快递运输记录”。一旦成功找到运单记录，系统会进一步检查$express_delivery['link']是否为空。如果此字段为空，则返回错误提示：“扫码失败：运单没有关联生成页面地址”。需要特别注意的是，对于寄售回收订单，该link字段必定存在，因此这种情况不应出现。如果成功获取link，意味着本次扫码识别顺利完成，系统将返回代码和信息：“code：msg：单号识别成功”。
9、在consignment_acceptance场景成功获取到link（订单页面地址）后，将通过do_shortcode进行短代码解析处理，还原成前端支持的link页面地址信息。接着会额外返回相关信息【request：page、link：对应的地址字段】。前端的ajax监听器会自动通过xc_hook_page_request(data.request, data.link)执行页面跳转处理。跳转方式是通过内页APP访问并打开指定的link地址。这样一来，实现了通过扫描运单号，自动跳转到订单详情页。在验收时，可以通过扫描藏品运单号信息，一键进入订单详情页。
10、前端新增了一个名为xc_hook_qr_result_callback的回调脚本。当用户发起扫码识别请求时，如果服务端返回的code为0（表示解析和处理成功），这个回调脚本就会被触发。在触发时，服务端返回的信息将通过msg参数传递给回调脚本。这个回调脚本的主要作用是根据不同的场景来处理页面的交互动作。由于在不同场景下，返回的msg数组对象内容会有所不同，因此执行的页面交互动作也会有所差异。开发者需要根据返回的字段内容来进行具体的处理。同时，请注意，服务端在返回信息时，必定会包含一个method参数，用于指示处理的具体方法。
11、在服务端成功解析扫码结果后，会在返回前端之前触发hook_afte脚本。触发时，会将包含扫码结果、扫码场景以及其他相关字段的result数组传递给该脚本。hook_afte脚本通过xc_do_action(FUNCTION, $result, func_get_args())来注册动作脚本，这样如果第三方或外部事件需要同步获取扫码结果，就可以按照要求注册事件来接收此次扫码结果。需要注意的是，hook_afte仅负责回调，并不负责管理返回的过程。