From a3d1bdfb143bbc1f866330cdcddff072f698930e Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Thu, 27 Aug 2026 17:16:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20DevHarness=20?= =?UTF-8?q?=E9=95=BF=E6=9C=9F=E6=96=87=E6=A1=A3=20(#108)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/00-project-profile.md | 20 +- docs/01-workflow.md | 160 ++++++++-- docs/02-architecture-and-code-map.md | 16 +- docs/03-business-rules-and-glossary.md | 12 +- docs/04-local-development-and-verification.md | 18 +- docs/05-common-changes.md | 12 +- docs/06-troubleshooting.md | 13 +- docs/07-new-project-documentation-setup.md | 145 +++++++-- docs/08-existing-project-adoption.md | 51 +++- docs/09-product-requirements.md | 55 +++- docs/README.md | 95 ++++-- docs/delivery/README.md | 9 +- docs/delivery/deployment-and-operations.md | 82 +++++ docs/task/66-Sense视频接入与Profile.md | 13 +- ...视频服务生命周期与状态对账.md | 13 +- docs/templates/deployment.md | 282 ++++++++++++++++++ 16 files changed, 875 insertions(+), 121 deletions(-) create mode 100644 docs/delivery/deployment-and-operations.md create mode 100644 docs/templates/deployment.md diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index f60dc29..0c0576e 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/ila/yovision/wiki/Project-Profile.- -wiki_revision: 84cb91d5fb87fcb711c04c1f94b5c09ebe8c22a1 -synchronized_at: 2026-08-15T06:45:18Z +wiki_revision: 5e6d18991d69aad15311aae811f35206aa0b5ee6 +synchronized_at: 2026-08-27T09:04:26Z # 项目档案 @@ -22,6 +22,18 @@ synchronized_at: 2026-08-15T06:45:18Z | 当前阶段 | 进入 GoAdmin 源码派生重建：旧实现归档于 `explore`，`main` 为审核基线，`dev` 为集成开发分支 | | 历史来源 | `D:\OPC\yovision_old`，只读追溯 | +## DevHarness 来源与基线 + +| 项目 | 内容 | +|---|---| +| 上游仓库 | `https://git.ilapage.cn/OPC/dev_harness` | +| 本次升级前基线 | `f23c2cf81f9792495f696d49e88d79b16cf29810` | +| 当前目标基线 | `4bbacf4d7fb265984396bb5589c544105043fa0b` | +| 升级日期 | 2026-08-27 | +| 识别方式 | 初始导入文件 blob 与上游历史逐项对照；完整 commit 是基线标识 | + +YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Gitea 工单/Wiki 事实源边界和模板；项目适配保留三项目并行与写路径所有权、`explore/main/dev` 分支治理、Sense/Bell GoAdmin 固定基线、UI 精简复用门禁和现有产品文档结构。升级不得整页覆盖项目事实，也不得复制 DevHarness 自身任务状态。 + ## 子项目与交付单元 | 单元 | 职责 | 技术栈目标 | 独立构建/测试/发布 | 规则入口 | 共享边界 | @@ -57,9 +69,9 @@ synchronized_at: 2026-08-15T06:45:18Z 当前初始化阶段可执行： ```powershell -python dev_scripts/check_harness.py --strict +python dev_scripts/harness.py check --strict python -m unittest discover -s tests -v -python dev_scripts/sync_wiki_docs.py --check +python dev_scripts/harness.py sync --check git diff --check ``` diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 7c48bca..88b0667 100644 --- a/docs/01-workflow.md +++ b/docs/01-workflow.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Development-Workflow.- -wiki_revision: 2bb60b79073439babfda05140ce813d197de81d9 -synchronized_at: 2026-08-14T01:06:22Z +wiki_revision: b377b601b04074b834c4c9f6fbd37434b3d19d22 +synchronized_at: 2026-08-27T09:04:39Z # 开发工作流 @@ -11,10 +11,94 @@ synchronized_at: 2026-08-14T01:06:22Z ## 事实来源边界 - Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 -- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。 +- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。 +## 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 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。 + +## 工单与设计证据双门禁 + +开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。 + +### 先判断是否需要工单 + +只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型： + +- 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案； +- 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果； +- 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义； +- 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符； +- 不造成明显布局、截断、换行、可访问性或支持平台问题； +- 有任何不确定时不使用豁免。 + +豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。 + +### 再判断设计证据 + +| 修改类型 | 最低设计证据 | 正式编码门禁 | +|---|---|---| +| 纯显示文案且满足全部豁免条件 | 无原型 | 完成最小界面检查即可 | +| 现有界面的小范围样式或布局调整 | 标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范 | 工单确认设计证据后编码 | +| 新组件但复用现有设计体系 | 组件状态、错误和边界说明；按需提供低保真图 | 工单确认状态和复用边界后编码 | +| 新页面、独立用户功能、重大交互或导航变化 | Quant-UX 或其他合适工具制作的可审阅原型 | 用户确认原型和文字需求后才能编写生产代码 | +| 后端、接口、数据处理或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后编码，不制作无意义的 UI 原型 | +| 恢复既有确认行为的 Bug | 原设计、已确认截图、复现步骤或现有验收证据 | 确认是恢复而不是改变行为后修复 | + +采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。 + +### 线上原型审核与按需导出 + +新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，默认直接通过线上原型审核，不要求每次导出本地 HTML： + +- 可编辑设计源保存在 Quant-UX 或原设计工具；工单和 Wiki 只保存链接、版本与确认记录，不复制为第二份可编辑事实来源。 +- 线上链接必须能被确认人访问，并能通过版本、revision、复制版本或确认日期识别本次审核对象；无法访问或无法区分版本时停止审核，等待用户确认等效方案。 +- 提交审核前检查主要页面、流程、状态和交互可访问，并删除令牌、真实账号、个人信息和生产数据。 +- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，更新线上原型并重新确认；不得用旧确认覆盖新版本。 +- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据，不强制建立完整线上原型。 + +只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出本地 HTML： + +- 指定工单的快照放入 `prototypes/<工单号>/<版本>/index.html`；全部导出时也按工单和版本分目录，先在工单明确导出范围。 +- 图片、样式、脚本和字体使用版本目录内的相对路径；需要网络资源才能显示时不得标记为可离线浏览。 +- 已确认的本地快照不得原位覆盖；新版本使用新目录，已有快照继续作为历史审核证据。 +- 导出后检查入口、主要交互和资源完整性；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。 +- 导出指令只生成或更新请求范围内的快照并报告结果，不自动提交；用户未明确要求时不得顺带导出其他原型。 +- 设计工具无法生成用户要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型仍可访问且版本明确时，不因此阻塞线上审核。 + +### 记录和重新确认 + +需要设计证据的工单必须记录： + +- 原型或设计的线上链接、对应事实来源，以及链接可访问性； +- 版本、revision、复制版本或确认日期，以及审核版本的识别方式； +- 状态：无、草稿、已确认或已废弃； +- 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果； +- 确认人和确认时间； +- 本次确认覆盖的页面、组件、流程和边界； +- 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。 + +页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。 ## 一次任务怎样完成 ### 1. 讨论 @@ -67,35 +151,50 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新 - Git 提交哈希； - 相关 Wiki 页面及 revision。 -长期文档遵循唯一顺序： +工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。 + +只有长期事实发生变化时才执行核心文档闭环： ```text -修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像 +修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像 ``` -不得先编辑 `docs/` 再反向覆盖 Wiki。 +没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。 ### 4. 待验收 实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。 -### 5. 归档和关闭 +### 5. 待验收和关闭 -使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像： +实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。 + +用户明确验收通过后： + +1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据； +2. 关闭单元工单并勾选所属 MVP/Epic 子任务； +3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki； +4. 默认不创建或导出任务归档。 + +任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行： ```powershell -python dev_scripts/new_task_archive.py 123 "修复登录超时" +python dev_scripts/harness.py archive 123 "修复登录超时" +python dev_scripts/harness.py export # 增量导出已有归档 +python dev_scripts/harness.py export --all # 全量导出已有归档 ``` -归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。 +可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。 ## 文档同步规则 -- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。 -- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。 +- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。 +- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。 +- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。 - 镜像头必须记录页面名、页面地址、revision 和同步时间。 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。 -- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。 +- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。 +- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。 - 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。 - Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。 @@ -129,6 +228,8 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" - 业务规则、安全边界或权限变化； - 日志位置、错误定位或常见处理方式变化。 +部署命令的落点：有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由[部署文档模板](Deployment-Template.-)复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。 + 普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。 ## 需求记录与流转 @@ -149,20 +250,20 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | -| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` | +| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 | 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 -## 稳定文档与任务归档 +## 稳定文档与可选历史快照 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 -- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。 -- 新人先读稳定主题页，只有追查历史原因时才读任务归档。 -- 任务产生的长期结论必须合并到主题页，不能只留在归档。 +- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。 +- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。 +- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。 ## 效率与范围控制 -本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 +本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。 ### 严格控制范围 @@ -200,20 +301,26 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" |---|---|---| | `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 | | `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 | -| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” | +| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” | | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” | | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | -| `同步文档` | 读取 Wiki，导出已映射的 `docs/` 镜像并检查一致性 | 显示结果和差异；不修改 Wiki、不自动提交 | -| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，导出并提交镜像，推送、同步父工单并关闭任务 | 工单“已完成”并关闭 | +| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 | +| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 | +| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 | +| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | +| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 | +| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 | 补充边界： - 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 -- `同步文档` 发现镜像有未提交改动时停止，不覆盖现有修改。 -- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存 Wiki 最终任务归档的镜像。 +- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 +- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。 +- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。 +- Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。 ## 什么时候重新确认方案 @@ -235,8 +342,9 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" | 讨论过程和临时方案 | 是 | 否 | 否 | | 实施进度和阻塞 | 是 | 否 | 否 | | 长期有效的最终方案 | 链接 | 是 | 镜像 | -| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 | -| 提交哈希 | 是 | 任务归档 | 镜像 | +| 测试结果与未验证内容 | 是 | 否 | 否 | +| 提交哈希和验收结论 | 是 | 否 | 否 | +| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 | | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | ## go-admin / go-admin-ui 开发约束 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 78b4974..be60b3b 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/ila/yovision/wiki/Architecture-and-Code-Map.- -wiki_revision: 8df12aa3e136b1faee9c2dffb58ca39b045bc49f -synchronized_at: 2026-08-17T02:54:44Z +wiki_revision: ee5b5507bf8a8a834e07f223f1a90c2f67a70d6f +synchronized_at: 2026-08-27T09:14:31Z # 架构与代码地图 @@ -35,9 +35,9 @@ Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense | Brain 推理 | `Brain/` | `Brain/AGENTS.md`；后续包入口 | `Brain/` 内测试与契约测试 | 高：模型、GPU、隐私、事件语义 | | Bell 产品 | `Bell/` | `Bell/AGENTS.md`；待 GoAdmin 派生工单建立 README/入口 | 待新骨架建立 | 高：GoAdmin 派生、认证、事件与告警状态机 | | 共享契约 | `contracts/` | `contracts/AGENTS.md` | 三端消费者/生产者测试 | 高：兼容性与跨项目影响 | -| Harness | `dev_scripts/` | `check_harness.py` | `tests/` | 中 | +| Harness | `dev_scripts/` | `harness.py check --strict` | `tests/` | 中 | | 工单模板 | `.gitea/issue_template/` | `task.md` | Harness 严格检查 | 中 | -| Wiki 镜像 | `docs/` | `docs/README.md` | `sync_wiki_docs.py --check` | 低；禁止直接编辑 | +| Wiki 镜像 | `docs/` | `docs/README.md` | `harness.py sync --check` | 低；禁止直接编辑 | 旧 Sense、Bell 入口仅存在于 `explore` 快照，不是 `main` / `dev` 当前代码地图。三个项目的新入口必须随新骨架工单建立；不得把旧自研基础框架复制回 `dev`。 @@ -142,3 +142,11 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea 交付包同时提供检查、迁移、管理员初始化、停止、备份和恢复入口。停止脚本只操作当前包且监听配置端口的 Sense 进程树；备份密码只进入子进程环境；恢复要求数据库名和二次短语确认。包不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。 + + +## DevHarness 执行路径 + +- `dev_scripts/harness.py check --strict` 检查核心结构、YoVision GoAdmin 基线和项目规则。 +- `dev_scripts/harness.py sync` 只从 Gitea Wiki 导出 `wiki-docs.json` 映射的核心镜像；`sync --check` 只检查一致性。 +- `archive`、`export` 和 `export --all` 只在人工明确要求时处理可选任务快照，任务快照不进入核心映射。 +- `dev_scripts/wiki_docs.py` 负责 Gitea Wiki 读取、revision、镜像头、脏文件保护和安全路径校验。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index df741d8..265a734 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.- -wiki_revision: 2bcd90c508180eb9a2f9fe37b62115d7d9207e18 -synchronized_at: 2026-08-15T01:13:04Z +wiki_revision: 96fca4d2aa411725282bd3911c133efc75f7146a +synchronized_at: 2026-08-27T09:04:59Z # 业务规则与术语 @@ -146,3 +146,11 @@ synchronized_at: 2026-08-15T01:13:04Z - 鼠标可点击/拖动顶点；键盘必须能添加、移动和删除顶点。错误在绘制区域附近以可被辅助技术感知的文字给出，并提供撤销、清空和未保存关闭确认。 - 区域配置是 Sense 内部事实；#69 不发布 Brain 契约。后续 Sense→Brain 配置协议必须由独立协调工单从当前版本投影生成，不能共享数据库模型。 + + +## DevHarness 任务证据边界 + +- Gitea 工单正文与评论是单次任务的需求、变化、实现、测试、提交和验收事实来源。 +- Gitea Wiki 只保存长期有效的项目事实；核心页面由 `wiki-docs.json` 显式映射。 +- `docs/task/` 是按人工明确要求形成的专项或历史兼容快照，可能不完整或不是最新状态，不得替代工单。 +- 默认不创建、导出或更新任务快照；导出过程不自动删除本地历史文件。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 6f19378..6b7653b 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/ila/yovision/wiki/Local-Development-and-Verification.- -wiki_revision: 925a16a72bd5840697b5c61489a97018134b3930 -synchronized_at: 2026-08-27T08:07:04Z +wiki_revision: 7ede95108304cec08572d9da5ce1f41116e4970d +synchronized_at: 2026-08-27T09:05:09Z # 本地开发与验证 @@ -19,6 +19,12 @@ synchronized_at: 2026-08-27T08:07:04Z Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。 +## Windows PowerShell 与 UTF-8 + +- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不为设置编码重复启动一层 PowerShell。 +- 文本文件读写在命令支持时显式指定 UTF-8。文件解码与控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才调整当前进程输出编码或 Python UTF-8 环境变量。 +- 不默认使用 `-ExecutionPolicy Bypass`。只有可信脚本确实被策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。 + ## 第一次运行 1. 检查工作区： @@ -32,7 +38,7 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 2. 检查 Harness： ```powershell - python dev_scripts/check_harness.py --strict + python dev_scripts/harness.py check --strict ``` 预期：输出“DevHarness 检查通过”。 @@ -48,7 +54,7 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 4. 对照 Wiki： ```powershell - python dev_scripts/sync_wiki_docs.py --check + python dev_scripts/harness.py sync --check ``` 预期：全部映射一致。 @@ -81,8 +87,8 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 ```powershell python -m unittest discover -s tests -v -python dev_scripts/check_harness.py --strict -python dev_scripts/sync_wiki_docs.py --check +python dev_scripts/harness.py check --strict +python dev_scripts/harness.py sync --check git diff --check git status --short ``` diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index 4f010b7..9172dd0 100644 --- a/docs/05-common-changes.md +++ b/docs/05-common-changes.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Common-Changes.- -wiki_revision: edfcd6dd2cd254d31e88e980558e467b5fe758a3 -synchronized_at: 2026-08-11T10:30:43Z +wiki_revision: becaa9f08fd07397da516c31e3d93362626df050 +synchronized_at: 2026-08-27T09:05:21Z # 常见修改指南 @@ -20,15 +20,15 @@ synchronized_at: 2026-08-11T10:30:43Z | 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 | | 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | -“代码行数少”不等于低风险。 +“代码行数少”不等于低风险。风险等级只决定由谁实施和验证，不改变建单门禁：新功能、缺陷修复、重构及行为变化仍需工单；只有 AGENTS.md 明确列出的非行为修改和纯显示文案豁免可以直接提交。 ## 修改 Wiki 文案 1. 在相关工单确认目标。 2. 读取线上 Wiki 页面和当前 revision。 3. 修改线上 Wiki，不直接编辑 `docs/`。 -4. 运行 `python dev_scripts/sync_wiki_docs.py`。 -5. 运行 `python dev_scripts/sync_wiki_docs.py --check`。 +4. 运行 `python dev_scripts/harness.py sync`。 +5. 运行 `python dev_scripts/harness.py sync --check`。 6. 审查本地镜像差异并提交。 停止条件：页面需要删除、重命名或改变事实源边界。 @@ -45,7 +45,7 @@ synchronized_at: 2026-08-11T10:30:43Z ## 调整 Harness 检查 -1. 从 `dev_scripts/check_harness.py` 的 `main()` 开始读。 +1. 从 `dev_scripts/harness.py` 的 `run_check()` 开始读。 2. 新检查应输出具体文件和缺失内容。 3. 检查结构事实，不声称自动判断文档语义质量。 4. 在 `tests/` 添加成功和失败用例。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index 946db2e..5aab750 100644 --- a/docs/06-troubleshooting.md +++ b/docs/06-troubleshooting.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting -wiki_revision: 1a452e9aafdfe01580f37f9179584b89516cf992 -synchronized_at: 2026-08-15T07:59:38Z +wiki_revision: 046624c1b2d7963ef733b4c9687d5dec14771388 +synchronized_at: 2026-08-27T09:05:32Z # 故障排查 @@ -152,3 +152,12 @@ synchronized_at: 2026-08-15T07:59:38Z 如果迁移报告不支持的唯一性结构，不要手工删除约束或路由；在备份副本中核对实际约束和业务数据。正式迁移失败时保留错误并从迁移前备份恢复，不通过关闭唯一性绕过迁移。 + + +## DevHarness 同步排错 + +1. 先运行 `python dev_scripts/harness.py check --strict` 定位结构或项目规则问题。 +2. 镜像不一致时运行 `python dev_scripts/harness.py sync --check`；不得直接修改 `docs/` 后反向覆盖 Wiki。 +3. 若同步提示本地镜像有未提交修改，先核对改动归属并停止覆盖。 +4. Wiki 页面缺失、没有 revision、MCP/API 凭据不可用或映射准备删除/重命名时停止，由工单确认后处理。 +5. PowerShell 显示乱码时先区分文件编码和控制台输出编码，不默认另起 PowerShell 或使用 `-ExecutionPolicy Bypass`。 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index a34ece9..32adf89 100644 --- a/docs/07-new-project-documentation-setup.md +++ b/docs/07-new-project-documentation-setup.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: New-Project-Documentation-Setup wiki_url: https://git.ilapage.cn/ila/yovision/wiki/New-Project-Documentation-Setup.- -wiki_revision: 8ac3aaf5a1cc5479f2a37a07fec6510b6dcc9cab -synchronized_at: 2026-08-11T10:30:50Z +wiki_revision: 66d63c1e43de4dc54bb7c16ec6eb462a07bab15c +synchronized_at: 2026-08-27T09:05:42Z # 新项目文档初始化 @@ -26,7 +26,81 @@ synchronized_at: 2026-08-11T10:30:50Z 把项目专用红线写入根目录或子目录 `AGENTS.md`。 -### 2. 识别子项目与交付单元 +#### 需求总览启用条件 + +从模板创建项目时保留 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. 识别子项目与交付单元 先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认： @@ -40,19 +114,21 @@ synchronized_at: 2026-08-11T10:30:50Z 把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。 -### 3. 建立 Gitea +### 4. 建立 Gitea -创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。 +创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。 -### 4. 修改镜像配置 +任何产品功能开发在引导提交后都必须先有单元任务工单，并且必须通过第 8 步的线上 Wiki 初始化门禁。 -把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。 +### 5. 修改镜像配置 -确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后，移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 +把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。 + +确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 不要把 PAT 写入配置。 -### 5. Agent 检查项目事实 +### 6. Agent 检查项目事实 Agent 只读检查： @@ -65,7 +141,7 @@ Agent 只读检查： 区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。 -### 6. 确定交付对象和文档 +### 7. 确定交付对象和文档 由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定： @@ -77,25 +153,36 @@ Agent 只读检查： 按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。 -### 7. 先创建线上 Wiki +### 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. Architecture-and-Code-Map； -4. Business-Rules-and-Glossary； -5. Local-Development-and-Verification； -6. Common-Changes； -7. Troubleshooting； -8. Development-Workflow； -9. Delivery-Documentation-Guide； -10. Audience-Document-Template； -11. Task-Archive-Template。 +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 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。 +Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 7 步确认的受众创建。 -### 8. 人工确认 +部署页按需创建，不属于必需核心页面：项目负责人确认存在需要部署的常驻服务时，复制[部署文档模板](Deployment-Template.-)在本项目 Wiki 建立 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）；确认没有常驻服务时，在初始化工单记录原因，不创建该页面。 + +### 9. 人工确认 项目负责人至少确认： @@ -103,29 +190,33 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图 - 关键业务规则和状态； - 权限、安全和数据边界； - 真实运行、测试和部署命令； +- 本项目是否有需要部署的常驻服务； - 哪些修改属于高风险； - 交付对象、文档可见范围和外部信息边界。 -### 9. 导出镜像并检查 +### 10. 导出镜像并检查 ```powershell -python dev_scripts/sync_wiki_docs.py -python dev_scripts/check_harness.py --strict -python dev_scripts/sync_wiki_docs.py --check +python dev_scripts/harness.py sync --verify python -m unittest discover -s tests -v ``` -只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。 +只有线上 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 index 8bca003..9417f7d 100644 --- a/docs/08-existing-project-adoption.md +++ b/docs/08-existing-project-adoption.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Existing-Project-Adoption-Guide wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Existing-Project-Adoption-Guide.- -wiki_revision: dfb92b4551c317a08f49e68d0262258157da6d04 -synchronized_at: 2026-08-11T10:30:53Z +wiki_revision: 54e7c774b679f582d210c08179de31d6e12ed9b4 +synchronized_at: 2026-08-27T09:05:54Z # 已有项目接入 DevHarness 指南 @@ -23,7 +23,7 @@ synchronized_at: 2026-08-11T10:30:53Z | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | -| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 | +| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 | | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 @@ -71,7 +71,7 @@ Agent 在提出方案前只读检查： - 多个应用共同完成一条产品或业务链路； - 由同一团队维护，仓库权限基本一致； - 接口变更需要在一个工单中同步修改或验证多端； -- 共享契约、业务规则和任务归档放在一起更容易保持一致； +- 共享契约和业务规则由同一项目维护并指定唯一事实来源； - 仓库体积、测试时间和工具性能尚未明显影响开发； - 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。 @@ -131,7 +131,42 @@ Agent 在提出方案前只读检查： ### 7. 提交和验收 -提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。 +提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 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 已记录新基线。 +``` + +路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。 ## 冲突处理和停止条件 @@ -175,8 +210,8 @@ Agent 在提出方案前只读检查： 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 -本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持 -为“待验收”；未经我明确验收，不关闭工单。 +本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后 +保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。 ``` 路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。 @@ -192,7 +227,7 @@ Agent 在提出方案前只读检查： - [ ] 已为每类长期文档明确事实来源和迁移状态。 - [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。 - [ ] Harness 检查已按目标项目调整并通过。 -- [ ] 必要测试、未验证部分、提交和归档证据已记录。 +- [ ] 必要测试、未验证部分、提交和最终证据已记录。 - [ ] 工单处于待验收，未提前关闭。 ## 回退原则 diff --git a/docs/09-product-requirements.md b/docs/09-product-requirements.md index 28a678b..ea7df60 100644 --- a/docs/09-product-requirements.md +++ b/docs/09-product-requirements.md @@ -2,12 +2,63 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.- -wiki_revision: e6c6e0d7f658a7c1040fe569026e7d0ec581701a -synchronized_at: 2026-08-17T02:54:53Z +wiki_revision: e912a1ca1410e01680a0f11f6199ccb42cd8fe8f +synchronized_at: 2026-08-27T09:06:08Z # 产品需求 +## 本页用途 + +本页同时承担 YoVision 产品需求正文与需求总览索引，保留已经确认的 Sense、Brain、Bell 和跨项目要求，不因 DevHarness 升级重命名或拆分事实源。 + +## 事实来源边界 + +- 长期产品目标、边界和稳定需求记录在本页。 +- 单次任务的范围、变化、实现和验收记录在对应 Gitea 工单。 +- 原型用于确认页面、流程与交互，不替代正式需求和验收标准。 + +## 当前需求索引 + +- 产品边界：PR-BND-001～PR-BND-003。 +- Sense：SEN-001 起，按 P0、P1/P2 管理。 +- Brain：BRN-001 起，按 P0、P1/P2 管理。 +- Bell：BEL-001 起，按 P0、P1/P2 管理。 +- 跨项目与非功能要求：见本页第 6 节及对应协调工单。 + +## 登记规则 + +新增或变化的长期需求必须有来源、状态、所属产品、优先级和验收边界；会改变已确认结果时先更新工单并重新取得用户确认。 + +## 原型与设计资产 + +### 原型门禁 + +新页面、独立用户功能、重大交互或导航变化必须先形成可审阅原型；小范围 UI 使用标注截图、低保真图或明确复用规范；非 UI 任务使用架构、API、数据、状态或流程设计。 + +### 线上原型与按需 HTML 快照 + +默认使用可访问且版本明确的线上原型审核。只有用户明确要求或项目规则要求时，才导出 `prototypes/<工单号>/<版本>/index.html`；已确认快照不得原位覆盖。 + +### 原型确认记录 + +实现工单记录设计链接或路径、版本/revision、访问检查、确认人、确认时间和覆盖范围。结构、流程、状态、权限或异常处理发生实质变化时必须重新确认。 + +## 状态规则 + +需求使用拟议、已确认、实施中、已交付、已废弃等状态；工单状态仍按待确认、待实施、进行中、阻塞、待验收、已完成管理，两者不得混用。 + +## 更新时机 + +产品边界、长期业务规则、需求优先级或验收边界变化时更新本页；单次实现细节、测试日志和提交哈希只写工单。 + +## 最小验收清单 + +- 需求有稳定编号、所属产品、优先级、来源和验收边界。 +- 跨项目需求只有一个契约或协调事实源。 +- 需要原型的变更已有可访问、可识别版本并完成确认。 +- 不包含密码、令牌、生产数据或完整聊天记录。 + ## 1. 产品范围与优先级 YoVision 首个可交付目标是在民办寄宿学校以默认 16 路高风险点位形成完整闭环： diff --git a/docs/README.md b/docs/README.md index 96865af..f74f456 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,55 +2,100 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Home wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Home -wiki_revision: 1a2dadc746ce76e182150ca93fc4a1ec192c6b6a -synchronized_at: 2026-08-11T10:30:24Z +wiki_revision: 8ba2aba01f287ec5ab9cafda3d719bfd9e7fc459 +synchronized_at: 2026-08-27T09:04:13Z # YoVision 文档中心 -YoVision 是单仓三项目的智能视频事件平台。Sense 负责设备与媒体，Brain 负责推理与事件生成，Bell 负责事件预警和处置。Sense 与 Bell 是可独立销售、部署和验收的产品；Brain 是独立构建的推理交付单元。 +DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。 ## 第一次阅读 -1. [项目档案](Project-Profile.-)：目标、子项目、技术栈和边界。 -2. [产品需求](Product-Requirements.-)：功能、质量、安全和非目标。 -3. [架构与代码地图](Architecture-and-Code-Map.-)：职责、数据流和代码入口。 -4. [业务规则与术语](Business-Rules-and-Glossary.-)：不可破坏的领域规则。 -5. [需求迁移矩阵](Requirements-Migration-Matrix.-)：旧项目需求怎样进入新仓库。 -6. [多 Agent 协作](Multi-Agent-Collaboration.-)：三名主 agent 和协调任务的写路径规则。 -7. [本地开发与验证](Local-Development-and-Verification.-)：当前可执行命令和待补门禁。 -8. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收和归档。 +建议按以下顺序，用 10～20 分钟建立整体认识： + +1. [项目档案](Project-Profile.-)：项目目标、环境、命令和目录边界。 +2. [产品需求总览](Product-Requirements-Overview.-)：长期需求、状态、原型和验收入口。 +3. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。 +4. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。 +5. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。 +6. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。 +7. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。 +8. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和可选快照流程。 + +从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。 ## 五分钟开始 +在仓库根目录执行： + ```powershell git status --short --branch -python dev_scripts/check_harness.py --strict +python dev_scripts/harness.py check --strict python -m unittest discover -s tests -v -python dev_scripts/sync_wiki_docs.py --check +python dev_scripts/harness.py sync --check ``` -预期：工作区变更归属清楚，Harness 与测试通过，Wiki 镜像一致。业务代码尚未初始化时，不应臆造 Sense、Brain 或 Bell 的构建命令。 +预期结果： + +- 工作区没有不属于当前任务的修改； +- Harness 输出“DevHarness 检查通过”； +- 所有单元测试通过； +- 所有 Wiki 映射显示“一致”。 + +如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。 ## 简单修改从哪里开始 -| 修改类型 | 先读 | 主要验证 | +| 想做什么 | 先读哪里 | 主要验证 | |---|---|---| -| Sense 单项目 | Project-Profile、`Sense/AGENTS.md` | Sense 自身测试 | -| Brain 单项目 | Product-Requirements、`Brain/AGENTS.md` | Brain 自身测试与事件契约测试 | -| Bell 单项目 | Business-Rules、`Bell/AGENTS.md` | Bell 自身测试 | -| 共享契约 | Multi-Agent-Collaboration、`contracts/AGENTS.md` | 三端消费者/生产者契约测试 | -| 长期文档 | 对应 Wiki 页面 | Wiki 同步检查 | +| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 | +| 查看或更新产品需求 | Product-Requirements-Overview、对应主题 Wiki 和工单 | 状态、链接和事实来源核对 | +| 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 | +| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 | +| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 | +| 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 | +| 增加结构检查 | `dev_scripts/harness.py` | 成功与失败测试 | +| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 | + +权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。 ## 事实来源 | 信息 | 事实来源 | |---|---| -| 实时任务状态、方案确认和验收过程 | Gitea 工单 | -| 长期需求、架构、规则、操作与归档 | Gitea Wiki | -| API/Schema/迁移及代码版本事实 | Git 仓库 | -| 离线文档 | `docs/` Wiki 只读镜像 | -| 历史需求和旧证据 | `D:\OPC\yovision_old`，只读参考，不是当前状态 | +| 任务状态、讨论、阻塞、验收过程 | Gitea 工单 | +| 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview | +| 架构、业务规则、开发规范、操作手册和交付文档 | Gitea Wiki | +| 源码和与特定代码版本强绑定的文档 | Git 仓库 | +| 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 | +| 单次任务需求、实现、测试和验收 | Gitea 工单；专项 Wiki 快照仅在人工明确要求时创建 | + +本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。 + +## 项目入口 + +- [Gitea 工单](https://git.ilapage.cn/OPC/dev_harness/issues) +- [产品需求总览](Product-Requirements-Overview.-) +- [代码仓库](https://git.ilapage.cn/OPC/dev_harness) +- [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-) +- [交付文档指南](Delivery-Documentation-Guide.-) +- [岗位文档模板](Audience-Document-Template.-) +- [可选任务归档模板（兼容）](Task-Archive-Template.-) + +## 同步原则 + +```text +修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像 +``` + +- 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。 +- 默认不创建任务归档；只有用户明确要求专项快照或项目专用规则要求时，才创建 Wiki 归档并按需导出到 `docs/task/`。 +- 镜像头记录来源页面、Wiki revision 和同步时间。 +- 已映射镜像存在未提交修改时同步必须停止。 +- 页面删除、重命名和映射变更必须人工确认。 +- 长期事实发生变化而核心 Wiki 或必要同步失败时，相关任务不能标记为完成；没有长期文档变化时不运行 Wiki 同步，未请求可选归档不阻止任务完成。 +- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。 ## 项目入口 diff --git a/docs/delivery/README.md b/docs/delivery/README.md index e8ec8cf..402cc1d 100644 --- a/docs/delivery/README.md +++ b/docs/delivery/README.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Delivery-Documentation-Guide wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.- -wiki_revision: 3d95c9d392e81cf59d2af1f6f21d8e67f580b68f -synchronized_at: 2026-08-15T03:02:47Z +wiki_revision: 5b295898612f86ac2301ea243df76fb284912317 +synchronized_at: 2026-08-27T09:06:55Z # 交付文档指南 @@ -79,7 +79,6 @@ synchronized_at: 2026-08-15T03:02:47Z 开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。 - ## Sense MVP 岗位操作路径 Sense 面向网管、实施人员和非技术现场人员，菜单按日常任务组织：工作台 → 设备管理 → 视频接入 → 视频服务 → 实时监看 → 区域与警戒线。普通操作优先展示中文状态与下一步，不要求用户理解 ONVIF、RTSP 或 MediaMTX 内部模型。 @@ -134,3 +133,7 @@ Sense 面向网管、实施人员和非技术现场人员，菜单按日常任 + +## 部署与运维文档 + +YoVision 已有 Sense Windows 交付包和本机 Supervisor 常驻实例，因此维护 `Deployment-and-Operations` 页面。部署命令、服务身份、配置来源、端口、日志、启动停止、回退或升级方式变化时必须先更新该 Wiki 页面，再同步本地镜像。 diff --git a/docs/delivery/deployment-and-operations.md b/docs/delivery/deployment-and-operations.md new file mode 100644 index 0000000..ccfcaa5 --- /dev/null +++ b/docs/delivery/deployment-and-operations.md @@ -0,0 +1,82 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Deployment-and-Operations +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.- +wiki_revision: 367c6aed6eaeece793622431c7d1b11b1b9dbec5 +synchronized_at: 2026-08-27T09:07:20Z + + +# YoVision 部署与运维 + +## 文档信息 + +- 系统：YoVision +- 当前常驻实例：Sense +- 适用环境：Windows 本机开发/验收与 Sense Windows 交付包 +- 维护入口：工单 #108 后由长期 Wiki 持续维护 +- 安全边界：本文不记录数据库密码、管理员密码、摄像头凭据、JWT/会话密钥或 Gitea token + +## 部署范围与边界 + +当前可核对的常驻服务是 Sense。Brain 尚未初始化，Bell 新 GoAdmin 基线尚未完成，因此不在本页提供虚构的生产部署命令。三个交付单元保持独立配置、数据、身份、版本和发布边界；跨项目编排必须另建协调工单。 + +## 目录与入口 + +- Sense 项目目录启动入口：`Sense\start_sense.bat` +- Windows 交付包：`Sense\dist\sense-windows-amd64` +- 包内启动入口：`Sense\dist\sense-windows-amd64\start-sense.bat` +- 包内配置：`Sense\dist\sense-windows-amd64\config\sense.env` +- 项目配置源：`Sense\config\sense.env` +- 构建入口：`Sense\scripts\build\build-windows.bat` +- 本机 Supervisor 根目录：`D:\supervisor` + +`Sense\start_sense.bat` 只定位并调用交付包入口、透传参数和退出码；它不读取配置、不自动构建，也不直接启动 Go 或 Node 开发服务。MediaMTX 是否随包启动由 Sense 包内运行脚本和配置控制。 + +## 配置与秘密 + +- 生产模式必须提供有效 PostgreSQL 连接和应用安全配置；变量名及无敏感示例以项目或交付包中的 `.env.example` 为准。 +- 配置文件和进程环境中的秘密不得提交到 Git、工单、Wiki、日志或示例。 +- Sense、Bell 必须使用不同数据库角色、用户库、JWT/会话密钥和 Cookie；Brain 使用独立机器身份。 +- 修改服务账号、权限、端口、数据库、媒体二进制或持久化目录前必须建立相应工单并说明回退。 + +## 构建与启动 + +从 Sense 目录生成 Windows 包： + +```powershell +Sense\scripts\build\build-windows.bat +``` + +生成包并正确配置后，可从仓库根运行： + +```powershell +Sense\start_sense.bat +``` + +临时演示模式可透传 `demo` 参数；演示数据随进程停止而丢失，不得作为生产部署。 + +## Supervisor 常驻实例 + +本机 Supervisor 的 YoVision Sense 实例由工单 #106 建立。Supervisor 配置、启动停止命令、工作目录、环境文件和日志位置以 `D:\supervisor` 中的当前实例配置为准。修改该外部目录前必须建立工单并确认精确目标；仓库不得复制其中的秘密。 + +## 健康检查与日志 + +- 默认 Sense 访问地址以当前配置为准；已验收的本机默认地址为 `http://127.0.0.1:18080/`。 +- 先确认端口监听和 HTTP 页面，再检查 Sense 结构化日志、PostgreSQL 连接、数据库迁移以及 MediaMTX 进程和路径状态。 +- 日志不得输出数据库密码、摄像头凭据、会话 Cookie、JWT secret 或 token。 +- 具体视频、迁移和登录故障按 `Troubleshooting` 页面处理。 + +## 停止、升级与回退 + +- 手工前台启动时在原控制台正常终止进程；Supervisor 托管时使用该实例的受控停止方式，避免同时启动第二个占用相同端口的进程。 +- 升级前记录当前 Git 提交、交付包版本、数据库备份/恢复方案和配置差异。 +- 数据库迁移、凭据、权限或不可逆操作属于高风险，必须另建工单并等待确认。 +- 回退优先恢复上一已验收交付包和对应配置；涉及数据库迁移时只能使用该迁移工单确认的回退方案。 + +## 最小验收 + +- 启动入口、工作目录、配置来源和端口与实际一致。 +- Sense 页面与必要 API 可访问，数据库迁移成功。 +- MediaMTX 启用时进程、路径和播放链路状态可定位。 +- Supervisor 不会与手工进程重复占用端口。 +- 日志和文档没有秘密；未验证的 Brain、Bell、真机或生产行为明确标注。 diff --git a/docs/task/66-Sense视频接入与Profile.md b/docs/task/66-Sense视频接入与Profile.md index db9b259..0152ac3 100644 --- a/docs/task/66-Sense视频接入与Profile.md +++ b/docs/task/66-Sense视频接入与Profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Task-66-Sense视频接入与Profile wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-66-Sense%E8%A7%86%E9%A2%91%E6%8E%A5%E5%85%A5%E4%B8%8EProfile.- -wiki_revision: 322feb232fc03c3a9ba22f65504cf3e151fb0e57 -synchronized_at: 2026-08-14T09:15:26Z +wiki_revision: 87b3a59f3f27df1f1fb357f6c13a1e31cdde5e05 +synchronized_at: 2026-08-27T09:13:37Z # 66 Sense视频接入与Profile @@ -32,6 +32,13 @@ synchronized_at: 2026-08-14T09:15:26Z - 复用 GoAdmin JWT/Casbin/操作审计、迁移和 go-admin-ui BasicLayout、Element Plus Form/Dialog/Table/Tag、动态菜单与权限按钮。 - implementation_operator、site_admin 可发现和探测，viewer 只读保存结果。 +## 修改文件 + +- 后端入口与业务：`Sense/server/app/admin/router/sense_admission.go`、`Sense/server/app/sense/admission/**`、`Sense/server/app/sense/onvif/**`、`Sense/server/app/sense/rtsp/**`。 +- 数据与验证：`Sense/server/cmd/migrate/migration/version/2026081417000_profile.go`、`Sense/server/tests/admission/postgres_test.go`。 +- 前端：`Sense/ui/src/api/sense/admission.js`、`Sense/ui/src/views/sense/admission/**`、`Sense/ui/src/views/sense/device/index.vue` 及对应单元测试。 +- 完整文件清单以实现提交 `2bb1614` 和 PR #84 的 Git diff 为准。 + ## 验收结果 | 标准 | 结果 | @@ -54,7 +61,7 @@ synchronized_at: 2026-08-14T09:15:26Z - PostgreSQL 17：迁移与重复迁移通过；migration=1、tables=2、menus=3、policies=7。 - SENSE_ADMISSION_TEST_DATABASE_URL 隔离测试：写入 Profile、重开连接、读取主子码流通过。 - Wiki 镜像检查：通过。 -- 未验证部分：未连接客户或实验室真实摄像机；真实厂商 Digest/RTSP 兼容、网络 ACL、设备校时和目标浏览器留待授权现场验收，不声称已通过。 +**未验证部分**：未连接客户或实验室真实摄像机；真实厂商 Digest/RTSP 兼容、网络 ACL、设备校时和目标浏览器留待授权现场验收，不声称已通过。 ## 回退 diff --git a/docs/task/67-Sense视频服务生命周期与状态对账.md b/docs/task/67-Sense视频服务生命周期与状态对账.md index 5f59a14..516454a 100644 --- a/docs/task/67-Sense视频服务生命周期与状态对账.md +++ b/docs/task/67-Sense视频服务生命周期与状态对账.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Task-67-Sense视频服务生命周期与状态对账 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-67-Sense%E8%A7%86%E9%A2%91%E6%9C%8D%E5%8A%A1%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E4%B8%8E%E7%8A%B6%E6%80%81%E5%AF%B9%E8%B4%A6.- -wiki_revision: 4642924705d7a3406874ef532579fb2d6a25a88b -synchronized_at: 2026-08-14T10:13:23Z +wiki_revision: 718765b6b8eff5f4c81612ea8720272c97cd1a25 +synchronized_at: 2026-08-27T09:13:38Z # 67 Sense视频服务生命周期与状态对账 @@ -30,6 +30,13 @@ synchronized_at: 2026-08-14T10:13:23Z - 接入成功后幂等建立路由；冷启动恢复 desired=running，明确 stopped 路径保持停止；稳定路径只刷新状态，不重复下发或增加版本。 - 复用 GoAdmin JWT/Casbin/操作审计、迁移、动态菜单和 go-admin-ui BasicLayout、Element Plus Descriptions/Table/Tag/Button/MessageBox。 +## 修改文件 + +- 后端入口与业务：`Sense/server/app/admin/router/sense_media.go`、`Sense/server/app/sense/media/**`、`Sense/server/app/sense/reconcile/**`。 +- 数据、配置与验证：`Sense/server/cmd/migrate/migration/version/2026081419000_media*`、`Sense/server/config/mediamtx/mediamtx.yml.example`、`Sense/server/tests/media/**`。 +- 前端：`Sense/ui/src/api/sense/media.js`、`Sense/ui/src/views/sense/media/**` 及对应单元测试。 +- 完整文件清单以实现提交 `19f9bfa` 和 PR #85 的 Git diff 为准。 + ## 验收结果 | 标准 | 结果 | @@ -53,7 +60,7 @@ synchronized_at: 2026-08-14T10:13:23Z - PostgreSQL 17 定向迁移：3 个菜单、12 条角色策略、1 条迁移记录通过。 - Wiki 镜像检查：通过。 - 已处理测试安全问题：MediaMTX 自动 TLS 文件的工作目录已固定到外部配置目录；临时证书/私钥未进入最终提交或远端。 -- 未验证部分：未连接客户真实摄像机和现场网络；真实上游持续拉流、reader 变化、端口 ACL 和目标浏览器留待授权现场验收。 +**未验证部分**：未连接客户真实摄像机和现场网络；真实上游持续拉流、reader 变化、端口 ACL 和目标浏览器留待授权现场验收。 - 已知相邻问题：空白 PostgreSQL 执行完整上游迁移链时，在到达 #67 前被旧 `sys_config` 初始化字段长度问题中止；#67 定向迁移已通过，空库安装链应由 #70/#71 单独复核，不在本工单混改上游初始化。 ## 回退 diff --git a/docs/templates/deployment.md b/docs/templates/deployment.md new file mode 100644 index 0000000..4c676ed --- /dev/null +++ b/docs/templates/deployment.md @@ -0,0 +1,282 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Deployment-Template +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-Template.- +wiki_revision: 75bd653ab2f3314a37eb9086e18152129941befa +synchronized_at: 2026-08-27T09:07:38Z + + +# 部署文档模板 + +> 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。 +> +> 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](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 +``` + +**预期结果**：健康检查全部通过。 + +> **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。 + +### 备份与恢复 + + + +## 已知限制 + + + +-