# M10：AI 工作台从基础接口到后台闭环（教程大纲）

## 一、这篇内容写给谁

- 已经完成 `M1 ~ M9`，项目已经具备基础展示、发布流和体验基线的开发者
- 想继续把 AI 能力从“后端能调用”推进到“后台可演示、可讲解、可控边界”的读者
- 想学习如何在教程型仓库里，小步把 AI 能力做成闭环，而不是一上来就堆满队列、历史和复杂编排的人

## 二、M10 要解决什么问题

M9 结束后，项目已经具备：

- `admin / web / server` 三端最小展示闭环
- 统一主题与最小共享 UI
- AI Provider、文件提取、缓存报告等后端基础能力

但 AI 这一条线仍然存在明显断层：

- 后台有 AI 工作台壳，但还不是真正可操作的工作台
- 文件提取入口存在，但还没有接成“输入 -> 分析 -> 结果”的连续链路
- 管理员和 viewer 的页面体验边界还没有真正落在前端

所以 M10 的本质，不是扩更多 AI 能力，而是把现有基础能力收成一条可演示、可解释、可继续扩展的后台闭环。

## 三、M10 的阶段边界

### 本里程碑做什么

- 建立后台 AI 工作台入口
- 接通文件上传、文本提取与输入预览
- 让管理员可触发真实分析并阅读结果
- 让 viewer 只读缓存或预设结果，明确成本控制边界

### 本里程碑不做什么

- 不引入 Redis / BullMQ 队列
- 不做分析历史持久化
- 不做复杂 Prompt 编排系统
- 不做 JD 多版本商业化能力
- 不扩展新的角色模型

## 四、M10 的 issue 拆解思路

### issue-47 AI 工作台入口与运行时摘要

- 为什么 AI 相关能力要先收成独立工作台，而不是散在后台各处
- 为什么先把 Provider、model、场景和角色边界写清楚
- 为什么这一轮还不急着把上传和分析一次性做完

### issue-48 文件上传与文本提取预览

- 为什么 AI 的第一步不是直接分析，而是先统一输入链路
- 为什么文件提取继续坚持由 NestJS 统一承载
- 如何把上传与提取做成最小可验证闭环，而不抢跑到附件系统

### issue-49 管理员真实分析闭环

- 为什么要先做同步最小闭环，而不是直接上队列
- 如何把提取结果接到分析输入区，形成连续主线
- 如何在页面上展示场景、Provider、结果结构和错误反馈

### issue-50 viewer 缓存体验与权限收束

- 为什么成本控制不能只靠“禁用按钮”
- 如何给 viewer 一条真正可用的只读缓存体验链路
- 为什么单一工作台壳比拆成两套 AI 页面更适合当前教程型仓库

### issue-51 教程大纲与里程碑收束

- 为什么 AI 相关里程碑更需要及时沉淀文档
- 如何把“工作台入口、输入链路、真实分析、viewer 边界”串成稳定素材
- 怎样把当前已完成边界和后续队列 / 历史系统区分开

## 五、M10 的关键设计取舍

### 1. 先做后台可演示闭环，再做更复杂 AI 基建

- 当前更重要的是证明“这条 AI 主线真的能工作”
- 如果一开始就上队列、任务中心、历史表，会让教学节奏过快失控
- 所以 M10 选择先把同步短链路站稳

### 2. 输入链路必须统一收在 NestJS

- 文件提取、缓存读取、真实分析都继续走 `apps/server`
- 这样前端只负责页面壳、交互和结果展示
- 也能继续守住“唯一业务后端”的整体原则

### 3. admin 与 viewer 不是两套系统，而是同一工作台的两种边界

- `admin`：上传、真实分析、结果阅读
- `viewer`：缓存 / 预设结果体验

M10 选择不拆成两套页面，而是在同一工作台内通过能力与顺序组织把边界讲清楚。

### 4. 缓存体验是教学能力，不只是权限兜底

- viewer 缓存体验让 AI 成本控制更容易解释
- 也让开源读者不需要自带 API Key 就能体验部分工作流
- 这比单纯的“403 + 说明文案”更适合教学

## 六、M10 完成后的项目状态

- `apps/admin`：具备 AI 工作台、上传提取、真实分析、缓存体验与角色边界
- `apps/server`：继续作为唯一 AI 业务后端，承载运行时、缓存、文件提取与分析触发
- `viewer`：可在后台只读体验缓存结果
- `admin`：可从输入到分析再到结果阅读，完成最小演示闭环

## 七、建议展开成系列文章的章节

### 文章 1：为什么 AI 项目的第一步不是“直接分析”，而是统一输入链路

- 重点讲文件提取入口、NestJS 统一承载和输入边界

### 文章 2：如何把后台 AI 能力从“入口壳”推进到“真实分析闭环”

- 重点讲工作台、输入区、错误反馈和结果阅读

### 文章 3：为什么同步最小闭环比一上来做队列系统更适合教程型项目

- 重点讲节奏控制、验证成本和迭代顺序

### 文章 4：AI 成本控制为什么不能只靠权限判断

- 重点讲 viewer 缓存体验、预设结果和教学演示策略

### 文章 5：如何在同一工作台中表达 admin / viewer 的能力边界

- 重点讲页面顺序、入口可用性和边界提示语

## 八、推荐引用的开发日志

- `docs/30-开发日志/M10-issue-47-AI-工作台入口与运行时摘要.md`
- `docs/30-开发日志/M10-issue-48-文件上传与文本提取预览.md`
- `docs/30-开发日志/M10-issue-49-管理员真实分析闭环.md`
- `docs/30-开发日志/M10-issue-50-viewer-缓存体验与权限收束.md`

## 九、M10 刻意没做什么

- 没做异步任务队列
- 没做分析历史持久化
- 没做复杂 Prompt 编排
- 没做新的 AI 角色系统
- 没把 viewer 体验扩成完整业务用户系统

## 十、后续衔接建议

- `M11` 如果继续做 AI 方向，可以考虑任务中心、分析历史、异步状态流转
- 也可以回到体验层，继续做更成熟的后台信息架构或前台 AI 结果展示
- 但无论进入哪条线，都建议继续守住 M10 已收住的原则：
  - 先定义边界
  - 先做短链路
  - 先证明能工作
  - 再做复杂系统
