<?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,
        ];
    }
}