# CLAUDE.md — oa.tlyq.ai 统一门户

## 项目概述

oa-ai 是基于 Next.js 的 OA 统一门户，域名 `oa.tlyq.ai`。提供站点聚合导航、LLDAP 统一认证入口、用户管理（创建/删除/角色分配）、密码修改功能。各子站点（assets/issue）各自直连 LLDAP 认证，通过共享 JWT（`tlyq_session` cookie, domain=.tlyq.ai）实现跨站点免登录。

---

## 快速参考

| 属性 | 值 |
|------|-----|
| 站点域名 | `oa.tlyq.ai` |
| 服务器 | txjp（IP: 43.133.38.210） |
| 代码路径 | `/root/docker/oa-ai/` |
| 本地端口 | 6179 |
| 容器名 | `oa-ai` |
| 默认账号 | `admin` / `admin123`（LLDAP 统一管理） |

### 常用命令

```bash
npm run dev          # 本地开发（端口 6179）
npm run build        # 生产构建
```

---

## 关键文件

| 文件 | 职责 |
|------|------|
| `src/middleware.ts` | 全局路由守卫：检查 `tlyq_session` cookie，未认证跳转 /login |
| `src/lib/jwt.ts` | 共享 JWT 签发/验证（HS256，与 assets/issue 共用密钥和格式） |
| `src/lib/ldap.ts` | LLDAP 认证（ldapAuth）+ 密码修改（ldapChangePassword）+ 用户存在性检查 |
| `src/lib/email.ts` | 邮件发送（nodemailer，163 企业邮箱，创建用户时发送凭证） |
| `src/app/page.tsx` | 门户首页：站点卡片导航（核心系统 + 其他站点） |
| `src/app/login/page.tsx` | 登录页（LLDAP 认证） |
| `src/app/profile/page.tsx` | 个人信息页（账户信息 + 修改密码） |
| `src/app/admin/create-user/page.tsx` | 用户管理页（创建/删除/角色管理，仅 admin 可见） |
| `src/app/api/auth/login/route.ts` | 登录 API（OA 仅 LLDAP 认证，无本地 DB） |
| `src/app/api/auth/logout/route.ts` | 退出 API（清除 tlyq_session） |
| `src/app/api/auth/change-password/route.ts` | 修改密码（docker exec 调 lldap_set_password） |
| `src/app/api/admin/create-user/route.ts` | 创建用户（SQLite 写 LLDAP + 自动同步站点 + 角色设置） |
| `src/app/api/admin/users/route.ts` | 用户列表/删除（GET/DELETE） |
| `src/app/api/admin/user-roles/route.ts` | 角色查询/修改（GET/PUT） |
| `src/components/ThemeToggle.tsx` | 深色/浅色主题切换按钮 |
| `src/app/profile/change-password-form.tsx` | 修改密码客户端组件 |
| `src/app/admin/create-user/role-manager.tsx` | 角色管理组件（待保存机制 + 批量提交） |

---

## 认证机制

OA 本身**不存储用户数据**（无本地 users 表），纯 LLDAP 认证：

1. 用户登录 → LDAP bind 验证 → 签发 `tlyq_session` JWT（7 天）
2. 中间件检查 `tlyq_session` → 有效则设置 `session` cookie → 放行
3. 退出清除 `tlyq_session`

跨站点共享：assets/issue 各自中间件优先检查 `tlyq_session`，有效则免登录。

---

## 环境配置

### 本地与云端差异

| 环境变量 | 本地开发 | 云服务器（txjp） |
|---------|---------|----------------|
| `LDAP_URL` | `ldap://localhost:3890` | `ldap://lldap:3890` |
| `LDAP_BASE_DN` | `dc=tlyq,dc=ai` | 同 |
| `LDAP_ADMIN_DN` | `uid=admin,ou=people,dc=tlyq,dc=ai` | 同 |
| `LDAP_ADMIN_PASS` | `admin123` | LLDAP admin 密码 |
| `JWT_SECRET` | `dev-secret-key-local` | 强随机值（与 assets/issue 相同） |
| `COOKIE_DOMAIN` | `""`（空） | `.tlyq.ai` |
| `SMTP_HOST` | `smtphz.qiye.163.com` | 163 企业邮箱 |
| `SMTP_PORT` | `465` | SSL 端口 |
| `SMTP_USER` | `gxp@qx002575.com` | 发件邮箱 |
| `SMTP_PASS` | 见 .env | 邮箱密码 |
| `SMTP_FROM` | `gxp@qx002575.com` | 发件人地址 |

### `.env` 示例

```bash
LDAP_URL=ldap://localhost:3890
LDAP_BASE_DN=dc=tlyq,dc=ai
LDAP_ADMIN_DN=uid=admin,ou=people,dc=tlyq,dc=ai
LDAP_ADMIN_PASS=admin123
JWT_SECRET=dev-secret-key-local
COOKIE_DOMAIN=
NODE_ENV=development
SMTP_HOST=smtphz.qiye.163.com
SMTP_PORT=465
SMTP_USER=gxp@qx002575.com
SMTP_PASS=
SMTP_FROM=gxp@qx002575.com
```

---

## Docker 部署

```
txjp 服务器
├── oa-ai（容器）                 ← Next.js standalone，监听 3000
├── nginx-ai                      ← 反向代理 oa.tlyq.ai → oa-ai:3000
└── webnet（external）            ← 共享网络
```

生产环境需要 OA 容器能访问 Docker socket（`/var/run/docker.sock`）以执行 `docker exec lldap` 修改密码和创建用户。

---

## 主题切换

支持深色/浅色双主题：
- `layout.tsx` 注入 `<script>` 读取 localStorage/系统偏好设置 `dark` class
- CSS 变量 `var(--bg)`、`var(--text)` 等响应主题变化
- `ThemeToggle` 组件：`document.documentElement.classList.toggle('dark')` + localStorage 持久化
- 配色对齐 assets/issue（slate/blue）

---

## 站点 URL 规则

源码中站点跳转 URL 均使用 localhost，部署时 `deploy-ai.sh` 通过 `sed` 自动替换为生产域名。

---

## 开发规范

- **新增页面**：在 `src/app/` 下创建，中间件自动检查认证
- **API 路由**：`/api/auth/` 公开，`/api/admin/` 需 admin 权限
- **admin 校验**：`verifySharedJwt(token).username === 'admin'`

---

## 故障排查

### OA 502 Bad Gateway

**常见原因**：nginx DNS 缓存旧 IP。OA 容器重启后 IP 变化，nginx 仍向旧 IP 发送请求。

**解决**：
```bash
docker restart nginx-ai
```

### 用户管理/角色管理一直加载

**原因**：OA 容器未挂载 assets/issue 的 SQLite 数据库文件，或 LLDAP 容器缺少 `sqlite3`。

**检查**：
```bash
docker exec oa-ai ls /data/other-sites/assets/   # 应有 assets.db, assets.db-wal, assets.db-shm
docker exec oa-ai ls /data/other-sites/issue/    # 应有 issue.db, issue.db-wal, issue.db-shm
docker exec lldap which sqlite3                   # 应有 /usr/bin/sqlite3
```

**LLDAP 容器 sqlite3 安装**（每次容器重建后需重新安装）：
```bash
docker exec lldap apk add --no-cache sqlite
```

### 生产部署关键点

- **Docker socket**：OA 需 `/var/run/docker.sock` 挂载（用于 `docker exec lldap` 创建用户和改密）
- **数据库卷**：OA 需挂载 assets/issue 的 Docker volume **整个数据目录**（非单个文件），确保 SQLite WAL 文件（`.db-wal`/`.db-shm`）共享，否则权限管理页面无法实时反映子站点用户变更：
  - `/var/lib/docker/volumes/assets-ai_assets-data/_data` → `/data/other-sites/assets`
  - `/var/lib/docker/volumes/issue-ai_issue-data/_data` → `/data/other-sites/issue`
- **WAL 共享**：OA 容器必须挂载整个目录而非单个 `.db` 文件。挂载单个文件会导致 WAL 文件独立，sqlite3 CLI 读取过期数据。参见 `docker-compose.yml` 中的 volumes 配置
- **JWT 密钥**：三站点必须一致（`JWT_SECRET=oa-shared-jwt-secret-tlyq-2026`）
- **COOKIE_DOMAIN**：生产必须设为 `.tlyq.ai`