49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
|
# CODEBUDDY.md
|
|||
|
|
|
|||
|
|
This file provides guidance to CodeBuddy Code when working with code in this repository.
|
|||
|
|
|
|||
|
|
## 项目概述
|
|||
|
|
|
|||
|
|
微信公众号扫码授权服务，基于 FastAPI。当前实现微信服务器验证（GET /wechat）与消息/事件接收（POST /wechat）。MySQL 与 Redis 已在配置层声明，但业务代码尚未使用。
|
|||
|
|
|
|||
|
|
## 常用命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖（建议先创建/激活虚拟环境 venv）
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
|
|||
|
|
# 本地开发（uvicorn reload，监听 127.0.0.1:8000）
|
|||
|
|
python run_local.py
|
|||
|
|
# 等价于：
|
|||
|
|
uvicorn wechat:app --reload --host 127.0.0.1 --port 8000
|
|||
|
|
|
|||
|
|
# 服务器部署（不 reload，单 worker，监听 127.0.0.1:8000，由 Nginx 反代）
|
|||
|
|
python run_server.py
|
|||
|
|
|
|||
|
|
# 初始化本地配置
|
|||
|
|
cp .env.example .env # 然后填入真实值
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
当前仓库没有测试框架、lint 或构建配置；如需运行单个测试，需先引入 pytest 等工具。
|
|||
|
|
|
|||
|
|
## 架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
config.py # 从 .env 读取配置（dotenv），模块级常量
|
|||
|
|
wechat.py # FastAPI app 本体：路由 + 签名校验 + XML 解析/构造
|
|||
|
|
run_local.py # 开发启动入口（reload=True）
|
|||
|
|
run_server.py # 生产启动入口（reload=False, workers=1）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **配置**：所有敏感值经 `config.py` 从 `.env` 读取，`.env` 已被 `.gitignore` 排除。`.env.example` 是字段模板。新增配置项需同时更新这两处。
|
|||
|
|
- **应用入口**：两个启动脚本均以 `"wechat:app"` 字符串形式加载 `wechat.py` 中的 `app`，因此模块名/对象名不可随意重命名。
|
|||
|
|
- **微信交互协议**：
|
|||
|
|
- 所有请求先经 `verify_signature()`（token+timestamp+nonce 字典序拼接后 SHA1 比对）校验，失败返回 403。
|
|||
|
|
- GET 校验通过后原样返回 `echostr`。
|
|||
|
|
- POST 解析微信推送的 XML（`MsgType`/`FromUserName`/`Event` 等），通过 `_reply_text()` 构造文本回复 XML 返回。新增消息类型处理应在 `wechat_message()` 的事件/消息分支中扩展。
|
|||
|
|
- **注意**：`_reply_text()` 中 ToUserName/FromUserName 是反置的（回复时收发方互换），这是微信协议要求。
|
|||
|
|
|
|||
|
|
## 约定
|
|||
|
|
|
|||
|
|
- 代码注释与文档字符串使用中文。
|
|||
|
|
- 生产环境仅监听 127.0.0.1，对外暴露依赖 Nginx 反向代理。
|