58 lines
3.4 KiB
Markdown
58 lines
3.4 KiB
Markdown
# 项目上下文记录
|
||
|
||
## 2026-05-15：修复 Windows 启动脚本编码问题
|
||
|
||
- `run.bat` 改为纯 ASCII 输出，并规范为 CRLF 行尾，避免 Windows `cmd` 在 PowerShell 中执行 UTF-8 中文批处理时把提示文本解析成碎片命令。
|
||
- 启动脚本仍使用 `.venv\Scripts\python.exe`、检查 Python 依赖和 `frontend/dist/index.html`，实际启动方式保持 `python -m app.main` 不变。
|
||
- 后续如需中文启动提示，优先放到 PowerShell 脚本或应用日志中，不建议直接写入 `.bat`。
|
||
|
||
## 2026-05-15：后端拆分与前端迁移
|
||
|
||
### 当前架构
|
||
|
||
- 后端入口收敛到 `app/main.py`，只负责创建 FastAPI 应用、注册中间件、注册路由和托管前端构建产物。
|
||
- API 按业务拆分到 `app/api/routers/`：
|
||
- `auth.py`：登录和修改密码。
|
||
- `upload.py`：上传会话和文件上传。
|
||
- `tasks.py`：任务锁、处理启动、处理状态。
|
||
- `history.py`：历史记录、日志和记录删除。
|
||
- `database.py`：数据库测试、表查询、表维护和导出。
|
||
- `config.py`：配置读取、保存、上传和下载。
|
||
- `cache.py`：缓存大小统计。
|
||
- `service.py`：服务状态和重启。
|
||
- `script.py`：SQL 脚本读取、保存和执行。
|
||
- `health.py`：健康检查。
|
||
- 运行时共享状态放在 `app/state.py`，包括配置实例、历史管理器、处理任务、上传会话和全局任务锁。
|
||
- 登录、密码文件和 Token 逻辑放在 `app/auth.py`，继续使用本地 `auth.ini`。
|
||
- 服务重启检测和进程退出逻辑放在 `app/services/runtime.py`。
|
||
- 文件大小等工具函数放在 `app/utils/files.py`。
|
||
|
||
### 前端
|
||
|
||
- 旧 `static/` 原生 HTML/CSS/JS 已替换为 `frontend/`。
|
||
- 前端技术栈为 Vue 3 + TypeScript + Vite + Naive UI。
|
||
- 构建产物位于 `frontend/dist`，由 FastAPI 根路由托管；`/assets` 映射到 `frontend/dist/assets`。
|
||
- 未构建前端时，后端会返回 503，并提示执行 `cd frontend && npm install && npm run build`。
|
||
- Vite 开发服务器将 `/api` 和 `/health` 代理到后端 `http://localhost:9081`。
|
||
|
||
### 部署与运行
|
||
|
||
- Windows 本地运行使用 `run.bat`，优先使用 uv 创建的 `.venv\Scripts\python.exe`。
|
||
- `run.bat` 会检查 Python 依赖和 `frontend/dist/index.html`，缺少前端产物时要求先构建前端。
|
||
- Docker 构建改为多阶段：
|
||
- `node:22-slim` 阶段安装前端依赖并执行 `npm run build`。
|
||
- `python:3.13.11-slim` 阶段安装后端依赖，复制应用代码，再复制前端构建产物。
|
||
- `.dockerignore` 只排除 `frontend/node_modules`、`frontend/dist` 等本地产物，不再排除完整前端源码。
|
||
|
||
### 依赖与清理
|
||
|
||
- Python 依赖保留当前代码实际使用项：`fastapi`、`uvicorn[standard]`、`python-multipart`、`pymysql`、`sqlalchemy`、`cryptography`、`pandas`、`openpyxl`、`chardet`、`supervisor`。
|
||
- 已移除未使用的 `sqlparse`、`aiofiles`、`python-dateutil`。
|
||
- 旧静态目录、根目录打包产物、日志和 Python 编译缓存属于可清理产物，不应提交。
|
||
|
||
### 注意事项
|
||
|
||
- 当前项目按每周整包替换使用，不维护旧版 API 兼容层；但核心处理流程、配置文件和 `ReportScript.sql` 仍沿用现有语义。
|
||
- `ReportScript.sql` 是业务处理链路的一部分，重构接口或前端时不要改写 SQL 语义。
|
||
- `auth.ini`、`cache/`、`dist/`、`frontend/dist/`、`frontend/node_modules/` 均为本地运行或构建产物，不进入版本库。
|