feat(admin-frontend): 完成订阅与系统管理真实工作台

补齐订单、优惠券、主题、插件、公告与支付管理页面，接入对应后台接口、路由入口与工具层类型定义。同时修复套餐页开关初始化误写问题，避免浏览即触发写操作。在订阅协议侧为 Stash 导出增加 AnyTLS 版本守卫，未知版本或低于 3.3.0 时不再导出该协议，并补充回归测试与知识记录。
2026-04-24 16:52:41 +08:00
parent 16203b14f6
commit f7cef30b9c
89 changed files with 11122 additions and 92 deletions
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "知识库管理页已完成并通过构建验证",
+  "updated_at": "2026-04-24 16:24:00"
+}
@@ -0,0 +1,83 @@
+# 变更提案: admin-frontend-knowledge-management
+
+## 元信息
+```yaml
+类型: 功能增强
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+`admin-frontend` 当前已经完成系统管理分组与系统配置页，但 `#/system/knowledge` 仍停留在结构化占位页。用户已提供目标截图，希望继续补齐真实“知识库管理”页面，并保持现有 Apple 化后台的低噪音运营风格。
+
+### 目标
+- 将 `#/system/knowledge` 从占位页升级为真实知识库管理工作台。
+- 支持知识列表查看、搜索、分类筛选、显隐切换、编辑排序、删除和新增/编辑。
+- 编辑器采用用户刚确认的“轻量 Markdown 编辑器”方案，支持常用格式插入与预览，不新增富文本依赖。
+
+### 约束条件
+```yaml
+范围约束: 仅实现 admin-frontend 的知识库管理页，不改 Laravel 后端接口行为
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus + markdown-it 现有栈，不新增第三方编辑器依赖
+视觉约束: 保持 Apple 风格后台气质，贴近用户截图中的“轻表格 + 中央编辑弹窗”结构
+业务约束: 后端真相源固定为 knowledge/fetch、knowledge/getCategory、knowledge/save、knowledge/show、knowledge/drop、knowledge/sort
+```
+
+### 验收标准
+- [√] `#/system/knowledge` 可以展示真实知识列表，并支持关键字搜索与分类筛选。
+- [√] 列表支持显隐切换、删除、排序调整与编辑入口。
+- [√] 新增/编辑弹窗支持标题、分类、语言、显示状态与正文编辑；正文采用轻量 Markdown 方案并支持预览。
+- [√] `admin-frontend` 构建通过，产物成功输出到 `public/assets/admin`。
+
+---
+
+## 2. 方案
+
+### 信息架构
+1. 列表页采用“页头说明 + 操作工具条 + 白色数据表格”结构，贴近用户截图的运营后台感。
+2. 编辑页采用中央 `ElDialog`，而非侧滑抽屉，保持与截图一致的工作流。
+3. 排序采用本地编辑对话框，复用当前列表顺序生成 `ids`，再调用 `/knowledge/sort`。
+
+### 技术方案
+1. 在 `src/types/api.d.ts` 与 `src/api/admin.ts` 中补充知识库实体类型和请求封装。
+2. 新增 `src/utils/knowledge.ts`，统一处理分类、表单模型、Markdown 渲染和本地过滤逻辑。
+3. 新建 `SystemKnowledgeView.vue` 与 `KnowledgeEditorDialog.vue`，分别承载知识库列表页和编辑弹窗。
+4. 路由层将 `/system/knowledge` 从 `SystemPlaceholderView` 切换为真实页面组件。
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 后端列表接口不返回正文与语言 | 中 | 编辑时单独调用 `knowledge/fetch?id=` 拉取详情 |
+| 轻量 Markdown 编辑体验弱于完整富文本 | 低 | 用工具栏 + 预览补齐高频编辑动作，优先满足当前截图与范围 |
+| 排序与显隐属于真实写操作 | 中 | 保持明确按钮、反馈提示与失败回滚，避免静默提交 |
+
+---
+
+## 3. 技术决策
+
+### admin-frontend-knowledge-management#D001: 编辑器采用轻量 Markdown 方案
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户在执行前确认选择了“轻量 Markdown 编辑器（推荐）”。
+**决策**: 复用仓内已有 `markdown-it` 能力，自建工具栏 + 预览编辑器，不引入额外富文本依赖。
+**理由**: 能更快贴近当前截图的编辑体验，同时控制依赖和实现复杂度。
+
+### admin-frontend-knowledge-management#D002: 列表页采用真实表格，编辑页采用中央对话框
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户截图呈现的是“列表页 + 中央弹窗”的运营后台工作流。
+**决策**: 保持列表、筛选、开关、排序留在主页面，新增/编辑放入对话框集中处理。
+**理由**: 更符合知识库管理的批量维护场景，也能最大程度贴合用户提供的视觉参考。
+
+### admin-frontend-knowledge-management#D003: 排序采用本地草稿编辑后统一提交
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 后端排序接口为 `POST /knowledge/sort`，需要提交有序 `ids`。
+**决策**: 先在前端弹窗维护当前顺序草稿，再一次性提交排序结果。
+**理由**: 避免列表页直接拖拽带来的交互复杂度和误操作风险，保持后台操作克制清晰。
@@ -0,0 +1,43 @@
+# 任务清单: admin-frontend-knowledge-management
+
+> **@status:** completed | 2026-04-24 16:24
+
+```yaml
+@feature: admin-frontend-knowledge-management
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 梳理知识库后端接口、类型边界与现有系统管理设计契约
+- [√] 2. 实现知识库 API/类型/工具层与真实列表页面
+- [√] 3. 实现知识编辑弹窗、排序流程与显隐/删除操作
+- [√] 4. 运行 `admin-frontend` 构建验证，并同步 `.helloagents` 记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 16:10 | 方案包初始化 | completed | 用户已确认采用轻量 Markdown 编辑器方案 |
+| 2026-04-24 16:18 | 页面实现 | completed | 已接入知识列表、分类筛选、编辑弹窗、显隐切换与排序对话框 |
+| 2026-04-24 16:22 | 构建验证 | completed | `admin-frontend` 执行 `npm run build` 通过，并输出知识库页面产物 |
+| 2026-04-24 16:24 | 文档同步 | completed | 已更新 CHANGELOG、模块文档与状态快照 |
+
+---
+
+## 执行备注
+
+- 当前仓存在未提交的历史变更与多个未归档方案包，本轮只增量实现知识库管理，不覆盖无关文件。
+- `public/assets/admin` 为前端产物子模块；构建后需要同时复核根仓与子模块状态。