JiuContinent
71ca804764
feat: 添加公司AI管理平台基础架构 添加了完整的FastAPI后端项目结构，包括： - 环境配置文件(.env.example)和项目说明文档(README.md、AGENTS.md) - Dockerfile用于容器化部署 - 核心基础设施：配置管理、数据库连接、调度器、安全认证 - 模块化设计：AI代理、审批流程、审计日志、业务台账等功能模块 - 支持多数据库连接(主库和遗留系统只读库) - AI适配器支持OpenClaw、Hermes、OpenAI兼容接口 - 飞书集成、报表生成、风险监控等企业级功能 - 完整的依赖管理和测试指南 ```
312 lines
6.1 KiB
Markdown
312 lines
6.1 KiB
Markdown
# Company AI Management Platform
|
||
|
||
这是一个公司全生命周期 AI 管理系统的后端工程，定位是：
|
||
|
||
```text
|
||
现有项目管理系统 / MySQL
|
||
+
|
||
FastAPI AI 集成层
|
||
+
|
||
飞书推送与审批入口
|
||
+
|
||
OpenClaw / Hermes / 模型适配接口
|
||
```
|
||
|
||
第一版已经实现：
|
||
|
||
- FastAPI 后端工程
|
||
- Conda 独立环境配置
|
||
- MySQL 主库连接
|
||
- 现有项目管理系统 MySQL 只读接入
|
||
- 业务台账 CRUD：项目、任务、采购、费用、资金、制度、规范、绩效、供应商
|
||
- 飞书文本和卡片推送接口
|
||
- 飞书 Webhook 入口
|
||
- 飞书消息命令路由：日报、周报、风险、AI 问答
|
||
- AI 适配器：OpenClaw、Hermes、OpenAI-compatible、noop
|
||
- 经营晨报、项目周报
|
||
- 风险检测：逾期任务、延期项目、超预算项目、资金低于安全线
|
||
- 审批单：高风险资金/绩效更新必须通过审批 ticket
|
||
- 现有 MySQL 项目数据同步到内部台账，支持 dry-run 和字段映射
|
||
- AI 操作审计日志
|
||
- Docker Compose 本地运行模板
|
||
|
||
## 1. 技术栈
|
||
|
||
```text
|
||
Python 3.11
|
||
FastAPI
|
||
SQLAlchemy 2
|
||
MySQL / PyMySQL
|
||
Redis
|
||
APScheduler / Celery 预留
|
||
httpx
|
||
Pydantic Settings
|
||
```
|
||
|
||
## 2. Conda 环境
|
||
|
||
重新创建专用环境：
|
||
|
||
```powershell
|
||
cd C:\Users\20143\Documents\Codex\2026-06-21\new-chat\outputs\company-ai-platform
|
||
conda env remove -n company-ai-platform
|
||
conda env create -f environment.yml
|
||
conda activate company-ai-platform
|
||
```
|
||
|
||
更新已有环境：
|
||
|
||
```powershell
|
||
conda env update -f environment.yml --prune
|
||
```
|
||
|
||
也可以直接运行：
|
||
|
||
```powershell
|
||
.\scripts\recreate_conda_env.ps1
|
||
```
|
||
|
||
## 3. 配置
|
||
|
||
复制配置文件：
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
至少配置：
|
||
|
||
```text
|
||
DATABASE_URL=你的新业务库
|
||
LEGACY_DATABASE_URL=现有项目管理系统的只读 MySQL 账号
|
||
LEGACY_PROJECT_QUERY=从现有系统读取项目的 SELECT 查询
|
||
API_KEY=你的内部 API Key
|
||
```
|
||
|
||
飞书和模型可以后续再配置。未配置模型时，`MODEL_PROVIDER=noop` 会返回可预测占位结果，确保项目先能启动。
|
||
|
||
## 4. 初始化数据库
|
||
|
||
```powershell
|
||
python -m app.tools.init_db
|
||
```
|
||
|
||
## 5. 启动服务
|
||
|
||
```powershell
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8010
|
||
```
|
||
|
||
访问：
|
||
|
||
```text
|
||
http://127.0.0.1:8010/docs
|
||
```
|
||
|
||
带 API Key 请求时加 header：
|
||
|
||
```text
|
||
X-API-Key: 你的 API_KEY
|
||
```
|
||
|
||
## 6. 关键接口
|
||
|
||
### 系统健康
|
||
|
||
```text
|
||
GET /api/v1/health
|
||
```
|
||
|
||
### 业务台账
|
||
|
||
```text
|
||
GET /api/v1/business/domains
|
||
GET /api/v1/business/projects
|
||
POST /api/v1/business/projects
|
||
PATCH /api/v1/business/projects/{id}
|
||
```
|
||
|
||
支持的 domain：
|
||
|
||
```text
|
||
projects
|
||
tasks
|
||
procurements
|
||
expenses
|
||
fund-accounts
|
||
policies
|
||
standards
|
||
performance-metrics
|
||
suppliers
|
||
```
|
||
|
||
### 现有 MySQL
|
||
|
||
```text
|
||
GET /api/v1/integrations/mysql/health
|
||
GET /api/v1/integrations/mysql/tables
|
||
GET /api/v1/integrations/mysql/tables/{table_name}
|
||
POST /api/v1/integrations/mysql/query
|
||
GET /api/v1/integrations/mysql/projects
|
||
POST /api/v1/integrations/mysql/projects/sync
|
||
```
|
||
|
||
只允许 `SELECT`，默认第一阶段不写回原系统。
|
||
|
||
项目同步默认 `dry_run=true`，确认映射无误后再设置为 `false`。
|
||
|
||
### 飞书
|
||
|
||
```text
|
||
POST /api/v1/integrations/feishu/send-text
|
||
POST /api/v1/integrations/feishu/send-card
|
||
POST /api/v1/integrations/feishu/webhook
|
||
POST /api/v1/integrations/feishu/commands/preview
|
||
```
|
||
|
||
飞书命令支持：
|
||
|
||
```text
|
||
日报 / 晨报 / 经营日报
|
||
周报 / 项目周报
|
||
风险 / 预警
|
||
问 xxx / AI xxx / 普通问题
|
||
```
|
||
|
||
### AI
|
||
|
||
```text
|
||
POST /api/v1/ai/ask
|
||
POST /api/v1/ai/draft-policy
|
||
POST /api/v1/ai/investment-research
|
||
```
|
||
|
||
### 审批
|
||
|
||
```text
|
||
POST /api/v1/approvals
|
||
GET /api/v1/approvals
|
||
GET /api/v1/approvals/{ticket_id}
|
||
POST /api/v1/approvals/{ticket_id}/approve
|
||
POST /api/v1/approvals/{ticket_id}/reject
|
||
```
|
||
|
||
`fund-accounts` 和 `performance-metrics` 更新需要已批准的 `approval_ticket_id`。
|
||
|
||
### 报表
|
||
|
||
```text
|
||
GET /api/v1/reports/daily-brief
|
||
GET /api/v1/reports/project-weekly
|
||
POST /api/v1/reports/daily-brief/push
|
||
POST /api/v1/reports/project-weekly/push
|
||
```
|
||
|
||
### 风险
|
||
|
||
```text
|
||
GET /api/v1/risks/summary
|
||
GET /api/v1/risks/overdue-tasks
|
||
GET /api/v1/risks/delayed-projects
|
||
GET /api/v1/risks/over-budget-projects
|
||
GET /api/v1/risks/funds
|
||
```
|
||
|
||
## 7. 接入现有项目管理系统
|
||
|
||
第一阶段建议只读接入：
|
||
|
||
```text
|
||
现有项目系统 MySQL -> FastAPI 只读查询 -> 报表/风险 -> 飞书推送
|
||
```
|
||
|
||
不要一开始让 AI 直接改原系统数据库。
|
||
|
||
配置示例：
|
||
|
||
```text
|
||
LEGACY_DATABASE_URL=mysql+pymysql://readonly_user:password@10.0.0.10:3306/project_system?charset=utf8mb4
|
||
LEGACY_PROJECT_QUERY=SELECT id, name, owner, status, progress, start_date, due_date, budget, actual_cost FROM project ORDER BY id DESC LIMIT :limit
|
||
```
|
||
|
||
## 8. 接入 OpenClaw / Hermes / 模型
|
||
|
||
OpenClaw：
|
||
|
||
```text
|
||
MODEL_PROVIDER=openclaw
|
||
OPENCLAW_BASE_URL=http://127.0.0.1:18789
|
||
OPENCLAW_API_KEY=
|
||
```
|
||
|
||
Hermes：
|
||
|
||
```text
|
||
MODEL_PROVIDER=hermes
|
||
HERMES_BASE_URL=http://127.0.0.1:8080
|
||
HERMES_API_KEY=
|
||
```
|
||
|
||
OpenAI-compatible：
|
||
|
||
```text
|
||
MODEL_PROVIDER=direct_llm
|
||
DIRECT_LLM_BASE_URL=https://api.openai.com/v1
|
||
DIRECT_LLM_API_KEY=你的Key
|
||
DIRECT_LLM_MODEL=gpt-4.1-mini
|
||
```
|
||
|
||
## 9. 安全边界
|
||
|
||
已经内置的边界：
|
||
|
||
- 现有 MySQL 只允许 SELECT
|
||
- 高风险模块更新需要 `approval_ticket_id`
|
||
- 飞书和 AI 动作写入审计日志
|
||
- API 支持 `X-API-Key`
|
||
- AI 不直接审批付款、绩效、投资交易
|
||
|
||
后续建议补：
|
||
|
||
- 用户登录
|
||
- RBAC 角色权限
|
||
- 字段级脱敏
|
||
- 飞书审批回调
|
||
- 数据库迁移 Alembic
|
||
- 对接真实财务/采购系统 API
|
||
|
||
## 10. 下一步实施顺序
|
||
|
||
```text
|
||
1. 配置现有 MySQL 只读账号
|
||
2. 调通 /integrations/mysql/health
|
||
3. 调通 /integrations/mysql/projects
|
||
4. 初始化新业务库
|
||
5. 导入或同步项目数据
|
||
6. 配置飞书应用
|
||
7. 调通飞书 send-text/send-card
|
||
8. 配置 MODEL_PROVIDER
|
||
9. 开启日报、周报、风险推送
|
||
10. 再逐步做写回和审批闭环
|
||
```
|
||
|
||
## 11. 验证
|
||
|
||
编译：
|
||
|
||
```powershell
|
||
conda run -n company-ai-platform python -m compileall app tests scripts
|
||
```
|
||
|
||
Smoke 验证：
|
||
|
||
```powershell
|
||
conda run -n company-ai-platform python scripts\verify_smoke.py
|
||
```
|
||
|
||
测试：
|
||
|
||
```powershell
|
||
conda run -n company-ai-platform pytest -q
|
||
```
|