IT项目外包数据指标要求模版

本文档只是为了留档方便以后工作运维，或者给同事分享文档内容比较简陋命令也不是特别全，不适合小白观看，如有不懂可以私信，上班期间都是在得

记录一下项目外包流程

一、架构要求

（一）分层架构规范

要求四层严格分离，职责界定如下：
└── src/main/java
├── controller # 仅做参数校验、格式转换（DTO <-> VO）
├── service # 业务逻辑层（接口+实现分离）
│ ├── impl # 实现类包
├── common # 数据访问接口定义（仅接口）
│ ├── dto # 服务之间传输对象
│ ├── vo # 服务之间传输对象
│ ├── domain # 实体类对象
└── mapper # MyBatis XML/注解实现（需.分隔与dao同名包）

（二）模块化组织

项目结构必须按业务垂直拆分，示例：
xhao
├── xhao-common # 通用工具包约束：
│ ├── constant # 枚举类（禁止魔法值）
│ ├── util # 工具类（需final修饰+私有构造）
│ └── exception # 自定义异常体系
├── xhao-admin # 后台服务（禁止直接依赖其他业务模块）
└── … # 其他模块

（三）技术选型

技术栈	具体要求
Spring Boot	必须使用2.7.x LTS版本，提供spring-boot-dependencies BOM依赖管理
MySQL	必须使用8以上版本，并且提供数据备份脚本
Redis	需提供缓存Key命名规范（如业务:模块:功能:{参数}）及本地缓存兜底策略
消息队列	需提供消息体Schema定义（Protobuf/JSON Schema）及死信队列处理方案，以及配置文档或配置教程网页链接
JDK	必须使用jdk1.8版本
等等	等等

二、 代码规范

（一）编码硬性规则

接口返回值：统一使用CommonResult包装类，禁止出现Map<String,Object>

public class CommonResult<T> {
    private long code; // 必须使用预定义错误码（如200=成功）
    private String message;
    private T data;
}

分页规范：统一使用PageParam+PageResult对象

public class PageParam {
    private Integer pageNum = 1;  // 页码（从1开始）
    private Integer pageSize = 10;// 每页数量
}

（二）日志规范

// 错误示例：缺乏上下文
log.error("Save order failed"); 

// 正确示例：结构化日志
log.error("订单保存失败 [业务类型={}] [参数={}]", 
    OrderTypeEnum.MALL.getValue(), 
    JsonUtils.toJson(orderRequest));

（三） 接口设计强制要求

方法	URL规范	示例
GET	/api/资源	/api/users/123
POST	/api/资源	/api/orders
PUT	/api/资源	/api/users/123/status
DELETE	/api/资源	/api/products/456

三、注释规范

（一） 注释层级要求

注释类型	要求
类注释	必须包含@author @since @see链接到设计文档
方法注释	使用Swagger @ApiOperation + Javadoc @param @return
复杂逻辑注释	需要详细注释，// NOTE:标注业务规则（如// NOTE: 跨境订单需额外计税逻辑）
数据库字段注释	需在DDL中写注释，并通过MyBatis Generator同步到实体类

（二）文档生成

必须集成Swagger3生成在线API文档
每个接口有请求/响应示例

四、功能流程图

流程图类型要求

图表类型	工具建议	交付格式要求
业务流程图	PlantUML	.puml源码 + PNG导出
系统交互时序图	Mermaid	Markdown内嵌代码
微服务调用拓扑图	C4 Model	draw.io源文件 + PDF矢量图
数据流转图	Draw	draw.io源文件

五、服务清单

（一）服务列表（列如）

用到得服务以下表格模版进行记录

服务名	端口	版本
Mysql	3306	8.02
Redis	6379	7.01
RabbitMQ	5672,15672	V3.9.11

（二） 第三方服务清单

- 短信服务: 
   供应商: 阿里云
   鉴权方式: AK/SK加密
   限流策略: 100 QPS

六、部署文档

（一）环境配置模板

# 启动参数示例
java -jar admin.jar 
--spring.profiles.active=prod 
--server.tomcat.max-threads=200 
--spring.redis.timeout=3000ms

-（二）容器化部署（示例）

# 基础镜像要求
FROM eclipse-temurin:8-jre-alpine

# 安全加固
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

（三） 其他服务部署示例

注：容器化部署要求严格将数据文件、配置文件和日志文件映射到本地系统中。

docker run -d --name XH_RabbitMQ  \
-p 5672:5672 -p 15672:15672  \
-v /home/docker/rabbitmq/data:/var/lib/rabbitmq  \
-- hostname XH_RabbitMQ \
-e  RABBITMQ_DEFAULT_USER=XHao -e RABBITMQ_DEFAULT_PASS=xhao666 \
--log-driver json-file \
--log-opt max-size=100m --log-opt max-file=3 \
rabbitmq:3.9.11

七、数字孪生核心能力要求

（一）虚实映射规范

// 设备实体建模示例（需满足建设方案3.3.4设备管理）
@DigitalTwin(entityType = "EQUIPMENT")
public class DeviceTwin {
    @RealTimeField(source = "deviceId") 
    private String id; // 与物理设备ID严格绑定
    
    @HistoricalField(storage = "HBase")
    private List<SensorData> history; // 历史数据存储
    
    @PredictionField(model = "LSTM")
    private Double tempForecast; // 温度预测值
}

（二）实时同步指标

指标	建设方案对应项	验收标准
数据采集延迟	设备管理 ≤300ms	（99%分位）
指令下发成功率	机器人管理	机器人管理 ≥99.9%
孪生体更新频率	数据仓库	可配置（1s/5s/30s）

八、项目交付物清单

文档类型	内容详情
《API接口文档》	包含Swagger UI链接、Postman Collection文件、每个接口的详细说明
《数据库设计文档》	ER图、表结构SQL脚本、索引优化方案
《部署手册》	云服务器配置步骤（含安全组规则）、Docker Compose部署命令
《应急预案》	常见故障处理流程图（如数据库宕机切换方案）、灾备恢复时间目标（RTO）

写了半天，还不赶紧给我点赞

如果点赞多，评论多会更新详细教程，待补充。