diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md new file mode 100644 index 0000000..9aabdc9 --- /dev/null +++ b/docs/00-project-profile.md @@ -0,0 +1,59 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Project-Profile +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.- +wiki_revision: d5832ae249dabbf6ce2515ce350b3adc730fff46 +synchronized_at: 2026-09-10T06:27:39Z + + +# LexGo 项目档案 + + +## 基本信息 + +目标：围绕“导入内容 → 阅读查词 → 保存词语/短语 → 复习 → 查看进展”建设自托管语言学习 Web 应用。主要受众暂按学习者和实例管理员规划。 + +现状：只有四份调研文档，无业务代码、依赖锁文件、数据库结构或产品测试。首次盘点时没有本地 `.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`；本轮只整理已提供的调研，没有重新核验上游代码、依赖或许可。gin-vue-admin 尚未锁定提交，不能记为已采用工程基线。 + +## 子项目与交付单元 + +当前独立交付物只有文档和治理工具。目标按一个产品版本、一个仓库规划：Go API/Worker、Vue 学习与管理界面、内部 NLP 服务；是否拆前端构建尚待确认。暂不创建不存在的产品目录或子项目规则。 + +## 技术栈与运行环境 + +| 决策 ID | 议题 | 现有证据与状态 | 对估算的影响 | +|---|---|---|---| +| D01 | 工程底座 | 两份分析均建议评估 gin-vue-admin，也允许精简 Gin 路线；未批准 | 通用管理复用程度 | +| D02 | 数据库 | **已确认 MySQL 8**；依据 2026-09-10 用户原话“使用mysql8”。覆盖两份分析的数据库分歧，具体小版本待基线验证锁定 | 按单一 MySQL 8 数据层估算，不做 PostgreSQL 双库兼容 | +| D03 | NLP | 保留 Python 为建议，纯 Go 是否硬约束未确认 | 首发语言质量与开发量 | +| D04 | 首发语言 | 英语先行为估算假设，中文/日语需独立验收 | 分词、读音和 UI | +| D05 | 用户范围 | 暂按自托管普通用户+管理员，无组织租户 | 数据隔离和部署边界 | +| D06 | 旧数据 | 全量迁移是否需要未确认，CSV 与完整迁移不同 | 迁移另估 | +| D07 | 范围与交付 | 首版 P0、后续 P1/P2 为建议；人员、读者、运行环境未确认 | 排期可信度与验收 | +| D08 | Gitea | 已确认 `https://git.ilapage.cn/OPC/lexgo.git`，分支 main，工单与 Wiki 已启用 | 本轮发布核心 Wiki 并同步验证 | + +数据库确定为 MySQL 8。Go/Gin、Vue 3/TypeScript、Redis 任务队列、Python NLP、Compose 为候选组合，具体版本和构建命令在 M0 验证后固定。不能同时按两种数据库承诺交付。 + +## 阅读入口 + +[需求总览](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 安全配置或环境变量。 diff --git a/docs/01-LinguaCafe需求提取.md b/docs/01-LinguaCafe需求提取.md index 19ec9e6..3aac73e 100644 --- a/docs/01-LinguaCafe需求提取.md +++ b/docs/01-LinguaCafe需求提取.md @@ -1,3 +1,11 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: LinguaCafe-Requirements +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.- +wiki_revision: 240e5aae95507dda2e349fefc000add901c0189e +synchronized_at: 2026-09-10T06:27:49Z + + # LinguaCafe 功能需求提取 调研日期：2026-09-10。用途：作为 LexGo 使用 Go 复刻 LinguaCafe 的需求基线。 @@ -182,4 +190,4 @@ N08 是拟定目标，不是基准测试结果；不包含公网延迟、外部 | 字符与短语 | 中文、日文、重音字符、emoji、换行与重叠短语不造成错位或原文丢失 | | 备份 | 恢复后书籍数量、抽样词汇状态、用户设置与文件校验一致 | -需求提取已完成；具体范围取舍和框架方案见 [Go 复刻与框架选型分析](02-Go复刻与框架选型分析.md)。 +需求提取已完成；具体范围取舍和框架方案见 [Go 复刻与框架选型分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-)。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md new file mode 100644 index 0000000..342e55c --- /dev/null +++ b/docs/01-workflow.md @@ -0,0 +1,350 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Development-Workflow +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.- +wiki_revision: 972b8ceddedf00fa2d28a7441855fc4ad3db7c57 +synchronized_at: 2026-09-10T06:27:40Z + + +# LexGo 工作流适用说明 + +本项目明确采用轻量模式；下文其他模式仅供风险升级参考。MySQL 8 已确认，产品方案其余候选未定版。阶段表不是已批准工单。 + +# 开发工作流 + +## 事实来源边界 + +- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 +- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。 +- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。 +- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。 + +## 语言与术语 + +- 用户可以使用中文、英文或合理的中英混合语言提出需求和补充信息；Agent 不要求用户先翻译。 +- Agent 默认使用中文进行分析、回复、工单记录和内部项目文档维护。 +- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样，不做会影响搜索、复制、执行或排错的翻译。 +- commit、revision、middleware 等通用英文术语可以保留；可能影响初级维护者理解时，在首次出现处补充简短中文解释，不反复注释。 +- 用户明确要求某次回复、交付物或对外文档使用其他语言时，按该次明确要求执行；默认中文不是禁止其他交付语言的门禁。 +- 引用外部材料时保留必要原文并用中文说明结论；不得为了语言统一改写事实、错误信息或接口契约。 + +## Gitea 交互与工单最小读取 + +- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。 +- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。 +- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。 +- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。 +- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。 +- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。 +- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。 + +## 新项目 Wiki 初始化门禁 + +从 DevHarness 创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环： + +1. 先创建 Gitea 远端仓库并启用 Wiki，再把 `wiki-docs.json` 指向该仓库。 +2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。 +3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。 +4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。 +5. 运行 `python dev_scripts/harness.py sync --verify`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。 + +Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。 + +## 按治理模式选择最小门禁 + +使用 DevHarness 创建新项目时默认采用轻量模式。只有项目负责人明确选择标准或高风险模式，并在 Project-Profile 记录理由时，才改变项目默认模式；未明确填写时按轻量模式执行并提示补写，不因此阻塞产品开发。DevHarness 上游模板自身继续采用标准模式。单个任务风险高于项目默认模式时，只升级该任务，不抬高全部日常工作。不得为了流程完整而增加没有实际作用的工单、原型、文档或测试。 + +### 不可裁剪底线 + +任何治理模式都必须遵守： + +- 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界； +- 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要； +- 手机号等明确为虚构的测试数据无需形式化脱敏，但必须能与真实用户数据区分；来源不明时按真实个人数据处理； +- 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；授权有效时按下一节执行； +- 测试结果必须真实，未执行或无法覆盖的验证必须说明； +- 任务涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时按高风险处理；尚未获得有效授权时等待人工确认，已经获得时不重复确认。 + +### 明确授权后的执行 + +- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。 +- 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。 +- 获得有效授权后，Agent 只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。 +- 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。 +- 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。 +- 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。 + +### 先判断是否需要工单 + +| 治理模式 | 可直接实施 | 必须建单 | +|---|---|---| +| 轻量 | 文案、注释、格式、局部样式或布局；预期行为明确的小 Bug；不改变接口、数据结构、权限和安全边界的单模块低风险调整 | 完整独立需求、新页面或跨模块功能；API、数据结构、权限、安全、迁移；范围或预期不明确的变化 | +| 标准 | 纯文档措辞、格式化、内部标识符改名和确定不改变行为的小整理 | 新功能、缺陷修复、重构及用户可感知的行为变化 | +| 高风险 | 只读诊断和不会改变行为的文档整理 | 任何正式行为变化；按风险补充人工确认和验证 | + +直接实施项无需为了留痕补建工单，也无需填写工单模板；开始前只做必要的工作区和安全检查，完成最小测试后报告结果。无法确定是否符合直接实施条件时，先澄清或建单，不用代码行数代替风险判断。 + +### 再判断设计证据 + +- 轻量模式的小 Bug、局部样式或布局、复用现有规范的组件调整无需完整原型；能用一句话、现有界面或标注截图确认时即停止增加设计材料。 +- 完整独立需求、新页面、重大交互或导航变化需要工单；只有存在明显交互不确定性、用户明确要求，或返工成本显著时，才制作 Quant-UX 或其他可审阅原型。 +- 标准模式对新页面、独立用户功能和重大交互使用可审阅原型；小范围 UI 使用最低成本的文字、截图或低保真证据。 +- 高风险任务按影响补充技术设计、数据和权限边界、回退方案及人工确认；非 UI 任务不制作无意义的 UI 原型。 +- 恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。 + +### 线上原型审核与按需导出 + +需要完整原型时，默认通过 Quant-UX 或等效工具的可访问线上链接审核，记录可识别的版本和确认范围。只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则要求离线交付时，才导出到 `prototypes/<工单号>/<版本>/index.html`；不得把本地快照变成第二份可编辑事实来源。 + +页面结构、主要流程、权限、状态或异常处理发生影响验收的变化时，才更新设计证据并重新确认。设计工具无法生成用户明确要求的离线 HTML 时，记录限制并等待等效方案；线上版本可访问且可识别时不阻塞线上审核。 + +## 一次任务怎样完成 + +### 1. 讨论 + +用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。 + +### 2. 建单 + +方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。 + +新产品或较大版本先建立 Epic，再建立 MVP： + +```text +[Epic] 产品或长期目标 +└── [MVP] 第一个可交付版本 + ├── #101 单元任务 + ├── #102 单元任务 + └── #103 单元任务 +``` + +每个单元任务都应目标单一，能够独立测试、提交和回退。 + +#### 依赖与并行 + +建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明： + +- 前置工单，没有时填写“无”； +- 是否允许与未完成的前置工单并行； +- 判断可以或不可以并行的原因。 + +开始修改前，Agent 检查工单声明的前置工单： + +- 没有前置工单，或前置工单已经完成，可以进入“进行中”； +- 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”； +- 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因； +- 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。 + +依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。 + +### 3. 实施 + +Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。 + +重要进度及时写回工单： + +- 已确认的根因； +- 方案或范围变化； +- 测试结果； +- 阻塞和未验证内容； +- Git 提交哈希； +- 相关 Wiki 页面及 revision。 + +工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。 + +只有长期事实发生变化时才执行核心文档闭环： + +```text +修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像 +``` + +没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。 + +### 4. 待验收 + +实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。 + +### 5. 待验收和关闭 + +实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。 + +用户明确验收通过后： + +1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据； +2. 关闭单元工单并勾选所属 MVP/Epic 子任务； +3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki； +4. 默认不创建或导出任务归档。 + +任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行： + +```powershell +python dev_scripts/harness.py archive 123 "修复登录超时" +python dev_scripts/harness.py export # 增量导出已有归档 +python dev_scripts/harness.py export --all # 全量导出已有归档 +``` + +可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。 + +## 文档同步规则 + +- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。 +- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。 +- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。 +- 镜像头必须记录页面名、页面地址、revision 和同步时间。 +- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。 +- `sync` 和 `sync --check` 先读取一次页面列表，并用远端 revision 与本地镜像头比较；revision 未变化时不下载正文，只有页面新增、变化、元数据缺失或本地镜像元数据无效时才读取正文。 +- `sync --check` 是核心镜像的日常快速检查，不要求线上任务归档全部存在于本地；它验证 revision 和镜像元数据，不替代正文审计。 +- `sync --deep-check` 显式下载全部映射页面正文并逐页比较，用于疑似镜像损坏、同步算法审计或人工要求的完整核对。 +- `sync --verify` 用于新项目 Wiki 初始化门禁，完整读取并写入核心镜像后执行严格结构检查；同一次运行复用读取结果，不重复下载正文。 +- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。 +- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。 +- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。 +- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。 + +## 面向初级维护者的修改边界 + +| 风险 | 示例 | 处理方式 | +|---|---|---| +| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 | +| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 | +| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | + +风险由影响范围决定，不按代码行数判断。 + +## 每个任务的文档影响 + +单元任务必须明确选择： + +- 不影响长期文档，并说明原因； +- 更新项目档案或运行验证； +- 更新架构与代码地图； +- 更新业务规则与术语； +- 更新常见修改或故障排查； +- 新增或调整其他 Wiki 页面。 + +以下变化必须更新相关 Wiki： + +- 启动、测试、部署或排错命令变化； +- 模块入口、目录职责或主要调用路径变化； +- 配置项、API、数据结构或状态变化； +- 业务规则、安全边界或权限变化； +- 日志位置、错误定位或常见处理方式变化。 + +部署命令的落点：有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由[部署文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.-)复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。 + +普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。 + +## 需求记录与流转 + +聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录： + +- 原始需求的来源和提出时间； +- 能表达用户目的、使用场景和限制的少量关键原话； +- 整理后的目标、非目标、确认方案、验收标准和文档影响； +- 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。 + +只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 + +需求按以下边界流转： + +| 内容 | 事实来源 | 本地镜像 | +|---|---|---| +| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | +| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | +| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | +| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 | + +任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 + +## 稳定文档与可选历史快照 + +- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 +- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。 +- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。 +- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。 + +## 效率与范围控制 + +本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。 + +### 严格控制范围 + +- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。 +- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。 +- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。 +- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。 + +### 渐进执行和修复 + +- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。 +- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。 +- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。 +- 不在真实证据出现前堆叠与已知风险无关的预防性检查。 +- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。 + +### 复用已验证事实 + +- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。 +- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。 +- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。 +- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 + +### 明确停止条件 + +- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。 +- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。 +- 未影响当前验收的相邻问题只提示或建单，不顺手处理。 + +## 自然语言快捷指令 + +快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。 + +| 指令 | 执行动作 | 停止位置 | +|---|---|---| +| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 | +| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 | +| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” | +| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” | +| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | +| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | +| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 | +| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 | +| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 | +| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | +| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 | +| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 | + +补充边界： + +- 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。 +- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 +- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 +- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 +- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。 +- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。 +- 需要工单的任务以 Gitea 工单为单次任务事实来源，不导出全文；符合轻量模式直接实施条件的任务以用户确认范围、Git 提交和结果报告留痕，不补建工单。`docs/task/` 只保存人工明确要求的专项或历史兼容快照。 + +## 什么时候重新确认方案 + +以下变化必须重新确认；已有工单时先更新工单，直接实施项遇到这些变化时不再符合豁免，先建单再继续： + +- 交付结果或用户操作发生变化； +- 增加或删除接口、数据库字段或迁移； +- 安全边界、权限或不可逆操作发生变化； +- 原方案不可行，需要更换主要技术路线； +- 任务范围明显扩大； +- Wiki 页面删除、重命名或事实源边界改变。 + +普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。 + +## 工单、Wiki 与 Git 分别写什么 + +| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 | +|---|---:|---:|---:| +| 讨论过程和临时方案 | 是 | 否 | 否 | +| 实施进度和阻塞 | 是 | 否 | 否 | +| 长期有效的最终方案 | 链接 | 是 | 镜像 | +| 测试结果与未验证内容 | 是 | 否 | 否 | +| 提交哈希和验收结论 | 是 | 否 | 否 | +| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 | +| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/02-Go复刻与框架选型分析.md b/docs/02-Go复刻与框架选型分析.md index 2917238..bd49845 100644 --- a/docs/02-Go复刻与框架选型分析.md +++ b/docs/02-Go复刻与框架选型分析.md @@ -1,6 +1,14 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Go-Architecture-Analysis +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.- +wiki_revision: 4df1efc6cfb7a5e493501ce753a120065932271a +synchronized_at: 2026-09-10T06:27:50Z + + # 使用 Go 复刻 LinguaCafe：架构与二次开发选型 -调研日期：2026-09-10。状态：可供评审的技术建议，尚未进入编码实现。原项目证据、提交基线与需求 ID 见 [需求提取](01-LinguaCafe需求提取.md)。 +调研日期：2026-09-10。状态：可供评审的技术建议，尚未进入编码实现。原项目证据、提交基线与需求 ID 见 [需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)。 ## 1. 结论与适用前提 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md new file mode 100644 index 0000000..4425438 --- /dev/null +++ b/docs/02-architecture-and-code-map.md @@ -0,0 +1,40 @@ + +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: 2f5461e714febafd5a25b6e43f7cad635deaac05 +synchronized_at: 2026-09-10T06:27:41Z + + +# 架构与代码地图 + + +## 项目定位 + +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 中建立唯一来源，字段和版本尚未定案；不能以本页概要直接生成冻结接口。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md new file mode 100644 index 0000000..c2ee632 --- /dev/null +++ b/docs/03-business-rules-and-glossary.md @@ -0,0 +1,43 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Business-Rules-and-Glossary +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.- +wiki_revision: 014f3da14206e994d55fd32f9c75dbc7220af5f0 +synchronized_at: 2026-09-10T06:27:41Z + + +# 业务规则与术语 + + +## 核心术语 + +| 术语 | 含义与边界 | +|---|---| +| 书籍 / 章节 | 内容集合 / 可阅读处理单元；不限于小说 | +| 词典词条 | 共享查询资源，不等于用户保存释义 | +| 个人词语 / 短语 | 用户、语言与词条类型共同限定的学习项 | +| lemma | 词元/词形还原结果；不能擅自与原词合并学习状态 | +| SRS | 间隔复习；原版规则不应直接称为 FSRS | +| 练习 | 不改变复习调度的练习模式 | +| 轻量模式 | 裁剪流程，不能裁剪数据与验证底线 | + +## 工单状态 + +见[工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)；“代码完成”“AI 自测通过”和“人工验收通过”是不同状态。 + +## 稳定业务规则 + +此处“稳定”指准备纳入产品规则的候选语义，并非已批准或已实现： + +1. 同一用户、语言、词语跨章节应共享学习状态；不同用户互相隔离。 +2. 忽略与已知分开统计。原版内部 stage 为已知 0、忽略 1、新词 2、学习等级 1～7 对应 -1～-7；内部新设计可显式建模，互通时保留正确映射。 +3. 完成阅读关闭自动置已知开关时，不批量更改新词；重复完成不能重复累计。 +4. 服务端计算复习状态；到期、重学、跨日、时区、边界等级和重复作答要用固定时钟样例验证。 +5. 导入失败应可见、可重试，重试不产生重复章节或旧版本索引覆盖。 +6. CSV 缺列与显式空值语义不同；词汇 CSV 不承担全实例备份。 +7. 普通用户直接访问管理员 API 必须被拒绝；隐藏菜单不构成授权。 +8. 原文空白、标点、Unicode 与位置可还原；词语身份、短语重叠优先级和规范化规则需批准后固定。 + +## 新项目需要补充什么 + +M0 固定首发语言语料、词条身份规则、短语选择与重叠规则、SRS 对照样例、时区边界、管理员可见范围、删除级联和恢复口径。性能目标 N08 仅为候选指标，需按硬件、词典和并发数据实测后定版。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md new file mode 100644 index 0000000..dd31a4a --- /dev/null +++ b/docs/04-local-development-and-verification.md @@ -0,0 +1,43 @@ + +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: 205b5548e0c2b30a4dd517c9e4cfcef0b823223e +synchronized_at: 2026-09-10T06:27:42Z + + +# 本地开发与验证 + +## 环境要求 + +当前工作区为 Windows PowerShell，文档工具使用 Python 3。产品 Go、Node、MySQL 8 小版本、Redis、NLP 和模型版本在 M0 锁定，尚无产品运行环境。 + +## Windows PowerShell 与 UTF-8 + +读中文使用 `Get-Content -Encoding utf8`，复杂路径使用 `-LiteralPath`。Python 输出可设置进程 `PYTHONIOENCODING=utf-8`；文件解码与终端显示分别处理。不得打印凭据。 + +### PowerShell 语法与外部命令 + +不要套用 Bash heredoc；Python 脚本可用单引号 here-string。通过 `$LASTEXITCODE` 检查外部命令，使用原生 PowerShell 路径操作，避免跨 shell 拼接。 + +## 第一次运行 + +从仓库根目录执行： + +| 命令 | 预期与边界 | +|---|---| +| `python dev_scripts/harness.py --help` | 退出码 0，列出工具命令 | +| `python dev_scripts/harness.py check --strict` | 退出码 0，正式主题结构与镜像元数据完整；不单独证明线上状态 | +| `python dev_scripts/harness.py sync --verify` | 从配置目标读取并同步全部映射页面，再严格检查，预期退出码 0 | +| `python -m unittest discover -s tests -v` | 全部治理测试通过，不证明阅读器、NLP、SRS 已实现 | +| `git status --short --branch` | 显示分支与待提交变化，提交后应无意外改动 | + +同步会保护已有未提交镜像改动。新项目首次导出前先保存原有资料并提交引导材料；不跳过脏文件检查。凭据只通过安全配置或环境变量 `GITEA_TOKEN` 提供，不进入命令文本、日志或 Git。当前 MCP 连接其他站点，使用 API 的原因见初始化记录。 + +## 常用调试方式 + +先处理第一个可定位错误。页面缺失先发布、回读，不伪造 revision；配置错误先核对 owner/repository。产品阶段按用户/语言、任务、API、Worker/NLP 和数据文件逐层追踪，日志避免个人正文和凭据。 + +## 完成修改前 + +文档检查来源、链接、事实/建议区分和工作量加总；工具运行受影响的现有测试。产品阶段按具体工单测试隔离、Unicode、幂等、复习或恢复，未执行部分如实记录。当前没有 go.mod、package.json 或 Compose，不能声称产品能启动。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md new file mode 100644 index 0000000..15dee92 --- /dev/null +++ b/docs/05-common-changes.md @@ -0,0 +1,30 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Common-Changes +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Common-Changes.- +wiki_revision: 168796cda21f6e0dacc9a3d44cf053caf38044e4 +synchronized_at: 2026-09-10T06:27:43Z + + +# 常见修改 + + +## 风险分级 + +文案或明确的局部样式走轻量直接实施；新增导入器、阅读页面、词条身份变化、SRS 算法、权限与迁移均需单元工单和对应设计。 + +## 修改 Wiki 文案 + +先改线上主题页、回读，再同步核心镜像。旧草稿只用于本轮整理，不再作为后续编辑入口。两份原始调研分歧在项目档案 D01～D08 登记，不能靠删除一份来“解决”。 + +## 调整 Harness 检查 + +先判断是文档不完整、远端缺失还是工具问题。工具来自固定上游基线，不为通过检查移除镜像或线上回读门禁。真实工具改动单独记录上游差异，并运行治理工具测试。 + +## 看懂 Agent 的修改 + +先看目标和状态，再看文件差异、测试证据、未验证部分及回退方法。没有产品代码时，架构图或目录建议只能证明已做设计。涉及数据或状态的修改必须能解释一个具体输入经过修改后的输出。 + +## 产品阶段的常见入口 + +新增词典先定义格式/许可/语言/错误报告再实现 lexicon；新增导入源先定义限制与重试语义再实现 ingestion；修改复习先固定状态转换样例再实现 review。具体路径在工程创建后更新，不把规划模块当作存在的文件。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md new file mode 100644 index 0000000..ea0657b --- /dev/null +++ b/docs/06-troubleshooting.md @@ -0,0 +1,24 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Troubleshooting +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting +wiki_revision: c202a8adb9b720981761e07f52fb7c0033d6d7d2 +synchronized_at: 2026-09-10T06:27:43Z + + +# 故障排查 + +## 排查顺序 + +| 现象 | 判断与处理 | 成功条件 | +|---|---|---| +| 没有产品启动入口 | 当前仅文档阶段，先完成 M0 和工程创建 | 有真实构建/运行命令后更新验证页 | +| MCP 看不到 LexGo | 当前 MCP 指向其他站点；以用户确认的 git.ilapage.cn 为准 | API 能读取 OPC/lexgo | +| 新 Wiki 列表 404 | 先确认仓库存在且 has_wiki=true；未初始化时创建 Home 并回读 | Home 有正文和 revision | +| sync 拒绝脏镜像 | 检查并保存合法本地修改，不覆盖现有改动 | 提交/妥善保存后重试 | +| check 缺少标题或映射 | 补齐真实主题和显式映射 | check --strict 通过 | +| 数据库方案冲突 | 用户已确定 MySQL 8，历史 PostgreSQL 建议被覆盖 | 档案和新方案一致 | + +## 必须停止的情况 + +目标仓库身份不清时停止远端写入；页面无法回读、无 revision 或同步失败时停止产品编码。数据越权、破坏性操作超出授权时停止相关操作。独立文档整理可以继续。 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md new file mode 100644 index 0000000..66076eb --- /dev/null +++ b/docs/07-new-project-documentation-setup.md @@ -0,0 +1,258 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: New-Project-Documentation-Setup +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.- +wiki_revision: 1f84d8d38a6052120351da56639d88b70e99f58f +synchronized_at: 2026-09-10T06:27:44Z + + +# LexGo 初始化记录 + +## 本项目状态与证据边界 + +2026-09-10 用户确认远端 `https://git.ilapage.cn/OPC/lexgo.git`；main 已有 DevHarness 引导提交 `ecab8995026e57f2c28f307a6aa32b871cb3163f`。本轮将本地 LexGo 连接此远端，保留原调研，发布项目主题和工作量，再执行同步与验证。数据库 MySQL 8、治理轻量已确认，产品代码尚未开始。 + +本轮使用 Gitea API 的原因：已配置 MCP 连接 `ilaer.eicp.net:8418`，目标却是 `git.ilapage.cn`，MCP 无法操作该目标。先用目标站点安全配置验证身份和仓库，凭据只读入进程；不复制到代码、日志、工单或 Wiki。目标仓库已启用工单/Wiki，初始页面列表返回 404；先创建 Home 并回读 revision 后才创建其他页面。 + +发布准备、正文回读、同步校验和产品验收是不同证据。最终本地命令与结果见 Git 提交说明及本轮结果报告；不能把工具单测中的模拟 Wiki 输出当真实线上状态。 + +现有 docs/task 内容属于上游模板历史，不作为 LexGo 的任务完成记录，也不带入项目镜像。原有四份调研分别作为参考页面保留，数据库分歧以 MySQL 8 决策为准。未创建无实际作用的 Epic/MVP 或任务快照。 + +当前交付对象为负责人和开发维护者，交付规划、规则和估算。尚无产品部署实例；部署模板仅供后续环境确认后使用，不预建可运行运维手册。 + +## 后续产品步骤 + +完成本文的 Wiki 门禁后，按已确认目标组织 M0 技术验证；工程底座、Python NLP、首发语言与旧数据范围仍需在方案中明确，不把“继续文档初始化”视为整份产品方案批准。 + +以下为本项目沿用的 DevHarness 初始化规范，示例不代表 LexGo 已执行产品开发。 + +# 新项目文档初始化 + +## 本页用途 + +从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。 + +## 初始化顺序 + +### 1. 建立项目边界 + +由项目负责人确认： + +- 项目名称和一句话目标； +- 用户和主要使用场景； +- 技术栈和支持环境； +- Gitea 仓库、默认分支和维护者； +- 安全、权限、数据和发布红线。 + +把项目专用红线写入根目录或子目录 `AGENTS.md`。 + +#### 选择治理模式 + +使用 DevHarness 创建新项目时默认采用轻量模式，并在 Project-Profile 记录实际模式和理由： + +- 目标项目尚未填写治理模式时按轻量模式执行并提示补写，不因此阻塞产品开发；从模板继承的“DevHarness / 标准”文字不代表目标项目已经选择标准模式； +- 轻量模式尤其适合内部、单人、低风险项目，但默认值不限制后续按真实风险升级； +- 只有项目负责人明确选择并记录理由时，才将项目默认值改为标准或高风险； +- 多人协作、对外交付、跨模块接口较多或需要稳定审计时，可以明确选择标准模式； +- 项目整体持续涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时，可以明确选择高风险模式； +- 单个任务风险高于项目默认模式时只升级该任务，不自动升级整个项目；不为可能发生的情况预设额外门禁； +- DevHarness 上游模板自身继续采用标准模式。 + +治理模式只裁剪工单、原型、测试和文档流程，不覆盖凭据、授权边界和真实测试证据。使用虚构手机号等测试数据时记录其为虚构数据即可，无需为了形式执行脱敏流程；来源不明或来自真实用户时按已确认的数据处理规则执行。 + +#### 需求总览启用条件 + +从模板创建项目时保留 Product-Requirements-Overview 这一核心页面。仅有探索性想法时可以只记录已确认目标和待确认项；形成 MVP、长期需求超过少量工单或开始制作原型时，必须建立并持续维护需求索引，把需求领域、状态、主题 Wiki、工单、原型和验收入口关联起来。不要复制完整工单或聊天记录。 + +### 2. 选择建设基线 + +确定技术方案前，优先评估是否存在功能和架构匹配、持续维护、许可证兼容且工程流程完善的开源项目。这里要求的是“先评估”，不是强制采用开源项目，也不能只根据知名度、Star 数量或演示效果决定。 + +至少检查： + +- 核心功能、架构和支持平台是否匹配，哪些能力可以直接保留； +- 许可证是否允许预期的使用、修改、分发和商业模式；不确定时交由负责人或法律专业人员确认； +- 最近维护活跃度、发布频率、Issue 处理和社区或维护团队的持续性； +- 已知安全问题、依赖健康度、供应链风险和安全响应方式； +- 自动化测试、CI、发布、升级、回退和文档是否足以支持长期维护； +- 定制、学习、迁移和后续跟踪上游的总成本是否低于从零开发； +- 是否能够固定上游仓库和基线版本，并建立合并上游更新、兼容验证和退出方案。 + +满足适配、许可证、安全、维护和总成本条件时，优先在该基线上二次开发。不存在合适基线，或引入后会增加不可接受的许可证、安全、架构或维护风险时，可以从零开发，但必须记录排除候选项目和选择从零开发的主要原因。 + +采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。 + +#### 工程基线裁剪 + +所有项目采用最小工程基线，不按项目规模免除事实和验收要求： + +- 用完整 Git commit 和核验日期固定“当前事实”的代码基线； +- 分开记录“当前已经实现什么”和“目标规范要求什么”，不得用目标描述宣称现有能力； +- 写明证据路径、可确认行为、未覆盖范围和证据不能证明什么； +- 明确目标、非目标、安全边界和可判定的验收标准； +- 跨子项目接口或契约指定唯一事实来源和各端验证命令。 + +当前事实以指定 commit 的代码、可执行测试和运行证据为依据；目标行为以人工批准的契约、ADR 和业务规则为依据。两者冲突时登记为带编号的差距或缺陷，不允许现有错误实现覆盖目标规范，也不允许目标设计冒充当前实现。 + +出现跨团队或跨仓库协作、外部交付、接口或状态机复杂、权限安全、迁移并发、明显文档漂移等情况时，采用增强工程基线：按需增加 GAP-ID 差距表、带状态的 ADR、接口与数据契约、需求追踪测试矩阵，以及 PR、RC、Definition of Done 分层门禁。SRS、SAD、安全、运维和测试文档按风险与读者选择，不强制小型单人项目建立完整文档集。 + +#### 判断案例 + +以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。 + +##### 案例一：适合基于成熟项目二次开发 + +计划开发企业内部管理系统。候选项目已经具备用户、权限、审计日志、基础数据管理和自动化测试；功能与目标架构基本匹配，许可证允许预期使用，项目持续维护，发布与升级流程完整，预计只需修改业务模块和界面。 + +- 结论：优先基于该项目二次开发。 +- 原因：可以减少通用功能的开发和验证成本，定制范围可控。 +- 记录：上游仓库、基线版本、许可证、保留功能、定制模块和上游升级方式。 + +##### 案例二：项目成熟但许可证不兼容 + +候选项目功能完整、维护活跃、文档充分，但许可证与当前产品的闭源分发、商业模式或交付条件不兼容。 + +- 结论：不采用该项目作为建设基线。 +- 原因：技术成熟度不能消除许可证风险；不确定结论必须交由负责人或法律专业人员确认。 +- 记录：候选项目、许可证限制、确认人员和排除原因。 + +##### 案例三：功能相似但改造成本过高 + +候选项目表面上覆盖大部分功能，但数据模型、权限体系和部署结构与目标项目差异很大，需要大量删除模块、重写主要接口，并长期维护上游冲突。 + +- 结论：不直接基于完整项目二次开发，可以评估只复用合适的组件或设计思路。 +- 原因：二次开发的总成本、理解成本和长期维护风险已经高于自主实现核心业务。 +- 记录：主要结构差异、改造估算、长期维护风险和最终选择。 + +##### 案例四：只复用成熟框架或组件 + +没有功能高度匹配的完整开源产品，但存在成熟的应用框架、更新组件、日志组件或通信库。 + +- 结论：从零开发业务功能，同时复用经过评估的成熟框架或组件。 +- 原因：复用基础能力不等于必须采用完整产品，可以避免被不匹配的业务架构绑定。 +- 记录：每个依赖的用途、版本、许可证、安全边界、升级方式和可替换方案。 + +每个案例的实际评估都必须记录候选项目、判断依据、最终选择、未采用原因，以及升级或退出方式。 + +### 3. 识别子项目与交付单元 + +先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认： + +- 职责和目录边界； +- 技术栈、依赖和支持环境； +- 构建、测试和运行命令； +- 是否拥有独立版本号和发布方式； +- 适用的根目录或子目录 `AGENTS.md`； +- 与其他子项目共享的接口、数据或业务流程； +- 共享契约的唯一事实来源和兼容要求。 + +把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。 + +### 4. 建立 Gitea + +创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。 + +引导提交后按项目明确选择的治理模式判断是否需要工单；尚未选择时按轻量模式执行并提示补写，不因此阻塞产品开发。轻量模式的明确小 Bug、局部 UI 和单模块低风险调整可以直接实施；完整独立需求、新页面、跨模块功能和中高风险变化必须先有单元任务工单。开始产品代码前仍须通过第 8 步的线上 Wiki 初始化门禁。 + +### 5. 修改镜像配置 + +把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。 + +确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 + +不要把 PAT 写入配置。 + +### 6. Agent 检查项目事实 + +Agent 只读检查： + +- README、配置和依赖文件； +- 启动入口； +- 主要模块和目录规则； +- 测试、格式和静态检查命令； +- 日志、示例配置和测试数据； +- 已存在的接口、数据模型和状态。 + +区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 + +### 7. 确定交付对象和文档 + +由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定： + +- 需要完成的工作； +- 所需文档类型； +- 文档可见范围； +- 适用版本、负责人和验证人； +- 不得对外披露的内部信息。 + +按照[交付文档指南](https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。 + +### 8. 先创建线上 Wiki + +#### 在线创建与回读门禁 + +1. 使用配置好的 Gitea MCP 查询目标仓库的 Wiki 页面列表；MCP 不可用时使用 Gitea API，并记录回退原因。 +2. 如果 `Home` 不存在，先创建 `Home`。创建后立即在线回读正文并记录 revision；`Home` 可读取后才能继续。 +3. 依照 `wiki-docs.json` 逐页创建或更新其他核心页面。每页写入后在线回读正文，记录页面名和 revision。 +4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `harness.py check --strict` 通过，都不能单独证明线上 Wiki 已初始化。 +5. 页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码；Gitea 恢复后从首个失败页面继续。 + +至少创建或填写： + +1. Home； +2. Project-Profile； +3. Product-Requirements-Overview； +4. Architecture-and-Code-Map； +5. Business-Rules-and-Glossary； +6. Local-Development-and-Verification； +7. Common-Changes； +8. Troubleshooting； +9. Development-Workflow； +10. Delivery-Documentation-Guide； +11. Audience-Document-Template； +12. Task-Archive-Template。 + +Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。 + +部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制[部署文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.-)在本项目 Wiki 建立 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）；确认没有常驻服务时，在初始化工单记录原因，不创建该页面。 + +### 9. 人工确认 + +项目负责人至少确认： + +- 一句话目标和业务术语； +- 关键业务规则和状态； +- 权限、安全和数据边界； +- 真实运行、测试和部署命令； +- 本项目是否有需要部署的常驻服务； +- 哪些修改属于高风险； +- 交付对象、文档可见范围和外部信息边界。 + +### 10. 导出镜像并检查 + +```powershell +python dev_scripts/harness.py sync --verify +python -m unittest discover -s tests -v +``` + +只有线上 Wiki 确认后才导出核心 `docs/`。默认不创建或导出任务归档；用户明确要求专项快照时才运行 `archive`、`export` 或 `export --all`。旧项目的任务归档快照不能带入新项目历史。 + +`harness.py sync --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。 + +## 完成标准 + +初级程序员应能仅依靠 Home 和链接页面回答： + +- 项目解决什么问题； +- 当前有哪些长期需求、状态如何，详细规则、工单、原型和验收入口在哪里； +- 怎样启动和运行测试； +- 常用功能从哪个目录和入口开始读； +- 一个简单修改通常要改哪里、验证什么； +- 哪些情况必须停止并交给 Agent 或负责人； +- 项目采用哪个建设基线，为什么适合二次开发，或者为什么选择从零开发； +- 采用开源基线时，上游仓库、基线版本、许可证、定制范围和升级策略是什么； +- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布； +- 跨子项目共享什么接口或契约，其唯一事实来源在哪里； +- 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。 + +回答不了的问题应继续补充主题文档，而不是堆入任务归档。 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md new file mode 100644 index 0000000..a4c979a --- /dev/null +++ b/docs/08-existing-project-adoption.md @@ -0,0 +1,236 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Existing-Project-Adoption-Guide +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Existing-Project-Adoption-Guide.- +wiki_revision: 974238bcadff9718faf8b368b7e883c77670954b +synchronized_at: 2026-09-10T06:27:45Z + + + +# 已有项目接入 DevHarness 指南 + +## 本页用途 + +本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。 + +接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。 + +## 与新项目初始化的区别 + +| 场景 | 新项目初始化 | 已有项目接入 | +|---|---|---| +| 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 | +| 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 | +| 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | +| 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | +| Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | +| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 | +| 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | + +从模板创建全新仓库时使用[新项目文档初始化](https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 + +## 接入前只读盘点 + +Agent 在提出方案前只读检查： + +- 根目录和相关子目录中的 `AGENTS.md`、`CLAUDE.md` 及其他 Agent 规则； +- README、现有 `docs/`、Wiki 页面、工单模板和任务状态； +- Git 默认分支、远端、提交历史、未提交修改和忽略规则； +- 语言、框架、依赖、启动入口、主要模块和目录职责； +- 格式检查、静态检查、单元测试和必要集成测试命令； +- 配置、日志、接口、数据模型、权限、安全、部署和发布边界； +- 已完成、进行中、阻塞和待验收任务； +- 现有长期文档的事实来源、负责人和更新方式。 + +输出时区分： + +1. 从代码、配置或现有系统确认的事实； +2. 项目负责人确认的业务规则； +3. 尚待确认的假设； +4. DevHarness 与现有规则的冲突； +5. 与接入无关、必须保留的工作区改动。 + +只读盘点不授权修改文件、创建 Wiki、迁移文档或改变工单状态。 + +## 已有内容保护原则 + +- 保留 Git 历史、分支、标签和当前任务状态。 +- 保留已有 `AGENTS.md`、README、规则和项目专用红线；DevHarness 规则按冲突结果增量合并。 +- 保留与接入无关的未提交改动，不重置、不覆盖、不混入提交。 +- 不复制 DevHarness 的 `docs/task/`、任务归档映射和历史工单。 +- 不因采用 Wiki-first 就立即删除原本地文档；先逐页确认事实来源和迁移状态。 +- 不把模板占位值当成项目事实，不臆造技术栈、命令、业务规则、凭据或环境。 +- 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。 +- 页面删除、重命名、历史清理和事实来源切换必须单独确认。 + +## 多应用单仓库判断 + +一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由；先把每个子项目和交付单元记录到 Project-Profile，再根据实际协作边界判断。 + +### 适合继续单仓库 + +- 多个应用共同完成一条产品或业务链路； +- 由同一团队维护，仓库权限基本一致； +- 接口变更需要在一个工单中同步修改或验证多端； +- 共享契约和业务规则由同一项目维护并指定唯一事实来源； +- 仓库体积、测试时间和工具性能尚未明显影响开发； +- 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。 + +### 可以考虑拆仓 + +- 长期由不同团队独立负责并需要不同访问权限； +- 发布周期、版本策略和验收负责人已经完全独立； +- 某个应用被多个产品复用或需要单独对外提供； +- 仓库体积、检出、索引或测试耗时已经持续影响效率； +- 共享接口已经版本化、兼容周期明确，并有跨仓契约测试； +- 跨应用任务很少，拆仓后的协调成本低于继续共仓。 + +不满足这些条件时，优先保持单仓库并完善边界，不为了目录整洁或技术栈不同而拆仓。 + +### 保持单仓库时的最小规则 + +- 根目录 `AGENTS.md` 只放共同流程、安全和跨项目规则，技术栈专用规则写入子目录 `AGENTS.md`。 +- 每个交付单元拥有自己的构建、测试、版本和发布方式，不强制统一版本。 +- 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口，以及各端需要执行的验证。 +- 共享接口或契约只能指定一个事实来源；其他文档引用它，不复制一个“差不多”的版本。 +- 跨子项目契约变更在同一工单中更新事实来源，并验证所有受影响端。 +- 拆仓属于事实来源、任务和发布边界变化，必须另建工单、确认迁移和回退方案后实施。 + +## 增量接入顺序 + +### 1. 确认差异方案 + +根据盘点结果列出目标、非目标、复用项、改写项、冲突项、影响范围、风险、回退、验证和文档影响。方案得到用户明确确认前不实施。 + +### 2. 建立单元任务工单 + +使用目标项目的 Gitea 建立接入工单，记录原始需求、范围、依赖、方案和验收标准。目标项目没有可用 Gitea 时，先提交完整工单草稿并说明阻塞，不默认绕过。 + +### 3. 接入共同规则和工单流程 + +优先增量合并根规则、Claude 入口和单元任务模板。项目专用安全、业务和目录规则继续有效；冲突时由负责人决定最终表述。 + +### 4. 确定长期文档事实来源 + +为每份已有文档标记： + +- 保留在 Git：与特定代码版本强绑定； +- 迁移到 Wiki：长期架构、业务规则、开发规范或操作说明； +- 合并：内容重复但各有有效事实； +- 暂不迁移：事实未确认或当前不影响接入； +- 停止维护：必须由负责人确认，不能由 Agent 自行删除。 + +切换到 Wiki-first 的页面必须先在线上创建或更新、读取确认，再建立 `wiki-docs.json` 映射并导出本地镜像。避免 Wiki 和手写本地文档长期形成双事实源。 + +### 5. 接入 Harness 工具 + +仅复制当前项目实际需要的 `dev_scripts/` 工具、配置和测试。业务脚本使用独立目录。根据目标项目调整核心页面、路径、命令和结构检查，不照搬 DevHarness 项目值。 + +### 6. 分阶段验证 + +先验证工单和规则入口，再验证 Wiki 映射，最后启用严格检查。每阶段采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环，不用一次接入全部旧文档。 + +### 7. 提交和验收 + +提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。 + +## 后续升级 + +已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。 + +### 升级步骤 + +1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。 +2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。 +3. 只读比较与 Harness 有关的 `AGENTS.md`、`CLAUDE.md`、工单模板、`dev_scripts/`、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。 +4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。 +5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。 +6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 `docs/` 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。 +7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。 +8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。 + +### 升级停止条件 + +除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。 + +### 可复制升级指令 + +```text +请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到 +。 + +先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目 +适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及 +风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git +历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在 +当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。 +工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。 +``` + +路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。 + +## 冲突处理和停止条件 + +出现以下情况时停止实施并请求负责人确认： + +- 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突； +- 无法判断某份文档应该保留、迁移、合并还是停止维护； +- 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档； +- 需要改变接口、数据库、权限、部署、发布或其他产品行为； +- 工作区存在可能与接入文件重叠的未知修改； +- Gitea、Wiki、凭据或远端权限不可用； +- 真实命令、环境或业务规则无法从证据或负责人确认。 + +相邻问题最多提示或另建工单，不混入接入任务。 + +## 可复制 Agent 指令 + +### 只分析 + +```text +请把 的文档模板和开发流程接入当前已有项目。 + +先只分析，不修改文件、工单或 Wiki： + +1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、 + 新项目文档初始化和已有项目接入指南。 +2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、 + Wiki 配置、代码入口、测试命令和目录结构。 +3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。 +4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、 + 最小接入范围、风险、回退、验证和文档影响。 +5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容， + 不把模板占位值当成项目事实。 +6. 输出方案后停止，等待我确认。 +``` + +### 方案确认后实施 + +```text +按照已确认方案建工单并做。 + +严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 +任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 +本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后 +保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。 +``` + +路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。 + +## 最小验收清单 + +- [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。 +- [ ] 已识别所有子项目和独立交付单元。 +- [ ] 跨子项目共享契约已经指定唯一事实来源。 +- [ ] 已明确复用、改写、冲突和暂不处理内容。 +- [ ] 已保留项目专用规则、历史和无关改动。 +- [ ] 未复制 DevHarness 历史归档或模板项目事实。 +- [ ] 已为每类长期文档明确事实来源和迁移状态。 +- [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。 +- [ ] Harness 检查已按目标项目调整并通过。 +- [ ] 必要测试、未验证部分、提交和最终证据已记录。 +- [ ] 工单处于待验收，未提前关闭。 + +## 回退原则 + +接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md new file mode 100644 index 0000000..9a6d691 --- /dev/null +++ b/docs/09-product-requirements-overview.md @@ -0,0 +1,66 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Product-Requirements-Overview +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.- +wiki_revision: 77035d7811d6df3880b575e91d1ce224dec21e2e +synchronized_at: 2026-09-10T06:27:45Z + + +# 产品需求总览 + + +## 本页用途 + +连接调研、候选交付范围、工作量和验收。详细行为见 [中文需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)，两份分析冲突见[项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)。 + +## 事实来源边界 + +当前实现：无。当前证据：已有静态调研。以下状态全部为“待范围确认/未实施”；工单、原型及运行验收入口均尚未建立。不能用上游功能清单计算 LexGo 已完成比例。 + +## 当前需求索引 + +| 领域 | 需求定位 | 候选阶段 | 最小验收入口 | +|---|---|---|---| +| 身份与管理 | U01、A01/A02/A09、N01 | M1 | A/B 用户数据不可互访，普通用户直接管理 API 被拒绝 | +| 内容库与文本处理 | U02/U03/U04/U08/U09、N02/N03/N04 | M0/M1 | 导入→就绪→阅读；失败重试无重复；原文可还原 | +| 阅读器、词语与短语 | U10/U11/U12/U13/U16、N04/N07 | M0/M1 | 点词、划短语、跨章状态与完成阅读开关正确 | +| 词典与语言资源 | U14、A03/A04、N05 | M0/M1 | 一种已验收语言查词与模型配置，本地核心无需翻译服务 | +| 复习与词汇库 | U17/U19、A07、N02 | M0/M1 | 到期/重学/时区/等级样例，重复作答不重复记账 | +| 统计、外观与移动 | U21/U24/U25、N07 | M1 基础、M2 补齐 | 事件统计一致、基础主题、手机与键盘操作 | +| 备份恢复 | A10、N06 | M1 基础、M4 演练 | 空实例恢复数据库、文件、配置清单后抽样一致 | +| 多格式导入 | U05/U06/U07 文件部分 | M2 | EPUB/网页/字幕文件成功与失败样例，明确格式限制 | +| 功能完善 | U11 完整形态/U15/U18/U19 CSV/U22/U24 定制/U25 PWA/U26、A04 格式/A05/A06 | M2 | 练习不改调度、CSV 空值语义、TTS、设置及删除本人数据边界 | +| 外部与语言专项 | U07 远程/U20/U23、A08 | M3 | 独立验证 Anki/Jellyfin/YouTube 和中日专项，可降级 | +| 稳定化 | N01～N08 | M1 起持续，M4 集中 | 隔离、恢复、Unicode、幂等、性能实测；N08 待定版 | + +## 登记规则 + +阶段与[工作量表](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)关联。正式建单后增加真实 URL、状态和设计版本；不编造 #1 等占位编号。拆分某个需求时保留原编号并注明子范围。 + +## 原型与设计资产 + +尚无原型。优先验证阅读器和短语交互；低风险管理表单沿用最终选定的规范即可。审核记录需包含链接/版本、覆盖范围及实际确认结果，未确认即保留草稿状态。 + +## 状态规则 + +范围确认后更新为待实施；开始执行才标实施中；有实际证据才标待验收；用户明确验收才标已验收。发生范围、技术基线或验收标准变化时更新主题与估算，不用“已写文档”替代产品状态。 + +## 最小验收清单 + +首版按完整学习闭环、词语状态一致、阅读完成开关、多用户隔离、管理员越权拒绝、任务失败恢复、固定时间复习、Unicode/短语定位、完整备份恢复九类场景验收。真实测试入口待工程建立后补齐。 + +### 原型门禁 + +按轻量模式，只在交互不确定性或明显返工风险下建立可审阅原型；独立功能仍需单元工单。 + +### 线上原型与按需 HTML 快照 + +默认以带版本的线上链接审核；仅用户明确要求才导出 HTML，已确认快照不得覆盖。 + +### 原型确认记录 + +当前无原型、无审核结论。后续记录链接、revision/日期、范围、确认人和结果。 + +## 更新时机 + +范围确认、实际实施状态变化或验收标准变化时更新索引；工单只有实际创建后才填写 URL。 diff --git a/docs/10-workload-estimate.md b/docs/10-workload-estimate.md new file mode 100644 index 0000000..6ffa60a --- /dev/null +++ b/docs/10-workload-estimate.md @@ -0,0 +1,84 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Workload-Estimate +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.- +wiki_revision: bcba6674445cd28c44216167a321c348a1ae7469 +synchronized_at: 2026-09-10T06:27:48Z + + +# LexGo 开发工作量估算 + + +## 估算口径 + +暂按两名熟悉 Go/Vue 的工程师、每人每周 5 个有效工作日、每日 8 小时计算。复用管理底座、保留 Python NLP、首发英语、有可用测试语料和合法可用的词典；一个产品、单一 MySQL 8 数据库，无 SaaS/原生 App/全离线同步。MySQL 8 已获用户确认，其他估算条件尚待确认。 + +每项人日包含分析、实现、相关测试、评审修正和必要文档；不是纯编码时长。M4 只包含跨功能的额外稳定化，不重复计算各功能基础测试。日历周以两人能合理分工为前提，依赖、请假和确认等待会延长日历时间。AI 辅助未作为固定折扣，实际速度用 M0/M1 数据校准。 + +首版目标暂按 P0 范围；M2/M3 按选定的 P1/P2 能力补齐。27 种语言全部达到质量承诺、旧实例全量迁移和商业扩展不在基准总额内。 + +## 分阶段总量 + +| 阶段 | 人日 | 人时 | 两人日历周参考 | 前置与退出条件 | +|---|---:|---:|---:|---| +| M0 风险验证与方案定版 | 10～20 | 80～160 | 1～2 | 确认首发语言/底座/数据库；分词位置、查词、复习样例和阅读交互可行 | +| M1 首个核心可用版 | 50～80 | 400～640 | 5～8 | M0 通过；P0 学习闭环、隔离、幂等与基础恢复可验收 | +| M2 主要功能补齐 | 30～50 | 240～400 | 3～5 | M1 稳定；选定 P1 格式、练习、CSV、显示与管理补齐 | +| M3 外部/语言专项 | 30～60 | 240～480 | 3～6 | M1 接口稳定；选定集成与新增语言各有验收证据 | +| M4 集中稳定化 | 20～40 | 160～320 | 2～4 | 前述目标范围完成；压测、恢复、升级和发布候选验证 | +| **首版 M0+M1** | **60～100** | **480～800** | **6～10** | 可用闭环，不是全部功能复刻 | +| **基准合计 M0～M4** | **140～250** | **1120～2000** | **14～25** | 选定范围覆盖，不承诺 27 语言完整对齐 | + +两人周数由阶段人日除以 10 得到，是容量参考，不是通过资源排程求出的最早完工时间。单人相同工作量约 28～50 个有效工作周，尚未加入技能差异和等待。 + +## M0、M1 可分配工作包 + +这是工作量拆解，不是已批准的实施计划。正式开工时按可独立测试/回退的边界细化单元工单，不机械地为每一行建父子层级。 + +| 包 | 范围与需求 | 人日 | 依赖 | 验收样例 | +|---|---|---:|---|---| +| W00 | 基线、语言、词典、token 定位、SRS 样例、阅读交互风险验证 | 10～20 | D01～D07 的必要范围确认 | 样本文本可还原、点击定位正确；技术选择形成记录 | +| W01 | 工程接入、身份与最小用户/全局管理 U01/A01/A02/A09 | 5～8 | W00 | 普通用户不能访问管理 API；账号与偏好流程可用 | +| W02 | 书库/章节/文本导入/分章选项/队列 U02/U04/U08/U09 | 7～11 | W01 与数据契约 | 失败可见；相同任务重试不生成重复章节 | +| W03 | 语言资源、分词集成、词典基础 A03/A04/U14 | 7～11 | W00/W01，和 W02 契约对齐 | 语言安装状态正确；离线查词可用；错模型明确报错 | +| W04 | 阅读器、主查询、词语短语、完成阅读 U10～U13/U16 | 12～19 | W02/W03 | 划词与短语正确，跨章状态同步，重复完成不重复计数 | +| W05 | 复习/基础词汇库/复习配置 U17/U19/A07 | 7～11 | W04 的词条契约 | 固定时钟下到期、重学、等级与重复作答符合样例 | +| W06 | 难度统计、目标日历、基础主题、响应式 U03/U21/U24/U25 | 6～10 | W02/W04/W05 的事件契约 | 忽略/已知分开，事件统计一致，手机与键盘可操作 | +| W07 | 首版集成、备份任务与恢复 A10/N01～N07 | 6～10 | W01～W06 | 两账号闭环通过；空实例恢复后数据和文件抽样一致 | +| **W01～W07 合计** | **M1** | **50～80** | | | + +W02/W03 可在契约确定后分工；W04 依赖它们的真实集成结果；W05 不宜在词条身份和状态语义未定时先冻结实现。无法通过简单增加人数消除这条依赖链。 + +## 后续阶段拆解 + +| 阶段 | 工作包 | 人日 | +|---|---|---:| +| M2 | EPUB/网页/字幕文件导入与失败回退 | 9～15 | +| M2 | 完整词汇 CSV、练习模式与过滤补齐 | 6～10 | +| M2 | 查询形态、字体、TTS、主题、PWA 及本人数据维护 | 9～15 | +| M2 | 词典格式、翻译服务配置与调用补齐 | 6～10 | +| M3 | Anki、YouTube、Jellyfin 选定连接方式与降级 | 12～24 | +| M3 | 中日读音/汉字专项与选定新增语言验收 | 12～24 | +| M3 | 专项集成回归、样例与使用说明 | 6～12 | +| M4 | 压测、长文/大词典优化 | 7～14 | +| M4 | Worker 故障、升级/回退、完整恢复演练 | 7～14 | +| M4 | 发布候选回归、交付文档和验收修正 | 6～12 | + +新增功能在各阶段包含自身基础测试；发布候选回归仅覆盖组合与环境差异。原中文分析 M4 同时提到“迁移需求”，但没有定义旧数据范围；本表将全量迁移单列为条件增量，不隐含承诺在 20～40 人日内完成。 + +## 条件增量与重估点 + +| 变化 | 处理方式 | +|---|---| +| 旧实例全量迁移成为必需 | 先用虚构/获授权样本盘点和 dry-run，再估用户、章节、文件、状态与索引迁移；不把 CSV 工期当全量迁移 | +| 禁止 Python / 要求所有语言同等支持 | M0 增加逐语言可行性与质量验证，重新估 NLP 工作；当前区间不适用 | +| 更换底座或数据库 | 在 W01 前解决兼容性；开工后切换需评估数据与接口返工 | +| 公开服务、多租户或收费 | 另立需求并估算安全、配额、审计及运维，不并入自托管基准 | +| 第三方字幕/翻译不稳定 | 按选定服务验证降级和成本，调整 M3 范围 | +| 团队人数/熟练度/有效投入不同 | 用实际可用人日重算日历时间，不线性承诺效率 | + +如果需要预算预留，可对基准人日另加 20%：168～300 人日；该比例是管理假设，不是统计置信区间，也不包含新增范围。基准低/高值已经体现已知实现难度，不应再重复加入相同工作包。 + +## 进度记录方式 + +当前开发完成量为 0，文档准备不计作上述产品包已完成。本轮编写文档的实际工时未记录，不反推为已消耗人日。M0 后记录实际投入、遗漏项、语言/底座测试结果，再更新 M1～M4；每阶段结束按剩余范围重估。 diff --git a/docs/README.md b/docs/README.md index 3692832..b7191db 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,33 +1,34 @@ -# LexGo 文档入口 + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Home +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home +wiki_revision: e1245504efbb44ee3ab3835b3180fa6f6906b14a +synchronized_at: 2026-09-10T06:27:39Z + -状态：2026-09-10，本地文档准备完成后仍需发布至确认的 Gitea 仓库；本页不是 Wiki 镜像。 +# LexGo 文档入口 ## 第一次阅读 -1. [项目档案](harness-drafts/00-project-profile.md)：目标、现状、治理、技术待决策项。 -2. [需求总览](harness-drafts/09-product-requirements-overview.md)：需求编号、阶段和验收入口。 -3. [工作量估算](harness-drafts/10-workload-estimate.md)：前提、人日拆解、依赖及重估条件。 -4. [架构与代码地图](harness-drafts/02-architecture-and-code-map.md)：现有文件与目标模块。 -5. [轻量工作流](harness-drafts/01-workflow.md)：如何开始和完成一个任务。 -6. [开发与验证](harness-drafts/04-local-development-and-verification.md)、[常见修改](harness-drafts/05-common-changes.md)、[排错](harness-drafts/06-troubleshooting.md)。 +1. [项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)：已确认使用轻量模式和 MySQL 8；其余技术候选与范围状态。 +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.-)。 ## 五分钟开始 -先阅读项目档案的待决策项，再按工作量估算查看 M0 风险验证。当前没有产品启动命令。工具命令和预期见开发验证页。线上初始化步骤见[初始化记录](harness-drafts/07-new-project-documentation-setup.md)。 +项目目前只有需求与设计资料、治理工具，没有产品代码。先核对项目档案 D01～D07，再安排 M0 技术验证。数据库已确定 MySQL 8；不把候选技术建议当作已实现能力。 + +命令从仓库根目录执行：`python dev_scripts/harness.py sync --verify` 同步线上页面并校验结构，预期退出码 0；`python -m unittest discover -s tests -v` 验证治理工具，预期全部通过。产品启动命令尚不存在。 ## 简单修改从哪里开始 -本次新增文档尚为草稿，可在 `harness-drafts/` 直接修订。原有调研文件保留为证据材料；形成批准的方案后用需求总览关联，不默默覆写历史建议。正式 Wiki 初始化后，从线上主题页修改再单向同步。 +先看[常见修改](https://git.ilapage.cn/OPC/lexgo/wiki/Common-Changes.-)和[故障排查](https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting)。轻量局部改动做最小验证；新功能和数据/权限变化建单。长期规则先改 Wiki，再导出镜像。 ## 事实来源 -| 资料 | 使用方式 | -|---|---| -| [中文需求提取](01-LinguaCafe需求提取.md) | U01～U26、A01～A10、N01～N08 的索引来源；静态调研，不是产品验收 | -| [中文 Go 分析](02-Go复刻与框架选型分析.md) | MySQL 路线和两人团队 14～25 周估算的来源；待确认建议 | -| [另一份需求提取](linguacafe-requirements.md) | 保留对照，使用自己的编号；不要直接混用编号 | -| [另一份 Go 分析](linguacafe-go-analysis.md) | PostgreSQL 路线及另一种阶段划分；待确认建议 | -| [业务规则](harness-drafts/03-business-rules-and-glossary.md) | 提取待批准规则与验收约束 | -| [交付文档指南](harness-drafts/delivery/README.md) | 按实际受众准备文档，不预建空白手册 | +Wiki 保存长期规则，工单保存单次实施与验收，Git 保存源码和镜像。当前产品实现为零，已有调研不等于运行验收。数据库选择以用户确认的 MySQL 8 为准，历史 PostgreSQL 建议不再适用。 -当前事实是上述本地资料和文件检查。产品 Git commit、远端、运行和验收证据尚不存在或未确认；不使用 DevHarness 的 commit 代替产品 commit。 +原有四份调研资料作为证据页面保留：[需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)、[Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-)、[另一份需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-)、[另一份 Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-)。其正文为既有调研记录，不将整份建议视为已批准方案。 + +[初始化记录与流程](https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-)、[接入指南](https://git.ilapage.cn/OPC/lexgo/wiki/Existing-Project-Adoption-Guide.-)、[交付文档指南](https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-)。不默认创建任务快照。 diff --git a/docs/delivery/README.md b/docs/delivery/README.md new file mode 100644 index 0000000..609d5ae --- /dev/null +++ b/docs/delivery/README.md @@ -0,0 +1,30 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Delivery-Documentation-Guide +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.- +wiki_revision: 2fded6b8141921cffd4a6f9b9c43ea9163b33a6b +synchronized_at: 2026-09-10T06:27:46Z + + +# 交付文档指南 + + +## 什么时候需要交付文档 + +按真实读者和可验证产品版本创建。当前负责人需要项目档案、需求范围和工作量估算；开发维护者需要业务边界、工作流与验证入口。尚无可运行产品，不预建空白用户/管理员手册。 + +## 受众与文档选择 + +学习者手册在 M1 形成可用闭环后编写，覆盖导入、阅读、保存和复习；部署维护指南在环境及常驻服务确认后编写，覆盖版本、配置、备份恢复和升级；管理员说明覆盖语言、词典、用户及备份授权。具体交付负责人、可见范围和验证人待确认。 + +## 内部文档与交付文档边界 + +交付文档仅包含读者所需操作与限制，不泄露凭据、内部配置或个人数据。测试示例明确使用虚构数据。研究建议不能当成对外功能承诺。 + +## 编写和维护流程 + +确认读者与版本 → 基于真实流程编写 → 执行操作验证 → 记录已知限制 → 人工验收。通用岗位模板仅供后续使用，不因模板存在认为手册已交付。 + +## 最小验收清单 + +入口可访问、步骤与版本一致、预期结果明确、错误可恢复、权限说明正确、敏感信息不外泄。无法执行的步骤明确标注，不能作为已验证交付内容。 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md new file mode 100644 index 0000000..2fa61e5 --- /dev/null +++ b/docs/delivery/audience-document-template.md @@ -0,0 +1,97 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Audience-Document-Template +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.- +wiki_revision: 43b4bf97a5c289dca1abd39fef312311881440be +synchronized_at: 2026-09-10T06:27:46Z + + + +# 岗位文档模板 + +> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 + +## 文档信息 + +| 字段 | 内容 | +|---|---| +| 文档名称 | | +| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 | +| 适用版本 | | +| 最后验证日期 | YYYY-MM-DD | +| 负责人 | | +| 可见范围 | 内部 / 指定客户 / 公开 | +| 相关产品或模块 | | + +## 目的与适用范围 + +说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。 + +## 前置条件 + +- 所需权限： +- 所需环境或设备： +- 已完成的准备： +- 需要提前获得的信息： + +不得在这里填写真实密码、令牌、个人数据或生产数据。 + +## 操作步骤 + +### 任务一：<明确的操作目标> + +1. <执行动作> +2. <执行动作> +3. <执行动作> + +**预期结果**：<读者可以观察到的成功结果> + +**失败时**：<先检查什么；何时停止并联系支持> + +每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。 + +## 常见错误与恢复 + +| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 | +|---|---|---|---| +| | | | | + +只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。 + +## 安全与权限 + +- 本岗位允许执行的操作： +- 明确禁止或需要审批的操作： +- 敏感信息处理规则： +- 数据、日志和截图脱敏要求： +- 删除、发布、迁移或其他高风险操作的确认要求： + +## 已知限制 + +- 支持的环境和版本： +- 当前不支持的场景： +- 兼容性限制： +- 未验证的环境或步骤： + +## 支持与升级处理 + +- 支持渠道： +- 服务时间或响应约定： +- 联系支持前需要收集的信息： +- 不得提交的信息： +- 需要升级到下一岗位或负责人的条件： + +## 版本记录 + +| 日期 | 适用版本 | 变更内容 | 验证人 | +|---|---|---|---| +| | | | | + +## 交付前检查 + +- [ ] 目标岗位能够理解术语和步骤。 +- [ ] 前置条件、步骤与预期结果一一对应。 +- [ ] 关键流程已按目标岗位视角验证。 +- [ ] 常见错误、恢复方法和升级条件清楚。 +- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。 +- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。 diff --git a/docs/linguacafe-go-analysis.md b/docs/linguacafe-go-analysis.md index 0709dfe..92da3fb 100644 --- a/docs/linguacafe-go-analysis.md +++ b/docs/linguacafe-go-analysis.md @@ -1,6 +1,14 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Go-Analysis-Alternative +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.- +wiki_revision: c1d22173cf01d60b46dd130e860367b8146fdc80 +synchronized_at: 2026-09-10T06:27:51Z + + # LinguaCafe 的 Go 复刻与框架选型分析 -日期：2026-09-10。本文是调研建议，尚未开始应用开发。需求与上游固定版本见 [需求提取](linguacafe-requirements.md)。默认目标是可自托管、可继续二次开发的 Web 应用；未假定要做付费 SaaS、原生手机应用或大型多租户平台。 +日期：2026-09-10。本文是调研建议，尚未开始应用开发。需求与上游固定版本见 [需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-)。默认目标是可自托管、可继续二次开发的 Web 应用；未假定要做付费 SaaS、原生手机应用或大型多租户平台。 ## 1. 结论 diff --git a/docs/linguacafe-requirements.md b/docs/linguacafe-requirements.md index d944d29..8c80dc8 100644 --- a/docs/linguacafe-requirements.md +++ b/docs/linguacafe-requirements.md @@ -1,3 +1,11 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: LinguaCafe-Requirements-Alternative +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.- +wiki_revision: 55fdebd66e3c1ece8c7dae81ca8639f5a8be5388 +synchronized_at: 2026-09-10T06:27:50Z + + # LinguaCafe 需求提取 调研日期：2026-09-10。目标项目：LexGo（Go 复刻方案）。本文提取上游需求，不代表已实现或已完成运行验收。 @@ -136,4 +144,4 @@ P2：YouTube、Jellyfin、Anki 的完整接入、汉字部首等专门功能， 用户删除、配额、公共书库、多租户、计费、AI 讲解、云端 TTS、离线同步、FSRS 均应明确列为扩展；P0 完成不能称为完整复刻。 -对应技术分析见 [Go 复刻与框架选型](linguacafe-go-analysis.md)。 +对应技术分析见 [Go 复刻与框架选型](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-)。 diff --git a/docs/templates/deployment.md b/docs/templates/deployment.md new file mode 100644 index 0000000..d709b59 --- /dev/null +++ b/docs/templates/deployment.md @@ -0,0 +1,283 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Deployment-Template +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-Template.- +wiki_revision: 552a2e7ba27fd76461ee9d8e4c3bb79fa32e0737 +synchronized_at: 2026-09-10T06:27:47Z + + + +# 部署文档模板 + +> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。 +> +> 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](https://git.ilapage.cn/OPC/lexgo/wiki/Audience-Document-Template.-)。 +> +> 标准栈为 nginx 反向代理 + supervisor 进程托管，示例按 Python 服务（gunicorn / uvicorn）编写。实际技术栈不同时替换命令，但保留章节结构和“每条命令写明预期结果”的要求。 + +## 本页用途 + +让维护者能够在一台干净的服务器上完成首次部署、日常运维、健康检查和回滚。所有命令默认以具备 sudo 权限的账号在服务器上执行，示例以 Linux 为主。 + +## 安全边界 + +- 本页只写配置项的**名称和来源**，不写任何真实密码、令牌、私钥、证书内容、生产数据库地址或个人数据。 +- 需要凭据的步骤写明“从哪里取”，例如运维密码库条目名或环境变量名。 +- 涉及删除数据、数据库迁移和不可逆操作的步骤必须给出醒目警告、影响范围和回退条件。 + +## 服务概览 + +| 项目 | 内容 | +|---|---| +| 服务名（supervisor program） | `` | +| 代码部署目录 | `/srv/` | +| 运行账号 | `` | +| 运行时 | Python `<3.x>` | +| 应用服务器 | gunicorn / uvicorn | +| 本地监听地址 | `127.0.0.1:<8000>` | +| 进程数 | `` | +| 对外域名与路径 | `https:///` | +| 依赖的外部服务 | 数据库 / 缓存 / 对象存储 / 无 | +| 日志目录 | `/var/log//` | + +服务只监听 `127.0.0.1`，不直接对外暴露端口；所有外部访问经 nginx 转发。 + +## 环境要求 + +| 组件 | 版本要求 | 检查命令 | 预期结果 | +|---|---|---|---| +| 操作系统 | `` | `cat /etc/os-release` | 输出与要求一致 | +| Python | `<3.11+>` | `python3 --version` | 输出版本号且不低于要求 | +| nginx | `<1.18+>` | `nginx -v` | 输出版本号 | +| supervisor | `<4.2+>` | `supervisord --version` | 输出版本号 | + +未安装时： + +```bash +sudo apt update +sudo apt install -y nginx supervisor python3-venv +``` + +**预期结果**：`systemctl status nginx` 与 `systemctl status supervisor` 均为 `active (running)`。 + +## 首次部署 + +### 1. 创建运行账号与目录 + +```bash +sudo useradd --system --home /srv/ --shell /usr/sbin/nologin +sudo mkdir -p /srv/ /var/log/ +sudo chown -R : /srv/ /var/log/ +``` + +**预期结果**：`id ` 输出该账号；两个目录存在且属主为 ``。 + +服务账号使用 `nologin`，不允许直接登录。 + +### 2. 取得代码 + +```bash +sudo -u git clone <仓库地址> /srv//app +cd /srv//app && sudo -u git rev-parse HEAD +``` + +**预期结果**：输出本次部署的完整提交哈希，记录到部署记录中。 + +### 3. 安装依赖 + +```bash +sudo -u python3 -m venv /srv//venv +sudo -u /srv//venv/bin/pip install -r /srv//app/requirements.txt +``` + +**预期结果**：pip 以 `Successfully installed ...` 结束，无 ERROR。 + +### 4. 落位配置文件 + +```bash +sudo install -o -g -m 600 /dev/null /srv//app.env +sudo -u vi /srv//app.env +``` + +**预期结果**：`ls -l /srv//app.env` 显示权限 `-rw-------` 且属主为 ``。 + +配置项清单见下方“配置与凭据来源”。配置文件不进入 Git。 + +### 5. 数据库初始化或迁移 + + + +> **注意**：迁移可能不可逆。执行前必须先备份，并确认回退方式。 + +```bash +sudo -u /srv//venv/bin/python -m .manage migrate +``` + +**预期结果**：输出全部迁移已应用，无失败项。 + +## supervisor 配置 + +写入 `/etc/supervisor/conf.d/.conf`： + +```ini +[program:] +command=/srv//venv/bin/gunicorn .wsgi:application --workers --bind 127.0.0.1:<8000> --timeout 60 +directory=/srv//app +user= +environment=PATH="/srv//venv/bin",APP_ENV_FILE="/srv//app.env" +autostart=true +autorestart=true +startsecs=5 +stopasgroup=true +killasgroup=true +stopwaitsecs=30 +stdout_logfile=/var/log//stdout.log +stderr_logfile=/var/log//stderr.log +stdout_logfile_maxbytes=50MB +stdout_logfile_backups=5 +``` + +> 异步框架使用 uvicorn 时把 `command` 换成： +> `/srv//venv/bin/uvicorn .asgi:app --host 127.0.0.1 --port <8000> --workers ` + +不要在 `environment` 里写明文密码或令牌；敏感值放在 `app.env`，由应用读取。 + +加载配置并启动： + +```bash +sudo supervisorctl reread +sudo supervisorctl update +sudo supervisorctl start +sudo supervisorctl status +``` + +**预期结果**：`reread` 输出 `: available`；`status` 显示 `RUNNING` 且 uptime 持续增长。出现 `BACKOFF` 或 `FATAL` 时查看 `stderr.log`。 + +## nginx 配置 + +写入 `/etc/nginx/sites-available/.conf` 并软链到 `sites-enabled`： + +```nginx +server { + listen 80; + server_name ; + + access_log /var/log/nginx/.access.log; + error_log /var/log/nginx/.error.log; + + client_max_body_size <20m>; + + location /static/ { + alias /srv//app/static/; + expires 7d; + } + + location / { + proxy_pass http://127.0.0.1:<8000>; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_connect_timeout 5s; + proxy_read_timeout <60s>; + } +} +``` + + + +启用并生效： + +```bash +sudo ln -sf /etc/nginx/sites-available/.conf /etc/nginx/sites-enabled/.conf +sudo nginx -t +sudo systemctl reload nginx +``` + +**预期结果**：`nginx -t` 输出 `syntax is ok` 与 `test is successful`；reload 无输出且 `systemctl status nginx` 仍为 `active (running)`。 + +`nginx -t` 未通过时不要 reload，先修正配置。 + + + +## 配置与凭据来源 + +| 配置项 | 用途 | 来源 | 是否敏感 | +|---|---|---|---| +| `APP_ENV_FILE` | 指向配置文件路径 | supervisor 配置 | 否 | +| `` | 数据库连接 | `/srv//app.env`，值取自运维密码库条目 `<条目名>` | 是 | +| `` | 会话与签名 | 同上 | 是 | +| `` | 日志级别 | `/srv//app.env` | 否 | + +敏感值只记录取用位置，不在本页、工单、日志和提交中出现真实内容。 + +## 日常运维 + +| 操作 | 命令 | 预期结果 | +|---|---|---| +| 查看状态 | `sudo supervisorctl status ` | `RUNNING`，uptime 持续增长 | +| 重启服务 | `sudo supervisorctl restart ` | 输出 `stopped` 后 `started` | +| 停止服务 | `sudo supervisorctl stop ` | 输出 `stopped` | +| 实时日志 | `sudo supervisorctl tail -f stderr` | 持续输出应用日志 | +| 应用日志 | `sudo tail -n 200 /var/log//stderr.log` | 输出最近日志 | +| 接入层日志 | `sudo tail -n 200 /var/log/nginx/.error.log` | 输出 nginx 错误 | +| 重载 nginx | `sudo nginx -t && sudo systemctl reload nginx` | 测试通过后无中断生效 | + +修改 supervisor 配置后必须 `reread` + `update`，只 `restart` 不会加载新配置。 + +## 健康检查 + +每次部署、重启和回滚后必须全部执行： + +```bash +sudo supervisorctl status +curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:<8000><健康检查路径> +curl -sS -o /dev/null -w "%{http_code}\n" https://<健康检查路径> +sudo tail -n 50 /var/log//stderr.log +``` + +**预期结果**：状态为 `RUNNING`；两个 `curl` 均返回 `200`；日志无新增异常堆栈。 + +任何一项不符合时不视为部署成功，按“升级与回滚”处理。 + +## 升级与回滚 + +### 升级 + +```bash +cd /srv//app +sudo -u git rev-parse HEAD # 记录当前提交，回滚需要 +sudo -u git fetch --all +sudo -u git checkout <目标提交或标签> +sudo -u /srv//venv/bin/pip install -r requirements.txt +sudo -u /srv//venv/bin/python -m .manage migrate # 无数据库时删除 +sudo supervisorctl restart +``` + +**预期结果**：restart 后 `status` 为 `RUNNING`，随后健康检查全部通过。 + +升级前必须记录当前提交哈希；涉及数据库迁移时必须先备份。 + +### 回滚 + +```bash +cd /srv//app +sudo -u git checkout <升级前记录的提交> +sudo -u /srv//venv/bin/pip install -r requirements.txt +sudo supervisorctl restart +``` + +**预期结果**：健康检查全部通过。 + +> **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。 + +### 备份与恢复 + + + +## 已知限制 + + + +- diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md new file mode 100644 index 0000000..783c82d --- /dev/null +++ b/docs/templates/task-archive.md @@ -0,0 +1,51 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Task-Archive-Template +wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Task-Archive-Template.- +wiki_revision: f87960fa6b715ea5cd58d074378cb3b0d8ec8559 +synchronized_at: 2026-09-10T06:27:48Z + + + +# <工单号> <标题> + +- 类型：需求 / 缺陷 / 重构 +- 所属 Epic：# +- 所属 MVP / 版本：# +- 状态：待验收 / 已完成 +- 日期：YYYY-MM-DD +- Gitea 工单：<链接> +- Wiki 页面：<页面名> +- Wiki revision：见本地镜像头 + +## 背景与目标 + + + +## 最终方案 + + + +## 修改文件 + +- `<文件>`：<改动说明> + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| | 通过 / 未通过 | + +## 测试 + +- 执行命令：`<命令>` +- 结果： +- **未验证部分**： + +## 遗留问题 + + + +## 相关提交 + +- `<提交哈希>` <提交说明>