167 lines
8.2 KiB
Markdown
167 lines
8.2 KiB
Markdown
# 取名小程序产品规格说明（NamingAssistant）
|
||
|
||
## 1. 文档信息
|
||
- **版本**：v0.1（初版）
|
||
- **创建日期**：2025-11-04
|
||
- **适用范围**：`MiniProgram/NamingAssistant` 首个迭代（姓名生成与收藏）
|
||
- **维护人**：前端负责人、后端接口负责人、测试负责人共用
|
||
|
||
## 2. 背景与目标
|
||
- 提供面向抖音生态的姓名生成服务，支持根据用户输入的姓氏、性别、出生日期与名字长度快速获取候选姓名。
|
||
- 通过广告激励实现变现，确保用户在观看广告后获得生成结果。
|
||
- 支撑用户在本地收藏心仪姓名，限制每日请求频率防止滥用。
|
||
|
||
## 3. 名词与角色
|
||
- **用户**：使用抖音小程序的终端访客。
|
||
- **AI 命名服务**：后端聚合接口，根据提示词返回 5 个姓名及释义。
|
||
- **校验服务**：后端接口，校验姓氏是否合法。
|
||
- **激励广告**：抖音小程序提供的激励视频广告组件。
|
||
|
||
## 4. 产品范围
|
||
- **In Scope**
|
||
- 主页表单输入、校验与广告流程。
|
||
- 结果页展示 5 个姓名与释义，支持收藏。
|
||
- 收藏页展示本地收藏记录、删除、查看详情。
|
||
- 本地记录每日调用次数，超过 10 次给出提示，次数可在后台配置。
|
||
- **Out of Scope**
|
||
- 账户登录、云端收藏同步。
|
||
- 历史生成记录、多端同步。
|
||
- 自定义广告策略与多渠道投放。
|
||
|
||
## 5. 用户流程（KISS）
|
||
1. 用户打开主页填写表单：姓 → 性别 → 出生日期/时间 → 名字字数。
|
||
2. 姓输入失焦触发校验接口；非法返回后提示并清空输入。
|
||
3. 用户点击“生成姓名”，系统执行整体验证；失败则提示错误并阻止提交。
|
||
4. 校验通过后展示激励广告；广告播放完成触发生成逻辑。
|
||
5. 调用生成接口并显示“计算中”加载状态；成功后缓存结果并跳转结果页。
|
||
6. 结果页展示 5 条姓名及含义，用户可选择任意一个收藏，收藏立即写入本地，数量可在后台配置。
|
||
7. 用户可从结果页或主导航进入收藏页查看或删除收藏项。
|
||
|
||
## 6. 页面结构与职责（SOLID）
|
||
- **主页（`pages/home/index`）**
|
||
- 负责表单输入组件渲染与状态管理。
|
||
- 调用校验服务、触发广告播放与生成流程。
|
||
- 控制每日次数提示、跳转结果页。
|
||
- **结果页（`pages/result/index`）**
|
||
- 展示当前生成结果，处理收藏交互。
|
||
- 支持返回主页重新生成。
|
||
- **收藏页（`pages/favorites/index`）**
|
||
- 读取本地收藏列表并渲染。
|
||
- 提供单项删除与查看释义。
|
||
|
||
> 页面逻辑使用独立 `store`（如 `store/namingStore.ts`）管理：当前表单、生成结果、调用次数、收藏集合，避免重复状态（DRY）。
|
||
|
||
## 7. 数据模型（YAGNI：仅覆盖本迭代必要字段）
|
||
| 实体 | 字段 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `NamingForm` | `surname` | string | 1-2 个汉字，必填 |
|
||
| | `gender` | `'male' \| 'female'` | 单选，必填 |
|
||
| | `birthDate` | `string` | `YYYY-MM-DD`，默认当天，必填 |
|
||
| | `birthTime` | `string \| null` | `HH:mm`，默认空，选填 |
|
||
| | `nameLength` | `'single' \| 'double'` | 单名 or 双名，默认 `double` |
|
||
| `NamingResult` | `name` | string | 生成姓名 |
|
||
| | `meaning` | string | 含义说明 |
|
||
| | `score` | number? | 预留；本迭代不返回（保持可选，默认不展示） |
|
||
| `FavoriteItem` | `id` | string | `name + timestamp` 生成的唯一键 |
|
||
| | `name` | string | 收藏姓名 |
|
||
| | `meaning` | string | 对应释义 |
|
||
| | `createdAt` | string | ISO 时间戳 |
|
||
|
||
## 8. 业务规则
|
||
- 姓氏校验：输入长度 1-2，失焦时调用 `/validate-surname`，返回 `isValid=false` 时清空并 Toast“请输入合法姓氏”。
|
||
- 表单必填项：姓氏、性别、出生日期、名字字数；出生时间选填（为空不纳入提示词）。
|
||
- 提交前整体验证：若任一必填缺失或校验失败，阻止广告播放并给出错误提示。
|
||
- 激励广告完成事件 `onClose` 返回 `isEnded=true` 才允许调用生成接口；否则提示“观看完整广告后才能生成姓名”。
|
||
- 每日次数：基于本地缓存键 `naming:quota:YYYYMMDD` 记录已用次数；达到 10 次时 Toast“今日生成次数已用尽，请明日再试”。
|
||
- 收藏：每个姓名可多次生成；收藏时如同名存在则更新 `createdAt`，避免重复条目。
|
||
- 删除收藏：从本地存储移除对应 `id` 并刷新列表。
|
||
|
||
## 9. 接口契约（接口分离，依赖抽象而非具体实现）
|
||
- **POST `/api/naming/validate-surname`**
|
||
- 请求：`{ "surname": "李" }`
|
||
- 响应：`{ "isValid": true, "message": "" }`
|
||
- 错误码：`40001` 非法字符、`50000` 系统异常。
|
||
- **POST `/api/naming/generate`**
|
||
- 请求：
|
||
```json
|
||
{
|
||
"surname": "李",
|
||
"gender": "male",
|
||
"birthDate": "2025-11-04",
|
||
"birthTime": "",
|
||
"nameLength": "double"
|
||
}
|
||
```
|
||
- 服务端将上述信息组合成提示词，例如：`"以“李”为姓，男孩，出生于2025年11月4日，生成双名，提供5个寓意美好的中文名字"`。
|
||
- 响应：
|
||
```json
|
||
{
|
||
"results": [
|
||
{ "name": "李承泽", "meaning": "承载福泽，寓意富足" },
|
||
{ "name": "李昱辰", "meaning": "昱意为光辉，辰代表时光" },
|
||
{ "name": "李颢宇", "meaning": "广阔天空，胸怀大志" },
|
||
{ "name": "李景曜", "meaning": "景象辉煌，曜为光耀" },
|
||
{ "name": "李辰逸", "meaning": "自在悠然，辰意指时光" }
|
||
]
|
||
}
|
||
```
|
||
- 异常：
|
||
- `42900` 请求超限（由后端或网关返回，与前端本地控制互补）。
|
||
- `50000` 系统异常。
|
||
|
||
## 10. 本地存储策略
|
||
- `tt.setStorageSync('naming:quota:YYYYMMDD', number)`：记录当日已使用次数。
|
||
- `tt.setStorageSync('naming:favorites', FavoriteItem[])`：存储收藏列表。
|
||
- 加载收藏页时若数据缺失则返回空数组，避免抛错。
|
||
|
||
## 11. 激励广告模块
|
||
- 封装 `utils/adService.ts` 暴露 `showRewardedVideoAd(): Promise<void>`。
|
||
- 广告位 ID 通过配置注入，方便后续替换；模块负责加载、展示、清理事件监听。
|
||
- 页面调用时捕获异常并提示“广告加载失败，请稍后重试”。
|
||
|
||
## 12. 错误与提示文案（DRY：集中在 `constants/messages.ts`）
|
||
- `INVALID_SURNAME`：`请输入合法姓氏`
|
||
- `FORM_INCOMPLETE`：`请完整填写必填项`
|
||
- `WATCH_AD_TO_CONTINUE`：`观看完整广告后才能生成姓名`
|
||
- `QUOTA_EXCEEDED`：`今日生成次数已用尽，请明日再试`
|
||
- `GENERATION_FAILED`：`生成失败，请稍后再试`
|
||
|
||
## 13. 验收标准（测试覆盖）
|
||
- **表单校验**：
|
||
- 输入非法姓氏提示并清空。
|
||
- 必填项缺失无法触发广告。
|
||
- **广告流程**：
|
||
- 未完整观看广告不可调用生成接口。
|
||
- 广告失败异常提示正常。
|
||
- **生成结果**：
|
||
- 成功返回后跳转结果页，展示 5 条记录及释义。
|
||
- “计算中” loading 在接口完成后消失。
|
||
- **收藏功能**：
|
||
- 收藏后收藏页可见，删除后立即消失。
|
||
- 重复收藏刷新时间戳不新增条目。
|
||
- **请求限额**：
|
||
- 连续触发 10 次后出现限额提示，第 11 次被阻止。
|
||
|
||
## 14. 非功能需求
|
||
- Loading 状态 300ms 内出现，避免空白。
|
||
- API 网络失败时 2s 内给出提示。
|
||
- 本地存储读写失败需兜底为内存态并告警（日志）。
|
||
|
||
## 15. 依赖与配置
|
||
- 抖音小程序基础库 ≥ 3.0；需启用激励视频广告能力。
|
||
- 后端提供校验与生成接口；约定响应时间 ≤ 3s。
|
||
- 配置文件 `config/index.ts`：广告位 ID、接口基础地址、最大生成次数。
|
||
|
||
## 16. 待确认事项
|
||
- 广告必须观看时长是否有具体数值要求（默认以 `isEnded` 判断）。
|
||
- AI 接口返回释义字段是否稳定，若缺失由兜底。
|
||
- 是否需要埋点统计广告完成率与收藏次数（暂未纳入：YAGNI）。
|
||
|
||
## 17. 里程碑
|
||
- **M1**：完成项目脚手架、页面路由与表单控件。
|
||
- **M2**：接入校验与生成接口，贯通广告流程。
|
||
- **M3**：实现收藏、本地限额逻辑并完成联调、测试用例。
|
||
|
||
> 设计遵循 KISS（简洁流程）、DRY（统一状态与文案）、YAGNI（仅落地当前需求），页面与服务模块职责清晰满足 SOLID。
|
||
|