研发任务管理系统 H5 — 冷启动文件

研发任务管理系统 H5 — 冷启动文件

版本: 1.0 ｜更新: 2026-08-31 ｜用途: 研发任务管理系统（含库房集成）的冷启动/重建/排障手册
⚠️ 功能保全铁律（用户定稿）：本系统功能只增不减，改版前先读本文件，改完逐项验证，功能不允许丢失。
⚠️ 测试铁律：测试必须用独立数据/独立进程，严禁污染生产数据（rd_tasks.json/accounts.json/store.db）。

一、系统概述

研发任务管理 + 研发库房管理一体化系统（钉钉生态）：

任务：任务看板（跟踪任务/临时任务）、筛选（优先级/项目/状态/更新天数/搜索）、人员筛选、新增任务、更新记录（带时分+附件+可删）、子任务（进度联动）、工时统计、日报生成
账户体系：管理员（武燕青）全权；普通用户（钉钉人员）只看自己任务、可编辑自己任务；管理员可配置用户权限
登录：钉钉统一认证（JSAPI 免登 requestAuthCode / OAuth 授权码 / 工作台 authCode 三通道）
库房集成：底部导航 3 tab（任务/库房/我的）；库房 = 研发库房管理（独立子系统，蓝图挂载）
线上地址：https://rd.huiflytech.com（Caddy HTTPS）＝ https://rd.huiflytech.com/rd/（任务）、/store/（库房）

二、部署架构

<code> 用户/钉钉 → https://rd.huiflytech.com (Caddy :443/:80 自动 HTTPS)

       → rd-h5.service (systemd, Flask :13544, 统一进程)
            ├─ /rd/*        → 任务前端 + API（rd_h5.py + rd_h5.html）
            ├─ /store/*     → 库房前端 + API（rd_store.py 蓝图 + rd_store.html）
            └─ /api/*       → 任务 API

<code>

systemd 服务：`rd-h5.service`（ExecStart=/home/ubuntu/projects/ctwing-2/venv/bin/python /home/ubuntu/.hermes/scripts/rd_h5.py，端口 13544）
Caddy：`/etc/caddy/Caddyfile`（rd.huiflytech.com → 127.0.0.1:13544；80→443 自动跳转；Let's Encrypt 自动证书）
数据目录：`/home/ubuntu/docs/`

三、数据文件

文件	内容	说明
——	——	——
`rd_tasks.json`	任务数据（items/updated_at）	主数据；normalize 兼容字段
`accounts.json`	账户体系	roles.admin（武燕青）/roles.user/perms（用户权限）/pwds
`people.json`	人员库	简称→全名（钉钉通讯录）；注意：无 roles 字段（admin 判定在 accounts.json）
`ding_org.json`	钉钉通讯录全量	MCP 同步缓存（17 人：姓名/userid/部门）；/api/ding/org 优先读此文件
`store.db`	库房 SQLite	samples/requests/history 表（软删除 deleted 标记）
`.env`	凭证	DINGTALK_CLIENT_ID/SECRET（慧飞任务应用 dingh2ogz…）、DINGTALK_CORP_ID=4901944860、HALO_DB_PASSWORD 等

四、核心功能

1. 任务看板

任务类型：跟踪任务（[优先级](项目)内容）/ 临时小任务（⏱️ 当天）
筛选：优先级/项目/状态/未更新天数（工作日）/搜索；人员标签筛选（点击）
人员标签：显示所有有任务人（从任务提取）；“＋更多”打开钉钉通讯录全量（17 人）
任务详情：状态/进度/负责人/子任务（进度联动）/更新记录（带时分+附件）/总耗时

2. 账户体系（2026-08-31）

管理员：武燕青（全部权限：查看/编辑/删除所有任务、账号管理、生成日报、新增）
普通用户：只见自己任务（负责人=自己或子任务负责人=自己，简称/全名变体匹配 is_mine）、可编辑/删除自己任务（can_edit/can_delete）
权限配置：管理员「账号管理」弹窗（view_own_only/edit_own/delete_own/manage_subtask 开关 + 设置口令）
后端强制校验：can_edit/can_delete 在 update_task/add_note/del_note/del_task/subtask_note 接口执行（403）
⚠️ isAdmin 判定：统一账户体系（USER_ROLE=admin 或名字=武燕青）；不依赖 people.json roles（空）

3. 钉钉统一认证（3 通道）

JSAPI 免登（主，钉钉内）：UA 检测 DingTalk → 加载 dingtalk.open.js → requestAuthCode({corpId: ding3049357e0fcfed24f5bf40eda33b7ba0}) → code → /api/ding/login（gettoken+getuserinfo）→ 自动登录
OAuth 授权码（浏览器）：/api/ding/oauth/url 生成授权 URL → 回跳 /rd/ding_cb?code → /api/ding/oauth/cb（userAccessToken+users/me）→ 登录
工作台 authCode：URL 带 authCode → 直接 dingLogin（失败自动降级 JSAPI）
登录态：localStorage rd_user（同域任务/库房共享）；登录用户自动退出只读模式（exitReadonly）

4. 库房集成（2026-08-31 迁移）

rd_store.py 改 Blueprint（bp）挂载到 rd_h5 统一进程（13544）；rd-store.service 已停（13545 退役）
库房独立运行兼容：`STORE_DB=/tmp/x.db STORE_PORT=13599 python rd_store.py`（测试隔离）
底部导航（任务/库房/我的）：任务=视图切换；库房=跳 /store/；我的=账户信息
库房页登录校验：同域读 localStorage rd_user，未登录显示橙色提示条（不覆盖页面）
库房 tabbar 用 div（不能用 nav——库房 CSS 有 nav 标签选择器 sticky 会覆盖 fixed）

5. 底部导航（3 tab）

我的：账户信息（姓名/身份/钉钉ID/登录方式/我的任务数/权限）+ 账号管理（管理员）+ 返回首页 + 退出登录
普通用户无「切换身份」「账号管理」

五、API 列表

API	方法	说明
—–	——	——
/api/tasks	GET	任务列表（?user= 过滤：普通用户只看自己；admin 全量）
/api/tasks	POST	新增任务（记录 creator）
/api/tasks/<tid>	POST	更新任务（can_edit 校验）
/api/tasks/<tid>	DELETE	删除任务（can_delete 校验）
/api/tasks/<tid>/note	POST	添加更新记录（can_edit）
/api/tasks/<tid>/note/<idx>	DELETE	删除记录（can_edit）
/api/tasks/<tid>/subtask/<idx>/note	POST	子任务更新（can_edit）
/api/me	GET	当前用户信息（role/perms）
/api/accounts	GET/POST	账户列表（管理员）/配置权限（管理员）
/api/login_pwd	POST	口令登录（备用）
/api/set_pwd	POST	设置口令（管理员）
/api/people	GET/POST	人员库
/api/ding/login	POST	免登 authCode→身份
/api/ding/org	GET	钉钉通讯录（读 ding_org.json）
/api/ding/oauth/url	GET	OAuth 授权 URL
/api/ding/oauth/cb	POST	OAuth 授权码→身份
/api/upload	POST	附件上传
/api/report/today	GET	今日日报
/api/store/*	*	库房 API（samples/requests/approve/destroy/back/back_apply/ledger/history/…）

六、关键规则（用户拍板）

管理员：武燕青——查看/编辑所有任务 + 账号管理；普通用户只见/只编辑自己任务
只读模式：?ro=1（共享链接）；登录用户自动退出只读（exitReadonly 恢复标题/按钮）
任务负责人：存简称（张/席），登录用全名——匹配用 name_variants（简称↔全名变体）
普通用户不显示：切换身份、账号管理、口令登录入口（唯一登录=钉钉认证）
日报：生成今日日报（按任务/工时）；员工日报汇总 21:30 推送（cron 52967bf00170）
钉钉通讯录：MCP 同步到 ding_org.json（cron 8f32fd550f80 每周一 06:00）

七、部署运维

<code> sudo systemctl restart rd-h5.service # 重启 sudo journalctl -u rd-h5.service -n 50 # 日志 sudo systemctl reload caddy # Caddy 重载 sudo vi /etc/caddy/Caddyfile # 域名配置（rd.huiflytech.com → 13544） git -C /home/ubuntu add -A && git -C /home/ubuntu commit -m “…” # 版本管理 <code>

证书：Caddy 自动（Let's Encrypt）；阿里云手动证书包可留档备用
域名 DNS：rd.huiflytech.com → 82.156.85.124（huiflytech.com 已备案，80/443 不被劫持）

八、排障速查

现象	原因	解决
——	——	——
钉钉打开不自动登录	应用类型/权限	JSAPI 免登需钉钉 JSAPI 安全域名；应用需在钉钉后台配置
免登报“不合法的appKey”	凭证错	.env CLIENT_ID（ding 开头）+ SECRET 匹配
通讯录同步空	应用未开通通讯录权限	钉钉后台开通 qyapi_get_department_list/member；或 MCP 同步 ding_org.json
管理员变“只读”	applyPerm 用 people.json roles（空）	isAdmin 已改账户体系判定（名字=武燕青）
普通用户看到全部任务	view_own_only 未生效	accounts.json perms；后端 is_mine 过滤
任务匹配不上	owner 简称 vs 全名	name_variants 变体匹配
库房 tabbar 跑中间	nav 标签选择器覆盖	tabbar 用 div 类（不用 nav）
库房内容空白	登录校验覆盖 body	已改提示条（不覆盖）
页面旧版	浏览器缓存	强刷 / 加 ?v= 参数；服务端 no-store

九、测试隔离

任务：测试账号不写生产 rd_tasks.json（改前备份 git 可回滚）
库房：`STORE_DB=/tmp/store_test.db STORE_PORT=13599 python rd_store.py` 独立实例，测完删库
严禁直接操作生产数据；测试数据即时清理

Table of Contents