初始化

2026-04-02 23:40:04 +08:00
commit 381ea7085d
107 changed files with 11858 additions and 0 deletions
@@ -0,0 +1,73 @@
+# 代码规范
+
+## Python 后端规范
+
+- 遵循 PEP 8 规范
+- 使用 Black 进行代码格式化
+- 使用 isort 进行导入排序
+- 使用类型注解（Type Hints）
+- 异步函数使用 async/await
+- 错误处理使用自定义异常类
+
+**示例**：
+```python
+from typing import List, Optional
+from fastapi import HTTPException
+
+async def get_devices(
+    skip: int = 0,
+    limit: int = 100
+) -> List[Device]:
+    """获取设备列表"""
+    try:
+        devices = await device_service.get_all(skip, limit)
+        return devices
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+```
+
+## Vue 前端规范
+
+- 使用 Composition API（setup script）
+- 组件使用 PascalCase 命名
+- 使用 TypeScript 类型检查
+- 遵循 Vue 官方风格指南
+- 使用 ESLint + Prettier 格式化
+
+**示例**：
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import type { Device } from '@/types'
+
+const devices = ref<Device[]>([])
+
+const fetchDevices = async () => {
+  // 实现逻辑
+}
+
+onMounted(() => {
+  fetchDevices()
+})
+</script>
+```
+
+## Git 提交规范
+
+使用 Conventional Commits 格式：
+```
+<type>(<scope>): <subject>
+
+类型：
+- feat: 新功能
+- fix: 修复bug
+- docs: 文档更新
+- style: 代码格式
+- refactor: 重构
+- test: 测试
+- chore: 构建/工具
+
+示例：
+feat(device): 添加设备导入功能
+fix(auth): 修复登录token过期问题
+```
@@ -0,0 +1,40 @@
+# 架构规则
+
+## 后端架构
+
+### 分层架构
+- **API 层**：仅处理请求/响应，调用 Service
+- **Service 层**：业务逻辑，不直接操作数据库
+- **Model 层**：SQLAlchemy 模型定义
+
+### 目录结构
+```
+app/
+├── api/v1/          # API 路由
+├── services/        # 业务逻辑
+├── models/          # 数据模型
+├── schemas/         # Pydantic 模式
+├── core/            # 核心配置
+├── tasks/           # Celery 任务
+└── utils/           # 工具函数
+```
+
+### 异步任务
+- 耗时操作使用 Celery
+- SSH 状态检查使用异步任务
+- 批量导入使用后台任务
+
+## 前端架构
+
+### 组件分类
+- `components/common/`：通用组件（Layout、Table、Form）
+- `components/business/`：业务组件（Device、User）
+- `views/`：页面组件
+
+### 状态管理
+- 使用 Pinia stores
+- 按模块划分：auth、device、user、system
+
+### API 调用
+- 统一在 `api/` 目录封装
+- 使用 Axios 拦截器处理认证和错误
@@ -0,0 +1,44 @@
+# 安全规则
+
+## 数据安全
+
+- SSH 密码必须加密存储（使用 Fernet 加密）
+- 敏感信息通过环境变量配置
+- 数据库连接使用 SSL
+- 定期备份数据（90天历史记录）
+
+**密码加密示例**：
+```python
+from cryptography.fernet import Fernet
+
+def encrypt_password(password: str, key: bytes) -> str:
+    f = Fernet(key)
+    return f.encrypt(password.encode()).decode()
+
+def decrypt_password(encrypted: str, key: bytes) -> str:
+    f = Fernet(key)
+    return f.decrypt(encrypted.encode()).decode()
+```
+
+## 应用安全
+
+- 所有 API 端点需要认证（除登录接口）
+- 实现 CSRF 保护
+- 输入验证使用 Pydantic
+- SQL 注入防护（使用 ORM）
+- XSS 防护（前端转义）
+- 实现速率限制
+
+## 访问控制
+
+- 基于 RBAC 的权限控制
+- 数据级权限过滤（按区域/学校）
+- 操作审计日志记录
+- 设备信息变更需要审核
+
+**权限级别**：
+- 超级管理员：所有权限
+- 管理员：管理所有设备和用户
+- 区域管理员：管理指定区域的设备
+- 学校管理员：管理指定学校的设备
+- 普通用户：只读权限
@@ -0,0 +1,41 @@
+# 性能规则
+
+## 数据库优化
+
+- 为常用查询字段添加索引（mac_address, region, school_name）
+- 使用连接池（pool_size=20, max_overflow=40）
+- 避免 N+1 查询问题
+- 定期清理历史数据（保留90天）
+- 使用 select_related/joinedload 预加载关联数据
+
+**索引示例**：
+```python
+class ONUDevice(Base):
+    __tablename__ = "onu_devices"
+
+    mac_address = Column(String(17), index=True)
+    region = Column(String(100), index=True)
+    school_name = Column(String(200), index=True)
+```
+
+## 缓存策略
+
+- Redis 缓存热点数据（设备状态）
+- 缓存过期时间：30分钟
+- 手动刷新有5分钟冷却限制
+- 使用缓存键命名规范：`device:status:{device_id}`
+
+## 异步处理
+
+- SSH 状态检查使用 Celery 异步任务
+- 批量导入使用后台任务
+- 定时任务使用 Celery Beat（每30分钟）
+- 分批处理大量设备（每批100个）
+
+## 前端优化
+
+- 组件懒加载
+- 图片懒加载
+- 虚拟滚动（大列表）
+- 防抖和节流
+- 资源压缩和 CDN
@@ -0,0 +1,48 @@
+# 开发规则
+
+## 环境配置
+
+- 开发环境使用 `.env.development`
+- 生产环境使用 `.env.production`
+- 不提交 `.env` 文件到 Git
+- 提供 `.env.example` 模板
+
+**必需环境变量**：
+```bash
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+REDIS_URL=redis://host:6379/0
+CASDOOR_ENDPOINT=https://casdoor.example.com
+CASDOOR_CLIENT_ID=your_client_id
+CASDOOR_CLIENT_SECRET=your_client_secret
+SECRET_KEY=your-secret-key
+```
+
+## 测试要求
+
+- 核心业务逻辑需要单元测试
+- API 端点需要集成测试
+- 测试覆盖率目标：≥80%
+- 使用 pytest（后端）和 vitest（前端）
+
+**测试示例**：
+```python
+def test_device_status_check():
+    device = create_test_device()
+    result = check_device_status(device)
+    assert result.status in ["online", "offline"]
+```
+
+## 文档要求
+
+- API 变更及时更新 Swagger 文档
+- 复杂业务逻辑添加注释
+- 重要配置添加说明
+- 保持 README 和设计文档同步
+
+## 开发流程
+
+1. 创建功能分支：`git checkout -b feature/xxx`
+2. 开发并提交代码
+3. 运行测试：`pytest` / `npm run test`
+4. 提交 PR 并等待审核
+5. 合并到主分支
@@ -0,0 +1,55 @@
+# 部署规则
+
+## Docker 部署
+
+- 使用 Docker Compose 编排
+- 外部 PostgreSQL 和 Redis（不在容器内）
+- 日志挂载到宿主机
+- 使用 Nginx 反向代理
+
+**服务列表**：
+- backend: FastAPI 应用
+- celery-worker: Celery 工作进程
+- celery-beat: Celery 定时任务
+- frontend: Vue 静态文件（Nginx）
+- nginx: 反向代理
+
+## 环境变量
+
+**后端必需配置**：
+```bash
+DATABASE_URL          # PostgreSQL 连接
+REDIS_URL            # Redis 连接
+CASDOOR_*            # Casdoor 认证配置
+SECRET_KEY           # 应用密钥
+SSH_TIMEOUT=30       # SSH 超时时间
+```
+
+**前端必需配置**：
+```bash
+VITE_API_BASE_URL    # 后端 API 地址
+VITE_CASDOOR_*       # Casdoor 前端配置
+```
+
+## 监控告警
+
+- 健康检查端点：`GET /health`
+- 性能指标端点：`GET /metrics`
+- 日志级别：生产环境使用 INFO
+- 日志轮转：10MB 每个文件，保留30天
+
+## 部署流程
+
+1. 配置环境变量（`.env` 文件）
+2. 构建镜像：`docker-compose build`
+3. 启动服务：`docker-compose up -d`
+4. 运行数据库迁移：`docker-compose exec backend alembic upgrade head`
+5. 检查服务状态：`docker-compose ps`
+6. 查看日志：`docker-compose logs -f`
+
+## 备份策略
+
+- 数据库每日自动备份
+- 备份保留30天
+- 重要操作前手动备份
+- 定期测试恢复流程