v0.9.9 基线版本
parent
4ef3c92d65
commit
f92fff6546
|
|
@ -1,6 +1,8 @@
|
||||||
# 部署配置更新日志
|
# 部署配置更新日志
|
||||||
|
|
||||||
## v1.0.1 (2024-12-23)
|
> ⚠️ 版本对齐：git 发布线当前为 v0.9.9（无 v1.0.x tag），下列 v1.0.1 为早期文案占位。详见 SDD `docs/sdd/releases/`。
|
||||||
|
|
||||||
|
## v1.0.1 (2024-12-23，遗留占位)
|
||||||
|
|
||||||
### 🔧 配置变更
|
### 🔧 配置变更
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -336,6 +336,6 @@ CREATE TABLE `operation_logs` (
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**文档版本**: v1.0
|
**文档版本**: v1.0（与代码版本 v0.9.9 的 git 基线无直接对应，见 SDD releases/）
|
||||||
**最后更新**: 2023-12-20
|
**最后更新**: 2023-12-20
|
||||||
**维护人**: Mula.liu
|
**维护人**: Mula.liu
|
||||||
|
|
|
||||||
|
|
@ -316,7 +316,9 @@ find backend/logs -name "*.log" -mtime +30 -delete
|
||||||
|
|
||||||
## 📝 更新日志
|
## 📝 更新日志
|
||||||
|
|
||||||
### v1.0.0 (2024-12-20)
|
> ⚠️ 版本对齐：git 发布线当前为 v0.9.9（无 v1.0.0 tag），下列 v1.0.0 为早期文案占位。详见 SDD `docs/sdd/releases/`。
|
||||||
|
|
||||||
|
### v1.0.0 (2024-12-20，遗留占位)
|
||||||
- ✨ 完整的 Docker 部署方案
|
- ✨ 完整的 Docker 部署方案
|
||||||
- ✨ 一键初始化和升级
|
- ✨ 一键初始化和升级
|
||||||
- ✨ 数据库备份恢复
|
- ✨ 数据库备份恢复
|
||||||
|
|
|
||||||
|
|
@ -231,7 +231,9 @@ npm run dev
|
||||||
|
|
||||||
## 🔄 版本历史
|
## 🔄 版本历史
|
||||||
|
|
||||||
### v1.0.0 (2023-12-20)
|
> ⚠️ 版本对齐：git 发布线为 v0.9.1 → v0.9.2 → v0.9.6 → v0.9.7 → v0.9.8 → v0.9.9（当前基线，提交 `416ef48`），仓库未打 tag。下列 v1.0.0 为早期文案占位，与 git 不符；详见 SDD `docs/sdd/releases/`。
|
||||||
|
|
||||||
|
### v1.0.0 (2023-12-20，遗留占位，见上方对齐说明)
|
||||||
|
|
||||||
- ✅ 完整的用户认证系统
|
- ✅ 完整的用户认证系统
|
||||||
- ✅ 项目管理功能
|
- ✅ 项目管理功能
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@ class Settings(BaseSettings):
|
||||||
|
|
||||||
# 应用信息
|
# 应用信息
|
||||||
APP_NAME: str = "NEX Docus"
|
APP_NAME: str = "NEX Docus"
|
||||||
APP_VERSION: str = "1.0.0"
|
APP_VERSION: str = "0.9.9"
|
||||||
DEBUG: bool = True
|
DEBUG: bool = True
|
||||||
|
|
||||||
# 服务器配置
|
# 服务器配置
|
||||||
|
|
|
||||||
|
|
@ -1,370 +0,0 @@
|
||||||
# 文档目录 Docker 部署方案
|
|
||||||
|
|
||||||
## 问题描述
|
|
||||||
|
|
||||||
应用中 `/design` 路由通过 `fetch('/docs/...')` 加载项目根目录下 `docs/` 文件夹中的 Markdown 文档。在 Docker 容器中运行时，需要确保这些文档能够被访问。
|
|
||||||
|
|
||||||
## 解决方案：Docker 卷挂载
|
|
||||||
|
|
||||||
采用 Docker 卷挂载方式，将宿主机的 `docs/` 目录直接映射到容器内，实现文档的实时更新和灵活管理。
|
|
||||||
|
|
||||||
### 配置方式
|
|
||||||
|
|
||||||
#### docker-compose.yml 配置
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: '3.8'
|
|
||||||
|
|
||||||
services:
|
|
||||||
nex-design:
|
|
||||||
build:
|
|
||||||
context: .
|
|
||||||
dockerfile: Dockerfile
|
|
||||||
volumes:
|
|
||||||
- ./logs:/app/logs # 日志目录挂载
|
|
||||||
- ./docs:/app/dist/docs:ro # 文档目录挂载（只读）
|
|
||||||
```
|
|
||||||
|
|
||||||
**说明：**
|
|
||||||
- `./docs:/app/dist/docs` - 将宿主机当前目录的 `docs` 映射到容器的 `/app/dist/docs`
|
|
||||||
- `:ro` - 只读挂载，提高安全性，防止容器内进程修改文档
|
|
||||||
|
|
||||||
### 方案优势
|
|
||||||
|
|
||||||
✅ **实时更新**
|
|
||||||
- 修改 MD 文件后立即生效
|
|
||||||
- 无需重新构建 Docker 镜像
|
|
||||||
- 无需重启容器
|
|
||||||
|
|
||||||
✅ **方便维护**
|
|
||||||
- 在宿主机直接编辑文档
|
|
||||||
- 使用熟悉的编辑器和工具
|
|
||||||
- 支持版本控制
|
|
||||||
|
|
||||||
✅ **轻量镜像**
|
|
||||||
- Docker 镜像不包含文档内容
|
|
||||||
- 镜像体积更小
|
|
||||||
- 构建速度更快
|
|
||||||
|
|
||||||
✅ **灵活部署**
|
|
||||||
- 可以独立管理文档版本
|
|
||||||
- 支持多环境部署（开发、测试、生产使用不同文档）
|
|
||||||
- 易于更新和回滚
|
|
||||||
|
|
||||||
### 目录结构
|
|
||||||
|
|
||||||
**宿主机：**
|
|
||||||
```
|
|
||||||
nex-design/
|
|
||||||
├── docs/ # 文档源文件（Git 管理）
|
|
||||||
│ ├── DESIGN_COOKBOOK.md
|
|
||||||
│ ├── components/
|
|
||||||
│ │ ├── PageTitleBar.md
|
|
||||||
│ │ ├── ListTable.md
|
|
||||||
│ │ └── ...
|
|
||||||
│ └── pages/
|
|
||||||
├── dist/ # 构建产物（容器内）
|
|
||||||
│ ├── index.html
|
|
||||||
│ └── assets/
|
|
||||||
└── docker-compose.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
**容器内：**
|
|
||||||
```
|
|
||||||
/app/
|
|
||||||
├── dist/ # 应用构建产物
|
|
||||||
│ ├── index.html
|
|
||||||
│ ├── assets/
|
|
||||||
│ └── docs/ # 挂载点 → 宿主机 docs/
|
|
||||||
├── logs/ # 日志目录（挂载）
|
|
||||||
└── ecosystem.config.js # PM2 配置
|
|
||||||
```
|
|
||||||
|
|
||||||
### 使用流程
|
|
||||||
|
|
||||||
#### 1. 启动服务
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 第一次启动（构建镜像）
|
|
||||||
docker-compose up -d --build
|
|
||||||
|
|
||||||
# 后续启动（使用已有镜像）
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 修改文档
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 在宿主机直接编辑文档
|
|
||||||
vim docs/DESIGN_COOKBOOK.md
|
|
||||||
|
|
||||||
# 或使用 VS Code 等编辑器
|
|
||||||
code docs/components/PageTitleBar.md
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. 验证更新
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 文档修改后立即生效，无需任何操作
|
|
||||||
# 浏览器刷新即可看到最新内容
|
|
||||||
|
|
||||||
# 或使用 curl 验证
|
|
||||||
curl http://localhost:3000/docs/DESIGN_COOKBOOK.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### 验证挂载
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 检查容器内的挂载情况
|
|
||||||
docker exec nex-design-app ls -la /app/dist/docs/
|
|
||||||
|
|
||||||
# 查看某个文档内容
|
|
||||||
docker exec nex-design-app cat /app/dist/docs/DESIGN_COOKBOOK.md
|
|
||||||
|
|
||||||
# 验证文件同步
|
|
||||||
# 在宿主机修改文件
|
|
||||||
echo "# Test" >> docs/test.md
|
|
||||||
|
|
||||||
# 立即在容器内查看
|
|
||||||
docker exec nex-design-app cat /app/dist/docs/test.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### 部署注意事项
|
|
||||||
|
|
||||||
#### 1. 生产环境部署
|
|
||||||
|
|
||||||
**方式一：携带 docs 目录**
|
|
||||||
```bash
|
|
||||||
# 使用 git clone 或 scp 上传整个项目
|
|
||||||
git clone <repo> /path/to/deploy
|
|
||||||
cd /path/to/deploy
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
**方式二：单独管理文档**
|
|
||||||
```bash
|
|
||||||
# 文档单独部署在某个目录
|
|
||||||
mkdir -p /var/www/nex-design-docs
|
|
||||||
# 上传文档到该目录
|
|
||||||
|
|
||||||
# 修改 docker-compose.yml
|
|
||||||
volumes:
|
|
||||||
- /var/www/nex-design-docs:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 权限管理
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 确保 docs 目录有正确的权限
|
|
||||||
chmod -R 755 docs/
|
|
||||||
|
|
||||||
# 只读挂载可防止容器内修改，但宿主机权限仍需控制
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. 多环境配置
|
|
||||||
|
|
||||||
可以为不同环境创建不同的 docker-compose 文件：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# docker-compose.dev.yml - 开发环境
|
|
||||||
volumes:
|
|
||||||
- ./docs:/app/dist/docs:ro
|
|
||||||
|
|
||||||
# docker-compose.prod.yml - 生产环境
|
|
||||||
volumes:
|
|
||||||
- /var/www/docs:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
使用时指定配置文件：
|
|
||||||
```bash
|
|
||||||
docker-compose -f docker-compose.prod.yml up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### 故障排查
|
|
||||||
|
|
||||||
#### 问题 1：文档无法加载
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 检查挂载是否成功
|
|
||||||
docker inspect nex-design-app | grep -A 10 Mounts
|
|
||||||
|
|
||||||
# 检查容器内文件
|
|
||||||
docker exec nex-design-app ls -la /app/dist/docs/
|
|
||||||
|
|
||||||
# 检查文件权限
|
|
||||||
ls -la docs/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 问题 2：修改后未生效
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 确认使用的是卷挂载而不是 COPY
|
|
||||||
docker exec nex-design-app cat /app/dist/docs/DESIGN_COOKBOOK.md
|
|
||||||
|
|
||||||
# 检查浏览器缓存
|
|
||||||
# 使用 Ctrl+Shift+R 强制刷新
|
|
||||||
|
|
||||||
# 检查 serve 是否缓存了静态文件
|
|
||||||
docker-compose restart
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 问题 3：Windows 路径问题
|
|
||||||
|
|
||||||
Windows 下需要注意路径格式：
|
|
||||||
```yaml
|
|
||||||
# 错误
|
|
||||||
volumes:
|
|
||||||
- .\docs:/app/dist/docs:ro
|
|
||||||
|
|
||||||
# 正确
|
|
||||||
volumes:
|
|
||||||
- ./docs:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
### 性能考虑
|
|
||||||
|
|
||||||
#### 1. 卷挂载性能
|
|
||||||
|
|
||||||
- **Linux/macOS**: 性能很好，几乎无损耗
|
|
||||||
- **Windows/macOS + Docker Desktop**: 可能有轻微性能损耗
|
|
||||||
- **生产环境**: 使用 Linux 主机，性能最佳
|
|
||||||
|
|
||||||
#### 2. 优化建议
|
|
||||||
|
|
||||||
如果文档很多且访问频繁，可考虑：
|
|
||||||
|
|
||||||
1. **使用命名卷**：
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
docs-data:
|
|
||||||
driver: local
|
|
||||||
driver_opts:
|
|
||||||
type: none
|
|
||||||
o: bind
|
|
||||||
device: /path/to/docs
|
|
||||||
|
|
||||||
services:
|
|
||||||
nex-design:
|
|
||||||
volumes:
|
|
||||||
- docs-data:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **缓存策略**：
|
|
||||||
在 Nginx 反向代理中添加缓存：
|
|
||||||
```nginx
|
|
||||||
location /docs/ {
|
|
||||||
proxy_pass http://nex_design;
|
|
||||||
proxy_cache_valid 200 10m;
|
|
||||||
add_header X-Cache-Status $upstream_cache_status;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 替代方案对比
|
|
||||||
|
|
||||||
### 方案 A: 构建时复制（未采用）
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
# Dockerfile
|
|
||||||
COPY docs /app/dist/docs
|
|
||||||
```
|
|
||||||
|
|
||||||
❌ 缺点：
|
|
||||||
- 修改文档需要重新构建镜像
|
|
||||||
- 镜像体积更大
|
|
||||||
- 更新流程复杂
|
|
||||||
|
|
||||||
✅ 优点：
|
|
||||||
- 镜像自包含
|
|
||||||
- 适合不常修改的场景
|
|
||||||
|
|
||||||
### 方案 B: prebuild 脚本（未采用）
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"scripts": {
|
|
||||||
"prebuild": "cp -r docs public/"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
❌ 缺点：
|
|
||||||
- 需要重新构建才能更新
|
|
||||||
- 增加构建时间
|
|
||||||
- 文档和代码耦合
|
|
||||||
|
|
||||||
### 方案 C: 卷挂载（✅ 当前采用）
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docs:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
✅ 优点：
|
|
||||||
- 实时更新
|
|
||||||
- 灵活管理
|
|
||||||
- 镜像轻量
|
|
||||||
|
|
||||||
⚠️ 注意：
|
|
||||||
- 需要保持 docs 目录结构
|
|
||||||
- 部署时需要文档文件
|
|
||||||
|
|
||||||
## 最佳实践
|
|
||||||
|
|
||||||
### 1. 文档版本管理
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 使用 Git 管理文档版本
|
|
||||||
cd docs
|
|
||||||
git log DESIGN_COOKBOOK.md
|
|
||||||
|
|
||||||
# 回滚到特定版本
|
|
||||||
git checkout <commit-hash> DESIGN_COOKBOOK.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 文档自动化部署
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
# scripts/update-docs.sh
|
|
||||||
|
|
||||||
echo "更新文档..."
|
|
||||||
cd /path/to/nex-design
|
|
||||||
|
|
||||||
# 拉取最新文档
|
|
||||||
git pull origin main -- docs/
|
|
||||||
|
|
||||||
# 无需重启容器，文档即时生效
|
|
||||||
echo "文档已更新！"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 监控文档访问
|
|
||||||
|
|
||||||
可以在 Nginx 中记录文档访问日志：
|
|
||||||
```nginx
|
|
||||||
location /docs/ {
|
|
||||||
access_log /var/log/nginx/docs-access.log;
|
|
||||||
proxy_pass http://nex_design;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 总结
|
|
||||||
|
|
||||||
使用 Docker 卷挂载方案是最灵活、最适合本项目的解决方案：
|
|
||||||
|
|
||||||
✅ **实时更新** - 修改即生效
|
|
||||||
✅ **简单维护** - 直接编辑文件
|
|
||||||
✅ **轻量镜像** - 更快的构建和部署
|
|
||||||
✅ **灵活部署** - 支持多种场景
|
|
||||||
|
|
||||||
**核心配置只需一行：**
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docs:/app/dist/docs:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
## 相关文件
|
|
||||||
|
|
||||||
- `docker-compose.yml:16` - 卷挂载配置
|
|
||||||
- `DEPLOYMENT.md:14-35` - 部署文档说明
|
|
||||||
- `QUICKSTART.md` - 快速参考
|
|
||||||
|
|
||||||
|
|
@ -1,297 +0,0 @@
|
||||||
# NexDocs MCP 使用文档
|
|
||||||
|
|
||||||
## 1. 方案说明
|
|
||||||
|
|
||||||
NexDocs 现在不再使用项目根目录下的独立 `mcp_server/`。
|
|
||||||
|
|
||||||
当前方案为后端内集成 MCP：
|
|
||||||
|
|
||||||
- 业务 REST API 继续走 `/api/v1/...`
|
|
||||||
- MCP 入口挂载在同一个 backend 服务上
|
|
||||||
- 传输协议为 `streamableHttp`
|
|
||||||
- MCP 地址为 `/mcp`（`/mcp/` 也兼容）
|
|
||||||
- 认证方式为 `X-Bot-Id` + `X-Bot-Secret`
|
|
||||||
|
|
||||||
这意味着：
|
|
||||||
|
|
||||||
- 不需要单独部署一套 MCP 服务
|
|
||||||
- 不需要让 MCP client 传业务账号密码
|
|
||||||
- 不需要让远程 agent 访问本地脚本进程
|
|
||||||
|
|
||||||
|
|
||||||
## 2. 接口地址
|
|
||||||
|
|
||||||
MCP 对外地址：
|
|
||||||
|
|
||||||
```text
|
|
||||||
http://<backend-host>:<backend-port>/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
例如：
|
|
||||||
|
|
||||||
```text
|
|
||||||
http://backend.internal:8000/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
说明：
|
|
||||||
|
|
||||||
- 推荐优先使用 `/mcp`
|
|
||||||
- `/mcp/` 也兼容
|
|
||||||
- 如果前面还有 Nginx/网关，请不要对 `/mcp` 做 `301`/`302` 重定向
|
|
||||||
- 未携带 bot 凭证时，访问 `/mcp` 或 `/mcp/` 都会返回 `401`
|
|
||||||
|
|
||||||
|
|
||||||
## 3. 认证模型
|
|
||||||
|
|
||||||
MCP client 只需要传两个 header：
|
|
||||||
|
|
||||||
- `X-Bot-Id`
|
|
||||||
- `X-Bot-Secret`
|
|
||||||
|
|
||||||
后端会执行以下逻辑：
|
|
||||||
|
|
||||||
1. 根据 `X-Bot-Id` 查询 `mcp_bots`
|
|
||||||
2. 校验 `X-Bot-Secret`
|
|
||||||
3. 将该 bot 映射到 NexDocs 用户
|
|
||||||
4. 以该用户身份执行 MCP 工具
|
|
||||||
|
|
||||||
因此 client 不需要再传：
|
|
||||||
|
|
||||||
- NexDocs 用户名
|
|
||||||
- NexDocs 密码
|
|
||||||
- NexDocs access token
|
|
||||||
|
|
||||||
|
|
||||||
## 4. 用户如何获取凭证
|
|
||||||
|
|
||||||
每个用户可在个人中心管理自己的 MCP 凭证。
|
|
||||||
|
|
||||||
页面位置：
|
|
||||||
|
|
||||||
1. 登录 NexDocs
|
|
||||||
2. 打开个人中心
|
|
||||||
3. 进入 `MCP 接入` 标签页
|
|
||||||
|
|
||||||
可执行操作：
|
|
||||||
|
|
||||||
- 查看 `X-Bot-Id`
|
|
||||||
- 查看并复制 `X-Bot-Secret`
|
|
||||||
- 重新生成 `X-Bot-Secret`
|
|
||||||
|
|
||||||
后端接口：
|
|
||||||
|
|
||||||
- `GET /api/v1/auth/mcp-credentials`
|
|
||||||
- `POST /api/v1/auth/mcp-credentials/rotate-secret`
|
|
||||||
|
|
||||||
|
|
||||||
## 5. 当前支持的 MCP Tools
|
|
||||||
|
|
||||||
### 5.1 获取当前用户创建的项目列表
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
list_created_projects
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `keyword`: 可选，按项目名/描述过滤
|
|
||||||
- `limit`: 可选，默认 100
|
|
||||||
|
|
||||||
|
|
||||||
### 5.2 获取指定项目文件树
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
get_project_tree
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `project_id`: 必填
|
|
||||||
|
|
||||||
|
|
||||||
### 5.3 获取指定文件内容
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
get_file
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `project_id`: 必填
|
|
||||||
- `path`: 必填，项目内相对路径
|
|
||||||
|
|
||||||
|
|
||||||
### 5.4 在项目中创建新文件
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
create_file
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `project_id`: 必填
|
|
||||||
- `path`: 必填，项目内相对路径
|
|
||||||
- `content`: 可选，文件初始内容，默认空字符串
|
|
||||||
|
|
||||||
说明：
|
|
||||||
|
|
||||||
- 目标路径已存在时会报错
|
|
||||||
- 会自动创建缺失的上级目录
|
|
||||||
- 会校验项目写权限
|
|
||||||
- 写入 Markdown 文件时会更新搜索索引
|
|
||||||
- 会记录操作日志
|
|
||||||
- 会通知项目成员
|
|
||||||
|
|
||||||
|
|
||||||
### 5.5 修改指定文件
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
update_file
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `project_id`: 必填
|
|
||||||
- `path`: 必填，项目内相对路径
|
|
||||||
- `content`: 必填，新的文件内容
|
|
||||||
|
|
||||||
说明：
|
|
||||||
|
|
||||||
- 目标文件不存在时会报错
|
|
||||||
- 只允许更新文件，不允许更新目录
|
|
||||||
- 会校验项目写权限
|
|
||||||
- 写入 Markdown 文件时会更新搜索索引
|
|
||||||
- 会记录操作日志
|
|
||||||
- 会通知项目成员
|
|
||||||
|
|
||||||
|
|
||||||
### 5.6 删除指定文件
|
|
||||||
|
|
||||||
工具名：
|
|
||||||
|
|
||||||
```text
|
|
||||||
delete_file
|
|
||||||
```
|
|
||||||
|
|
||||||
参数：
|
|
||||||
|
|
||||||
- `project_id`: 必填
|
|
||||||
- `path`: 必填，项目内相对路径
|
|
||||||
|
|
||||||
说明：
|
|
||||||
|
|
||||||
- 目标文件不存在时会报错
|
|
||||||
- 只允许删除文件，不允许删除目录
|
|
||||||
- 删除 Markdown 文件时会同步删除搜索索引
|
|
||||||
- 会记录操作日志
|
|
||||||
- 会通知项目成员
|
|
||||||
|
|
||||||
|
|
||||||
## 6. 调用端配置示例
|
|
||||||
|
|
||||||
如果调用端内置的是 MCP client，并支持 `streamableHttp`，可以这样配置：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"tools": {
|
|
||||||
"mcpServers": {
|
|
||||||
"biz_mcp": {
|
|
||||||
"type": "streamableHttp",
|
|
||||||
"url": "http://backend.internal:8000/mcp",
|
|
||||||
"headers": {
|
|
||||||
"X-Bot-Id": "nexbot_xxxxxxxxxxxxxxxx",
|
|
||||||
"X-Bot-Secret": "nxbotsec_xxxxxxxxxxxxxxxxxxxxxxxx"
|
|
||||||
},
|
|
||||||
"toolTimeout": 60
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
注意：
|
|
||||||
|
|
||||||
- `url` 建议使用 `/mcp`
|
|
||||||
- `headers` 中不需要再放业务用户名密码
|
|
||||||
- `X-Bot-Secret` 只应发给受信任的调用端
|
|
||||||
- 如果客户端运行在浏览器环境，记得把对应站点加入后端 `CORS_ORIGINS`
|
|
||||||
|
|
||||||
|
|
||||||
## 7. 后端部署要求
|
|
||||||
|
|
||||||
### 7.1 Python 版本
|
|
||||||
|
|
||||||
后端运行环境需要 Python 3.12。
|
|
||||||
|
|
||||||
本地开发建议：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
/opt/homebrew/bin/python3.12 -m venv venv312
|
|
||||||
env -u HTTP_PROXY -u HTTPS_PROXY ./venv312/bin/pip install -r requirements.txt
|
|
||||||
./venv312/bin/uvicorn main:app --host 0.0.0.0 --port 8000
|
|
||||||
```
|
|
||||||
|
|
||||||
说明：
|
|
||||||
|
|
||||||
- 当前 backend 的 MCP 依赖要求 Python 3.10+
|
|
||||||
- 本项目已在本地按 Python 3.12 调试通过
|
|
||||||
|
|
||||||
|
|
||||||
### 7.2 Docker
|
|
||||||
|
|
||||||
`backend/Dockerfile` 已切换到 Python 3.12 基线。
|
|
||||||
|
|
||||||
|
|
||||||
### 7.3 数据表
|
|
||||||
|
|
||||||
`mcp_bots` 表需要存在。
|
|
||||||
|
|
||||||
如果你已经执行过建表脚本，这一步可以跳过。
|
|
||||||
|
|
||||||
相关文件：
|
|
||||||
|
|
||||||
- [create_mcp_bots_table.sql](/Users/jiliu/工作/projects/NexDocus/backend/scripts/create_mcp_bots_table.sql)
|
|
||||||
- [init_database.sql](/Users/jiliu/工作/projects/NexDocus/backend/scripts/init_database.sql)
|
|
||||||
|
|
||||||
|
|
||||||
## 8. 已验证结果
|
|
||||||
|
|
||||||
本地调试已验证：
|
|
||||||
|
|
||||||
- Python 3.12 环境可正常启动 backend
|
|
||||||
- `/health` 返回 `200`
|
|
||||||
- `/mcp` 与 `/mcp/` 均可访问
|
|
||||||
- 未传 `X-Bot-Id` / `X-Bot-Secret` 时返回 `401`
|
|
||||||
|
|
||||||
调试使用地址：
|
|
||||||
|
|
||||||
```text
|
|
||||||
http://127.0.0.1:8012/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
生产或测试环境请替换为你的 backend 实际域名或 IP。
|
|
||||||
|
|
||||||
|
|
||||||
## 9. 相关代码位置
|
|
||||||
|
|
||||||
- MCP 挂载入口：
|
|
||||||
[main.py](/Users/jiliu/工作/projects/NexDocus/backend/main.py)
|
|
||||||
- MCP 服务实现：
|
|
||||||
[server.py](/Users/jiliu/工作/projects/NexDocus/backend/app/mcp/server.py)
|
|
||||||
- MCP Bot 模型：
|
|
||||||
[mcp_bot.py](/Users/jiliu/工作/projects/NexDocus/backend/app/models/mcp_bot.py)
|
|
||||||
- 用户凭证管理接口：
|
|
||||||
[auth.py](/Users/jiliu/工作/projects/NexDocus/backend/app/api/v1/auth.py)
|
|
||||||
- 个人中心凭证管理页面：
|
|
||||||
[ProfilePage.jsx](/Users/jiliu/工作/projects/NexDocus/frontend/src/pages/Profile/ProfilePage.jsx)
|
|
||||||
|
|
@ -1,61 +0,0 @@
|
||||||
# 文档迁移说明
|
|
||||||
|
|
||||||
## 📦 按钮扩展组件文档已迁移
|
|
||||||
|
|
||||||
原 `docs/` 目录下的按钮扩展相关文档已整合并迁移至：
|
|
||||||
|
|
||||||
**新位置：** `src/components/docs/ButtonExtensions.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🗂️ 迁移的文档
|
|
||||||
|
|
||||||
以下文档已整合到新文档中：
|
|
||||||
|
|
||||||
| 原文档 | 状态 |
|
|
||||||
|--------|------|
|
|
||||||
| ~~ButtonHelpDesign.md~~ | ✅ 已整合 |
|
|
||||||
| ~~ButtonDesignFixes.md~~ | ✅ 已整合 |
|
|
||||||
| ~~ButtonDesignUpdate.md~~ | ✅ 已整合 |
|
|
||||||
| ~~ButtonDesignLatestFixes.md~~ | ✅ 已整合 |
|
|
||||||
| ~~ActionHelpPanelFix.md~~ | ✅ 已整合 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📖 新文档包含
|
|
||||||
|
|
||||||
- ✅ 5种设计方案完整说明
|
|
||||||
- ✅ 所有组件的API文档
|
|
||||||
- ✅ 详细的使用指南和示例
|
|
||||||
- ✅ 最佳实践和性能优化建议
|
|
||||||
- ✅ 完整的更新日志和变更记录
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔗 快速链接
|
|
||||||
|
|
||||||
- **文档路径：** `/src/components/docs/ButtonExtensions.md`
|
|
||||||
- **在线演示：** http://localhost:5173/design/button-designs
|
|
||||||
- **菜单路径：** 组件设计 → 扩展按钮
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📅 迁移时间
|
|
||||||
|
|
||||||
**2025-11-17** - 所有文档已完成整合
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 文档组织原则
|
|
||||||
|
|
||||||
今后组件文档将遵循以下原则：
|
|
||||||
|
|
||||||
1. **统一位置** - 所有组件文档放在 `src/components/docs/`
|
|
||||||
2. **就近原则** - 文档与组件代码保持近距离
|
|
||||||
3. **单一文档** - 同一功能的文档整合到一个文件
|
|
||||||
4. **版本控制** - 使用版本号和更新日志记录变更
|
|
||||||
|
|
||||||
这样可以：
|
|
||||||
- ✅ 更容易找到和维护文档
|
|
||||||
- ✅ 避免文档分散和重复
|
|
||||||
- ✅ 与代码保持同步更新
|
|
||||||
|
|
@ -1,184 +0,0 @@
|
||||||
# NexDocs v0.9.6 升级日志
|
|
||||||
|
|
||||||
## 版本信息
|
|
||||||
|
|
||||||
- 版本号：`v0.9.6`
|
|
||||||
- 更新时间：`2026-03-11`
|
|
||||||
|
|
||||||
|
|
||||||
## 本次升级摘要
|
|
||||||
|
|
||||||
`v0.9.6` 主要完成了以下升级：
|
|
||||||
|
|
||||||
1. 新增后端内集成的 MCP Server 能力
|
|
||||||
2. 新增用户级 MCP 凭证管理
|
|
||||||
3. 打通通过 Nginx 统一入口访问 MCP
|
|
||||||
4. 调整部署运行环境到 Python 3.12
|
|
||||||
5. 将 MySQL、Redis 数据目录改为项目根目录 `storage/` 持久化
|
|
||||||
6. 优化个人中心与文档页面部分交互体验
|
|
||||||
|
|
||||||
|
|
||||||
## 功能升级
|
|
||||||
|
|
||||||
### 1. MCP Server 内集成
|
|
||||||
|
|
||||||
系统已支持直接在 backend 中提供 MCP `streamableHttp` 服务，不再依赖项目根目录下的独立 `mcp_server/` 进程。
|
|
||||||
|
|
||||||
当前 MCP 入口：
|
|
||||||
|
|
||||||
```text
|
|
||||||
/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
当前支持的工具：
|
|
||||||
|
|
||||||
1. `list_created_projects`：列出当前用户的项目
|
|
||||||
2. `get_project_tree`：列出项目文件树结构
|
|
||||||
3. `get_file`：获取指定文件
|
|
||||||
4. `create_file`：在项目中创建新文件
|
|
||||||
5. `update_file`：修改指定文件
|
|
||||||
6. `delete_file`：删除指定文件
|
|
||||||
|
|
||||||
|
|
||||||
### 2. MCP 认证与用户凭证管理
|
|
||||||
|
|
||||||
新增基于 `X-Bot-Id` 和 `X-Bot-Secret` 的 MCP 认证模型。
|
|
||||||
|
|
||||||
能力包括：
|
|
||||||
|
|
||||||
- 每个用户可拥有自己的 MCP 凭证
|
|
||||||
- 通过数据库表 `mcp_bots` 维护 bot 与用户的映射
|
|
||||||
- 支持在个人中心查看和重新生成凭证
|
|
||||||
- 服务端自动按凭证映射到对应 NexDocs 用户身份执行工具
|
|
||||||
|
|
||||||
相关接口：
|
|
||||||
|
|
||||||
- `GET /api/v1/auth/mcp-credentials`
|
|
||||||
- `POST /api/v1/auth/mcp-credentials/rotate-secret`
|
|
||||||
|
|
||||||
|
|
||||||
### 3. Nginx 统一入口支持 MCP
|
|
||||||
|
|
||||||
前端 Nginx 已新增 `/mcp` 与 `/mcp/` 兼容的反向代理配置。
|
|
||||||
|
|
||||||
现在在只暴露一个公网入口端口的部署模式下，可以通过统一入口访问：
|
|
||||||
|
|
||||||
```text
|
|
||||||
http(s)://<host>/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
不再要求调用端直连 backend 容器端口。
|
|
||||||
|
|
||||||
|
|
||||||
## 前端与交互优化
|
|
||||||
|
|
||||||
### 1. 个人中心布局调整
|
|
||||||
|
|
||||||
个人中心由上下结构调整为左右结构：
|
|
||||||
|
|
||||||
- 左侧为纵向导航
|
|
||||||
- 右侧为内容区域
|
|
||||||
- 移动端会自动回退为上下布局
|
|
||||||
|
|
||||||
|
|
||||||
### 2. 文档浏览/编辑切换优化
|
|
||||||
|
|
||||||
本轮已对项目文档页做过一组交互统一：
|
|
||||||
|
|
||||||
- 浏览/编辑模式切换样式统一
|
|
||||||
- 页面头部高度与操作区对齐
|
|
||||||
- 切换时保留当前文件上下文
|
|
||||||
- 登录跳转回原目标页的逻辑补齐
|
|
||||||
|
|
||||||
|
|
||||||
### 3. 认证异常提示优化
|
|
||||||
|
|
||||||
对未登录和 token 失效场景做了重复错误提示抑制：
|
|
||||||
|
|
||||||
- 避免并发请求弹出多条重复 Toast
|
|
||||||
- 统一 401 处理与跳转逻辑
|
|
||||||
|
|
||||||
|
|
||||||
## 部署与运行环境变更
|
|
||||||
|
|
||||||
### 1. Python 运行环境升级
|
|
||||||
|
|
||||||
backend 运行环境已调整为：
|
|
||||||
|
|
||||||
```text
|
|
||||||
Python 3.12
|
|
||||||
```
|
|
||||||
|
|
||||||
原因：
|
|
||||||
|
|
||||||
- MCP Python SDK 需要 Python 3.10+
|
|
||||||
- 当前版本已按 Python 3.12 完成调试与验证
|
|
||||||
|
|
||||||
|
|
||||||
### 2. Docker 构建链调整
|
|
||||||
|
|
||||||
backend Docker 镜像构建已做以下处理：
|
|
||||||
|
|
||||||
- 基础镜像切换为 `python:3.12-slim`
|
|
||||||
- 增加 pip 构建工具升级
|
|
||||||
- pip 安装支持国内源失败后回退官方源
|
|
||||||
- Nginx 已补充 `/mcp` 与 `/mcp/` 兼容代理配置
|
|
||||||
|
|
||||||
|
|
||||||
### 3. 数据持久化目录调整
|
|
||||||
|
|
||||||
本次升级将 MySQL、Redis 的数据目录改为挂载到项目根目录下的 `storage/`：
|
|
||||||
|
|
||||||
```text
|
|
||||||
storage/
|
|
||||||
├── mysql/
|
|
||||||
├── redis/
|
|
||||||
├── projects/
|
|
||||||
└── temp/
|
|
||||||
```
|
|
||||||
|
|
||||||
当前挂载关系：
|
|
||||||
|
|
||||||
- `storage/mysql -> /var/lib/mysql`
|
|
||||||
- `storage/redis -> /data`
|
|
||||||
- `storage -> /data/nex_docus_store`
|
|
||||||
|
|
||||||
这样做的目的：
|
|
||||||
|
|
||||||
- 宿主机可直接看到数据库与缓存数据目录
|
|
||||||
- 便于整体备份
|
|
||||||
- 避免数据只留在 Docker named volume 中
|
|
||||||
|
|
||||||
|
|
||||||
## 升级迁移注意事项
|
|
||||||
|
|
||||||
### 1. MCP 调用地址调整
|
|
||||||
|
|
||||||
如果原先通过 backend 端口直连 MCP，可以继续使用。
|
|
||||||
|
|
||||||
如果当前部署是通过前端 Nginx 暴露统一入口，推荐改为：
|
|
||||||
|
|
||||||
```text
|
|
||||||
http(s)://<host>/mcp
|
|
||||||
```
|
|
||||||
|
|
||||||
调用头保持不变：
|
|
||||||
|
|
||||||
- `X-Bot-Id`
|
|
||||||
- `X-Bot-Secret`
|
|
||||||
|
|
||||||
|
|
||||||
### 部署与文档
|
|
||||||
|
|
||||||
- [docker-compose.yml](/Users/jiliu/工作/projects/NexDocus/docker-compose.yml)
|
|
||||||
- [MCP_HTTP_INTEGRATION.md](/Users/jiliu/工作/projects/NexDocus/docs/MCP_HTTP_INTEGRATION.md)
|
|
||||||
|
|
||||||
|
|
||||||
## 升级建议
|
|
||||||
|
|
||||||
建议升级到 `v0.9.6` 后按以下顺序验证：
|
|
||||||
|
|
||||||
1. 验证 backend `/health` 是否正常
|
|
||||||
2. 验证统一入口 `/api/`、`/mcp` 与 `/mcp/` 是否可访问
|
|
||||||
3. 验证 MCP client 是否能正常完成 `initialize`
|
|
||||||
4. 验证个人中心的 MCP 凭证展示与轮换功能
|
|
||||||
|
|
@ -0,0 +1,79 @@
|
||||||
|
# NEX Docus – 规格驱动开发（SDD）中心
|
||||||
|
|
||||||
|
本目录是 NEX Docus **规格驱动的开发中心**（Spec-Driven Development）。它把「产品意图 → 架构决策 → 功能规格 → 实施任务 → 验证证据」放进同一条可追踪链路，并作为团队讨论、开发与验收的**唯一真相源（single source of truth）**。
|
||||||
|
|
||||||
|
## 文档结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
docs/sdd/
|
||||||
|
├── README.md # 入口、状态与工作流（本文件）
|
||||||
|
├── governance.md # 编号、审批、变更与追踪规则
|
||||||
|
├── archive.md # 遗留文档归档说明（整合/弃置追踪）
|
||||||
|
├── product/
|
||||||
|
│ ├── vision.md # 产品愿景、用户与边界
|
||||||
|
│ ├── principles.md # 产品与工程原则
|
||||||
|
│ └── roadmap.md # 阶段性路线图
|
||||||
|
├── architecture/
|
||||||
|
│ ├── overview.md # 当前架构方向与系统边界
|
||||||
|
│ ├── constraints.md # 已知约束与待决事项
|
||||||
|
│ ├── standards/
|
||||||
|
│ │ ├── README.md # 代码结构规范索引
|
||||||
|
│ │ ├── code-structure-standards.md # 代码结构规范（整合自 docs/）
|
||||||
|
│ │ └── code-structure-audit-2026-04-08.md # 结构审计记录（整合自 docs/）
|
||||||
|
│ └── decisions/
|
||||||
|
│ ├── README.md # ADR 索引与规则
|
||||||
|
│ └── ADR-0001-*.md # 持久架构决策（逐条一文件）
|
||||||
|
├── integrations/
|
||||||
|
│ ├── mcp.md # MCP Streamable HTTP 接入（含详细使用文档）
|
||||||
|
│ └── git.md # 项目 Git 仓库集成
|
||||||
|
├── releases/
|
||||||
|
│ ├── README.md # 公开版本与资产索引
|
||||||
|
│ ├── v0.9.6.md # v0.9.6 历史升级记录（整合自 docs/）
|
||||||
|
│ └── v0.9.9.md # 当前基线发布（对齐 git）
|
||||||
|
└── specs/
|
||||||
|
├── README.md # 功能规格索引
|
||||||
|
├── _template/ # 新规格模板
|
||||||
|
└── DV-NNNN-short-name/ # 一个功能或变更单元（spec/design/tasks/verification）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 当前状态（Status）
|
||||||
|
|
||||||
|
- **SDD 文档状态**：基线（Baseline）· 对齐 git 当前版本 v0.9.9
|
||||||
|
- **适用代码基线**：当前仓库（backend + frontend + docker-compose 部署）
|
||||||
|
- **规格覆盖**：11 个功能单元（DV-0001 ~ DV-0011）；价值主张 PO-1~5；架构决策 ADR-0001~0008
|
||||||
|
- **已知整改项**：见 governance「开放问题」与各规格 tasks.md 中的“待整改/待决”标记（如敏感日志脱敏 TS-12、Compose v2 官方化 TS-13）
|
||||||
|
- **版本基线**：以 git 为准（当前 v0.9.9；见 releases/README.md 与 v0.9.9.md 版本对齐说明；代码字段 1.0.0 为遗留占位）
|
||||||
|
|
||||||
|
## 如何使用本中心（工作流）
|
||||||
|
|
||||||
|
### 读者
|
||||||
|
| 角色 | 入口 |
|
||||||
|
| --- | --- |
|
||||||
|
| 产品/方案 | `product/vision.md`、`product/roadmap.md` |
|
||||||
|
| 架构评审 | `architecture/overview.md`、`architecture/standards/README.md`、`architecture/decisions/README.md` |
|
||||||
|
| 功能负责人 | `specs/README.md` → 对应 `DV-NNNN/spec.md` |
|
||||||
|
| 开发 | `DV-NNNN/design.md` + `tasks.md` |
|
||||||
|
| 测试/验收 | `DV-NNNN/verification.md` |
|
||||||
|
| 发布 | `releases/README.md` |
|
||||||
|
| 遗留文档去向 | `archive.md` |
|
||||||
|
|
||||||
|
### 作者（新增/改功能）
|
||||||
|
1. 在 `governance.md` 读取编号规则，申请下一个规格编号（DV-NNNN）与 ADR 编号。
|
||||||
|
2. 复制 `specs/_template/` 到 `specs/DV-NNNN-short-name/`，先写 `spec.md`（为什么、做什么）。
|
||||||
|
3. 评审通过后写 `design.md`；实现过程中维护 `tasks.md` 勾选切片。
|
||||||
|
4. 完成后在 `verification.md` 登记验收证据，并回填 `specs/README.md` 索引。
|
||||||
|
5. 涉及跨文件刚性承诺（ADR）变更的，走 `architecture/decisions` 审批。
|
||||||
|
|
||||||
|
### 最小变更（bug 修复）
|
||||||
|
- 若属于既有 DV 规格范围：直接在该单元 `tasks.md` 追加切片并更新 `verification.md`。
|
||||||
|
- 若超出所有现有范围：新建 DV 规格。
|
||||||
|
|
||||||
|
## 与外部文档的关系
|
||||||
|
|
||||||
|
SDD 中心**汇总并指向**仓库既有的详细材料，而非重复复制全部内容：
|
||||||
|
- 数据库细节 → 仓库根 `DATABASE.md`（SDD 只保留 ER 概览与规格化的链路表）
|
||||||
|
- 部署运维 → `DEPLOY.md`、`README_DOCKER.md`、`CHANGELOG_DEPLOY.md`（及已并入的 docs/DOCKER_DOCS_SETUP 历史，见 archive.md）
|
||||||
|
- 历史变更 → `docs/UPGRADE_v0.9.6.md`、`docs/MIGRATION.md`（已整合/弃置，见 archive.md）
|
||||||
|
- 结构规范 → `architecture/standards/`（原 docs/code-structure-* 已迁入）
|
||||||
|
|
||||||
|
> 本中心是入口与追踪层；具体逐表 DDL、逐配置项说明等细节仍以被指向的源文档为准。
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
# 约束与待决事项（Constraints & Open Points）
|
||||||
|
|
||||||
|
## 技术约束（当前代码库既定）
|
||||||
|
1. **Python 3.12 + FastAPI 0.109**：异步栈；`requirements.txt` 固定大部分版本。
|
||||||
|
2. **SQLAlchemy 2.0（async）+ aiomysql**；同步连接供 Alembic 风格脚本（pymysql）。
|
||||||
|
3. **MySQL 5.7.5+ / 生产镜像 MySQL 8.0**，utf8mb4。
|
||||||
|
4. **Redis**：Token 缓存、会话状态、通知等。
|
||||||
|
5. **JWT**（python-jose HS256）+ **bcrypt**（passlib）。
|
||||||
|
6. **前端 React 18 + Vite 5 + Ant Design 5 + Tailwind + Zustand**；路由 React Router v6。
|
||||||
|
7. **Whoosh3**（全文）+ **ZVec**（向量）+ **jieba**（中文分词）。
|
||||||
|
8. **WeasyPrint**（PDF 导出）、**pdfjs-dist/react-pdf**（前端 PDF 预览）、**react-virtuoso/react-window**（虚拟列表）。
|
||||||
|
9. **部署**：Docker Compose v2 + Engine ≥ 25（ADR-0008）。
|
||||||
|
|
||||||
|
## 约束来源
|
||||||
|
- 依赖锁定：`backend/requirements.txt`、`frontend/package.json`。
|
||||||
|
- 配置默认：`backend/app/core/config.py`、`.env.example`、`docker-compose.yml`。
|
||||||
|
|
||||||
|
## 待决事项（Open Points）
|
||||||
|
| 编号 | 事项 | 现状 | 建议 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| OP-1 | Alembic vs 幂等 ALTER | 采用幂等 ALTER（`migrations.py`） | 评估引入 Alembic 以支撑大规模结构变更 |
|
||||||
|
| OP-2 | 敏感日志 | `security.py`/`deps.py` 记录 SECRET_KEY 前缀/JWT 载荷 | 脱敏，见 OI-1 |
|
||||||
|
| OP-3 | Compose v2 官方化 | deploy.sh 探测 v2 但根文档仍提及 v1 | 统一 v2 路径，见 OI-2 |
|
||||||
|
| OP-4 | 测试覆盖 | 仅 3 个后端单测 | 增加集成/E2E，见 OI-3 |
|
||||||
|
| OP-5 | 实时协同编辑 | 明确不在此版本做（vision 边界） | 另立项评估 OT/CRDT |
|
||||||
|
| OP-6 | 多实例/高可用 | 单机部署，无状态服务仅后端（Redis/DB 独立） | 若需要再评估 |
|
||||||
|
|
||||||
|
## 约束的规格化引用
|
||||||
|
- 以上条目若成为刚性承诺，须固化为 ADR 并登记到 `decisions/README.md`。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# ADR-0001：混合架构「DB 权限 + FS 内容」
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
- **日期**：对应仓库基线
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
需要平衡权限管理的可控性与内容数据的可迁移/透明性。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
结构化元数据（用户/项目/权限/菜单/日志/向量状态等）存 MySQL；文档内容、图片、附件以原生文件存于服务器磁盘（`STORAGE_ROOT` 下 `projects/<storage_key>`）。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 正向：文件即真理，备份/迁移只需拷贝目录 + 导出 DB。
|
||||||
|
- 代价：需要自行实现严格的路径安全校验（见 DV-0002 / NFR-3）。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
PO-1, PO-2, PO-3；DV-0002；NFR-3。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# ADR-0002：磁盘目录用 UUID（storage_key）映射
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
中文文件名、重名项目在文件系统层面易出乱码与冲突。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
磁盘文件夹名使用 `storage_key`（UUID，36 字符），数据库 `projects.storage_key` 保存映射；对外展示名 `projects.name` 与磁盘名解耦。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 展示名可随时改，磁盘标识不变。
|
||||||
|
- 资源路径以 uuid 为根，天然隔离且无中文。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0002。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# ADR-0003：技术栈选型
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
- **后端**：Python 3.12 + FastAPI（异步）+ SQLAlchemy 2.0（async）+ aiomysql/PyMySQL + Redis（aioredis）+ JWT（python-jose/bcrypt）+ Uvicorn。
|
||||||
|
- **前端**：React 18 + Vite 5 + Ant Design 5 + Tailwind + Zustand + React Router v6；Markdown bytemd；PDF pdfjs-dist/react-pdf；虚拟列表 react-virtuoso/react-window。
|
||||||
|
- **搜索/向量**：Whoosh3 + jieba（全文）；ZVec + 可配置 embedding（语义）。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
依赖锁定在 `requirements.txt` 与 `package.json`；更换组件须评审。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
全部 DV。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# ADR-0004：全文（Whoosh）+ 语义（ZVec）双检索引擎
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
既需要全文关键词检索，又需要语义向量检索支撑 RAG。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
1. 全文检索：Whoosh3 本地索引（`search_index`），中文自定义 `ChineseAnalyzer`（基于 jieba）。
|
||||||
|
2. 语义向量：ZVec 本地向量库（`vector_index`，每项目一个 collection）+ 可配置 embedding 模型（LLMModelConfig 的 `model_type=embedding`）。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 两套索引需在文件变更时同步维护（ADR-0006）。
|
||||||
|
- 向量维度变更时需重建 collection 并全量重向量化。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0005, DV-0006, DV-0007。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# ADR-0005：RAG 答案可溯源（编号引用 + 支撑句对齐）
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
- 每条知识使用必须紧跟 `[n]` 编号引用。
|
||||||
|
- 采用“答案论断句 ↔ 原文候选句”向量对齐（`align_citation_quotes`），为每次 `[n]` 出现回填支撑句（`quote_occurrences`）。
|
||||||
|
- 同文件多个分块命中在展示层合并为同一 `citation_id` 并重新编号（`_canonicalize_message_citations`）。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 提升可验证性，但依赖 embedding 可用；对齐失败时降级为不返回支撑句（NFR-10）。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0007, DV-0011。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# ADR-0006：写路径异步索引同步
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
文件变更（创建/修改/删除/移动）需同步维护向量索引与全文索引，但不能阻塞主请求线程。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
文件操作经 `ProjectFileService` → `FileVectorSyncService`（独立 DB 会话、按项目串行、后台 `asyncio.Task`）触发 ZVec 重向量化/删除；全文索引经 `search_service` 同步更新。整项目向量化走 `ProjectVectorizationTaskService`（后台任务 + 进度表）。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 写请求返回快，索引最终一致。
|
||||||
|
- 需处理并发同一项目的串行化与任务去重。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0002, DV-0006, DV-0010。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# ADR-0007：轻量幂等数据库迁移（非破坏性）
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
项目未引入 Alembic 可执行迁移链。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
启动时（lifespan）执行 `migrate_schema()`：查询 `information_schema` 判断列是否存在，仅对缺失列执行幂等 `ALTER TABLE`。只做“新增列”这类非破坏性变更。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 多实例/重复启动安全。
|
||||||
|
- 大规模结构变更缺少回放/回滚（见 OP-1 / OI-4）。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0010, NFR-7。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# ADR-0008：部署仅支持 Docker Compose v2 + Engine ≥ 25
|
||||||
|
|
||||||
|
- **状态**：Accepted
|
||||||
|
- **触发背景**：服务器上旧版 docker-compose v1（Python 实现）在 Docker Engine 25+ 上因读取 `ContainerConfig` 字段崩溃（`KeyError: 'ContainerConfig'`）。
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
仅支持 **Docker Compose v2**（`docker compose` 子命令）部署；弃用 v1。`deploy.sh` 中 `get_compose_cmd` 优先探测 v2，回退 v1 仅作兼容提示。
|
||||||
|
|
||||||
|
## 后果
|
||||||
|
- 升级路径：安装 `docker-compose-plugin`（v2）并卸载 v1 后即可用 `./deploy.sh upgrade` 或 `docker compose up -d --build`。
|
||||||
|
- `docker-compose.yml` 顶部 `version:` 仅产生弃用警告，不影响功能。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
NFR-6, OI-2；部署细节见 `DEPLOY.md`、`README_DOCKER.md`。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
# ADR 索引与规则（Architecture Decision Records）
|
||||||
|
|
||||||
|
## 规则
|
||||||
|
- 每个持久架构决策一个文件：`ADR-NNNN-简短名称.md`。
|
||||||
|
- 内容固定：**背景 / 决策 / 后果 / 状态 / 关联规格**。
|
||||||
|
- 状态：`Proposed → Accepted → Deprecated / Superseded by ADR-NNNN`。
|
||||||
|
- 变更已 Accepted 的 ADR 须走 governance 审批矩阵。
|
||||||
|
|
||||||
|
## 索引
|
||||||
|
|
||||||
|
| ADR | 标题 | 状态 | 关联规格 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| [ADR-0001](ADR-0001-hybrid-storage.md) | 混合架构：DB 权限 + FS 内容 | Accepted | PO-1/2/3, DV-0002 |
|
||||||
|
| [ADR-0002](ADR-0002-uuid-storage-key.md) | 磁盘目录用 UUID（storage_key）映射 | Accepted | DV-0002 |
|
||||||
|
| [ADR-0003](ADR-0003-tech-stack.md) | 技术栈选型（FastAPI/React/SQLAlchemy/Redis/JWT） | Accepted | 全部 DV |
|
||||||
|
| [ADR-0004](ADR-0004-dual-search-engine.md) | 全文（Whoosh）+ 语义（ZVec）双检索引擎 | Accepted | DV-0005/0006/0007 |
|
||||||
|
| [ADR-0005](ADR-0005-rag-citations.md) | RAG 答案可溯源：编号引用 + 支撑句对齐 | Accepted | DV-0007/0011 |
|
||||||
|
| [ADR-0006](ADR-0006-async-index-sync.md) | 写路径异步索引同步（后台任务） | Accepted | DV-0002/0006/0010 |
|
||||||
|
| [ADR-0007](ADR-0007-idempotent-migrations.md) | 轻量幂等数据库迁移（非 Alembic） | Accepted | DV-0010, NFR-7 |
|
||||||
|
| [ADR-0008](ADR-0008-compose-v2.md) | 部署仅支持 Docker Compose v2 + Engine ≥ 25 | Accepted | NFR-6, DV-0000(部署) |
|
||||||
|
|
||||||
|
> 注：DV-0000 为「部署/环境」逻辑单元，对应 NFR-6/ADR-0008，不生成独立功能规格文件，仅作追踪占位。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,42 @@
|
||||||
|
# 架构概览（Overview）
|
||||||
|
|
||||||
|
## 系统定位
|
||||||
|
|
||||||
|
NEX Docus 是**单机可部署**的团队文档平台，后端 FastAPI 单体 + 前端 React SPA + MySQL + Redis + 本地文件系统 + 本地检索/向量引擎，全部由 docker-compose 编排为同网段容器。
|
||||||
|
|
||||||
|
## 逻辑架构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
Client[React SPA] -->|JSON/HTTP| API[FastAPI Backend :8000]
|
||||||
|
Agent[External Agent] -->|MCP streamableHttp| API
|
||||||
|
API --> DB[(MySQL)]
|
||||||
|
API --> RD[(Redis)]
|
||||||
|
API --> FS[文件系统 STORAGE_ROOT/projects/<uuid>]
|
||||||
|
API --> WH[Whoosh 全文索引 search_index]
|
||||||
|
API --> ZV[ZVec 向量库 vector_index/<project_id>]
|
||||||
|
API --> LLM[LLM Provider: chat/embedding]
|
||||||
|
FS -->|变更同步| SVC[FileVectorSyncService → ZVec / SearchService]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三层结构（物理/逻辑/应用映射）
|
||||||
|
|
||||||
|
| 层 | 载体 | 说明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 应用层 | FastAPI（/api/v1 + /mcp）+ React SPA | 业务 API 与前端 |
|
||||||
|
| 数据层 | MySQL（元数据/权限/状态）、Redis（Token/会话）、文件系统（内容）、Whoosh/ZVec（索引） | 结构化 vs 非结构化分离 |
|
||||||
|
| 基础设施 | docker-compose（backend/frontend/mysql/redis）、nginx（frontend 内） | 容器化部署 |
|
||||||
|
|
||||||
|
## 关键子系统
|
||||||
|
1. **认证**：JWT Bearer + Redis Token 缓存双校验（见 DV-0001）。
|
||||||
|
2. **权限**：RBAC（roles/system_menus/role_menus）+ 项目级角色（admin/editor/viewer）双维度（DV-0002/0004）。
|
||||||
|
3. **文件系统**：`StorageService` 统一封装，含路径安全校验（DV-0002）。
|
||||||
|
4. **检索**：Whoosh 全文（DV-0005）+ ZVec 语义（DV-0006）双引擎，写路径后台同步（ADR-08）。
|
||||||
|
5. **知识库**：RAG 检索 + LLM 生成 + 引用支撑句对齐（DV-0007）。
|
||||||
|
6. **开放**：MCP Streamable HTTP（/mcp），bot 凭据映射到用户（DV-0011）。
|
||||||
|
|
||||||
|
## 系统边界
|
||||||
|
- 进程内单后端：REST 与 MCP 同挂一个 service。
|
||||||
|
- 存储边界：内容永不进 DB BLOB；DB 只存元数据。
|
||||||
|
- 网络边界：前端经 nginx 反代 /api，可同域免跨域；/mcp 不可 301/302 重定向（MCP 客户端要求）。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,10 @@
|
||||||
|
# 代码结构规范（Standards）
|
||||||
|
|
||||||
|
本目录整合了仓库既有的**代码结构设计规范**与其落地审计记录。
|
||||||
|
|
||||||
|
| 文件 | 类型 | 说明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| [code-structure-standards.md](code-structure-standards.md) | 规范（强制执行） | 通用代码结构边界、分层模型、前端/后端/CLI 规范、审计清单 |
|
||||||
|
| [code-structure-audit-2026-04-08.md](code-structure-audit-2026-04-08.md) | 审计记录 | 2026-04-08 前后端结构审计与已落地优化项 |
|
||||||
|
|
||||||
|
> 来源：原 `docs/code-structure-standards.md`、`docs/code-structure-audit-2026-04-08.md`，于 SDD 整合时迁入。
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
# 遗留文档归档说明（Archive / Disposition）
|
||||||
|
|
||||||
|
> 本文件记录项目根目录 `docs/` 下**遗留文档的处置结果**，作为整合与删除的追踪依据。原文件删除后，此文件保留其去向，保证可追溯。
|
||||||
|
|
||||||
|
## 处置汇总
|
||||||
|
|
||||||
|
| 原文件 | 评估 | 处置 | 落点 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `docs/code-structure-standards.md` | 现行、长期有效的工程规范 | **整合**（全量保留） | `architecture/standards/code-structure-standards.md` |
|
||||||
|
| `docs/code-structure-audit-2026-04-08.md` | 历史审计记录，有参考价值 | **整合**（全量保留） | `architecture/standards/code-structure-audit-2026-04-08.md` |
|
||||||
|
| `docs/MCP_HTTP_INTEGRATION.md` | 现行 MCP 使用文档，内容详实 | **合并**（内容并入，超集） | `integrations/mcp.md` |
|
||||||
|
| `docs/UPGRADE_v0.9.6.md` | 历史发布记录（多已吸收为基线） | **整合**为发布记录 | `releases/v0.9.6.md` |
|
||||||
|
| `docs/MIGRATION.md` | **过时**：指向已不存在的按钮文档/`/design` 路由 | **弃置**（归档说明，不保留实质内容） | 本文件 |
|
||||||
|
| `docs/DOCKER_DOCS_SETUP.md` | **过时**：`/design` 文档功能已不在代码中，当前 compose 无 `./docs` 挂载 | **弃置**（归档说明，不保留实质内容） | 本文件 |
|
||||||
|
|
||||||
|
## 弃置内容说明
|
||||||
|
|
||||||
|
### `docs/MIGRATION.md`（弃置）
|
||||||
|
该文档描述「按钮扩展组件文档整合方案」，指向 `src/components/docs/ButtonExtensions.md` 与 `/design/button-designs` 路由。经核查：
|
||||||
|
- `frontend/src` 中无对应消费者，`docsMenuData.json` 引用的 `/docs/*.md` 文件在仓库中不存在；
|
||||||
|
- `/design` 相关文档功能已不在当前代码中；
|
||||||
|
- 故判定为**过时遗留**，实质内容不再保留。
|
||||||
|
|
||||||
|
### `docs/DOCKER_DOCS_SETUP.md`（弃置）
|
||||||
|
该文档描述「将 `./docs` 卷挂载到容器 `/app/dist/docs` 以服务设计文档」。经核查：
|
||||||
|
- 当前 `docker-compose.yml` 仅挂载 `./storage`、`./backend/logs`（及 mysql/redis storage）；**无 `./docs` 挂载**；
|
||||||
|
- `/docs/*.md` 设计文档文件与消费方在当前仓库中不存在；
|
||||||
|
- 涉及的 `nex-design`、`/design`、PM2/ecosystem 等描述与当前项目结构不符；
|
||||||
|
- 故判定为**过时遗留**，实质内容不再保留。
|
||||||
|
|
||||||
|
## 相关提示
|
||||||
|
- 若未来重新引入「程序内文档中心」能力，须先在 SDD 登记规格（DV/FR），再落地，避免再次产生无人消费的遗留文档。
|
||||||
|
- 敏感内容（如默认口令、历史地址）仅保留在相应发布/部署文档的历史上下文中，不鼓励据此推断现状。
|
||||||
|
|
@ -0,0 +1,72 @@
|
||||||
|
# SDD 治理规则（Governance）
|
||||||
|
|
||||||
|
本文件定义 NEX Docus SDD 中心的**编号、审批、变更与追踪**规则，保证「产品意图 → 架构决策 → 功能规格 → 实施任务 → 验证证据」始终处于同一条可追踪链路。
|
||||||
|
|
||||||
|
## 1. 编号体系
|
||||||
|
|
||||||
|
| 前缀 | 含义 | 格式 | 范围 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| PO | Product Outcome（价值主张） | PO-N | 稳态常量，变更需评审 |
|
||||||
|
| ADR | Architecture Decision Record | ADR-NNNN | 持久架构决策，一决策一文件 |
|
||||||
|
| NFR | Non-Functional Requirement | NFR-N | 非功能需求，依附规格 |
|
||||||
|
| FR | Functional Requirement | FR-N | 功能需求，依附 DV 规格 |
|
||||||
|
| DV | Delivered Value（功能/变更单元） | DV-NNNN-shot-name | 一个功能或变更单元 |
|
||||||
|
| TS | Task（实施切片） | TS-N | 实施任务，从属于 DV |
|
||||||
|
| VER | Verification（验证证据） | VER-N | 验收证据，从属于 DV |
|
||||||
|
|
||||||
|
编号由 sdd 维护人统一分配；申请人不得自行占用 DV/ADR 编号。
|
||||||
|
|
||||||
|
## 2. 文档生命周期
|
||||||
|
|
||||||
|
```text
|
||||||
|
草稿(Draft) → 评审(Review) → 批准(Approved) → 已实现(Implemented) → 已验收(Verified) → 归档(Archived)
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Draft**：spec.md 初稿，仅供讨论。
|
||||||
|
- **Review**：进入评审；架构影响大的须同时评审 ADR。
|
||||||
|
- **Approved**：批准为规格基线，可据此实现。
|
||||||
|
- **Implemented**：tasks.md 所有切片完成。
|
||||||
|
- **Verified**：verification.md 证据齐全且通过。
|
||||||
|
- **Archived**：功能下线/重构，移入归档，不再作为基线。
|
||||||
|
|
||||||
|
## 3. 审批矩阵
|
||||||
|
|
||||||
|
| 变更类型 | 需审批方 | 说明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 新增/修改 PO | 产品负责人 | 价值主张变化 |
|
||||||
|
| 新增/修改 ADR | 架构负责人 + 技术负责人 | 跨文件刚性承诺 |
|
||||||
|
| 新增 DV 规格 | 功能负责人 + 架构评审（涉架构时） | 新功能入口 |
|
||||||
|
| 修改已批准 spec/design | 相应 DV 负责人 | 变更影响追踪 |
|
||||||
|
| 只改 tasks/verification | DV 负责人 | 实施与验收细节 |
|
||||||
|
| 发布 | 发布负责人 | 见 releases/ |
|
||||||
|
|
||||||
|
## 4. 追踪规则（Traceability）
|
||||||
|
|
||||||
|
- **强制反向可追踪**：每一条实施切片（TS）必须引用一个或多个规格（FR/ADR/NFR）；每一条验收证据（VER）必须引用其证明的规格与任务。
|
||||||
|
- **双向矩阵**：`specs/README.md` 维护「规格 ↔ 任务 ↔ 证据」索引；`architecture/decisions/README.md` 维护「ADR ↔ 规格」映射。
|
||||||
|
- **变更即更新**：任何 spec/design 改动或布局改动，须同步更新关联的 tasks 与 verification，保持链路不断签。
|
||||||
|
- **孤儿项处理**：新增代码若无规格/任务支撑，属「未登记变更」，应在当次 SDD 评审中补登记或回滚。
|
||||||
|
|
||||||
|
## 5. 变更工作流
|
||||||
|
|
||||||
|
1. 在本中心提出变更（写明受影响 DV/ADR/NFR）。
|
||||||
|
2. 按审批矩阵过审。
|
||||||
|
3. 更新对应 spec/design/tasks/verification。
|
||||||
|
4. 回填索引（specs/README、decisions/README）。
|
||||||
|
5. 若变更跨越发布边界，登记到 releases/。
|
||||||
|
|
||||||
|
## 6. 当前开放问题（Open Items）
|
||||||
|
|
||||||
|
| 编号 | 类型 | 内容 | 关联 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| OI-1 | 安全 | `security.py`/`deps.py` 存在 SECRET_KEY 前缀、JWT 载荷、token 前缀等敏感日志，需脱敏 | NFR-9, DV-0001/TS-12 | 待整改 |
|
||||||
|
| OI-2 | 部署 | 统一官方化 Docker Compose v2 部署路径（升级 compose-plugin、移除外层 v1 工具链依赖/说明） | NFR-6, ADR-0008 | 待整改 |
|
||||||
|
| OI-3 | 测试 | 后端测试仅覆盖引用/模型配置/检索三处，缺集成与 E2E 测试 | DV-* verification | 待增强 |
|
||||||
|
| OI-4 | 迁移 | 未引入 Alembic，迁移依赖幂等 ALTER；大规模结构变更缺少回放/回滚机制 | ADR-000?（见 ADR-07） | 已记录，待评估 |
|
||||||
|
|
||||||
|
## 7. 维护约定
|
||||||
|
|
||||||
|
- 本目录变更遵循「小步提交」：一次合并只动一个逻辑单元。
|
||||||
|
- 每个新建 DV 单元必须包含完整的四文件（spec/design/tasks/verification），缺一不可。
|
||||||
|
- 每次功能合并，默认要求补齐对应 verification 证据或明确标注“将由 OI-3 覆盖”。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# 集成：项目 Git 仓库（DV-0010 支撑）
|
||||||
|
|
||||||
|
## 能力
|
||||||
|
- 项目可绑定 Git 仓库（`project_git_repos`：name、repo_url、branch、username、token、is_default）。
|
||||||
|
- 支持 `git pull` / `git push`。
|
||||||
|
|
||||||
|
## 接口
|
||||||
|
- `GET/POST /api/v1/projects/{id}/git-repos`
|
||||||
|
- `PUT/DELETE /api/v1/projects/{id}/git-repos/{repo_id}`
|
||||||
|
- `POST /api/v1/projects/{id}/git/pull`
|
||||||
|
- `POST /api/v1/projects/{id}/git/push`
|
||||||
|
|
||||||
|
## 安全
|
||||||
|
- 凭据（token/密码）以字段存储于 `project_git_repos.token`；注意避免日志泄露（关联 OI-1/NFR-9 敏感信息治理）。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
DV-0010, ADR-0006（文件系统与外部仓库的边界：分享/同步策略见具体实现）。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,121 @@
|
||||||
|
# 集成：MCP Streamable HTTP（DV-0011 支撑）
|
||||||
|
|
||||||
|
> 本页为 MCP 接入的规格化工作说明，**整合自原 `docs/MCP_HTTP_INTEGRATION.md`（已并入）** 与 DV-0011 规格。实现代码：`backend/app/mcp/server.py`、`backend/app/mcp/context.py`、`backend/app/models/mcp_bot.py`。
|
||||||
|
|
||||||
|
## 1. 方案说明（决策摘要）
|
||||||
|
|
||||||
|
- 不再使用项目根目录独立 `mcp_server/`；改为**后端内集成**。
|
||||||
|
- 业务 REST API 继续走 `/api/v1/...`；MCP 入口挂载在同一个 backend 服务上。
|
||||||
|
- 传输协议：`streamableHttp`；MCP 地址 `/mcp`（`/mcp/` 也兼容）。
|
||||||
|
- 认证：`X-Bot-Id` + `X-Bot-Secret`。
|
||||||
|
|
||||||
|
这意味着：
|
||||||
|
- 不需要单独部署一套 MCP 服务；
|
||||||
|
- 不需要让 MCP client 传业务账号密码；
|
||||||
|
- 不需要让远程 agent 访问本地脚本进程。
|
||||||
|
|
||||||
|
## 2. 接口地址
|
||||||
|
|
||||||
|
```text
|
||||||
|
http://<backend-host>:<backend-port>/mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
说明：
|
||||||
|
- 推荐优先使用 `/mcp`；`/mcp/` 也兼容。
|
||||||
|
- 前面有 Nginx/网关时，**不要对 `/mcp` 做 301/302 重定向**。
|
||||||
|
- 未携带 bot 凭证访问 `/mcp` 或 `/mcp/` 返回 `401`。
|
||||||
|
|
||||||
|
## 3. 认证模型
|
||||||
|
|
||||||
|
MCP client 只传两个 header：`X-Bot-Id`、`X-Bot-Secret`。后端逻辑：
|
||||||
|
|
||||||
|
1. 根据 `X-Bot-Id` 查询 `mcp_bots`；
|
||||||
|
2. 校验 `X-Bot-Secret`；
|
||||||
|
3. 将该 bot 映射到 NexDocs 用户；
|
||||||
|
4. 以该用户身份执行 MCP 工具。
|
||||||
|
|
||||||
|
因此 client 不需要再传：NexDocs 用户名、密码、access token。
|
||||||
|
|
||||||
|
## 4. 用户如何获取凭证
|
||||||
|
|
||||||
|
个人中心 → `MCP 接入` 标签页：
|
||||||
|
- 查看 `X-Bot-Id`；
|
||||||
|
- 查看并复制 `X-Bot-Secret`；
|
||||||
|
- 重新生成 `X-Bot-Secret`。
|
||||||
|
|
||||||
|
后端接口：
|
||||||
|
- `GET /api/v1/auth/mcp-credentials`
|
||||||
|
- `POST /api/v1/auth/mcp-credentials/rotate-secret`
|
||||||
|
|
||||||
|
## 5. 当前支持的 MCP 工具
|
||||||
|
|
||||||
|
| 工具 | 说明 | 关键参数 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `list_created_projects` | 列出当前用户创建的项目 | keyword(可选), limit(默认100) |
|
||||||
|
| `get_project_tree` | 项目文件树 | project_id(必填) |
|
||||||
|
| `get_file` | 获取文件内容 | project_id, path |
|
||||||
|
| `create_file` | 创建新文件 | project_id, path, content(可选) |
|
||||||
|
| `update_file` | 修改文件 | project_id, path, content |
|
||||||
|
| `delete_file` | 删除文件 | project_id, path |
|
||||||
|
|
||||||
|
### 文件类工具的语义
|
||||||
|
- `create_file`：目标已存在报错；自动创建缺失上级目录；校验项目写权限；写 Markdown 更新搜索索引；记录操作日志；通知项目成员。
|
||||||
|
- `update_file`：目标不存在报错；只允许更新文件（非目录）；校验写权限；写 Markdown 更新索引；记日志；通知。
|
||||||
|
- `delete_file`：目标不存在报错；只允许删除文件（非目录）；删除 Markdown 同步删搜索索引；记日志；通知。
|
||||||
|
|
||||||
|
## 6. 调用端配置示例
|
||||||
|
|
||||||
|
支持 streamableHttp 的 MCP client：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tools": {
|
||||||
|
"mcpServers": {
|
||||||
|
"biz_mcp": {
|
||||||
|
"type": "streamableHttp",
|
||||||
|
"url": "http://backend.internal:8000/mcp",
|
||||||
|
"headers": {
|
||||||
|
"X-Bot-Id": "nexbot_xxxxxxxxxxxxxxxx",
|
||||||
|
"X-Bot-Secret": "nxbotsec_xxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
},
|
||||||
|
"toolTimeout": 60
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
注意：
|
||||||
|
- `url` 建议使用 `/mcp`；
|
||||||
|
- `headers` 中不需再放业务用户名密码；
|
||||||
|
- `X-Bot-Secret` 只应发给受信任调用端；
|
||||||
|
- 浏览器环境客户端需把站点加入后端 `CORS_ORIGINS`。
|
||||||
|
|
||||||
|
## 7. 后端部署要求
|
||||||
|
|
||||||
|
- **Python 版本**：backend 需要 Python 3.12（MCP SDK 要求 3.10+；本项目按 3.12 调试）。
|
||||||
|
- **Docker**：`backend/Dockerfile` 基于 Python 3.12。
|
||||||
|
- **数据表**：需要 `mcp_bots` 表（通过建表脚本/init 创建）。
|
||||||
|
- **Nginx 统一入口**：前端 Nginx 已加 `/mcp`、`/mcp/` 反代配置，可经统一入口访问。
|
||||||
|
|
||||||
|
本地开发建议：
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
/opt/homebrew/bin/python3.12 -m venv venv312
|
||||||
|
env -u HTTP_PROXY -u HTTPS_PROXY ./venv312/bin/pip install -r requirements.txt
|
||||||
|
./venv312/bin/uvicorn main:app --host 0.0.0.0 --port 8000
|
||||||
|
```
|
||||||
|
|
||||||
|
## 8. 验证结果
|
||||||
|
|
||||||
|
本地已验证：
|
||||||
|
- Python 3.12 启动 backend 正常；
|
||||||
|
- `/health` 返回 200；
|
||||||
|
- `/mcp`、`/mcp/` 均可访问；
|
||||||
|
- 未传 `X-Bot-Id`/`X-Bot-Secret` 返回 401。
|
||||||
|
|
||||||
|
## 9. 规格映射
|
||||||
|
|
||||||
|
- 关联 ADR：ADR-0005（开放接入/可溯源）。
|
||||||
|
- 功能规格：FR-18（见 DV-0011）。
|
||||||
|
- 验证证据：见 DV-0011/verification.md；详细集成说明已并入本页（原 `docs/MCP_HTTP_INTEGRATION.md`）。
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# 产品与工程原则（Principles）
|
||||||
|
|
||||||
|
## 产品原则
|
||||||
|
1. **文件即真理**：内容数据以文件为本，数据库只承载元数据/权限/状态。
|
||||||
|
2. **透明可迁移**：任何时刻都应能通过「拷贝目录 + 导出 DB」完成迁移。
|
||||||
|
3. **严格隔离**：项目级磁盘隔离 + RBAC 权限，双保险。
|
||||||
|
4. **答案可溯源**：知识库问答必须可验证，禁止无依据编造。
|
||||||
|
5. **开放接入**：优先用行业标准协议（如 MCP）暴露能力。
|
||||||
|
|
||||||
|
## 工程原则
|
||||||
|
1. **异步优先**：后端 FastAPI + 异步 I/O（aiofiles/aiomysql/aioredis），长任务走后台任务。
|
||||||
|
2. **写路径不阻塞**：索引/向量同步放后台（`FileVectorSyncService`、`ProjectVectorizationTaskService`），主请求线程不等待。
|
||||||
|
3. **路径安全第一**：任何文件访问必须先过 `get_secure_path` 校验。
|
||||||
|
4. **健壮降级**：LLM/embedding/对齐失败不阻断主流程；无配置时跳过。
|
||||||
|
5. **幂等变更**：数据库结构演进用幂等 ALTER；初始化脚本可重复执行。
|
||||||
|
6. **单一真相源**：本 SDD 中心是规格/追踪入口，细节指向源文档与代码。
|
||||||
|
7. **小步可追踪**：一次合并一个逻辑单元，切片（TS）可被证据（VER）验证。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,34 @@
|
||||||
|
# 阶段性路线图（Roadmap）
|
||||||
|
|
||||||
|
> 基于仓库现状（IMPLEMENTATION_PLAN.md 三阶段已基本完成）与 SDD 梳理结果，重新组织为阶段化路线图。状态为 SDD 核对后的推断。
|
||||||
|
|
||||||
|
## 阶段一：MVP 文档平台（已完成）
|
||||||
|
- 认证与会话（DV-0001）
|
||||||
|
- 项目与文件系统（DV-0002）
|
||||||
|
- 文档编辑与文件操作（DV-0003）
|
||||||
|
- RBAC 与系统管理（DV-0004）
|
||||||
|
|
||||||
|
## 阶段二：检索与知识库（已完成）
|
||||||
|
- 全文检索（DV-0005）
|
||||||
|
- ZVec 向量化（DV-0006）
|
||||||
|
- RAG 知识库对话（DV-0007）
|
||||||
|
- LLM 模型配置（DV-0008）
|
||||||
|
|
||||||
|
## 阶段三：协作与开放（已完成）
|
||||||
|
- 分享与公开预览（DV-0009）
|
||||||
|
- 通知、日志、Git 集成、导出（DV-0010）
|
||||||
|
- MCP 接入（DV-0011）
|
||||||
|
|
||||||
|
## 待决/增强（Backlog）
|
||||||
|
| 项 | 说明 | 关联 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 安全整改 | 敏感日志脱敏、口令复杂度校验 | OI-1, NFR-9 |
|
||||||
|
| 部署官方化 | Compose v2 路径统一、清理 v1 依赖说明 | OI-2, ADR-08 |
|
||||||
|
| 测试增强 | 集成测试与 E2E，提升回归覆盖 | OI-3 |
|
||||||
|
| 迁移体系评估 | 评估引入 Alembic 以支撑大规模结构变更 | OI-4 |
|
||||||
|
| 实时协同评估 | 若需多人实时编辑，另行立项（当前 exclude） | vision 边界 |
|
||||||
|
|
||||||
|
## 里程碑原则
|
||||||
|
- 每个里程碑对应一组 DV 规格；合入前 verification.md 证据必须齐全（或明确标注 OI-3 覆盖）。
|
||||||
|
- 发布版本在 releases/ 登记。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,39 @@
|
||||||
|
# 产品愿景（Vision）
|
||||||
|
|
||||||
|
## 一句话愿景
|
||||||
|
|
||||||
|
**NEX Docus 是一款面向团队协作的轻量级文档管理平台**，以「数据库管理权限 + 文件系统存储内容」的混合架构，让团队在获得可控权限管理的同时，拥有文件级的数据透明性、可迁移性与可理解性（可检索、可问答、可溯源）。
|
||||||
|
|
||||||
|
## 产品价值主张（PO）
|
||||||
|
|
||||||
|
| 编号 | 价值主张 | 说明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| PO-1 | **文件即真理（File as Truth）** | 文档内容、图片、附件以原生文件存于服务器磁盘，不落数据库 BLOB；便于备份、迁移与 Git 版本控制。 |
|
||||||
|
| PO-2 | **三级模型** | 用户（User）→ 项目（Project）→ 文档/文件夹（File/Folder）的分层组织。 |
|
||||||
|
| PO-3 | **严格隔离与权限** | 基于项目的物理磁盘隔离 + 数据库 RBAC 权限的双重控制。 |
|
||||||
|
| PO-4 | **可理解内容库** | 文档可向量化构建知识库，支持基于 RAG 的问答，且答案可溯源（引用支撑句）。 |
|
||||||
|
| PO-5 | **开放接入** | 通过 MCP (Model Context Protocol) Streamable HTTP 让外部 Agent 访问项目/文档能力。 |
|
||||||
|
|
||||||
|
## 目标用户与角色
|
||||||
|
|
||||||
|
- **系统管理员（super_admin）**：全量菜单与权限，管理用户、角色、模型配置、日志。
|
||||||
|
- **管理员（admin）**：系统级管理人员。
|
||||||
|
- **普通用户（user）**：创建/参与项目、编辑文档、使用知识库对话。
|
||||||
|
- **访客（匿名分享访问者）**：通过公开分享链接访问项目/文件预览（受限）。
|
||||||
|
|
||||||
|
## 边界（Scope）
|
||||||
|
|
||||||
|
### 范围内（In Scope）
|
||||||
|
用户认证与 RBAC、项目管理与协作、文档/文件系统管理、全文检索、ZVec 向量化知识库、RAG 对话、分享/预览、Git 仓库集成、通知、系统日志、LLM 模型配置、后台导出/向量化任务、MCP 接入。
|
||||||
|
|
||||||
|
### 范围外（Out of Scope）
|
||||||
|
- 不做数据库内大文件二进制 BLOB 存储（文件一律落盘）。
|
||||||
|
- 不内置完整 Alembic 迁移链（见 ADR；采用幂等 ALTER）。
|
||||||
|
- 不承诺 docker-compose v1 兼容（依赖 Compose v2 / Engine ≥ 25）。
|
||||||
|
- 不做实时多人协同编辑（当前为「保存即落盘 + 后台索引同步」，无 OT/CRDT）。
|
||||||
|
|
||||||
|
## 成功度量（建议）
|
||||||
|
- MVP 链路通：创建项目 → 编辑 MD → 保存 → 检索命中 → 向量化 → RAG 问答可溯源。
|
||||||
|
- 知识库引用准确率：答案中的 [n] 引用均可回填到原文支撑句（引用对齐覆盖率）。
|
||||||
|
- 部署/升级成功率：Compose v2 一键 init/upgrade 无阻断。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# 发布索引（Releases）
|
||||||
|
|
||||||
|
本目录登记**公开版本与资产索引**。每个发布一个文件：`vX.Y.Z.md`，记录发布元数据、产物与验证边界。
|
||||||
|
|
||||||
|
## 发布规则
|
||||||
|
- 版本号语义化（MAJOR.MINOR.PATCH）。
|
||||||
|
- 发布前必须：对应 DV verification.md 证据通过；ADR 无未决的重大分歧。
|
||||||
|
- 发布文件中须给出「验证边界」：哪些 DV 被覆盖、如何复验、已知限制。
|
||||||
|
- 部署相关变更同步到 `DEPLOY.md` / `CHANGELOG_DEPLOY.md`。
|
||||||
|
- **版本以 git 为准**：发布必须对应一个 git 版本标记（提交信息中的 vX.Y.Z 或 tag）；代码内版本字段应与 git 标记一致。
|
||||||
|
|
||||||
|
## 版本列表（对齐 git）
|
||||||
|
| 版本 | 文件 | 对应 git 标记 | 主要规格覆盖 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| v0.9.9 | [v0.9.9.md](v0.9.9.md) | `416ef48 v0.9.9`（当前基线，HEAD `4ef3c92`） | 阶段一~三全部 DV | 当前基线 |
|
||||||
|
| v0.9.6 | [v0.9.6.md](v0.9.6.md) | `c005964 v0.9.6` | MCP 内集成/凭证管理/Python3.12/storage 持久化（历史） | 历史发布记录 |
|
||||||
|
|
||||||
|
> git 发布线：v0.9.1 → v0.9.2 → v0.9.6 → v0.9.7 → v0.9.8 → **v0.9.9**。仓库**未打 git tag**；上表以提交信息中的版本标记为准。
|
||||||
|
>
|
||||||
|
> v0.9.6 为**历史发布记录**（整合自原 `docs/UPGRADE_v0.9.6.md`）；v0.9.9 为**当前基线**。
|
||||||
|
>
|
||||||
|
> ⚠️ 代码内版本字段（`APP_VERSION`、`package.json version`）与部分旧文档标注为 1.0.0，与 git 标记不符，属遗留占位，见 v0.9.9.md「版本对齐说明」。
|
||||||
|
|
||||||
|
## 历史部署变更参考（非发布、仅供追踪）
|
||||||
|
- `CHANGELOG_DEPLOY.md`：v1.0.1 前端端口 80→8080、storage 目录映射（STORAGE_PATH）等（该记录与 git 发布线冲突，已标注意外，见 archive/版本对齐）。
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
# Release v0.9.6（历史升级记录）
|
||||||
|
|
||||||
|
> **文档性质**：历史发布记录。整合自原 `docs/UPGRADE_v0.9.6.md`（已并入）。内容多为当时的新增能力，绝大部分已被后续版本吸收为基线；此处仅作发布历史留存。
|
||||||
|
|
||||||
|
## 元数据
|
||||||
|
- **版本**：v0.9.6
|
||||||
|
- **更新时间**：2026-03-11
|
||||||
|
|
||||||
|
## 主要变更
|
||||||
|
1. 新增后端内集成的 MCP Server 能力（原生 `streamableHttp`，入口 `/mcp`，兼容 `/mcp/`）。
|
||||||
|
2. 新增用户级 MCP 凭证管理（`X-Bot-Id` / `X-Bot-Secret` 认证模型）。
|
||||||
|
3. 打通通过 Nginx 统一入口访问 MCP。
|
||||||
|
4. 调整部署运行环境到 Python 3.12（MCP SDK 要求 3.10+）。
|
||||||
|
5. 将 MySQL、Redis 数据目录改为项目根目录 `storage/` 持久化（`storage/mysql`、`storage/redis`、`storage/projects`、`storage/temp`）。
|
||||||
|
6. 个人中心与文档页交互优化（左右布局、浏览/编辑切换、认证异常 Toast 抑制）。
|
||||||
|
|
||||||
|
## MCP 能力（当时新增）
|
||||||
|
- 工具：`list_created_projects`、`get_project_tree`、`get_file`、`create_file`、`update_file`、`delete_file`。
|
||||||
|
- 接口：`GET /api/v1/auth/mcp-credentials`、`POST /api/v1/auth/mcp-credentials/rotate-secret`。
|
||||||
|
|
||||||
|
## 部署变更
|
||||||
|
- backend 基础镜像切换为 `python:3.12-slim`；pip 构建工具升级；国内源失败回退官方源。
|
||||||
|
- Nginx 补 `/mcp`、`/mcp/` 兼容反代。
|
||||||
|
- MySQL/Redis 数据目录挂载到 `storage/`。
|
||||||
|
|
||||||
|
## 升级迁移注意事项
|
||||||
|
- MCP 调用地址：经前端 Nginx 统一入口改为 `http(s)://<host>/mcp`；调用头保持 `X-Bot-Id`/`X-Bot-Secret`。
|
||||||
|
|
||||||
|
## 验证边界（当时建议）
|
||||||
|
1. backend `/health` 正常；
|
||||||
|
2. 统一入口 `/api/`、`/mcp`、`/mcp/` 可访问；
|
||||||
|
3. MCP client 能完成 `initialize`；
|
||||||
|
4. 个人中心 MCP 凭证展示与轮换正常。
|
||||||
|
|
||||||
|
## 关联
|
||||||
|
- 现规格映射：FR-18 / DV-0011；集成细节见 `integrations/mcp.md`。
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
# Release v0.9.9（当前基线）
|
||||||
|
|
||||||
|
> 基于 `git log` 版本标记对应的最新发布提交（`416ef48 v0.9.9`）与当前 HEAD（`4ef3c92 优化了显示`，位于 v0.9.9 之后）。仓库未打 git tag，此记录以提交信息中的版本标记为准。
|
||||||
|
|
||||||
|
## 元数据
|
||||||
|
- **版本**：v0.9.9（当前基线）
|
||||||
|
- **对应提交**：v0.9.9 标记提交 `416ef48`；当前 HEAD `4ef3c92`
|
||||||
|
- **适用代码**：backend + frontend + docker-compose（main 分支）
|
||||||
|
- **代码内版本字段**：意外标注为 1.0.0，与 git 标记 v0.9.9 不符，见「已知差异」
|
||||||
|
|
||||||
|
## 主要能力
|
||||||
|
覆盖阶段一~三：认证/DV-0001、项目管理与文件系统/DV-0002、文档编辑/DV-0003、RBAC 与系统管理/DV-0004、全文检索/DV-0005、ZVec 向量化/DV-0006、RAG 对话/DV-0007、模型配置/DV-0008、分享预览/DV-0009、通知日志 Git 导出/DV-0010、MCP/DV-0011。
|
||||||
|
|
||||||
|
## 产物
|
||||||
|
- 后端镜像（docker-compose backend build）
|
||||||
|
- 前端镜像（frontend build，nginx 托管静态资源）
|
||||||
|
- 部署编排：`docker-compose.yml` + `deploy.sh`
|
||||||
|
|
||||||
|
## 验证边界
|
||||||
|
- 自动化测试：`backend/tests/test_chat_citations.py`、`test_model_and_vector_configuration.py`、`test_search_service.py`。
|
||||||
|
- 运行验证：`/health` 返回 healthy；Swagger `/docs` 可用。
|
||||||
|
- 部署验证：Compose v2 `docker compose up -d --build`；`./deploy.sh upgrade`。
|
||||||
|
- 已知限制：单机部署；无实时协同编辑；测试覆盖待增强（OI-3）。
|
||||||
|
|
||||||
|
## 已知问题
|
||||||
|
| 编号 | 内容 | 处置 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| OI-1 | 敏感日志脱敏 | 待整改 |
|
||||||
|
| OI-2 | Compose v2 官方化 | 待整改 |
|
||||||
|
| OI-4 | 版本字段 1.0.0 与 git 标记不符，需统一 | 待整改（见本文档「版本对齐」说明） |
|
||||||
|
|
||||||
|
## 版本对齐说明
|
||||||
|
- git 发布线：v0.9.1 → v0.9.2 → v0.9.6 → v0.9.7 → v0.9.8 → v0.9.9（`416ef48`）。
|
||||||
|
- **无 v1.0.0** 的 git 版本；代码 `APP_VERSION=1.0.0`、`package.json version=1.0.0` 与文档中的 v1.0.0/v1.0.1 均为遗留占位，与 git 不符。
|
||||||
|
- 建议：下次打 tag 时以 v0.9.9 为基线；若计划升级 v1.0.0 则应显式建 tag 并同步代码字段。
|
||||||
|
|
@ -0,0 +1,28 @@
|
||||||
|
# DV-0001：认证与会话 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
涉及 `auth.py`（API）、`security.py`（JWT/bcrypt）、`deps.py`（依赖注入）、`redis_client.py`（TokenCache）。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `users`（id/username/password_hash/…）——细节见 DATABASE.md。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- POST /api/v1/auth/{register,login,logout}
|
||||||
|
- GET /api/v1/auth/me
|
||||||
|
- PUT /api/v1/auth/profile
|
||||||
|
- POST /api/v1/auth/change-password
|
||||||
|
- POST /api/v1/auth/upload-avatar
|
||||||
|
- GET /api/v1/auth/avatar/{user_id}/{filename}
|
||||||
|
- GET/POST /api/v1/auth/mcp-credentials{,/rotate-secret}
|
||||||
|
|
||||||
|
## 认证流程
|
||||||
|
1. 登录成功：bcrypt 校验 → 生成 JWT（sub=user_id）→ 写入 Redis TokenCache。
|
||||||
|
2. 每次请求：`get_current_user` 校验 Redis 中 token→user_id，再 decode JWT，两项一致且用户启用才放行。
|
||||||
|
3. 登出：移除 Redis 中的 token，实现即时失效。
|
||||||
|
|
||||||
|
## 状态与降级
|
||||||
|
- Redis 不可用 → 认证失败（受 NFR-2 约束）；可选认证（`get_current_user_optional`）返回 None 而非报错。
|
||||||
|
|
||||||
|
## 变更影响
|
||||||
|
- NFR-9 敏感日志：security.py/deps.py 的 SECRET_KEY/JWT 载荷日志需脱敏（TS-12）。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
# DV-0001：认证与会话 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0003
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
提供安全的用户认证与会话管理，为所有受保护资源提供身份基础。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：注册、登录、登出、修改密码、个人资料、头像上传、JWT Bearer + Redis 双校验。
|
||||||
|
- **Out**：第三方 SSO/OAuth 登录。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为用户，我希望登录一次后持续访问项目/文档，以便高效工作而不反复输入凭据。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求描述 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-1 | 注册/登录/登出、改密、资料、头像 | 登录返回 JWT；退出后 token 失效 |
|
||||||
|
| FR-1a | 每次请求经 get_current_user 校验 | Redis 缓存 + JWT 完整性 + 用户状态；禁用即拒绝 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-1 | 密码 bcrypt 哈希存储，绝不明文 |
|
||||||
|
| NFR-2 | JWT + Redis Token 缓存双校验；token 存 Redis 可失效 |
|
||||||
|
| NFR-9 | 敏感日志脱敏（缺陷，见 OI-1） |
|
||||||
|
|
||||||
|
## 边界与约束
|
||||||
|
- 使用 OAuth2 password bearer；token 有效期 ACCESS_TOKEN_EXPIRE_MINUTES=1440。
|
||||||
|
- 用户被禁用（status!=1）即拒绝访问。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,9 @@
|
||||||
|
# DV-0001：认证与会话 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-1 | 注册/登录/登出 + JWT + Redis | FR-1, NFR-2 | 已完成 |
|
||||||
|
| TS-1a | 修改密码、个人资料、头像上传 | FR-1 | 已完成 |
|
||||||
|
| TS-1b | mcp-credentials 接口 | FR-1/FR-18 | 已完成 |
|
||||||
|
| TS-12 | **敏感日志脱敏、口令复杂度** | NFR-1, NFR-9 | 待整改 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# DV-0001：认证与会话 – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
- 结构性证据为主（认证逻辑无独立单测文件）。
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 登录返回 JWT；携带后可访问受保护接口
|
||||||
|
- [x] 退出后同 token 返回 401
|
||||||
|
- [x] 禁用用户登录后请求被拒
|
||||||
|
- [x] 修改密码后旧密码失效
|
||||||
|
- [ ] 敏感日志脱敏（TS-12 未完成）
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | backend/app/models/user.py | FR-1 数据层 |
|
||||||
|
| VER-11 | backend/app/api/v1/auth.py | FR-1 API 层 |
|
||||||
|
| VER-15 | backend/app/core/security.py + deps.py | NFR-1/2；揭示 NFR-9 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# DV-0002：项目与文件系统 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`projects.py`、`storage.py`、`project_file_service.py`、`file_vector_sync_service.py`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `projects`（storage_key/owner_id/status/access_pass…）
|
||||||
|
- `project_members`（role: admin/editor/viewer）
|
||||||
|
- `document_meta`、`document_vector`
|
||||||
|
- 细节见 DATABASE.md。
|
||||||
|
|
||||||
|
## 存储结构
|
||||||
|
`STORAGE_ROOT/projects/<storage_key>/` + `_assets/images|files` + 默认 README.md。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- /api/v1/projects/*（CRUD、my、shared、transfer、members）
|
||||||
|
- /api/v1/files/{project_id}/tree
|
||||||
|
|
||||||
|
## 路径安全
|
||||||
|
`get_secure_path(storage_key, rel)`：以 project_root 为根，`relative_to` 校验，失败 403。
|
||||||
|
|
||||||
|
## 状态与降级
|
||||||
|
- 权限不足→403；索引同步失败不阻塞文件写（最终一致）。
|
||||||
|
|
||||||
|
## 变更影响
|
||||||
|
- ADR-0006：文件变更触发向量/全文索引进后台同步。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
# DV-0002：项目与文件系统 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0001, ADR-0002, ADR-0003, ADR-0006
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
建立「用户→项目→文档/文件夹」三级模型，并以“DB 权限 + FS 内容”实现项目文档的文件级存储与严格隔离。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：项目 CRUD/转移/归档、成员协作、StorageService 路径安全、目录树。
|
||||||
|
- **Out**：实时协同编辑。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为项目成员，我希望按权限访问项目文档，以便协同维护知识库。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-2 | 三级模型 + 项目 CRUD/转移 | 创建生成 UUID storage_key 并建磁盘结构 |
|
||||||
|
| FR-3 | 文件系统存储 + 路径安全 | get_secure_path 防穿越；隐藏文件/_assets 不进树 |
|
||||||
|
| FR-5 | 项目成员协作 | 按 admin/editor/viewer 判定读写 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-3 | 所有路径经 get_secure_path 校验 |
|
||||||
|
| NFR-4 | 项目访问做 RBAC 校验 |
|
||||||
|
| NFR-11 | 索引在文件变更时同步维护 |
|
||||||
|
|
||||||
|
## 边界与约束
|
||||||
|
- 磁盘名用 UUID（storage_key），展示名解耦。
|
||||||
|
- 内容不进 DB BLOB。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# DV-0002：项目与文件系统 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-2 | 三级模型、项目 CRUD、存储服务、路径安全、成员协作 | FR-2/3/5, NFR-3/4 | 已完成 |
|
||||||
|
| TS-2a | 项目转移/归档/访问密码 | FR-2 | 已完成 |
|
||||||
|
| TS-2b | 磁盘结构初始化（uuid + _assets + README） | FR-2 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# DV-0002：项目与文件系统 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 创建项目生成 uuid 目录 + README.md + _assets
|
||||||
|
- [x] 路径穿越（../）返回 403
|
||||||
|
- [x] 非成员访问返回 403
|
||||||
|
- [x] 目录树隐藏 . 开头的文件与 _assets
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | models/project.py 等 | FR-2/5 数据层 |
|
||||||
|
| VER-11 | api/v1/projects.py, files.py | FR-2/3/5 API 层 |
|
||||||
|
| VER-12 | services/storage.py, project_file_service.py | ADR-0001/2/6, FR-3 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
# DV-0003：文档编辑与文件操作 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`files.py`（API）、`storage.py`（读写）、前端 `DocumentPage/DocumentEditor`（pages/Document）、Markdown 组件 bytemd。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- GET /api/v1/files/{project_id}/tree
|
||||||
|
- GET|POST /api/v1/files/{project_id}/file
|
||||||
|
- POST /api/v1/files/{project_id}/file/operate
|
||||||
|
- POST /api/v1/files/{project_id}/upload{,-document}
|
||||||
|
- POST /api/v1/files/{project_id}/import-documents
|
||||||
|
- GET /api/v1/files/{project_id}/export-directory
|
||||||
|
- GET /api/v1/files/{project_id}/export-pdf
|
||||||
|
|
||||||
|
## 前端
|
||||||
|
- 左侧目录树，右侧 Markdown 编辑/预览；PDF 用 react-pdf；长列表虚拟滚动。
|
||||||
|
|
||||||
|
## 状态与降级
|
||||||
|
- 写文件自动创建父目录；重命名目标冲突→400。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
# DV-0003：文档编辑与文件操作 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0002
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
提供无限层级目录树与完整的 Markdown 文档编辑/文件操作能力。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：目录树、读/存文件、新建/重命名/删除/移动、上传图片/文档、导入/导出、导出 PDF。
|
||||||
|
- **Out**：富文本编辑器（仅 Markdown）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为文档作者，我希望编辑 Markdown 并管理目录结构，以便维护有序的知识库。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-4 | 目录树 + 文件操作 + 上传/导入/导出 | 无限层级；目录在前名称排序；_assets 不展示 |
|
||||||
|
| FR-4a | 前端编辑器 + 保存 | Cmd+S 保存；图片/附件上传 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-3 | 路径安全（所有文件操作复用 get_secure_path） |
|
||||||
|
| NFR-5 | aiofiles 异步 I/O；PDF/长文档虚拟滚动 |
|
||||||
|
|
||||||
|
## 边界与约束
|
||||||
|
- 隐藏文件不进入树；_assets 不进入树。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# DV-0003：文档编辑与文件操作 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-3 | tree/file/operate/upload/import/export 基础链路 | FR-4 | 已完成 |
|
||||||
|
| TS-3a | 前端编辑器与目录树 | FR-4a | 已完成 |
|
||||||
|
| TS-3b | PDF 预览与导出 | FR-4a | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,16 @@
|
||||||
|
# DV-0003：文档编辑与文件操作 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 新建/重命名/删除/移动文件与文件夹
|
||||||
|
- [x] 文件内容保存后读回一致
|
||||||
|
- [x] 图片/文档上传成功
|
||||||
|
- [x] 目录导出 ZIP、文档导出 PDF
|
||||||
|
- [x] 隐藏文件与 _assets 不在树中
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-11 | api/v1/files.py | FR-4 |
|
||||||
|
| VER-12 | services/storage.py | FR-4 |
|
||||||
|
| VER-16 | frontend/src/pages/Document/* | FR-4a |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# DV-0004：RBAC 与系统管理 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`roles.py`、`role_permissions.py`、`users.py`、`menu.py`、`dashboard.py`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `roles`、`user_roles`、`system_menus`、`role_menus`。
|
||||||
|
- 细节见 DATABASE.md。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- /api/v1/roles/*、/api/v1/role-permissions/*
|
||||||
|
- /api/v1/users/*
|
||||||
|
- /api/v1/menu/user-menus、/user-permissions
|
||||||
|
- /api/v1/dashboard/*
|
||||||
|
|
||||||
|
## 权限判定
|
||||||
|
- 前端按 user-permissions 渲染；后端依赖校验。超级管理员跳过细粒度检查。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# DV-0004：RBAC 与系统管理 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0003
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
提供基于角色的访问控制（RBAC）与系统管理能力（用户、角色、权限、菜单、仪表盘）。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：角色→菜单/权限点、用户管理、仪表盘统计。
|
||||||
|
- **Out**：细粒度字段级权限（当前为菜单/权限点/项目角色）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为管理员，我希望按角色分配能力并量化系统使用情况，以便治理平台。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-6 | RBAC：roles/system_menus/role_menus；超级管理员全量 | 用户多角色；菜单/权限点授权 |
|
||||||
|
| FR-7 | 用户管理：增删改查/启停/角色/重置密码 | 管理员可操作 |
|
||||||
|
| FR-8 | 仪表盘：统计与文档活跃度 | 数据正确 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-4 | 权限判定统一走 RBAC 依赖 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0004：RBAC 与系统管理 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-4 | RBAC、角色/权限/菜单、用户管理、仪表盘统计 | FR-6/7/8 | 已完成 |
|
||||||
|
| TS-4a | 菜单/权限点初始化（scripts/init_db.py） | FR-6 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# DV-0004：RBAC 与系统管理 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 角色增删改、菜单/权限点授权
|
||||||
|
- [x] 用户增删改/启停/分配角色/重置密码
|
||||||
|
- [x] 超级管理员拥有全部权限
|
||||||
|
- [x] 仪表盘统计正确
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | models/role.py, menu.py | FR-6 |
|
||||||
|
| VER-11 | api/v1/{roles,role_permissions,users,menu,dashboard}.py | FR-6/7/8 |
|
||||||
|
| VER-16 | frontend/src/pages/System/* | FR-6/7 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# DV-0005：全文检索 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`search_service.py`（Whoosh + `ChineseAnalyzer`/jieba）。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- GET /api/v1/search/documents
|
||||||
|
- POST /api/v1/search/rebuild-index
|
||||||
|
|
||||||
|
## 索引结构
|
||||||
|
- `search_index` 本地目录；schema：project_id/path/title/content；`path` 用 `<project_id>:<path>` 唯一化。
|
||||||
|
|
||||||
|
## 变更同步
|
||||||
|
- 文件读写路径调用 `search_service.update_doc/delete_document`（files.py 导入触发）。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# DV-0005：全文检索 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0004
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
基于本地 Whoosh 索引对文档内容/标题做中文关键词检索。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：文档索引维护、关键词检索、重建索引。
|
||||||
|
- **Out**：语义向量检索（归 DV-0006）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为用户，我希望按关键词搜到项目文档，以便快速定位。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-9 | Whoosh 中文检索 + 变更同步 + 重建 | 命中标题/内容；jieba 中文分词 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-11 | 文档变更时同步索引（ADR-0006） |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0005：全文检索 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-5 | Whoosh 中文索引 + 变更同步 + 重建 | FR-9 | 已完成 |
|
||||||
|
| TS-5a | 检索结果高亮/命中 | FR-9 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# DV-0005：全文检索 – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
| VER | 测试 | 证明 | 结果 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| VER-3 | test_search_service.py | FR-9, TS-5 | 通过 |
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 创建文档后立即可被关键词命中
|
||||||
|
- [x] 删除文档后不再命中
|
||||||
|
- [x] 重建索引可用
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-12 | services/search_service.py | ADR-0004, FR-9 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# DV-0006：ZVec 向量化 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`zvec_service.py`、`file_vector_sync_service.py`、`project_vectorization_task_service.py`。
|
||||||
|
|
||||||
|
## 分块
|
||||||
|
- 字符滑动窗口：chunk_size（默认 800）/ overlap（150）；每块生成 anchor、content_hash。
|
||||||
|
|
||||||
|
## 写入
|
||||||
|
- ZVec collection 每项目一个（`vector_index/<project_id>`）；embedding 用配置的 `model_type=embedding` 模型。
|
||||||
|
- `document_vector` 表逐块记录（zvec_id/chunk_text/status/error）。
|
||||||
|
|
||||||
|
## 触发
|
||||||
|
- 写路径：`ProjectFileService → FileVectorSyncService`（后台、按项目串行）。
|
||||||
|
- 全量：`ProjectVectorizationTaskService`（后台任务 + 进度表）。
|
||||||
|
|
||||||
|
## 维度变更
|
||||||
|
- 检测现有 collection 维度与模型不一致 → 重建 collection，旧向量作废需重向量化。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# DV-0006：ZVec 向量化 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0004, ADR-0006
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
将项目 MD 文档分块向量化，写入本地 ZVec 库并记录状态，为 RAG 提供语义检索基础。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：MD 分块向量化、增量同步、删除清理、整项目后台任务。
|
||||||
|
- **Out**：对话本身（归 DV-0007）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为用户，我希望项目文档自动向量化，以便后续语义问答。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-10 | MD 分块 + embedding + ZVec 写入 + document_vector 记录 | 保存/新建/重命名触发；删除清理；PDF 不向量化；维度变更重建 |
|
||||||
|
| FR-11 | 整项目向量化后台任务 + 进度 | pending/running/success/failed 持久化 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-10 | embedding 失败不阻断；无配置跳过 |
|
||||||
|
| NFR-11 | 向量维度变更重建 collection 并全量重向量化 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# DV-0006：ZVec 向量化 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-6 | 分块、embedding、collection、增量同步、进度 | FR-10/11 | 已完成 |
|
||||||
|
| TS-6a | MD 变更触发重向量化/删除清理 | FR-10 | 已完成 |
|
||||||
|
| TS-6b | 维度变更重建 collection | FR-10, NFR-11 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# DV-0006：ZVec 向量化 – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
| VER | 测试 | 证明 | 结果 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| VER-2 | test_model_and_vector_configuration.py | FR-10, TS-6 | 通过 |
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 保存 MD 触发向量化、document_vector 出现记录
|
||||||
|
- [x] 删除 MD 清理向量
|
||||||
|
- [x] PDF 不向量化
|
||||||
|
- [x] 维度变更后重建 collection
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | models/document_vector.py, project_vectorization_task.py | FR-10/11 |
|
||||||
|
| VER-12 | services/zvec_service.py, file_vector_sync_service.py | ADR-0004/6 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# DV-0007：知识库 RAG 对话 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`chat.py`（API）、`rag_service.py`（检索/生成/对齐）、`zvec_service.search_similar`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `chat_session`、`chat_message`（status/duration_ms/thinking_log/referenced_files）。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- POST /api/v1/chat/sessions、GET /chat/sessions、GET|PUT|DELETE /chat/sessions/{id}
|
||||||
|
- GET /chat/sessions/{id}/messages、DELETE /chat/messages/{id}
|
||||||
|
- POST /chat/send、/chat/send/stream、/chat/messages/{id}/interrupt
|
||||||
|
- GET /chat/search、（向量化系列归 DV-0006）
|
||||||
|
|
||||||
|
## 检索与生成
|
||||||
|
1. `search_similar`（top_k*4 命中去重，每文件最多 MAX_CHUNKS_PER_DOCUMENT=3）。
|
||||||
|
2. 上下文围绕命中锚点截取（CHUNK_CONTEXT_WINDOW=1200）。
|
||||||
|
3. 系统提示词约束：仅依知识库、必须 [n] 引用。
|
||||||
|
4. 历史仅注入最近用户问题（HISTORY_USER_QUESTION_LIMIT=3）作为指代。
|
||||||
|
|
||||||
|
## 引用对齐
|
||||||
|
- `align_citation_quotes`：答案论断句 ↔ 原文候选句向量对齐，回填 quote_occurrences。
|
||||||
|
|
||||||
|
## 状态与降级
|
||||||
|
- 中断：status=interrupted；旧数据按只读兼容判定（不回溯改库）。
|
||||||
|
- 对齐/embedding 失败 → 降级不返回支撑句。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,26 @@
|
||||||
|
# DV-0007：知识库 RAG 对话 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0004, ADR-0005
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
基于向量检索 + LLM 生成可溯源的问答对话。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：会话/消息管理、检索 + 生成、流式、中断、引用支撑句。
|
||||||
|
- **Out**：多轮复杂 Agent（仅单轮检索增强 + 指代历史）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为用户，我希望问知识库问题并看到带引用的可验证答案。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-12 | 向量检索 + LLM 生成 + 会话管理 + 流式 | 答案带 [n] 引用；检索按文件去重；历史仅注入最近用户问题 |
|
||||||
|
| FR-19 | 引用支撑句对齐 + 消息规范化 | [n] 按出现顺序回填 quote_occurrences；旧数据只读兼容 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-10 | 引用对齐/embedding 失败降级 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,8 @@
|
||||||
|
# DV-0007：知识库 RAG 对话 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-7 | 会话/消息/流式/中断/引用对齐 | FR-12/19 | 已完成 |
|
||||||
|
| TS-7a | 引用规范化与去重 | FR-19 | 已完成 |
|
||||||
|
| TS-7b | 历史指代处理 | FR-12 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
# DV-0007：知识库 RAG 对话 – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
| VER | 测试 | 证明 | 结果 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| VER-1 | test_chat_citations.py | FR-12/19, TS-7 | 通过 |
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 创建会话、发消息、流式接收
|
||||||
|
- [x] 答案带 [n] 引用并可回填支撑句
|
||||||
|
- [x] 中断消息正确处理
|
||||||
|
- [x] 检索命中高亮
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-11 | api/v1/chat.py | FR-12 |
|
||||||
|
| VER-12 | services/rag_service.py | ADR-0004/5 |
|
||||||
|
| VER-16 | frontend/src/pages/Chat/* | FR-12 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,18 @@
|
||||||
|
# DV-0008：LLM 模型配置 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`llm_model_configs.py`、`llm_provider_service.py`、模型 `llm_model_config.py`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `llm_model_config`（model_code/model_type/provider/endpoint/api_key/llm_model_name/llm_timeout/type_config/is_active/is_default）。
|
||||||
|
|
||||||
|
## type_config 差异字段
|
||||||
|
- chat：temperature/top_p/max_tokens/system_prompt
|
||||||
|
- embedding：dimension/chunk_size/chunk_overlap
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- /api/v1/llm-model-configs/*（CRUD、status、default、test、providers）
|
||||||
|
|
||||||
|
## 默认选择
|
||||||
|
- embedding 默认取 is_active 且 model_type=embedding，is_default 优先。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# DV-0008：LLM 模型配置 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0004
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
管理 chat/embedding 两类模型配置，供对话与向量化使用。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：模型配置 CRUD、启停、默认、连通性测试、类型差异参数。
|
||||||
|
- **Out**：密钥托管/加密（当前 API Key 明文字段，见 OI 关注）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为管理员，我希望配置并测试大模型，以便对话与向量化使用。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-13 | 模型配置 CRUD/启停/默认/测试 | chat 与 embedding 分离存储；维度等差异参数 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-10 | 无默认 embedding 时向量化跳过并告警 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0008：LLM 模型配置 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-8 | chat/embedding 配置、测试、默认标记 | FR-13 | 已完成 |
|
||||||
|
| TS-8a | provider 归一化与类型差异参数 | FR-13 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# DV-0008：LLM 模型配置 – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
| VER | 测试 | 证明 | 结果 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| VER-2 | test_model_and_vector_configuration.py | FR-13, TS-8 | 通过 |
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 新增/编辑/启停 chat 与 embedding 配置
|
||||||
|
- [x] 设置默认模型
|
||||||
|
- [x] 连通性测试
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | models/llm_model_config.py | FR-13 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# DV-0009：分享与公开预览 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`shares.py`、`preview.py`、模型 `share.py`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `share_links`（share_type: project/file、share_code、file_path、access_pass、status）。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- /api/v1/shares/projects/{id}（settings）、/files/share（文件分享）
|
||||||
|
- /api/v1/shares/{project|file}/{share_code}/{verify,tree,file,document,export-pdf,assets}
|
||||||
|
|
||||||
|
## 预览
|
||||||
|
- 公开只读：树/文档/PDF 导出/资源读取，均以 share_code + 可选密码鉴权。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,24 @@
|
||||||
|
# DV-0009：分享与公开预览 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
通过公开分享链接（可带访问密码）让访客浏览项目/文件。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：项目/文件分享链接、密码校验、公开预览树/文档/PDF/资源。
|
||||||
|
- **Out**：分享编辑权（分享为只读预览）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为访客，我希望通过链接（+密码）预览文档，以便无需账号即可阅读。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-14 | 分享链接 + 密码 + 公开预览 | share_code 唯一；密码校验；预览树/文档/导出 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-4 | 分享访问受密码保护；资源防盗链（鉴权） |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0009：分享与公开预览 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-9 | 项目/文件分享、预览、导出 | FR-14 | 已完成 |
|
||||||
|
| TS-9a | 分享密码与资源防盗链 | FR-14, NFR-4 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,14 @@
|
||||||
|
# DV-0009：分享与公开预览 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 创建项目/文件分享链接
|
||||||
|
- [x] 密码校验通过后可预览
|
||||||
|
- [x] 预览树/文档正常、PDF 导出可用
|
||||||
|
- [x] 无密码/密码错误时资源访问受限
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-11 | api/v1/shares.py, preview.py | FR-14 |
|
||||||
|
| VER-16 | frontend/src/pages/Preview/* | FR-14 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# DV-0010：通知 / 日志 / Git / 导出 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`notifications.py`、`logs.py`、`git_repos.py`、`project_export_service.py`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `notifications`、`operation_logs`、`project_git_repos`。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- /api/v1/notifications/*（unread-count/read/mark-all/system）
|
||||||
|
- /api/v1/logs/*（列表/stats）
|
||||||
|
- /api/v1/projects/{id}/git-repos + /git/{pull,push}
|
||||||
|
- /api/v1/files/{id}/export-*（ZIP/PDF）
|
||||||
|
|
||||||
|
## 导出
|
||||||
|
- `ProjectExportService` 后台线程打包 ZIP，任务带进度/TTL 清理。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,28 @@
|
||||||
|
# DV-0010：通知 / 日志 / Git / 导出 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0006, ADR-0007
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
提供通知、操作审计日志、Git 仓库集成与 ZIP/PDF 导出能力。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：用户通知、操作日志、Git pull/push、后台导出。
|
||||||
|
- **Out**：第三方消息渠道（短信/邮件网关）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为用户/管理员，我希望收到系统通知、查看审计日志并按需导出项目内容。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-15 | 通知 + 操作日志 | 通知分类；operation_logs 记录用户/类型/资源/IP/UA |
|
||||||
|
| FR-16 | Git 仓库集成 | 绑定仓库 + pull/push |
|
||||||
|
| FR-17 | 导出 ZIP/PDF | 后台任务+进度；WeasyPrint PDF |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-7 | 操作入库审计 |
|
||||||
|
| NFR-11 | export 后台任务同向量化模式（ADR-0006） |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0010：通知 / 日志 / Git / 导出 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-10 | 通知、日志、Git、导出 | FR-15/16/17 | 已完成 |
|
||||||
|
| TS-10a | 导出后台任务（进度/TTL） | FR-17, ADR-0006 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,16 @@
|
||||||
|
# DV-0010：通知 / 日志 / Git / 导出 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 通知产生与已读标记
|
||||||
|
- [x] 操作日志记录正确
|
||||||
|
- [x] Git 仓库绑定与 pull/push
|
||||||
|
- [x] 项目导出 ZIP 带进度、文档导出 PDF
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-10 | models/{notification,log,git_repo}.py | FR-15/16 |
|
||||||
|
| VER-11 | api/v1/{notifications,logs,git_repos}.py | FR-15/16 |
|
||||||
|
| VER-12 | services/project_export_service.py | FR-17, ADR-0006 |
|
||||||
|
| VER-14 | core/migrations.py | ADR-0007, FR-15 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# DV-0011：MCP 接入 – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
`app/mcp/server.py`、`app/mcp/context.py`、模型 `mcp_bot.py`；挂载于 `main.py` 的 `/mcp`。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- `mcp_bots`（user_id 唯一、bot_id、bot_secret、status、last_used_at）。
|
||||||
|
|
||||||
|
## 认证
|
||||||
|
1. X-Bot-Id 查 mcp_bots → 校验 X-Bot-Secret → 映射到用户 → 以该用户执行工具。
|
||||||
|
|
||||||
|
## 工具示例
|
||||||
|
- list_created_projects、create_project 等；均经权限判定（require_project_read/write_access）。
|
||||||
|
|
||||||
|
## 挂载
|
||||||
|
- `app.mount("/mcp", MCPHeaderAuthApp(mcp_http_app))`；前端 Nginx 不得对 /mcp 301/302。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# DV-0011：MCP 接入 – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Implemented
|
||||||
|
- **关联 ADR**：ADR-0005（可溯源/开放）
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
通过 MCP Streamable HTTP 让外部 Agent 以用户身份访问 NexDocs 能力。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：后端内嵌 MCP server、bot 凭据管理、工具暴露。
|
||||||
|
- **Out**：独立 MCP 部署（已废弃 mcp_server/）。
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为外部 Agent，我希望用 bot 凭据调用 NexDocs 工具管理项目/文档。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-18 | MCP /mcp + X-Bot-Id/Secret 认证 | streamableHttp；bot 映射用户；401 未带凭据 |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-4 | 工具以用户身份 + 权限判定执行 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# DV-0011：MCP 接入 – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS（全局/切片） | 切片 | 关联规格 | 状态 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| TS-11 | MCP server 内嵌 + bot 凭据管理 | FR-18 | 已完成 |
|
||||||
|
| TS-11a | 工具权限判定 | FR-18, NFR-4 | 已完成 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# DV-0011：MCP 接入 – 验证（Verification）
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [x] 携带 X-Bot-Id/Secret 可调用工具
|
||||||
|
- [x] 未带凭据 /mcp 返回 401
|
||||||
|
- [x] 工具以用户身份与权限执行
|
||||||
|
- [x] 前端不重定向 /mcp
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
| VER | 证据 | 证明 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| VER-11 | api/v1/auth.py（mcp-credentials） | FR-18 |
|
||||||
|
| VER-13 | main.py（/mcp 挂载） | FR-18 |
|
||||||
|
| 集成 | integrations/mcp.md、integrations/mcp.md | FR-18 |
|
||||||
|
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# 功能规格索引（Specs）
|
||||||
|
|
||||||
|
本目录登记每个功能/变更单元（DV）的四文件规格：**spec（为什么/做什么）、design（怎么做）、tasks（实施切片）、verification（验收证据）**。
|
||||||
|
|
||||||
|
## 索引（规格 ↔ 任务 ↔ 证据）
|
||||||
|
|
||||||
|
| DV | 单元 | 主要规格(FR) | 关键任务(TS) | 关键证据(VER) | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- | --- |
|
||||||
|
| [DV-0001](DV-0001-auth/spec.md) | 认证与会话 | FR-1 | TS-1 | VER-10/11/15 | Implemented |
|
||||||
|
| [DV-0002](DV-0002-project-filesystem/spec.md) | 项目与文件系统 | FR-2/3/5 | TS-2 | VER-10/11/12 | Implemented |
|
||||||
|
| [DV-0003](DV-0003-document-editing/spec.md) | 文档编辑与文件操作 | FR-4 | TS-3 | VER-11/12/16 | Implemented |
|
||||||
|
| [DV-0004](DV-0004-rbac-admin/spec.md) | RBAC 与系统管理 | FR-6/7/8 | TS-4 | VER-10/11/16 | Implemented |
|
||||||
|
| [DV-0005](DV-0005-fulltext-search/spec.md) | 全文检索 | FR-9 | TS-5 | VER-3/12 | Implemented |
|
||||||
|
| [DV-0006](DV-0006-zvec-vectorization/spec.md) | ZVec 向量化 | FR-10/11 | TS-6 | VER-2/10/12 | Implemented |
|
||||||
|
| [DV-0007](DV-0007-rag-chat/spec.md) | 知识库 RAG 对话 | FR-12/19 | TS-7 | VER-1/11/12/16 | Implemented |
|
||||||
|
| [DV-0008](DV-0008-llm-model-config/spec.md) | LLM 模型配置 | FR-13 | TS-8 | VER-2/10 | Implemented |
|
||||||
|
| [DV-0009](DV-0009-share-preview/spec.md) | 分享与公开预览 | FR-14 | TS-9 | VER-11/16 | Implemented |
|
||||||
|
| [DV-0010](DV-0010-notify-log-git-export/spec.md) | 通知/日志/Git/导出 | FR-15/16/17 | TS-10 | VER-10/11/12/14 | Implemented |
|
||||||
|
| [DV-0011](DV-0011-mcp-integration/spec.md) | MCP 接入 | FR-18 | TS-11 | VER-11/13 | Implemented |
|
||||||
|
|
||||||
|
> 说明：状态为 SDD 核对仓库实现后的推断。DOC 中列举的 TS 编号沿用原 SDD 单文件版的全局编号，spec 内亦给出所属 DV 的切片编号。
|
||||||
|
|
||||||
|
## 新建规格流程
|
||||||
|
1. 复制 `_template/` 到 `DV-NNNN-short-name/`。
|
||||||
|
2. 按 governance 申请编号、过审。
|
||||||
|
3. 补齐四文件后回填本索引。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
# DV-NNNN：<功能名> – 设计（Design）
|
||||||
|
|
||||||
|
## 上下文
|
||||||
|
- 涉及模块、数据流、依赖。
|
||||||
|
|
||||||
|
## 结构设计
|
||||||
|
- 代码/模块组织。
|
||||||
|
|
||||||
|
## 数据模型
|
||||||
|
- 涉及表/字段（指向 DATABASE.md 细节）。
|
||||||
|
|
||||||
|
## 接口设计
|
||||||
|
- API 端点 / 交互。
|
||||||
|
|
||||||
|
## 状态与降级
|
||||||
|
- 边界情况、健壮降级（对齐 NFR-10）。
|
||||||
|
|
||||||
|
## 变更影响
|
||||||
|
- 对既有 DV/ADR 的影响。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
# DV-NNNN：<功能名> – 规格（Spec）
|
||||||
|
|
||||||
|
- **状态**：Draft | Review | Approved | Implemented | Verified
|
||||||
|
- **关联 ADR**：ADR-NNNN
|
||||||
|
|
||||||
|
## 目标（为什么做）
|
||||||
|
一段话说明该功能要解决的业务问题或带来的价值（对齐 PO）。
|
||||||
|
|
||||||
|
## 范围
|
||||||
|
- **In**：……
|
||||||
|
- **Out**：……
|
||||||
|
|
||||||
|
## 用户故事
|
||||||
|
> 作为 <角色>，我希望 <能力>，以便 <收益>。
|
||||||
|
|
||||||
|
## 功能需求（FR）
|
||||||
|
| ID | 需求描述 | 验收要点 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| FR-N | … | … |
|
||||||
|
|
||||||
|
## 非功能需求（NFR）
|
||||||
|
| ID | 需求 |
|
||||||
|
| --- | --- |
|
||||||
|
| NFR-N | … |
|
||||||
|
|
||||||
|
## 边界与约束
|
||||||
|
- 约束（技术/数据/权限）。
|
||||||
|
|
||||||
|
## 开放问题
|
||||||
|
- 占位。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,10 @@
|
||||||
|
# DV-NNNN：<功能名> – 任务（Tasks）
|
||||||
|
|
||||||
|
| TS | 切片 | 关联规格 | 依赖 | 状态 |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| TS-N | … | FR-N | … | 未开始 |
|
||||||
|
|
||||||
|
## 任务规则
|
||||||
|
- 每个切片可独立评审/合并。
|
||||||
|
- 完成勾选并同步更新 verification。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,17 @@
|
||||||
|
# DV-NNNN：<功能名> – 验证（Verification）
|
||||||
|
|
||||||
|
## 自动化测试
|
||||||
|
| VER | 测试 | 证明规格/任务 | 结果 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| VER-N | … | FR-N / TS-N | 通过/未跑 |
|
||||||
|
|
||||||
|
## 手工验收清单
|
||||||
|
- [ ] 场景 1
|
||||||
|
- [ ] 场景 2
|
||||||
|
|
||||||
|
## 结构性证据
|
||||||
|
- 涉及文件/模块。
|
||||||
|
|
||||||
|
## 已知缺口
|
||||||
|
- 说明未覆盖项（可引用 OI-3）。
|
||||||
|
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
{
|
{
|
||||||
"name": "nex-docus-frontend",
|
"name": "nex-docus-frontend",
|
||||||
"version": "1.0.0",
|
"version": "0.9.9",
|
||||||
"lockfileVersion": 3,
|
"lockfileVersion": 3,
|
||||||
"requires": true,
|
"requires": true,
|
||||||
"packages": {
|
"packages": {
|
||||||
"": {
|
"": {
|
||||||
"name": "nex-docus-frontend",
|
"name": "nex-docus-frontend",
|
||||||
"version": "1.0.0",
|
"version": "0.9.9",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@ant-design/icons": "^5.2.6",
|
"@ant-design/icons": "^5.2.6",
|
||||||
"@bytemd/plugin-breaks": "^1.22.0",
|
"@bytemd/plugin-breaks": "^1.22.0",
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
{
|
{
|
||||||
"name": "nex-docus-frontend",
|
"name": "nex-docus-frontend",
|
||||||
"private": true,
|
"private": true,
|
||||||
"version": "1.0.0",
|
"version": "0.9.9",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "vite",
|
"dev": "vite",
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue