Files

T

Simon 44e77dcb0e chore(docs): docs/ 目录全面重新编号 + 重组

**重构前**（旧编号 02-11）：
- docs/02-产品需求/      → 00 产品规划/PRD
- docs/03-技术架构/      → 01-05 子目录散落
- docs/04-原型设计/      → 01-02 产品设计（HTML 原型）
- docs/05-原型设计/      → screens/
- docs/06-测试素材/      → 02-E2E / 03-功能 / 04-版本测试
- docs/07-项目管理/      → 任务说明书/日报/计划
- docs/08-安全审计/      → 审计报告
- docs/09-堡垒运维/      → toolbox / deploy
- docs/10-项目管理/      → 任务说明书（重复）
- docs/11-历史归档/      → deploy-nas-archived

**重构后**（新编号 00-07，语义化）：
- docs/00-产品开发流程与文档管理规范.md
- docs/00-版本迭代总览.md
- docs/01-产品文档/      （PRD/原型/认证/会话/AI 服务/坐席/集成）
- docs/02-技术文档/      （技术方案/架构图/重构记录/前端改造/实现配置）
- docs/03-测试文档/      （E2E/功能用例/版本报告/缺陷单）
- docs/04-运维文档/      （部署运维/运维指南）
- docs/05-运营文档/      （品牌推广/用户手册）
- docs/06-安全审计/      （审计报告）
- docs/07-项目管理/      （任务说明书/日报/计划/看板）

**净收益**：
- 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号）
- 消除 02-产品需求 与 10-项目管理 的编号重叠
- 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录）
- 把运维/安全/项目管理从 0X 散落改为 04/06/07

合计 494 文件 + 78495 行 / - 14076 行

2026-08-03 18:46:55 +08:00

6.5 KiB

Raw Permalink 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 Permalink Blame History Unescape Escape