startup-plan/技术设计/潜在问题清单.md

# 潜在问题清单

> 逐层审查代码和策略后发现的问题。
> 更新时间：2026-05-12
>
> ✅ = 已决策 / 已解决（但可能尚未在代码中落地）

---

## 🔴 严重（会阻断编译 / 上线 / 安全）

| # | 位置 | 问题 | 后果 |
|---|------|------|------|
| 1 | 后端 13 个 Repository 全部 | 数据只存内存 `Map`，没有调 Prisma 写 MySQL。服务器上已有 MySQL，但代码不走它。 | 服务重启 = 全量数据丢失 |
| 2 | 后端 `infrastructure/queue/queue.service.ts` | 队列是内存数组 `push/shift`，不是 BullMQ，没接 Redis | 队列任务重启丢失，无可靠异步处理 |
| 3 | 后端 3 个 Worker 文件 | 全是空壳（只有 `console.log` + `setInterval`），没有真正消费队列 | 异步任务（AI分析/导入/通知）全部未生效 |
| 4 | 后端 `.gitea/workflows/deploy.yml` | 数据库密码、Redis 密码、JWT Secret、Swagger 密码全部明文硬编码 | 任何人拿到仓库就能访问生产环境 |
| 5 | 后端 `服务器密钥/WangDL.pem` | ~~SSH 密钥已提交到 Git~~ ✅ 已从工作目录删除，移至 `startup-plan/凭据配置/` 并已 gitignore | 密钥泄露风险已消除 |
| 6 | iOS 全部 View 文件 | 自定义 `NavigationLink(destination:label:)` 没有定义，SwiftUI 原生签名不同 | **项目无法编译** |
| 7 | iOS `Core/Network/APIConfig.swift` + `Info.plist` | ✅ `baseURL` 已改为 `https://api.longde.cloud`，`NSAllowsArbitraryLoads` 已移除 | App Store 审核合规 |

---

## 🟠 高危（功能主链路断裂）

| # | 位置 | 问题 | 后果 |
|---|------|------|------|
| 8 | 后端 `auth.service.ts` L154-158 | Apple 登录实际未接入，走 mock（`verifyRealApple` 直接抛异常） | 用户认证链无效（虽账号刚开通，但代码需要准备好） |
| 9 | 后端 `modules/` 大部分 Controller | 10 个 Controller 没有 `@UseGuards(JwtAuthGuard)`，或使用 `user?.id \|\| 'anonymous'` 降级 | 未登录可调用知识库/AI分析/学习记录等接口 |
| 10 | 后端 `ai-analysis.service.ts` L61-78 | `.then().catch()` 未 await，fire-and-forget | AI 分析异常静默丢失 |
| 11 | iOS `Core/Network/APIClient.swift` L11 | Token 只存 `actor` 内 `var token: String?`，没写 Keychain | 杀进程重启就要重新登录 |
| 12 | iOS 全部 View | `APIService` 有 8 个 Service 类（20+ 方法），但没有任何 View 调用它们。所有数据硬编码。 | 前后端完全断开 |
| 13 | iOS Tests 全部 4 个文件 | 引用的 `ReviewPlanViewModel`、`StudyHomeViewModel`、`AIChatViewModel`、`FileCache` 全不存在 | 测试无法编译 |
| 14 | 官网 `WaitlistForm.astro` L83-95 | 提交事件只 `e.preventDefault()` 然后显示假成功，没有 `fetch()` | 等待名单完全无效 |
| 15 | 官网 `support.astro` | 反馈表单无任何 JS 处理，无 `action`/`method`，提交即刷新丢失 | 支持/反馈功能无效 |

---

## 🟡 中危（体验 / 架构债务）

| # | 位置 | 问题 | 后果 |
|---|------|------|------|
| 16 | iOS 全部 View | 零 ViewModel 分层，所有逻辑写在 View `@State` 里，无 `@StateObject`/`@Published` | 代码不可测试，日后重构极其困难 |
| 17 | iOS 全部 View | 零加载态（Loading）、零错误态（Error）、零空态（Empty） | 用户体验极差，网络出错无提示 |
| 18 | iOS 无任何持久化 | 没有 CoreData/SwiftData/UserDefaults 持久层，无离线缓存 | 断网完全不能用 |
| 19 | iOS `SettingsView` / `LibrarySubpages` | 所有保存/提交按钮的闭包是 `{}` 空的，点了无任何反应 | 设置和创建知识库等全部失效 |
| 20 | iOS `zh-Hans.lproj/Localizable.strings` | 180+ key 已写好，但没有一个 View 用 `NSLocalizedString` | 多语言架构白写了 |
| 21 | 后端 `common/utils/rate-limit.service.ts` | 限流 Service 写好了但没在任何 Module 注册，没在任何 Controller 使用 | 零限流保护 |
| 22 | 后端 `common/interceptors/response.interceptor.ts` | 拦截器写好了但没全局或局部注册 | 响应格式不一致 |
| 23 | 后端 大部分 Controller | `@Body() body: any` 无 DTO class | 无输入校验，恶意 payload 直通 |
| 24 | 后端 `document-import.service.ts` | 用 3 层 `setTimeout` 模拟处理，无真正文件解析 | 资料导入完全无效 |
| 25 | 后端 `infrastructure/storage/` | 只有 `getUploadPath()` 和 `healthCheck()`，没有真正的读写/上传 | 文件上传完全无效 |
| 26 | 后端 `main.ts` | 无 `enableShutdownHooks()` | SIGTERM 时请求被硬断，连接不排空 |
| 27 | 后端 ID 类型 | Prisma schema 用 `BigInt`，所有代码生成 `string` ID | 接 Prisma 时全部 ID 逻辑要重写 |
| 28 | 后端 所有 list 接口 | `PaginationDto` 写好了但无接口使用 | 无分页，数据量大时撑不住 |
| 29 | 后端 `prisma/migrations/` | 无 migration 目录 | 数据库 schema 变更无版本管理 |

---

## 🟢 低危（清理 / 微调）

| # | 位置 | 问题 |
|---|------|------|
| 30 | 官网 `src/styles/global.css` | 7 个 CSS 自定义属性（`--color-accent`、`--color-text` 等）未定义，Tailwind v4 变量名不一致 |
| 31 | 官网品牌名 | "知习 AI" 和 "龙德AI学习" 两个名字混用，约各占一半页面 |
| 32 | 官网 `sitemap.xml.astro` | 缺少 `/product` 和 `/philosophy`，`lastmod` 生成时间全是"今天" |
| 33 | 官网 `BaseLayout.astro` L12 | `og-default.png` 不存在，所有页面社交分享无缩略图 |
| 34 | 官网 `robots.txt` | 写死 `Sitemap: http://localhost:4321/sitemap.xml` |
| 35 | 官网 `support.astro` / `privacy.astro` | 绕过 `BaseLayout`，缺失所有 SEO meta 标签 |
| 36 | 后端 Swagger | 生产环境 `ENABLE_SWAGGER=true`，且密码硬编码在 deploy.yml |
| 37 | 后端 无 `docker-compose.yml` | 文档写了但没创建，本地无法一键起全栈 |
| 38 | 后端 E2E 测试 | `test/app.e2e-spec.ts` 期望 `Hello World!` 但根路径返回的是健康检查 JSON |
| 39 | iOS 无崩溃监控 | 无 Crashlytics / Sentry / 自建监控 |
| 40 | iOS 无推送 | 无 `BGTaskScheduler`，无 Push Notification 注册 |

---

## 📊 统计

| 等级 | 数量 |
|------|------|
| 🔴 严重 | 7 |
| 🟠 高危 | 8 |
| 🟡 中危 | 14 |
| 🟢 低危 | 11 |
|- **合计（技术向）** | **40** |

---

## 🧭 项目方向 / 策略层遗漏（非技术问题）

> 这些是你现有的规划文档中提到但未实质性推进、或根本没被覆盖的问题。

| # | 类别 | 问题 | 现状 | 为什么重要 |
|---|------|------|------|-----------|
| D1 | **方向决策** | 3 个候选方向至今未选定 | `方向验证.md` 列出了公考申论 / AI工具学习 / 前端面试三个方向，评分维度也写了，但没打分没结论 | 代码已经写了 21 个页面 + 13 个后端模块，但还不知道往哪个垂直方向走。按计划"先选方向再做产品"，现在反了 |
| D2 | **竞品分析** | 零竞品拆解 | 文档多次提"做竞品分析表""看竞品差评"，但没有任何竞品文档 | 没有竞品分析就无法定义差异化，也不知道当前方向是否已红海 |
| D3 | **第一个知识库内容** | 没有开始准备内容 | 计划反复强调"只做一个7天路径"，但没有任何内容草稿 | 产品核心价值是 AI + 结构化知识库，AI 链路通了但内容没准备，学什么？ |
| D4 | **范围失控** | 实际代码远超 MVP 计划 | 计划要求 8 个 P0 模块、8-14 页、不做 Worker/导入/通知；实际做了 13 模块、21 页、3 Worker、文档导入骨架 | 每多做一个未验证的模块都是成本，而且在方向没确定前做这些是风险 |
| D5 | **AI 成本模型** | 没算过真实的 AI 调用成本 | 计划提了"成本失控"的警惕，但没有具体数字：每用户每天几次调用、每次多少 token、月成本预估 | 不收钱还好，一旦内测量大或定价，成本算不清就没办法定价，也没办法判断盈亏 |
| D6 | **验证的硬性退出条件** | 没有"什么是验证失败"的定义 | `方向验证.md` 有最低目标（50条原话、10份问卷等），但没有明确时间节点和放弃标准 | 容易陷进"再试试"的循环，没有止损线 |
| D7 | ✅ **定价策略** | ~~`商业化与支付模块.md` 只是目录骨架~~ | 已写入完整定价方案：¥29/月、$9.99/月，免费版+Pro版权益、竞品价格区间、收入测算 | ✅ 已决策，详见 `商业化与支付模块.md` |
| D8 | **季节性风险** | 公考/面试方向有强时间窗口 | 公务员考试有固定报名和考试周期，错过窗口期获客成本急剧上升 | 如果选定公考方向但不卡时间发布，第一波内测可能完全找不到备考用户 |
| D9 | **用户输入意愿风险** | 没提出降低输入门槛的方案 | `Demo与MVP.md` 自己写了"用户不愿意主动输入内容"是最大风险之一，但没有给缓解策略 | 学习闭环的核心是用户写笔记/回答，如果用户跳过这一步，整个链条断了 |
| D10 | **内容持续供给** | 知识库由谁维护、更新节奏 | 产品定位是"AI驱动的学习系统"，但内容来源方案停在"合法整理"这四个字上 | 一个 7 天路径学完就没新内容了，用户不回来。没有持续的内容生产计划 |
| D11 | **AI 分析质量的验证标准** | 没有产品侧的 AI 效果验收机制 | AI 分析输出的是掌握度/薄弱点/建议，但没有说"多准确算合格"，谁来验收 | 如果 AI 分析结果用户觉得不靠谱，产品核心价值崩塌。需要真人验证标准 |
| D12 | **Prompt 管理策略** | 没有 Prompt 版本管理和效果追踪 | `BACKEND-PLAN.md` 设计了 prompts/ 目录和 Provider 抽象，但没有 prompt A/B 测试、效果对比、迭代机制 | Prompt 是这个产品的核心资产之一，随缘改会越来越差 |
| D13 | ✅ **品牌定位** | ~~品牌名都不统一~~ | 已决策统一用"知习 AI"（官网代码和页面尚未全部更新） | ✅ 已决策，官网待执行 |
| D14 | **内测用户获取** | 没有用户触达的路径验证 | 计划写了小红书/B站/知乎 + 等待名单，但等待名单在官网上是假的，没有跑过一次真实用户获取 | 方向验证的第一步"看评论区"还没批量执行过 |
| D15 | **上线后运营** | 零运营准备 | 计划有 `运营与客服模块.md` 但只是目录，没有客服响应 SLA、没有内测群管理方案、没有版本发布沟通流程 | TestFlight 内测用户遇到问题找谁？等多久？怎么反馈给你？全没定义 |
| D16 | **隐私合规落空** | 官网隐私政策是用 AI 生成的模板 | `privacy.astro` 内容很长但法律有效性存疑；`App Privacy` 数据声明没准备 | App Store 上架时 Apple 会严格审查隐私声明，模板可能被退回 |

---

## 📊 统计（含方向）

| 等级 | 数量 |
|------|------|
| 🔴 严重（技术） | 7 |
| 🟠 高危（技术） | 8 |
| 🟡 中危（技术） | 14 |
| 🟢 低危（技术） | 11 |
| 🧭 方向/策略 | 14 |
| **合计** | **54** |

---

## 🎯 建议优先修复顺序

```
第 0 批（现在，不写代码）：
  D1   选定一个垂直方向并打分       → 不选方向后面都是浪费
  D2   做 3-5 个竞品拆解            → 知道差异化在哪
  D3   准备第一个 7 天路径的内容     → 没内容验证不了学习闭环
  D4   砍掉 MVP 不需要的模块和页面   → 别再继续膨胀了

第 1 批（技术底线，本周）：
  #6   iOS NavigationLink 编译问题   → 让项目能跑
  #1   Repository 接 Prisma + MySQL → 数据能落库
  #4   CI/CD 密钥脱敏               → 安全底线
  #5   删除或 gitignore WangDL.pem  → 安全底线
  #7   iOS 换 HTTPS                 → App Store 上架要求

第 2 批（功能链路，下周）：
  D5   算清 AI 单用户月成本          → 为定价打底
  #2   Queue 接 BullMQ + Redis      → 异步链路通
  #8   Apple 登录接入               → 认证链路通
  D14  跑一次真实用户获取            → 开始验证方向
  #14  官网 Waitlist 接后端 API     → 等待名单能用
  #12  iOS View 调 APIService       → 前后端打通

第 3 批（内测前）：
  D6   设定验证退出条件和时间节点     → 有止损线
  D9   设计输入降门槛方案            → 解决最大风险
  D11  定 AI 分析质量验收标准        → 产品核心价值要可控
  #9   各 Controller 加 Auth Guard  → 接口安全
  #11  Token 写 Keychain            → 登录持久化
  #16  iOS MVVM 分层                → 代码可维护
  #17  iOS 加载/错误/空态           → 体验完整
  D15  准备内测运营方案             → TestFlight 用户有处可去
  D16  检查隐私政策合规性           → App Store 审核不被拒
```

---

## ✅ 已解决问题

| # | 问题 | 决策 |
|---|------|------|
| D7 | 定价策略空缺 | 免费+单一Pro订阅，中国¥29/月、海外$9.99/月，已写入 `商业化与支付模块.md` |
| D13 | 品牌名不统一 | 统一使用"知习 AI" |