找书查书功能 - 审计评估报告

⚠️ **归档文档 — 数据已过时** 本报告为历史快照存档。当前版本 **v1.3.0-dev**，232 测试通过。 👉 最新工程状态请参阅 **[ENGINEERING_ALIGNMENT.md](ENGINEERING_ALIGNMENT.md)**

---

审计日期: 2026-03-31 审计对象: 三个核心设计文档 状态: ⚠️ 需要修正后才能实施

---

✅ 优点

1. 整体设计优秀

• ✅ 参考FoJin的成熟架构，设计合理
• ✅ 功能需求分析全面，优先级划分清晰
• ✅ 数据库设计规范，表结构完整
• ✅ API设计符合RESTful规范
• ✅ 分阶段实施计划可行

2. 技术选型合理

• ✅ PostgreSQL + pgvector（已有）
• ✅ 本地BGE模型（已集成）
• ✅ FastAPI（现有架构）
• ✅ 全文搜索支持

3. 文档完整

• ✅ 设计文档详细
• ✅ 实现指南清晰
• ✅ SQL脚本完整

---

⚠️ 关键问题（必须修正）

1. 向量维度不匹配 🔴 CRITICAL

问题: - 设计文档: vector(1024) (BGE-M3) - 实际代码: vector(512) (BAAI/bge-small-zh-v1.5)

影响: 所有向量索引和搜索将失败

修正方案:

-- 修改 SQL 脚本第68行
- embedding vector(1024),
+ embedding vector(512),

-- 修改索引定义第84行
- CREATE INDEX idx_books_embedding ON books USING ivfflat(embedding vector_cosine_ops) WITH (lists = 100);
+ CREATE INDEX idx_books_embedding ON books USING ivfflat(embedding vector_cosine_ops);

2. 全文搜索配置不存在 🔴 HIGH

问题:

-- 使用 'chinese' 配置，但PostgreSQL默认没有
to_tsvector('chinese', title)
to_tsquery('chinese', :query)

修正方案:

-- 方案1: 使用默认配置（简单）
to_tsvector('simple', title)

-- 方案2: 安装 zhparser 扩展（推荐）
CREATE EXTENSION zhparser;
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser;

-- 方案3: 使用 pg_trgm（模糊匹配）
CREATE EXTENSION pg_trgm;
title % query  -- 相似度匹配

3. 导入路径错误 🟡 MEDIUM

问题:

# 实现指南中的导入路径与现有架构不符
from backend.core.database import Base  # ❌ 不存在
from backend.models.book import Book    # ❌ 文件不存在

实际架构:

# 正确的导入方式
from core.database import Base           # ✅ 存在
from core.dependency_injection import get_db_pool  # ✅ 存在

4. 数据库连接方式不一致 🟡 MEDIUM

问题:

# 实现指南示例
service = BookSearchService(db, get_db_pool())  # ❌ get_db_pool() 不返回连接池

# 实际应该使用
from core.database import db_pool
service = BookSearchService(db, db_pool)  # ✅

---

📊 兼容性检查

与现有系统的兼容性

组件	状态	说明
数据库连接	✅ 兼容	使用现有的 core.database
向量嵌入	✅ 兼容	已有本地BGE模型（512维）
认证系统	✅ 兼容	已有JWT认证
Redis缓存	✅ 兼容	已有缓存层
API路由	⚠️ 需适配	需注册到主路由

表结构冲突检查

-- 现有表
documents (id, title, content, category, embedding)

-- 新增表
books (id, title, content, category, embedding)
book_chapters (id, book_id, content)

-- ⚠️ 潜在问题：
-- 1. books 和 documents 结构类似，可能重复
-- 2. 建议明确区分或合并

建议:

-- 方案1: 重用 documents 表，添加书籍特有字段
ALTER TABLE documents ADD COLUMN author VARCHAR(200);
ALTER TABLE documents ADD COLUMN dynasty VARCHAR(50);

-- 方案2: 明确区分用途
-- documents = 问答检索（短文本）
-- books = 书籍检索（长文本、有结构）

---

🔧 必要修正

修正1: 向量维度

-- scripts/init_book_search_db.sql:68
- embedding vector(1024),
+ embedding vector(512),

修正2: 全文搜索配置

-- 方案A: 使用 pg_trgm（推荐，无需安装）
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- 修改索引
- CREATE INDEX idx_books_title ON books USING gin(to_tsvector('chinese', title));
+ CREATE INDEX idx_books_title ON books USING gin(title gin_trgm_ops);

-- 修改搜索函数
- WHERE b.textsearchable_index_col @@ to_tsquery('chinese', search_query)
+ WHERE b.title ILIKE '%' || search_query || '%'

修正3: 移除 textsearchable_index_col

-- 这个列依赖 'chinese' 配置
- ALTER TABLE books ADD COLUMN textsearchable_index_col tsvector ...
- CREATE INDEX idx_books_textsearch ON books USING gin(textsearchable_index_col);

-- 替代方案：直接使用 LIKE 或 pg_trgm
+ CREATE INDEX idx_books_title_trgm ON books USING gin(title gin_trgm_ops);

修正4: 简化实现指南代码

# backend/models/book.py
- from backend.core.database import Base
+ from core.database import Base

# api/v2/books.py
- from backend.core.database import get_db
+ from core.database import get_db
- from backend.core.dependency_injection import get_db_pool
+ from core.dependency_injection import get_db_pool

---

📝 修正后的SQL脚本

-- 修正后的关键部分

-- 1. 确保扩展安装
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- 2. 修正向量维度
embedding vector(512),  -- 使用512维（匹配bge-small-zh-v1.5）

-- 3. 使用 pg_trgm 索引
CREATE INDEX idx_books_title_trgm ON books USING gin(title gin_trgm_ops);
CREATE INDEX idx_books_author_trgm ON books USING gin(author gin_trgm_ops);
CREATE INDEX idx_books_content_trgm ON book_chapters USING gin(content gin_trgm_ops);

-- 4. 移除 textsearchable_index_col（不需要）
-- 删除第229-237行

-- 5. 简化搜索函数
CREATE OR REPLACE FUNCTION search_books_simple(search_query TEXT)
RETURNS TABLE(
    book_id INTEGER,
    title VARCHAR,
    author VARCHAR,
    category VARCHAR
) AS $$
BEGIN
    RETURN QUERY
    SELECT
        b.id,
        b.title,
        b.author,
        b.category
    FROM books b
    WHERE b.title ILIKE '%' || search_query || '%'
       OR b.author ILIKE '%' || search_query || '%'
    LIMIT 20;
END;
$$ LANGUAGE plpgsql;

---

🎯 修正优先级

优先级	问题	影响	修正时间
P0	向量维度不匹配	数据库错误	5分钟
P0	全文搜索配置	索引创建失败	10分钟
P1	导入路径错误	代码无法运行	15分钟
P1	数据库连接	运行时错误	10分钟
P2	表结构重复	数据冗余	规划阶段

总计修正时间: ~40分钟

---

✅ 审计结论

总体评价: ⭐⭐⭐⭐ (4/5)

优点: - 设计思路清晰，参考系统成熟 - 功能规划全面，分阶段实施合理 - 文档详细，便于实施

缺点: - 未与现有代码库充分对齐 - 向量维度配置错误 - 全文搜索依赖不存在的配置

建议

1. 立即修正P0问题后再开始实施
2. 创建适配层连接现有架构
3. 考虑复用documents表而非新建books表
4. 先MVP验证再全面实施

实施建议

方案A - 保守实施 (推荐):

1. 修正所有P0问题
2. 先实施MVP（仅书籍搜索）
3. 验证后逐步添加功能
4. 总时间: 2-3周

方案B - 快速实施:

1. 直接使用现有 documents 表
2. 添加书籍元数据字段
3. 快速上线基础搜索
4. 总时间: 1周

---

下一步: 选择实施方案，修正文档后开始