# 开发技术规范文档

> 本规范文档适用于技术团队及新引入技术的项目落地，目标是规范化公司技术选型、架构设计、开发流程，提升质量与效率，降低技术风险。

---

## 📌 一、前言

### 目标与背景
规范化公司技术选型、架构设计、开发流程，提升质量与效率，降低技术风险。

### 适用范围
适用于技术团队及新引入技术的项目落地。

---

## 🧱 二、技术栈选型与架构概览

### 2.1 技术体系结构图
平台整体架构图， Web 层、服务层、硬件接口层、中间件层、存储层、第三方接入等模块交互与部署方式。

### 2.2 技术选型说明

| 模块 | 技术选型                                                               | 说明 |
|------|--------------------------------------------------------------------|------|
| Web 框架 | PHP + Swoole + Hyperf                                              | 高并发、协程模型，用于高性能后端服务 |
| 硬件上位机开发 | C# + C++                                                           | C# 用于可视化控制界面，C++ 用于底层驱动与 TCP 通信模块 |
| 前端框架 | Vue 3.x + TypeScript/JavaScript + Vuex + Vue Router + Element Plus | 前端开发栈，响应式与组件化开发 |
| 对外接口 | RESTful API                                                        | 标准化输出格式，统一鉴权方案 |
| 数据库 | MySQL（RDS） + Redis（缓存+分布式锁）                                        | 用数据库架构 |
| 中间件 | RabbitMQ                                                           | 异步任务队列、事件消息总线 |
| 服务发现与配置中心 | Nacos                                                              | 服务注册发现 + 动态配置中心 |
| 硬件通信 | TCP 服务                                                             | 所有硬件上位机通过统一 TCP 服务接入，遵循协议解析规范 |

---

## ☁️ 三、云服务与第三方服务使用规范

### 3.1 阿里云资源管理

- **ECS 实例命名规则**：`<环境>-<业务>-<编号>`（如：prod-order-01）
- **资源标签管理**：按业务、环境、负责人分类
- **网络安全组规则**：最小权限原则，仅开放必要端口，需开放端口时，需由技术审批

### 3.2 第三方基础服务

- **阿里短信服务**：统一 SDK、消息模板管理、错误码处理机制
- **e签宝电子签名**：鉴权方式、回调接口、数据可追溯性管理

---

## 💰 四、采购审批流程

- 所有第三方服务需走审批流程：**技术经理 → 总监审批 → 录入内部采购系统**
- 保留完整审批链，评估成本、替代方案与风险
- 采购记录需与采购管理系统对接

---

## 📐 五、系统设计与文档规范

### 5.1 需求分析文档

- 使用统一模板，输出功能描述、用户角色、流程图、非功能性需求等

### 5.2 接口设计规范

- 遵循 RESTful 设计原则
- 使用统一接口文档框架（Apipost）
- 支持自动代码生成、Mock 调试、文档同步更新
- 硬件TCP接口使用统一接口规范，签名验签

### 5.3 架构决策记录

- 流程记录重大技术决策
- 内容包括：背景、讨论、决定等

---

## 🧑‍💻 六、开发规范与代码结构

### 6.1 目录结构（以自动化/MES/生产系统为例）

- 本文基于 Hyperf 官方框架结构，并结合社区最佳实践，逐一说明每个目录/文件的职责与用途。

```text
├── .devcontainer/
├── .github/
├── app/
├── bin/
├── config/
├── migrations/
├── public/
├── runtime/
├── storage/
├── test/
├── .env.example
├── composer.json
├── phpunit.xml.dist
└── ...

```
### 6.2 Hyperf 项目目录结构详解 📁

| **路径**               | **类型** | **功能说明** |
|------------------------|----------|--------------|
| `.devcontainer/`       | 文件夹   | VS Code 容器配置，统一开发环境 |
| `.github/`             | 文件夹   | CI/CD（如 GitHub Actions）、Issue 模板配置 |
| `composer.json`        | 文件     | PHP 包依赖配置 |
| `.env.example`         | 文件     | 环境变量模板，供复制为 `.env` 使用 |
| `phpunit.xml.dist`     | 文件     | PHPUnit 测试配置 |

| **路径**               | **类型** | **功能说明**                     |
|------------------------|----------|------------------------------|
| `app/`                 | 文件夹   | 应用主要业务代码入口，包含以下子模块           |
| `app/Amqp/`            | 文件夹   | AMQP 消息发送/消费任务类              |
| `app/Aspect/`          | 文件夹   | AOP 切面逻辑（如日志、鉴权）             |
| `app/Command/`         | 文件夹   | CLI 自定义命令脚本                  |
| `app/Constants/`       | 文件夹   | 全局常量定义（状态码、消息类型等）            |
| `app/Context/`         | 文件夹   | 请求上下文管理（如 QID、用户信息）          |
| `app/Controller/`      | 文件夹   | HTTP 接口控制层                   |
| `app/Dao/`             | 文件夹   | 直接数据库访问层封装                   |
| `app/Exception/`       | 文件夹   | 自定义异常类和统一逻辑                  |
| `app/Helpers/`         | 文件夹   | 通用工具函数                       |
| `app/Job/`             | 文件夹   | 定时任务或队列任务执行类                 |
| `app/JsonRpc/`         | 文件夹   | JSON-RPC 接口，供硬件或外部调用         |
| `app/Listener/`        | 文件夹   | 事件监听器与触发机制                   |
| `app/Log/`             | 文件夹   | 日志入口、格式化、QID 链路              |
| `app/Middleware/`      | 文件夹   | HTTP/MQ 中间件（限流、鉴权、异常处理）      |
| `app/Model/`           | 文件夹   | ORM 映射层，对应数据库表               |
| `app/Process/`         | 文件夹   | 自定义进程（如 Socket、守护进程）         |
| `app/Repository/`      | 文件夹   | Repository 或 DAO 层，封装 Model 调用 |
| `app/Request/`         | 文件夹   | 接口参数验证对象                     |
| `app/Scope/`           | 文件夹   | Eloquent 范畴定义（global/local）  |
| `app/Service/`         | 文件夹   | 业务逻辑层        |
| `app/Task/`            | 文件夹   | 异步任务，配合 Scheduler 使用         |
| `app/Utils/`           | 文件夹   | 独立于业务的工具逻辑封装                 |

- 代码调用层级：Controller → Repository → Dao → Service → Model
- Repository 不直接操作 DB，由 Dao 统一调用 Model

### 6.3 命名与依赖注入

- 类命名：以 `Repository`, `Dao`, `Service`, `Controller`, `Model`... 后缀命名
- 使用 `@property` 注解实现隐式 DI，提高 IDE 识别与导航

### 6.4 响应与日志规范

- 统一响应出口：`App\Utils`
- 示例代码：

```php
namespace App\Utils;

class Response {
    public function success(array $data = [], string $message = 'Success', int $code = 200): Response
    {
        $result = [
            'code' => $code,
            'message' => $message,
            'data' => $data,
        ];

        return self::jsonResponse($result);
    }

    public function error(string $message, int $code = 0, $data = null): Response
    {
        $result = [
            'code' => $code,
            'message' => $message,
            'data' => $data,
        ];

        return self::jsonResponse($result);
    }
}
```
- 中间件在请求到达 Controller 前生成 qid（唯一请求 ID），写入上下文，日志需携带 qid 用于链路追踪

## 🔨 七、测试策略

- 单元测试：Service 层、关键工具类、协议解析模块覆盖。
- 集成测试：API 接口调试、数据库交互、消息队列流程。
- 性能测试：压力测试脚本（wrk）、Swoole 并发 benchmark。
- 协议连通：硬件 TCP 接口测试工具、模拟场景以及并发测试。

## 🚫 八、安全与合规

- 配置隔离：生产环境用配置中心读取，禁止硬编码。
- 鉴权方式：对外接口通过 OAuth2/JWT + IP 白名单 + 签名方式同网关。
- 硬件接入安全：TCP 接口需做协议签名校验，防重放、防 DOS、防配置漏洞攻击。
- 数据保护：敏感数据如手机号、身份证在数据库存储时采用加密。

## 🎓 九、文档与知识管理

- 所有文档采用 Markdown 管理，统一托管于 Git 仓库。
- 配合 Docsify 等文档生成方案，形成知识库。
- 技术规范等文档均版本化管理、长期维护。

## 🚩 十、组织与流程管控

- 技术规范由 技术总监 起草，由技术团队评审、讨论完善，由总监批准。
- 新技术、新框架、新工具需要流程引入（决策/评审），并记录至技术规范文档。
- 接口或框架调整须形成文档、明确迁移路径、兼容性策略。