AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

CTO来分享：如何让技术人员写好开发文档？

2022-11-13 123
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： CTO来分享：如何让技术人员写好开发文档？

前言

对于如何让技术人员写好开发文档，这是一个很常见的问题。

本次不过多分享理论，而是通过分享我们团队新成员编写的第一份真正的开发文档，作为成例，给大家参考和借鉴。

对于新人，一开始就明确高标准、提高专业要求，是很有价值的。

需求背景

有一天，有位YesDev的企业客户和我们提到：“黄总， 上次说的客户管理的流程下，手工选择发送【反馈信息】，方式为短信，企业微信，钉钉，邮件。 四种方式的配置信息和客户管理进行 关联配置。 发送后有发送记录可以进行管理，检索和导出。 发送内容可以根据需求自动生成。 其中短信可以进行模板管理和分配，短信发送接口配置（建议阿里云短信）。”

于是，我们产品经理整理并设计了以下的产品方案和PRD。

以下，则是对应的技术开发人员在完整需求开发的同时，编写整理的开发文档。内容包含：开发分支、单元测试、SQL数据库变更、核心流程的时序图、新增的API接口、单元测试覆盖率报告、新增的配置文件等。

使用的研发协同工具

YesDev，一款更友好的研发协同工具。

开发文档成例分享

需求背景

用户需要一个可以管理自己客户及客户联系人的功能，并且在需求需要反馈时，可以选择发短信或者邮件进行通知

仓库地址

https://codeup.aliyun.com/xxxxxxx/yesinew/yesinew_www.git
使用的是codeup云效。

后端开发分支

mxh_test

实现思路

  1. 用户需要可以配置短信和邮箱服务的后台录入功能
  2. 用户需要进行客户名单的管理，包括但不限于客户分组、客户管理、客户联系人等功能，并且对以上的功能可添加、编辑、删除以及查看
  3. 前端需增加反馈功能模块，用户可以获取录好的客户名单，进行邮件/短信通知，并且记录反馈通知信息
  4. 用户可以查看某个需求的发送给客户的反馈列表，也可以在企业管理后台，进行发送反馈记录的查看和导出记录

新增接口（基于PhalApi开源接口框架）

  • Platform.Customer_Customer.AddCustomer 添加客户
  • Platform.Customer_Customer.AddCustomerContacts 新增客户联系人
  • Platform.Customer_Customer.AddCustomerGroup 添加客户分组
  • Platform.Customer_Customer.DeleteCustomer 删除客户
  • Platform.Customer_Customer.DeleteCustomerContacts 删除客户联系人
  • Platform.Customer_Customer.GetContactsListByCustomerId 根据客户ID获取联系人列表
  • Platform.Customer_Customer.GetCustomerDetailLeftSideMenu 客户详情页左边栏
  • Platform.Customer_Customer.GetCustomerGroupList 获取客户分组列表
  • Platform.Customer_Customer.GetCustomerGroupOption 获取客户分组选项，用于select标签
  • Platform.Customer_Customer.GetCustomerList 获取客户列表(用于分组下的客户名单管理)
  • Platform.Customer_Customer.GetFeedbackContactsList 发送反馈时用到的客户联系人列表
  • Platform.Customer_Customer.GetOneCustomer 获取单个客户
  • Platform.Customer_Customer.GetOneCustomerContacts 获取单个客户联系人
  • Platform.Customer_Customer.GetOneCustomerDetail 获取单个客户详情(用于客户详情页)
  • Platform.Customer_Customer.UpdateCustomer 编辑客户
  • Platform.Customer_Customer.UpdateCustomerContacts 编辑客户联系人
  • Platform.Customer_Customer.UpdateCustomerGroup 编辑客户分组
  • Platform.Customer_Feedback.GetFeedbackList 获取反馈列表(用于前端需求页面)
  • Platform.Customer_Feedback.GetFeedbackListForAll 企业后台获取反馈列表
  • Platform.Customer_Feedback.GetFeedbackListForAllExportData 反馈列表导出
  • Platform.Customer_Feedback.GetFeedbackListForAllExportUrl 企业后台获取反馈列表导出链接
  • Platform.Customer_Feedback.SendFeedback 发送反馈信息接口
  • Platform.Sms_Sms.AddSmsConfig 添加短信配置
  • Platform.Sms_Sms.AddSmsTemplate 添加短信模板
  • Platform.Sms_Sms.DeleteSmsTemplate 删除单个短信模板
  • Platform.Sms_Sms.GetOneSmsConfig 获取短信配置
  • Platform.Sms_Sms.GetOneSmsTemplate 获取单个短信模板
  • Platform.Sms_Sms.GetSmsTemplateDetailByMoudleId 根据短信模板ID和模块ID，来获取替换后的短信文本
  • Platform.Sms_Sms.GetSmsTemplateList 获取短信模板列表
  • Platform.Sms_Sms.GetSmsTemplateListByOpen 获取已开启的短信模板
  • Platform.Sms_Sms.GetSmsTemplateParam 获取短信模板变量列表
  • Platform.Sms_Sms.SendSmsTest 发送短信测试
  • Platform.Sms_Sms.UpdateSmsConfig 修改短信配置
  • Platform.Sms_Sms.UpdateSmsTemplate 更新单个短信模板
  • Platform.Customer_Feedback.GetFeedbackList 获取反馈列表(用于前端)
  • Platform.Customer_Feedback.GetFeedbackListForAll 企业后台获取反馈列表
  • Platform.Customer_Feedback.GetFeedbackListForAllExportData 需求导出
  • Platform.Customer_Feedback.GetFeedbackListForAllExportUrl 企业后台获取反馈列表导出链接
  • Platform.Customer_Feedback.SendFeedback 发送反馈信息

修改的接口

  • Platform.Notes.CreateNewNote 添加新备注
  • Platform.Notes.GetNoteListMoreInfo 获取备注列表
  • Platform.AppSiteConfig_AppSiteConfig.AddOrUpdateAppSiteConfig 添加app配置设置

文件变更（基于PhalApi开源接口框架）

config/sms.php                                   |  22 +++
data/phalapi_pro.sql                             | 101 ++++++++++
src/app/Common/Api.php                           |  17 +-
src/base/Common/Sms.php                          |  70 +++++++
src/base/Common/ToolUtil.php                     |  67 +++++++
src/base/Common/UrlUtil.php                      |   5 +
src/base/Domain/AppSms.php                       |  73 ++++++++
src/base/Domain/Base.php                         |   8 +-
src/base/Domain/Customer.php                     | 348 ++++++++++++++++++++++++++++++----
src/base/Domain/CustomerFeedback.php             | 350 +++++++++++++++++++++++++++++++++++
src/base/Domain/Notes.php                        |  11 +-
src/base/Domain/Sms.php                          |   2 +-
src/base/Domain/SmsConfig.php                    | 243 ++++++++++++++++++++++++
src/base/Model/Customer.php                      |   5 +-
src/base/Model/CustomerContacts.php              |   5 +-
src/base/Model/CustomerFeedback.php              |  72 +++++++
src/base/Model/CustomerGroup.php                 |   6 +-
src/base/Model/SmsConfig.php                     |  11 ++
src/base/Model/SmsTemplate.php                   |  11 ++
src/platform/Api/AppSiteConfig/AppSiteConfig.php |   6 +-
src/platform/Api/Customer/Customer.php           | 218 +++++++++++++++++++++-
src/platform/Api/Customer/Feedback.php           | 150 +++++++++++++++
src/platform/Api/Notes.php                       |  11 +-
src/platform/Api/Sms/Sms.php                     | 184 +

数据库变更（使用MySQL数据库）

DROP TABLE IF EXISTS `pp_sms_config`;
  CREATE TABLE `pp_sms_config` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `access_key` varchar(255) NOT NULL DEFAULT '' COMMENT '短信服务商的access_key',
    `access_secret` varchar(255) NOT NULL DEFAULT '' COMMENT '短信服务商的access_secret',
    `config_status` tinyint(2) NOT NULL DEFAULT 0 COMMENT '邮箱状态：1-开启  0-关闭',
    `admin_id` int(11) NOT NULL DEFAULT '0' COMMENT '管理员ID',
    `add_time` datetime DEFAULT NULL COMMENT '创建时间',
    `app_key` varchar(100) NOT NULL DEFAULT '公司标识',
    `created_staff_id` int(11) NOT NULL DEFAULT '0' COMMENT '创建员工ID',
    PRIMARY KEY (`id`)
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = '短信配置表';
  DROP TABLE IF EXISTS `pp_sms_template`;
  CREATE TABLE `pp_sms_template` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `sms_sign` varchar(255) NOT NULL DEFAULT '' COMMENT '短信签名',
    `template_code` varchar(255) NOT NULL DEFAULT '' COMMENT '短信模板Code',
    `template_detail` text COMMENT '短信模板详情',
    `template_status` tinyint(2) NOT NULL DEFAULT 0 COMMENT '邮箱状态：1-开启 0-关闭',
    `admin_id` int(11) NOT NULL DEFAULT '0' COMMENT '管理员ID',
    `add_time` datetime DEFAULT NULL,
    `app_key` varchar(100) NOT NULL DEFAULT '',
    `created_staff_id` int(11) NOT NULL DEFAULT '0' COMMENT '员工ID',
    PRIMARY KEY (`id`)
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = '短信模板表';
  DROP TABLE IF EXISTS `pp_customer_group`;
  CREATE TABLE `pp_customer_group` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `group_name` varchar(100) NOT NULL DEFAULT '' COMMENT '分组名称',
    `customer_num` int(10) NOT NULL DEFAULT 0 COMMENT '分组下的客户人数（冗余）',
    `admin_id` int(11) NOT NULL DEFAULT '0' COMMENT '管理员ID',
    `add_time` datetime DEFAULT NULL COMMENT '创建时间',
    `app_key` varchar(100) NOT NULL DEFAULT '公司标识',
    `created_staff_id` int(11) NOT NULL DEFAULT '0' COMMENT '员工ID',
    PRIMARY KEY (`id`)
  )ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = '客户分组表';
  DROP TABLE IF EXISTS `pp_customer`;
  CREATE TABLE `pp_customer` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `customer_name` varchar(255) NOT NULL DEFAULT '' COMMENT '客户名称',
    `customer_level` varchar(20) NOT NULL DEFAULT 'A' COMMENT '客户等级，A-E',
    `group_id` int(10) NOT NULL DEFAULT 0 COMMENT '分组ID',
    `feedback_num` int(10) NOT NULL DEFAULT 0 COMMENT '反馈次数（冗余）',
    `customer_status` tinyint(1) NOT NULL DEFAULT 1 COMMENT '客户状态：1-开启 0-隐藏',
    `customer_remark` text COMMENT '客户备注',
    `admin_id` int(11) NOT NULL DEFAULT '0' COMMENT '管理员ID',
    `add_time` datetime DEFAULT NULL COMMENT '创建时间',
    `app_key` varchar(100) NOT NULL DEFAULT '公司标识',
    `created_staff_id` int(11) NOT NULL DEFAULT '0' COMMENT '员工ID',
    PRIMARY KEY (`id`)
  )ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = '客户表';

注意事项

  1. 新增了./config/sms.php，
第71行 ./config/sms*.php
  1. 新增模块客户反馈，需要在两个表配置权限
INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (440, 'platform', '/customer', '主模块 - 客户管理', NULL);
INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (441, 'platform', '/customer/list', '客户管理模块 - 客户列表', NULL);
INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (442, 'platform', '/customer/detail', '客户管理模块 - 客户详情', NULL);
INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (443, 'platform', '/customer/feedback', '客户管理模块 - 客户反馈记录', NULL);
INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (444, 'platform', '/service-config/sms', '服务配置 - 短信服务配置', NULL);

单元测试（使用PHPUnit）

邮件/短信发送的时序图（使用ProcessOn等工具可在线制作UML）


最终实现的效果截图（在YesDev可免费体验和真实使用）

登录后选择你的研发团队，

在企业管理后台，录入客户信息，

配置短信通道和通知文案，

最后，在前台可以进行邮件通知反馈，

也可以进行短信的通知反馈。

文章标签：
前端开发
测试技术
SQL
关系型数据库
MySQL
API
数据库
uml
1554023534442740
目录
相关文章
flydean程序那些事
|
8月前
一键自动化博客发布工具,用过的人都说好(51cto篇)
使用一键自动化博客发布工具blog-auto-publishing-tools把博客发布到51cto上。
flydean程序那些事
85 0
一键自动化博客发布工具,用过的人都说好(51cto篇)
可喜可乐
|
弹性计算 前端开发 NoSQL
新手学生上线我的博客
自己参加飞天加速计划活动，阿里云助力学生免费上线项目，我也成功使自己的小项目上线，在学期间学习前端相关知识，逐渐熟练后便开编写了一个小项目，通过老师了解阿里云的飞天加速计划活动，通过新手预备营学习了上线服务器的步骤，再经过学习发现问题解决问题，最后成功上线自己的项目。
可喜可乐
152 1
新手学生上线我的博客
开发工程师
|
JavaScript Java 应用服务中间件
从 0 开始搭建一个技术博客，私藏干货~
技术博客的选型有很多种，如：博客园、CSDN、开源中国、简书、知乎等……都可以用来写文章，形成自己的技术博客。 上面的博客都是第三方的，有没有方式搭建自己的服务器、自己的域名的博客呢？栈长知道的成熟方案有：WordPress, Hexo 等，栈长的博客就是用 Hexo 搭建的。
开发工程师
1023 0
从 0 开始搭建一个技术博客，私藏干货~
微wx笑
|
程序员
为什么写技术博客对新人如此重要?
最近看到一篇文章，站在招聘者的角度提出了自己对这个问题的看法，主要是以下几个方面：台湾和大陆的对比首先谈谈台湾情况，Programmer 在台湾不叫程序员，而是程式设计师，从搜索引擎找台湾程序员，往往得到的是内地搜索结果。
微wx笑
1231 0
迦境0125
|
存储 关系型数据库 程序员
CTO职场解惑指南系列（一）
基于科技能够改变世界的事实，几乎每个公司的程序员都自带闪光灯。程序员的手和普通人的手自然是有区别的，“我们可是用双手改变了世界” 。（码农真的是靠双手吃饭，呵呵） 这个世界上但凡靠双手吃饭就会特别不容易，真的特别。
迦境0125
1469 0
幻凡ss
|
JavaScript Shell 开发工具
用码云搭建简单的个人个性博客
很简单，大概一个小时就可以做好！ 先说下原理 码云pages是一个静态网站托管地方，再加上码云本来就是个代码托管的地方，集成pages后，可以很方便的部署你的代码 本文原理：利用 马克飞象生成博客的md文件，利用He...
幻凡ss
2552 0
技术小甜
把你的博客办的更好的45个技巧
技术小甜
1252 0
小尘哥
|
JavaScript 开发工具 git
搭建自己的个性博客平台
每次百度问题看到别人的个性博客，都纳闷是怎么来的，本教程教你搭建一个自己的个性博客平台。采用当前流行的博客开源框架hexo+oschina，别问为啥不用github~~~支持国产，哈哈哈 1、准备工作 本地安装nodejs环境 oschina帐号...
小尘哥
1247 0
zting科技
使用wiz（为知）发布网易博客实践
zting科技
1170 0
zting科技
|
程序员 JavaScript
说说程序员、博客、论坛及个人专业相关知识的提高
zting科技
1223 0

热门文章

最新文章

  • 1
    为什么说流处理即未来？
  • 2
    【实战】锐捷AC+AP配置WLAN基本服务系列
  • 3
    Mac：安装Python3并配置环境变量（本地多个Python版本选择配置）
  • 4
    丰富、连接、待集成—MaxCompute 生态再出发
  • 5
    Tomcat 7.0 64位免安装解压版 安装及配置
  • 6
    securecrt克隆会话与sshd 的 MaxSessions
  • 7
    C语言结构体的使用！简易学生成绩统计程序发布！
  • 8
    《VMware Virtual SAN权威指南》一2.2　VSAN的要求
  • 9
    webstorm9.0.3 注册码
  • 10
    数据文件offline后unusable索引造成的问题
  • 1
    LangGraph：构建多代理动态工作流的开源框架，支持人工干预、循环、持久性等复杂工作流自动化
    27
  • 2
    Eliza：TypeScript 版开源 AI Agent 开发框架，快速搭建智能、个性的 Agents 系统
    25
  • 3
    AI Dev Gallery：微软开源 Windows AI 模型本地运行工具包和示例库，助理开发者快速集成 AI 功能
    33
  • 4
    「Mac畅玩鸿蒙与硬件51」UI互动应用篇28 - 模拟记账应用
    100
  • 5
    我的博客年度之旅：感恩、成长与展望
    87
  • 6
    《构建高效K近邻算法：降低计算复杂度的策略与实践》
    24
  • 7
    《提升支持向量机泛化能力：核函数改进策略大揭秘》
    16
  • 8
    《智能算法设计与开发的全解析：从理念到实践》
    20
  • 9
    《深度学习梯度消失问题：原因与解决之道》
    21
  • 10
    《docker基础篇：8.Docker常规安装简介》包括：docker常规安装总体步骤、安装tomcat、安装mysql、安装redis
    17

    • 相关课程

    更多
  • 云上建站快速入门-博客、论坛、CMS、电子商务网站统统搞定
  • 全栈数据工程师养成攻略
  • 场景实践 - 云上建站博客、论坛、CMS、电子商务网站
  • mPaaS运维工程师认证课程
  • 企业运维训练营之数据库原理与实践课程

    • 相关电子书

    更多
  • 从码农到CTO再到CEO过程中的认知升级
  • 钉钉酷应用开发手册
  • 2020前端工程师必读手册
    • 下一篇
    阿里云无影云电脑免费试用，最长可试用3个月