nepiedg
207 lines
7.9 KiB
PHP
207 lines
7.9 KiB
PHP
<?php
|
|
declare(strict_types=1);
|
|
|
|
namespace app\note\service;
|
|
|
|
/**
|
|
* 笔记小程序接口规划服务
|
|
*
|
|
* 说明：
|
|
* - 当前阶段先在独立 `note` 模块沉淀接口规划与模块骨架
|
|
* - 暂未落真实业务逻辑，接口先返回规划结构与字段建议
|
|
* - 后续确定表结构后，可直接在 `app/note` 模块内继续补 Model / Service / Controller
|
|
*/
|
|
class PlanningService
|
|
{
|
|
/**
|
|
* 获取整个 note 模块接口概览。
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getModuleOverview(): array
|
|
{
|
|
return [
|
|
'module' => 'note',
|
|
'version' => 'v1',
|
|
'description' => '笔记小程序独立模块，负责小程序登录、笔记、转写、AI 总结能力',
|
|
'business_blocks' => [
|
|
[
|
|
'name' => '小程序用户登录',
|
|
'goal' => '基于微信 code 登录，换取 openid / session_key，并建立本地用户映射与 JWT 登录态',
|
|
],
|
|
[
|
|
'name' => '笔记创建与实时录音转文字',
|
|
'goal' => '支持纯文本笔记、语音笔记、实时转写文本落地、后续编辑与查看',
|
|
],
|
|
[
|
|
'name' => 'AI 总结',
|
|
'goal' => '对单条笔记或一次录音转写结果生成结构化摘要、待办、标签等内容',
|
|
],
|
|
],
|
|
'routes' => [
|
|
['method' => 'GET', 'path' => '/note/v1/meta/interfaces', 'desc' => '获取 note 模块接口规划'],
|
|
['method' => 'POST', 'path' => '/note/v1/auth/wechat-login', 'desc' => '微信小程序登录'],
|
|
['method' => 'GET', 'path' => '/note/v1/auth/me', 'desc' => '获取当前小程序用户信息'],
|
|
['method' => 'POST', 'path' => '/note/v1/item/create', 'desc' => '创建笔记'],
|
|
['method' => 'GET', 'path' => '/note/v1/item/list', 'desc' => '笔记列表'],
|
|
['method' => 'GET', 'path' => '/note/v1/item/:id', 'desc' => '笔记详情'],
|
|
['method' => 'POST', 'path' => '/note/v1/item/update/:id', 'desc' => '更新笔记'],
|
|
['method' => 'POST', 'path' => '/note/v1/item/delete/:id', 'desc' => '删除笔记'],
|
|
['method' => 'POST', 'path' => '/note/v1/item/transcript/:id', 'desc' => '保存实时转写内容'],
|
|
['method' => 'POST', 'path' => '/note/v1/ai/summary/:id', 'desc' => '发起 AI 总结'],
|
|
['method' => 'GET', 'path' => '/note/v1/ai/summary/:id', 'desc' => '查看 AI 总结结果'],
|
|
],
|
|
'suggested_tables' => [
|
|
'note_user',
|
|
'note_item',
|
|
'note_transcript',
|
|
'note_ai_summary',
|
|
],
|
|
'development_priority' => [
|
|
'1. 先落小程序登录，打通微信 openid 与 JWT',
|
|
'2. 再落笔记主表与笔记 CRUD',
|
|
'3. 再补实时转写保存接口',
|
|
'4. 最后接入 AI 总结任务与结果存储',
|
|
],
|
|
];
|
|
}
|
|
|
|
/**
|
|
* 小程序登录接口规划。
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getWechatLoginSpec(): array
|
|
{
|
|
return [
|
|
'name' => '微信小程序登录',
|
|
'route' => 'POST /note/v1/auth/wechat-login',
|
|
'request' => [
|
|
'code' => '微信 wx.login 获取的临时 code，必填',
|
|
'nickname' => '用户昵称，可选',
|
|
'avatar_url' => '头像地址，可选',
|
|
'device' => '设备信息，可选',
|
|
],
|
|
'response' => [
|
|
'token' => '沿用 tp 现有 JWT 登录态',
|
|
'refresh_token' => '刷新令牌',
|
|
'expires_in' => '过期时间',
|
|
'user' => [
|
|
'id' => 'note_user 主键 ID',
|
|
'member_id' => '关联 tp 现有 member 用户 ID，可为空',
|
|
'openid' => '微信 openid',
|
|
'nickname' => '昵称',
|
|
'avatar_url' => '头像',
|
|
'is_new_user' => '是否首次登录',
|
|
],
|
|
],
|
|
'depends_on' => [
|
|
'微信 code2Session',
|
|
'note_user 表',
|
|
'是否与现有 member 表映射的业务策略',
|
|
],
|
|
];
|
|
}
|
|
|
|
/**
|
|
* 笔记接口规划。
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getNoteSpecs(): array
|
|
{
|
|
return [
|
|
'create' => [
|
|
'route' => 'POST /note/v1/item/create',
|
|
'request' => [
|
|
'title' => '标题，可选',
|
|
'content' => '正文，可选',
|
|
'source_type' => '来源类型：text / audio / mix',
|
|
'audio_duration_ms' => '录音时长，可选',
|
|
'status' => '状态：draft / completed，默认 draft',
|
|
],
|
|
],
|
|
'list' => [
|
|
'route' => 'GET /note/v1/item/list',
|
|
'request' => [
|
|
'page' => '页码，默认 1',
|
|
'page_size' => '每页数量，默认 10',
|
|
'keyword' => '标题/正文搜索，可选',
|
|
'status' => 'draft / completed，可选',
|
|
],
|
|
],
|
|
'detail' => [
|
|
'route' => 'GET /note/v1/item/:id',
|
|
'response' => [
|
|
'id' => '笔记 ID',
|
|
'title' => '标题',
|
|
'content' => '正文',
|
|
'transcript_text' => '转写文本',
|
|
'audio_duration_ms' => '录音时长',
|
|
'summary' => 'AI 总结结果，可选',
|
|
],
|
|
],
|
|
'update' => [
|
|
'route' => 'POST /note/v1/item/update/:id',
|
|
],
|
|
'delete' => [
|
|
'route' => 'POST /note/v1/item/delete/:id',
|
|
],
|
|
'transcript' => [
|
|
'route' => 'POST /note/v1/item/transcript/:id',
|
|
'request' => [
|
|
'segment_no' => '分片序号',
|
|
'segment_text' => '本次实时转写文本，可选',
|
|
'full_text' => '当前整段累计文本，必填',
|
|
'is_final' => '是否最终片段',
|
|
'audio_duration_ms' => '当前累计录音时长，可选',
|
|
],
|
|
],
|
|
];
|
|
}
|
|
|
|
/**
|
|
* AI 总结接口规划。
|
|
*
|
|
* @return array
|
|
*/
|
|
public function getAiSpecs(): array
|
|
{
|
|
return [
|
|
'create_summary' => [
|
|
'route' => 'POST /note/v1/ai/summary/:id',
|
|
'request' => [
|
|
'summary_type' => '摘要类型：brief / outline / todo',
|
|
'force_refresh' => '是否强制重新生成，可选',
|
|
],
|
|
],
|
|
'read_summary' => [
|
|
'route' => 'GET /note/v1/ai/summary/:id',
|
|
'response' => [
|
|
'summary_id' => '总结记录 ID',
|
|
'summary_type' => '摘要类型',
|
|
'summary_text' => '总结内容',
|
|
'todo_list' => '待办列表，可选',
|
|
'keywords' => '关键词列表，可选',
|
|
'status' => '状态',
|
|
],
|
|
],
|
|
];
|
|
}
|
|
|
|
/**
|
|
* 返回接口尚未落库的统一说明。
|
|
*
|
|
* @param array $spec
|
|
* @return array
|
|
*/
|
|
public function buildPendingImplementationPayload(array $spec): array
|
|
{
|
|
return [
|
|
'implemented' => false,
|
|
'reason' => '当前阶段仅完成 note 独立模块接口规划骨架，数据库表已设计，真实业务逻辑待继续实现',
|
|
'spec' => $spec,
|
|
];
|
|
}
|
|
}
|