# 数据对象约定

本文件是核心表、字段、外键关系和状态字段的唯一事实源。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. secretary_conversations

老板 AI 秘书会话。第一阶段只有一个老板秘书入口，可先固定 `conversation_id=boss_secretary_default`，但表结构要能支持后续多会话。

| 字段 | 说明 |
| --- | --- |
| `id` | 会话 ID |
| `conversation_id` | 业务会话唯一标识 |
| `boss_id` | 关联老板用户 |
| `source` | `feishu`、`web`、`debug` |
| `status` | `active`、`closed` |
| `last_message_at` | 最近消息时间 |

## 6. secretary_messages

老板输入、AI 回复、AI 追问、普通记录和上下文回顾的统一消息记录。该表只追加，不修改，用于对话回放、上下文回顾和问题复盘。

| 字段 | 说明 |
| --- | --- |
| `id` | 消息 ID |
| `conversation_id` | 关联 `secretary_conversations.conversation_id` |
| `boss_id` | 关联老板用户 |
| `source` | `feishu`、`web`、`debug` |
| `message_id` | 外部消息 ID 或内部生成 ID，和 `source` 组成幂等键 |
| `role` | `boss`、`assistant`、`system` |
| `text` | 原始输入或 AI 回复 |
| `answer` | AI 给老板的回复，可为空 |
| `intent_type` | `task`、`reminder`、`qa`、`realtime_qa`、`note`、`need_more_info`、`unsupported`、`context_summary` |
| `draft_id` | 关联 AI 草稿，可为空 |
| `raw_payload` | 原始请求摘要，避免保存密钥 |
| `bot_context_snapshot` | JSONB，消息发生时的上下文快照 |
| `created_at` | 消息时间 |

## 7. bot_contexts

记录老板机器人私聊中的补充/重说上下文。

| 字段 | 说明 |
| --- | --- |
| `id` | 上下文 ID |
| `conversation_id` | 当前老板秘书会话 ID |
| `boss_id` | PostgreSQL 中的老板用户 ID |
| `status` | `empty`、`awaiting_more_info`、`awaiting_confirm`、`expired`、`cleared` |
| `pending_draft_id` | 当前待补充或待确认的草稿 ID |
| `pending_draft_type` | `task`、`reminder`、`none` |
| `last_intent` | 上一条有效意图 |
| `expires_at` | 上下文有效期，进入待补充或待确认时重置为 30 分钟后 |
| `follow_up_count` | 当前草稿累计追问轮次 |
| `last_message_id` | 最近一次参与上下文判断的消息 ID |
| `extracted_facts` | JSONB，从多轮对话提取的候选事实，只用于草稿修订 |
| `updated_at` | 上下文最近更新时间 |

## 8. prompt_contexts

维护 AI 秘书调用模型时加载的上下文版本。

| 字段 | 说明 |
| --- | --- |
| `id` | 上下文 ID |
| `context_type` | `company_background_summary`、`boss_communication_style`、`ai_secretary_rules`、`role_and_alias_rules` |
| `version` | 版本号 |
| `title` | 标题 |
| `content` | 实际使用的摘要或规则文本 |
| `status` | `draft`、`active`、`archived` |
| `activated_at` | 启用时间 |
| `created_by` | 创建人 |

模型调用日志只保存本次使用的摘要、版本号和必要规则，避免反复保存完整背景库全文。

## 9. ai_drafts

保存 AI 从一句话整理出的可确认草稿。

| 字段 | 说明 |
| --- | --- |
| `id` | 草稿 ID |
| `source` | `platform`、`feishu_bot` |
| `created_by` | 发起人 |
| `raw_input` | 原始输入 |
| `intent` | `task`、`reminder` |
| `draft_type` | `task`、`reminder` |
| `should_create_draft` | 固定为 true；`qa/realtime_qa/note/need_more_info/unsupported` 不落 ai_drafts |
| `status` | 见状态流转约定 |
| `title` | 草稿标题 |
| `content` | 事项或提醒内容 |
| `receiver_candidates` | JSON，接收人候选和置信度 |
| `receiver_text` | 未映射成功时保留老板原始称呼 |
| `scheduled_at` | 提醒时间，可为空；任务可使用 `schedule_text` 表达期望时间 |
| `schedule_text` | 老板原始时间表达 |
| `recurrence_type` | `none`、`daily`、`weekly`、`monthly` |
| `requires_feedback` | 是否需要反馈 |
| `route_type` | `direct_after_boss_confirm`、`manager_confirm_required` |
| `need_manager_confirm` | 是否需要程经理确认 |
| `missing_fields` | JSON 数组 |
| `questions` | JSON 数组，最多 3 个；确认草稿一般为空 |
| `answer` | 给老板看的回复摘要；不得写“已通知、已创建、已发送”等执行语义 |
| `model_call_log_id` | 关联模型调用日志 |

## 10. model_call_logs

记录模型输入输出、模型名、耗时和结果。

| 字段 | 说明 |
| --- | --- |
| `id` | 日志 ID |
| `provider` | `bailian` |
| `model_name` | 模型名 |
| `prompt_context_snapshot` | 本次使用的上下文版本和摘要 |
| `request_payload` | 请求摘要，避免保存密钥 |
| `raw_response` | 模型原始响应 |
| `parsed_json` | 解析后的 `AiSecretaryResponse` JSON |
| `status` | `success`、`failed` |
| `failure_reason` | 失败原因 |
| `latency_ms` | 耗时 |
| `created_by` | 调用发起人 |

## 11. 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` | 有问题原因，可选 |

## 12. reminders

未来某个时间触发的提醒。

| 字段 | 说明 |
| --- | --- |
| `id` | 提醒 ID |
| `source_draft_id` | 来源草稿，可选 |
| `related_task_id` | 关联事项，可选 |
| `title` | 标题 |
| `content` | 提醒内容 |
| `initiator_id` | 发起人 |
| `receiver_id` | 接收人 |
| `status` | 见状态流转约定 |
| `scheduled_at` | 首次提醒时间 |
| `next_trigger_at` | 下一次触发时间 |
| `recurrence_type` | `none`、`daily`、`weekly`、`monthly` |
| `requires_feedback` | 是否需要反馈 |
| `last_triggered_at` | 最近触发时间 |
| `cancelled_at` | 取消时间 |

## 13. 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` | 失败原因 |

## 14. 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` | 反馈时间 |

## 15. 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` | 处理结果 |

## 16. 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` | 操作时间 |

## 17. 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` | 接收时间 |

## 18. 敏感字段规则

1. `phone`、`email` 可入库，但普通日志和普通列表接口默认脱敏。
2. API Key、App Secret、飞书 token 不得入库到业务表或普通日志。
3. `raw_error`、`metadata`、`request_payload` 必须避免密钥和完整个人联系方式。
4. 飞书通知内容只保存和发送摘要，不展开敏感全文。