# 瑞小美系统技术栈标准与字符标准

## 技术栈

### 后端

| 技术 | 版本/说明 |
| --- | --- |
| **语言** | Python 3.11 |
| **框架** | FastAPI |
| **ORM** | SQLAlchemy |
| **数据库** | MySQL 8.0 |
| **认证** | OAuth |

### 前端

| 类别 | 首选技术 | 说明 |
| --- | --- | --- |
| **语言** | TypeScript | 类型安全，提升代码质量 |
| **框架** | Vue 3 | 统一前端框架 |
| **构建工具** | Vite | 快速开发体验 |
| **包管理器** | pnpm | 高效、节省空间 |
| **UI组件库** | Element Plus / Ant Design Vue | 企业级UI |
| **CSS方案** | Tailwind CSS | 可与组件库共存 |
| **HTTP客户端** | Axios | 统一请求库 |
| **状态管理** | Pinia | 按需使用 |
| **代码规范** | ESLint | 必须配置 |

### 前端（特殊场景可选）

| 技术 | 适用场景 |
| --- | --- |
| **qiankun** | 微前端架构整合 |
| **Uni-app** | 小程序/跨平台开发 |
| **Turborepo** | Monorepo管理 |
| **React/Next.js** | 仅用于遗留系统维护 |

### 基础设施

| 技术 | 说明 |
| --- | --- |
| **容器化** | Docker + Docker Compose |
| **反向代理** | Nginx（独立 Docker 容器部署） |
| **网络** | Docker Bridge Network |
| **SSL** | Let's Encrypt (Certbot)，在主机申请后挂载到容器 |

---

## 部署规范

### 基本原则

| 规范 | 说明 |
| --- | --- |
| **容器化部署** | 所有服务必须部署在 Docker 容器中，不可在容器外部署 |
| **前后端分离** | 前后端必须分离部署在不同 Docker 容器中，互相独立、解耦 |
| **服务编排** | 必须使用 Docker Compose 管理多服务与依赖关系 |
| **统一入口** | 必须通过 Nginx 反向代理提供统一入口，后端不直接暴露公网 |
| **热重载** | 开发环境必须启用代码热重载（HMR/auto-reload） |

### Nginx 配置规范

| 规范 | 说明 |
| --- | --- |
| **独立部署** | Nginx 部署在独立 Docker 容器中 |
| **路由转发** | 根据不同子域名转发到对应的 Docker 容器 |
| **SSL 终止** | 仅在 Nginx 层配置 SSL 证书 |
| **端口暴露** | 仅 Nginx 容器暴露 80/443 端口，其他服务端口绑定 127.0.0.1 |

### 镜像源配置

| 类型 | 首选镜像 | 备用镜像 |
| --- | --- | --- |
| **Docker Registry** | 阿里云：`https://kjphlxn2.mirror.aliyuncs.com` | DaoCloud：`https://docker.m.daocloud.io`<br>轩辕镜像：`https://docker.xuanyuan.me` |
| **APT 源** | 阿里云：`http://mirrors.aliyun.com/debian/` | - |
| **通用镜像站** | 阿里云：`https://developer.aliyun.com/mirror` | - |

### 镜像版本规范

| 规范 | 说明 |
| --- | --- |
| **禁用 latest** | ACR 镜像加速器已停止同步 latest 标签 |
| **指定版本号** | 必须使用具体版本号，如 `python:3.11.9-slim` |

### 健康检查

| 规范 | 说明 |
| --- | --- |
| **必须配置** | 所有服务容器必须配置健康检查 |
| **检查端点** | 后端服务应提供 `/health` 或 `/api/health` 端点 |
| **检查间隔** | 建议 30 秒检查一次 |
| **超时设置** | 建议 10 秒超时，3 次重试 |

健康检查配置示例：

```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
```

### 日志管理

| 规范 | 说明 |
| --- | --- |
| **日志格式** | 统一使用 JSON 格式，便于收集分析 |
| **日志轮转** | 必须配置日志轮转，避免磁盘撑满 |
| **日志驱动** | Docker 容器使用 `json-file` 驱动并限制大小 |

日志配置示例：

```yaml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
```

### 资源限制

| 规范 | 说明 |
| --- | --- |
| **内存限制** | 所有容器应设置内存上限，防止单个服务耗尽资源 |
| **CPU 限制** | 根据服务负载合理分配 CPU 配额 |
| **建议配置** | 前端容器 256M-512M，后端容器 512M-1G |

资源限制配置示例：

```yaml
deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M
    reservations:
      cpus: '0.25'
      memory: 128M
```

### 网络隔离

| 规范 | 说明 |
| --- | --- |
| **自定义网络** | 不同项目使用独立 Docker 网络，避免容器间意外通信 |
| **内部通信** | 容器间使用容器名通信，不使用硬编码 IP |
| **网络命名** | 网络名称格式：`项目名_network`，如 `scrm_network` |
| **DNS 刷新** | 后端容器重启后，需执行 `docker exec nginx_proxy nginx -s reload` 刷新 nginx DNS 缓存 |

网络配置示例：

```yaml
networks:
  scrm_network:
    driver: bridge
```

### 敏感信息管理

| 规范 | 说明 |
| --- | --- |
| **禁止硬编码** | 密码、密钥等敏感信息禁止硬编码到代码或镜像中 |
| **环境变量** | 使用环境变量传递配置，通过 `.env` 文件管理 |
| **文件权限** | `.env` 文件权限设置为 600，禁止提交到 Git |
| **生产环境** | 生产环境使用 Docker Secrets 管理敏感数据 |

环境变量配置示例：

```yaml
env_file:
  - .env
environment:
  - DATABASE_URL=${DATABASE_URL}
  - SECRET_KEY=${SECRET_KEY}
```

---

## 字符标准

| 项目 | 标准 |
| --- | --- |
| **字符编码** | UTF-8 |
| **数据库字符集** | utf8mb4 (支持 emoji 表情) |
| **数据库排序规则** | utf8mb4_unicode_ci |
| **API 响应** | JSON (UTF-8 编码) |
| **日期格式** | ISO 8601 (YYYY-MM-DDTHH:mm:ss) |
| **时区** | Asia/Shanghai (UTC+8) |