Imported from zhilin1719-hue/sixinmate-private-message-ai (
AGENTS.md). Install upstream withnpx skills add zhilin1719-hue/sixinmate-private-message-ai. Copyright stays with the author.
了得AI-私信聚合 · AI Agent 指南
版本: 1.0.0-beta | 状态: 已交付 | 最后更新: 2026-05-07
本文件是 AI Agent 工作所需的最小上下文规则。详细资料请按需读取docs/下的对应文件。
1. 项目性质
企业级多平台私信与评论聚合 + AI 智能接待 SaaS，覆盖抖音 / 快手 / 小红书 / 视频号 / 企业微信。
规模：113 API / 66 页面 / 122 组件 / 112 表 / 8 个 Drizzle 迁移 / 001 基线 139 条 RLS 策略（pending SQL 合计 195 条 CREATE POLICY）。
核心技术栈：Next.js 16 (App Router, standalone) · React 19 · TypeScript 5 · shadcn/ui · Tailwind 4 · Supabase (Postgres) + Drizzle 0.45 · DeepSeek API · Zod 4 · Pino logger。
2. 必读顺序
| 场景 | 文档 |
|---|---|
| API 列表 / 路由总览 | docs/API_DOCUMENTATION.md |
| 部署 / 故障排查 / FAQ | docs/DEPLOYMENT_GUIDE.md（已合并旧 RUNBOOK） |
| 阿里云专项部署 | docs/DEPLOY_ALIYUN.md |
| 第三方平台与支付凭证 | docs/THIRD_PARTY_INTEGRATION_GUIDE.md |
| 用户操作手册 | docs/USER_MANUAL.md |
| Bug 修复流程 | docs/BUG_FIX_PROCESS.md |
| 交付检查 | docs/DELIVERY_CHECKLIST.md |
| 交付前审查 | docs/DELIVERY_READINESS_REVIEW.md |
| License 清单 | docs/LICENSE_INVENTORY.md |
| 发版说明 | docs/RELEASE_NOTES.md |
| 应急预案 / UAT / 培训 | docs/templates/EMERGENCY_RUNBOOK.md 等 |
3. 目录速览
src/
├── app/
│ ├── api/ 113 个 route.ts，全部使用真实 DB 查询
│ └── (页面 66 个)
├── components/ 122 个组件（53 个 shadcn ui + 69 业务/布局）
├── lib/
│ ├── api-response.ts successResponse / errorResponse / paginatedResponse
│ ├── auth-context.ts getAuthContext / requireAuthContext
│ ├── tenant-scope.ts loadOwnedAccountIds / assertAccountOwnership / ...
│ ├── validations.ts Zod schemas + validateInput
│ ├── security.ts 限流 + 敏感词
│ ├── ssrf-guard.ts Webhook 外呼 SSRF 校验
│ └── ...
├── storage/database/
│ ├── shared/schema.ts 112 个 pgTable 定义
│ └── shared/relations.ts
├── proxy.ts Edge Runtime CSRF + JWT 注入中间件
└── server.ts 自定义 Next.js standalone 入口
drizzle/ 0000~0007 八个迁移
supabase/_pending_migrations/ RLS 等待合入 SQL（含 README）
4. 强制规范（违反会导致回滚）
4.1 包管理 - 仅 pnpm
pnpm add <pkg> # 安装依赖
pnpm install # 装依赖
pnpm build / dev / start禁止 npm install / yarn add。
4.2 API 响应
- 所有 API 返回
{ code, message, data }，使用successResponse(data, message)/errorResponse(code, message, httpStatus?)/paginatedResponse(items, total, page, pageSize)。 - 严禁
NextResponse.json({ success: true, data })旧格式。 - 前端用
isApiSuccess(data)判断（兼容code===0与历史success===true）。 - HTTP 状态码语义化：400 / 401 / 403 / 404 / 429 / 500。
4.3 认证与多租户
- 所有非公开 API 必须调用
requireAuthContext(request)。 - 严禁直接读取
x-user-id头；必须用getAuthContext/requireAuthContext。 - 多租户：除管理员外，每个查询都必须用
loadOwnedAccountIds(auth)+applyAccountScope(query, ownedIds)，或调用assertAccountOwnership(auth, accountId)/assertRecordAccountOwnership(table, id, auth)校验资源归属。
4.4 输入验证
- 核心 API 必须定义 Zod Schema 在
src/lib/validations.ts。 - 使用
validateInput<T>(schema, data)统一入口；Zod 错误信息从result.error.issues取，不是errors。 z.record必须传两个参数：z.record(z.string(), z.unknown())。
4.5 Edge Runtime（src/proxy.ts）
- 仅可用 Web Crypto API（
crypto.subtle）。 - 禁用
crypto、fs、path、Buffer、process.cwd()等 Node 专属 API。
4.6 Hydration
- 严禁在 JSX 渲染逻辑里直接使用
typeof window、Date.now()、Math.random()。 - 动态内容必须
'use client' + useEffect + useState在客户端挂载后渲染。 - 严禁
<p>嵌套<div>；使用metadata替代<head>。
4.7 UI 设计
- 优先使用
src/components/ui/中的 shadcn/ui 组件。 - 颜色用语义变量
bg-background/text-foreground，禁止硬编码 Hex/RGB。 - 圆角用 Tailwind 类（
rounded-md、rounded-lg）。 - 禁止 AI 风格渐变（如
from-blue-500 to-purple-500）。
4.8 数据库字段
- DB 用 snake_case，前端用 camelCase。API 层负责转换：
function mapAccount(row: Record<string, unknown>): PlatformAccount { return { id: row.id as number, userId: row.user_id as number, ... }; }
4.9 注释
- 不要写"narrate code"型注释（"Increment counter" 之类）。
- 仅在解释非显然意图、权衡、约束时加注释。
5. 常用命令
pnpm dev # 开发（端口 PORT/DEPLOY_RUN_PORT）
pnpm build && pnpm start # 生产
pnpm verify:delivery # lint + ts-check + test + audit + build 一键
pnpm lint / pnpm ts-check / pnpm test
pnpm db:migrate # 按 journal 执行 0000-0007
pnpm db:generate # 改 schema 后生成迁移
pnpm db:push # 开发期快速同步
pnpm db:baseline-0000 # db:push 建库后补录基线
pnpm db:apply-unique-settings # 单跑 0001 去重 + 唯一索引
pnpm db:backup / pnpm db:restore # pg_dump / pg_restore
pnpm seed:commercial # 同步订阅 + 积分套餐目录
pnpm encrypt:legacy-settings # 明文凭据转 gcm:6. 关键安全机制
| 机制 | 实现位置 |
|---|---|
| 安全响应头 5 项 | next.config.ts（X-Content-Type-Options / X-Frame-Options / X-XSS-Protection / Referrer-Policy / Permissions-Policy） |
| CSRF 双重验证 | src/proxy.ts Edge Runtime + Web Crypto HMAC-SHA256 |
| API 限流 | src/lib/security.ts（100 次/分钟/IP，内存 Map + 5 分钟清理） |
| 敏感词过滤 | src/lib/security.ts（自动替换为 *，SSE sensitiveWarning 通知） |
| 数据加密 | src/lib/wecom-crypto.ts 等（AES-256-GCM 列加密） |
| RLS | supabase/_pending_migrations/001_enable_rls_policies.sql（待合入） |
| JWT | Access 2h + Refresh 7d + Token Rotation + 重放检测；HS256；JWT_STRICT_CLAIMS=1 强制校验 issuer/audience |
| 暴力破解 | login_attempts 表持久化，5 次失败锁定 15 分钟 |
| ErrorBoundary | src/components/error-boundary.tsx 全局错误边界 |
| SSRF 防护 | src/lib/ssrf-guard.ts，管理后台 Webhook 测试默认禁内网；WEBHOOK_SSRF_ALLOW_LOCAL=1 仅开发期 |
7. scheduled_tasks 多用途
| task_type | reference_id | 用途 |
|---|---|---|
system_settings |
用户 ID | 用户级系统设置（通知 / AI / 平台） |
admin_system_settings |
无 | 管理端全站设置 |
anti_ban_config |
用户 ID | 平台防封配置 |
anti_loss_config |
用户 ID | 防丢失消息配置 |
payload 为 JSONB；平台 AppSecret 等敏感字段使用 AES-256-GCM 加密存储。
8. 数据库迁移
| 迁移文件 | 说明 |
|---|---|
0000_melted_outlaw_kid.sql |
初始全量建表 |
0001_scheduled_tasks_settings_dedupe_unique.sql |
system_settings/admin_system_settings 行去重 + 唯一索引 |
0002_sudden_blue_marvel.sql |
+17 张表（认证 7 表、合规 6 表、财务等）+ 6 个业务联合索引/唯一约束 + 50+ 索引 |
0003_nosy_darkstar.sql |
+5 张外链表（external_links / landing_pages / link_clicks / external_servers / message_external_links） |
0004_great_galactus.sql |
external_servers 扩展字段（priority / weight / failure_count / last_failed_at） |
0005_secret_dazzler.sql |
补齐裂变、分销、代理、自动回复、群聊、消息配额、AI 员工执行记录、bonus_credits 等 schema drift |
0006_condemned_clea.sql |
payment_invoices 发票字段扩展 |
0007_enable_rls_policies.sql |
RLS helper + 139 条基线策略 |
drizzle/meta/_journal.json 中各条目 when 必须单调递增，否则 db:migrate 失败。
9. 关键环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
COZE_SUPABASE_URL / COZE_SUPABASE_ANON_KEY / COZE_SUPABASE_SERVICE_ROLE_KEY |
✅ | Supabase 凭证 |
DATABASE_URL |
✅（迁移/加密脚本） | Postgres 直连 |
JWT_SECRET |
✅ | ≥32 字符强随机 |
CSRF_SECRET |
✅ | 强随机 |
ENCRYPTION_MASTER_KEY |
✅ | AES-256-GCM 主密钥 |
APP_URL / COZE_PROJECT_DOMAIN_DEFAULT |
推荐 | 域名 |
PORT / DEPLOY_RUN_PORT |
可选 | 默认 5000 |
LOG_LEVEL |
可选 | info/warn/error/debug |
JWT_ISSUER / JWT_AUDIENCE / JWT_STRICT_CLAIMS |
可选 | 严格 JWT 校验 |
ALLOW_SEED |
生产禁用 | 为 1 时开放 /api/seed |
WEBHOOK_SSRF_ALLOW_LOCAL |
生产禁用 | Webhook 测试允许内网 |
REDIS_URL |
可选 | 多实例共享状态（未配置走进程内 LRU） |
SMTP_* / SMS_* / ALIPAY_* / WECHAT_PAY_* / WECOM_OAUTH_* |
按需 | 第三方通道 |
完整列表见 .env.example。
10. 上线 / 交付要点
- 生产必须配置
JWT_SECRET/CSRF_SECRET/ENCRYPTION_MASTER_KEY，禁用默认值。 - 生产探活统一走
/api/health。 - 第三方平台凭证（抖音/快手/小红书/视频号/支付宝/微信支付）需客户提供后写入
.env。 - RLS 默认未开启；要求多租户严格隔离时按
supabase/_pending_migrations/顺序合入。 - 部署具备
ENCRYPTION_MASTER_KEY+DATABASE_URL后跑pnpm encrypt:legacy-settings做一次性密文迁移。 - 一键校验：
pnpm verify:delivery（覆盖 lint / ts-check / 87+ 单测 / pnpm audit / build）。
11. 已知不在本次范围
- 真实第三方平台凭证联调（抖音/快手/小红书/视频号/支付宝/微信支付）—— 需客户提供。
- 生产环境部署本身（域名 / HTTPS / 反代 / 生产 DB / APM）—— 仓库仅做演练。
- 大规模重构（Repository 层抽取、AI Chat 拆分等）—— 不在本次窗口内。
12. 速查链接
- 路由总数核验：
find src/app/api -name route.ts \| wc -l→113 - 表数量核验：
grep -c "pgTable(" src/storage/database/shared/schema.ts→112 - RLS 基线策略数：
grep -c "CREATE POLICY" supabase/_pending_migrations/001_enable_rls_policies.sql→139 - pending SQL 策略总数：
grep -h "CREATE POLICY" supabase/_pending_migrations/*.sql \| wc -l→195 - 迁移数：
ls drizzle/0*.sql \| wc -l→8
