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

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

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

## 本地开发

后端：

```powershell
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
```

前端：

```powershell
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密钥；生产环境必填。开发环境首次启动时只在数据目录生成本地密钥文件。

数据库维护：

```powershell
.\.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
```

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

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

```powershell
$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](docs/deployment.md)。正式 NAS
容器不会被脚本自动替换，切换必须在最终验收后单独人工确认。

## 最小质量门禁

```powershell
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`。