chore: docs update + docker-compose + H5 login

2026-07-09 13:46:48 +08:00
parent db70a3a6a8
commit 3d152fc8eb
5 changed files with 48 additions and 5 deletions
@@ -136,8 +136,11 @@ services:
      - BACKEND_PORT=8000
      # 上传文件目录（持久化）
      - UPLOAD_DIR=/app/uploads
+      # 运行期日志目录（供"运行期日志"管理页面读取，需与下方 volumes 挂载一致）
+      - RUNTIME_LOG_DIR=/app/logs
    volumes:
      - backend-uploads:/app/uploads
+      - ${RUNTIME_LOG_HOST_DIR:-/var/log/wecom-it-desk}:/app/logs
    depends_on:
      postgres:
        condition: service_healthy
@@ -1071,6 +1071,30 @@ ALTER TABLE agents ADD COLUMN mfa_bound_at TIMESTAMP;

 **开发周期**：4-6周

+#### 管理后台日志体系（贯穿各阶段，2026-07-09 增补）
+
+> **为什么单列**：管理后台长期存在 5 类「日志」机制概念混淆（配置变更历史 / 安全审计日志 / 自动化动作日志 / 运行期结构化日志 / 会话消息记录）。本小节统一定义与边界，支撑阶段四「日志标准」，并将用户 2026-07-09 拍板的 5 项决策纳入 PRD。详细定义、接口、字段、验收标准见 `docs/04-功能设计/系统日志与审计日志-产品与设计.md`。
+
+**五类日志定位**：
+
+| 编号 | 名称 | 落点 | 核心用途 | 实现状态 |
+|------|------|------|----------|----------|
+| A | 配置变更历史（系统日志） | `config_change_logs` | 配置项前后值 diff | 已实现（前端无筛选） |
+| B | 安全审计日志（操作日志） | `audit_logs` | 安全行为事件 | 已实现（部分事件待补） |
+| C | 自动化动作日志 | `auto_action_logs` | 外部系统调用出入参 | 已实现（落表为主） |
+| D | 运行期结构化日志 | stdout → Docker 文件 | 应用运行排障 | 后端已实现，查看页未落地 |
+| E | 会话 / 消息记录 | `conversations` / `messages` | 业务主数据 | 已实现 |
+
+**用户已拍板 5 项决策（2026-07-09，宋献）**：
+
+| # | 决策 | 优先级 | 验收要点 |
+|---|------|--------|----------|
+| 1 | 侧边栏「系统日志」区分命名：配置变更历史（A） vs 安全审计日志（B） | P1 | 两个独立清晰入口，无「系统日志」歧义统称 |
+| 2 | 配置变更维持 A+B 双写，不收敛 | P0 | `PUT /api/admin/configs/{key}` 同时写两表（`config_change` 事件） |
+| 3 | A 页补充「配置键 / 操作人 / 时间」筛选（后端 `GET /api/admin/system-logs` 加参） | P1 | 三筛选可用，后端参数支持 |
+| 4 | D 运行期日志查看：按级别 / 时间筛选 + 下载（权限 admin） | P0 | 页面 + 后端接口落地（`.txt` / `.log`） |
+| 5 | 补《系统日志/审计日志 产品+设计文档》，并入 PRD/架构、列项目任务 | — | 本文档即交付，看板登记 #101–#104 |
+
 #### 阶段五：自动/辅助审核、开单、结单

 > **本阶段解决痛点**：多系统切换效率问题（延伸痛点4/5，进一步提升人效）。
@@ -294,6 +294,18 @@ OAuth2 授权完成（用户端） / 登录成功（坐席/管理端）
 - 会话监控
 - 知识图谱管理

+#### 7.1.1 日志体系（2026-07-09 增补）
+
+> 管理后台 5 类「日志」机制统一归口，详细定义、接口、字段、权限见 `docs/04-功能设计/系统日志与审计日志-产品与设计.md`。
+
+| 编号 | 日志 | 表 / 存储 | 接口路径 | 权限 | 状态 |
+|------|------|-----------|----------|------|------|
+| A | 配置变更历史 | `config_change_logs` | `GET /api/admin/system-logs`（写：`PUT /api/admin/configs/{key}`） | admin | 已实现（无筛选） |
+| B | 安全审计日志 | `audit_logs` | `GET /admin/audit-logs` | `audit_log:read:all`（admin / auditor） | 已实现（事件待补） |
+| C | 自动化动作日志 | `auto_action_logs` | （落表，暂未暴露列表接口） | — | 已实现 |
+| D | 运行期结构化日志 | stdout → Docker 文件 | 待开发：`GET /api/admin/runtime-logs`（筛选 + 下载） | admin | 查看页未落地 |
+| E | 会话 / 消息记录 | `conversations` / `messages` | 会话管理相关接口 | agent / admin | 已实现（业务主数据） |
+
 ### 7.2 坐席工作台模块

 **技术栈**：Vue 3 + TypeScript + Element Plus + Pinia
@@ -4,7 +4,7 @@
 >
 > 📝 **更新规则**:每次 Claude 完成 / 开始 / 阻塞重要任务,会主动更新本文件。你也可以自己改(纯 markdown,git 跟踪)。

-最后更新:**2026-07-09 09:20**(WS 子协议修复部署生产 + 合入 origin/main；方案A E2E 2026-07-08 通过)
+最后更新:**2026-07-09**(WS 子协议修复部署生产 + 合入 origin/main；方案A E2E 2026-07-08 通过；+ 日志体系 5 项决策登记 #101–#104)

 ---

@@ -151,6 +151,7 @@
 | #48 | v1.0 收窄 set_real_ip_from | 🔴 P0 | 现 allow 0.0.0.0/0 是临时方案,正式上线前必须改精确代理 IP |
 | #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤 ⚠️验真:隐私检测Bug+仅警告 |
 | #90 | 身份认证问题修复 | ✅已完成 | ✅Portal→H5 token传递修复：路由守卫接收token后调用fetchEmployeeInfo()获取用户信息 |
+| #104 | 运行期结构化日志查看页（D） | 🔴 P0 | 决策4：落地「按级别/时间筛选 + 下载」页面与后端接口（`GET /api/admin/runtime-logs`），权限 admin；产品规格见 `docs/04-功能设计/系统日志与审计日志-产品与设计.md`；状态：待开发 |

 ---

@@ -166,6 +167,9 @@
 | #100 | 消息推送策略优化与超时提醒 | ✅已完成：坐席回复仅推 H5，超时未回复发送企微提醒，10分钟后标记待关闭 |
 | 🆕 | 修 64 pre-existing 测试失败 | Role.data_scope 缺字段 / WecomService DI / test_message_experience 等 |
 | #75 | 头像同步功能完善 | 登录全路径强制同步 + 前端首字降级；代码已交付（12/12 单测 + 103 回归），**业务效果待端到端验真** | 🆕 等用户通知执行 |
+| #101 | 管理后台日志命名区分（决策1） | 侧边栏「系统日志」明确区分「配置变更历史(A)」与「安全审计日志(B)」，避免管理员混淆；状态：待开发 |
+| #102 | 配置变更 A+B 双写边界确认（决策2） | 维持 `PUT /api/admin/configs/{key}` 同时写 `config_change_logs` 与 `audit_logs` 的 `config_change` 事件，不收敛；代码已实现，本文档锁定边界；状态：设计中 |
+| #103 | 配置变更历史页筛选（决策3） | A 页补充「配置键/操作人/时间」筛选，后端 `GET /api/admin/system-logs` 增加对应过滤参数；状态：待开发 |

 ---

@@ -21,10 +21,10 @@
      <div class="login-form">
        <van-field
          v-model="employeeId"
-          label="员工ID"
-          placeholder="请输入企微员工 UserID"
+          label="员工账号"
+          placeholder="请输入企微员工账号（UserID）"
          clearable
-          :rules="[{ required: true, message: '请输入员工ID' }]"
+          :rules="[{ required: true, message: '请输入员工账号' }]"
          @keyup.enter="handleLogin"
        />

@@ -156,7 +156,7 @@ function handleResetPassword(): void {
 async function handleLogin(): Promise<void> {
  const id = employeeId.value.trim()
  if (!id) {
-    showToast('请输入员工ID')
+    showToast('请输入员工账号')
    return
  }