docs: 重写 README，补齐两套后端并行期的配置与启动说明

原 README 停留在「新后端持久层已就绪、业务接口待重构」的阶段，与实际状态脱节。

新增内容：
- 目录结构与两个后端的端口分工（Java 7690 / NestJS 7691）
- 两份 .env 的完整字段，并说明 JWT 密钥必须一致——
  不一致会导致切换或回退时所有人被登出
- 前端如何用环境变量在两个后端之间切换，无需改代码
- Prisma 只作只读映射、禁止执行 migrate 的约束
- 契约比对与业务规则验证工具的用法
- 相关文档索引与当前迁移进度

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

 # 学有为资产后台
 
-## 当前重构状态
+内部资产管理系统。前端 Vue 3，后端正在从 Java Spring Boot 迁移至 TypeScript NestJS。
 
-- 前端已迁入 `frontend/`，开发入口为 Vite。
-- 旧 phone/wechat 后端接口与业务模块已移除。
-- `#/reference/phone` 是不可操作的旧界面参考页，不请求旧 API；`#/reference/wecom` 展示企微账号资产真实列表。
-- 新后端持久层映射 `as_*` 资产表；Service、Controller 与真实资产 API 留待后续重构。
+## 目录结构
 
-## 前端开发
+```
+frontend/       Vue 3 + Vite 前端（不随本次迁移改动）
+backend/        Java 后端（迁移完成后删除，当前作为对拍基准保留）
+backend-nest/   NestJS 后端（迁移目标）
+scripts/contract/   契约录制与比对工具
+docs/           迁移待办与设计记录
+```
+
+迁移期两个后端并行运行：Java 占 **7690**，NestJS 占 **7691**。
+前端默认连 Java，通过环境变量可切到 NestJS，切换与回退都不需要改代码。
+
+## 环境要求
+
+| 项 | 版本 | 说明 |
+|---|---|---|
+| Node.js | >= 20（实测 24） | 前端与 NestJS |
+| MySQL | 8.x | 库名 `xyw_data_test`，表前缀 `as_` |
+| JDK | 17 | 仅迁移期需要，用于跑 Java 后端与对拍 |
+| Maven | 3.8+ | 仅迁移期需要，用于跑 Java 测试 |
+
+## 首次配置
+
+两个后端各需一份 `.env`，都已在 `.gitignore` 中，不会进仓库。
+
+**backend/.env**
+
+```properties
+XYW_DB_URL=jdbc:mysql://127.0.0.1:3306/xyw_data_test?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai&characterEncoding=utf8
+XYW_DB_USERNAME=数据库账号
+XYW_DB_PASSWORD=数据库密码
+XYW_AUTH_JWT_SECRET=至少32位的随机串
+XYW_AUTH_SESSION_HOURS=8
+XYW_AUTH_COOKIE_SECURE=false
+XYW_AUTH_LOGIN_FAILURE_MIN_MILLIS=400
+xyw.device-assets.upload-dir=./uploads/device-assets
+```
+
+**backend-nest/.env**
+
+```properties
+DATABASE_URL="mysql://账号:密码@127.0.0.1:3306/xyw_data_test"
+XYW_AUTH_JWT_SECRET=与 backend/.env 完全相同的那一个
+XYW_AUTH_SESSION_HOURS=8
+XYW_AUTH_COOKIE_SECURE=false
+XYW_AUTH_LOGIN_FAILURE_MIN_MILLIS=400
+XYW_DEVICE_ASSETS_UPLOAD_DIR=./uploads/device-assets
+```
 
-```powershell
+两处 `XYW_AUTH_JWT_SECRET` 必须一致。否则在一个后端登录后切到另一个会被判为未登录，
+切换与回退时所有人都要重新登录。
+
+生成随机密钥：
+
+```bash
+node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+```
+
+## 启动
+
+### 前端
+
+```bash
 cd frontend
 npm install
 npm run dev
 ```
 
-访问：`http://localhost:5173/asset/#/reference/wecom`。
-生产构建仍使用 `/assets/` 基础路径：
+访问 `http://localhost:5173/asset/`。默认连 Java 后端（7690）。
 
-```powershell
-cd frontend
-npm run build
-npm run test:e2e
+连 NestJS 后端时加环境变量：
+
+```bash
+VITE_API_TARGET=http://127.0.0.1:7691 npm run dev
+```
+
+PowerShell：
+
+```bash
+$env:VITE_API_TARGET="http://127.0.0.1:7691"; npm run dev
+```
+
+关掉终端重开即恢复默认，随时可与 Java 对照。
+
+### NestJS 后端（7691）
+
+```bash
+cd backend-nest
+npm install
+npx prisma generate
+npm start
 ```
 
-## 后端编译
+`prisma generate` 只在首次或 `prisma/schema.prisma` 变更后需要执行。
+
+> Prisma 在本项目中**只作只读映射**：schema 由 `npx prisma db pull` 从现有库反向生成。
+> 禁止执行 `prisma migrate` —— Java 后端仍在使用同一套表，改表结构会同时影响两边。
+
+### Java 后端（7690，迁移期保留）
+
+IDE 直接运行 `com.xyw.console.XywConsoleBackendApplication` 即可。
+命令行方式：
 
-```powershell
+```bash
 cd backend
-mvn -q -DskipTests compile
+mvn -DskipTests spring-boot:run
 ```
 
-运行 Maven 前需将 `JAVA_HOME` 配置为可用的 JDK 17 路径。
\ No newline at end of file
+需要先把 `JAVA_HOME` 指向 JDK 17。
+`application.yml` 会同时尝试 `.env` 与 `backend/.env` 两个路径，
+因此从项目根或 `backend/` 启动都能读到配置。
+
+## 测试
+
+```bash
+cd backend-nest && npm test        # NestJS 单元测试
+cd backend && mvn test             # Java 单元测试（迁移期基准）
+cd frontend && npm run test:e2e    # 端到端测试
+```
+
+## 契约比对
+
+迁移期用来确认 NestJS 与 Java 的行为逐字一致。**两个后端需同时运行。**
+
+```bash
+# 全量比对：重放全部端点，差异精确到字段路径
+node scripts/contract/compare.mjs --base http://127.0.0.1:7691
+
+# 只比对某个模块
+node scripts/contract/compare.mjs --base http://127.0.0.1:7691 --filter wecom
+
+# 重新录制基准（改动 Java 后端后需要执行）
+node scripts/contract/record.mjs
+```
+
+业务规则验证（会在测试库写入带 `__contract__` 前缀的数据）：
+
+```bash
+node scripts/contract/wecom-flows.mjs  --base http://127.0.0.1:7691 --no-snapshot   # 企微手机号联动
+node scripts/contract/device-flows.mjs --base http://127.0.0.1:7691 --no-snapshot   # 设备图片上传
+cd backend-nest && node ../scripts/contract/image-compare.mjs                        # 两边缩略图像素比对
+```
+
+## 相关文档
+
+| 文档 | 内容 |
+|---|---|
+| [scripts/contract/CONTRACT-NOTES.md](scripts/contract/CONTRACT-NOTES.md) | 17 条实现要点：时间格式、Cookie 属性、错误文案、事务范围等，是 NestJS 实现的依据 |
+| [docs/migration-backlog.md](docs/migration-backlog.md) | 迁移期有意不做的行为变更，迁移完成后逐项处理 |
+| [DESIGN.md](DESIGN.md) | 界面与交互设计 |
+| [PRODUCT.md](PRODUCT.md) | 产品说明 |
+
+## 迁移进度
+
+```
+契约比对   31/31 端点一致
+单元测试   101 条通过（NestJS）/ 114 条通过（Java）
+已迁移     认证、账号管理、公司档案、公司人员、手机号、企微、设备
+待完成     生产部署配置、切换到 7690、Java 后端下线
+```