AI-Secretary/docs/contracts/数据对象约定.md

数据对象约定

本文件是核心表、字段、外键关系和状态字段的唯一事实源。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. 飞书通知内容只保存和发送摘要，不展开敏感全文。