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
