CapacityReport/docs/project_context.md

项目上下文记录

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/ 均为本地运行或构建产物，不进入版本库。