lexgo/docs/02-architecture-and-code-map.md

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: d9b2e822e6b3769fc6f6170074de580c71da2ae9 synchronized_at: 2026-09-10T06:49:57Z

架构与代码地图

项目定位

Go 承担业务与后台任务，浏览器提供阅读学习界面，NLP 保留独立边界是现有分析的建议。用户区与管理区共享身份服务，但功能权限与个人数据所有权分别校验。

代码地图

现有位置	内容	能证明什么
docs/01-LinguaCafe需求提取.md、docs/linguacafe-requirements.md	两份需求研究	参考需求与上游证据索引
docs/02-Go复刻与框架选型分析.md、docs/linguacafe-go-analysis.md	两份设计建议	候选方案，含未解决差异
docs/ 核心页面	Gitea Wiki 的单向镜像	仅文档与治理准备，不是产品实现
dev_scripts/harness.py、dev_scripts/wiki_docs.py	原样复制的 DevHarness 工具	治理工具入口，无业务 API
tests/	上游治理工具与文档结构测试	不验证阅读、NLP 或 SRS

不存在产品入口、数据库迁移或前端页面。拟定职责：identity（身份）、library（书库）、ingestion（导入）、lexicon（全局词典）、vocabulary（个人词语）、review（复习）、progress（统计）、administration（管理）。底座固定后再决定具体目录。

两条主要执行路径

目标路径一：上传文本 → 创建有所有者的导入任务 → 提取/分词/索引 → 章节就绪 → 阅读器按 token 展示原文和用户词语状态。

目标路径二：阅读保存词语或短语 → 写入个人学习状态与例句 → 查询到期词条 → 服务端计算作答后的状态 → 写入幂等事件 → 更新统计。

不可破坏的边界

• 词典资源与个人释义分离，共享缓存不能混入个人记录。
• Go/Python/JavaScript 的偏移契约必须统一；原文与内容版本必须保留。
• API 与 Worker 复用业务规则；NLP 通过明确契约调用，不泄露模型内部对象到前端。
• 任务至少可重试而不重复产出；学习事件不重复计数。
• 共享 API/NLP/状态契约在批准后的主题 Wiki 中建立唯一来源，字段和版本尚未定案；不能以本页概要直接生成冻结接口。

管理端选型落地边界

管理端采用用户指定的 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 的推荐已被本次用户决策替代。

学习端与管理端的目标架构

技术方向已纳入本轮方案，以下是目标结构，尚无对应产品目录或可运行应用。

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 范围将在后续需求讨论中确定。