talesofzes
9.4 KiB
9.4 KiB
数据对象约定
本文件是核心表、字段、外键关系和状态字段的唯一事实源。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. 敏感字段规则
phone、email可入库，但普通日志和普通列表接口默认脱敏。- API Key、App Secret、飞书 token 不得入库到业务表或普通日志。
raw_error、metadata、request_payload必须避免密钥和完整个人联系方式。- 飞书通知内容只保存和发送摘要，不展开敏感全文。