talesofzes
293 lines
9.4 KiB
Markdown
293 lines
9.4 KiB
Markdown
# 数据对象约定
|
|
|
|
本文件是核心表、字段、外键关系和状态字段的唯一事实源。Django model、serializer、接口返回和测试用例中的字段应与本文件一致。
|
|
|
|
## 1. 通用字段
|
|
|
|
多数业务表使用：
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 主键，建议 bigint 或 uuid |
|
|
| `created_at` | 创建时间 |
|
|
| `updated_at` | 更新时间 |
|
|
| `created_by` | 创建人，可为空时必须说明来源 |
|
|
| `updated_by` | 最后修改人 |
|
|
| `deleted_at` | 软删除时间，可选 |
|
|
| `remark` | 备注，可选 |
|
|
|
|
第一版建议使用软删除，避免误删过程记录。
|
|
|
|
## 2. users
|
|
|
|
平台登录、角色判断和数据范围控制。Django 项目初始化时建议使用自定义用户模型。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 用户 ID |
|
|
| `username` | 登录名或内部唯一标识 |
|
|
| `name` | 显示姓名 |
|
|
| `role` | `boss`、`manager`、`employee`、`admin` |
|
|
| `phone` | 手机号，可选，普通日志需脱敏 |
|
|
| `email` | 邮箱，可选，普通日志需脱敏 |
|
|
| `feishu_open_id` | 飞书 open_id，可选 |
|
|
| `feishu_user_id` | 飞书 user_id，可选 |
|
|
| `feishu_union_id` | 飞书 union_id，可选 |
|
|
| `auth_provider` | `local`、`feishu` |
|
|
| `last_login_channel` | `platform`、`feishu_scan`、`feishu_in_app` |
|
|
| `status` | `active`、`disabled` |
|
|
| `last_login_at` | 最后登录时间 |
|
|
|
|
## 3. person_mappings
|
|
|
|
把老板输入中的姓名、称呼、部门或角色映射到平台用户和飞书身份。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 映射 ID |
|
|
| `user_id` | 关联平台用户，可选 |
|
|
| `display_name` | 标准姓名 |
|
|
| `aliases` | JSON 数组，例如 `["东东", "CJN"]` |
|
|
| `department` | 部门 |
|
|
| `business_role` | 业务角色，例如行政、程经理、下单员 |
|
|
| `phone` | 手机号，可选 |
|
|
| `email` | 邮箱，可选 |
|
|
| `feishu_open_id` | 飞书 open_id |
|
|
| `feishu_user_id` | 飞书 user_id，可选 |
|
|
| `feishu_union_id` | 飞书 union_id，可选 |
|
|
| `mapping_status` | `pending`、`resolved`、`failed` |
|
|
| `is_trial_user` | 是否第一批试用人员 |
|
|
| `note` | 备注 |
|
|
|
|
## 4. feishu_auth_sessions
|
|
|
|
记录飞书登录过程和平台用户绑定结果。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 会话 ID |
|
|
| `state` | OAuth state 或登录状态标识 |
|
|
| `feishu_open_id` | 飞书 open_id |
|
|
| `feishu_user_id` | 飞书 user_id |
|
|
| `feishu_union_id` | 飞书 union_id，可选 |
|
|
| `matched_user_id` | 匹配到的平台用户 |
|
|
| `login_channel` | `feishu_scan`、`feishu_in_app` |
|
|
| `status` | `pending`、`success`、`failed` |
|
|
| `failure_reason` | 失败原因 |
|
|
| `completed_at` | 完成时间 |
|
|
|
|
## 5. bot_contexts
|
|
|
|
记录老板机器人私聊中的补充/重说上下文。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 上下文 ID |
|
|
| `user_id` | 平台用户 ID，第一版应为老板 |
|
|
| `feishu_open_id` | 飞书发送人 open_id |
|
|
| `current_draft_id` | 等待补充的草稿 ID |
|
|
| `status` | `idle`、`awaiting_follow_up`、`expired`、`closed` |
|
|
| `expires_at` | 补充/重说有效期，默认 30 分钟 |
|
|
| `last_message_id` | 最近一条飞书消息 ID |
|
|
| `last_message_text` | 最近一条消息内容 |
|
|
|
|
## 6. prompt_contexts
|
|
|
|
维护 AI 秘书调用模型时加载的上下文版本。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 上下文 ID |
|
|
| `context_type` | `company_background`、`boss_style`、`business_rules` |
|
|
| `version` | 版本号 |
|
|
| `title` | 标题 |
|
|
| `content` | 实际使用的摘要或规则文本 |
|
|
| `status` | `draft`、`active`、`archived` |
|
|
| `activated_at` | 启用时间 |
|
|
| `created_by` | 创建人 |
|
|
|
|
模型调用日志只保存本次使用的摘要、版本号和必要规则，避免反复保存完整背景库全文。
|
|
|
|
## 7. ai_drafts
|
|
|
|
保存 AI 从一句话整理出的可确认草稿。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 草稿 ID |
|
|
| `source` | `platform`、`feishu_bot` |
|
|
| `created_by` | 发起人 |
|
|
| `raw_input` | 原始输入 |
|
|
| `draft_type` | `task`、`reminder`、`qa`、`realtime_qa`、`note`、`unknown` |
|
|
| `status` | 见状态流转约定 |
|
|
| `title` | 草稿标题 |
|
|
| `content` | 事项或提醒内容 |
|
|
| `receiver_candidates` | JSON，接收人候选和置信度 |
|
|
| `scheduled_time` | 提醒或期望处理时间，可为空 |
|
|
| `repeat_rule` | `none`、`daily`、`weekly`、`monthly` |
|
|
| `requires_feedback` | 是否需要反馈 |
|
|
| `route_type` | `direct_notify`、`manager_confirm`、`needs_clarification` |
|
|
| `missing_fields` | JSON 数组 |
|
|
| `follow_up_questions` | JSON 数组，最多 3 个 |
|
|
| `answer` | `qa` / `realtime_qa` 的回答 |
|
|
| `parent_draft_id` | 补充/重说生成的新草稿指向上一版 |
|
|
| `model_call_log_id` | 关联模型调用日志 |
|
|
|
|
## 8. model_call_logs
|
|
|
|
记录模型输入输出、模型名、耗时和结果。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 日志 ID |
|
|
| `provider` | `bailian` |
|
|
| `model_name` | 模型名 |
|
|
| `prompt_context_snapshot` | 本次使用的上下文版本和摘要 |
|
|
| `request_payload` | 请求摘要，避免保存密钥 |
|
|
| `raw_response` | 模型原始响应 |
|
|
| `parsed_json` | 解析后的 JSON |
|
|
| `status` | `success`、`failed` |
|
|
| `failure_reason` | 失败原因 |
|
|
| `latency_ms` | 耗时 |
|
|
| `created_by` | 调用发起人 |
|
|
|
|
## 9. tasks
|
|
|
|
需要接收人处理并反馈的事情。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 事项 ID |
|
|
| `source_draft_id` | 来源草稿，可选 |
|
|
| `title` | 标题 |
|
|
| `content` | 事项内容 |
|
|
| `initiator_id` | 发起人 |
|
|
| `receiver_id` | 接收人 |
|
|
| `manager_id` | 复杂事项确认人，可选 |
|
|
| `status` | 见状态流转约定 |
|
|
| `visible_feedback_status` | `received`、`in_progress`、`completed`、`problem` |
|
|
| `requires_feedback` | 是否需要反馈 |
|
|
| `due_at` | 截止或期望反馈时间，可选 |
|
|
| `confirmed_at` | 确认时间 |
|
|
| `notified_at` | 通知时间 |
|
|
| `completed_at` | 完成时间 |
|
|
| `problem_reason` | 有问题原因，可选 |
|
|
|
|
## 10. reminders
|
|
|
|
未来某个时间触发的提醒。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 提醒 ID |
|
|
| `source_draft_id` | 来源草稿，可选 |
|
|
| `related_task_id` | 关联事项，可选 |
|
|
| `title` | 标题 |
|
|
| `content` | 提醒内容 |
|
|
| `initiator_id` | 发起人 |
|
|
| `receiver_id` | 接收人 |
|
|
| `status` | 见状态流转约定 |
|
|
| `remind_at` | 首次提醒时间 |
|
|
| `next_trigger_at` | 下一次触发时间 |
|
|
| `repeat_rule` | `none`、`daily`、`weekly`、`monthly` |
|
|
| `requires_feedback` | 是否需要反馈 |
|
|
| `last_triggered_at` | 最近触发时间 |
|
|
| `cancelled_at` | 取消时间 |
|
|
|
|
## 11. notifications
|
|
|
|
飞书或平台内通知发送记录。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 通知 ID |
|
|
| `target_type` | `ai_draft`、`task`、`reminder`、`failure_record` |
|
|
| `target_id` | 关联对象 ID |
|
|
| `receiver_id` | 接收人 |
|
|
| `channel` | `feishu`、`platform` |
|
|
| `message_type` | `text`、`card` |
|
|
| `summary` | 通知摘要 |
|
|
| `link_url` | 平台详情链接 |
|
|
| `status` | `pending`、`sent`、`failed`、`retrying`、`cancelled` |
|
|
| `idempotency_key` | 幂等键 |
|
|
| `feishu_message_id` | 飞书消息 ID |
|
|
| `sent_at` | 发送时间 |
|
|
| `failure_reason` | 失败原因 |
|
|
|
|
## 12. feedbacks
|
|
|
|
接收人的反馈状态和问题原因。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 反馈 ID |
|
|
| `target_type` | `task`、`reminder` |
|
|
| `target_id` | 关联对象 ID |
|
|
| `feedback_by` | 反馈人 |
|
|
| `status` | `received`、`in_progress`、`completed`、`problem` |
|
|
| `problem_reason` | 有问题原因，`problem` 时必填 |
|
|
| `source` | `feishu_card`、`platform` |
|
|
| `notification_id` | 关联通知 |
|
|
| `created_at` | 反馈时间 |
|
|
|
|
## 13. failure_records
|
|
|
|
AI、通知、回调、调度等失败原因。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 失败记录 ID |
|
|
| `failure_type` | 见状态流转约定中的失败类型 |
|
|
| `target_type` | 关联对象类型 |
|
|
| `target_id` | 关联对象 ID |
|
|
| `status` | `pending`、`processing`、`resolved`、`cancelled` |
|
|
| `reason` | 失败原因 |
|
|
| `raw_error` | 原始错误摘要，不含密钥 |
|
|
| `need_manager_sync` | 是否需要同步程经理 |
|
|
| `handled_by` | 处理人 |
|
|
| `handled_at` | 处理时间 |
|
|
| `handle_result` | 处理结果 |
|
|
|
|
## 14. operation_logs
|
|
|
|
人工确认、修改、取消、补发等过程留痕。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 日志 ID |
|
|
| `actor_id` | 操作人 |
|
|
| `action` | 动作 |
|
|
| `target_type` | 对象类型 |
|
|
| `target_id` | 对象 ID |
|
|
| `channel` | `platform`、`feishu_bot`、`feishu_card`、`scheduler`、`admin` |
|
|
| `result` | `success`、`failed` |
|
|
| `summary` | 操作摘要 |
|
|
| `metadata` | JSON，避免敏感明文 |
|
|
| `created_at` | 操作时间 |
|
|
|
|
## 15. feishu_events
|
|
|
|
飞书回调原始事件和处理结果。
|
|
|
|
| 字段 | 说明 |
|
|
| --- | --- |
|
|
| `id` | 事件 ID |
|
|
| `event_id` | 飞书事件 ID |
|
|
| `event_type` | 事件类型 |
|
|
| `operator_open_id` | 操作人 open_id |
|
|
| `action_value` | 按钮值 |
|
|
| `target_type` | `ai_draft`、`task`、`reminder`、`auth`、`bot` |
|
|
| `target_id` | 关联业务对象 |
|
|
| `notification_id` | 关联通知 |
|
|
| `raw_payload` | 原始事件 |
|
|
| `process_status` | `pending`、`processed`、`failed`、`ignored` |
|
|
| `process_result` | 处理结果 |
|
|
| `created_at` | 接收时间 |
|
|
|
|
## 16. 敏感字段规则
|
|
|
|
1. `phone`、`email` 可入库，但普通日志和普通列表接口默认脱敏。
|
|
2. API Key、App Secret、飞书 token 不得入库到业务表或普通日志。
|
|
3. `raw_error`、`metadata`、`request_payload` 必须避免密钥和完整个人联系方式。
|
|
4. 飞书通知内容只保存和发送摘要，不展开敏感全文。
|