# 追光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**
- 重启脚本仅扫描8301-8310范围
- **强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品**
## 服务器连接信息（重要！总是需要）
- **IP地址**: 119.45.242.239
- **登录用户**: ubuntu
- **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证书自动续期)
- **部署目录**: /home/ubuntu/zhuiguang-ai
- **访问地址**: https://www.zhuig.com (HTTP自动跳转HTTPS)
- **数据库**: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
- **Redis**: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
- **工作区/开发目录**: `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`
### ⚠️ 多项目共存服务器（更新/部署铁律）
服务器 119.45.242.239 上**同时运行多个项目**和**多个共享服务**，任何代码更新、部署、运维操作必须严格隔离，绝不能影响其他项目。
#### 当前服务器实际部署清单（2026-06-10 巡检）
| 项目 | 路径 | 占用端口 | 进程 |
|------|------|----------|------|
| **zhuiguang-ai（我们）** | /home/ubuntu/zhuiguang-ai | 8301 (next-server) | Docker: zhuiguang-ai-app + zhuiguang-ai-cron |
| zhuiguang-ai-backup | /home/ubuntu/zhuiguang-ai-backup | — | 静态备份 |
| zhuiguang-quant | /home/ubuntu/zhuiguang-quant | 8701 / 8802 (java) | 独立 java 进程 |
| zhenfang | /home/ubuntu/zhenfang | — | — |
| snowy-fgt | /home/ubuntu/snowy-fgt | 7001 (gunicorn) | 独立 gunicorn |
| agent-system | /home/ubuntu/agent-system | — | — |
| nacos | /home/ubuntu/nacos | 8601 / 8602 (java) | 独立 java 进程 |
#### 共享服务（绝对不能动）
| 服务 | 端口 | 容器名 | 共享给 |
|------|------|--------|--------|
| Redis | 6379 | redis-cache (Docker) | 所有项目 |
| Nacos | 8848 / 9848 | nacos (Docker) | 注册中心 |
| MinIO | 9000 / 9001 | minio (Docker) | 文件存储 |
| nginx | 80 / 443 / 8720 / 8801 | 系统 nginx | 反向代理多域名 |
#### 铁律（更新/部署前必读）
1. **端口锁定 8301-8310**：本项目所有 HTTP/WS 服务只能使用 8301-8310 区间。禁止占用 80/443/8601-8802/8848/9000-9001/6379/7001 等任何其他端口。Docker 容器启动时若发现目标端口被占，**先排查是哪个项目在用**，绝不能 kill 别人的进程。
2. **进程隔离**：禁止 `pkill -f node` / `pkill -f java` / `pkill -f nginx` / `pkill -f docker` 等全局杀进程。重启本项目**只能重启 Docker 容器**（`docker restart zhuiguang-ai-app`）或 8301-8310 端口上的进程。
3. **禁止修改其他项目目录**：`/home/ubuntu/{zhuiguang-quant,zhenfang,snowy-fgt,agent-system,nacos}` 及其子目录**只读**，不要 `cd` 进去 `git pull` / `npm install` / 改文件。
4. **禁止修改共享服务配置**：
- 不动 Redis（6379）—— 别人可能正在用我们的 key 以外的数据
- 不动 Nacos（8848）—— 注册中心是全局的
- 不动 MinIO（9000）—— 文件存储多项目共用
- 不动 nginx 主配置 / sites-enabled 下的其他站点 —— 我们的反代规则放在独立文件，文件名带 `zhuiguang` 前缀
- 不 `docker restart` / `docker stop` / `docker rm` 任何邻居容器（本项目容器名以 `zhuiguang-ai` 开头）
5. **数据库隔离**：阿里云 RDS 上的数据库是本项目专用（`zhuiguang_ai`），但**严禁 `DROP DATABASE` / `TRUNCATE` 全表 / 删 migration 文件**。改 schema 必须 `prisma migrate dev` 生成新 migration 走前向变更。绝不执行任何会清空数据的脚本。
6. **Crontab 隔离**：本项目定时任务已全部迁移到容器内 supercronic 调度（`zhuiguang-ai-cron` 容器），主机 crontab 已清空。**禁止在主机 crontab 中添加本项目定时任务**，所有定时任务通过更新 `crontab.txt` 并重建 cron 容器完成。也禁止 `crontab -r` 清空（可能影响邻居项目）。
7. **磁盘隔离**：`/home/ubuntu/zhuiguang-ai/logs/` 是本项目日志目录；`/home/ubuntu/logs/` 是其他项目的，**不要混淆**。本项目备份只放 `/home/ubuntu/zhuiguang-ai-backup/`。
8. **环境变量隔离**：只读 `/home/ubuntu/zhuiguang-ai/.env`。**不要改 `~/.bashrc` / `/etc/environment` / `/etc/profile`** 等全局环境文件，全局变量可能影响其他项目。
9. **部署前自检清单**（强制）：
- [ ] `docker ps --filter name=zhuiguang-ai` —— 确认当前运行的容器
- [ ] `ss -tlnp | grep :8301` —— 确认 8301 是容器进程
- [ ] `git status` —— 确认本地代码只动本项目文件
- [ ] `npx tsc --noEmit` —— 零错误
- [ ] **不动** `/home/ubuntu/` 下其他项目目录
- **不动** Redis/Nacos/MinIO 容器
- **不动** nginx/sites-enabled 下非 zhuiguang 开头的文件
- **不动** 全局 crontab（本项目已用 supercronic 容器）
10. **部署后自检清单**（强制）：
- [ ] `docker ps` —— zhuiguang-ai-app 和 zhuiguang-ai-cron 状态 healthy
- [ ] `curl -I https://www.zhuig.com` —— 200，且响应时间 < 3s
- [ ] `ss -tlnp | grep :8301` —— 进程为 Docker 容器内 next-server
- [ ] `docker logs --tail 20 zhuiguang-ai-app` —— 无 ERROR
- [ ] 其他项目（zhuiguang-quant/zhenfang/snowy-fgt/nacos 等）的进程仍在、状态正常
#### 反例（禁止操作）
```bash
# ❌ 禁止 —— 全局杀进程
pkill -f node
pkill -f java
kill -9 $(pgrep node)
systemctl restart nginx
# ❌ 禁止 —— 改其他项目
cd /home/ubuntu/zhuiguang-quant && git pull
rm -rf /home/ubuntu/zhenfang
docker restart redis-cache
docker stop nacos
vi /etc/nginx/nginx.conf
crontab -r
# ❌ 禁止 —— 改共享服务
redis-cli FLUSHALL
mysql -e "DROP DATABASE ..."
```
#### 正例（本项目更新/部署的标准做法）
```bash
# ✅ 只动本项目
cd /home/ubuntu/zhuiguang-ai
git pull
docker build -t zhuiguang-ai:latest .
docker stop zhuiguang-ai-app zhuiguang-ai-cron
docker rm zhuiguang-ai-app zhuiguang-ai-cron
# 然后重新 docker run（参考 docker-compose.yml 或 CONTAINERIZATION.md）
# ✅ 查看状态时不漏看其他项目
docker ps --filter name=zhuiguang-ai # 看本项目容器状态
ss -tlnp | grep -E ':(8301|8601|8701|8802)' # 看我们的端口 + 邻居项目的端口
# ✅ 日志查看
docker logs --tail 50 zhuiguang-ai-app # APP 容器日志
docker logs --tail 50 zhuiguang-ai-cron # Cron 容器日志
```
## 技术栈
- Next.js 14 (App Router) + TypeScript
- Tailwind CSS + shadcn/ui
- Prisma 7.8 + MySQL (阿里云RDS)
- NextAuth.js v4 (Credentials Provider)
- DeepSeek API (deepseek-v4-pro) — 用于技能五维评测生成（服务端脚本调用）
## 代码风格
- 不添加注释（除非明确要求）
- 使用中文作为UI文案和提示词语言
- TypeScript严格模式，零编译错误
- 组件使用 `"use client"` 标记客户端组件
- 路径别名: `@/*` → `./src/*`
- **禁止在代码中硬编码任何AI API Key**
- **禁止在代码中调用任何外部AI API（DeepSeek、OpenAI等）** — 前台/后台页面代码中禁止调用；服务端脚本(scripts/)中允许通过环境变量调用DeepSeek API和GitHub API
- 所有发现/导入功能通过页面提示词+JSON粘贴方式完成，不调用外部接口
## 构建与检查
- 修改代码后必须运行 `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`)，禁止使用原生 `![]()
` 标签
- LazyImage 特性:
- 基于 next/image 的懒加载包装器
- 内置骨架屏加载状态（Skeleton loading state）
- 错误回退占位图（Error fallback）
- 支持 `referrerPolicy` 属性（用于跨域图片场景）
- 支持 `width`/`height` 或 `fill` 模式
- 用法示例:
```tsx
import LazyImage from "@/components/ui/LazyImage";
// 固定尺寸
// 响应式
// 跨域图片
```
- 必须提供有意义的 `alt` 文本
- 装饰性图片使用 `alt=""` 配合 `role="presentation"`
## 导航规范（Link vs router.push）
- 所有静态页面内导航必须使用 Next.js `` 组件
- 禁止使用 `