chore: 清理无用文件并更新 CLAUDE.md 至 v0.9.0

清理： - 删除含硬编码敏感信息的脚本（run_celery.py, start-celery.sh） - 删除冗余开发脚本（setup.sh, start-backend.sh, start-frontend.sh） - 删除冗余文档（about.md, PROJECT_STRUCTURE.md, QUICKSTART.md, OLT时间同步.md） - 删除调试文件（backend/test_parser.py） - 删除 JWT 密钥文件（backend/token_jwt_key.pem） - .gitignore 添加 *.pem 忽略规则 CLAUDE.md 更新： - 版本号 v0.8.0 → v0.9.0 - 新增 v0.9.0 功能：操作记录日志、OLT时间同步、IMC集成 - 补全 API 端点文档（从5个分类扩展到13个分类、50+端点） - 添加 More 分页标记清理经验教训 - 添加提交前清理文件规则 - 更新项目结构和快速启动指南 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-22 08:57:38 +08:00
parent b5d542a725
commit 3453441754
13 changed files with 132 additions and 876 deletions
@@ -4,8 +4,8 @@

 这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。

-**当前版本**: v0.8.0
-**开发状态**: 核心功能已完成，权限与运维功能完善中
+**当前版本**: v0.9.0
+**开发状态**: 核心功能已完成，运维增强功能持续迭代

 **已实现功能**：
 - ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页、终端控制字符清理）
@@ -18,7 +18,7 @@
 - ✅ OLT 管理（增删改查、批量导入、区域动态同步）
 - ✅ OLT 端口管理（查看端口状态、开关端口）
 - ✅ 重复 MAC 检测与清除
- ✅ 新设备发现与信息补全
+- ✅ 新设备发现与信息补全（扫描发现 → 补全信息 → 入库）
 - ✅ 快速扫描（多线程并发）
 - ✅ 环路检测
 - ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
@@ -26,6 +26,9 @@
 - ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
 - ✅ 审计日志（全量操作记录、筛选查询、CSV 导出）
 - ✅ 设备更换记录（MAC 地址更换历史，与库存序列号联动）
+- ✅ 操作记录日志（查看指定设备的上下线事件历史）
+- ✅ OLT 时间同步（NTP 服务器配置同步到所有 OLT）
+- ✅ IMC 网管服务集成（ONU 远程重启、光功率查询）
 - ✅ iOS PWA 主屏幕支持（standalone 模式 safe area 适配）

 **技术栈**：
@@ -45,15 +48,72 @@
 ### 设备管理
 - `GET /api/devices` - 获取设备列表（分页、筛选）
 - `GET /api/devices/{id}` - 获取设备详情
+- `PUT /api/devices/{id}` - 更新设备信息
+- `GET /api/devices/{id}/events` - 获取设备上下线事件记录
+- `POST /api/devices/{id}/reboot` - 远程重启 ONU（IMC）
+- `GET /api/devices/{id}/optical-power` - 获取 ONU 光功率（IMC）

 ### 状态检查
- `POST /api/check/status` - 手动触发状态检查
+- `POST /api/check/status` - 手动触发全量状态检查（Celery 异步）
+- `GET /api/check/status/{task_id}` - 查询检查任务进度
+- `POST /api/check/scan/{olt_id}` - 扫描单台 OLT（预览，不入库）
+- `POST /api/check/discover/{olt_id}` - 扫描单台 OLT 并入库新设备
+
+### OLT 管理
+- `GET /api/olt/devices` - OLT 设备列表
+- `POST /api/olt/devices` - 新增 OLT
+- `PUT /api/olt/devices/{id}` - 编辑 OLT
+- `DELETE /api/olt/devices/{id}` - 删除 OLT
+- `GET /api/olt/regions` - 获取 OLT 区域列表
+- `POST /api/olt/quick-scan` - 多线程快速扫描所有 OLT
+- `GET /api/olt/ports/{olt_id}` - 获取 OLT 端口状态
+- `POST /api/olt/ports/{olt_id}/toggle` - 开关 OLT 端口
+- `POST /api/olt/sync-ntp` - 同步 NTP 时间服务器配置
+- `POST /api/olt/loopback-detection` - 环路检测
+- `GET /api/olt/new-devices` - 获取新发现设备列表
+- `PUT /api/olt/new-devices/{id}` - 补全新设备信息
+- `DELETE /api/olt/new-devices/{id}` - 忽略新设备

 ### 数据导入
 - `POST /api/import/upload` - 上传并导入 Excel 文件
+- `GET /api/import/template` - 下载导入模板

 ### 统计信息
- `GET /api/stats/summary` - 获取统计摘要（总数、在线、离线）
+- `GET /api/stats/summary` - 获取统计摘要
+- `GET /api/stats/trend` - 7天趋势数据
+- `GET /api/stats/region-distribution` - 区域分布
+
+### 权限管理
+- `GET /api/roles` - 角色列表
+- `POST /api/roles` - 创建角色
+- `PUT /api/roles/{id}` - 编辑角色
+- `DELETE /api/roles/{id}` - 删除角色
+- `GET /api/permissions` - 权限列表
+
+### 用户管理
+- `GET /api/users` - 用户列表
+- `PUT /api/users/{id}` - 编辑用户
+- `DELETE /api/users/{id}` - 删除用户
+
+### 库存管理
+- `GET /api/inventory/materials` - 物料列表
+- `POST /api/inventory/materials` - 新增物料
+- `GET /api/inventory/serial-devices` - 序列号设备
+- `POST /api/inventory/stock-in` - 入库
+- `POST /api/inventory/stock-out` - 出库
+- `POST /api/inventory/check` - 盘点
+
+### 审计日志
+- `GET /api/audit/logs` - 审计日志列表（筛选、分页）
+- `GET /api/audit/logs/export` - 导出审计日志 CSV
+
+### 设备更换记录
+- `GET /api/devices/{id}/replacements` - 查看设备更换历史
+- `GET /api/replacements` - 全量更换记录列表
+
+### 系统设置
+- `GET /api/settings` - 获取系统设置
+- `PUT /api/settings` - 更新系统设置

 ### 系统
 - `GET /health` - 健康检查
@@ -147,11 +207,18 @@

 ### 开发规则

+#### 提交前清理
+- 每次提交前必须清理项目中不需要的文件
+- 包括：测试文件（`test_*.py`）、调试脚本、不再使用的 shell 脚本、冗余 markdown 文档
+- 检查是否有硬编码的敏感信息（密码、密钥、token）
+- 检查 `.gitignore` 是否覆盖了所有不应提交的文件（`*.pem`、`.env`、`__pycache__` 等）
+
 #### 环境配置
 - 开发环境使用 `.env.development`
 - 生产环境使用 `.env.production`
 - 不提交 `.env` 文件到 Git
 - 提供 `.env.example` 模板
+- 敏感信息（数据库密码、Casdoor 密钥等）仅通过环境变量注入

 #### 测试要求
 - 核心业务逻辑需要单元测试
@@ -328,6 +395,21 @@ healthcheck:
  start_period: 40s
 ```

+### More 分页标记清除不能使用 `[^\n]*` 删除整行
+
+**问题**：`_clean_output` 中 `---- More ----[^\n]*` 会将 `---- More ----` 及其后同行所有内容删除。当 OLT 输出的 More 提示与下一页第一条设备数据出现在同一行时（如 `---- More ----\r\r 1484-778f-aa60 ...`），该设备行会被错误丢弃，导致部分设备扫描不到。
+
+**规则**：仅移除 More 标记文本本身，保留同行后续内容：
+```python
+# 错误：删除整行
+output = re.sub(r'---- More ----[^\n]*', '', output)
+
+# 正确：仅移除标记文本
+output = re.sub(r'---- More ----', '', output)
+```
+
+此问题在 OLT `172.16.0.18`（大化县新城初中）上发现：93 台设备仅解析出 90 台，丢失 3 台。
+
 ---

 ## 项目结构
@@ -336,27 +418,32 @@ healthcheck:
 H3ConuMS2/
 ├── backend/              # Python 后端
 │   ├── app/
-│   │   ├── api/         # API 路由
+│   │   ├── api/v1/      # API 路由
 │   │   ├── core/        # 核心配置
+│   │   ├── middleware/  # 中间件（权限、审计）
 │   │   ├── models/      # 数据模型
 │   │   ├── schemas/     # Pydantic 模式
-│   │   ├── services/    # 业务逻辑
-│   │   ├── tasks/       # Celery 任务
-│   │   └── utils/       # 工具函数
+│   │   ├── services/    # 业务逻辑（SSH、IMC、导入等）
+│   │   └── tasks/       # Celery 任务
 │   ├── alembic/         # 数据库迁移
-│   └── tests/           # 测试代码
-├── frontend/            # Vue 前端
+│   ├── scripts/         # 初始化脚本
+│   └── templates/       # Excel 导入模板
+├── frontend/            # Vue 3 前端
 │   └── src/
-│       ├── api/         # API 调用
-│       ├── components/  # 组件
+│       ├── api/         # API 调用封装
+│       ├── components/  # 公共组件
+│       ├── composables/ # 组合式函数
 │       ├── router/      # 路由
-│       ├── stores/      # 状态管理
-│       ├── views/       # 页面
-│       └── utils/       # 工具函数
+│       ├── stores/      # Pinia 状态管理
+│       ├── styles/      # 主题样式
+│       ├── utils/       # 工具函数
+│       └── views/       # 页面组件
 ├── deploy/              # 部署配置
 │   ├── docker-compose.yml
-│   └── nginx.conf
-└── docs/                # 文档
+│   ├── nginx/
+│   └── scripts/
+├── docs/                # 文档
+└── docker-compose.yml   # 主部署文件
 ```

 ---
@@ -393,44 +480,38 @@ H3ConuMS2/

 ### 快速启动

-**后端**：
+**Docker 部署（推荐）**：
 ```bash
+# 1. 配置环境变量
+cp backend/.env.example backend/.env
+# 编辑 .env 填入实际配置
+
+# 2. 启动所有服务
+docker compose up -d
+
+# 3. 初始化数据库
+docker compose exec backend python scripts/init_db.py
+```
+
+**本地开发**：
+```bash
+# 后端
 cd backend
-python -m venv venv
-source venv/bin/activate
+python -m venv venv && source venv/bin/activate
 pip install -r requirements.txt
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-```

-**前端**：
-```bash
+# 前端
 cd frontend
-npm install
-npm run dev
-```
+npm install && npm run dev

-**Celery Worker**：
-```bash
+# Celery Worker
 cd backend
-celery -A app.core.celery_app worker --loglevel=info
-```
+celery -A celery_worker.celery_app worker --loglevel=info

-**Celery Beat**：
-```bash
+# Celery Beat
 cd backend
-celery -A app.core.celery_app beat --loglevel=info
-```
-
-**Docker 部署**：
-```bash
-# 配置环境变量
-cp backend/.env.example backend/.env
-
-# 启动所有服务
-docker-compose up -d
-
-# 初始化数据库
-docker-compose exec backend python scripts/init_db.py
+celery -A celery_worker.celery_app beat --loglevel=info --schedule=/tmp/celerybeat-schedule
 ```

 ### 数据库迁移
@@ -438,7 +519,7 @@ docker-compose exec backend python scripts/init_db.py
 ```bash
 # 创建迁移
 alembic revision --autogenerate -m "描述"
-/home/v6ole/pyproject/H3ConuMS2/CLAUDE.md
+
 # 执行迁移
 alembic upgrade head

@@ -488,8 +569,7 @@ alembic downgrade -1
 - [Vue 3 文档](https://vuejs.org/)
 - [Element Plus 文档](https://element-plus.org/)
 - [Casdoor 文档](https://casdoor.org/)
- [项目详细设计](./系统设计文档.md)
- [开发计划](./开发计划.md)
+- [现场ONU故障排查指南](./docs/现场ONU故障排查指南.md)

 <!-- code-review-graph MCP tools -->
 ## MCP Tools: code-review-graph