diff --git a/AGENTS.md b/AGENTS.md index 0275073..539c0a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -258,10 +258,13 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - 治理模式：轻量。数据库：MySQL 8（用户于 2026-09-10 确认）；具体小版本在工程验证后锁定。 - 远端：https://git.ilapage.cn/OPC/lexgo.git；分支 main。不得把邻接 dev_harness 工作区当成本项目工作区。 -- 当前为需求和设计阶段，没有产品代码。管理端底座已确定为 D:/github_project/goadmin 的 go-admin/go-admin-ui；其运行兼容性、学习端方案、Python NLP 与首发语言仍待验证/确认，不能冒充批准的产品实现。 +- 当前为需求和设计阶段，没有产品代码。管理端底座已确定为 D:/github_project/goadmin 的 go-admin/go-admin-ui；学习端技术方向已记录为 Vue 3 + TypeScript + Vite 独立工程；运行兼容性、Python NLP 与首发语言仍待验证/确认，不能冒充批准的产品实现。 - 原四份研究保留为历史参考；PostgreSQL 建议被 MySQL 8 决策覆盖，U/A/N 索引用于追踪而不是批准所有范围。 - 用户/语言数据所有权、Unicode 原文位置、任务和复习幂等、完整备份恢复是后续方案的必要验收边界。 - 当前 MCP 连接其他 Gitea 站点，需使用目标站点 API 时记录原因；凭据仅从安全配置进入进程。 - DevHarness 基线 ecab8995026e57f2c28f307a6aa32b871cb3163f；工具保持原样，不为跳过门禁修改检查。 - 管理端采用用户指定的 go-admin/go-admin-ui，固定参考 commit 见项目档案；替换历史 gin-vue-admin 建议，不修改源目录，不直接复制源仓库配置或运行数据库。 + +- 学习端通过 create-vue 新建，采用 Vue Router、Pinia、Element Plus、Vitest + Playwright；与 go-admin-ui 分开构建，共用基于 go-admin 扩展的 Go 后端和 MySQL 8。阅读器、划词、短语与复习组件定制，未决定移植 LinguaCafe 前端。 +- 本轮先更新技术文档，再讨论需求和 MVP；技术方案不代表候选需求或阶段范围全部获批，不自动启动产品实现。 diff --git a/README.md b/README.md index 54fd18a..5ab2270 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 面向自托管场景的阅读式语言学习项目，规划提供内容导入、阅读查词、词汇与短语、复习和实例管理。 -已确认：**DevHarness 轻量模式、MySQL 8、go-admin 管理端**。当前是需求和设计阶段，没有产品代码；管理端使用 `D:/github_project/goadmin` 的 go-admin/go-admin-ui；配套构建、学习端方案、Python NLP 和首发语言仍待验证或确认。 +已确认：**DevHarness 轻量模式、MySQL 8、go-admin 管理端**。当前是需求和设计阶段，没有产品代码；管理端使用 `D:/github_project/goadmin` 的 go-admin/go-admin-ui；学习端采用 Vue 3 + TypeScript + Vite，独立工程、共用后端。配套构建、Python NLP 和首发语言仍待验证或确认；需求和 MVP 范围将在下一轮讨论。 - [文档入口](docs/README.md) · [线上 Wiki](https://git.ilapage.cn/OPC/lexgo/wiki/Home) - [项目档案](docs/00-project-profile.md) · [需求总览](docs/09-product-requirements-overview.md) diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 14f4d40..ba21271 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.- -wiki_revision: 4eec4c7e89156660392206ef5d1f3d8713845fe1 -synchronized_at: 2026-09-10T06:39:31Z +wiki_revision: 1afb0e6da6b5379ff5179b9b415c97543e86c369 +synchronized_at: 2026-09-10T06:49:54Z # LexGo 项目档案 @@ -13,7 +13,7 @@ synchronized_at: 2026-09-10T06:39:31Z 目标：围绕“导入内容 → 阅读查词 → 保存词语/短语 → 复习 → 查看进展”建设自托管语言学习 Web 应用。主要受众暂按学习者和实例管理员规划。 -现状：只有四份调研文档，无业务代码、依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 `.git`；本轮已连接确认的远端 `https://git.ilapage.cn/OPC/lexgo.git`，默认分支 `main`，已有引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。仓库归属 OPC，产品验收负责人为当前用户，具体长期维护分工尚未确定。 +现状：已有四份调研材料、项目主题文档和治理工具，无业务代码、产品依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 `.git`；本轮已连接确认的远端 `https://git.ilapage.cn/OPC/lexgo.git`，默认分支 `main`，已有引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。仓库归属 OPC，产品验收负责人为当前用户，具体长期维护分工尚未确定。 非目标暂按既有分析：商业 SaaS、多组织租户、课程商城、原生 App、完整离线同步、OCR、视频转写和 FSRS 改造均不包含在本轮基础估算。 @@ -29,7 +29,7 @@ LinguaCafe 参考基线由现有调研记录为 `c1ea298ce40c65b9dd33e9b26fd2e52 ## 子项目与交付单元 -当前独立交付物只有文档和治理工具。目标按一个产品版本、一个仓库规划：Go API/Worker、Vue 学习与管理界面、内部 NLP 服务；是否拆前端构建尚待确认。暂不创建不存在的产品目录或子项目规则。 +当前独立交付物只有文档和治理工具。目标按一个产品版本、一个仓库规划：基于 go-admin 扩展的共享 Go API/Worker、独立学习前端和独立管理前端；内部 NLP 服务暂为建议。学习端与管理端分开构建，共用后端与账号体系。暂不创建不存在的产品目录或子项目规则。 ## 技术栈与运行环境 @@ -42,9 +42,11 @@ LinguaCafe 参考基线由现有调研记录为 `c1ea298ce40c65b9dd33e9b26fd2e52 | D05 | 用户范围 | 暂按自托管普通用户+管理员，无组织租户 | 数据隔离和部署边界 | | D06 | 旧数据 | 全量迁移是否需要未确认，CSV 与完整迁移不同 | 迁移另估 | | D07 | 范围与交付 | 首版 P0、后续 P1/P2 为建议；人员、读者、运行环境未确认 | 排期可信度与验收 | +| 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/Gin、Vue 3/TypeScript、Redis 任务队列、Python NLP、Compose 为候选组合，具体版本和构建命令在 M0 验证后固定。不能同时按两种数据库承诺交付。 +数据库确定为 MySQL 8；管理端使用 go-admin/go-admin-ui；学习端方案与复用边界见 D09/D10。Redis 任务队列、Python NLP、Compose 仍为候选，具体版本和构建命令在技术验证后固定。不能同时按两种数据库承诺交付。 ## 阅读入口 @@ -78,4 +80,22 @@ LinguaCafe 参考基线由现有调研记录为 `c1ea298ce40c65b9dd33e9b26fd2e52 M0 在 LexGo 隔离工程中验证：指定前后端配套构建；MySQL 8 迁移与启动；登录、菜单和 API 权限；普通学习者的数据所有权隔离；用户区与管理区的身份衔接。管理 UI 的 dev/build 脚本使用类 Unix 的内联环境变量写法，Windows 执行方式需验证并最小适配，不假定 PowerShell 下直接成功。 -复用范围为通用管理界面及其配套 API/身份能力；阅读器、词汇、短语与复习仍需实现 LexGo 领域逻辑。管理端采用 Vue 3 不自动决定学习端构建方式。实际引入前核对代码和资源许可、排除本地配置及数据库等运行文件；按固定提交建立上游差异记录，后续升级先验证再更新基线。当前只完成选型记录，未宣称管理端已接入 LexGo。 +复用范围为通用管理界面及其配套 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、安装产品依赖或构建应用。 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 7dab349..9e7e57e 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.- -wiki_revision: 10e16ca5a1557c1508b94af113019c86c99edca2 -synchronized_at: 2026-09-10T06:39:32Z +wiki_revision: d9b2e822e6b3769fc6f6170074de580c71da2ae9 +synchronized_at: 2026-09-10T06:49:57Z # 架构与代码地图 @@ -44,3 +44,29 @@ Go 承担业务与后台任务，浏览器提供阅读学习界面，NLP 保留 管理端采用用户指定的 `D:/github_project/goadmin`，前后端固定 commit 见项目档案。后端现有入口为源仓库 main.go，业务分布于 app/cmd/common；管理前端入口为 go-admin-ui/src/main.js，页面位于 src/views，路由/API 封装位于 src/router、src/api。这些是外部参考仓库路径，尚未复制或运行于 LexGo。 M0 验证配套后再确定 LexGo 内部目录和身份衔接契约；通用管理能力可复用，用户与语言的数据所有权检查由业务层实现。既有分析中 gin-vue-admin 的推荐已被本次用户决策替代。 + +## 学习端与管理端的目标架构 + +技术方向已纳入本轮方案，以下是目标结构，尚无对应产品目录或可运行应用。 + +```mermaid +flowchart TD + L[学习端 Vue 3 / TypeScript / Vite] --> API[共享 Go API：基于 go-admin 扩展] + A[管理端 go-admin-ui] --> API + API --> B[独立学习业务模块] + B --> DB[(MySQL 8)] + B --> W[后台任务：具体选型待验证] + W --> N[NLP 服务：Python 方案待确认] +``` + +| 交付部分 | 建设方式 | 复用与自建边界 | +|---|---|---| +| 学习端 | create-vue 新建独立 SPA 工程 | 复用 Vue Router、Pinia、Element Plus；定制书库、阅读器、划词与复习组件 | +| 管理端 | 指定本地 go-admin-ui 二次开发 | 沿用现有 Vue CLI/Vuex 工程，按 LexGo 需要适配管理页面 | +| 共享后端 | 指定 go-admin 后端扩展为模块化单体 | 复用适配后的身份、权限与管理能力；新增 library、vocabulary、review、progress 等业务模块 | + +两个前端分别构建，共用账号体系、API 与数据库。角色权限和数据所有权分别校验，隐藏路由不能替代服务端授权。共享业务规则由后端维护；两端不各实现一套词汇或复习状态规则。 + +部署方向为同域名 `/app` 学习端、`/admin` 管理端、共享 API，首期不拆业务微服务。这些前缀是部署建议，具体网关、静态资源 base、路由回退和登录方式在接口/部署设计中验证后固定。学习端独立工程不要求单独部署后端。 + +先按浏览器响应式界面设计电脑与手机使用；PWA 保留为后续候选，完整离线同步不在本次技术确认中。最终页面和 MVP 范围将在后续需求讨论中确定。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 6916902..0f3d7e1 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.- -wiki_revision: 0497f11b18e9016dd70ee561cc225a46fcc678c3 -synchronized_at: 2026-09-10T06:28:59Z +wiki_revision: 71ede783b059584cdfd7e5b8c3076def704407f6 +synchronized_at: 2026-09-10T06:50:01Z # 本地开发与验证 @@ -81,3 +81,9 @@ rg -n -g '*.md' 'PowerShell' docs 示例预期：Python 输出 hello；Measure-Object 返回 Count 为 3；rg 返回当前文档中匹配 PowerShell 的行（有匹配时退出码 0，无匹配时为 1）。这些是 Shell 使用示例，不是产品测试命令。 + +## 学习端工程创建后的验证方向 + +学习端拟使用 create-vue + Vite，测试组合为 Vitest + Playwright；管理端保持指定 go-admin-ui 的现有工具链。当前未创建学习端工程，因此尚无可执行的产品 npm/pnpm 脚本。本轮技术方案记录不改变该事实。 + +正式工程建立时记录精确 Node/包管理器/依赖版本、锁文件、构建和测试命令；分别验证两端构建、共享登录/API 授权，以及阅读选择、Unicode 定位和学习闭环。具体测试范围依赖后续 MVP，不提前声称全部业务场景已有覆盖。 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md index f4b87eb..936c1ee 100644 --- a/docs/09-product-requirements-overview.md +++ b/docs/09-product-requirements-overview.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements-Overview wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.- -wiki_revision: fa9dbb8a07a83a6673e365fbbebb445e3ecc050e -synchronized_at: 2026-09-10T06:29:02Z +wiki_revision: 3878c6e9d1b24132c8a3f1f943d08f3d81d77266 +synchronized_at: 2026-09-10T06:50:11Z # 产品需求总览 @@ -68,3 +68,9 @@ synchronized_at: 2026-09-10T06:29:02Z ## 轻量修改边界 目标明确的局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构和权限的单模块调整可直接实施，完成必要验证后报告即可，不为了留痕补建工单。完整独立需求和中高风险变化仍需工单。 + +## 本轮技术决策与需求状态 + +2026-09-10 用户要求先记录已讨论技术方案，再讨论需求和 MVP。学习端采用 Vue 3 + TypeScript + Vite，通过 create-vue 新建独立工程，配套 Vue Router、Pinia、Element Plus、Vitest 和 Playwright；管理端基于指定 go-admin-ui 二次开发，共用基于 go-admin 扩展的后端及 MySQL 8。 + +上述决策只固定实现方向。当前 U/A/N 需求索引与 M0～M4 阶段仍是候选规划，不视为用户已批准全部 P0/P1/P2 或首版范围。不因技术选择自动创建实施工单或开始产品代码。下一轮讨论首先明确目标用户、学习场景、首发语言和必须成立的学习闭环，再裁剪 MVP。 diff --git a/docs/10-workload-estimate.md b/docs/10-workload-estimate.md index ce714ac..560f0d2 100644 --- a/docs/10-workload-estimate.md +++ b/docs/10-workload-estimate.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Workload-Estimate wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.- -wiki_revision: 3caa9a2e716608fc0626edb4ed33cea93d8ed5da -synchronized_at: 2026-09-10T06:39:40Z +wiki_revision: 2c07708c1b6b90d6d8c0a94d6f6adfc7917518c9 +synchronized_at: 2026-09-10T06:50:16Z # LexGo 开发工作量估算 @@ -86,3 +86,9 @@ W02/W03 可在契约确定后分工；W04 依赖它们的真实集成结果；W0 ## 管理端选型更新（2026-09-10） 用户指定本地 go-admin/go-admin-ui，替代早期 gin-vue-admin 推荐。W00 改为验证指定前后端 commit、工具链、MySQL 8 适配、认证与数据隔离；W01 在验证通过的配套版本上复用管理能力。不能仅因已选底座下调工作量：两套本地版本的构建、依赖与业务接入尚未实测。当前 60～100 人日首版及 140～250 人日总区间暂保留，M0 以实际结果重估，不把底座选择算作 W00 已完成。 + +## 学习端架构对估算的影响（2026-09-10） + +学习端使用 create-vue 新建 Vue 3 + TypeScript + Vite 工程，独立于管理端 go-admin-ui。通用路由、状态和组件可复用成熟库，但阅读器、划词、短语、复习界面仍需定制；后端共用 go-admin 的通用能力并新增学习模块。学习端不是现成管理页面换皮，也不包含直接移植 LinguaCafe 前端的承诺。 + +W00 后续需验证双前端与共享后端的接口/身份衔接、学习端构建及阅读交互；W04 的自定义阅读器工作量不能因存在 go-admin-ui 而扣除。原人日区间暂保留为待重新评估的规划量级，待需求和 MVP 范围讨论后更新，不视为已确认排期。本轮只记录技术方案，未消耗这些产品工作包的实施进度。 diff --git a/docs/README.md b/docs/README.md index 2a534c5..d081931 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,15 +2,15 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Home wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home -wiki_revision: c910a4d378fdcb4a99d3a6db57aebe5c0dbb1d32 -synchronized_at: 2026-09-10T06:39:30Z +wiki_revision: a172d5613dcb2de5dd2498dcdff4d0ccc552d80f +synchronized_at: 2026-09-10T06:49:53Z # LexGo 文档入口 ## 第一次阅读 -1. [项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)：已确认使用轻量模式、MySQL 8 和本地 go-admin 管理端；其余技术候选与范围状态。 +1. [项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)：已确认使用轻量模式、MySQL 8 和本地 go-admin 管理端；学习端采用 Vue 3 + TypeScript + Vite 独立工程；其余技术候选与范围状态。 2. [需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)、[工作量估算](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)：首版闭环与后续范围。 3. [架构与代码地图](https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-)、[业务规则](https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-)。 4. [开发工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)、[本地开发与验证](https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-)。