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. 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. 飞书通知内容只保存和发送摘要，不展开敏感全文。