# 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
```