宫论项目开发记录

2025年4月2日
1、在用户完成发货操作后，服务端会将相应的结果反馈给前端进行处理。前端页面会根据返回的code值进行相应的页面交互操作。如果code值为1，则表示本次发货操作失败，可能由于各种原因被拦截处理。此时，页面会通过msg显示相应的提示信息。如果接收到的结果是code值为0，则表示本次发货操作成功，同样会触发msg提示，但后续还会执行一些方法来进行页面交互处理。除了监听code值外，系统还会对complete状态进行监听处理，以确保在服务器响应异常的情况下，主动触发xc_loading_hide，避免页面始终处于异常状态。
2、新增了名为xc_express_official_hook_callback的回调脚本，当用户成功发出寄售回收藏品后，服务端将会返回code=0。此时，系统不仅会触发页面提示，还会激活这个回调脚本。在回调脚本中，页面将会执行以下一系列简单的交互操作。首先，将特定元素进行页面锁定处理【$('.send_collection_details_content');】。接着，获取页面中的操作按钮，并对其进行一系列调整：清理按钮的onclick事件以防止重复点击，将按钮文字更改为“发货成功”，并将按钮的背景颜色更改为黑色。
3、在规范化管理方面，后续所有前端HOOK事件的执行，如果成功【code=0】，都会主动触发相应的callback脚本事件。所有的页面交互都将通过callback脚本来处理。在回调脚本中，回调参数的命名方式将通过原HOOK名称加上callback后缀进行处理。如果需要接管相应的回调处理，只需检索原HOOK名称即可。需要注意的是，通过callback进行页面交互时，必须主动继承原有的变量参数，以确保能够正确进行相应的页面交互处理。
4、对ajaxSetup全局初始化配置进行了优化调整，新增了以下监听器：【dataFilter：数据处理过滤器】【error：自定义错误处理（覆盖全局错误）】【success：成功回调（需慎重使用，避免出现冲突）】【complete：请求完成后（无论成功与否）】【beforeSend：请求即将发送前】。这些监听器都是在ajax请求发送前后执行的处理动作，通过这些监听器，可以全面接管整个ajax交互过程。前后端的交互行为基本上都是通过ajax来完成的，因此这些监听器显得尤为重要。
5、在ajaxSetup初始化过程中，complete监听器会进行额外处理。首先，它会从xhr对象中提取关键参数【responseJSON】，并将其保存到data中。接着，验证返回值是否包含data，如果包含则进一步检查data是否为对象。如果data存在且为对象，还会进一步核验当前页面是否存在遮盖提示层。这个遮盖层是为了防止用户误点击，在页面交互过程中由系统发起的。如果遮盖层存在，则通过complete监听器进行主动关闭操作，以避免服务端响应结果异常，导致页面始终处于遮掩状态，从而无法进行点击交互。
6、系统通用的ajax配置不仅新增了各种监听器，还对以下参数进行了预设处理。首先，withCredentials被禁用以防止跨域时携带cookie，确保系统的整体安全性。其次，dataType默认配置为json，确保ajax请求能够自动响应并解析json结构。processData参数设为true，系统将自动把对象转换为查询字符串。为了避免前端发出同步请求造成阻塞，async参数强制设为true，确保所有请求都以异步模式进行。timeout参数被设定为10秒，这意味着任何请求超过10秒将会立即返回异常。此外，所有ajax请求的type参数均设置为post，确保所有数据传输都通过post方式进行。
7、宫论的AJAX请求会主动携带以下头部信息：【X-Requested-With: XMLHttpRequest】用于标识这是一个AJAX请求；【X-Content-Type-Options: nosniff】用于防御MIME类型混淆攻击。上述两个请求头通过ajaxSetup进行配置处理，每次发起请求时都会自动添加。此外，为了保证参数的安全性和可靠性，每次请求还会携带一个专属头部【X-gonglun-ajax】，其参数为$.now()生成的当前时间戳。这些头部信息将在后续的拦截器中进行安全校验，以确保请求的安全性和可靠性。
8、在初始化 xc 对象时，新增了一个重要字段：wpApiSettings。这个参数通过调用 wp_create_nonce('wp_rest') 函数生成，该函数利用系统内置的安全密钥（Nonce）来提供以下几个关键功能：首先，防止 CSRF 攻击。Nonce 确保请求来自可信的来源，有效防止恶意第三方网站伪造请求。其次，验证用户权限。在执行敏感操作前，通过验证 Nonce 可以确认用户具有相应的权限，从而确保只有授权用户才能进行这些操作。最后，提升安全性。在 REST API、AJAX 请求、表单提交等场景中使用 Nonce，有助于增强整体网站的安全性。这个参数在初始化时生成，后续将会集成到前后端交互中，确保所有请求的可靠性。
9、宫论每次发起ajax请求时，会主动传递以下参数：1、头部信息【'X-WP-Nonce': xc.wpApiSettings】，这是一个WordPress安全随机数，在页面初始化时会自动生成。2、data数据参数：_wpnonce，每个请求自动携带的校验参数；_wp_http_referer，表示当前页面的URL，用于来源页验证。需要注意的是，核心验证参数为wpApiSettings，这是系统生成的唯一加密请求参数，通过ajax发送到服务器端。服务器在接收到请求后，会对该参数进行解析和验证，以确认其有效性。
10、宫论服务端【API请求拦截器：ajax_api.php】已经完成重构和优化处理。新增了安全校验机制：包括重新设计的Nonce校验（同时验证Header和POST参数），具体对_wpnonce和HTTP_X_WP_NONCE进行核验提交处理。通过wp_verify_nonce读取header和data对象中的wp_rest，如果读取失败则说明本请求的参数与后台生成的密钥不一致，此时系统会直接返回错误信息：“非法请求: 参数错误(-02)”，并立即终止请求，返回JSON格式的错误信息，拒绝后续的接口调用请求。
11、服务端的API拦截器，除了进行Nonce效验检测和拦截处理之外，还会执行Referer验证处理。具体操作是通过wp_get_referer函数获取Referer地址，然后从$_SERVER['HTTP_HOST']中获取当前请求的主机名。验证Referer的有效性和来源。如果请求中没有Referer，或者Referer的主机名与当前主机名不匹配，则认为该请求来源不合法。在核验过程中，不仅要比较Referer的主机名是否与当前主机名相同，还会使用hash_equals()函数在恒定时间内比较两个字符串，以防御时序攻击（Timing Attack），确保系统的安全性和可靠性。

2025年4月1日
1、由于集成了update_time字段，可以显著减少对数据表时间字段的维护工作。每当数据表发生变化时，系统会利用CURRENT_TIMESTAMP机制自动发起更新处理。结合status字段的管理，可以明确了解当前订单所处状态的持续时间，从而有效触发系统任务调度的执行。因此，所有主要的数据表均已手动添加该字段，未来新增的业务数据表也必须整合此字段，以确保数据的一致性和追踪性。
2、在完成xc_consignment数据表的状态回调操作后，系统会立即执行【xc_consignment_status_hook($consignment['id'])】方法。该方法是一个内置的通用刷新机制，每当寄售回收订单数据表中的字段发生更新时，都需要通过执行这个方法来刷新缓存数据。这样做的目的是确保分页查询、审核列表和统一订单查询的缓存能够同步更新，从而保证这些页面返回的数据是真实可靠的。
3、在宫论全局push通知管理中，我们新增了一个消息场景：【寄售回收】订单发货线下验收通知。当用户的寄售回收订单通过线上审核后，如果用户在规定时间内通过线上发货页面完成寄出操作，则会触发此消息通知。此通知将提醒相关审核工作人员立即关注订单的状态变化。如果订单已收到货物，则需及时进行验收，并按照流程进行线下入仓和鉴定处理。该通知场景的唯一标识为：consignment_shipping。
4、为了确保系统安全保护，用户通过xc_express_official_hook钩子寄出藏品时，系统会重新通过xc_category_config配置信息读取当前负责的线下工作人员，并将其地址重新写入到$express_delivery['staff']字段。虽然在提交订单时系统会自动写入线上专家人员的信息，但由于存在一定的延迟，从提交到审核再到寄出藏品，这个过程可能长达十几天甚至更久。如果平台在此期间更换了工作人员，可能会导致交易流程出现不可预估的错误。因此，在发货时进行重新读取，可以大大减少这种问题的...
5、在寄售回收的藏品寄出后，相关工作人员会通过多渠道接收通知，确保信息的及时传达。目前已开启【APP通知、站内信、服务号消息】三个渠道来实现这一目标。当APP处于在线状态时，工作人员会收到即时的站内信弹出窗口通知，确保第一时间获取信息。如果APP处于离线状态，则会通过离线消息推送（push通知）将消息传递给工作人员。此外，无论APP的在线状态如何，宫论服务号都会收到发货消息提醒，确保信息传达的全面性和可靠性。用户也可以通过站内信查看订单的发货记录，便于后续的查询和管理。该消息场景已被标记为“寄售订单通知”，以便于信息的分类和管理。
6、关于consignment_shipping的通知计划共有两个步骤。首先，当用户执行发货操作时，系统会触发一条简单的站内消息，提醒验收工作人员及时关注相关订单。这类消息仅限于站内通知，不涉及短信、邮件或公众号等外部渠道。其次，当用户发货超过5天且订单仍处于待发货状态时，系统将启动一次消息检查流程。此时，会发送一条提醒给工作人员，敦促他们及时跟进订单的处理进度。通常情况下，发货后3天左右订单应已处理完毕，若超过5天仍未处理，则可能存在问题。因此，这类通知会采用更为复杂的方式，包含短信和邮件等多渠道提醒，以确保问题得到及时解决。...
7、在通过xc_notify_hook发送【consignment_shipping】通知消息时，系统会自动封装一个变量【push_data】。这个变量包含了一系列关键参数信息，以确保消息在异步环境下能够正确处理。具体来说，push_data包括以下内容：1、id：这是本次处理的寄售回收订单的主键ID，用于唯一标识和后续处理。2、ip：这是通过调用xc_is_ip函数获取的当前用户的IP地址信息。3、ua：当前用户的用户代理（User Agent）信息，由xc_is_ua函数获取。4、指纹信息：这项信息是通过读取用户的浏览器指纹获得的。之所以需要提前封装并传递这些参数，是因为在大多数情况下，xc_notify_hook是在异步环境中运行，系统无法实时获取当前的环境信息，因此需要在通知发送前就将这些信息准备好并封装在一起。
8、在处理寄售回收的用户发货通知时，系统首先调用统一订单查询方法【xc_query_consignment】以获取当前订单的配置信息。如果查询失败，流程将会立即终止。而一旦成功获取，该信息将被存储到变量consignment中。接下来，系统会利用consignment中的数据逐步读取【xc_category_config】的藏品分类配置信息，特别是提取[express_delivery]字段中发货订单的主键ID。随后，系统通过调用【xc_query_express_delivery】方法获取相关的发货记录信息，并将这些信息存储到express数组中。后续的参数封装将依赖于这些获取到的信息，以确保整个流程的顺利进行。
9、寄售回收订单发货PUSH，关键参数封装处理：1、标题通用变量（APP、邮件、服务号、站内信）：[审核通知]寄售回收发货通知。2、正文通用变量：用户已寄出了“' . $cat_name . '”藏品，请及时跟进处理。（其中，cat_name是通过解析category_config配置参数获取的藏品分类。）3、链接通用变量：用户点击后将直接跳转至审核大厅页面，用户需自行在大厅中前往审核列表页面。请注意：未来将推出订单审核页面，届时点击会调整为跳转至订单详情页了。
10、宫论服务号不仅仅是一个简单的消息通知工具，还具有历史记录溯源的功能。用户可以通过点击服务号查看所有过往的关联通知记录。因此，在设计（寄售发货通知）消息场景时，需要尽可能详细地封装信息。除了标题和正文内容外，还通过菜单方式集成以下内容：第一栏显示'订单号'，后接具体的订单ID；第二栏显示'发货时间'，以当前日期和时间格式化展示；第三栏提供'快递公司'的信息，依据快递公司的配置进行解析；第四栏则是'快递单号'，通过提取发货记录获取。这样设计的目的是确保用户在查看服务号消息时，能够一目了然地获取到所有与订单相关的关键信息。
11、完成了push通知下发处理后，xc_express_official_hook事件便已经完成处理。系统此时会返回code=0、msg='藏品发货成功'。剩下的就是前端进行页面交互处理，服务端的响应便已经结束。整个执行过程如下：1、hook_before拦截响应事件，包括外部拦截参数的处理。2、express_delivery物流发货记录参数的封装处理，数据表写入动作处理。3、通过xc_update_sql发起寄售回收订单状态的回调处理，将订单状态、验收员工、快递记录记录更新处理。4、通过xc_consignment_status_hook进行缓存更新处理。5、触发xc_notify_hook消息通知下发，告知工作人员，订单藏品已寄出。6、hook_afte回调动作脚的响应处理。

2025年3月31日
1、在通过xc_express_official_hook成功完成发货请求后，相关的数据将被写入到数据表xc_express_delivery。接下来，系统将进行订单回调操作。具体而言，系统会通过insert变量来判断xc_insert_sql的返回执行状态。如果返回结果为空，则系统将提示错误信息：发货错误：数据表（express_delivery）写入失败！反之，如果返回结果为false，说明执行成功，系统将封装一个名为consignment_update的空数组。该数组将作为后续更新操作的依据，以确保数据的一致性与准确性。
2、consignment_update数组的封装结构如下：首先，将status字段的值变更为4，这表示用户已经完成了发货请求，并已将藏品寄出且填写了运单号。接下来，读取$consignment['time_summary']中的json字段，并在原有基础上新增一个字段【express】，该字段用于记录当前的发货时间。time_summary是一个时间汇总的json字段，用于记录订单各个时间维度的信息。由于涉及到json的复杂操作处理，这里采用了xc_is_json_update方法进行处理，该方法能够自动解析json并转换为数组，同时也支持自动更新并插入新的数组字段，最终再将其转回为json格式。
3、在完成对update数组的更新处理后，系统将生成一个update_where数组，该数组仅包含一个ID参数值。接着，通过对consignment的调用，我们可以获取到订单数据表的主键ID。在将update和where的参数进行封装后，系统会调用xc_update_sql(table_name,table_name,update_data, $where)来执行更新请求。如果更新操作成功，系统将返回true；若操作失败，则返回false。此外，需要注意的是，通过xc_update_sql更新的数据表会自动触发缓存刷新处理，确保后续查询所返回的结果是可靠且有效的。
4、寄售回收订单数据表（xc_consignment）新增一个字段（update_time）该字段为更新时间。字段采用 CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP类型存储。当插入新记录时，如果没有指定update_time的值，会自动填入当前时间。而ON UPDATE CURRENT_TIMESTAMP则是关键，它会在每次更新记录时自动将update_time字段更新为当前时间戳。这里可能需要举例说明，比如当执行UPDATE语句修改其他字段时，这个字段会自动变化。
5、因为订单的复杂性，需要每次订单发生变化的时需要自动更新update_time字段，这样在执行系统任务的时候，task接口可以通过status+update_time来知晓订单状态时间。示例：比如系统任务需要检查用户发货超过5天，还未入仓的寄售订单。对于这类异常订单，需要下发通知给验收工作人员。这个时候可以通过监听status=4，并且update_time超过XX天的记录，然后进行业务处理。这个处理过程非常依赖update_time的自动更新，如果每次都维护这个时间字段，非常的麻烦。最好是系统自动保持更新。‘
6、数据表的规划处理：所有的数据表都增加【update_time】字段，并且都是以UPDATE CURRENT_TIMESTAMP字段类型来自动维护。这样数据表发生变动的时候，系统会自动将对应的时间戳加上。默认情况下，数据表的字段必须包含以下几个字段。1、id（主键值，这里为了兼容性，采用的小写字母）2、time：数据表建立的时间，只有插入的时候才会触发写入。3、status：状态字段。当订单发生变化的时候触发更新处理，通过状态判断订单的类型。4、update_time当订单发生变动系统自动更新的时间。5、可选（type）订单的来源标识，可选，部分数据表不需要。
7、宫论IS脚本库新增了一项检测获取方法，名为xc_is_ua。对于后续的一些业务，如需在服务器端或获取来访者的用户代理（UA）信息，都必须通过该方法发起请求。此方法将在内部通过$_SERVER['HTTP_USER_AGENT']读取浏览器的UA字符串。同时，由于封装层级的问题，可以利用php_sapi_name来验证当前环境是否为命令行，这样能够友好地区分脚本执行和客户执行。此外，该方法还支持接管其他方法，对于APP等特定环境，会通过UA识别进行相应的参数接管和替换，从而实现更高效的返回处理。
8、对xc_is_ip方法进行了重构，以提升系统获取来访者IP地址信息的准确性。传统上，该方法通过$_SERVER['REMOTE_ADDR']来获取IP地址，但未考虑到在代理层下可能存在的情况，导致获取的IP信息不一定真实可靠。重构后的方法会检查常见的HTTP头，以便在出现多层代理的情况下，提取第一个非unknown的有效IP地址。如果成功获取到有效IP，则返回该IP；如果未经过代理，则直接返回REMOTE_ADDR。通过这一系列优化，可以确保系统返回的IP地址始终是可靠且真实的，从而增强系统的安全性和准确性。
9、在通过xc_update_sql完成寄售订单回收操作后，系统将对返回结果进行严格的核验处理。如果操作失败，系统会返回相应的错误信息，并相应地协调后续执行动作以确保问题得到解决。若执行成功，系统将进行订单回调处理，利用Redis清理相关的缓存记录，包括统一订单查询和统一列表订单查询（与当前寄售订单相关的缓存）。这一流程旨在确保未来的订单查询操作均通过wpdb发起，以增强返回内容的可靠性。这项措施有效避免了在发货已完成的情况下，订单查询接口因延迟问题而仍显示处于待发货状态的情况。
10、在完成缓存清理动作后，寄售订单藏品寄出事件便基本宣告结束。此时系统会执行hook_afte脚本，该脚本负责外部事件的回调处理，如果第三方事件需要接收通知，可以通过内置xc_do_action方法来注册函数，注册方法需要按照标准的wp过滤HOOK来进行处理，一旦完成注册，系统在完成寄售回收订单发货处理后，会将对应的ID订单主键转发到注册方法内，具体业务在对应的注册方法中进行执行并响应。
11、xc_consignment新增一个字段：express_delivery（藏品发货记录），当用户提交藏品寄售回收申请的时候，订单会进行线上专家审核，审核通过后。用户需要将藏品寄到官方，在订单详情页完成发货请求后，系统会将发货运输记录写入到【宫论物流跟踪表】，这个时候为了追踪方便，系统会将运输记录ID主键ID值，回调到寄售订单表的[express_delivery]字段，后续物流追踪的处理，都将通过查询这个字段来发起。注：该字段采用INT来存储，因为本身是主键ID，因此必定是数字。长度限定为11位。

2025年3月28日
1、为了提高系统的模块化和重用性，设计了一个专门的HOOK事件，名为xc_express_delivery_add_hook，用于更新wp_xc_express_delivery数据表。这个钩子将接收一个名为express的数组，该数组包含了写入数据表所需的各种字段信息。在构建这个数组时，需要遵循严格的字段标准，虽然部分字段会在内部生成，但大多数字段如订单类型、订单标识、收件人信息、快递单号以及承运公司等都需要从外部传入。重要的是，无论是卖家还是官方发货，都应通过这个HOOK事件来执行数据写入操作，这样可以确保数据的统一性和准确性。
2、系统在通过 xc_express_delivery_add_HOOK 接口更新运输记录时，会返回一个标准的数组结构用于判断处理结果。其中，返回值 code=1 表示写入失败，失败的原因可能包括权限不足、数据表异常、字段结构不符合要求等，具体的错误信息会通过 msg 字段进行传递。所有失败情况统一返回 code=1。若处理成功，则返回 code=0，表示数据库写入已成功完成，当前订单的发货信息也已成功登记。注：在执行业务回调处理前，需要执行收货地址表的更新，如果更新失败需要中断执行，禁止后续的处理。
3、在通过HOOK执行订单发货表的更新处理时，系统会启动以下拦截检测机制以确保操作的安全性与准确性。首先，会检测用户是否已登录；若用户未登录，系统将返回错误信息，并提示用户需要先进行登录，因为在发货过程中，用户在线是不可或缺的，尤其在输入或录入单号的环节。其次，系统会对参数进行效验，检查express数组的结构是否完整，若发现有信息丢失或缺失的情况，将及时返回相应的错误提示。在数据插入表时，系统还会对关键参数进行esc_sql处理，以有效防止SQL注入风险，从而保障系统的安全性。
4、官方收件仓库信息配置组（xc_express_official_config）新增了一个重要字段：user_id（收货员的宫论UID），该字段旨在负责处理一系列发货消息的接收工作。例如，在A仓库（位于上海某地，专门处理玉器寄售）中，一旦设定了收件人UID，当用户或卖家寄出藏品后，系统会自动读取该仓库的站内UID，并及时向相关方发送通知消息。此外，系统在货运列表筛选功能中也将提供通过UID一键查找该仓库收货历史记录的便利。需要注意的是，设定UID并不意味着所有的通知都将通过此UID发送，具体的通知处理方式将依据不同的业务场景而有所区别。
5、为防止重复执行和数据写入，在通过HOOK发起发货处理请求时，系统将利用Redis进行上锁保护，锁定时间为5秒。锁的标识为：express_official:user_id，确保每个用户在同一时间段内只能执行一次请求，重复请求将被系统自动拦截，并返回相应的错误提示，旨在防止用户因不小心多次点击而导致物流信息的重复写入，从而引发后续处理中的异常情况。此外，前端也将设置遮盖层以阻止用户重复点击，但考虑到安全问题，后端的上锁机制倍显必要性，从而提供更为稳妥的防护措施。
6、在封装express_delivery数组的过程中，系统会依次读取一系列配置参数以完成数组的构建处理。首先，通过调用xc_query_consignment接口获取相关的交易订单数组信息。接着，利用xc_is_config接口获取快递公司的配置信息，该信息包括快递名称和快递编号。随后，系统通过xc_category_config接口采集藏品分类的信息，以便于后续的处理。根据订单类型（寄售和回收的配置有所不同），系统会读取xc_express_official_config接口中的官方收件地址配置。最后，依托订单类型，系统将读取相关的线下工作人员信息，并将这些信息保存到staff字段中。
7、express_delivery数组已完成封装，具体结构如下：type（类型标识，例：consignment 表示发货单）。shop_id：订单ID，关联订单表的主键。user_id：发货人ID，可能是商家或系统用户。recipient ：收件人ID，通常是用户UID。name：收件人姓名。phone:收件人手机号. province:收件人所在省份。city：收件人所在城市。county：收件人所在区/县。detailed_address：收件人详细地址（街道、门牌号）。address：收件人完整地址（拼接后的）。courier_company ：快递公司名称。code：快递单号（已使用 esc_sql() 转义）。time：发货时间。created_at：创建时间（通常与发货时间一致）。status：物流状态，0 表示未发货或初始状态。link：跳转链接。express_key：快递公司唯一标识（如拼音缩写、代码等）。
8、xc_express_delivery_add_hook在处理完成基础效验工作后，会直接通过xc_insert_sql($table_name, $data)执行数据表写入动作。并将执行结果保存到$insert变量。如果插入成功则insert是本次插入的行数主键。如果插入失败则会返回false。如果插入失败则返回【错误：数据表执行错误】并返回code=1.如果返回了插入ID，则返回code=0，并且额外返回insert字段。上级业务HOOK钩子，可以通过判断code或者insert来验证是否插入成功。注：xc_insert_sql是系统封装好的方法，支持缓存管理。
9、宫论统一订单查询接口新增了一项方法：xc_query_express_delivery()，该方法可以通过物流数据表的ID来查询相关的物流运输记录。使用此查询方法时，需要传递一个主键变量$id，系统会内部构建一个wpdb查询语句，以便从xc_express_delivery数据表中检索对应的记录。在检索的过程中，为了确保数据安全性，采用prepare函数进行参数过滤，并使用get_row函数来返回单行数据。如果查询结果存在有效内容，则会将其转换为数组格式进行返回；若查询未能找到相应结果，则将返回false。通过这种封装方法实现订单查询，不仅减少了SQL语句的构建复杂度，还有助于后续的维护与管理。
10、物流订单查询方法新增一个缓存控制开关：uncache该值默认为false，即返回优先缓存。如果将其设置为true，则系统会优先检索缓存是否存在，存在的的情况下，则直接返回缓存，而不是从wpdb发起sql查询。这样可以有效的减少数据库的读取，提升整体响应速度。缓存的键名为：$redis_key = "express_delivery:" . $id;。缓存有效期为24小时，超时会自动清理缓存。通过wpdb发起查询的时候，会在返回结果前主动更新缓存结果。
11、为了提升物流查询的灵活性，xc_query_express_delivery统一物流查询方法进行了重要更新。此次更新不仅增强了对ID主键的查询支持，同时也新增了通过code进行查询的功能。系统内部会自动检测传递的ID是否为纯数字，并判断其长度是否小于8位。如果满足这些条件，系统会在wpdb语句的检索中将ID转换为code进行查询。此外，由于ID同时引入了两种查询方式，因此在缓存的更新与写入机制方面进行了相应的调整。在成功读取到查询结果后，系统将同时提取ID和code，并单独执行update_redis_meta操作，以确保两个缓存的同步生效。需要注意的是，这一处理不仅兼顾了ID和code的索引，还实现了缓存的自动同步更新功能，从而进一步提升了查询的效率与准确性。

2025年3月27日
1、xc_express_official_hook 在执行 AJAX 请求前，会先触发一个 layer 弹出对话框，提示用户是否确认进行运单发货请求。如果用户选择取消，对话框将关闭，并终止本次事件的执行流程；如果用户选择确定，则会触发 xc_loading_show 显示遮盖层提示，同时发起 AJAX 请求，并携带 expres 数组参数传递至服务端进行处理。服务端接收到请求后，将执行相应的业务逻辑，并返回处理结果至前端。前端在收到响应后，将执行 xc_loading_hide 关闭遮盖层，以完成整个交互流程。注：增加一个对话框，可以防止用户误操作。因为一旦确定运单填写，不可变更处理。
2、前端在处理 expres 数组时，会对传入参数进行基础校验，以确保提交至服务端的数据是可靠的，从而防止恶意或非法提交行为。具体规则如下：id 必须为数字或可转换为数字的类型，且长度不得超过 8 位，否则返回错误信息【参数异常：主键编号不存在或异常】。key 代表快递公司标识，必须为大写英文字符，且长度不得超过 7 位，否则返回【参数异常：请选择有效的快递公司】。code 作为快递单号，最大长度为 15 位，并需通过 is_html 校验，以防止恶意注入风险，若不符合条件，则返回【参数异常：运单号不符合条件】。
3、在收到运单号录入请求后，后端会创建一个名为xc_express_official_hook的新业务钩子来处理请求。这个钩子会使用宫论API接口捕获参数，然后将其转换为HOOK流程进行处理。在转发HOOK的过程中，系统会通过POST方法提取express数组，并将其一并提交到HOOK进程响应。最后，系统会直接通过xc_exit来返回处理结果。这个hook将返回一个标准的数组结构：code=1代表执行失败，msg字段包含失败的详细原因；code=0代表执行成功，表示运单号已成功录入到系统中。
4、在通过xc_express_official_hook执行运单发货请求时，会经历四个执行步骤。首先是业务初始化阶段，需要将result设置为空数组，随后的返回结果都将通过result数组返回。接着，通过xc_is_login获取当前用户的UID。最后，提取express参数以备后续请求使用。其次是通过hook_before执行全面拦截动作，如果条件不符合将返回相应错误。然后执行业务动作处理，完成拦截请求后，将触发数据写入、通知处理、缓存更新等操作。最后，在hook_after中触发回调动作，一些外部事件的回调将通过这个事件完成。
5、在处理用户发货请求时，hook_before拦截脚本执行以下基础拦截步骤：首先，通过xc_is_login获取当前用户UID。如果获取失败，则返回【错误：请登录后再试】，同时强制前端跳转至登录页面。使用xc_is_security验证环境是否安全可靠。如果不可靠，则返回【设备环境不安全，需要短信验证。】并强制跳转至安全验证页面。检测express数组是否存在，若不存在则返回提交失败：参数数组为空。逐一检查ID、key、code三个参数是否存在，若缺失则返回参数缺失。最后，对express数组的参数进行细节核验，确保参数的可靠性，防止非法提交。
6、在完成基础拦截处理后，系统将进入订单核验流程。确保订单状态和用户是可以进行发货请求操作。具体核验过程为：1、通过统一订单查询方法xc_query_consignment进行订单读取，读取过程中会禁用缓存，确保返回的数组是可靠的。2、如果读取失败则直接返回错误【错误：订单记录不存在】。3、如果订单存在但是订单用户非当前用户则返回错误【错误：你无权进行操作】。订单仅限用户本人操作，防止非法提交。4、如果订单状态status不等于1，则代表订单未处于待寄出状态。此时不允许发货。返回对应错误：错误：订单不处于可发货状态。
7、考虑到后期会有电子面单功能的集成，需要外部接入发货功能。因此在完成基础拦截和订单权限拦截处理后，hook_before脚本会通过xc_apply_filters来接入过滤函数，允许通过add_filter来接管函数的执行。这样后期再执行电子面单功能的时候，可以注册方法来检测订单信息，并进行参数效验。如果符合电子面单需求，则进行返回允许执行，如果参数出现缺失或不对，则返回对应的错误。确保用户在勾选自动面单发货功能的时候，订单能够顺利进行发货处理。注：通过hook_before集成的动态注册过滤事件，必须返回标准的数组结构：即code+msg的组着。code=0外部的拦截规则不生效，允许用户进行下一步操作、code=1外部的拦截规则生效，不允许系统继续往下执行，需要直接放回错误到上一级。并且对应的MSG提示信息，也是必须携带的。因为这个值可能直接要转发到前端，进行页面提示响应。
8、在完成hook_before拦截处理且未触发任何拦截后，发货流程将进入业务执行层。此阶段的第一步是提取参数变量。首先，通过xc_query_consignment函数读取订单配置。虽然之前的拦截脚本已进行过一次读取，但在执行层中需要重新获取这些数据，好在可以利用缓存机制，以减少数据访问的延迟。读取的结果将被保存在consignment数组中。接下来，通过xc_is_config函数读取快递公司的配置列表（标识为xc_express_company_config），从中提取出用户所选择的快递公司的配置信息，并将这些信息存储到express变量中。最后，通过xc_is_cat函数读取当前订单的分类标识，以获取关于藏品分类的详细配置信息。这些配置信息中包括寄售回收订单的线下验收员信息和收货地址，这些都是在此配置中进行读取的。
9、考虑到场景的复杂性，在成功获取到consignment（订单数组）express（快递公司配置）cat（藏品分类配置）三个数组信息后，会对其进行一次检查处理。如果有空数组或者缺失的情况，则会返回错误【错误：关联参数提取失败，请联系官方处理】，该返回除了返回code和msg外，还会额外返回request_id。该参数通过redis进行生成的键位：里面包含了本次请求的所有参数信息。缓存的有效期为24小时。当用户在这一步发生异常的时候，因为整个处理流程比较复杂。因此通过缓存方式记录错误信息，运维在追查问题的时候，可以通过读取redis获取本次请求的所有参数，进一步找到问题，并进行修复解决。
10、在执行寄售回收订单回调操作前，系统会先封装一个express_delivery数组。该数组为宫论物流跟踪数据表，不管是卖家还是买家或者官方。进行订单发货的时候都会触发这个数据表的写入，详细且完整的记录物流记录。里面的包含的数组字段如下：1、type：物流订单来源：寄售回收订单默认值为consignment。shop_id：寄售订单的主键ID。user_id：当前发货人UID。【name、phone、province、city、county、detailed_address】收件人信息，通过读取官方收件仓库信息来获取。不同的订单，会根据分类的不同，指派的收件仓库信息不同。【courier_company：快递公司、code：快递单号】通过用户页面提交的KEY解析获取到快递公司，单号则通过用户输入表单提取。link：跳转链接，这个指向验收订单详情页。created_at：创建时间，当前的Y-m-d H：i:s。express_key：快递公司标识，用于物流公司追踪，用户选择的快递公司时会自动获取到。
11、在完成对express_delivery数组的封装之后，系统将调用xc_insert_sql($table_name, $express_delivery)方法，以实现数据的写入操作。此过程将详细记录到wp_xc_express_delivery数据表中，并将写入操作的结果存储在result_id变量中。接下来，通过empty函数对result_id进行验证，以判断写入是否成功。如果empty(result_id)返回false，则表示数据库操作成功，result_id将存储对应的主键ID。反之，如果返回true，则表示数据库写入过程中出现异常，此时系统将中断所有执行，并返回错误信息：“发货失败：数据表写入异常”。注：后续对寄售回收订单回调操作的时候，需要将发货数据表的主键ID写入到对应字段中，这样订单就与物流信息关联上了。后续验收过程中，工作人员可以通过APP扫运单号，一键完成页面跳转，进入对应的寄售回收订单详情页。

2025年3月26日
1、在进入藏品发货页面之前，系统会额外执行拦截检测机制，通过 xc_is_page_open 方法读取藏品分类配置信息，并依据 $consignment['type'] 判断订单类型是寄售订单还是回收订单。随后，系统会根据订单类型获取相应的收件仓库信息，并调用 xc_is_config 方法获取仓库地址信息。如果仓库地址获取失败，系统将提示【处理事变：官方收货仓库不可用】。此外，如果读取失败，还需进一步检查 OPEN 字段是否开启，若未开启，则会提示【收货地址不可用，请联系官方处理】。
2、在快递发货页面，系统同样会通过 xc_is_config 读取对应订单类型的官方寄件地址，并在页面中构建一个名为 express 的容器。在该容器内，收件地址将以列表形式展示，包括收件人姓名、手机号和详细地址。同时，在容器的右上角提供一个【复制地址】按钮，用户点击后可一键复制收件人信息至剪贴板。该按钮绑定 xc_copy(text, successMessage) 事件，复制成功后，系统会弹出提示【收件地址已复制】。目前，用户收件暂不支持线上下电子面单，后续可根据需求进行功能扩展。
3、在后台的 官方收件信息配置组（xc_express_official_config） 中新增了一个字段：remake 备注栏。该字段为可选项，主要用于仓库的自定义提醒信息。例如，某些仓库可能仅接受京东或顺丰的快递件，且未保价的包裹将被拒收；或者在寄件时，建议用户附上一张包含订单号信息的纸条，以便验收员能够更高效地完成入库处理。由于不同仓库的收件流程和要求各不相同，因此增加一个备注字段是合理的，能够让仓库根据自身需求填写个性化信息，方便用户了解具体要求。
4、系统在成功读取到藏品官方收件仓库后，会封装变量【$address】，其中包含省、市、区及详细地址，并将完整地址展示在address表单中。同时，复制事件xc_copy也会拼接一个【copy_address】变量，该地址结构参数为（姓名:' . $express['name'] . ' 手机号:' . $express['phone'] . ' 地址:' . $address），用户点击复制后，可直接将该信息粘贴至快递网点或在线下单页面，实现一键识别并快速完成下单操作，提升使用便捷性。
5、后台发货配置页面新增字段：xc_express_official_remak（藏品寄往官方说明，展示到发货页面,提醒用户注意事项）。默认内容【官方不接受任何形式的到付件，请务必自行支付运费。建议优先选择京东或顺丰，以确保运输安全。请尽量购买保价服务，避免运输损坏带来的损失。请自行妥善打包，建议使用防震材料（如泡沫、气泡膜）并加固外包装。若运输过程中藏品损坏，平台不负责售后，需用户自行联系快递公司处理。寄出的藏品必须与订单提交的藏品完全一致。若藏品不符，平台将封禁账户，并可能拒收或退回，退回运费由用户承担。在寄件前录制打包视频，并保留快递底单及保价凭证，以便后续维权。】
6、在藏品官方寄件页面的优化中，我们新增了一个 tips 提示框，该提示框位于 express_info 容器内，专门用于展示 xc_express_official_remak（寄件提示信息）。由于该提示信息可能较长，因此表单字段结构已调整为 htmlmixed 类型，以支持长文本及 HTML 结构，同时允许使用系统短代码。页面在输出寄件提示时，会通过 do_shortcode 解析短代码，以确保信息的完整性和可读性。需要特别注意的是，寄件提醒是用户寄件流程中的重要环节，相当于平台的简要版用户寄件协议，能够帮助用户了解运输过程中可能遇到的问题和风险，从而提前做好准备。
7、在藏品寄出页面新增了一个名为 Send_info 的 BOX 容器，用于填写寄件表单信息。用户可以在该页面输入已寄出藏品的运单信息，以便系统进行追踪管理。在该容器中，系统采用 weui 框架中的 cell_select 组件展示 快递公司列表，该列表由后台配置，涵盖主流物流公司，并为每家公司分配唯一的标识码。在前端展示时，系统使用 KEY 作为标识，并以 VALUE 进行命名，以确保用户能够清晰选择对应的快递公司。在提交数据至服务端时，系统会通过 KEY 获取对应快递公司的详细信息，以实现规范化处理。通过这种方式，每个快递公司都具备唯一标识，确保系统能够精准追踪和管理寄件信息。
8、在寄件表单容器中，用户除了需要选择相应的快递公司外，还需手动输入运单号码。为提升用户体验，我们在快递公司选择组件下方新增了一个 WeUI 输入框，方便用户直接录入运单号。此外，为了进一步优化操作流程，后续将会引入扫码功能。在页面右上角预留扫码图标，用户点击后可调用手机摄像头，启用扫一扫功能，自动识别并录入运单号，省去手动输入的步骤。同时，对于主要的几家快递公司，我们还将支持自动选取功能，进一步提升寄件流程的便捷性和智能化。
9、宫论用户协议配置组新增了【藏品官方收件协议】，标识为 express_official。该协议详细规定了用户在寄售或回收藏品时，运输过程中可能出现的损坏、丢失及货不对版的处理方式。用户在填写运单信息后，需主动勾选该协议才能继续操作。协议将通过短代码组件模式集成至寄件页面，以确保用户在寄件前充分了解相关条款。注：用户必须同意并且认可才能进行下一步操作。确保在产生纠纷的时候，平台可以应对处理！
10、在藏品寄出页面，新增一个按钮（提交运单号完成发货），用户在完成运单号的填写后，可以点击这个按钮进行发货处理。该按钮绑定事件：xc_express_official_hook()，不需要传递任何参数变量。HOOK事件触发后，首先会通过xc.is_login检测用户是否登录，如果未登录则触发错误提示。并调用xc_login进行弹出登录框。然后使用xc_is_last_page获取当前页面的标识，如果标识不等于send_collection_details则视为非法请求，提示对应的错误并组织后续的执行。最后使用xc_is_protocol验证协议是否勾选，如果未勾选提示对应错误。
11、当 xc_express_official_hook 完成基础拦截后，会封装两个 let 变量参数。首先是 page_content，它通过页面元素选择器锁定页面的主要内容区域，后续的所有页面交互都需要依赖该元素进行触发。其次是 express，它是一个空数组结构，主要用于存储从当前页面提取的关键信息，包括：id（寄售回收订单的唯一主键）、key（用户选择的快递公司唯一标识，服务端需要解析处理）、code（用户填写的运单号信息）。如果这些参数存在缺失，系统将直接返回错误并阻止后续执行，以确保数据完整性和交互流程的正确性。

2025年3月25日
1、前端在接收到地址删除的响应结果后，将根据返回的状态执行相应的业务逻辑。首先，如果删除操作失败，系统将触发 xc_msg 进行提示，并立即终止后续的处理流程，确保用户能够及时获知失败原因。其次，如果删除成功（即返回 code=0），则会触发 xc_hook_address_update 事件，促使页面进行更新，重新加载上级页面的内容，特别是收货地址列表，以移除当前被删除的地址。此外，前端还会清除删除按钮的 onclick 事件，防止用户误操作，同时调整底部页面菜单的显示状态，将其修改为“该地址已被删除”，并更改背景颜色为黑色，以提供直观的视觉反馈。
2、在处理【删除地址、新增地址、修改地址】这三个业务逻辑时，后端引入了锁机制以确保数据一致性和防止并发问题。具体实现方式是通过 Redis 设定一个名为 lock_address:$USER_id 的简单锁，该锁基于用户 ID 进行区分，确保每个用户的操作互不干扰，避免 A 用户的请求影响 B 用户。该锁的保护周期为 10 秒，超过 10 秒后会自动释放。如果获取锁失败，系统会返回提示信息：“处理失败：重复请求，请稍后操作。” 该锁的主要目的是防止重复请求导致的业务逻辑重复执行。尽管前端已做了相应的拦截处理，但由于前端拦截并不完全可靠，因此仍需后端通过加锁机制进行最终保障。
3、宫论用户收货地址的处理已完成封装，全面支持现代化物流标准，精确到省、市、区，确保地址管理的高效与精准。系统提供一键导入、一键下单功能，并具备城市筛选和快速查找能力，极大提升用户体验。用户可自由新增、修改、删除地址，满足个性化需求。地址读取采用统一查询方案，并结合缓存优化，确保在需要展示收货地址时，系统能优先通过缓存快速响应，减少SQL查询压力。同时，地址变动时，系统会自动更新缓存数据，确保数据的实时性和准确性。此外，所有地址相关操作均基于标准HOOK机制发起请求，使每个环节都可控、可接管，确保系统的灵活性和可扩展性。
4、为了加强安全隐私保护，用户收货地址数据表（xc_user_address）中的电话字段采用加密存储，而非明文保存。这样即使数据库遭遇风险或被非法下载，也能有效防止用户隐私泄露。加密处理的过程发生在【xc_address_update_hook：修改用户地址】和【xc_address_add_hook：新增用户地址】这两个HOOK执行数据库写入时。具体而言，在phone字段写入数据库时，会调用宫论加密函数（xc_encrypt($data)）进行加密，该加密算法基于AES-256-CBC，对输入数据进行加密处理。最终，数据库中存储的手机号将呈现为一段随机哈希值，从而确保用户隐私的安全性。
5、由于收货人手机号经过加密处理，因此在输出时需要进行解密还原。该还原过程通过 xc_decrypt($data) 方法完成，该方法采用 AES-256-CBC 解密算法，对加密数据进行解密。需要注意的是，目前收货地址的查询均通过 xc_query_user_address 和 xc_query_user_all_address 这两个方法进行。因此，在这两个方法返回结果时，需单独对 phone 字段进行解密还原，以确保正确显示用户手机号。注：xc_decrypt解密方法，是通过宫论解密算法处理，内置的KEY参数不可做出二次变更。
6、在寄售回收订单详情页（consignment_order_details）中，如果当前订单状态为【status=1（订单已通过审核）】，则会在status_btn容器内显示一个操作按钮【填写寄件信息】。该按钮绑定事件xc_hook_consignment_user_send_collection，用户可通过点击该按钮触发页面响应。该事件无需传递任何参数，用户点击时，系统会首先检测其是否位于订单详情页，若不在该页面，则视为非法请求；若在，则从页面中提取订单ID参数，并触发页面访问，跳转至藏品寄件页面。
7、新增页面【/module/xc_consignment/send_collection.php】，该页面的唯一标识参数为 consignment_send_collection.php。用户可通过此页面将寄售回收的收藏品寄送至官方指定地点。进入该页面时，需通过 GET 方式传递一个 ID 参数，该参数为寄售回收订单的主键 ID，系统将依据此 ID 获取并关联相应的订单信息。页面采用标准的 APP 结构进行构建，并支持使用 xc_is_last_page 方法获取当前页面的唯一标识，以确保页面导航的准确性和一致性。
8、寄售回收订单寄出藏品页面已优化安全机制，现已通过 xc_local_link 加载 ajax_page.php 脚本库，确保非法请求、机器人行为及恶意访问均能被有效拦截，并触发页面访问限制或跳转至人机交互页面。此外，该页面采用动态页面标识，所有涉及页面参数的部分均通过 page_name 变量动态传递，使页面交互更加灵活，能够通过元素选择器精准锁定页面标识并进行相应处理。同时，在 page-content 容器中新增了自定义 id 属性，使事件处理更加便捷，无需额外传参即可完成页面逻辑操作。
9、在进入藏品寄出页面时，系统会在页面加载前通过 xc_is_login 方法获取当前用户的 UID，并将其赋值给 user_id 变量。同时，系统会通过 GET 请求获取 ID 变量，并将结果存入 id 变量。如果 ID 参数为空，则使用三元运算符将其设为空值。随后，系统调用 xc_query_consignment 统一订单查询接口，传递 id 作为参数，执行订单查询操作，并将查询结果存入 consignment 数组。整个过程中，如果 user_id、id 或 consignment 这三个变量中的任何一个获取失败，系统将立即拦截并终止页面的正常加载，强制跳转至 403 页面，并提示相应的错误信息。
10、寄售回收订单的寄出藏品页面现已支持【xc_is_page_open】访问拦截脚本处理。该拦截钩子需要主动传递两个变量参数：1. page_name（页面唯一标识）；2. consignment（交易订单数组信息，禁用缓存返回的数组）。在拦截脚本中，将执行以下校验逻辑：首先，系统会验证用户身份权限，确保当前访问用户必须是提交寄售回收申请的当事人，只有申请人本人才能访问该页面。其次，系统会检查订单状态，若订单状态不为 1（即“已通过审核，等待寄出藏品”），则用户将无法进行寄出操作。
11、在完成 xc_is_page_open 拦截脚本的校验后，页面将被允许访问和构建。在页面生成之前，系统会先调用以下两个方法获取必要的参数： xc_is_status：用于获取当前订单的状态信息。该方法会接收两个变量——'consignment' 和 $consignment['status']，并返回订单的状态数据。 xc_is_cat($consignment['cat'])：用于获取本次寄出藏品的分类信息。其返回结果将被存储到 is_cat 变量中，其中包含本次藏品的寄出地址以及线下审核员的信息。 通常情况下，这两个方法都会成功返回数据。如果任意一个方法返回失败，系统将终止页面加载，并提示相应的错误信息，以确保页面的正确性和数据的完整性。

2025年3月24日
1、当 xc_address_update_hook 钩子成功修改用户的地址信息后，系统会自动触发缓存清理操作。在执行清理前，系统会先检查数据表的修改是否成功（即返回值是否为 true），如果返回 false，则表示修改失败，并提示错误信息：“修改失败：数据表写入失败”。如果修改成功，系统会主动清理统一订单查询缓存以及用户收货地址列表的缓存，以确保后续查询时返回的地址数据是最新、真实且可靠的。需要注意的是，凡是涉及地址的修改或删除操作，都必须同步更新相应的缓存列表，以保证数据一致性。
2、在完成缓存清理操作后，后端的业务逻辑调整基本告一段落。此时，系统会触发 hook_after 脚本，并携带本次修改的收货地址数据表的主键 ID。在 hook_after 脚本中，系统会注册一个方法，用于接收第三方事件的回调。如果后续需要接管地址修改的通知，可以通过标准方法进行外部注册，确保系统能够自动转发相关通知。完成回调脚本的封装后，系统将返回标准响应 {code: 0, msg: "地址已成功修改"}，至此，服务端的处理流程正式结束。
3、当服务端成功返回结果后，系统会根据 code 值执行相应的业务逻辑处理。如果 code=1，则通过 xc_msg 触发错误提示，向用户说明地址修改失败的具体原因，引导其进行修正。而当 code=0 时，表示地址已成功修改，此时系统会通过 xc_hook_address_update 触发页面交互流程，具体包括以下几个步骤：首先，页面会弹出提示，明确告知用户修改成功；接着，系统会设置一定的延迟后触发页面返回，以确保用户能够看到成功提示；最后，在页面返回前，系统会将最新的收货地址信息同步至上级页面，例如，如果用户修改了收货人姓名，返回后地址列表页将展示更新后的姓名信息，确保数据一致性和用户体验的流畅性。
4、为了提升用户在管理收货地址时的便捷性，考虑到用户可能会因释放额度而删除已有地址，以便新增新的收货地址，因此在收货地址编辑页面新增了一个删除按钮。该按钮位于页面的右上角，用户点击后将触发删除操作。事件名称为 xc_hook_address_delete，该事件无需传递额外变量，系统会自动从页面中提取所需参数，并进行校验处理，确保操作的安全性和准确性。需要注意的是，收货地址的管理权限仅限当前用户，管理员无法进行任何操作，以保障用户隐私和数据安全。
5、xc_hook_address_delete 在发起服务端响应前，会进行一系列拦截检测，以确保用户具备执行该操作的权限。首先，通过 xc.is_login 方法验证用户的登录状态，若用户未登录，则会触发 xc_login()，强制弹出登录窗口或相关组件，并阻止后续操作的执行。其次，系统会尝试锁定元素 page-content.update_address，若锁定失败，则会弹出提示框，警告用户该请求为【非法请求】。随后，从页面中提取 key 作为唯一编号值，若提取失败，则会提示【失败：key获取失败】。在完成所有拦截校验后，系统将触发 xc_loading_show，显示遮罩层并提示【删除中】。最后，系统会发起 ajax 请求，与服务端进行交互并处理删除操作。
6、为了防止用户误操作，在发起删除地址请求前，系统会弹出一个 Layer 对话框，提示【确定删除当前收货地址吗】。如果用户点击“确定”，系统将继续执行 AJAX 请求，并弹出遮罩层以防止二次点击，确保操作的唯一性；如果用户点击“取消”，则直接跳过 AJAX 请求，终止后续执行，避免误删的风险。删除操作本身较为敏感，若不增加确认步骤，用户可能会因误触导致地址被意外删除，影响使用体验。因此，增加确认对话框不仅能有效降低误操作的可能性，也符合良好的用户交互设计。
7、服务端新增了 xc_address_delete_hook 钩子，专门用于处理地址删除业务请求。该钩子需要接收唯一变量 $_POST['key']，该变量对应被删除地址的数据表主键 ID。钩子的封装遵循标准流程，共分为三个步骤：首先是业务拦截层，确保请求的合法性和可靠性；其次是执行层，在通过拦截后正式执行删除操作；最后是回调层，在完成业务处理后执行相应的回调逻辑。此外，该钩子返回标准的数组结构，其中 code=0 表示删除成功，code=1 表示删除失败，msg 字段则用于返回具体的失败原因。
8、当用户通过服务端发起删除地址请求时，系统会通过 hook_before 进行拦截处理，以确保请求的可靠性。具体拦截规则如下： 检查传递的 key 参数是否为空，或者是否为数字。如果 key 为空或非数字，则返回错误提示：【错误：key 参数存在问题】。 通过 xc_is_login 方法获取当前用户的 UID，如果获取失败，则返回错误信息：【删除失败：请登录后进行操作】，并附带 jump=login，要求前端跳转至登录页面。 通过统一的收货地址查询方法，根据 key 进行查询。如果查询失败，则返回错误提示：【收货地址不存在】；如果查询成功，则将查询结果赋值给 address。 检查当前用户的 UID 是否与 address 关联的 UID 匹配。如果不匹配，则返回错误提示：【删除失败：你无权进行操作】
9、鉴于删除地址属于高危敏感操作，因此在前后端均新增了环境检查流程，以确保操作的安全性。系统通过 xc_is_security 变量来校验用户环境的安全性。如果前端检测到环境不安全（返回 false），则会立即跳转至短信验证页面，强制用户完成短信核验后方可继续操作。后端同样依赖 xc_is_security 进行校验，但其验证方式是直接通过 wpdb 数据表检查浏览器指纹信息。如果后端校验未通过，则会返回错误信息【设备环境不安全，需要短信验证。】并附带 jump 参数值 security，前端在接收到该响应后，会自动跳转至短信验证页面。
10、在完成环境检测后，hook_before 脚本即顺利执行完毕。此时，系统会自动封装一个 xc_apply_filters 事件，允许第三方通过过滤机制接入 hook_before 事件，实现灵活扩展。如果需要新增拦截条件，只需通过动态注册 add_filter 过滤事件，即可接管函数的执行逻辑。接管方法的返回值必须是标准的数组结构，其中 code=0 代表符合条件，code=1 代表不符合条件。在外部方法完成检测后，系统会返回 {code: 0, msg: "通过检测机制"}，标志着 hook_before 处理流程的正式结束。
11、在完成拦截检测后，xc_address_delete_hook 将正式进入业务执行层。系统会调用 xc_delete_sql($table_name, $id) 发起删除请求，目标是用户收货地址表中与当前 KEY 匹配的记录。删除操作的执行结果会被赋值给 $delete 变量，随后系统会对其进行参数校验。如果校验结果返回 true，则系统会抛出错误提示【删除失败：数据表写入失败！】。若删除成功，系统将进入缓存清理流程，针对统一收货地址查询和用户收货地址列表查询进行 Redis 缓存清理，以确保后续查询结果中不再包含已删除的地址信息。

2025年3月21日
1、在收货地址管理页面，如果用户已有收货地址，并且当前登录用户是本人，则系统会在每个收货地址的末尾显示【修改/删除】按钮菜单。用户点击该按钮后，将触发访问请求并进入收货地址管理页面。在访问该页面时，系统会主动传递唯一标识【KEY】，用于读取对应的收货地址信息。需要注意的是，只有用户本人才能执行修改或删除操作，而管理员仅具备查看权限，无法进行任何编辑或删除操作。
2、新增或修改收货地址的页面路径为【/global/setting/update_address.php】，其唯一标识为 update_address，并且必须传递 KEY 参数。进入页面后，系统会通过统一的收货地址函数读取对应的收货地址信息，若读取失败，则视为非法请求并进行拦截。该页面采用标准的 APP 结构进行构建，动态生成 APP 标识码，并使用 xc_local_link 加载 ajax_page，以确保通用访问拦截机制生效，从而拦截非法请求及非正常 APP 行为。
3、优化收货地址页面的访问控制，正式启用 xc_is_page_open 访问拦截脚本，以确保用户身份验证的严格性。当页面打开时，该拦截脚本会自动检测用户身份：若用户未登录，则直接拒绝访问并跳转至 403 页面；若用户已登录但尝试修改非本人收货地址，则会触发提示【抱歉，你不具备修改该地址的权限】。身份校验是系统规划中的重要环节，确保收货地址仅能由本人修改。同时，由于收货地址管理页面可供管理员访问，为防止管理员误操作导致地址信息变更，特增加身份核验机制，以提升系统的安全性和数据准确性。
4、当用户进入修改地址页面后，系统会通过 xc_query_address 方法获取当前收货地址的信息，其中，地址的唯一标识 ID 通过 GET 请求参数 key 传递。成功获取地址信息后，页面将自动填充标准的信息栏，包括【姓名、电话、所在省份、所在城市、所在区县、详细地址、是否设为默认收货地址】等字段。该页面的布局和新增收货地址页面基本一致，但不同之处在于，表单中的内容不会为空，而是默认显示用户之前填写的收货地址信息。用户可以根据需要对地址信息进行修改和调整，以确保收货信息的准确性和完整性。
5、在收货地址修改页面的 page-content 容器中新增了四个自定义属性：key（唯一标识ID）、province（地址省份参数信息）、city（地址城市参数信息）和 district（地址区县参数信息）。当页面打开时，页面请求监听器会自动读取这些参数，并向服务端发起 AJAX 请求，调用 API 获取行政区域数据。如果请求成功，系统会将返回的省、市、区完整列表填充到对应的下拉框中，并优先展示当前收货地址的县市区，确保用户可以快速确认或修改地址信息，从而提升用户体验。
6、前端新增了一个 HOOK 脚本 xc_hook_update_address，该脚本绑定在“修改收货信息”按钮的菜单事件上。当用户点击页面底部的按钮时，该 HOOK 会被触发。此脚本无需传递任何参数，触发时会自动检测用户当前所在的页面是否为 update_address，如果不是，则返回非法请求提示；如果是，则进一步提取页面的 key 标识，并按照新增收货地址的逻辑，依次获取页面中的表单元素，将其封装到 _address 数组中。封装完成后，脚本会通过 AJAX 发送修改收货地址的请求至服务端，等待响应处理。
7、服务端在接收到修改地址的请求后，会将该请求转发至业务钩子 xc_update_address_hook 进行处理。整个业务钩子分为三个层级： 拦截脚本层：所有的拦截事件都会通过 hook_before 进行预处理，确保请求符合业务逻辑要求。 业务执行层：在拦截脚本完成基本校验后，系统会执行核心业务逻辑，包括数据表的写入和缓存的更新，以保证数据一致性。 回调脚本层：在完成基础业务处理后，系统会触发 hook_after 进行回调操作。如果需要挂载额外的业务逻辑，可以通过 hook_after 进行扩展和执行。 整个执行流程中，HOOK 统一返回标准化的数组结构，其中 code=0 表示执行成功，code=1 表示执行失败，msg 字段则包含具体的返回信息，便于调试和问题排查
8、收货地址拦截机制的封装工作已顺利完成。首先，系统会检查用户的登录状态，若未登录，则直接判定为非法请求并予以拦截。接着，通过主键 ID 读取对应的收货地址信息，若查询结果为空，则返回相应的错误提示，表明该收货地址不存在。在此基础上，对 address 数组的内容进行严格校验，该校验逻辑与创建流程基本一致，先检查是否存在缺失的变量，再逐一核对各个参数，确保其符合预期标准。所有条件满足后，系统会通过 hook_before 机制构建一个注册方法，使外部能够通过注册的方式集成新的拦截条件，从而提升系统的灵活性和可扩展性。
9、在完成基础业务拦截校验后，系统将通过 xc_update_sql($table_name, $update_data, $where) 语法触发收货地址表的更新操作，对用户提交的收货地址修改请求进行数据表更新处理，并将处理结果存储至 update 变量。随后，系统会对 update 变量进行核验，若返回 false，则表示更新操作失败，系统将返回错误提示【执行失败：数据表写入异常】。若返回 true，则系统会执行缓存清理操作，确保订单查询时的地址信息得到同步更新，从而保证后续查询结果的准确性和可靠性。
10、在执行 xc_update_sql 操作前，系统会先检测用户提交的收货地址信息是否包含默认选项（default）。如果存在默认收货地址，系统会通过 wpdb 语句将当前用户的所有收货地址的默认状态重置为 0（即清除之前的默认地址）。随后，将用户新提交的默认收货地址状态更新为 1，以确保默认地址的正确变更。与此同时，在完成数据表的更新操作后，系统还会将用户自定义的元字段 address_default 更新为当前默认地址的主键 ID。这样，在后续读取用户默认收货地址时，能够准确获取到最新的默认地址信息，确保数据的有效性和一致性。
11、由于修改收货地址涉及敏感操作，因此在执行该操作时，无论是前端还是后端都会对用户身份进行严格校验。前端在发送 AJAX 请求前，会调用 xc_is_security 进行安全检查，如果返回 false，则会强制用户跳转至短信验证页面，要求用户完成短信身份核验。后端则会在拦截脚本事件中通过环境检测语句进行安全校验，如果返回 false，则会返回错误信息【设备环境不安全，需要短信验证。】并同时返回 jump: security，强制用户跳转至安全验证页面，以确保操作的安全性。

2025年3月20日
1、新增收货地址页面新增了两个 change 选择监听器。首先是 xc_address_province（省份选择器），当用户选择省份时，会触发城市选择器，并通过 API 请求高德地图，获取该省份下属的城市列表。例如，选择江西省时，系统会返回【南昌市、宜春市、赣州市、九江市……】等行政区域，并将这些城市列表动态插入到对应的下拉选项中。其次是 xc_address_city（城市选择器），其逻辑与省份选择器类似，但在用户选择城市时，会请求接口获取该城市下属的县区列表。采用 API 方式的优势在于数据的准确性和实时性，但也需要考虑 API 请求的延迟问题，因此可以考虑建立本地数据表进行维护。
2、当服务端接收到用户提交的收货地址保存请求后，会执行 xc_add_address_hook 业务钩子，将前端封装的 address 数组传递至业务 HOOK 进行处理。该 HOOK 采用标准数组结构执行，首先通过 hook_before 进行拦截和预处理，然后执行核心业务逻辑，包括数据存储和缓存更新，最后通过 hook_after 进行回调处理。整个流程均返回标准化的数组结构，其中 code=0 代表成功，code=1 代表失败，msg 字段用于返回错误信息。
3、在用户新增收货地址时，hook_before 依次执行以下拦截检测：首先，通过 xc_is_login 获取用户 UID，若用户未登录，则返回错误提示【请登录后再进行操作】，并返回 jump: login，要求前端跳转至登录页面。其次，对 address 提交的参数进行完整性校验，若参数缺失或格式不符，则返回错误并阻止提交。然后，系统通过 xc_is_security 进行环境安全检测，若检测到异常环境，则返回【设备环境不安全，需要短信验证】，并返回 jump: security，要求前端跳转至短信验证页面。
4、在 address 数组结构的校验过程中，系统会执行以下检查：首先，读取 xc_pay_address_limit 配置，若用户的收货地址数量已达到或超过后台设定的上限，则返回错误【添加失败：最多设置 ' . $address_limit . ' 个收货地址】。然后，依次检查 nickname（收件人姓名）、phone（手机号）、address（详细地址）、province（省份）、city（城市）、district（区县）是否为空，若有缺失，则返回【添加失败：收件人信息不完整】。此外，系统通过 xc_is_html 检测省市区参数，若发现 HTML 代码，则返回【添加失败：非法提交】。对于 nickname，系统使用 mb_strlen 进行长度校验，若超过 10 个字符，则返回【添加失败：收件人姓名字数过长】。手机号则通过 xc_phone_regular 进行格式校验，若格式不正确，则返回【添加失败：收件人手机号不正确】。详细地址的校验包括 xc_is_html 和 mb_strlen，确保其内容合法且长度不超过 100 个字符。
5、在完成参数校验后，系统进入业务执行流程。首先解析 address['default'] 参数，若其值为 true，则表示该地址需设为默认地址。在处理前，系统会通过 wpdb 查询用户是否已有收货地址，若无，即使 default 传递的是 false，也会强制设为 true。随后，系统会执行 wpdb 语句，将当前用户的所有收货地址 default 字段重置为 0，然后通过 xc_insert_sql($table_name, $data) 将新的收货地址写入数据库，并将 SQL 执行结果赋值给 $insert_id。若 $insert_id 返回 false，则返回错误【数据写入失败】。
6、当服务端通过 WPDP 成功构建新的收货地址信息后，如果该地址被设为默认地址，系统将执行相应的更新操作。首先，用户自定义元字段 address_default 将被修改为最新构建的收货地址主键 ID，以确保默认地址信息的准确性。同时，系统会触发缓存更新机制，对 xc_query_user_address 进行全量缓存刷新，确保用户在查询收货地址列表时获取的始终是最新、可靠的数据。为了验证数据是否成功写入，可通过 insert_id 进行判断——如果该值存在，则说明插入成功，并且其值即为新建地址的主键 ID。
7、在用户新增收货地址后，系统会根据服务端的响应结果执行相应的业务逻辑处理。如果返回的 code=1，则会通过 xc_msg 触发错误提示，引导用户进行修正。而当 code=0 时，表示收货地址添加成功，系统不仅会弹出成功提示，还会执行一系列页面交互优化。首先，移除提示框，确保界面整洁；接着，对保存按钮进行处理，先移除 onclick 事件，防止用户重复点击导致的多次提交；然后，将按钮的背景颜色修改为红色，以直观地传达操作成功的状态；最后，将按钮上的文字更改为【地址添加成功】，进一步增强用户的操作反馈体验。
8、在用户添加收货地址后，需要确保上级页面能够及时更新，使新地址能够有序地展示在列表中。为此，前后端共同新增了一个回调方法：xc_hook_address_update。前端会将服务端返回的HTML结构动态插入到列表页面，使新添加的地址与已有地址保持一致，支持选择、删除和修改等操作，并确保所有交互控件均可正常使用。xc_hook_address_update 作为收货地址列表的交互更新HOOK，在地址新增、删除或修改时，都会通过该方法来同步更新页面元素，以保证数据的一致性和交互的统一性。封装该方法的目的是为了提高维护的便利性，使代码更加清晰和可扩展。
9、为了提升用户在【add_address】页面的操作便捷性，新增了一个导入收货地址的功能。具体实现方式是在页面右上角添加一个“导入”菜单选项，用户点击后将触发 layer 弹出表单窗口。窗口标题设为“导入新的收货地址”，输入框内提供提示语，引导用户复制粘贴收件人信息（包括联系人、电话、地址）。此外，新增“一键识别地址”按钮，用户可直接从电商平台（如淘宝、京东、拼多多）复制收件信息粘贴至输入框，点击按钮后系统将自动解析并填充相应字段，极大减少了手动输入的繁琐步骤，提高了填写效率和用户体验。
10、收货地址一键识别功能的实现依赖于服务端的响应与解析处理，该过程由 xc_address_parse_hook 负责执行。整个流程如下：首先，系统会对请求的合法性进行校验，若用户未登录，则直接拒绝请求；若用户已登录，但提交的字符串中包含 HTML 标签，则返回错误提示【地址解析失败：内容不得包含 HTML】。接下来，系统调用 xc_is_address_parse 进行地址解析，该解析过程依赖于内置 SDK 进行处理。如果解析成功，解析结果将被赋值至 address_parse 并返回给用户；若解析失败，则返回错误提示【地址解析失败：无法识别处理】。需要注意的是，由于解析依赖于内置 SDK，其识别准确率可能存在一定局限性。如果对解析精度有更高要求，可以考虑集成第三方 API（付费）以提升识别效果。
11、当收货地址解析成功后，系统会返回标准化的省份（province）、城市（city）、手机号（phone）、姓名（name）等信息。其中，姓名、手机号和详细地址会直接填充到页面表单中，而省市区（行政区域）信息则需要经过高德地图的二次处理，以获取更详细、完整的地址列表，确保用户在解析后仍可自由选择省份、城市等信息。该处理流程会在 xc_is_address_parse 接口响应成功后，实时调用高德 API 进行解析。如果地址解析成功但高德 API 发生故障，系统将终止执行，并返回错误提示【执行失败：高德 API 接口出现故障】。

2025年3月19日
1、用户更多资料设置页面的【address】菜单请求路径已调整为：do_shortcode('[xc_link type=global]/setting/setting_address.php?author_id=' . $author_id)。此前的旧版本已正式下线，现阶段所有收货地址的管理（包括新增、删除、修改）均通过该地址进行处理。新版收货地址管理页面已全面适配数据表的管理和存储机制，功能更加完善，能够满足现代化物流标准的需求。同时，该页面支持丰富的扩展功能，如电子面单生成、实时物流追踪等，为用户提供更高效、便捷的地址管理体验。
2、修复了用户在进入个人收货地址管理页面时，xc_is_page_open 访问拦截钩子误判权限的问题。此前，由于权限验证机制的错误，当前用户如果不具备管理权限，会被错误地拦截并跳转至【xc_403】页面，同时显示“你无权访问页面”的提示。此次修正后，系统会自动过滤 user_id 等于 author_id 的情况，即使当前用户不是管理员，但访问的管理页面属于自己，也不会再被拦截，从而确保用户能够正常管理自己的收货地址。
3、在进入收货地址管理页面后，系统会首先检查是否通过 GET 方式传递了 author_id 参数。如果 author_id 存在，系统会验证其是否与当前用户的 ID 相匹配。若 author_id 与当前用户一致，则直接读取当前用户的头像信息；若不一致，则调用 xc_get_avatar 方法获取对应用户的头像。这样的逻辑确保了页面的归属权正确归类，避免了管理员在查看收货地址列表时误读取自己的地址信息。此外，页面右上角现在会显示用户的头像，方便管理员快速区分当前所查看的收货地址是否属于本人，从而提升管理的准确性和用户体验。
4、新增了一个变量 myself，用于判断当前用户的权限状态。如果当前用户是管理员，并且不是当前收货地址的归属方，则 myself 设为 false，否则设为 true。在页面底部，会进行参数校验：当用户的收货地址数量小于系统后台设定的上限，并且 myself 为 true 时，页面将显示 xc_setting_btn 按钮（用于添加新的收货地址）。用户可以点击该按钮进入添加页面，新增收货地址。需要注意的是，系统出于安全考虑，会通过 xc_pay_address_limit 配置项来限制用户可添加的收货地址数量，默认最多允许添加五个。
5、新增收货操作页面 add_address.php 已完成开发，该页面的唯一标识为 add_address，并采用标准 APP 结构进行构造。在用户访问该页面时，系统会首先加载 ajax_page.php，并应用通用拦截规则，以有效过滤机器人行为和非法请求，确保系统安全性。此外，页面还集成了 xc_is_page_open 机制进行拦截处理，若当前用户未登录，或 author_id 与 xc_is_login 获取的 UID 不匹配，系统将阻止访问。值得注意的是，该功能仅允许用户本人操作，管理员无权代为添加收货地址，以确保用户隐私和数据安全。
6、当用户进入 add_address 页面时，系统会触发 onPageBeforeInit 事件监听，并通过 AJAX 请求调用宫论 API 接口 xc_address_province，该接口依赖高德地图 API 以获取全国行政区域的地址信息。如果请求成功，系统会将返回的地址数据动态插入到页面中，供用户选择所在省份、城市和区县。这些表单项均由服务端生成并实时渲染，以确保数据的准确性。由于收货地址需要精确的地理位置信息，因此用户在添加收货地址时，必须逐一选择相关的行政区域，以确保地址的完整性和准确性。
7、通过高德地图读取行政区域的业务逻辑如下：1、首先通过 xc_get_option('xc_gaode_map_web_key') 获取高德地图 API 的 Web Key。2、构造 API 请求 URL，调用 高德地图行政区划 API。3、使用 file_get_contents($api) 发送 HTTP 请求，获取 API 返回的 JSON 数据。4、通过json_decode($result, true) 将 JSON 字符串转换为 PHP 数组。5/检查 API 返回的数据是否是数组，并且是否包含 districts[0]['districts']（即子行政区划）。6、如果数据异常，则调用 xc_exit(1, '高德API接口异常'); 终止程序并返回错误信息。7、遍历 districts 数组，将每个行政区划的 name 生成 <option> 选项。8、额外添加 “钓鱼岛” 和 “海外地区” 选项。9、将生成的 HTML 选项存入 $data_arr['html']，并设置 code 为 0（表示成功）。
8、新增收货地址页面的开发已完成，页面包含6个可操作的按钮和表单项，以确保用户能够准确填写收货信息。具体包括：1. 姓名输入框：用于填写收货人的姓名；2. 手机号/电话输入框：支持用户输入收货人的联系方式；3. 省份选择下拉框：用户可从下拉列表中选择所在省份；4. 城市选择下拉框：根据所选省份动态加载对应的城市列表；5. 区县选择下拉框：根据所选城市进一步筛选区县信息；6. 详细地址输入框：用于填写具体的街道、楼牌号等详细地址信息。省、市、区数据均通过高德 API 实时获取，确保地址信息的准确性和实时性。同时，收货人电话和详细地址采用表单输入方式，以提升用户体验和数据录入的便捷性。
9、新增收货地址页面新增了一个复选框选项【是否设置为账户默认的收件地址】，用户在添加新地址时可以选择勾选该选项。如果用户勾选了该复选框，提交时会携带 default 参数至服务端进行处理，系统会将该地址设为默认收货地址。若用户已有默认地址，系统会遍历现有地址列表，将原默认地址的标识更新为非默认，并将最新添加的地址设为默认。需要注意的是，如果用户是首次添加收货地址，无论是否勾选该选项，系统都会自动将其设为默认收货地址，以确保用户始终有一个默认的收货地址。
10、前端新增了一个名为 xc_hook_add_address 的 HOOK 钩子，专门用于保存新增的收货地址，并绑定在页面的“保存”按钮上。当用户点击添加按钮时，该 HOOK 会被触发，并执行一系列校验逻辑：首先，通过元素选择器锁定 add_address 元素，若未能成功锁定，则返回“非法请求”错误；其次，利用 xc.is_login 方法验证用户是否已登录，若未登录，则返回相应的错误提示，并强制跳转至登录页面；然后，检查所有输入框和选择框是否为空，确保六个表单项均已填写，若有缺失，则返回“信息不完整”提示；此外，还会对单个字段进行校验，例如：若姓名超过 10 个字，则提示“姓名过长”；若电话号码格式不符合内地手机号规范，则返回“请输入正确的内地手机号”；若省市区未选择，则提示相应的错误信息；若详细地址少于 5 个字，则提示“请补充详细的地址”。
11、在提交收货地址时，除了对基础信息字段进行校验外，还会额外检查 xc_address_default 元素，以验证用户是否将该地址设置为默认地址。如果用户已设置默认地址，则会将 default 标记为 1。在完成所有参数的读取后，系统会创建一个 address 数组，并将所有参数封装到该数组中。随后，通过 AJAX 请求将该数组发送至服务端进行处理。为了防止用户重复提交，在发起 AJAX 请求前，系统会显示遮罩层提示，待请求完成后再关闭遮罩层。接下来的业务逻辑则交由服务端进行相应的处理和反馈。

2025年3月18日
1、对 xc_address_hook 的拦截脚本进行了优化处理，现在会根据 type 值执行相应的拦截检测逻辑。如果 type 为 add，则检测机制保持不变，依旧会解析提交的 address 数组并逐一检查其有效性。而对于 update 或 delete 操作，则额外增加了对 id 主键参数的检查，因为这些操作涉及对已有收货地址信息的修改或删除，必须确保 id 存在，否则无法继续执行后续操作。因此，在处理 update 或 delete 时，需要通过 xc_query_user_address 进行查询，并在查询过程中禁用缓存，以确保获取到的地址信息是最新且准确的。
2、用户修改收货地址属于较为敏感的操作，因此我们新增了安全检测机制，以确保操作由用户本人执行。具体流程如下：首先，xc_address_hook 组件移除了 user_id 变量，系统内部将通过 xc_is_login 方法获取当前用户的 UID。如果用户未登录，则系统会返回错误提示【请登录后进行操作】；如果用户已登录，则进一步调用 xc_is_security 方法检测当前设备环境的安全性。如果检测结果为 false，系统将返回错误提示【设备环境不安全，需要短信验证。】，并同时返回 jump: security，强制前端跳转至安全验证页面，以确保操作的安全性。
3、在 xc_address_hook 执行过程中，当操作类型为 ADD 时，系统会构建 wpdb 查询语句，以检查当前用户是否已有收货地址记录。如果查询结果为空，意味着用户此前未添加过收货地址，此时系统会将 address 标记为 1（默认地址）。首次新增的收货地址会被自动设为默认，以确保在后续的地址管理和订单结算过程中，系统能够正确展示默认收货地址。由于默认收货地址在用户体验中至关重要，系统在处理时需格外细致，确保默认地址的逻辑清晰、准确，避免因地址管理不当导致用户操作困扰。
4、新增用户自定义元字段 address_default：当用户的默认收货地址发生变更时，该字段将被更新。具体流程如下：当用户首次添加收货地址时，系统会创建 address_default 字段，并将新建的收货地址主键 ID 写入其中；如果用户修改默认收货地址，则该字段会更新为新的默认地址 ID。在页面展示用户收货地址时，系统会从用户资料中提取 address_default，并结合 xc_query_address 获取默认收货地址的详细信息。需要注意的是，为了确保数据的实时性和安全性，该字段的维护应禁止缓存处理，并在发生变更时及时更新，以确保用户始终获取到最新的默认收货地址信息。
5、在完成 xc_address_hook 业务处理后（包括删除、新增和修改操作），系统会自动触发缓存清理机制，以确保数据的实时性和准确性。具体而言，xc_query_address（统一ID查询收货地址方法）和 xc_query_user_address（用户统一收货地址查询方法）都会进行缓存更新，确保用户在查询收货地址时获取的始终是最新的数据。值得注意的是，收货地址的所有操作和管理均由 xc_address_hook 统一处理，因此业务逻辑可以专注于核心功能，而缓存的同步更新将由系统自动执行，无需额外干预，从而提升系统的稳定性和数据一致性。
6、在 xc_user_address 数据表中新增了一个字段 code（行政区划代码），字段类型为 VARCHAR(25)。该字段用于记录用户收货地址对应的行政区域代码，精确到县区级别。目前，该字段作为备用参数，计划通过高德 API 解析地址以获取相应的行政区域代码。当前阶段暂不进行处理，仅预留该字段，后续如有需求，可在相关接口中扩展集成。引入行政区域代码的优势在于能够快速筛选同城交易订单，并精确统计各地区的交易量。
7、由于业务需求的调整，收货地址需要重新建表，因此前端相关页面也需要进行重构。首先针对 setting_address（收货地址管理）页面进行优化，该页面用于展示用户的收货地址列表。由于该页面构建时间较早，部分设计已不符合当前 APP 的标准风格，因此需要进行调整优化。具体改动如下：1. 拦截 AJAX 请求：对 ajax_page.php 的访问事件进行拦截，确保系统能够有效限制机器人行为，防止非法请求的发生。2. 引入动态页面标识：所有页面标识均通过动态变量引入，以确保页面的唯一性，并在元素变更时能够快速适配，提升维护性和扩展性。
8、对收货地址页面的 page-content 元素进行了优化调整，新增了类名 xc_app <?php echo $page_name; ?>_content，以便将其标记为标准的 APP 页面，从而支持通过内置方法检测当前页面是否匹配。此外，增加了自定义属性 page_name 和 author_id，其中 page_name 作为页面标识，进入页面后可通过监听器进行匹配；author_id 用于标识查看用户的 UID，当管理员访问用户的收货地址时，该属性将会生效。
9、xc_is_page_open 拦截访问钩子现已支持 setting_address 页面处理，针对以下情况的请求将被重定向至 403 页面： 若用户未登录，则视为非法请求，禁止访问该页面，以确保收货地址等敏感信息的安全性。 若 author_id 变量存在，表示管理员正在查看用户的收货地址，此时系统将通过 xc_is_admin_x 进行身份验证。如果访问者不具备管理员权限，页面将提示【抱歉：你不具备访问权限】。若验证通过，则 author_id 将被设置为 user_id，并通过 xc_get_avatar 获取用户头像及基础信息，以便后续页面构造使用。
10、当管理员查看用户的收货地址时，系统将在页面的 page-content 容器下动态展示一个提示标签，内容为【你正在查看 <m>' . $avatar['nickname_type'] . '</m> 的收货地址信息】。此标签用于明确标识当前查看的收货地址属于指定用户，而非管理员本人。该提示仅在管理员通过用户资料页面审查收货地址信息时才会显示，系统会通过 avatar 进行身份验证，以确保当前查看的地址不属于管理员本人。如果平台无法联系到用户，管理员可以尝试查看其收货地址信息，以获取可能的联系方式，从而提高沟通效率。
11、在完成收货地址页面的构建后，系统会执行一个 wpdb 查询方法，以获取指定用户的所有收货地址信息。查询结果若存在，则会将其转换为数组格式，并存储到 address 变量中。在页面容器中，系统会使用 empty 方法来判断是否存在收货地址数据。如果用户已设置收货地址，则通过 for 循环遍历并展示地址列表；若用户尚未添加收货地址，则页面会根据用户身份显示不同的提示信息。例如，普通用户会看到【当前用户没有设置收货地址，请添加新的收货地址】，而管理员则仅能查看用户的收货地址信息，无法进行修改或操作。

2025年3月17日
1、xc_swoole_asyn接口在返回code的时候，会通过xc_redis_count方法来进行计数统计处理。计数器的唯一标识为：swoole_asyn，将异步请求记录进行递增+1处理。记录每日平台累计swoole的实际操作数。可以通过get_redis_count($key)获取计数器统计详情，支持查询【总数、今日、昨日、本周、上周、本月、上月、今年、去年】多维度的计数器查询统计。注：这个计数器可以监听异步处理接口的压力和性能。
2、为了提升 Swoole 异步进程的稳定性，宫论固定计划新增一个定时任务，每天凌晨 04:00 触发 xc_swoole_reload 函数，对 Swoole 服务器进行平缓重启。此操作旨在释放常驻内存，确保系统长期运行的稳定性。重启过程采用平滑过渡方案，并安排在凌晨时段执行，以尽可能减少对业务进程的影响。需要注意的是，如果 Swoole 服务器本身已出现故障，重启请求可能无法成功执行。
3、为了提升系统的稳定性，新增了一个基于【swoole_asyn】的日志报警器。该功能的主要作用是在 swoole 接口请求发生故障时，自动记录错误日志，方便运维团队快速排查问题。报警触发机制如下：当同一天内某接口请求失败次数超过 10 次时，系统将自动触发警报并通知指定管理员。为了避免过度报警，系统设定了报警上限，即最多触发 3 次警报，若连续 3 次触发后仍有异常，则不再继续发送通知。此外，短信报警功能已开启，确保管理员能够及时收到警报信息。需要特别注意的是，swoole 作为系统中的关键功能，其服务器的稳定性至关重要，一旦发生故障，系统将立即触发报警，以便尽快修复问题，保障业务的正常运行。
4、修复了在 Swoole 执行部分项目函数时出现的 xc_get_option 请求错误问题，该问题导致后台配置读取失败，进而影响方法的正常执行。经过深入排查，发现问题的根源在于 Swoole 环境下无法直接读取 $_SERVER 超全局变量，导致配置读取接口无法正确返回数据。为了解决此问题，我们通过 global 关键字对相关变量进行了二次声明，确保其在 Swoole 环境下能够正常访问。此外，除了对 $_SERVER 变量进行重新声明，我们还对 wpdb 进行了相应处理，以确保数据库操作对象能够正常响应并执行相关操作，从而提升系统的稳定性和兼容性。
5、在执行 Swoole 服务器请求时，如果服务器返回的状态码不是 200，则可能意味着服务器出现了故障。此时，系统会通过 curl_error 捕获具体的错误码，并触发日志报警接口。日志的记录格式如下：[时间: ' . date("Y-m-d H:i:s") . '] [返回状态:' . $httpCode . '] [错误信息: ' . $errorMsg . '] [执行函数: ' . $functionName . ']。系统会将本次请求的错误信息记录到 swoole_asyn 日志文件中，并在内部进行检查和处理。如果错误符合特定条件，还会触发报警通知，提醒管理和运维人员及时处理，以确保服务器的稳定运行。
6、Swoole 服务器的封装工作现已完成，这将成为宫论项目的重要核心扩展之一。未来，项目中的大部分异步请求和高并发任务都将依赖 Swoole 进行处理。目前，已集成的 Swoole 具备以下特性：支持远程脚本重启、每日定时计划执行重启、异步进程转发机制（系统内置的大部分函数均可通过异步方式执行）、多种日志记录方式、故障报警通知机制以及基于 Redis 的计数器统计功能。接下来，将进入实装阶段，并在更多应用场景中进行测试和优化，以确保其稳定性和高效性，同时根据测试结果进一步完善封装。
7、在用户收货地址数据表（xc_user_address）中新增了一个组合索引：user_id, time, name, default。该索引的引入能够显著提升查询性能，使得系统可以更快速地检索指定用户的所有收货地址信息，并且能够高效筛选出默认的收货地址。由于收货地址表的存储机制以及用户可能拥有多个收货地址，预计该表数据量会随着时间快速增长，因此提前构建该组合索引，有助于优化查询效率，确保后续系统在处理相关请求时能够保持高速响应。
8、宫论服务端封装一个全新的HOOK钩子：xc_add_address_hook，该钩子需要传递两个变量。1、user_id：当前用户的UID，考虑到异步的执行可能性，该HOOK钩子需要主动传递user_id，而不是从xc_is_login来实时获取。2、address：数组结构：包含完整的收货地址信息参数，这个数组一般是通过前端用户参数提交获取。该钩子返回标准的数组结构：code=1、代表执行失败。code=0代表执行成功。
9、xc_add_address_hook 钩子采用标准化的钩子执行顺序来处理业务逻辑，同时支持 hook_before 拦截脚本和 hook_after 回调脚本。在用户新增收货地址时，系统会优先执行 hook_before，该脚本可用于拦截并响应事件，同时支持外部方法注册，允许第三方扩展拦截逻辑。如果 hook_before 返回的 code=1，则会阻止收货地址的新增，并向上层返回相应的错误信息。接下来，系统会执行核心业务逻辑，包括数据表的写入、通知的处理以及缓存的更新等。业务处理完成后，hook_after 将被执行，并会接收新增收货地址的主键 ID。如果外部系统需要获取新增的收货人信息，可以通过 hook_after 进行回调注册，以便接收相关数据。
10、hook_before基础拦截规则如下：1、通过xc_is_user方式判断传递的user_id是否正确，如果系统没有这个用户则返回非法请求。2、检查address数组是否为空，如果为空的情况则返回【参数缺失】。3、依次检查address数组中的【name、phone、province、city】四个字段是是否都存在，如果有缺失则返回错误（字段缺失）。4、通过正则方式匹配phone是否为手机号或者电话号码。如果匹配失败则返回手机号错误。5、检测name长度是否大于10位数（中文算一个），如果超过10位数则返回姓名过长。7、通过xc_apply_filters注册外部方法。8、条件都符合的情况下，返回code=0，允许进入业务响应。
11、针对用户收货地址的业务处理，原本分别为新增、修改和删除三个场景单独封装 HOOK，但这样会导致拦截和回调脚本的数量增加，后期维护成本较高。因此，对 xc_add_address_hook 进行了调整，统一命名为 xc_address_hook，并新增 type 参数，该参数包含三个固定属性：add（新增收货地址）、delete（删除收货地址）和 update（修改收货地址）。原有的 address 数组变量保持不变，但传递的参数需根据 type 进行区分。这样，一个 HOOK 即可同时处理收货地址的增删改操作，调用时只需关注 type 的值，提高了代码的可维护性和可读性。

2025年3月14日
1、当通过 xc_swoole_reload 触发 Swoole 服务器的重载操作请求时，系统会使用 curl_getinfo 获取返回的 HTTP 状态码。如果状态码为 200，则会解析返回的 JSON 数据，并转换为标准的数组结构。同时，Swoole 服务器会对该请求进行验证，若符合条件，则调用 $server->reload() 发起重启请求，并返回 code=0 给前端，表示重启成功。若请求不合法，则返回 code=1，并提示无效请求。此外，如果 HTTP 状态码不是 200，则会直接判定请求失败，无法完成 Swoole 服务器的重载操作。前端可以通过 code 的值来判断重启是否成功。
2、Swoole 的重启服务并非异步执行，而是同步执行的，必须通过 $response->end 发送回复消息后，才会真正关闭请求。因此，在初始化 cURL 请求时，会将超时时间设定为 5 秒，如果超过 5 秒仍未收到响应，则会主动断开连接。此外，出于参数提交的安全性考虑，Swoole 仅接受 POST 请求，并且无论是请求还是响应，都必须采用 JSON 结构。同时，返回的数据格式严格遵循 code、msg 和 data 三个字段的标准结构，以确保数据的规范性和一致性。
3、宫论Swoole服务器共有四个监听器，分别承担不同的功能：start 监听器负责服务器启动时的初始化操作，每次启动时触发一次，通常用于重置服务器环境；request 监听器用于处理请求的接收与响应，所有的参数都需通过 request 进行处理，包括任务的分发、服务器的重启等，值得注意的是，只有 request 监听器能够同步返回消息；task 监听器用于任务的异步处理，绝大部分任务都会通过 task 进行响应和执行，但由于其异步特性，进入 task 处理的请求将无法直接回复消息；finish 监听器用于接收任务的最终处理结果，通常用于清理资源或执行后续操作。
4、Swoole 服务器现已成功集成 WordPress 运行环境。当 Task 监听器接收到业务响应时，会通过 require_once 加载 wp-load.php，并使用 define('WP_USE_THEMES', false) 进行标记，以确保仅加载 WordPress 核心库文件。在任务执行过程中，允许调用项目及 WordPress 的所有核心方法。同样地，Finish 监听器也会加载 wp-load.php，因此在需要进行回调操作时，可以安全地执行数据库交互。需要注意的是，由于 Swoole 采用常驻内存模式，并且存在多个 Task 进程，因此在每次响应任务时，都需要检查是否已正确加载 WordPress 依赖文件，以确保执行的稳定性和可靠性。
5、swoole新增task任务function_asyn 于在服务端处理业务逻辑时涉及消息下发、缓存清理、数据写入等操作的场景。此前，这类异步任务主要依赖 Workerman 进行处理，但该方案存在一定弊端。为优化异步执行能力，引入 Swoole 作为新的解决方案。相比同步处理方式，Swoole 能有效避免进程阻塞，特别是在业务逻辑复杂的情况下，能够显著降低前端响应时间。接下来，将对该方案进行性能评测和稳定性测试，若效果理想，将逐步替换现有的异步处理方案，全面升级至 Swoole。function_asyn 主要负责异步任务的规划与执行，确保系统在高并发场景下的稳定性和效率。
6、新增方法 xc_swoole_asyn()，该方法利用 Swoole 服务器实现异步执行指定函数。调用时需传入两个参数：$functionName（要异步执行的函数名）和 $params（传递给函数的参数数组，默认为空数组）。方法内部会先读取后台 Swoole 服务器的地址，并构造一个请求数组，其中包含 type（值为 function_asyn）、function（需要执行的函数名称）以及 params（传递的参数数组）。随后，该数组会通过 json_encode 转换为 JSON 结构，并通过 HTTP POST 请求发送至 Swoole 服务器进行异步处理。由于该方法采用异步执行方案，因此 curl 配置如下：使用 POST 请求、设置 500 毫秒的延迟、不使用任何信号处理，并在请求头中标记 `Content-Type: application/json
7、在使用 xc_swoole_asyn 发起异步执行请求时，为了避免出现递归调用的“套娃”现象（即在 Swoole 环境中仍然触发并执行，导致无限循环执行），系统会通过 defined('IS_SWOOLE') && IS_SWOOLE 来检测当前运行环境是否为 Swoole 服务器。如果检测到当前环境已经是 Swoole，则不会再通过 curl 请求下发到 Swoole 进行响应，而是直接使用 call_user_func 执行目标函数。此外，系统还会检查 params 数组是否存在，如果存在，则会使用 call_user_func_array 传递参数并执行函数，以确保调用的正确性和灵活性。
8、Swoole 在处理 function_asyn 请求时，首先通过 request 监听器获取请求参数。由于统一采用 JSON 结构，因此在接收到 request 请求后，会通过 $response->header 将请求头标记为 application/json，然后利用 json_decode 将 JSON 数据解析为数组，并将其赋值给 $data。如果 $data['type'] === 'function_asyn'，则进入异步 TASK 处理业务逻辑。具体操作流程如下：通过 $server->task 发送一个任务请求。当 task 进程接收到该请求后，会对传递的参数进行校验，并使用 call_user_func 或 call_user_func_array 执行相应的业务逻辑，从而实现异步任务的处理。
9、Swoole 引入了任务标识机制，以解决任务异步执行时无法同步返回结果的问题。在某些场景下，任务完成后需要触发异步通知，因此需要对任务进行标记处理（任务 ID）。目前的方案是在接收到请求时，使用 uniqid("task_", true) 生成唯一标识作为任务 ID，并将其赋值给任务。在通过 $server->task 下发任务时，会携带该 ID 作为参数。任务执行完成后，会将处理结果和任务 ID 一起发送到 finish 监听器。此时，可以选择将 ID 和处理结果存入 Redis 缓存或数据库表中，方便后续查询；或者直接通过 WebSocket 将响应结果推送给指定用户，实现实时通知。
10、xc_swoole_asyn 由于引入了任务 ID 概念，在任务下发成功后，Swoole 需要返回该 ID 给服务端，以确保后续的监听或回传能够顺利执行。因此，该方法现在会监听并接收返回的数据包，而这个返回结果是由 request 进行处理的。具体流程如下：当收到异步执行请求后，系统会生成一个任务标识 ID，并通过 $server->task 下发任务。此时，response->end 会返回一个 JSON 数据包，格式如下：{'code' => 0, 'id' => $id, 'task_id' => $task_id, 'msg' => "异步任务执行请求已提交"}，其中 id 即为本次任务的唯一标识。该返回操作不会等待任务执行完成，通常延迟在 50ms 以内，不会阻塞进程。收到任务 ID 后，即可进行监听和响应，例如：通过 Redis 记录当前客户端的 WebSocket 参数，并在任务完成后异步推送处理结果通知等。
11、为了更高效地监听异步进程的可靠性，task 在执行任务的过程中会通过 xc_log_error_warn 记录执行日志，日志文件命名为 swoole_task。日志格式如下：时间：[当前时间 Y-m-d H:i:s]，请求类型：[${data['type']}]，任务 ID：[${id}]，执行函数：[${data['function']}]。此外，在 finish 监听器中，同样会记录任务的执行结果日志，基本参数与 task 记录一致，但额外增加了 result 字段用于存储返回结果。通过任务执行前后的日志记录（基于任务编码），可以有效追踪任务的完整处理流程，确保任务执行的可靠性和可追溯性。

2025年3月13日
1、新增了一个统一的订单查询方法 xc_query_user_all_address，该方法需要传递固定参数 user_id（即查询用户的 UID）。系统会通过内置的 wpdb 语句生成查询语句，并返回指定用户的所有收货地址。为了优化用户体验，返回结果中会进行优先级转换处理：如果用户存在多个收货地址，则 default=1 的地址会被放在第一位。这样在展示用户收货地址时，默认地址将优先显示，确保用户在选择地址时更加便捷。
2、xc_query_user_all_address 查询方法现已支持缓存处理方案，新增 uncache 变量，默认值为 false（即启用缓存）。系统会基于预设的 key 进行 Redis 缓存查询，若缓存中存在数据，则优先返回缓存结果。若需更新缓存或禁用缓存，只需将 uncache 设为 true，系统便会跳过缓存查询，直接构建 wpdb 语句执行查询请求。需要注意的是，所有通过 wpdb 发起的查询请求都会同步更新 Redis 缓存，缓存有效期为 24 小时，超时后自动释放。
3、为了应对系统可能面临的并发处理压力，宫论项目决定集成 Swoole 异步编程框架。该框架支持高效的异步 I/O 操作，使系统在等待 I/O 任务（如文件读写、网络请求等）完成的同时，能够继续执行其他代码，从而提升整体性能。此外，Swoole 提供强大的协程支持，使开发者能够以同步编程的方式编写异步代码，在处理大规模数据或高并发请求时，能够高效地管理多个请求并行执行。宫论后台的任务系统涉及大量计划任务，因此，我们将充分利用 Swoole 的异步任务功能和协程机制，优化后台任务的调度与执行，提升系统的整体运行效率，确保业务流程的稳定性和高效性。
4、后台新增了一个专门的配置页面：Swoole，用于管理和调整 Swoole 相关的参数配置，包括服务器运行命令、重载语法以及异步请求方法等。所有配置项都将通过该页面集中管理，以提升后续的维护性和扩展性。配置页面的具体路径为 configure/Swoole.php。目前，宫论项目已通过扩展方式成功集成并安装了 Swoole 5.5。值得注意的是，当前项目并未直接运行在 Swoole 环境中，而是通过建立独立服务，并利用 Swoole 的异步特性和协程机制来缓解同步阻塞问题，从而提升系统的并发处理能力和整体性能。
5、宫论项目新增了 api 目录，未来所有 API 请求将采用分离方案，不同的业务逻辑请求将分别构建独立的 API 请求接口文件，以提升维护性和扩展性。例如，所有 Swoole 相关的请求将通过 api/Swoole.php 处理，而 WebSocket 相关的请求则由 api/websocket.php 负责，各业务模块相互独立，避免干扰。在集成 API 接口时，仍然会加载 wp-load.php，确保业务代码的通用性。同时，之前的 API 接口方案仍然保留，但后续的所有新请求需遵循新的标准执行。
6、当前 Swoole 服务器的启动脚本位于【api/swoole/swoole-server.php】，系统目前监听的端口为【9501】，且服务器已开放该端口。目前的启动方式仅支持通过命令行执行，后续计划将其挂载至开机事件，以确保服务器重启时能够自动启动。同时，需要确保 Swoole 运行的稳定性，防止因异常情况导致崩溃，从而影响业务的正常运行。由于 Swoole 未来将承载大量系统计划任务的处理，一旦出现不可用的情况，可能会引发一系列不可控的问题。因此，在后续优化中，需要重点关注 Swoole 进程的监控与自动恢复机制，以提升系统的可靠性和可用性。
7、后台Swoole配置页新增字段：xc_swoole_server（服务地址）。该字段并非指向具体的脚本文件，而是用于内部请求的地址，例如 0.0.0.0:9501。在进行异步或协程请求时，内部方法会调用该地址进行响应处理。此外，页面还提供了启动、重载和关闭服务的命令，方便管理。如果需要手动操作服务管理，可以通过 cd 命令切换到对应目录：/www/wwwroot/www.acocoa.com/wp-content/module/public/function/acocoa/api/swoole，然后在命令行执行相应的管理命令即可。
8、Swoole 服务脚本的参数配置如下：worker_num 设置为 4，表示工作进程的数量为 4 个，以便更好地利用多核 CPU 资源；max_request 设定为 10000，意味着每个 worker 进程在处理 10000 个请求后会自动重启，以防止内存泄漏；max_conn 设为 800，表示允许的最大连接数为 800，确保服务器在高并发情况下的稳定性；task_worker_num 设定为 10，表示 Task 进程的数量为 10，用于处理异步任务；task_enable_coroutine 设为 true，允许在 Task 进程中使用协程，从而提高异步任务的执行效率；log_file 指定了运行日志的存储位置，日志将被记录在当前目录下的 log_file 文件中，方便问题追踪和重要信息记录；log_level 设为 SWOOLE_LOG_TRACE，这是最详细的日志级别，能够记录包括跟踪信息在内的所有日志，便于调试和监控系统运行情况。
9、由于 Swoole 本身是常驻内存的，因此当脚本库或方法发生变更时，需要手动重启 Swoole，这一过程较为频繁且不够便捷。目前只能通过命令行进行重启，操作较为繁琐。如果采用定时任务进行周期性重启，虽然可以一定程度上缓解问题，但无法保证实时性，同时频繁重启可能会对业务造成干扰。基于此，决定构建一个 HOOK 钩子机制来优化重启流程。该机制通过监听请求，当 $request->server['request_uri'] 包含 reload 参数时，触发 $server->reload() 方法，实现 Swoole 的自动重启，并返回“重启已挂载”的响应。后续将通过 HOOK 触发该请求，使得在需要重启时，仅需执行相应的 HOOK 即可完成操作，从而提升开发效率并减少人为干预。
10、为了保持业务逻辑的一致性，Swoole 服务器仅支持 JSON 格式的数据包。数据包的结构必须包含以下关键参数：type，用于标识请求类型。由于 Swoole 需要处理多种业务逻辑，因此必须依据 type 值来确定具体的处理方式，并决定相应的返回格式。data，该字段为子数组，包含提交的各类参数信息，例如待执行的函数名称、关联变量参数、任务 ID 以及 Redis 相关标识参数。由于 data 采用数组结构，其具体格式需根据不同业务场景进行封装和处理。此外，返回结果也遵循标准化格式，采用数组结构，包含 code（状态码）和 msg（返回信息）。需要特别注意的是，由于 Swoole 不支持直接处理数组，因此无论是发送请求还是返回响应，均需使用 JSON 格式进行数据传输。
11、封装一个swoole方法：xinle_swoole_reload()通过 HTTP 请求触发 Swoole 服务器的重载操作。它的主要步骤和逻辑如下：函数首先调用 xinle_get_option('xc_swoole_server') 来获取 Swoole 服务器的基础 URL。然后，将 /reload 追加到 URL 末尾，形成完整的请求 URL。使用 curl_init() 初始化一个新的 cURL 会话。执行请求并获取响应，如果状态码为 200，表示请求成功。此时，使用 json_decode($response, true) 解析返回的 JSON 数据，并将解析后的数组返回。如果状态码不是 200，表示请求失败。此时，返回一个包含错误代码和错误消息的数组。

2025年3月12日
1、寄售回收申请拦截事件（xc_consignment_apply_hook_before）现已优化，系统将通过 xc_is_config 读取藏品分类的配置信息，并依据 $consignment['type'] 依次检查寄售和回收的相关参数设置。如果 consignment_address 或 recycle_address 为空，系统将返回错误提示：申请失败，所属藏品分类未设置收货地址。此外，如果某个藏品分类已开启寄售或回收功能，但未配置官方收货地址，系统仍然不会允许提交申请，以确保流程的完整性和数据的准确性。
2、如果收货地址存在，则系统会调用 xc_is_config 方法读取 xc_express_official_config 配置数组，以获取官方收货仓库地址。系统会使用相应的 key 进行精确匹配查找。如果查询结果为空，或者查询到的地址存在但 open 字段为 false，则表示该地址不存在或已被停用。此时，系统将返回错误提示："申请失败：官方收货地址不存在或已停用！"。 注意：寄售回收订单的申请必须确保藏品的寄出地址信息存在且有效，以避免用户在申请通过后将藏品寄送至错误的地址。
3、新增数据表：xc_user_address 数据表，该表专门用于存储宫论用户的收货地址信息。此前，收货地址数据是通过用户 meta 自定义元字段存储的，但这种方式存在明显的不合理性。首先，收货地址涉及的字段较多，且用户可以设置多个地址，使用数组存储并进行反序列化处理会占用大量字符串资源。随着用户数量的增长，这种存储方式会给 meta 数据表带来巨大压力，影响查询效率和系统性能。因此，建立独立的数据表来存储用户地址信息是更合理的方案。通过单独建表的方式，不仅可以优化数据存储结构，减少 meta 表的负担，还能灵活扩展字段，以满足不同业务需求，提高系统的可维护性和扩展性。
4、xc_user_address数据表基础字段规划如下：id：主键唯一值，绝大部分的情况下，都是通过这个主键来读取用户收件信息。user_id：对应的用户UID参数，表明该收货地址信息为指定用户的。time：收货地址的创建时间。1、name：收货人姓名（该字数长度不超过10个中文）。2、phone：收件人手机号或者电话号码、3、province：用于存储收件人所在的省份信息，便于区域管理。4、city：详细记录收件人所在的城市，利于快递路线优化。5、county：明确收件人所在的区县，以提高投递精准度。6、detailed_address：这是一个可手动输入的字段，用于详细记录收件人的住址，如“XXX路XX小区X栋X单元”，确保快递人员能够准确找到收件地点。通过将收件人的详细信息分离成独立字段，可以更好地适应各种系统交互需求。
5、系统会对用户地址信息表进行了加密处理：为了提升数据安全性，（phone：收件人手机号或电话）字段将采用内部加密方式进行存储。具体实现上，在数据写入数据库时，该字段会经过加密处理，而在读取时，则通过解密函数还原出真实有效的号码。由于该表采用单独建表的设计规范，一旦发生安全风险，若数据表被恶意获取，可能导致全站所有用户的收货信息泄露。因此，明文存储手机号存在极大的安全隐患。此外，未来在进行等保合规审查时，也不允许明文存储此类敏感信息，因此本次优化能够有效降低数据泄露风险，提升系统的安全性和合规性。
6、在用户收货地址管理功能中，新增了两个时间字段：time（记录用户创建该收货地址的时间）和 updated_time（记录收货地址的最新修改时间）。当用户对收货地址进行修改时，updated_at 字段会自动更新。此外，新增了 default 字段，用于标识默认收货地址。默认地址的规则如下：用户首次创建收货地址时，该地址会被设为默认地址；在用户拥有多个收货地址的情况下，始终只能有一个默认地址。当用户修改默认收货地址时，系统会将之前的默认地址标记为 0，并将新选中的地址设为 1。该功能的实现需要确保数据一致性，避免出现多个默认地址的情况。
7、在构建用户收货地址信息时，新增了一个可选的 Remark 备注字段，用户可在此填写个性化需求，例如指定快递公司（如禁止发韵达、要求发顺丰）或配送要求（如必须送货上门）。此外，还增加了一个 meta 扩展字段，采用 JSON 结构设计，以便未来在字段扩展时通过 meta 记录相关信息，减少对数据库表结构的直接修改。至此，用户收货地址数据表的整体结构已完成规划，为后续的灵活扩展奠定了基础。
8、以下是 xc_user_address 数据表的字段列表：id：BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY（主键，自增） user_id：BIGINT UNSIGNED（用户 UID，外键） name：VARCHAR(30)（收货人姓名，最长 10 个中文字符） phone：VARBINARY(255)（收件人手机号/电话，存储时加密） province：VARCHAR(50)（省份） city：VARCHAR(50)（城市） county：VARCHAR(50)（区县） detailed_address：VARCHAR(255)（详细地址） remark：TEXT（备注，可选） meta：JSON（扩展字段，JSON 格式） time：TIMESTAMP DEFAULT CURRENT_TIMESTAMP（创建时间） updated_time：TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP（更新时间） default：TINYINT(1) DEFAULT 0（是否为默认地址）
9、在 xc_user_address 数据表中新增了三个字段索引，以优化查询效率并提升系统性能。首先，添加了 id 作为主键索引，由于大部分查询场景都是基于 id 进行记录定位，因此该索引至关重要，并且具有唯一性。其次，为 user_id 字段创建索引，当用户打开收货地址管理页面时，系统会通过 user_id 读取该用户的所有地址列表，因此该索引有助于提高查询速度。最后，针对 default 字段增加索引，在用户下单时，系统会自动选中默认收货地址，只有在用户需要更改地址时才会进入收货列表页进行切换，因此该索引能够加快默认地址的读取速度，优化用户体验。
10、统一订单查询接口新增了 xc_query_user_address 方法，该方法需要传递 ID 作为主键值。在内部实现上，它会构建一个 wpdb 查询语句，检索 xc_user_address 数据表中与该 ID 对应的记录。如果查询结果为空，则返回 false；如果存在匹配记录，则使用 ARRAY_A 将其转换为数组，并通过 get_row 获取单行数据，最终直接返回查询结果。该方法是平台唯一用于查询收货地址的接口，专门用于基于 ID 进行精准查询，旨在减少 SQL 语句的二次封装处理。如果需要获取用户的全部收货地址列表，则需使用其他专门的方法进行处理。
11、在 xc_query_user_address 方法中新增了 uncache 变量参数，默认值设为 false（即启用缓存）。当缓存启用时，系统会构建键名 query_user_address:$id，并通过 get_redis_meta 进行缓存查询。如果缓存中存在数据，则直接返回缓存内容；如果缓存数据不存在或禁用了缓存查询，则会使用 wpdb 构建 SQL 查询语句，获取数据后直接返回。在返回数据之前，查询结果会被存入 Redis，以便下次查询时可以直接从缓存中读取最新数据。需要特别注意缓存的更新机制，以防止数据不一致的问题。此外，缓存的最大有效期设定为 24 小时，超过该时间后，缓存数据将自动清理。

2025年3月11日
1、快递号数据表新增两个时间戳字段：created_at：记录物流信息建立时间。updated_at：记录更新的时间。这两个字段有助于跟踪物流数据的变更历史。同时通过idx_code建立索引机制，将以下键位加入其中。1、idx_code (code)：加速通过 code（快递单号）查询物流信息的速度。2、idx_user_id (user_id)：加速查询某个用户的所有物流记录。3、idx_recipient (recipient)：加速查询某个收件人的所有物流记录。4、idx_shop_id (shop_id)：加速查询某个订单的物流信息。注：索引可以让数据库更快地找到匹配的数据，而不必扫描整个表。优化 JOIN 操作：如果 user_id、recipient 等字段与其他表有关联，索引可以加速 JOIN 查询。减少磁盘 I/O：索引可以减少数据库在磁盘上读取数据的次数，提高性能。
2、在构建 xc_express_delivery 数据表时，系统会使用 dbDelta 来执行数据库操作。整个流程如下：首先，集成 global $wpdb;，利用 WordPress 提供的 $wpdb 对象进行数据库操作。接着，通过 $wpdb->prefix 获取 WordPress 数据表的前缀，以确保表名符合系统规范。然后，使用 $table_name 拼接完整的表名，结合 $wpdb->get_charset_collate(); 获取数据库的字符集和排序规则，以保证数据存储的兼容性和稳定性。最后，构建 SQL 语句，并创建相应的索引，以优化查询性能并提高数据检索效率。
3、xc_express_delivery 数据表结构参数如下。1、id（主键，自增 ID） 字段数据类型：BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY。 2、type（物流来源类别） 字段数据类型：VARCHAR(50)。 3、shop_id（商品订单的主键 ID） 字段数据类型：BIGINT UNSIGNED。 4、user_id（寄件人的用户唯一标识符） 字段数据类型：BIGINT UNSIGNED。 5、recipient（收件人的用户唯一标识符） 字段数据类型：BIGINT UNSIGNED。 6、name（收件人姓名） 字段数据类型：VARCHAR(100)。 7、phone（收件人手机号） 字段数据类型：VARCHAR(20)。 8、province（收件人所在省份） 字段数据类型：VARCHAR(50)。 9、city（收件人所在城市） 字段数据类型：VARCHAR(50)。 10、county（收件人所在区县） 字段数据类型：VARCHAR(50)。 11、detailed_address（收件人详细地址） 字段数据类型：VARCHAR(255)。 12、address（完整的收件人信息） 字段数据类型：VARCHAR(255)。 13、courier_company（快递公司名称） 字段数据类型：VARCHAR(100)。 14、code（快递单号） 字段数据类型：VARCHAR(50)。 15、code_list（多个快递单号，JSON 格式） 字段数据类型：JSON。 16、time（发货时间） 字段数据类型：DATETIME。 17、status（物流状态） 字段数据类型：VARCHAR(50)。 18、logistics（物流详细信息，JSON 格式） 字段数据类型：JSON。 19、electronic（电子运单信息，JSON 格式） 字段数据类型：JSON。 20、link（订单详情页链接） 字段数据类型：VARCHAR(255)。 21、remark（备注信息） 字段数据类型：TEXT。 22、price（运费） 字段数据类型：DECIMAL(10,2) DEFAULT 0.00。 23、insured（保价金额） 字段数据类型：DECIMAL(10,2) DEFAULT 0.00。 24、meta（自定义字段参数，JSON 格式） 字段数据类型：JSON。 25、created_at（记录创建时间） 字段数据类型：TIMESTAMP DEFAULT CURRENT_TIMESTAMP。 26、updated_at（记录更新时间） 字段数据类型：`TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP。
4、现代化物流追踪数据表结构（xc_express_delivery）的构建已顺利完成，该表将作为平台物流管理的核心，全面支持物流追踪与管理功能。其设计涵盖远程下单、扫码自动识别、单号全程追踪、物流状态查询、入库管理等关键环节，确保物流信息的高效流转与精准追踪。鉴于整个宫论系统涉及实物交易，无论是官方拍卖还是用户间的交易，均需依赖稳定可靠的快递物流体系。因此，该表的建立不仅提升了物流管理的智能化水平，也为交易的可追溯性提供了有力保障，确保用户能够实时掌握物流动态，提升整体交易体验。
5、新增了后台配置页面 configure/express.php，用于处理宫论物流快递的相关参数配置。在该页面中，可以对部分快递公司的参数选项、网上电子面单接口信息、物流追踪接口以及页面访问权限等内容进行配置。该页面的图标标识为 fa-truck，并通过 require_once 方式引入，注：只要是涉及物流单号的处理，相关接口或参数配置都必须在这个页面处理，方便维护和管理。
6、为了更高效地管理各个快递公司，后台在物流管理页面新增了一个字段：xc_express_company_config。该字段用于配置快递公司的相关参数，具体如下：name（快递公司名称）：例如“京东快递”，该名称将在物流发货页面以下拉选项的方式展示，方便用户选择。key（系统唯一标识）：该字段用于唯一标识快递公司，一旦设定不可修改，通常采用英文格式（如“JD”）。建议对标主流接口平台（如快递鸟、快递100）提供的参数信息，以便于系统管理和维护。该标识主要用于两个方面：一是统计物流运输数据，二是进行远程下单接口的集成管理。number（可选参数，数字编号）：该字段用于内部管理，便于系统对快递公司进行分类和识别。
7、针对快递表新增字段 express_key（类型：VARCHAR(20)），用于存储快递公司的唯一标识。在用户通过宫论对订单进行发货操作时，系统会读取 xc_express_company_config 配置信息，并以下拉选项卡的方式展示平台支持的物流公司。当用户选择某个快递公司并填写单号或执行发货操作时，系统将自动获取该快递公司的 key 参数，并存储到 express_key 字段中。该字段的作用是确保系统能够准确识别快递公司，并进行计数器管理和维护。由于物流公司数量众多，单纯依赖快递单号来识别快递公司并不可靠，因此需要使用唯一的身份标识，以便与接口进行交互处理。
8、目前，宫论系统已支持的快递公司包括：韵达速递（YD）、中通快递（ZTO）、顺丰速运（SF）、圆通速递（YTO）、申通快递（STO）、京东快递（JD）、EMS（EMS）、德邦（DBL）、极兔速递（JTSD）以及丹鸟物流（DNWL）。基本覆盖了主流快递服务商，快递公司的标识对照表参考了快递鸟平台的标准。未来，线上官方的发货接口也计划集成快递鸟，以确保对接的规范性和一致性。需要注意的是，如果快递公司不在上述列表中，系统将视其为“其他”选项，用户需手动填写快递公司名称，同时 express_key 字段将被标记为 NULL。
9、在处理寄售回收订单申请时，官方可能会根据不同类别的藏品指定不同的仓库。例如，所有玉器的寄售回收订单可能统一寄往山东的某个仓库，该仓库专门负责玉器的鉴定和验收。而瓷器类藏品则可能统一寄往上海的某个仓库，由当地团队进行验收处理。如果在初期阶段不需要如此精细的分类管理，可以暂时指定一个统一的收货仓库，以简化流程。然而，从系统设计的角度来看，仍然需要支持多仓库的概念，以便未来业务扩展时无需大幅调整。因此，在物流快递配置管理页面新增了一个字段：xc_express_official_config，以支持不同类别藏品的仓库配置需求。
10、xc_express_official_config参数字段结构如下：name：收件仓库的描述信息，例如“山东A区仓库”。key：唯一标识，设定后不可更改，建议使用仓库名称的拼音简写。name：收件人姓名，例如“张文军”。phone：收件人联系电话，例如“136XXXXXXX”。province：收件人所在省份，例如“江西省”。city：收件人所在城市，例如“宜春市”。county：收件人所在区县，例如“万载县”。detailed_address：收件人详细地址，例如“XXXX街道XX小区XX栋”。open：用于控制仓库的启用状态。如果该字段设为关闭状态，则该仓库将不接受任何发货请求。
11、在全局藏品分类配置中，如果开启了寄售或回收功能，将在其下方额外展示一个字段：official_address（官方收货地址），该字段对应的是官方收件信息配置中的 KEY 标识。这一设计使得用户在申请寄售或回收时，平台能够灵活选择藏品寄送的仓库或指定不同的验收人员。例如，玉器寄售可由张某负责签单核验，而瓷器回收则由李某进行签单验收处理。对于大批量收货的情况，合理指派不同的仓库和验收员尤为重要，毕竟并非所有人都精通各个领域。对于不符合要求的藏品，也能及时退回，确保验收流程的专业性和高效性。

2025年3月10日
1、当用户通过xc_hook_consignment_user_cancel_pass_hook发起订单关闭请求时，不会触发push消息通知。此时，系统会专注于完成对信用分的更新，一旦信用分更新完成，服务器便会返回code=0的响应码给前端，标志着该业务钩子服务端的处理流程已完成。由于这是用户主动操作的关闭事件，因此无需进行其他方面的通知处理。随着订单回调和信用分更新操作结束，整个流程便正式宣告完成。
2、如果用户需要取消已通过审核的订单，整个处理流程如下：首先，通过xc_hook_consignment_user_cancel_apply_hook_before发起全面拦截操作。所有的拦截步骤都通过此脚本执行，如果条件不满足则返回code=1。这个拦截脚本会进行全面检测，包括用户权限、环境的适用性、订单状态等多方面的处理。接下来，通过xc_query_consignment获取订单的当前状态，并利用xc_update_sql更新订单信息，具体涉及到更新status状态和time_summary这两个字段。随后，使用xc_consignment_status_hook进行缓存更新，确保在订单取消后，缓存数据能够被正确清理。接着，利用xc_score_status_hook更新用户的信用分数，根据后台配置，对于用户主动取消的订单，会有相应的信用分处理机制。通过hook_after发起回调操作，允许外部系统通过注册的方法接收到此订单的关闭信息。最后，返回给前端code=0和msg=取消订单成功，确认订单取消成功并通知用户。
3、在前端处理服务端返回的响应结果时，会根据不同的状态码执行相应的业务逻辑。当code=1（订单取消失败）时，系统会通过xc_msg弹出具体的错误原因，同时阻止后续操作的继续执行，确保错误得以及时提示。然而，当code=0（订单处理成功）时，会启动callback回调脚本，这一过程中，通过callback进行页面的互动处理，以便更新用户界面。同时，无论请求成功还是失败，系统都会依赖complete回调，确保在任意情况下都能通过xc_loading_hide关闭加载提示框，以避免出现页面无响应的“死亡圈圈”现象，提高用户体验的流畅性。
4、为满足日益复杂的业务需求，新增了一个名为“xc_express_delivery”的快递物流信息数据表。此表将全面记录各类物流信息，包括平台发出、卖家寄出、买家售后退回以及用户资料文件邮寄等。新数据表的设计基于现代化物流标准结构，确保其能够适应不同情境下的信息管理需求。为提升使用效率，该表增加了多项便捷功能：一键查询能够快速获取物流信息，扫码一键入库功能（寄售回收藏品，后续将支持PDA设备扫码）简化了物品入库流程，扫运单即可一键跳转订单详情页，方便用户查看相关信息。此前曾建立过类似的数据表，但由于信息参数设置不够完善，未能有效支持复杂业务场景，因此此次改进势在必行，旨在更好地服务于多样化的物流管理需求。
5、在xc_express_delivery数据表的字段设计中，具体定义如下：首先，id字段作为唯一主键，用于标识每条记录的唯一性。type字段用于记录物流的来源类别，示例值包括“tao”表示淘货交易的商品，“consignment”代表寄售到收藏品，从而实现对物流场景的分类。shop_id则用于存储商品订单的主键，相较于直接使用“order”名称而言，采用更为规范的主键ID更为合适。user_id是寄件人的用户唯一标识符，而recipient则表示收件人的用户唯一标识符。在address字段中，完整的收件人信息得以记录，包括收件人的姓名、详细的省市区地址以及联系电话等。courier_company字段则用中文记录选择的快递公司，如“京东快递”、“京东物流”或者“顺丰快递”。code字段表示快递单号，是物流追踪的重要信息。time字段用于记录发货时间，这里指的是快递发出的时间，而非上门揽收的时间。status字段用于反映物流状态，系统会通过接口进行定期检查快递单号，并根据物流跟踪信息更新其状态，从而确保物流信息的准确性，杜绝虚假发货的发生。最后，logistics字段以JSON格式存储详细的物流信息，包括运输轨迹以及签收记录等，这样做有助于提供详尽的物流动态信息，便于查询与追踪。
6、在xc_express_delivery数据表中，新增了6个重要字段，以更好地支持系统对接第三方下单接口平台，并提升信息管理效率。新增字段如下：1、name：记录收件人的姓名，方便联系和确认身份。2、phone：记录收件人的手机号，便于及时沟通和查询。3、province：用于存储收件人所在的省份信息，便于区域管理。4、city：详细记录收件人所在的城市，利于快递路线优化。5、county：明确收件人所在的区县，以提高投递精准度。6、detailed_address：这是一个可手动输入的字段，用于详细记录收件人的住址，如“XXX路XX小区X栋X单元”，确保快递人员能够准确找到收件地点。通过将收件人的详细信息分离成独立字段，可以更好地适应各种系统交互需求，实现电子面单的生成及配送流程的自动化处理，快速接收电子订单并安排上门揽收。
7、为提升用户体验，实现扫码自动跳转至订单详情页的功能，xc_express_delivery数据表新增了一个关键字段：link（页面链接）。在输入快递单号时，系统会自动生成订单详情页的地址，并设置拦截保护以防止非法请求。当用户通过宫论APP扫码操作快递单号时，如果能成功匹配到相关订单，系统将自动跳转至订单详情页。例如，当用户将寄售的收藏品寄往宫论的指定仓库时，仓库管理员可以通过手机或PDA进行扫码，系统会自动识别快递单号对应的订单并跳转至申请详情页。签收时，仓库会对寄出的藏品进行核实，以确保其与平台登记的记录一致。如有不一致的情况，仓库将拒收或采取其他措施处理。此功能大大减少了手动匹配和查找订单的时间，尤其是在处理大量藏品入库时，提高了效率，避免了快递员长时间等待的情况。
8、在极个别情况下，例如订单中的商品支持拆装或附带礼物赠品及需分开邮寄的情境下，用户或卖家可能会同时寄出多个包裹。为应对这种情况，计划在xc_express_delivery数据表中新增一个名为code_list的JSON字段。当包裹数量超过一个时，用户可以填写多个运单号。这些运单号将以JSON格式存储在该字段中。系统在执行快递物流追踪时，会对这些运单号进行遍历检索，以确保每个运单号都能准确追踪其物流状态。此外，在订单详情页上也将支持展示多个运单信息，使用户可以清楚地查看每个包裹的物流情况。
9、在物流单号填写过程中，用户将有机会填写备注信息，此项信息的填写为可选而非必填。一旦用户填写了备注信息，这些内容将被记录在xc_express_delivery数据表的【remark】字段中。在后续的订单详情页和物流单号查询页中，此备注信息将被显示，帮助收件人第一时间了解相关情况。然而需要特别指出的是，备注信息的提供并不保证用户能够看到，关键信息的传达仍然需要通过站内im工具或电话进行确认和沟通。系统只是为今后不同需求的扩展留出了一个信息输入口。
10、在最近的数据更新中，xc_express_delivery表新增了三个重要字段，以提升系统的数据管理与运单信息处理的灵活性。这些字段分别为：price，insured，以及meta。其中，price作为运费字段，目前大多数情况下无法获取到具体运费，因此作为备用字段存在；insured字段用于记录保价金额，默认情况下用户在录入运单号时填写此值，未填写则默认为0。如果是寄给官方的收藏品而未保价，系统将设置此类物品为不可发货状态，以确保物流安全；meta字段采用JSON结构，旨在存储自定义的字段参数，方便对运单进行补充记录以及处理其他附加信息；另外，还有一个新字段electronic，用于记录电子运单信息，它在通过线上电子渠道发货时提供详细的发送记录，以保证发货步骤的准确性和可追溯性。通过这些新字段的引入，数据表在信息记录的全面性和灵活性方面都有了显著提升。
11、xc_express_delivery 数据表的完整字段如下： 主键 id：唯一主键，标识每条记录的唯一性。 基础物流信息 type：物流来源类别（如 tao 表示淘货交易，consignment 代表寄售）。 shop_id：商品订单的主键 ID。 user_id：寄件人的用户唯一标识符。 recipient：收件人的用户唯一标识符。 收件人信息 name：收件人姓名。 phone：收件人手机号。 province：收件人所在省份。 city：收件人所在城市。 county：收件人所在区县。 detailed_address：收件人详细地址（如“XXX路XX小区X栋X单元”）。 address：完整的收件人信息（可能是冗余字段，存储合并后的地址信息）。 快递信息 courier_company：快递公司名称（如“京东快递”、“顺丰快递”）。 code：快递单号。 code_list：JSON 格式存储多个快递单号（用于支持多个包裹）。 time：发货时间（快递发出的时间）。 status：物流状态（系统定期更新）。 logistics：JSON 格式存储详细的物流信息（运输轨迹、签收记录等）。 electronic：电子运单信息（记录线上电子渠道发货的详细信息）。 附加信息 link：订单详情页链接（用于扫码跳转）。 remark：备注信息（用户可选填写）。 price：运费（备用字段，当前大多数情况下无法获取具体运费）。 insured：保价金额（未填写则默认为 0）。 meta：JSON 结构存储自定义字段参数（用于补充记录和附加信息）。

2025年3月7日
1、前端部分新增了一个名为 xc_hook_consignment_user_cancel_pass 的 onclick 事件。当订单成功通过审核时，status_btn 按钮将显示【取消' . $type . '订单申请】。该按钮上的事件绑定就是这个 onclick，允许用户点击按钮触发相应的页面交互操作，从而对已经通过审核的订单进行取消。此取消操作严格限定为用户自身的权限，管理员和审核员均不具备执行该操作的权限。通过此设计，确保用户可以灵活地管理其订单，提供更大的操作自由度和更好的用户体验。
2、在进行取消寄售回收申请（通过审核）操作时，前端会依次执行以下步骤：首先，通过xc.is_login方法验证用户是否已登录。如果用户未登录，则会调用xc_login方法，将页面重定向至登录界面。接下来，使用xc_is_last_page方法检查当前所在页面是否为consignment_order_details，如果不是，则该请求被视为非法，并停止进一步操作。随后，通过page-content.xc_app.consignment_order_details_content锁定页面元素，并从中提取ID参数，这个ID是操作的主键。在提取ID失败的情况下，同样视为非法请求，并停止执行。需要注意的是，为了安全起见，事件处理过程中不会直接传递主键ID，而是在页面中提取。
3、为了加强系统的安全性，如果用户试图取消已经审核通过的寄售订单，系统会启动环境安全监测，以防止非本人操作。具体的前端验证过程如下：首先，通过调用xc_is_security接口进行检查。如果返回值为true，则表明当前环境是安全的，可以继续执行后续操作；如果返回值为false，则表示环境存在安全隐患，此时系统将强制用户进入短信验证页面，并阻止任何后续操作的执行。需要注意的是，无论是前端还是后端，都会进行环境监测，以确保所有请求都是安全和可靠的。
4、为了防止用户误操作，前端在用户发起取消订单申请时，经过安全环境检测后，会弹出一个确认对话框，询问"确定要取消订单申请吗？"。此对话框提供两个按钮选项：首先是“确定”，点击此按钮将触发一个AJAX请求，将订单的ID发送到服务端进行相应的业务处理。其次是“点错了”，点击此按钮则会关闭弹出窗口，并阻止任何后续操作的执行。在AJAX请求发送到服务端时，将利用xc_loading_show显示遮盖层，提示用户当前请求正在处理中，以防止用户误操作或二次点击。当服务端返回处理结果后，会通过xc_loading_hide关闭遮盖层，恢复页面操作。
5、新增了一个名为 xc_hook_consignment_user_cancel_pass_hook 的服务端业务钩子。该钩子需传递唯一参数，即需要处理的订单主键ID值。返回结果采用标准的数组结构设计，其中，code=0 表示订单取消成功，code=1 表示订单取消失败，msg 用于详细描述取消失败的原因。由于可能存在多种失败原因，故可以通过 msg 查看订单操作失败的具体原因。为保持返回结果的统一性，本钩子不设定其他状态的返回。
6、在处理订单申请操作的过程中（已通过审核的订单），系统会依次在HOOK中执行以下检测处理。1、通过xc_is_login获取登录用户UID，如果获取失败则会返回【错误：请登录后再试】，并且返回jump=login，前端会强制打开登录窗口。2、通过is_numeric验证提交的ID参数是否为数字，不为的话返回【错误：参数ID异常错误】。3、通过xc_query_consignment获取订单数据查询结果，拒绝缓存。如果获取失败则返回【错误：订单记录不存在】。4、验证$consignment['user_id']是否与当前用户一致，不一致的情况则返回【错误：你无权进行操作】。5、通过xc_is_security验证环境是否可靠，如果不可靠则返回【设备环境不安全，需要短信验证。】同时返回jump=security，前端将强制跳转到短信验证页面。
7、自从寄售回收订单取消申请功能（审核通过后）引入了hook_before脚本处理机制后，其功能得到了进一步的提升。目前，所有的拦截事件均通过hook_before进行处理。在此基础上，系统还集成了[过滤钩子]的功能，开发人员可以通过add_filter方法轻松接管和执行所需的函数。这种设计使得在无需修改原始代码的情况下，外部开发者可以通过动态注册过滤事件的方式，灵活地加入新的拦截机制进行独立处理。需要特别注意的是，HOOK仅需验证hook_before返回的结果是否为CODE=1，这一数值直接标识请求已被拦截，在此情况下，响应会立即返回，以确保操作的高效和准确。
8、在完成hook_before脚本的拦截处理后，系统会利用xc_query_consignment方法从订单数据表中提取信息，并将查询结果保存至consignment对象。接下来，系统开始构建一个名为update的数组，此数组将作为数据表的更新载体。针对本次订单取消申请，需要对两个字段进行更新。首先是将订单状态字段status更新为3，表示用户主动取消。其次，通过xc_is_json_update方法，将当前取消时间以cancel键的形式添加到time_summary字段中。在完成update数组的构建后，系统将通过xc_update_sql方法对数据表进行相应的更新操作。特别说明，审核前和审核后的订单取消，无论何种情况，状态值均设为3。而要区分订单是在审核前还是审核后被取消的，可以通过检查audit字段的时间记录来进行验证。
9、在使用xc_update_sql更新数据表信息后，处理结果将被存储在update_result中。若返回值为false，这意味着更新操作未能成功，系统将阻止任何后续步骤的执行。此外，失败的情况下会记录错误日志，便于进一步分析和排查问题。然而，当返回值为true时，将进一步调用xc_consignment_status_hook($consignment['id']); 以更新与当前统一订单相关的查询缓存和分页查询缓存。此步骤确保后续操作中调用的数据具有实时性和准确性，保证系统的稳定和信息的可靠传递。
10、用户信用评分系统新增了一个场景，唯一标识为“consignment_user_cancel_pass”，其场景名称为【寄售回收】线上审核通过后用户关闭订单。触发机制设置为1，即每次在相应条件下都会触发，而不是依赖于触发器模式。具体的分数变化为扣减0.4分。扣分原因是用户主动关闭已通过审核的寄售回收订单。这一行为被视为不友好，因此需要对用户的信用分进行适度的惩罚。通知功能已开启，用户将在订单行为发生后收到分数变化的通知。在HOOK钩子执行事件中，如果数据表的写入工作完成，系统将通过调用xc_score_status_hook('user', $user_id, 'consignment_user_cancel_pass', 'consignment', $id)来执行信用分的处罚。这一处罚机制旨在维护系统的公平性和良好的交易环境。
11、在完成了信用分更新后，系统会触发名为hook_after的回调通知脚本。具体的回调函数为xc_hook_consignment_user_cancel_pass_hook_after($consignment['id'])，此函数需要传入用于标识订单的ID主键。内部机制通过xc_do_action方法进行注册，这使得第三方扩展能够在不需要修改源代码的情况下，接收到用户取消订单的相应通知。这一设计为系统的灵活性和可扩展性提供了保障。在处理完回调动作脚本的各项任务后，整个流程随即结束。系统此时会返回结果，其中code为0，表示取消订单成功，并将相应信息通过msg字段反馈给调用方。

2025年3月6日
1、当用户主动取消待审核的寄售回收订单时，信用分的变动将通过回调 hook_after 脚本来触发。此前，这一操作是通过内部的 HOOK 事件来处理的，然而由于 HOOK 通常是在主进程中执行，并未异步转发，可能导致程序运行时出现进程阻塞的风险。将信用分的动作调整为通过回调脚本触发是更为合理的做法，因为 hook_after 脚本本身是以异步方式触发的，从而有效避免了进程阻塞的问题。此外，需注意的是，信用分的触发动作在内部也进行了进程转发的验证处理，确保不会发生循环异步请求的现象。
2、在用户寄售订单详情页（consignment_order_details）中，订单状态处理容器（status_btn）现在将通过$consignment['status']变量来验证订单状态是否为1。如果订单状态的值等于1，这意味着该订单已经通过官方审核。此时页面将显示提示信息【订单已通过官方审核，请尽快寄出藏品】。同时，页面上将出现两个自定义菜单选项：【1、填写寄件信息。2、取消寄售/回收订单】。用户可以通过选择这两个选项之一来决定订单的下一步操作，以便更方便地管理寄售流程。
3、新增信用分配置组场景：唯一标识为consignment_mailing_restrictions的信用分结算场景已上线，适用于【寄售回收】体系下的订单因系统超时关闭的情况。具体的触发机制为：每次此类情况发生，用户的信用分将减少0.5分。结算的原因在于订单在通过审核后，如果超过指定天数（默认为30天，具体可在后台进行配置）仍未发货，系统将自动关闭订单。平台还会在此过程中启用通知功能，确保相关用户及时获知信用分变化。之所以设定这样的时间限制，是因为平台在30天后可能不再接受这些藏品，原因在于平台需求可能会随时间变化进行调整。
4、在通过corn_consignment_mailing_restrictions系统任务发起订单关闭请求时，一旦数据库写入操作成功，系统将主动触发名为xc_score_status_hook的钩子进行信用分的自动处理。传递过程中涉及的变量参数包括：user：用户信用分处理。$consignment['user_id']：寄售回收的订单申请用户，分数将针对这个用户进行处理、consignment_mailing_restrictions：信用分的处理场景，具体的分数变化将通过读取其配置来进行。consignment：分数的订单来源为寄售回收表、$consignment['id']：对应的主键ID参数。
5、任务计划系统顺利关闭超时未处理的寄售回收订单后，将通过调用 xc_consignment_status_hook($consignment['id']) 发起缓存清理更新操作。这一过程确保了统一订单查询的缓存数据得到及时清理，以防范因订单关闭而引起的数据不一致性。特别是在订单关闭时，系统会更新状态字段和时间汇总字段（status 和 time_summary），如果不进行及时的缓存清理，可能会导致订单查询接口和分页查询接口返回的数据之间出现不一致的情况。需要注意的是，只要发生数据表的更新，必须通过 xc_consignment_status_hook 进行统一处理，以确保数据的精确性和一致性。
6、宫论任务系统现已整合hook_afte回调动作脚本，这一新功能大大增强了系统的可扩展性和协调能力。当系统任务、固定任务或主副锁计划成功执行时，系统将自动触发相应的回调脚本，允许第三方组件进行扩展。同时，内部事件也可以通过xc_do_action(FUNCTION, $id, func_get_args());方法来处理结果，确保每个系统任务的处理结果能够有效传递至外部响应。例如，一个预定的系统任务是定时关闭超时订单，在订单成功关闭后，相应的回调会立即被触发。如果当前任务中有10个订单被关闭，那么系统将触发10次回调脚本。这一功能的实现不仅提高了任务管理的效率，还为系统的进一步扩展创造了良好的条件。回调脚本的应用范围广泛，为开发者提供了更加灵活的任务响应机制，助力于更高效的任务处理和结果反馈。
7、在当前的项目开发中，任务系统的hook_afte脚本与HOOK事件的脚本不能通用，主要原因是这两个功能的应用场景存在显著差异，若将其整合到同一脚本中进行维护，无疑会增加复杂性和不便。因此，对于任务系统，采用了独立的回调脚本命名为task_afte。这个脚本位于项目路径function/task_afte.php，并通过require_once引入到项目之中。在具体实现中，task_afte与HOOK的afte的执行原理基本保持一致：二者都是利用xc_do_action方法来传递参数，进而通过注册特定方法来获取并处理最终结果。
8、在寄售回收订单通过审核后，如果长时间未得到响应，系统将通过`corn_consignment_mailing_restrictions`任务接口来发起关闭订单的请求。整个执行流程如下：首先，通过`is_redis_corn`验证订单锁的存在性，如果订单已被锁定，则需要跳过当前处理步骤。接下来，构建`wpdb`语句来进行数据库查询，获取所有符合关闭条件的订单列表，并将查询结果存储在`results`数组中。然后，进入订单的遍历循环，在此过程上锁以保护数据完整性，并进一步确认订单是否具备执行权限。对于不满足条件的订单，将使用`continue`来跳过当前处理。紧接着，利用`xc_update_sql`对数据表执行更新操作。通过`xc_notify_hook`发送消息通知，告知用户其订单状态已发生变化。此外，还将通过`xc_score_status_hook`更新用户的信用评分，以及通过`xc_consignment_status_hook`更新相关缓存记录。最后，通过`corn_consignment_mailing_restrictions_afte`激活回调脚本，完成整套流程。
9、为了确保计划任务的可溯源性，任务系统全面接入宫论日志模式：通过task发起的任务，都将会进行日志记录处理。日志的写入工作通过task_afte回调脚本来完成（该脚本后续所有的任务都会集成，因此是百分百能够触发）。日志的写入方式通过xc_log_error_warn来写入。日志名称为（任务函数名称.log），这样可以清晰知道日志文件的触发来源。日志格式则较为简单:$log = '[执行时间 - ' . date("Y-m-d H:i:s") . '] [订单标识 - ' . $id . '] [任务名称 - 寄售回收订单审核通过后,用户超过XX天仍未寄出藏品，系统关闭计划]'。记录执行时间、执行的订单主键即可。知道任务是否触发过即可，具体溯源通过查找数据表订单详情进行处理。
10、对xc_log_error_warn日志函数进行了重构优化。在此之前，日志文件的路径是通过构建【xc_get_option('xc_log_path') . $key . '.log'】来生成的，所有日志统一存放在后台配置的目录中。然而，随着日志类型的增多和日趋复杂，我们发现有必要支持子目录的处理以便于更好的管理。因此，我们对日志路径的构建方法进行了优化，现在允许key参数传递子目录信息。例如，对于任务执行的日志，若传递的key参数为【task/xxxxxxx】，那么其最终的日志写入路径将变为【日志目录/task/xxxxx.log】。这样的调整能够实现对日志的分类管理，避免大量不同类型的日志混杂在一起，提升查找和管理的便利性。此外，这种变化也方便执行定时清理任务，能够针对特定目录设置日志的每日清理或每周清理计划。
11、宫论定期任务系统执行配置，新增固定计划（每日固定时间执行一次）。任务名称：寄售回收订单审核通过后，用户超过XX天仍未寄出藏品，系统关闭订单计划，执行时间：03:00、异步处理(开启)，采用异步进程来执行这个任务。执行函数：corn_consignment_mailing_restrictions_afte。也就是每天3:00会触发该任务一次，将系统中超时仍未寄出的藏品订单，主动关闭处理。