aipm-backend 0.1.0

AI Project Manager Server - REST API backend for project and task management

AIPM - AI Project Manager

版本：0.1.0 (Phase 1 MVP) 描述：基于 FastAPI + SQLite 的项目管理后台 REST API

---

功能概述

AIPM 是一个完全独立的项目管理后台系统，提供：

• 项目管理：创建、查询、更新项目
• 任务管理：添加、查询、更新任务进展
• 进展收集：定时启动进展收集，发送提醒
• 预警检查：自动检查即将逾期的任务
• 周报生成：自动生成项目周报
• 定时任务：内置 APScheduler，支持三种定时任务

架构设计

┌──────────────────────────────────────────┐
│  aipm Backend（完全独立）                │
│  ├── REST API                            │
│  ├── Scheduler（定时任务）               │
│  ├── SQLite 数据库                       │
│  └── Business Logic                      │
└──────────────────────────────────────────┘

关键原则：

• Backend 完全独立，不绑定任何客户端
• 通知只返回内容，不负责发送
• 任何支持 HTTP 的客户端都能调用

---

快速开始

安装

# 从源码安装
pip install -e .

# 或从 git 安装
pip install git+https://github.com/yourname/aipm.git

启动

# 默认启动（端口 8000）
aipm

# 指定端口
aipm --port 9000

# 网络访问
aipm --host 0.0.0.0

# 使用自定义数据库
aipm --db sqlite:///custom.db

# 禁用定时任务
aipm --no-scheduler

# 开发模式（自动重载）
aipm --reload

访问 API 文档

启动后访问：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc

---

API 接口

项目管理

接口	方法	描述
/api/v1/projects	POST	创建项目
/api/v1/projects/{id}	GET	查询项目详情
/api/v1/projects	GET	查询项目列表
/api/v1/projects/{id}	PATCH	更新项目
/api/v1/projects/{id}	DELETE	删除项目

任务管理

接口	方法	描述
/api/v1/tasks	POST	添加任务
/api/v1/tasks	GET	查询任务列表
/api/v1/tasks/{id}	GET	查询任务详情
/api/v1/tasks/{id}/progress	PATCH	更新进展
/api/v1/tasks/{id}	DELETE	删除任务

进展收集

接口	方法	描述
/api/v1/collection/start	POST	启动进展收集
/api/v1/collection/check	POST	检查并发送提醒
/api/v1/collection/status/{session_id}	GET	查看收集状态
/api/v1/collection/feedback/chat	POST	群聊反馈
/api/v1/collection/feedback/form/{session_id}/{task_id}	POST	表单提交

报表与预警

接口	方法	描述
/api/v1/reports	POST	生成报表
/api/v1/reports/overdue	GET	查询预警任务

定时任务

接口	方法	描述
/api/v1/scheduled/check-overdue	POST	执行预警检查
/api/v1/scheduled/weekly-report	POST	生成周报
/api/v1/scheduled/collect-progress	POST	启动进展收集
/api/v1/scheduled/config	GET	查看定时任务配置
/api/v1/scheduled/config/{task_id}	PATCH	修改定时任务配置

---

数据库表

核心表

表名	描述
users	用户表
user_channels	用户渠道绑定表
projects	项目表
tasks	任务表
progress_history	进展历史表
progress_collect_sessions	收集会话表
progress_collect_details	收集明细表

辅助表

表名	描述
scheduled_task_configs	定时任务配置表

---

定时任务

三种定时任务

任务 ID	名称	默认触发时间
daily_check	每日预警检查	周一至周五 09:00
progress_collect	进展收集	周三 09:00
weekly_report	周报生成	周五 17:00

配置修改

通过 API 修改定时任务配置：

# 修改预警检查时间
curl -X PATCH http://localhost:8000/api/v1/scheduled/config/daily_check \
  -H "Content-Type: application/json" \
  -d '{"trigger_time": "08:00", "params": {"days_threshold": 5}}'

# 禁用定时任务
curl -X PATCH http://localhost:8000/api/v1/scheduled/config/weekly_report \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

---

使用示例

创建项目

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "智慧城市项目",
    "channel": "wecom",
    "group_id": "group_001",
    "background": "打造智慧城市管理平台",
    "objective": "完成一期建设",
    "deadline": "2026-06-30"
  }'

添加任务

curl -X POST http://localhost:8000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xxx",
    "title": "数据采集模块",
    "assignee": "user_001",
    "deadline": "2026-04-20",
    "priority": "high"
  }'

启动进展收集

curl -X POST http://localhost:8000/api/v1/collection/start \
  -H "Content-Type: application/json" \
  -d '{"project_id": "proj_xxx"}'

# 返回：
{
  "session_id": "session_xxx",
  "tasks_count": 5,
  "notifications": [
    {
      "target": "user",
      "channel": "wecom",
      "user_id": "user_001",
      "message": "请更新进展..."
    }
  ]
}

更新进展

curl -X PATCH http://localhost:8000/api/v1/tasks/task_xxx/progress \
  -H "Content-Type: application/json" \
  -d '{
    "progress": 60,
    "note": "已完成数据采集框架",
    "user_id": "user_001",
    "feedback_method": "chat"
  }'

生成周报

curl -X POST http://localhost:8000/api/v1/reports \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xxx",
    "report_type": "weekly"
  }'

---

配置文件

环境变量

所有配置可通过环境变量设置，格式为 AIPM_<section>__<key>：

# 数据库配置
export AIPM_DATABASE__DATABASE_URL="sqlite:///./aipm.db"

# 定时任务配置
export AIPM_SCHEDULER__SCHEDULER_ENABLED="true"
export AIPM_SCHEDULER__SCHEDULER_TIMEZONE="Asia/Shanghai"

# API 配置
export AIPM_API_PREFIX="/api/v1"

配置文件

配置文件可选，默认使用内置配置：

# ~/.aipm/config.json（未来支持）
{
  "database": {
    "database_url": "sqlite:///./aipm.db"
  },
  "scheduler": {
    "scheduler_enabled": true,
    "scheduler_timezone": "Asia/Shanghai"
  }
}

---

技术栈

组件	技术	版本
Web 框架	FastAPI	≥0.104.0
数据库	SQLite	默认
ORM	SQLAlchemy	≥2.0.23
数据验证	Pydantic	≥2.5.0
定时任务	APScheduler	≥3.10.4
ASGI 服务器	Uvicorn	≥0.24.0

---

项目结构

code/
├── src/aipm/
│   ├── __init__.py           # 包入口
│   ├── config.py             # 配置管理
│   ├── database.py           # 数据库连接
│   ├── models.py             # 数据模型
│   ├── schemas.py            # API schemas
│   ├── scheduler.py          # 定时任务
│   ├── main.py               # FastAPI 应用
│   ├── cli.py                # CLI 入口
│   ├── api/                  # API 路由
│   │   ├── __init__.py
│   │   ├── projects.py
│   │   ├── tasks.py
│   │   ├── collection.py
│   │   ├── reports.py
│   │   └── scheduled.py
│   └── services/             # 业务逻辑
│       ├── __init__.py
│       ├── project_service.py
│       ├── task_service.py
│       ├── collection_service.py
│       └── report_service.py
├── pyproject.toml            # 项目配置
├── requirements.txt          # 依赖列表
└── README.md                 # 本文档

---

Phase 1 MVP 验收

✅ 已完成功能：

• aipm Python package 结构（可 pip install）
• FastAPI 后台 + SQLite 数据库
• 项目管理 API（5个接口）
• 任务管理 API（6个接口）
• 进展收集功能（5个接口）
• 预警检查 API
• 周报生成 API
• 定时任务（APScheduler）
• 三种定时任务可配置
• CLI 启动命令

📋 后续 Phase 2：

• 认证机制（API token）
• 多用户支持
• PostgreSQL 迁移
• OpenClaw Skill
• 云服务器部署
• PyPI 发布

---

开发指南

本地开发

# 安装开发依赖
pip install -e ".[dev]"

# 启动开发服务器
aipm --reload

# 运行测试（未来添加）
pytest

代码结构

• models.py：数据库模型定义
• schemas.py：Pydantic 数据验证模型
• services/：业务逻辑层，与数据库交互
• api/：API 路由层，处理 HTTP 请求响应
• scheduler.py：定时任务调度器

API 设计原则

1. RESTful 风格
2. 清晰的请求/响应模型
3. 错误处理统一
4. 通知只返回内容，不发送

---

License

MIT License

---

文档位置：/Users/hmt/.openclaw/workspace/pm/shared/aipm/code/README.md