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

This commit is contained in:
talesofzes
2026-06-22 16:27:57 +08:00
parent 53a5260cac
commit fcbd728457
19 changed files with 2806 additions and 0 deletions
+159
View File
@@ -1 +1,160 @@
# 01_老板 AI 秘书与 AI 草稿
## 1. 模块目标
老板 AI 秘书负责接收老板在飞书机器人私聊或平台输入的一句话,判断意图,并整理成可人工确认的草稿。第一版 AI 只生成草稿或回答,不直接创建事项、不直接创建提醒、不直接发送通知。
## 2. 第一版做什么
1. 支持老板在平台输入文本。
2. 支持老板通过飞书机器人私聊输入文本。
3. 判断意图类型:`task``reminder``qa``realtime_qa``note``unknown`
4.`task` 生成事项草稿。
5.`reminder` 生成提醒草稿。
6.`qa` 直接用大白话回答,不生成草稿。
7.`realtime_qa` 提示第一版暂不支持正式实时查询,不创建草稿、不通知、不做交易判断。
8.`unknown` 追问关键缺失信息,最多 3 个补充项。
9. 支持老板确认、补充/重说、取消草稿。
10. 支持补充/重说 30 分钟上下文,超时后按新输入处理。
11. 支持复杂事项转程经理确认。
12. AI 调用时加载公司背景摘要、老板大白话风格和第一版业务规则版本。
## 3. 第一版不做
1. 不做老板独立 App。
2. 不做语音、图片、文件上传或多模态输入。
3. 不做员工通用 AI 工作台。
4. 不让 AI 自动替代程经理拆复杂任务。
5. 不让 AI 未经确认直接通知别人。
6. 不做实时天气、新闻、股价、行情查询的正式能力。
7. 不把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
## 4. 核心流程
平台入口:
```text
老板输入一句话
-> POST /api/ai-drafts/parse
-> 后端加载 prompt_contexts
-> 调用 ai_client
-> 校验模型 JSON
-> 写入 model_call_logs
-> 生成 ai_drafts
-> 前端展示草稿
```
飞书机器人入口:
```text
老板私聊机器人
-> 飞书事件回调
-> 后端验签
-> 匹配平台用户
-> 校验 boss 角色
-> 检查 bot_contexts 是否等待补充
-> 调用 AI 生成或重写草稿
-> 发送飞书确认卡片
-> 写入 feishu_events、ai_drafts、operation_logs
```
非老板私聊机器人:
```text
收到机器人私聊
-> 匹配用户
-> 发现不是 boss
-> 不调用 AI
-> 不生成草稿
-> 回复进入平台处理
-> 写入未授权访问失败记录
```
## 5. 数据对象
本模块主要使用:
1. `users`
2. `person_mappings`
3. `bot_contexts`
4. `prompt_contexts`
5. `ai_drafts`
6. `model_call_logs`
7. `feishu_events`
8. `failure_records`
9. `operation_logs`
字段以 `docs/contracts/数据对象约定.md` 为准。
## 6. 接口需求
主要接口:
1. `POST /api/ai-drafts/parse`
2. `GET /api/ai-drafts`
3. `GET /api/ai-drafts/{id}`
4. `PATCH /api/ai-drafts/{id}`
5. `POST /api/ai-drafts/{id}/confirm`
6. `POST /api/ai-drafts/{id}/cancel`
7. `POST /api/ai-drafts/{id}/convert`
8. `POST /api/ai-drafts/{id}/follow-up`
9. `POST /api/feishu/events`
10. `POST /api/feishu/card-callback`
接口格式以 `docs/contracts/API接口约定.md` 为准。
## 7. 权限规则
1. 飞书机器人私聊入口第一版只允许老板使用。
2. 非老板私聊机器人时,不调用模型、不生成草稿,只记录未授权访问。
3. 老板可以确认、补充/重说、取消自己发起的草稿。
4. 程经理只能确认转给自己的复杂事项草稿。
5. 管理员 / AI 团队只能协助排查,不代替老板或程经理做业务确认。
## 8. 状态流转
草稿状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
1. `pending_confirmation` 只能等待确认、取消、补充或转程经理。
2. 未确认草稿不得创建事项、提醒或通知。
3. `parse_failed` 不得继续转换。
4. `converted` 草稿不得重复转换。
5. 补充/重说会生成新草稿,并通过 `parent_draft_id` 指向上一版草稿。
## 9. 失败和日志
必须记录:
1. 原始输入和 AI 输出摘要。
2. 模型调用使用的背景摘要版本、老板风格版本和业务规则版本。
3. AI JSON 解析失败。
4. 缺少人员映射。
5. 非老板机器人访问。
6. 补充/重说上下文过期。
7. 人工确认、修改、取消、转程经理确认。
不得记录:
1. API Key。
2. 飞书 token。
3. 完整手机号。
4. 完整邮箱。
5. 飞书 App Secret。
## 10. 给 AI 的测试样例
1. 老板输入“明天上午提醒东东给我订会议室”,应生成 `reminder` 草稿,不直接创建提醒。
2. 老板输入“让剑楠下周给我看一下期货策略风险”,应生成 `task` 草稿,并倾向 `manager_confirm`
3. 老板输入“今天杭州天气怎么样”,应识别为 `realtime_qa`,不生成事项或提醒。
4. 普通员工私聊机器人,应返回未开放提示,并写入未授权访问记录。
5. 老板点击补充/重说后 30 分钟内再发消息,应关联上一版草稿。
6. AI 输出 JSON 缺少 `draft_type` 时,应写入解析失败,不创建草稿闭环对象。
## 11. Review 重点
1. 是否严格保证 AI 只生成草稿。
2. 是否所有关键动作都需要人工确认。
3. 是否避免将游戏化表达写入结构化字段。
4. 是否记录模型版本和 prompt_contexts 版本。
5. 是否对非老板机器人访问做了后端权限校验。
6. 是否对模型 JSON 做了结构校验和失败记录。
+130
View File
@@ -1 +1,131 @@
# 02_事项任务
## 1. 模块目标
事项任务模块承接老板 AI 秘书草稿、程经理确认和手动创建事项,负责通知接收人、记录反馈、展示状态和沉淀失败原因。第一版只做轻量事项闭环,不做完整项目管理。
## 2. 第一版做什么
1. 事项可以来自 AI 草稿确认。
2. 事项可以由程经理确认复杂草稿后生成。
3. 事项可以由老板或程经理手动创建。
4. 普通员工第一版不默认给别人创建事项。
5. 事项必须有发起人、接收人、事项内容、反馈要求和状态。
6. 事项生成前必须经过人工确认。
7. 事项生成后可以创建飞书通知。
8. 接收人可以反馈:已收到、处理中、已完成、有问题。
9. 有问题反馈必须填写一句原因。
10. 发起人、程经理或有权限人员可以查看处理进度。
11. 通知失败或无人反馈的事项需要可见,但不单独做看板。
## 3. 第一版不做
1. 不做复杂项目管理系统。
2. 不做多级子任务。
3. 不做复杂审批流。
4. 不做绩效排名。
5. 不做任务依赖和甘特图。
6. 不做项目级看板。
7. 不做独立反馈看板。
8. 不从 AI 工作台结果生成事项。
## 4. 核心流程
简单事项:
```text
AI 草稿或手动输入
-> 人工确认
-> 创建 tasks
-> 创建 notifications
-> 飞书通知接收人
-> 接收人反馈
-> 更新事项状态
-> 写入 operation_logs
```
复杂事项:
```text
老板确认转程经理
-> 创建 pending_manager_confirm 事项或待确认记录
-> 给程经理发飞书提醒
-> 程经理进入平台确认、修改和分发
-> 通知接收人
-> 接收反馈
```
## 5. 数据对象
本模块主要使用:
1. `ai_drafts`
2. `tasks`
3. `notifications`
4. `feedbacks`
5. `failure_records`
6. `operation_logs`
字段以 `docs/contracts/数据对象约定.md` 为准。
## 6. 接口需求
主要接口:
1. `GET /api/tasks`
2. `POST /api/tasks`
3. `GET /api/tasks/{id}`
4. `PATCH /api/tasks/{id}`
5. `POST /api/tasks/{id}/manager-confirm`
6. `POST /api/tasks/{id}/cancel`
7. `POST /api/tasks/{id}/notify`
8. `POST /api/tasks/{id}/feedback`
接口格式以 `docs/contracts/API接口约定.md` 为准。
## 7. 权限规则
1. 老板可以创建事项。
2. 程经理可以创建和分发事项。
3. 普通员工不能给别人创建事项。
4. 接收人只能反馈自己相关事项。
5. 程经理只能确认待自己处理的复杂事项。
6. 管理员 / AI 团队可以为排查查看必要记录,但不处理业务分歧。
## 8. 状态流转
事项状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
1. 未确认事项不得通知接收人。
2. `pending_manager_confirm` 必须由程经理确认后才能进入通知流程。
3. 通知失败进入 `notify_failed`,不得假装已通知。
4. 已取消事项不能反馈、通知或补发。
5. 有问题反馈会将事项标记为 `problem`,并记录原因。
## 9. 失败和日志
必须记录:
1. 事项创建来源:AI 草稿、手动创建或程经理确认。
2. 创建、修改、取消、通知、补发、反馈操作。
3. 权限拒绝。
4. 通知失败。
5. 有问题反馈原因。
6. 人员映射缺失或接收人不明确。
## 10. 给 AI 的测试样例
1. 普通员工请求给同事创建事项,应返回权限错误。
2. 老板确认简单事项后,事项进入待通知或已通知状态。
3. 研究类事项应进入程经理确认路径。
4. 接收人反馈“有问题”但不填原因,应返回校验错误。
5. 通知失败时,事项状态不得变成已通知。
6. 已取消事项不得再次通知。
## 11. Review 重点
1. 后端是否做了权限校验,而不是只靠前端隐藏按钮。
2. 状态流转是否只走允许路径。
3. 通知失败是否留下失败记录。
4. 有问题反馈是否强制原因。
5. 是否避免把复杂项目管理能力混入第一版。
+145
View File
@@ -1 +1,146 @@
# 03_飞书通知与反馈
## 1. 模块目标
飞书模块负责平台登录身份、老板机器人私聊入口、个人消息通知、交互卡片确认和反馈回调。第一版飞书是闭环主入口之一,所有回调必须验签、幂等、可追溯。
## 2. 第一版做什么
1. 飞书扫码登录 / 身份登录。
2. 根据飞书身份匹配平台用户和角色。
3. 接收老板机器人私聊消息。
4. 非老板私聊机器人时提示进入平台并记录未授权访问。
5. 发送 AI 草稿确认卡片给老板。
6. 发送复杂事项待确认提醒给程经理,按钮只跳转平台。
7. 发送事项或提醒通知给接收人。
8. 接收卡片按钮回调。
9. 支持接收人反馈已收到、处理中、已完成、有问题。
10. 记录飞书事件、通知发送结果和回调处理结果。
## 3. 第一版不做
1. 不把机器人开放成程经理或普通员工通用派活入口。
2. 不让程经理在机器人里对话分发事项。
3. 不在飞书消息里展开敏感全文。
4. 不做飞书卡片内复杂字段编辑表单。
5. 不绕过平台角色权限。
## 4. 核心流程
飞书登录:
```text
用户点击飞书登录
-> 跳转飞书授权
-> 飞书回调 auth callback
-> 校验 state 和 code
-> 换取飞书身份
-> 匹配平台用户
-> 写入 feishu_auth_sessions
-> 建立平台登录态
```
机器人私聊:
```text
飞书推送消息事件
-> 验签
-> 记录 feishu_events
-> 匹配平台用户
-> 校验 boss 角色
-> 调用 AI 草稿服务
-> 发送确认卡片
```
卡片回调:
```text
飞书卡片按钮点击
-> 验签
-> 记录 feishu_events
-> 查找 notification / draft / task / reminder
-> 校验操作人权限
-> 执行业务动作
-> 写 operation_logs
-> 返回飞书处理结果
```
## 5. 数据对象
本模块主要使用:
1. `users`
2. `person_mappings`
3. `feishu_auth_sessions`
4. `feishu_events`
5. `notifications`
6. `feedbacks`
7. `bot_contexts`
8. `failure_records`
9. `operation_logs`
字段以 `docs/contracts/数据对象约定.md` 为准。
## 6. 接口需求
主要接口:
1. `GET /api/auth/feishu/login`
2. `GET /api/auth/feishu/callback`
3. `POST /api/feishu/events`
4. `POST /api/feishu/bot/messages`
5. `POST /api/feishu/card-callback`
6. `POST /api/notifications/{id}/retry`
接口格式以 `docs/contracts/API接口约定.md` 为准。
## 7. 权限规则
1. 飞书身份只用于认证和操作人追溯,业务权限仍以平台角色为准。
2. 机器人私聊入口第一版只允许老板使用。
3. 老板只能确认、取消、补充自己发起的草稿。
4. 程经理待办提醒只能跳转平台确认。
5. 反馈人必须是事项或提醒接收人。
6. 管理员 / AI 团队可以处理系统失败和补发,但不能代替业务反馈。
## 8. 状态与幂等
状态以 `docs/contracts/状态流转约定.md` 为准。幂等约束:
1. 同一个飞书 `event_id` 只处理一次。
2. 同一个通知只允许一个有效发送结果。
3. 同一个卡片按钮重复点击不得重复创建事项、提醒或反馈。
4. 回调处理失败必须标记 `feishu_events.process_status = failed` 并写失败记录。
## 9. 失败和日志
必须记录:
1. 飞书登录成功或失败。
2. 飞书事件原始 payload。
3. 机器人消息处理结果。
4. 卡片回调处理结果。
5. 通知发送成功或失败。
6. 验签失败。
7. 找不到关联对象。
8. 操作人无权操作。
9. 有问题反馈缺少原因。
普通日志不得打印飞书 token、App Secret、完整手机号或完整邮箱。
## 10. 给 AI 的测试样例
1. 验签失败的回调应返回拒绝并写失败记录。
2. 同一 `event_id` 重放应幂等,不重复创建反馈。
3. 非接收人点击反馈按钮应返回权限错误。
4. 老板点击取消草稿后,草稿不能再转换。
5. 非老板私聊机器人不应调用 AI。
6. 飞书通知失败时,应写 `failure_records` 并保留通知失败状态。
## 11. Review 重点
1. 回调是否验签。
2. 回调是否幂等。
3. 飞书身份是否没有直接绕过平台权限。
4. 通知内容是否只发摘要和链接。
5. 失败是否可复盘。
+138
View File
@@ -1 +1,139 @@
# 04_定时提醒
## 1. 模块目标
定时提醒模块负责创建一次性或固定周期提醒,到点生成通知、发送飞书消息、按需接收反馈,并记录触发结果和失败原因。
## 2. 第一版做什么
1. 支持一次性提醒。
2. 支持每天、每周、每月固定周期提醒。
3. 支持提醒来自手动创建。
4. 支持提醒来自老板 AI 草稿确认。
5. 支持提醒与事项关联。
6. 到点后通知接收人。
7. 通知成功或失败都要记录。
8. 支持查看自己相关提醒状态。
9. 创建人、发起人、管理员可以修改、暂停或取消提醒。
10. 提醒可以设置是否需要接收人反馈。
## 3. 第一版不做
1. 不做 cron 表达式。
2. 不做自定义复杂周期规则。
3. 不做日历系统。
4. 不做复杂自动化流程。
5. 不自动操作外部系统。
6. 不从 AI 工作台结果生成提醒。
## 4. 核心流程
创建提醒:
```text
手动创建或草稿确认
-> 后端校验创建权限
-> 写入 reminders
-> 计算 next_trigger_at
-> 写 operation_logs
```
触发提醒:
```text
scheduler 扫描 due reminders
-> 校验提醒状态
-> 生成幂等键
-> 创建 notifications
-> 调用飞书发送
-> 更新 last_triggered_at 和 next_trigger_at
-> 成功或失败都写记录
```
反馈:
```text
接收人点击卡片反馈
-> 飞书回调验签
-> 校验接收人权限
-> 写 feedbacks
-> 保留 reminders 调度状态,反馈结果通过 feedbacks 展示
```
## 5. 数据对象
本模块主要使用:
1. `ai_drafts`
2. `tasks`
3. `reminders`
4. `notifications`
5. `feedbacks`
6. `failure_records`
7. `operation_logs`
字段以 `docs/contracts/数据对象约定.md` 为准。
## 6. 接口需求
主要接口:
1. `GET /api/reminders`
2. `POST /api/reminders`
3. `GET /api/reminders/{id}`
4. `PATCH /api/reminders/{id}`
5. `POST /api/reminders/{id}/pause`
6. `POST /api/reminders/{id}/resume`
7. `POST /api/reminders/{id}/cancel`
8. `POST /api/reminders/{id}/notify`
9. `POST /api/reminders/{id}/feedback`
接口格式以 `docs/contracts/API接口约定.md` 为准。
## 7. 权限规则
1. 所有人可以创建自己的提醒。
2. 老板和程经理可以给别人创建提醒。
3. 普通员工不能给同事创建提醒。
4. 创建人、发起人、管理员可以修改、暂停或取消提醒。
5. 接收人只能反馈自己相关提醒。
## 8. 状态流转
提醒状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
1. `active` 提醒才允许 scheduler 触发。
2. `paused` 不触发,但可以恢复。
3. `cancelled` 不触发、不可恢复。
4. `trigger_failed` 必须写失败记录。
5. 同一个提醒同一触发时间同一接收人只能生成一条有效通知。
6. 一次性提醒成功触发后进入 `triggered`;周期提醒成功触发后保持 `active` 并计算下一次 `next_trigger_at`
7. 提醒反馈不改变提醒调度状态,反馈结果通过 `feedbacks` 展示。
## 9. 失败和日志
必须记录:
1. 提醒创建、修改、暂停、恢复、取消。
2. scheduler 触发成功或失败。
3. 飞书通知发送成功或失败。
4. 幂等冲突或重复触发跳过。
5. 权限拒绝。
6. 有问题反馈原因。
## 10. 给 AI 的测试样例
1. 普通员工给同事创建提醒,应返回权限错误。
2. `paused` 提醒到点不应触发通知。
3. 同一提醒同一触发时间重复扫描,不应重复创建通知。
4. 每周提醒触发后,应计算下一次提醒时间。
5. 通知失败应写失败记录。
6. 自己提醒自己默认不需要反馈,老板或程经理给别人提醒默认需要反馈。
## 11. Review 重点
1. 是否防止重复触发。
2. 是否限制普通员工给别人创建提醒。
3. 是否不支持 cron 等第一版不做内容。
4. scheduler 是否走 service 层而不是直接改业务表。
5. 失败是否可复盘。
+134
View File
@@ -1 +1,135 @@
# 05_权限日志失败记录
## 1. 模块目标
权限、日志和失败记录模块负责保证第一版闭环可控、可追溯、可复盘。权限必须在后端校验,关键操作必须写日志,AI、飞书、调度和业务失败必须形成失败记录。
## 2. 第一版做什么
1. 定义老板、程经理、普通员工、管理员 / AI 团队四类角色。
2. 控制事项、提醒、草稿、反馈、失败记录的可见范围和操作范围。
3. 记录关键操作日志。
4. 记录 AI 解析失败、人员映射缺失、飞书通知失败、回调失败、定时触发失败、用户反馈有问题等失败。
5. 支持管理员 / AI 团队查看和处理失败记录。
6. 对敏感信息做日志边界约束。
## 3. 第一版不做
1. 不做复杂组织架构。
2. 不做细粒度多级权限。
3. 不做复杂审批流。
4. 不做独立失败看板或复杂 BI。
5. 不把飞书身份直接等同于业务权限。
6. 不把密钥、token、完整手机号、完整邮箱写入普通日志。
## 4. 核心流程
权限校验:
```text
请求进入 DRF view
-> permission class 做入口校验
-> serializer 做参数校验
-> service 做业务权限和状态校验
-> 通过后执行业务动作
```
失败记录:
```text
业务或外部调用失败
-> 写 failure_records
-> 保留关联对象和失败类型
-> 管理员 / AI 团队处理
-> 填写处理结果
-> 写 operation_logs
```
操作日志:
```text
关键动作发生
-> 记录 actor、action、target_type、target_id
-> 记录操作渠道和结果摘要
-> 避免记录敏感明文
```
## 5. 数据对象
本模块主要使用:
1. `users`
2. `failure_records`
3. `operation_logs`
4. `model_call_logs`
5. `feishu_events`
字段以 `docs/contracts/数据对象约定.md` 为准。
## 6. 接口需求
主要接口:
1. `GET /api/users/me`
2. `GET /api/failure-records`
3. `GET /api/failure-records/{id}`
4. `PATCH /api/failure-records/{id}`
5. `POST /api/failure-records/{id}/resolve`
6. `GET /api/notifications`
7. `GET /api/notifications/{id}`
8. `GET /api/feedbacks`
接口格式以 `docs/contracts/API接口约定.md` 为准。
## 7. 权限规则
1. 普通员工只能看自己作为接收人、创建人或反馈人的记录。
2. 老板能看自己发起、创建或接收的记录。
3. 程经理能看自己发起、负责、待确认,以及第一批试用管理范围内的记录。
4. 管理员 / AI 团队能看失败记录、通知记录、人员映射和必要操作日志。
5. 普通员工不能给别人创建事项或提醒。
6. 反馈人必须是事项或提醒接收人。
7. 飞书登录用户必须匹配到启用状态的平台用户后才能进入平台。
## 8. 状态流转
失败记录状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
1. 新失败进入 `pending`
2. 处理中进入 `processing`
3. 填写处理结果后进入 `resolved`
4. 确认不处理可进入 `cancelled`
5. 失败记录状态变化必须写操作日志。
## 9. 必须写日志的动作
1. 飞书登录成功或失败。
2. 机器人收到老板消息。
3. 非老板私聊机器人。
4. AI 生成草稿、解析失败。
5. 人工确认、修改、取消草稿。
6. 老板点击补充/重说。
7. 程经理确认复杂事项。
8. 创建事项、创建提醒。
9. 发送通知、补发通知、通知失败。
10. 接收反馈,尤其是有问题反馈。
11. 定时提醒触发成功或失败。
12. 失败记录处理。
13. 背景摘要或老板风格提示词版本启用。
## 10. 给 AI 的测试样例
1. 普通员工创建给别人的事项,应被拒绝并写权限失败日志。
2. 普通员工创建给别人的提醒,应被拒绝。
3. 非接收人提交反馈,应被拒绝。
4. 管理员处理失败记录时,必须留下处理结果。
5. 日志中不得包含完整手机号、完整邮箱、飞书 token 或密钥。
6. 未匹配平台用户的飞书登录应失败并写失败记录。
## 11. Review 重点
1. 后端权限是否完整。
2. 状态流转是否可追踪。
3. 失败记录是否包含关联对象、失败类型和处理结果。
4. 日志是否记录操作人和渠道。
5. 敏感信息是否被脱敏。