wecom_it_smart_desk/docs/数据库ER图与环境变量清点.md

数据库 ER 图 + 环境变量清点

日期: 2026-06-15 审计人: Claude(满载跑批) 关联: 技术架构 / 风险跟踪表 / 前端审计报告

---

📌 1. ER 图(ASCII + Mermaid)

1.1 实体清单(16 张表)

#	表名	中文	模型文件	用途
1	conversations	会话	conversation.py	核心:员工-坐席咨询会话
2	messages	消息	message.py	会话内的所有消息
3	agents	坐席	agent.py	IT 服务人员
4	employees	员工	employee.py	通过 OAuth2 认证的员工
5	agent_notes	坐席备注	agent_note.py	坐席对会话的备注
6	system_configs	系统配置	system_config.py	动态配置(关键词/阈值)
7	config_change_logs	配置变更日志	config_change_log.py	配置项的审计
8	quick_reply_templates	快速回复模板	quick_reply_template.py	坐席常用回复
9	funny_phrases	趣味话术	funny_phrase.py	等候中的趣味话
10	approval_links	审批流程链接	approval_link.py	各类审批入口
11	software_downloads	软件下载	software_download.py	常用软件清单
12	troubleshooting_templates	排障模板	troubleshooting_template.py	标准化排障路径
13	todo_items	待办事项	todo_item.py	工单/审批/设备
14	roles	角色	role.py	RBAC 角色定义
15	user_roles	用户-角色关联	user_role.py	多对多关联
16	role_mapping_rules	角色映射规则	role_mapping_rule.py	自动分配规则

1.2 ER 图(Mermaid)

erDiagram
    EMPLOYEES ||--o{ CONVERSATIONS : "创建(通过 corp_id+employee_id)"
    EMPLOYEES ||--o{ USER_ROLES : "拥有角色"
    CONVERSATIONS ||--o{ MESSAGES : "包含"
    CONVERSATIONS ||--o{ AGENT_NOTES : "有备注"
    CONVERSATIONS }o--|| AGENTS : "被分配给"
    AGENTS ||--o{ AGENT_NOTES : "写"
    AGENTS ||--o{ QUICK_REPLY_TEMPLATES : "提交"
    AGENTS ||--o{ CONFIG_CHANGE_LOGS : "改配置"
    ROLES ||--o{ USER_ROLES : "分配给"
    ROLES ||--o{ ROLE_MAPPING_RULES : "按规则映射"
    CONVERSATIONS ||--o| TODO_ITEMS : "关联待办"
    SYSTEM_CONFIGS ||--o{ CONFIG_CHANGE_LOGS : "被改"

    EMPLOYEES {
        string id PK "UUID"
        string corp_id "企业ID"
        string employee_id "企微UserID"
        string name "姓名"
        string department "部门(IDs)"
        string position "岗位"
        string mobile
        string email
        string avatar
        int status "1激活 2禁用 4未激活"
        string it_level "技能等级"
        string it_level_source
        json notes "坐席备注"
        datetime last_login_at
        datetime created_at
        datetime updated_at
    }

    AGENTS {
        string id PK
        string user_id UK "企微UserID"
        string name
        string status "online/offline/busy"
        int current_load
        int max_load
        string role "admin/agent"
        json skill_tags
        string otp_secret "TOTP密钥"
        boolean otp_enabled
        string password_hash "bcrypt"
        datetime created_at
        datetime updated_at
    }

    CONVERSATIONS {
        string id PK
        string corp_id
        string employee_id
        string employee_name
        string department
        string position
        string level
        string status "ai/queued/serving/resolved"
        boolean is_vip
        boolean is_pinned
        boolean is_todo
        int urgency_score "1-5"
        json tags
        string assigned_agent_id FK
        json collaborating_agent_ids
        json participants
        int ai_substantive_reply_count
        int impact_scope
        boolean is_blocking
        string emotion_state
        string dify_conversation_id
        datetime last_message_at
        string last_message_summary
        datetime created_at
        datetime updated_at
    }

    MESSAGES {
        string id PK
        string conversation_id FK
        string sender_type "employee/agent/ai/system"
        string sender_id
        string sender_name
        text content
        string msg_type "text/image/file/voice/system"
        string reply_to_id "引用"
        string media_id
        string media_url
        string file_name
        int file_size
        json extra_data
        boolean ai_suggestion
        string status "sending/sent/delivered/read"
        datetime recallable_until
        boolean is_read
        string suggestion_action "accepted/edited/ignored"
        datetime created_at
    }

    AGENT_NOTES {
        string id PK
        string conversation_id FK
        string agent_id
        text content
        datetime created_at
        datetime updated_at
    }

    SYSTEM_CONFIGS {
        string id PK
        string config_key UK
        text config_value
        string description
        datetime updated_at
    }

    CONFIG_CHANGE_LOGS {
        string id PK
        string config_key
        text old_value
        text new_value
        string changed_by
        datetime changed_at
    }

    QUICK_REPLY_TEMPLATES {
        string id PK
        string category
        string title
        text content
        json variables
        int sort_order
        string status "draft/pending/approved/rejected"
        int version
        string submitted_by
        datetime created_at
        datetime updated_at
    }

    FUNNY_PHRASES {
        string id PK
        string scene "shake/keyword/waiting/connected/timeout/vip"
        text content
        string tone
        int sort_order
        boolean is_active
        datetime created_at
        datetime updated_at
    }

    APPROVAL_LINKS {
        string id PK
        string category "IT/HR/行政/财务"
        string title
        text url
        int sort_order
        datetime created_at
        datetime updated_at
    }

    SOFTWARE_DOWNLOADS {
        string id PK
        string category "办公/开发/安全/工具"
        string name
        string version
        string platform
        text download_url
        int sort_order
        datetime created_at
        datetime updated_at
    }

    TROUBLESHOOTING_TEMPLATES {
        string id PK
        string name
        string category "vpn/email/system/account"
        json path_steps
        json flowchart
        boolean is_active
        datetime created_at
        datetime updated_at
    }

    TODO_ITEMS {
        string id PK
        string type "ticket/approval/device"
        string title
        string priority "urgent/high/normal"
        json description
        string status "pending/processing/resolved"
        string assigned_agent_id
        string corp_id
        datetime created_at
        datetime updated_at
    }

    ROLES {
        string id PK
        string name UK "user/agent/admin"
        string display_name
        text description
        json permissions
        boolean is_default
        datetime created_at
        datetime updated_at
    }

    USER_ROLES {
        string id PK
        string employee_id
        string role_id FK
        string source "auto/tag/ehr/manual"
        string assigned_by
        datetime assigned_at
        datetime expires_at
    }

    ROLE_MAPPING_RULES {
        string id PK
        string role_id FK
        string source_type "wecom_tag/ehr_position"
        string source_value
        int priority
        boolean is_active
        datetime created_at
    }

1.3 ER 关系总结

                ┌────────────┐
                │  EMPLOYEES │
                │  (员工)    │
                └─────┬──────┘
                      │ corp_id + employee_id
        ┌─────────────┼─────────────┐
        │             │             │
        v             v             v
   ┌────────┐  ┌──────────────┐  ┌──────────────┐
   │CONVER- │  │  USER_ROLES  │  │TODO_ITEMS    │
   │SATIONS │  │      ↕       │  │(企业内待办)   │
   └──┬─────┘  │   ROLES      │  └──────────────┘
      │        │↕             │
      │        │ROLE_MAPPING  │
      │        │_RULES        │
      │        └──────────────┘
      │ 1:N
      v
   ┌────────┐  1:N  ┌────────┐
   │MESSAGES│◄─────│AGENT_  │
   └────────┘      │NOTES   │
                   └────┬───┘
                        │ 写
                        v
                   ┌────────┐
   ┌──────────┐    │AGENTS  │
   │CONFIGS   │    └───┬────┘
   │  ↕       │        │ 改
   │CHANGE    │◄───────┘
   │LOGS      │
   └──────────┘

关系数: 13 个外键关联 + 3 个 JSON 数组(协作/参与者/技能) 外键关系:

1. conversations.employee_id → 企微 ID(无 DB FK,跨企业灵活)
2. conversations.assigned_agent_id → agents.id(可空)
3. messages.conversation_id → conversations.id (CASCADE)
4. agent_notes.conversation_id → conversations.id (CASCADE)
5. agent_notes.agent_id → agents.id(无 CASCADE)
6. user_roles.role_id → roles.id (CASCADE)
7. role_mapping_rules.role_id → roles.id (CASCADE)
8. config_change_logs.changed_by → agents.id(无 FK)
9. quick_reply_templates.submitted_by → agents.id(可空)

---

📌 2. 字段-模块映射

业务模块	主要表	关键字段
鉴权登录	agents, employees, roles, user_roles	user_id, password_hash, otp_secret, role
会话管理	conversations	status, urgency_score, assigned_agent_id, is_vip
消息	messages	sender_type, content, msg_type, reply_to_id
AI 助手	conversations, system_configs	dify_conversation_id, ai_substantive_reply_count
排障	troubleshooting_templates	path_steps, flowchart
快速回复	quick_reply_templates	category, content, variables
待办	todo_items	type, status, priority
工具面板	approval_links, software_downloads, funny_phrases	category, scene
动态配置	system_configs, config_change_logs	config_key, config_value
审计	config_change_logs	changed_by, changed_at, old_value, new_value

---

📌 3. 数据规模评估(生产估算)

表	日增(估)	总量/年	备注
conversations	100-500	50K-100K	视企业规模
messages	1K-10K	1M-3M	高频
employees	10-30	5K-20K	增长慢
agents	0-1	20-50	增长极慢
agent_notes	50-200	30K-70K	每会话 1-2 条
quick_reply_templates	1-3	50-200	缓慢增长
system_configs	0-1	50-100	极慢
config_change_logs	5-20	5K-10K	审计
todo_items	50-200	30K-70K	流转快
troubleshooting_templates	0-1	30-50	缓慢
funny_phrases	0	30-50	几乎不变
approval_links	0-1	20-50	缓慢
software_downloads	0-1	30-80	缓慢
roles	0	3-10	几乎不变
user_roles	5-15	5K-20K	跟员工同步
role_mapping_rules	0	5-15	几乎不变

总数据量估算: 第 1 年 ~5-10 MB(纯数据), 含索引 ~20-50 MB 建议: PostgreSQL 起步 10 GB 足够,3-5 年无需扩容

---

📌 4. 环境变量清点(15 个 + 4 个文档化待补)

4.1 后端核心(backend/app/config.py)

#	变量	类型	默认	必填	敏感	用途
1	WECOM_CORP_ID	str	ww1234...	✅	❌	企微企业 ID
2	WECOM_AGENT_ID	str	1000002	✅	❌	企微应用 ID
3	WECOM_SECRET	str	your-agent-secret	✅	🔴 高	企微应用 Secret
4	WECOM_TOKEN	str	your-callback-token	✅	🟠 中	回调 Token
5	WECOM_ENCODING_AES_KEY	str	your-aes-key-43-...	✅	🟠 中	回调 AES Key
6	DATABASE_URL	str	postgresql://wecom:...	✅	🔴 高(密码部分)	DB 连接
7	REDIS_URL	str	redis://localhost:6379/0	✅	🟠 中(密码)	Redis 连接
8	BACKEND_HOST	str	0.0.0.0	❌	❌	监听地址
9	BACKEND_PORT	int	8000	❌	❌	监听端口
10	CORS_ORIGINS	str(逗号分隔)	localhost:5173,5174	🟡 生产必填	❌	CORS 白名单
11	DIFY_API_URL	str	""	🟡 启用 AI 必填	❌	Dify Chat 端点
12	DIFY_API_KEY	str	""	🟡 启用 AI 必填	🔴 高	Dify API Key
13	DIFY_TIMEOUT	int	30	❌	❌	Dify 超时
14	DIFY_WINGMAN_API_URL	str	""	❌	❌	Wingman 端点
15	DIFY_WINGMAN_API_KEY	str	""	❌	🔴 高	Wingman Key
16	DIFY_WINGMAN_TIMEOUT	int	30	❌	❌	Wingman 超时
17	MOCK_LOGIN_ENABLED	bool	false	❌	❌	Mock 登录开关

合计 17 个(Settings 字段),5 个敏感(3 个 P0-高,2 个 P0-中)

4.2 部署相关(deploy-server/.env / deploy-nas/.env.nas)

#	变量	用途
18	POSTGRES_USER	DB 用户名
19	POSTGRES_PASSWORD	DB 密码(🔴)
20	POSTGRES_DB	DB 名
21	REDIS_PASSWORD	Redis 密码(🔴)

4.3 前端(Vue 4 个端)

前端	变量	用途
admin	VITE_API_BASE_URL	后端地址
agent	VITE_API_BASE_URL, VITE_WS_URL	后端 + WebSocket
h5	VITE_API_BASE_URL, VITE_WS_URL	同上
portal	VITE_API_BASE_URL, VITE_PORTAL_REDIRECT	入口跳转

4.4 漏配/待补

#	变量	状态	影响
A	LOG_LEVEL	❌ 缺失	日志粒度无法控制
B	JWT_SECRET / SESSION_SECRET	❌ 缺失	token 加密用,但还没用 JWT
C	WS_TOKEN_SECRET	❌ 缺失	WS token 签名用
D	DIFY_PROXY_URL	❌ 文档化但未用	公司有内部 Dify,本项目直连

---

📌 5. 敏感凭据安全审计

5.1 现状

#	凭据	存储位置	风险
1	WECOM_SECRET	.env.production(git?)	🟠 中(看是否加 .gitignore)
2	POSTGRES_PASSWORD	.env.production	🟠 中
3	REDIS_PASSWORD	.env.production	🟠 中
4	DIFY_API_KEY	.env.production	🟠 中
5	内部 Gitea tokens	wincred(✅)	🟢 已修

5.2 待办(风险跟踪表 M-11)

• .env.production 是否在 .gitignore?(需确认)
• .env.nas 是否入仓?(文档明确说不入)
• 公司有内部 Vault?目前直连 Dify
• WECOM_TOKEN / AES_KEY 走 vault(下一轮)

5.3 短期方案(本周)

# 1. 验证 .gitignore 覆盖
git check-ignore -v .env.production .env.nas backend/.env

# 2. 验证仓里无 secret
git log --all -p --source -- .env.production 2>/dev/null | head -20

# 3. 跑 gitleaks 扫描
bash scripts/security-audit.sh --secrets

5.4 长期方案(下季度)

1. NAS Vault:用 Synology 的「密码保险箱」存关键 secret
2. Server Keyring:用 systemd-creds / HashiCorp Vault
3. 环境变量注入:容器启动时从 vault 拉,不入镜像

---

📌 6. 关联文档

• 技术架构 §3 数据层
• 风险跟踪表 M-11(凭据管理)/ D-3(DB 密码)
• 外部系统集成 §1-4(火绒/联软/aTrust/eHR 凭据)
• SOP-001-Gitea部署 - token 走 wincred
• Gitea部署指南 - Gitea app.ini 凭据

---

本清点是 2026-06-15 Claude 满载跑批产出,待评审