服务管理开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中服务管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导服务管理模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
服务套餐	系统提供的各种增值服务组合
电子面单	在线生成的快递单模板
短信服务	用于发送验证码、通知等短信的服务
商品复制	从其他平台复制商品信息到本地系统的服务
小票打印	打印订单小票的服务
电子发票	在线生成和管理电子发票的服务
Access Token	服务API的认证令牌

2. 核心功能模块

2.1 服务开通与管理

服务套餐管理：查看和购买各种服务套餐
服务开通：开通和配置各种服务
服务状态管理：查看和管理已开通服务的状态
服务配置管理：配置服务的各项参数

2.2 消费记录管理

消费记录查询：按类型、时间等条件查询消费记录
消费统计：统计各项服务的消费情况
消费详情：查看消费记录的详细信息

2.3 用户信息管理

服务平台登录：登录服务管理平台
用户信息获取：获取服务平台用户信息
密码修改：修改服务平台登录密码
手机号修改：修改绑定的手机号

2.4 短信服务管理

短信服务开通：开通短信服务
短信模板管理：申请和管理短信模板
签名修改：修改短信签名
短信发送配置：配置短信发送参数

2.5 电子面单服务

电子面单开通：开通电子面单服务
电子面单配置：配置电子面单参数
电子面单生成：生成电子面单
电子面单模板管理：管理电子面单模板

2.6 商品复制服务

商品复制开通：开通商品复制服务
商品复制配置：配置商品复制参数
商品复制操作：从其他平台复制商品信息

2.7 小票打印服务

小票打印开通：开通小票打印服务
小票打印配置：配置小票打印参数
小票模板管理：管理小票打印模板

2.8 电子发票服务

电子发票开通：开通电子发票服务
电子发票配置：配置电子发票参数
电子发票生成：生成电子发票
电子发票管理：管理电子发票记录

3. 代码结构与设计

3.1 架构设计

系统采用分层架构设计，严格遵循MVC设计模式，并采用驱动模式支持多种服务提供商：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Routes      │────▶│   Controllers   │────▶│    Services     │────▶│    Storage      │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        ▲                      ▲                      ▲                      ▲
        │                      │                      │                      │
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Request &      │     │   FormBuilder   │     │ BaseManager     │     │ External APIs   │
│   Response      │     └─────────────────┘     └─────────────────┘     └─────────────────┘
└─────────────────┘

3.2 核心文件结构

3.2.1 路由配置

服务路由：crmeb/app/adminapi/route/serve.php

包含服务管理相关的所有API路由
模块化设计：平台登录、电子面单、用户信息、支付套餐、短信服务、消费记录等

3.2.2 控制器层（Controller）

服务控制器：crmeb/app/adminapi/controller/v1/serve/

Serve.php - 核心服务控制器，处理服务套餐、支付、开通、记录查询等功能
Export.php - 处理电子面单相关功能
Sms.php - 处理短信服务相关功能
Login.php - 处理服务平台登录相关功能

3.2.3 服务层（Services）

服务管理Services：crmeb/app/services/serve/

ServeServices.php - 核心服务管理服务，提供服务实例化方法
- sms()：短信服务
- copy()：商品复制服务
- express()：电子面单服务
- orderPrint()：小票打印服务
- user()：用户服务
- invoice()：电子发票服务

3.2.4 服务管理器

服务管理器：crmeb/crmeb/services/serve/Serve.php

基于BaseManager实现，采用驱动模式设计
支持多种服务驱动，默认使用CRMEB服务
提供服务实例化和管理功能

3.2.5 服务存储层

服务存储：crmeb/crmeb/services/serve/storage/Crmeb.php

与外部服务API交互
获取用户信息
查询用量记录
处理服务开通和配置

3.2.6 认证服务

AccessToken服务：crmeb/app/services/serve/AccessTokenServeService.php

处理服务API的认证和授权
生成和管理Access Token
验证API请求的合法性

4. 数据库设计

4.1 服务套餐表（serve_meal）

字段名	数据类型	描述
id	int(10) unsigned	套餐ID
name	varchar(100)	套餐名称
type	varchar(20)	服务类型
price	decimal(10,2)	套餐价格
description	text	套餐描述
days	int(10)	有效期（天）
status	tinyint(1)	状态（0-关闭，1-开启）
sort	int(10)	排序
add_time	int(10)	添加时间

4.2 服务开通记录表（serve_open）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
uid	int(10)	用户ID
type	varchar(20)	服务类型
status	tinyint(1)	状态（0-未开通，1-已开通，2-已过期）
start_time	int(10)	开始时间
end_time	int(10)	结束时间
add_time	int(10)	添加时间

4.3 服务消费记录表（serve_record）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
uid	int(10)	用户ID
type	varchar(20)	服务类型
money	decimal(10,2)	消费金额
mark	varchar(255)	消费原因
add_time	int(10)	消费时间

4.4 短信模板表（sms_template）

字段名	数据类型	描述
id	int(10) unsigned	模板ID
name	varchar(100)	模板名称
content	text	模板内容
status	tinyint(1)	状态（0-审核中，1-已通过，2-未通过）
add_time	int(10)	添加时间
audit_time	int(10)	审核时间
audit_msg	varchar(255)	审核备注

4.5 电子面单配置表（express_config）

字段名	数据类型	描述
id	int(10) unsigned	配置ID
uid	int(10)	用户ID
company	varchar(50)	快递公司
app_id	varchar(100)	应用ID
app_key	varchar(100)	应用密钥
config	text	其他配置（JSON格式）
status	tinyint(1)	状态（0-未开通，1-已开通）
add_time	int(10)	添加时间

5. API接口说明

5.1 服务套餐管理

5.1.1 获取服务套餐列表

请求URL：/adminapi/v1/serve/meal/list
请求方法：GET
权限要求：serve/meal/list
返回结果：服务套餐列表数据

5.1.2 购买服务套餐

请求URL：/adminapi/v1/serve/meal/buy/{id}
请求方法：POST
权限要求：serve/meal/buy
请求参数：
- pay_type：支付方式
返回结果：支付信息

5.2 服务开通管理

5.2.1 获取已开通服务列表

请求URL：/adminapi/v1/serve/open/list
请求方法：GET
权限要求：serve/open/list
返回结果：已开通服务列表数据

5.2.2 开通服务

请求URL：/adminapi/v1/serve/open/{type}
请求方法：POST
权限要求：serve/open
请求参数：服务配置参数
返回结果：操作结果

5.3 消费记录管理

5.3.1 获取消费记录列表

请求URL：/adminapi/v1/serve/record/list
请求方法：GET
权限要求：serve/record/list
请求参数：
- page：页码
- limit：每页数量
- type：服务类型
- start_time：开始时间
- end_time：结束时间
返回结果：消费记录列表数据

5.4 短信服务管理

5.4.1 获取短信模板列表

请求URL：/adminapi/v1/serve/sms/template/list
请求方法：GET
权限要求：serve/sms/template/list
返回结果：短信模板列表数据

5.4.2 申请短信模板

请求URL：/adminapi/v1/serve/sms/template/apply
请求方法：POST
权限要求：serve/sms/template/apply
请求参数：
- name：模板名称
- content：模板内容
- remark：备注
返回结果：操作结果

5.5 电子面单管理

5.5.1 开通电子面单

请求URL：/adminapi/v1/serve/export/open
请求方法：POST
权限要求：serve/export/open
请求参数：
- company：快递公司
- app_id：应用ID
- app_key：应用密钥
返回结果：操作结果

5.5.2 生成电子面单

请求URL：/adminapi/v1/serve/export/generate
请求方法：POST
权限要求：serve/export/generate
请求参数：
- company：快递公司
- order_id：订单ID
- recipient：收件人信息
- sender：发件人信息
返回结果：电子面单数据

5. 开发规范与流程

5.1 代码规范

命名规范：
- 类名采用大驼峰命名法，如 ServeServices
- 方法名采用小驼峰命名法，如 getMealList
- 变量名采用小驼峰命名法，如 serviceConfig
- 常量名采用全大写，下划线分隔，如 SERVE_TYPE_SMS
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 服务驱动类应继承自BaseManager
API交互：
- 所有外部API请求必须经过AccessTokenServeService认证
- API请求和响应必须使用统一的格式
- 必须处理API请求异常，提供友好的错误提示

5.2 开发流程

需求分析：明确服务管理的功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：按照分层架构编写代码
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试，测试服务与其他模块的交互
性能测试：对API调用进行性能测试
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 API认证问题

问题：API请求认证失败 解决方案：

检查AccessToken是否过期，及时刷新
确保请求参数正确，特别是签名参数
检查服务是否已开通，状态是否正常
检查IP白名单设置（如果有）

6.2 服务开通失败

问题：服务开通或配置失败 解决方案：

检查服务套餐是否有效
确保支付状态正常
检查配置参数是否正确
查看服务日志，定位具体错误

6.3 API请求超时

问题：外部API请求超时 解决方案：

检查网络连接是否正常
优化API请求，减少请求次数
实现请求重试机制，设置合理的超时时间
考虑使用异步请求，避免阻塞主流程

6.4 服务数据同步问题

问题：本地数据与服务平台数据不同步 解决方案：

实现定期同步机制，确保数据一致性
在关键操作后立即同步数据
提供手动同步功能，允许管理员手动触发同步

7. 扩展与定制

7.1 添加新的服务类型

创建服务驱动类：继承BaseManager，实现服务的核心功能
添加服务配置表：为新服务类型创建配置表
实现服务控制器：处理新服务的API请求
添加路由配置：在serve.php中添加新服务的路由
更新服务管理器：在ServeServices中添加新服务的实例化方法

7.2 更换服务提供商

创建新的服务存储类：继承自服务存储基类，实现与新服务提供商的交互
更新服务配置：修改服务配置，切换到新的服务提供商
测试服务功能：确保所有服务功能正常工作

7.3 扩展服务功能

添加新的API接口：在控制器中添加新的方法，实现扩展功能
更新路由配置：添加新接口的路由
实现业务逻辑：在服务层实现新的业务逻辑
更新数据库：如果需要，添加或修改数据库表

8. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含服务开通与管理、消费记录管理、用户信息管理、短信服务管理、电子面单服务、商品复制服务、小票打印服务、电子发票服务等核心功能	AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Routes      │────▶│   Controllers   │────▶│    Services     │────▶│    Storage      │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
        ▲                      ▲                      ▲                      ▲
        │                      │                      │                      │
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Request &      │     │   FormBuilder   │     │ BaseManager     │     │ External APIs   │
│   Response      │     └─────────────────┘     └─────────────────┘     └─────────────────┘
└─────────────────┘

9.2 服务开通流程图

服务开通流程：
1. 用户选择服务套餐
2. 系统生成服务订单
3. 用户支付订单
4. 支付成功后，系统调用服务API开通服务
5. 系统更新服务状态
6. 系统记录消费记录
7. 发送服务开通通知给用户

9.3 API请求流程图

API请求流程：
1. 客户端发起API请求
2. 服务端验证请求参数
3. AccessTokenServeService验证AccessToken
4. 服务控制器处理请求
5. 服务层调用相应的服务驱动
6. 服务驱动调用外部API
7. 外部API返回结果
8. 服务驱动处理结果
9. 服务控制器返回响应给客户端

9.4 服务类型常量

常量	描述
SERVE_TYPE_SMS	短信服务
SERVE_TYPE_COPY	商品复制服务
SERVE_TYPE_EXPRESS	电子面单服务
SERVE_TYPE_ORDER_PRINT	小票打印服务
SERVE_TYPE_INVOICE	电子发票服务

提示：该文档由AI生成，仅供参考。

服务管理开发文档.md 16 KB History Raw