From 03701c5d496943f9ea9f0a0303250dd46b115e60 Mon Sep 17 00:00:00 2001 From: lewis_yan Date: Fri, 3 Apr 2026 13:39:52 +0800 Subject: [PATCH 1/3] docs: add GitLab MR template --- .gitlab/merge_request_templates/default.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .gitlab/merge_request_templates/default.md diff --git a/.gitlab/merge_request_templates/default.md b/.gitlab/merge_request_templates/default.md new file mode 100644 index 0000000..d8c48e5 --- /dev/null +++ b/.gitlab/merge_request_templates/default.md @@ -0,0 +1,19 @@ +## 变更描述 + + +## 关联需求 + + +## 变更类型 +- [ ] Feature +- [ ] Bugfix +- [ ] Hotfix +- [ ] Refactor + +## 自检清单 +- [ ] 代码已通过 Pre-commit 检查（后端 ruff / 前端 lint-staged） +- [ ] 已添加必要的测试 +- [ ] 文档已更新（如需） + +## Reviewer 备注 + From 69097e48b8dd19b75cf8ab9e56a512368fb11a6b Mon Sep 17 00:00:00 2001 From: lewis_yan Date: Fri, 3 Apr 2026 13:53:19 +0800 Subject: [PATCH 2/3] chore: update .gitignore and CLAUDE.md to exclude superpowers files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .claude/ directory to .gitignore - Add docs/scripts-documentation.md to .gitignore - Add git注意事项 section to CLAUDE.md - Remove tracked superpowers/docs files from git index --- .gitignore | 2 + CLAUDE.md | 7 + docs/scripts-documentation.md | 295 ---------------- .../2026-04-03-git-collaboration-plan.md | 281 --------------- .../specs/2026-04-02-ai-agent-design.md | 322 ------------------ ...uote-deadline-email-notification-design.md | 93 ----- .../2026-04-03-git-collaboration-design.md | 271 --------------- 7 files changed, 9 insertions(+), 1262 deletions(-) delete mode 100644 docs/scripts-documentation.md delete mode 100644 docs/superpowers/plans/2026-04-03-git-collaboration-plan.md delete mode 100644 docs/superpowers/specs/2026-04-02-ai-agent-design.md delete mode 100644 docs/superpowers/specs/2026-04-02-quote-deadline-email-notification-design.md delete mode 100644 docs/superpowers/specs/2026-04-03-git-collaboration-design.md diff --git a/.gitignore b/.gitignore index d5e0305..d44ce9a 100644 --- a/.gitignore +++ b/.gitignore @@ -12,5 +12,7 @@ web/package-lock.json .planning/ # Superpowers files +.claude/ docs/superpowers/ +docs/scripts-documentation.md .pids/ \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 978c5f1..b441c6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,3 +103,10 @@ Backend settings are split: - The `miscprocurement` app handles询价 (RFQ) and cost template building - Supplier quotations are managed in `pissupplier` app - Default demo credentials: `superadmin` / `admin123456` + +## Git 注意事项 + +**不要提交本地文档和 superpowers 相关文件**： +- `.claude/` 目录下的 superpowers 相关文件（`.planning/`、skills 等） +- `docs/` 目录下的本地文档 +- 这些文件每个人开发任务不同，不应提交到仓库 diff --git a/docs/scripts-documentation.md b/docs/scripts-documentation.md deleted file mode 100644 index 05088be..0000000 --- a/docs/scripts-documentation.md +++ /dev/null @@ -1,295 +0,0 @@ -# 脚本文档 - -PIS 项目跨平台服务管理脚本。 - -## 概述 - -| 脚本 | Windows (PowerShell) | Unix/Linux/macOS (Bash) | -|------|---------------------|------------------------| -| 启动后端 | `start-backend.ps1` | `start-backend.sh` | -| 启动前端 | `start-frontend.ps1` | `start-frontend.sh` | -| 启动 Celery | `start-celery.ps1` | `start-celery.sh` | -| 停止所有 | `stop-all.ps1` | `stop-all.sh` | -| 停止 Celery | `stop-celery.ps1` | `stop-celery.sh` | -| 查看日志 | `view-logs.ps1` | `view-logs.sh` | -| 检查状态 | `check-status.ps1` | `check-status.sh` | - -## 快速开始 - -### Windows (PowerShell) - -```powershell -# 启动所有服务 -.\make.ps1 dev - -# 停止所有服务 -.\make.ps1 stop - -# 查看日志 -.\make.ps1 logs - -# 检查状态 -.\make.ps1 status -``` - -### Unix/Linux/macOS (Bash) - -```bash -# 启动所有服务 -make dev - -# 停止所有服务 -make stop - -# 查看日志 -make logs - -# 检查状态 -make status -``` - -## 使用方法 - -### make.ps1 命令 (Windows PowerShell) - -| 命令 | 说明 | -|------|------| -| `.\make.ps1 help` | 显示所有可用命令 | -| `.\make.ps1 dev` | 启动开发环境（前端 + 后端 + Celery） | -| `.\make.ps1 dev-backend` | 仅启动后端 | -| `.\make.ps1 dev-frontend` | 仅启动前端 | -| `.\make.ps1 dev-celery` | 仅启动 Celery | -| `.\make.ps1 stop` | 停止所有服务 | -| `.\make.ps1 restart` | 重启所有服务 | -| `.\make.ps1 restart-celery` | 仅重启 Celery | -| `.\make.ps1 logs` | 查看所有日志 | -| `.\make.ps1 logs-backend` | 查看后端日志 | -| `.\make.ps1 logs-frontend` | 查看前端日志 | -| `.\make.ps1 logs-celery` | 查看 Celery 日志 | -| `.\make.ps1 status` | 检查服务状态 | -| `.\make.ps1 clean-logs` | 清理日志文件 | -| `.\make.ps1 clean-pids` | 清理 PID 文件 | - -### make 命令 (Unix/Linux/macOS Bash) - -| 命令 | 说明 | -|------|------| -| `make help` | 显示所有可用命令 | -| `make dev` | 启动开发环境（前端 + 后端 + Celery） | -| `make dev-backend` | 仅启动后端 | -| `make dev-frontend` | 仅启动前端 | -| `make dev-celery` | 仅启动 Celery | -| `make stop` | 停止所有服务 | -| `make restart` | 重启所有服务 | -| `make restart-celery` | 仅重启 Celery | -| `make logs` | 查看所有日志 | -| `make logs-backend` | 查看后端日志 | -| `make logs-frontend` | 查看前端日志 | -| `make logs-celery` | 查看 Celery 日志 | -| `make status` | 检查服务状态 | -| `make clean-logs` | 清理日志文件 | -| `make clean-pids` | 清理 PID 文件 | - -## 直接调用脚本 - -### Windows PowerShell - -```powershell -# 启动后端 -.\scripts\start-backend.ps1 [dev|prod] - -# 启动前端 -.\scripts\start-frontend.ps1 [dev|prod] - -# 启动 Celery -.\scripts\start-celery.ps1 [dev|prod] - -# 停止所有服务 -.\scripts\stop-all.ps1 - -# 仅停止 Celery -.\scripts\stop-celery.ps1 - -# 查看日志 -.\scripts\view-logs.ps1 [backend|frontend|celery|all] - -# 检查状态 -.\scripts\check-status.ps1 -``` - -### Unix/Linux/macOS Bash - -```bash -# 启动后端 -./scripts/start-backend.sh [dev|prod] - -# 启动前端 -./scripts/start-frontend.sh [dev|prod] - -# 启动 Celery -./scripts/start-celery.sh [dev|prod] - -# 停止所有服务 -./scripts/stop-all.sh - -# 仅停止 Celery -./scripts/stop-celery.sh - -# 查看日志 -./scripts/view-logs.sh [backend|frontend|celery|all] - -# 检查状态 -./scripts/check-status.sh -``` - -## 环境参数 - -- `dev`（默认）：开发模式，带热重载 -- `prod`：生产模式，使用优化构建 - -### Windows PowerShell -```powershell -.\make.ps1 dev -ENV prod -``` - -### Unix/Linux/macOS -```bash -ENV=prod make dev -``` - -## 端口 - -| 服务 | 端口 | -|------|------| -| 后端 (Django) | 8000 | -| 前端 (Vue) | 8080 | - -## 日志文件 - -日志存储在 `backend/logs/`： - -- `backend.log` - 后端应用日志 -- `frontend.log` - 前端应用日志 -- `celery_worker.log` - Celery Worker 日志 -- `celery_beat.log` - Celery Beat 调度器日志 - -## PID 文件 - -PID 文件存储在 `.pids/`： - -- `backend.pid` -- `frontend.pid` -- `celery_worker.pid` -- `celery_beat.pid` - -## 跨平台兼容性 - -### Windows PowerShell -- 支持 Windows PowerShell 5.1 及 PowerShell 7+ -- 使用 `System.Net.Sockets.TcpClient` 检查端口 -- 使用 WMI 查询检测进程（兼容 PS 5.1 和 PS 7+） -- 所有输出使用英文（避免编码问题） - -### Unix/Linux/macOS -- 需要 Bash 4.0+ -- 使用 `nc`（netcat）检查端口（如果可用） -- 使用 `pgrep` 和 `pkill` 管理进程 -- 输出使用中文 - -### Windows PowerShell Celery 已知问题 - -**Celery 在 Windows PowerShell 上有已知的兼容性问题。** - -问题原因：PowerShell 的 `Start-Process` 与 Celery 的多进程池（billiard）不兼容，导致以下错误： -- `PermissionError: [WinError 5] 拒绝访问` -- `OSError: [WinError 6] 句柄无效` - -**推荐解决方案：使用 Git Bash** - -在 Windows 上，推荐使用 Git Bash 运行 Celery 脚本： - -```bash -# 启动 Celery (推荐) -bash scripts/start-celery.sh - -# 停止 Celery -bash scripts/stop-celery.sh -``` - -Git Bash 使用 `nohup` 和 `&` 后台运行，与 Celery 的多进程机制完全兼容。 - -**如需使用 PowerShell：** - -可以尝试使用 `--pool solo` 参数（单进程模式）： - -```powershell -.\scripts\start-celery.ps1 -``` - -但这可能会影响 Celery 的性能和稳定性。 - -## 依赖要求 - -### 后端 -- Python 3.10+ -- Django 4.2.14 -- uvicorn（开发）或 gunicorn（生产） -- Celery + Redis broker - -### 前端 -- Node.js 18+ -- Yarn 或 npm - -### Celery -- Redis 服务运行中 -- django-celery-beat - -## 故障排除 - -### 后端无法启动 -1. 检查端口 8000 是否被占用 -2. 检查 Python 依赖是否安装 -3. 检查 Django 配置：确保 `backend/conf/env.py` 已配置 - -### 前端无法启动 -1. 检查 Node.js 是否安装 -2. 安装依赖：`cd web && yarn install` -3. 检查端口 8080 是否被占用 - -### Celery 无法启动 -1. 检查 Redis 是否运行 -2. 执行数据库迁移：`python manage.py migrate` -3. 查看 Celery 日志 -4. **Windows 用户**：如果使用 PowerShell 启动失败，请改用 Git Bash： - ```bash - bash scripts/start-celery.sh - ``` - 这是 Windows 上的已知问题，PowerShell 的进程管理机制与 Celery 不兼容。 - -### 编码问题 -如果 PowerShell 显示乱码，确保使用 UTF-8 with BOM 编码保存的脚本文件。 - -## 脚本架构 - -``` -scripts/ -├── start-backend.ps1/.sh # 启动 Django 后端服务 -├── start-frontend.ps1/.sh # 启动 Vue 前端开发服务器 -├── start-celery.ps1/.sh # 启动 Celery worker 和 beat -├── stop-all.ps1/.sh # 停止所有服务 -├── stop-celery.ps1/.sh # 仅停止 Celery 服务 -├── view-logs.ps1/.sh # 查看和跟踪日志文件 -├── check-status.ps1/.sh # 检查服务运行状态 -├── Makefile # Unix/Linux/macOS 编排 -└── make.ps1 # Windows PowerShell 编排 -``` - -## 注意事项 - -- 所有脚本都是幂等的 - 多次运行是安全的 -- 脚本会检测服务是否已运行，已运行则跳过启动 -- 使用 PID 文件实现优雅关闭 -- 停止时会清理残留进程 -- PowerShell 脚本输出使用英文，避免编码问题 -- Bash 脚本输出使用中文 -- **Windows 用户**：建议使用 Git Bash 运行 Celery 脚本，以避免进程兼容性问题 diff --git a/docs/superpowers/plans/2026-04-03-git-collaboration-plan.md b/docs/superpowers/plans/2026-04-03-git-collaboration-plan.md deleted file mode 100644 index 28c0ee8..0000000 --- a/docs/superpowers/plans/2026-04-03-git-collaboration-plan.md +++ /dev/null @@ -1,281 +0,0 @@ -# Git 协作规范实施计划 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**目标：** 建立标准 Git 协作规范，包含 Git Flow 分支模型、PR 模板、Code Review 流程、Git Hooks（后端 pre-commit + 前端 husky） - -**架构概述：** -- 后端 Python 项目使用 `pre-commit` + `ruff` 管理 Git Hooks -- 前端 Node.js 项目使用 `husky` + `lint-staged` 管理 Git Hooks -- PR 模板放在 `.github/` 目录（GitHub 自动识别） -- Jenkins CI 配置在各自的 Jenkinsfile 中（后端已存在） - -**技术栈：** pre-commit, ruff, husky, lint-staged - ---- - -## 文件结构 - -``` -backend/ - ├── .pre-commit-config.yaml # 新建：pre-commit hooks 配置 - └── requirements.txt # 修改：添加 pre-commit, ruff - -web/ - ├── .husky/ # 新建：husky git hooks 目录 - │ └── pre-commit # 新建：pre-commit hook script - ├── .lintstagedrc.json # 新建：lint-staged 配置 - └── package.json # 修改：添加 husky, lint-staged - -.github/ - └── PULL_REQUEST_TEMPLATE.md # 新建：PR 模板 -``` - ---- - -## 任务清单 - -### 任务 1：后端 pre-commit 配置（ruff） - -**文件：** -- 创建：`backend/.pre-commit-config.yaml` -- 修改：`backend/requirements.txt` - -- [ ] **Step 1: 创建 backend/.pre-commit-config.yaml** - -```yaml -# 后端 pre-commit hooks 配置 -# 安装方式：pip install pre-commit && pre-commit install -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 - hooks: - - id: trailing-whitespace - - id: end-of-file-fixer - - id: check-yaml - - id: check-added-large-files - args: ['--maxkb=5000'] - - id: check-merge-conflict - - id: debug-statements - - - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.9.0 - hooks: - - id: ruff - args: [--fix] - - id: ruff-format -``` - -- [ ] **Step 2: 验证文件创建** - -命令：`cat backend/.pre-commit-config.yaml` -预期：显示上述 yaml 内容 - -- [ ] **Step 3: 添加依赖到 requirements.txt** - -在 `backend/requirements.txt` 末尾添加： - -``` -# Git hooks -pre-commit>=3.0.0 -ruff>=0.9.0 -``` - -- [ ] **Step 4: 验证 requirements.txt 更新** - -命令：`grep -E "pre-commit|ruff" backend/requirements.txt` -预期：显示 pre-commit 和 ruff 两行 - -- [ ] **Step 5: 提交** - -```bash -git add backend/.pre-commit-config.yaml backend/requirements.txt -git commit -m "feat(git): add pre-commit with ruff for backend - -- Add .pre-commit-config.yaml with ruff (lint + format) -- Add pre-commit and ruff to requirements.txt -- Ruff replaces flake8 + black + isort (10-100x faster)" -``` - ---- - -### 任务 2：前端 husky + lint-staged 配置 - -**文件：** -- 创建：`web/.husky/pre-commit` -- 创建：`web/.lintstagedrc.json` -- 修改：`web/package.json` - -- [ ] **Step 1: 安装 husky 和 lint-staged** - -```bash -cd web -npm install husky lint-staged -D -``` - -- [ ] **Step 2: 初始化 husky** - -```bash -cd web -npx husky install -``` - -- [ ] **Step 3: 创建 .lintstagedrc.json** - -```json -{ - "*.{js,vue,ts,jsx,tsx}": [ - "eslint --fix", - "prettier --write" - ], - "*.{css,scss,vue}": [ - "prettier --write" - ] -} -``` - -- [ ] **Step 4: 添加 husky pre-commit hook** - -```bash -cd web -npx husky add .husky/pre-commit "npx lint-staged" -``` - -- [ ] **Step 5: 验证 .husky/pre-commit 内容** - -命令：`cat web/.husky/pre-commit` -预期：包含 `npx lint-staged` - -- [ ] **Step 6: 更新 package.json 添加 prepare script** - -在 `web/package.json` 的 `scripts` 中添加： - -```json -"prepare": "cd .. && husky install" -``` - -原有 scripts 示例： -```json -"scripts": { - "dev": "vite --force", - "prepare": "cd .. && husky install", - ... -} -``` - -- [ ] **Step 7: 验证 lint-staged 配置** - -命令：`cat web/.lintstagedrc.json` -预期：显示上述 json 内容 - -- [ ] **Step 8: 提交** - -```bash -git add web/package.json web/.lintstagedrc.json web/.husky/ -git commit -m "feat(git): add husky + lint-staged for frontend - -- Add .husky/pre-commit hook running lint-staged -- Add .lintstagedrc.json for staged file linting -- Add prepare script for husky setup on npm install" -``` - ---- - -### 任务 3：PR 模板 - -**文件：** -- 创建：`.github/PULL_REQUEST_TEMPLATE.md` - -- [ ] **Step 1: 创建 .github 目录** - -```bash -mkdir -p .github -``` - -- [ ] **Step 2: 创建 .github/PULL_REQUEST_TEMPLATE.md** - -```markdown -## 变更描述 - - -## 关联需求 - - -## 变更类型 -- [ ] Feature -- [ ] Bugfix -- [ ] Hotfix -- [ ] Refactor - -## 自检清单 -- [ ] 代码已通过 Pre-commit 检查（后端 ruff / 前端 lint-staged） -- [ ] 已添加必要的测试 -- [ ] 文档已更新（如需） - -## Reviewer 备注 - -``` - -- [ ] **Step 3: 验证模板创建** - -命令：`cat .github/PULL_REQUEST_TEMPLATE.md` -预期：显示上述 markdown 内容 - -- [ ] **Step 4: 提交** - -```bash -git add .github/PULL_REQUEST_TEMPLATE.md -git commit -m "docs: add PR template for standardized pull requests - -- Add change description, related issues -- Add change type checklist (Feature/Bugfix/Hotfix/Refactor) -- Add self-check checklist for pre-commit compliance -- Add reviewer notes section" -``` - ---- - -## 实施后验证 - -所有任务完成后，验证步骤： - -### 后端验证 - -```bash -cd backend -pip install pre-commit ruff -pre-commit install -# 测试运行 -pre-commit run --all-files -``` - -预期：ruff 检查通过（无 error） - -### 前端验证 - -```bash -cd web -# 首次 clone 后安装依赖 -npm install -# 测试 pre-commit hook -git add . -git commit -m "test: verify husky hook" -``` - -预期：lint-staged 运行，eslint + prettier 检查通过 - ---- - -## Spec 覆盖检查 - -- ✅ 分支模型：规范文档（已在 spec 中定义，无需代码实现） -- ✅ PR/MR 模板：任务 3 创建 `.github/PULL_REQUEST_TEMPLATE.md` -- ✅ Code Review 规范：规范文档（已在 spec 中定义，无需代码实现） -- ✅ Git Hooks 后端（pre-commit + ruff）：任务 1 -- ✅ Git Hooks 前端（husky + lint-staged）：任务 2 -- ✅ CI/CD 联动：Jenkinsfile 已存在（后端 `backend/Jenkinsfile`），无需修改 -- ✅ 分支保护规则：GitHub/GitLab 界面配置，不在代码库中 - -## 占位符扫描 - -无占位符，所有步骤均包含完整配置和命令。 diff --git a/docs/superpowers/specs/2026-04-02-ai-agent-design.md b/docs/superpowers/specs/2026-04-02-ai-agent-design.md deleted file mode 100644 index 6a294d4..0000000 --- a/docs/superpowers/specs/2026-04-02-ai-agent-design.md +++ /dev/null @@ -1,322 +0,0 @@ -# AVC 内部 Agent 开发设计方案 - -**日期**: 2026-04-02 -**状态**: 设计中 - ---- - -## 一、需求概述 - -### 1.1 背景 - -为 AVC 内部设计开发 AI Agent 平台，用于： -- 智能助手/问答（查询政策、制度、流程文档） -- 业务流程自动化（审批、数据录入、报表生成） -- 数据分析/决策支持 -- 客户服务/工单处理 - -### 1.2 约束条件 - -- 大型企业（500-2000人） -- 完全私有化部署，数据不出公司 -- **国产 LLM**（通义千问/Qwen、智谱/ChatGLM 等）在本地 GPU 运行 -- 多端访问：网页 + 嵌入现有后台 + 企业IM + API -- 全数据源接入：文档、数据库(SQL Server)、业务系统API、文件 -- 单租户架构（多租户后期考虑） - ---- - -## 二、整体架构 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 多端访问层 │ -│ (Web客户端 │ 嵌入现有后台 │ 企业IM(钉钉/飞书) │ REST API) │ -└─────────────────────────┬───────────────────────────────────────┘ - │ -┌─────────────────────────▼───────────────────────────────────────┐ -│ API 网关层 │ -│ (认证 · 鉴权 · 限流 · 日志) │ -└─────────────────────────┬───────────────────────────────────────┘ - │ -┌─────────────────────────▼───────────────────────────────────────┐ -│ LangChain Agent 编排层 │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 问答 Agent │ │ 自动化 Agent │ │ 分析 Agent │ │ -│ │ (RAG+Vector) │ │ (RPA+Tools) │ │ (DB+API) │ │ -│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ -│ │ │ │ │ -│ ┌──────▼─────────────────▼─────────────────▼───────┐ │ -│ │ LangChain Core / LangGraph │ │ -│ │ (Agent Executor · Tool Router) │ │ -│ └─────────────────────────┬─────────────────────────┘ │ -└─────────────────────────────┼─────────────────────────────────────┘ - │ -┌─────────────────────────────▼─────────────────────────────────────┐ -│ 工具层 (Tools) │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ SQL Svr │ │ HTTP API│ │File Parse│ │ RAG搜索 │ ... │ -│ │ Query │ │ Call │ │(Excel/ │ │ (向量检索)│ │ -│ │ │ │ │ │Word/PDF) │ │ │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -│ ┌──────────┐ ┌──────────┐ │ -│ │ Python │ │ Msg │ │ -│ │ Script │ │ Send │ │ -│ └──────────┘ └──────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 三、核心组件 - -| 组件 | 技术选型 | 职责 | -|------|---------|------| -| **Agent 框架** | LangChain / LangGraph | Agent 编排、推理循环、Tool 调度 | -| **RAG 引擎** | LangChain VectorStore + Embedding | 企业知识库检索 | -| **向量数据库** | Milvus | 文本向量存储与检索 | -| **Embedding 模型** | 本地 BGE / XInference | 文本向量化 | -| **LLM 推理** | vLLM + 国产模型（Qwen/ChatGLM） | 大语言模型推理（国产化） | -| **工具层** | LangChain Tools | DB查询、API调用、文件处理等 | -| **API 服务** | FastAPI | 对外接口、多端接入 | -| **任务队列** | Celery + Redis | 异步任务处理 | -| **主数据库** | SQL Server | Agent 记忆、对话历史、配置存储 | - ---- - -## 四、Router 设计 - -### 4.1 混合路由策略 - -采用 **规则 + 小模型 LLM 混合路由**，优先级： - -1. **规则优先匹配**：高频、明确意图（如"发邮件"、"查考勤"） -2. **小模型意图分类**：中频、可描述的意图 -3. **大模型路由兜底**：复杂、模糊意图 - -### 4.2 意图分类 - -| 意图类型 | 标识 | 示例 | -|---------|------|------| -| 问答类 | `qa` | "年假有多少天？"、"如何申请设备维修？" | -| 自动化类 | `automation` | "帮我给张三发邮件说会议改到下午3点" | -| 分析类 | `analysis` | "统计一下各部门本月报销金额" | - -### 4.3 路由实现伪代码 - -```python -def classify_intent(query: str) -> str: - """ - 规则优先，匹配则直接返回 - 未命中则调用小模型分类 - """ - # 规则匹配 - for rule in intent_rules: - if rule.matches(query): - return rule.intent - - # 小模型分类 - return llm_small.invoke( - f"判断意图类型：qa/automation/analysis\n问题：{query}" - ).content.strip() -``` - -### 4.4 插件化扩展 - -```python -class BaseAgent(ABC): - name: str - description: str - tools: list[BaseTool] - - @abstractmethod - def run(self, query: str) -> str: - pass - -class AgentRegistry: - _agents: dict[str, BaseAgent] = {} - - @classmethod - def register(cls, agent: BaseAgent): - cls._agents[agent.name] = agent -``` - -新增 Agent 只需： -```python -@AgentRegistry.register -class NewAgent(BaseAgent): - name = "new_agent" - description = "处理XXX类型问题" - tools = [tool1, tool2] -``` - ---- - -## 五、工具层设计 - -### 5.1 工具列表 - -| 工具 | 输入 | 输出 | 说明 | -|------|------|------|------| -| **MySQLQueryTool** | SQL 查询语句 | JSON 数组 | 只读查询，支持超时保护 | -| **HttpApiTool** | URL + Method + Body | JSON 响应 | 封装常见 HTTP 方法，自动重试 | -| **FileParserTool** | 文件路径 | 文本内容 | 支持 xlsx/docx/pdf/txt，自动提取结构化数据 | -| **RAGSearchTool** | 自然语言查询 | Top-K 相关文本块 | 配合向量库，返回知识库检索结果 | -| **PythonScriptTool** | 脚本内容 + 参数 | JSON 结果 | 沙箱执行，用于复杂数据处理 | -| **MessageSendTool** | 接收人 + 内容 + 渠道 | 发送状态 | 支持邮件/钉钉/飞书/企业微信 | - -### 5.2 工具架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Tools 层 │ -├─────────────┬─────────────┬─────────────┬─────────────────┤ -│ SQL Server │ HTTP API │ File Parse │ RAG Search │ -│ Query │ Call │ (Excel/ │ (Milvus) │ -│ │ │ Word/PDF) │ │ -├─────────────┼─────────────┼─────────────┼─────────────────┤ -│ Script Run │ Msg Send │ ...更多工具可扩展 │ -│ (Python) │ (邮件/IM) │ │ │ -└─────────────┴─────────────┴─────────────┴─────────────────┘ -``` - ---- - -## 六、数据流设计 - -### 6.1 用户查询完整流程 - -``` -用户输入 - │ - ▼ -┌─────────────┐ -│ FastAPI │ ← 限流、日志记录 -└──────┬──────┘ - │ - ▼ -┌─────────────┐ -│ Router │ ← 规则匹配 → 小模型分类 -└──────┬──────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ LangGraph Agent │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ LLM (国产模型: Qwen/ChatGLM) │ │ -│ │ reasoning + tool calling │ │ -│ └───────────────┬─────────────────┘ │ -│ │ │ -│ ┌────────▼────────┐ │ -│ │ Tool Router │ │ -│ │ (选择合适的tool)│ │ -│ └────────┬────────┘ │ -│ │ │ -│ ┌────────▼────────┐ │ -│ │ Tool Executor │ │ -│ │ (并行执行tools) │ │ -│ └────────┬────────┘ │ -│ │ │ -│ ┌────────▼────────┐ │ -│ │ Response │ │ -│ │ Synthesizer │ │ -│ │ (整合tool结果) │ │ -│ └─────────────────┘ │ -└──────────────────┬──────────────────────┘ - │ - ▼ - ┌─────────────┐ - │ 返回用户 │ - └─────────────┘ -``` - ---- - -## 七、错误处理策略 - -| 错误类型 | 处理策略 | -|---------|---------| -| **LLM 超时/宕机** | 自动切换备用模型；返回"服务暂时不可用，请稍后重试" | -| **Tool 执行失败** | 重试 3 次 → 失败则返回错误信息 + 部分结果 | -| **数据库连接失败** | 返回"数据库暂时不可用"；记录错误日志 | -| **文件解析失败** | 返回"文件格式不支持或文件损坏" | -| **RAG 检索为空** | 返回"未找到相关内容，建议换个问法" | -| **恶意注入攻击** | SQL/指令注入检测；敏感操作需二次确认 | - ---- - -## 八、存储层设计 - -| 用途 | 技术选型 | 说明 | -|------|---------|------| -| **向量数据库** | Milvus | 企业文档向量存储，RAG 检索用 | -| **知识库原始文档** | MinIO / 本地文件系统 | 存储原始文档（PDF/Word/Excel） | -| **主业务数据库** | SQL Server | Agent 记忆、对话历史、配置存储 | -| **任务状态** | Redis + Celery | 异步任务队列、任务状态 | -| **日志存储** | Elasticsearch + Loki | 请求日志、Agent 执行日志 | - ---- - -## 九、部署架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 内网环境 │ -│ │ -│ ┌─────────────┐ │ -│ │ 用户端 │ ← Web / 嵌入后台 / 钉钉 / API │ -│ └──────┬──────┘ │ -│ │ │ -│ ┌──────▼──────┐ │ -│ │ FastAPI │ │ -│ └──────┬──────┘ │ -│ │ │ -│ ┌──────▼──────┐ │ -│ │ Router │ ← 规则 + 小模型混合路由 │ -│ └──────┬──────┘ │ -│ │ │ -│ ┌──────▼──────────────────────────────┐ │ -│ │ LangChain Agent 集群 │ │ -│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ -│ │ │ QA Agent │ │Auto Agent│ │Analysis │ │ │ -│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ -│ └───────┼────────────┼────────────┼───────┘ │ -│ │ │ │ │ -│ ┌───────▼────────────▼────────────▼───────┐ │ -│ │ Tools 层 │ │ -│ │ (SQL Server │ API │ 文件解析 │ RAG) │ │ -│ └──────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ vLLM │ │ Milvus │ │ SQL Server │ │ -│ │ (国产模型) │ │ (向量库) │ │ (主库) │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## 十、技术选型总结 - -| 模块 | 技术选型 | -|------|---------| -| Agent 框架 | LangChain / LangGraph | -| Router | 规则 + 小模型混合意图分类 | -| Agent 类型 | QA Agent、Automation Agent、Analysis Agent | -| 工具层 | SQL Server 查询、HTTP API 调用、文件解析、RAG 检索、脚本执行、消息发送 | -| 向量库 | Milvus | -| LLM 推理 | vLLM + 国产模型（Qwen 通义千问 / 智谱 ChatGLM） | -| 主数据库 | SQL Server | -| 任务队列 | Redis + Celery | -| 访问端 | Web + 嵌入后台 + 钉钉/飞书 + API | - ---- - -## 十一、后续步骤 - -1. 编写详细实现方案（implementation plan） -2. 确定开发优先级和里程碑 -3. 开始原型开发 diff --git a/docs/superpowers/specs/2026-04-02-quote-deadline-email-notification-design.md b/docs/superpowers/specs/2026-04-02-quote-deadline-email-notification-design.md deleted file mode 100644 index 8991936..0000000 --- a/docs/superpowers/specs/2026-04-02-quote-deadline-email-notification-design.md +++ /dev/null @@ -1,93 +0,0 @@ -# 报价截止时间到期邮件通知采购 — 设计文档 - -## 1. 需求概述 - -每 5 分钟轮询 `pissupplier.QuotationMaster`，找出已到期（`quote_deadline < now`）但仍未报价（`status ∈ {1 待报价, 2 报价中}`）的报价单，按**询价单维度**合并发送一封邮件给采购负责人，每天最多一次。 - -## 2. 触发条件 - -- **字段**：`pissupplier.QuotationMaster.quote_deadline` 和 `status` -- **逻辑**：`quote_deadline < now` 且 `status in (1, 2)` -- **轮询间隔**：Celery Beat 每 5 分钟 - -## 3. 通知逻辑 - -### 3.1 合并规则 -- 按 `inquiry_no` 分组，同一询价单下所有到期未报价的供应商合并到一封邮件 -- 避免邮件轰炸 - -### 3.2 去重规则 -- 复用现有 `should_send_quote_timeout_reminder(inquiry_no, cooldown_hours=24)` 按 `inquiry_no` 做 24 小时冷却期 -- 已发送过（EmailNotice.biz_type="inquiry_quote_timeout" + status="success"）的询价单跳过 - -### 3.3 收件人 -- 仅「采购负责人」(buyer)，对应 Inquiry.buyer 字段 -- 复用现有 `resolve_inquiry_purchaser_emails` 函数 - -### 3.4 邮件内容 -- 字段：询价单名称、编号、报价截止时间、到期供应商列表、比价页面链接 -- 模板：参考 `backend/templates/emails/quote_timeout_body.html` - -## 4. 数据流 - -``` -Celery Beat (每5分钟) - └── check_quote_deadline_expired() [Celery Task] - ├── 查询所有 status∈{1,2} 且 quote_deadline < now 的 QuotationMaster - ├── 按 inquiry_no 分组 - ├── 对每个 inquiry_no： - │ ├── 检查24h冷却期（should_send_quote_timeout_reminder） - │ ├── 查找 Inquiry，获取采购负责人邮箱 - │ ├── 渲染邮件内容（过期供应商列表） - │ └── 发送邮件（send_email_notice） - └── 写 EmailNotice 记录（biz_type="inquiry_quote_timeout"） -``` - -## 5. 新增文件 - -| 文件路径 | 说明 | -|---|---| -| `backend/apps/pisadmin/miscprocurement/tasks.py` | Celery 定时任务：轮询报价截止时间、发送邮件 | - -## 6. 修改文件 - -| 文件路径 | 修改内容 | -|---|---| -| `backend/application/celery.py` | 注册 Celery Beat Schedule（新增 `check_quote_deadline_expired` 任务） | - -## 7. 核心任务函数签名 - -```python -@app.task -def check_quote_deadline_expired() -> dict: - """ - Celery Beat 定时任务：轮询报价截止时间已到期的报价单， - 按询价单合并发送邮件通知采购负责人，每天最多一次。 - - Returns: {"checked": N, "sent": M, "skipped": K} - """ -``` - -## 8. Celery Beat Schedule 配置 - -```python -CELERY_BEAT_SCHEDULE = { - "check-quote-deadline-expired": { - "task": "apps.pisadmin.miscprocurement.tasks.check_quote_deadline_expired", - "schedule": crontab(minute="*/5"), # 每5分钟 - }, -} -``` - -## 9. 已有可复用代码 - -- `apps.pisadmin.basicinfo.views.email_utils.send_quote_timeout_notice_to_purchaser` — 单封邮件发送 -- `apps.pisadmin.basicinfo.views.email_utils.should_send_quote_timeout_reminder` — 24h冷却期判断 -- `apps.pisadmin.basicinfo.views.email_utils.resolve_inquiry_purchaser_emails` — 采购负责人邮箱解析 -- `apps.pisadmin.basicinfo.views.email_utils.send_email_notice` — 邮件发送底层 -- `backend/templates/emails/quote_timeout_body.html` — 邮件模板 - -## 10. 异常处理 - -- 邮件发送失败不影响其他询价单处理，记录异常日志 -- Celery 任务失败自动重试（最多3次，间隔3分钟） diff --git a/docs/superpowers/specs/2026-04-03-git-collaboration-design.md b/docs/superpowers/specs/2026-04-03-git-collaboration-design.md deleted file mode 100644 index d13086f..0000000 --- a/docs/superpowers/specs/2026-04-03-git-collaboration-design.md +++ /dev/null @@ -1,271 +0,0 @@ -# Git 协作规范设计 - -> 创建日期：2026-04-03 -> 状态：评审中 -> 作者：Lewis Yan -> 关联：Git 协作标准化 - ---- - -## 1. 分支模型 - -采用标准 Git Flow。 - -``` -main ──────────────────────────── 生产环境（受保护，禁止直接 push） - ↑ - │ ← hotfix/xxx（从 main 分出，修复完成需合并回 main + develop） - │ -develop ───────────────────────── 开发集成主线（受保护，禁止直接 push） - ↑ - │ ← feature/xxx（从 develop 分出，功能完成后合并回 develop） - │ ← bugfix/xxx（从 develop 分出，develop 上的 bug 修复） -``` - -### 分支命名规范 - -| 分支类型 | 命名格式 | 示例 | -|---------|---------|------| -| Feature | `feature/功能描述` 或 `feature/ISSUE号-功能描述` | `feature/PIS-123-user-auth` | -| Bugfix | `bugfix/问题描述` 或 `bugfix/ISSUE号-修复描述` | `bugfix/PIS-456-login-timeout` | -| Hotfix | `hotfix/紧急修复描述` | `hotfix/critical-payment-fix` | - -### 分支生命周期 - -- **创建**：`git checkout develop && git pull && git checkout -b feature/xxx` -- **同步上游**：`git merge develop` 或 `git rebase develop` -- **完成合并后**：分支自动删除（GitHub/GitLab 设置 `delete branch after merge`） - ---- - -## 2. PR/MR 流程 - -### 标准流程 - -``` -1. 从 develop 创建分支 -2. 开发并 commit（保持原子性） -3. Push 到远程 -4. 创建 PR，填写模板 -5. 指定 Reviewer -6. 等待 Review 通过 -7. Jenkins CI 构建通过 -8. 合并到 develop -9. 分支自动删除 -``` - -### PR 模板 - -```markdown -## 变更描述 - - -## 关联需求 - - -## 变更类型 -- [ ] Feature -- [ ] Bugfix -- [ ] Hotfix -- [ ] Refactor - -## 自检清单 -- [ ] 代码已通过 Pre-commit 检查 -- [ ] 已添加必要的测试 -- [ ] 文档已更新（如需） - -## Reviewer 备注 - -``` - -### 合并标准 - -- 至少 **1 人** Approve -- **Jenkins CI** 构建通过 -- 无未解决的 Conversation -- 分支已最新（解决与目标分支的冲突） - ---- - -## 3. Code Review 规范 - -### 作者职责 - -- 代码逻辑复杂处添加必要注释 -- 准备好回复 Review 意见 -- **不要在 Review 前自行合并** -- 不要在 PR 中混入不相关的改动 - -### Reviewer 职责 - -- **24 小时内**完成 Review -- 聚焦：逻辑正确性、代码风格、安全隐患 -- 评价客观，避免个人偏好带入 -- 确认 Jenkins CI 状态 - -### 合并门槛 - -``` -最低 1 人 Approve + CI 通过 → 可合并 -``` - ---- - -## 4. Git Hooks - -后端和前端分开管理，各自使用最合适的工具。 - -### 后端（Python）— pre-commit - -**安装方式：** -```bash -cd backend -pip install pre-commit ruff -pre-commit install -``` - -**检查内容：** -- Python：`ruff`（替代 flake8 + black + isort，速度快 10-100x） -- 通用：禁止 debug 代码、敏感信息检查 - -**.pre-commit-config.yaml 示例：** -```yaml -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 - hooks: - - id: trailing-whitespace - - id: end-of-file-fixer - - id: check-yaml - - id: check-added-large-files - - - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.9.0 - hooks: - - id: ruff - - id: ruff-format -``` - -### 前端（Node.js）— husky - -**安装方式：** -```bash -cd web -npm install husky lint-staged -D -npx husky install -npx husky add .husky/pre-commit "npx lint-staged" -``` - -**package.json lint-staged 配置：** -```json -{ - "lint-staged": { - "*.{js,vue,ts}": ["eslint --fix", "prettier --write"] - } -} -``` - ---- - -## 5. Git Etiquette - -### 鼓励的行为 - -``` -✅ Commit Often — 小步提交，每次有清晰改动 -✅ 保持 commit 原子性 — 一个 commit 只做一件事 -✅ 提交前本地跑测试 — 不要把坏代码推向远程 -✅ Review 通过后再合并 — 不要绕过 Review -✅ 功能完成后及时开 PR — 不要等代码变坏 -✅ 同步上游分支 — 经常 pull/rebase develop 减少冲突 -``` - -### 禁止的行为 - -``` -❌ 不要 push WIP（未完成的工作）到远程主分支 -❌ 不要强制 push（git push --force）到 main/develop -❌ 不要在 PR 里混入不相关的改动 -❌ 不要跳过 Pre-commit 直接 commit -``` - ---- - -## 6. CI/CD 联动（Jenkins） - -### Pre-commit（本地） - -- 在开发者本地运行 -- 不阻塞远程，但作为质量门槛 -- 失败则无法 commit（可 --no-verify 绕过，但不推荐） - -### Jenkins Pipeline - -``` -Push → 自动触发 Jenkins Build - ├── Backend - │ ├── 单元测试 (pytest) - │ ├── 代码检查 (ruff) - │ └── 构建 - │ - ├── Frontend - │ ├── 依赖安装 - │ ├── ESLint 检查 - │ ├── 构建 - │ └── 预览部署 - │ - └── 结果通知（可选：邮件/Slack） -``` - -### 部署规则 - -| 合并目标 | 触发动作 | -|---------|---------| -| `main` | 自动部署到生产环境（可选，视团队节奏） | -| `develop` | 自动部署到测试环境 | - ---- - -## 7. 分支保护规则 - -### main（生产环境） - -- ❌ 禁止直接 push -- ❌ 禁止 force push -- ✅ 必须通过 PR 合并 -- ✅ 必须有 CI 通过 -- ✅ 必须有 1 人 Approve - -### develop（开发主线） - -- ❌ 禁止直接 push -- ❌ 禁止 force push -- ✅ 必须通过 PR 合并 -- ✅ 必须有 CI 通过 - -### feature/bugfix/hotfix - -- 可直接 push -- 鼓励通过 PR 协作 - ---- - -## 8. 工具链汇总 - -| 环节 | 工具 | 适用范围 | -|-----|------|---------| -| Git Hooks（后端） | pre-commit | backend/ | -| Git Hooks（前端） | husky + lint-staged | web/ | -| CI/CD | Jenkins | 全项目 | -| 代码风格（后端） | ruff（lint + format） | backend/ | -| 代码风格（前端） | eslint, prettier | web/ | - ---- - -## 设计决策 - -1. **分支模型**：标准 Git Flow，平衡了规范性和灵活性 -2. **Review 门槛**：1 人 Approve，门槛适中不过度拖延 -3. **Hook 管理**：后端 pre-commit、前端 husky，各自用最合适的工具 -4. **分支合并后自动删除**：保持仓库整洁 -5. **CI 联动**：Jenkins 覆盖构建和测试，不重复造轮子 From 6dcd44ba42acccd6a547d422b3f10d1dae5e64fb Mon Sep 17 00:00:00 2001 From: lewis_yan Date: Fri, 3 Apr 2026 13:56:10 +0800 Subject: [PATCH 3/3] docs: add Docs option to MR template change type --- .gitlab/merge_request_templates/default.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitlab/merge_request_templates/default.md b/.gitlab/merge_request_templates/default.md index d8c48e5..9caba46 100644 --- a/.gitlab/merge_request_templates/default.md +++ b/.gitlab/merge_request_templates/default.md @@ -9,6 +9,7 @@ - [ ] Bugfix - [ ] Hotfix - [ ] Refactor +- [ ] Docs ## 自检清单 - [ ] 代码已通过 Pre-commit 检查（后端 ruff / 前端 lint-staged）