From f68b052a69bf7150ca460294df6c4b856c5cf7f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E8=83=9C=E5=AE=87?=
 <17412268+zzzzz11122222@user.noreply.gitee.com>
Date: Sat, 12 Sep 2026 11:53:35 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E7=AB=AF=E7=82=B9=E7=BC=96=E5=8F=B7?=
 =?UTF-8?q?=E5=8E=BB=E9=87=8D=E4=B8=8E=20milvus-lite=20=E9=99=8D=E4=B8=BA?=
 =?UTF-8?q?=E5=8F=AF=E9=80=89=E4=BE=9D=E8=B5=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

按 qyqy 在 PR #7 评审中的要求处理两项：

- docs/05-接口文档.md §19：客服画像候选的两个端点由 A034/A035 改为 A039/A040。
  原编号与 qyqy 侧登录 / RBAC 只读接口（A034-A038）重复；docs 守卫脚本只校验
  文档文件名编号、不校验 §19 端点编号，因此该重复会静默遗留。改后全表 55 个
  端点编号唯一。
- pyproject.toml / requirements.txt：milvus-lite 由主 dependencies 挪到
  [project.optional-dependencies] dev；requirements.txt 只保留说明性注释，
  不再作为生效依赖。理由：它仅用于本地开发（Docker Milvus 未运行时的本地
  持久化向量库），进主依赖会让生产环境多背一个包。

验证：pytest tests/unit tests/contract -> 1275 passed, 2 skipped, 0 failed；
ruff check app tests tools alembic 通过；mypy app 通过（244 个源文件）。
---
 docs/05-接口文档.md | 4 ++--
 pyproject.toml      | 6 +++++-
 requirements.txt    | 5 ++++-
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/05-接口文档.md b/docs/05-接口文档.md
index 859c450..cf4191e 100644
--- a/docs/05-接口文档.md
+++ b/docs/05-接口文档.md
@@ -1097,8 +1097,8 @@ GET /internal/metrics
 | M002 | `GET /api/v1/customers/{customer_id}/memory-profile` | `memory:read:customer` | 否 | `200` | 敏感访问 |
 | M003 | `GET /api/v1/users/me/memory-candidates` | `memory:read:self` | 否 | `200` | 候选查询 |
 | M004 | `POST /api/v1/users/me/memory-candidates/{candidate_id}/decisions` | `memory:candidate:confirm` | 必须 | `200` | 用户确认/拒绝 |
-| A034 | `GET /api/v1/admin/customer-profile-candidates` | `memory:candidate:review` | 否 | `200` | 候选审核列表 |
-| A035 | `POST /api/v1/admin/customer-profile-candidates/{candidate_id}/reviews` | `memory:candidate:review` | 必须 | `200` | 候选审核 |
+| A039 | `GET /api/v1/admin/customer-profile-candidates` | `memory:candidate:review` | 否 | `200` | 候选审核列表 |
+| A040 | `POST /api/v1/admin/customer-profile-candidates/{candidate_id}/reviews` | `memory:candidate:review` | 必须 | `200` | 候选审核 |
 | K001 | `GET /api/v1/knowledge-references/{reference_token}` | `knowledge:reference:read` | 否 | `200` | 否 |
 | K002 | `POST /api/v1/knowledge/upload` | `knowledge:manage` | 否 | `201` | 知识文档变更 |
 | K003 | `GET /api/v1/knowledge/list` | `knowledge:manage` | 否 | `200` | 否 |
diff --git a/pyproject.toml b/pyproject.toml
index 789ea59..c9526f0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,7 +21,6 @@ dependencies = [
   "redis>=5.2,<6",
   "neo4j>=5.28,<6",
   "pymilvus>=2.5,<3",
-  "milvus-lite>=3.2,<4",
   "PyJWT>=2.10,<3",
   "cryptography>=44,<51",
   "bcrypt>=4.0,<5",
@@ -50,6 +49,11 @@ dev = [
   # 原先没声明 —— 别人的环境装完依赖跑测试，这 6 个用例会直接
   # ModuleNotFoundError: No module named 'aiosqlite'。
   "aiosqlite>=0.20,<1",
+  # 本地开发专用：Docker Milvus 未运行时用的本地持久化向量库
+  # （配合 `.env` 的 `MILVUS_LOCAL_URI` 使用）。
+  # 刻意**不**进主 `dependencies`：团队/生产环境使用受管 Milvus，
+  # 多背这个包没有意义，而它还正是 `MILVUS_LOCAL_URI` 那个坑的来源。
+  "milvus-lite>=3.2,<4",
 ]
 
 [tool.setuptools.packages.find]
diff --git a/requirements.txt b/requirements.txt
index defd557..0199fa6 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -12,7 +12,10 @@ pymysql>=1.1,<2
 redis>=5.2,<6
 neo4j>=5.28,<6
 pymilvus>=2.5,<3
-milvus-lite>=3.2,<4
+# milvus-lite（本地开发专用：Docker Milvus 未运行时的本地持久化向量库，
+# 配合 .env 的 MILVUS_LOCAL_URI）**刻意不在此列** —— 它是可选依赖，
+# 声明在 pyproject.toml 的 `[project.optional-dependencies] dev`。
+# 本机需要时：`pip install "milvus-lite>=3.2,<4"` 或 `pip install -e ".[dev]"`。
 PyJWT>=2.10,<3
 cryptography>=44,<51
 httpx>=0.28,<1