346 lines
24 KiB
Markdown
346 lines
24 KiB
Markdown
# AI Knowledge Link — 产品需求文档（MVP v1）
|
||
|
||
> 状态标注说明：✅ 已完成 ｜ 🔄 部分完成 ｜ ⬜ 未开始（对应 Phase N） ｜ 📌 持续约束（贯穿全程）
|
||
>
|
||
> **版本说明**：本文档为当前有效需求（MVP 版）。早前一版需求（PostgreSQL + Redis + Celery + MinIO 全功能栈）已被本 MVP 版**取代**，核心差异：MySQL 替代 PostgreSQL+SQLite、本地文件系统替代 MinIO、同步解析替代 Celery、内存限流替代 Redis。原版中的商业许可审查结论仍有效（PDF 解析商品化前需将 PyMuPDF 替换为 pypdfium2，见 `technical-review.md` R3）。
|
||
>
|
||
> **最新更新**：数据库已从 SQLite 迁移到 MySQL（远程开发 47.109.98.44:33306 / 本地生产 127.0.0.1:3306）。新增用户角色系统（internal=内部员工 / customer=客户）和独立内部登录入口（`/internal-login`）。
|
||
>
|
||
> 关联文档：[技术审查报告](technical-review.md) ｜ [CLAUDE.md](../CLAUDE.md)
|
||
|
||
## Phase 进度总览（对应 §56 开发顺序）
|
||
|
||
| Phase | 内容 | 状态 |
|
||
|---|---|---|
|
||
| 1 | 项目初始化 | ✅ 完成 |
|
||
| 2 | 数据库和 Alembic | ✅ 完成 |
|
||
| 3 | 用户注册登录 | ✅ 完成 |
|
||
| 4 | 知识库 CRUD | ✅ 完成 |
|
||
| 5 | 本地 StorageService | ✅ 完成（提前实现于 Phase 1） |
|
||
| 6 | 文档上传 | ✅ 完成 |
|
||
| 7 | 文档解析和 Markdown | ✅ 完成 |
|
||
| 8 | 文档管理 | ✅ 完成（随 Phase 6/7 一起实现） |
|
||
| 9 | Secret URL | ✅ 完成（随 Phase 4/9-11 一起实现） |
|
||
| 10 | AI 公共页面 | ✅ 完成 |
|
||
| 11 | Markdown/TXT/JSON 输出 | ✅ 完成 |
|
||
| 12 | 搜索 | ✅ 完成（LIKE 搜索，可升级 FTS5） |
|
||
| 13 | 安全 | ✅ IDOR 防护、限流、XSS 防护、路径穿越防护、Session 安全 |
|
||
| 14 | 前端完善 | ✅ 完成（含手机适配、字体大小、内部登录页） |
|
||
| 15 | 测试 | ✅ 后端 58/58 通过 |
|
||
| 16 | Docker | 🔄 compose/Dockerfile 已写，待 Docker 环境验证 |
|
||
| 17 | Ubuntu 部署文档 | ✅ 完成（README.md） |
|
||
| - | MySQL 迁移 | ✅ 完成（远程 47.109.98.44:33306） |
|
||
| - | 内部登录系统 | ✅ 完成（role 字段 + /internal-login） |
|
||
|
||
---
|
||
|
||
## 一、产品核心目标 🔄 产品定位，随各 Phase 逐步实现（Phase 1-2 已完成）
|
||
|
||
这个产品不是普通网盘。
|
||
|
||
核心功能是：
|
||
|
||
用户上传自己的 Word、PDF 等文档 → 系统自动解析文档 → 转换成 Markdown → 建立个人知识库 → 系统生成一个 AI 专属访问链接 → 用户复制这个链接 → 发送给第三方 AI → AI 访问知识库 → AI 查看知识库中的文档列表 → 根据用户的描述选择一个或多个相关文档 → 访问具体文档内容 → 利用这些资料回答用户问题
|
||
|
||
例如：用户上传 公司介绍.docx、产品说明.pdf、技术架构.pdf、项目需求.docx，系统生成 `https://example.com/k/xxxxxxxx`。用户把这个链接发送给 AI："请访问这个知识库，阅读产品A相关的技术架构和产品说明，然后告诉我产品A有哪些技术风险。" AI 访问 /k/xxxxxxxx，看到文档列表，然后根据用户要求访问相关文档。
|
||
|
||
## 二、第一阶段必须保持简单 📌 持续约束（Phase 1 已遵循）
|
||
|
||
这是一个 MVP。第一版禁止过度工程化。
|
||
|
||
第一版只使用：
|
||
|
||
- 前端：Vue 3、TypeScript、Vite、Element Plus、Pinia、Axios
|
||
- 后端：Python 3.12+、FastAPI、SQLAlchemy、Pydantic、Alembic
|
||
- 数据库：MySQL 8.0（utf8mb4）
|
||
- 文件存储：服务器本地文件系统
|
||
- 文档解析：MarkItDown、PyMuPDF、python-docx
|
||
- 部署：Docker Compose，可以使用 Nginx
|
||
|
||
第一版禁止强制依赖：PostgreSQL、Redis、Celery、MinIO、Qdrant、Elasticsearch、Kafka。不要因为未来可能商品化而提前加入这些组件。
|
||
|
||
## 三、开发环境 ✅ 完成（Phase 1 验证通过）
|
||
|
||
本地开发环境：Windows。本地没有 Docker。因此 Windows 开发必须可以直接运行。
|
||
|
||
- 前端：`npm install` → `npm run dev` ✅
|
||
- 后端：Python venv → `pip install` → `uvicorn` ✅
|
||
- 本地开发不要求 Docker ✅
|
||
- Docker 主要用于 Ubuntu 云服务器
|
||
|
||
生产环境：Ubuntu、Docker、Docker Compose。
|
||
|
||
## 四、第一版系统架构 🔄 架构已定 + 数据库层 ✅ 实现随 Phase 推进
|
||
|
||
采用：
|
||
|
||
- Windows 开发：Vue 3 + FastAPI + SQLite + 本地文件
|
||
- 生产：Ubuntu + Docker（frontend / backend / nginx）
|
||
|
||
数据目录：
|
||
|
||
```
|
||
/data
|
||
├── app.db
|
||
└── users/{user_id}/knowledge_bases/{knowledge_base_id}/
|
||
├── original/
|
||
└── markdown/
|
||
```
|
||
|
||
SQLite 保存元数据。文件系统保存：Word、PDF、Markdown。
|
||
|
||
## 五、不要把文件塞进 SQLite 📌 持续约束（存储层设计已按此实现）
|
||
|
||
禁止把原始 PDF、Word 二进制内容存进 SQLite。SQLite 只保存：用户信息、知识库信息、文档元数据、文件路径、Markdown 路径、文档状态、Token hash、时间、分类、描述、关键词、搜索相关数据。原始文件与 Markdown 均存服务器文件系统。
|
||
|
||
## 六、数据库访问必须抽象 ✅ 完成（Phase 2：ORM 模型 + Alembic 迁移已落地）
|
||
|
||
不能在业务代码中到处直接调用 sqlite3。必须使用 SQLAlchemy，并通过 Repository / Service 分层（UserRepository、KnowledgeBaseRepository、DocumentRepository）。业务逻辑不能依赖 SQLite 具体实现。数据库配置通过 `DATABASE_URL`（如 `sqlite:///./data/app.db`），未来可以切换 PostgreSQL 而尽量不修改业务层。
|
||
|
||
## 七、未来扩展接口 1：SQLite → PostgreSQL 📌 持续约束（设计规则已在 db.py 落地）
|
||
|
||
第一版使用 SQLite，但设计 DatabaseRepository、SQLAlchemy models、Alembic migrations。不要使用 SQLite 特有 SQL 作为核心业务逻辑；避免 PRAGMA（WAL 设置除外）、SQLite 专属函数、SQLite 专属数据类型。业务代码尽可能使用标准 SQLAlchemy。未来切换只需更换连接配置并处理迁移。
|
||
|
||
## 八、未来扩展接口 2：本地文件 → MinIO/S3 ✅ 完成（Phase 1 提前实现）
|
||
|
||
已实现 `StorageService` 协议（`storage/base.py`：save/read/delete/exists/get_size）与 `LocalStorageService`（`storage/local_storage.py`）。业务代码不能直接 `open("/data/xxx")`，所有文件读写必须经过 StorageService。未来可增加 MinioStorageService / S3StorageService。
|
||
|
||
## 九、未来扩展接口 3：同步解析 → 异步任务 ⬜ Phase 7（DocumentProcessor 协议）
|
||
|
||
第一版：上传文件 → FastAPI → 同步解析 → 保存 Markdown → 返回结果。必须抽象 `DocumentProcessor`（如 `process_document()`）：第一版 `LocalDocumentProcessor`，未来可增加 `CeleryDocumentProcessor`。业务代码不要把文档解析逻辑写进 API endpoint。
|
||
|
||
## 十、未来扩展接口 4：关键词搜索 → RAG ⬜ Phase 12（Retriever 协议）
|
||
|
||
第一版不使用向量数据库。实现 `Retriever` 统一接口（`search(query, knowledge_base_id)`），第一版 `KeywordRetriever`（SQLite FTS 或简单关键词搜索）。未来可加 VectorRetriever / HybridRetriever / QdrantRetriever、Embedding、Reranker。第一版不安装这些依赖。
|
||
|
||
## 十一、未来扩展接口 5：个人用户 → 团队/企业 📌 持续约束（数据库设计时遵守）
|
||
|
||
第一版：一个用户拥有多个知识库（User → KnowledgeBase → Documents）。但数据库设计必须避免以后无法扩展。未来：Organization → Members → KnowledgeBases → Documents。第一版不实现团队，但不要把 user_id 硬编码成未来无法扩展的权限结构。
|
||
|
||
## 十二、未来扩展接口 6：AI 网页访问 → API/MCP 📌 持续约束（Phase 10 落地）
|
||
|
||
第一版：AI 通过 Secret URL 访问（GET /k/{token}），这是产品核心功能。未来可增加 API Key、REST API、MCP Server、OpenAPI、AI Agent 接口。第一版不实现 MCP，但公共知识库服务层必须独立：HTML、Markdown、TXT、JSON 都调用同一个 `KnowledgeBasePublicService`（Controller → Service → Repository → Database），不要每种格式各写一套查询逻辑。
|
||
|
||
## 十三、用户系统 ✅ Phase 3 完成
|
||
|
||
实现注册、登录、退出登录。
|
||
|
||
User：id、username、email、password_hash、status、storage_quota、storage_used、created_at、updated_at。密码必须安全哈希，优先 Argon2id；禁止明文密码、MD5、SHA1。
|
||
|
||
## 十四、存储限制 ✅ 完成（config.py 配额配置 + Plan 模型已落地 Phase 2）
|
||
|
||
默认免费用户 100MB，单文件 20MB。不要硬编码，放到配置或 Plan 模型。第一版 Free Plan（100MB / 20MB-per-file），未来 Basic 1GB、Pro 5GB、Enterprise 自定义。第一版不实现支付。
|
||
|
||
## 十五、知识库 ⬜ Phase 4
|
||
|
||
KnowledgeBase：id、user_id、name、description、enabled、secret_token_hash、created_at、updated_at。一个用户可以创建多个知识库（公司知识库、项目A、项目B、个人AI资料）。
|
||
|
||
## 十六、AI 专属链接 ⬜ Phase 9
|
||
|
||
每个知识库生成一个 Secret Token（`https://example.com/k/7fA92xKpQ8m...`）。必须使用密码学安全随机数（`secrets.token_urlsafe()` 或同等方案）；禁止自增 ID、时间戳、用户名、UUID 短截断。数据库保存 token_hash 而不是明文 Token。用户复制的完整 URL 只在生成时提供给用户。
|
||
|
||
## 十七、AI 链接安全模型 ⬜ Phase 9/13
|
||
|
||
公共 AI 访问不需要登录（第三方 AI 无法使用用户后台登录状态），Secret URL 本身就是访问凭证，相当于 Bearer Credential——任何获得 URL 的人理论上都可以读取知识库，必须在产品中明确这一点。提供启用/禁用链接、重新生成链接；重新生成后旧链接立即失效。
|
||
|
||
## 十八、AI 知识库首页 ⬜ Phase 10
|
||
|
||
`GET /k/{token}` 必须返回服务端生成的 HTML，不能依赖 Vue / JavaScript（第三方 AI 可能不执行 JS），页面必须首屏直接包含核心信息。页面结构：title=知识库名称、`<meta name="robots" content="noindex,nofollow,noarchive">`、知识库名称、知识库描述、Documents 列表（每篇含标题、描述、类型、更新时间、URL）。
|
||
|
||
## 十九、多格式输出 ⬜ Phase 11
|
||
|
||
- `GET /k/{token}` → HTML
|
||
- `GET /k/{token}.md` → Markdown
|
||
- `GET /k/{token}.txt` → 纯文本
|
||
- `GET /k/{token}.json` → JSON
|
||
|
||
JSON 只能返回必要的信息，禁止：用户密码、token hash、内部数据库 ID、服务器路径、MinIO 地址、内部配置。
|
||
|
||
## 二十、单文档访问 ⬜ Phase 10/11
|
||
|
||
- `GET /k/{token}/doc/{document_token}` → HTML
|
||
- `GET /k/{token}/doc/{document_token}.md` → Markdown
|
||
- `GET /k/{token}/doc/{document_token}.txt` → TXT
|
||
|
||
文档页面：标题、描述、文件类型、关键词、更新时间、Markdown 正文。默认不直接提供原始文件下载。
|
||
|
||
## 二十一、文档 Token ⬜ Phase 9
|
||
|
||
不要使用 /doc/1 这种容易猜测的 URL。每个文档生成随机 document_token，数据库保存 hash。例如 `/k/knowledge-token/doc/document-token`，两个 Token 都必须随机。
|
||
|
||
## 二十二、文档上传 ⬜ Phase 6
|
||
|
||
支持 .docx、.pdf；暂不支持 .doc、.xls、.xlsx、.ppt、.pptx，但代码架构预留扩展。
|
||
|
||
上传流程：POST /api/documents/upload → 检查登录 → 检查知识库权限 → 检查文件大小 → 检查扩展名 → 检查 MIME → 计算 SHA256 → 检查存储额度 → 保存原始文件 → 解析 → 转换 Markdown → 提取标题 → 生成摘要 → 提取关键词 → 保存 Markdown → 更新 Document → 返回结果。
|
||
|
||
## 二十三、文件目录 📌 持续约束（key 生成已实现于 storage/object_keys.py）
|
||
|
||
推荐布局：
|
||
|
||
```
|
||
data/
|
||
├── app.db
|
||
└── users/{user_id}/knowledge_bases/{knowledge_base_id}/
|
||
├── original/ （random-name.docx / random-name.pdf）
|
||
└── markdown/ （random-name.md）
|
||
```
|
||
|
||
不要使用用户原始文件名直接作为物理存储路径（如 `../../evil.pdf` 必须安全处理）。
|
||
|
||
## 二十四、文档解析 ⬜ Phase 7
|
||
|
||
优先 MarkItDown；PDF 用 PyMuPDF 作为辅助/fallback；Word 用 python-docx 作为 fallback。Markdown 需尽可能保留：标题、段落、列表、表格、粗体、斜体、代码块、引用。解析失败时 Document.status = FAILED，不向用户显示 Traceback / 服务器路径 / Python 异常堆栈，只显示友好错误（"文档解析失败，请检查文件是否损坏或格式是否受支持。"），服务器日志记录详细错误。
|
||
|
||
## 二十五、扫描 PDF ⬜ Phase 7
|
||
|
||
第一版不强制 OCR。如果 PDF 没有文本层，提示"该 PDF 可能是扫描件，当前版本暂不支持 OCR。"未来预留 OCRProcessor（PaddleOCR 等），第一版不加入 OCR。
|
||
|
||
## 二十六、文档状态 🔄 状态模型 ✅ 完成（Phase 2）；流转 ⬜ Phase 7
|
||
|
||
PENDING、PROCESSING、READY、FAILED、DELETED。虽然第一版同步处理，但状态模型必须保留，未来异步任务可以直接使用。
|
||
|
||
## 二十七、知识库搜索 ⬜ Phase 12
|
||
|
||
`GET /k/{token}/search?q=关键词` 返回：文档、标题、匹配摘要、URL。第一版用 SQLite FTS 或简单关键词搜索，实现 Retriever 接口（第一版 KeywordRetriever）。不引入 Qdrant、Embedding。
|
||
|
||
## 二十八、AI 选择多个文档 ⬜ Phase 10（产品最重要功能之一）
|
||
|
||
知识库首页不能把所有文档正文全部输出。首页应提供：文档标题、文档描述、关键词、文档类型、文档 URL。例如"产品A技术架构（关键词：产品A、架构、服务器、数据库、Redis）→ /k/xxxx/doc/yyyy"。这样 AI 可以根据用户描述选择文档——用户说"请阅读产品A的架构和数据库设计"，AI 应能发现并访问"产品A技术架构"和"产品A数据库设计"两个文档。
|
||
|
||
## 二十九、AI 兼容性 ⬜ Phase 10/11（README 声明 Phase 17）
|
||
|
||
不能假设第三方 AI 一定支持 JavaScript、Cookie、登录、API 调用、自动跟随所有链接、搜索接口。AI 页面必须：服务端渲染、HTML 标准、正文直接返回、链接使用标准 `<a href>`、不依赖 JS、不使用复杂 SPA、内容结构清晰。同时提供 HTML / Markdown / TXT / JSON，尽可能提高 DeepSeek、豆包、Kimi、ChatGPT 及其他支持网页访问的 AI 的兼容性。README 必须明确：第三方 AI 是否支持访问外部 URL、跟随链接和读取页面，由第三方 AI 自身能力决定，本系统不能保证所有 AI 都一定会访问后续文档。
|
||
|
||
## 三十、前端 🔄 骨架完成（Phase 1）；完整 UI ⬜ Phase 14
|
||
|
||
Vue 3、TypeScript、Vite、Element Plus、Pinia。UI 要求：现代、简洁、SaaS 风格、中文、不要花哨、不要大量动画。主要页面：/login、/register、/dashboard、/knowledge-bases、/knowledge-bases/:id、/settings。
|
||
|
||
## 三十一、登录页面 🔄 占位页已有（Phase 1）；功能 ⬜ Phase 14
|
||
|
||
登录：用户名/邮箱、密码、登录。注册：用户名、邮箱、密码、确认密码。基本校验。
|
||
|
||
## 三十二、Dashboard 🔄 占位页已有（Phase 1）；功能 ⬜ Phase 14
|
||
|
||
显示：知识库数量、文档数量、已使用空间/总空间（如 32MB / 100MB）、最近知识库、最近上传、解析失败文件。
|
||
|
||
## 三十三、知识库管理 ⬜ Phase 4（接口）/ Phase 14（UI）
|
||
|
||
显示：知识库名称、描述、文档数量、空间、创建时间、AI 链接。操作：管理、复制 AI 链接、预览、启用/禁用、重新生成链接、删除。
|
||
|
||
## 三十四、文档管理 ⬜ Phase 6/8（接口）/ Phase 14（UI）
|
||
|
||
支持拖拽上传、多文件上传。显示：文件名、类型、大小、状态、更新时间。操作：预览、重新解析、删除。
|
||
|
||
## 三十五、文档编辑 ⬜ Phase 8
|
||
|
||
用户可以修改：标题、描述、关键词、分类。Markdown 正文默认由系统生成。第一版可提供 Markdown 预览；是否允许直接编辑 Markdown 不是最高优先级，时间有限可暂时只读。
|
||
|
||
## 三十六、权限 ⬜ Phase 13（编码时全程遵守）
|
||
|
||
必须防止 IDOR：用户A访问 /api/knowledge-bases/10，不能通过修改 10 → 11 读取用户B知识库。所有后台接口必须验证：当前登录用户 → 资源 owner → 允许操作。不能只验证资源 ID 存在。
|
||
|
||
## 三十七、公共 AI 链接权限 ⬜ Phase 9
|
||
|
||
公共 AI URL 不要求登录，但必须验证 Secret Token。enabled = false 返回 404。重新生成 Token 后旧 Token 立即失效。
|
||
|
||
## 三十八、安全 ⬜ Phase 13（编码时全程遵守）
|
||
|
||
考虑：SQL 注入、XSS、CSRF、路径穿越、恶意文件、超大文件、Zip Bomb、暴力破解、Token 猜测、IDOR、资源耗尽。上传文件：限制大小、限制扩展名、限制 MIME、随机物理文件名。Markdown 输出必须防存储型 XSS；用户输入的标题、描述、关键词不能直接插入 HTML；Markdown 渲染需要安全处理。
|
||
|
||
## 三十九、限流 ✅ RateLimiter 抽象完成（Phase 1）；接入公共 URL ⬜ Phase 13
|
||
|
||
第一版不需要 Redis，可以使用内存限流（如单 IP 每分钟一定次数），保护公共 AI URL。注意内存限流只适合单实例 MVP，代码中抽象 RateLimiter，未来可实现 RedisRateLimiter。（已实现 `core/rate_limit.py`：内存 TokenBucket + 配置化阈值。）
|
||
|
||
## 四十、访问日志 🔄 模型 ✅ 完成（Phase 2）；记录 ⬜ Phase 10
|
||
|
||
第一版可简单记录：knowledge_base_id、document_id、timestamp、user_agent、请求类型。不要默认长期保存完整 IP。后台可显示访问次数、最近访问时间。不要声称可以准确判断访问者是不是 AI，使用"外部访问"而不是"AI 访问"。
|
||
|
||
## 四十一、数据库模型 ✅ 完成（Phase 2：User/Plan/KnowledgeBase/DocumentCategory/Document/AccessLog 全部落地）
|
||
|
||
至少：User、Plan、KnowledgeBase、Document、DocumentCategory、AccessLog。
|
||
|
||
Document：id、knowledge_base_id、user_id、document_token_hash、original_filename、storage_path、markdown_path、file_size、mime_type、sha256、title、description、keywords、category_id、status、created_at、updated_at。
|
||
|
||
KnowledgeBase：id、user_id、name、description、secret_token_hash、enabled、created_at、updated_at。
|
||
|
||
## 四十二、数据库迁移 ✅ 完成（Phase 2：Alembic 初始化 + 初始迁移 initial_schema 已应用）
|
||
|
||
使用 Alembic，即使 SQLite 也必须使用迁移。不要手工修改生产数据库。README 提供：初始化迁移、升级迁移、回滚迁移。
|
||
|
||
## 四十三、API 设计 🔄 分 Phase 实现
|
||
|
||
认证：✅ POST /api/auth/register、✅ POST /api/auth/login、✅ POST /api/auth/logout、✅ GET /api/me、✅ PATCH /api/me、✅ GET /api/auth/storage
|
||
知识库：GET/POST /api/knowledge-bases、GET/PUT/DELETE /api/knowledge-bases/{id}
|
||
知识库链接：POST /api/knowledge-bases/{id}/regenerate-token、/enable、/disable
|
||
文档：GET /api/knowledge-bases/{id}/documents、POST /api/knowledge-bases/{id}/documents、GET/PUT/DELETE /api/documents/{id}、POST /api/documents/{id}/reprocess
|
||
存储：GET /api/storage
|
||
公共：GET /k/{token}（+.md/.txt/.json）、GET /k/{token}/search?q=、GET /k/{token}/doc/{document_token}（+.md/.txt）
|
||
|
||
## 四十四、统一 Service 层 🔄 分 Phase 实现（Phase 1 已落 StorageService）
|
||
|
||
不要把业务逻辑全部写进 FastAPI 路由。至少：AuthService、UserService、KnowledgeBaseService、DocumentService、DocumentProcessor、StorageService、KnowledgeBasePublicService、Retriever、RateLimiter。
|
||
|
||
## 四十五、公共 AI 访问统一 Service ⬜ Phase 10
|
||
|
||
HTML / Markdown / TXT / JSON 各 Renderer 都必须：KnowledgeBasePublicService → 返回知识库数据 → 各格式 Renderer。所有格式必须使用同一套数据来源。
|
||
|
||
## 四十六、Docker 🔄 compose/Dockerfile 已写（Phase 1）；验证 ⬜ Phase 16
|
||
|
||
虽然 Windows 开发不需要 Docker，但项目必须提供生产 Docker 配置。docker-compose.yml：frontend、backend、nginx。SQLite 和文件：宿主机 ./data 挂载到 /app/data。重要：数据库和用户文件不能写进 Docker 镜像；删除容器以后数据仍然存在。
|
||
|
||
## 四十七、生产目录 ⬜ Phase 17
|
||
|
||
服务器 /opt/ai-knowledge-link/：docker-compose.yml、.env、data/（app.db + users/）、nginx/、project/（或合理目录）。data 必须独立于代码。
|
||
|
||
## 四十八、备份 ⬜ Phase 17
|
||
|
||
第一版使用 SQLite，必须提供备份脚本：app.db + users/。建议每日备份，保留最近 7 天、最近 4 周。备份不能影响正在运行的服务。README 说明如何备份、如何恢复。
|
||
|
||
## 四十九、Git ✅ 完成（Phase 1）
|
||
|
||
已提供 .gitignore（禁止提交：.env、data/、*.db、上传文件、虚拟环境、node_modules）与 .env.example。
|
||
|
||
## 五十、Windows 开发 ✅ 完成（Phase 1，README 已含完整步骤；实测通过）
|
||
|
||
README 必须详细说明：安装 Python、创建 venv（`python -m venv .venv`、Windows 激活 `.venv\Scripts\activate`）、安装依赖（`pip install -r requirements.txt`）、启动 FastAPI（`uvicorn app.main:app --reload`）；安装 Node、`npm install`、`npm run dev`。
|
||
|
||
## 五十一、生产部署 ⬜ Phase 17
|
||
|
||
README 必须详细说明：Ubuntu 安装 Docker、克隆 Git 仓库、配置 .env、创建 data 目录、启动（`docker compose up -d --build`）、查看（`docker compose ps`）、日志（`docker compose logs -f`）、更新（`git pull && docker compose up -d --build`）。数据不能因为更新丢失。
|
||
|
||
## 五十二、测试 🔄 冒烟测试 3 条通过（Phase 1）；完整覆盖 ⬜ Phase 15
|
||
|
||
必须编写测试，至少覆盖：注册、登录、错误密码、创建知识库、删除知识库、用户隔离、上传 DOCX、上传 PDF、文件大小限制、存储空间限制、文档解析、Markdown 生成、Token 生成、Token 禁用、Token 重新生成、旧 Token 失效、公共知识库 HTML、公共 Markdown、公共 TXT、公共 JSON、单文档访问、文档 Token、搜索、XSS 防护、路径穿越、IDOR。
|
||
|
||
## 五十三、项目目录 ✅ 完成（Phase 1）
|
||
|
||
```
|
||
project/
|
||
├── backend/（app/{api,core,models,schemas,repositories,services,processors,storage,retrieval,public}、alembic/、tests/、requirements.txt、Dockerfile）
|
||
├── frontend/（src/{api,components,layouts,views,stores,router,types}、package.json、Dockerfile）
|
||
├── nginx/nginx.conf
|
||
├── data/.gitkeep
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
## 五十四、代码原则 📌 持续约束（Phase 1 已遵循）
|
||
|
||
不要：一个 main.py 写完所有东西；所有数据库查询写在路由；业务代码直接 open 文件；硬编码路径；硬编码 100MB；硬编码 Secret Token；把密码明文保存；把用户 A/B 数据混在一起；使用 Vue 渲染 AI 公共页面。
|
||
|
||
## 五十五、产品第一阶段验收标准 ⬜ 最终验收（Phase 15 后）
|
||
|
||
1. 用户注册。2. 用户登录。3. 创建"公司知识库"。4. 上传 公司介绍.docx、产品说明.pdf、技术架构.pdf。5. 系统自动转换 Markdown。6. 后台显示 3 个文档。7. 用户复制 AI 专属链接。8. 退出登录。9. 未登录状态打开链接仍能访问知识库。10. 页面显示知识库名称、描述、文档列表、文档描述、文档 URL。11. 访问其中一个文档能看到 Markdown 正文。12. 访问 .md 得到 Markdown。13. 访问 .txt 得到纯文本。14. 访问 .json 得到机器可读数据。15. /search?q=产品A 能找到相关文档。16. 重新生成 AI 链接后旧链接立即失效。17. 禁用 AI 链接后公共访问失败。18. 用户A无法访问用户B后台数据。19. 用户A无法通过修改 ID 读取用户B资源。20. Docker 部署后删除容器并重新创建，用户数据不能丢失。
|
||
|
||
## 五十六、第一阶段开发顺序 ✅ Phase 1 完成，按序推进中
|
||
|
||
Phase 1 项目初始化 → Phase 2 数据库和 Alembic → Phase 3 用户注册登录 → Phase 4 知识库 CRUD → Phase 5 本地 StorageService → Phase 6 文档上传 → Phase 7 文档解析和 Markdown → Phase 8 文档管理 → Phase 9 Secret URL → Phase 10 AI 公共页面 → Phase 11 Markdown/TXT/JSON 输出 → Phase 12 搜索 → Phase 13 安全 → Phase 14 前端完善 → Phase 15 测试 → Phase 16 Docker → Phase 17 Ubuntu 部署文档。
|
||
|
||
每完成一个 Phase：1. 检查代码 2. 运行测试 3. 修复错误 4. 确认没有破坏之前功能 5. 再进入下一阶段。
|
||
|
||
## 五十七、当前任务 ✅ 完成（技术审查报告见 technical-review.md）
|
||
|
||
第一步不要立即创建大量业务代码，先对整个需求进行技术审查，输出：最终架构、数据库 ER 结构、API 结构、项目目录、六个未来扩展接口如何设计、安全模型、文档处理流程、AI 访问流程、Windows 开发流程、Docker 生产流程、发现的风险、建议修改的地方。确认后从 Phase 1 开始，不要跳过架构审查。 |