文档：完善泽源后端协作基线

2026-06-22 16:27:57 +08:00
parent 53a5260cac
commit fcbd728457
19 changed files with 2806 additions and 0 deletions
@@ -1 +1,137 @@
+# ARCHITECTURE.md

+本文是后端架构入口，说明 Django 项目内部模块边界和调用规则。具体业务需求看 `docs/specs/`，字段、接口和状态以 `docs/contracts/` 为准。
+
+## 架构原则
+
+1. 第一版采用 Django 模块化单体，不拆微服务。
+2. app 负责边界和数据归属，复杂业务逻辑放 service 层。
+3. view / serializer 只做请求响应、参数校验和呈现，不承载复杂流程。
+4. 所有关键动作必须写操作日志或失败记录。
+5. 飞书回调、AI 输出、定时触发必须幂等。
+6. 权限必须在接口层和 service 层双重校验。
+
+## 运行时与依赖版本
+
+> 第一版新项目采用仍在官方扩展支持期内的 Django 5.2 LTS。Docker / 部署环境固定 Python 3.12.13；本地开发允许 Python 3.11 或 3.12，但提交前必须在部署基线 Python 3.12.13 上跑完整测试。
+
+| 类别              | 版本约定                                                                             |
+| --------------- | -------------------------------------------------------------------------------- |
+| Python          | 部署 `3.12.13`；本地开发 `>=3.11,<3.13`                                                 |
+| Web 框架          | `Django==5.2.15`                                                                 |
+| API 框架          | `djangorestframework==3.17.1`                                                    |
+| ORM / Migration | Django ORM + Django Migrations，跟随 `Django==5.2.15`                               |
+| 数据库             | MySQL `8.4.10` LTS，使用平台自有应用库                                                     |
+| MySQL 驱动        | `mysqlclient==2.2.8`                                                             |
+| 定时任务            | `APScheduler==3.11.2` + `django-apscheduler==0.7.0`，通过独立 management command 进程运行 |
+| AI 接入           | `dashscope==1.25.23`；百炼管理类 OpenAPI 可选 `alibabacloud-bailian20231229==2.13.1`     |
+| 飞书接入            | `lark-oapi==1.6.8`                                                               |
+| 登录态 / 加解密       | `PyJWT==2.13.0` + `cryptography==49.0.0`                                         |
+| HTTP / 配置       | `requests==2.34.2`、`httpx==0.28.1`、`python-dotenv==1.2.2`                        |
+| WSGI            | `gunicorn==26.0.0`                                                               |
+| Docker 基础镜像     | `python:3.12.13-slim-bookworm`、`mysql:8.4.10`、`nginx:stable-alpine`              |
+
+Python 依赖基线：
+
+```txt
+Django==5.2.15
+djangorestframework==3.17.1
+mysqlclient==2.2.8
+asgiref==3.11.1
+sqlparse==0.5.5
+tzdata==2026.2
+python-dotenv==1.2.2
+requests==2.34.2
+httpx==0.28.1
+APScheduler==3.11.2
+django-apscheduler==0.7.0
+dashscope==1.25.23
+alibabacloud-bailian20231229==2.13.1
+lark-oapi==1.6.8
+PyJWT==2.13.0
+cryptography==49.0.0
+gunicorn==26.0.0
+```
+
+## 推荐 Django app
+
+| app | 职责 |
+| --- | --- |
+| `accounts` | 自定义用户、角色、登录态、飞书身份绑定 |
+| `people` | 人员映射、称呼匹配、第一批试用人员 |
+| `drafts` | AI 草稿、补充/重说、草稿状态流转 |
+| `tasks` | 事项创建、程经理确认、事项状态流转 |
+| `reminders` | 定时提醒、固定周期、触发记录 |
+| `notifications` | 飞书通知、通知补发、通知状态 |
+| `feedbacks` | 飞书卡片反馈、平台内反馈 |
+| `feishu` | 飞书登录、机器人事件、卡片回调、验签 |
+| `prompts` | 背景摘要、老板风格提示词、业务规则版本 |
+| `audit` | 失败记录、操作日志、模型调用日志 |
+
+## 分层约定
+
+| 层 | 放什么 | 不放什么 |
+| --- | --- | --- |
+| `models` | 字段、索引、基础枚举、简单 model 方法 | 跨模块流程、外部 API 调用 |
+| `serializers` | 入参出参结构、字段级校验、展示转换 | 状态机、权限决策、飞书调用 |
+| `views` | DRF ViewSet/APIView、权限入口、调用 service | 复杂业务分支、事务主体 |
+| `services` | 业务流程、状态流转、事务、幂等、日志 | HTTP 请求细节 |
+| `clients` | 阿里百炼、飞书 API 等外部调用封装 | 业务状态修改 |
+| `tasks/commands` | scheduler、补发、批处理命令 | Web 请求上下文依赖 |
+
+## 核心调用方向
+
+```text
+views
+-> serializers
+-> services
+-> models / clients
+-> audit logs / failure records
+```
+
+允许：
+
+1. `drafts` 通过 service 转换为 `tasks` 或 `reminders`。
+2. `tasks` / `reminders` 通过 service 创建 `notifications`。
+3. `notifications` 通过 `feishu` client 发送消息。
+4. `feishu` 回调通过 service 更新 `drafts`、`feedbacks`、`tasks`、`reminders`。
+5. 所有模块写入 `audit`。
+
+避免：
+
+1. app 之间直接互相改 model 状态。
+2. 在 view 里直接调用飞书或模型 API。
+3. 在 serializer 里做状态流转。
+4. 在 scheduler 中绕过 service 直接改业务表。
+
+## 必须写日志的动作
+
+1. 飞书登录成功或失败。
+2. 机器人收到老板消息。
+3. 非老板私聊机器人。
+4. AI 生成草稿、解析失败。
+5. 人工确认、修改、取消草稿。
+6. 老板点击补充/重说。
+7. 程经理确认复杂事项。
+8. 创建事项、创建提醒。
+9. 发送通知、补发通知、通知失败。
+10. 接收反馈，尤其是“有问题”反馈。
+11. 定时提醒触发成功或失败。
+12. 失败记录处理。
+13. 背景摘要或老板风格提示词版本启用。
+
+## 后台任务
+
+定时提醒扫描使用独立进程，不放在 Gunicorn worker 内。生产和测试环境必须保证同一环境同一应用库同时只有一个 scheduler 进程在运行；如果未来多实例部署，需要先引入外部锁、leader election 或数据库级幂等锁。建议命令：
+
+```bash
+python manage.py run_reminder_scheduler
+```
+
+调度器每次触发前必须检查幂等键：
+
+```text
+reminder_id + trigger_time + receiver_id + notification_channel
+```
+
+同一个提醒、同一个触发时间、同一个接收人，只允许生成一条有效通知。