134 lines
13 KiB
Markdown
134 lines
13 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Project-Profile
|
||
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-
|
||
wiki_revision: 80cd91be7e64552b0205f45c59a2234934760b0e
|
||
synchronized_at: 2026-09-10T09:38:10Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# LexGo 项目档案
|
||
|
||
|
||
## 基本信息
|
||
|
||
目标：围绕“导入内容 → 阅读查词 → 保存词语/短语 → 复习 → 查看进展”建设自托管语言学习 Web 应用。MVP 定位已确认：支持多账号、数据独立的自托管学习工具，先邀请少量用户使用；主要角色为学习者和实例管理员。
|
||
|
||
现状：已有四份调研材料、项目主题文档和治理工具，无业务代码、产品依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 `.git`；本轮已连接确认的远端 `https://git.ilapage.cn/OPC/lexgo.git`，默认分支 `main`，已有引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。仓库归属 OPC，产品验收负责人为当前用户，具体长期维护分工尚未确定。
|
||
|
||
非目标暂按既有分析：商业 SaaS、多组织租户、课程商城、原生 App、完整离线同步、OCR、视频转写和 FSRS 改造均不包含在本轮基础估算。
|
||
|
||
## 项目治理模式
|
||
|
||
**轻量**，依据 2026-09-10 用户明确指令。低风险局部调整直接实施；独立需求及中高风险变化建单；不为初始化强制拆 Epic/MVP。见[工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)。
|
||
|
||
## DevHarness 来源与基线
|
||
|
||
本地来源 `D:/opc_project/dev_harness`，Git commit `ecab8995026e57f2c28f307a6aa32b871cb3163f`，核验日 2026-09-10。治理脚本、测试与模板按此基线复制，不复制凭据、Git 历史或旧任务快照。升级先比较该基线之后的变化，按本项目真实需要引入。
|
||
|
||
LinguaCafe 参考基线由现有调研记录为 `c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8`；本轮只整理已提供的调研，没有重新核验上游代码、依赖或许可。管理端已由用户指定 go-admin，锁定的本地参考 commit 见下文；现有 gin-vue-admin 建议作为历史材料保留。
|
||
|
||
## 子项目与交付单元
|
||
|
||
当前独立交付物包括文档、治理工具、账号后端和两个前端。目标按一个产品版本、一个仓库规划：基于 go-admin 扩展的共享 Go API/Worker、独立学习前端和独立管理前端；内部 NLP 服务暂为建议。学习端与管理端分开构建，共用后端与账号体系。当前目录为 server、admin、learner 和 scripts，实际入口见代码地图。
|
||
|
||
## 技术栈与运行环境
|
||
|
||
| 决策 ID | 议题 | 现有证据与状态 | 对估算的影响 |
|
||
|---|---|---|---|
|
||
| D01 | 管理端底座 | **已确认使用 `D:/github_project/goadmin` 的 go-admin + go-admin-ui**，依据用户指令“管理端用D:\github_project\goadmin”；替代 gin-vue-admin 建议 | M0 验证指定本地版本配套、MySQL 8 及数据隔离，不再比较管理底座 |
|
||
| D02 | 数据库 | **已确认 MySQL 8**；依据 2026-09-10 用户原话“使用mysql8”。覆盖两份分析的数据库分歧，具体小版本待基线验证锁定 | 按单一 MySQL 8 数据层估算，不做 PostgreSQL 双库兼容 |
|
||
| D03 | NLP | 保留 Python 为建议，纯 Go 是否硬约束未确认 | 首发语言质量与开发量 |
|
||
| D04 | 默认学习语言 | 用户已确认英语；中文/日语后续需独立范围与验收 | 分词、读音和 UI |
|
||
| D05 | 用户范围 | **已确认：支持多账号、数据独立的自托管学习工具，先邀请少量用户使用** | 首版按多用户归属和隔离设计；不自动加入公开注册、邀请链接或组织租户 |
|
||
| D06 | 旧数据 | 全量迁移是否需要未确认，CSV 与完整迁移不同 | 迁移另估 |
|
||
| D07 | 范围与交付 | 已确认 F01～F12；X 系列后置；原型审核后拆实施工单，人员与运行环境待细化 | 按已确认 MVP 重新估算与验收 |
|
||
| D09 | 学习端技术栈 | 已按用户要求纳入方案：Vue 3 + TypeScript + Vite，Vue Router、Pinia、Element Plus，Vitest + Playwright | 使用官方 create-vue 新建独立前端，具体版本与构建待验证 |
|
||
| D10 | 前后端复用边界 | 两个前端工程共用基于 go-admin 扩展的 Go 模块化单体；登录和业务数据共用 | 学习界面及领域模块需开发，不复制整套后台布局或直接移植 LinguaCafe 前端 |
|
||
| D08 | Gitea | 已确认 `https://git.ilapage.cn/OPC/lexgo.git`，分支 main，工单与 Wiki 已启用 | 本轮发布核心 Wiki 并同步验证 |
|
||
|
||
数据库确定为 MySQL 8；管理端使用 go-admin/go-admin-ui；学习端方案与复用边界见 D09/D10。Redis 任务队列、Python NLP、Compose 仍为候选，具体版本和构建命令在技术验证后固定。不能同时按两种数据库承诺交付。
|
||
|
||
## 阅读入口
|
||
|
||
[需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)、[代码地图](https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-)、[工作量](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)。现有分析中的许可说明仅作资源评估线索，采用代码、词典、模型和素材前记录来源与实际许可；本轮不作新的法律结论。
|
||
|
||
## 常用命令
|
||
|
||
见[开发与验证](https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-)。产品构建、启动、测试和部署命令暂不存在，不用示例命令冒充实际可运行入口。
|
||
|
||
## 环境、配置与凭据
|
||
|
||
本地 Windows PowerShell，工作目录 `D:/opc_project/lexgo`。当前 Gitea MCP 指向 `ilaer.eicp.net:8418`，并非用户确认的目标站点；本轮因此使用目标站点 Gitea API。凭据从已配置的安全来源读入进程，不复制进项目。Wiki 配置只保存非敏感地址与页面映射，凭据使用 MCP 安全配置或环境变量。
|
||
|
||
## 治理默认值与已核验主机
|
||
|
||
新项目默认采用轻量模式；本项目同时已获用户明确选择。DevHarness 上游模板自身继续采用标准模式，该模板模式不覆盖 LexGo 的选择。
|
||
|
||
本轮核实本机为 Microsoft Windows 10 企业版 LTSC，使用 PowerShell 7 `pwsh`，版本 7.3.12；Python 工具当前运行于 Python 3.8。该环境记录只证明文档工具运行主机，不代表产品支持矩阵。
|
||
|
||
## 已确认管理端基线
|
||
|
||
2026-09-10 用户指定 `D:/github_project/goadmin`。它是三个仓库的容器目录，本轮只读检查三个工作区均无未提交修改；不修改源目录，也不将其中配置、数据库文件或运行数据自动复制到 LexGo。
|
||
|
||
| 组成 | 来源与用途 | 当前本地完整 commit |
|
||
|---|---|---|
|
||
| go-admin | `D:/github_project/goadmin/go-admin`；origin `https://github.com/go-admin-team/go-admin.git`；管理 API 与通用基础 | `f06540883b41d03782bb6b2c4150f298f328c6b6` |
|
||
| go-admin-ui | `D:/github_project/goadmin/go-admin-ui`；origin `https://github.com/go-admin-team/go-admin-ui.git`；管理前端 | `67d393d713877572fab0b897296a4c1d525fc81d` |
|
||
| go-admin-doc | `D:/github_project/goadmin/go-admin-doc`；origin `https://github.com/go-admin-team/go-admin-doc.git`；配套参考文档 | `424855aacf6905f3fde860c3331385cb25529a0d` |
|
||
|
||
版本依据是上述本地文件，不宣称最新上游版本：后端 go.mod 声明 Go 1.26.5、Gin v1.12.0、GORM v1.31.2、MySQL driver v1.6.0；前端 package.json 声明 Vue ^3.5.41、Element Plus ^2.14.4、Vue Router ^4.6.4、Vuex ^4.1.0，使用 Vue CLI，packageManager 为 pnpm@9.15.1，engines 为 Node >=22 / pnpm >=9。本轮没有执行依赖安装、构建或运行，锁文件可安装性和前后端兼容性仍需实测。
|
||
|
||
M0 在 LexGo 隔离工程中验证：指定前后端配套构建；MySQL 8 迁移与启动；登录、菜单和 API 权限；普通学习者的数据所有权隔离；用户区与管理区的身份衔接。管理 UI 的 dev/build 脚本使用类 Unix 的内联环境变量写法，Windows 执行方式需验证并最小适配，不假定 PowerShell 下直接成功。
|
||
|
||
复用范围为通用管理界面及其配套 API/身份能力；阅读器、词汇、短语与复习仍需实现 LexGo 领域逻辑。学习端另建 Vue 3 + TypeScript + Vite 工程，管理端继续使用其现有 Vue CLI/Vuex 结构；不要求两端统一构建工具和状态库。实际引入前核对代码和资源许可、排除本地配置及数据库等运行文件；按固定提交建立上游差异记录，后续升级先验证再更新基线。管理端已按选用模块接入 LexGo，范围与差异见本页末尾。
|
||
|
||
## 学习端技术方案（2026-09-10）
|
||
|
||
依据本轮讨论及用户“先把这些更新到文档.然后再来讨论需求和mvp”的指令记录。此处确定技术方向和复用边界，不代表产品需求、MVP 范围或实现已完成；默认学习语言已确认英语；NLP 方案与具体依赖版本仍待工程验证。
|
||
|
||
| 层次 | 采用方案 | 用途 |
|
||
|---|---|---|
|
||
| 页面与交互 | Vue 3、Composition API、TypeScript | 类型约束与交互组件 |
|
||
| 工程与构建 | 官方 create-vue + Vite | 创建学习端独立工程 |
|
||
| 路由 | Vue Router | 书库、阅读、词汇、复习等页面导航；页面范围待需求讨论 |
|
||
| 状态 | Pinia | 登录信息、阅读偏好等前端状态；服务端仍是业务状态主源 |
|
||
| 通用组件 | Element Plus | 表单、设置、弹窗等通用界面 |
|
||
| 领域界面 | 定制 Vue 组件 | 阅读器、划词、短语高亮、复习卡片 |
|
||
| 验证 | Vitest + Playwright | 组件/规则验证与浏览器学习闭环验证 |
|
||
|
||
创建方式是基于官方脚手架与成熟组件库开发学习业务，不是基于完整后台模板换皮。管理端基于 go-admin-ui 二次开发；后端基于配套 go-admin 扩展并复用适配后的身份/权限能力。LinguaCafe 继续提供需求与行为参考，未选定直接移植其前端代码。
|
||
|
||
参考依据：[Vue 官方创建指南](https://vuejs.org/guide/quick-start.html)、[Pinia](https://pinia.vuejs.org/introduction.html)、[Element Plus](https://element-plus.org/en-US/)。本轮只更新设计文档，尚未执行 create-vue、安装产品依赖或构建应用。
|
||
|
||
## MVP 定位确认与筛选边界
|
||
|
||
2026-09-10 用户接受多账号、数据独立、自托管及少量用户试用的定位，并要求从 LinguaCafe 提取候选需求。定位确认不表示旧 P0 或全部功能获批。F/X 候选、来源与最小验收统一维护在需求总览，当前筛选结果为 F01～F12；原型审核后再拆实施工单。
|
||
|
||
## MVP 功能范围确认
|
||
|
||
2026-09-10 用户确认 F01～F12 全部进入首版，X01～X14 暂不纳入；随后授权使用 Quant-UX 制作原型，并同意先建原型工单，原型审核后再拆实施工单。桌面和手机均覆盖；默认学习语言已确认英语。工程基础已实现待验收，其余范围沿用已验收原型。
|
||
|
||
原型站点为 https://qux.ilapage.cn/；v1 编辑源和预览统一见需求总览及工单 #1。用户要求减少页面说明、按目标页面呈现。账号配置不进入仓库。
|
||
|
||
默认学习语言：英语（用户于 2026-09-10 明确确认）。英语分词与本地词典资源仍需工程验证后固定版本。
|
||
|
||
|
||
## 原型验收与实施准备（2026-09-10）
|
||
|
||
用户已验收当前 Quant-UX 桌面/手机 v1，原型工单 #1 已关闭；结论见[验收记录](https://git.ilapage.cn/OPC/lexgo/issues/1#issuecomment-7498)。LinguaCafe 对照修订未执行，后续由划词验证工单承接，不将预设交互计作真实选择验证。
|
||
|
||
学习端与管理端均使用账号（用户名）＋密码登录，账号不要求邮箱格式；邮箱不作为必填登录标识。两端共用账号体系，管理权限由服务端单独校验。用户名唯一性和大小写规则在账号工单中细化。
|
||
|
||
[四阶段实施总览 #16](https://git.ilapage.cn/OPC/lexgo/issues/16) 已建立四阶段、14 张单元工单；详见需求总览与工作量估算。工程基础 #2 已实现并完成本地验证，等待用户验收：两端用户名登录、管理员创建/启停/重置学习账号、可撤销会话和本人英语空空间。阅读、导入、词典和复习尚未实现。代码在 feat/2-account-foundation 分支。
|
||
|
||
|
||
## 工程基础实际基线（#2，2026-09-10）
|
||
|
||
MySQL 服务端实际为 8.4.3，连接本机 127.0.0.1:3308；项目专用库 lexgo_dev、lexgo_test_issue2。连接凭据只存本机忽略的 .env.local；文档和 Git 不保存密码。已有非项目数据库未连接读写业务数据、未迁移。
|
||
|
||
Go 1.26.5 通过 Go 独立工具链下载并校验，系统 Go 1.24.0 保持不变；脚本只为子进程设置 GOTOOLCHAIN/GOSUMDB。Node 22.22.1，两个前端锁定 pnpm 9.15.1。管理端保留 Vue CLI/Vuex，学习端由官方 create-vue 3.23.0 生成，保留 Vue/TypeScript/Vite/Router/Pinia/Element Plus，实际包版本以各自 pnpm-lock.yaml 为准，不要求两端依赖版本一致。
|
||
|
||
server 是 go-admin 的选用模块接入：原样保留 SysUser、SysDept、必要 common/models 和 MIT 许可，新增 LexGo 路由、账号服务、会话与显式迁移；未接入整套后台路由、代码生成或任意任务执行。server/upstream.json 记录来源和文件摘要。admin/upstream.json 区分原样复用与适配的 go-admin-ui 布局、组件、页面和依赖，原始三个 go-admin 源工作区保持只读。
|
||
|
||
当前采用随机 Bearer 会话而非直接启用上游开发模式的超长 JWT。已验证退出、禁用、密码重置和到期拒绝；该差异是为满足当前可撤销会话要求，不宣称上游默认实现满足此要求。
|