小白复盘重建版
本目录是依据产品规格说明书从零建立的新系统。旧系统只用于行为对照，新系统不得在运行时导入或读取旧系统源码。
本地开发
后端：
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。