使用说明
Word文档提案生成器
REST API，用于从Word模板自动生成Microsoft 365商业提案，支持变量替换和表格管理。
设计用于与……集成 Microsoft Copilot Studio（微软Copilot工作室）。
🎯 使用场景
为Microsoft 365创建专业的商业提案：
- ✅ 从自定义模板生成文档
- ✅ 自动替换变量（客户姓名、电子邮件、电话、内容）
- ✅ 在现有表格中添加产品/服务行
- ✅ 自动格式化表格（边框、彩色标题、交替行）
- ✅ 将文档存储在 Azure Blob 存储中
- ✅ 获取签名URL以下载文档
📋 功能
文档管理
POST /api/create/document/from/template- 使用带有变量的模板创建文档GET /api/get/document/url- 获取文档的下载URLGET /api/list/all/documents- 列出所有生成的文件POST /api/check/document/exists- 检查文件是否存在POST /api/delete/document- 删除文档
模板管理
GET /api/list/all/templates- 列出所有可用的模板POST /api/add/document/template- 添加一个新模板POST /api/delete/document/template- 删除一个模板
内容管理
POST /api/add/paragraph- 添加一个段落文本POST /api/add/heading- 添加一个章节标题POST /api/add/table/with/rows- 添加一个包含数据的新表格POST /api/add/table/row- 在现有表格中添加一行
表格格式化
POST /api/format/table/with/borders- 为表格添加边框格式POST /api/highlight/table/header/colors- 为表格标题着色POST /api/apply/alternating/row/colors- 应用交替颜色POST /api/format/cell/text/appearance- 格式化特定单元格
🚀 Azure 部署
先决条件
- 具有有效订阅的 Azure 帐户
- 已安装并连接 Azure CLI（
az login) - Azure 容器注册表 (ACR)
- Azure 容器应用环境
- 带有容器的Azure存储帐户
word-documents和word-templates
所需的环境变量
# Azure Storage
AZURE_STORAGE_ACCOUNT_NAME=<votre-storage-account>
AZURE_STORAGE_CONNECTION_STRING=<connection-string>
# API Security (optionnel)
API_KEY=<votre-cle-api>
# Debug (optionnel)
DEBUG_MODE=false
快速部署
# 1. Cloner le repository
git clone https://github.com/votre-username/word-proposal-generator.git
cd word-proposal-generator
# 2. Configurer les variables (editez le script)
nano deploy-azure-with-storage.sh
# 3. Déployer
chmod +x deploy-azure-with-storage.sh
./deploy-azure-with-storage.sh <ACR_NAME> <RESOURCE_GROUP> <ENVIRONMENT_NAME>
脚本内容如下：
- 构建Docker镜像并将其推送到ACR
- 创建/更新容器应用
- 配置与存储帐户的托管身份认证
- 分配必要的角色（存储Blob数据贡献者）
手动部署
# Build et push de l'image
az acr build -t word-proposal-api:latest -r <ACR_NAME> -f Dockerfile.connector .
# Créer Container App
az containerapp create \
--name word-proposal-api \
--resource-group <RESOURCE_GROUP> \
--environment <ENVIRONMENT_NAME> \
--image <ACR_NAME>.azurecr.io/word-proposal-api:latest \
--target-port 8080 \
--ingress external \
--min-replicas 1 \
--max-replicas 3 \
--env-vars \
AZURE_STORAGE_ACCOUNT_NAME=<storage-account> \
API_KEY=<your-api-key>
# Activer managed identity
az containerapp identity assign \
--name word-proposal-api \
--resource-group <RESOURCE_GROUP> \
--system-assigned
# Assigner le rôle Storage Blob Data Contributor
PRINCIPAL_ID=$(az containerapp show -n word-proposal-api -g <RESOURCE_GROUP> --query identity.principalId -o tsv)
STORAGE_ID=$(az storage account show -n <STORAGE_ACCOUNT> -g <RESOURCE_GROUP> --query id -o tsv)
az role assignment create \
--assignee $PRINCIPAL_ID \
--role "Storage Blob Data Contributor" \
--scope $STORAGE_ID
📖 与 Copilot Studio 的配合使用
操作配置
- 导入Swagger使用
/openapi.json通过您的Container App URL - 添加API密钥设置请求头
X-API-Key在身份验证中 - 创建操作查看完整指南于
profiles/GUIDE_ACTIONS_COPILOT.md
典型工作流程
User: "Crée une proposition pour Jean Dupont, email j.dupont@mail.com"
Bot: [Appelle create/document/from/template]
- template_name: "template-text"
- new_document_name: "proposal_jean_dupont"
- variables: {
"commercialName": "Jean Dupont",
"commercialEmail": "j.dupont@mail.com",
...
}
Bot: [Appelle add/table/row pour chaque produit Microsoft 365]
- filename: "proposal_jean_dupont"
- table_index: 0
- row_data: ["Microsoft 365 Business Premium", "Description...", "1", "21.00", "25.00"]
Bot: [Appelle highlight/table/header/colors]
- filename: "proposal_jean_dupont"
- table_index: 0
- header_color: "4472C4"
- text_color: "FFFFFF"
Bot: "Voici votre proposition: https://storage.blob.core.windows.net/..."
🛠️ 本地开发
安装
# Créer environnement virtuel
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
# ou .venv\Scripts\activate # Windows
# Installer dépendances
pip install -r requirements.txt
配置
创建一个文件 .env：
AZURE_STORAGE_ACCOUNT_NAME=<votre-storage-account>
AZURE_STORAGE_CONNECTION_STRING=<connection-string>
API_KEY=<votre-cle-api>
DEBUG_MODE=true
PORT=8080
本地启动
python connector_wrapper.py
该API将在 http://localhost:8080
端点测试
# Lister les templates
curl -H "X-API-Key: <your-key>" http://localhost:8080/api/list/all/templates
# Créer un document
curl -X POST http://localhost:8080/api/create/document/from/template \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-key>" \
-d '{
"template_name": "template-text",
"new_document_name": "test_proposal",
"variables": {
"commercialName": "Test Client",
"commercialEmail": "test@client.com",
"commercialTel": "0123456789",
"propalContent": "Test content"
}
}'
📁 项目结构
.
├── connector_wrapper.py # API REST FastAPI
├── Dockerfile.connector # Dockerfile pour Container Apps
├── requirements.txt # Dépendances Python
├── deploy-azure-with-storage.sh # Script de déploiement Azure
├── word_document_server/
│ ├── tools/
│ │ ├── document_tools.py # Gestion documents
│ │ ├── content_tools.py # Ajout contenu (paragraphes, tableaux)
│ │ ├── format_tools.py # Formatage tableaux
│ │ └── template_tools.py # Gestion templates
│ └── utils/
│ ├── azure_storage.py # Intégration Azure Blob Storage
│ ├── file_utils.py # Utilitaires fichiers
│ └── template_storage.py # Gestion templates Azure
└── profiles/
├── GUIDE_ACTIONS_COPILOT.md # Guide configuration Copilot Studio
└── create-propal.swagger.json # Swagger pour import
🔐 安全
- API密钥通过头部保护终端节点
X-API-Key - 托管身份无需存储密钥的Azure身份验证
- **RBAC（Role-Based Access Control）的中文翻译是“基于角色的访问控制”**使用Azure角色实现细粒度的访问控制
- 签名URL临时访问文档（默认24小时）
🔧 维修
内容过滤错误（Copilot Studio）
如果您在Copilot Studio中遇到“ContentFiltered”错误：
- 答案会自动缩短为
ok或者error: <type> - 文档的URL得以保留
- 激活
DEBUG_MODE=true查看完整答案（仅开发）
未找到文档
- 确认托管身份拥有“存储Blob数据贡献者”角色
- 检查 Azure 存储中的容器名称
word-documents） - 检查Container App的日志：
az containerapp logs show -n <app-name> -g <rg>
权限被拒绝
# Re-assigner le rôle
az role assignment create \
--assignee <PRINCIPAL_ID> \
--role "Storage Blob Data Contributor" \
--scope <STORAGE_ID>
📝 许可证
麻省理工学院（MIT）
🤝 贡献
欢迎贡献！请随时提出问题或提交拉取请求。
📞 支持
对于任何问题或疑问：
- 在GitHub上打开一个issue
- 查阅Copilot Studio指南于
profiles/GUIDE_ACTIONS_COPILOT.md
