feat: 首次推送到Gitea - 完整项目代码 + 安全加固 + 知识库

.trae/rules/project_rules.md

@@ -1,5 +1,10 @@
 # 追光AI 项目开发规则
 
+> **本文件是 L2 工程标准层**（四层结构索引见 [README.md](README.md)）。其他层：
+> - L0 方法论：[../ai_coding_knowledge.json](../ai_coding_knowledge.json)（AI 编程效率方法库，机器可解析）
+> - L1 协作规则：[ai_agent_rules.md](ai_agent_rules.md)（启动加载）· [ai_collaboration.md](ai_collaboration.md)（Plan-first + 自动记录）
+> - L3 项目事实：[../knowledge_graph.jsonl](../knowledge_graph.jsonl)（知识图谱）· [../knowledge/](../knowledge/)（能力/过程/成果自动记录）
+
 ## 端口规范
 - 应用端口范围: **8301-8310**（预留扩展）
 - 默认端口: **8301**
@@ -9,9 +14,9 @@
 ## 服务器连接信息（重要！总是需要）
 - **IP地址**: 119.45.242.239
 - **登录用户**: ubuntu
-- **SSH密钥**: `C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem`
-- **SSH命令**: `ssh -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" ubuntu@119.45.242.239`
-- **SCP示例**: `scp -i "C:\SGP_KF\ZhuiGuangAI\zhuiguang-ai\Pem\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
+- **SSH密钥**: `C:\SSH\zhuiguang-ai\zg.pem`（2026-10-02 校正；旧值 `E:\0.Center-S2\S890-V3\pem\zg.pem` 已迁移）
+- **SSH命令**: `ssh -i "C:\SSH\zhuiguang-ai\zg.pem" ubuntu@119.45.242.239`
+- **SCP示例**: `scp -i "C:\SSH\zhuiguang-ai\zg.pem" localfile ubuntu@119.45.242.239:/home/ubuntu/zhuiguang-ai/`
 
 ## 服务器与基础设施
 - **域名**: www.zhuig.com (HTTPS，SSL证书自动续期)
@@ -19,8 +24,10 @@
 - **访问地址**: https://www.zhuig.com (HTTP自动跳转HTTPS)
 - **数据库**: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
 - **Redis**: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
-- **本地Git同步目录**: K:\git-repos
-- **开发机**: E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai
+- **工作区/开发目录**: `E:\KF_7\ZhuiGuangAI\zhuiguang-ai`（master，当前唯一活跃工作副本）
+- **本地裸仓镜像（备份入口）**: `K:\git-repos\zhuiguang-ai.git`（bare，2026-10-01 新建。源仓库 remote 需指向它才能持续备份）
+- **已停用副本**: `E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai`（停在 2026-05-23，无 remote）与 `K:\git-repos\zhuiguang-ai`（非裸仓旧工作副本，同样停在 2026-05-23）
+- **远端现状**: 源仓库 remote `local` 仍指向已不存在的 `c:\gitbf\zhuiguang-ai.git`；云端 Gitea（119.45.242.239:3000）无本项目仓库
 - **Docker管理**: `docker ps` / `docker logs zhuiguang-ai-app` / `docker restart zhuiguang-ai-app`
 
 ### ⚠️ 多项目共存服务器（更新/部署铁律）
@@ -142,9 +149,87 @@ docker logs --tail 50 zhuiguang-ai-cron     # Cron 容器日志
 
 ## 构建与检查
 - 修改代码后必须运行 `npx tsc --noEmit` 确认零错误
+- 修改代码后必须运行 `npx vitest run` 确认所有测试通过
 - 本地开发服务器: `npm run dev` (端口8301)
 - 生产构建: `docker build -t zhuiguang-ai:latest .`
 - 部署: `docker stop/rm` 旧容器 → `docker run` 新容器
+- **打包分析**: `ANALYZE=true npm run build` 启用 `@next/bundle-analyzer` 分析包体积
+
+## 测试规范
+- 测试框架: Vitest
+- 配置文件: `vitest.config.ts` + `vitest.setup.ts`
+- 测试目录: `src/__tests__/`，文件名匹配 `*.test.ts`
+- 覆盖率目标: **80%+**（行/分支/函数/语句）
+- tsconfig 需包含 `"types": ["vitest/globals"]` 以启用全局 test/expect/describe
+- 测试类别:
+  - 工具函数单元测试（lib 目录下的纯函数）
+  - API 路由集成测试
+  - 组件渲染测试（配合 @testing-library/react）
+- 禁止跳过测试（`.skip`）除非有明确的 TODO 注释说明原因
+
+## 图片优化规范
+- **强制使用 LazyImage 组件** (`src/components/ui/LazyImage.tsx`)，禁止使用原生 `<img>` 标签
+- LazyImage 特性:
+  - 基于 next/image 的懒加载包装器
+  - 内置骨架屏加载状态（Skeleton loading state）
+  - 错误回退占位图（Error fallback）
+  - 支持 `referrerPolicy` 属性（用于跨域图片场景）
+  - 支持 `width`/`height` 或 `fill` 模式
+- 用法示例:
+  ```tsx
+  import LazyImage from "@/components/ui/LazyImage";
+  // 固定尺寸
+  <LazyImage src={url} alt="描述" width={32} height={32} />
+  // 响应式
+  <LazyImage src={url} alt="描述" fill className="object-cover" />
+  // 跨域图片
+  <LazyImage src={url} alt="描述" width={48} height={48} referrerPolicy="no-referrer" />
+  ```
+- 必须提供有意义的 `alt` 文本
+- 装饰性图片使用 `alt=""` 配合 `role="presentation"`
+
+## 导航规范（Link vs router.push）
+- 所有静态页面内导航必须使用 Next.js `<Link>` 组件
+- 禁止使用 `<button onClick={() => router.push(...)}>` 进行页面跳转
+- 适用场景:
+  - 分页按钮 → `<Link>`
+  - 侧边栏筛选 → `<Link>`（含查询参数）
+  - 面包屑 → `<Link>`
+  - 卡片/列表项 → `<Link>`
+  - "清除筛选"按钮 → `<Link href="/base-path">`
+- 仅外部链接使用 `<a>`（需加 `target="_blank" rel="noopener noreferrer"`）
+
+## API 响应格式规范
+- 列表接口统一使用 `total`（不是 `totalCount`）表示总数
+- 返回格式: `{ data, total, page, pageSize }` 或 `{ success, error }`
+- 前端消费端也同步使用 `total` 字段
+- 已统一接口: `/api/notifications`, `/api/forum/topics`, `/api/comments`, `/api/user/points`
+
+## 并行查询规范
+- 多个独立的 Prisma 查询必须使用 `Promise.all` 并行执行
+- 严禁串行 await 多个无依赖的数据库查询
+```typescript
+// ✅ 正确：并行查询
+const [tool, relatedTools, reviewCount] = await Promise.all([
+  prisma.tool.findUnique({ where: { slug } }),
+  prisma.tool.findMany({ where: { categoryId }, take: 6 }),
+  prisma.review.count({ where: { toolId } }),
+]);
+```
+
+## 无障碍规范（WCAG 2.1）
+- 所有交互元素（div onClick）必须添加 `role` + `aria-*` 属性 + 键盘事件（`onKeyDown`）
+- 搜索输入框必须添加 `aria-label` 属性
+- 装饰性图片添加 `role="presentation"`（不暴露给屏幕阅读器）
+- 根布局必须提供跳过导航链接（Skip-link）
+- 主内容区域使用 `<main id="main-content" tabIndex={-1}>`
+
+## TypeScript 类型规范
+- 禁止使用 `any` 类型
+- 泛型函数使用 `<T>` 约束（参考 `src/lib/cache.ts` 的 `cachedResponse<T>`）
+- API 回调函数使用明确的参数类型
+- 内联对象类型使用 interface 而非匿名类型字面量
+- `src/lib/admin-auth.ts`: 使用 Prisma 严格类型，id 字段统一为 `number`
 
 ## 数据库
 - 云数据库: 阿里云RDS MySQL
@@ -236,16 +321,19 @@ docker logs --tail 50 zhuiguang-ai-cron     # Cron 容器日志
 - OPENAI_API_KEY: OpenAI API Key（Bot活动引擎使用，生成论坛内容）
 
 ## 数字人Bot系统
-- **角色定义文件**: `data/bot-characters.json` — 112个Bot角色定义，所有Bot脚本和前端工具依赖此文件
-- **Bot头像目录**: `public/bot-avatars/` — 程序化SVG头像（112个，~2.5KB/个）
+- **角色定义文件**: `data/bot-characters.json` — 当前 **6 个**「行业情报官」角色（cb_intel / fi_ins_intel / fi_stock_intel / brand_intel / ai_intel / ct_intel）；旧 112 角色「模拟真人互刷」体系已于 2026-09-05 退役
+- **Bot头像目录**: `public/bot-avatars/` — SVG 头像 178 个（含历史角色头像）
+- **会员头像库**: `public/avatars/` — SVG 头像 530 个，会员可在个人中心选择或自定义上传
+- **头像生成脚本**: `scripts/generate-avatar-library.mjs` — 批量生成头像库，支持按性别/主题/数量筛选
+- **头像上传目录**: `public/uploads/avatars/` — 用户自定义上传头像存储
 - **Bot用户标记**: User表中 `isBot: true` 标识Bot用户，与真人的互动数据分别统计
-- **Bot活动时段**: 9:00-23:00每小时运行，15轮/天，论坛内容不干扰深夜用户体验
+- **Bot活动时段**: 旧「模拟真人互刷」体系已停用（`bot-activity` 等任务在 `crontab.txt` 中已注释，2026-09-05 退役）；现由行业情报官引擎承担
 - **Bot数据库**: 12张Bot专用表（BotConfig/BotMemory/BotDailyStat/BotSkill/BotWeeklyReview/BotPersona/BotPersonaVariant/BotPersonaExperiment/BotPersonaAssignment/BotPersonaMetric/BotAdversarialLearning/BotCrossForumAffinity）
 
 ## 定时任务调度系统
 - **后台管理**: `/admin/tasks`（任务中心）、`/admin/tasks/logs`（执行日志）、`/admin/tasks/[taskKey]`（单任务详情+统计）
 - **数据模型**: TaskConfig（任务配置，含enabled/cronExpr/config）、TaskLog（执行历史，含status/duration/result/error）
-- **种子数据**: `scripts/seed-task-configs.mjs` 初始化6个任务配置
+- **种子数据**: `scripts/seed-task-configs.mjs` 初始化 29 个任务配置（含已停用任务，与 `crontab.txt` 存在漂移，见下）
 - **手动触发**: `/admin/tasks` 页支持每个任务运行，也可通过 POST `/api/admin/tasks/run` 触发
 - **API**:
   - `GET/PUT /api/admin/tasks/configs` — 任务配置查询/更新
@@ -253,25 +341,42 @@ docker logs --tail 50 zhuiguang-ai-cron     # Cron 容器日志
   - `POST /api/admin/tasks/run` — 手动触发任务执行
 
 ### 定时任务（Supercronic 容器调度）
-所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`。不再使用主机 crontab + cron-wrapper.sh。
+所有定时任务由 `zhuiguang-ai-cron` 容器内的 supercronic 调度，配置文件 `crontab.txt`（**唯一准绳**）。不再使用主机 crontab。
 
-| 时间 | 任务 | 脚本 | TaskKey | 说明 |
-|------|------|------|---------|------|
-| 01:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars | 更新所有GitHub技能Stars数+日/周/月变化 |
-| 03:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools | 检查网站/Logo可访问性+自动发布合格待审核工具 |
-| 04:00 | Bot技能结晶 | `scripts/bot-skill-crystallize.mjs` | bot-skill-crystallize | 扫过去14天高互动Bot话题→DeepSeek解构共性→入库BotSkill（usageCount驱动调用）；末尾回收7天前成熟技能更新successRate（<30%且使用≥3次自动isActive=false） |
-| 05:00 | Bot亲和度与画像 | `scripts/bot-affinity-update.mjs` | bot-affinity-update | 刷BotCrossForumAffinity（affinity=min(1, samples/total/4)）和BotPersona（avgReplyLength/questionRatio/stanceKeywords/topHumanUsers/topTopicTypes/lastTopicTitles，bot-activity发帖时注入prompt） |
-| 04:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot | 评测2个最热未评测GitHub技能(五维评测) |
-| 05:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills | GitHub搜索≥1000 stars项目→DeepSeek预评测→入库PendingSkill |
-| 06:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools | 36kr/IT之家/开源中国RSS→DeepSeek提取工具→入库PendingTool |
-| 07:30 | AI日报 | `scripts/daily-news.mjs` | daily-news | 多源搜索真实新闻+DeepSeek整理格式→发布日报 |
-| 21:30 | Bot反馈闭环 | `scripts/bot-feedback-loop.mjs` | bot-feedback-loop | 扫描Bot自己帖子下的新回复→存反馈记忆→按概率触发二次回复（仅expert bots，配额high=6/medium=3/low=1） |
-| 周日02:00 | Bot周度复盘 | `scripts/bot-weekly-review.mjs` | bot-weekly-review | 算engagementScore→生成REFLECTION记忆→决定下周配额tier（写入BotWeeklyReview.nextWeekQuota，bot-activity下次跑时动态覆盖） |
-| 08:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community | 将当日日报新闻分发到社区4个板块（AI工具推荐/AI资讯/技术探讨/观点讨论） |
+> ⚠️ supercronic 在容器内按 **UTC** 执行（TZ 环境变量不生效），下表时刻均为 UTC，括号外已换算为北京时间（UTC + 8h）。
+> ⚠️ 2026-10-01 巡检确认：`crontab.txt` 已注释停用大量 Bot/行业情报 AI 任务，但 `scripts/seed-task-configs.mjs` 仍写 `enabled: true`、`scripts/health-check.mjs` 仍把它们列入期望键 —— **三方漂移会产生误告警**，新增/停用任务时必须同步这三处。
+
+**启用中（19 个）**
+
+| UTC | 北京时间 | 任务 | 脚本 | TaskKey |
+|-----|---------|------|------|---------|
+| 0 1 | 09:00 | Task5 更新星值 | `scripts/task5-update-stars.mjs` | task5-update-stars |
+| 0 3 | 11:00 | Task3 工具巡检 | `scripts/task3-check-tools.mjs` | task3-check-tools |
+| 0 4 | 12:00 | Task6 评测热门 | `scripts/task6-review-hot.mjs` | task6-review-hot |
+| 0 4 * * 0 | 周日 12:00 | 工具数据补全 | `scripts/enrich-tool-data.mjs` | enrich-tool-data |
+| 30 4 | 12:30 | 日志清理 | `scripts/cleanup-logs.mjs` | cleanup-logs |
+| 0 5 | 13:00 | Task4 发现技能 | `scripts/daily-discover.mjs` | task4-discover-skills |
+| 0 6 | 14:00 | Task1 发现工具 | `scripts/task1-discover-tools.mjs` | task1-discover-tools |
+| 30 6 | 14:30 | task_log 清理 | `scripts/cleanup-task-logs.mjs` | cleanup-task-logs |
+| 30 7 | 15:30 | AI 日报 | `scripts/daily-news.mjs` | daily-news |
+| 0 8 | 16:00 | Task7 新闻推社区 | `scripts/task7-news-to-community.mjs` | task7-news-to-community |
+| 0 8 1 * * | 每月 1 日 16:00 | 断签保护卡发放 | `scripts/grant-freeze-cards.mjs` | grant-freeze-cards |
+| 30 8 | 16:30 | 任务健康检查 | `scripts/health-check.mjs` | health-check |
+| 0 9 | 17:00 | 通知摘要生成 | `scripts/notification-digest.mjs` | notification-digest |
+| 0 9 * * 1 | 周一 17:00 | 竞品工具数监测 | `scripts/competitor-monitor.mjs` | competitor-monitor |
+| 0 10 | 18:00 | 行业趋势监测 | `scripts/trend-alert.mjs` | trend-alert |
+| 0 10 * * 1 | 周一 18:00 | 周刊生成 | `scripts/newsletter-generate.mjs` | newsletter-generate |
+| 30 10 * * 1 | 周一 18:30 | 每周推荐邮件 | `scripts/weekly-recommend-email.mjs` | weekly-recommend-email |
+| 15 */6 | 每 6 小时 | 点赞计数对账 | `scripts/reconcile-like-counts.mjs` | reconcile-like-counts |
+| 5 23,3,7,11,15 | 每日 7/11/15/19/23 点 | 行业素材采集 | `scripts/industry-thinktank.mjs collect --all` | industry-thinktank |
+
+**已注释停用**：`bot-activity`、`bot-skill-crystallize`、`bot-affinity-update`、`bot-weekly-review`、`bot-feedback-loop`、`bot-adversarial-learning-run`、`bot-persona-experiment-run`、`bot-roundtable`、`industry-thinktank weekly/respond`、`industry-daily daily/respond`
+（原因：2026-09-05 旧 Bot「模拟真人互刷」体系退役；2026-09-26 按要求关闭全部 AI 生成功能，行业情报改为需登录访问）
 
 - 调度配置: `crontab.txt`（supercronic 格式），修改后需重建 cron 容器生效
-- 日志目录: 容器内 `/app/logs/`（挂载到 Docker volume `zhuiguang_ai_bot_logs`）
+- 日志目录: 容器内 `/app/logs/`；实际 Docker 卷名为 `zhuiguang-ai_bot-logs`（旧文档写 `zhuiguang_ai_bot_logs`，已过时）
 - 定时任务脚本从 `scripts/` 目录直接执行，环境变量由容器 entrypoint 注入
+- **新增任务必须同步四处**：`crontab.txt` + `scripts/<task>.mjs` + `scripts/seed-task-configs.mjs` + `scripts/health-check.mjs`
 
 ## AI日报新闻源
 - **36kr** RSS (https://36kr.com/feed) — 国内科技资讯
@@ -300,6 +405,7 @@ docker logs --tail 50 zhuiguang-ai-cron     # Cron 容器日志
 - 敏感信息（密钥、密码、Token）必须使用环境变量，禁止硬编码
 - `.env` 文件已被加入 `.gitignore`，仅 `.env.example` 模板可提交
 - HTTP 响应必须包含安全头：CSP、HSTS、X-Content-Type-Options、X-Frame-Options
+- CSP 的 `script-src` 必须包含 `'unsafe-inline'`（Next.js App Router 水合依赖内联 `self.__next_f` 脚本），禁止 `'unsafe-eval'`；详见 workspace 规则 7.1
 - 文件上传/下载必须限制大小（最大 5MB）和类型，SVG 内容需消毒 script/iframe/on-event 标签
 - Logo 文件名使用 SHA256 哈希（不使用 MD5）
 - VIP 用户不能访问管理后台（/admin/* 和 /api/admin/*）
@@ -318,8 +424,10 @@ docker logs --tail 50 zhuiguang-ai-cron     # Cron 容器日志
   - 修改项目架构/技术栈/部署配置 → 更新 `追光AI` 或对应 `Module` 实体
   - 新增/修改实体间关系 → 更新 Knowledge Graph 关系
 - **同步时机**：在代码修改完成并通过检查后、提交代码前执行同步
-- **同步方法**：使用 `mcp_Knowledge_Graph_Memory_create_entities`（新增实体）、`mcp_Knowledge_Graph_Memory_add_observations`（追加观察）、`mcp_Knowledge_Graph_Memory_update_entities`（更新实体）、`mcp_Knowledge_Graph_Memory_create_relations`（新增关系）、`mcp_Knowledge_Graph_Memory_delete_entities`/`delete_relations`/`delete_observations`（删除）
-- **查询优先**：在开始任何开发任务前，先通过 `mcp_Knowledge_Graph_Memory_search_nodes` 或 `mcp_Knowledge_Graph_Memory_open_nodes` 查询图谱，利用已有知识加速开发
+- **图谱存储**：`.trae/knowledge_graph.jsonl`（MCP 源文件，JSONL，一行一实体/关系）；`.trae/knowledge_graph.json` 为渲染版（`project` / `version` / `updated_at` / `entities` / `relations`）
+- **MCP 配置**：`.trae/mcp.json` 注册 `Knowledge Graph Memory` 服务（`npx -y @itseasy21/mcp-knowledge-graph`，`MEMORY_FILE_PATH=.trae/knowledge_graph.jsonl`）
+- **同步方法**：优先使用 `create_entities` / `add_observations` / `update_entities` / `create_relations` / `delete_entities` 等工具；若 MCP 未挂载，直接维护 `.trae/knowledge_graph.jsonl`
+- **查询优先**：在开始任何开发任务前，先通过 `search_nodes` / `open_nodes` 查询图谱，利用已有知识加速开发
 
 ### 7. 可靠性原则
 - 所有外部 API 调用（GitHub、DeepSeek 等）必须设置超时和重试