# Map AI Advisor：dev-chen → master 上线流程

目标：mentor 合并 `dev-chen → master` 后，运维在确认的 app 服务器运行一条命令，完成代码、站点迁移、知识索引和管理员入口启用。2026-10-13 准备；未在生产执行。

页面为 https://app.propertylab.com.my/property/research?mode=advisor，菜单 **Analyze Property → AI Advisor**。保留管理员限制。本流程不启用另一套 /property/ai-advisor 通用聊天，不开放会员，不导入或修改共享 master。

知识库后台新增 `/manage/propertylab/knowledge`，供现有 Admin / Super Admin 上传、编辑、审核和发布资料。操作与数据备份说明见 [KNOWLEDGE_ADMIN.md](KNOWLEDGE_ADMIN.md)。部署需包含新增的 `knowledge_drafts`、`knowledge_admin_events` 迁移，并持久化备份 `storage/app/propertylab-knowledge-private/` 私有原文件；上传文件不随 Git 保存。后台同步发布沿用现有 embedding / Qdrant，不增加 queue worker 要求，也不修改知识开关、凭证或取代下述首次生产 rollout 审核。

## 合并前还缺什么

| 必须补齐 | 负责人 | 当前证据与通过标准 |
|---|---|---|
| 生产部署对象 | 运维 | 域名已确认；实际 APP_DIR、APP_USER、当前 SHA、origin、CLI/FPM PHP 8.4、磁盘、备份恢复能力待确认。保留线上已有改动，不直接用旧本地分支覆盖。 |
| G01 Research 实际模型 | 后端 / 运维 | OpenAI available=true 不证明实际模型。提供生效 provider/model/endpoint/路由及关联 Research 的调用证据；预发布真实对话成功。client 模式须确认 Hub 最终模型，不能采用本地默认值。 |
| G02 数据库及 snapshot | 后端 / 运维 | 实际站点写连接及 catalogue 读连接的 DATABASE()/server_uuid、LIVE/COPY 模式、active ready snapshot、manifest/原文件/覆盖证据。部署命令不修复 provider ID、不迁移 master、不镜像数据。 |
| embedding | 后端 / 运维 | 批准的 HTTPS OpenAI-compatible 基地址、密钥、模型、维度、出网权限；支持 dimensions/float 参数。基地址会拼接 /embeddings。代码默认模型不代表公司已批准服务。 |
| Qdrant | 运维 | 批准 URL/API key、持久化存储、备份/恢复和访问范围；支持集合创建、写 points、/points/query。本 PR 不购买或部署服务。 |
| 地图 | 运维 / QA | 有效 MAPBOX_TOKEN 及域名授权；实际地图、引用点击和三项目位置通过浏览器验收。路线服务不是此次必需项。 |
| 试用账号 | QA / 账号负责人 | mentor 及指定试用者有现有管理员账号、可进入 portal、AI funding/credits 可用；使用实际账号走完问答。部署不创建账号、充值或扩大访问。配置检查的 availability(null) 不证明每个账号有额度。 |
| 正式知识包 | mentor / Wai Kit | 6 份资料 / 20 个事实（3 项目、2 区域、12 FAQ）的来源、使用范围、en/zh/ms 翻译获实际审核。review.status=approved，真实 by/at，usageScope=site_answer；保留事实 ID、原文件/来源哈希。materials.draft.json 仍全部为草稿。 |
| Eaton 映射和坐标 | 数据负责人 + mentor | UUID cb9a9534-009e-4f5f-afdc-2aec28459621，候选 39ffdbda759553e8/source46621。有约 9.51km 坐标冲突，必须解决并审核，不能直接批准候选。 |
| MET 1 映射 | 数据负责人 + mentor | UUID 72746902-d409-4a01-bbc9-e77916d27e70，候选 4d47c4df03a21cf1/source46464。source active、LINK、confidence>=90、decided_by 及独立坐标审核仍待确认。 |
| Pavilion Mont Kiara 映射 | 数据负责人 + mentor | UUID 57532f33-fe5a-4db1-8d11-3015e3833c3d。正确 scheme 未确认，不能用 Pavilion Residences 替代。若未覆盖，先走授权数据流程补齐；本命令不造数据或改映射。 |
| 预发布验收报告 | QA + mentor / Wai Kit | 记录代码 SHA、包哈希、snapshot、最终模型、固定检索/30 个真实对话/12 个原 QA、浏览器、并发成本及回滚。缺失原 QA 输入须补齐；pending 不得伪造为 passed。 |
| rollout 批准文件 | mentor / Wai Kit + 运维 | 填 rollout-approval.template.json 的实际值；绑定站点、数据库、snapshot、服务模型、正式包和报告 SHA-256。批准文件是审核记录，不代替测试报告或重新测量模型质量。 |

三个项目都需在批准包中有独立 mappingReview：approved、真实 by/at、coordinatesVerified=true、正确 schemeId，并在实际 catalogue 中有唯一有效 RealtyCheck LINK。命令检查各 scheme 的有效坐标、snapshot value 和至少一条正数价格月度记录。缺少成交或面积口径时继续明确展示缺口，不补猜测。

验收沿用 MVP：16 个正向检索至少 15 个 Hit@5，4 个边界正确；30 个端到端案例和全部 12 个原 QA 按固定标准逐项签字；5 并发检索 P95≤2s、端到端 P95≤15s，记录真实成本及 45s 混合请求预算。部署中的三语言冒烟查询不替代这些验收。

## 运维一次性准备

1. 在生产基线的预发布环境完成真实验收。review 整份发布版本及待执行迁移，备份站点 DB 并验证可恢复，记录当前 SHA/active release。禁止 migrate:fresh 或演示 seed。
2. 将正式包、批准文件、报告放在 Git/部署目录之外的受限路径，例如 /etc/propertylab/advisor/；部署用户可读，普通用户不可写。模板所有 pending/null 都要由实际证据补齐。三个 smokeQueries 的 factId 必须存在于正式包。
3. 在现有服务器配置渠道准备以下值；密钥不提交到 Git 或聊天：

```dotenv
PROPERTYLAB_RESEARCH_ENABLED=true
PROPERTYLAB_KNOWLEDGE_ENABLED=true
AI_ADVISOR_LOCKED=true
PROPERTYLAB_EMBEDDING_BASE_URL=<批准的 HTTPS 基地址>
PROPERTYLAB_EMBEDDING_KEY=<密钥>
PROPERTYLAB_EMBEDDING_MODEL=<批准模型>
PROPERTYLAB_EMBEDDING_DIMENSIONS=<对应维度>
PROPERTYLAB_QDRANT_URL=<批准地址>
PROPERTYLAB_QDRANT_KEY=<密钥>
PROPERTYLAB_ADVISOR_PACKAGE_PATH=/etc/propertylab/advisor/package.approved.json
PROPERTYLAB_ADVISOR_APPROVAL_PATH=/etc/propertylab/advisor/rollout.approved.json
MAPBOX_TOKEN=<现有有效 token>
```

生成凭证沿用现有 AI gateway/global credentials，不新增生成密钥。非 client 模式按 Research 配置 → 有效 pin → provider default 解析；PROPERTYLAB_RESEARCH_MODEL 若显式设置，必须与批准模型一致。client 模式须有已验证的 PROPERTYLAB_GATEWAY_OPENAI_VERIFIED=true 及现有 Hub 配置，不能为过检查伪造 verified。

Research/Knowledge 开关和管理员试用锁是运维预置值，命令不编辑 .env，仓库 Research/Knowledge 默认仍关闭。新版有独立 AI_ADVISOR_LOCKED；必须保持 true，部署拒绝会员开放配置。管理员可访问，Explorer/Heat Map 的锁保持原设置。首次旧代码不识别知识开关；若服务器已有该功能，不要提前刷新配置缓存开启页面，应在维护窗口准备配置。缓存/系统环境覆盖须一致；错误配置拒绝安装。

4. 从已审查 PR 的文件安装启动脚本一次（上传 reviewed 文件即可，无须提前把业务代码合入生产）：

```bash
sudo install -m 0755 /path/to/reviewed/deploy-map-advisor.sh \
  /usr/local/sbin/propertylab-map-advisor-deploy
```

启动器默认 APP_USER=ubuntu，目录默认当前工作目录。使用实际值，不为默认配置创建新用户或修改 DB 权限。它只接受 property-lab/petav3 的 HTTPS/SSH origin，其他格式先由运维核实。服务器需 sudo、git、flock、PHP 8.4、Composer、Node/npm 和现有系统服务。

填批准记录前，用只读命令获取实际值：

```bash
sha256sum /etc/propertylab/advisor/package.approved.json \
  /etc/propertylab/advisor/staging-report.md
```

以下第一条分别在实际站点写连接和 catalogue 读连接执行；第二条只在 catalogue 连接执行，不复制数据库凭证：

```sql
SELECT DATABASE() AS name, @@server_uuid AS serverUuid;
SELECT id, collected_at, coverage_start, coverage_end, manifest_hash
FROM propertylab_snapshots
WHERE is_active = 1 AND status = 'ready';
```

## mentor 合并后的唯一部署命令

在确认的 app checkout 目录执行：

```bash
sudo /usr/local/sbin/propertylab-map-advisor-deploy
```

若目录/用户不同，仍是一条调用：

```bash
sudo env APP_DIR=/actual/app/checkout APP_USER=actual_deploy_user \
  /usr/local/sbin/propertylab-map-advisor-deploy
```

1. 检查 checkout/origin/未提交改动，取得已合并 master SHA，从该 SHA 读取新版 deploy-update.sh。旧服务器不用先 git pull；master 中途变化则退出，避免发布另一 head。
2. 复用部署锁、完整维护模式、代码/依赖更新。只读预检在前端构建/DB 迁移前运行，检查包、批准记录、配置、实际 DB、模型可用配置、snapshot、映射及地图/图表。无 HTTP 或付费模型调用。
3. 复用站点备份、已审核待执行迁移、client+SSR 构建、缓存重建。通用部署会执行**全部 pending migrations**，不限本次知识表；须提前审查。入口不调用 master migration、market import、镜像或 seed。
4. 维护模式内同步导入包，不经过 queue；生成 ready 索引，对 en/zh/ms 各做一次 embedding+Qdrant Hit@5 冒烟。会产生少量真实 embedding 费用，须提前批准服务预算；失败不替换旧 active。
5. 保存上一份 activation 恢复记录再激活；复用 FPM/Horizon/scheduler/SSR 重启，解除维护，执行既有 service-check。成功后管理员进入 Analyze Property → AI Advisor。

没有自动批准、下载资料、创建凭证或修复映射。本入口同步导入，**无需 knowledge-import 常驻 worker**；以后使用默认排队的 knowledge-import 命令仍需监听该队列。

## 预检、故障和回滚

新版本在预发布/服务器已有时，先只读检查：

```bash
php8.4 artisan propertylab:advisor-prepare --check
```

不写知识数据、不激活、不改配置、不调用 embedding/生成模型；缺项返回非零，只显示受控原因或字段名。

导入/语义冒烟失败保留旧 active。后续部署步骤失败，错误处理在回退代码前尝试恢复上一份 activation；首次恢复成无 active。恢复记录在 storage/app/deploy/map-advisor-previous-release.json，不含密钥。若有人另行激活其他 release，恢复拒绝覆盖。

需要手动恢复时先进入维护模式：

```bash
php8.4 artisan down
php8.4 artisan propertylab:advisor-prepare --restore
php8.4 artisan up
```

也可用既有 propertylab:knowledge-release <ready UUID> 切旧知识版本。停用知识问答：设置 PROPERTYLAB_KNOWLEDGE_ENABLED=false、重建缓存、重启 FPM/长驻进程；停用整个页面再设 PROPERTYLAB_RESEARCH_ENABLED=false。停用不删除表、索引或历史引用。

代码/资产回退用既有 deploy-update.sh --rollback；**不会自动撤销 DB 迁移**，不要通用 migrate:rollback 删除整批业务表。恢复失败须人工处理。原 service-check 返回 3 表示代码已部署但服务异常，不自动撤回 activation；应关闭功能并排查服务。

## PR 和交付

固定 dev-chen → master，由 mentor 审核合并。开发提交先整合本地 dev-chen；本次准备不推送、不创建 PR、不执行生产部署。PR 附本流程、缺项状态、真实验收报告入口及自动化检查结果，不能写“线上已启用”。

本地 dev-chen 已保留旧 head 的备份并同步到已核实的 origin/dev-chen d788451728c7536c542eafb3d825b29e8df18a95；本次部署提交 f80689a8a 已整合。工作目录为 /Users/dadadineiyou/Documents/GitHub/petav3-dev-chen-integration。发布前由负责推送的人将该分支推至同名远端，再建 base=master、head=dev-chen 的 PR。

已针对当前 master f3f2d4250243cace34e4e2ada1fe5ff5011dee9f 做实际合并预演，相关 77 个 PHP 测试、75 个前端测试及 client/SSR 构建通过。此时 master 有 84 个独有提交，正式发布包含其业务和迁移；相关回归不代表全仓验收，也不证明线上正在运行该 SHA。完整证据见 VALIDATION.md。mentor 合并前必须完成表中缺项和真实预发布报告；若目标分支再变化，按实际发布版本复核。
