TSS Portal
使用指南

点击登录页上的 Google 登录按钮，使用 企业邮箱完成 OAuth 认证。

• 需要管理员提前将您的邮箱添加到用户白名单
• 首次登录后自动同步头像和用户名

点击登录页底部的「开发者入口」，输入已注册邮箱和访问码即可进入。

服务器部署在阿里云无法访问 googleapis.com，Google 验签用的公钥（每 1-2 周轮换一次）由管理员浏览器代为拉取后推送到服务器。普通用户登录无任何感知。

• 管理员每次打开 /admin.html 时自动触发一次刷新（静默执行，无需操作）
• 「Google 配置」tab 底部的「Google 公钥证书」卡片可手动点击「立即刷新」
• 登录路径带 5 秒超时 + 宽容缓存策略，即使 Google 临时不可达也不会 hang 死整个登录请求

• 顶部 cat-tab 胶囊按钮「全部 / 分类 A / 分类 B / ...」
• 选「全部」：显示分类卡片网格，每张卡显示分类名 + 链接数量徽章
• 选具体分类：直接平铺该分类下所有链接
• 未分类的链接自动聚合到末尾的「其他」虚拟卡
• 图标由系统根据名称和描述自动分配（去重），无需手动选择

• 智能定位（视口边缘自动调整方向，不溢出）
• 列出该分类下所有链接（含个人链接，带「我的」徽章）
• 点 ESC / 点外部 / 滚动页面 → Popover 自动关闭
• 底部「+ 添加链接到此分类」→ 跳到管理页并预选当前分类

• 顶部胶囊按钮按工具分类过滤（PPT 制作 / 数据分析 / 邮件处理 / ...）
• 工具卡显示状态指示灯（在线 / 离线 / 检测中）
• 受权限和个人隐藏设置控制（在「我的工作台 → 工具设置」管理）

• 顶部 cat-tab 过滤栏（绿色风格）
• 「全部」显示项目分类卡片，点击弹 Popover 概览
• 选具体分类 tab → 平铺显示该分类下项目（保留绿色边框风格）
• 「+ 添加项目到此分类」→ 跳管理页预选分类

• 顶部默认分类 + 默认公开范围（每行可单独覆盖）
• 表格逐行填写：标题 / URL / 描述 / 分类 / 公开范围
• 支持粘贴 TSV/CSV：从 Excel / Notion / Google Sheets 直接复制粘贴整张表
• 分隔符自动识别（含制表符 → TSV，否则 CSV）
• 第一行如含「标题/title」「url/链接」字样会被识别为表头并跳过
• 行级修改自动脱离默认值（边框变色提示）
• 提交时图标自动分配，事务原子性（要么全部成功要么全部回滚）

• 侧边栏「项目分类」入口，同链接分类操作模式
• 项目编辑 Modal 增加「分类」下拉
• 项目管理表格增加「分类」列
• 支持用户私有项目分类（在「我的工作台」管理）
• 删除分类时该分类下项目自动归到「其他」（ON DELETE SET NULL）

LLM 配置分为两层：

• 全局提供商凭证：在「LLM 配置」Tab 中设置 MiniMax 或 GLM 的 API Key、API URL、模型名称等
• 工具级配置：为「日报周报心得」「日语润色」等 AI 工具单独选择使用哪个提供商，并可自定义系统提示词

当 LLM 未启用、无 API Key 或余额不足时，系统自动回退到本地模板，不影响使用。

• 公开（all）：所有登录用户均可看到
• 仅分配（assigned）：只有在 user_content_access 表中被授权的用户才能看到
• 个人（private）：仅创建者自己可见（user_id 关联）

当管理员把某条内容的 visibility 从 assigned 改为 all 时，系统会自动删除该内容在 user_content_access 中的所有授权记录。

为什么？ 防止以后切回 assigned 时旧授权意外恢复（曾发生过：原本只授权给 A 用户，后改成全员公开，再后来又改回限定状态，结果 A 用户依然能看，造成困惑）。

之前 /projects/<slug> 和 /tools/<dir>/* 是纯静态资源，知道 URL 即可访问。现已加入服务端鉴权：

• 未登录访问 → 自动 redirect 到 /login.html（HTTP 302）
• 登录但无权限 → 返回 403 友好提示页（含「返回首页」按钮）
• 资源文件（.css/.js/图片等）放行（性能优化，安全边界在 HTML 入口）
• 认证机制：JWT 同时存 localStorage（API 调用）+ httpOnly Cookie（HTML 入口校验）

把生产数据库 + 项目 HTML + 工具数据拉到本地：

bash pull-data.sh

自带安全机制：

• Schema 安全预检：本地 init.js 比服务器新（说明你有未发布修改）会要求输入 yes 确认
• 本地服务停止检测：检查 3000 端口占用，让你停服防 DB 损坏
• WAL checkpoint：确保 [容器名称].db-wal 落入主库（防数据丢失）
• 本地 DB 备份：拷贝到 data/.backup-TIMESTAMP/，可随时回滚
• 同步 3 个 SQLite 文件（.db / .db-wal / .db-shm）

• node_modules/ — 服务器独立安装
• data/ — 数据库文件（保留服务器生产数据）
• .env — 环境变量（各环境独立配置）
• .git/、.claude/、deploy.log — 本地专用
• design/、*.command、*.md 文档文件

需要管理员先将您的邮箱添加到用户白名单（管理后台 → 用户管理 → 新增用户）。

检查网络是否能访问 Google 服务。如在境内网络中可尝试开启代理，或使用开发者入口备用登录方式。如仍不行，请联系管理员检查 Google Client ID 配置。

请联系管理员在「用户管理」中重新启用账号。

• 该内容设置为「仅分配」且您不在分配列表中 → 联系管理员添加
• 该内容设置为「仅自己可见」且不是您创建的 → 正常
• 您在「工作台 → 工具设置」中隐藏了该工具 → 取消隐藏即可

这些功能受管理员的「权限设置」控制。若被关闭，对应 Tab 会自动隐藏。请联系管理员开启。

• 检查管理后台 LLM 配置是否已填写正确的 API Key
• 确认选择的提供商（MiniMax/GLM）账户余额充足
• 如 LLM 不可用，系统会自动回退到本地模板输出

需要管理员在「邮件配置」中填写正确的 Gmail OAuth Client ID，并确保已在 Google Cloud Console 中添加对应域名的授权来源。

确认服务器上 Playwright 浏览器依赖已正确安装。如是首次部署，可 SSH 进入服务器运行 docker exec [容器名称] npx playwright install chromium。

• 确认本地与服务器之间 SSH 免密登录已配置
• 查看 deploy.log 获取详细错误信息
• 手动检查：ssh root@[服务器地址] 'docker logs [容器名称] --tail 30'

deploy.sh 会在 DB 变更时自动备份。如需手动回滚，SSH 进入服务器，在 [备份目录] 找到对应备份文件，按提示执行恢复命令。