Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/

2026-08-07 22:31:32 +08:00

6.5 KiB

Raw Blame History

贡献指南 (CONTRIBUTING)

适用范围: 企微 IT 智能服务台 (wecom_it_smart_desk) 维护者: 宋献（项目负责人）+ Claude（评审协作）+ workbuddy（自动化开发） 最后更新: 2026-06-14

📌 仓库入口

Gitea（公网 Funnel）: https://ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk
Gitea（内网 LAN）: http://100.85.152.112:8418/simon/wecom_it_smart_desk
Tailscale 私网: 100.85.152.112:8418

🌿 分支模型

分支	用途	保护规则
`main`	稳定可发布版本	🔒 禁止直推,需 PR + 1 reviewer
`develop`	主开发分支	🟡 允许 push
`feature/*`	新功能(从 develop 拉)	🟢 自由
`hotfix/*`	紧急修复(从 main 拉)	🟢 自由,合入需评审
`release/*`	发布准备	🟡 自由,合入 main 需评审

主分支: main(默认推送目标)

📝 Commit 规范

格式 (Conventional Commits):

<type>(<scope>): <subject>

<body>

<footer>

type 取值:

type	用途	示例
`feat`	新功能	`feat(messages): 撤回消息端点`
`fix`	Bug 修复	`fix(h5): 修复参与者权限校验`
`refactor`	重构(无新功能 / 无 Bug 修复)	`refactor(agents): 提取鉴权中间件`
`docs`	文档变更	`docs: 评审报告 workbuddy-2026-06-14`
`chore`	构建/工具/依赖	`chore: 强化 .gitignore`
`security`	安全相关	`security: P0 鉴权止血`
`perf`	性能优化	`perf(messages): 消息批量插入`
`test`	测试相关	`test: 加 mark_read 鉴权测试`

scope 取值: 模块名,如 agents / messages / h5 / frontend-agent / nginx / workbuddy

subject: 中文,不超过 50 字,祈使句,如 "修复 xx" 而非 "修复了 xx"

body (可选): 详细说明,每行 ≤ 72 字

footer (可选): 关联 Issue / workbuddy 任务编号,如:

Refs: #18
Refs: workbuddy-2026-06-14-任务-修遗留

示例:

security(ws): WS token 从 URL 改 header 鉴权

【workbuddy 推送 2026-06-14】
- ws.py 服务端: 优先 Authorization: Bearer header, query 降级
- ws.ts 前端: 待 workbuddy 改 Sec-WebSocket-Protocol 方案
- 详见 docs/评审报告/workbuddy-2026-06-14-P0安全.md

Refs: #18
Refs: workbuddy-2026-06-14-任务-修遗留

🔄 PR 流程

推送前自检清单

所有 P0 修复推送前必须 4 件套自检:

鉴权: 新增/修改端点是否有 Depends(get_current_agent) 或 _get_current_employee?
依赖: 改代码是否同步 requirements.txt / package.json?
alembic: 数据库 schema 变化是否生成迁移脚本?
配置: nginx / docker / conf 变化 plan 写了是否做完?

PR 流程

本地开发

git checkout develop
git pull
git checkout -b feature/xxx
# 改代码
git add .
git commit -m "feat(xxx): ..."
git push origin feature/xxx

开 PR(走 Gitea Web 或 API)
- 标题 = commit subject
- 描述 = body 内容 + 关联评审报告 / workbuddy 任务
- Reviewer: simon(主) + 可选 workbuddy auto-review
评审员评审(Gitea UI)
- 🟢 P0 鉴权 / 安全: 必须 Claude 评审 + 通过
- 🟡 功能 / 重构: 至少 1 reviewer 通过
- 🟢 docs / chore: 自审即可
合并
- 评审通过 + status check 绿 → squash merge → 删 feature 分支

🔒 main 分支保护规则

由 Gitea API 配置,目前设定:

项	值
禁止直推	✅
需 PR	✅
Approvals 数	1
Dismiss stale approvals	✅
状态检查必须通过	✅(待配)
管理员限制	✅(管理员也走 PR)

配分支保护:

curl -X POST \
  -H "Authorization: token <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_push": false,
    "enable_pull_request": true,
    "required_approvals": 1,
    "dismiss_stale_approvals": true,
    "block_admin_merge": true
  }' \
  "https://ds923plus.tail58d872.ts.net/api/v1/repos/simon/wecom_it_smart_desk/branch_protections/main"

🤖 workbuddy 推送规则

workbuddy 自动化开发,推送必须满足:

完整自检: 鉴权 + 依赖 + alembic + 配置 4 件套
评审报告: 每次推送生成 docs/评审报告/workbuddy-{日期}-{主题}.md
workbuddy 记忆更新: .workbuddy/memory/{日期}-{主题}.md
5 项遗留: 上一轮评审遗留的 5 项必须修完才能合入下一轮
不叠加新功能: 评审未消化前不推新功能(见 docs/评审报告/ 历次教训)

评审失败处理:

评审标 🔴 P0 → 立即修,不接受反驳(除非评审员改判)
评审标 🟡 P1 → 列入遗留表(workbuddy 记忆 + 风险跟踪表)
评审标 🟢 P2 → 知识库积累,不强制修

🆘 紧急修复 (hotfix)

场景: 生产 P0 漏洞 / 数据丢失风险

流程:

从 main 拉 hotfix/xxx
改 + 测(用预生产环境)
PR → main(快通道,reviewer 优先 @ 宋献)
评审通过 → 立即合并 + 部署
同步 cherry-pick 回 develop

禁止:

❌ 跳过评审
❌ 推 main 直接部署
❌ 评审未通过就部署

📚 关联文档

README.md — 项目总览（新人快速入门）
docs/01-项目总览与部署手册.md — 完整架构设计与部署详情
docs/智能IT服务系统运维手册.md — 统一运维手册
docs/索引.md — 文档目录索引（快速导航）
CHANGELOG.md — 版本变更概览
docs/archive-归档/ — 历史版本详情
.workbuddy/memory/ — workbuddy 任务记忆

📑 文档同步规则

更新文档时需同步关联文档：

更新内容	需同步的文档
新功能/重构	README.md（进度）+ CHANGELOG.md + 相关 docs/*.md
部署变更	智能IT服务系统运维手册.md + 01-项目总览与部署手册.md
安全修复	CHANGELOG.md（Security 章节）+ 评审报告
API 变更	README.md（API 概览）+ 01-项目总览与部署手册.md

文档目录规范：

docs/ 目录下按类型分子目录（deploy/, SOPs/, ADRs/, 评审报告/, archive/ 等）
根目录保留 README.md / CONTRIBUTING.md / CHANGELOG.md（Git 生态标准）
新增文档优先放在 docs/，避免根目录文件膨胀

6.5 KiB Raw Blame History Unescape Escape