feat: 接入两端用户名登录和独立学习空间 (#2)

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: 1c6333435f539af5253b18c563bce56bc336afc8
-synchronized_at: 2026-09-10T09:11:22Z
+wiki_revision: 51d40a6d4f7d0bcc0882bcd7d9c544aae964afa8
+synchronized_at: 2026-09-10T09:38:13Z
 <!-- gitea-wiki-mirror:end -->
 
 # 架构与代码地图
@@ -43,7 +43,7 @@ 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 的推荐已被本次用户决策替代。
+当前 #2 已固定首批 LexGo 目录和身份衔接契约；通用管理能力可复用，用户与语言的数据所有权检查由业务层实现。既有分析中 gin-vue-admin 的推荐已被本次用户决策替代。
 
 ## 学习端与管理端的目标架构
 
@@ -87,3 +87,38 @@ flowchart TD
 源码检查发现 common/actions/permission.go 允许关闭 EnableDP，且 DataScope 默认分支不添加过滤；该机制用于管理数据范围，不能单独保证私人学习数据隔离。学习接口必须强制按认证用户归属查询，不允许客户端指定用户替代认证身份。
 
 仅当管理流程引入多步安装、处理中/失败重试等明显交互不确定性时，补关键状态原型。通常的列表、编辑、删除确认沿用 go-admin 表格、表单和弹窗，记录字段、权限、异常和验收即可。
+
+
+## 已实现工程入口（#2）
+
+| 路径 | 职责 |
+|---|---|
+| server/cmd/lexgo/main.go | 配置连接、migrate/bootstrap/serve 命令；默认只监听 127.0.0.1:8000 |
+| server/app/admin/models、server/common/models | 按 upstream.json 原样选用的 go-admin 模型和约定 |
+| server/app/lexgo/database.go | MySQL 8 显式版本迁移、所有权标记、启动检查 |
+| server/app/lexgo/service.go | 用户名校验、账号创建、bcrypt、随机会话摘要和撤销 |
+| server/app/lexgo/router.go | JSON 请求、角色和归属授权、API 路由和安全错误响应 |
+| server/app/lexgo/*_test.go | 真实 MySQL 隔离、撤销、并发创建、迁移拒绝/恢复、bootstrap 验证 |
+| admin/src/views、admin/src/session.mjs | 基于 go-admin-ui 的账号页面与管理端会话 |
+| learner/src/views、learner/src/stores/session.ts | 独立学习端登录与私人空空间、会话及迟到响应隔离 |
+| scripts/server.py | 安全读取本机 .env.local，传入子进程；不输出秘密 |
+
+### 账号 API v1
+
+请求使用 JSON；受保护接口使用 Authorization: Bearer。成功结构 {code:200,data:...}，创建账号 HTTP 201；失败使用实际 HTTP 400/401/403/404/409/429/500 和 {code:状态码,msg:必要提示}。响应 Cache-Control:no-store。
+
+| 方法与路径 | 行为和权限 |
+|---|---|
+| POST /api/v1/login | username/password，返回 token、expiresAt、user；不要求邮箱 |
+| GET /api/v1/me | 当前登录者 id/username/role/disabled |
+| POST /api/v1/logout | 撤销当前会话 |
+| GET /api/v1/space | 当前用户英语空间；拒绝查询参数指定用户 |
+| GET /api/v1/spaces/:id | 仅本人的空间可读，他人编号返回 404 |
+| GET /api/v1/accounts | 管理员查看账号列表；只输出必要字段 |
+| POST /api/v1/accounts | 管理员创建 learner；拒绝客户端 role 等未知字段 |
+| PATCH /api/v1/accounts/:id | 管理员启停或重置 learner 密码；不能修改自己或其他管理员 |
+| GET /healthz | 检查数据库连接，仅返回健康状态 |
+
+schema v1：sys_user 保留选用 go-admin 模型字段，唯一小写用户名；lexgo_spaces 以 owner_id 为主键；lexgo_sessions 保存 token_hash/owner_id/expires_at；lexgo_schema 记录版本与产品所有权。服务启动不自动迁移。迁移仅接受空库或合法已有 LexGo marker，拒绝空 marker、其他产品、负版本与未来版本；版本 0 可重试部分迁移，版本 1 幂等。
+
+凭据字段只存在本地环境和必要数据库哈希中。后台账号密码更新使用表/字段更新，避免上游 BeforeUpdate hook 对已有哈希再次加密。账号行再会话行的锁顺序用于串行化撤销与请求；API 在事务提交后才返回成功。