xiaobaifupan/next/README.md

小白复盘重建版（失败冻结）

禁止部署或继续开发。 本实现已于2026-07-30被用户判定为迁移失败，原发布候选已作废。 冻结原因和后续边界见../docs/migration/next失败冻结记录.md。 本目录以下内容只保留作历史取证，不再代表产品现状或交付状态。

本目录是依据产品规格说明书从零建立的新系统。旧系统只用于行为对照，新系统不得在运行时导入或读取旧系统源码。

本地开发

后端：

cd next
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m uvicorn backend.main:app --host 127.0.0.1 --port 8780 --reload

前端：

cd next\frontend
npm.cmd install
npm.cmd run dev

浏览器访问http://127.0.0.1:5173。开发服务器将/api转发到后端8780端口。

运行配置

配置只从进程环境读取，不在源码或浏览器中保存密钥。基础变量：

• APP_ENV：development、test或production。
• APP_DATA_DIR：持久化数据目录；相对路径以next/为基准。
• APP_DATABASE_PATH：SQLite文件路径，默认位于数据目录。
• APP_LOG_FILE：轮转日志路径；单文件10MB，保留3份。
• APP_LOG_LEVEL：DEBUG、INFO、WARNING、ERROR或CRITICAL。
• APP_HOST、APP_PORT：监听地址和端口；迁移开发端口为8780。
• APP_TIMEZONE：固定为Asia/Shanghai，其他值会拒绝启动。
• APP_ENCRYPTION_KEY：Fernet密钥；生产环境必填。开发环境首次启动时只在数据目录生成本地密钥文件。

数据库维护：

.\.venv\Scripts\python.exe -m tools.database status
.\.venv\Scripts\python.exe -m tools.database upgrade
.\.venv\Scripts\python.exe -m tools.database downgrade --target 0 --confirm-downgrade

回退只允许显式执行；代码回退不会自动回退数据库。

旧库迁移、生产部署与恢复不进入正常运行时代码。迁移只读打开旧库并写入独立目标：

$env:APP_ENCRYPTION_KEY='<现有固定密钥>'
.\.venv\Scripts\python.exe -m tools.legacy_migration `
  --source ..\data\review.db `
  --target data\xiaobai.db `
  --report data\migration-report.json

一致性备份、校验恢复和 Docker 部署见 docs/deployment.md。正式 NAS 容器不会被脚本自动替换，切换必须在最终验收后单独人工确认。

最小质量门禁

cd next
.\.venv\Scripts\python.exe -m ruff check backend tools tests
.\.venv\Scripts\python.exe -m pytest
cd frontend
npm.cmd run check
npm.cmd run test
npm.cmd run build

迁移约束和阶段状态见../docs/migration/重建迁移章程.md。