# Map AI Advisor 知识库管理

本后台管理当前站点的房地产知识资料。发布后沿用现有 `search_property_knowledge` 检索、版本引用和 Map AI Advisor 回答链路；不把草稿直接送入聊天。

代码入口：`/manage/propertylab/knowledge`，Manage 菜单 **Map Advisor Knowledge**；Map AI Advisor 中的 **Manage Advisor knowledge** 也可进入。代码合入不代表线上已部署或已启用。

## 谁可以使用

沿用现有 **Admin / Super Admin** 角色。mentor 或 Wai Kit 使用自己的管理员账号即可；普通会员、agent、staff 仅能进入其他 Manage 页面时，不因此获得知识库权限。页面、写入接口、原文件下载均在服务端检查角色。

审核记录使用当前登录账号的身份和时间。MVP 不新增专门的审核角色，也不强制作者与审核者为两个人；团队可以安排由 mentor 或 Wai Kit 负责最终审核。上传文件中的 `review: approved` 不会变成后台的审核通过记录。

## 上传和准备资料

1. 点击 **Upload source** 上传，或用 **New draft** 手工创建。
2. 在 **Source preview** 核对提取的文字，可下载原文件、打开来源网站。
3. 填写标题、来源网站 URL、可选的生效／失效日期。
4. 每条 **Knowledge item** 对应一个有来源的事实或 FAQ，填写来源页码／章节、原文摘录、检索关键词和 English / Chinese / Malay 三个答案。
5. 保存草稿，再提交审核。

支持格式与限制：

| 格式 | 导入行为 |
|---|---|
| PDF | 使用带解码体积限制的 PDF 提取器读取文字。无可提取文字的扫描件需先整理成文本；不执行 OCR。采用 LZW / RunLength 压缩的 PDF 不支持，需先导出为可读取的文本版。 |
| DOCX | 使用现有 Word 提取器；检查 Word 文件结构和解压体积。旧 `.doc` 不支持。 |
| TXT / MD | 读取 UTF-8 文本。Markdown 作为来源文字，不作为可执行内容。 |
| JSON | 接受包含 `documents` 数组的知识包，可一次导入多篇草稿；不是任意 JSON 文件。包内原有审批声明不会跳过本后台审批。 |

单文件最多 10 MiB，提取文字最多 100,000 字符。PDF 单个解码流最多 2 MiB、累计解码内容最多 20 MiB；DOCX 解压内容最多 20 MiB。即使原文件小于上传上限，超过解码限制仍会拒绝，应拆分文件或导出文本后再上传。JSON 包最多 50 篇，每篇最多 50 条事实。当前整套发布版本同样最多 50 篇文档。

PDF、DOCX、TXT、MD 上传只建立来源草稿及文字预览，**不会自动生成或批准房地产事实、翻译或地图坐标**。来源 URL、摘录及三语答案由编辑者整理，再由审核者核对。未完成的草稿可以保存；提交审核必须满足完整字段和日期校验。

**Related projects or areas** 可填写数据团队确认的 catalogue project、region 或 Research scheme 标识。关联标识不等于坐标审核，也不替代正式项目映射流程。上传和文本审核不会批准新的地图映射。

从当前已发布文档创建新草稿时，保留服务端已有的可信 `mappingReview`。保存修改时，仅在来源 URL／哈希和各事实的实体关联均未变化时保留该映射；改变来源或实体关联会使其失效，需要回到正式映射审核流程。上传 JSON 中自带的映射批准信息不会被接受。

## 审核、发布和修改

```text
Draft → In review → Approved → Published
            ↓
      Return to draft（附修改意见）
```

- **Submit for review**：校验来源、事实 ID、摘录、关键词、三语答案和日期后进入审核。
- **Approve material**：记录实际审核人、时间、意见，并绑定本次内容哈希。
- **Return to draft**：必须填写需要修改的原因。
- **Publish to Map AI Advisor**：再次校验获批内容并构建索引，成功后切换当前站点的知识版本。

待审资料通过 **Return to draft** 退回后修改；已批准资料点击 **Edit approved material** 返回 Draft，清除原批准状态，需要重新提交和批准。修改已发布资料时点击 **Create new draft**；旧发布内容继续提供回答，直到新版本成功发布。已发布版本及旧聊天引用不被原地改写。

新草稿以当前 active release 的内容为起点。如果该版本原先由本后台上传并发布，且能匹配其发布记录，会一并保留原文件下载、提取文字和来源哈希。历史 CLI 导入但未保存原文件的资料不会因此产生一个不存在的下载附件。

页面使用文档 revision 和当前 active release ID 防止覆盖他人的更新。出现冲突时保留页面中的未保存内容，先复制需要保留的修改，再重新加载最新版本；不要用反复点击发布绕过冲突。

发布同步执行，会使用已配置的云端 embedding 和 Qdrant，产生 embedding 调用成本；本后台不依赖常驻 `knowledge-import` worker。发布期间保持页面打开，等待结果。上传、编辑和审批不调用生成模型。

每次发布构建完整知识版本：**当前 active release 的全部文档，加上本次获批的新文档或替换文档**。因此发布一篇资料不会删除其他已发布资料。索引构建在数据库短事务之外执行；切换 active 前再次检查文档审批和当前 release，避免并发发布覆盖较新的资料。

embedding、索引构建或最终检查失败时，原 active release 继续提供回答，草稿不会被标记为已发布。页面错误提示不包含服务密钥或原始供应商错误响应。同包正在构建时不会再启动一个互相覆盖状态的构建。

## 撤回和恢复

**Withdraw live material** 用于停止新回答检索某篇资料，需填写原因；保留原文件、发布版本、审核记录和已保存引用。撤回不会删除数据库历史。

**Published library history → Restore this version** 恢复的是整套 ready 知识版本，不是只回退当前选中的文档。恢复前核对时间和文档数量；该版本之后发布的其他修改也会退出当前检索版本。恢复过程检查当前 active ID，避免覆盖别人刚完成的发布。

整套回滚不会自动恢复已撤回的文档。重新上线撤回资料应通过新草稿、审核和发布流程。

## 资料存放和备份

| 内容 | 位置 |
|---|---|
| 可编辑草稿、提取文字、审批绑定 | 当前站点数据库 `knowledge_drafts` |
| 创建、编辑、审核、发布、撤回、恢复记录 | 当前站点数据库 `knowledge_admin_events` |
| 不可变文档版本、事实、发布版本 | `knowledge_documents`、`knowledge_document_versions`、`knowledge_chunks`、`knowledge_releases` |
| 上传的原文件 | `local` 私有磁盘的 `propertylab-knowledge-private/`，默认 `storage/app/propertylab-knowledge-private/` |
| 向量索引 | 已配置 Qdrant 中与 release 对应的 collection |

原文件不放在 `public/` 或 `storage/app/public/`，下载经过管理员鉴权。部署时需保留持久化的 `storage/app`；多台应用服务器需保证相同私有文件对执行下载的服务器可见。备份至少覆盖站点数据库、私有来源目录以及 Qdrant 的持久化／恢复方案。仅备份 Git 仓库不包含业务上传和审核记录。

数据库中的文档与事实是权威内容，向量索引可重新构建。恢复索引仍需要可用的 embedding 服务与配置；不能只恢复 active 标记而丢失对应 collection。先在预发布验证整套恢复流程。

## 接入和上线边界

- 新增两张后台表，沿用现有四张知识表；正式部署需执行已审核的迁移。禁止对现有站点运行 `migrate:fresh` 或演示 seed。
- `PROPERTYLAB_KNOWLEDGE_ENABLED=true` 仍是知识问答前提；Research 开关、管理员访问锁及现有模型／embedding／Qdrant 配置仍需满足 [部署流程](DEPLOYMENT.md)。后台不创建凭证、不修改 `.env`、不绕过首次生产 rollout 审核。
- 发布只改变当前站点的知识库内容，不自动同步 `app`、`wk` 等其他独立站点数据库，也不修改共享 master 或 Research snapshot。
- 项目价格、项目卡片、地图坐标及 MRT 连接仍来自各自的数据链路。上传一份文档不代表新增了可售房源、成交记录或已核实的通勤时间。

开发验收使用的原有本地知识与 Research 项目包含显式标注的 `LOCAL TEST` 模拟资料，不得作为正式房地产证据。仓库中的 [materials.draft.json](materials.draft.json) 是正式资料候选草稿，仍需 mentor 或 Wai Kit 核对来源、翻译、有效期和项目映射；此后台的实现不等于这些草稿已获批准。

## 验收方式

使用隔离的测试资料完成一次上传、编辑、提交、退回、再审核、发布，再从 Map AI Advisor 提问并核对答案与版本引用。另检查普通账号拒绝访问、未审资料不可检索、编辑使审批失效、发布保留其他文档、过期 revision 拒绝覆盖、索引失败保留原 active、撤回停止新检索、整套回滚保留撤回状态及原文件下载权限。

本说明描述操作与验收标准，不宣称生产已启用；实际测试结果、代码 SHA 和证据由对应 PR 验收记录提供。
