曼陀林知识库

Edit the page and hit Save. See syntax for Wiki syntax. Please edit the page only if you can improve it. If you want to test some things, learn to make your first steps on the playground.

====== 研发任务管理系统 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） ====
<code>
[📋 任务] [📦 库房] [👤 我的]
<code>
  * 我的：账户信息（姓名/身份/钉钉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` 独立实例，测完删库
  * 严禁直接操作生产数据；测试数据即时清理

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International