业务服务实现 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

业务服务实现

简介

本文件面向 DouPHP 框架的业务服务层，聚焦产品、订单、用户三大核心域的服务类设计与协作方式。文档说明：

服务类如何以"薄编排门面"组织复杂业务流程，协调多个子服务与模型完成数据读写、状态流转与规则校验。
如何处理业务规则验证、数据转换、展示格式化、跨模块能力开关（features.*）。
事务、异常、日志等横切关注点在服务层的落地方式与最佳实践。
新增：云服务的安全加密机制，包括CredentialCipher AES-256-CBC加密和向后兼容性处理。
新增：云服务错误处理增强机制，包括登录权限检测、安装包验证和多语言错误消息支持。
提供典型业务场景的调用序列图与流程图，帮助读者理解从控制器到服务再到模型的完整链路。

项目结构

DouPHP 将业务服务按领域拆分，并在 core、front、admin 三层分别提供面向不同端的服务入口：

core/service：通用业务服务与基础能力（如订单、用户、定价、内容渲染、安全加密等），不绑定具体前端或后台视图。
front/service：面向前台展示与交互的业务组装（如商品列表、详情构建）。
admin/service：面向后台管理的业务编排（如商品新增、编辑、批量操作、缩略图重建、云服务管理等）。

graph TB
subgraph "核心服务(core)"
BS["BaseService"]
OS["OrderService"]
US["UserService"]
CC["CredentialCipher"]
end
subgraph "前台(front)"
FP["Front ProductService"]
end
subgraph "后台(admin)"
AP["Admin ProductService"]
CS["CloudService"]
IS["InstallService"]
end
FP --> OS
FP --> US
AP --> OS
AP --> US
CS --> CC
CS --> IS
IS --> CC
OS --> BS
US --> BS
CS --> BS
IS --> BS

图表来源

BaseService.php:15-63
OrderService.php:15-79
UserService.php:15-69
ProductService.php（前台）:15-59
ProductService.php（后台）:15-66
CloudService.php:39-61
InstallService.php:720-750
CredentialCipher.php:26-53

核心组件

服务基类 BaseService：定义服务层约定与依赖解析方式（ORM 静态门面、配置、语言、附件、审计等），强调"Model 不入参"，通过静态门面访问数据。
订单服务 OrderService：作为订单域的薄编排门面，组合购物车、状态机、库存守卫、定时任务、结算选项等子服务，对外暴露稳定方法签名。
用户服务 UserService：作为会员域的薄编排门面，组合资料查询、扩展身份、收货联系人、推广关系等子服务，屏蔽 features 开关带来的差异。
前台产品服务 ProductService：负责商品列表与详情页的数据组装，整合定价、Markdown、排序、附件、收藏等能力。
后台产品服务 ProductService：负责商品新增、编辑、删除、批量操作、缩略图重建、型号关联等管理流程，并记录后台审计日志。
新增：云服务 CloudService：负责云端账号管理、扩展订购、版权验证等云端交互功能，集成CredentialCipher进行安全加密，并提供增强的错误处理机制。
新增：安装服务 InstallService：负责云端扩展的安装流程，包含安装包验证、权限检查、多语言错误处理等功能。
新增：凭据加密器 CredentialCipher：提供AES-256-CBC加密解密功能，支持密钥轮换和向后兼容。

章节来源

BaseService.php:15-63
OrderService.php:23-79
UserService.php:23-69
ProductService.php（前台）:35-59
ProductService.php（后台）:38-66
CloudService.php:39-61
InstallService.php:720-750
CredentialCipher.php:26-53

架构总览

服务层采用"薄编排门面 + 主题域子服务"的模式：

门面类只负责参数校验、能力开关判断、子服务编排与结果组装，不直接持有复杂业务细节。
子服务按职责拆分（如购物车装配、状态机、库存守卫、定价计算、Markdown 渲染、安全加密、错误处理等），便于测试与复用。
通过 features.* 配置控制可选模块加载，避免强耦合；未启用时优雅降级返回空/默认值。
ORM 访问统一通过静态门面（Xxx::create/find/update/paginate），减少构造函数注入复杂度。
新增：云服务通过CloudApi网关与云端通信，使用CredentialCipher确保敏感数据安全存储，并通过InstallService提供完整的安装流程和错误处理。

classDiagram
class BaseService
class OrderService {
+getCart(user_id)
+changeStatus(order_sn, new_status)
+checkStock(module, item_id, number)
+autoCancelOrder(where_conditions)
}
class UserService {
+buildUserProfile(row, field)
+isVip(userId)
+contactList(user_id, current_contact_id)
+resolvePromotionLineage(userSn, selfUserId)
}
class Front_ProductService {
+buildProductListData(...)
+buildProductShowData(productId, userId)
}
class Admin_ProductService {
+insert(data, draftToken, adminId)
+update(data, adminId)
+delete(id, data)
+action(data)
}
class CloudService {
+saveCloudAccount(validated)
+loadCloudAccount()
+fetchExtendList(slug, currentGet, localsite)
+resolveInstallDownload(type, cloudId, mode)
}
class InstallService {
+filterTrustedInstallDownloadUrl(url)
+looksLikeZipArchive(binary)
+resolveDownloadFailureMessage()
}
class CredentialCipher {
+encrypt(plaintext)
+decrypt(stored)
+isEncrypted(stored)
+rewrapIfNeeded(stored, maxBytes)
}
OrderService --> BaseService
UserService --> BaseService
Front_ProductService --> BaseService
Admin_ProductService --> BaseService
CloudService --> BaseService
CloudService --> CredentialCipher
InstallService --> BaseService
InstallService --> CredentialCipher

图表来源

BaseService.php:15-63
OrderService.php:23-79
UserService.php:23-69
ProductService.php（前台）:35-59
ProductService.php（后台）:38-66
CloudService.php:39-61
InstallService.php:774-824
CredentialCipher.php:26-53

详细组件分析

订单服务（OrderService）

设计要点
- 薄编排门面：聚合购物车、状态机、条目查询、库存守卫、定时任务、结算选项等子服务，对外保持稳定的方法签名。
- 状态机与付款联动：变更订单状态时触发积分、分销奖励等副作用，支持幂等重跑。
- 库存守卫：下单前校验可售库存，并提供实时库存计算。
- 定时任务：自动评价、售后标记过期清理、超时未支付取消。
- 结算选项：获取启用的支付方式/配送方式插件列表，生成付款剩余时间文案。

关键流程（示例：创建订单号并写入支付方式）

sequenceDiagram
participant C as "控制器"
participant S as "OrderService"
participant ST as "OrderStatusTransition"
participant CO as "OrderCheckoutOptions"
C->>S : createOrderSn(user_sn)
S->>ST : createOrderSn(user_sn)
ST-->>S : order_sn
C->>S : writePayId(order_sn, pay_id)
S->>ST : writePayId(order_sn, pay_id)
ST-->>S : bool
C->>S : getPaymentList()
S->>CO : getPaymentList()
CO-->>S : payment_list
S-->>C : result

图表来源

OrderService.php:122-177
OrderService.php:277-319

关键流程（示例：库存校验）

flowchart TD
Start(["进入 checkStock"]) --> Validate["校验 module/item_id/number"]
Validate --> Guard{"库存是否充足?"}
Guard -- 否 --> ReturnFalse["返回不可下单"]
Guard -- 是 --> ReturnTrue["返回可下单"]
ReturnFalse --> End(["结束"])
ReturnTrue --> End

图表来源

OrderService.php:211-234

章节来源

OrderService.php:23-79
OrderService.php:85-177
OrderService.php:183-234
OrderService.php:240-319

用户服务（UserService）

设计要点
- 薄编排门面：组合资料查询、扩展身份（VIP/工作端/分销）、收货联系人、推广关系等子服务。
- 能力开关：通过 features.* 控制 VIP、分销等模块是否启用，未启用时返回空/默认值。
- 展示型能力：等级名称、当前等级、标准化行格式等由子服务完成。

关键流程（示例：判断 VIP 与工作端身份）

sequenceDiagram
participant C as "控制器"
participant U as "UserService"
participant M as "UserMembershipQuery"
C->>U : isVip(userId)
U->>M : vip(userId)
M-->>U : row|false
U-->>C : bool
C->>U : isWork(userId)
U->>M : work(userId)
M-->>U : row|false
U-->>C : bool

图表来源

UserService.php:135-214

章节来源

UserService.php:23-69
UserService.php:71-214
UserService.php:216-289

前台产品服务（Front ProductService）

设计要点
- 列表页：分类筛选、品牌筛选、归档区间、排序选项、分页、收藏状态、价格格式化、API 字段增强。
- 详情页：商品主体、价格与售价、图库、品牌信息、多语言处理、Markdown 内容渲染、型号列表。
- 属性选择后价格：结合 AttributeService 计算选中属性的价格变化，更新售价与积分。

关键流程（示例：商品列表数据构建）

sequenceDiagram
participant C as "控制器"
participant P as "Front ProductService"
participant Q as "Product Model(AR)"
participant F as "Favorites Module"
participant A as "Attachment"
C->>P : buildProductListData(catId, page, pageSize, brandId, sortBy, sortDir, archive, isApi, userId, allCategories)
P->>Q : with('category')->published()->filterByCategory/Archive()->filterByBrand()->order()->paginate()
Q-->>P : list + pager
P->>F : mapFavoritedIds('product', ids) (条件启用)
P->>A : galleryFirstMap('product', ids)
P-->>C : product_list, pager, sort_list, brand

图表来源

ProductService.php（前台）:61-201

关键流程（示例：商品详情数据构建）

sequenceDiagram
participant C as "控制器"
participant P as "Front ProductService"
participant M as "Product Model"
participant F as "Favorites Module"
participant A as "Attachment"
participant L as "Language"
participant MD as "MarkdownRenderer"
C->>P : buildProductShowData(productId, userId)
P->>M : findPublishedById(productId)
M-->>P : model|null
P->>P : toArray()/formatPrice/salePrice/gallery/brand
P->>F : getFavoritesState('product', productId, uid) (条件启用)
P->>A : galleryFirst('product', productId)
P->>L : langBox(product, 'product', fields)
P->>MD : toHtml(content)
P-->>C : product

图表来源

ProductService.php（前台）:203-258

章节来源

ProductService.php（前台）:61-201
ProductService.php（前台）:203-258
ProductService.php（前台）:260-345

后台产品服务（Admin ProductService）

设计要点
- 列表与表单：分页查询、模板展示字段补齐（分类名、图片、会员价档位等）、默认数据初始化。
- 新增/更新：主图上传、正文远程图片本地化、会员价序列化入库、审计日志记录。
- 删除与批量操作：二次确认、批量改分类、批量删除，均记录审计日志。
- 缩略图重建：逐条生成缩略图并通过 JS 更新进度遮罩。
- 型号关联：维护同 model 字段的关联商品集合。

关键流程（示例：新增商品）

sequenceDiagram
participant C as "控制器"
participant P as "Admin ProductService"
participant M as "Product Model"
participant A as "Attachment"
participant AUD as "Audit"
C->>P : insert(data, draftToken, adminId)
P->>P : levelPrice(level_price) (条件启用)
P->>P : xss/content_remote_image_local -> storeDraftContentImages
P->>M : create(data)
M-->>P : product
P->>A : store('product', id, image, main, options)
A-->>P : image_path
P->>M : update(image)
P->>AUD : writeAdminLog(CREATE, title)
P-->>C : newId

图表来源

ProductService.php（后台）:162-213

关键流程（示例：删除商品）

flowchart TD
Start(["进入 delete"]) --> CheckTitle["读取标题用于提示"]
CheckTitle --> Exists{"存在?"}
Exists -- 否 --> ThrowErr["抛出 DomainException"]
Exists -- 是 --> Confirm{"已确认?"}
Confirm -- 否 --> ReturnCheck["返回二次确认响应"]
Confirm -- 是 --> Audit["记录删除日志"]
Audit --> Destroy["销毁记录"]
Destroy --> ReturnOK["返回成功响应"]

图表来源

ProductService.php（后台）:419-450

章节来源

ProductService.php（后台）:68-119
ProductService.php（后台）:121-213
ProductService.php（后台）:215-294
ProductService.php（后台）:296-343
ProductService.php（后台）:365-417
ProductService.php（后台）:419-485

云服务与安全加密

云服务概述

CloudService 负责豆壳云端账号与订购扩展对接，提供以下核心功能：

云端账号校验与保存：通过 /user/client-check 接口验证邮箱或手机号格式，远程校验通过后保存至配置。
扩展订购客户端 HTML：拉取云端订购页面 HTML，嵌入后台订购弹窗。
扩展列表管理：获取云端扩展资源列表，支持筛选、分页和安装链接生成。
版权授权验证：探测云端版权授权状态，验证域名授权有效性。
安装包下载解析：根据授权状态解析安装包下载地址。

安全加密机制

重要更新：CloudService 现已集成 CredentialCipher 进行增强的安全加密，替代了之前的 MD5 密码存储方式。

加密算法实现

CredentialCipher 使用 AES-256-CBC 对称加密算法，提供以下安全特性：

密钥派生：基于 DOU_APP_KEY 或 DOU_SHELL 常量派生加密密钥
随机IV：每次加密使用随机初始化向量（IV）
消息认证码：使用 HMAC-SHA256 验证数据完整性
前缀标识：加密数据以 enc:v1: 前缀标识，便于识别加密格式

向后兼容性

系统支持新旧两种密码存储格式的无缝切换：

新格式：使用 CredentialCipher 加密的密文（enc:v1: 前缀）
旧格式：保留历史 MD5 值，通过云端宽版验证协议继续工作
自动迁移：在解密失败时自动降级为明文处理，确保系统稳定性

账户管理流程

sequenceDiagram
participant UI as "用户界面"
participant CS as "CloudService"
participant CC as "CredentialCipher"
participant CA as "CloudApi"
UI->>CS : saveCloudAccount(user, password)
CS->>CA : POST /user/client-check (明文密码)
CA-->>CS : valid=true
CS->>CC : encrypt(password)
CC-->>CS : enc : v1 : ...密文
CS->>DB : 保存加密后的cloud_account
CS->>AUDIT : 记录审计日志

图表来源

CloudService.php:173-204
CredentialCipher.php:95-119

账户加载流程

flowchart TD
Start(["loadCloudAccount"]) --> LoadConfig["读取config.cloud_account"]
LoadConfig --> Parse["反序列化为数组"]
Parse --> CheckPassword{"password是否为空?"}
CheckPassword -- 否 --> TryDecrypt["尝试CredentialCipher解密"]
TryDecrypt --> DecryptSuccess{"解密成功?"}
DecryptSuccess -- 是 --> ReturnDecrypted["返回解密后的明文"]
DecryptSuccess -- 否 --> KeepOriginal["保留原始值(MD5或明文)"]
CheckPassword -- 是 --> ReturnEmpty["返回空密码"]
KeepOriginal --> ReturnOriginal["返回原始值"]
ReturnDecrypted --> End(["返回账户信息"])
ReturnOriginal --> End
ReturnEmpty --> End

图表来源

CloudService.php:230-248
CredentialCipher.php:177-192

章节来源

CloudService.php:39-61
CloudService.php:173-204
CloudService.php:230-248
CredentialCipher.php:26-53
CredentialCipher.php:95-119
CredentialCipher.php:177-192
CloudApi.php:30-53

云服务错误处理增强

错误状态映射机制

CloudService 的 resolveInstallDownload 方法实现了完整的云端错误状态映射，支持多种授权失败场景：

错误类型定义

login_required：需要登录云账号才能访问资源
not_purchased：付费扩展尚未购买
vip_required：需要VIP会员权限
vip_expired：VIP会员已过期
unauthorized：版权验证失败
unavailable：云服务不可用或网络错误

错误处理流程

sequenceDiagram
participant CS as "CloudService"
participant CA as "CloudApi"
participant UI as "用户界面"
CS->>CA : POST download/install-resolve
CA-->>CS : envelope(code, message, data)
alt code === 0 && download_url存在
CS-->>UI : status='ok'
else code === 401 || message==='login_required'
CS-->>UI : status='login_required'
else code === 403
alt message==='not_purchased'
CS-->>UI : status='not_purchased'
else message==='vip_required'
CS-->>UI : status='vip_required'
else message==='vip_expired'
CS-->>UI : status='vip_expired'
else
CS-->>UI : status='unauthorized'
end
else
CS-->>UI : status='unavailable'
end

图表来源

CloudService.php:638-680

安装包验证机制

InstallService 实现了严格的安装包验证和安全防护措施：

ZIP格式验证

文件头检测：验证ZIP文件的PK\x03\x04、PK\x05\x06、PK\x07\x08签名
空文件检测：拒绝小于4字节的文件
跨卷签名检测：支持ZIP分卷压缩格式

SSRF防护

URL白名单：仅允许与 cloud.download_base 同scheme/host/port的URL
禁止userinfo：阻止包含用户名密码的URL
协议限制：仅允许http和https协议

错误消息映射

flowchart TD
Start(["downloadFile"]) --> CheckBody["检查响应体"]
CheckBody --> LoginRequired{"body === 'login_required'?"}
LoginRequired -- 是 --> SetDetail1["lastDownloadFailureDetail = 'login_required'"]
LoginRequired -- 否 --> CheckZip{"looksLikeZipArchive(body)?"}
CheckZip -- 否 --> SetDetail2["lastDownloadFailureDetail = 'invalid_package'"]
CheckZip -- 是 --> SaveFile["保存文件"]
SaveFile --> Success["返回文件路径"]
SetDetail1 --> Fail1["返回false"]
SetDetail2 --> Fail2["返回false"]

图表来源

InstallService.php:1285-1292

多语言错误消息支持

系统为云服务错误处理提供了完整的多语言支持：

简体中文错误消息

cloud_down_login_required：当前云账号没有该资源的下载权限
cloud_down_invalid_package：下载内容不是有效的安装包
cloud_install_login_required：请先设置云账号后再下载安装
cloud_install_not_purchased：该付费扩展尚未购买
cloud_install_vip_required：该扩展为 VIP 专享
cloud_install_vip_expired：您的 VIP 已过期

繁体中文错误消息

cloud_down_login_required：目前雲帳號沒有該資源的下載權限
cloud_down_invalid_package：下載內容不是有效的安裝包
cloud_install_login_required：請先設定雲端帳號後再下載安裝
cloud_install_not_purchased：該付費擴充尚未購買
cloud_install_vip_required：該擴充為 VIP 專享
cloud_install_vip_expired：您的 VIP 已過期

错误消息映射机制

flowchart TD
Start(["resolveDownloadFailureMessage"]) --> GetDetail["获取lastDownloadFailureDetail"]
GetDetail --> MapCheck{"detail在映射表中?"}
MapCheck -- 是 --> LangCheck{"lang_has(key)?"}
LangCheck -- 是 --> Translate["lang(key)"]
LangCheck -- 否 --> Default["lang('cloud_down_wrong')"]
MapCheck -- 否 --> Default
Translate --> End(["返回翻译消息"])
Default --> End

图表来源

InstallService.php:1324-1339

章节来源

CloudService.php:620-682
InstallService.php:720-750
InstallService.php:774-824
InstallService.php:1285-1292
InstallService.php:1309-1317
InstallService.php:1324-1339
cloud.lang.php（简体中文）:60-92
cloud.lang.php（繁体中文）:60-92

依赖关系分析

服务间耦合
- OrderService 与 UserService 在 core 层解耦，通过 features.* 控制是否启用相关模块（如分销、VIP），避免强依赖。
- 前台/后台 ProductService 依赖 core 服务（定价、Markdown、附件、配置），但不直接持有复杂业务细节。
- 新增：CloudService 依赖 CredentialCipher 进行安全加密，通过 CloudApi 与云端通信，并通过InstallService提供完整的安装流程。
- 新增：InstallService 依赖 CloudService 进行云端交互，同时提供独立的安装包验证和安全检查功能。
外部依赖
- ORM 静态门面：通过 Xxx::create/find/update/paginate 访问数据，降低构造注入复杂度。
- 附件系统：attachment() 统一管理图片、缩略图、图库与 URL 生成。
- 审计系统：audit()->writeAdminLog 记录后台操作日志。
- 配置系统：Config::get('features.*') 控制功能开关。
- 新增：云服务 API：CloudApi 提供统一的云端通信接口。
- 新增：安全加密：CredentialCipher 提供 AES-256-CBC 加密解密功能。
- 新增：国际化系统：lang() 函数提供多语言错误消息支持。
潜在循环依赖
- 服务层通过薄编排门面与子服务拆分，避免循环依赖；模块能力通过 Module::make 按需解析。

graph LR
OS["OrderService"] --> ST["OrderStatusTransition"]
OS --> SG["OrderStockGuard"]
OS --> OT["OrderScheduledTasks"]
OS --> OC["OrderCheckoutOptions"]
US["UserService"] --> MQ["UserMembershipQuery"]
FP["Front ProductService"] --> PS["PricingService"]
FP --> MR["MarkdownRenderer"]
FP --> AM["Attachment"]
AP["Admin ProductService"] --> AU["Audit"]
AP --> AS["Attachment"]
CS["CloudService"] --> CC["CredentialCipher"]
CS --> CA["CloudApi"]
IS["InstallService"] --> CS
IS --> FS["FileSystem"]
IS --> LANG["Language System"]

图表来源

OrderService.php:23-79
UserService.php:23-69
ProductService.php（前台）:35-59
ProductService.php（后台）:38-66
CloudService.php:39-61
InstallService.php:774-824
CredentialCipher.php:26-53
CloudApi.php:30-53

章节来源

OrderService.php:23-79
UserService.php:23-69
ProductService.php（前台）:35-59
ProductService.php（后台）:38-66
CloudService.php:39-61
InstallService.php:774-824
CredentialCipher.php:26-53
CloudApi.php:30-53

性能考虑

列表查询优化
- 使用 AR 的 with('category') 预加载关联，减少 N+1 查询。
- 分页与字段裁剪：仅选取必要字段，降低数据传输量。
- 归档与分类互斥：避免同时应用冲突的 scope。
资源与缓存
- 附件 URL 生成与缩略图缓存，减少重复计算。
- 收藏状态映射一次性批量查询，避免逐条检查。
- 新增：加密操作缓存：CredentialCipher 实例化开销较大，建议复用实例。
- 新增：错误消息缓存：lang() 函数的翻译结果会被缓存，避免重复翻译。
异步与批处理
- 缩略图重建采用流式输出与 flush，提升长任务体验。
- 定时任务处理自动评价、售后标记清理、超时取消，避免阻塞请求。
- 新增：云端请求超时处理：CloudApi 设置合理的超时时间，避免长时间阻塞。
- 新增：安装包下载验证：在下载阶段就进行ZIP格式验证，避免无效的解压操作。

故障排查指南

常见异常与处理
- 非法参数：当缺少必要参数或参数无效时，抛出领域异常并返回错误页面或消息。
- 记录不存在：删除/更新前校验记录是否存在，不存在则抛出异常。
- 能力未启用：VIP/分销等模块未启用时，返回空/默认值，避免空指针。
- 新增：加密解密失败：CredentialCipher 解密失败时返回空字符串，不影响系统正常运行。
- 新增：云端连接失败：CloudApi 请求失败时返回 null，调用方应提供本地兜底逻辑。
- 新增：安装包验证失败：InstallService 会返回具体的失败原因（login_required、invalid_package等）。
日志与审计
- 后台操作通过 audit()->writeAdminLog 记录增删改行为，便于追踪问题。
- 前台 API 场景可通过日志定位请求上下文与输入参数。
- 新增：云服务操作审计：CloudService 对账户修改、版权验证等操作记录详细审计日志。
- 新增：下载失败追踪：InstallService 通过 lastDownloadFailureDetail 记录详细的下载失败原因。
调试建议
- 开启 features.* 开关逐步验证模块能力。
- 使用 attachment() 与 Config::get 检查资源路径与配置是否正确。
- 对复杂查询使用 with() 预加载与字段裁剪，观察 SQL 执行次数。
- 新增：加密调试：检查 DOU_APP_KEY 和 DOU_SHELL 常量配置是否正确。
- 新增：云端调试：启用 CloudApi 请求日志，检查云端接口响应状态。
- 新增：安装包调试：检查 ZIP 文件头签名和URL白名单配置。
- 新增：多语言调试：确认 lang() 函数能正确加载对应的语言文件。

章节来源

ProductService.php（后台）:162-213
ProductService.php（后台）:215-294
ProductService.php（后台）:419-485
CloudService.php:173-204
CloudService.php:230-248
CloudService.php:638-680
InstallService.php:1285-1292
InstallService.php:1324-1339
CredentialCipher.php:177-192

结论

DouPHP 的业务服务层通过"薄编排门面 + 主题域子服务"的设计，实现了高内聚、低耦合的业务组织方式：

订单、用户、产品等服务清晰划分职责，便于扩展与维护。
通过 features.* 控制能力开关，确保系统在未启用模块时的稳定性。
借助 ORM 静态门面、附件系统、审计系统等基础设施，简化了服务实现复杂度。
新增：云服务集成 CredentialCipher 安全加密，提供企业级的数据安全保护。
新增：向后兼容性设计确保从 MD5 到 AES-256-CBC 的平滑迁移。
新增：云服务错误处理增强机制，提供完整的授权状态映射、安装包验证和多语言错误消息支持。
新增：InstallService 提供严格的ZIP格式验证和SSRF防护，确保云端资源的安全性。
提供了丰富的业务场景流程（列表/详情构建、订单状态变更、库存校验、后台管理、云服务管理等），可作为开发参考。

附录

最佳实践
- 服务方法入参显式化，避免在 Service 中直接读取 Request。
- 写操作优先使用 create/fill/save，读操作使用 with() 预加载与 paginate。
- 复杂查询抽取到 Reader/Query/Core 服务，通过 DI 注入。
- 对外接口保持稳定签名，内部实现可替换。
- 新增：敏感数据必须使用 CredentialCipher 加密存储。
- 新增：云端请求必须处理超时和异常情况，提供本地兜底逻辑。
- 新增：安装包下载必须进行ZIP格式验证和SSRF防护。
- 新增：错误消息必须使用lang()函数进行多语言支持。
代码片段路径（示例）
- 订单状态变更与付款联动：OrderService.php:122-177
- 库存校验流程：OrderService.php:211-234
- 用户 VIP/工作端判断：UserService.php:135-214
- 商品列表数据构建：ProductService.php（前台）:61-201
- 商品详情数据构建：ProductService.php（前台）:203-258
- 后台新增商品：ProductService.php（后台）:162-213
- 后台删除商品：ProductService.php（后台）:419-450
- 新增：云服务账户保存：CloudService.php:173-204
- 新增：云服务账户加载：CloudService.php:230-248
- 新增：云服务错误处理：CloudService.php:638-680
- 新增：安装包URL过滤：InstallService.php:774-824
- 新增：ZIP格式验证：InstallService.php:1309-1317
- 新增：错误消息映射：InstallService.php:1324-1339
- 新增：凭据加密实现：CredentialCipher.php:95-119
- 新增：凭据解密实现：CredentialCipher.php:177-192

添加日期：2026-10-05