jackyu66gitandCursor
89756f65b4
落地输入合规、探索题库、报告日/时辰刷新、账号头像、OEJTS 量表，并补齐 H5 埋点与 Admin 漏斗；同步 ESS 工件、切至自建 Git、清理 GitHub Actions。 Co-authored-by: Cursor <cursoragent@cursor.com>
185 lines
5.2 KiB
Markdown
185 lines
5.2 KiB
Markdown
# Feature Spec: AI 成长助手（问答）
|
||
|
||
> Status: `Active` · Map: `§3 问答 [P1]` · Phase: `P1`
|
||
> 规范：[../feature-design.md](../feature-design.md)
|
||
|
||
---
|
||
|
||
## 1. 功能定义
|
||
|
||
| 字段 | 内容 |
|
||
|---|---|
|
||
| Name | AI 成长助手 |
|
||
| Purpose | 结合个人档案，用对话帮助认识自己、理解关系、整理情绪与生活节奏 |
|
||
| Business Goal | 战略中心 Tab 留存；配额驱动会员 |
|
||
|
||
| In | Out |
|
||
|---|---|
|
||
| 挂 profile 的多轮对话；场景入口 | 占卜/运势/预测未来 |
|
||
| DeepSeek（可配）+ 规则引擎降级 | 医疗诊断 |
|
||
| 免费次数 + 额度包（ask_pack）+ 会员配额 | 无档案空聊（禁止） |
|
||
|
||
---
|
||
|
||
## 2. 用户价值
|
||
|
||
1. **为何需要：** 看完画像仍有具体情境问题。
|
||
2. **完成后获得：** 结合档案的结构化建议与可执行小步骤。
|
||
3. **为何付费：** 免费次数用尽后可购买问答额度包，或开通成长会员获得更多回复。
|
||
|
||
---
|
||
|
||
## 3. 用户角色
|
||
|
||
| Actor | 能力 |
|
||
|---|---|
|
||
| Visitor | 有档案则可问；受配额限制 |
|
||
| VIP | 额外 Ask 配额 |
|
||
| 无档案 | 仅引导建档，不可消耗成功回复 |
|
||
|
||
---
|
||
|
||
## 4. 用户流程
|
||
|
||
```text
|
||
进入 /ask
|
||
↓
|
||
无档案？ → Empty 引导首页/档案
|
||
↓
|
||
选择档案（我 / TA）+ 可选场景
|
||
↓
|
||
输入问题 → 检查配额
|
||
├─ 耗尽 → 引导购买额度包 / 成长会员（mock 支付后立刻加次）
|
||
└─ 有余 → 创建/续 thread → assistant **SSE 流式**回复（delta → done）
|
||
↓
|
||
DeepSeek 失败/无 key → 规则引擎降级（仍按字流式输出）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 页面设计
|
||
|
||
| 路由 | 页面 |
|
||
|---|---|
|
||
| `/ask` | AskPage（ChatThread） |
|
||
|
||
```text
|
||
/ask
|
||
├── 愈心 AI / 顾问 Tab
|
||
├── 顾问列表 → 顾问专属对话（?advisor=key · 顶栏返回回列表）
|
||
├── Empty（无档案）
|
||
├── Loading（发送中）
|
||
├── Normal（历史 + 输入）
|
||
├── Error（发送失败可重试）
|
||
└── Quota Exhausted（额度包 + 会员）
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 页面状态规范
|
||
|
||
| 状态 | UI |
|
||
|---|---|
|
||
| Empty | 无档案引导 |
|
||
| Loading | 发送中禁用重复点 |
|
||
| Error | 失败 + 重试 |
|
||
| Normal | 消息列表 |
|
||
| Quota | 明确耗尽文案 + 额度包购买 + `/membership` |
|
||
|
||
---
|
||
|
||
## 7. Business Rules
|
||
|
||
| ID | Rule |
|
||
|---|---|
|
||
| R1 | 每条用户消息必须绑定 `profile_id`（self 或 other） |
|
||
| R2 | 免费回复次数有上限（实现：如 3）；可购 `ask_pack` 加次；会员另计配额 |
|
||
| R3 | 配额耗尽返回明确业务错误，不生成付费假回复；引导购买额度或会员 |
|
||
| R7 | 扣次顺序：会员配额 → 已购额度包 → 免费额度（非会员）；购买额度不解锁报告深度版 |
|
||
| R4 | LLM 可选；失败降级规则引擎，仍须 lexicon 安全 |
|
||
| R5 | 禁止占卜/算命/吉凶恐吓/医疗诊断；可用愈心解码·星座·人格匹配等探索向用语 |
|
||
| R6 | 回复宜短（约 80–160 字）：回应当下 → 1 条档案洞察 → 1–2 条可执行建议；system prompt 须对齐 lexicon 与产品定位 |
|
||
|
||
---
|
||
|
||
## 8. 数据模型影响
|
||
|
||
| 表 | 备注 |
|
||
|---|---|
|
||
| `ask_threads` | user_id, profile_id |
|
||
| `ask_messages` | role, content |
|
||
| `ask_quotas` / 等价 | 余量 |
|
||
| `users.ask_paid_quota_left` | 已购额度包余量 |
|
||
|
||
---
|
||
|
||
## 9. API 需求
|
||
|
||
| Method | Path | 意图 |
|
||
|---|---|---|
|
||
| GET | `/api/v1/ask/quota` | 余量 |
|
||
| POST | `/api/v1/ask/threads` | 创建线程（profile_id, scene?） |
|
||
| POST | `/api/v1/ask/threads/{id}/messages` | 发消息拿回复（默认 JSON） |
|
||
| POST | `/api/v1/ask/threads/{id}/messages?stream=1` | SSE：`meta` / `delta` / `done` / `error` |
|
||
| DELETE | `/api/v1/ask/threads/{id}` | 清空该会话（软删除） |
|
||
| POST | `/api/v1/orders` kind=`ask_pack` | 购买额度包（plan: pack10/pack30/pack100） |
|
||
| POST | `/api/v1/orders/{id}/pay-mock` | 支付后增加 `ask_paid_quota_left` |
|
||
|
||
---
|
||
|
||
## 10. 权限设计
|
||
|
||
| 能力 | 无档案 | 有配额 | 配额耗尽 | VIP 有配额 |
|
||
|---|---|---|---|---|
|
||
| 提问 | ✗ | ✓ | ✗ | ✓ |
|
||
|
||
---
|
||
|
||
## 11. 埋点
|
||
|
||
| Event | 触发 |
|
||
|---|---|
|
||
| `ask_opened` | 进入页 |
|
||
| `ask_message_sent` | 发送 |
|
||
| `ask_reply_received` | 成功回复 |
|
||
| `ask_quota_exhausted` | 耗尽 |
|
||
| `ask_fallback_rule` | 走规则引擎 |
|
||
|
||
---
|
||
|
||
## 12. 测试验收标准
|
||
|
||
**Given** 有 Self 档案与配额
|
||
**When** 发送问题
|
||
**Then** 返回助手消息且含免责；配额减一
|
||
|
||
**Given** 配额为 0
|
||
**When** 再发送
|
||
**Then** 业务错误引导购买额度/会员，无助手胡编
|
||
|
||
**Given** 免费额度耗尽
|
||
**When** pay-mock `ask_pack` pack10
|
||
**Then** GET `/ask/quota` remaining ≥ 10，可继续提问
|
||
|
||
**Given** 无 DeepSeek key
|
||
**When** 提问
|
||
**Then** 规则引擎仍给出档案相关回复
|
||
|
||
---
|
||
|
||
## 13. AI 开发前检查
|
||
|
||
- [x] Spec 齐全 · map · lexicon · OpenAPI · 可测
|
||
|
||
---
|
||
|
||
## 14. Implementation Notes
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Packages | `service/ask` · `internal/ask` · `internal/llm/deepseek` · `AskPage` |
|
||
| Config | `config.local.yaml` deepseek.* |
|
||
| Gaps | 长期记忆 P3；顾问预约仅占位；埋点未接 |
|
||
| Tests | ask reply L1；集成 thread；AskPage.spec |
|
||
| Process Review | 2026-08-02 [P1-PROCESS-REVIEW](P1-PROCESS-REVIEW.md) · 设计闭合 · 实现 PASS · 测试 PASS |
|