Agent 开发计划及完成状态

TOTP 服务端开发需求

本项目要求使用 Go 语言开发；目前已经建好了的数据表，初始数据表结构，可查看 /docs/sql/database.sql

开发任务

• [x] 制定开发计划，讨论对齐开发需求
• [x] 在 /service 目录中创建 go 项目开发目录，并将目录说明文档添加到 /docs 目录（见 ./docs/directory.md）
• [x] 开始 API 服务的开发，完成开放 API 功能开发以及管理后台 API 开发（见 ./service）
• [x] 编写开放 API 使用说明文档（含 PHP 示例，见 ./docs/open-api.md）
• [x] 编辑后台管理 API 对接文档（面向另一个 AI/前端对接，见 ./docs/admin-api.md）

Console（后台前端）

• [x] 创建迁移/对接计划文档（见 ./docs/console-plan.md）
• [x] 初始化 ./console 工程骨架（Vue3 + Vite + TS + Pinia + ElementPlus + Tailwind）
• [x] dev/prod /api 路径策略落地：Vite proxy + Nginx 示例配置（见 ./nginx/console.conf.example）
• [ ] 对接页面完善与样式打磨（按最小页面集逐步完善交互）

增量需求（2026-01-27）

围绕后台 console 落地，补齐“用户管理”能力：

• [x] 后台用户列表：同时展示 group=system 和 group=project 用户（分页 page/page_size）
• [x] 后台用户详情：查询单个用户（用于详情页/编辑回显）
• [x] 后台用户编辑：
  • system 用户允许修改：mobile / display_name / status
  • project 用户允许修改：mobile / display_name（不允许修改 status）
• [x] “禁用立即生效”：system 管理员被禁用后，现有 JWT 立即失效（后端每次请求查库校验）
• [x] 更新后台 API 文档以覆盖以上接口与规则（见 ./docs/admin-api.md）

增量需求（2026-01-27 第二轮）

围绕“后台账号安全 + project 用户后台能力 + 列表体验”，进行以下增量：

• [x] 后台账号 2FA（不引入 pending 状态）

  • [x] 增加 ADMIN_TOTP_ISSUER 配置项（用于后台账号 otpauth issuer）
  • [x] Me：绑定 2FA（二维码 + 验证码确认后生效）
  • [x] Me：解绑 2FA（必须输入 code；解绑语义为 is_active=0，保留 secret 可复启）
  • [x] 登录：若账号已启用 2FA，则强制二次校验（内存 challenge store，单机）

• [x] 列表分页统一

  • [x] 所有列表 API 统一返回：data 数组 + paging 对象（page/page_size/total）
  • [x] Audit Logs 列表增加 page/page_size 并按分页返回
  • [x] Projects 列表增加 page/page_size 并按分页返回

• [x] Projects 列表增强与启停

  • [x] Projects 列表增加所属用户 display_name
  • [x] Projects：Disable 增加弹窗确认（前端）
  • [x] Projects：支持重新开启（后端增加 enable + 前端对接）

• [x] Project user 登录与权限收敛

  • [x] 放开 project user 登录后台
  • [x] project user 只能看“自己账号下创建的 projects”及其关联数据（audit / identifiers）

• [x] 用户管理规则调整

  • [x] system 用户编辑 project user 时允许修改 status

• [x] Project User Identifiers 列表

  • [x] 新增 identifiers 列表：关联 project_user_identifiers + project_user_credentials
  • [x] 返回 identifiers 全字段 + credentials 的 is_active/last_used_at/created_at
  • [x] 支持过滤：project_id/email/mobile/is_active + 分页
  • [x] project user 仅可查看自己 projects 的 identifiers

增量需求（2026-01-27 第三轮）

围绕“open API 访问可观测性 + 运维便利”，增加 API 访问日志列表与自动清理：

• [x] Admin API：open API 访问日志列表

  • [x] 新增：GET /admin/v1/api_call/logs（仅 /open/v1/* 调用）
  • [x] 支持分页：page/page_size（与 audit logs 对齐）
  • [x] 支持过滤：project_id/api_key/status_code/method/path/ip/since/until
  • [x] 权限边界：system 全看；project 仅看自己名下 projects

• [x] 数据保留：保留最近 30 天（服务内 ticker 清理）

  • [x] 配置项（环境变量）：
    • API_CALL_LOG_RETENTION_DAYS（默认 30）
    • API_CALL_LOG_CLEANUP_INTERVAL（默认 1h，Go duration，例如 10m/1h/24h）
    • API_CALL_LOG_CLEANUP_BATCH_SIZE（默认 2000）
  • [x] 单实例部署：启动后先清理一轮，再按 interval 周期清理

• [x] SQL：补索引

  • [x] 增量脚本：docs/sql/migrations/20260127_add_api_call_logs_indexes.sql
  • [x] 全量脚本同步更新：docs/sql/database.sql

增量需求（2026-01-27 第四轮）

围绕“后台账号信息 + 修改/重置密码 + 强制改密”，增加以下能力：

• [x] Me：返回 email/display_name/mobile/must_change_password
• [x] Me：支持修改自己的密码（PATCH /admin/v1/me/password）
  • 密码规则：长度 ≥ 6，且必须同时包含字母与数字
  • 修改成功后更新 password_changed_at，使旧 token 失效
• [x] 用户管理：system 管理员重置用户密码（POST /admin/v1/users/{id}/reset_password）
  • 必须输入管理员自己的 TOTP code
  • 返回一次性展示的临时密码（有效期 24 小时）
  • 置 must_change_password=1，并更新 password_changed_at
• [x] 中间件：强制改密（HTTP 403 + code=MUST_CHANGE_PASSWORD）
• [x] 文档同步更新：docs/admin-api.md
• [x] SQL：新增字段与索引（迁移脚本：docs/sql/migrations/20260127_add_user_password_policies.sql；全量脚本同步 docs/sql/database.sql）

增量需求（2026-01-28 第五轮）

围绕“Dashboard 监控（角色隔离）+ ECharts 可视化”，增加以下能力：

• [x] Admin API：open API 调用统计（Dashboard 数据源）

  • [x] 新增：GET /admin/v1/api_call/stats/summary
    • 支持 since/until（RFC3339；默认最近 24h）
    • 支持 project_id（可选）
  • [x] 新增：GET /admin/v1/api_call/stats/timeseries
    • 支持 since/until（RFC3339；默认最近 24h）
    • 支持 bucket（默认 5m；allowlist：1m|5m|15m|1h|24h）
    • 支持 project_id（可选）
  • [x] 新增：GET /admin/v1/api_call/stats/by_project
    • 支持 since/until（RFC3339；默认最近 24h）
    • 支持 limit（默认 10；最大 50）
  • [x] 新增：GET /admin/v1/api_call/stats/by_endpoint
    • 由于聚合成本高，要求 project_id（必填）
    • 支持 since/until、limit（默认 10；最大 50）

• [x] 权限边界（后端强制）

  • [x] system：可查询全量统计；可选 project_id 过滤
  • [x] project：仅可查询自己名下 projects 的统计（通过 JOIN projects + user_id 收敛范围）

• [x] 文档同步更新

  • [x] docs/admin-api.md 补齐 /admin/v1/api_call/stats/* 统计接口说明与示例

• [x] Console：Dashboard 页面 + ECharts

  • [x] 新增 Dashboard 页面（路由 /dashboard）
    • KPI：Total / Success Rate / 2xx / 4xx / 5xx
    • Timeseries：按桶堆叠展示（2xx/4xx/5xx）
    • Top Projects 表格
    • Top Endpoints 表格（要求先选择 project）
  • [x] 引入 ECharts（echarts + vue-echarts）并封装通用组件
  • [x] 暗黑模式兼容：根据 html.dark 切换图表主题/重建

增量需求（2026-01-28 第六轮）

围绕“Project API Key 可读性 + 鉴权错误返回一致性 + 控制台体验”，增加以下能力：

• [x] Project api_key 缩短（仍保证唯一）

  • [x] projects.api_key 改为 17 位：16 位 payload + 1 位校验位
  • [x] 字符集：ABCDEFGHJKMNPQRSTUVWXYZ23456789（不包含 0/1/I/L/O）
  • [x] 服务端比较不区分大小写；可在展示层按 4-4-4-4-1 分组
  • [x] 后端写入时对 uk_api_key 唯一冲突做有限重试

• [x] Open API 鉴权（OpenAuth）错误响应 JSON 化

  • [x] 原先 http.Error 纯文本错误改为 JSON：{"ok":false,"message":"..."}
  • [x] 保留原有状态码与错误文案（401/403/503 等）
  • [x] 校验 api_key 格式与校验位（不兼容旧 key；开发阶段可清库）

• [x] Console 体验优化

  • [x] Projects 列表 API Key 按 4-4-4-4-1 分组展示
  • [x] 创建/重置 secret 弹窗增加醒目提示：api_secret 仅显示一次，遗失只能重置
  • [x] 弹窗仅展示分组后的 api_key，并提供一键复制：Key + Secret（两行 Header）

增量需求（2026-01-28 第七轮）

围绕“控制台内置 API 文档页（暗黑模式 + 语法高亮 + 复制 + TOC）”，增加以下能力：

• [x] Admin API：提供开放接口文档获取接口

  • [x] 新增：GET /admin/v1/docs/open-api，返回 markdown 内容（用于控制台渲染）
  • [x] 文档以 embed 方式打包进服务端二进制（便于单文件部署）
  • [x] 文档同步更新：docs/admin-api.md

• [x] Console：新增“API Document”页面

  • [x] 侧边栏菜单增加入口（/api-document）
  • [x] markdown 渲染为 HTML（禁用 raw HTML，避免注入）
  • [x] code block 支持语法高亮（dark/light 主题跟随 html.dark）
  • [x] code block 支持一键复制
  • [x] 右侧 TOC（标题锚点 + 滚动高亮）

开发/运行注意事项

• Console 依赖安装需要较新 Node 版本（当前 console/package.json 要求 Node >= 20.19.0）。
• 常用命令：
  • 后端：在 service 目录执行 go test ./... / go run ./cmd/server
  • 前端：在 console 目录执行 pnpm install / pnpm dev