lexgo/docs/00-project-profile.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.- wiki_revision: 08d992aee15b7fd5cea0cdbb4eb0b90583068449 synchronized_at: 2026-09-14T13:37:59Z

LexGo 项目档案

基本信息

目标：围绕“导入内容 → 阅读查词 → 保存词语/短语 → 复习 → 查看进展”建设自托管语言学习 Web 应用。MVP 定位已确认：支持多账号、数据独立的自托管学习工具，先邀请少量用户使用；主要角色为学习者和实例管理员。

现状：已有四份调研材料、项目主题文档和治理工具，无业务代码、产品依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 .git；本轮已连接确认的远端 https://git.ilapage.cn/OPC/lexgo.git，默认分支 main，已有引导提交 ecab8995026e57f2c28f307a6aa32b871cb3163f。仓库归属 OPC，产品验收负责人为当前用户，具体长期维护分工尚未确定。

非目标暂按既有分析：商业 SaaS、多组织租户、课程商城、原生 App、完整离线同步、OCR、视频转写和 FSRS 改造均不包含在本轮基础估算。

项目治理模式

轻量，依据 2026-09-10 用户明确指令。低风险局部调整直接实施；独立需求及中高风险变化建单；不为初始化强制拆 Epic/MVP。见工作流。

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	用户于2026-09-11确认正式产品全 Go；Python小样仅历史验证	使用词典词形候选，不承诺上下文消歧
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 仍为候选，具体版本和构建命令在技术验证后固定。不能同时按两种数据库承诺交付。

阅读入口

需求总览、代码地图、工作量。现有分析中的许可说明仅作资源评估线索，采用代码、词典、模型和素材前记录来源与实际许可；本轮不作新的法律结论。

常用命令

见开发与验证。产品构建、启动、测试和部署命令暂不存在，不用示例命令冒充实际可运行入口。

环境、配置与凭据

本地 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 官方创建指南、Pinia、Element Plus。本轮只更新设计文档，尚未执行 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 已关闭；结论见验收记录。LinguaCafe 对照修订未执行，后续由划词验证工单承接，不将预设交互计作真实选择验证。

学习端与管理端均使用账号（用户名）＋密码登录，账号不要求邮箱格式；邮箱不作为必填登录标识。两端共用账号体系，管理权限由服务端单独校验。用户名唯一性和大小写规则在账号工单中细化。

四阶段实施总览 #16 已建立四阶段、14 张单元工单；详见需求总览与工作量估算。工程基础 #2 已于 2026-09-10 通过用户验收：两端用户名登录、管理员创建/启停/重置学习账号、可撤销会话和本人英语空空间。阅读、导入、词典和复习尚未实现。代码在 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。已验证退出、禁用、密码重置和到期拒绝；该差异是为满足当前可撤销会话要求，不宣称上游默认实现满足此要求。

日志审计基线（#18）

管理端新增两个审计列表，后端为 LexGo 自有日志模型与接口，参照 go-admin 模块布局但不复制其原始参数/响应持久化逻辑。schema v2 新增 lexgo_login_logs、lexgo_operation_logs；保留 90 天，启动和每小时分批清理，也可显式 audit-cleanup。新建/重置密码均为 6～72 UTF-8 字节；初始 bootstrap 保留 10 字节下限。#2 已验收，#18 已验收；默认模块中的其他候选未纳入。

全 Go 正式架构决定（2026-09-11，#6）

用户已明确选择全 Go：正式英语分词、原文位置映射、本地词典解析和词形候选查询由 Go 后端完成，不运行 Python NLP 服务。此前“Python 建议/全 Go 未决”仅为历史决策记录，由本决定覆盖；spikes/english 保留历史验证，不接入产品。#6 按该方向实施，当前方案见工单最新启动评论；WordNet 3.0 仍为首个资源（英语释义），词形规则候选不等同于 spaCy 上下文消歧，原文及个人学习状态不按候选合并。

#6 当前工程状态（2026-09-11）

#5已验收且相关前置PR均已合入main。#6正式词典/点词查义已按全Go实现，已于2026-09-11通过用户验收，PR #25已合入main；server schema v4，管理端新增英语词典页，学习端加入Go分片及查词面板。正式Go进程不依赖Python NLP，WordNet包随数据库持久化。#3小样仍是历史验证；保存个人释义和状态归#7，音频封面#21、列表优化#24尚未实施。

#7 当前工程状态（2026-09-11）

#6已通过用户验收并合入main。#7个人词条、学习状态与阅读器高亮已按用户确认口径实现，并于2026-09-11通过用户验收，PR #26已fast-forward-only合入main；server schema v5新增lexgo_terms，学习端面板可保存释义、例句与状态并按状态高亮，同一词形在本人其他章节显示一致。个人释义与共享词典分离，且不进入审计日志。词汇库#12、短语#11、到期复习#8、进度#13、音频封面#21与列表优化#24尚未实施。

#8 当前工程状态（2026-09-11）

#7已通过用户验收并合入main。#8到期单词复习已按用户确认的决策表实现，并于2026-09-11通过用户验收，PR #27已fast-forward-only合入main；server schema v6新增lexgo_term_reviews（排期与计数）与lexgo_review_answers（作答记录），固定间隔1/2/4/7/15/30/60天，答对升级封顶7、答错降级最低1、再学一次不改等级，答错与再学立即回队，已知与忽略不入队。作答按answerId去重并以expectedDueAt判定过期标签页，重复提交、网络重发与双标签页都只记一次；到期判定用UTC绝对时刻，不引入本地日边界。独立审核（Claude Code）指出的并发同键500、编辑文本重排复习、面板保存重置等级三项已整改并复测。第3阶段「首条学习闭环」（#5～#8）至此全部验收；剩余#9～#15与#21、#24尚未实施。

#9 当前工程状态（2026-09-13）

#8已通过用户验收并合入main。#9 TXT文件导入已按用户确认的契约实现，并于2026-09-13通过用户验收，PR #28已fast-forward-only合入main；本单没有数据库结构变化，schema仍为v6。解码只接受UTF-8（可选BOM剥离且不进原文），非法字节整体拒绝、不使用替换字符，UTF-16按BOM识别后明确拒绝；文件字节上限2MiB并仍受单章100000码点约束；换行与空白不归一化。文件只在内存中解码，不创建临时文件，客户端文件名不参与任何路径也不入库。解码后交给既有PasteBook/PasteChapter，分章、任务幂等与恢复与粘贴一致。第4阶段已完成#9；剩余#10～#15与#21、#24尚未实施。

#10 当前工程状态（2026-09-14）

#9已通过用户验收并合入main。#10编辑与删除书籍章节已按用户确认的契约实现，并于2026-09-14通过用户验收，PR #29已fast-forward-only合入main；本单没有数据库结构变化，schema仍为v6。可改书名、章节标题与章节正文；只有正文变化才重新处理，重复保存或改回原内容不新建任务，只改标题不改变处理状态。版本门控按content_sha256执行：过期版本任务被标为superseded且完全不触碰章节，认领、恢复扫描与重试都按版本裁决，存储文本重算SHA与存储SHA不一致时按content_changed失败——这修掉了「处理中编辑导致新版本被标失败」的既有缺陷。删除为事务内硬删除加外键级联，删章后重排序号；个人词条、复习排期与作答记录不随删除清理。第4阶段已完成#9与#10；剩余#11～#15与#21、#24尚未实施。