УТВЕРЖДЁН УЖАС.00001-01 33 01-ЛУ ПРОГРАММНЫЕ СРЕДСТВА

УТВЕРЖДЁН
УЖАС.00001-01 33 01-ЛУ
ПРОГРАММНЫЕ СРЕДСТВА
СЕРВИС «УМНЫЕ ЗНАКОМСТВА» И
КЛИЕНТЫ СЕРВИСА
Руководство программиста
УЖАС.00001-01 33 01
Листов 16
2010
2
УЖАС.00001-01 33 01
АННОТАЦИЯ
Настоящий документ предназначен для программистов и системных администраторов, обслуживающих программу УЖАС.00001-01 «Программные средства сервис «Умные знакомства»
и клиенты сервиса».
В документе содержатся сведения о назначении и условиях применения программы, процедуры инсталляции и начальной настройки серверной части и клиентских частей, а также общие
сведения о структуре программных средств, входные и выходные данные программы. Приводятся сообщения, выдаваемые в ходе работы программы.
Документ соответствует изданию (версии) 0.6 программы УЖАС.00001-01.
3
УЖАС.00001-01 33 01
СОДЕРЖАНИЕ
1. Назначение и условия применения программных средств ................................................ 4
1.1. Назначение программных средств .................................................................................... 4
1.2. Функции, выполняемые программными средствами ...................................................... 4
1.3. Состав аппаратных средств ................................................................................................ 4
1.4. Состав общесистемного программного обеспечения ...................................................... 4
2. Характеристики программных средств ................................................................................ 6
2.1. Выбор архитектуры программного комплекса ................................................................ 6
2.2. Основные классы системы ................................................................................................. 6
3. Обращение к программным средствам ................................................................................ 8
3.1. Установка программных средств....................................................................................... 8
3.2. Запуск программных средств ............................................................................................. 8
3.3. Удаление программных средств ........................................................................................ 8
4.
Описание алгоритмов функциональных задач ............................................................ 9
5. Входные и выходные данные .............................................................................................. 12
6. Сообщения ............................................................................................................................ 14
Перечень сокращений .............................................................................................................. 15
4
УЖАС.00001-01 33 01
1. НАЗНАЧЕНИЕ И УСЛОВИЯ ПРИМЕНЕНИЯ ПРОГРАММНЫХ
СРЕДСТВ
1.1. Назначение программных средств
Программные средства (ПС) сервис «Умные знакомства» и клиенты сервиса представляют собой компоненты службы интернет-знакомств, основанной на отслеживании географического положения пользователей.
1.2. Функции, выполняемые программными средствами
Программные средства сервис «Умные знакомства» и клиенты сервиса должны выполнять следующие функции:
– согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами»);
– регистрация и удаление зарегистрированного пользователя;
– вход в службу знакомств и выход из нее зарегистрированного пользователя;
– определение и задание текущего местоположения пользователя;
– ввод и просмотр сведений персональной анкеты пользователя, включая паспортные
данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.),
физические параметры (рост, вес и т.д.), фотографию;
– поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос;
– отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее;
– поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе
непосредственной близости от пользователя, где радиус непосредственной близости равен 1
(одному) километру.
1.3. Состав аппаратных средств
Минимальная конфигурация аппаратных средств для машин, на которых выполняется сервис, должна позволять запуск серверных приложений на базе Microsoft ASP.NET 4.0 и работу
СУБД Microsoft SQL Server 2008.
Минимальная конфигурация аппаратных средств для веб-клиента должна позволять запуск
любого из современных веб-браузеров (Firefox 4.0, Opera 11, Internet Explorer 9) и обеспечивать
доступ в интернет.
Минимальная конфигурация аппаратных средств для мобильного клиента должна позволять запуск Java-приложений, соответствующих профилю устройства CLDC 1.1 и упакованных в
соответствии со спецификацией MIDP 2.0. При этом для корректного функционирования мобильного клиента абсолютно необходимо наличие периферийного устройства — GPS-сенсора,
снабженного программным интерфейсом, совместимым с JSR-00179 «Location API for J2ME».
1.4. Состав общесистемного программного обеспечения
Для обеспечения функционирования ПС должны быть установлены и настроены:
– для сервиса — серверная версия ОС Microsoft Windows 2003 R2, не ниже; Microsoft
.NET Framework 4.0 Client Profile и Extended Profile, не ниже; Microsoft ASP.NET 4.0, не ниже;
– для веб-клиента — любая ОС, поддерживающая один из указанных браузеров: Firefox
4.0, Opera 11, Internet Explorer 9;
– для мобильного клиента — рекомендуется ОС Symbian S60 5th Edition (или выше), либо
эмулятор мобильного устройства на базе указанной ОС; однако допустима любая мобильная ОС,
имеющая J2ME с профилем CLDC 1.1, поддержкой MIDP 2.0 и JSR-00179.
5
УЖАС.00001-01 33 01
Для корректной работы сервиса необходимо правильно указать строку подключения к базе
данных
в
файле
конфигурации
Web.config
сервиса
(XPath
configuration/connectionStrings/add[name="Entities"]). Для руководства по строкам подключения следует
обратиться к локальной справке СУБД Microsoft SQL Server 2008.
Для корректной работы веб-клиента необходимо обеспечить доступность сервиса по адресу
http://localhost:61673/ServicePrototype.svc.
Для корректной работы мобильного клиента необходимо обеспечить доступность сервиса
по произвольному адресу и соответствие настроек мобильного клиента этому адресу.
6
УЖАС.00001-01 33 01
2. ХАРАКТЕРИСТИКИ ПРОГРАММНЫХ СРЕДСТВ
При разработке ПС использовались языки C# и Java, платформы ASP.NET 4.0 и J2ME,
ORM Entity Framework 4.0.
2.1. Выбор архитектуры программного комплекса
ПC сервиса «Умные знакомства» и клиентов сервиса использует следующую архитектуру
(см. рис. 2.1):
– Клиенты сервиса связываются с сервисом по протоколу HTTP и передают сообщения
в формате SOAP.
– Сервис связывается через прослойку объектно-реляционного отображения (ORM) Entity Framework с СУБД Microsoft SQL Server по протоколу TDF (Tabular Data Format).
СУБД SQL
Server
Рис. 2.1
2.2. Основные классы системы
Основные классы ПС:
1) интерфейс контракта сервиса и его реализации:
– IServicePrototype — контракт сервиса;
– ServicePrototype — серверная реализация контракта;
– SmartDatingClient — клиентская реализация контракта (stub).
2) основные компоненты веб-клиента:
– BasePage – базовый класс всех страниц веб-клиента, предоставляющий доступ к
клиенту сервиса (объекту класса SmartDatingClient), а также информации о текущем ключе шифрования (свойства SessionKey и SessionKeyHash);
– SiteMaster – класс-шаблон, предоставляющий основу разметки для всех страниц
веб-клиента;
– CryptoImpl — реализация криптографических процедур, требуемых для работы с
сервисом.
7
УЖАС.00001-01 33 01
3) основные компоненты мобильного клиента:
– ClientMIDlet — MIDlet клиента, содержащий описание пользовательского интерфейса (компоненты интерфейса, последовательность страниц интерфейса);
– SetLocationThread — класс потока, периодически обновляющего текущее местоположение пользователя по данным GPS-датчика;
– CryptoImpl — реализация криптографических процедур, требуемых для работы с
сервисом.
4) сгенерированные прокси-классы доступа к сервису (в случае ASP.NET — класс
SmartDatingClient, в случае J2ME — набор классов в пакете ru.zombator.services.smartdating.
8
УЖАС.00001-01 33 01
3. ОБРАЩЕНИЕ К ПРОГРАММНЫМ СРЕДСТВАМ
3.1. Установка программных средств
Для установки ПС необходимо выполнить следующие действия:
Установка сервиса
1) зарегистрироваться в системе под учетной записью администратора;
2) извлечь из репозитория папку ST-Prototype/SmartDatingService, поместить ее в нужное
место иерархии папок веб-сервера (IIS или Cassini);
3) в случае использования Cassini — запустить Cassini командой
WebDev.WebServer40.exe /port:61673 /path:"<путь к папке SmartDatingService>"
4) в случае использования IIS — создать в папке SmartDatingService приложение
(Application) и удостовериться, что используетcя пул ASP.NET 4.0;
5) проверить работу сервиса, введя в браузере адрес сервиса. Должна появиться страница
«SmartDatingService Service», сообщающая метаданные сервиса.
Установка веб-клиента
1) зарегистрироваться в системе под учетной записью администратора;
2) извлечь из репозитория папку ST-Prototype/ClientProto/WebUI, поместить ее в нужное
место иерархии папок веб-сервера (IIS или Cassini);
3) в случае использования Cassini — запустить Cassini командой
WebDev.WebServer40.exe /port:8080 /path:"<путь к папке WebUI>"
4) в случае использования IIS — создать в папке WebUI приложение (Application) и
удостовериться, что используетcя пул ASP.NET 4.0;
5) проверить работу веб-клиента, введя в браузере адрес веб-клиента. Должна появиться
страница «Добро пожаловать --- Smart Dating».
Установка мобильного клиента
1) извлечь из репозитория папку ST-Prototype/ClientProto/Client/Last Release, поместить ее
содержимое на карту памяти или во внутреннюю память мобильного устройства;
2) открыть папку Last Release в диспетчере файлов устройства, щелкнуть по файлу
Client.jad для установки;
3) подтвердить установку, несмотря на отсутствие цифровой подписи;
4) по окончании установки в меню «Приложения» (Applications) щелкнуть по ярлыку
«ClientForServise» для запуска клиента;
5) если клиент установлен успешно, на экране появится страница «Мобильный клиент».
3.2. Запуск программных средств
Запуск сервиса происходит автоматически в случае использования IIS, вручную в случае
использования сервера Cassini.
Запуск веб-клиента при использовании IIS производится автоматически, при использовании Cassini — производится вручную с помощью файла start.bat в папке WebUI.
Запуск мобильного клиента осуществляется из меню «Приложения» (или аналогичного),
имя приложения «ClientForServise».
3.3. Удаление программных средств
Для удаления сервиса и веб-клиента необходимо, зайдя в систему с правами администратора, удалить папки SmartDatingService и WebUI соответственно.
Для удаления мобильного клиента следует воспользоваться средством деинсталляции,
предлагаемым ОС мобильного устройства для удаления J2ME-приложений, и удалить приложение «ClientForServise 1.0».
9
УЖАС.00001-01 33 01
4. ОПИСАНИЕ АЛГОРИТМОВ ФУНКЦИОНАЛЬНЫХ ЗАДАЧ
В данном разделе кратко описываются алгоритмы, реализуемые в сервисе, к которым
получают доступ веб-клиент и мобильный клиент.
П р и м е ч а н и е. При описании алгоритмов (всех кроме согласования ключа) многократно повторяемые шаги «проверка правильности хеш-значения сеансового ключа, определение имени и идентификатора пользователя по сеансовому ключу» подразумеваются, но не описываются в силу их очевидности.
4.1. Согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами»)
1) генерация криптографически случайного ключа длиной 256 бит клиентом;
2) упаковка сгенерированного ключа в сообщение «Key Exchange» PKCS1.5, заполнение типа «2» (случайные данные);
3) передача сообщения сервису, вместе с e-mail пользователя (если обмен ключами
осуществляется для создания нового пользователя, вместо e-mail ставится «*»)
4) расшифровка сообщения «Key Exchange» на стороне сервиса, запоминание ключа
сеанса, SHA1-хеша ключа сеанса и e-mail пользователя, осуществившего обмен ключами
4.2. Регистрация и удаление зарегистрированного пользователя
Регистрация:
1) проверка пользователя по базе (нет ли?);
2) расшифрование пароля пользователя ключом сеанса;
3) сохранение SHA1-хеша пароля пользователя в базе в таблице Membership;
Удаление:
1) проверка пользователя по базе (есть ли?);
2) удаление пользователя из таблицы Membership (по выявленному по SHA1-хешу
ключа сеанса идентификатору пользователя).
4.2. Вход в службу знакомств и выход из нее зарегистрированного пользователя
Вход:
1) проверка пользователя по базе (есть ли?);
2) расшифрование пароля пользователя ключом сеанса;
3) проверка SHA1-хеша расшифрованного пароля на соответствие хешу, сохраненному в базе в таблице Membership для данного пользователя;
4) пометка «пользователь с данным ключом сеанса аутентифицирован».
Выход:
1) проверка, аутентифицирован ли пользователь с данным ключом сеанса;
2) удаление пометки об аутентификации;
3) удаление пометки о прохождении обмена ключами, ключ сеанса теперь недействителен.
4.3. Определение и задание текущего местоположения пользователя
Определение:
1) проверка пользователя по базе (есть ли?);
2) получение полей latitude и longitude из базы из таблицы Location для данного ид
пользователя
Задание:
1) проверка пользователя по базе (есть ли?);
2) установка полей latitude и longitude в базе в таблице Location для данного ид
пользователя
3) в поле date_changed («момент обновления местоположения») устанавливается текущий момент времени
10
УЖАС.00001-01 33 01
4.4. Ввод и просмотр сведений персональной анкеты пользователя, включая паспортные
данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.), физические параметры (рост, вес и т.д.), фотографию
Просмотр:
1) проверка пользователя по базе (есть ли?);
2) получение данных из таблицы PersonalData для данного ид пользователя в структуру PersonalData;
3) формирование xml-представления указанной структуры, вида
<pd>
<имя_поля_базы_данных>
значение_поля_если_не_null
</имя_поля_базы_данных>
</pd>
4) зашифрование полученного представления ключом сеанса
Ввод:
1) проверка пользователя по базе (есть ли?);
2) расшифрование xml-представления структуры PersonalData ключом сеанса;
3) заполнение полей структуры PersonalData в соответствии с xml-представлением;
4) обновление (если запись уже есть) или добавление записи в таблицу PersonalData
со значениями полей, соответствующими полям структуры PersonalData
4.5. Поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос
1) создание объекта «запрос поиска»;
2) добавление к созданному объекту критериев поиска (вида «имя_параметра {= |
>= | like} значение), расшифровываемых ключом сеанса;
3) выполнение запроса согласно заданному объекту «запрос поиска» (критерии объединяются ключевым словом and);
4) получение результатов как списка результатов поиска (результат поиска —
структура PersonalData и два поля: latitude (широта), longitude (долгота);
5) вычисление для каждого из результатов расстояния между текущим пользователем и пользователем, чьи данные указаны в результате поиска;
6) сортировка по расстоянию до текущего пользователя, по возрастанию;
7) удаление объекта «запрос поиска».
4.6. Отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее
Отправка:
1) проверка пользователя по базе (есть ли?);
2) проверка получателя по базе (есть ли?);
3) расшифрование тела и заголовка сообщения ключом сеанса;
4) сохранение сообщения в таблице Msgs в двух экземплярах: в почтовом ящике отправителя (msgbox_id=ид текущего пользователя, folder=2) и почтовом ящике получателя
(msgbox_id=ид_получателя, folder=0).
Получение:
1) проверка пользователя по базе (есть ли?);
2) получение всех сообщений в заданной папке (либо folder=0 «входящие», либо
folder=2 «отправленные») для заданного ид пользователя по таблице Msgs; результат возвращается массивом элементов типа Msg (сообщение)
11
УЖАС.00001-01 33 01
4.7. Поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе непосредственной близости от пользователя, где радиус непосредственной близости равен 1 (одному)
километру
Поиск:
1) проверка пользователя по базе (нет ли?);
2) просмотр всех записей в таблице Location, для которых ид не равен ид текущего
пользователя;
3) для найденных записей — определение расстояния до текущего пользователя
аналогично п. 4.5;
4) фильтрация записей по признаку «расстояние <= 1000» (расстояние вычисляется
в метрах).
Оповещение:
Для каждого результата поиска, если заполнено поле phone_number структуры PersonalData, извлечь телефон, удалить ведущий знак «+» (если имеется), и выполнить методы Authenticate и SubmitSm сервиса SmsHostService (sms-host.ru), указав параметры аккаунта sms-host.ru в первом случае
и номер, время доставки сообщения и его текст — во втором. Текст сообщения может содержать последовательность символов «[]», перед отправкой она заменяется на «<имя_пользователя> <фамилия_пользователя>».
12
УЖАС.00001-01 33 01
5. ВХОДНЫЕ И ВЫХОДНЫЕ ДАННЫЕ
П р и м е ч а н и я. Везде, где на вход требуется подавать последовательности байт
(например, криптографические ключи), на вход подаются base64-закодированные строки,
представляющие указанные последовательности.
5.1. Согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами»)
ВХОД:
1) e-mail пользователя (если обмен ключами осуществляется для создания нового
пользователя, вместо e-mail ставится «*»)
2) байты сообщения «Key Exchange» PKCS1.5 (тип заполнения =2, случайные данные)
ВЫХОД:
статус обмена ключами
5.2. Регистрация и удаление зарегистрированного пользователя
Регистрация
ВХОД:
1) e-mail пользователя
2) зашифрованный ключом сеанса пароль
ВЫХОД:
статус регистрации
Удаление
ВХОД
SHA1-хеш ключа сеанса
ВЫХОД
результат удаления
5.3. Вход в службу знакомств и выход из нее зарегистрированного пользователя
Вход
ВХОД
1) e-mail пользователя
2) зашифрованный ключом сеанса пароль
ВЫХОД
статус входа
Выход
ВХОД
SHA1-хеш ключа сеанса;
ВЫХОД
статус выхода
5.4. Определение и задание текущего местоположения пользователя
Определение
ВХОД
SHA1-хеш ключа сеанса
ВЫХОД
пара значений (широта; долгота)
Задание
ВХОД
SHA1-хеш ключа сеанса, широта, долгота
ВЫХОД
статус задания
13
УЖАС.00001-01 33 01
5.5. Ввод и просмотр сведений персональной анкеты пользователя, включая паспортные
данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.), физические параметры (рост, вес и т.д.), фотографию
Просмотр
ВХОД:
SHA1-хеш ключа сеанса
ВЫХОД:
зашифрованное xml-представление структуры PersonalData (см. 4.5)
Ввод
ВХОД:
SHA1-хеш ключа сеанса, зашифрованное xml-представление структуры PersonalData
(см. 4.5)
ВЫХОД:
результат задания персональных данных
5.6. Поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос
ВХОД:
SHA1-хеш ключа сеанса; набор критериев поиска
ВЫХОД:
набор результатов поиска
5.7. Отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее
Отправка
ВХОД:
SHA1-хеш ключа сеанса; ид пользователя-получателя; зашифрованные ключом сеанса
заголовок и текст письма
ВЫХОД:
результат отправки
Получение
ВХОД:
SHA1-хеш ключа сеанса; папка, в которой показываем сообщения (либо folder=0 «входящие»,
либо folder=2 «отправленные»)
ВЫХОД:
набор сообщений (данных типа Msg)
5.8. Поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе непосредственной близости от пользователя, где радиус непосредственной близости равен 1 (одному)
километру
ВХОД:
SHA1-хеш ключа сеанса; текст сообщения для оповещения
ВЫХОД:
результат оповещения
14
УЖАС.00001-01 33 01
6. СООБЩЕНИЯ
При работе ПC могут выдаваться следующие виды сообщений об ошибках и
предупреждений (табл. 1).
Таблица 1
Сообщение
"Операция завершена неудачно." /* Failure */,
Возможная причина
Неполадки с базой данных.
Ошибка в сервисе.
"Введен неверный адрес электронной почты или Ошибка в адресе или пароле: такого пользопароль."
/*
InvalidEmail
*/,/* вателя в базе нет
InvalidEmailOrPassword */
Ошибка в клиенте. Попробуйте еще раз.
"Ошибка связи: неправильный ключ сессии. Попробуйте чуть позже." /* InvalidSessionKey */,
"Эта операция доступна только для пользовате- Не выполнен вход в сервис
лей, вошедших в службу." /* NotAuthenticated */,
"Пользователь с таким адресом почты уже зарегистрирован. Выберите другой адрес." /*
AccountAlreadyExists */,
"Личная анкета еще не заполнена." /*
NoPersonalData */,
"Местоположение неизвестно." /* NoLocation */,
"Такого пользователя-получателя не существует." /* NoRecipient */,
"Сообщение не найдено." /* MessageNotFound */,
"Невозможно переместить сообщения в эту папку." /* IllegalDestination */,
Пользователь с таким адресом в базе уже
есть
Анкета еще не заполнена, поэтому данные
получить нельзя
Участник еще не указал свое местоположение
Указан несуществующий адресат сообщения,
возможно, пользователь удалил себя
Сообщения с указанным идентификатором в
данном почтовом ящике нет
Перемещение сообщений не реализовано
(нет смысла перемещать из «Входящих» в
«Отправленные» или наоборот)
Проблема в клиенте
"Ошибка поиска: неправильный дескриптор.
Попробуйте
чуть
позже."
/*
InvalidSearchDescriptor */,
"Попытка повторно добавить уже имеющийся Проблема в клиенте
критерий поиска." /* DuplicateSearchCriteria */,
"Критерий
поиска
не
обнаружен."
/*
SearchCriteriaNotFound */,
"Не задано ни одного критерия поиска. Поиск
невозможен." /* NoCriteriasDefined */,
"Не найдено участников, удовлетворяющих заданным критериям. Попробуйте обобщить запрос." /* NoMembersFound */,
"Неизвестный
критерий
поиска."
/*
UnknownSearchCriteria */};
Проблема в клиенте
Не указано ни одного критерия, результат
будет слишком общим, поэтому не ищем
Критериев слишком много и/или они слишком строгие
Проблема в клиенте. Указан недопустимый
критерий поиска
15
УЖАС.00001-01 33 01
ПЕРЕЧЕНЬ СОКРАЩЕНИЙ
БД
ОС
ПС
– база данных;
– операционная система;
– программное средство
16
УЖАС.00001-01 33 01
Лист регистрации изменений
Номера листов (страниц)
Изм. изме- замененненных
ных
новых
Всего
№
Входящий
листов
документа
№
сопровоаннули(страдительного
рованниц)
в
документа
и
ных
докумендата
те
Подпись
(фамилия)
Дата